/** * attach Command - open a worktree's tmux session in this terminal (Issue #2317, Phase A/D) * * commandmate attach [--instance ] [--read-only] [--live] * * ## Why this exists when `tmux attach` already does * * Three reasons, and each one is a thing an operator got wrong before it: * * 1. **The session name.** It is `mcbd---[-]` (or * the legacy `mcbd--[-]` for a session the server * adopted), the suffix depends on the agent-instance roster, and the `` * lives in the server's DB (Issue #2866). `commandmate ls` did not print it, * so the name had to be assembled by hand from facts spread across two * commands — and since #2866 it cannot be assembled client-side at all. * 2. **The `=` trap.** The exact-match target form is `'=:'` (Issue #1156), * and in zsh an unquoted `=name` is an equals expansion — `tmux attach -t * =mcbd-…:` fails with `not found` before tmux ever runs. Measured; it is in * the Issue. This command quotes it so nobody has to know. * 3. **What you will see.** For an alternate-screen agent a bare attach shows * the composer and nothing else — the transcript is at the top of a 1000-row * canvas and tmux follows the cursor at row 997. That is not a fault to * debug, it is the geometry, and the hint printed before attaching says so * and names the three ways to read anyway. * * ## `--live` is claude-only, and that is a measurement * * See `LIVE_ATTACH_TOOLS` in `lib/tmux/session-surface.ts`. Every other tool * either reads its reply off the pane, or has detection rules measured only at * 200x1000, or cannot survive a width change at all. */ import { Command } from 'commander'; import { ApiClient } from '../utils/api-client'; import type { ApiErrorPayload } from '../utils/api-client'; import { type CommandTarget } from './command-target'; /** The name `attach` will connect to, and whether the server published it. */ export interface AttachSessionTarget { sessionName: string; /** * True when the name came from the server's roster (Issue #2867); false when * it is the legacy name assembled here because the roster could not supply * one. Only a published name is the one the server's own routes address, so * only a published name can be vouched for by them (Issue #3334). */ published: boolean; } /** * What the server could say about the session `attach` is about to open. * * - `owned`: the server's ownership check passed, for this very name. * - `foreign`: the server answered 409 `session_owned_by_other_server` for * this very name. * - `unconfirmed`: anything else — the owner is not known. The server answered * about a DIFFERENT name than the one `attach` connects to (`other-name`), or * gave no ownership answer at all (`no-answer`: any non-2xx such as the 404 * for a namespaced session that does not exist, a server older than #2865, * no server). */ export type AttachOwnership = { verdict: 'owned'; } | { verdict: 'foreign'; payload: ApiErrorPayload; } | { verdict: 'unconfirmed'; why: 'other-name' | 'no-answer'; checkedName: string | null; }; /** * Ask the server whether the session `attach` is about to open is its own * (Issue #3334). * * ## Why ask the server, and why through `capture` * * `has-session` answers by name, and a name is all two servers on one tmux * socket have in common (Issue #2865): a worktree directory called the same on * both resolves to the same `mcbd-…` name. Only the server that holds the * worktree row knows the directory its own session was started in, and every * session route already compares that with tmux's `#{session_path}` and * answers 409 `session_owned_by_other_server` when they differ. `capture` with * `lines: 1` is the cheapest of them, reads nothing it would not show anyway, * and sends tmux no key. * * ## The name has to be the same one * * The route checks the name IT resolves — the namespaced one, or the legacy * one it adopted — which is exactly the name the roster publishes. When the * roster could not be read, `attach` falls back to the legacy name, and a 200 * from `capture` is then about a different session: the namespaced name and * the legacy name can both exist, one this server's and one another's. So a * 200 counts as `owned` only for a published name, and a 409 counts as * `foreign` only when the name it reports is the one being opened. * * Every other outcome is `unconfirmed`, including no answer at all. A 404 * from `capture` is the common case of that: the roster could not be read, the * name fell back to the legacy form, and the server's namespaced session does * not exist — so the legacy session `has-session` found belongs to nobody this * server can vouch for. Only a confirmed owner gets a writable attach. */ export declare function checkAttachOwnership(client: ApiClient, worktreeId: string, cliToolId: string, instanceId: string | undefined, target: AttachSessionTarget): Promise; /** * What to do with an attach the server did not vouch for (Issue #3334): a * session another server owns (`foreign`), or one whose owner could not be * confirmed because the server checked a different name (`unconfirmed`). * * Attaching is the one path where the operator named the session themselves, * and looking at it can be what they came for — so the attach is not refused, * it is made read-only: tmux then delivers no key but the detach one. The two * forms that cannot be made read-only are refused before tmux is touched: * * - `--live` re-lays the session out (`set-option` / `resize-window`), which * changes the other server's pane whether or not a key is typed; * - inside tmux, `switch-client` has no read-only form (its `-r` TOGGLES the * client's mode, so it can just as well turn read-only off), and the manual * `attach -r` from outside tmux is printed instead. * * @returns the lines for stderr and whether to go on (read-only) */ export declare function planGuardedAttach(ownership: Extract, sessionName: string, options: { live?: boolean; insideTmux: boolean; }): { proceedReadOnly: boolean; lines: string[]; }; /** * The lines printed to stderr before the terminal is handed to tmux. * * stderr, not stdout: the session takes the screen over immediately afterwards, * and a caller piping this command's stdout is not asking for advice. * * Exported so the test asserts the text a user actually sees rather than a * paraphrase of it. * * @param cliToolId - Resolved CLI tool * @param worktreeId - Worktree id, so the hint's commands are copy-pasteable * @param sessionName - Resolved tmux session name * @param options - The flags as given; `target` is the resolved target the * `capture` hints name (Issue #3982), none when absent */ export declare function buildAttachHints(cliToolId: string, worktreeId: string, sessionName: string, options: { readOnly?: boolean; live?: boolean; target?: CommandTarget; }): string[]; export declare function createAttachCommand(): Command; //# sourceMappingURL=attach.d.ts.map