@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/agent/providers/claude/transport/sdk.js

@@ -0,0 +1,219 @@
+import { query, } from "@anthropic-ai/claude-agent-sdk";
+import { tmuxEnabled, tmuxIgnoredOnNonPtyMessage } from "./tmux.js";
+import { createProviderEnv, createProviderEnvSpec, } from "../../../provider-launch-config.js";
+import { buildSelfNodeCommand } from "../../../../paseo-env.js";
+import { spawnProcess } from "../../../../../utils/spawn.js";
+function isChildProcessWithStreams(child) {
+    return child.stdin !== null && child.stdout !== null && child.stderr !== null;
+}
+function resolveClaudeSpawnCommand(spawnOptions, runtimeSettings) {
+    const commandConfig = runtimeSettings?.command;
+    if (!commandConfig || commandConfig.mode === "default") {
+        return {
+            command: spawnOptions.command,
+            args: [...spawnOptions.args],
+        };
+    }
+    if (commandConfig.mode === "append") {
+        return {
+            command: spawnOptions.command,
+            args: [...spawnOptions.args, ...(commandConfig.args ?? [])],
+        };
+    }
+    return {
+        command: commandConfig.argv[0],
+        args: [...commandConfig.argv.slice(1), ...spawnOptions.args],
+    };
+}
+function applyRuntimeSettingsToClaudeOptions(options, runtimeSettings, launchEnv) {
+    return {
+        ...options,
+        spawnClaudeCodeProcess: (spawnOptions) => {
+            const resolved = resolveClaudeSpawnCommand(spawnOptions, runtimeSettings);
+            const isDefaultRuntime = resolved.command === "node" || resolved.command === "bun";
+            const providerEnvSpec = createProviderEnvSpec({
+                baseEnv: spawnOptions.env,
+                runtimeSettings,
+                overlays: [launchEnv],
+            });
+            const providerEnv = createProviderEnv({
+                baseEnv: spawnOptions.env,
+                runtimeSettings,
+                overlays: [launchEnv],
+            });
+            const selfNodeCommand = isDefaultRuntime
+                ? buildSelfNodeCommand(resolved.args, providerEnv)
+                : null;
+            const command = selfNodeCommand?.command ?? resolved.command;
+            const args = selfNodeCommand?.args ?? resolved.args;
+            const child = spawnProcess(command, args, {
+                cwd: spawnOptions.cwd,
+                ...(selfNodeCommand
+                    ? { env: selfNodeCommand.env, envMode: "internal" }
+                    : providerEnvSpec),
+                signal: spawnOptions.signal,
+                stdio: ["pipe", "pipe", "pipe"],
+                shell: false,
+            });
+            if (typeof options.stderr === "function") {
+                child.stderr?.on("data", (chunk) => {
+                    options.stderr?.(chunk.toString());
+                });
+            }
+            if (!isChildProcessWithStreams(child)) {
+                throw new Error("Claude process was spawned without stdio streams");
+            }
+            return child;
+        },
+    };
+}
+/**
+ * Construct a raw SDK Query with the project-standard runtime-settings/env handling
+ * applied. Kept as a free function for tests that exercise the SDK call directly
+ * (see `sdk-behavior.test.ts`, `agent.integration.test.ts`).
+ */
+export function claudeQuery(input, context = {}) {
+    const launchQuery = context.queryFactory ?? query;
+    return launchQuery({
+        ...input,
+        options: applyRuntimeSettingsToClaudeOptions(input.options, context.runtimeSettings, context.launchEnv),
+    });
+}
+/**
+ * SDK transport — wraps the @anthropic-ai/claude-agent-sdk `query()` call behind
+ * the shared `AgentTransport` interface so `ClaudeAgentSession` can dispatch
+ * between SDK and PTY transports uniformly in Story 3.2+.
+ *
+ * In Story 3.1 the pump still consumes the raw `Query` object directly; this
+ * class exists primarily for type-compatibility and to centralize SDK spawn
+ * configuration. `createQuery()` is the transitional helper agent.ts uses to
+ * fetch the underlying `Query` while preserving today's behavior.
+ */
+export class SdkTransport {
+    constructor(opts = {}) {
+        this._cwd = "";
+        this._query = null;
+        this._killed = false;
+        this._exited = false;
+        this.exitHandlers = [];
+        this.runtimeSettings = opts.runtimeSettings;
+        this.launchEnv = opts.launchEnv;
+        this.queryFactory = opts.queryFactory;
+    }
+    /**
+     * Transitional helper for Story 3.1 — agent.ts uses this in `ensureQuery()` to
+     * obtain the underlying `Query` while the pump continues to consume it
+     * directly. Story 3.2 will pivot the pump onto `onHookEvent` and remove this.
+     */
+    createQuery(input) {
+        const q = claudeQuery(input, {
+            runtimeSettings: this.runtimeSettings,
+            launchEnv: this.launchEnv,
+            queryFactory: this.queryFactory,
+        });
+        this._query = q;
+        return q;
+    }
+    async spawn(opts) {
+        // The SDK path is not driven by binary/args/dims like the PTY path is. The
+        // caller is expected to use `createQuery(input)` with a fully-assembled
+        // ClaudeQueryInput. We only record the cwd for context() reporting.
+        this._cwd = opts.cwd;
+        // Someone asked for tmux and is not going to get it. Say so here, because this is the
+        // only place the mismatch is observable: PtyTransport is never constructed on this path,
+        // so its own guards can never fire, and the session otherwise behaves identically to one
+        // that IS under tmux.
+        if (tmuxEnabled(opts.env)) {
+            console.warn(`[paseo] ${tmuxIgnoredOnNonPtyMessage("sdk")}`);
+        }
+    }
+    async write(text) {
+        if (!this._query) {
+            throw new Error("SdkTransport.write called before createQuery()/spawn()");
+        }
+        const message = {
+            type: "user",
+            message: { role: "user", content: text },
+            parent_tool_use_id: null,
+            session_id: "",
+        };
+        // The SDK Query exposes `input.send` via the input channel set up by the
+        // caller's `createAsyncMessageInput`. In Story 3.1 this method is dormant
+        // (the pump still uses the original input directly); Story 3.2 wires it up.
+        const queryWithInput = this._query;
+        await queryWithInput.input?.send(message);
+    }
+    /** True once the SDK query has been closed/returned. Mirrors PtyTransport.exited. */
+    get exited() {
+        return this._exited;
+    }
+    async kill(timeoutMs = 5000) {
+        if (this._killed)
+            return;
+        this._killed = true;
+        if (!this._query)
+            return;
+        const q = this._query;
+        try {
+            q.close?.();
+        }
+        catch {
+            // already closed
+        }
+        const returnPromise = (async () => {
+            try {
+                await q.return?.();
+            }
+            catch {
+                // already returned
+            }
+        })();
+        let timer = null;
+        const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(resolve, timeoutMs);
+        });
+        await Promise.race([returnPromise, timeoutPromise]);
+        if (timer)
+            clearTimeout(timer);
+        this._exited = true;
+        this.fireExit(0, null);
+    }
+    onHookEvent(_handler) {
+        // In Story 3.1 the SDK pump in agent.ts consumes the raw Query iterator
+        // directly. Hook-event translation lives in agent.ts:2593-2820. This
+        // method exists for AgentTransport interface compatibility and will be
+        // populated with the SDK-message → HookEvent mapper in Story 3.2.
+        return () => { };
+    }
+    onData(_handler) {
+        // SDK transport has no raw PTY data stream.
+        return () => { };
+    }
+    onExit(handler) {
+        this.exitHandlers.push(handler);
+        if (this._exited) {
+            handler(0, null);
+        }
+        return () => {
+            this.exitHandlers = this.exitHandlers.filter((h) => h !== handler);
+        };
+    }
+    fireExit(code, signal) {
+        for (const h of this.exitHandlers) {
+            try {
+                h(code, signal);
+            }
+            catch {
+                // handler errors must not break siblings
+            }
+        }
+    }
+    context() {
+        return {
+            transport: "sdk",
+            pid: null,
+            cwd: this._cwd,
+        };
+    }
+}
+//# sourceMappingURL=sdk.js.map

package/dist/server/server/agent/providers/claude/transport/tmux.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Optional tmux multiplexer under the claude PTY.
+ *
+ * WHY THIS EXISTS, and what it does NOT buy. The dead-session bug people reach for tmux to
+ * solve was a missing `onExit` subscription, and it is already fixed in the transport: under
+ * tmux the same bug would simply have been spelled `pane_dead` and been equally unread. What
+ * tmux actually buys is two things nothing else here provides:
+ *
+ *   1. PROCESS OWNERSHIP. The `claude` children belong to the tmux server, not to the daemon.
+ *      Restarting or crashing the daemon no longer takes every live session with it (on
+ *      2026-08-19 one restart killed 21).
+ *   2. A RENDERED-PANE ORACLE. `capture-pane -p` returns the settled screen as text, out of
+ *      band. Delivery currently leans on `QUEUED_FOOTER_RE` matched against a live byte
+ *      stream, which races wrapping and ANSI interleaving; the same regex against a settled
+ *      pane does not.
+ *
+ * OPT-IN, AND POSIX ONLY. Enabled per host with `PASEO_PTY_TMUX=1`. There is no tmux on
+ * Windows and paseo ships an Electron desktop, so this refuses to run there rather than
+ * silently degrading. node-pty is already an optionalDependency that falls back to SDK when
+ * absent; stacking a second silent fallback would make "which transport am I actually on"
+ * unanswerable, so a missing tmux binary is a LOUD error, never a shrug.
+ */
+/** Cols/rows the daemon pins. tmux would otherwise resize to the smallest attached client. */
+export interface TmuxDims {
+    cols: number;
+    rows: number;
+}
+/**
+ * The agent screen every spawned agent gets. Write-once: nothing resizes the pane after
+ * spawn, so this is the size for the life of the session, not a starting guess.
+ *
+ * It lives HERE, exported, because it feeds three consumers that must agree - the node-pty
+ * grid, `new-session -x/-y`, and `set -g default-size` - and it used to be two separate
+ * literals (`DEFAULT_COLS`/`DEFAULT_ROWS` in pty.ts and `DEFAULT_DIMS` in
+ * pty-session-launcher.ts) that agreed only by luck. No test compared them, so bumping one
+ * and not the other would have silently split the pty grid from the tmux window.
+ *
+ * Sizing is asymmetric, which is why rows moved further than cols. The Agent screen sheet
+ * polls `capture-pane` once a second with 200 lines of scrollback, so a frame is
+ * `(rows + 200) x cols`: rows are amortised against that fixed 200, cols multiply every
+ * line of it. Measured against the old 200x50, 220x80 costs 1.23x the bytes for +30 visible
+ * rows, where a wider-but-shorter 240x64 costs more (1.27x) for less (+14). Cols also
+ * reflow the agent's TUI under the stream scrapers, so that is the axis to be stingy on.
+ */
+export declare const DEFAULT_PTY_DIMS: TmuxDims;
+export interface TmuxWrap {
+    binary: string;
+    args: string[];
+    socket: string;
+    session: string;
+}
+export declare function tmuxEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Stable, collision-free session name. */
+export declare function tmuxSessionName(sessionId: string): string;
+/**
+ * Build the argv that runs `binary args...` inside tmux.
+ *
+ * `new-session -A` attaches to an existing session of that name and creates one otherwise,
+ * which is exactly the reattach semantics a daemon restart needs: the agent kept running in
+ * the tmux server, and the new daemon becomes a client of it.
+ */
+export declare function wrapWithTmux(opts: {
+    binary: string;
+    args: string[];
+    cwd: string;
+    sessionId: string;
+    dims: TmuxDims;
+    /** The SAME env that enabled tmux, so PASEO_HOME picks the socket dir consistently. */
+    env: NodeJS.ProcessEnv;
+}): TmuxWrap;
+/**
+ * `PASEO_PTY_TMUX=1` was set on a session that is NOT on the PTY transport.
+ *
+ * The flag is only consulted inside `PtyTransport.spawn`, so on the SDK transport it does
+ * nothing at all: no tmux session, no config written, no error, and the agent works perfectly
+ * on a bare pty. The two outcomes are indistinguishable from the agent's reply, which is
+ * exactly how an hour went into "why is there no tmux session" on 2026-08-22. A fresh
+ * PASEO_HOME is the common way to land here, because it has no `agents.providers` block and
+ * the built-in default is not PTY.
+ *
+ * Warn rather than throw: the session is fine, only the operator's expectation is wrong, and
+ * failing a working agent over a diagnostic would be worse than the confusion it prevents.
+ */
+export declare function tmuxIgnoredOnNonPtyMessage(transport: string): string;
+/** Loud, never a silent downgrade. See the header note on stacked fallbacks. */
+export declare function assertTmuxUsable(): void;
+/**
+ * THE ORACLE: the settled, rendered pane as text, read out of band.
+ *
+ * Everything paseo currently knows about the screen it scrapes from the live byte stream it
+ * is simultaneously racing, which is why `QUEUED_FOOTER_RE` is fragile to wrapping and ANSI
+ * interleaving. This asks tmux for what is actually on screen instead. Returns null rather
+ * than throwing: the caller is always able to fall back to the stream, and a diagnostic must
+ * never be able to fail a turn.
+ */
+export interface CapturePaneOptions {
+    /**
+     * Keep the SGR sequences tmux would otherwise strip, so the capture is the screen as
+     * RENDERED rather than as plain text. Off by default: the diagnostic readers that
+     * predate this want text they can regex, and colour codes only get in their way.
+     */
+    ansi?: boolean;
+    /**
+     * How many scrollback rows to include ABOVE the visible pane. 0 (the default) is the
+     * visible pane alone. tmux counts scrollback backwards from the pane top, which is why
+     * this becomes `-S -<n>`.
+     */
+    scrollbackLines?: number;
+}
+/**
+ * The argv for a capture, split out so the flag mapping is unit-testable without a tmux
+ * server. Every option here is one tmux flag and the mapping is the part worth pinning:
+ * `-e` and `-S` are silently ignored if misspelled, and a capture that quietly loses its
+ * colour is indistinguishable from a pane that has none.
+ */
+export declare function buildCapturePaneArgs(socket: string, session: string, options?: CapturePaneOptions): string[];
+/**
+ * The settled, rendered screen as text, read OUT OF BAND, or null when unavailable.
+ *
+ * Everything paseo currently knows about the screen it scrapes from the live byte stream it
+ * is simultaneously racing, which is why `QUEUED_FOOTER_RE` is fragile to wrapping and ANSI
+ * interleaving. This asks tmux for what is actually on screen instead. Returns null rather
+ * than throwing: the caller is always able to fall back to the stream, and a diagnostic must
+ * never be able to fail a turn.
+ *
+ * ASYNC ON PURPOSE. This was `execFileSync`, which is fine for a once-per-stall diagnostic
+ * and not fine for the pane viewer, which polls it on a timer across every live session. A
+ * synchronous 2s-timeout spawn on the daemon's only event loop stalls every other session
+ * for as long as tmux takes to answer.
+ */
+export declare function capturePane(socket: string, session: string, options?: CapturePaneOptions): Promise<string | null>;
+/** Is the tmux session still alive? An out-of-band liveness check the bare pty cannot offer. */
+export declare function sessionAlive(socket: string, session: string): boolean;
+/**
+ * Kill the SESSION, not merely our client.
+ *
+ * Detaching would leave `claude` running forever, which is the whole point of the design and
+ * therefore also its sharpest edge: `kill()` has to mean kill.
+ */
+export declare function killSession(socket: string, session: string): void;
+//# sourceMappingURL=tmux.d.ts.map

package/dist/server/server/agent/providers/claude/transport/tmux.js

@@ -0,0 +1,218 @@
+import { execFile, execFileSync, spawnSync } from "node:child_process";
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * The agent screen every spawned agent gets. Write-once: nothing resizes the pane after
+ * spawn, so this is the size for the life of the session, not a starting guess.
+ *
+ * It lives HERE, exported, because it feeds three consumers that must agree - the node-pty
+ * grid, `new-session -x/-y`, and `set -g default-size` - and it used to be two separate
+ * literals (`DEFAULT_COLS`/`DEFAULT_ROWS` in pty.ts and `DEFAULT_DIMS` in
+ * pty-session-launcher.ts) that agreed only by luck. No test compared them, so bumping one
+ * and not the other would have silently split the pty grid from the tmux window.
+ *
+ * Sizing is asymmetric, which is why rows moved further than cols. The Agent screen sheet
+ * polls `capture-pane` once a second with 200 lines of scrollback, so a frame is
+ * `(rows + 200) x cols`: rows are amortised against that fixed 200, cols multiply every
+ * line of it. Measured against the old 200x50, 220x80 costs 1.23x the bytes for +30 visible
+ * rows, where a wider-but-shorter 240x64 costs more (1.27x) for less (+14). Cols also
+ * reflow the agent's TUI under the stream scrapers, so that is the axis to be stingy on.
+ */
+export const DEFAULT_PTY_DIMS = { cols: 220, rows: 80 };
+export function tmuxEnabled(env = process.env) {
+    return env.PASEO_PTY_TMUX === "1";
+}
+/** Private socket dir. 0700 because of what these sessions are. */
+function socketDir(env) {
+    const home = env.PASEO_HOME ?? path.join(os.homedir(), ".paseo");
+    const dir = path.join(home, "tmux");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // mkdir's mode is umask-masked, so set it explicitly rather than hoping.
+    chmodSync(dir, 0o700);
+    return dir;
+}
+/**
+ * The config every paseo tmux session runs with. Four settings, each load-bearing, each for a
+ * failure this transport would otherwise hit in production rather than in review.
+ */
+function writeConf(dir, dims) {
+    const conf = path.join(dir, "paseo.tmux.conf");
+    writeFileSync(conf, [
+        // 1. NO PREFIX. paseo writes real control chords straight through to the TUI, including
+        //    Claude Code's `ctrl+x ctrl+k` kill chord, and the protocol layer already encodes
+        //    \x02 (terminal-key-input.test.ts calls it "the tmux prefix"). Leaving the default
+        //    ctrl+b bound means tmux and the agent fight over the keyboard.
+        "set -g prefix None",
+        "set -g prefix2 None",
+        "unbind-key -a",
+        // 2. ESCAPE TIME ZERO. PtyQuery.interrupt() sends a bare \x1b to interrupt a turn.
+        //    tmux's default 500ms escape-time holds that byte back while it waits to see if a
+        //    meta sequence follows, so interrupts would arrive late or be swallowed outright.
+        "set -sg escape-time 0",
+        // 3. NO STATUS BAR. It steals a row from the pane and would land in capture-pane output,
+        //    which is precisely the surface the oracle is supposed to read cleanly.
+        "set -g status off",
+        // 4. SIZE TO THE LARGEST CLIENT, PLUS AN EXPLICIT DEFAULT. tmux sizes a window to its
+        //    SMALLEST attached client by default, so a human attaching from a phone terminal to
+        //    troubleshoot would reflow the agent TUI to 80 columns underneath the daemon and
+        //    silently break every scraper built against the wide layout. The debugging tool must
+        //    not corrupt the thing being debugged.
+        //
+        //    `window-size manual` is the textbook answer and it is NOT USABLE HERE: on tmux
+        //    3.4 both `setw -g window-size manual` and `set -wg window-size manual` CRASH the
+        //    server outright ("server exited unexpectedly", session never created, verified by
+        //    bisecting this file line by line). `largest` achieves what we need anyway - a
+        //    smaller client can no longer shrink the window - and `default-size` pins the
+        //    dimensions a detached session starts at.
+        "set -g window-size largest",
+        `set -g default-size ${dims.cols}x${dims.rows}`,
+        "set -g history-limit 20000",
+        "set -g mouse off",
+        "set -g destroy-unattached off",
+    ].join("\n") + "\n", { mode: 0o600 });
+    return conf;
+}
+/** Stable, collision-free session name. */
+export function tmuxSessionName(sessionId) {
+    return `paseo-${sessionId.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 40)}`;
+}
+/**
+ * Build the argv that runs `binary args...` inside tmux.
+ *
+ * `new-session -A` attaches to an existing session of that name and creates one otherwise,
+ * which is exactly the reattach semantics a daemon restart needs: the agent kept running in
+ * the tmux server, and the new daemon becomes a client of it.
+ */
+export function wrapWithTmux(opts) {
+    // NOTE: assertTmuxUsable() is deliberately NOT called here. This function only builds argv
+    // and writes a config file, so keeping it free of any dependency on a live tmux binary
+    // makes it testable on a host that has none - which is the normal case in CI, where the
+    // image is node:24-slim. The assertion belongs at the spawn boundary (PtyTransport.spawn),
+    // which is the point where a missing binary actually matters.
+    const dir = socketDir(opts.env);
+    const socket = path.join(dir, "paseo.sock");
+    const conf = writeConf(dir, opts.dims);
+    const session = tmuxSessionName(opts.sessionId);
+    return {
+        binary: "tmux",
+        args: [
+            "-S",
+            socket,
+            "-f",
+            conf,
+            "new-session",
+            "-A",
+            "-s",
+            session,
+            "-c",
+            opts.cwd,
+            "-x",
+            String(opts.dims.cols),
+            "-y",
+            String(opts.dims.rows),
+            "--",
+            opts.binary,
+            ...opts.args,
+        ],
+        socket,
+        session,
+    };
+}
+/**
+ * `PASEO_PTY_TMUX=1` was set on a session that is NOT on the PTY transport.
+ *
+ * The flag is only consulted inside `PtyTransport.spawn`, so on the SDK transport it does
+ * nothing at all: no tmux session, no config written, no error, and the agent works perfectly
+ * on a bare pty. The two outcomes are indistinguishable from the agent's reply, which is
+ * exactly how an hour went into "why is there no tmux session" on 2026-08-22. A fresh
+ * PASEO_HOME is the common way to land here, because it has no `agents.providers` block and
+ * the built-in default is not PTY.
+ *
+ * Warn rather than throw: the session is fine, only the operator's expectation is wrong, and
+ * failing a working agent over a diagnostic would be worse than the confusion it prevents.
+ */
+export function tmuxIgnoredOnNonPtyMessage(transport) {
+    return (`PASEO_PTY_TMUX=1 is set but this session is on the "${transport}" transport, so tmux is ` +
+        `NOT in use: the flag is only honoured by the PTY transport. Set ` +
+        `agents.providers.<id>.transport = "pty" in config.json (an explicit "pty" - "auto" does ` +
+        `not activate it) if you meant to run this agent under tmux.`);
+}
+/** Loud, never a silent downgrade. See the header note on stacked fallbacks. */
+export function assertTmuxUsable() {
+    if (process.platform === "win32") {
+        throw new Error("PASEO_PTY_TMUX=1 is set, but tmux does not exist on Windows. Unset it, or run the " +
+            "daemon on a POSIX host. Refusing to silently fall back so the active transport stays knowable.");
+    }
+    const probe = spawnSync("tmux", ["-V"], { encoding: "utf8" });
+    if (probe.error || probe.status !== 0) {
+        throw new Error("PASEO_PTY_TMUX=1 is set, but `tmux -V` did not run. Install tmux or unset the variable. " +
+            "Refusing to silently fall back to a bare pty, because a silent downgrade makes the " +
+            "active transport unknowable (node-pty already degrades to SDK when absent).");
+    }
+}
+/**
+ * The argv for a capture, split out so the flag mapping is unit-testable without a tmux
+ * server. Every option here is one tmux flag and the mapping is the part worth pinning:
+ * `-e` and `-S` are silently ignored if misspelled, and a capture that quietly loses its
+ * colour is indistinguishable from a pane that has none.
+ */
+export function buildCapturePaneArgs(socket, session, options = {}) {
+    const args = ["-S", socket, "capture-pane", "-p"];
+    if (options.ansi)
+        args.push("-e");
+    const scrollback = options.scrollbackLines ?? 0;
+    if (scrollback > 0)
+        args.push("-S", `-${Math.floor(scrollback)}`);
+    args.push("-t", session);
+    return args;
+}
+/**
+ * The settled, rendered screen as text, read OUT OF BAND, or null when unavailable.
+ *
+ * Everything paseo currently knows about the screen it scrapes from the live byte stream it
+ * is simultaneously racing, which is why `QUEUED_FOOTER_RE` is fragile to wrapping and ANSI
+ * interleaving. This asks tmux for what is actually on screen instead. Returns null rather
+ * than throwing: the caller is always able to fall back to the stream, and a diagnostic must
+ * never be able to fail a turn.
+ *
+ * ASYNC ON PURPOSE. This was `execFileSync`, which is fine for a once-per-stall diagnostic
+ * and not fine for the pane viewer, which polls it on a timer across every live session. A
+ * synchronous 2s-timeout spawn on the daemon's only event loop stalls every other session
+ * for as long as tmux takes to answer.
+ */
+export async function capturePane(socket, session, options = {}) {
+    try {
+        const { stdout } = await execFileAsync("tmux", buildCapturePaneArgs(socket, session, options), {
+            encoding: "utf8",
+            timeout: 2000,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch {
+        return null;
+    }
+}
+/** Is the tmux session still alive? An out-of-band liveness check the bare pty cannot offer. */
+export function sessionAlive(socket, session) {
+    const r = spawnSync("tmux", ["-S", socket, "has-session", "-t", session], { timeout: 2000 });
+    return r.status === 0;
+}
+/**
+ * Kill the SESSION, not merely our client.
+ *
+ * Detaching would leave `claude` running forever, which is the whole point of the design and
+ * therefore also its sharpest edge: `kill()` has to mean kill.
+ */
+export function killSession(socket, session) {
+    try {
+        execFileSync("tmux", ["-S", socket, "kill-session", "-t", session], { timeout: 5000 });
+    }
+    catch {
+        // already gone
+    }
+}
+//# sourceMappingURL=tmux.js.map

package/dist/server/server/agent/providers/claude/transport/transcript-sdk-reader.d.ts

@@ -0,0 +1,53 @@
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+export interface UserPromptLine {
+    /** The transcript line's own uuid -- the ONLY id that identifies this turn on disk. */
+    uuid: string;
+    /** Flattened prompt text, used to match the line against the bubble paseo already emitted. */
+    text: string;
+}
+export interface TranscriptSdkReaderOptions {
+    transcriptPath: string;
+    onMessage: (message: SDKMessage) => void;
+    /**
+     * Fired for plain user-prompt lines -- the ones `toSdkMessage` deliberately drops so the
+     * bubble paseo emitted via `emitSubmittedUserMessage` is not double-rendered.
+     *
+     * Dropping them for RENDERING is correct. Dropping their `uuid` is not: on the PTY transport
+     * the prompt is typed into the terminal, so claude mints the transcript uuid itself and the
+     * id paseo minted (agent.ts, `randomUUID()` before the prompt is even sent) is written
+     * nowhere. Edit and Rewind resolve a turn by scanning this file for `uuid === turnId`
+     * (`truncateSessionAt`), so without this hop every edit on PTY fails `turn_not_found`.
+     *
+     * This callback is identity only. It must not emit a message, or the bubble doubles.
+     */
+    onUserPrompt?: (prompt: UserPromptLine) => void;
+}
+export declare class TranscriptSdkReader {
+    private readonly transcriptPath;
+    private readonly onMessage;
+    private readonly onUserPrompt?;
+    private timer;
+    private readOffset;
+    private buffer;
+    constructor(opts: TranscriptSdkReaderOptions);
+    /**
+     * Begin streaming NEW appends. Starts at the current EOF so a `--resume`'d session
+     * (whose transcript already holds the prior conversation) only surfaces new turns.
+     * Poll-based (not fs.watch) so a not-yet-created transcript is handled cleanly — the
+     * file is created by claude only once the first turn begins.
+     */
+    start(): void;
+    stop(): void;
+    /** Drain immediately (used by tests and on final teardown to flush trailing lines). */
+    drainNow(): void;
+    private drain;
+    private handleLine;
+    /**
+     * Surface the transcript uuid of a plain user prompt: exactly the line `toSdkMessage`
+     * returns null for. Deliberately narrow -- a tool_result user line is a different thing
+     * and already reaches the pump as a message.
+     */
+    private notifyUserPrompt;
+    private toSdkMessage;
+}
+//# sourceMappingURL=transcript-sdk-reader.d.ts.map