@north-light/crouter 0.3.233 → 0.3.234

package/dist/core/__tests__/plugin-page-components.test.js

@@ -81,7 +81,7 @@ test('two plugins whose kinds derive one JSX tag are rejected, naming both sourc
     plantPlugin(root, 'beta', ['foo--bar']);
     assert.throws(() => resolvePageComponents(), /kind "foo--bar" \(plugin "beta"\) derives JSX tag "FooBar", which duplicates kind "foo-bar" from plugin "alpha"/);
 });
-// --- archive path -----------------------------------------------------------
+// archive path
 function minimalCommandsJson() {
     return {
         schemaVersion: 1,

package/dist/core/__tests__/preview-registry-sync.test.js

@@ -15,7 +15,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { buildRoot } from '../../build-root.js';
-import { SUPPRESS_OUTPUT_LEAVES } from '../preview-registry.js';
+import { SUPPRESS_OUTPUT_LEAVES, LEAF_ICON_CP, SUMMARIZERS } from '../preview-registry.js';
 import { resetScopeCache } from '../scope.js';
 // buildRoot() composes external command-plugin branches from the effective
 // enabled plugins (user scope + project ancestors). Pin HOME + profile to an
@@ -62,3 +62,44 @@ test('preview-registry.ts matches every leaf declaring help.preview.suppressOutp
     assert.deepEqual([...declared].sort(), [...SUPPRESS_OUTPUT_LEAVES].sort(), 'src/core/preview-registry.ts is out of sync with the leaves that declare ' +
         'help.preview.suppressOutput — update SUPPRESS_OUTPUT_LEAVES to match.');
 });
+test('every LEAF_ICON_CP key and SUMMARIZERS path names a leaf or branch that still exists', async () => {
+    const root = await buildRoot();
+    // LEAF_ICON_CP is matched as a PREFIX against argv tokens (iconForPath), so
+    // a key may legitimately name either a leaf or a branch (e.g. "human
+    // review", a branch with no default action of its own). SUMMARIZERS keys
+    // ARE always a single invocable leaf. Both name sets are collected here.
+    const names = new Set();
+    const leafNames = new Set();
+    const walk = (branch) => {
+        names.add(branch.help.name);
+        for (const child of branch.children) {
+            if (child.kind === 'branch') {
+                walk(child);
+            }
+            else {
+                names.add(child.help.name);
+                leafNames.add(child.help.name);
+            }
+        }
+    };
+    for (const subtree of root.subtrees)
+        walk(subtree);
+    // The registry pre-declares icons for PLUGIN commands too (`search web` and
+    // friends), and a plugin is present only when installed — it is absent on a
+    // clean CI runner. So a key is only checkable when its ROOT command exists:
+    // root present means the rest of the path must resolve (this is what catches a
+    // genuinely stale entry, e.g. a renamed `human review`), while an absent root
+    // means an uninstalled plugin and is not evidence of staleness.
+    const rootNames = new Set(root.subtrees.map((s) => s.help.name));
+    const rootInstalled = (path) => rootNames.has(path.split(' ')[0]);
+    for (const path of Object.keys(LEAF_ICON_CP)) {
+        if (!rootInstalled(path))
+            continue;
+        assert.ok(names.has(path), `LEAF_ICON_CP names "${path}", which is not a leaf or branch in the live command tree — update or remove it.`);
+    }
+    for (const { path } of SUMMARIZERS) {
+        if (!rootInstalled(path))
+            continue;
+        assert.ok(leafNames.has(path), `SUMMARIZERS names "${path}", which is not a leaf in the live command tree — update or remove it.`);
+    }
+});

package/dist/core/__tests__/respawn-throttle.test.js

@@ -73,9 +73,7 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
-// ===========================================================================
 // Short-lived exits 1-5 defer with doubling backoff; the 6th terminalizes.
-// ===========================================================================
 test('consecutive short-lived exits defer respawn on a doubling backoff, then terminalize at the cap', async () => {
     // A booted row (saved session, no crash markers) — table row 6, respawn-resume.
     createNode(node('T', { pi_session_id: 'sess-T' }));
@@ -95,9 +93,7 @@ test('consecutive short-lived exits defer respawn on a doubling backoff, then te
     assert.equal(getNode('T').status, 'dead', 'the respawn loop terminalizes at MAX_RESPAWN_ATTEMPTS');
     assert.equal(events().some((e) => e.event === 'broker.respawn.exhausted'), true, 'exhaustion is surfaced as its own event');
 });
-// ===========================================================================
 // A healthy-uptime exit resets the counter: the next respawn is immediate.
-// ===========================================================================
 test('a pre-launch respawn refusal terminalizes the stranded node and wakes its parent', async () => {
     const missingCwd = join(home, 'reaped-worktree');
     createNode(node('P', { lifecycle: 'resident' }));

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

@@ -51,7 +51,7 @@ function meta(over = {}) {
         ...over,
     };
 }
-// --- engine liveness branch -------------------------------------------------
+// engine liveness branch
 test('a node whose engine is RUNNING (live pid) is NOT disconnected — never double-spawn', () => {
     assert.equal(isDisconnected(meta({ pi_pid: 1234 }), ALIVE), false);
 });
@@ -61,14 +61,14 @@ test('a node whose engine is DEAD but has a saved session IS disconnected', () =
 test('a node with a null pid (never/ no longer recorded) and a session IS disconnected', () => {
     assert.equal(isDisconnected(meta({ pi_pid: null }), DEAD), true);
 });
-// --- resumable-session requirement -----------------------------------------
+// resumable-session requirement
 test('a dead node with NO resumable saved session is NOT disconnected', () => {
     assert.equal(isDisconnected(meta({ pi_session_id: null, pi_session_file: null }), DEAD), false);
 });
 test('a session FILE alone (older node, no id) is enough to be disconnected', () => {
     assert.equal(isDisconnected(meta({ pi_session_id: null }), DEAD), true);
 });
-// --- terminal-by-choice scope ----------------------------------------------
+// terminal-by-choice scope
 for (const status of TERMINAL_BY_CHOICE) {
     test(`a dead-engine '${status}' node is EXCLUDED (terminal-by-choice, no opt-in)`, () => {
         assert.equal(isDisconnected(meta({ status: status }), DEAD), false);
@@ -89,11 +89,11 @@ test('a node with final_report set is EXCLUDED even when status is dead (finishe
 test("dormant 'idle' nodes with a saved session are swept by default", () => {
     assert.equal(isDisconnected(meta({ status: 'idle', intent: 'idle-release' }), DEAD), true);
 });
-// --- human-bridge carve-out -------------------------------------------------
+// human-bridge carve-out
 test("kind:'human' rows (the human bridge, never a pi engine) are never disconnected", () => {
     assert.equal(isDisconnected(meta({ kind: 'human', pi_pid: null }), DEAD), false);
 });
-// --- listDisconnected over a live canvas (the sweep's selection) -------------
+// listDisconnected over a live canvas (the sweep's selection)
 //
 // Locks that the canvas-wide select returns EXACTLY the disconnected set against
 // the REAL isPidAlive probe — a live-engine node (this process's pid) is kept

package/dist/core/__tests__/revive-parked-fresh.test.js

@@ -1,11 +1,17 @@
 // Run with: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/revive-parked-fresh.test.ts
 //
 // Re-entering a parked node starts a FRESH cycle grounded in goal + roadmap
-// rather than replaying the transcript its parking turn already concluded. The
-// rule is a property of the node, evaluated once inside reviveNode, so every
-// doorway gets it from one strict-resume veto. Its one exception is a park with
-// nothing on disk to stand on (reachable only on the degraded path, which
-// writes no summary): resuming an old transcript beats waking amnesiac.
+// rather than replaying the transcript its parking turn already concluded —
+// but only when the revival CARRIES NEW INPUT. Wake-worthy mail that the node
+// has not seen is that input: every doorway that wakes a parked node because
+// something arrived appends its durable inbox entry before calling in. An
+// input-less revival (a bare lifecycle revive, a viewer attach, a focus) has
+// nothing to answer, so it quietly resumes the old transcript and injects no
+// kickoff. The rule is a property of the node, evaluated once inside
+// reviveNode, so every doorway gets it from one strict-resume veto. Its other
+// exception is a park with nothing on disk to stand on (reachable only on the
+// degraded path, which writes no summary): resuming an old transcript beats
+// waking amnesiac.
 import { after, afterEach, before, beforeEach, test } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
@@ -14,6 +20,7 @@ import { join } from 'node:path';
 import { createNode, getNode } from '../canvas/canvas.js';
 import { contextDir } from '../canvas/paths.js';
 import { closeDb } from '../canvas/db.js';
+import { appendInbox, readCursor, writeCursor } from '../feed/inbox.js';
 import { transition } from '../runtime/lifecycle.js';
 import { reviveNode } from '../runtime/revive.js';
 import { headlessBrokerHost } from '../runtime/host.js';
@@ -49,6 +56,21 @@ function parkResident(id, ground = {}) {
         writeFileSync(join(contextDir(id), 'initial-prompt.md'), ground.goal);
     transition(id, 'park');
 }
+/** Durable wake-worthy mail, appended exactly as every message doorway appends
+ *  it before calling reviveNode. */
+function deliverMail(id, tier = 'normal') {
+    return appendInbox(id, { from: null, tier, kind: 'message', label: 'work', data: { body: 'work' } }).entry_id;
+}
+/** Did this launch carry the fresh-revive kickoff? `buildReviveKickoff` always
+ *  opens its card body with this sentence (src/core/runtime/kickoff.ts:325). */
+function kickedOff(entry) {
+    return entry.argv.some((arg) => arg.includes('You have been revived fresh'));
+}
+/** The two facts every row below asserts together: a fresh row is
+ *  `resuming:false` + kickoff, a quiet row is `resuming:true` + none. */
+function placements() {
+    return launches.map(({ nodeId, resuming }) => ({ nodeId, resuming }));
+}
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-revive-parked-'));
     priorHome = process.env['CRTR_HOME'];
@@ -62,8 +84,8 @@ beforeEach(() => {
     fleet = bindTestFleet();
     launches = [];
     originalLaunch = headlessBrokerHost.launch;
-    headlessBrokerHost.launch = ((nodeId, _inv, opts) => {
-        launches.push({ nodeId, resuming: opts.resuming });
+    headlessBrokerHost.launch = ((nodeId, inv, opts) => {
+        launches.push({ nodeId, resuming: opts.resuming, argv: inv.argv });
         const handle = { pid: 0x7ffffffe, exited: new Promise(() => { }) };
         fleet.fleet.register(nodeId, handle);
         return handle;
@@ -81,25 +103,54 @@ after(() => {
     else
         process.env['CRTR_HOME'] = priorHome;
 });
-test('a parked node with a roadmap re-enters fresh even when the caller asked to resume, and the marker clears', () => {
+test('a parked node with mail waiting re-enters fresh even when the caller asked to resume, and the marker clears', () => {
     parkResident('parked', { roadmap: '# Roadmap\n\n- one open item\n' });
+    deliverMail('parked');
     const result = reviveNode('parked', { resume: true });
     assert.equal(result.resumed, false, 'the concluded transcript is not replayed');
-    assert.deepEqual(launches, [{ nodeId: 'parked', resuming: false }]);
+    assert.deepEqual(placements(), [{ nodeId: 'parked', resuming: false }]);
+    assert.equal(kickedOff(launches[0]), true, 'the fresh window is handed its bearings');
     const reopened = getNode('parked');
     assert.equal(reopened.status, 'active');
     assert.equal(reopened.intent ?? null, null, 'the park marker clears on revival');
     assert.equal(reopened.cycle_pending, true, 'the fresh cycle is provisional until session_start confirms it');
 });
-test('a parked node grounded only by a goal still re-enters fresh', () => {
+test('a parked node grounded only by a goal still re-enters fresh when mail rides the revive', () => {
     parkResident('goal-only', { goal: 'Watch the deploy lane.' });
+    deliverMail('goal-only');
     assert.equal(reviveNode('goal-only', { resume: true }).resumed, false);
+    assert.equal(kickedOff(launches[0]), true);
+});
+test('an input-less revival of a parked node quietly resumes and injects no kickoff', () => {
+    parkResident('quiet', { roadmap: '# Roadmap\n\n- one open item\n' });
+    const result = reviveNode('quiet', { resume: true });
+    assert.equal(result.resumed, true, 'nothing arrived, so there is nothing a fresh window would answer');
+    assert.deepEqual(placements(), [{ nodeId: 'quiet', resuming: true }]);
+    assert.equal(kickedOff(launches[0]), false, 'a quiet resume generates nothing');
+    assert.equal(readCursor('quiet'), undefined, 'drainBearings did not run, so nothing was consumed');
+    const reopened = getNode('quiet');
+    assert.equal(reopened.status, 'active');
+    assert.equal(reopened.intent ?? null, null, 'the park marker clears on a quiet resume too');
+});
+test('deferred mail alone is not input, so the revival still resumes quietly', () => {
+    parkResident('deferred', { roadmap: '# Roadmap\n\n- one open item\n' });
+    deliverMail('deferred', 'deferred');
+    assert.equal(reviveNode('deferred', { resume: true }).resumed, true);
+    assert.equal(kickedOff(launches[0]), false);
+    assert.equal(readCursor('deferred'), undefined, 'the deferred entry rides the next natural cycle, unconsumed');
+});
+test('mail already covered by the cursor is not input, so the revival still resumes quietly', () => {
+    parkResident('stale', { roadmap: '# Roadmap\n\n- one open item\n' });
+    writeCursor('stale', deliverMail('stale'));
+    assert.equal(reviveNode('stale', { resume: true }).resumed, true, 'only the UNSEEN suffix counts as input');
+    assert.equal(kickedOff(launches[0]), false);
 });
 test('a parked node with no goal and no roadmap resumes its transcript rather than waking amnesiac', () => {
     parkResident('bare');
+    deliverMail('bare');
     const result = reviveNode('bare', { resume: true });
     assert.equal(result.resumed, true, 'the degraded park has nothing on disk to ground a fresh window');
-    assert.deepEqual(launches, [{ nodeId: 'bare', resuming: true }]);
+    assert.deepEqual(placements(), [{ nodeId: 'bare', resuming: true }]);
 });
 test('an ordinary done node with a roadmap still resumes — only the park marker vetoes', () => {
     parkResident('finished', { roadmap: '# Roadmap\n\n- one open item\n' });

package/dist/core/__tests__/seam/broker-attach-multiclient.test.js

@@ -79,7 +79,6 @@ const barrier = async (c, label) => {
 const isRequest = (f) => f.type === 'extension_ui_request';
 const dismissFor = (reqId) => (f) => f.type === 'extension_ui_dismiss' && f.id === reqId;
 const welcomes = (frames) => frames.filter((f) => f.type === 'welcome');
-// ---------------------------------------------------------------------------
 // G4 — multi-writer admission + read-only gating + broadcast fan-out. Guards: two
 // simultaneous `controller` hellos are BOTH welcomed writable, each one's own
 // submission reaches the engine, every connected client sees BOTH turns, an
@@ -90,7 +89,6 @@ const welcomes = (frames) => frames.filter((f) => f.type === 'welcome');
 // Failure mode: a singleton writer slot demoting the second client, a writer
 // whose prompt is silently dropped, fan-out that misses a viewer, a read-only
 // client that can drive the engine, or a model switch only its requester hears.
-// ---------------------------------------------------------------------------
 test('G4 — two simultaneous clients are both welcomed controller, each submits, all clients see both turns and the model switch; an observer drive → error{read_only}', async () => {
     const [w1, w2] = await Promise.all([
         attach(id, 'controller', 'g4-writer-1'),
@@ -132,7 +130,6 @@ test('G4 — two simultaneous clients are both welcomed controller, each submits
     const om = await obs.waitFrame((f) => f.type === 'model_changed', 'G4 observer receives model_changed');
     assert.ok(om.type === 'model_changed' && om.model?.id === 'fake-fable', 'G4: a read-only observer ALSO hears the switch');
 });
-// ---------------------------------------------------------------------------
 // G5 — dialog fan-out, mid-dialog handoff, and first-response settlement.
 // Guards: ONE blocking dialog reaches EVERY writable client (never a single
 // owner), a writable client attaching MID-dialog is handed it via
@@ -143,7 +140,6 @@ test('G4 — two simultaneous clients are both welcomed controller, each submits
 // Failure modes: a dialog only one viewer can see (the others sit blind), a
 // late-joining writable viewer blind to an in-flight dialog, peers left holding
 // an overlay nothing can answer, or a late peer answer re-settling a dead dialog.
-// ---------------------------------------------------------------------------
 test('G5 — one dialog fans out to every writable client and to a mid-dialog joiner, the first response settles it, all are dismissed, and a late peer response is a no-op', async () => {
     const base = h.dialogResults(id).length;
     const a = await writer('g5-A');
@@ -184,7 +180,6 @@ test('G5 — one dialog fans out to every writable client and to a mid-dialog jo
     assert.equal(settled[base].resolved, true, "G5: the late peer response did not overwrite the first answerer's value");
     assert.equal(isPidAlive(brokerPid()), true, 'G5: the late no-op response did not fault the broker');
 });
-// ---------------------------------------------------------------------------
 // G9 — re-welcome after an IN-PLACE session mutation (real bug, observed
 // 2026-06-11 in `crtr surface attach`: double-Esc/`/tree` opened the session-tree
 // picker, but SELECTING an entry visibly did nothing). session.navigateTree()
@@ -194,7 +189,6 @@ test('G5 — one dialog fans out to every writable client and to a mid-dialog jo
 // attached client rendering the abandoned branch and dropping the navigated-to
 // user message's editorText. Failure mode: no second welcome arrives at all, or
 // the re-welcome serves a stale snapshot.
-// ---------------------------------------------------------------------------
 test('G9 — navigate_tree re-welcomes every viewer onto the rewound transcript and acks the editor text', async () => {
     const c = await writer('nav-ctrl');
     // Accrue one observable turn so the rewind has something to drop.
@@ -222,7 +216,6 @@ test('G9 — navigate_tree re-welcomes every viewer onto the rewound transcript
     assert.ok(!frameHas(second, token), 'G9: re-welcome serves the rewound transcript (turn dropped)');
     assert.equal(second.snapshot.messages.length, first.snapshot.messages.length - 2, 'G9: re-welcome history is exactly one turn shorter (a turn = user + assistant = 2 tree messages)');
 });
-// ---------------------------------------------------------------------------
 // G10 — catch-up is ONE atomic frame. `ctx.ui.setStatus/setWidget/setTitle` are
 // LEVELS with no pi getter, so the broker is their only holder; it ships that
 // held state as `welcome.snapshot.display` and sends NO display edge after the
@@ -232,7 +225,6 @@ test('G9 — navigate_tree re-welcomes every viewer onto the rewound transcript
 // re-emitted N synthetic display frames after the snapshot: catch-up was
 // non-atomic and the viewer had to clear-and-rebuild, painting blank chrome in
 // the gap. Both halves of that cut fail this test.
-// ---------------------------------------------------------------------------
 test('G10 — retained extension display state rides IN welcome.snapshot.display, and no display edge follows the welcome', async () => {
     const DISPLAY_METHODS = new Set(['setStatus', 'setWidget', 'setTitle']);
     const isDisplayFrame = (f) => f.type === 'extension_ui_request' && f.method !== undefined && DISPLAY_METHODS.has(f.method);

package/dist/core/__tests__/seam/broker-attach-stream.test.js

@@ -61,11 +61,9 @@ afterEach(() => {
     kit.closeAll();
 });
 const brokerPid = () => h.node(id).pi_pid;
-// ---------------------------------------------------------------------------
 // G1 — controller drive + live relay. Guards: a controller's `prompt` runs the
 // engine AND the streaming AgentSessionEvents are fanned out to the client
 // VERBATIM. Failure mode: a broken relay/fan-out (viewer sees nothing).
-// ---------------------------------------------------------------------------
 test('G1 — controller prompt runs the engine and the streamed AgentSessionEvents relay to the client', async () => {
     const c = await ctrl('g1-ctrl');
     assert.equal(c.welcome.role, 'controller', 'first controller is admitted as controller');
@@ -80,7 +78,6 @@ test('G1 — controller prompt runs the engine and the streamed AgentSessionEven
     }
     assert.ok(c.frames.some((f) => f.type === 'message_start' && frameHas(f, token)), 'G1: a relayed message carries the prompt token');
 });
-// ---------------------------------------------------------------------------
 // G1b — message_update coalescing preserves ordering (regression for the F2
 // attach typing-lag fix, 2026-06-09). The broker holds the latest message_update
 // on a ~75ms timer; any OTHER event must flush it FIRST, so a viewer can never
@@ -88,7 +85,6 @@ test('G1 — controller prompt runs the engine and the streamed AgentSessionEven
 // streaming text over the final message), and the LAST coalesced update must not
 // be silently dropped at end-of-turn. Failure modes: a flush ordered after the
 // non-update event, or a pending update discarded when message_end wins the race.
-// ---------------------------------------------------------------------------
 test('G1b — coalesced message_update never arrives after message_end; updates still relayed', async () => {
     const c = await ctrl('g1b-ctrl');
     const token = tok('G1B');
@@ -114,10 +110,8 @@ test('G1b — coalesced message_update never arrives after message_end; updates
         assert.ok(i < 0 || lastUpdate < i, `G1b: message_update relayed after ${t}`);
     }
 });
-// ---------------------------------------------------------------------------
 // G2 — detach leaves the engine running. Guards: `bye`/close drops ONE listener,
 // never the engine. Failure mode: a detach that disposes the broker/engine.
-// ---------------------------------------------------------------------------
 test('G2 — detach (bye+close) leaves the broker alive + the engine still emitting; engine pid unchanged', async () => {
     const pid = brokerPid();
     const boots = h.bootCount(id);
@@ -139,7 +133,6 @@ test('G2 — detach (bye+close) leaves the broker alive + the engine still emitt
     assert.ok(o.welcome.snapshot.messages.length > 0, 'G2: the engine produced a message after the detach');
     assert.equal(isPidAlive(pid), true, 'G2: broker still alive after the post-detach turn');
 });
-// ---------------------------------------------------------------------------
 // G3 — the interactive `deliver` ack reports the ENGINE CALL's real outcome, not
 // the fact that a call was routed. A `session.prompt()` that REJECTS outright —
 // the shape a broker whose model resolved but whose provider has no installed
@@ -150,7 +143,6 @@ test('G2 — detach (bye+close) leaves the broker alive + the engine still emitt
 // engine's own agent_start) against rejection and records
 // `broker.prompt.deliver_failed` in the node's job/log.jsonl. Shares this file's
 // one broker: the contract is two frames on an attached controller.
-// ---------------------------------------------------------------------------
 test('G3 — a deliver whose prompt rejects acks ok:false and records deliver_failed; a succeeding deliver acks ok:true via prompt', async () => {
     // Both delivers must route as `prompt` (idle), never `steer` — the steer route
     // legitimately acks at routing time — so attach only once the engine is idle.

package/dist/core/__tests__/seam/broker-crash-teardown.test.js

@@ -43,11 +43,9 @@ after(async () => {
     else
         process.env['PI_FAKE_ENGINE_HOLD_TURN'] = priorHoldTurn;
 });
-// ===========================================================================
 // Items 4 + 5 + 6 — two independent real-process journeys:
 //   graceful busy teardown → strict resume + continuation;
 //   dirty interrupted-turn crash → recovery cycle → close.
-// ===========================================================================
 test('SIGTERM of a busy broker aborts cleanly and resumes with a continuation', { timeout: 30_000 }, async () => {
     const id = await h.spawnHeadlessChild(root, 'headless worker — graceful crash recovery');
     const boot1 = await h.awaitBoot(id);

package/dist/core/__tests__/tmux-driver-boundary.test.d.ts

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

package/dist/core/__tests__/tmux-driver-boundary.test.js

@@ -0,0 +1,50 @@
+// tmux-driver.ts owns the raw tmux process boundary — every direct
+// `spawnSync('tmux', ...)` elsewhere is a duplicated probe that should call
+// through tmux-driver.ts's exported primitives instead. This grep-enforces
+// that boundary with an explicit allowlist: the owner itself and three
+// pre-existing direct spawners with a genuinely distinct semantic (documented
+// per-entry below).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve, relative } from 'node:path';
+const SRC_ROOT = resolve(process.cwd(), 'src');
+// Relative to src/, forward-slash form.
+const ALLOWLIST = new Set([
+    'core/runtime/tmux-driver.ts', // the owner
+    'clients/attach/session/mouse.ts', // mouse-mode detection — a distinct probe, not reachability
+    'core/clipboard-text.ts', // OSC-52 paste-buffer write — not a reachability probe
+    'core/termrender/display.ts', // pane-count probe — not a reachability probe
+]);
+function tsFilesUnder(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        const path = join(dir, entry);
+        const stat = statSync(path);
+        if (stat.isDirectory()) {
+            if (entry === '__tests__')
+                continue;
+            out.push(...tsFilesUnder(path));
+        }
+        else if (entry.endsWith('.ts') && !entry.endsWith('.test.ts')) {
+            out.push(path);
+        }
+    }
+    return out;
+}
+test('every direct spawnSync("tmux", …) call site is inside the tmux-driver.ts allowlist', () => {
+    const offenders = [];
+    for (const file of tsFilesUnder(SRC_ROOT)) {
+        const relPath = relative(SRC_ROOT, file).split('\\').join('/');
+        if (ALLOWLIST.has(relPath))
+            continue;
+        const source = readFileSync(file, 'utf8');
+        const lines = source.split('\n');
+        lines.forEach((line, index) => {
+            if (/spawnSync\(\s*['"]tmux['"]/.test(line)) {
+                offenders.push(`${relPath}:${index + 1}`);
+            }
+        });
+    }
+    assert.deepEqual(offenders, [], `direct spawnSync('tmux', …) call(s) outside the tmux-driver.ts allowlist:\n${offenders.join('\n')}`);
+});

package/dist/core/activity-signal.d.ts

@@ -0,0 +1,7 @@
+/** One durable-mutation signal file under `crtrHome()/signals/<name>`, shared by
+ *  every subsystem that needs to tell every open viewer "something changed"
+ *  without watching each individual record's directory. */
+export declare function activityPath(name: string): string;
+/** Signal one durable mutation to every open watcher of `name`. */
+export declare function signalActivity(name: string): void;
+export declare function watchActivity(name: string, onChange: () => void): () => void;

package/dist/core/activity-signal.js

@@ -0,0 +1,38 @@
+import { basename, dirname, join } from 'node:path';
+import { mkdirSync, watch, writeFileSync } from 'node:fs';
+import { crtrHome } from './canvas/paths.js';
+/** One durable-mutation signal file under `crtrHome()/signals/<name>`, shared by
+ *  every subsystem that needs to tell every open viewer "something changed"
+ *  without watching each individual record's directory. */
+export function activityPath(name) {
+    return join(crtrHome(), 'signals', name);
+}
+/** Signal one durable mutation to every open watcher of `name`. */
+export function signalActivity(name) {
+    const path = activityPath(name);
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, `${Date.now()}\n`, { mode: 0o600 });
+    }
+    catch {
+        // A later read of the underlying record is still authoritative.
+    }
+}
+export function watchActivity(name, onChange) {
+    const path = activityPath(name);
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const watcher = watch(dirname(path), (_event, filename) => {
+            if (String(filename) === basename(path))
+                onChange();
+        });
+        return () => watcher.close();
+    }
+    catch (error) {
+        // The caller keeps a working no-op unwatch — a watch failure must not crash
+        // whatever set it up to be best-effort — but it stays surfaced once, since a
+        // silently-never-refreshing viewer is a real symptom, not a background detail.
+        console.error(`activity-signal: failed to watch "${name}": ${error instanceof Error ? error.message : String(error)}`);
+        return () => { };
+    }
+}

package/dist/core/auto-update.js

@@ -3,6 +3,7 @@ import { readConfig, readState, updateState } from './config.js';
 import { nowIso } from './fs-utils.js';
 import { info } from './output.js';
 import { SELF_UPDATE_SCRIPT, selfCheck, contentCheck } from './self-update.js';
+import { envDebug } from '../shared/env.js';
 const HOUR_MS = 60 * 60 * 1000;
 const SKIP_SUBCOMMANDS = new Set([
     'update',
@@ -85,7 +86,7 @@ export function maybeAutoUpdate(argv) {
         }
     }
     catch (e) {
-        if (process.env.CRTR_DEBUG === '1') {
+        if (envDebug()) {
             const msg = e instanceof Error ? e.message : String(e);
             process.stderr.write(`crtr: auto-update hook error: ${msg}\n`);
         }

package/dist/core/bootstrap.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { findProjectScopeRoot, resetScopeCache, userScopeRoot } from './scope.js';
 import { ensureScopeInitialized } from './config.js';
 import { CRTR_DIR_NAME } from '../types.js';
+import { envDebug } from '../shared/env.js';
 const SKIP_SUBCOMMANDS = new Set([
     'help',
     '--help',
@@ -42,7 +43,7 @@ export function ensureProjectScope(argv) {
         resetScopeCache();
     }
     catch (e) {
-        if (process.env.CRTR_DEBUG === '1') {
+        if (envDebug()) {
             const msg = e instanceof Error ? e.message : String(e);
             process.stderr.write(`crtr: project-init error: ${msg}\n`);
         }

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

@@ -10,7 +10,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { createServer } from 'node:http';
 import { RemoteCanvasSource } from '../remote-canvas-source.js';
-import { dashboardRowsAllFromSource, renderForestFromSource } from '../render.js';
+import { dashboardRowsAllFromSource, renderForestFromSource } from '../render-source.js';
 /** Stand up a bare `node:http` server on an ephemeral loopback port — the
  *  `/__crtr/source` endpoint a `RemoteCanvasSource` POSTs to. `route` decides
  *  the response per captured argv; every request is recorded first so a test

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

@@ -62,7 +62,7 @@ test('a normal fast response is unaffected by the timeout wiring', async (t) =>
     assert.equal(result.ok, true);
     assert.equal(result.stdout, JSON.stringify({ nodes: [] }));
 });
-// --- Phase 3 review Minor 1: no token bytes may ever reach returned stderr ---
+// 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']);

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

@@ -21,7 +21,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { atomicWriteJson, pageManifestPath } from '#core/human/convention';
 import { RemoteCanvasSource } from '../remote-canvas-source.js';
-import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render.js';
+import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render-source.js';
 import { createNode } from '../canvas.js';
 import { closeDb } from '../db.js';
 import { openFocusRow } from '../focuses.js';

package/dist/core/canvas/browse/app.js

@@ -7,6 +7,7 @@
 // Resume is one action: Enter routes the chosen node through `crtr surface node focus`,
 // which goes via reviveNode() — the ONLY sanctioned open. NEVER spawn
 // `pi --session` directly (see reviveNode() in revive.ts for the desync hazard).
+import { envNodeId } from '../../../shared/env.js';
 import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render-source.js';
@@ -452,7 +453,7 @@ export async function runBrowse(opts) {
     // ancestors so it is actually visible. No-op outside a node or when it's filtered
     // out of the current tab/scope. Same move the boot performs, on demand (`.`).
     const recenterOnSelf = () => {
-        const selfId = process.env['CRTR_NODE_ID'];
+        const selfId = envNodeId();
         if (selfId === undefined || selfId === '' || !tree.nodes.has(selfId))
             return;
         for (let p = tree.nodes.get(selfId)?.parentId ?? null; p !== null; p = tree.nodes.get(p)?.parentId ?? null) {
@@ -804,7 +805,7 @@ export async function runBrowse(opts) {
     // not the top of the tree. Expand its ancestors so the row is actually visible,
     // then home the cursor onto it. No-op when launched outside a node, or when the
     // node is filtered out of the current tab/scope.
-    const selfId = process.env['CRTR_NODE_ID'];
+    const selfId = envNodeId();
     if (selfId !== undefined && selfId !== '' && tree.nodes.has(selfId)) {
         for (let p = tree.nodes.get(selfId)?.parentId ?? null; p !== null; p = tree.nodes.get(p)?.parentId ?? null) {
             state.collapsed.delete(p);

package/dist/core/canvas/browse/model.d.ts

@@ -1,4 +1,4 @@
-import type { DashboardRow } from '../render.js';
+import type { DashboardRow } from '../render-source.js';
 export type Tab = 'All' | 'Live' | 'Dormant' | 'Attention' | 'Pinned';
 export declare const TABS: readonly Tab[];
 /** How the visible rows are ordered.

package/dist/core/canvas/browse/model.js

@@ -119,9 +119,7 @@ export function pruneNode(tree, id) {
     }
     tree.nodes.delete(id);
 }
-// ---------------------------------------------------------------------------
 // Fuzzy match
-// ---------------------------------------------------------------------------
 /** Case-insensitive subsequence match: every char of `query` appears in `text`
  *  in order (gaps allowed). Empty query matches everything. Substrings are a
  *  subsequence, so this subsumes substring matching too. */
@@ -322,9 +320,7 @@ export function scoreRow(query, row) {
     const strength = matches.reduce((sum, { match, weight }) => sum + (match.tier === tier ? match.quality * weight : 0), 0);
     return { tier, strength };
 }
-// ---------------------------------------------------------------------------
 // Attention tiering (default sort)
-// ---------------------------------------------------------------------------
 /** The "most recent message" signal for the attention sort: the pi session-file
  *  mtime (ms) the snapshot stamps on each row, falling back to the `created`
  *  birth timestamp when no session file exists. Larger = more recent.