@wastedcode/claudemux 0.2.0

package/dist/backends/tmux/exec.js

@@ -0,0 +1,226 @@
+import { spawn } from "node:child_process";
+import { BackendError, BackendUnreachable, SessionExists, SessionGone } from "../../errors.js";
+import { Emitter } from "../../util/emitter.js";
+/**
+ * tmux stderr patterns that indicate "the backend's server is not reachable
+ * on this socket." Older tmux says `no server running on /tmp/.../sock`;
+ * tmux ≥3.3 says `error connecting to /tmp/.../sock (No such file or
+ * directory)`. We treat both as the same condition (server's gone).
+ *
+ * Single-source — callers (`sessions.ts`, `classifyTmuxFailure`) import
+ * from here so the regex can't drift.
+ */
+export function isNoServerStderr(text) {
+    return /no server running on/i.test(text) || /error connecting to /i.test(text);
+}
+/**
+ * tmux stderr substrings that indicate "the target you asked about doesn't
+ * exist on this server." tmux emits different `can't find …:` strings
+ * depending on which level of the `session:window.pane` grammar failed.
+ * All three are semantically "the session you wanted isn't here" — callers
+ * that need a boolean (`hasSession`) treat them all as "no" rather than
+ * letting the routine `can't find pane:`/`can't find window:` shapes
+ * escape as `SessionGone` throws.
+ */
+const SESSION_GONE_PATTERNS = ["can't find session:", "can't find pane:", "can't find window:"];
+export function isSessionGoneStderr(text) {
+    const lower = text.toLowerCase();
+    return SESSION_GONE_PATTERNS.some((p) => lower.includes(p));
+}
+/**
+ * tmux stderr shape when `new-session -s <name>` races another process
+ * creating the same target. With the shared default socket (ADR 0006),
+ * concurrent `spawn`s of the same name are routine, and the TOCTOU window
+ * between `create()`'s exists-check and `backend.spawn()` means tmux —
+ * not the substrate's check — sometimes discovers the collision. The
+ * semantically-correct typed error is `SessionExists`, same as a check-time
+ * collision: the substrate refuses to silently adopt either way.
+ */
+export function isDuplicateSessionStderr(text) {
+    return /duplicate session:/i.test(text);
+}
+/**
+ * Default per-invocation timeout. tmux read/control ops (capture-pane,
+ * has-session, new-session, …) return in milliseconds against a healthy
+ * server; 10s is generous headroom. The long-lived "wait for the agent"
+ * budget belongs to `io/wait.ts`'s loop, NOT to a single subprocess — so
+ * a wedged tmux (process alive but unresponsive: NFS stall, server bug,
+ * modal pane) surfaces as a typed `BackendUnreachable[timeout]` inside
+ * `wait()`'s budget rather than hanging the consumer's `await` forever.
+ */
+const DEFAULT_EXEC_TIMEOUT_MS = 10_000;
+/**
+ * One executor instance per backend. Holds the private socket name and the
+ * observability emitter. Every tmux invocation goes through {@link run}; that
+ * is what enforces the `-f /dev/null` + `-L <socket>` discipline tree-wide.
+ *
+ * See `engineer/wiki/tmux-private-server-bootstrap` — bare `-L` does not
+ * prevent `~/.tmux.conf` reads; both flags are required.
+ */
+export class TmuxExec {
+    socket;
+    #events = new Emitter();
+    constructor(socket) {
+        this.socket = socket;
+    }
+    /** Subscribe to every tmux invocation + result. Returns unsubscribe. */
+    onCommand(handler) {
+        return this.#events.on(handler);
+    }
+    /**
+     * Spawn `tmux -L <socket> -f /dev/null <args...>` and capture both streams —
+     * stdout for the op's payload (e.g. `capture-pane`), stderr for failure
+     * classification (`can't find …` → `SessionGone`, etc.).
+     *
+     * @throws `BackendUnreachable` — `spawn-failed` on spawn error (ENOENT,
+     *   EPIPE), `no-server` when the server isn't running on a connect-only
+     *   operation, `timeout` when the invocation doesn't return within
+     *   `opts.timeoutMs` (default {@link DEFAULT_EXEC_TIMEOUT_MS}). The
+     *   session-name field on the typed error is the *requested* session.
+     */
+    async run(args, opts = {}) {
+        const fullArgs = ["-L", this.socket, "-f", "/dev/null", ...args];
+        const sessionName = opts.sessionName ?? "<unknown>";
+        const timeoutMs = opts.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS;
+        const startedAt = Date.now();
+        return new Promise((resolve, reject) => {
+            const child = spawn("tmux", fullArgs, {
+                stdio: [opts.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+                env: process.env,
+            });
+            if (opts.input !== undefined && child.stdin) {
+                child.stdin.write(opts.input);
+                child.stdin.end();
+            }
+            let stdout = "";
+            let stderr = "";
+            let spawnErr = null;
+            let settled = false;
+            // Per-invocation timeout: SIGKILL the child WE spawned (peer-process-safe
+            // by construction — exact PID, ADR 0004) and reject. The `close` handler
+            // still fires after the kill, but `settled` guards against double-settle.
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                child.kill("SIGKILL");
+                reject(new BackendUnreachable(sessionName, "timeout", new Error(`backend command did not return within ${timeoutMs}ms`)));
+            }, timeoutMs);
+            timer.unref?.();
+            child.stdout?.on("data", (b) => {
+                stdout += b.toString("utf8");
+            });
+            child.stderr?.on("data", (b) => {
+                stderr += b.toString("utf8");
+            });
+            child.on("error", (err) => {
+                spawnErr = err;
+            });
+            child.on("close", (code) => {
+                if (settled)
+                    return; // already rejected via timeout
+                settled = true;
+                clearTimeout(timer);
+                const durationMs = Date.now() - startedAt;
+                const exit = code ?? -1;
+                this.#events.emit({
+                    ts: startedAt,
+                    argv: ["tmux", ...fullArgs],
+                    durationMs,
+                    exit,
+                    stdout,
+                    stderr,
+                });
+                if (spawnErr) {
+                    reject(new BackendUnreachable(sessionName, "spawn-failed", spawnErr));
+                    return;
+                }
+                // tmux is on PATH but its server is down on a connect-only
+                // operation. Both shapes ("no server running on …" and
+                // "error connecting to …") are the same condition — promote.
+                // Don't echo the raw stderr (it leaks "tmux" via the socket path).
+                if (exit !== 0 && isNoServerStderr(stderr)) {
+                    reject(new BackendUnreachable(sessionName, "no-server", new Error("no server running on the configured socket")));
+                    return;
+                }
+                resolve({ exit, stdout, stderr, durationMs });
+            });
+        });
+    }
+}
+/**
+ * Classify a non-zero `TmuxResult` into a typed error. Callers use this when
+ * the operation was expected to succeed; for idempotent ops (kill), callers
+ * inspect `result.exit` + stderr directly and choose to swallow SessionGone.
+ *
+ * Returns `null` if the result looks successful (exit 0 with no error
+ * annotation on stdout), otherwise the right typed error to throw.
+ *
+ * `sessionName` is the requested target (so the error carries the right
+ * context even when tmux's stderr names something else).
+ *
+ * Order matters: `BackendUnreachable` (no server) > `SessionExists`
+ * (duplicate-session race) > `SessionGone` (target doesn't exist) >
+ * `BackendError` (unrecognized failure). The routine failure modes are
+ * promoted above `BackendError` so the substrate surfaces a clean typed
+ * error rather than the catch-all. As a structural backstop,
+ * `BackendError.message` itself does not embed the tmux argv (see
+ * `errors.ts`), so even an unclassified shape cannot leak the backend's
+ * vocabulary into user-facing text.
+ */
+export function classifyTmuxFailure(sessionName, argv, result) {
+    if (result.exit === 0)
+        return null;
+    if (isNoServerStderr(result.stderr)) {
+        // Don't echo the backend's stderr (path + "tmux" substring leak).
+        // The clean public summary tells the user what they can do; the raw
+        // stderr is still available via observability (`onBackendCommand`).
+        return new BackendUnreachable(sessionName, "no-server", new Error("no server running on the configured socket"));
+    }
+    if (isDuplicateSessionStderr(result.stderr)) {
+        // A concurrent spawn won the race — same outcome as a check-time
+        // collision. The substrate never silently adopts.
+        return new SessionExists(sessionName);
+    }
+    if (isSessionGoneStderr(result.stderr)) {
+        return new SessionGone(sessionName);
+    }
+    return new BackendError(sessionName, argv, result.exit, result.stderr);
+}
+/** Is this the `no-server` {@link BackendUnreachable} (empty/down server)? */
+export function isNoServer(err) {
+    return err instanceof BackendUnreachable && err.kind === "no-server";
+}
+/**
+ * Run a tmux op that targets ONE named session, applying the **canonical
+ * per-session failure mapping** — the single place reads and writes share so the
+ * same crash can't surface as two different errors again (the read/write drift).
+ *
+ * From a single session's vantage, a `no-server` failure means *this session is
+ * gone* → {@link SessionGone}, NOT a distinct backend fault. (Registry ops —
+ * `list`/`exists` — keep treating no-server as plain absence; `BackendUnreachable`
+ * is left to mean a *real* backend fault: `spawn-failed` / `timeout`.) The
+ * canonical answer holds whether no-server arrives as a rejection (the common
+ * path) or as a returned non-zero result.
+ *
+ * Returns the raw {@link TmuxResult} on success; throws the typed error otherwise.
+ */
+export async function runForSession(exec, args, label, opts = {}) {
+    let r;
+    try {
+        r = await exec.run([...args], { sessionName: label, ...opts });
+    }
+    catch (err) {
+        if (isNoServer(err))
+            throw new SessionGone(label);
+        throw err; // spawn-failed / timeout / a real fault — surface as-is
+    }
+    const classified = classifyTmuxFailure(label, ["tmux", ...args], r);
+    if (classified !== null) {
+        if (isNoServer(classified))
+            throw new SessionGone(label);
+        throw classified;
+    }
+    return r;
+}
+//# sourceMappingURL=exec.js.map

package/dist/backends/tmux/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../../src/backends/tmux/exec.ts"],"names":[],"mappings":"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"}

package/dist/backends/tmux/index.d.ts

@@ -0,0 +1,22 @@
+import { type Backend } from "../types.js";
+/**
+ * Assemble the `Backend` implementation from the tmux subsystem.
+ *
+ * This file is the *only* place where the tmux backend's concrete pieces
+ * compose into the seam contract — and the *only* place that bridges
+ * `SessionRef` → the tmux target-name encoding (`<ns>--<name>`). Callers
+ * outside `src/backends/tmux/**` never construct or parse target strings.
+ *
+ * **Validation policy (QA P1, 7360b35b):** name validation is a *mutating*
+ * concern. `spawn` / `send` / `capture` reject reserved-char names with
+ * `InvalidSessionName` (you cannot meaningfully write to / read from a name
+ * the substrate can't address). But `exists` and `kill` are *query /
+ * idempotent* verbs with total contracts — `exists` returns a boolean,
+ * `kill` is a no-op on a missing session. A reserved-char name simply
+ * *cannot* name a live session, so `exists` → `false` and `kill` → no-op,
+ * rather than throwing and breaking those documented contracts.
+ */
+export declare function tmuxBackend(opts: {
+    socket: string;
+}): Backend;
+//# sourceMappingURL=index.d.ts.map

package/dist/backends/tmux/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backends/tmux/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,OAAO,EAKb,MAAM,aAAa,CAAC;AAOrB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CA+E7D"}

package/dist/backends/tmux/index.js

@@ -0,0 +1,108 @@
+import { InvalidSessionName } from "../../errors.js";
+import { validateNamePart } from "../../session/validate.js";
+import { formatSessionLabel, } from "../types.js";
+import { capturePane } from "./capture.js";
+import { TmuxExec } from "./exec.js";
+import { pasteText, sendKey } from "./keys.js";
+import { getSessionOption, setSessionOption } from "./options.js";
+import { hasSession, killSession, listSessions, newSession, targetOf } from "./sessions.js";
+/**
+ * Assemble the `Backend` implementation from the tmux subsystem.
+ *
+ * This file is the *only* place where the tmux backend's concrete pieces
+ * compose into the seam contract — and the *only* place that bridges
+ * `SessionRef` → the tmux target-name encoding (`<ns>--<name>`). Callers
+ * outside `src/backends/tmux/**` never construct or parse target strings.
+ *
+ * **Validation policy (QA P1, 7360b35b):** name validation is a *mutating*
+ * concern. `spawn` / `send` / `capture` reject reserved-char names with
+ * `InvalidSessionName` (you cannot meaningfully write to / read from a name
+ * the substrate can't address). But `exists` and `kill` are *query /
+ * idempotent* verbs with total contracts — `exists` returns a boolean,
+ * `kill` is a no-op on a missing session. A reserved-char name simply
+ * *cannot* name a live session, so `exists` → `false` and `kill` → no-op,
+ * rather than throwing and breaking those documented contracts.
+ */
+export function tmuxBackend(opts) {
+    const exec = new TmuxExec(opts.socket);
+    // Validate the ref + produce both the tmux-internal target and the public
+    // label. Throws InvalidSessionName for reserved-char names — used by the
+    // mutating/I-O verbs. Defense-in-depth: create() validates at the public
+    // entry; a direct tmuxBackend caller could still bypass that.
+    const refToTarget = (ref) => {
+        validateNamePart("namespace", ref.namespace);
+        validateNamePart("name", ref.name);
+        return { target: targetOf(ref.namespace, ref.name), label: formatSessionLabel(ref) };
+    };
+    // Non-throwing variant for the total query/idempotent verbs. Returns null
+    // when the ref is invalid — an invalid name cannot name a live session.
+    const tryRefToTarget = (ref) => {
+        try {
+            return refToTarget(ref);
+        }
+        catch (err) {
+            if (err instanceof InvalidSessionName)
+                return null;
+            throw err;
+        }
+    };
+    // The mutating/I-O methods are `async` so a synchronous `validateNamePart`
+    // throw becomes a promise *rejection* — consistent with their Promise
+    // return type (a consumer's `.catch` / `await … rejects` works uniformly).
+    return {
+        id: "tmux",
+        spawn: async (o) => {
+            validateNamePart("namespace", o.namespace);
+            validateNamePart("name", o.name);
+            await newSession(exec, {
+                namespace: o.namespace,
+                name: o.name,
+                cwd: o.cwd,
+                ...(o.env ? { env: o.env } : {}),
+                cmd: o.cmd,
+                argv: o.argv,
+                label: formatSessionLabel({ namespace: o.namespace, name: o.name }),
+            });
+        },
+        kill: (ref) => {
+            const t = tryRefToTarget(ref);
+            if (t === null)
+                return Promise.resolve(); // invalid name → nothing to kill
+            return killSession(exec, t.target, t.label);
+        },
+        exists: (ref) => {
+            const t = tryRefToTarget(ref);
+            if (t === null)
+                return Promise.resolve(false); // invalid name can't be alive
+            return hasSession(exec, t.target, t.label);
+        },
+        list: async (namespace) => {
+            validateNamePart("namespace", namespace);
+            return listSessions(exec, namespace);
+        },
+        send: async (ref, payload) => {
+            const { target, label } = refToTarget(ref);
+            await (payload.kind === "paste"
+                ? pasteText(exec, target, payload.text, label)
+                : sendKey(exec, target, payload.key, label));
+        },
+        capture: async (ref, o) => {
+            const { target, label } = refToTarget(ref);
+            return capturePane(exec, target, { ...o, label });
+        },
+        setSessionMeta: async (ref, key, value) => {
+            const { target, label } = refToTarget(ref);
+            await setSessionOption(exec, target, key, value, label);
+        },
+        getSessionMeta: async (ref, key) => {
+            // Total/best-effort, like exists/kill: an invalid name can't name a live
+            // session, so it has no metadata — return undefined rather than throw.
+            const t = tryRefToTarget(ref);
+            if (t === null)
+                return undefined;
+            return getSessionOption(exec, t.target, key, t.label);
+        },
+        onCommand: (h) => exec.onCommand(h),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/backends/tmux/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/backends/tmux/index.ts"],"names":[],"mappings":"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"}

package/dist/backends/tmux/keys.d.ts

@@ -0,0 +1,38 @@
+import { type TmuxExec } from "./exec.js";
+/**
+ * Send a `paste` payload to a tmux session via `load-buffer + paste-buffer -p`.
+ *
+ * `-p` lets tmux emit bracketed-paste sequences if the receiver advertised
+ * support — empirically verified byte-perfect end-to-end against a passive
+ * sink on tmux 3.6 (see `docs/decisions/0001-tmux-paste-mechanism.md`). Body
+ * line terminators normalize
+ * to `\n` so claude (and other TUI agents that opt into bracketed paste)
+ * see literal newlines inside the bracket, not stray `\r`s.
+ *
+ * **Does NOT auto-append Enter.** Submission is a separate `key` call. This
+ * is the architectural lock-in from `engineer/wiki/tmux-private-server-bootstrap`'s
+ * sibling page — multi-line input cannot leak around the seam because
+ * `Backend.send` has no `sendRawText` primitive.
+ *
+ * **Pre-checks liveness.** `send-keys` returns exit 0 against a dead pane
+ * (silent input drop trap — see `engineer/wiki/tmux-pane-death-detection`).
+ * We check `has-session` first; if the session is gone, throw `SessionGone`
+ * rather than letting the paste land in the void.
+ *
+ * `label` is the user-facing identifier used in error messages (defaults to
+ * `target`); the wrapper in `tmuxBackend` passes the public label.
+ */
+/**
+ * Strip control bytes from a paste body that could break out of the bracketed
+ * paste or inject terminal control. The danger (F48): a body containing the
+ * paste-END marker `ESC[201~` closes the bracket early, so its tail submits as
+ * *typed* input — content carrying terminal escapes (logs, diffs, adversarial
+ * input) could run commands. Keep `\n` (literal newlines — the point of bracketed
+ * paste) and `\t`; drop the bracketed-paste markers explicitly (no `[201~`
+ * residue) plus every other C0/DEL control byte (incl. bare ESC). Normalize CRs
+ * to `\n` BEFORE stripping so a lone `\r` becomes a newline, not nothing.
+ */
+export declare function sanitizePasteBody(text: string): string;
+export declare function pasteText(exec: TmuxExec, target: string, text: string, label?: string): Promise<void>;
+export declare function sendKey(exec: TmuxExec, target: string, key: "Enter" | "Escape" | "1" | "2" | "3" | "y" | "n", label?: string): Promise<void>;
+//# sourceMappingURL=keys.d.ts.map

package/dist/backends/tmux/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/backends/tmux/keys.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,QAAQ,EAAiB,MAAM,WAAW,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUtD;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAsB,OAAO,CAC3B,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,OAAO,GAAG,QAAQ,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,EACrD,KAAK,GAAE,MAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/backends/tmux/keys.js

@@ -0,0 +1,63 @@
+import { randomBytes } from "node:crypto";
+import { SessionGone } from "../../errors.js";
+import { runForSession } from "./exec.js";
+import { hasSession } from "./sessions.js";
+/**
+ * Send a `paste` payload to a tmux session via `load-buffer + paste-buffer -p`.
+ *
+ * `-p` lets tmux emit bracketed-paste sequences if the receiver advertised
+ * support — empirically verified byte-perfect end-to-end against a passive
+ * sink on tmux 3.6 (see `docs/decisions/0001-tmux-paste-mechanism.md`). Body
+ * line terminators normalize
+ * to `\n` so claude (and other TUI agents that opt into bracketed paste)
+ * see literal newlines inside the bracket, not stray `\r`s.
+ *
+ * **Does NOT auto-append Enter.** Submission is a separate `key` call. This
+ * is the architectural lock-in from `engineer/wiki/tmux-private-server-bootstrap`'s
+ * sibling page — multi-line input cannot leak around the seam because
+ * `Backend.send` has no `sendRawText` primitive.
+ *
+ * **Pre-checks liveness.** `send-keys` returns exit 0 against a dead pane
+ * (silent input drop trap — see `engineer/wiki/tmux-pane-death-detection`).
+ * We check `has-session` first; if the session is gone, throw `SessionGone`
+ * rather than letting the paste land in the void.
+ *
+ * `label` is the user-facing identifier used in error messages (defaults to
+ * `target`); the wrapper in `tmuxBackend` passes the public label.
+ */
+/**
+ * Strip control bytes from a paste body that could break out of the bracketed
+ * paste or inject terminal control. The danger (F48): a body containing the
+ * paste-END marker `ESC[201~` closes the bracket early, so its tail submits as
+ * *typed* input — content carrying terminal escapes (logs, diffs, adversarial
+ * input) could run commands. Keep `\n` (literal newlines — the point of bracketed
+ * paste) and `\t`; drop the bracketed-paste markers explicitly (no `[201~`
+ * residue) plus every other C0/DEL control byte (incl. bare ESC). Normalize CRs
+ * to `\n` BEFORE stripping so a lone `\r` becomes a newline, not nothing.
+ */
+export function sanitizePasteBody(text) {
+    return (text
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n")
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping them is the point.
+        .replace(/\x1b\[20[01]~/g, "")
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping them is the point.
+        .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ""));
+}
+export async function pasteText(exec, target, text, label = target) {
+    await ensureLive(exec, target, label);
+    const normalized = sanitizePasteBody(text);
+    const bufferName = `claudemux-${randomBytes(4).toString("hex")}`;
+    await runForSession(exec, ["load-buffer", "-b", bufferName, "-"], label, { input: normalized });
+    await runForSession(exec, ["paste-buffer", "-p", "-d", "-b", bufferName, "-t", target], label);
+}
+export async function sendKey(exec, target, key, label = target) {
+    await ensureLive(exec, target, label);
+    await runForSession(exec, ["send-keys", "-t", target, key], label);
+}
+async function ensureLive(exec, target, label) {
+    if (!(await hasSession(exec, target, label))) {
+        throw new SessionGone(label);
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/backends/tmux/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/backends/tmux/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAiB,aAAa,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,CACL,IAAI;SACD,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC;SACtB,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC;QACrB,wFAAwF;SACvF,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;QAC9B,wFAAwF;SACvF,OAAO,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAC5C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAc,EACd,MAAc,EACd,IAAY,EACZ,QAAgB,MAAM;IAEtB,MAAM,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAEtC,MAAM,UAAU,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,aAAa,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IAEjE,MAAM,aAAa,CAAC,IAAI,EAAE,CAAC,aAAa,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IAChG,MAAM,aAAa,CAAC,IAAI,EAAE,CAAC,cAAc,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,CAAC;AACjG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,IAAc,EACd,MAAc,EACd,GAAqD,EACrD,QAAgB,MAAM;IAEtB,MAAM,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACtC,MAAM,aAAa,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;AACrE,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAc,EAAE,MAAc,EAAE,KAAa;IACrE,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC"}

package/dist/backends/tmux/options.d.ts

@@ -0,0 +1,24 @@
+import { type TmuxExec } from "./exec.js";
+/**
+ * Build the argv prefix that sets all server-globals, ready to be `;`-joined
+ * with a `new-session` (or any other command) into one tmux invocation.
+ *
+ * Returns chunks separated by `;` markers — callers concat with the next
+ * command's argv.
+ */
+export declare function serverOptionsArgv(): string[];
+/**
+ * Persist a session-scoped key/value as a tmux user option on `target`. The
+ * value is passed as a single argv element (no shell), so no escaping is
+ * needed. The option lives with the session and is dropped when the session
+ * is killed — no cleanup required.
+ */
+export declare function setSessionOption(exec: TmuxExec, target: string, key: string, value: string, label?: string): Promise<void>;
+/**
+ * Read a session user option previously set via {@link setSessionOption}.
+ * Returns `undefined` when the option is unset or the session/server is
+ * unreadable — this is best-effort metadata, never a hard error. `-v` prints
+ * just the value; an unset user option yields empty output (trimmed → unset).
+ */
+export declare function getSessionOption(exec: TmuxExec, target: string, key: string, label?: string): Promise<string | undefined>;
+//# sourceMappingURL=options.d.ts.map

package/dist/backends/tmux/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../src/backends/tmux/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAuB,MAAM,WAAW,CAAC;AA4B/D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAM5C;AAYD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,MAAe,GACrB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAY7B"}

package/dist/backends/tmux/options.js

@@ -0,0 +1,84 @@
+import { classifyTmuxFailure } from "./exec.js";
+/**
+ * Argv chunks that set the substrate's four server-global tmux options.
+ * Joined into a multi-command invocation in front of `new-session` so the
+ * globals are set **in the same tmux client connection** that creates the
+ * session — see `engineer/wiki/tmux-private-server-bootstrap`.
+ *
+ * Why this shape: `start-server` does not keep the server alive on its own
+ * (tmux exits the server when no session remains). `set-option -g` against
+ * an empty server fails with "no server running." Combining all commands
+ * into one `tmux …` invocation with `;` separators avoids the dead-window
+ * between "server starts" and "first session lands."
+ *
+ * `history-limit` is allocated at pane creation, so it must be set as a
+ * `-g` window-option BEFORE the pane is created. The other three follow the
+ * same pattern for consistency.
+ *
+ * `LC_ALL=C.UTF-8` lives on the session env (`-e` on new-session), so it is
+ * not in this list.
+ */
+const SERVER_OPTION_COMMANDS = [
+    ["set-option", "-g", "escape-time", "0"],
+    ["set-option", "-g", "default-terminal", "tmux-256color"],
+    ["set-window-option", "-g", "history-limit", "50000"],
+    ["set-window-option", "-g", "remain-on-exit", "off"],
+];
+/**
+ * Build the argv prefix that sets all server-globals, ready to be `;`-joined
+ * with a `new-session` (or any other command) into one tmux invocation.
+ *
+ * Returns chunks separated by `;` markers — callers concat with the next
+ * command's argv.
+ */
+export function serverOptionsArgv() {
+    const out = [];
+    for (const cmd of SERVER_OPTION_COMMANDS) {
+        out.push(...cmd, ";");
+    }
+    return out;
+}
+/**
+ * Map a backend-neutral session-meta key to a tmux **session user option**.
+ * User option names must begin with `@`; we further namespace under
+ * `@claudemux-` so the substrate's keys never collide with a consumer's own
+ * tmux options on the shared server.
+ */
+function userOptionName(key) {
+    return `@claudemux-${key}`;
+}
+/**
+ * Persist a session-scoped key/value as a tmux user option on `target`. The
+ * value is passed as a single argv element (no shell), so no escaping is
+ * needed. The option lives with the session and is dropped when the session
+ * is killed — no cleanup required.
+ */
+export async function setSessionOption(exec, target, key, value, label = target) {
+    const args = ["set-option", "-t", target, userOptionName(key), value];
+    const r = await exec.run(args, { sessionName: label });
+    const err = classifyTmuxFailure(label, ["tmux", ...args], r);
+    if (err)
+        throw err;
+}
+/**
+ * Read a session user option previously set via {@link setSessionOption}.
+ * Returns `undefined` when the option is unset or the session/server is
+ * unreadable — this is best-effort metadata, never a hard error. `-v` prints
+ * just the value; an unset user option yields empty output (trimmed → unset).
+ */
+export async function getSessionOption(exec, target, key, label = target) {
+    let r;
+    try {
+        r = await exec.run(["show-options", "-t", target, "-v", userOptionName(key)], {
+            sessionName: label,
+        });
+    }
+    catch {
+        return undefined; // session gone / no server / wedged — treat as "unset"
+    }
+    if (r.exit !== 0)
+        return undefined;
+    const v = r.stdout.trim();
+    return v.length > 0 ? v : undefined;
+}
+//# sourceMappingURL=options.js.map

package/dist/backends/tmux/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/backends/tmux/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,sBAAsB,GAAqC;IAC/D,CAAC,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC;IACxC,CAAC,YAAY,EAAE,IAAI,EAAE,kBAAkB,EAAE,eAAe,CAAC;IACzD,CAAC,mBAAmB,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC;IACrD,CAAC,mBAAmB,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,CAAC;CACrD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,GAAG,IAAI,sBAAsB,EAAE,CAAC;QACzC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,GAAW;IACjC,OAAO,cAAc,GAAG,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAc,EACd,MAAc,EACd,GAAW,EACX,KAAa,EACb,QAAgB,MAAM;IAEtB,MAAM,IAAI,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IACtE,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;IACvD,MAAM,GAAG,GAAG,mBAAmB,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7D,IAAI,GAAG;QAAE,MAAM,GAAG,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAc,EACd,MAAc,EACd,GAAW,EACX,QAAgB,MAAM;IAEtB,IAAI,CAAuC,CAAC;IAC5C,IAAI,CAAC;QACH,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE;YAC5E,WAAW,EAAE,KAAK;SACnB,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,CAAC,uDAAuD;IAC3E,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACnC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC1B,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACtC,CAAC"}