@crouton-kit/crouter 0.3.67 → 0.3.70

package/dist/core/__tests__/helpers/harness.js

@@ -45,12 +45,28 @@ const TSX_ESM = createRequire(import.meta.url).resolve('tsx/esm');
 // A multi-word launcher, baked verbatim ahead of the (shell-quoted) argv by the
 // seam. Absolute paths so it works regardless of the spawned window's cwd.
 const FAKE_PI_BINARY = `${process.execPath} --import ${TSX_ESM} ${FAKE_PI_HOST}`;
+// Every raw `tmux` call the harness/full-tier tests make against the shared
+// DEFAULT server is synchronous (spawnSync). Node's spawnSync blocks the WHOLE
+// worker (no event loop, no `node --test` timeout can preempt it) until the
+// child exits — with no `timeout` option it can wait FOREVER. A wedged/CPU-
+// starved tmux server (the acknowledged "intermittent Linux-only crash-revive
+// wedge", CI-only) has been observed to hang one of these calls indefinitely,
+// which permanently consumes one of the `--test-concurrency` slots; as more
+// full-tier files each hit the SAME wedged server, every slot eventually gets
+// consumed the same way and the whole suite flatlines with zero further TAP
+// output (confirmed 3/3 in CI, see ci-full-suite-hang-blocker.md). TMUX_TIMEOUT_MS
+// bounds every raw tmux spawnSync call so a wedge fails that ONE call (and the
+// test it belongs to) fast instead of hanging the run.
+export const TMUX_TIMEOUT_MS = 10_000;
 /** True when a usable tmux is on PATH — tests gate on this and SKIP otherwise. */
 export function hasTmux() {
-    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0;
+    return spawnSync('tmux', ['-V'], { stdio: 'ignore', timeout: TMUX_TIMEOUT_MS }).status === 0;
 }
 function tmuxSessionExists(session) {
-    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+    return (spawnSync('tmux', ['has-session', '-t', session], {
+        stdio: 'ignore',
+        timeout: TMUX_TIMEOUT_MS,
+    }).status === 0);
 }
 // Every canvas/tmux var the harness itself runs under — scrubbed from each child
 // env so a spawned CLI cannot leak the REAL canvas into the isolated test.
@@ -172,14 +188,19 @@ export async function createHarness(opts = {}) {
     if (!headless) {
         spawnSync('tmux', ['new-session', '-d', '-s', session, '-c', CROUTER, 'sleep 100000'], {
             stdio: 'ignore',
+            timeout: TMUX_TIMEOUT_MS,
         });
         // Put CRTR_PI_BINARY in the SESSION environment so EVERY pane/process spawned
         // in this session inherits it — so any pi the runtime launches (boot, revive)
         // resolves to the fake-pi vehicle, not a real pi.
         spawnSync('tmux', ['set-environment', '-t', session, 'CRTR_PI_BINARY', FAKE_PI_BINARY], {
             stdio: 'ignore',
+            timeout: TMUX_TIMEOUT_MS,
+        });
+        spawnSync('tmux', ['set-environment', '-t', session, 'CRTR_HOME', home], {
+            stdio: 'ignore',
+            timeout: TMUX_TIMEOUT_MS,
         });
-        spawnSync('tmux', ['set-environment', '-t', session, 'CRTR_HOME', home], { stdio: 'ignore' });
     }
     const pidsToKill = new Set();
     let nextRootSeq = 0;
@@ -517,7 +538,10 @@ export async function createHarness(opts = {}) {
             return subscriptionsOf(nodeId).map((s) => ({ node_id: s.node_id, active: s.active }));
         },
         async dispose() {
-            spawnSync('tmux', ['kill-session', '-t', session], { stdio: 'ignore' });
+            spawnSync('tmux', ['kill-session', '-t', session], {
+                stdio: 'ignore',
+                timeout: TMUX_TIMEOUT_MS,
+            });
             // Best-effort: a superviseTick-triggered revive of a fabricated node fires
             // a DETACHED throwaway broker (it loads the real SDK; the rmSync of home
             // below makes a mid-boot one self-terminate when its files vanish). Kill

package/dist/core/__tests__/live-mutation-verbs.test.js

@@ -47,6 +47,7 @@ import { commitPersonaAck, personaDrift } from '../runtime/persona.js';
 function persona(m) {
     return { mode: m.mode, lifecycle: m.lifecycle };
 }
+const FULL_CLI_TEST_TIMEOUT_MS = 180_000;
 // ===========================================================================
 // (b) THE demote / recycle SPLIT — two DISTINCT verbs:
 //   • `node lifecycle demote`  flips a LIVE node's lifecycle→TERMINAL IN PLACE — it keeps
@@ -60,9 +61,9 @@ function persona(m) {
 // ===========================================================================
 test('node lifecycle demote flips lifecycle→terminal IN PLACE; node lifecycle recycle is FINISH+RECYCLE', 
 // Drives several full-CLI subprocess spawns (each a cold tsx compile of the
-// whole CLI) + recycleNode; a 20s budget blew on the slower, concurrency-
-// oversubscribed CI runner though it passes in ~8s locally. 60s = safe margin.
-{ timeout: 60_000 }, async () => {
+// whole CLI) + recycleNode; this is a subprocess-heavy regression and gets a
+// CI-safe per-test budget while the npm script isolates it at file concurrency 1.
+{ timeout: FULL_CLI_TEST_TIMEOUT_MS }, async () => {
     const h = await createHeadlessHarness({ sessionPrefix: 'crtr-live-demote' });
     try {
         const A = h.spawnRoot('resident root');
@@ -136,7 +137,7 @@ test('node lifecycle demote flips lifecycle→terminal IN PLACE; node lifecycle
 // ===========================================================================
 test('A4: a base→orchestrator yield auto-promotes + sets refresh but leaves persona_ack PENDING (the steer is never delivered)', 
 // Full-CLI subprocess spawn under load — see the sibling test's budget note.
-{ timeout: 60_000 }, async () => {
+{ timeout: FULL_CLI_TEST_TIMEOUT_MS }, async () => {
     const h = await createHeadlessHarness({ sessionPrefix: 'crtr-live-a4' });
     try {
         const A = h.spawnRoot('resident root');

package/dist/core/__tests__/review-model-floor.test.js

@@ -27,7 +27,7 @@ test('review still permits equal-or-stronger explicit models', () => {
     assert.equal(spec('review', 'ultra'), normalizeModel('ultra'));
 });
 test('explore remains cheap by default and may explicitly run light', () => {
-    assert.equal(spec('explore'), normalizeModel('anthropic/light'));
+    assert.equal(spec('explore'), normalizeModel('openai/light'));
     assert.equal(spec('explore', 'light'), normalizeModel('light'));
 });
 // `node new --model` widened to the full spec grammar (provider/tier, exact

package/dist/core/__tests__/revive.test.js

@@ -34,9 +34,11 @@ import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
+import { DatabaseSync } from 'node:sqlite';
 import { createNode, subscribe } from '../canvas/canvas.js';
 import { readInboxSince } from '../feed/inbox.js';
-import { closeDb } from '../canvas/db.js';
+import { closeDb, openDb } from '../canvas/db.js';
+import { canvasDbPath } from '../canvas/paths.js';
 import { buildPiArgv } from '../runtime/launch.js';
 import { headlessBrokerHost } from '../runtime/host.js';
 import { resumeArgs, reviveNode } from '../runtime/revive.js';
@@ -350,3 +352,70 @@ test('reviveNode fans a doctrine wake to subscribers when launch/preflight throw
         await h.dispose();
     }
 });
+// ---------------------------------------------------------------------------
+// Duplicate-broker leak (live-incident regression): reviveNode's guard-check-
+// then-launch-then-recordPid critical section must be a single atomic write
+// transaction, so a concurrent reviveNode call for the SAME node (a second OS
+// process racing this one against the same canvas.db, e.g. a retried web-relay
+// revive under socket thrash) cannot read the same stale pid, launch its own
+// broker, and overwrite this call's freshly-recorded pid — leaking this call's
+// broker as an untracked live process. Proven here by holding a competing raw
+// write transaction open on a SECOND connection to the same db file before
+// calling reviveNode: with the fix, reviveNode's own BEGIN IMMEDIATE cannot
+// acquire the write lock while the other connection holds it, so it fails
+// closed (throws) rather than silently interleaving with the held lock and
+// corrupting the guard's read-then-write. Releasing the competing lock lets an
+// identical reviveNode call proceed and record a fresh pid normally — the
+// serialization is transient contention, not a permanent wedge.
+// ---------------------------------------------------------------------------
+test('reviveNode\'s guard-check-through-recordPid section is one atomic write transaction (duplicate-broker-leak regression)', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-lock' });
+    let contender;
+    try {
+        const sessionFile = join(home, 'sessions', 'crtr-revive-lock.jsonl');
+        mkdirSync(join(home, 'sessions'), { recursive: true });
+        writeFileSync(sessionFile, '{}\n', 'utf8');
+        const stalePid = deadPid();
+        const M = h.fabricateBrokerNode({
+            status: 'active',
+            intent: null,
+            pi_pid: stalePid,
+            pi_session_id: 'uuid-lock',
+            pi_session_file: sessionFile,
+        });
+        // Shorten THIS test's connection's busy_timeout (default 5000ms, db.ts) so
+        // the contended call below fails fast instead of waiting out the real
+        // production window — it's the ACQUIRING side's timeout that governs how
+        // long `BEGIN IMMEDIATE` waits, not the holder's.
+        openDb().exec('PRAGMA busy_timeout = 200;');
+        // A second raw connection to the SAME db file holds an exclusive write
+        // transaction open — modeling a concurrent reviveNode call (a different OS
+        // process, in the real incident) that already won the race and is mid-launch.
+        contender = new DatabaseSync(canvasDbPath());
+        contender.exec('BEGIN IMMEDIATE');
+        assert.throws(() => reviveNode(M, { resume: true }), /locked|busy/i, 'a reviveNode call cannot acquire the write lock while a concurrent revive holds it — no interleaved double-launch');
+        assert.equal(h.node(M).pi_pid, stalePid, 'blocked-out call recorded nothing — the held pid is untouched');
+        // Release the contender's lock — an identical reviveNode call now proceeds
+        // normally, exactly like the uncontended case.
+        contender.exec('COMMIT');
+        contender.close();
+        contender = undefined;
+        reviveNode(M, { resume: true });
+        const after = h.node(M);
+        assert.notEqual(after.pi_pid, stalePid, 'once uncontended, revive proceeds and records a fresh pid');
+        assert.equal(after.cycles, 1, 'the uncontended revive bumped the cycle counter');
+    }
+    finally {
+        if (contender !== undefined) {
+            try {
+                contender.exec('ROLLBACK');
+            }
+            catch { /* best-effort */ }
+            try {
+                contender.close();
+            }
+            catch { /* best-effort */ }
+        }
+        await h.dispose();
+    }
+});

package/dist/core/canvas/__tests__/remote-event-stream.test.js

@@ -45,7 +45,7 @@ async function waitFor(predicate, timeoutMs = 2000, intervalMs = 5) {
         await new Promise((r) => setTimeout(r, intervalMs));
     }
 }
-test('a listener fires once per known-kind SSE event, and never for a ping or an unknown kind', async () => {
+test('a listener fires once per known-kind SSE event, and never for a ping or an unknown kind', async (t) => {
     const server = await startSseServer((res) => {
         res.writeHead(200, { 'content-type': 'text/event-stream' });
         res.write(': connected\n\n');
@@ -55,15 +55,18 @@ test('a listener fires once per known-kind SSE event, and never for a ping or an
         res.end();
     });
     const stream = new RemoteEventStream(server.url, 'tok');
+    // Register cleanup BEFORE any assertion runs — a thrown assertion must not
+    // leave the client's reconnect loop or the server's listening socket alive
+    // (see the CI-hang postmortem on rebuild-coalescer.test.ts).
+    t.after(() => { stream.stop(); return server.close(); });
     const seen = [];
     stream.subscribe((kind) => seen.push(kind));
     stream.start();
     await waitFor(() => seen.length > 0);
     stream.stop();
     assert.deepEqual(seen, ['nodes']);
-    await server.close();
 });
-test('the SSE connection carries the token ONLY in the Authorization header — not in the URL or any other header', async () => {
+test('the SSE connection carries the token ONLY in the Authorization header — not in the URL or any other header', async (t) => {
     const server = await startSseServer((res) => {
         res.writeHead(200, { 'content-type': 'text/event-stream' });
         res.end();
@@ -73,6 +76,7 @@ test('the SSE connection carries the token ONLY in the Authorization header —
     // no header, including Host, is permitted to carry it.
     const token = 'secret-sse-token-value';
     const stream = new RemoteEventStream(server.url, token);
+    t.after(() => { stream.stop(); return server.close(); });
     stream.start();
     await waitFor(() => server.requests.length > 0);
     stream.stop();
@@ -87,9 +91,8 @@ test('the SSE connection carries the token ONLY in the Authorization header —
         assert.ok(!String(v).includes(token), `header ${k} must not carry the token`);
     }
     assert.ok(!req.url.includes(token));
-    await server.close();
 });
-test('stop() cancels a pending reconnect timer — no zombie loop survives a stop()+start() cycle', async () => {
+test('stop() cancels a pending reconnect timer — no zombie loop survives a stop()+start() cycle', async (t) => {
     const server = await startSseServer((res) => {
         res.writeHead(500);
         res.end();
@@ -101,6 +104,7 @@ test('stop() cancels a pending reconnect timer — no zombie loop survives a sto
     // wide enough that ordinary event-loop/scheduler jitter can't flip it.
     const BACKOFF = 200;
     const stream = new RemoteEventStream(server.url, 'tok', { initialBackoffMs: BACKOFF });
+    t.after(() => { stream.stop(); return server.close(); });
     stream.start();
     // t≈0: first request fires+fails, backoff(BACKOFF) scheduled → stale deadline ≈ BACKOFF.
     await waitFor(() => server.hitCount() >= 1);
@@ -119,10 +123,8 @@ test('stop() cancels a pending reconnect timer — no zombie loop survives a sto
     // this window; a cleared one (fixed) leaves it at 2.
     await new Promise((r) => setTimeout(r, BACKOFF * 0.7));
     assert.equal(server.hitCount(), 2, "no zombie request from the stopped loop's dangling timer");
-    stream.stop();
-    await server.close();
 });
-test('stop() halts the reconnect loop — no further requests after it is called', async () => {
+test('stop() halts the reconnect loop — no further requests after it is called', async (t) => {
     const server = await startSseServer((res) => {
         // Every connection is refused immediately (no SSE headers, just a close)
         // so the client's loop falls into its backoff-and-retry path.
@@ -131,6 +133,7 @@ test('stop() halts the reconnect loop — no further requests after it is called
     });
     const BACKOFF = 20;
     const stream = new RemoteEventStream(server.url, 'tok', { initialBackoffMs: BACKOFF });
+    t.after(() => { stream.stop(); return server.close(); });
     stream.start();
     await waitFor(() => server.hitCount() >= 1);
     const hitsAtStop = server.hitCount();
@@ -140,5 +143,4 @@ test('stop() halts the reconnect loop — no further requests after it is called
     // continuing to retry in the background after stop() returned.
     await new Promise((r) => setTimeout(r, BACKOFF * 5));
     assert.equal(server.hitCount(), hitsAtStop);
-    await server.close();
 });

package/dist/core/canvas/__tests__/render-remote.test.js

@@ -140,7 +140,7 @@ function seedPoisonedLocalState() {
     ].join('\n'));
     return sf;
 }
-test('dashboardRowsAllFromSource / enrichRowsFromSource / loadPreviewFromSource suppress every local-read field to its safe default for a RemoteCanvasSource, even with conflicting local state for the same node id', async () => {
+test('dashboardRowsAllFromSource / enrichRowsFromSource / loadPreviewFromSource suppress every local-read field to its safe default for a RemoteCanvasSource, even with conflicting local state for the same node id', async (t) => {
     sessionFile = seedPoisonedLocalState();
     const server = await startMockCrtrServer((args) => {
         if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'list') {
@@ -164,6 +164,10 @@ test('dashboardRowsAllFromSource / enrichRowsFromSource / loadPreviewFromSource
         }
         return { status: 500, body: {} };
     });
+    // Register the close BEFORE any assertion runs — a listening server left
+    // open by a thrown assertion keeps this test file's process alive forever
+    // (see the CI-hang postmortem on rebuild-coalescer.test.ts).
+    t.after(() => server.close());
     const source = new RemoteCanvasSource(server.url, 'tok');
     const rows = await dashboardRowsAllFromSource(source);
     assert.equal(rows.length, 1);
@@ -180,7 +184,6 @@ test('dashboardRowsAllFromSource / enrichRowsFromSource / loadPreviewFromSource
     assert.equal(previewed.prompts, undefined, 'a local session transcript must not leak into a remote preview');
     assert.equal(previewed.lastAssistant, undefined, 'a local session transcript must not leak into a remote preview');
     assert.equal(previewed.previewLoaded, true);
-    await server.close();
 });
 // The non-TTY `canvas browse` path (browse/app.ts's `if (!process.stdin.isTTY)`
 // branch) calls `renderForestFromSource(source)` directly — a SEPARATE code
@@ -190,7 +193,7 @@ test('dashboardRowsAllFromSource / enrichRowsFromSource / loadPreviewFromSource
 // test above never exercises it, so a regression that reintroduced local
 // telemetry/ask/fault reads into the static forest renderer specifically would
 // pass that test while still leaking poisoned local state here.
-test('renderForestFromSource suppresses local-read fields (ctx, asks, hanging) for a RemoteCanvasSource, even with conflicting local state for the same node id', async () => {
+test('renderForestFromSource suppresses local-read fields (ctx, asks, hanging) for a RemoteCanvasSource, even with conflicting local state for the same node id', async (t) => {
     const sf = seedPoisonedLocalState();
     const server = await startMockCrtrServer((args) => {
         if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'list') {
@@ -211,11 +214,11 @@ test('renderForestFromSource suppresses local-read fields (ctx, asks, hanging) f
         }
         return { status: 500, body: {} };
     });
+    t.after(() => server.close());
     const source = new RemoteCanvasSource(server.url, 'tok');
     const out = await renderForestFromSource(source);
     assert.match(out, /ctx 0k/, 'the remote node must render with the suppressed ctx default, not a real token read');
     assert.doesNotMatch(out, /⚑/, 'no ask badge — local asks must not leak into the static forest render');
     assert.doesNotMatch(out, /POISON FAULT/, 'a local active fault must not leak into the static forest render');
     assert.doesNotMatch(out, /POISON/, 'no poisoned local telemetry/goal/session text may appear anywhere in the output');
-    await server.close();
 });

package/dist/core/canvas/browse/__tests__/rebuild-coalescer.test.js

@@ -71,19 +71,36 @@ test('a burst of SSE-style triggers produces ONE round of remote requests, not N
             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 source = new RemoteCanvasSource(`http://127.0.0.1:${port}`, 'tok');
-    const rebuilder = createCoalescedRebuilder(async () => {
-        source.invalidate();
-        await source.listNodes(); // one round of remote requests, mirroring app.ts's rebuildSnapshot
-    }, 20);
-    for (let i = 0; i < 6; i++)
-        rebuilder.trigger();
-    await new Promise((r) => setTimeout(r, 80));
-    assert.equal(hits, 1, 'a burst of 6 SSE events must produce ONE round of remote requests, not 6');
-    await new Promise((r) => server.close(() => r()));
+    // The server MUST close in a `finally` — a listening TCP server keeps its
+    // process's event loop non-empty forever. Under `node --test`, every test
+    // file is its own child process; if an assertion in this test throws before
+    // the old inline `server.close()` at the end of the function ran, the
+    // server (and the process) never exited, wedging one `--test-concurrency`
+    // slot permanently and hanging the whole suite (see the CI-hang postmortem).
+    try {
+        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 source = new RemoteCanvasSource(`http://127.0.0.1:${port}`, 'tok');
+        const rebuilder = createCoalescedRebuilder(async () => {
+            source.invalidate();
+            await source.listNodes(); // one round of remote requests, mirroring app.ts's rebuildSnapshot
+        }, 20);
+        for (let i = 0; i < 6; i++)
+            rebuilder.trigger();
+        // Poll for the request to land instead of sleeping a fixed duration —
+        // deterministic under CI's variable CPU load, and doesn't slow down the
+        // common case (returns as soon as the debounce + request round trip land).
+        const deadline = Date.now() + 2000;
+        while (hits < 1 && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 10));
+        }
+        assert.equal(hits, 1, 'a burst of 6 SSE events must produce ONE round of remote requests, not 6');
+    }
+    finally {
+        server.closeAllConnections();
+        await new Promise((r) => server.close(() => r()));
+    }
 });
 // Integration proof for browse/app.ts's ACTUAL wiring — not the coalescer
 // helper in isolation. Every test above instantiates `createCoalescedRebuilder`

package/dist/core/canvas/pid.d.ts

@@ -74,16 +74,20 @@ export declare function identitiesMatch(a: string, b: string): boolean;
  *      `identitiesMatch` says so, else `'dead'` (positively reused). */
 export type RecordedPidLiveness = 'alive' | 'dead' | 'indeterminate';
 export declare function recordedPidLiveness(pid: number | null | undefined, expectedIdentity: string | null | undefined): RecordedPidLiveness;
-/** Boolean teardown-direction adapter over `recordedPidLiveness`, kept so
- *  every pre-existing signalling caller stays behavior-identical: `dead` is
- *  the ONLY thing that reads false. `indeterminate` (can't confirm either
- *  way) reads true alongside `alive` — never signal a maybe-ours pid on mere
- *  uncertainty, matching this module's universal discipline (a POSITIVE
- *  mismatch is the only thing that changes behavior, never an absence of
- *  evidence). Callers that need to distinguish "confirmed alive" from
- *  "can't confirm" (e.g. a double-launch guard, where treating uncertainty as
- *  alive risks silently skipping a needed relaunch) must call
- *  `recordedPidLiveness` directly instead of this adapter. */
+/** Boolean confirmed-dead-direction adapter over `recordedPidLiveness`:
+ *  `dead` is the ONLY thing that reads false. `indeterminate` (can't confirm
+ *  either way) reads true alongside `alive` — never act on a maybe-ours pid
+ *  on mere uncertainty, matching this module's universal discipline (a
+ *  POSITIVE verdict is the only thing that changes behavior, never an
+ *  absence of evidence). This is the correct read for BOTH signalling
+ *  callers (never signal on uncertainty) and the double-launch guard in
+ *  `reviveNode` (never RELAUNCH on uncertainty — the identity probe is a
+ *  fork+exec that fails precisely under the OOM pressure where an extra
+ *  broker is most destructive, while a truly dead pid always reads `dead`
+ *  via the fork-free signal-0 path; see the guard's comment for the live
+ *  incident this closed). Callers that need "confirmed alive" three-valued
+ *  precision (e.g. the daemon's grace-clock bookkeeping) call
+ *  `recordedPidLiveness` directly. */
 export declare function isRecordedPidAlive(pid: number | null | undefined, expectedIdentity: string | null | undefined): boolean;
 /** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
  *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of

package/dist/core/canvas/pid.js

@@ -132,16 +132,20 @@ export function recordedPidLiveness(pid, expectedIdentity) {
         logPidLivenessDecision(pid, alive, expectedIdentity, 'value', matches ? 'identity matches expected → alive' : 'identity differs from expected → REUSED → dead', matches ? 'alive' : 'dead', actual);
     return matches ? 'alive' : 'dead';
 }
-/** Boolean teardown-direction adapter over `recordedPidLiveness`, kept so
- *  every pre-existing signalling caller stays behavior-identical: `dead` is
- *  the ONLY thing that reads false. `indeterminate` (can't confirm either
- *  way) reads true alongside `alive` — never signal a maybe-ours pid on mere
- *  uncertainty, matching this module's universal discipline (a POSITIVE
- *  mismatch is the only thing that changes behavior, never an absence of
- *  evidence). Callers that need to distinguish "confirmed alive" from
- *  "can't confirm" (e.g. a double-launch guard, where treating uncertainty as
- *  alive risks silently skipping a needed relaunch) must call
- *  `recordedPidLiveness` directly instead of this adapter. */
+/** Boolean confirmed-dead-direction adapter over `recordedPidLiveness`:
+ *  `dead` is the ONLY thing that reads false. `indeterminate` (can't confirm
+ *  either way) reads true alongside `alive` — never act on a maybe-ours pid
+ *  on mere uncertainty, matching this module's universal discipline (a
+ *  POSITIVE verdict is the only thing that changes behavior, never an
+ *  absence of evidence). This is the correct read for BOTH signalling
+ *  callers (never signal on uncertainty) and the double-launch guard in
+ *  `reviveNode` (never RELAUNCH on uncertainty — the identity probe is a
+ *  fork+exec that fails precisely under the OOM pressure where an extra
+ *  broker is most destructive, while a truly dead pid always reads `dead`
+ *  via the fork-free signal-0 path; see the guard's comment for the live
+ *  incident this closed). Callers that need "confirmed alive" three-valued
+ *  precision (e.g. the daemon's grace-clock bookkeeping) call
+ *  `recordedPidLiveness` directly. */
 export function isRecordedPidAlive(pid, expectedIdentity) {
     return recordedPidLiveness(pid, expectedIdentity) !== 'dead';
 }

package/dist/core/command.d.ts

@@ -56,6 +56,17 @@ export interface BranchDef {
     rootEntry?: RootEntry;
     /** Opt into editor slash-command exposure (see SlashSpec). */
     slash?: SlashSpec;
+    /** Opt this branch out of the tree model entirely: every token after this
+     *  branch's name is forwarded VERBATIM (raw argv, not the `--json`-filtered
+     *  tokens) to an external binary via spawn, with stdio inherited and the
+     *  child's exit code propagated. A deliberate, documented exception for
+     *  wrapping an external CLI whose own schema crtr cannot and must not
+     *  duplicate (see `crtr capture`) — not a general escape hatch. A
+     *  passthrough branch should declare no children. */
+    passthrough?: {
+        bin: string;
+        installHint: string;
+    };
     children: (LeafDef | BranchDef)[];
 }
 export interface RootDef {
@@ -81,6 +92,10 @@ export declare function defineBranch(opts: {
     help: BranchHelp;
     rootEntry?: RootEntry;
     slash?: SlashSpec;
+    passthrough?: {
+        bin: string;
+        installHint: string;
+    };
     children: (LeafDef | BranchDef)[];
 }): BranchDef;
 /** Walk the whole tree and collect every node's SlashSpec (depth-first). Used

package/dist/core/command.js

@@ -10,6 +10,8 @@ import { renderResult } from './render.js';
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
 import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
 // ---------------------------------------------------------------------------
 // Factory functions
 // ---------------------------------------------------------------------------
@@ -34,6 +36,14 @@ function visibleSubCount(def) {
     return (def.help.listing ?? []).filter((c) => c.tier !== 'hidden').length;
 }
 export function defineBranch(opts) {
+    // A passthrough branch must be childless: walk() only stops at the deepest
+    // matched node, so a passthrough branch with children would let some
+    // invocations descend into a child (tree dispatch) while others hit the
+    // passthrough interception — silently inconsistent transparency. Fail loudly
+    // at construction instead of letting that split happen at runtime.
+    if (opts.passthrough !== undefined && opts.children.length > 0) {
+        throw new Error(`defineBranch("${opts.name}"): a passthrough branch must declare no children (found ${opts.children.length})`);
+    }
     // Assemble the parent-level listing straight from the child defs — each node
     // owns its own description/whenToUse/tier, so the parent copies nothing
     // (principle 16). Bottom-up construction guarantees a child branch's listing
@@ -57,6 +67,7 @@ export function defineBranch(opts) {
         help: opts.help,
         rootEntry: opts.rootEntry,
         slash: opts.slash,
+        passthrough: opts.passthrough,
         children: opts.children,
     };
 }
@@ -169,6 +180,59 @@ function renderNode(node) {
 function helpRequested(remaining) {
     return remaining.some((t) => t === '-h' || t === '--help');
 }
+/** Recover the RAW argv slice after a matched passthrough branch's path,
+ *  unaffected by the `--json`-stripping done to build `tokens`. `path` is a
+ *  prefix of non-`--json` tokens in order, so walking `rawTokens` while
+ *  skipping `--json` occurrences until `path` is fully matched lands the
+ *  cursor exactly where the branch's own args begin — including a literal
+ *  `--json` the external binary itself accepts. */
+function rawArgsAfterPath(rawTokens, path) {
+    let matched = 0;
+    for (let i = 0; i < rawTokens.length; i++) {
+        if (matched === path.length)
+            return rawTokens.slice(i);
+        if (rawTokens[i] === '--json')
+            continue;
+        if (rawTokens[i] === path[matched])
+            matched++;
+    }
+    return [];
+}
+/** Forward `args` to an external binary verbatim: stdio inherited (streaming
+ *  preserved), and the child's exit code propagated. Never returns — either
+ *  exits with the child's status or throws a structured CrtrError (ENOENT ->
+ *  install hint) for the caller's existing error handler to render. */
+function runPassthrough(passthrough, args) {
+    const result = spawnSync(passthrough.bin, args, { stdio: 'inherit' });
+    if (result.error !== undefined) {
+        // Any launch-time failure (not found, not executable, ...) means this
+        // binary isn't usable from here — surface one structured error with the
+        // install hint rather than branching on a specific errno. (Node/libuv can
+        // report EACCES instead of ENOENT for a genuinely-missing binary when PATH
+        // contains malformed entries — e.g. a literal `~/...` segment — so a
+        // ENOENT-only check would miss real missing-binary cases on such hosts.)
+        const err = result.error;
+        throw new CrtrError('binary_missing', `${passthrough.bin} could not be run (${err.code ?? err.message})`, ExitCode.USAGE, {
+            received: passthrough.bin,
+            next: passthrough.installHint,
+        });
+    }
+    if (result.status !== null) {
+        process.exit(result.status);
+    }
+    if (result.signal !== null) {
+        // Signal-terminated: exit(1) would break the transparent exit-propagation
+        // contract (a direct shell invocation would show 128+signal, e.g. 143 for
+        // SIGTERM). Map to the standard 128+signal-number convention.
+        const signalNumber = osConstants.signals[result.signal];
+        if (signalNumber !== undefined) {
+            process.exit(128 + signalNumber);
+        }
+    }
+    // Truly impossible per Node's spawnSync contract (status and signal are
+    // mutually exclusive and one is always set on a completed run) — fallback only.
+    process.exit(1);
+}
 /** Build a structured unknown-path error. Names valid children of the deepest
  *  matched node and names the entry command per the spec. The entry command is
  *  the full path to the matched node (not just its local name), so the recovery
@@ -367,6 +431,14 @@ export async function runCli(root, argv) {
     }
     const { node, path, remaining } = walk(root, tokens);
     try {
+        // Passthrough branches (e.g. `crtr capture`) opt out of the tree model
+        // entirely: forward every token after the branch verbatim to an external
+        // binary before any of the normal unknown-path / help / dispatch logic
+        // runs, so `crtr capture -h`, `crtr capture <args>`, and bare `crtr capture`
+        // all reach the external CLI untouched.
+        if (node.kind === 'branch' && node.passthrough !== undefined) {
+            runPassthrough(node.passthrough, rawArgsAfterPath(rawTokens, path));
+        }
         // A root/branch node's `remaining` is only non-empty because walk hit
         // -h/--help or an unmatched child name (a leaf always consumes the rest
         // of the path itself). So a non-help leading token here is always the

package/dist/core/profiles/select.d.ts

@@ -27,7 +27,10 @@ export declare function profileCoversCwd(entry: ProfileEntry, cwd: string): bool
  *         is covered). Default is the MRU covering profile.
  *       - Non-interactive: auto-pick the MRU covering profile, no prompt.
  *  4. Else — nothing covers cwd walking all the way up. Interactive: prompt to
- *     create a profile here or use the root profile. Non-interactive (no TTY):
+ *     create a profile here, select an existing profile (a searchable list of
+ *     every profile, for when you started somewhere none of them cover and
+ *     can't recall the exact name — the pick then offers to adopt cwd), or use
+ *     the root profile. Non-interactive (no TTY):
  *     default to the root profile and print the recovery instruction to STDERR —
  *     never stdout, which the caller may be piping. */
 export declare function selectProfileForCwd(cwd: string, explicitProfile?: string | null, forcePicker?: boolean): Promise<string>;