@north-light/crouter 0.3.232 → 0.3.234

package/dist/core/substrate/schema.js

@@ -9,21 +9,17 @@
 // render, and `crtr memory lint` owns strict authoring-time enforcement.
 import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
 import { surfaceEntryGatePasses } from './gate.js';
-// ---------------------------------------------------------------------------
 // Kinds — the two semantic kinds (design §3): `knowledge` (consult — procedural
 // playbooks + factual references merged) vs `preference` (behave — standing
 // directives). `kind` is a load-bearing binary, not a content taxonomy.
-// ---------------------------------------------------------------------------
 export const KINDS = ['knowledge', 'preference'];
 /** Is `v` one of the two valid document kinds? */
 export function isDocKind(v) {
     return typeof v === 'string' && KINDS.includes(v);
 }
-// ---------------------------------------------------------------------------
 // The 4-rung visibility ladder (design §4). A strict, monotone ordering where
 // each rung is a superset of disclosure over the one before:
 //   none < name < preview < content
-// ---------------------------------------------------------------------------
 // The ladder is ONE union, owned by the public API DTO (`ProfileProjectMemory`)
 // so a profile relationship's cap and a doc's authored rung are the same values
 // and clamp against each other without a conversion.
@@ -41,22 +37,18 @@ export function rungAtLeast(r, min) {
 export function minRung(a, b) {
     return rungRank(a) <= rungRank(b) ? a : b;
 }
-// ---------------------------------------------------------------------------
 // Identity — owned entirely by core/memory/identity.ts (ordering-prefix
 // normalization, INDEX collapse, explicit-name-then-path local identity,
 // namespace composition). Re-exported here so document parsing and identity
 // derivation stay one rule with one implementation.
-// ---------------------------------------------------------------------------
 export { normalizeNameSegment, normalizeDocName, resolveLocalName as resolveDocName } from '../memory/identity.js';
-// ---------------------------------------------------------------------------
 // Surfaces — explicit event routing (design: surfaces-design.md). A doc
 // declares WHEN it delivers as (event, match, rung) entries; matches are
 // always globs, always absolute in the event's namespace, with `./` as the
 // one relative spelling (anchoring to the doc's own container). A doc with
 // no `surfaces` at all does exactly one thing: appears in its directory's
 // listing.
-// ---------------------------------------------------------------------------
-export const SURFACE_EVENTS = ['boot', 'workspace-open', 'read', 'memory-read', 'command'];
+export const SURFACE_EVENTS = ['boot', 'workspace-open', 'read', 'memory-read', 'command', 'pre-command'];
 /** The rungs an entry may deliver at. There is no `none` — silence is the
  *  absence of an entry. (`Rung`'s `none` survives only as the internal
  *  ranking floor, e.g. `bootRung` of a doc with no boot entry.) */
@@ -74,9 +66,7 @@ export function bootRung(doc, subject) {
     }
     return r;
 }
-// ---------------------------------------------------------------------------
 // Parse / validate.
-// ---------------------------------------------------------------------------
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
@@ -135,9 +125,7 @@ export function previewLine(doc) {
     const line = doc.whenAndWhyToRead.trim().replace(/\.+$/, '');
     return line === '' ? '' : `${line}.`;
 }
-// ---------------------------------------------------------------------------
 // Field coercion helpers (private).
-// ---------------------------------------------------------------------------
 function strField(v) {
     return typeof v === 'string' ? v : '';
 }
@@ -158,8 +146,8 @@ function parseGate(v) {
         : undefined;
 }
 /** Tolerant `surfaces` parse: a non-array yields `[]`; invalid entries are
- *  dropped (bad `on`, bad `at`, a read/memory-read/command entry left with
- *  neither `match` nor — read only — `match-frontmatter`). `match-frontmatter`
+ *  dropped (bad `on`, bad `at`, a read/memory-read/command/pre-command entry
+ *  left with neither `match` nor — read only — `match-frontmatter`). `match-frontmatter`
  *  on a non-read event is dropped from the entry, which survives iff it still
  *  carries a `match`; an invalid entry `gate` is dropped. Lint owns strict
  *  enforcement; the runtime parser maps over many docs and must never throw. */
@@ -180,7 +168,7 @@ function parseSurfaces(v) {
         const match = parseMatchGlobs(rec['match']);
         const matchFrontmatter = on === 'read' ? parseGate(rec['match-frontmatter']) : undefined;
         const gate = parseGate(rec['gate']);
-        if ((on === 'read' || on === 'memory-read' || on === 'command') &&
+        if ((on === 'read' || on === 'memory-read' || on === 'command' || on === 'pre-command') &&
             match === undefined &&
             matchFrontmatter === undefined) {
             continue;

package/dist/core/substrate/surface-match.d.ts

@@ -20,6 +20,21 @@ export declare function matchesReadEntry(entry: SurfaceEntry, doc: Pick<Substrat
 export declare function matchesMemoryReadEntry(entry: SurfaceEntry, routingAnchor: string, subject: NodeConfigSubject | null, name: string): boolean;
 /** Does a `command` entry fit the executed command string? */
 export declare function matchesCommandEntry(entry: SurfaceEntry, subject: NodeConfigSubject, command: string): boolean;
+/** Remove heredoc BODIES (the stdin data between `<<DELIM` and its closing
+ *  `DELIM` line) from a command before it is matched. The opening line is kept
+ *  — `crtr push final <<'EOF'` is still a real `push final` invocation — but the
+ *  body lines, which are data fed on stdin and never executed as commands, are
+ *  dropped. Without this a doc-writing command whose body merely MENTIONS a
+ *  matched invocation would have its whole call held. Post-execution `command`
+ *  delivery does not need this (a spurious late injection costs a paragraph);
+ *  a `pre-command` block costs the agent a turn, so it does. */
+export declare function stripHeredocs(command: string): string;
+/** Does a `pre-command` entry fit a command that is ABOUT to run? The same
+ *  glob machinery `command` uses — one matcher, one semantics — applied to the
+ *  command with its heredoc bodies stripped. Subshell parentheses, backticks,
+ *  and path-prefixed binaries stay unhandled: this is a guardrail against the
+ *  faithful-but-uninformed action, not an enforcement boundary. */
+export declare function matchesPreCommandEntry(entry: SurfaceEntry, subject: NodeConfigSubject, command: string): boolean;
 /** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
 export declare function readDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces' | 'path' | 'scope'>, subject: NodeConfigSubject, absReadFile: string, readFrontmatter: Record<string, unknown>): Rung;
 /** The doc's workspace-open rung. Presence of an entry is the match; callers
@@ -33,3 +48,7 @@ export declare function workspaceOpenRung(doc: Pick<SubstrateDoc, 'surfaces'>, s
 export declare function memoryReadDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, routingAnchor: string, subject: NodeConfigSubject | null, name: string): Rung;
 /** The doc's delivery rung for an executed command string. */
 export declare function commandDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, subject: NodeConfigSubject, command: string): Rung;
+/** The doc's delivery rung for a command about to run — the highest `at`
+ *  over the doc's matching `pre-command` entries, folded the same way as every
+ *  other event. */
+export declare function preCommandDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, subject: NodeConfigSubject, command: string): Rung;

package/dist/core/substrate/surface-match.js

@@ -276,12 +276,57 @@ export function matchesCommandEntry(entry, subject, command) {
         return false;
     return entry.match.some((g) => commandGlobMatches(g, command));
 }
-// ---------------------------------------------------------------------------
+const HEREDOC_OPEN = /<<(-?)\s*(["']?)([A-Za-z_][A-Za-z0-9_]*)\2/g;
+/** Remove heredoc BODIES (the stdin data between `<<DELIM` and its closing
+ *  `DELIM` line) from a command before it is matched. The opening line is kept
+ *  — `crtr push final <<'EOF'` is still a real `push final` invocation — but the
+ *  body lines, which are data fed on stdin and never executed as commands, are
+ *  dropped. Without this a doc-writing command whose body merely MENTIONS a
+ *  matched invocation would have its whole call held. Post-execution `command`
+ *  delivery does not need this (a spurious late injection costs a paragraph);
+ *  a `pre-command` block costs the agent a turn, so it does. */
+export function stripHeredocs(command) {
+    const lines = command.split('\n');
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        out.push(line);
+        i += 1;
+        // Every heredoc opened on this line, left to right; their bodies stack and
+        // are consumed in that order.
+        const delims = [];
+        HEREDOC_OPEN.lastIndex = 0;
+        let m;
+        while ((m = HEREDOC_OPEN.exec(line)) !== null)
+            delims.push({ name: m[3], dash: m[1] === '-' });
+        for (const d of delims) {
+            while (i < lines.length) {
+                // `<<-` strips leading TABS from the body and the closing delimiter.
+                const probe = d.dash ? lines[i].replace(/^\t+/, '') : lines[i];
+                i += 1;
+                if (probe === d.name)
+                    break; // closing delimiter line — drop it, stop
+            }
+        }
+    }
+    return out.join('\n');
+}
+/** Does a `pre-command` entry fit a command that is ABOUT to run? The same
+ *  glob machinery `command` uses — one matcher, one semantics — applied to the
+ *  command with its heredoc bodies stripped. Subshell parentheses, backticks,
+ *  and path-prefixed binaries stay unhandled: this is a guardrail against the
+ *  faithful-but-uninformed action, not an enforcement boundary. */
+export function matchesPreCommandEntry(entry, subject, command) {
+    if (entry.on !== 'pre-command' || entry.match === undefined || !surfaceEntryGatePasses(entry, subject))
+        return false;
+    const stripped = stripHeredocs(command);
+    return entry.match.some((g) => commandGlobMatches(g, stripped));
+}
 // Per-doc rung folds — a doc's delivery rung for one event occurrence is the
 // highest `at` over its matching entries of that event, `none` when none
 // match (entries OR together; `none` is the internal "does not deliver"
 // floor, never an authored rung).
-// ---------------------------------------------------------------------------
 /** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
 export function readDeliveryRung(doc, subject, absReadFile, readFrontmatter) {
     let r = 'none';
@@ -331,3 +376,16 @@ export function commandDeliveryRung(doc, subject, command) {
     }
     return r;
 }
+/** The doc's delivery rung for a command about to run — the highest `at`
+ *  over the doc's matching `pre-command` entries, folded the same way as every
+ *  other event. */
+export function preCommandDeliveryRung(doc, subject, command) {
+    let r = 'none';
+    for (const e of doc.surfaces) {
+        if (!matchesPreCommandEntry(e, subject, command))
+            continue;
+        if (rungRank(e.at) > rungRank(r))
+            r = e.at;
+    }
+    return r;
+}

package/dist/core/termrender/display.js

@@ -1,3 +1,4 @@
+import { envNodeId } from '../../shared/env.js';
 import { spawnSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { breakPane, closePane, currentTmux, paneOfNode, splitWindow, } from '../runtime/placement-tmux.js';
@@ -6,7 +7,7 @@ function targetPane() {
     const callerPane = process.env['TMUX_PANE'];
     if (callerPane !== undefined && callerPane !== '')
         return callerPane;
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId !== undefined && nodeId !== '') {
         const viewerPane = paneOfNode(nodeId);
         if (viewerPane !== null)

package/dist/core/tui/page-host.d.ts

@@ -1,6 +1,6 @@
-import { ProcessTerminal, type Component, type Focusable, type TUI } from "@earendil-works/pi-tui";
-import { readRawScopeConfig } from "../config.js";
-import { type BindingId, type BindingResolution } from "../keybindings/index.js";
+import { ProcessTerminal, type Component, type Focusable, type TUI } from '@earendil-works/pi-tui';
+import { readRawScopeConfig } from '../config.js';
+import { type BindingId, type BindingResolution } from '../keybindings/index.js';
 /** A full-screen page: a focusable TUI component that cleans up after itself. */
 export type TuiPageSurface = Component & Focusable & {
     dispose(): void;

package/dist/core/tui/page-host.js

@@ -6,10 +6,10 @@
 // restore path that survives an exception, a signal, and process exit. Anything
 // a single page needs beyond that — pi's model runtime, a canvas client — the
 // page's own runner builds and closes over before calling in here.
-import { ProcessTerminal, TuiMainScreen, } from "@earendil-works/pi-tui";
-import { applyTheme } from "../../clients/attach/config.js";
-import { readRawScopeConfig } from "../config.js";
-import { resolveKeybindings, } from "../keybindings/index.js";
+import { ProcessTerminal, TuiMainScreen, } from '@earendil-works/pi-tui';
+import { applyTheme } from '../../clients/attach/config.js';
+import { readRawScopeConfig } from '../config.js';
+import { resolveKeybindings, } from '../keybindings/index.js';
 /** Mount one page as the TUI's only child and resolve when it closes.
  *
  *  `interceptCancel` is a process-level escape hatch for surfaces that must be

package/dist/core/tui/panel.js

@@ -1,5 +1,5 @@
-import { getMarkdownTheme, getSelectListTheme, getSettingsListTheme, } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, getSelectListTheme, getSettingsListTheme, } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
 const ansiGreen = (text) => `\x1b[32m${text}\x1b[39m`;
 const ansiYellow = (text) => `\x1b[33m${text}\x1b[39m`;
 export const theme = {
@@ -95,7 +95,7 @@ export function framed(lines, width) {
 export function fitTail(lines, budget) {
     return budget >= lines.length ? lines : lines.slice(lines.length - budget);
 }
-// --- Page chrome shared by the settings shell and the setup wizard ----------
+// Page chrome shared by the settings shell and the setup wizard
 /** Rows the page frame spends on its own title, rules and footer. */
 export const PAGE_CHROME_ROWS = 4;
 /** Title row with right-aligned scope metadata, a rule under it, the body

package/dist/core/wake.js

@@ -10,9 +10,7 @@
 // design §5.3 + D7 (engine evaluates UTC; the surface bakes the IANA zone
 // into a calendar `recur`). Tick-scale only — no sub-second precision.
 import { CronExpressionParser } from 'cron-parser';
-// ---------------------------------------------------------------------------
 // Constants
-// ---------------------------------------------------------------------------
 /** Cadence floor: reject any interval / cron min-spacing below this (AC-N4). */
 export const CADENCE_FLOOR_MS = 60_000;
 const DURATION_UNIT_MS = {
@@ -38,9 +36,7 @@ const CRON_ALIASES = {
     '@midnight': '0 0 * * *',
     '@hourly': '0 * * * *',
 };
-// ---------------------------------------------------------------------------
 // Internal helpers
-// ---------------------------------------------------------------------------
 function whenError(code, message, received) {
     return { error: { code, message, received } };
 }
@@ -127,9 +123,7 @@ function classifyIso(s) {
         return { zoned: true };
     return null; // trailing garbage -> not a valid ISO instant
 }
-// ---------------------------------------------------------------------------
 // parseWhen — resolve a one-shot <when> to an absolute UTC instant
-// ---------------------------------------------------------------------------
 /**
  * Resolve a `<when>` to a single UTC `fireAt`:
  *   - relative duration (`90s`, `1h30m`)        -> now + Σ
@@ -182,9 +176,7 @@ export function parseWhen(when, opts) {
     }
     return whenError('bad_when', `Could not parse "${received}". Use a duration ("5m", "1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00").`, received);
 }
-// ---------------------------------------------------------------------------
 // parseCadence — resolve --every to a stored recur + first fire
-// ---------------------------------------------------------------------------
 /**
  * Resolve a `<cadence>` (the `--every` value) to a stored `recur` JSON string
  * plus the first `fireAt`:
@@ -240,9 +232,7 @@ export function parseCadence(every, opts) {
         firstFireAt,
     };
 }
-// ---------------------------------------------------------------------------
 // cadenceDisplay — a recur JSON rendered for humans + agents
-// ---------------------------------------------------------------------------
 /**
  * Render a stored `recur` JSON as a compact, human-readable cadence:
  *   - {"every":"6h"}                         -> `every 6h`
@@ -270,9 +260,7 @@ export function cadenceDisplay(recur) {
     }
     return 'none';
 }
-// ---------------------------------------------------------------------------
 // nextSlotAfter — the coalescing primitive (daemon advance)
-// ---------------------------------------------------------------------------
 /**
  * Earliest occurrence of `recur` strictly greater than `now`, as a UTC ISO
  * string. Anchors on `now` (not the stored `fire_at`), so it structurally

package/dist/core/worktree.js

@@ -357,9 +357,7 @@ export function closeManagedWorktree(nodeId) {
         return closeManagedWorktreeLocked(nodeId);
     return withRepositoryWorktreeLock(wt.repo_root, () => closeManagedWorktreeLocked(nodeId));
 }
-// ---------------------------------------------------------------------------
 // Push-final auto-drop of a clean, zero-commit managed worktree
-// ---------------------------------------------------------------------------
 /** Delete a source branch only while the ref that proved it already delivered
  *  is still at the exact inspected SHA. `containingRef` can be the recorded
  *  local base or that base's remote-tracking upstream. */

package/dist/daemon/__tests__/reconciler-signature.test.d.ts

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

package/dist/daemon/__tests__/reconciler-signature.test.js

@@ -0,0 +1,36 @@
+// Every reconciler in crtrd's tick loop conforms to one shape:
+// `run(now: number, ctx: TCtx): void | Promise<unknown>`. The call loop treats
+// every reconciler identically — a 1-arg or discard-shaped signature is exactly
+// the drift this test catches (a runtime arity check; a compile-time
+// `satisfies` pass over the same five/seven classes would need a shared
+// Reconciler<TCtx> interface that adds no real safety this doesn't already
+// give, since `tsc --noEmit` already fails hard on a wrong-shaped ctx object
+// at each call site in crtrd.ts).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { BrokerSupervisionReconciler } from '../reconcilers/broker-supervision.js';
+import { ControllerDeathReconciler, DormantInboxReconciler } from '../reconcilers/dormant-inbox.js';
+import { CronLaneReconciler } from '../reconcilers/cron-lane.js';
+import { HumanDeliveryLaneReconciler } from '../reconcilers/human-delivery-lane.js';
+import { PendingReviewSubmitReconciler } from '../reconcilers/pending-review-submit.js';
+import { StorageMaintenanceReconciler } from '../reconcilers/storage-maintenance.js';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const RECONCILERS = [
+    ['BrokerSupervisionReconciler', BrokerSupervisionReconciler],
+    ['ControllerDeathReconciler', ControllerDeathReconciler],
+    ['DormantInboxReconciler', DormantInboxReconciler],
+    ['CronLaneReconciler', CronLaneReconciler],
+    ['HumanDeliveryLaneReconciler', HumanDeliveryLaneReconciler],
+    ['PendingReviewSubmitReconciler', PendingReviewSubmitReconciler],
+    ['StorageMaintenanceReconciler', StorageMaintenanceReconciler],
+];
+test('every crtrd reconciler declares run(now, ctx) — arity 2', () => {
+    const offenders = [];
+    for (const [name, Ctor] of RECONCILERS) {
+        const instance = new Ctor();
+        if (instance.run.length !== 2) {
+            offenders.push(`${name}.run has arity ${instance.run.length}, expected 2`);
+        }
+    }
+    assert.deepEqual(offenders, [], `reconciler(s) not shaped run(now, ctx):\n${offenders.join('\n')}`);
+});

package/dist/daemon/api/__tests__/seam/api-server.test.js

@@ -72,9 +72,7 @@ function countLines(path) {
         return 0;
     }
 }
-// ---------------------------------------------------------------------------
 // A1 — /healthz ok + socket mode 0600
-// ---------------------------------------------------------------------------
 test('A1: /healthz is ok and the unix socket is bound mode 0600', async () => {
     const health = await client.healthz();
     assert.equal(health.ok, true, 'GET /healthz → { ok: true }');
@@ -86,10 +84,8 @@ test('attention counts reads only the requested node slice', async () => {
     const result = await client.attentionCounts([root, 'unknown-node']);
     assert.deepEqual(result.counts, { [root]: 0, 'unknown-node': 0 });
 });
-// ---------------------------------------------------------------------------
 // A2 — POST /nodes → live node (row + broker + recorded pid), GET shows active,
 //      view.sock exists
-// ---------------------------------------------------------------------------
 test('A2: POST /nodes boots a live broker; GET /nodes/{id} shows active + live pid + view.sock', async () => {
     const root = h.spawnRoot('a2 root'); // in-process resident, pi_pid = harness pid (alive)
     const detail = await client.createNode({ kind: 'developer', parent: root, prompt: 'a2 worker' });
@@ -103,31 +99,27 @@ test('A2: POST /nodes boots a live broker; GET /nodes/{id} shows active + live p
     assert.ok(meta?.pi_pid != null && isPidAlive(meta.pi_pid), 'row records a live broker pid');
     assert.ok(existsSync(h.brokerSock(id)), 'view.sock exists for the live broker');
 });
-// ---------------------------------------------------------------------------
 // A3 — POST .../messages appends inbox.jsonl; POST .../reports {tier:'final'}
 //      writes the report, notifies subscribers, transitions the row
-// ---------------------------------------------------------------------------
 test('A3: messages append inbox.jsonl; final report writes + notifies subscriber + transitions row', async () => {
     const A = h.spawnRoot('a3 mgr');
     const B = (await client.createNode({ kind: 'developer', parent: A, prompt: 'a3 worker' })).node_id;
     await h.awaitBoot(B);
-    // --- messages append inbox.jsonl (raw line count is cursor-independent) ---
+    // messages append inbox.jsonl (raw line count is cursor-independent)
     const inboxFile = inboxPath(B);
     const before = countLines(inboxFile);
     const msg = await client.sendMessage(B, { body: 'hello inbox' });
     assert.equal(msg.delivered, true, 'message reports delivered');
     await h.waitFor(() => countLines(inboxFile) > before, { label: 'inbox.jsonl appended', timeoutMs: 10_000 });
-    // --- final report: file written + subscriber notified + row transitioned ---
+    // final report: file written + subscriber notified + row transitioned
     const res = await client.pushReport(B, { tier: 'final', body: 'a3 done result' });
     assert.ok(existsSync(res.report_path), `report file written at ${res.report_path}`);
     assert.ok(res.notified.includes(A), `final push notifies the spawn-subscribed manager A (notified=${JSON.stringify(res.notified)})`);
     assert.deepEqual(res.transitioned, { from: 'active', to: 'done' }, 'row transitioned active→done');
     assert.equal(h.node(B)?.status, 'done', 'row status is done after final');
 });
-// ---------------------------------------------------------------------------
 // A4 — WS attach reconstructs the same settled broker snapshot as a direct
 //      ViewSocketClient; ?revive=0 on a dormant node → 409 without launching a broker
-// ---------------------------------------------------------------------------
 test('A4a: WS attach welcome.snapshot is byte-identical to a direct ViewSocketClient snapshot', async () => {
     const root = h.spawnRoot('a4 root');
     const id = (await client.createNode({ kind: 'developer', parent: root, prompt: 'a4 worker' })).node_id;
@@ -229,9 +221,7 @@ test('A4b: ?revive=0 on a dormant node refuses 409 without launching a broker',
     assert.equal(h.bootCount(dorm), bootsBefore, 'no broker was launched (boot count unchanged)');
     assert.equal(h.node(dorm)?.pi_pid ?? null, null, 'no pid recorded — the node stayed dormant');
 });
-// ---------------------------------------------------------------------------
 // A5 — POST .../close tears down the broker + cascades per edges
-// ---------------------------------------------------------------------------
 test('A5: close tears down the target broker and cascades its subtree, leaving the ancestor untouched', async () => {
     const A = h.spawnRoot('a5 root');
     const B = (await client.createNode({ kind: 'developer', parent: A, prompt: 'a5 mid' })).node_id;
@@ -259,12 +249,10 @@ test('A5: close tears down the target broker and cascades its subtree, leaving t
     assert.equal(h.node(C)?.status, 'canceled', 'cascaded child C is canceled');
     assert.equal(h.node(A)?.status, 'active', 'ancestor A is untouched (still active)');
 });
-// ---------------------------------------------------------------------------
 // A6 — PUT /profiles/{name} idempotent; PUT /model-auth/{provider} writes
 //      auth.json (sandboxed PI_CODING_AGENT_DIR).
 //      HONEST PROXY: reload fan is asserted as the file write only (the mtime
 //      watcher lives in runDaemon, not createApiServer).
-// ---------------------------------------------------------------------------
 test('A6a: PUT /profiles/{name} is idempotent (twice → same profile id)', async () => {
     // Profiles write under `join(homedir(), '.crouter', 'profiles')` — homedir()
     // honors HOME, which the harness only overrides for SUBPROCESS children. For
@@ -312,11 +300,9 @@ test('A6b: PUT /model-auth/{provider} writes auth.json (reload fan asserted as f
         rmSync(piDir, { recursive: true, force: true });
     }
 });
-// ---------------------------------------------------------------------------
 // /v1/files/peek — host file read (capped → `truncated`), plus the
 // usage/relative/404 error mapping. Covers the handler's non-trivial
 // branching (usage / notFound / directory / truncation boundary).
-// ---------------------------------------------------------------------------
 const PEEK_CAP = 512 * 1024; // MUST mirror PEEK_MAX_BYTES in handlers/files.ts
 test('files/peek: 200 returns full content, untruncated, for a small file', async () => {
     const dir = mkdtempSync(join(tmpdir(), 'crtr-peek-'));

package/dist/daemon/api/__tests__/seam/b10-attach-modelauth.test.js

@@ -60,10 +60,8 @@ after(async () => {
     await server?.close();
     await h?.dispose();
 });
-// ---------------------------------------------------------------------------
 // B2 (attach hybrid) — ensureAttach revives a DORMANT node server-side; the
 // direct view.sock snapshot streams; DETACH LEAVES THE BROKER RUNNING.
-// ---------------------------------------------------------------------------
 test('B2-attach: ensureAttach revives a dormant node, snapshot streams, detach leaves the broker running', async () => {
     const root = h.spawnRoot('b10 attach root'); // in-process resident (alive pid)
     const id = (await client.createNode({ kind: 'developer', parent: root, prompt: 'b10 attach worker' })).node_id;
@@ -87,7 +85,7 @@ test('B2-attach: ensureAttach revives a dormant node, snapshot streams, detach l
     // reviveNode's double-launch guard reads the fleet entry, so attaching in the
     // window between the kill and the child-exit delivery is correctly a no-op.
     await h.awaitFleetExit(id);
-    // --- ensureAttach (the exact call viewer.ts makes) revives it SERVER-SIDE ---
+    // ensureAttach (the exact call viewer.ts makes) revives it SERVER-SIDE
     const res = await client.ensureAttach(id, { resume: true, revive: true });
     assert.equal(res.node_id, id, 'ensureAttach echoes the node id');
     assert.equal(res.revived, true, 'server launched a fresh broker (revived=true) for the dormant node');
@@ -101,7 +99,7 @@ test('B2-attach: ensureAttach revives a dormant node, snapshot streams, detach l
     //     hop viewer.ts keeps local). ---
     const attached = await kit.attach(id, 'observer', 'b10-attach-observer');
     assert.ok(attached.welcome.snapshot != null, 'welcome frame carries a reconstructed snapshot (snapshot streams)');
-    // --- DETACH LEAVES THE BROKER RUNNING (reap-on-detach removed this batch) ---
+    // DETACH LEAVES THE BROKER RUNNING (reap-on-detach removed this batch)
     attached.close();
     // Give any (now-absent) reap path a beat to have fired, then assert the broker
     // is unmistakably still alive.
@@ -111,11 +109,9 @@ test('B2-attach: ensureAttach revives a dormant node, snapshot streams, detach l
     assert.ok(isPidAlive(afterDetachPid), 'detach left the broker RUNNING (no reap-on-detach)');
     assert.notEqual(h.node(id)?.status, 'done', 'detach did not finalize the node');
 });
-// ---------------------------------------------------------------------------
 // B2 (model-auth) — installCredential writes auth.json (content asserted), the
 // reload FAN acks against a live broker, and the API path is byte-identical to
 // the old direct-write path.
-// ---------------------------------------------------------------------------
 test('B2-modelauth: installCredential writes auth.json and the reload fan acks a live broker', async () => {
     // Sandbox pi's credential store so the write lands in a throwaway dir, never the
     // developer's real ~/.pi/agent/auth.json. authPath() honors PI_CODING_AGENT_DIR.
@@ -128,7 +124,7 @@ test('B2-modelauth: installCredential writes auth.json and the reload fan acks a
         const root = h.spawnRoot('b10 modelauth root');
         liveId = (await client.createNode({ kind: 'developer', parent: root, prompt: 'b10 fan target' })).node_id;
         await h.awaitBoot(liveId);
-        // --- installCredential (the exact call setup.ts makes) writes auth.json ---
+        // installCredential (the exact call setup.ts makes) writes auth.json
         const res = await client.installCredential('anthropic', { kind: 'api_key', api_key: 'sk-b10-test-key' });
         assert.equal(res.installed, true, 'credential reports installed');
         assert.equal(res.managed, false, 'api_key install is not a managed-pool account');
@@ -150,14 +146,12 @@ test('B2-modelauth: installCredential writes auth.json and the reload fan acks a
         rmSync(apiDir, { recursive: true, force: true });
     }
 });
-// ---------------------------------------------------------------------------
 // B2 (model-auth, oauth) — non-managed OAuth install must PRESERVE
 // provider-specific extra credential fields (e.g. github-copilot's
 // `enterpriseUrl`, load-bearing for enterprise routing/refresh). The client
 // forwards non-standard keys through `extra` and the handler re-spreads them.
 // Regression guard for review M1 (a dropped enterpriseUrl breaks
 // GitHub-Enterprise Copilot).
-// ---------------------------------------------------------------------------
 test('B2-modelauth-oauth: installCredential(oauth) preserves extra fields (enterpriseUrl)', async () => {
     const savedPiDir = process.env['PI_CODING_AGENT_DIR'];
     const apiDir = mkdtempSync(join(tmpdir(), 'crtr-b10-oauth-api-'));
@@ -192,10 +186,8 @@ test('B2-modelauth-oauth: installCredential(oauth) preserves extra fields (enter
         rmSync(apiDir, { recursive: true, force: true });
     }
 });
-// ---------------------------------------------------------------------------
 // Credential truth/removal — GET exposes only connection state and DELETE
 // clears exactly its provider's durable store.
-// ---------------------------------------------------------------------------
 test('B2-modelauth-status: list is sanitized and delete clears only the selected provider', async () => {
     const savedPiDir = process.env['PI_CODING_AGENT_DIR'];
     const apiDir = mkdtempSync(join(tmpdir(), 'crtr-b10-status-'));

package/dist/daemon/api/__tests__/seam/leaf-api-parity.test.js

@@ -127,12 +127,10 @@ after(async () => {
     else
         process.env['CRTR_NODE_ID'] = savedNodeId;
 });
-// ---------------------------------------------------------------------------
 // push final — the report write, the subscriber fan, and the lifecycle
 // transition all happen server-side, driven through the real push.ts leaf. A
 // parent spawns a child (so the parent subscribes to the child); the child
 // pushes.
-// ---------------------------------------------------------------------------
 test('`crtr push final` from a child writes a report, notifies the subscribed parent, AND transitions the child row active→done', async () => {
     const parent = h.spawnRoot('leaf-api-parity final parent');
     const child = (await client.createNode({ kind: 'developer', parent, prompt: 'final worker' })).node_id;
@@ -153,11 +151,9 @@ test('`crtr push final` from a child writes a report, notifies the subscribed pa
     // — the re-homed guard only engages for a managed-worktree owner.
     assert.equal('worktree_auto_dropped' in out, false, 'a normal node final is unaffected by the worktree guard');
 });
-// ---------------------------------------------------------------------------
 // Re-homed worktree guard/auto-drop (ambiguity-2 follow-up): the pre-B-5 CLI
 // `push final` worktree behavior now lives SERVER-side in handlers/reports.ts,
 // exercised end-to-end through the real push.ts leaf.
-// ---------------------------------------------------------------------------
 test('re-homed guard: `crtr push final` on a node with a managed worktree holding REAL unlanded commits blocks with the parity open_managed_worktree InputError (round-tripped from the server), and does NOT finalize', async () => {
     const repo = initRepo();
     try {
@@ -255,13 +251,11 @@ test('`crtr push final` keeps an absent managed worktree open when its branch is
         rmSync(repo, { recursive: true, force: true });
     }
 });
-// ---------------------------------------------------------------------------
 // `node worktree close` error parity — the SPECIFIC WorktreeError code + its
 // `next` remediation round-trip verbatim through the server → ApiError → the
 // bespoke CLI mapper in node-worktree.ts, instead of collapsing to a generic
 // status bucket. That mapper exists for exactly this contract, so this is the
 // load-bearing regression to lock.
-// ---------------------------------------------------------------------------
 test('`crtr node worktree close` on a node with NO managed worktree round-trips the specific `no_managed_worktree` code + its exact next-hint (not a generic status bucket)', async () => {
     const id = 'wt-close-none';
     createNode({ node_id: id, name: id, created: new Date().toISOString(), cwd: process.cwd(), kind: 'developer', mode: 'base', lifecycle: 'terminal', status: 'active' });

package/dist/daemon/api/handlers/attach.js

@@ -5,7 +5,8 @@
 // is bridge.ts's (A-8) — NOT routed here.
 //
 // `{id}` is the target node being attached to.
-import { getNode, reviveNode } from '../../../index.js';
+import { getNode } from '../../../core/canvas/canvas.js';
+import { reviveNode } from '../../../core/runtime/revive.js';
 import { viewSocketPath } from '../../../core/canvas/paths.js';
 import { waitForBrokerViewSocket } from '../../../core/runtime/placement-tmux.js';
 import { notFound, usage } from '../../../core/errors.js';

package/dist/daemon/api/handlers/broker-ops.js

@@ -6,7 +6,7 @@ import { editorLabel } from '../../../core/canvas/labels.js';
 import { assembleNodeSubject } from '../../../core/substrate/subject.js';
 import { withCanvasWrite } from '../../../core/canvas/db.js';
 import { notFound, usage } from '../../../core/errors.js';
-import { readCursor, readInboxSince, writeCursor } from '../../../core/feed/inbox.js';
+import { hasUnseenWakeMail, readCursor, readInboxSince, writeCursor } from '../../../core/feed/inbox.js';
 import { clearYieldMessage } from '../../../core/runtime/kickoff.js';
 import { transition } from '../../../core/runtime/lifecycle.js';
 import { focusOf, tearDownNode } from '../../../core/runtime/placement.js';
@@ -224,9 +224,6 @@ function handleSessionBound(ctx) {
     });
     return { status: 200, body: result };
 }
-function hasUnseenNonDeferredInbox(nodeId) {
-    return readInboxSince(nodeId, readCursor(nodeId)).some((entry) => entry.tier !== 'deferred');
-}
 /** Commit the complete broker-settlement policy while holding one canvas write
  * boundary. This handler intentionally never invokes the broker that called it:
  * the returned directive is the only Pi-side consequence. */
@@ -300,14 +297,14 @@ function settleBroker(nodeId, request) {
     if (decision.action === 'reprompt')
         return { action: 'reprompt', prompt: decision.message };
     if (decision.reason === 'finished') {
-        return hasUnseenNonDeferredInbox(nodeId) ? { action: 'stay_dormant' } : { action: 'shutdown' };
+        return hasUnseenWakeMail(nodeId) ? { action: 'stay_dormant' } : { action: 'shutdown' };
     }
     if (decision.reason !== 'awaiting' && decision.reason !== 'scheduled') {
         return { action: 'stay_dormant' };
     }
     if (focusOf(nodeId) !== null
         || hasAttachedBrokerViewers(nodeId)
-        || hasUnseenNonDeferredInbox(nodeId))
+        || hasUnseenWakeMail(nodeId))
         return { action: 'stay_dormant' };
     transition(nodeId, 'release');
     return { action: 'shutdown' };