@hyperdrive.bot/paseo-server 0.3.40 → 0.3.42

package/dist/server/server/agent/providers/claude/tool-allowlist-guard.js

@@ -0,0 +1,93 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { SPECIFIER_SOURCES, escapeLiteral, isToolAllowed, readSpecifierValue, specifierMatches, } from "./tool-allowlist.js";
+/** Quote a path for a POSIX/`sh -c` hook command line. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** The standalone `PreToolUse` hook script, with the rules baked in. */
+export function buildGuardScript(rules) {
+    return `#!/usr/bin/env node
+// GENERATED by paseo (tool-allowlist-guard.ts). Do not edit; regenerated per session.
+import { readFileSync } from "node:fs";
+
+const RULES = ${JSON.stringify(rules)};
+const SPECIFIER_SOURCES = ${JSON.stringify(SPECIFIER_SOURCES)};
+
+const escapeLiteral = ${escapeLiteral.toString()};
+const specifierMatches = ${specifierMatches.toString()};
+const readSpecifierValue = ${readSpecifierValue.toString()};
+const isToolAllowed = ${isToolAllowed.toString()};
+
+let raw = "";
+try {
+  raw = readFileSync(0, "utf8");
+} catch {
+  raw = "";
+}
+let event = {};
+try {
+  event = JSON.parse(raw);
+} catch {
+  event = {};
+}
+const toolName = typeof event.tool_name === "string" ? event.tool_name : "";
+const toolInput = event.tool_input ?? {};
+
+// Fail closed: an unreadable event is not a licence to run an unknown tool.
+if (!toolName || !isToolAllowed(toolName, toolInput, RULES)) {
+  const listed = RULES.map((r) => (r.specifier === undefined ? r.tool : r.tool + "(" + r.specifier + ")")).join(", ");
+  process.stderr.write(
+    'Tool "' + (toolName || "<unknown>") + '" is blocked by this run\\'s tool allowlist and was not executed. ' +
+      "Allowed: " + listed + ". Do not retry this tool; achieve the goal with an allowed tool or report that you cannot.\\n",
+  );
+  process.exit(2);
+}
+process.exit(0);
+`;
+}
+/** The `--settings` payload that registers the guard for every tool call. */
+export function buildGuardSettings(nodeBinary, guardPath) {
+    return `${JSON.stringify({
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: "*",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `${shellQuote(nodeBinary)} ${shellQuote(guardPath)}`,
+                        },
+                    ],
+                },
+            ],
+        },
+    }, null, 2)}\n`;
+}
+/**
+ * Write the guard script + settings file for a session. Returns null when the
+ * allowlist is empty, i.e. no allowlist was configured and nothing is enforced.
+ */
+export function writeGuardArtifacts(options) {
+    if (options.rules.length === 0)
+        return null;
+    const dir = path.join(options.baseDir, `tool-allowlist-${options.sessionId}`);
+    mkdirSync(dir, { recursive: true });
+    const guardPath = path.join(dir, "guard.mjs");
+    const settingsPath = path.join(dir, "settings.json");
+    writeFileSync(guardPath, buildGuardScript(options.rules), { mode: 0o700 });
+    writeFileSync(settingsPath, buildGuardSettings(options.nodeBinary ?? process.execPath, guardPath));
+    return { dir, settingsPath, guardPath };
+}
+/** Best-effort teardown for `writeGuardArtifacts`. */
+export function removeGuardArtifacts(artifacts) {
+    if (!artifacts)
+        return;
+    try {
+        rmSync(artifacts.dir, { recursive: true, force: true });
+    }
+    catch {
+        // teardown is best effort — a leftover temp dir must never fail a session
+    }
+}
+//# sourceMappingURL=tool-allowlist-guard.js.map

package/dist/server/server/agent/providers/claude/tool-allowlist.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Per-run tool allowlist enforcement for the claude provider.
+ *
+ * WHY A HOOK AND NOT `--allowedTools`
+ * -----------------------------------
+ * `--allowedTools` (CLI) and `options.allowedTools` (SDK) are *permission allow
+ * rules*: they pre-approve a tool so it does not prompt. They do not restrict
+ * anything. Both of paseo's claude transports also run the child with
+ * `--dangerously-skip-permissions` / `allowDangerouslySkipPermissions`, under
+ * which every permission rule is moot, so passing an allowlist there would be
+ * decorative: accepted, parsed, and silently unenforcing.
+ *
+ * A `PreToolUse` hook is the one gate that still fires in that state. The Agent
+ * SDK says so explicitly (sdk.d.ts, PermissionDeniedHookInput): "PreToolUse hook
+ * denies bypass canUseTool". Verified against claude 2.1.239 with
+ * `--permission-mode acceptEdits --dangerously-skip-permissions`: a hook exiting
+ * 2 blocked a Bash call while an allowlisted Read call went through.
+ *
+ * FAIL CLOSED
+ * -----------
+ * When an allowlist is configured, anything this module cannot positively match
+ * is DENIED. A matcher that is too strict fails loudly (the model is told which
+ * rule set rejected it, and the run keeps going), while a matcher that is too
+ * lax fails silently and hands back a guarantee that is not real. Strictness is
+ * the safe direction, so unknown rule shapes and unknown specifier sources deny.
+ *
+ * Note this is *stricter* than `claude-pool launch --allowedTools`, where tools
+ * that never request permission (Read, Grep, TodoWrite, ...) were unaffected by
+ * the allowlist. Here the allowlist means exactly what it says: a tool absent
+ * from it cannot run at all.
+ */
+export interface ToolAllowRule {
+    /** Tool name, e.g. "Bash", "Read", "mcp__playwright-personal__browser_navigate". */
+    readonly tool: string;
+    /** Optional specifier from `Tool(specifier)` form, e.g. "git:*". */
+    readonly specifier?: string;
+}
+/** Tools whose specifier (the `Tool(spec)` argument) we know how to read off the input. */
+export declare const SPECIFIER_SOURCES: Record<string, string>;
+/**
+ * Parse CSV-or-array allowlist entries into rules. Entries are the same strings
+ * Claude Code permission rules use: `Bash`, `Bash(git:*)`, `Read`,
+ * `mcp__server__tool`. Blank entries are dropped.
+ */
+export declare function parseToolAllowlist(entries: readonly string[]): ToolAllowRule[];
+/** Escape a literal for use inside a RegExp, leaving `*` to be expanded by the caller. */
+export declare function escapeLiteral(value: string): string;
+/**
+ * Match a Claude-Code-style specifier pattern against a value.
+ *
+ * Supported shapes (anything else denies):
+ *  - `*`          any value
+ *  - `prefix:*`   value starts with `prefix` (Claude Code's command-prefix form)
+ *  - `glob`       `*` wildcards, everything else literal, anchored both ends
+ */
+export declare function specifierMatches(pattern: string, value: string): boolean;
+/** Read the specifier value a `Tool(spec)` rule compares against, or null when unknown. */
+export declare function readSpecifierValue(toolName: string, input: unknown): string | null;
+/**
+ * True when `toolName` (with `input`) is permitted by `rules`.
+ *
+ * An EMPTY rule list means "no allowlist configured" and allows everything; the
+ * caller is responsible for not installing the guard at all in that case.
+ */
+export declare function isToolAllowed(toolName: string, input: unknown, rules: readonly ToolAllowRule[]): boolean;
+/** The message handed back to the model when a call is blocked. */
+export declare function formatDenialMessage(toolName: string, rules: readonly ToolAllowRule[]): string;
+//# sourceMappingURL=tool-allowlist.d.ts.map

package/dist/server/server/agent/providers/claude/tool-allowlist.js

@@ -0,0 +1,133 @@
+/**
+ * Per-run tool allowlist enforcement for the claude provider.
+ *
+ * WHY A HOOK AND NOT `--allowedTools`
+ * -----------------------------------
+ * `--allowedTools` (CLI) and `options.allowedTools` (SDK) are *permission allow
+ * rules*: they pre-approve a tool so it does not prompt. They do not restrict
+ * anything. Both of paseo's claude transports also run the child with
+ * `--dangerously-skip-permissions` / `allowDangerouslySkipPermissions`, under
+ * which every permission rule is moot, so passing an allowlist there would be
+ * decorative: accepted, parsed, and silently unenforcing.
+ *
+ * A `PreToolUse` hook is the one gate that still fires in that state. The Agent
+ * SDK says so explicitly (sdk.d.ts, PermissionDeniedHookInput): "PreToolUse hook
+ * denies bypass canUseTool". Verified against claude 2.1.239 with
+ * `--permission-mode acceptEdits --dangerously-skip-permissions`: a hook exiting
+ * 2 blocked a Bash call while an allowlisted Read call went through.
+ *
+ * FAIL CLOSED
+ * -----------
+ * When an allowlist is configured, anything this module cannot positively match
+ * is DENIED. A matcher that is too strict fails loudly (the model is told which
+ * rule set rejected it, and the run keeps going), while a matcher that is too
+ * lax fails silently and hands back a guarantee that is not real. Strictness is
+ * the safe direction, so unknown rule shapes and unknown specifier sources deny.
+ *
+ * Note this is *stricter* than `claude-pool launch --allowedTools`, where tools
+ * that never request permission (Read, Grep, TodoWrite, ...) were unaffected by
+ * the allowlist. Here the allowlist means exactly what it says: a tool absent
+ * from it cannot run at all.
+ */
+/** Tools whose specifier (the `Tool(spec)` argument) we know how to read off the input. */
+export const SPECIFIER_SOURCES = {
+    Bash: "command",
+    BashOutput: "bash_id",
+    Read: "file_path",
+    Edit: "file_path",
+    Write: "file_path",
+    NotebookEdit: "notebook_path",
+    WebFetch: "url",
+    Glob: "pattern",
+    Grep: "pattern",
+};
+/**
+ * Parse CSV-or-array allowlist entries into rules. Entries are the same strings
+ * Claude Code permission rules use: `Bash`, `Bash(git:*)`, `Read`,
+ * `mcp__server__tool`. Blank entries are dropped.
+ */
+export function parseToolAllowlist(entries) {
+    const rules = [];
+    for (const raw of entries) {
+        for (const piece of raw.split(",")) {
+            const entry = piece.trim();
+            if (!entry)
+                continue;
+            const match = /^([^()\s]+)\((.*)\)$/.exec(entry);
+            if (match?.[1] !== undefined && match[2] !== undefined) {
+                rules.push({ tool: match[1], specifier: match[2].trim() });
+            }
+            else {
+                rules.push({ tool: entry });
+            }
+        }
+    }
+    return rules;
+}
+/** Escape a literal for use inside a RegExp, leaving `*` to be expanded by the caller. */
+export function escapeLiteral(value) {
+    return value.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Match a Claude-Code-style specifier pattern against a value.
+ *
+ * Supported shapes (anything else denies):
+ *  - `*`          any value
+ *  - `prefix:*`   value starts with `prefix` (Claude Code's command-prefix form)
+ *  - `glob`       `*` wildcards, everything else literal, anchored both ends
+ */
+export function specifierMatches(pattern, value) {
+    if (pattern === "*")
+        return true;
+    const prefixForm = /^(.*):\*$/.exec(pattern);
+    if (prefixForm?.[1] !== undefined) {
+        const prefix = prefixForm[1].trim();
+        if (!prefix)
+            return false;
+        return value === prefix || value.startsWith(`${prefix} `);
+    }
+    const expanded = pattern.split("*").map(escapeLiteral).join(".*");
+    return new RegExp(`^${expanded}$`).test(value);
+}
+/** Read the specifier value a `Tool(spec)` rule compares against, or null when unknown. */
+export function readSpecifierValue(toolName, input) {
+    const key = SPECIFIER_SOURCES[toolName];
+    if (!key)
+        return null;
+    if (typeof input !== "object" || input === null)
+        return null;
+    const value = input[key];
+    return typeof value === "string" ? value : null;
+}
+/**
+ * True when `toolName` (with `input`) is permitted by `rules`.
+ *
+ * An EMPTY rule list means "no allowlist configured" and allows everything; the
+ * caller is responsible for not installing the guard at all in that case.
+ */
+export function isToolAllowed(toolName, input, rules) {
+    if (rules.length === 0)
+        return true;
+    for (const rule of rules) {
+        if (rule.tool !== toolName)
+            continue;
+        if (rule.specifier === undefined)
+            return true;
+        const value = readSpecifierValue(toolName, input);
+        // Unknown specifier source: we cannot verify the rule, so we do not honor it.
+        if (value === null)
+            continue;
+        if (specifierMatches(rule.specifier, value))
+            return true;
+    }
+    return false;
+}
+/** The message handed back to the model when a call is blocked. */
+export function formatDenialMessage(toolName, rules) {
+    const listed = rules
+        .map((rule) => (rule.specifier === undefined ? rule.tool : `${rule.tool}(${rule.specifier})`))
+        .join(", ");
+    return (`Tool "${toolName}" is blocked by this run's tool allowlist and was not executed. ` +
+        `Allowed: ${listed}. Do not retry this tool; achieve the goal with an allowed tool or report that you cannot.`);
+}
+//# sourceMappingURL=tool-allowlist.js.map

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";