commandmate 0.30.1 → 0.31.0

package/dist/server/src/lib/session/cli-session.js

@@ -16,10 +16,20 @@ exports.isSessionRunning = isSessionRunning;
 exports.captureSessionOutput = captureSessionOutput;
 exports.captureSessionOutputFresh = captureSessionOutputFresh;
 exports.getSessionName = getSessionName;
+exports.publishSessionSurface = publishSessionSurface;
+exports.forgetSessionSurface = forgetSessionSurface;
 const manager_1 = require("../../lib/cli-tools/manager");
 const logger_1 = require("../../lib/logger");
 const polling_tmux_transport_1 = require("../../lib/tmux/polling-tmux-transport");
 const tmux_capture_cache_1 = require("../../lib/tmux/tmux-capture-cache");
+// Issue #2317: this module is one of the two gateways Issue #1922's import guard
+// names, which is why the tmux SURFACE is reached from here and not from
+// `worktree-status-helper.ts`. Static, not `await import()`: the guard's
+// `no-restricted-syntax` rule blocks the dynamic form outright ("keep it at
+// zero"), and this module already imports from `lib/tmux/**` above.
+const session_hooks_1 = require("../../lib/tmux/session-hooks");
+const session_status_options_1 = require("../../lib/tmux/session-status-options");
+const tmux_session_surface_1 = require("./tmux-session-surface");
 const logger = (0, logger_1.createLogger)('cli-session');
 function getDefaultTransport() {
     return (0, polling_tmux_transport_1.getPollingTmuxTransport)();
@@ -130,3 +140,45 @@ async function captureSessionOutputFresh(worktreeId, cliToolId, lines = 5000, in
 function getSessionName(worktreeId, cliToolId, instanceId) {
     return resolveSessionContext(worktreeId, cliToolId, instanceId).sessionName;
 }
+/**
+ * Publish one session's state onto its tmux session, and take back a geometry
+ * no human is using (Issue #2317, Phases B and D).
+ *
+ * ## Why this is here rather than called directly
+ *
+ * `worktree-status-helper.ts` is the caller, and Issue #1922's import guard
+ * (§4 D4) forbids it from reaching `lib/tmux/**` — this module is one of the two
+ * sanctioned gateways the guard's own message names, and the guard's allowlist
+ * "may only shrink". So the status poll asks this module, and this module owns
+ * the three tmux-side calls.
+ *
+ * Everything below is no-throw by construction (each callee swallows its own
+ * errors), and the whole thing is a convenience surface: a tmux hiccup must not
+ * be able to fail the poll that the sidebar, the header chip and
+ * `commandmate ls` all read.
+ *
+ * Costs nothing in the steady state: the status write is skipped unless the
+ * status CHANGED, the hook reconcile runs once per session per process, and the
+ * geometry probe is asked only for the tools `attach --live` accepts.
+ *
+ * @param publication - Session identity plus the status word to publish
+ */
+async function publishSessionSurface(publication) {
+    await (0, session_hooks_1.ensureSessionHooks)(publication.sessionName);
+    if ((0, tmux_session_surface_1.isLiveAttachEligibleSession)(publication.sessionName)) {
+        await (0, session_hooks_1.reconcileDelegatedGeometry)(publication.sessionName);
+    }
+    await (0, session_status_options_1.publishSessionStatus)(publication);
+}
+/**
+ * Drop every memo held for a session that is known to be gone (Issue #2317).
+ *
+ * Without it, a session created later under the same name would be deduped
+ * against the dead one's last published status and never write its own.
+ *
+ * @param sessionName - tmux session name that no longer exists
+ */
+function forgetSessionSurface(sessionName) {
+    (0, session_status_options_1.forgetSessionStatus)(sessionName);
+    (0, session_hooks_1.forgetSessionHooks)(sessionName);
+}

package/dist/server/src/lib/session/tmux-session-surface.js

@@ -0,0 +1,525 @@
+"use strict";
+/**
+ * The tmux "surface" CommandMate publishes on its own sessions (Issue #2317).
+ *
+ * Everything here is a pure argument builder or a pure predicate — no
+ * `child_process`, no `@/` path alias, and one constants import. Three
+ * constraints put it here rather than under `lib/tmux/`, and all three are
+ * load-bearing:
+ *
+ * 1. **`tsconfig.cli.json` sets `"paths": {}`.** The CLI bundle resolves nothing
+ *    through `@/…`, so a module the `attach` command needs may only reach the
+ *    rest of `src/` through relative specifiers. `lib/tmux/tmux.ts` cannot be
+ *    that module — it imports `@/lib/cli-tools/validation` and `@/lib/logger`.
+ * 2. **The Issue #1922 import guard.** `.eslintrc.json` forbids `src/cli/**`
+ *    from importing anything matching `**‍/tmux/**`, and its allowlist is
+ *    explicitly one-way ("may only shrink"). A pure argv builder is not the kind
+ *    of tmux access that guard exists to stop — it issues no command and opens
+ *    no session — but the rule is a path pattern, so the module lives on a path
+ *    the CLI may read. Nothing here can reach tmux: the executors are in
+ *    `lib/tmux/`, and those are what the guard still covers.
+ * 3. **One wire form, two callers.** The server writes `@cm_status` from the
+ *    status poll and the CLI writes `@cm_delegated` from `attach --live`. If
+ *    each spelled its own `set-option` argv, the two could disagree about the
+ *    target form (`=name:` vs `name`), and a bare name prefix-matches — the
+ *    Issue #1156 leak, in a new place. Tests assert the builders, so a change to
+ *    the wire form is a change to exactly one line.
+ *
+ * ## What is deliberately NOT here
+ *
+ * Anything server-global. Every builder below takes a session name and produces
+ * a `-t <session>` form: `set-option -g`, `bind-key` and `set-hook -g` are
+ * absent on purpose (Issue #2317 決定事項 2 — the only global tmux mutation
+ * CommandMate makes is #1623's `bind-key`, and it stays where it is, in
+ * `lib/tmux/read-mode.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATTACH_HOOK_FORMATS = exports.AUTO_POPUP_ENV = exports.LIVE_ATTACH_HOOK_ENV = exports.AUTO_POPUP_HOOK = exports.DELEGATE_HOOK = exports.ALT_SCREEN_TOOLS = exports.LIVE_ATTACH_TOOLS = exports.TMUX_STATUS_ENV = exports.CM_STATUS_RIGHT_FORMAT = exports.CM_SESSION_OPTIONS = exports.CM_DELEGATED_OPTION = exports.CM_UPDATED_OPTION = exports.CM_INSTANCE_OPTION = exports.CM_TOOL_OPTION = exports.CM_WORKTREE_OPTION = exports.CM_STATUS_OPTION = exports.MCBD_SESSION_PREFIX = void 0;
+exports.exactSessionTarget = exactSessionTarget;
+exports.isCommandMateSession = isCommandMateSession;
+exports.buildSetSessionOptionArgs = buildSetSessionOptionArgs;
+exports.buildUnsetSessionOptionArgs = buildUnsetSessionOptionArgs;
+exports.buildShowSessionOptionArgs = buildShowSessionOptionArgs;
+exports.buildShowSessionOptionValueArgs = buildShowSessionOptionValueArgs;
+exports.buildSetStatusRightArgs = buildSetStatusRightArgs;
+exports.buildUnsetStatusRightArgs = buildUnsetStatusRightArgs;
+exports.isTmuxStatusEnabled = isTmuxStatusEnabled;
+exports.buildSetSessionHookArgs = buildSetSessionHookArgs;
+exports.buildUnsetSessionHookArgs = buildUnsetSessionHookArgs;
+exports.buildShowSessionHooksArgs = buildShowSessionHooksArgs;
+exports.buildWindowSizeArgs = buildWindowSizeArgs;
+exports.buildResizeWindowArgs = buildResizeWindowArgs;
+exports.buildListClientsArgs = buildListClientsArgs;
+exports.countHumanClients = countHumanClients;
+exports.buildAttachArgs = buildAttachArgs;
+exports.buildSwitchClientArgs = buildSwitchClientArgs;
+exports.isLiveAttachSupported = isLiveAttachSupported;
+exports.isLiveAttachEligibleSession = isLiveAttachEligibleSession;
+exports.usesAltScreen = usesAltScreen;
+exports.isLiveAttachHookEnabled = isLiveAttachHookEnabled;
+exports.isAutoPopupEnabled = isAutoPopupEnabled;
+exports.quoteScriptPathForHook = quoteScriptPathForHook;
+exports.buildHookRunShellBody = buildHookRunShellBody;
+exports.buildInstallDelegateHookArgs = buildInstallDelegateHookArgs;
+exports.buildRemoveDelegateHookArgs = buildRemoveDelegateHookArgs;
+exports.buildInstallAutoPopupHookArgs = buildInstallAutoPopupHookArgs;
+exports.buildRemoveAutoPopupHookArgs = buildRemoveAutoPopupHookArgs;
+exports.buildDelegateGeometryCommands = buildDelegateGeometryCommands;
+exports.buildRestoreGeometryCommands = buildRestoreGeometryCommands;
+const tmux_pane_config_1 = require("../../config/tmux-pane-config");
+/**
+ * Session-name prefix every CommandMate tmux session carries.
+ *
+ * `lib/tmux/read-mode.ts` owns a constant of the same name for #1623's key
+ * binding; `tests/unit/tmux/session-surface-2317.test.ts` pins the two together
+ * so a rename breaks a test instead of silently turning a guard into a permanent
+ * "never fire". Not imported from `cli-tools/base.ts` because it is a template
+ * literal there, not a constant.
+ */
+exports.MCBD_SESSION_PREFIX = 'mcbd-';
+/**
+ * Exact-match tmux target for a session (Issue #1156's `=name:` form).
+ *
+ * The same string `exactTarget()` in `lib/tmux/tmux.ts` produces — that function
+ * stays the one the server-side module uses, and the test above pins the two to
+ * each other so this copy cannot drift. It exists at all because `tmux.ts` is
+ * unreachable from the CLI bundle (see the module docblock).
+ *
+ * @param sessionName - Exact tmux session name
+ * @returns `=<name>:` — exact session match, valid as both a session and a
+ *   window/pane target
+ */
+function exactSessionTarget(sessionName) {
+    return `=${sessionName}:`;
+}
+/** True when `sessionName` looks like a session CommandMate created. */
+function isCommandMateSession(sessionName) {
+    return sessionName.startsWith(exports.MCBD_SESSION_PREFIX);
+}
+// ---------------------------------------------------------------------------
+// Phase B: the state CommandMate publishes onto its own sessions
+// ---------------------------------------------------------------------------
+/** User option carrying the session's status word. */
+exports.CM_STATUS_OPTION = '@cm_status';
+/** User option carrying the worktree id the session belongs to. */
+exports.CM_WORKTREE_OPTION = '@cm_worktree';
+/** User option carrying the CLI tool id running in the session. */
+exports.CM_TOOL_OPTION = '@cm_tool';
+/** User option carrying the agent instance id. */
+exports.CM_INSTANCE_OPTION = '@cm_instance';
+/** User option carrying the ISO timestamp of the last status write. */
+exports.CM_UPDATED_OPTION = '@cm_updated';
+/**
+ * User option set to `1` while a human client owns the session's geometry
+ * (Phase D). Read by the server so it can stand down from resizing and from
+ * saving a scraped reply off a terminal-sized frame.
+ */
+exports.CM_DELEGATED_OPTION = '@cm_delegated';
+/**
+ * Every `@cm_*` option this feature writes, in the order they are removed.
+ *
+ * The opt-out path (`CM_TMUX_STATUS=off`) iterates this list rather than
+ * re-typing names, so an option added above cannot be left behind on a user's
+ * tmux server.
+ */
+exports.CM_SESSION_OPTIONS = [
+    exports.CM_STATUS_OPTION,
+    exports.CM_WORKTREE_OPTION,
+    exports.CM_TOOL_OPTION,
+    exports.CM_INSTANCE_OPTION,
+    exports.CM_UPDATED_OPTION,
+    exports.CM_DELEGATED_OPTION,
+];
+/**
+ * The session-scoped `status-right` CommandMate installs.
+ *
+ * A tmux FORMAT, not an interpolated string: the values come from the `@cm_*`
+ * options above, so the status line re-renders on every status write without a
+ * second write for the line itself. `window_width`x`window_height` is on it
+ * because the whole Issue is about a window whose size the reader cannot see —
+ * during Phase D delegation it is the fastest way to tell whether the geometry
+ * handover actually happened.
+ */
+exports.CM_STATUS_RIGHT_FORMAT = '[CommandMate #{@cm_tool}/#{@cm_instance} #{@cm_status}] #{window_width}x#{window_height}';
+/** `tmux set-option -t <session> <name> <value>`. */
+function buildSetSessionOptionArgs(sessionName, option, value) {
+    return ['set-option', '-t', exactSessionTarget(sessionName), option, value];
+}
+/** `tmux set-option -u -t <session> <name>` — remove a session-scoped value. */
+function buildUnsetSessionOptionArgs(sessionName, option) {
+    return ['set-option', '-u', '-t', exactSessionTarget(sessionName), option];
+}
+/**
+ * `tmux show-options -t <session> <name>`.
+ *
+ * Deliberately WITHOUT `-v`: the empty-vs-set distinction is the whole point of
+ * the call at the `status-right` site. Measured on tmux 3.5a — a session that
+ * has never had `status-right` set answers with empty stdout and exit 0, and one
+ * that has answers `status-right "…"`. `-v` would print an empty line for the
+ * first case too, and "the user already customised this session" would become
+ * indistinguishable from "nobody has".
+ */
+function buildShowSessionOptionArgs(sessionName, option) {
+    return ['show-options', '-t', exactSessionTarget(sessionName), option];
+}
+/**
+ * `tmux show-options -v -t <session> <name>` — the VALUE alone.
+ *
+ * The right shape when only the value matters (`@cm_delegated` is `1` or it is
+ * nothing). {@link buildShowSessionOptionArgs} is the right shape when the
+ * distinction between "set to empty" and "never set" matters, which is the
+ * `status-right` case.
+ */
+function buildShowSessionOptionValueArgs(sessionName, option) {
+    return ['show-options', '-v', '-t', exactSessionTarget(sessionName), option];
+}
+/** `tmux set-option -t <session> status-right '<format>'`. */
+function buildSetStatusRightArgs(sessionName, format) {
+    return buildSetSessionOptionArgs(sessionName, 'status-right', format);
+}
+/** `tmux set-option -u -t <session> status-right`. */
+function buildUnsetStatusRightArgs(sessionName) {
+    return buildUnsetSessionOptionArgs(sessionName, 'status-right');
+}
+/** Environment variable that turns the Phase B surface off. */
+exports.TMUX_STATUS_ENV = 'CM_TMUX_STATUS';
+/**
+ * True unless the operator set `CM_TMUX_STATUS` to `off` / `0` / `false`.
+ *
+ * Read at CALL time from an injected environment rather than at module load, so
+ * a test can flip it without module-registry surgery and so a process started
+ * with the variable set is not at the mercy of import order.
+ */
+function isTmuxStatusEnabled(env = process.env) {
+    const raw = (env[exports.TMUX_STATUS_ENV] ?? '').trim().toLowerCase();
+    return raw !== 'off' && raw !== '0' && raw !== 'false';
+}
+// ---------------------------------------------------------------------------
+// Session-scoped hooks
+// ---------------------------------------------------------------------------
+/**
+ * `tmux set-hook -t <session> <hook> <command>`.
+ *
+ * The command is passed as ONE argv element. Do not fold an `if-shell -F` into
+ * it: measured on tmux 3.5a (Issue #2317 技術検証), a hook body of the shape
+ * `if-shell -F '#{…}' 'display-popup …'` is accepted and then silently never
+ * fires. A `run-shell -b '<script> #{session_name} #{client_control_mode}'` that
+ * hands the formats to a script DOES fire, so every hook this feature installs
+ * has that shape and the branching happens in the script.
+ */
+function buildSetSessionHookArgs(sessionName, hook, command) {
+    return ['set-hook', '-t', exactSessionTarget(sessionName), hook, command];
+}
+/** `tmux set-hook -u -t <session> <hook>`. */
+function buildUnsetSessionHookArgs(sessionName, hook) {
+    return ['set-hook', '-u', '-t', exactSessionTarget(sessionName), hook];
+}
+/** `tmux show-hooks -t <session>` — session-scoped hooks only, never the global table. */
+function buildShowSessionHooksArgs(sessionName) {
+    return ['show-hooks', '-t', exactSessionTarget(sessionName)];
+}
+// ---------------------------------------------------------------------------
+// Geometry
+// ---------------------------------------------------------------------------
+/** `tmux set-window-option -t <session> window-size <mode>`. */
+function buildWindowSizeArgs(sessionName, mode) {
+    return ['set-window-option', '-t', exactSessionTarget(sessionName), 'window-size', mode];
+}
+/** `tmux resize-window -t <session> -x <w> -y <h>`. */
+function buildResizeWindowArgs(sessionName, width, height) {
+    return [
+        'resize-window',
+        '-t',
+        exactSessionTarget(sessionName),
+        '-x',
+        String(width),
+        '-y',
+        String(height),
+    ];
+}
+/**
+ * `tmux list-clients -t <session> -F '#{client_control_mode}'`.
+ *
+ * `client_control_mode` is `1` for a `tmux -C` client — which is what
+ * CommandMate's own control-mode transport attaches as — and `0` for a human
+ * terminal. Phase D hands the geometry back when the HUMAN count reaches zero,
+ * so a control client sitting on the session forever must not keep the
+ * delegation open (Issue #2317 受入条件 Phase D 4).
+ */
+function buildListClientsArgs(sessionName) {
+    return ['list-clients', '-t', exactSessionTarget(sessionName), '-F', '#{client_control_mode}'];
+}
+/**
+ * Number of human (control-mode `0`) clients in `list-clients` output.
+ *
+ * Counts lines that are exactly `0`, NOT lines that are "anything but 1". The
+ * difference matters twice: `list-clients` exits 0 with EMPTY stdout on a
+ * detached session, and a line this function does not recognise is not evidence
+ * that a person is looking at the pane. Since the answer gates a resize, "I
+ * could not read this" has to mean "nobody is attached" — the reading that
+ * leaves `reconcileSessionGeometry` doing its normal job — rather than "somebody
+ * is", which would pin a window open on an unparsed byte.
+ *
+ * `#{client_control_mode}` is `1` for a `tmux -C` client and `0` for a terminal;
+ * measured on tmux 3.5a, a human client attached to a CommandMate session
+ * reports exactly `0`.
+ *
+ * @param stdout - Raw stdout of {@link buildListClientsArgs}
+ * @returns How many attached clients are humans
+ */
+function countHumanClients(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line === '0').length;
+}
+/** `tmux attach-session -t '=<session>:'`, with `-r` when read-only. */
+function buildAttachArgs(sessionName, readOnly) {
+    const args = ['attach-session'];
+    if (readOnly)
+        args.push('-r');
+    args.push('-t', exactSessionTarget(sessionName));
+    return args;
+}
+/** `tmux switch-client -t '=<session>:'` — the in-tmux equivalent of attaching. */
+function buildSwitchClientArgs(sessionName) {
+    return ['switch-client', '-t', exactSessionTarget(sessionName)];
+}
+// ---------------------------------------------------------------------------
+// Which tools each behaviour applies to
+// ---------------------------------------------------------------------------
+/**
+ * CLI tools `attach --live` will hand the pane geometry to (Issue #2317 決定事項 3).
+ *
+ * claude alone, and the list is a measurement rather than a starting point:
+ * claude's reply is written from its own transcript JSONL, so a terminal-sized
+ * frame during delegation cannot lose History. Every other tool either reads its
+ * reply off the pane (copilot / gemini / vibe-local), or has detection rules
+ * that were only ever measured at 200x1000 (codex / antigravity / command-code),
+ * or cannot survive a width change at all (opencode paints a sidebar at >=121
+ * columns). Widening this set is out of scope for #2317 and requires
+ * re-measuring the tool it adds.
+ */
+exports.LIVE_ATTACH_TOOLS = ['claude'];
+/** Whether `attach --live` is allowed for a CLI tool. */
+function isLiveAttachSupported(cliToolId) {
+    return exports.LIVE_ATTACH_TOOLS.includes(cliToolId);
+}
+/**
+ * Whether a tmux session's NAME says it runs a tool `--live` supports.
+ *
+ * The session name is `mcbd-<tool>-<worktree>` and no supported tool id is a
+ * prefix of another, so this is exact rather than a guess. It exists because
+ * the two callers that need the answer — the attach hook script's installer and
+ * the response poller — hold a session name and nothing else: a hook fires with
+ * tmux formats, and the poller must not pay a tmux round-trip to ask about a
+ * session that could never be delegated in the first place.
+ *
+ * @param sessionName - tmux session name
+ */
+function isLiveAttachEligibleSession(sessionName) {
+    if (!isCommandMateSession(sessionName))
+        return false;
+    return exports.LIVE_ATTACH_TOOLS.some((tool) => sessionName.startsWith(`${exports.MCBD_SESSION_PREFIX}${tool}-`));
+}
+/**
+ * CLI tools that paint their transcript in the terminal's alternate screen.
+ *
+ * The reason a bare `tmux attach` looks EMPTY for them: the TUI draws the
+ * transcript at the top of a 1000-row canvas and its composer at the bottom, and
+ * tmux follows the cursor, so a 44-row client sees the composer and nothing
+ * else. `attach` prints its hint for exactly these.
+ *
+ * Deliberately a local list rather than an import of `usesAlternateScreen()`:
+ * this module must stay free of `lib/cli-tools`, whose graph the CLI bundle
+ * cannot afford (see the module docblock). The two are pinned to each other by
+ * `tests/unit/tmux/session-surface-2317.test.ts`, so a tool moving in or out of
+ * the alternate screen breaks a test rather than silently dropping the hint.
+ */
+exports.ALT_SCREEN_TOOLS = ['claude', 'opencode', 'copilot'];
+/** Whether `attach` should warn that a bare attach shows no transcript. */
+function usesAltScreen(cliToolId) {
+    return exports.ALT_SCREEN_TOOLS.includes(cliToolId);
+}
+// ---------------------------------------------------------------------------
+// Phase D: live attach — handing the geometry over and taking it back
+// ---------------------------------------------------------------------------
+/**
+ * ## The safety net is a poll, NOT a `client-detached` hook — measured
+ *
+ * Issue #2317's 技術検証 says a session-scoped `client-detached` hook fires.
+ * Re-measured on tmux 3.5a against a private socket before this was written, it
+ * does not, and two further facts make the shape unusable:
+ *
+ * | probe (tmux 3.5a, `tmux -L`)                        | result |
+ * |-----------------------------------------------------|--------|
+ * | `set-hook -t <s> client-attached`, human attaches    | fires; `#{session_name}` is the session, `#{client_control_mode}` is `0` |
+ * | same, control-mode client attaches                   | does NOT fire |
+ * | `set-hook -t <s> client-detached`, human detaches    | **never fires** |
+ * | `set-hook -g client-detached`, human detaches        | fires — but `#{session_name}` is the CLIENT's other session and `#{client_control_mode}` is EMPTY |
+ *
+ * So the detach edge is unreachable session-scoped, and reaching it globally
+ * would both break 決定事項 2 (no global tmux mutation) and arrive without the
+ * session identity the restore needs. The restore therefore runs from the status
+ * poll instead — `reconcileDelegatedGeometry()` in `lib/tmux/session-hooks.ts` —
+ * which sees every session every couple of seconds, needs no tmux state of its
+ * own, and covers cases a hook could not anyway: the CLI being killed, the
+ * terminal window being closed, and a detach from some other client.
+ *
+ * The `client-attached` edge DOES work session-scoped, and that is the one the
+ * opt-in hooks below are installed on.
+ *
+ * Both opt-in features hang off that same edge, and a tmux hook name without an
+ * index IS `[0]`: installing two of them unindexed would mean the second
+ * silently replaced the first. Measured on tmux 3.5a — `client-attached[0]` and
+ * `client-attached[1]` both fire, and `set-hook -u` removes one without
+ * disturbing the other.
+ */
+exports.DELEGATE_HOOK = 'client-attached[0]';
+/** @see DELEGATE_HOOK */
+exports.AUTO_POPUP_HOOK = 'client-attached[1]';
+/**
+ * Environment variable that also installs the geometry hand-over for a session
+ * the user attached to BY HAND (`tmux attach`), not through
+ * `commandmate attach --live`.
+ *
+ * Opt-in, because installing it unasked would mean a hand-rolled `tmux attach`
+ * silently changes a session's geometry — the one thing Issue #2317 決定事項 1
+ * says must not happen by default.
+ */
+exports.LIVE_ATTACH_HOOK_ENV = 'CM_LIVE_ATTACH_HOOK';
+/**
+ * Environment variable that opens the following read popup on attach (Phase C).
+ * Default off; see `AUTO_POPUP_SCRIPT` for why.
+ */
+exports.AUTO_POPUP_ENV = 'CM_READ_MODE_AUTO_POPUP';
+/** True when the operator opted into the attach-time geometry hand-over. */
+function isLiveAttachHookEnabled(env = process.env) {
+    return (env[exports.LIVE_ATTACH_HOOK_ENV] ?? '').trim().toLowerCase() === 'on';
+}
+/** True when the operator opted into the automatic read popup. */
+function isAutoPopupEnabled(env = process.env) {
+    return (env[exports.AUTO_POPUP_ENV] ?? '').trim().toLowerCase() === 'on';
+}
+/**
+ * Quote a path for the `sh` command a tmux hook runs.
+ *
+ * Double quotes rather than single, because the whole shell-command is already
+ * inside tmux's own single quotes and tmux's lexer does not process escapes
+ * inside those — a `'\''` would end the tmux string, not the shell one.
+ *
+ * Returns undefined for a path carrying any character that would change the
+ * meaning of a double-quoted word (`"`, `$`, a backtick, a backslash) or that
+ * cannot appear on a command line at all (newline / carriage return). Callers
+ * treat that as "install no hook": a home directory nobody can quote safely is a
+ * reason to fall back to the CLI's own hand-over, not a reason to run a command
+ * whose parse is a guess.
+ *
+ * @param path - Absolute script path
+ * @returns The double-quoted word, or undefined when it cannot be represented
+ */
+function quoteScriptPathForHook(path) {
+    if (/["$`\\\n\r]/.test(path))
+        return undefined;
+    return `"${path}"`;
+}
+/**
+ * The `run-shell` body of a session-scoped hook.
+ *
+ * `-b` because a hook that blocks the tmux server for the length of a shell
+ * script is a hook that makes tmux feel broken.
+ *
+ * The formats are passed as separate words and consumed as `$1`, `$2`, `$3` by
+ * the script, which is why none of them is quoted here — a tmux format that
+ * expanded to something with a space would be split, and all three of these
+ * (`session_name`, `client_control_mode`, `client_name`) are single words by
+ * construction.
+ *
+ * @param quotedScriptPath - Result of {@link quoteScriptPathForHook}
+ * @param formats - tmux formats to hand the script
+ * @param extraArgs - Literal words appended after the formats
+ * @returns The command string to hand to `set-hook`
+ */
+function buildHookRunShellBody(quotedScriptPath, formats, extraArgs = []) {
+    const words = [quotedScriptPath, ...formats, ...extraArgs].join(' ');
+    return `run-shell -b '${words}'`;
+}
+/**
+ * Formats every attach hook hands to its script.
+ *
+ * `#{client_name}` is included for both because the auto-popup needs it
+ * (`display-popup -c <client>`) and the delegate script ignores extra arguments
+ * — one format list is one thing to keep right.
+ */
+exports.ATTACH_HOOK_FORMATS = [
+    '#{session_name}',
+    '#{client_control_mode}',
+    '#{client_name}',
+];
+/**
+ * `set-hook -t <session> client-attached[0] 'run-shell -b …'`, or undefined when
+ * the script path cannot be quoted safely.
+ *
+ * @param sessionName - Target session
+ * @param scriptPath - Absolute path of the materialized delegate script
+ */
+function buildInstallDelegateHookArgs(sessionName, scriptPath) {
+    const quoted = quoteScriptPathForHook(scriptPath);
+    if (quoted === undefined)
+        return undefined;
+    return buildSetSessionHookArgs(sessionName, exports.DELEGATE_HOOK, buildHookRunShellBody(quoted, exports.ATTACH_HOOK_FORMATS));
+}
+/** `set-hook -u -t <session> client-attached[0]`. */
+function buildRemoveDelegateHookArgs(sessionName) {
+    return buildUnsetSessionHookArgs(sessionName, exports.DELEGATE_HOOK);
+}
+/**
+ * `set-hook -t <session> client-attached[1] 'run-shell -b …'`, or undefined when
+ * the script path cannot be quoted safely.
+ */
+function buildInstallAutoPopupHookArgs(sessionName, scriptPath) {
+    const quoted = quoteScriptPathForHook(scriptPath);
+    if (quoted === undefined)
+        return undefined;
+    return buildSetSessionHookArgs(sessionName, exports.AUTO_POPUP_HOOK, buildHookRunShellBody(quoted, exports.ATTACH_HOOK_FORMATS));
+}
+/** `set-hook -u -t <session> client-attached[1]`. */
+function buildRemoveAutoPopupHookArgs(sessionName) {
+    return buildUnsetSessionHookArgs(sessionName, exports.AUTO_POPUP_HOOK);
+}
+/**
+ * The tmux commands that hand a session's geometry to the attaching terminal.
+ *
+ * Ordered: the flag is raised BEFORE `window-size latest`, so a status poll that
+ * lands between the two sees "delegated, still 200x1000" — which suppresses the
+ * scraped save one poll early — rather than "not delegated, 44 rows", which
+ * would save a truncated reply. The cheap failure is the safe one.
+ *
+ * @param sessionName - Target session
+ * @returns Argument vectors, to run in order
+ */
+function buildDelegateGeometryCommands(sessionName) {
+    return [
+        buildSetSessionOptionArgs(sessionName, exports.CM_DELEGATED_OPTION, '1'),
+        buildWindowSizeArgs(sessionName, 'latest'),
+    ];
+}
+/**
+ * The tmux commands that take a session's geometry back.
+ *
+ * The mirror image of {@link buildDelegateGeometryCommands}, and ordered the
+ * other way for the same reason: the canvas is restored first and the flag is
+ * dropped last, so no poll can ever see "not delegated" while the pane is still
+ * the size of somebody's terminal.
+ *
+ * @param sessionName - Target session
+ * @param width - Canvas width (defaults to the pinned {@link TUI_PANE_WIDTH})
+ * @param height - Canvas height (defaults to the pinned {@link TUI_PANE_HEIGHT})
+ */
+function buildRestoreGeometryCommands(sessionName, width = tmux_pane_config_1.TUI_PANE_WIDTH, height = tmux_pane_config_1.TUI_PANE_HEIGHT) {
+    return [
+        buildWindowSizeArgs(sessionName, 'manual'),
+        buildResizeWindowArgs(sessionName, width, height),
+        buildUnsetSessionOptionArgs(sessionName, exports.CM_DELEGATED_OPTION),
+    ];
+}