@north-light/crouter 0.3.176 → 0.3.177

package/dist/clients/inbox/controller.js

@@ -7,7 +7,8 @@ import { scanInbox } from '../../core/human/scan.js';
 import { watchInboxActivity } from '../../core/human/root.js';
 import { claimTicket, heartbeatClaim, releaseClaim } from '../../core/human/claim.js';
 import { readTicketResult } from '../../core/human/tickets.js';
-import { clearProgress, deckPath, readJson } from '../../core/human/convention.js';
+import { clearProgress, deckPath } from '../../core/human/convention.js';
+import { readJsonOrNull } from '../../core/fs-utils.js';
 import { DeckAdapter } from './deck-adapter.js';
 import { validateDeck } from '../../core/human/deck-schema.js';
 import { ReviewAdapter } from './review-adapter.js';
@@ -258,7 +259,7 @@ export class InboxController {
         this.markDirty();
     }
     readDeck(dir) {
-        const deck = readJson(deckPath(dir));
+        const deck = readJsonOrNull(deckPath(dir));
         if (deck === null)
             return undefined;
         try {

package/dist/clients/inbox/deck-adapter.js

@@ -1,4 +1,5 @@
-import { progressPath, readJson } from '../../core/human/convention.js';
+import { progressPath } from '../../core/human/convention.js';
+import { readJsonOrNull } from '../../core/fs-utils.js';
 import { mountPanel } from './tui/panel.js';
 /** Embeds the single deck renderer in a controller-owned rectangle. */
 export class DeckAdapter {
@@ -50,7 +51,7 @@ function notificationsAcknowledged(deck, responses) {
     });
 }
 function initialResponses(deck, dir) {
-    const saved = readJson(progressPath(dir))?.responses;
+    const saved = readJsonOrNull(progressPath(dir))?.responses;
     if (Array.isArray(saved))
         return saved;
     return deck.interactions.flatMap((interaction) => {

package/dist/clients/surfaces/host.d.ts

@@ -12,7 +12,7 @@ export interface SurfaceComponent extends Component {
     /** Consume wheel input when applicable. */
     handleWheel?(direction: 'up' | 'down', lines: number): boolean;
 }
-/** The identities used for mounted Phase 3 surfaces. */
+/** The identities used for mounted surfaces. */
 export type SurfaceId = 'inbox' | 'review';
 /** How long a notice stays up. */
 export interface SurfaceNoticeOptions {

package/dist/commands/api-client.d.ts

@@ -20,14 +20,14 @@ export declare function rethrowAsCliError(err: unknown, next?: string): never;
  *  404-only→null mapping as `ApiCanvasSource.orNull`, but returning the raw DTO
  *  and rethrowing non-404s as CLI errors rather than swallowing them. */
 export declare function getNodeOrNull(nodeId: string): Promise<NodeDetailDTO | null>;
-/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout
- *  (issue #516). Large enough to catch a real startup failure/stack trace,
+/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout.
+ *  Large enough to catch a real startup failure/stack trace,
  *  small enough that a runaway daemon log can never leak unbounded into a CLI
  *  error message. */
 export declare const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4096;
 /** Read a bounded tail of crtrd's stderr log to enrich a `daemon_unavailable`
- *  cold-start timeout (issue #516: the prior bare message discarded the actual
- *  startup failure). Bounds the I/O itself — opens the file and reads only the
+ *  cold-start timeout, so the actual startup failure is not discarded behind a
+ *  bare message. Bounds the I/O itself — opens the file and reads only the
  *  final `COLD_START_DIAGNOSTIC_TAIL_BYTES` bytes via `fstatSync`+`readSync`,
  *  never `readFileSync`-ing the whole append-only log — then decodes/filters
  *  that bounded slice. Best-effort and synchronous per the `coldStartDiagnostic`
@@ -42,15 +42,14 @@ export declare function readColdStartDiagnostic(): string | undefined;
  *  autostart is disabled — the client throws `daemon_unavailable` (spec §7.1,
  *  §8). This is the ONLY CLI reference to `ensureDaemon`.
  *
- *  #508 follow-up: `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns
- *  crtrd and returns immediately, so the client's OWN `/healthz` poll is the
- *  only deadline the initiating CLI invocation actually waits on. That poll
- *  used to default to a fixed 10s window while `spawnDaemon`'s
- *  `verifyDaemonStartup` (which `ensureDaemon`'s spawn transitively awaits, in
- *  the detached child, on the SAME cold-start path) was widened to 20s for a
- *  slow-but-valid cold boot: a daemon that took 12s was a valid, verified
- *  startup, but the CLI process that triggered it still gave up and reported
- *  `daemon_unavailable` at 10s. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
+ *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
+ *  returns immediately, so the client's OWN `/healthz` poll is the only
+ *  deadline the initiating CLI invocation actually waits on. It must never be
+ *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows (which
+ *  `ensureDaemon`'s spawn transitively awaits, in the detached child, on the
+ *  SAME cold-start path): a daemon that takes 12s is a valid, verified startup,
+ *  and a 10s client poll would still give up and report `daemon_unavailable`
+ *  against it. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
  *  here keeps the two in lockstep — one authoritative window, not two that can
  *  drift apart — without adding any retry/fallback poll loop. */
 export declare function cliClient(opts?: {

package/dist/commands/api-client.js

@@ -65,15 +65,15 @@ export async function getNodeOrNull(nodeId) {
 function autostartDisabled() {
     return process.env['CRTR_NO_DAEMON_AUTOSTART'] === '1' || process.argv.includes('--no-autostart');
 }
-/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout
- *  (issue #516). Large enough to catch a real startup failure/stack trace,
+/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout.
+ *  Large enough to catch a real startup failure/stack trace,
  *  small enough that a runaway daemon log can never leak unbounded into a CLI
  *  error message. */
 export const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4_096;
 const COLD_START_DIAGNOSTIC_TAIL_LINES = 20;
 /** Read a bounded tail of crtrd's stderr log to enrich a `daemon_unavailable`
- *  cold-start timeout (issue #516: the prior bare message discarded the actual
- *  startup failure). Bounds the I/O itself — opens the file and reads only the
+ *  cold-start timeout, so the actual startup failure is not discarded behind a
+ *  bare message. Bounds the I/O itself — opens the file and reads only the
  *  final `COLD_START_DIAGNOSTIC_TAIL_BYTES` bytes via `fstatSync`+`readSync`,
  *  never `readFileSync`-ing the whole append-only log — then decodes/filters
  *  that bounded slice. Best-effort and synchronous per the `coldStartDiagnostic`
@@ -116,15 +116,14 @@ export function readColdStartDiagnostic() {
  *  autostart is disabled — the client throws `daemon_unavailable` (spec §7.1,
  *  §8). This is the ONLY CLI reference to `ensureDaemon`.
  *
- *  #508 follow-up: `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns
- *  crtrd and returns immediately, so the client's OWN `/healthz` poll is the
- *  only deadline the initiating CLI invocation actually waits on. That poll
- *  used to default to a fixed 10s window while `spawnDaemon`'s
- *  `verifyDaemonStartup` (which `ensureDaemon`'s spawn transitively awaits, in
- *  the detached child, on the SAME cold-start path) was widened to 20s for a
- *  slow-but-valid cold boot: a daemon that took 12s was a valid, verified
- *  startup, but the CLI process that triggered it still gave up and reported
- *  `daemon_unavailable` at 10s. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
+ *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
+ *  returns immediately, so the client's OWN `/healthz` poll is the only
+ *  deadline the initiating CLI invocation actually waits on. It must never be
+ *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows (which
+ *  `ensureDaemon`'s spawn transitively awaits, in the detached child, on the
+ *  SAME cold-start path): a daemon that takes 12s is a valid, verified startup,
+ *  and a 10s client poll would still give up and report `daemon_unavailable`
+ *  against it. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
  *  here keeps the two in lockstep — one authoritative window, not two that can
  *  drift apart — without adding any retry/fallback poll loop. */
 export function cliClient(opts) {
@@ -140,7 +139,7 @@ export function cliClient(opts) {
             ensureDaemon();
         },
         // On a cold-start timeout, enrich the bare `daemon_unavailable` with the
-        // tail of crtrd's own stderr log (issue #516) instead of discarding it.
+        // tail of crtrd's own stderr log instead of discarding it.
         coldStartDiagnostic: readColdStartDiagnostic,
         coldStartPollWindowMs: DAEMON_VERIFY_WINDOW_MS,
     });
@@ -153,8 +152,8 @@ export function cliClient(opts) {
 // performs no lossy legacy reconstruction or invented local-presence values.
 // The attach viewer's recurring subtree walk (chrome/canvas-panels.ts + overlays/graph.ts
 // computeActivity/visitActivity) calls subscriptionsOf/subscribersOf once per
-// visited node on every poll tick; each call was previously its own
-// `GET /v1/nodes/:id` round trip just to read the edge list off the detail DTO.
+// visited node on every poll tick, and a `GET /v1/nodes/:id` per call just to
+// read the edge list off the detail DTO costs one round trip per visited node.
 // This short-TTL cache backs those two methods with the lean roster
 // (`GET /v1/canvas/roster`) instead — one shared fetch per TTL window covers
 // every topology walk in that window, comfortably under the attach viewer's 5s

package/dist/commands/chord.js

@@ -19,8 +19,7 @@ const pexec = promisify(execFile);
  *  here rather than importing node.ts's `nodeInPane` (which reaches openDb via the
  *  canvas accessors) so this dispatcher's import graph stays db-free. Under the
  *  headless-broker model every engine runs DETACHED (window=null), so the pane tag
- *  is the ONLY node handle — the window→node fallback in node.ts's variant only ever
- *  matched legacy in-pane engines, which no longer exist. A stale tag is ignored
+ *  is the ONLY node handle. A stale tag is ignored
  *  (the tagged node must still be live), validated through the daemon API. */
 async function nodeInPane(pane) {
     if (pane === undefined || pane === '')

package/dist/commands/human/queue.js

@@ -5,7 +5,8 @@ import { defineLeaf } from '../../core/command.js';
 import { ticketDir } from '../../core/human/root.js';
 import { scanInbox } from '../../core/human/scan.js';
 import { parseDeck } from '../../core/human/deck-schema.js';
-import { deckPath, isResolved, readJson, reviewPath } from '../../core/human/convention.js';
+import { deckPath, isResolved, reviewPath } from '../../core/human/convention.js';
+import { readJsonOrNull } from '../../core/fs-utils.js';
 import { InputError } from '../../core/io.js';
 import { paginate } from '../../core/pagination.js';
 import { cliClient, rethrowAsCliError } from '../api-client.js';
@@ -14,9 +15,9 @@ function toRef(n) {
     return { node_id: n.node_id, name: n.name, cwd: n.cwd, parent: n.parent, status: n.status };
 }
 /** The canvas roster, fetched ONCE per leaf run through the API and threaded
- *  into the sync provenance helpers below (they used to call `listNodes()`/
- *  `getNode()` synchronously; the API surface is async, so the fetch is hoisted
- *  to the leaf and the helpers read the pre-fetched array/map). */
+ *  into the sync provenance helpers below (the API surface is async, so the
+ *  fetch is hoisted to the leaf and the helpers read the pre-fetched
+ *  array/map). */
 async function fetchNodeRefs() {
     return (await cliClient().listNodes()).map(toRef);
 }
@@ -67,7 +68,7 @@ function summarizeTicket(summary, nodes, byId) {
         return null;
     const asking = askingNodeFor(jobId, byId);
     const conversation = resolveConversation(asking, nodes);
-    const interactionCount = summary.kind === 'deck' ? readJson(deckPath(summary.dir))?.interactions.length : undefined;
+    const interactionCount = summary.kind === 'deck' ? readJsonOrNull(deckPath(summary.dir))?.interactions.length : undefined;
     const sourceLabel = readableSourceLabel(summary.source);
     return {
         id: summary.id,

package/dist/commands/memory/find.js

@@ -155,9 +155,9 @@ export const findLeaf = defineLeaf({
         // Sort comparator MUST match keyOf exactly (score desc, then scope asc,
         // then name asc as the final deterministic identity component — the
         // candidate dedup keys on scope+name, so this pair is always unique).
-        // Equal-score hits from different scopes previously sorted by name alone
-        // while the cursor key ordered by scope first, so the array could disagree
-        // with its own keys and paginate() would silently skip a later item.
+        // Sorting equal-score hits from different scopes by name alone while the
+        // cursor key orders by scope first would let the array disagree with its
+        // own keys, and paginate() would silently skip a later item.
         hits.sort((a, b) => {
             if (b.score !== a.score)
                 return b.score - a.score;

package/dist/commands/node/lifecycle.js

@@ -375,7 +375,7 @@ export const nodeYield = defineLeaf({
             { kind: 'flag', name: 'promote', type: 'bool', required: false, constraint: 'Also become an orchestrator as you refresh. Pass only when (1) the remaining work contains independent units that can run in parallel and (2) the task is large enough that parallel execution will materially improve intelligence, productivity, or elapsed throughput after coordination and synthesis. Task length, context exhaustion, sequential phases, or one helper are not enough; keep hands-on work in base mode and yield again as needed. Promote when coordinating and integrating children becomes your primary job. Already an orchestrator? This is not an error: your mode stays orchestrator and a missing roadmap is seeded.' },
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Respecialize as you refresh. The <kinds> list below names every top-level available kind and when to choose it; a sub-kind (e.g. plan/reviewers/security) is valid too by exact path but not listed here. Defaults to your current kind. With --promote it sets the orchestrator kind you become; without --promote it changes the kind while preserving your current mode.' },
             { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model your fresh revive runs on, by capability tier: `ultra` (frontier — reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus — regular dev work). Omit to keep your current model. A node steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
-            // Deliberate fail-first contract (#395): builtin orchestration guidance shows bare
+            // Deliberate fail-first contract: builtin orchestration guidance shows bare
             // `crtr node yield`; that invocation fails fast and surfaces yield's full help just in
             // time, at the point of use. Keep the note required rather than pre-documenting stdin
             // in kernel guidance.

package/dist/commands/node-lifecycle-revive.d.ts

@@ -3,7 +3,7 @@ import type { Fault } from '../core/runtime/fault.js';
 /** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
  *  (kick it early instead of waiting out the schedule), or any fault the
  *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
- *  disposition that otherwise has NO sanctioned recovery verb (issue #115).
+ *  disposition that otherwise has NO sanctioned recovery verb.
  *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
  *  (redialing) already in flight, and refuses any OTHER link — notably a
  *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch

package/dist/commands/node-lifecycle-revive.js

@@ -40,7 +40,7 @@ import { waitForViewSocketReady } from '../core/runtime/view-socket.js';
 /** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
  *  (kick it early instead of waiting out the schedule), or any fault the
  *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
- *  disposition that otherwise has NO sanctioned recovery verb (issue #115).
+ *  disposition that otherwise has NO sanctioned recovery verb.
  *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
  *  (redialing) already in flight, and refuses any OTHER link — notably a
  *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
@@ -143,7 +143,7 @@ export const nodeReviveLeaf = defineLeaf({
         // above) so it can't be used to nuke a healthy node. This whole path stays
         // LOCAL: the kick is a direct SIGTERM to the broker pid (there is no revive
         // API call), and the node detail comes from the daemon read (`getNode`). The
-        // reopen gate (#339) is NOT invoked here — --now targets a LIVE broker, and a
+        // reopen gate is NOT invoked here — --now targets a LIVE broker, and a
         // finalized node has none (its own live-pid check below refuses it anyway).
         if (now) {
             // The detail DTO projects `pi_pid_identity` (the launch-time process-identity
@@ -201,7 +201,7 @@ export const nodeReviveLeaf = defineLeaf({
             };
         }
         // Ordinary revive: the daemon relaunches the broker (the ONLY sanctioned
-        // launcher). Node-existence validation (`not_found`) and the #339 reopen gate
+        // launcher). Node-existence validation (`not_found`) and the reopen gate
         // are both enforced server-side in `handleRevive`; a thrown gate/not-found
         // error round-trips through `ApiError.details` and is reconstructed into the
         // identical `InputError` by the shared `apiErrorToCliError` (via

package/dist/commands/push.js

@@ -73,7 +73,7 @@ function makeTierLeaf(tier) {
                 ...(tier === 'final'
                     ? [
                         'Marks the node done (status + intent) server-side; its engine shuts down on next stop.',
-                        'When this node owns a managed worktree with zero commits ahead of its base and no uncommitted changes, the server auto-drops it instead of blocking on `node worktree close` (#327/#333); a worktree with real commits or real uncommitted changes still blocks with open_managed_worktree.',
+                        'When this node owns a managed worktree with zero commits ahead of its base and no uncommitted changes, the server auto-drops it instead of blocking on `node worktree close`; a worktree with real commits or real uncommitted changes still blocks with open_managed_worktree.',
                     ]
                     : []),
             ],

package/dist/commands/surface/node/placement.d.ts

@@ -39,7 +39,7 @@ export declare function openSpawnViewer(nodeId: string, cwd: string, name: strin
  *  A `crtr surface attach` viewer self-tags its pane with the node it views
  *  (`@crtr_node`) — the tag IS the handle (a broker engine runs DETACHED with
  *  window=null, so there is no window→node fallback). Kept SYNC + tag-only: the
- *  re-plumbed CLI no longer reads canvas state to confirm the tagged node is
+ *  CLI does not read canvas state to confirm the tagged node is
  *  still live, so a stale tag (attach SIGKILLed without clearing) resolves until
  *  the pane is respawned. Callers that mutate then re-validate the id via the
  *  API (getNode 404 → clean error). */

package/dist/commands/surface/node/placement.js

@@ -111,7 +111,7 @@ export function openSpawnViewer(nodeId, cwd, name) {
  *  A `crtr surface attach` viewer self-tags its pane with the node it views
  *  (`@crtr_node`) — the tag IS the handle (a broker engine runs DETACHED with
  *  window=null, so there is no window→node fallback). Kept SYNC + tag-only: the
- *  re-plumbed CLI no longer reads canvas state to confirm the tagged node is
+ *  CLI does not read canvas state to confirm the tagged node is
  *  still live, so a stale tag (attach SIGKILLed without clearing) resolves until
  *  the pane is respawned. Callers that mutate then re-validate the id via the
  *  API (getNode 404 → clean error). */

package/dist/commands/surface-edit.js

@@ -33,6 +33,7 @@ import { isAbsolute, resolve } from 'node:path';
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { currentTmux, splitWindow, paneLocation, paneOfNode, } from '../core/runtime/placement-tmux.js';
+import { shellQuote } from '../shared/shell-quote.js';
 /** Resolve the pane the editor should open BESIDE — the pane that opened this
  *  command: explicit --pane, the caller's own $TMUX_PANE, the pane where THIS
  *  node is being watched (its `@crtr_node`-tagged pane, whatever viewer put it
@@ -57,10 +58,6 @@ function resolveTargetPane(explicit) {
     }
     return currentTmux()?.pane ?? null;
 }
-/** POSIX single-quote a shell word so paths survive spaces/specials. */
-function shellQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
 /** The command the new pane runs. The pane INHERITS the tmux server environment
  *  (like every crtr chrome pane — the subagent viewer panes get theirs the same
  *  way), and a tmux server started from the human's interactive shell captured

package/dist/commands/sys/panels/panel.d.ts

@@ -7,9 +7,9 @@ export interface SetupPanel {
 type ThemeFgRole = "border" | "accent" | "dim" | "success" | "warning" | "muted" | "mdLink" | "mdLinkUrl";
 export declare const theme: {
     fg(role: ThemeFgRole, text: string): string;
-    /** A real filled selection band. `selectedBg` was previously an identity
-     *  function, which left the active tab and the active row with no background
-     *  at all — reverse video is the one background every terminal theme honours. */
+    /** A real filled selection band. An identity `selectedBg` would leave the
+     *  active tab and the active row with no background at all — reverse video is
+     *  the one background every terminal theme honours. */
     bg(_role: "selectedBg", text: string): string;
     bold(text: string): string;
 };

package/dist/commands/sys/panels/panel.js

@@ -23,9 +23,9 @@ export const theme = {
                 return ansiYellow(text);
         }
     },
-    /** A real filled selection band. `selectedBg` was previously an identity
-     *  function, which left the active tab and the active row with no background
-     *  at all — reverse video is the one background every terminal theme honours. */
+    /** A real filled selection band. An identity `selectedBg` would leave the
+     *  active tab and the active row with no background at all — reverse video is
+     *  the one background every terminal theme honours. */
     bg(_role, text) {
         return `\x1b[7m${text}\x1b[27m`;
     },

package/dist/commands/sys/setup-core.js

@@ -14,6 +14,7 @@ import { detectNerdFont, nerdFontInstallCommand, NERD_FONT_SELECT_HINT } from '.
 import { ensureRenderer, isRendererReady } from '../../core/termrender/termrender.js';
 import { installFromMarketplace } from '../pkg/plugin-manage.js';
 import { findPluginByName } from '../../core/resolver.js';
+import { expandTilde } from '../../core/fs-utils.js';
 function isKeybindingsObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -214,13 +215,6 @@ export function buildSetupManifest(resolveBuiltinPackageDir = builtinPiPackageDi
         };
     });
 }
-function expandTilde(pathValue, homeDir) {
-    if (pathValue === '~')
-        return homeDir;
-    if (pathValue.startsWith('~/'))
-        return join(homeDir, pathValue.slice(2));
-    return pathValue;
-}
 function npmPackageName(source) {
     if (!source.startsWith('npm:'))
         return null;

package/dist/commands/sys/sync-deps.js

@@ -32,13 +32,11 @@ import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { pathExists, readJsonIfExists, readText, walkFiles, writeText } from '../../core/fs-utils.js';
 import { serializeMemoryDoc } from '../memory/shared.js';
 import { routeFromDescription, scalarString } from './sync-shared.js';
+import { isRecord } from '../../shared/predicates.js';
 /** Marker value written to the generated top INDEX's `generated-by` field —
  *  the wipe guard: `deps` only ever deletes a deps/ dir whose INDEX carries
  *  this marker. */
 export const DEPS_GENERATED_MARKER = 'crtr sys sync deps';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function invalidDepsConfig(message) {
     throw usage(`--deps: invalid package.json crtr.sync.deps.exclude: ${message}`);
 }

package/dist/commands/sys/sync-project-guidance.js

@@ -3,7 +3,7 @@
 // `.crouter/memory/`. Each project guide becomes the root INDEX front door;
 // rules retain their explicit path routes, or use the workspace-open `.` route
 // when they are pathless.
-import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
@@ -13,6 +13,7 @@ import { loadProfileManifest } from '../../core/profiles/manifest.js';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { memoryFilePath, serializeMemoryDoc } from '../memory/shared.js';
 import { normalizedName, routeFromDescription, scalarString } from './sync-shared.js';
+import { realpathOrSelf } from '../../core/fs-utils.js';
 // Directories a project-doc walk never descends into — build/dependency trees
 // plus crouter's own state dir.
 const PROJECT_DOC_JUNK_DIRS = new Set([
@@ -136,16 +137,6 @@ function gitWorktreeRoot(dir) {
     const top = res.stdout.trim();
     return top === '' ? undefined : resolve(top);
 }
-/** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved
- *  (falls back to the path as given). */
-function realpathOrSelf(p) {
-    try {
-        return realpathSync(p);
-    }
-    catch {
-        return p;
-    }
-}
 /** First Markdown H1 heading in the doc body, heading marker stripped. */
 function h1Title(body) {
     for (const raw of body.split('\n')) {

package/dist/commands/sys/sysprompt.js

@@ -7,9 +7,7 @@ import { jobDir } from '../../core/canvas/paths.js';
 import { openNodeWindow } from '../../core/runtime/placement-tmux.js';
 import { ApiError } from '../../api/index.js';
 import { cliClient } from '../api-client.js';
-function shellQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
+import { shellQuote } from '../../shared/shell-quote.js';
 export const sysSyspromptLeaf = defineLeaf({
     name: 'sysprompt',
     description: 'print a node\'s assembled system prompt',

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -139,7 +139,7 @@ export class SessionManager {
     }
 }
 // ---------------------------------------------------------------------------
-// AgentSessionEvent stream synthesis (T8 / G1, G3, G4, G8). The fake emits a
+// AgentSessionEvent stream synthesis. The fake emits a
 // REALISTIC streaming assistant turn through session.subscribe — the SAME channel
 // the real pi engine feeds the broker's fan-out — so the frames a `crtr surface attach`
 // client receives are byte-for-byte real AgentSessionEvents. The EMITTED event

package/dist/core/__tests__/helpers/harness.d.ts

@@ -37,7 +37,7 @@ export interface HarnessOpts {
      *  harness does NOT gate on tmux, does NOT eagerly create the isolated tmux
      *  session, and skips the per-pane `set-environment` seeding — nothing in a
      *  headless run opens a window. CRTR_NODE_SESSION/CRTR_ROOT_SESSION are still
-     *  scrubbed/restored for env hygiene, but no longer route placement: a managed
+     *  scrubbed/restored for env hygiene, but do not route placement: a managed
      *  child opens NO viewer (it boots a detached broker, supervised by pid), and a
      *  --root opens one viewer in the caller's current session. Headless tests must
      *  use `spawnHeadlessChild`, never `spawnChild`. See createHeadlessHarness(). */

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

@@ -312,7 +312,7 @@ export async function createHarness(opts = {}) {
     }
     // Pre-create the isolated session on the DEFAULT server so teardown always
     // has a kill-sessions target.
-    // ISOLATION ASSUMPTION (see header + MINOR-6): isolation is by SESSION NAME on
+    // ISOLATION ASSUMPTION (see header): isolation is by SESSION NAME on
     // the DEFAULT tmux server only. The runtime CLI shells `tmux` with no `-L`, so
     // a custom-socket server (`tmux -L foo`) would be invisible to it; this harness
     // therefore assumes the default socket and only ever kill-sessions, never the

package/dist/core/canvas/boot.js

@@ -148,7 +148,7 @@ export function reconcileBootLiveness(current = currentBootIdentity()) {
         const rows = db
             .prepare('SELECT node_id FROM nodes WHERE pi_pid IS NOT NULL')
             .all();
-        // Clear the launch-time identity baseline (crouter#98 review finding 1)
+        // Clear the launch-time identity baseline
         // alongside `pi_pid` — a boot resets the OS process table, so any recorded
         // identity is as meaningless as the pid it was captured for; leaving it
         // behind would let a coincidentally-reused pid on the NEW boot compare

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

@@ -358,8 +358,8 @@ export async function runBrowse(opts) {
     // Coalesced search repaint. The expensive work per keystroke is recompute()
     // (a fuzzyMatch flatten over the whole corpus) + a full renderFrame. Doing it
     // synchronously on every key blocks the event loop, so fast typing batches into
-    // the stdin reads — and batched chunks used to be dropped (see onKeySearch).
-    // Instead, each key only mutates state.query (cheap) and marks the view dirty;
+    // the stdin reads, where a naive per-key handler drops batched chunks (see
+    // onKeySearch). Instead, each key only mutates state.query (cheap) and marks the view dirty;
     // a single setImmediate drains AFTER every queued stdin 'data' callback (poll
     // phase) has appended its chars, so N rapid keys collapse to ONE recompute+paint
     // and no keystroke is ignored. The sort may still take a moment — that's fine.

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

@@ -33,7 +33,7 @@ export declare function setPresence(nodeId: string, presence: {
     pane?: string | null;
 }): void;
 /** Record the live pi pid (daemon liveness signal) PLUS its launch-time
- *  identity fingerprint, in one atomic write (crouter#98 review finding 1):
+ *  identity fingerprint, in one atomic write:
  *  `capturePidIdentities([pid])` is a signal-0-adjacent `ps -p <pid>` probe
  *  taken RIGHT NOW, while `pid` is the process we just spawned/bound and
  *  therefore definitely still exists — this is the LAUNCH-time baseline
@@ -242,7 +242,7 @@ export type TerminalGuardResult<T> = {
 } | {
     kind: 'missing';
 };
-/** #343: close the TOCTOU between checking a target has a natural cycle ahead
+/** Close the TOCTOU between checking a target has a natural cycle ahead
  *  of it and the write that depends on that (for example, a deferred inbox
  *  append). Fresh-reads `nodeId`'s
  *  (status, final_report) and either runs `body` (a write) or short-circuits
@@ -254,7 +254,7 @@ export type TerminalGuardResult<T> = {
  *  write left open. Pass the shared `hasNoNaturalCycle` predicate rather than
  *  a bespoke one so the two never drift.
  *
- *  #343 review (Major): a dangling `nodeId` — the row deleted after the
+ *  A dangling `nodeId` — the row deleted after the
  *  caller's own selection but before this guard's fresh read — MUST NEVER run
  *  `body`. Reporting `'missing'` distinctly from `'terminal'` (rather than
  *  folding it into either the terminal branch or a fabricated "safe" empty

package/dist/core/canvas/canvas.js

@@ -243,7 +243,7 @@ export function setPresence(nodeId, presence) {
         .run(presence.tmux_session ?? null, presence.window ?? null, presence.pane ?? null, nodeId);
 }
 /** Record the live pi pid (daemon liveness signal) PLUS its launch-time
- *  identity fingerprint, in one atomic write (crouter#98 review finding 1):
+ *  identity fingerprint, in one atomic write:
  *  `capturePidIdentities([pid])` is a signal-0-adjacent `ps -p <pid>` probe
  *  taken RIGHT NOW, while `pid` is the process we just spawned/bound and
  *  therefore definitely still exists — this is the LAUNCH-time baseline
@@ -633,7 +633,7 @@ export function settleDeadMessageWait(nodeId, controller, deliver) {
         return result;
     });
 }
-/** #343: close the TOCTOU between checking a target has a natural cycle ahead
+/** Close the TOCTOU between checking a target has a natural cycle ahead
  *  of it and the write that depends on that (for example, a deferred inbox
  *  append). Fresh-reads `nodeId`'s
  *  (status, final_report) and either runs `body` (a write) or short-circuits
@@ -645,7 +645,7 @@ export function settleDeadMessageWait(nodeId, controller, deliver) {
  *  write left open. Pass the shared `hasNoNaturalCycle` predicate rather than
  *  a bespoke one so the two never drift.
  *
- *  #343 review (Major): a dangling `nodeId` — the row deleted after the
+ *  A dangling `nodeId` — the row deleted after the
  *  caller's own selection but before this guard's fresh read — MUST NEVER run
  *  `body`. Reporting `'missing'` distinctly from `'terminal'` (rather than
  *  folding it into either the terminal branch or a fabricated "safe" empty

package/dist/core/canvas/daemon-owner.js

@@ -1,5 +1,4 @@
-// daemon-owner.ts — the canvas-layer authoritative daemon ownership primitive
-// (Phase 1 runtime-boundary, task D0).
+// daemon-owner.ts — the canvas-layer authoritative daemon ownership primitive.
 //
 // A pidfile check followed by a later write is not singleton ownership: two
 // `crtrd` invocations racing a cold start can both read "no pidfile", both

package/dist/core/canvas/db.js

@@ -58,10 +58,9 @@ function addNodeColumnIfMissing(db, columns, name, ddl) {
     db.exec(ddl);
     columns.add(name);
 }
-/** v2 — additive runtime columns the keystone (Phase 2) will make
- *  authoritative: `intent, pi_pid, window, tmux_session`. `status` already
- *  lives in the baseline row, so it is NOT re-added here. All four default to
- *  NULL, so nothing observes a behavior change until a later phase reads them. */
+/** v2 — the additive runtime columns: `intent, pi_pid, window, tmux_session`.
+ *  `status` already lives in the baseline row, so it is NOT re-added here. All
+ *  four default to NULL; v3 backfills them. */
 function addRuntimeColumns(db) {
     const columns = nodeColumns(db);
     addNodeColumnIfMissing(db, columns, 'intent', `ALTER TABLE nodes ADD COLUMN intent TEXT;`);
@@ -69,14 +68,14 @@ function addRuntimeColumns(db) {
     addNodeColumnIfMissing(db, columns, 'window', `ALTER TABLE nodes ADD COLUMN window TEXT;`);
     addNodeColumnIfMissing(db, columns, 'tmux_session', `ALTER TABLE nodes ADD COLUMN tmux_session TEXT;`);
 }
-/** v3 — DATA backfill (keystone, Phase 2). The runtime fields
+/** v3 — DATA backfill. The runtime fields
  *  (`intent, pi_pid, window, tmux_session`) become authoritative in the row;
  *  copy each existing node's values out of its meta.json into the row columns
  *  once, so the version boundary loses no live state. `status` already mirrors
  *  the row, so it is not re-copied.
  *
- *  LAYERING NOTE (explicitly sanctioned by the runtime-fix plan): a *data*
- *  migration must read meta.json, which db.ts normally would not. Reading it
+ *  LAYERING NOTE — a sanctioned exception: a *data* migration must read
+ *  meta.json, which db.ts normally would not. Reading it
  *  directly here — via paths.ts, a one-time, clearly-labeled boot-time data
  *  migration — is the deliberate choice over splitting the `user_version`
  *  counter across two modules. Idempotent and gated: it runs exactly once at the
@@ -367,7 +366,7 @@ function addProfileIdColumn(db) {
  *  identity fingerprint (`pid.ts`'s `composeIdentity`) recorded alongside
  *  `pi_pid` (v2) by `recordPid`, so `headlessBrokerHost.teardown()` can refuse
  *  to signal a `pi_pid` the OS has since recycled for an unrelated process
- *  (crouter#98 final review, Fix 1 — see `NodeRuntime.pi_pid_identity`).
+ *  (see `NodeRuntime.pi_pid_identity`).
  *  Defaults NULL ⇒ no baseline ⇒ the guard fails open, exactly like a node
  *  booted before this column existed. No data backfill: an existing `pi_pid`
  *  with no recorded identity simply has no launch-time baseline to compare

package/dist/core/canvas/index.js

@@ -1,5 +1,5 @@
-// The canvas: one global graph of nodes + edges. Phase 0 of the pi-native
-// agent runtime. Topology in sqlite (WAL), node flesh on disk.
+// The canvas: one global graph of nodes + edges.
+// Topology in sqlite (WAL), node flesh on disk.
 export * from './types.js';
 export * from './labels.js';
 export * from './paths.js';