@north-light/crouter 0.3.175 → 0.3.177

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

@@ -4,6 +4,15 @@ export declare function profilesRoot(): string;
 export declare function profileRoot(profileId: string): string;
 export declare function profileManifestPath(profileId: string): string;
 export declare function profileMemoryDir(profileId: string): string;
+/** The directory a node running under `profileId` is pinned to — the profile's
+ *  home, but only while it still exists on disk (a node pinned to a deleted dir
+ *  cannot boot). Null for the root profile, a profile with no projects, a home
+ *  that has since been deleted, and an unresolvable id.
+ *
+ *  This is the whole of the profile→cwd direction: cwd SELECTS a profile at the
+ *  front door, and the selected profile then SUPPLIES the node's cwd. Never
+ *  throws — it sits on the node-create path. */
+export declare function profileHome(profileId: string | null): string | null;
 export interface ProfileEntry {
     profileId: string;
     manifest: ProfileManifest;
@@ -18,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;
@@ -30,6 +39,8 @@ export declare function ensureRootProfile(): ProfileEntry;
 export declare function createProfile(name: string, projects?: string[]): ProfileEntry;
 export declare function updateProfileLastUsed(profileId: string): ProfileEntry;
 export declare function renameProfile(profileId: string, name: string): ProfileEntry;
-export declare function addProfileProject(profileId: string, dir: string): ProfileEntry;
+export declare function addProfileProject(profileId: string, dir: string, opts?: {
+    home?: boolean;
+}): ProfileEntry;
 export declare function removeProfileProject(profileId: string, dir: string): ProfileEntry;
 export declare function deleteProfile(profileId: string): void;

package/dist/core/profiles/manifest.js

@@ -6,12 +6,13 @@
 // here, so no caller ever passes a raw CLI operand or `CRTR_PROFILE_ID`
 // straight into `join(profilesRoot(), value)`.
 import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { dirname, join, relative, resolve as resolvePath, sep } from 'node:path';
 import { SCHEMA_VERSION, PROFILE_DIR } from '../../types.js';
 import { userScopeRoot, resetScopeCache } from '../scope.js';
 import { ensureDir, nowIso } from '../fs-utils.js';
 import { usage, notFound, ambiguous, general } from '../errors.js';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 // ---------------------------------------------------------------------------
 // Path safety — the only code in the tree that builds a path under the
 // profiles root. Every other module reaches profile paths through this file.
@@ -73,11 +74,47 @@ export function profileMemoryDir(profileId) {
 // a profile id. Both walk immediate children of the canonical root; neither
 // ever joins an unvalidated operand into a path.
 // ---------------------------------------------------------------------------
-function readManifestFile(path) {
+/** A profile's `home` DEFAULTS to its first project dir. Normalizing here (the
+ *  single read path) rather than at write time means a manifest written before
+ *  homes existed, and one whose explicit home was later removed from purview,
+ *  both still answer with a usable home — no migration pass.
+ *
+ *  The root profile is the exception and never takes the default: it is the
+ *  identity a directory nothing covers falls back to, so its nodes belong where
+ *  the user started them, not in whatever dir was last added to its purview. */
+function normalizeHome(profileId, manifest) {
+    const stored = typeof manifest.home === 'string' && manifest.home !== '' ? manifest.home : null;
+    if (profileId === ROOT_PROFILE_ID)
+        return { ...manifest, home: stored };
+    return { ...manifest, home: stored ?? manifest.projects[0] ?? null };
+}
+function readManifestFile(path, profileId) {
     if (!existsSync(path))
         return null;
     try {
-        return JSON.parse(readFileSync(path, 'utf8'));
+        return normalizeHome(profileId, JSON.parse(readFileSync(path, 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+/** The directory a node running under `profileId` is pinned to — the profile's
+ *  home, but only while it still exists on disk (a node pinned to a deleted dir
+ *  cannot boot). Null for the root profile, a profile with no projects, a home
+ *  that has since been deleted, and an unresolvable id.
+ *
+ *  This is the whole of the profile→cwd direction: cwd SELECTS a profile at the
+ *  front door, and the selected profile then SUPPLIES the node's cwd. Never
+ *  throws — it sits on the node-create path. */
+export function profileHome(profileId) {
+    if (profileId === null || profileId === '')
+        return null;
+    try {
+        const { manifest } = loadProfileManifest(profileId);
+        const home = manifest.home;
+        if (home === null)
+            return null;
+        return existsSync(home) && statSync(home).isDirectory() ? home : null;
     }
     catch {
         return null;
@@ -99,7 +136,7 @@ export function listProfiles() {
         const profileId = dirent.name;
         if (!ID_SHAPE.test(profileId))
             continue;
-        const manifest = readManifestFile(join(root, profileId, 'profile.json'));
+        const manifest = readManifestFile(join(root, profileId, 'profile.json'), profileId);
         if (manifest === null)
             continue;
         out.push({ profileId, manifest });
@@ -110,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) {
@@ -142,55 +179,20 @@ export function loadProfileManifest(profileIdOrName) {
             : 'No profiles exist on this host yet — create one with `crtr profile new --name <name>`.',
     });
 }
-// ---------------------------------------------------------------------------
-// Locking — a plain mkdir-based mutex under `profilesRoot()/.locks/`. mkdir is
-// atomic (EEXIST when already held), so this needs no extra dependency. The
-// blocking wait uses Atomics.wait on a throwaway SharedArrayBuffer to stay
-// synchronous, matching every other sync fs call in this module.
-// ---------------------------------------------------------------------------
-const LOCK_TIMEOUT_MS = 5000;
-const LOCK_POLL_MS = 25;
 function locksDir() {
     return join(profilesRoot(), '.locks');
 }
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
 /** Hold the per-profile manifest lock for the duration of `fn`. ALL manifest
  *  mutations (create/rename/add-project/remove-project/delete/last-used)
  *  below run inside this. */
 export function withProfileManifestLock(profileId, fn) {
     assertSafeProfileId(profileId);
     ensureDir(locksDir());
-    const lockPath = join(locksDir(), `${profileId}.lock`);
-    const deadline = Date.now() + LOCK_TIMEOUT_MS;
-    for (;;) {
-        try {
-            mkdirSync(lockPath);
-            break;
-        }
-        catch (err) {
-            if (err.code !== 'EEXIST')
-                throw err;
-            if (Date.now() > deadline) {
-                throw general(`timed out waiting for the profile lock: ${profileId}`, {
-                    next: 'Retry — another `crtr profile` command may be running concurrently on this profile.',
-                });
-            }
-            sleepSync(LOCK_POLL_MS);
-        }
-    }
-    try {
-        return fn();
-    }
-    finally {
-        try {
-            rmSync(lockPath, { recursive: true, force: true });
-        }
-        catch {
-            /* best-effort release */
-        }
-    }
+    return withExclusiveDirectoryLock(join(locksDir(), `${profileId}.lock`), fn, {
+        timeoutError: () => general(`timed out waiting for the profile lock: ${profileId}`, {
+            next: 'Retry — another `crtr profile` command may be running concurrently on this profile.',
+        }),
+    });
 }
 function writeManifestAtomic(path, manifest) {
     ensureDir(dirname(path));
@@ -254,7 +256,7 @@ export function ensureRootProfile() {
     return withProfileManifestLock(ROOT_PROFILE_ID, () => {
         const manifestPath = profileManifestPath(ROOT_PROFILE_ID);
         const manifestExists = existsSync(manifestPath);
-        const manifest = manifestExists ? readManifestFile(manifestPath) : null;
+        const manifest = manifestExists ? readManifestFile(manifestPath, ROOT_PROFILE_ID) : null;
         if (manifestExists && manifest === null) {
             throw general(`root profile manifest is unreadable: ${manifestPath}`);
         }
@@ -267,6 +269,7 @@ export function ensureRootProfile() {
             schema_version: SCHEMA_VERSION,
             name: ROOT_PROFILE_NAME,
             projects: [],
+            home: null,
             created_at: nowIso(),
             last_used_at: nowIso(),
         };
@@ -286,6 +289,7 @@ export function createProfile(name, projects = []) {
             schema_version: SCHEMA_VERSION,
             name: trimmed,
             projects: resolvedProjects,
+            home: resolvedProjects[0] ?? null,
             created_at: nowIso(),
             last_used_at: null,
         };
@@ -307,7 +311,7 @@ function mutateManifest(profileId, mutate) {
     requireExistingProfile(profileId);
     return withProfileManifestLock(profileId, () => {
         const path = profileManifestPath(profileId);
-        const current = readManifestFile(path);
+        const current = readManifestFile(path, profileId);
         if (current === null) {
             throw notFound(`profile not found: ${profileId}`, { received: profileId });
         }
@@ -327,11 +331,12 @@ export function renameProfile(profileId, name) {
     resetScopeCache();
     return result;
 }
-export function addProfileProject(profileId, dir) {
+export function addProfileProject(profileId, dir, opts = {}) {
     const resolved = resolveExistingProjectDir(dir);
     const result = mutateManifest(profileId, (m) => ({
         ...m,
         projects: dedupeOrdered([...m.projects, resolved]),
+        ...(opts.home === true ? { home: resolved } : {}),
     }));
     resetScopeCache();
     return result;
@@ -351,13 +356,17 @@ export function removeProfileProject(profileId, dir) {
     }
     const result = mutateManifest(profileId, (m) => {
         const filtered = m.projects.filter((p) => p !== real && p !== abs);
+        // Dropping the home dir from purview falls the home back to the first
+        // remaining project, exactly as `normalizeHome` would for a manifest that
+        // never named one — never leaves the profile pointing outside its purview.
+        const home = m.home === real || m.home === abs ? filtered[0] ?? null : m.home;
         if (filtered.length === m.projects.length) {
             throw notFound(`project not found on profile: ${dir}`, {
                 received: dir,
                 next: `Current projects: ${m.projects.length > 0 ? m.projects.join(', ') : '(none)'}.`,
             });
         }
-        return { ...m, projects: filtered };
+        return { ...m, projects: filtered, home };
     });
     resetScopeCache();
     return result;

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

@@ -1,5 +1,5 @@
 import type { DatabaseSync } from 'node:sqlite';
-import type { NewReviewRow, ReviewRecord, ReviewState } from './types.js';
+import { type NewReviewRow, type ReviewRecord, type ReviewState } from './types.js';
 /** Fields written when an open review is conditionally approved. */
 export interface ApproveReviewArgs {
     review_id: string;
@@ -17,6 +17,9 @@ export declare function commitBindingReview(row: NewReviewRow): {
     won: boolean;
 };
 export declare function getReview(reviewId: string): ReviewRecord | null;
+/** The review `reviewId` names, for a caller that cannot proceed without one.
+ *  A `binding` row is still mid-creation and reads as absent. */
+export declare function requireVisibleReview(reviewId: string): ReviewRecord;
 export declare function getReviewByIdempotencyKey(key: string): ReviewRecord | null;
 export declare function getReviewByCompanion(nodeId: string): ReviewRecord | null;
 export declare function getReviewByBridge(nodeId: string): ReviewRecord | null;

package/dist/core/review/store.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { newNodeId } from '../runtime/nodes.js';
 import { openDb, withCanvasWrite } from '../canvas/db.js';
+import { ReviewOperationError, } from './types.js';
 function recordFromRow(raw) {
     return {
         review_id: raw['review_id'],
@@ -79,6 +80,15 @@ export function commitBindingReview(row) {
 export function getReview(reviewId) {
     return readRecord(openDb(), 'review_id = ?', reviewId);
 }
+/** The review `reviewId` names, for a caller that cannot proceed without one.
+ *  A `binding` row is still mid-creation and reads as absent. */
+export function requireVisibleReview(reviewId) {
+    const review = getReview(reviewId);
+    if (review === null || review.state === 'binding') {
+        throw new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
+    }
+    return review;
+}
 export function getReviewByIdempotencyKey(key) {
     return readRecord(openDb(), 'idempotency_key = ?', key);
 }

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/branded-host.js

@@ -21,12 +21,13 @@
 // (a `brew upgrade node` moves realpath(execPath) to a new Cellar version) or the
 // copy is missing. The drift check is a cheap marker compare — no subprocess, no
 // copy — on the happy path.
-import { copyFileSync, mkdirSync, existsSync, readFileSync, writeFileSync, chmodSync, readdirSync, renameSync, realpathSync, unlinkSync, rmSync, statSync, linkSync, } from 'node:fs';
+import { copyFileSync, mkdirSync, existsSync, readFileSync, writeFileSync, chmodSync, readdirSync, renameSync, realpathSync, unlinkSync, rmSync, linkSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { emitEvent } from '../events/emit.js';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 /** The filename the FDA / TCC entry is shown under. */
 const BRANDED_BIN_NAME = 'crouter';
 /** Machine-global host dir. Deliberately NOT under `CRTR_HOME` (tests override
@@ -75,95 +76,16 @@ function readMarker(path = markerPath()) {
     }
 }
 const HOST_LOCK_TIMEOUT_MS = 30_000;
-const HOST_LOCK_POLL_MS = 25;
-const UNOWNED_LOCK_GRACE_MS = 1_000;
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-function processIsAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code === 'EPERM';
-    }
-}
-function reclaimDeadHostLock(lockPath) {
-    let reclaimable = false;
-    try {
-        const owner = JSON.parse(readFileSync(join(lockPath, 'owner.json'), 'utf8'));
-        reclaimable = typeof owner.pid === 'number' && !processIsAlive(owner.pid);
-    }
-    catch {
-        try {
-            reclaimable = Date.now() - statSync(lockPath).mtimeMs > UNOWNED_LOCK_GRACE_MS;
-        }
-        catch {
-            return true;
-        }
-    }
-    if (!reclaimable)
-        return false;
-    const stalePath = `${lockPath}.stale.${process.pid}.${Math.random().toString(36).slice(2)}`;
-    try {
-        renameSync(lockPath, stalePath);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return true;
-        return false;
-    }
-    rmSync(stalePath, { recursive: true, force: true });
-    return true;
-}
 /** Serialize reconciliation of the one machine-global host tuple. This lock is
  * deliberately separate from the immutable runtime-generation install lock. */
 function withBrandedHostLock(run) {
     const root = join(homedir(), CRTR_DIR_NAME);
     const lockPath = join(root, 'host.lock');
-    const token = `${process.pid}.${Math.random().toString(36).slice(2)}`;
-    const candidatePath = `${lockPath}.candidate.${token}`;
     mkdirSync(root, { recursive: true });
-    mkdirSync(candidatePath);
-    writeFileSync(join(candidatePath, 'owner.json'), JSON.stringify({ pid: process.pid, token }));
-    const deadline = Date.now() + HOST_LOCK_TIMEOUT_MS;
-    for (;;) {
-        try {
-            // The owner record and lock become visible together, so another process
-            // can never mistake an in-progress live acquisition for an abandoned lock.
-            renameSync(candidatePath, lockPath);
-            break;
-        }
-        catch (error) {
-            const code = error.code;
-            if (code !== 'EEXIST' && code !== 'ENOTEMPTY') {
-                rmSync(candidatePath, { recursive: true, force: true });
-                throw error;
-            }
-            if (reclaimDeadHostLock(lockPath))
-                continue;
-            if (Date.now() > deadline) {
-                rmSync(candidatePath, { recursive: true, force: true });
-                throw new Error(`timed out waiting for branded host lock: ${lockPath}`);
-            }
-            sleepSync(HOST_LOCK_POLL_MS);
-        }
-    }
-    try {
-        return run();
-    }
-    finally {
-        try {
-            const owner = JSON.parse(readFileSync(join(lockPath, 'owner.json'), 'utf8'));
-            if (owner.token === token)
-                rmSync(lockPath, { recursive: true, force: true });
-        }
-        catch {
-            /* A reclaimed/replaced lock is not ours to remove. */
-        }
-        rmSync(candidatePath, { recursive: true, force: true });
-    }
+    return withExclusiveDirectoryLock(lockPath, run, {
+        timeoutMs: HOST_LOCK_TIMEOUT_MS,
+        timeoutError: () => new Error(`timed out waiting for branded host lock: ${lockPath}`),
+    });
 }
 /** macOS keys FDA grants on the Mach-O cdhash. A real developer identity
  *  keeps that hash stable across branded-host rebuilds; ad-hoc signing is the

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-extension-render.js

@@ -7,7 +7,7 @@ import { hostname } from 'node:os';
 import { interpolateNodePaths } from '../canvas/paths.js';
 import { fullName } from '../canvas/labels.js';
 import { renderKnowledgeForSubject, renderPreferencesForSubject } from '../substrate/render.js';
-import { renderWorkspaceOpenDocsForSubject } from '../substrate/on-read-pure.js';
+import { renderWorkspaceOpenDocsForSubject } from '../substrate/on-read.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
 export function editorLabelForBrokerNode(node) {
     const icon = (node.icon ?? '').trim();

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/canvas-extensions.d.ts

@@ -9,6 +9,7 @@ export declare const CANVAS_TOOL_GUIDE_PATH: string;
 export declare const CANVAS_DOC_SUBSTRATE_PATH: string;
 export declare const CANVAS_STRUCTURED_OUTPUT_PATH: string;
 export declare const CANVAS_BASH_VALVE_PATH: string;
+export declare const CANVAS_PREVIEW_RESULT_PATH: string;
 /** The canvas extensions every node loads, in order. The inbox watcher commits
  *  its cursor at agent_settled before the stophook checks it for idle release.
  *  The review boundary must run before the stophook commits companion session

package/dist/core/runtime/canvas-extensions.js

@@ -21,6 +21,7 @@ export const CANVAS_TOOL_GUIDE_PATH = resolveExtension('canvas-tool-guide');
 export const CANVAS_DOC_SUBSTRATE_PATH = resolveExtension('canvas-doc-substrate');
 export const CANVAS_STRUCTURED_OUTPUT_PATH = resolveExtension('canvas-structured-output');
 export const CANVAS_BASH_VALVE_PATH = resolveExtension('canvas-bash-valve');
+export const CANVAS_PREVIEW_RESULT_PATH = resolveExtension('canvas-preview-result');
 /** The canvas extensions every node loads, in order. The inbox watcher commits
  *  its cursor at agent_settled before the stophook checks it for idle release.
  *  The review boundary must run before the stophook commits companion session
@@ -37,6 +38,7 @@ export const CANVAS_EXTENSIONS = [
     CANVAS_DOC_SUBSTRATE_PATH,
     CANVAS_STRUCTURED_OUTPUT_PATH,
     CANVAS_BASH_VALVE_PATH,
+    CANVAS_PREVIEW_RESULT_PATH,
 ];
 /** Preserve the invariant: mandatory extensions are always present exactly once.
  *