@hyperdrive.bot/paseo-server 0.3.41 → 0.3.43

package/dist/server/server/agent/providers/claude/background-work-kinds.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The complete census of background work a Claude Code session can hold open.
+ *
+ * WHY THIS FILE EXISTS
+ *
+ * `deriveAgentStateBucket` ends in `return "done"`. That makes "done" the
+ * FALLTHROUGH: any kind of background work nobody taught the system about
+ * becomes invisible by construction, not by decision. Monitors and crons sat in
+ * that blind spot for the life of the feature — a session with an armed monitor
+ * reported zero background tasks, bucketed as "done", and looked idle while it
+ * was actively watching.
+ *
+ * The fix is not "remember to add a pattern". It is to enumerate what we
+ * SILENCE rather than what we want, so an unlisted kind is merely noisy (a
+ * failing build) instead of invisible (a lying UI).
+ *
+ * HOW IT FAILS LOUDLY
+ *
+ * `BACKGROUND_WORK_KINDS` is declared `satisfies Record<BackgroundWorkKind, …>`.
+ * Add a member to the union without adding its entry here and the TYPE CHECK
+ * fails. Add an entry claiming `tracked: true` without a start pattern that
+ * actually extracts its id and `background-work-kinds.test.ts` fails.
+ *
+ * SAMPLES ARE CAPTURES, NOT TRANSCRIPTIONS
+ *
+ * Every `sample` below was pasted verbatim out of a live session's tool_result
+ * on 2026-08-22. Do not tidy them. This repo has already shipped a regex that
+ * passed 21 green tests against hand-typed fixtures while being broken in
+ * production, because the real text was prose and every fixture was a clean
+ * one-liner. If you add a kind, capture its real string first.
+ */
+/** Every flavour of background work, tracked or deliberately not. */
+export type BackgroundWorkKind = "shell" | "monitor" | "cron" | "scheduled_wakeup" | "subagent";
+interface TrackedKind {
+    tracked: true;
+    /** Human label for the UI ("pending · monitoring deploy.log"). */
+    label: string;
+    /** Verbatim capture of the harness text that announces a start. */
+    sample: string;
+    /** The id the sample must yield, proving the pattern actually works. */
+    expectedId: string;
+    /** Where the record is retired. */
+    retiredBy: string;
+    /** Which module owns the tracking. */
+    trackedBy: string;
+}
+interface SilencedKind {
+    tracked: false;
+    label: string;
+    /**
+     * Why this kind does NOT keep an agent alive. Must be a real, specific
+     * reason — "not implemented yet" is one, and an honest one. What is not
+     * allowed is for a kind to be absent from this file entirely.
+     */
+    silencedBecause: string;
+}
+export type BackgroundWorkKindEntry = TrackedKind | SilencedKind;
+export declare const BACKGROUND_WORK_KINDS: {
+    readonly shell: {
+        readonly tracked: true;
+        readonly label: "background shell";
+        readonly sample: "Command running in background with ID: beuhoixae. Output is being written to: /tmp/x/beuhoixae.output. You will be notified when it completes.";
+        readonly expectedId: "beuhoixae";
+        readonly retiredBy: "<task-notification> with a terminal <status>";
+        readonly trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText";
+    };
+    readonly monitor: {
+        readonly tracked: true;
+        readonly label: "monitor";
+        readonly sample: "Monitor started (task b6dxcqe9y, timeout 20000ms). You will be notified on each event. Keep working — do not poll or sleep.";
+        readonly expectedId: "b6dxcqe9y";
+        readonly retiredBy: "<task-notification> with a terminal <status>";
+        readonly trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText";
+    };
+    readonly cron: {
+        readonly tracked: true;
+        readonly label: "scheduled job";
+        readonly sample: "Scheduled recurring job b8df03d3 (Every Wednesday at 4:23 AM). Session-only (not written to disk, dies when Claude exits). Auto-expires after 7 days. Use CronDelete to cancel sooner.";
+        readonly expectedId: "b8df03d3";
+        readonly retiredBy: "\"Cancelled job <id>.\" in a later tool_result";
+        readonly trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText";
+    };
+    readonly scheduled_wakeup: {
+        readonly tracked: false;
+        readonly label: "scheduled wakeup";
+        readonly silencedBecause: "ScheduleWakeup only exists inside /loop dynamic mode, and invoking it to capture its announcement would schedule a real wakeup of the capturing session. No verbatim capture has been taken yet, and this module's rule is that a pattern is written from a real string or not at all. A /loop session's transcript must be captured before this can move to tracked:true. Until then a dynamic /loop between wakeups buckets as done.";
+    };
+    readonly subagent: {
+        readonly tracked: false;
+        readonly label: "subagent";
+        readonly silencedBecause: "Live subagents DO keep the parent alive, but not through this tracker: they arrive as their own agent snapshots and are attributed to the delegation root in workspace-directory.applyAgentBucketContributions (server) and countActiveChildrenByParent (app). Counting them here as well would double-count them.";
+    };
+};
+export {};
+//# sourceMappingURL=background-work-kinds.d.ts.map

package/dist/server/server/agent/providers/claude/background-work-kinds.js

@@ -0,0 +1,73 @@
+/**
+ * The complete census of background work a Claude Code session can hold open.
+ *
+ * WHY THIS FILE EXISTS
+ *
+ * `deriveAgentStateBucket` ends in `return "done"`. That makes "done" the
+ * FALLTHROUGH: any kind of background work nobody taught the system about
+ * becomes invisible by construction, not by decision. Monitors and crons sat in
+ * that blind spot for the life of the feature — a session with an armed monitor
+ * reported zero background tasks, bucketed as "done", and looked idle while it
+ * was actively watching.
+ *
+ * The fix is not "remember to add a pattern". It is to enumerate what we
+ * SILENCE rather than what we want, so an unlisted kind is merely noisy (a
+ * failing build) instead of invisible (a lying UI).
+ *
+ * HOW IT FAILS LOUDLY
+ *
+ * `BACKGROUND_WORK_KINDS` is declared `satisfies Record<BackgroundWorkKind, …>`.
+ * Add a member to the union without adding its entry here and the TYPE CHECK
+ * fails. Add an entry claiming `tracked: true` without a start pattern that
+ * actually extracts its id and `background-work-kinds.test.ts` fails.
+ *
+ * SAMPLES ARE CAPTURES, NOT TRANSCRIPTIONS
+ *
+ * Every `sample` below was pasted verbatim out of a live session's tool_result
+ * on 2026-08-22. Do not tidy them. This repo has already shipped a regex that
+ * passed 21 green tests against hand-typed fixtures while being broken in
+ * production, because the real text was prose and every fixture was a clean
+ * one-liner. If you add a kind, capture its real string first.
+ */
+export const BACKGROUND_WORK_KINDS = {
+    shell: {
+        tracked: true,
+        label: "background shell",
+        sample: "Command running in background with ID: beuhoixae. Output is being written to: /tmp/x/beuhoixae.output. You will be notified when it completes.",
+        expectedId: "beuhoixae",
+        retiredBy: "<task-notification> with a terminal <status>",
+        trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText",
+    },
+    monitor: {
+        tracked: true,
+        label: "monitor",
+        sample: "Monitor started (task b6dxcqe9y, timeout 20000ms). You will be notified on each event. Keep working — do not poll or sleep.",
+        expectedId: "b6dxcqe9y",
+        // Confirmed live: the monitor's completion arrives as the SAME
+        // <task-notification> envelope, same <task-id>, <status>completed</status>.
+        // Only its START was ever invisible.
+        retiredBy: "<task-notification> with a terminal <status>",
+        trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText",
+    },
+    cron: {
+        tracked: true,
+        label: "scheduled job",
+        sample: "Scheduled recurring job b8df03d3 (Every Wednesday at 4:23 AM). Session-only (not written to disk, dies when Claude exits). Auto-expires after 7 days. Use CronDelete to cancel sooner.",
+        expectedId: "b8df03d3",
+        // A cron emits NO task-notification. "Cancelled job <id>." in a later
+        // tool_result is its only retirement signal — note the glued-on period.
+        retiredBy: '"Cancelled job <id>." in a later tool_result',
+        trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText",
+    },
+    scheduled_wakeup: {
+        tracked: false,
+        label: "scheduled wakeup",
+        silencedBecause: "ScheduleWakeup only exists inside /loop dynamic mode, and invoking it to capture its announcement would schedule a real wakeup of the capturing session. No verbatim capture has been taken yet, and this module's rule is that a pattern is written from a real string or not at all. A /loop session's transcript must be captured before this can move to tracked:true. Until then a dynamic /loop between wakeups buckets as done.",
+    },
+    subagent: {
+        tracked: false,
+        label: "subagent",
+        silencedBecause: "Live subagents DO keep the parent alive, but not through this tracker: they arrive as their own agent snapshots and are attributed to the delegation root in workspace-directory.applyAgentBucketContributions (server) and countActiveChildrenByParent (app). Counting them here as well would double-count them.",
+    },
+};
+//# sourceMappingURL=background-work-kinds.js.map

package/dist/server/server/agent/providers/claude/pty-session-launcher.js

@@ -47,6 +47,9 @@ export async function createPtySession(opts) {
         cwd: realCwd,
         env,
         dims: opts.dims ?? DEFAULT_DIMS,
+        // Names the tmux session deterministically when PASEO_PTY_TMUX=1, so a daemon restart
+        // reattaches this agent rather than spawning a second one alongside it.
+        sessionId: opts.sessionId,
         ...(systemPromptFilePath ? { systemPromptFilePath } : {}),
     });
     const query = new PtyQuery({

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

@@ -59,6 +59,8 @@ export declare class PtyTransport implements AgentTransport {
     private hookBuffer;
     private bridgeClose;
     private systemPromptFilePath;
+    /** Set only when PASEO_PTY_TMUX=1 wrapped this spawn. Null means a bare pty. */
+    private tmux;
     /**
      * Has the child process exited?
      *
@@ -102,6 +104,21 @@ export declare class PtyTransport implements AgentTransport {
     onHookEvent(handler: (event: HookEvent) => void): () => void;
     onData(handler: (chunk: string) => void): () => void;
     onExit(handler: (code: number | null, signal: NodeJS.Signals | null) => void): () => void;
+    /**
+     * The settled, rendered screen as text, read OUT OF BAND, or null when unavailable.
+     *
+     * This is the reason to run tmux at all. Everything paseo knows about the screen today is
+     * scraped from the live byte stream it is simultaneously racing, which is why the queued
+     * footer match is fragile to wrapping and ANSI interleaving. Null on a bare pty and on any
+     * tmux error, so a caller must always keep its stream-based path: a diagnostic that can
+     * fail a turn is worse than no diagnostic.
+     */
+    capturePane(): string | null;
+    /** Multiplexer identity, for logs and tests. Null on a bare pty. */
+    get multiplexer(): {
+        socket: string;
+        session: string;
+    } | null;
     context(): AgentTransportContext;
 }
 export {};

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

@@ -2,6 +2,7 @@ import { unlink } from "node:fs";
 import { createRequire } from "node:module";
 import { setTimeout as delay } from "node:timers/promises";
 import { redactChunk } from "./redact.js";
+import { assertTmuxUsable, capturePane, killSession, tmuxEnabled, wrapWithTmux } from "./tmux.js";
 const DEFAULT_COLS = 200;
 const DEFAULT_ROWS = 50;
 const DEFAULT_KILL_TIMEOUT_MS = 5000;
@@ -83,6 +84,8 @@ export class PtyTransport {
         this.hookBuffer = [];
         this.bridgeClose = null;
         this.systemPromptFilePath = null;
+        /** Set only when PASEO_PTY_TMUX=1 wrapped this spawn. Null means a bare pty. */
+        this.tmux = null;
     }
     /**
      * Has the child process exited?
@@ -142,7 +145,30 @@ export class PtyTransport {
         this._cols = cols;
         this._rows = rows;
         this.systemPromptFilePath = opts.systemPromptFilePath ?? null;
-        this._pty = pty.spawn(opts.binary, opts.args, {
+        // Optionally run the agent inside tmux. The daemon's pty then holds a tmux CLIENT rather
+        // than the agent itself, so the agent survives this process: `new-session -A` reattaches
+        // an existing session and creates one otherwise, which is the reattach a daemon restart
+        // needs. Exit detection is unaffected - when the agent exits, its tmux session ends, our
+        // client exits, and node-pty's onExit fires exactly as before.
+        let binary = opts.binary;
+        let args = opts.args;
+        if (tmuxEnabled(opts.env)) {
+            // Assert at the boundary where a missing binary actually matters. wrapWithTmux() stays
+            // pure so it can be unit-tested on a host without tmux (CI runs node:24-slim).
+            assertTmuxUsable();
+            const wrap = wrapWithTmux({
+                binary: opts.binary,
+                args: opts.args,
+                cwd: opts.cwd,
+                sessionId: opts.sessionId ?? `${process.pid}-${this._cols}x${this._rows}`,
+                dims: { cols, rows },
+                env: opts.env,
+            });
+            binary = wrap.binary;
+            args = wrap.args;
+            this.tmux = { socket: wrap.socket, session: wrap.session };
+        }
+        this._pty = pty.spawn(binary, args, {
             name: "xterm-256color",
             cols,
             rows,
@@ -231,6 +257,12 @@ export class PtyTransport {
             }
             this.bridgeClose = null;
         }
+        // Under tmux, killing our client only DETACHES: the agent would keep running forever,
+        // which is the design working against us here. kill() has to mean kill, so end the
+        // session first and let the client fall out with it.
+        if (this.tmux) {
+            killSession(this.tmux.socket, this.tmux.session);
+        }
         if (!this._pty)
             return;
         try {
@@ -285,6 +317,24 @@ export class PtyTransport {
             this.exitHandlers = this.exitHandlers.filter((h) => h !== handler);
         };
     }
+    /**
+     * The settled, rendered screen as text, read OUT OF BAND, or null when unavailable.
+     *
+     * This is the reason to run tmux at all. Everything paseo knows about the screen today is
+     * scraped from the live byte stream it is simultaneously racing, which is why the queued
+     * footer match is fragile to wrapping and ANSI interleaving. Null on a bare pty and on any
+     * tmux error, so a caller must always keep its stream-based path: a diagnostic that can
+     * fail a turn is worse than no diagnostic.
+     */
+    capturePane() {
+        if (!this.tmux)
+            return null;
+        return capturePane(this.tmux.socket, this.tmux.session);
+    }
+    /** Multiplexer identity, for logs and tests. Null on a bare pty. */
+    get multiplexer() {
+        return this.tmux ? { ...this.tmux } : null;
+    }
     context() {
         if (!this._pty) {
             throw new Error("PtyTransport.context called before spawn()");

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

@@ -0,0 +1,74 @@
+/**
+ * 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;
+}
+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;
+/** 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 declare function capturePane(socket: string, session: string): 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,157 @@
+import { 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";
+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,
+    };
+}
+/** 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 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 function capturePane(socket, session) {
+    try {
+        return execFileSync("tmux", ["-S", socket, "capture-pane", "-p", "-t", session], {
+            encoding: "utf8",
+            timeout: 2000,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+    }
+    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/types.d.ts

@@ -14,6 +14,12 @@ export interface AgentTransportSpawnOptions {
      * transport is responsible for unlinking this file in kill().
      */
     systemPromptFilePath?: string;
+    /**
+     * The claude session id, used to name a tmux session deterministically so a restarted
+     * daemon reattaches the SAME agent instead of starting a second one beside it. Optional
+     * because a bare pty has no use for it.
+     */
+    sessionId?: string;
 }
 export type AgentTransportContext = {
     transport: "pty";

package/dist/server/server/agent/providers/opencode-agent.d.ts

@@ -165,6 +165,13 @@ export interface OpenCodeEventTranslationState {
     pendingChildToolPartsBySessionId?: Map<string, OpenCodeToolPartEventPart[]>;
     modelContextWindowsByModelKey?: ReadonlyMap<string, number>;
     onAssistantModelContextWindowResolved?: (contextWindowMaxTokens: number) => void;
+    /**
+     * Invoked when a provider "retry" status carries a DETERMINISTIC, non-retryable
+     * error. opencode never gives up on a retry on its own (it backs off and retries
+     * forever), so for these the agent must abort the underlying opencode session or
+     * the turn wedges on an infinite retry loop. See isTerminalProviderRetryMessage.
+     */
+    onTerminalProviderRetry?: (message: string) => void;
 }
 type OpenCodeToolPartEventPart = Extract<Extract<OpenCodeEvent, {
     type: "message.part.updated";

package/dist/server/server/agent/providers/opencode-agent.js

@@ -1925,6 +1925,29 @@ function appendOpenCodeSessionError(event, state, events) {
         });
     }
 }
+/**
+ * Some opencode "retry" errors are DETERMINISTIC: the exact request that failed
+ * will fail identically on every retry, so opencode's retry-forever policy turns
+ * them into a permanent wedge (endless "Provider retry" lines, spinner never ends,
+ * the turn never reaches a terminal state). We only match the failure whose
+ * unrecoverability is provable from the request itself.
+ *
+ * Deliberately NARROW. Notably EXCLUDED (kept retryable on purpose):
+ *  - "model does not exist" / "not found": ollama and other backends lazy-load a
+ *    model on first use, so this can resolve mid-retry once the model finishes
+ *    loading. A unit test pins this as non-terminal.
+ *  - auth failures (401 / invalid api key): a token can be refreshed out of band
+ *    between retries in some provider setups.
+ *
+ * Currently the sole member is the model server rejecting a request that has no
+ * user-role message (e.g. ollama 0.32.x "no user query found in messages"). The
+ * message array cannot gain a user turn on retry, so it never recovers. Add a new
+ * pattern here only when its unrecoverability is likewise provable.
+ */
+const TERMINAL_PROVIDER_RETRY_PATTERNS = [/no user query found in messages/i];
+function isTerminalProviderRetryMessage(message) {
+    return message.length > 0 && TERMINAL_PROVIDER_RETRY_PATTERNS.some((re) => re.test(message));
+}
 function appendOpenCodeSessionStatus(event, state, events) {
     if (event.properties.sessionID !== state.sessionId) {
         return;
@@ -1936,12 +1959,32 @@ function appendOpenCodeSessionStatus(event, state, events) {
         return;
     }
     if (status.type === "retry") {
+        const message = typeof status.message === "string" ? status.message.trim() : "";
+        // A deterministic provider error fails identically on every retry, and
+        // opencode never gives up on its own. Fail the turn cleanly and ask the agent
+        // to abort the opencode session so it stops backing off forever.
+        if (isTerminalProviderRetryMessage(message)) {
+            events.push({
+                type: "timeline",
+                provider: "opencode",
+                item: {
+                    type: "error",
+                    message: `Provider gave up (non-retryable after attempt ${status.attempt}): ${message}`,
+                },
+            });
+            state.onTerminalProviderRetry?.(message);
+            events.push({
+                type: "turn_failed",
+                provider: "opencode",
+                error: message,
+            });
+            return;
+        }
         // Mirror what opencode's TUI shows: retry attempts are visible activity, not
         // terminal. opencode itself never gives up — it backs off and tries again
         // forever. If we silently swallow these the user sees a spinner with no
         // explanation. Forwarding as a timeline error item is a no-op for old
         // clients (the schema already supports it).
-        const message = typeof status.message === "string" ? status.message.trim() : "";
         const text = message
             ? `Provider retry (attempt ${status.attempt}): ${message}`
             : `Provider retry (attempt ${status.attempt})`;
@@ -2801,6 +2844,13 @@ class OpenCodeAgentSession {
                     this.selectedModelContextWindowMaxTokens = contextWindowMaxTokens;
                 }
             },
+            onTerminalProviderRetry: () => {
+                // The translated turn_failed already ends the turn for our clients; this
+                // aborts opencode's session so its own retry-forever loop stops hammering
+                // the provider in the background. Best-effort: an abort failure must not
+                // mask the terminal turn_failed.
+                void this.beginSessionAbort(this.activeForegroundTurnId, "provider_error").catch(() => { });
+            },
         });
         const events = [];
         if (typeof this.accumulatedUsage.totalCostUsd === "number") {

package/dist/server/server/bootstrap.js

@@ -669,6 +669,7 @@ export async function createPaseoDaemon(config, rootLogger) {
     const workflowManager = new WorkflowManager({
         agentManager,
         storage: workflowStorage,
+        logger,
     });
     // Story 2.1 — read-only HTTP status + SSE phase-transition routes. Gated on the
     // same WORKFLOWS_FEATURE_ENABLED constant as the server_info handshake flag.

package/dist/server/server/session.js

@@ -1202,6 +1202,7 @@ export class Session {
                 baseConfig,
                 ...(msg.title ? { title: msg.title } : {}),
                 ...(msg.labels ? { labels: msg.labels } : {}),
+                ...(msg.agentPresets ? { agentPresets: msg.agentPresets } : {}),
             });
             const started = await manager.startWorkflow(workflow.id);
             this.emit({