@north-light/crouter 0.3.176 → 0.3.178

package/dist/core/human/claim.js

@@ -1,7 +1,8 @@
 import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
-import { claimPath, deckPath, readJson, responsePath, reviewPath } from './convention.js';
+import { claimPath, deckPath, responsePath, reviewPath } from './convention.js';
+import { readJsonOrNull } from '../fs-utils.js';
 import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 const REMOTE_STALE_MS = 30_000;
 function parseClaim(raw) {
@@ -12,7 +13,7 @@ function parseClaim(raw) {
         return null;
     return { token: claim.token, host: claim.host, pid: claim.pid, claimedAt: claim.claimedAt, heartbeatAt: claim.heartbeatAt, ...(typeof claim.tmuxClient === 'string' ? { tmuxClient: claim.tmuxClient } : {}) };
 }
-export function readTicketClaim(dir) { return parseClaim(readJson(claimPath(dir))); }
+export function readTicketClaim(dir) { return parseClaim(readJsonOrNull(claimPath(dir))); }
 function isLiveLocalPid(pid) { try {
     process.kill(pid, 0);
     return true;

package/dist/core/human/convention.d.ts

@@ -14,7 +14,6 @@ export declare function stampCanvasNode(deck: Deck): void;
 export declare function atomicWriteJson(path: string, value: unknown): void;
 /** Publish one immutable JSON record without replacing an existing winner. */
 export declare function publishJsonExclusive(path: string, value: unknown): boolean;
-export declare function readJson<T>(path: string): T | null;
 export declare function writeResponse(dir: string, responses: InteractionResponse[], completedAt: string, deck?: Deck): string;
 export declare function writeProgress(dir: string, responses: InteractionResponse[]): void;
 export declare function clearProgress(dir: string): void;

package/dist/core/human/convention.js

@@ -1,4 +1,4 @@
-import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { buildSummary } from './summary.js';
 export function deckPath(dir) { return `${dir}/deck.json`; }
@@ -53,14 +53,6 @@ export function publishJsonExclusive(path, value) {
         unlinkSync(tmp);
     }
 }
-export function readJson(path) {
-    try {
-        return JSON.parse(readFileSync(path, 'utf8'));
-    }
-    catch {
-        return null;
-    }
-}
 export function writeResponse(dir, responses, completedAt, deck) {
     const summary = deck === undefined ? '' : buildSummary(deck, responses);
     atomicWriteJson(responsePath(dir), { schema: 'humanloop.response/v2', kind: 'deck', responses, summary, completedAt });

package/dist/core/human/scan.js

@@ -1,16 +1,17 @@
 import { readdirSync, statSync } from 'node:fs';
 import { basename, join } from 'node:path';
-import { claimPath, deckPath, isResolved, readJson, reviewPath } from './convention.js';
+import { claimPath, deckPath, isResolved, reviewPath } from './convention.js';
+import { readJsonOrNull } from '../fs-utils.js';
 import { validateDeck, validateReviewDescriptor } from './deck-schema.js';
 import { ticketsRoot } from './root.js';
 function claimSummary(dir) {
-    const claim = readJson(claimPath(dir));
+    const claim = readJsonOrNull(claimPath(dir));
     if (claim === null || typeof claim.host !== 'string' || typeof claim.claimedAt !== 'string' || typeof claim.heartbeatAt !== 'string')
         return undefined;
     return { owner: claim.host, claimedAt: claim.claimedAt, heartbeatAt: claim.heartbeatAt };
 }
 function deckSummary(dir, id) {
-    const raw = readJson(deckPath(dir));
+    const raw = readJsonOrNull(deckPath(dir));
     if (raw === null)
         return null;
     let deck;
@@ -35,7 +36,7 @@ function deckSummary(dir, id) {
     return { dir, id, kind: 'deck', title: deck.title, subtitle: first.subtitle, interactionKind: first.kind, interactionCount: deck.interactions.length, source: deck.source ?? {}, blockedSince, claim: claimSummary(dir) };
 }
 function reviewSummary(dir, id) {
-    const raw = readJson(reviewPath(dir));
+    const raw = readJsonOrNull(reviewPath(dir));
     if (raw === null)
         return null;
     let review;

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

@@ -27,7 +27,7 @@ export declare function listProfiles(): ProfileEntry[];
  *  actually-enumerated dirs, never a blind join), then a unique manifest
  *  `name` match. Ambiguous names fail listing every matching id; no match
  *  fails naming `profile list`/`profile new` as recovery. This is the ONLY
- *  function every command leaf and future runtime consumer (Phase 5/6) should
+ *  function every command leaf and runtime consumer should
  *  call to turn a `<profile>` operand or `CRTR_PROFILE_ID` into a concrete,
  *  safe profile id. */
 export declare function loadProfileManifest(profileIdOrName: string): ProfileEntry;

package/dist/core/profiles/manifest.js

@@ -147,7 +147,7 @@ export function listProfiles() {
  *  actually-enumerated dirs, never a blind join), then a unique manifest
  *  `name` match. Ambiguous names fail listing every matching id; no match
  *  fails naming `profile list`/`profile new` as recovery. This is the ONLY
- *  function every command leaf and future runtime consumer (Phase 5/6) should
+ *  function every command leaf and runtime consumer should
  *  call to turn a `<profile>` operand or `CRTR_PROFILE_ID` into a concrete,
  *  safe profile id. */
 export function loadProfileManifest(profileIdOrName) {

package/dist/core/review/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Internal review/comment/error vocabulary and constants.
- * Phase 4 implementation: daemon-owned review lifecycle and comment authority.
+ * Backs the daemon-owned review lifecycle and comment authority.
  * This module declares no HTTP status, DTOs, or I/O.
  */
 import type { FeedbackComment } from '../human/types.js';

package/dist/core/review/types.js

@@ -1,6 +1,6 @@
 /**
  * Internal review/comment/error vocabulary and constants.
- * Phase 4 implementation: daemon-owned review lifecycle and comment authority.
+ * Backs the daemon-owned review lifecycle and comment authority.
  * This module declares no HTTP status, DTOs, or I/O.
  */
 /** Limits */

package/dist/core/runtime/broker/frame-dispatch.js

@@ -620,8 +620,8 @@ export function createFrameDispatchContext(deps) {
         }
     };
     // -------------------------------------------------------------------------
-    // Command-op helpers (T3, §2.3). The write guard is hoisted here (it was
-    // inlined twice) and reused by all mutating ops; the ack/error replies
+    // Command-op helpers. The write guard is hoisted here and reused by all
+    // mutating ops; the ack/error replies
     // and a few resolvers keep the per-op cases one-liners.
     // -------------------------------------------------------------------------
     /** Reject a read-only client for a mutating op. The decision reads this
@@ -841,7 +841,7 @@ export function createFrameDispatchContext(deps) {
     };
     const handleEngineControlFrame = (client, frame) => {
         switch (frame.type) {
-            // --- extended engine-command ops (T3, §1.2 floor set) ------------------
+            // --- extended engine-command ops -------------------------------------
             case 'set_model': {
                 if (notWritable(client, 'set the model'))
                     break;
@@ -1070,7 +1070,7 @@ export function createFrameDispatchContext(deps) {
                 // engine, so it is not a controller-gated op. Terminal observer
                 // connections use it to populate the command palette.
                 // The merged command list rides in ack.detail as JSON (the foundation's
-                // AckFrame.detail field) — the viewer (T6) JSON.parses it when for ===
+                // AckFrame.detail field) — the viewer JSON.parses it when for ===
                 // 'get_commands'. Keeps every command op a uniform ack reply.
                 try {
                     ackTo(client, 'get_commands', true, JSON.stringify(buildCommandList(currentSession())));

package/dist/core/runtime/broker-cli.js

@@ -1,6 +1,6 @@
 // broker-cli.ts — the headless broker's dedicated detached entry (plan T4 /
 // decision §1.13). Spawned directly via `spawn(execPath, [thisFile, nodeId], …)`
-// by HeadlessBrokerHost.launch (T6) — NEVER routed through src/cli.ts, which
+// by HeadlessBrokerHost.launch — NEVER routed through src/cli.ts, which
 // would run the whole bootstrap chain (auto-update / scope-init / slash-template
 // rewrite) on every broker boot. Mirrors src/daemon/crtrd-cli.ts: parse the one
 // positional arg and hand off; keep this file a thin shim.

package/dist/core/runtime/broker-protocol.d.ts

@@ -47,7 +47,7 @@ export interface BrokerSnapshot {
         title: string | undefined;
     };
     /** Broker-owned summaries keyed by the first tool-call id in each group.
-     * Structured objects with bullets, nodesSpawned, and filesEdited.
+     * Structured objects with bullets, nodesSpawned, and filesDeleted.
      * Optional so snapshots from an older live runtime remain readable. */
     toolGroupSummaries?: Record<string, ToolGroupSummary>;
     /** The broker-selected normal activity label for the current turn. Optional so
@@ -68,7 +68,7 @@ export interface HelloFrame {
     };
 }
 /** Drive the engine — writable (`controller`) clients only. Map 1:1 to session.prompt/steer/followUp/abort.
- *  `images` carries pasted/attached images to the engine (review M1): pi accepts
+ *  `images` carries pasted/attached images to the engine: pi accepts
  *  `prompt(text,{images})` / `steer(text,images)` / `followUp(text,images)` at
  *  0.78.1. The wire TYPE lives here; T3/T6 wire the runtime side. The BROKER read
  *  cap (`BROKER_READ_CAPS`) is sized to hold a resizeImage-bounded PNG's base64. */
@@ -612,15 +612,14 @@ export declare class FrameOverflowError extends Error {
 }
 /** Caps the CLIENT uses reading BROKER frames. The `welcome.snapshot` carries the
  *  full message history and can be many MiB, so these are generous. Covers
- *  realistic long sessions; snapshot CHUNKING is deferred (plan §1.1 known
- *  limitation, review m3 — the long-lived broker makes a big welcome a realistic,
- *  not pathological, trigger, but the fixed cap is accepted for Phase 4). */
+ *  realistic long sessions; snapshot CHUNKING is deferred — the long-lived
+ *  broker makes a big welcome a realistic, not pathological, trigger, but the
+ *  fixed cap is accepted. */
 export declare const CLIENT_READ_CAPS: FrameDecoderCaps;
-/** Caps the BROKER uses reading CLIENT frames. Plan §1.1 specified a tight
- *  4/16 MiB, but review M1 requires image-paste frames to fit: a resizeImage-
- *  bounded PNG's base64 is a few MiB and would clip a 4 MiB line cap. So these are
- *  RAISED above the plan's 4/16 to hold an image-bearing `prompt`/`steer`/
- *  `follow_up` frame (M1). Still bounded, so a malicious/buggy client→broker frame
+/** Caps the BROKER uses reading CLIENT frames. Sized so an image-paste frame
+ *  fits: a resizeImage-bounded PNG's base64 is a few MiB and would clip a
+ *  tighter 4 MiB line cap, so these hold an image-bearing `prompt`/`steer`/
+ *  `follow_up` frame. Still bounded, so a malicious/buggy client→broker frame
  *  is cap-and-dropped, never grow-to-OOM (C5). */
 export declare const BROKER_READ_CAPS: FrameDecoderCaps;
 /** Incremental newline-delimited JSON reader: feed raw socket chunks, get back

package/dist/core/runtime/broker-protocol.js

@@ -1,7 +1,7 @@
 // broker-protocol.ts — the client↔broker wire protocol for the headless node
 // Surface (design §5.2). Pure types + a newline-delimited JSON codec; no I/O, no
-// SDK construction. Consumed by the broker (src/core/runtime/broker.ts) and, in
-// Phase 4, by the `crtr surface attach` terminal client and crtrd's attach bridge.
+// SDK construction. Consumed by the broker (src/core/runtime/broker.ts), the
+// `crtr surface attach` terminal client, and crtrd's attach bridge.
 //
 // The transport is one unix socket per node (`nodeDir(id)/view.sock`) speaking
 // newline-delimited JSON frames. Live engine events are relayed VERBATIM — the
@@ -43,18 +43,17 @@ export class FrameOverflowError extends Error {
 }
 /** Caps the CLIENT uses reading BROKER frames. The `welcome.snapshot` carries the
  *  full message history and can be many MiB, so these are generous. Covers
- *  realistic long sessions; snapshot CHUNKING is deferred (plan §1.1 known
- *  limitation, review m3 — the long-lived broker makes a big welcome a realistic,
- *  not pathological, trigger, but the fixed cap is accepted for Phase 4). */
+ *  realistic long sessions; snapshot CHUNKING is deferred — the long-lived
+ *  broker makes a big welcome a realistic, not pathological, trigger, but the
+ *  fixed cap is accepted. */
 export const CLIENT_READ_CAPS = {
     maxLineBytes: 256 * 1024 * 1024,
     maxTotalBytes: 256 * 1024 * 1024,
 };
-/** Caps the BROKER uses reading CLIENT frames. Plan §1.1 specified a tight
- *  4/16 MiB, but review M1 requires image-paste frames to fit: a resizeImage-
- *  bounded PNG's base64 is a few MiB and would clip a 4 MiB line cap. So these are
- *  RAISED above the plan's 4/16 to hold an image-bearing `prompt`/`steer`/
- *  `follow_up` frame (M1). Still bounded, so a malicious/buggy client→broker frame
+/** Caps the BROKER uses reading CLIENT frames. Sized so an image-paste frame
+ *  fits: a resizeImage-bounded PNG's base64 is a few MiB and would clip a
+ *  tighter 4 MiB line cap, so these hold an image-bearing `prompt`/`steer`/
+ *  `follow_up` frame. Still bounded, so a malicious/buggy client→broker frame
  *  is cap-and-dropped, never grow-to-OOM (C5). */
 export const BROKER_READ_CAPS = {
     maxLineBytes: 24 * 1024 * 1024,

package/dist/core/runtime/broker-sdk.d.ts

@@ -15,7 +15,7 @@ export interface BrokerEngine {
     createAgentSessionServices: typeof createAgentSessionServices;
     createAgentSessionFromServices: typeof createAgentSessionFromServices;
     /**
-     * The session-replacement runtime factory (T3 new_session/switch_session/fork).
+     * The session-replacement runtime factory (new_session/switch_session/fork).
      * OPTIONAL: the real SDK (0.78.1) exposes it, so production gets full session
      * replacement; the `fake-engine` test fixture does NOT provide it, so the
      * broker degrades those three ops to an `error{engine_error}` reply rather than

package/dist/core/runtime/broker.js

@@ -1,4 +1,4 @@
-// broker.ts — the headless node broker (design §4, §5; plan T4).
+// broker.ts — the headless node broker (design §4, §5).
 //
 // One broker process per node — the SOLE host. It hosts ONE pi engine IN-PROCESS
 // via the SDK (createAgentSession), is the SOLE writer of the node's session
@@ -81,9 +81,9 @@ function formatExactModelSpec(model, thinkingLevel) {
     return base === null ? null : `${base}:${thinkingLevel === undefined || thinkingLevel === '' ? 'off' : thinkingLevel}`;
 }
 // ---------------------------------------------------------------------------
-// Tunables (T3 backpressure / T4 dialog anti-deadlock)
+// Tunables (backpressure / dialog anti-deadlock)
 // ---------------------------------------------------------------------------
-/** Broker-side default dialog timeout (C2 anti-deadlock, T4). When an extension
+/** Broker-side default dialog timeout (anti-deadlock). When an extension
  *  dialog is forwarded to every writable client, the broker ALWAYS arms a timeout
  *  (this default, or a shorter per-dialog `opts.timeout` if the extension passed
  *  one) so unanswered dialogs — including ones whose writable viewers all detach
@@ -167,7 +167,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     };
     // Defensive: any `crtr` child the engine/extensions spawn must inherit the
     // front-door recursion guard (see
-    // src/core/runtime/.crouter/memory/INDEX.md). The host (T6) also sets this;
+    // src/core/runtime/.crouter/memory/INDEX.md). The host also sets this;
     // setting it here keeps the broker self-sufficient.
     process.env[FRONT_DOOR_ENV] = '1';
     // A successful in-turn crtr command stamps this process id into its stop
@@ -203,7 +203,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     // 2–4. Build the engine session via the SERVICES path (C3) — see
     //       buildBrokerSession below. Register it so the FATAL exit path (M3) can
     //       dispose it and reap detached bash children.
-    // `session` + `services` are MUTABLE holders (T3 session-rebind): when the
+    // `session` + `services` are MUTABLE holders (session-rebind): when the
     // controller drives new_session/switch_session/fork, the AgentSessionRuntime
     // tears down the old session and builds the next one, then runs our rebind
     // callback which reassigns these. Every closure below (buildSnapshot,
@@ -411,7 +411,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         registry.forEachHelloed(sendWelcome);
     };
     // -------------------------------------------------------------------------
-    // The single exit helper (plan §0): dispose the engine, close + unlink the
+    // The single exit helper: dispose the engine, close + unlink the
     // socket, exit 0. Idempotent — every trigger converges here.
     // -------------------------------------------------------------------------
     const completeExit = (status) => {

package/dist/core/runtime/host.js

@@ -127,7 +127,7 @@ const BROKER_SIGKILL_GRACE_MS = 2_000;
 /** How often `pollUntilTreeDead` re-checks the process TREE. Short enough that
  *  the common/happy path (tree already dead) pays only a couple of ticks; the
  *  full grace ceilings above are reserved for the genuinely-wedged case,
- *  where the added latency is the whole point (crouter#98 review finding 3). */
+ *  where the added latency is the whole point. */
 const TEARDOWN_POLL_MS = 150;
 /** Poll `isAlive` every `TEARDOWN_POLL_MS` until it reports dead. If it is
  *  STILL alive once `timeoutMs` elapses, fire `onTimeout` exactly once (the
@@ -136,7 +136,7 @@ const TEARDOWN_POLL_MS = 150;
  *  up (an unkillable/D-state descendant is out of scope for this primitive).
  *
  *  Deliberately a recursive, NEVER-`.unref()`'d `setTimeout` rather than a
- *  fixed unref'd wait (crouter#98 review finding 3): most teardown callers
+ *  fixed unref'd wait: most teardown callers
  *  are short-lived CLI subprocesses (`node lifecycle close`, `canvas prune`)
  *  that would otherwise exit before an unref'd SIGKILL timer ever fires,
  *  silently skipping the last-resort rung. Polling (instead of a blind fixed
@@ -167,7 +167,7 @@ function pollUntil(isAlive, timeoutMs, onTimeout, hardCeilingMs = timeoutMs + 5_
  *  `captureTeardownSnapshot` identity map over that same list) — both taken
  *  ONCE by `teardown()` synchronously at its very top, before EITHER
  *  escalation path (connect-error or post-shutdown-frame) can run, and
- *  threaded through here unchanged (crouter#98 review finding 1). This
+ *  threaded through here unchanged. This
  *  function must NEVER re-walk the process tree itself: `launch()` spawns the
  *  broker `detached: true`, so
  *  signaling the broker's OWN group (the first thing `killProcessTreePids`
@@ -180,8 +180,8 @@ function pollUntil(isAlive, timeoutMs, onTimeout, hardCeilingMs = timeoutMs + 5_
  *  "lose" a still-alive detached descendant — e.g. the pi bash tool's shell
  *  child, itself `detached: true` and thus its own group leader, distinct
  *  from the broker's group, so a plain `kill(-brokerPid)` never reaches it
- *  either (crouton-labs/crouter#98). `identities` guards each signal against
- *  PID REUSE across the multi-second escalation window (review finding 3) —
+ *  either. `identities` guards each signal against
+ *  PID REUSE across the multi-second escalation window —
  *  see `killProcessTreePids`. `null` means the initial `captureTeardownSnapshot`
  *  probe itself failed (no baseline to compare against) — `killProcessTreePids`
  *  falls through to its normal unguarded signal path in that case, never
@@ -312,19 +312,19 @@ export const headlessBrokerHost = {
         // won't revive. On connect failure (broker dead/crashed/wedged) fall back
         // to escalateBrokerTeardown — a tree-wide SIGTERM now, a tree-wide SIGKILL
         // as the last resort — so no orphaned descendant of a dead/wedged broker
-        // survives the node (crouton-labs/crouter#98) — + unlink the stale socket.
+        // survives the node — + unlink the stale socket.
         //
         // Capture the broker pid ONCE, synchronously, right here — never re-query
         // `getNode(nodeId)` inside the async callbacks/timers below. Callers such
         // as placement.ts's `reapIfEmpty()` call `teardown()` then immediately
         // `deleteNode()` in the same tick; by the time an async callback fires the
         // row can already be gone, so a re-query would silently resolve to
-        // `undefined` and skip escalation entirely (crouter#98 review finding 2).
+        // `undefined` and skip escalation entirely.
         const node = getNode(nodeId);
         const pid = node?.pi_pid;
-        // Snapshot the full descendant TREE (crouter#98 review finding 1) — the
+        // Snapshot the full descendant TREE — the
         // root pid plus every transitive descendant — and a stable identity
-        // fingerprint for every pid in it (review finding 3), BOTH from ONE `ps`
+        // fingerprint for every pid in it, BOTH from ONE `ps`
         // table read (`captureTeardownSnapshot`, final review: closes the small
         // race between two separate probes), exactly ONCE, right here, while the
         // broker (if alive) still holds parentage over any detached descendant.
@@ -393,10 +393,10 @@ export const headlessBrokerHost = {
             // Bounded exit confirmation: a broker that connects fine but then HANGS
             // inside session.dispose() (disposeAndExit catches a throw, not a hang)
             // would leak the process holding the sole .jsonl writer — and any
-            // bash→test→app descendants it spawned along the way (crouter#98). Poll
+            // bash→test→app descendants it spawned along the way. Poll
             // the whole process TREE (not just the broker's own pid) for up to
-            // `BROKER_SHUTDOWN_GRACE_MS`, UNCONDITIONAL on the broker's own liveness
-            // (crouter#98 review finding 1): a broker that exits cleanly can still
+            // `BROKER_SHUTDOWN_GRACE_MS`, UNCONDITIONAL on the broker's own liveness:
+            // a broker that exits cleanly can still
             // leave a live descendant behind (dispose() partially failed, or never
             // reached a detached SDK child), which is exactly the shape this
             // closes. `pollUntil` is ref'd — not `.unref()`'d — so a short-lived
@@ -405,8 +405,8 @@ export const headlessBrokerHost = {
             // couple of poll ticks.
             //
             // Checks `isAnyPidAlive(tree)` against the FIXED pre-signal snapshot,
-            // NEVER a fresh `isProcessTreeAlive`/`descendantPids` re-walk (crouter#98
-            // review finding 1, fixed): the broker can exit at any point during this
+            // NEVER a fresh `isProcessTreeAlive`/`descendantPids` re-walk: the broker
+            // can exit at any point during this
             // grace window while leaving a detached descendant alive, and the
             // instant it does, the kernel reparents that descendant away from `pid`
             // — a re-walk-by-ppid would then find nothing and silently skip

package/dist/core/runtime/launch.d.ts

@@ -56,7 +56,7 @@ export declare function nextLadderModel(currentSpec: string, direction?: 1 | -1,
  *   3. Unset → pi default.
  *  Callers pass the authoritative lifecycle + hasManager (`parent !== null`) so
  *  a polymorph/flip rebuilds the recipe faithfully; `lifecycle` is returned
- *  as-given — it is no longer persona-frontmatter-derived. The two canvas
+ *  as-given, never derived from persona frontmatter. The two canvas
  *  extensions are always first; kind-declared extensions follow. */
 export declare function buildLaunchSpec(kind: string, mode: Mode, opts: {
     lifecycle: Lifecycle;

package/dist/core/runtime/launch.js

@@ -249,7 +249,7 @@ export function nextLadderModel(currentSpec, direction = 1, providers) {
  *   3. Unset → pi default.
  *  Callers pass the authoritative lifecycle + hasManager (`parent !== null`) so
  *  a polymorph/flip rebuilds the recipe faithfully; `lifecycle` is returned
- *  as-given — it is no longer persona-frontmatter-derived. The two canvas
+ *  as-given, never derived from persona frontmatter. The two canvas
  *  extensions are always first; kind-declared extensions follow. */
 export function buildLaunchSpec(kind, mode, opts) {
     const merged = readMergedLaunchConfig(opts.cwd ?? process.cwd(), opts.profileId !== undefined ? opts.profileId : (process.env['CRTR_PROFILE_ID'] || null));

package/dist/core/runtime/lifecycle.js

@@ -1,33 +1,28 @@
 // lifecycle.ts — the node status×intent state machine.
 //
 // ONE place defines which (status, intent) moves are legal and enacts them.
-// Before this, ~a dozen scattered setStatus()/setIntent() pairs across
-// reset/close/revive/feed/daemon/stophook/queue/promote re-derived the lifecycle
-// by hand, with no shared definition of "what move is legal." Here the legal
-// transition TABLE is the definition, and `transition(id, event)` is the single
-// writer of status+intent: it validates the from-status, then writes both fields
-// in ONE atomic statement (built on Phase 2's WAL'd row setters) so the two can
-// never disagree.
+// The legal transition TABLE is the definition, and `transition(id, event)` is
+// the single writer of status+intent for every caller (reset, close, revive,
+// feed, daemon, stophook, queue, promote): it validates the from-status, then
+// writes both fields in ONE atomic statement (on the WAL'd row setters) so the
+// two can never disagree.
 //
 // This mirrors persona.ts: persona.ts is the single source of transition PROSE;
 // lifecycle.ts is the single source of which status/intent move is LEGAL. Two
 // parallel, legible state machines instead of scattered enactment.
 //
-// Crash-safety invariant (was a comment repeated in close/reapDescendants):
-// "flip status to a non-supervised value + clear intent BEFORE killing the
-// host" (tmux pane or headless broker) — the daemon only ever revives
-// active|idle nodes, so a teardown must
-// leave the node done/canceled first to close the revive race. That invariant is
-// now the DEFINITION of the `cancel` event: callers flip via transition()
-// and only THEN tear the host down.
+// Crash-safety invariant: flip status to a non-supervised value + clear intent
+// BEFORE killing the host (tmux pane or headless broker) — the daemon only ever
+// revives active|idle nodes, so a teardown must leave the node done/canceled
+// first to close the revive race. That invariant is the DEFINITION of the
+// `cancel` event: callers flip via transition() and only THEN tear the host down.
 //
-// Unification (A5, human-confirmed 2026-06-06): an externally-reaped node — torn
-// down because the user moved on (close cascade) OR because a root relaunch
-// superseded its workers — ends `canceled`, NOT `done`. `done` is reserved for a
-// node that finished its OWN work (finish) — including a relaunched root, which
-// is parked `done` as history, not canceled. The old `reap` event (→ done) was
-// identical to `cancel` in every field and side effect once unified on status, so
-// it was COLLAPSED into `cancel`; reset.ts's reapDescendants routes through
+// An externally-reaped node — torn down because the user moved on (close
+// cascade) OR because a root relaunch superseded its workers — ends `canceled`,
+// NOT `done`. `done` is reserved for a node that finished its OWN work (finish)
+// — including a relaunched root, which is parked `done` as history, not
+// canceled. There is no separate reap event: it would be identical to `cancel`
+// in every field and side effect, so reset.ts's reapDescendants routes through
 // `cancel`.
 //
 // Layering note: lifecycle.ts is runtime, but it is the canvas write surface's

package/dist/core/runtime/node-read.js

@@ -4,9 +4,8 @@
 // These are canvas/runtime reads (getNode + SessionManager + session-cycles):
 // they belong SERVER-SIDE. crtrd's node read handlers (daemon/api/handlers/
 // nodes.ts) call them behind `GET /v1/nodes/{id}/{snapshot,transcript}`. They
-// used to live in the CLI leaves (commands/node-snapshot.ts, node-transcript.ts)
-// and were imported into the handlers from there; Stage B-3 relocated them here
-// so the CLI leaves' import graph reaches no canvas state store (spec §1/§10).
+// live here rather than in the CLI leaves so the leaves' import graph reaches
+// no canvas state store (spec §1/§10).
 import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { readJsonIfExists } from '../fs-utils.js';
 import { tmpdir } from 'node:os';

package/dist/core/runtime/package-health.js

@@ -14,6 +14,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { isRendererReady } from '../termrender/termrender.js';
+import { expandTilde } from '../fs-utils.js';
 /** A non-fatal, action-oriented diagnostic for an unprovisioned managed
  * renderer — the one remaining out-of-tree dependency. Deliberately calls
  * `isRendererReady()`, NOT `ensureRenderer()`: this runs on the front-door boot
@@ -25,14 +26,6 @@ export function rendererWarning() {
     return 'crtr: the pinned termrender renderer is not provisioned — decks, reviews, and inline diagrams render as plaintext.\n' +
         '  Fix: run `crtr sys setup` (requires `uv`: curl -LsSf https://astral.sh/uv/install.sh | sh).';
 }
-/** Expand a leading `~` against `homeDir` (pi's own convention). */
-function expandTilde(pathValue, homeDir) {
-    if (pathValue === '~')
-        return homeDir;
-    if (pathValue.startsWith('~/'))
-        return join(homeDir, pathValue.slice(2));
-    return pathValue;
-}
 /**
  * The pi agent config dir (`~/.pi/agent`, or `$PI_CODING_AGENT_DIR`) — a local
  * reimplementation of pi's `getAgentDir()`. Reimplemented (not imported) ON

package/dist/core/runtime/persona.js

@@ -30,7 +30,7 @@ import { orchestratorContextNote } from './bearings.js';
 /** Load a builtin/user/project memory doc's body by its normalized name, or ''
  *  if it can't be resolved. The single source for the lifecycle/spine/
  *  orchestration-kernel fragments this injector re-delivers on a transition —
- *  the SAME docs Phase 2 authored under `src/builtin-memory/`, so static
+ *  the SAME docs under `src/builtin-memory/`, so static
  *  (system-prompt splice) and transition prose can never drift. */
 function loadMemoryBody(name) {
     try {
@@ -48,7 +48,7 @@ function loadMemoryBody(name) {
  *  resource is its own context window. Roadmap-shaping guidance is just another orchestrator-gated memory
  *  doc the node already gets via the boot-render splice (kinds/<kind>/orchestrator
  *  gated `{kind, mode: orchestrator}`). (Lifecycle is left to its own section —
- *  promotion no longer forces resident, so this never asserts residency.) */
+ *  promotion does not force resident, so this never asserts residency.) */
 function orchestrationGuidance(nodeId, kind) {
     const kernel = loadMemoryBody('orchestration-kernel');
     const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';

package/dist/core/runtime/pi-vendored.d.ts

@@ -4,7 +4,9 @@
  *  heavy pi SDK index on crtr's front-door hot path (the reason broker-sdk.ts
  *  dynamic-imports the engine). Mirrors pi: `PI_CODING_AGENT_DIR` env, else
  *  `~/.pi/agent` (APP_NAME defaults to 'pi'). Re-sync on a pi SDK bump that moves
- *  the sessions dir — same vendoring rationale as the slash-command list below. */
+ *  the sessions dir — same vendoring rationale as the slash-command list below.
+ *  `PI_CODING_AGENT_DIR` goes through the same tilde expansion pi's
+ *  `getAgentDir()` applies, or `~/custom-pi` yields a broken relative path. */
 export declare function piSessionsRoot(): string;
 /**
  * pi's builtin slash commands — vendored verbatim from pi `core/slash-commands.js`
@@ -13,7 +15,7 @@ export declare function piSessionsRoot(): string;
  * Builtins are NOT engine-interpreted (`session.prompt('/model')` ships `/model`
  * to the LLM as literal text), so the broker's `get_commands` op MERGES this list
  * with the engine's registered commands/templates/skills, and the viewer
- * autocomplete parses these locally. Both the broker (T3) and the viewer (T6)
+ * autocomplete parses these locally. Both the broker and the viewer
  * import this single copy.
  *
  * Upstream interpolates `${APP_NAME}` into the `quit` description; `APP_NAME`

package/dist/core/runtime/pi-vendored.js

@@ -12,32 +12,21 @@
 // below to match and adjust the count note.
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { expandTilde } from '../fs-utils.js';
 /** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
  *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be
  *  deep-imported, and a ROOT import of `getAgentDir` would eager-load the entire
  *  heavy pi SDK index on crtr's front-door hot path (the reason broker-sdk.ts
  *  dynamic-imports the engine). Mirrors pi: `PI_CODING_AGENT_DIR` env, else
  *  `~/.pi/agent` (APP_NAME defaults to 'pi'). Re-sync on a pi SDK bump that moves
- *  the sessions dir — same vendoring rationale as the slash-command list below. */
+ *  the sessions dir — same vendoring rationale as the slash-command list below.
+ *  `PI_CODING_AGENT_DIR` goes through the same tilde expansion pi's
+ *  `getAgentDir()` applies, or `~/custom-pi` yields a broken relative path. */
 export function piSessionsRoot() {
     const env = process.env['PI_CODING_AGENT_DIR'];
     const agentDir = env !== undefined && env !== '' ? expandTilde(env) : join(homedir(), '.pi', 'agent');
     return join(agentDir, 'sessions');
 }
-/** Mirror pi's `expandTildePath` (= `normalizePath` with the default expandTilde
- *  on): a bare `~` is the home dir, and a leading `~/` (or `~\` on win32) joins
- *  the remainder under home. pi's `getAgentDir()` runs `PI_CODING_AGENT_DIR`
- *  through this, so the vendored root must too or `~/custom-pi` yields a broken
- *  relative path. Other forms (absolute, relative, `~user`) pass through as pi
- *  leaves them. */
-function expandTilde(p) {
-    if (p === '~')
-        return homedir();
-    if (p.startsWith('~/') || (process.platform === 'win32' && p.startsWith('~\\'))) {
-        return join(homedir(), p.slice(2));
-    }
-    return p;
-}
 /**
  * pi's builtin slash commands — vendored verbatim from pi `core/slash-commands.js`
  * `BUILTIN_SLASH_COMMANDS` (review C1). **21 entries at 0.78.1** (review n1 — NOT 23).
@@ -45,7 +34,7 @@ function expandTilde(p) {
  * Builtins are NOT engine-interpreted (`session.prompt('/model')` ships `/model`
  * to the LLM as literal text), so the broker's `get_commands` op MERGES this list
  * with the engine's registered commands/templates/skills, and the viewer
- * autocomplete parses these locally. Both the broker (T3) and the viewer (T6)
+ * autocomplete parses these locally. Both the broker and the viewer
  * import this single copy.
  *
  * Upstream interpolates `${APP_NAME}` into the `quit` description; `APP_NAME`

package/dist/core/runtime/promote.js

@@ -7,7 +7,7 @@
 //      orchestrator), and seeds a roadmap scaffold.
 //      The transition guidance the node needs is injected CENTRALLY by the
 //      persona injector (runtime/persona.ts) at the turn boundary — promote()
-//      itself no longer returns or hand-emits guidance.
+//      itself returns no guidance and emits none by hand.
 //   2. Refresh → persona swap (permanent). On the next fresh revive the node
 //      starts with the orchestrator system prompt baked in (because the launch
 //      spec now says orchestrator). The injected guidance bridges until then.

package/dist/core/runtime/reopen.js

@@ -1,4 +1,4 @@
-// The re-task/reopen gate (#339) — enforced at every doorway that can revive a
+// The re-task/reopen gate — enforced at every doorway that can revive a
 // node: `node message send` immediate delivery, `node wait deadline`, and
 // `node lifecycle revive`.
 //
@@ -12,7 +12,7 @@
 // so the node's next real `push final` re-latches through the normal
 // `WHERE final_report IS NULL` guard.
 //
-// Concurrency (#340 review): every check here reads `final_report` FRESH from
+// Concurrency: every check here reads `final_report` FRESH from
 // the DB — never a caller-cached snapshot from an earlier point in the
 // command — and the actual clear is a compare-and-swap (`UPDATE ... WHERE
 // final_report = <the exact value just observed>`), mirroring the CAS