commandmate 0.30.1 → 0.31.0

package/dist/server/src/lib/tmux/session-hook-scripts.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * The shell scripts session-scoped tmux hooks run (Issue #2317, Phases C and D).
+ *
+ * ## Why the text is embedded rather than shipped as a file
+ *
+ * The same reason `read-mode-pager.ts` gives for `cm-read-pane.sh`:
+ * `package.json`'s `files` list does not publish `scripts/`, and an `npx`
+ * install lives in a cache npm may garbage-collect out from under a hook that
+ * outlives the process which installed it. Embedding the text and materializing
+ * it into `~/.commandmate/bin/` gives every hook one absolute path that is
+ * stable across global / local / npx installs.
+ *
+ * ## Why the hooks call scripts instead of doing the work inline
+ *
+ * Measured on tmux 3.5a (Issue #2317 技術検証): a hook body of the shape
+ * `if-shell -F '#{…}' '<command>'` is accepted by `set-hook` and then never
+ * fires — silently, with no error anywhere. A
+ * `run-shell -b '<script> #{session_name} #{client_control_mode}'` DOES fire.
+ * So the formats are handed to a script and every branch is taken in `sh`.
+ *
+ * The hook environment is the tmux SERVER's, which carries `TMUX` — so the bare
+ * `tmux` these scripts call reaches the same server that fired the hook, private
+ * socket included. That is verified, not assumed: the whole live probe for this
+ * Issue ran under `tmux -L cm2317` and the scripts reached that server.
+ *
+ * ## Both scripts refuse to touch a session that is not CommandMate's
+ *
+ * A hook is session-scoped, so in principle it can only fire on the session it
+ * was installed on. The `mcbd-` guard is still there because these scripts are
+ * also runnable by hand and because a session can be renamed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTO_POPUP_SCRIPT = exports.LIVE_DELEGATE_SCRIPT = exports.LIVE_RESTORE_SCRIPT = exports.AUTO_POPUP_SCRIPT_FILENAME = exports.LIVE_DELEGATE_SCRIPT_FILENAME = exports.LIVE_RESTORE_SCRIPT_FILENAME = void 0;
+exports.getScriptDir = getScriptDir;
+exports.getScriptPath = getScriptPath;
+exports.materializeScript = materializeScript;
+exports.materializeLiveRestoreScript = materializeLiveRestoreScript;
+exports.materializeLiveDelegateScript = materializeLiveDelegateScript;
+exports.materializeAutoPopupScript = materializeAutoPopupScript;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const tmux_pane_config_1 = require("../../config/tmux-pane-config");
+const tmux_session_surface_1 = require("../session/tmux-session-surface");
+const read_mode_pager_1 = require("./read-mode-pager");
+/** Basename of the Phase D geometry-restore script. */
+exports.LIVE_RESTORE_SCRIPT_FILENAME = 'cm-live-restore.sh';
+/** Basename of the Phase D geometry-delegation script. */
+exports.LIVE_DELEGATE_SCRIPT_FILENAME = 'cm-live-delegate.sh';
+/** Basename of the Phase C auto-popup script. */
+exports.AUTO_POPUP_SCRIPT_FILENAME = 'cm-auto-popup.sh';
+/**
+ * Restore a session's pinned canvas once no human client is attached.
+ *
+ * NOT a hook body — tmux 3.5a never fires a session-scoped `client-detached`
+ * (see the measurement table in `live-attach.ts`). Two things run this sequence:
+ * `commandmate attach --live` when `attach-session` returns, and the server's
+ * status poll (`reconcileDelegatedGeometry`) for every case where the CLI never
+ * got to — it was killed, the terminal window was closed, or the detach happened
+ * from a client this process never saw. This script is the third, manual, path:
+ * the escape hatch for a session left delegated while no server is running.
+ *
+ * The control-mode test is the whole reason the client count is not simply
+ * `#{session_attached}`: CommandMate's own transport attaches as a `tmux -C`
+ * client and never leaves, so a session with the human gone still reports
+ * `session_attached=1`. `client_control_mode` is `1` for those and `0` for a
+ * terminal, so the restore waits for the HUMAN count to reach zero
+ * (Issue #2317 受入条件 Phase D 4).
+ */
+exports.LIVE_RESTORE_SCRIPT = `#!/bin/sh
+# CommandMate live-attach restore (Issue #2317) — generated file, edits are overwritten.
+#
+#   sh ~/.commandmate/bin/${exports.LIVE_RESTORE_SCRIPT_FILENAME} <session> [control_mode] [width] [height]
+#
+# Pins the session's window back to CommandMate's canvas once no human client is
+# attached to it any more. Safe to run when nothing is delegated: it then simply
+# re-applies the geometry the session already has.
+set -u
+
+SESSION="\${1:-}"
+CONTROL_MODE="\${2:-0}"
+WIDTH="\${3:-${tmux_pane_config_1.TUI_PANE_WIDTH}}"
+HEIGHT="\${4:-${tmux_pane_config_1.TUI_PANE_HEIGHT}}"
+
+case "$SESSION" in
+  ${tmux_session_surface_1.MCBD_SESSION_PREFIX}*) ;;
+  *) exit 0 ;;
+esac
+
+# A control-mode client detaching is CommandMate's own transport reconnecting,
+# not the human leaving. Doing the restore here would fight the human's attach.
+if [ "$CONTROL_MODE" = "1" ]; then
+  exit 0
+fi
+
+# Anyone left who is NOT a control client? Then the geometry is still theirs.
+HUMANS=$(tmux list-clients -t "=$SESSION:" -F '#{client_control_mode}' 2>/dev/null \\
+  | grep -c -v '^1$') || HUMANS=0
+if [ "\${HUMANS:-0}" -gt 0 ]; then
+  exit 0
+fi
+
+tmux set-window-option -t "=$SESSION:" window-size manual 2>/dev/null || exit 0
+tmux resize-window -t "=$SESSION:" -x "$WIDTH" -y "$HEIGHT" 2>/dev/null || true
+tmux set-option -u -t "=$SESSION:" @cm_delegated 2>/dev/null || true
+`;
+/**
+ * Hand a session's geometry to the terminal that just attached.
+ *
+ * The opt-in half of Phase D: `commandmate attach --live` performs these two
+ * writes itself, and this script is what makes a HAND-ROLLED `tmux attach`
+ * behave the same way when the operator asked for it with
+ * `CM_LIVE_ATTACH_HOOK=on`.
+ *
+ * claude-only by session-name prefix, and that is not a shortcut. The session
+ * name is `mcbd-<tool>-<worktree>`, no other CLI tool id begins with `claude`,
+ * and the script has nothing but the name to go on — a hook fires with tmux
+ * formats, not with CommandMate's roster. Widening it means widening
+ * `LIVE_ATTACH_TOOLS` too, and that needs the per-tool re-measurement
+ * Issue #2317 puts out of scope.
+ */
+exports.LIVE_DELEGATE_SCRIPT = `#!/bin/sh
+# CommandMate live-attach delegate (Issue #2317) — generated file, edits are overwritten.
+#
+#   sh ~/.commandmate/bin/${exports.LIVE_DELEGATE_SCRIPT_FILENAME} <session> <control_mode> [client]
+#
+# Hands the session's window from CommandMate's pinned canvas to the terminal
+# that just attached, so an alternate-screen agent re-lays-out and its transcript
+# becomes readable. Installed as a session-scoped \`client-attached[0]\` hook only
+# when CM_LIVE_ATTACH_HOOK=on; \`commandmate attach --live\` does the same two
+# writes itself and needs no hook.
+#
+# The window is put back by whoever notices the human is gone first: the CLI on
+# return from attach-session, or the server's status poll. This script never
+# restores — the attach edge is the only edge tmux 3.5a lets a session-scoped
+# hook see.
+set -u
+
+SESSION="\${1:-}"
+CONTROL_MODE="\${2:-0}"
+
+case "$SESSION" in
+  ${tmux_session_surface_1.MCBD_SESSION_PREFIX}claude-*) ;;
+  *) exit 0 ;;
+esac
+
+# A control-mode client is CommandMate's own transport. Handing it the geometry
+# would resize the canvas to whatever that connection negotiated, which is the
+# #1163 regression this whole feature is built to avoid.
+if [ "$CONTROL_MODE" = "1" ]; then
+  exit 0
+fi
+
+# Raised BEFORE the size change, so a status poll landing between the two sees
+# "delegated, still pinned" rather than "not delegated, 44 rows".
+tmux set-option -t "=$SESSION:" @cm_delegated 1 2>/dev/null || exit 0
+tmux set-window-option -t "=$SESSION:" window-size latest 2>/dev/null || true
+`;
+/**
+ * Open the following transcript popup when a human attaches (Phase C, opt-in).
+ *
+ * Default off, and it has to be: the popup owns the keyboard until `q` is
+ * pressed, so opening it unasked would make every attach start by taking input
+ * away from the composer. `CM_READ_MODE_AUTO_POPUP=on` is the opt-in, and even
+ * then the control-mode test below keeps it from firing for CommandMate's own
+ * transport — a popup opened on a control client would be a popup nobody can
+ * see and nobody can close.
+ */
+exports.AUTO_POPUP_SCRIPT = `#!/bin/sh
+# CommandMate auto read popup (Issue #2317) — generated file, edits are overwritten.
+#
+#   sh ~/.commandmate/bin/${exports.AUTO_POPUP_SCRIPT_FILENAME} <session> <control_mode> <client>
+#
+# Opens the following transcript popup for a human client attaching to a
+# CommandMate session. Never opens for a control-mode client.
+set -u
+
+SESSION="\${1:-}"
+CONTROL_MODE="\${2:-0}"
+CLIENT="\${3:-}"
+
+case "$SESSION" in
+  ${tmux_session_surface_1.MCBD_SESSION_PREFIX}*) ;;
+  *) exit 0 ;;
+esac
+
+if [ "$CONTROL_MODE" = "1" ]; then
+  exit 0
+fi
+
+PAGER_SCRIPT="$HOME/.commandmate/bin/${read_mode_pager_1.PAGER_SCRIPT_FILENAME}"
+[ -x "$PAGER_SCRIPT" ] || exit 0
+
+if [ -n "$CLIENT" ]; then
+  tmux display-popup -c "$CLIENT" -w 90% -h 85% -E "sh \\"$PAGER_SCRIPT\\" --follow \\"$SESSION\\"" 2>/dev/null || true
+else
+  tmux display-popup -w 90% -h 85% -E "sh \\"$PAGER_SCRIPT\\" --follow \\"$SESSION\\"" 2>/dev/null || true
+fi
+`;
+/** Directory every materialized CommandMate script lives in. */
+function getScriptDir() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'bin');
+}
+/** Absolute path of a materialized script. */
+function getScriptPath(filename) {
+    return (0, path_1.join)(getScriptDir(), filename);
+}
+/**
+ * Write a script to `~/.commandmate/bin/<filename>` if its content changed.
+ *
+ * Idempotent by content comparison so a restart does not churn the file's mtime,
+ * and re-executable after a `chmod` accident because the mode is re-applied —
+ * the same contract `materializePagerScript()` has had since #1623.
+ *
+ * @param filename - Basename to write
+ * @param content - Full script text
+ * @returns The absolute path written
+ */
+function materializeScript(filename, content) {
+    const scriptPath = getScriptPath(filename);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(scriptPath), { recursive: true });
+    let current;
+    if ((0, fs_1.existsSync)(scriptPath)) {
+        try {
+            current = (0, fs_1.readFileSync)(scriptPath, 'utf-8');
+        }
+        catch {
+            current = undefined;
+        }
+    }
+    if (current !== content) {
+        (0, fs_1.writeFileSync)(scriptPath, content, { mode: 0o755 });
+    }
+    (0, fs_1.chmodSync)(scriptPath, 0o755);
+    return scriptPath;
+}
+/** Materialize the Phase D restore script and return its absolute path. */
+function materializeLiveRestoreScript() {
+    return materializeScript(exports.LIVE_RESTORE_SCRIPT_FILENAME, exports.LIVE_RESTORE_SCRIPT);
+}
+/** Materialize the Phase D delegate script and return its absolute path. */
+function materializeLiveDelegateScript() {
+    return materializeScript(exports.LIVE_DELEGATE_SCRIPT_FILENAME, exports.LIVE_DELEGATE_SCRIPT);
+}
+/** Materialize the Phase C auto-popup script and return its absolute path. */
+function materializeAutoPopupScript() {
+    return materializeScript(exports.AUTO_POPUP_SCRIPT_FILENAME, exports.AUTO_POPUP_SCRIPT);
+}

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

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Server side of Issue #2317's session-scoped hooks and geometry hand-back.
+ *
+ * Two jobs, both keyed off one session name:
+ *
+ *  - {@link ensureSessionHooks} reconciles the two OPT-IN `client-attached`
+ *    hooks (Phase C's auto popup, Phase D's delegate-on-hand-attach) with what
+ *    the environment asks for. Like #1623's key binding it CONVERGES: turning an
+ *    option off removes the hook a previous run installed, rather than merely
+ *    not installing it again.
+ *  - {@link reconcileDelegatedGeometry} is the safety net the Issue asked a
+ *    `client-detached` hook to be. tmux 3.5a does not fire that hook
+ *    session-scoped (measured — see the table in `live-attach.ts`), so the
+ *    restore runs from the status poll instead: every couple of seconds, for
+ *    every session, "is this delegated while no human is looking at it?".
+ *
+ * Nothing here throws. All of it hangs off the status poll and off session
+ * creation, and neither may be failed by a convenience feature.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureSessionHooks = ensureSessionHooks;
+exports.reconcileDelegatedGeometry = reconcileDelegatedGeometry;
+exports.forgetSessionHooks = forgetSessionHooks;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const tmux_session_surface_1 = require("../session/tmux-session-surface");
+const session_hook_scripts_1 = require("./session-hook-scripts");
+const geometry_delegation_1 = require("./geometry-delegation");
+const logger_1 = require("../logger");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const logger = (0, logger_1.createLogger)('tmux-session-hooks');
+/** tmux calls here are interactive-latency, not long-running. */
+const TMUX_TIMEOUT = 5000;
+const ensured = globalThis.__cmEnsuredSessionHooks ?? (globalThis.__cmEnsuredSessionHooks = new Set());
+/**
+ * Reconcile a session's opt-in `client-attached` hooks with the environment.
+ *
+ * Runs once per session per process; call it freely. Both hooks are removed when
+ * their option is off, so `CM_READ_MODE_AUTO_POPUP=on` followed by a restart
+ * without it leaves no hook behind.
+ *
+ * @param sessionName - Target session
+ */
+async function ensureSessionHooks(sessionName) {
+    if (!(0, tmux_session_surface_1.isCommandMateSession)(sessionName))
+        return;
+    if (ensured.has(sessionName))
+        return;
+    ensured.add(sessionName);
+    try {
+        if ((0, tmux_session_surface_1.isLiveAttachHookEnabled)() && (0, tmux_session_surface_1.isLiveAttachEligibleSession)(sessionName)) {
+            // The restore script rides along with the delegate one: a user whose
+            // server is down needs the manual way back, and materializing it here is
+            // the only moment we know the delegate path is in use at all.
+            (0, session_hook_scripts_1.materializeLiveRestoreScript)();
+            const args = (0, tmux_session_surface_1.buildInstallDelegateHookArgs)(sessionName, (0, session_hook_scripts_1.materializeLiveDelegateScript)());
+            if (args)
+                await execFileAsync('tmux', args, { timeout: TMUX_TIMEOUT });
+        }
+        else {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildRemoveDelegateHookArgs)(sessionName), {
+                timeout: TMUX_TIMEOUT,
+            });
+        }
+        if ((0, tmux_session_surface_1.isAutoPopupEnabled)()) {
+            const args = (0, tmux_session_surface_1.buildInstallAutoPopupHookArgs)(sessionName, (0, session_hook_scripts_1.materializeAutoPopupScript)());
+            if (args)
+                await execFileAsync('tmux', args, { timeout: TMUX_TIMEOUT });
+        }
+        else {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildRemoveAutoPopupHookArgs)(sessionName), {
+                timeout: TMUX_TIMEOUT,
+            });
+        }
+    }
+    catch (error) {
+        logger.debug('session-hooks:reconcile-failed', {
+            sessionName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Take a delegated session's geometry back when no human is attached.
+ *
+ * The Phase D safety net. Restores unconditionally once the two conditions hold,
+ * because the sequence is idempotent — a session already at `manual` 200x1000
+ * with no `@cm_delegated` is left byte-identical by it.
+ *
+ * Also self-healing for a flag left behind by a CLI that was killed: the flag
+ * alone never keeps a window unpinned, because this runs whenever nobody is
+ * looking.
+ *
+ * @param sessionName - Target session
+ * @returns true when the geometry was handed back by this call
+ */
+async function reconcileDelegatedGeometry(sessionName) {
+    try {
+        if (!(await (0, geometry_delegation_1.isGeometryDelegated)(sessionName)))
+            return false;
+        if (await (0, geometry_delegation_1.hasHumanClientAttached)(sessionName))
+            return false;
+        for (const args of (0, tmux_session_surface_1.buildRestoreGeometryCommands)(sessionName)) {
+            await execFileAsync('tmux', args, { timeout: TMUX_TIMEOUT });
+        }
+        logger.info('session-hooks:geometry-restored', { sessionName });
+        return true;
+    }
+    catch (error) {
+        logger.debug('session-hooks:geometry-restore-failed', {
+            sessionName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/** Forget a session's hook bookkeeping — call when it is known to be gone. */
+function forgetSessionHooks(sessionName) {
+    ensured.delete(sessionName);
+    (0, geometry_delegation_1.forgetGeometryDelegation)(sessionName);
+}

package/dist/server/src/lib/tmux/session-status-options.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Phase B of Issue #2317: publish the session's state ONTO the tmux session.
+ *
+ * Before this module, `running` / `waiting` / `ready` / `idle` existed only
+ * inside CommandMate. `tmux ls` showed a name and a window count, an attached
+ * status line showed tmux's stock clock, and an operator who wanted to know what
+ * an agent was doing had to open the web UI or run `commandmate ls`. Two writes
+ * per transition fix that:
+ *
+ *  - **user options** (`@cm_status` and friends) — readable without attaching:
+ *    `tmux ls -F '#{session_name} #{@cm_status}'`;
+ *  - **a session-scoped `status-right`** — readable while attached, rendered
+ *    from those same options so the line updates without being rewritten.
+ *
+ * ## Everything here is session-scoped, and that is the point
+ *
+ * `set-option -t <session>` writes the SESSION's option table. The tmux server's
+ * global table — which every session on the machine inherits, including ones
+ * CommandMate knows nothing about — is never touched, and
+ * `tests/unit/tmux/session-status-options-2317.test.ts` asserts that by
+ * inspecting the argv of every call this module makes. #1623's `bind-key` is the
+ * one global mutation CommandMate makes and it is not made here.
+ *
+ * ## Writes happen on TRANSITION, not on every poll
+ *
+ * `GET /api/worktrees` probes every tool of every worktree every couple of
+ * seconds. Setting five options on each of those polls would be a few hundred
+ * `execFile` round-trips a minute for a value that changes a few times an hour,
+ * so {@link publishSessionStatus} keeps the last published tuple per session and
+ * returns without touching tmux when nothing moved. The memo is keyed by session
+ * name and dropped by {@link forgetSessionStatus} when the session goes away.
+ *
+ * ## The opt-out converges, without a startup hook
+ *
+ * `CM_TMUX_STATUS=off` does not merely stop writing: the first status poll after
+ * the restart REMOVES the `@cm_*` options and the CommandMate `status-right`
+ * from each session it visits, once per session. That is the same "an opt-out
+ * that uninstalls" contract #1623 gave `CM_READ_MODE`, and it is done from the
+ * poll rather than from a startup sweep for two reasons — the poll already knows
+ * which sessions exist (a sweep would have to ask tmux again), and it keeps this
+ * feature from needing a wire into `server.ts`, whose startup path is
+ * deliberately a single dynamic import per module graph.
+ *
+ * ## Nothing here may ever throw
+ *
+ * This is a convenience surface hanging off the status poll. A tmux hiccup must
+ * not be able to fail the poll that the sidebar, `commandmate ls` and the header
+ * chip all read, so every entry point swallows its errors and logs at debug.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishSessionStatus = publishSessionStatus;
+exports.ensureSessionStatusLine = ensureSessionStatusLine;
+exports.clearSessionStatus = clearSessionStatus;
+exports.forgetSessionStatus = forgetSessionStatus;
+exports.publishedSessionCount = publishedSessionCount;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const tmux_session_surface_1 = require("../session/tmux-session-surface");
+const logger_1 = require("../logger");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const logger = (0, logger_1.createLogger)('tmux-session-status');
+/** tmux calls here are interactive-latency, not long-running. */
+const TMUX_TIMEOUT = 5000;
+const published = globalThis.__cmPublishedTmuxStatus ??
+    (globalThis.__cmPublishedTmuxStatus = new Map());
+/** Sessions this process has already uninstalled the surface from. */
+const cleared = globalThis.__cmClearedTmuxStatus ?? (globalThis.__cmClearedTmuxStatus = new Set());
+/**
+ * Write one session's state onto its tmux session, if it changed.
+ *
+ * @param publication - Session identity plus the status word to publish
+ * @returns What was done, for tests and for the caller's logging
+ */
+async function publishSessionStatus(publication) {
+    const { sessionName, worktreeId, cliToolId, instanceId, status } = publication;
+    if (!(0, tmux_session_surface_1.isTmuxStatusEnabled)()) {
+        // The uninstall path. Once per session per process: `clearSessionStatus`
+        // issues six `execFile` calls, and repeating them on every poll of a server
+        // that has the surface turned off would be the cost the feature was turned
+        // off to avoid.
+        if (!cleared.has(sessionName)) {
+            cleared.add(sessionName);
+            await clearSessionStatus(sessionName);
+        }
+        return 'disabled';
+    }
+    const previous = published.get(sessionName);
+    if (previous &&
+        previous.status === status &&
+        previous.worktreeId === worktreeId &&
+        previous.cliToolId === cliToolId &&
+        previous.instanceId === instanceId) {
+        return 'unchanged';
+    }
+    const updated = (publication.now ?? new Date()).toISOString();
+    const writes = [
+        [tmux_session_surface_1.CM_STATUS_OPTION, status],
+        [tmux_session_surface_1.CM_WORKTREE_OPTION, worktreeId],
+        [tmux_session_surface_1.CM_TOOL_OPTION, cliToolId],
+        [tmux_session_surface_1.CM_INSTANCE_OPTION, instanceId],
+        [tmux_session_surface_1.CM_UPDATED_OPTION, updated],
+    ];
+    try {
+        for (const [option, value] of writes) {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildSetSessionOptionArgs)(sessionName, option, value), {
+                timeout: TMUX_TIMEOUT,
+            });
+        }
+        published.set(sessionName, { status, worktreeId, cliToolId, instanceId });
+        // The line renders FROM the options above, so it is installed after them —
+        // a status-right referencing `#{@cm_status}` on a session that has none
+        // paints an empty pair of brackets until the first write lands.
+        await ensureSessionStatusLine(sessionName);
+        return 'written';
+    }
+    catch (error) {
+        // A session that was killed between the poll and this write is the ordinary
+        // case, not an incident. Drop the memo so the next live session under the
+        // same name republishes rather than being deduped against a dead one.
+        published.delete(sessionName);
+        logger.debug('session-status:write-failed', {
+            sessionName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return 'error';
+    }
+}
+/**
+ * Install the session-scoped `status-right`, unless the session already has one.
+ *
+ * "Already has one" means a SESSION-scoped value, which is exactly what
+ * `show-options -t <session> status-right` reports: measured on tmux 3.5a, a
+ * session that never set it answers with empty stdout (the global value is not
+ * echoed), and one that did answers `status-right "…"`. So a user who
+ * customised this session in `.tmux.conf` — or who set it by hand — keeps their
+ * line, and everyone else gets CommandMate's.
+ *
+ * Idempotent: once installed, the value contains {@link CM_STATUS_RIGHT_FORMAT}
+ * and is recognised as ours, so a restart re-installs nothing.
+ *
+ * @param sessionName - Target session
+ * @returns true when the line is CommandMate's after this call
+ */
+async function ensureSessionStatusLine(sessionName) {
+    try {
+        const { stdout } = await execFileAsync('tmux', (0, tmux_session_surface_1.buildShowSessionOptionArgs)(sessionName, 'status-right'), { timeout: TMUX_TIMEOUT });
+        const existing = stdout.trim();
+        if (existing !== '' && !existing.includes(tmux_session_surface_1.CM_STATUS_RIGHT_FORMAT)) {
+            logger.debug('session-status:status-right-user-owned', { sessionName, existing });
+            return false;
+        }
+        if (existing === '') {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildSetStatusRightArgs)(sessionName, tmux_session_surface_1.CM_STATUS_RIGHT_FORMAT), { timeout: TMUX_TIMEOUT });
+        }
+        return true;
+    }
+    catch (error) {
+        logger.debug('session-status:status-right-failed', {
+            sessionName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * Remove every `@cm_*` option and the session-scoped `status-right` we own.
+ *
+ * The `status-right` is only removed when it is still ours — a user who rebound
+ * it after us owns it now, and clobbering that would be the same rudeness
+ * {@link ensureSessionStatusLine} exists to avoid.
+ *
+ * @param sessionName - Target session
+ */
+async function clearSessionStatus(sessionName) {
+    published.delete(sessionName);
+    for (const option of tmux_session_surface_1.CM_SESSION_OPTIONS) {
+        try {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildUnsetSessionOptionArgs)(sessionName, option), {
+                timeout: TMUX_TIMEOUT,
+            });
+        }
+        catch {
+            // Unsetting an option that was never set exits non-zero on some builds.
+        }
+    }
+    try {
+        const { stdout } = await execFileAsync('tmux', (0, tmux_session_surface_1.buildShowSessionOptionArgs)(sessionName, 'status-right'), { timeout: TMUX_TIMEOUT });
+        if (stdout.includes(tmux_session_surface_1.CM_STATUS_RIGHT_FORMAT)) {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildUnsetStatusRightArgs)(sessionName), {
+                timeout: TMUX_TIMEOUT,
+            });
+        }
+    }
+    catch {
+        // Same reasoning as above: nothing here may fail a caller.
+    }
+}
+/**
+ * Forget a session's published state without touching tmux.
+ *
+ * Called when a session is known to be gone. The next session created under the
+ * same name then publishes from scratch instead of being deduped against the
+ * dead one's last status.
+ */
+function forgetSessionStatus(sessionName) {
+    published.delete(sessionName);
+    cleared.delete(sessionName);
+}
+/** Test seam: how many sessions currently have a memoised publication. */
+function publishedSessionCount() {
+    return published.size;
+}