@crouton-kit/crouter 0.3.67 → 0.3.68

package/dist/core/runtime/revive.js

@@ -23,7 +23,7 @@
 //
 // reviveNode remains the ONLY sanctioned launcher of the node engine.
 import { existsSync } from 'node:fs';
-import { getNode, updateNode, clearPid, recordPid, fullName, cancelDeadlinesFor, subscribersOf, } from '../canvas/index.js';
+import { getNode, updateNode, clearPid, recordPid, fullName, cancelDeadlinesFor, subscribersOf, openDb, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { fanDoctrineWake } from './close.js';
 import { buildPiArgv } from './launch.js';
@@ -89,147 +89,184 @@ export function reviveNode(nodeId, opts) {
     // actually matters, so it's safe to call on every revive regardless of
     // entry point (daemon tick, or a direct/manual `node lifecycle revive`).
     reconcileBootLiveness();
-    // Double-revive guard: identity-aware liveness on pi_pid, requiring
-    // CONFIRMED alive — not the fail-open-to-alive boolean adapter. A node
-    // whose broker pid is CONFIRMED still running as that same broker (not a
-    // reused pid) was already revived by another path — re-launching would put
-    // a SECOND broker on the same session file. No-op. A bare isPidAlive would
-    // misread a reused pid (heavy forking, esp. Linux) as "still alive" and
-    // skip the relaunch forever; conversely, treating an INDETERMINATE read
-    // (can't confirm either way, e.g. a transient `ps` probe failure) as
-    // "alive" here would risk the opposite failure — silently skipping a
-    // needed relaunch and stranding the node with no engine. So this guard
-    // blocks ONLY on a positively confirmed-alive read; `dead` AND
-    // `indeterminate` both proceed to relaunch. We accept that tradeoff: an
-    // `indeterminate` read CAN come from a genuinely live broker whose identity
-    // `ps` probe transiently failed, so proceeding risks a rare double-launch —
-    // but stranding a truly-dead node with no engine is the worse failure, and
-    // recovering from it is far harder, so we bias toward relaunching.
-    const live = getNode(nodeId) ?? meta;
-    if (recordedPidLiveness(live.pi_pid, live.pi_pid_identity) === 'alive') {
-        return {
-            window: null,
-            session: live.tmux_session ?? null,
-            resumed: false,
-        };
-    }
-    // Every (re)launch is a new cycle — bump the counter so CRTR_CYCLES and the
-    // footer stay in sync. Mutate the in-memory meta too so buildPiArgv below
-    // launches with the incremented count.
-    meta.cycles = (meta.cycles ?? 0) + 1;
-    updateNode(nodeId, { cycles: meta.cycles });
-    // Decide whether to wake the saved pi conversation, cycle it in place (a
-    // refresh-yield reusing the same `.jsonl`), or start fresh. resumeArgs
-    // resumes/cycles ONLY by the absolute session-file path (cwd-immune) and ONLY
-    // when that .jsonl actually exists; there is no bare-id fallback (the broker
-    // preflight rejects a bare `--session`). No file on disk yet ⇒ a fresh launch.
-    const resume = resumeArgs(meta, opts.resume);
-    // hasSessionPath: there is a real `.jsonl` to hand pi via `--session`, whether
-    // as a true resume OR a cycling refresh-yield (resumeArgs sets `newCycle` in
-    // the latter case). cycling and resuming are mutually exclusive; `resuming`
-    // keeps the STRICT true-resume-only meaning `ReviveResult.resumed` and the
-    // launch-placement hint below have always carried.
-    const hasSessionPath = resume.resumeSessionPath !== undefined;
-    const cycling = hasSessionPath && resume.newCycle === true;
-    const resuming = hasSessionPath && !cycling;
-    // Mirror THIS launch attempt's cycling-ness durably, BEFORE launching, so a
-    // pre-session_start crash-retry (crtrd.ts) can tell "was the attempt I'm
-    // retrying a cycle" apart from an ordinary resume/crash. Cleared by
-    // canvas-stophook's session_start handler the instant this boot is confirmed.
-    // Written unconditionally (true for cycling, false otherwise) so it never
-    // goes stale across launch kinds.
-    updateNode(nodeId, { cycle_pending: cycling });
-    meta.cycle_pending = cycling;
-    // A truly fresh launch — no `.jsonl` to resume OR cycle from — starts a NEW
-    // pi session, so the old session identity is dead. Clear it from meta NOW,
-    // before launch, so the recorded state matches what we're about to do. This
-    // is load-bearing for boot-failure classification: if this fresh broker dies
-    // BEFORE session_start (recording no new pid and no new session), the
-    // daemon's pid-null branch keys on pi_session_id — a leftover stale id would
-    // be misread as a "stranded relaunch" and retried forever instead of surfaced
-    // via transition('crash') + surfaceBootFailure. Clearing it makes the failure
-    // show as pid=NULL + session=NULL → boot failure, the correct terminal
-    // outcome. A cycling refresh keeps BOTH ids — the `.jsonl` and its recorded
-    // session id are exactly what's being reused — so a cycling broker that dies
-    // pre-session_start reads as a "stranded relaunch" and is retried, same class
-    // as a resume revive today.
-    if (!hasSessionPath && (meta.pi_session_id != null || meta.pi_session_file != null)) {
-        updateNode(nodeId, { pi_session_id: null, pi_session_file: null });
-        meta.pi_session_id = null;
-        meta.pi_session_file = null;
-    }
-    // A true resume needs no kickoff — the saved conversation just continues. A
-    // fresh revive OR a cycling refresh-yield both get one so the (re-rooted)
-    // window re-reads its roadmap and continues: drainBearings is the one-shot
-    // consuming step (yield note + feed cursor + persona ack); the builder is
-    // then pure. `resume` carries `resumeSessionPath`/`newCycle` through
-    // unchanged (empty for true-fresh, both set for cycling) so buildPiArgv emits
-    // the right argv either way.
-    let inv;
-    if (resuming) {
-        inv = buildPiArgv(meta, resume);
-    }
-    else {
-        // Fresh or cycling: drain the one-shot bearings, then build the kickoff.
-        // When a scheduled bare self-alarm drove this revive, opts.wakeReason
-        // carries the wake provenance so the kickoff leads with a <crtr-wake> block
-        // ("a timer woke you"); every other reviveNode caller passes nothing → no
-        // block.
-        const bearings = drainBearings(meta);
-        inv = buildPiArgv(meta, {
-            ...resume,
-            prompt: buildReviveKickoff(meta, bearings, opts.wakeReason),
-        });
-        // Fresh or cycling revive starts a NEW LLM context — reset the on-read doc
-        // dedup so it surfaces docs from scratch (a true resume above instead KEEPS
-        // the persisted set, continuing the same transcript).
-        clearInjectedDocs(nodeId);
-    }
-    // The broker host launches the detached engine. reviveNode keeps
-    // transition+clearPid around it (the crash-safety ordering, unchanged). It
-    // opens NO viewer — engine-only; existing viewers reconnect, and a viewer-less
-    // node is brought on screen by the next `focus`.
-    transition(nodeId, 'revive');
-    // Clear any active fault the instant this node is (re)launched — don't wait
-    // for the fresh agent_start. A revive (auto or on-demand) is the recovery
-    // this marker advertised.
-    clearFault(nodeId);
-    // Cancel-on-wake (design §6.4, AC-E1): every revive-for-any-reason (an inbox
-    // event, a different wake, a manual focus) drops this node's pending deadline,
-    // so the deadline always belongs to the dormancy being left. Writes only the
-    // wakeups table, after the atomic transition above.
-    cancelDeadlinesFor(nodeId);
-    let launched;
+    // Cross-invocation revive lock (the duplicate-broker leak this fixes — live
+    // incident: repeated revive attempts against one node under socket thrash
+    // left MULTIPLE live `broker-cli` processes for the same node id, with
+    // canvas `pi_pid` overwritten and the older brokers untracked/leaked). The
+    // guard below reads `pi_pid` liveness and then, several statements later,
+    // launches + records a NEW pid — a classic check-then-act race. Two
+    // `reviveNode` calls for the SAME node (typically two separate OS processes:
+    // a retried `crtr node lifecycle revive`/web-relay bridge call racing the
+    // daemon's own auto-revive tick, or a burst of reconnect retries) can both
+    // read the SAME stale not-alive pid before either one's `recordPid` commits,
+    // both launch a broker, and the second `recordPid` silently overwrites the
+    // first's pid — leaking the first broker as an untracked live process
+    // forever. A `BEGIN IMMEDIATE` write transaction around the guard-check
+    // through `recordPid` serializes every `reviveNode` call sharing this
+    // canvas.db (same process or a concurrent one — SQLite's write lock plus the
+    // WAL/`busy_timeout` already set on every connection, see db.ts): whichever
+    // call wins the lock finishes its guard check, launch, and `recordPid`
+    // BEFORE the next contender's guard check ever runs, so a second contender
+    // always sees the freshly-recorded ALIVE pid and no-ops instead of
+    // double-launching. Committed UNCONDITIONALLY in `finally` — never rolled
+    // back — because every write inside (the cycle bump, the crash-path
+    // `transition('crash')`/`clearPid` on a launch failure, etc.) must persist
+    // exactly as it would with no transaction at all (each statement
+    // auto-committing today); this adds only the missing mutual exclusion, it
+    // changes no write's durability or the function's existing throw/return
+    // semantics.
+    const db = openDb();
+    db.exec('BEGIN IMMEDIATE');
     try {
-        launched = headlessBrokerHost.launch(nodeId, inv, {
-            cwd: meta.cwd,
-            name: fullName(meta),
-            resuming,
-        });
-    }
-    catch (error) {
+        // Double-revive guard: identity-aware liveness on pi_pid, requiring
+        // CONFIRMED alive — not the fail-open-to-alive boolean adapter. A node
+        // whose broker pid is CONFIRMED still running as that same broker (not a
+        // reused pid) was already revived by another path — re-launching would put
+        // a SECOND broker on the same session file. No-op. A bare isPidAlive would
+        // misread a reused pid (heavy forking, esp. Linux) as "still alive" and
+        // skip the relaunch forever; conversely, treating an INDETERMINATE read
+        // (can't confirm either way, e.g. a transient `ps` probe failure) as
+        // "alive" here would risk the opposite failure — silently skipping a
+        // needed relaunch and stranding the node with no engine. So this guard
+        // blocks ONLY on a positively confirmed-alive read; `dead` AND
+        // `indeterminate` both proceed to relaunch. We accept that tradeoff: an
+        // `indeterminate` read CAN come from a genuinely live broker whose identity
+        // `ps` probe transiently failed, so proceeding risks a rare double-launch —
+        // but stranding a truly-dead node with no engine is the worse failure, and
+        // recovering from it is far harder, so we bias toward relaunching.
+        const live = getNode(nodeId) ?? meta;
+        if (recordedPidLiveness(live.pi_pid, live.pi_pid_identity) === 'alive') {
+            return {
+                window: null,
+                session: live.tmux_session ?? null,
+                resumed: false,
+            };
+        }
+        // Every (re)launch is a new cycle — bump the counter so CRTR_CYCLES and the
+        // footer stay in sync. Mutate the in-memory meta too so buildPiArgv below
+        // launches with the incremented count.
+        meta.cycles = (meta.cycles ?? 0) + 1;
+        updateNode(nodeId, { cycles: meta.cycles });
+        // Decide whether to wake the saved pi conversation, cycle it in place (a
+        // refresh-yield reusing the same `.jsonl`), or start fresh. resumeArgs
+        // resumes/cycles ONLY by the absolute session-file path (cwd-immune) and ONLY
+        // when that .jsonl actually exists; there is no bare-id fallback (the broker
+        // preflight rejects a bare `--session`). No file on disk yet ⇒ a fresh launch.
+        const resume = resumeArgs(meta, opts.resume);
+        // hasSessionPath: there is a real `.jsonl` to hand pi via `--session`, whether
+        // as a true resume OR a cycling refresh-yield (resumeArgs sets `newCycle` in
+        // the latter case). cycling and resuming are mutually exclusive; `resuming`
+        // keeps the STRICT true-resume-only meaning `ReviveResult.resumed` and the
+        // launch-placement hint below have always carried.
+        const hasSessionPath = resume.resumeSessionPath !== undefined;
+        const cycling = hasSessionPath && resume.newCycle === true;
+        const resuming = hasSessionPath && !cycling;
+        // Mirror THIS launch attempt's cycling-ness durably, BEFORE launching, so a
+        // pre-session_start crash-retry (crtrd.ts) can tell "was the attempt I'm
+        // retrying a cycle" apart from an ordinary resume/crash. Cleared by
+        // canvas-stophook's session_start handler the instant this boot is confirmed.
+        // Written unconditionally (true for cycling, false otherwise) so it never
+        // goes stale across launch kinds.
+        updateNode(nodeId, { cycle_pending: cycling });
+        meta.cycle_pending = cycling;
+        // A truly fresh launch — no `.jsonl` to resume OR cycle from — starts a NEW
+        // pi session, so the old session identity is dead. Clear it from meta NOW,
+        // before launch, so the recorded state matches what we're about to do. This
+        // is load-bearing for boot-failure classification: if this fresh broker dies
+        // BEFORE session_start (recording no new pid and no new session), the
+        // daemon's pid-null branch keys on pi_session_id — a leftover stale id would
+        // be misread as a "stranded relaunch" and retried forever instead of surfaced
+        // via transition('crash') + surfaceBootFailure. Clearing it makes the failure
+        // show as pid=NULL + session=NULL → boot failure, the correct terminal
+        // outcome. A cycling refresh keeps BOTH ids — the `.jsonl` and its recorded
+        // session id are exactly what's being reused — so a cycling broker that dies
+        // pre-session_start reads as a "stranded relaunch" and is retried, same class
+        // as a resume revive today.
+        if (!hasSessionPath && (meta.pi_session_id != null || meta.pi_session_file != null)) {
+            updateNode(nodeId, { pi_session_id: null, pi_session_file: null });
+            meta.pi_session_id = null;
+            meta.pi_session_file = null;
+        }
+        // A true resume needs no kickoff — the saved conversation just continues. A
+        // fresh revive OR a cycling refresh-yield both get one so the (re-rooted)
+        // window re-reads its roadmap and continues: drainBearings is the one-shot
+        // consuming step (yield note + feed cursor + persona ack); the builder is
+        // then pure. `resume` carries `resumeSessionPath`/`newCycle` through
+        // unchanged (empty for true-fresh, both set for cycling) so buildPiArgv emits
+        // the right argv either way.
+        let inv;
+        if (resuming) {
+            inv = buildPiArgv(meta, resume);
+        }
+        else {
+            // Fresh or cycling: drain the one-shot bearings, then build the kickoff.
+            // When a scheduled bare self-alarm drove this revive, opts.wakeReason
+            // carries the wake provenance so the kickoff leads with a <crtr-wake> block
+            // ("a timer woke you"); every other reviveNode caller passes nothing → no
+            // block.
+            const bearings = drainBearings(meta);
+            inv = buildPiArgv(meta, {
+                ...resume,
+                prompt: buildReviveKickoff(meta, bearings, opts.wakeReason),
+            });
+            // Fresh or cycling revive starts a NEW LLM context — reset the on-read doc
+            // dedup so it surfaces docs from scratch (a true resume above instead KEEPS
+            // the persisted set, continuing the same transcript).
+            clearInjectedDocs(nodeId);
+        }
+        // The broker host launches the detached engine. reviveNode keeps
+        // transition+clearPid around it (the crash-safety ordering, unchanged). It
+        // opens NO viewer — engine-only; existing viewers reconnect, and a viewer-less
+        // node is brought on screen by the next `focus`.
+        transition(nodeId, 'revive');
+        // Clear any active fault the instant this node is (re)launched — don't wait
+        // for the fresh agent_start. A revive (auto or on-demand) is the recovery
+        // this marker advertised.
+        clearFault(nodeId);
+        // Cancel-on-wake (design §6.4, AC-E1): every revive-for-any-reason (an inbox
+        // event, a different wake, a manual focus) drops this node's pending deadline,
+        // so the deadline always belongs to the dormancy being left. Writes only the
+        // wakeups table, after the atomic transition above.
+        cancelDeadlinesFor(nodeId);
+        let launched;
         try {
-            transition(nodeId, 'crash');
-            // Doctrine wake: a launch-refusal here marks the node dead with NOTHING
-            // else fanning that out — the daemon's own auto-revive is the most common
-            // caller (superviseTick, best-effort try/catch, stderr-only on failure), so
-            // without this a manager waiting dormant on this child hangs forever,
-            // never told it will not come back on its own. Mirrors closeNode's step-4
-            // fan-out (same subscribers table, same active/passive split).
-            fanDoctrineWake(nodeId, subscribersOf(nodeId), `Child crashed — ${fullName(meta)} (${nodeId}) failed to relaunch and is now dead: ${error.message}\n\n` +
-                `It stays dead until you revive it — \`crtr node lifecycle revive ${nodeId}\`.`, { reason: 'child-crashed', child: nodeId });
+            launched = headlessBrokerHost.launch(nodeId, inv, {
+                cwd: meta.cwd,
+                name: fullName(meta),
+                resuming,
+            });
         }
-        catch {
-            /* best-effort cleanup */
+        catch (error) {
+            try {
+                transition(nodeId, 'crash');
+                // Doctrine wake: a launch-refusal here marks the node dead with NOTHING
+                // else fanning that out — the daemon's own auto-revive is the most common
+                // caller (superviseTick, best-effort try/catch, stderr-only on failure), so
+                // without this a manager waiting dormant on this child hangs forever,
+                // never told it will not come back on its own. Mirrors closeNode's step-4
+                // fan-out (same subscribers table, same active/passive split).
+                fanDoctrineWake(nodeId, subscribersOf(nodeId), `Child crashed — ${fullName(meta)} (${nodeId}) failed to relaunch and is now dead: ${error.message}\n\n` +
+                    `It stays dead until you revive it — \`crtr node lifecycle revive ${nodeId}\`.`, { reason: 'child-crashed', child: nodeId });
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+            clearPid(nodeId);
+            throw new Error(`[broker] refusing to revive ${nodeId}: ${error.message}`);
         }
-        clearPid(nodeId);
-        throw new Error(`[broker] refusing to revive ${nodeId}: ${error.message}`);
+        // Record the real broker pid immediately, still inside the lock — this is
+        // the write that makes the guard's next reader (a contender unblocked from
+        // its own BEGIN IMMEDIATE the instant this transaction commits) see an
+        // ALIVE pid instead of racing past the same stale one this call just
+        // relaunched from. session_start will re-record the same pid after
+        // extension bind, but the daemon must supervise the process during the
+        // cold-boot window too; otherwise a slow-but-alive broker reads as
+        // pid=null+session=null and can be falsely crashed by the boot-grace path.
+        if (launched.pid !== null)
+            recordPid(nodeId, launched.pid);
+        return { window: null, session: meta.tmux_session ?? null, resumed: resuming, launch: launched };
+    }
+    finally {
+        db.exec('COMMIT');
     }
-    // Record the real broker pid immediately. session_start will re-record the
-    // same pid after extension bind, but the daemon must supervise the process
-    // during the cold-boot window too; otherwise a slow-but-alive broker reads as
-    // pid=null+session=null and can be falsely crashed by the boot-grace path.
-    if (launched.pid !== null)
-        recordPid(nodeId, launched.pid);
-    return { window: null, session: meta.tmux_session ?? null, resumed: resuming, launch: launched };
 }

package/dist/core/runtime/tmux.js

@@ -67,7 +67,10 @@ function ensureBracketedPaste() {
     const current = tmux(['show-options', '-s', 'terminal-overrides']).stdout;
     if (current.includes('Enbp='))
         return;
-    tmux(['set-option', '-sga', 'terminal-overrides', '*:Enbp=\E[?2004h:Dsbp=\E[?2004l']);
+    // Emit a LITERAL backslash-E (`\\E`) so tmux's option parser resolves it to ESC.
+    // A single `\E` in this JS source collapses to the letter `E`, which stores a
+    // broken `Enbp=E[?2004h` (no ESC) and silently disables bracketed paste.
+    tmux(['set-option', '-sga', 'terminal-overrides', '*:Enbp=\\E[?2004h:Dsbp=\\E[?2004l']);
 }
 /** 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. */

package/dist/core/view/transport-local.js

@@ -38,9 +38,18 @@ function sendExec(req, baseCwd) {
                 resolve({ ok: true, exitCode: code, stdout: stdout ?? '', stderr: stderr ?? '' });
                 return;
             }
-            if (err.signal) {
-                // Killed by signal: it ran; surface as a non-zero exit.
-                resolve({ ok: true, exitCode: 1, stdout: stdout ?? '', stderr: stderr ?? '' });
+            const signal = err.signal;
+            if (signal) {
+                // Killed by signal: it ran; surface as a non-zero exit. A SIGKILL with
+                // no stderr at all (the live-incident shape: a guest OOM killer takes
+                // out the child before it ever writes anything) used to come back as
+                // a bare `failed (1)` with nothing to explain it — the signal itself
+                // IS the useful diagnostic here, so surface it when stderr is empty
+                // rather than discarding it.
+                const detail = stderr && stderr.trim() !== ''
+                    ? stderr
+                    : `killed by signal ${signal}${signal === 'SIGKILL' ? ' (often out-of-memory)' : ''}`;
+                resolve({ ok: true, exitCode: 1, stdout: stdout ?? '', stderr: detail });
                 return;
             }
             // Spawn-level failure (ENOENT/EACCES/maxBuffer): transport failure.