@north-light/crouter 0.3.175 → 0.3.177

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

package/dist/core/runtime/revive-all.d.ts

@@ -13,18 +13,18 @@ export declare const TERMINAL_BY_CHOICE: readonly NodeStatus[];
  *  inbox watcher's own hold-and-flush) ever brings such a node back on its
  *  own — only an explicit revive/reopen does. Shared by `isDisconnected`
  *  (mass-revive scope, below) and `node message send --tier deferred`'s terminal-edge
- *  rejection (gh #341) — a deferred entry appended to such a target would
+ *  rejection — a deferred entry appended to such a target would
  *  never be delivered, so that doorway rejects instead of silently holding
  *  it forever. */
 export declare function hasNoNaturalCycle(meta: Pick<NodeMeta, 'status' | 'final_report'>): boolean;
 /** True when `meta`'s engine is NOT running but it has a resumable saved session
- *  — the precise "disconnected" predicate (gh #9).
+ *  — the precise "disconnected" predicate.
  *
  *  - engine not running: no live `pi_pid` (a dead/absent broker pid).
  *  - reconnectable: a captured pi session marker (`pi_session_file` or
  *    `pi_session_id`) — without one there is nothing to reopen. reviveNode
  *    resumes by the `.jsonl` path when it still exists, else relaunches fresh (a
- *    bare `pi_session_id` alone no longer resumes — the broker preflight rejects
+ *    bare `pi_session_id` alone does not resume — the broker preflight rejects
  *    it — so such a node comes back fresh).
  *  - `human`-kind rows are the `crtr human` bridge, never a pi engine, so they
  *    are never "disconnected" (mirrors the daemon's superviseTick carve-out).

package/dist/core/runtime/revive-all.js

@@ -1,4 +1,4 @@
-// revive-all — resume EVERY disconnected node in one shot (gh issue #9).
+// revive-all — resume EVERY disconnected node in one shot.
 //
 // After a mass-disconnect event (a reboot, a killed login/tmux session, a mass
 // crash, or the daemon being down a while) many nodes end up with their
@@ -30,20 +30,20 @@ export const TERMINAL_BY_CHOICE = ['done', 'canceled'];
  *  inbox watcher's own hold-and-flush) ever brings such a node back on its
  *  own — only an explicit revive/reopen does. Shared by `isDisconnected`
  *  (mass-revive scope, below) and `node message send --tier deferred`'s terminal-edge
- *  rejection (gh #341) — a deferred entry appended to such a target would
+ *  rejection — a deferred entry appended to such a target would
  *  never be delivered, so that doorway rejects instead of silently holding
  *  it forever. */
 export function hasNoNaturalCycle(meta) {
     return meta.final_report != null || TERMINAL_BY_CHOICE.includes(meta.status);
 }
 /** True when `meta`'s engine is NOT running but it has a resumable saved session
- *  — the precise "disconnected" predicate (gh #9).
+ *  — the precise "disconnected" predicate.
  *
  *  - engine not running: no live `pi_pid` (a dead/absent broker pid).
  *  - reconnectable: a captured pi session marker (`pi_session_file` or
  *    `pi_session_id`) — without one there is nothing to reopen. reviveNode
  *    resumes by the `.jsonl` path when it still exists, else relaunches fresh (a
- *    bare `pi_session_id` alone no longer resumes — the broker preflight rejects
+ *    bare `pi_session_id` alone does not resume — the broker preflight rejects
  *    it — so such a node comes back fresh).
  *  - `human`-kind rows are the `crtr human` bridge, never a pi engine, so they
  *    are never "disconnected" (mirrors the daemon's superviseTick carve-out).
@@ -78,8 +78,8 @@ export function listDisconnected() {
         // IDENTITY-aware AND requires CONFIRMED alive: a bare isPidAlive would
         // misread a recycled pi_pid as "engine running" and SKIP the node, so it
         // never reaches reviveNode's own identity-aware double-launch guard
-        // (Round 2 of the pid-reuse-liveness fix, fold-in Major). `dead` OR
-        // `indeterminate` both count as disconnected/eligible here — only a
+        // guard. `dead` OR `indeterminate` both count as disconnected/eligible
+        // here — only a
         // positively confirmed-alive read is treated as "still connected".
         if (meta !== null && isDisconnected(meta, (pid) => recordedPidLiveness(pid, meta.pi_pid_identity) === 'alive'))
             out.push(meta);

package/dist/core/runtime/revive.js

@@ -100,7 +100,7 @@ export function reviveNode(nodeId, opts) {
     }
     // Fresh durable snapshot immediately before the lifecycle guard.
     meta = getNode(nodeId) ?? meta;
-    // #339/#340: refuse to revive a LATCHED node — the reopen gate at every
+    // Refuse to revive a LATCHED node — the reopen gate at every
     // legitimate caller (node message send, node lifecycle revive) already checked this
     // before calling in, but a target can finalize in the gap between that
     // check and this call. This authoritative snapshot closes that race;

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

@@ -109,8 +109,7 @@ export interface SpawnChildResult {
  *  (explicit `--parent` or the calling node's CRTR_NODE_ID). A --root spawn
  *  does not: it is top-level by definition and the spawner identity is
  *  provenance only — a human shell with no CRTR_NODE_ID is a legitimate root
- *  spawner (regression: `crtr node new --root` from outside a node used to
- *  throw here). */
+ *  spawner, so `crtr node new --root` from outside a node must not throw. */
 export declare function resolveSpawner(parent: string | undefined, ctxNodeId: string | null, root: boolean): string | null;
 /** Spawn a node from a live node. By default a managed terminal worker in a
  *  background window, with the spawner auto-subscribed (active) via spawnNode.

package/dist/core/runtime/spawn.js

@@ -187,8 +187,7 @@ export async function assertLaunchModelRegistered(request, options, registry) {
  *  (explicit `--parent` or the calling node's CRTR_NODE_ID). A --root spawn
  *  does not: it is top-level by definition and the spawner identity is
  *  provenance only — a human shell with no CRTR_NODE_ID is a legitimate root
- *  spawner (regression: `crtr node new --root` from outside a node used to
- *  throw here). */
+ *  spawner, so `crtr node new --root` from outside a node must not throw. */
 export function resolveSpawner(parent, ctxNodeId, root) {
     const spawner = parent ?? ctxNodeId ?? null;
     if (!root && spawner === null) {
@@ -218,7 +217,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
     const attendedRoot = root && lifecycle === 'resident';
     // Born WITHOUT a name — the canvas-goal-capture extension names it async from
     // its first message (the kickoff task) inside its own pi process, so spawn
-    // never blocks on the LLM naming round-trip (the 2-3s freeze it used to cost).
+    // never blocks on the LLM naming round-trip (a 2-3s freeze).
     const wantsWorktree = opts.worktree === true;
     const nodeId = wantsWorktree ? (opts.nodeId ?? newNodeId()) : opts.nodeId;
     // Preflight: resolve every fallible input BEFORE creating the worktree or the

package/dist/core/runtime/structured-output.js

@@ -3,15 +3,13 @@ import { dirname, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { nodeDir, contextDir } from '../canvas/paths.js';
 import { InputError } from '../io.js';
+import { isRecord } from '../../shared/predicates.js';
 export function outputSchemaPath(nodeId) {
     return `${nodeDir(nodeId)}/output-schema.json`;
 }
 export function outputResultPath(nodeId) {
     return `${contextDir(nodeId)}/result.json`;
 }
-function isObject(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
 export function parseOutputSchemaValue(value) {
     const raw = value?.trim();
     if (raw === undefined || raw === '')
@@ -49,7 +47,7 @@ export function parseOutputSchemaValue(value) {
             next: 'Pass valid JSON whose top-level value is an object.',
         });
     }
-    if (!isObject(parsed)) {
+    if (!isRecord(parsed)) {
         throw new InputError({
             error: 'bad_output_schema',
             message: `output schema from ${source} must be a JSON object`,
@@ -91,7 +89,7 @@ export function readOutputRequest(nodeId) {
     catch (err) {
         return { state: 'invalid', error: `request file is not valid JSON: ${err.message}` };
     }
-    if (!isObject(parsed)) {
+    if (!isRecord(parsed)) {
         return { state: 'invalid', error: 'request file top-level value must be an object' };
     }
     const mode = parsed['mode'];
@@ -99,7 +97,7 @@ export function readOutputRequest(nodeId) {
     if (mode !== 'terminal' && mode !== 'oneoff') {
         return { state: 'invalid', error: `mode must be 'terminal' or 'oneoff', got ${JSON.stringify(mode)}` };
     }
-    if (!isObject(schema)) {
+    if (!isRecord(schema)) {
         return { state: 'invalid', error: `schema must be an object, got ${typeof schema}` };
     }
     return { state: 'valid', request: { mode, schema } };

package/dist/core/runtime/tmux-bindings.js

@@ -7,7 +7,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { ATTACH_CONTROL_BINDINGS, BINDING_CATALOG, BINDING_IDS, encodeAttachControlInput, formatGesture, isAttachPaneBinding, resolveUserKeybindingSettings, } from '../keybindings/index.js';
 import { normalizeTmuxPassthrough } from '../config.js';
-import { withExclusiveDirectoryLock } from '../human/convention.js';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 import { surfaceTmuxStyleArgs } from './surface-bg.js';
 import { runTmux as tmux, shellQuote } from './tmux-driver.js';
 // ---------------------------------------------------------------------------

package/dist/core/runtime/tmux-driver.d.ts

@@ -1,6 +1,6 @@
 import { type AttachBindingId } from '../keybindings/index.js';
-/** POSIX single-quote escaping for one shell word. */
-export declare function shellQuote(s: string): string;
+import { shellQuote } from '../../shared/shell-quote.js';
+export { shellQuote };
 declare function tmux(args: string[]): {
     ok: boolean;
     stdout: string;

package/dist/core/runtime/tmux-driver.js

@@ -6,13 +6,11 @@
 import { execFile, spawnSync } from 'node:child_process';
 import { encodeAttachControlInput, } from '../keybindings/index.js';
 import { bundledPiCommandForShell } from './pi-cli.js';
+import { shellQuote } from '../../shared/shell-quote.js';
 // ---------------------------------------------------------------------------
-// Shell quoting + tmux invocation
+// tmux invocation
 // ---------------------------------------------------------------------------
-/** POSIX single-quote escaping for one shell word. */
-export function shellQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
+export { shellQuote };
 function tmux(args) {
     const r = spawnSync('tmux', args, { encoding: 'utf8' });
     return {

package/dist/core/runtime/tool-group-summary.js

@@ -49,9 +49,10 @@ const SUMMARY_SYSTEM_PROMPT = 'Create a structured recap of this coding-agent to
     'Omit inbox receipt, delivery, and queueing; node-response and report bookkeeping; help lookups; status checks; and summary-generation activity. ' +
     'A node response may support a substantive outcome, but its arrival or resummarization is never itself an outcome. ' +
     'If no meaningful outcome remains after those omissions, submit the single bullet "No meaningful changes." ' +
-    'Count nodes created and distinct files created, modified, or deleted only when evidenced by the supplied tool arguments or results; otherwise use zero, even when the corresponding mechanics are omitted from bullets. ' +
+    'Count nodes created, and separately count distinct files removed from disk, only when the supplied tool arguments or results evidence them; otherwise use zero, even when the corresponding mechanics are omitted from bullets. ' +
+    'A deleted file is one that no longer exists after the segment, never a file that was merely edited or overwritten, and a recursive or wildcard removal of an unknown number of files counts as one. ' +
     'Do not invent success when a result shows failure. ' +
-    'Call submit_summary exactly once with bullets, nodesSpawned, and filesEdited, then stop.';
+    'Call submit_summary exactly once with bullets, nodesSpawned, and filesDeleted, then stop.';
 const SUBMIT_SUMMARY_SCHEMA = Type.Object({
     bullets: Type.Array(Type.String({
         minLength: 1,
@@ -62,9 +63,9 @@ const SUBMIT_SUMMARY_SCHEMA = Type.Object({
         minimum: 0,
         description: 'Count of nodes created during the supplied segment, or zero when none are evidenced.',
     }),
-    filesEdited: Type.Integer({
+    filesDeleted: Type.Integer({
         minimum: 0,
-        description: 'Count of distinct files created, modified, or deleted during the supplied segment, or zero when none are evidenced.',
+        description: 'Count of distinct files removed from disk during the supplied segment, or zero when none are evidenced.',
     }),
 }, { additionalProperties: false });
 /** Generate a structured summary object, or null on every failure. */

package/dist/core/runtime/warm-pool.d.ts

@@ -16,10 +16,11 @@ export declare function warmPoolEnabled(): boolean;
 export interface WarmRequest {
     kind: string;
     mode: Mode;
+    /** Where the node runs — already resolved by the create handler (pin >
+     *  spawner > profile home), never a raw caller directory. */
     cwd: string;
-    /** The RAW `--profile` operand: a string to pin, `null` for explicitly no
-     *  profile, `undefined` to let the daemon resolve one for the cwd. */
-    profile: string | null | undefined;
+    /** The RESOLVED profile id, or null for explicitly no profile. */
+    profileId: string | null;
     model: string | null;
     situationalContext: string | null;
     name: string | null;
@@ -43,9 +44,9 @@ export declare function reapStaleSpares(): string[];
  *  throws and never blocks a caller: a failed mint just means the next create
  *  for this key is cold again. */
 export declare function refillWarmPool(request: WarmRequest): void;
-/** Mint a spare for the most recently used project recipes so the FIRST create
- *  after crtrd boots is warm too, not only the second. The recipe is sourced
- *  from real recent roots — (cwd, profile) is the whole of it, since everything
- *  else a claim reshapes live. Fire-and-forget: returns as soon as the mints
- *  are scheduled, never blocking the daemon's work lane. */
+/** Mint a spare for the most recently used profiles so the FIRST create after
+ *  crtrd boots is warm too, not only the second. The profile is the whole
+ *  recipe: it supplies the cwd, and everything else a claim reshapes live.
+ *  Fire-and-forget — returns as soon as the mints are scheduled, never blocking
+ *  the daemon's work lane. */
 export declare function prewarmRecentRecipes(): void;