@crouton-kit/crouter 0.3.70 → 0.3.79

package/dist/core/runtime/session-list-cache.js

@@ -0,0 +1,338 @@
+// Broker-side cache for the `/resume` session picker's `list_sessions` reply.
+//
+// pi's `SessionManager.list()` reads EVERY `.jsonl` in a cwd's session dir in
+// full, line-by-line, to build each session's `allMessagesText` search field.
+// On a large corpus (3.3k files / 1.1 GiB here) that is ~3.6s of CPU-bound
+// JSON.parse on EVERY picker open — pi exposes no per-file entry point and no
+// cache. This module keeps a `(mtimeMs, size)`-keyed cache of the already-wire-
+// shaped, search-text-bounded `WireSessionInfo`: on each open it stats every
+// file (cheap — ~260ms for 3.3k) and rebuilds info ONLY for new/changed files,
+// reusing cached entries for the rest and dropping deleted ones. The cache is
+// persisted to one global JSON file so the first open after a broker restart is
+// also fast.
+//
+// `buildWireSessionInfo` below is a faithful mirror of pi's private
+// `buildSessionInfo` (node_modules/@earendil-works/pi-coding-agent/dist/core/
+// session-manager.js) — it is not exported, so the only way to rebuild a single
+// file's info without re-reading the whole corpus is to reproduce its parse.
+// Keep it in sync with pi's session-file format (CURRENT_SESSION_VERSION).
+import { createReadStream } from 'node:fs';
+import { readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { dirname, join } from 'node:path';
+/** Search-text bound: `allMessagesText` is searched on every query edit; pi's
+ *  unbounded value retains gigabytes in the viewer and turns key-repeat into GC
+ *  jitter. The opening and latest text keep search useful. */
+const SESSION_SEARCH_TEXT_CHARS = 1024;
+export function compactSessionSearchText(text) {
+    if (text.length <= SESSION_SEARCH_TEXT_CHARS)
+        return text;
+    const half = SESSION_SEARCH_TEXT_CHARS / 2;
+    return `${text.slice(0, half)} … ${text.slice(-half)}`;
+}
+const MAX_CONCURRENT_INFO_LOADS = 10;
+/** Persisted-file schema version. Bump whenever `CacheEntry`'s shape (or
+ *  `WireSessionInfo`'s) changes: on a version mismatch the whole file is
+ *  discarded and rebuilt from disk — no per-entry migration, no lenient
+ *  recovery (the cache is fully derivable). */
+const CACHE_SCHEMA_VERSION = 1;
+/** The full map is tens of MB (~15 MB for one cwd, ~46 MB for `all`); a
+ *  synchronous `JSON.stringify` of it must never sit on the reply path. Persists
+ *  are coalesced onto this trailing timer so rapid opens write at most once per
+ *  window, off the hot path. */
+const PERSIST_DEBOUNCE_MS = 2000;
+/** Shape-check a loaded entry — a well-formed-JSON file with the right version
+ *  but a stale entry shape (e.g. missing `info`) would otherwise push undefined
+ *  into the sort and throw. Any failure discards the whole file (rebuild). */
+function isValidEntry(e) {
+    if (typeof e !== 'object' || e === null)
+        return false;
+    const c = e;
+    return (typeof c['mtimeMs'] === 'number' &&
+        typeof c['size'] === 'number' &&
+        typeof c['info'] === 'object' &&
+        c['info'] !== null &&
+        typeof c['info']['modified'] === 'string');
+}
+// ---- faithful mirror of pi's private buildSessionInfo -----------------------
+function parseLine(line) {
+    if (!line.trim())
+        return null;
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+function extractTextContent(message) {
+    const content = message['content'];
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join(' ');
+}
+function messageActivityTime(entry) {
+    const message = entry['message'];
+    if (!message || !('content' in message))
+        return undefined;
+    const role = message['role'];
+    if (role !== 'user' && role !== 'assistant')
+        return undefined;
+    const ts = message['timestamp'];
+    if (typeof ts === 'number')
+        return ts;
+    const t = new Date(entry['timestamp']).getTime();
+    return Number.isNaN(t) ? undefined : t;
+}
+/** Build one session's wire info by streaming the file. Returns null for a
+ *  malformed/headerless file (matches pi, which drops those from the list). */
+async function buildWireSessionInfo(filePath) {
+    try {
+        const stats = await stat(filePath);
+        let header = null;
+        let messageCount = 0;
+        let firstMessage = '';
+        const allMessages = [];
+        let name;
+        let lastActivityTime;
+        const rl = createInterface({
+            input: createReadStream(filePath, { encoding: 'utf8' }),
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            const entry = parseLine(line);
+            if (!entry)
+                continue;
+            if (!header) {
+                if (entry['type'] !== 'session')
+                    return null;
+                header = entry;
+                continue;
+            }
+            if (entry['type'] === 'session_info') {
+                name = entry['name']?.trim() || undefined;
+            }
+            if (entry['type'] !== 'message')
+                continue;
+            messageCount++;
+            const activityTime = messageActivityTime(entry);
+            if (typeof activityTime === 'number') {
+                lastActivityTime = Math.max(lastActivityTime ?? 0, activityTime);
+            }
+            const message = entry['message'];
+            if (!message || !('content' in message))
+                continue;
+            const role = message['role'];
+            if (role !== 'user' && role !== 'assistant')
+                continue;
+            const textContent = extractTextContent(message);
+            if (!textContent)
+                continue;
+            allMessages.push(textContent);
+            if (!firstMessage && role === 'user')
+                firstMessage = textContent;
+        }
+        if (!header)
+            return null;
+        const cwd = typeof header['cwd'] === 'string' ? header['cwd'] : '';
+        const headerTime = typeof header['timestamp'] === 'string' ? new Date(header['timestamp']).getTime() : NaN;
+        const modified = typeof lastActivityTime === 'number' && lastActivityTime > 0
+            ? new Date(lastActivityTime)
+            : !Number.isNaN(headerTime)
+                ? new Date(headerTime)
+                : stats.mtime;
+        return {
+            path: filePath,
+            id: header['id'],
+            cwd,
+            name,
+            parentSessionPath: header['parentSession'],
+            created: new Date(header['timestamp']).toISOString(),
+            modified: modified.toISOString(),
+            messageCount,
+            firstMessage: firstMessage || '(no messages)',
+            // Cache the already-bounded wire form (the selector searches this field).
+            allMessagesText: compactSessionSearchText(allMessages.join(' ')),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ---- the cache ---------------------------------------------------------------
+/** In-memory + file-backed cache keyed by absolute `.jsonl` path. One instance
+ *  per broker; the file is shared across brokers (last-writer-wins via atomic
+ *  rename — a lost update just costs one file's rebuild next open, never
+ *  corruption). */
+export class SessionListCache {
+    cacheFile;
+    cache = new Map();
+    loaded = false;
+    persisting = false;
+    persistAgain = false;
+    persistTimer = null;
+    constructor(cacheFile) {
+        this.cacheFile = cacheFile;
+    }
+    /** Fire-and-forget warm of the cwd scope at broker start, so the first
+     *  `/resume` open after this broker launches is already warm. The cold scan
+     *  streams each file via readline (yields per chunk), so it never blocks the
+     *  broker loop — pre-warming beats worker threads here. Errors are swallowed
+     *  by the same paths that guard a normal open. */
+    prewarm(sessionDir) {
+        void this.listDir(sessionDir);
+    }
+    /** Sessions for one cwd's session dir (the picker's default `cwd` scope). */
+    async listDir(sessionDir) {
+        return this.build(await jsonlFiles(sessionDir), new Set([sessionDir]));
+    }
+    /** Sessions across every cwd's dir under the sessions root (`all` scope). */
+    async listAll(sessionsRoot) {
+        let dirEntries;
+        try {
+            dirEntries = (await readdir(sessionsRoot, { withFileTypes: true }))
+                .filter((e) => e.isDirectory())
+                .map((e) => join(sessionsRoot, e.name));
+        }
+        catch {
+            return [];
+        }
+        const files = [];
+        for (const dir of dirEntries)
+            files.push(...(await jsonlFiles(dir)));
+        return this.build(files, new Set(dirEntries));
+    }
+    async build(files, scannedDirs) {
+        await this.ensureLoaded();
+        const present = new Set(files);
+        let changed = false;
+        // Prune ONLY keys under the dirs we actually scanned. A cwd-scope open must
+        // not evict other cwds' cached entries: they weren't rescanned, so their
+        // absence from `files` says nothing about whether they still exist on disk.
+        // (Pruning the whole map here would self-destruct the global/`all` cache on
+        // every cwd open.)
+        for (const key of this.cache.keys()) {
+            if (!present.has(key) && scannedDirs.has(dirname(key))) {
+                this.cache.delete(key);
+                changed = true;
+            }
+        }
+        // Positioned by file index so equal-`modified` ties keep readdir order
+        // deterministically (workers finish out of order); a stable sort preserves it.
+        const infos = new Array(files.length);
+        let next = 0;
+        const worker = async () => {
+            for (;;) {
+                const i = next++;
+                if (i >= files.length)
+                    return;
+                const file = files[i];
+                if (file === undefined)
+                    return;
+                const st = await stat(file).catch(() => null);
+                if (!st) {
+                    if (this.cache.delete(file))
+                        changed = true;
+                    continue;
+                }
+                const cached = this.cache.get(file);
+                if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) {
+                    infos[i] = cached.info;
+                    continue;
+                }
+                const info = await buildWireSessionInfo(file);
+                changed = true;
+                if (!info) {
+                    this.cache.delete(file);
+                    continue;
+                }
+                this.cache.set(file, { mtimeMs: st.mtimeMs, size: st.size, info });
+                infos[i] = info;
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENT_INFO_LOADS, files.length) }, () => worker()));
+        if (changed)
+            this.schedulePersist();
+        const result = infos.filter((x) => x !== undefined);
+        result.sort((a, b) => new Date(b.modified).getTime() - new Date(a.modified).getTime());
+        return result;
+    }
+    async ensureLoaded() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const raw = JSON.parse(await readFile(this.cacheFile, 'utf8'));
+            // Version mismatch or shape drift → discard and rebuild. No lenient
+            // multi-path recovery: the cache is derivable, so a bad file is just
+            // overwritten on the next persist.
+            if (raw?.version !== CACHE_SCHEMA_VERSION || typeof raw.entries !== 'object')
+                return;
+            for (const [path, entry] of Object.entries(raw.entries)) {
+                if (!isValidEntry(entry)) {
+                    this.cache.clear();
+                    return;
+                }
+                this.cache.set(path, entry);
+            }
+        }
+        catch {
+            // Missing or corrupt cache file → start empty and rebuild.
+            this.cache.clear();
+        }
+    }
+    /** Coalesce persists onto a single trailing timer so the tens-of-MB
+     *  `JSON.stringify` never runs on the reply path and rapid opens write once. */
+    schedulePersist() {
+        if (this.persistTimer)
+            return;
+        this.persistTimer = setTimeout(() => {
+            this.persistTimer = null;
+            void this.persist();
+        }, PERSIST_DEBOUNCE_MS);
+        this.persistTimer.unref?.();
+    }
+    /** Atomic write (temp + rename) so a concurrent reader never sees a partial
+     *  file. Coalesces overlapping writes into one trailing flush. */
+    async persist() {
+        if (this.persisting) {
+            this.persistAgain = true;
+            return;
+        }
+        this.persisting = true;
+        const tmp = `${this.cacheFile}.${process.pid}.tmp`;
+        try {
+            const entries = {};
+            for (const [path, entry] of this.cache)
+                entries[path] = entry;
+            const payload = { version: CACHE_SCHEMA_VERSION, entries };
+            await writeFile(tmp, JSON.stringify(payload));
+            await rename(tmp, this.cacheFile);
+        }
+        catch {
+            // Best-effort: a failed persist only costs a rebuild next open. Clean up
+            // the temp file so a failed write never leaks it.
+            await unlink(tmp).catch(() => { });
+        }
+        finally {
+            this.persisting = false;
+            if (this.persistAgain) {
+                this.persistAgain = false;
+                void this.persist();
+            }
+        }
+    }
+}
+async function jsonlFiles(dir) {
+    try {
+        return (await readdir(dir)).filter((f) => f.endsWith('.jsonl')).map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/core/runtime/spawn.js

@@ -12,7 +12,6 @@
 import { spawn } from 'node:child_process';
 import { readdirSync, existsSync } from 'node:fs';
 import { isAbsolute, resolve, join } from 'node:path';
-import { homedir } from 'node:os';
 import { spawnNode, currentNodeContext, rootOfSpine, newNodeId } from './nodes.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
 import { selectProfileForCwd } from '../profiles/select.js';
@@ -24,10 +23,11 @@ import { writeGoal } from './kickoff.js';
 import { appendSituationalContext } from './situational-context.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
-import { installMenuBinding, installNavBindings, installViewNavBindings } from './tmux-chrome.js';
+import { installTmuxBindings } from './tmux-chrome.js';
 import { getNode, fullName, recordPid } from '../canvas/index.js';
 import { registerViewerFocus, openViewerWindow, waitForBrokerViewSocket, viewerSplitEnv, windowOfPane, currentTmux, inTmux, focusWindow, } from './placement.js';
 import { transition } from './lifecycle.js';
+import { piSessionsRoot } from './pi-vendored.js';
 import { headlessBrokerHost } from './host.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 // ---------------------------------------------------------------------------
@@ -72,9 +72,13 @@ export async function bootRoot(opts) {
     // covering cwd > a synchronous create-or-root-profile prompt (the stable root
     // profile, headless).
     const profileId = await selectProfileForCwd(opts.cwd, opts.profile, opts.pickProfile ?? false);
+    // Immediate feedback: the broker + viewer boot take ~1s and the profile
+    // selector has just released the terminal — a silent cursor reads as a hang.
+    if (process.stdout.isTTY)
+        process.stdout.write('\u001b[2m  › starting…\u001b[0m\r\n');
     // A born-resident root starts in base mode; it earns the orchestrator persona
     // the first time it delegates (or on promotion). Resident lifecycle either way.
-    const { launch } = buildLaunchSpec(kind, 'base', { lifecycle: 'resident', hasManager: false });
+    const { launch } = buildLaunchSpec(kind, 'base', { lifecycle: 'resident', hasManager: false, cwd: opts.cwd, profileId });
     // Born WITHOUT a name. Naming is async + event-driven: the canvas-goal-capture
     // extension names the node from its FIRST real message (the kickoff prompt or
     // a human's first line) inside its own pi process, via a headless `pi -p`.
@@ -93,18 +97,9 @@ export async function bootRoot(opts) {
     // mandate (bare `crtr` has none — writeGoal no-ops on empty).
     if (opts.prompt !== undefined)
         writeGoal(meta.node_id, opts.prompt);
-    // Make the Alt+C action menu + Alt+] / Alt+[ node-nav keys + Alt+V then ]/[
-    // view-nav chord live on this server (idempotent; guaranteed in tmux above).
+    // Reconcile the crouter-owned tmux bindings on this server.
     try {
-        installMenuBinding();
-    }
-    catch { /* best-effort */ }
-    try {
-        installNavBindings();
-    }
-    catch { /* best-effort */ }
-    try {
-        installViewNavBindings();
+        installTmuxBindings();
     }
     catch { /* best-effort */ }
     // This terminal becomes the root's attach VIEWER in the user's CURRENT session,
@@ -140,19 +135,14 @@ export async function bootRoot(opts) {
         throw new Error(`failed to launch the broker engine for the front-door root ${meta.node_id} — nothing to attach to.`);
     }
     recordPid(meta.node_id, placed.pid);
-    // The terminal has nothing to attach to until view.sock accepts. The root is
-    // useless without its engine, so a socket timeout IS fatal here (unlike a
-    // background child's optional viewer, which is skipped on timeout).
-    if (!(await waitForBrokerViewSocket(meta.node_id, placed.exited))) {
-        try {
-            transition(meta.node_id, 'crash');
-        }
-        catch {
-            /* best-effort cleanup */
-        }
-        throw new Error(`the front-door root broker ${meta.node_id} never bound its view socket — cannot attach.`);
-    }
-    const attachEnv = { ...process.env, ...viewerSplitEnv() };
+    // Spawn the attach viewer NOW, in parallel with the broker's boot: the
+    // viewer's own `crtr` cold start (~0.4s of module load) then overlaps the
+    // broker's ~1s view-socket bind instead of serializing after it — this was
+    // the bulk of the post-profile-pick dead air. CRTR_ATTACH_WAIT_MS tells the
+    // viewer to poll view.sock until it accepts (preWaitForViewSocket in
+    // attach-cmd.ts) instead of failing fast on the not-yet-bound socket; the
+    // deadline mirrors placement's BROKER_FOCUS_SOCKET_WAIT_MS.
+    const attachEnv = { ...process.env, ...viewerSplitEnv(), CRTR_ATTACH_WAIT_MS: '30000' };
     // Async, NOT spawnSync: a synchronous spawn would park THIS process's own
     // event loop for the whole attach session (which legitimately runs for
     // hours) — starving it of the SIGCHLD delivery it needs to reap its OWN
@@ -165,23 +155,36 @@ export async function bootRoot(opts) {
     // reap it in real time; `stdio: 'inherit'` still hands the child the TTY
     // directly, so this is a behavior-neutral swap for the foreground session.
     const attachChild = spawn('crtr', ['surface', 'attach', 'to', meta.node_id], { stdio: 'inherit', env: attachEnv });
-    const code = await new Promise((resolveCode) => {
+    const attachExit = new Promise((resolveCode) => {
         attachChild.once('exit', (exitCode) => resolveCode(exitCode ?? 0));
         attachChild.once('error', () => resolveCode(1));
     });
-    process.exit(code);
-}
-/** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
- *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be
- *  deep-imported, and a ROOT import of `getAgentDir` would eager-load the entire
- *  heavy pi SDK index on crtr's front-door hot path (the reason broker-sdk.ts
- *  dynamic-imports the engine). Mirrors pi: `PI_CODING_AGENT_DIR` env, else
- *  `~/.pi/agent` (APP_NAME defaults to 'pi'). Re-sync on a pi SDK bump that moves
- *  the sessions dir — same vendoring rationale as pi-vendored.ts. */
-function piSessionsRoot() {
-    const env = process.env['PI_CODING_AGENT_DIR'];
-    const agentDir = env !== undefined && env !== '' ? env : join(homedir(), '.pi', 'agent');
-    return join(agentDir, 'sessions');
+    // The root is useless without its engine, so a socket timeout IS fatal here
+    // (unlike a background child's optional viewer, which is skipped on timeout):
+    // await readiness concurrently with the viewer's own pre-wait, mark the node
+    // crashed and reap the polling viewer if the broker never binds. Raced
+    // against the viewer exiting on its own first (e.g. the user quits during
+    // boot), which simply ends the session like any other detach.
+    const outcome = await Promise.race([
+        waitForBrokerViewSocket(meta.node_id, placed.exited).then((ok) => (ok ? 'ready' : 'never')),
+        attachExit.then(() => 'viewer-exit'),
+    ]);
+    if (outcome === 'never') {
+        try {
+            attachChild.kill();
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            transition(meta.node_id, 'crash');
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw new Error(`the front-door root broker ${meta.node_id} never bound its view socket — cannot attach.`);
+    }
+    process.exit(await attachExit);
 }
 /** Resolve a bare/partial pi session uuid to its ABSOLUTE `.jsonl` path by
  *  scanning pi's sessions store the way pi's own CLI does (exact id, else a
@@ -302,10 +305,6 @@ export async function spawnChild(opts) {
     // reaps when done. A child born as an orchestrator is terminal/orchestrator
     // (delegates + holds a roadmap, but still reports up), NOT resident.
     const lifecycle = root ? 'resident' : 'terminal';
-    // Spine: a managed child reports up to its spawner (has a manager); an
-    // independent root sits top-of-spine with nobody to push to. Mirrors the
-    // `parent` set below (root ? null : spawner), so hasManager === parent!==null.
-    const { launch } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model });
     // Born WITHOUT a name — the canvas-goal-capture extension names it async from
     // its first message (the kickoff task) inside its own pi process, so spawn
     // never blocks on the LLM naming round-trip (the 2-3s freeze it used to cost).
@@ -326,6 +325,14 @@ export async function spawnChild(opts) {
             managedWorktree = createManagedWorktree(opts.cwd, nodeId);
             spawnCwd = managedWorktree.path;
         }
+        // Spine: a managed child reports up to its spawner (has a manager); an
+        // independent root sits top-of-spine with nobody to push to. Mirrors the
+        // `parent` set below (root ? null : spawner), so hasManager === parent!==null.
+        // Built HERE — after profile + worktree cwd are resolved — so the kind's
+        // model/tools resolve against the CHILD's own profile + project stack, not
+        // this process's ambient scope (a front-door shell has no CRTR_PROFILE_ID,
+        // which silently hid every profile-scope kind override).
+        const { launch } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: spawnCwd, profileId });
         const meta = spawnNode({
             kind: opts.kind,
             mode,

package/dist/core/runtime/stream-watchdog.d.ts

@@ -0,0 +1,26 @@
+export declare function resolveStreamWatchdogMs(): number;
+/**
+ * A single-timer dead-man's switch: `poke(token)` (re)arms it, `clear()`
+ * disarms it, and `onStall(token)` fires exactly once if `poke()` isn't called
+ * again within `ms`. The broker pokes it on relayed engine events while a turn
+ * is awaiting the provider and clears it at `agent_end` / tool execution — see
+ * broker.ts `relayEvent`.
+ *
+ * The `token` is an opaque generation stamp: each arm captures the token passed
+ * to its `poke()`, and `onStall` receives exactly that token. The broker bumps
+ * a session generation on every rebind, so a timer armed against a since-
+ * superseded session hands its stale generation to `onStall`, which no-ops it
+ * instead of aborting the live replacement session.
+ */
+export declare class StreamWatchdog {
+    private readonly onStall;
+    private timer;
+    private readonly ms;
+    constructor(onStall: (token: number) => void, ms?: number);
+    /** Proof of progress — (re)arm the timer for `token`, canceling any prior
+     *  countdown. The fired `onStall` receives THIS arm's token. */
+    poke(token: number): void;
+    /** Turn over (or broker tearing down) — no more relay expected until the
+     *  next `poke()`. Idempotent. */
+    clear(): void;
+}

package/dist/core/runtime/stream-watchdog.js

@@ -0,0 +1,75 @@
+// stream-watchdog.ts — broker-side dead-provider-stream detector.
+//
+// A laptop sleep or Wi-Fi loss can leave the provider's HTTP response stream
+// half-open: the socket never errors and never closes, it just stops
+// delivering bytes. pi's turn loop has no read-timeout on that socket, so the
+// engine wedges in phase='turn' indefinitely — nothing drains (steer/followUp
+// queues included) until the daemon's 20-minute wedge detector SIGTERMs the
+// broker, which is the actual data-loss event a wedge this long causes (see
+// queued-messages-never-delivered-diagnosis.md RC1/RC2). This watchdog aborts
+// the stalled stream itself, well before that backstop: if no engine event has
+// been relayed for STREAM_WATCHDOG_MS while a turn is active, the stream is
+// presumed dead — abort it. The turn ends with stopReason 'aborted' (or the
+// stophook's own error classification if the abort races a real error), the
+// existing connection-fault retry machinery (which arms on agent_end) owns
+// re-driving the turn, and the broker process — and its in-memory queues —
+// survive instead of being killed.
+const DEFAULT_STREAM_WATCHDOG_MS = 5 * 60_000; // 5 minutes.
+// Comfortably under the daemon's 20-minute WEDGE_QUIET_MS hard kick (crtrd.ts),
+// so this is the common-case recovery path and the daemon kick becomes the rare
+// backstop. Generous enough that a live, healthy stream never trips it: a
+// single LLM turn's own network round-trips (message_update deltas,
+// tool_execution_start/update/end) land well inside 5 minutes. The watchdog
+// covers ONLY time awaiting the provider: the broker disarms it while a tool is
+// executing (a legitimately silent tool can run longer than the timeout — see
+// broker.ts relayEvent) and rearms it once the last in-flight tool ends, so a
+// slow-but-live turn is never mistaken for a dead one.
+export function resolveStreamWatchdogMs() {
+    const raw = process.env['CRTR_STREAM_WATCHDOG_MS'];
+    if (raw === undefined)
+        return DEFAULT_STREAM_WATCHDOG_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_STREAM_WATCHDOG_MS;
+}
+/**
+ * A single-timer dead-man's switch: `poke(token)` (re)arms it, `clear()`
+ * disarms it, and `onStall(token)` fires exactly once if `poke()` isn't called
+ * again within `ms`. The broker pokes it on relayed engine events while a turn
+ * is awaiting the provider and clears it at `agent_end` / tool execution — see
+ * broker.ts `relayEvent`.
+ *
+ * The `token` is an opaque generation stamp: each arm captures the token passed
+ * to its `poke()`, and `onStall` receives exactly that token. The broker bumps
+ * a session generation on every rebind, so a timer armed against a since-
+ * superseded session hands its stale generation to `onStall`, which no-ops it
+ * instead of aborting the live replacement session.
+ */
+export class StreamWatchdog {
+    onStall;
+    timer;
+    ms;
+    constructor(onStall, ms) {
+        this.onStall = onStall;
+        this.ms = ms ?? resolveStreamWatchdogMs();
+    }
+    /** Proof of progress — (re)arm the timer for `token`, canceling any prior
+     *  countdown. The fired `onStall` receives THIS arm's token. */
+    poke(token) {
+        this.clear();
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.onStall(token);
+        }, this.ms);
+        // unref() so a live watchdog never keeps the broker process open on its own.
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    /** Turn over (or broker tearing down) — no more relay expected until the
+     *  next `poke()`. Idempotent. */
+    clear() {
+        if (this.timer === undefined)
+            return;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+}

package/dist/core/runtime/tmux-chrome.d.ts

@@ -1 +1 @@
-export { installMenuBinding, installNavBindings, installViewNavBindings, sendKeysEnter, displayMessage, paneCurrentPath } from './tmux.js';
+export { installTmuxBindings, sendKeysEnter, displayMessage, paneCurrentPath, type TmuxInstalledPair, type TmuxInstallDiagnostic, type TmuxInstallResult, } from './tmux.js';

package/dist/core/runtime/tmux-chrome.js

@@ -1,4 +1,4 @@
 // tmux-chrome.ts — chrome seam (§2.1): stateless keybind/input verbs.
 // The ONLY non-placement module allowed to import the tmux driver, per the
-// §5.1 lint. Re-exports the menu/nav/send-keys verbs callers (spawn, chord) need.
-export { installMenuBinding, installNavBindings, installViewNavBindings, sendKeysEnter, displayMessage, paneCurrentPath } from './tmux.js';
+// §5.1 lint. Re-exports the server chrome callers need.
+export { installTmuxBindings, sendKeysEnter, displayMessage, paneCurrentPath, } from './tmux.js';

package/dist/core/runtime/tmux.d.ts

@@ -1,3 +1,4 @@
+import { type BindingId, type BindingResolution } from '../keybindings/index.js';
 /** POSIX single-quote escaping for one shell word. */
 export declare function shellQuote(s: string): string;
 export declare function inTmux(): boolean;
@@ -202,18 +203,20 @@ export declare function switchClient(session: string): boolean;
  *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
  *  empty, same limitation as the menu's `/promote` item. Best-effort. */
 export declare function sendKeysEnter(pane: string, text: string): boolean;
-/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
-export declare function installMenuBinding(): boolean;
-/** Bind Alt+] (forward) and Alt+[ (back) to the DFS canvas walk. Best-effort;
- *  false if either bind fails. NOTE: Alt+[ is only delivered cleanly when the
- *  terminal/tmux disambiguate it from a raw CSI introducer (`extended-keys on`).
- */
-export declare function installNavBindings(): boolean;
-/** Bind Alt+V → (], [) to the view-monitor cycle. `M-v` enters the private
- *  `crtr-view` key table (switch-client -T), then ] cycles next / [ cycles prev.
- *  Best-effort; false if any of the three binds fail. Deliberately distinct from
- *  installNavBindings' bare Alt+]/Alt+[ (node cycle): the two cycles coexist on
- *  the same server — brackets alone walk the node graph, Alt+V-then-bracket flips
- *  view monitors. The bracket keys are bound in the private table, so they NEVER
- *  shadow the user's root ]/[ and carry no CSI-introducer ambiguity. */
-export declare function installViewNavBindings(): boolean;
+export interface TmuxInstalledPair {
+    readonly table: string;
+    readonly key: string;
+}
+export interface TmuxInstallDiagnostic {
+    readonly code: 'occupied' | 'tmux-error';
+    readonly bindingId?: BindingId;
+    readonly gesture?: string;
+    readonly message: string;
+}
+export interface TmuxInstallResult {
+    readonly ok: boolean;
+    readonly installed: readonly TmuxInstalledPair[];
+    readonly diagnostics: readonly TmuxInstallDiagnostic[];
+}
+/** Reconcile the tmux server with one immutable crouter binding snapshot. */
+export declare function installTmuxBindings(bindings?: BindingResolution<BindingId>): TmuxInstallResult;