@crouton-kit/crouter 0.3.66 → 0.3.68

package/dist/core/runtime/__tests__/node-env.test.js

@@ -0,0 +1,91 @@
+// Run with: node --import tsx/esm --test src/core/runtime/__tests__/node-env.test.ts
+//
+// Regression lock for the 0.3.62 roll regression: `nodeEnv()` (`../nodes.ts`)
+// is the ONLY place a broker child's deployment-layout path overrides
+// (CRTR_SOCK_DIR, CRTR_CANVAS_DB — siblings of CRTR_HOME in paths.ts) get from
+// ambient process.env into `inv.env`, the TRUSTED overlay `buildBrokerEnv`
+// applies on top of the default-deny spawn-env allowlist (spawn-env.ts, which
+// admits no ambient `CRTR_*`). Losing this propagation is exactly the 0.3.62
+// bug: the broker boots healthy but binds view.sock at the wrong path on a
+// Hearth guest (CRTR_SOCK_DIR=/run/crtr/socks, on tmpfs, separate from the
+// durable-volume node dir), so nothing that watches the real socket ever sees
+// it ready.
+import { test, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { nodeEnv } from '../nodes.js';
+function node(over = {}) {
+    return {
+        node_id: 'n1',
+        name: 'n1',
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        profile_id: null,
+        ...over,
+    };
+}
+const PATH_OVERRIDE_KEYS = ['CRTR_HOME', 'CRTR_SOCK_DIR', 'CRTR_CANVAS_DB', 'CRTR_SUBTREE'];
+let saved;
+before(() => {
+    saved = {};
+    for (const k of PATH_OVERRIDE_KEYS)
+        saved[k] = process.env[k];
+});
+beforeEach(() => {
+    for (const k of PATH_OVERRIDE_KEYS)
+        delete process.env[k];
+});
+afterEach(() => {
+    for (const k of PATH_OVERRIDE_KEYS)
+        delete process.env[k];
+});
+after(() => {
+    for (const k of PATH_OVERRIDE_KEYS) {
+        const v = saved[k];
+        if (v === undefined)
+            delete process.env[k];
+        else
+            process.env[k] = v;
+    }
+});
+test('CRTR_SOCK_DIR is propagated from ambient env into the broker child env', () => {
+    process.env.CRTR_SOCK_DIR = '/run/crtr/socks';
+    const env = nodeEnv(node());
+    assert.equal(env.CRTR_SOCK_DIR, '/run/crtr/socks');
+});
+test('CRTR_CANVAS_DB is propagated from ambient env into the broker child env (same latent-path class as CRTR_HOME)', () => {
+    process.env.CRTR_CANVAS_DB = '/mnt/shared/canvas.db';
+    const env = nodeEnv(node());
+    assert.equal(env.CRTR_CANVAS_DB, '/mnt/shared/canvas.db');
+});
+test('both path overrides propagate together, alongside the existing CRTR_HOME propagation', () => {
+    process.env.CRTR_HOME = '/mnt/canvas-home';
+    process.env.CRTR_SOCK_DIR = '/run/crtr/socks';
+    process.env.CRTR_CANVAS_DB = '/mnt/shared/canvas.db';
+    const env = nodeEnv(node());
+    assert.equal(env.CRTR_HOME, '/mnt/canvas-home');
+    assert.equal(env.CRTR_SOCK_DIR, '/run/crtr/socks');
+    assert.equal(env.CRTR_CANVAS_DB, '/mnt/shared/canvas.db');
+});
+test('unset ambient path overrides are omitted, never emitted as empty strings', () => {
+    // CRTR_SOCK_DIR/CRTR_CANVAS_DB/CRTR_HOME all deleted by beforeEach.
+    const env = nodeEnv(node());
+    assert.equal('CRTR_SOCK_DIR' in env, false);
+    assert.equal('CRTR_CANVAS_DB' in env, false);
+    assert.equal('CRTR_HOME' in env, false);
+});
+test('this is a narrow, named allowlist — an unrelated ambient CRTR_* var does NOT cross via nodeEnv', () => {
+    // Guards against "fix" drift toward spreading process.env wholesale: nodeEnv
+    // must keep naming each propagated key explicitly, not widen to any CRTR_*.
+    process.env.CRTR_SOME_UNRELATED_FLAG = 'leak-if-widened';
+    try {
+        const env = nodeEnv(node());
+        assert.equal('CRTR_SOME_UNRELATED_FLAG' in env, false);
+    }
+    finally {
+        delete process.env.CRTR_SOME_UNRELATED_FLAG;
+    }
+});

package/dist/core/runtime/nodes.js

@@ -76,6 +76,16 @@ export function nodeEnv(meta) {
     const home = process.env['CRTR_HOME'];
     if (home !== undefined && home !== '')
         env['CRTR_HOME'] = home;
+    // Propagate the deployment-layout path overrides (paths.ts siblings of
+    // CRTR_HOME) so the broker child binds its view.sock / opens canvas.db where
+    // every other process on this host looks. These are crtr-computed non-secret
+    // path config, same trust category as CRTR_HOME above — NOT a general
+    // CRTR_* allowlist weakening (spawn-env.ts's allowlist is untouched).
+    for (const key of ['CRTR_SOCK_DIR', 'CRTR_CANVAS_DB']) {
+        const v = process.env[key];
+        if (v !== undefined && v !== '')
+            env[key] = v;
+    }
     // Propagate the subtree-root node id. The broker uses it to group a subtree;
     // each launch site also emits the authoritative rootOfSpine(nodeId) over this
     // passthrough.

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/secrets.d.ts

@@ -0,0 +1,25 @@
+import type { Scope } from '../types.js';
+/** The 0600 secrets store: raw relay/bearer tokens for `remoteCanvas.targets`,
+ *  kept OUT of `config.json` (which is not permission-hardened and is treated
+ *  as shareable/inspectable) and never logged. `crtr canvas config add
+ *  --relay-token -` is the ONLY accepted form — reads the raw token from
+ *  stdin; any other value is rejected with a generic error (never echoing
+ *  what was received). Keyed by `RemoteCanvasTarget.relayTokenRef`, never by
+ *  the target name directly, so a rename doesn't orphan the secret. */
+export interface SecretsStore {
+    relayTokens: Record<string, string>;
+}
+export declare function readSecrets(scope: Scope): SecretsStore;
+/** Writes secrets.json directly (never via `fs-utils.writeJson`, which has no
+ *  mode control) so the file is created 0600 from the first byte, then
+ *  `chmodSync`s belt-and-suspenders in case the file pre-existed with looser
+ *  permissions (e.g. hand-copied from another machine). */
+export declare function writeSecrets(scope: Scope, store: SecretsStore): void;
+export declare function getRelayToken(ref: string, scope: Scope): string | undefined;
+export declare function setRelayToken(ref: string, token: string, scope: Scope): void;
+export declare function deleteRelayToken(ref: string, scope: Scope): void;
+/** A short, non-reversible display fingerprint of a raw token — safe to print
+ *  in `canvas config list`/`show` output. NEVER derive this from anything
+ *  that could round-trip back to the token, and never log/return the raw
+ *  token itself alongside it. */
+export declare function fingerprint(token: string): string;

package/dist/core/secrets.js

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { scopeRoot, requireScopeRoot } from './scope.js';
+import { ensureDir } from './fs-utils.js';
+const SECRETS_FILE = 'secrets.json';
+function secretsPathFor(root) {
+    return join(root, SECRETS_FILE);
+}
+export function readSecrets(scope) {
+    const root = scopeRoot(scope);
+    if (!root)
+        return { relayTokens: {} };
+    const p = secretsPathFor(root);
+    if (!existsSync(p))
+        return { relayTokens: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        return { relayTokens: parsed.relayTokens ?? {} };
+    }
+    catch {
+        return { relayTokens: {} };
+    }
+}
+/** Writes secrets.json directly (never via `fs-utils.writeJson`, which has no
+ *  mode control) so the file is created 0600 from the first byte, then
+ *  `chmodSync`s belt-and-suspenders in case the file pre-existed with looser
+ *  permissions (e.g. hand-copied from another machine). */
+export function writeSecrets(scope, store) {
+    const root = requireScopeRoot(scope);
+    ensureDir(root);
+    const p = secretsPathFor(root);
+    writeFileSync(p, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(p, 0o600);
+}
+export function getRelayToken(ref, scope) {
+    return readSecrets(scope).relayTokens[ref];
+}
+export function setRelayToken(ref, token, scope) {
+    const s = readSecrets(scope);
+    s.relayTokens[ref] = token;
+    writeSecrets(scope, s);
+}
+export function deleteRelayToken(ref, scope) {
+    const s = readSecrets(scope);
+    delete s.relayTokens[ref];
+    writeSecrets(scope, s);
+}
+/** A short, non-reversible display fingerprint of a raw token — safe to print
+ *  in `canvas config list`/`show` output. NEVER derive this from anything
+ *  that could round-trip back to the token, and never log/return the raw
+ *  token itself alongside it. */
+export function fingerprint(token) {
+    return createHash('sha256').update(token).digest('hex').slice(0, 12);
+}

package/dist/core/view/__tests__/transport-remote.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/view/__tests__/transport-remote.test.js

@@ -0,0 +1,95 @@
+// transport-remote.test.ts — `createRemoteExec` (`../transport-remote.ts`), the
+// Node-side POST transport `RemoteCanvasSource` shells every remote read
+// through. Covers the one thing a bare `fetch(...)` with no
+// AbortController/timeout doesn't give you for free: a hung endpoint fails
+// CLOSED within a bound instead of wedging the caller forever. WITHOUT the
+// timeout, the "stalled endpoint" test below would hang past its own
+// assertion deadline (the promise the transport returns never settles).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { createRemoteExec } from '../transport-remote.js';
+function startStalledServer() {
+    return new Promise((resolve) => {
+        // Accept the connection but never write a response — the request just
+        // hangs, exactly what a wedged in-guest `/__crtr/source` handler looks
+        // like from the caller's side.
+        const server = createServer(() => { });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+            resolve({
+                url: `http://127.0.0.1:${port}`,
+                close: () => new Promise((res) => server.close(() => res())),
+            });
+        });
+    });
+}
+test('a stalled endpoint returns a timeout failure within the configured bound instead of hanging forever', async () => {
+    const server = await startStalledServer();
+    const exec = createRemoteExec(server.url, 'tok', 100); // small timeout for the test
+    const started = Date.now();
+    // Race against a generous outer deadline: if the transport doesn't
+    // self-bound, this whole test times out instead of asserting cleanly —
+    // still proves the point, but assert explicitly for a clear failure message.
+    const result = await Promise.race([
+        exec('crtr', ['--json', 'node', 'inspect', 'list']),
+        new Promise((_resolve, reject) => setTimeout(() => reject(new Error('transport did not resolve within the outer deadline — no timeout is wired')), 2000)),
+    ]);
+    const elapsed = Date.now() - started;
+    assert.equal(result.ok, false);
+    assert.match(result.stderr, /timeout/i);
+    assert.ok(elapsed < 1000, `expected the timeout to fire near the configured 100ms bound, took ${elapsed}ms`);
+    await server.close();
+});
+test('a normal fast response is unaffected by the timeout wiring', async () => {
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify({ nodes: [] }), stderr: '' }));
+        });
+    });
+    await new Promise((r) => server.listen(0, '127.0.0.1', r));
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+    const exec = createRemoteExec(`http://127.0.0.1:${port}`, 'tok', 5000);
+    const result = await exec('crtr', ['--json', 'node', 'inspect', 'list']);
+    assert.equal(result.ok, true);
+    assert.equal(result.stdout, JSON.stringify({ nodes: [] }));
+    await new Promise((r) => server.close(() => r()));
+});
+// --- Phase 3 review Minor 1: no token bytes may ever reach returned stderr ---
+test('an unreachable endpoint returns a flat generic network-error message, never the raw exception text', async () => {
+    const exec = createRemoteExec('http://127.0.0.1:1', 'valid-token-123');
+    const result = await exec('crtr', ['--json', 'node', 'inspect', 'list']);
+    assert.equal(result.ok, false);
+    assert.equal(result.stderr, 'remote source: network error');
+});
+test('a malformed token (contains a newline) is rejected up front with a generic message, never reaching fetch/Headers', async () => {
+    const exec = createRemoteExec('http://127.0.0.1:1', 'bad\ntoken');
+    const result = await exec('crtr', ['--json', 'node', 'inspect', 'list']);
+    assert.equal(result.ok, false);
+    assert.equal(result.stderr, 'remote source: invalid stored relay token');
+    assert.ok(!result.stderr.includes('bad\ntoken'));
+    assert.ok(!result.stderr.includes('bad'));
+});
+test('a valid token containing typical bearer-token punctuation (-, _, .) still round-trips against a real server', async () => {
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify({ nodes: [] }), stderr: '' }));
+        });
+    });
+    await new Promise((r) => server.listen(0, '127.0.0.1', r));
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+    const exec = createRemoteExec(`http://127.0.0.1:${port}`, 'a1b2c3-real-token_ABC.789', 5000);
+    const result = await exec('crtr', ['--json', 'node', 'inspect', 'list']);
+    assert.equal(result.ok, true);
+    assert.equal(result.stdout, JSON.stringify({ nodes: [] }));
+    await new Promise((r) => server.close(() => r()));
+});