@crouton-kit/crouter 0.3.68 → 0.3.78

package/dist/core/runtime/spawn.js

@@ -24,7 +24,7 @@ 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';
@@ -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,11 +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);
+    // 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);
 }
 /** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
  *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be
@@ -302,10 +317,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 +337,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;