@north-light/crouter 0.3.154

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

@@ -0,0 +1,55 @@
+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 paused;
+    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. Inert while
+     *  paused (a deliberate known-stream wait, see `pause`), so a poke relayed
+     *  during the wait cannot rearm the disarmed watchdog. */
+    poke(token: number): void;
+    /** Turn over (or broker tearing down) — no more relay expected until the
+     *  next `poke()`. Idempotent. Does NOT touch the paused flag. */
+    clear(): void;
+    /** Enter a deliberate known-stream wait: disarm the timer AND make `poke()`
+     *  inert, so an intentional provider cooldown (which relays no engine events)
+     *  is not mistaken for a wedged network stream. Paired with `resume()`. */
+    pause(): void;
+    /** Leave a known-stream wait and rearm against `token` (the live session
+     *  generation). A no-op arm if the turn has already moved on — the broker only
+     *  resumes while still streaming and idle of tools. */
+    resume(token: number): void;
+    /** Fully disarm AND unpause — the lifecycle reset used at agent_end, session
+     *  rebind, and dispose so a superseded known-stream wait can never strand a
+     *  later session in a paused state. */
+    reset(): void;
+}
+/** Broker release policy for a deliberate wait: only an unchanged provider
+ * stream resumes; a completed/rebound turn or active tool fully resets. */
+export declare function releaseKnownStreamWait(watchdog: StreamWatchdog, token: number, sessionIsStreaming: boolean, hasExecutingTools: boolean): void;
+export declare const KNOWN_STREAM_WAIT_UI: unique symbol;
+/** The broker-supplied control: given a finite future deadline (epoch ms), pause
+ *  the dead-stream watchdog and return a release fn that resumes it. */
+export type KnownStreamWaitControl = (deadlineMs: number) => () => void;
+/** Run a deliberate, deadline-bounded provider wait as KNOWN liveness so the
+ *  broker's dead-stream watchdog does not abort the intentional silence. Looks up
+ *  the broker-owned control on the extension UI context (keyed by
+ *  `KNOWN_STREAM_WAIT_UI`) and holds the watchdog paused for the duration of
+ *  `op`, releasing in `finally`. Falls back to a plain `op()` when no broker
+ *  control is present (unit tests, non-broker hosts). */
+export declare function withKnownStreamWait(ui: unknown, deadlineMs: number, op: () => Promise<void>): Promise<void>;

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

@@ -0,0 +1,140 @@
+// 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;
+    paused = false;
+    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. Inert while
+     *  paused (a deliberate known-stream wait, see `pause`), so a poke relayed
+     *  during the wait cannot rearm the disarmed watchdog. */
+    poke(token) {
+        if (this.paused)
+            return;
+        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. Does NOT touch the paused flag. */
+    clear() {
+        if (this.timer === undefined)
+            return;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    /** Enter a deliberate known-stream wait: disarm the timer AND make `poke()`
+     *  inert, so an intentional provider cooldown (which relays no engine events)
+     *  is not mistaken for a wedged network stream. Paired with `resume()`. */
+    pause() {
+        this.clear();
+        this.paused = true;
+    }
+    /** Leave a known-stream wait and rearm against `token` (the live session
+     *  generation). A no-op arm if the turn has already moved on — the broker only
+     *  resumes while still streaming and idle of tools. */
+    resume(token) {
+        this.paused = false;
+        this.poke(token);
+    }
+    /** Fully disarm AND unpause — the lifecycle reset used at agent_end, session
+     *  rebind, and dispose so a superseded known-stream wait can never strand a
+     *  later session in a paused state. */
+    reset() {
+        this.paused = false;
+        this.clear();
+    }
+}
+/** Broker release policy for a deliberate wait: only an unchanged provider
+ * stream resumes; a completed/rebound turn or active tool fully resets. */
+export function releaseKnownStreamWait(watchdog, token, sessionIsStreaming, hasExecutingTools) {
+    if (sessionIsStreaming && !hasExecutingTools)
+        watchdog.resume(token);
+    else
+        watchdog.reset();
+}
+// A globally-stable key for the broker-owned known-stream-wait control, placed on
+// the extension UI context. Package extensions (provider-rotation) load through
+// jiti and may hold a SEPARATE module instance of this file, so a module-level
+// singleton would not be shared; `Symbol.for` + the real broker-owned UI object
+// cross that loader boundary safely (same technique as the pi theme symbol).
+export const KNOWN_STREAM_WAIT_UI = Symbol.for('@crouton-kit/crtr:known-stream-wait');
+/** Run a deliberate, deadline-bounded provider wait as KNOWN liveness so the
+ *  broker's dead-stream watchdog does not abort the intentional silence. Looks up
+ *  the broker-owned control on the extension UI context (keyed by
+ *  `KNOWN_STREAM_WAIT_UI`) and holds the watchdog paused for the duration of
+ *  `op`, releasing in `finally`. Falls back to a plain `op()` when no broker
+ *  control is present (unit tests, non-broker hosts). */
+export async function withKnownStreamWait(ui, deadlineMs, op) {
+    const control = ui?.[KNOWN_STREAM_WAIT_UI];
+    if (typeof control !== 'function') {
+        await op();
+        return;
+    }
+    const release = control(deadlineMs);
+    try {
+        await op();
+    }
+    finally {
+        try {
+            release();
+        }
+        catch {
+            /* best effort — a failed resume must not swallow the wait's own result */
+        }
+    }
+}

package/dist/core/runtime/structured-output.d.ts

@@ -0,0 +1,12 @@
+export type StructuredOutputMode = 'terminal' | 'oneoff';
+export interface StructuredOutputRequest {
+    mode: StructuredOutputMode;
+    schema: Record<string, unknown>;
+}
+export declare function outputSchemaPath(nodeId: string): string;
+export declare function outputResultPath(nodeId: string): string;
+export declare function parseOutputSchemaValue(value: string | undefined): Record<string, unknown> | null;
+export declare function writeOutputSchema(nodeId: string, mode: StructuredOutputMode, schema: Record<string, unknown>): string;
+export declare function readOutputRequest(nodeId: string): StructuredOutputRequest | null;
+export declare function removeOutputSchema(nodeId: string): void;
+export declare function hasPendingStructuredOutput(nodeId: string): boolean;

package/dist/core/runtime/structured-output.js

@@ -0,0 +1,90 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { nodeDir, contextDir } from '../canvas/paths.js';
+import { InputError } from '../io.js';
+export function outputSchemaPath(nodeId) {
+    return `${nodeDir(nodeId)}/output-schema.json`;
+}
+export function outputResultPath(nodeId) {
+    return `${contextDir(nodeId)}/result.json`;
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function parseOutputSchemaValue(value) {
+    const raw = value?.trim();
+    if (raw === undefined || raw === '')
+        return null;
+    let text;
+    let source;
+    if (raw.startsWith('{')) {
+        text = raw;
+        source = 'inline JSON';
+    }
+    else {
+        const path = resolve(raw);
+        source = path;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch (err) {
+            throw new InputError({
+                error: 'bad_output_schema',
+                message: `could not read output schema from ${path}: ${err.message}`,
+                field: 'output-schema',
+                next: 'Pass a readable JSON Schema file path, or inline JSON beginning with `{`.',
+            });
+        }
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new InputError({
+            error: 'bad_output_schema',
+            message: `output schema from ${source} is not valid JSON: ${err.message}`,
+            field: 'output-schema',
+            next: 'Pass valid JSON whose top-level value is an object.',
+        });
+    }
+    if (!isObject(parsed)) {
+        throw new InputError({
+            error: 'bad_output_schema',
+            message: `output schema from ${source} must be a JSON object`,
+            field: 'output-schema',
+            next: 'Pass a JSON Schema object, not an array, string, number, boolean, or null.',
+        });
+    }
+    return parsed;
+}
+export function writeOutputSchema(nodeId, mode, schema) {
+    const path = outputSchemaPath(nodeId);
+    mkdirSync(dirname(path), { recursive: true });
+    const request = { mode, schema };
+    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`, 'utf8');
+    return path;
+}
+export function readOutputRequest(nodeId) {
+    const path = outputSchemaPath(nodeId);
+    if (!existsSync(path))
+        return null;
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!isObject(parsed))
+        return null;
+    const mode = parsed['mode'];
+    const schema = parsed['schema'];
+    if ((mode !== 'terminal' && mode !== 'oneoff') || !isObject(schema))
+        return null;
+    return { mode, schema };
+}
+export function removeOutputSchema(nodeId) {
+    const path = outputSchemaPath(nodeId);
+    try {
+        unlinkSync(path);
+    }
+    catch { /* already gone */ }
+}
+export function hasPendingStructuredOutput(nodeId) {
+    return existsSync(outputSchemaPath(nodeId));
+}

package/dist/core/runtime/surface-bg.d.ts

@@ -0,0 +1,11 @@
+/** The SGR escape that turns ON the distinct-surface background (theme
+ *  `selectedBg`), e.g. `\x1b[48;2;58;58;74m`. Pair with `\x1b[49m` to reset just
+ *  the background. Throws if no process has initialized the theme — callers on a
+ *  render path (the attach overlay) always have, by construction. */
+export declare function surfaceBgAnsi(): string;
+/** tmux flags that frame a `display-menu` / `display-popup` on the distinct
+ *  surface background — a rounded border + the surface bg on the body and border.
+ *  Empty when the theme is unavailable in this process (chrome stays default; the
+ *  attach viewer re-installs the menu with these once it has themed). One knob:
+ *  every crtr tmux float shares this single definition. */
+export declare function surfaceTmuxStyleArgs(): string[];

package/dist/core/runtime/surface-bg.js

@@ -0,0 +1,68 @@
+// surface-bg.ts — the "distinct popup surface" background, theme-derived.
+//
+// crtr's overlays and popups must read as a SEPARATE surface from the normal one
+// (CTO ruling, taste/inline-ui-placement #11): a popup whose background matches
+// the surface has invisible edges, so you can't tell where the float begins. We
+// paint them with the active pi theme's `selectedBg` role — theme-derived, so it
+// adapts to light/dark and is ONE centralized knob, not a scattered hardcode.
+//
+// pi 0.79 does not re-export `selectedBg` through its public API (the `.` entry
+// omits `getResolvedThemeColors` and the live `theme` singleton). It DOES publish
+// the live `Theme` instance on a process-global symbol once `initTheme()` has run
+// — the same hook pi's own SDK reads (see broker.ts `ctx.ui.theme`). We read it
+// there and use the public `Theme.bg()` / `Theme.getBgAnsi()` methods.
+//
+// CRITICAL: this module must NOT statically import `@earendil-works/pi-coding-agent`
+// — that package costs ~400ms to load and would land on the cold `crtr` front
+// door (which never otherwise loads pi). We only READ the process-global symbol;
+// any process that needs styling (the attach viewer, a node's broker) has already
+// called `initTheme()` and populated it. Where the symbol is absent (the front
+// door, before it execs into the themed `crtr surface attach`), the tmux helpers return
+// no style args and the chrome stays at its default — the viewer re-themes it.
+const THEME_SYMBOL = Symbol.for('@earendil-works/pi-coding-agent:theme');
+/** The live pi Theme if a process has already run `initTheme()`, else undefined.
+ *  Read-only: never initializes (that would pull pi into the front door). */
+function liveTheme() {
+    const t = globalThis[THEME_SYMBOL];
+    return (t ?? undefined);
+}
+/** The SGR escape that turns ON the distinct-surface background (theme
+ *  `selectedBg`), e.g. `\x1b[48;2;58;58;74m`. Pair with `\x1b[49m` to reset just
+ *  the background. Throws if no process has initialized the theme — callers on a
+ *  render path (the attach overlay) always have, by construction. */
+export function surfaceBgAnsi() {
+    const t = liveTheme();
+    if (t === undefined)
+        throw new Error('surfaceBgAnsi: pi theme not initialized in this process');
+    return t.getBgAnsi('selectedBg');
+}
+/** The distinct-surface background as a tmux colour token (`#rrggbb` on a
+ *  truecolor theme, `colourN` on a 256-colour theme), or undefined when the theme
+ *  is not yet loaded in this process OR defines no selection background. tmux
+ *  cannot read pi's theme, so we translate the SGR pi resolved for us. */
+function surfaceBgTmux() {
+    const t = liveTheme();
+    if (t === undefined)
+        return undefined;
+    const ansi = t.getBgAnsi('selectedBg');
+    const tc = /48;2;(\d+);(\d+);(\d+)/.exec(ansi);
+    if (tc !== null) {
+        const hex = (n) => Number(n).toString(16).padStart(2, '0');
+        return `#${hex(tc[1])}${hex(tc[2])}${hex(tc[3])}`;
+    }
+    const c256 = /48;5;(\d+)/.exec(ansi);
+    if (c256 !== null)
+        return `colour${c256[1]}`;
+    return undefined; // empty/default selectedBg → nothing distinct to paint
+}
+/** tmux flags that frame a `display-menu` / `display-popup` on the distinct
+ *  surface background — a rounded border + the surface bg on the body and border.
+ *  Empty when the theme is unavailable in this process (chrome stays default; the
+ *  attach viewer re-installs the menu with these once it has themed). One knob:
+ *  every crtr tmux float shares this single definition. */
+export function surfaceTmuxStyleArgs() {
+    const bg = surfaceBgTmux();
+    if (bg === undefined)
+        return [];
+    return ['-b', 'rounded', '-s', `bg=${bg}`, '-S', `bg=${bg}`];
+}

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

@@ -0,0 +1 @@
+export { installTmuxBindings, legacyInboxKeyFile, sendKeysEnter, displayMessage, paneCurrentPath, getPaneOption, type TmuxInstalledPair, type TmuxInstallDiagnostic, type TmuxInstallResult, } from './tmux.js';

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

@@ -0,0 +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 server chrome callers need.
+export { installTmuxBindings, legacyInboxKeyFile, sendKeysEnter, displayMessage, paneCurrentPath, getPaneOption, } from './tmux.js';

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

@@ -0,0 +1,247 @@
+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;
+/** The pane currently displaying `nodeId`, found by the authoritative `@crtr_node`
+ *  pane tag — set by EVERY viewer (a bare `surface attach`, a focus split, a
+ *  spawned viewer) on connect. Scans all panes (`list-panes -a`); the reverse of
+ *  `nodeInPane`. Unlike the focus TABLE (which only `registerViewerFocus` writes,
+ *  so it misses attach-viewed nodes), the tag is on any pane showing the node.
+ *  Returns the pane id, or null when no pane shows it. Works headless (no $TMUX). */
+export declare function paneOfNode(nodeId: string): string | null;
+export interface TmuxLocation {
+    session: string;
+    window: string;
+    pane: string;
+}
+/** Where the caller currently is, or null if not inside tmux. */
+export declare function currentTmux(): TmuxLocation | null;
+export declare function sessionExists(name: string): boolean;
+/** Create a detached session rooted at `cwd` if it doesn't exist. The session
+ *  name is a root's tmux home; every node under that root is a window in it. */
+export declare function ensureSession(name: string, cwd: string): void;
+export interface OpenWindowOpts {
+    session: string;
+    /** Window name (the node's display name). */
+    name: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the window (already a shell string). */
+    command: string;
+}
+/** Open a background window for a node and run `command` in it. `-d` keeps it
+ *  detached so it doesn't steal focus or become the current window. Returns the
+ *  new window id AND the pane id it created (the durable `%pane_id`, LOCATION's
+ *  anchor) — callers that only need the window destructure `.window`.
+ *
+ *  Target is `${session}:` (trailing colon = the session, no window index) plus
+ *  `-a` (insert after the current window) so tmux allocates the next free index.
+ *  Passing a bare session name resolves to the session's *active window*, which
+ *  makes new-window try to create AT that occupied index and fail with
+ *  "create window failed: index N in use" whenever the active window is not the
+ *  last one (common when base-index is 0 but the live window sits at index 1).
+ *  `-a` also keeps node windows off index 0, which is reserved for the optional
+ *  dashboard. The explicit `-t ${session}:` target is the §2.2 HARD DRIVER
+ *  INVARIANT — never let new-window fall back to tmux's global current session. */
+export declare function openNodeWindow(opts: OpenWindowOpts): {
+    window: string;
+    pane: string;
+} | null;
+export interface SplitWindowOpts {
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the new pane (already a shell string). */
+    command: string;
+    /** Stack the new pane below instead of beside (default: beside, `-h`). */
+    vertical?: boolean;
+    /** Place the new pane BEFORE the target (left for `-h`, above for `-v`) via
+     *  `-b`, instead of after it (default: after — right/below). */
+    before?: boolean;
+    /** Fixed size of the new pane in the split axis' cells (columns for `-h`, rows
+     *  for `-v`) via `-l`. Omit ⇒ tmux's default even split. */
+    size?: number;
+}
+/** Split `targetPane`'s window, opening a NEW pane beside it running `command`,
+ *  and return the new pane id (the durable `%id`). The ONLY new-pane-beside verb
+ *  (Q3: a focus opened side-by-side). `-d` keeps the caller's pane active; `-h`
+ *  makes the split side-by-side (left/right), the default for a focus viewport.
+ *
+ *  §2.2 HARD DRIVER INVARIANT: `targetPane` is REQUIRED — a bare `split-window`
+ *  would split tmux's global current pane, which can leak a pane into an
+ *  unrelated user session (the exact bug this design kills). The explicit
+ *  `-t <targetPane>` makes the destination structurally un-leakable. Returns
+ *  null if tmux fails. */
+export declare function splitWindow(targetPane: string, opts: SplitWindowOpts): string | null;
+/** Bring a node's window forefront. Switches client across roots when needed. */
+export declare function focusWindow(session: string, window: string): boolean;
+/** Close a node's window (drop it from the UI). */
+export declare function closeWindow(window: string): boolean;
+/** Rename a window (`tmux rename-window -t <window> <name>`). Used by the
+ *  root relaunch to re-title the viewer window when its pane is re-pointed at
+ *  the freshly-minted node. Best-effort; false if tmux fails. */
+export declare function renameWindow(window: string, name: string): boolean;
+/** Break a single PANE out into a BRAND-NEW window of its own (`tmux break-pane
+ *  -d`). `-d` keeps the new window in the background (does not switch the client
+ *  to it); `-s <pane>` names the source pane — the §2.2 HARD DRIVER INVARIANT, so
+ *  the break never falls back to tmux's global current pane. The pane keeps its
+ *  durable `%id` across the move (only its window changes), so callers can keep
+ *  using the same pane handle. Returns the new `{window, pane}` location, or null
+ *  if tmux fails. Used by `surface tmux-spread` to lift the caller's viewer into a
+ *  fresh window before tiling sibling viewers beside it. */
+export declare function breakPane(pane: string): {
+    window: string;
+    pane: string;
+} | null;
+/** Close a single PANE. Its window closes automatically once this was the last
+ *  pane, but sibling panes survive — so co-located nodes (several agents sharing
+ *  one window via swap-pane focus) are torn down one at a time instead of all
+ *  at once by a window kill. Pane ids are the stable vehicle handle; windows
+ *  shift under swap-pane focus, so pane-granular teardown is the correct unit. */
+export declare function closePane(pane: string): boolean;
+/** Open a command in a tmux popup anchored to a pane. The command is a shell
+ * string because tmux executes popup payloads through the user's shell. */
+export declare function displayPopup(pane: string, cwd: string, command: string): boolean;
+/** The active pane id of a window. Node windows are single-pane, so this is the
+ *  node's pane. Returns null if the window is gone or tmux fails. */
+export declare function paneOfWindow(session: string, window: string): string | null;
+/** The window a pane currently lives in. Used after a swap-pane to learn which
+ *  slot the caller's pane occupied — pane ids are stable across swaps, windows
+ *  are not, so the node→window mapping must be re-derived from the pane. Returns
+ *  null if the pane is gone or tmux fails. */
+export declare function windowOfPane(pane: string): string | null;
+/** The session + window a pane currently lives in (`display-message -p -t %id`).
+ *  The §2.4 reconciliation read-back: resolve a node's/focus's CURRENT
+ *  window/session from its durable pane id before any act, so crtr follows a
+ *  manual `move-pane`/`join-pane`/`break-pane` instead of fighting it. Null if
+ *  the pane is gone or tmux fails. */
+export declare function paneLocation(pane: string): {
+    session: string;
+    window: string;
+} | null;
+/** Does this pane id still exist? A `display-message` probe on the `%id` — the
+ *  v3 PRIMARY liveness probe (§1.2/§2.2), replacing window-existence so a user
+ *  moving a pane to another window/session never reads as "gone". True iff tmux
+ *  knows the pane.
+ *
+ *  NOTE: `display-message -p -t <gone-pane>` EXITS 0 with EMPTY output (it does
+ *  not error on an unresolvable pane target) — so an `.ok` check alone would
+ *  report a dead pane as alive, defeating the whole point of pane-existence
+ *  liveness. We therefore require the echoed `#{pane_id}` to equal the requested
+ *  pane: a live pane echoes its own id, a gone/bogus one yields empty. */
+export declare function paneExists(pane: string): boolean;
+/** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
+ *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr surface attach`
+ *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
+export declare function paneRunning(pane: string): boolean;
+/** Every live pane id on the server (`list-panes -a`), as a Set for membership
+ *  probes. Returns null when tmux is unreachable (no server / transient failure)
+ *  so callers can tell "no panes" apart from "can't tell" — a GC pass must skip,
+ *  never mass-delete, on a failed probe. One subprocess call total, so batch
+ *  liveness sweeps (e.g. the daemon's stale-focus GC) don't pay a per-pane
+ *  display-message each. */
+export declare function listLivePanes(): Set<string> | null;
+/** The working directory of a pane (`display-message -p -t <pane>
+ *  '#{pane_current_path}'`). Used to preserve a view monitor's cwd across a
+ *  view-cycle respawn so project-scoped views still resolve. Null if tmux fails. */
+export declare function paneCurrentPath(pane: string): string | null;
+/** Flash a transient status-line toast on the client showing `pane` (or the
+ *  current client when `pane` is omitted). `ms` sets the display duration. Used
+ *  by `crtr canvas issue new` to confirm a capture from inside its popup.
+ *  Best-effort; never throws. */
+export declare function displayMessage(message: string, pane?: string, ms?: number): boolean;
+/** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
+ *  Used to tag a pane with the view id it currently hosts (`@crtr_view`) so the
+ *  view-nav cycle can read it back and switch to the next/prev view in place.
+ *  Best-effort; never throws. */
+export declare function setPaneOption(pane: string, name: string, value: string): boolean;
+/** Read a PANE-scoped tmux option value (`tmux show-options -p -t <pane> -q -v
+ *  <name>`): `-v` prints only the value, `-q` suppresses the unknown-option
+ *  error so an unset option yields an empty string. undefined if tmux fails. */
+export declare function getPaneOption(pane: string, name: string): string | undefined;
+export interface RespawnPaneOpts {
+    /** Target pane id (e.g. `%3`) — the pane to re-exec in place. */
+    pane: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the pane (already a shell string). */
+    command: string;
+}
+/** Re-exec a command in an EXISTING pane, in place — SYNCHRONOUS. Runs the
+ *  `respawn-pane` to completion and reports the real exit status. Used when the
+ *  caller is NOT the pane being respawned (e.g. the daemon resuming a frozen
+ *  focus pane), so it can confirm the respawn landed. Returns true on success. */
+export declare function respawnPaneSync(opts: RespawnPaneOpts): boolean;
+/** The command line a pane was originally started with (`#{pane_start_command}`)
+ *  — the exact command `respawn-pane` with no argument re-runs. undefined when
+ *  tmux is unreachable or the pane is gone. */
+export declare function paneStartCommand(pane: string): string | undefined;
+/** The pane's root process pid (`#{pane_pid}`) — the process tmux launched in
+ *  the pane (the viewer itself, or the login shell hosting it). undefined when
+ *  tmux is unreachable or the pane is gone. */
+export declare function panePid(pane: string): number | undefined;
+/** Kill a pane's current process and re-run the SAME command line it was
+ *  started with (`respawn-pane -k` with no command reuses the pane's original
+ *  command). Used to hot-reload a viewer pane in place: the fresh process
+ *  re-resolves `crtr` and picks up the currently selected runtime generation,
+ *  while the pane id, geometry, and the node's broker are untouched. */
+export declare function respawnPaneInPlace(pane: string): boolean;
+/** Turn a pi argv array into a single shell command string.
+ *
+ *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
+ *  bundled pi CLI launched with the current Node binary. CRTR_PI_BINARY is a
+ *  TEST-ONLY substitution seam: the integration-test harness points it at a
+ *  deterministic fake-pi vehicle so a real `crtr node new` reaches the fake
+ *  instead of the LLM pi, without depending on tmux/shell PATH inheritance. An
+ *  explicit `binary` arg still overrides the env. The value may be a multi-word
+ *  launcher (e.g. `node --import tsx/esm host.ts`); only argv entries are
+ *  shell-quoted, so a multi-word binary is spliced verbatim ahead of them. */
+export declare function piCommand(argv: string[], binary?: string): string;
+/** List all window ids present in `session`. Returns [] if the session does
+ *  not exist or tmux fails for any reason. Each entry is the raw window id
+ *  string reported by tmux (e.g. `@1`, `@2`, …). */
+export declare function listWindowIds(session: string): string[];
+/** True when both `session` and `window` are present (non-null/undefined) and
+ *  the window currently exists inside the session. False whenever either arg
+ *  is absent, the session is gone, or tmux does not know the window. */
+export declare function windowAlive(session: string | null | undefined, window: string | null | undefined): boolean;
+/** Activate a window within its session (same-session navigation). Equivalent
+ *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
+export declare function selectWindow(session: string, window: string): boolean;
+/** Apply a named tmux layout to a window (`tmux select-layout -t <window>
+ *  <layout>`). `surface tmux-spread` calls it with `tiled` to evenly grid every
+ *  viewer pane in the spread window (and between splits, to redistribute space so
+ *  the next split has room). Best-effort; false if tmux fails. */
+export declare function selectLayout(window: string, layout: string): boolean;
+/** Make a pane the ACTIVE pane in its window (`tmux select-pane -t <pane>`). A
+ *  `split-window -d` keeps the CALLER active, so a freshly-opened viewer pane is
+ *  not focused until this runs — `focus` calls it so picking a node (e.g. from the
+ *  alt+g graph) lands the keyboard on the new viewer. Best-effort; false if tmux
+ *  fails. */
+export declare function selectPane(pane: string): boolean;
+/** Switch the tmux client to a different session (cross-session focus). Runs
+ *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
+ *  responsible for following up with selectWindow to land on the right window. */
+export declare function switchClient(session: string): boolean;
+/** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
+ *  (`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;
+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[];
+}
+export declare function legacyInboxKeyFile(): string;
+/** Reconcile the tmux server with one immutable crouter binding snapshot. */
+export declare function installTmuxBindings(bindings?: BindingResolution<BindingId>): TmuxInstallResult;