@north-light/crouter 0.3.170 → 0.3.172

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

@@ -10,131 +10,20 @@
 // vanishes with no diagnostic. This turns that silent failure into a loud,
 // actionable warning. The fix it points at is `crtr sys setup`, which re-resolves
 // package paths to the repo's current location.
-import { accessSync, constants, existsSync, readFileSync, realpathSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { delimiter, dirname, join, resolve } from 'node:path';
-const GLOBAL_HUMANLOOP_INSTALL_COMMAND = 'npm i -g @crouton-kit/humanloop@latest';
-/** Read the installed library's version rather than coupling this check to the
- * dependency range in crouter's package.json. The bundled copy is the floor
- * required by crouter's generated `hl inbox toggle` binding. */
-export function bundledHumanloopVersion() {
-    try {
-        // package.json is deliberately not an exported subpath. Resolve the public
-        // ESM entry, then walk from dist/index.js to the package root.
-        const entryPath = fileURLToPath(import.meta.resolve('@crouton-kit/humanloop'));
-        const packageJsonPath = join(dirname(entryPath), '..', 'package.json');
-        const value = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-        return typeof value.version === 'string'
-            ? value.version
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** Compare ordinary npm semvers without loading a semver dependency on the
- * foreground/daemon startup path. Unparseable versions deliberately fail the
- * health check: setup can repair them and boot only warns. */
-function compareVersions(left, right) {
-    const parse = (version) => {
-        const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
-        if (match === null)
-            return null;
-        return { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4]?.split('.') ?? [] };
-    };
-    const a = parse(left);
-    const b = parse(right);
-    if (a === null || b === null)
+import { join, resolve } from 'node:path';
+import { isRendererReady } from '../termrender/termrender.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
+ * path and at crtrd startup, where a `uv pip install` (up to 180s) must never
+ * happen. Readiness is a handful of fs stats, no subprocess. */
+export function rendererWarning() {
+    if (isRendererReady())
         return null;
-    for (let index = 0; index < a.core.length; index++) {
-        const difference = a.core[index] - b.core[index];
-        if (difference !== 0)
-            return difference;
-    }
-    if (a.prerelease.length === 0 || b.prerelease.length === 0) {
-        return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length === 0 ? 1 : -1;
-    }
-    for (let index = 0; index < Math.max(a.prerelease.length, b.prerelease.length); index++) {
-        const aPart = a.prerelease[index];
-        const bPart = b.prerelease[index];
-        if (aPart === undefined || bPart === undefined)
-            return aPart === bPart ? 0 : aPart === undefined ? -1 : 1;
-        if (aPart === bPart)
-            continue;
-        const aNumber = /^\d+$/.test(aPart);
-        const bNumber = /^\d+$/.test(bPart);
-        if (aNumber && bNumber)
-            return Number(aPart) - Number(bPart);
-        if (aNumber !== bNumber)
-            return aNumber ? -1 : 1;
-        return aPart < bPart ? -1 : 1;
-    }
-    return 0;
-}
-/** Read the PATH-visible `hl` package directly. Spawning `npm ls -g` here
- * makes every front-door boot pay for npm's global dependency-tree scan; a
- * linked development install can make that scan take many seconds. The real
- * executable points into the package for both ordinary and npm-linked installs,
- * so walking upward to its package.json is authoritative for the CLI crtr will
- * actually invoke. */
-export function globalHumanloopVersion() {
-    const executable = (process.env['PATH'] ?? '')
-        .split(delimiter)
-        .filter(Boolean)
-        .map((entry) => join(entry, 'hl'))
-        .find((candidate) => {
-        try {
-            accessSync(candidate, constants.X_OK);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    });
-    if (executable === undefined)
-        return null;
-    try {
-        let cursor = dirname(realpathSync(executable));
-        for (;;) {
-            const packageJsonPath = join(cursor, 'package.json');
-            if (existsSync(packageJsonPath)) {
-                const value = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-                const manifest = value;
-                if (manifest.name === '@crouton-kit/humanloop')
-                    return typeof manifest.version === 'string' ? manifest.version : null;
-            }
-            const parent = dirname(cursor);
-            if (parent === cursor)
-                return null;
-            cursor = parent;
-        }
-    }
-    catch {
-        return null;
-    }
-}
-export function globalHumanloopHealth() {
-    const bundledVersion = bundledHumanloopVersion();
-    const globalVersion = globalHumanloopVersion();
-    const comparison = bundledVersion !== null && globalVersion !== null
-        ? compareVersions(globalVersion, bundledVersion)
-        : null;
-    return { bundledVersion, globalVersion, current: comparison !== null && comparison >= 0 };
-}
-/** A non-fatal action-oriented diagnostic for a missing, unreadable, or stale
- * global `hl` executable. */
-export function globalHumanloopWarning() {
-    const { bundledVersion, globalVersion, current } = globalHumanloopHealth();
-    if (current)
-        return null;
-    const floor = bundledVersion ?? 'the bundled version';
-    const found = globalVersion === null ? 'missing or unprobeable' : globalVersion;
-    return `crtr: global \`hl\` CLI is ${found}; crouter requires at least bundled humanloop ${floor} for its inbox toggle.\n` +
-        `  Fix: run \`${GLOBAL_HUMANLOOP_INSTALL_COMMAND}\`.`;
-}
-export function globalHumanloopInstallCommand() {
-    return GLOBAL_HUMANLOOP_INSTALL_COMMAND;
+    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) {

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

@@ -1,4 +1,4 @@
-export { paneExists, paneLocation, paneOfNode, paneCurrentPath, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, breakPane, inTmux, piCommand, shellQuote, installTmuxBindings, renameWindow, displayPopup, windowOfPane, respawnPaneSync, respawnPaneInPlace, paneStartCommand, panePid, windowAlive, listLivePanes, } from './tmux.js';
+export { paneExists, paneLocation, paneOfNode, paneCurrentPath, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, breakPane, inTmux, piCommand, shellQuote, installTmuxBindings, renameWindow, displayPopup, windowOfPane, respawnPaneSync, respawnPaneInPlace, paneStartCommand, panePid, windowAlive, listLivePanes, VIEWER_STAMP_OPTION, stampViewerPaneAsync, liveViewerPanes, sendAttachControl, displayClientMessage, } from './tmux.js';
 /** The shared cold-start deadline (ms) a freshly-opened viewer waits for its
  *  broker's view.sock — one source of truth for the CRTR_ATTACH_WAIT_MS a viewer
  *  pane is handed. */
@@ -39,4 +39,5 @@ export declare function openViewerPane(nodeId: string, session: string, opts?: {
     cwd?: string;
     besidePane?: string;
     waitForBroker?: boolean;
+    initialWhip?: boolean;
 }): ViewerPane | null;

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

@@ -21,7 +21,7 @@ import { viewSocketPath } from '../canvas/paths.js';
 // Re-export the pure tmux driver verbs the CLI/viewer consumers need, so the
 // §5.1 lint's "only placement / tmux-chrome import tmux.ts" holds while these
 // modules never reach the canvas focuses table.
-export { paneExists, paneLocation, paneOfNode, paneCurrentPath, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, breakPane, inTmux, piCommand, shellQuote, installTmuxBindings, renameWindow, displayPopup, windowOfPane, respawnPaneSync, respawnPaneInPlace, paneStartCommand, panePid, windowAlive, listLivePanes, } from './tmux.js';
+export { paneExists, paneLocation, paneOfNode, paneCurrentPath, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, breakPane, inTmux, piCommand, shellQuote, installTmuxBindings, renameWindow, displayPopup, windowOfPane, respawnPaneSync, respawnPaneInPlace, paneStartCommand, panePid, windowAlive, listLivePanes, VIEWER_STAMP_OPTION, stampViewerPaneAsync, liveViewerPanes, sendAttachControl, displayClientMessage, } from './tmux.js';
 // ---------------------------------------------------------------------------
 // view.sock readiness — the one shared broker-cold-start primitive
 // ---------------------------------------------------------------------------
@@ -124,9 +124,11 @@ export function openViewerPane(nodeId, session, opts = {}) {
     // the pane instantly — the same self-polling bootRoot/resume rely on. The
     // deadline is the shared BROKER_VIEW_SOCKET_WAIT_MS (one source of truth), not
     // a literal duplicated at the call site.
-    const env = opts.waitForBroker === true
-        ? { ...viewerSplitEnv(), CRTR_ATTACH_WAIT_MS: String(BROKER_FOCUS_SOCKET_WAIT_MS) }
-        : viewerSplitEnv();
+    const env = {
+        ...viewerSplitEnv(),
+        ...(opts.waitForBroker === true ? { CRTR_ATTACH_WAIT_MS: String(BROKER_FOCUS_SOCKET_WAIT_MS) } : {}),
+        ...(opts.initialWhip === true ? { CRTR_ATTACH_INITIAL_WHIP: '1' } : {}),
+    };
     const cwd = opts.cwd ?? process.cwd();
     if (opts.besidePane !== undefined) {
         const pane = splitWindow(opts.besidePane, { cwd, env, command });

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

@@ -55,6 +55,7 @@ export declare function openViewerWindow(nodeId: string, session: string, opts?:
     cwd?: string;
     besidePane?: string;
     waitForBroker?: boolean;
+    initialWhip?: boolean;
 }): FocusRow | null;
 export declare function focus(nodeId: string, opts: {
     pane?: string;

package/dist/core/runtime/placement.js

@@ -44,14 +44,10 @@ import { isPidAlive } from '../canvas/pid.js';
 // `selectLayout` are FRESH minimal viewer-chrome helpers (not the deleted
 // engine-in-pane `breakPaneToSession`): `surface tmux-spread` breaks the caller's
 // viewer pane into its own window and tiles sibling viewers beside it.
-// `piCommand` + `paneCurrentPath` are KEPT: the sessionless surface-view system
-// (view-cycle.ts / view-run.ts) builds its pane commands with them, and the §5.1
-// import-lint forbids those commands importing tmux.ts directly — they must reach
-// the driver through placement. (They are NOT engine-in-pane; the design's
-// "nothing keeps" classification missed the view consumers.) `shellQuote` is
-// re-exported for the same reason — callers building the seam's expected
-// bundled-pi command string (e.g. the M1 seam test) need the identical quoting
-// piCommand uses internally, without importing tmux.ts directly.
+// `piCommand`, `paneCurrentPath`, and `shellQuote` remain available to command
+// modules that need to build or inspect tmux pane commands without importing
+// tmux.ts directly; the §5.1 lint keeps the raw driver behind this placement
+// boundary.
 export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, installTmuxBindings, 
 // Compile seam for viewer.ts, which still calls installMenuBinding();
 // deleted when the attach unit imports installTmuxBindings directly.

package/dist/core/runtime/promote.js

@@ -60,6 +60,9 @@ function reshapeNode(nodeId, opts = {}, beforePersist) {
         // choice — so carry the node's existing pin verbatim instead.
         modelProviderPinned: opts.model === undefined ? node.launch?.modelProviderPinned : undefined,
         modelIntent: opts.model === undefined ? node.launch?.modelIntent : undefined,
+        // Exact-model human-work forks must stay fail-closed after a polymorph.
+        // Dropping this bit produces a recipe reviveNode refuses to relaunch.
+        modelExact: opts.model === undefined ? node.launch?.modelExact : undefined,
         // Resolve kind/ladder config against the NODE's own cwd + profile, not
         // this process's ambient scope.
         cwd: node.cwd,

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

@@ -1,8 +1,3 @@
-/** Ask pi headlessly for a concise briefing of `conversation`, async. Invokes
- *  `onRecap` with the parsed string on success, or never (silent) on any
- *  failure — non-zero exit, timeout, empty/garbled output. Owns the subprocess
- *  mechanics — crucially it hands pi an immediate stdin EOF: `pi -p` reads stdin,
- *  and execFile's default stdin is an OPEN pipe that never closes, so without
- *  this pi blocks waiting for EOF and the call exits non-zero (the same gotcha
- *  naming.ts documents). */
+/** Ask Pi for a concise briefing of `conversation`. Invokes `onRecap` with
+ *  the parsed string on success, or never on timeout, empty, or garbled output. */
 export declare function generateRecap(conversation: string, onRecap: (briefing: string) => void, liveModel?: string, roadmap?: string): void;

package/dist/core/runtime/recap.js

@@ -1,22 +1,16 @@
 // Inactivity recap — turn a dormant node's conversation into one concise
 // returning-developer briefing for the recap widget.
 //
-// One entry point: generateRecap — async (execFile, non-blocking), mirroring
-// naming.ts's headless-`pi -p` pattern exactly. It runs the live conversation's
-// working model over the literal back-and-forth (the caller concatenates user and
-// assistant text, plus the node's roadmap when one exists) with a stripped-
-// down pi invocation (no tools/session/context/extensions/skills), so it's fast
-// and side-effect free and can never recurse into another spawn.
+// One entry point: generateRecap — async and non-blocking. It runs the live
+// conversation's working model over the literal back-and-forth (the caller
+// concatenates user and assistant text, plus the node's roadmap when one exists)
+// in an isolated one-shot with no tools or canvas resources.
 //
-// Best-effort and silent on failure: a non-zero exit, timeout, empty or garbled
-// output resolves to NO recap (the caller shows nothing). The recap is throwaway
-// idle chrome — there is no local fallback, unlike naming, because a wrong or
-// stale recap is worse than none.
-//
-// Plain TS-with-types — no imports from @earendil-works/* so it compiles inside
-// crouter's own tsc build without a dep on the pi packages.
-import { execFile } from 'node:child_process';
-import { bundledPiSubprocessEnv, resolveBundledPiCliPath } from './pi-cli.js';
+// Best-effort and silent on failure: timeout, empty, or garbled output resolves
+// to NO recap (the caller shows nothing). The recap is throwaway idle chrome —
+// there is no local fallback, unlike naming, because a wrong recap is worse than
+// none.
+import { headlessText } from './headless-pi.js';
 /** Wall-clock budget for the headless pi call before we give up (no recap). */
 const RECAP_TIMEOUT_MS = 25_000;
 /** Fallback model when the live session has not resolved one yet. Ordinarily the
@@ -62,37 +56,15 @@ function recapUserPrompt(conversation, roadmap) {
         : '';
     return `${rm}<conversation>\n${conversation}\n</conversation>\n\nWrite the two-line Goal:/State: briefing for the conversation above. Output JUST the two lines.`;
 }
-/** The pi argv for a headless recap request. Stripped down (no tools, session,
- *  context files, extensions, skills, templates, themes) so it's fast and
- *  side-effect free. Thinking stays off; model precedence is explicit env
- *  override → the conversation's live working model → the small fallback. */
-function recapArgs(conversation, liveModel, roadmap) {
+/** Model precedence is explicit env override → the conversation's live
+ *  working model → the small fallback. */
+function recapModel(liveModel) {
     const override = process.env['CRTR_RECAP_MODEL'];
-    // An explicit operator override wins. Otherwise prefer the live conversation's
-    // current model: it just completed a successful turn, while a hard-pinned
-    // provider (the old Haiku-only path) may be rate-limited and silently produce
-    // no brief. The small default remains for sessions with no resolved model yet.
-    const model = override !== undefined && override.trim() !== ''
-        ? override.trim()
-        : liveModel !== undefined && liveModel.trim() !== ''
-            ? liveModel.trim()
-            : DEFAULT_RECAP_MODEL;
-    const argv = [
-        '-p',
-        '--no-session',
-        '--no-context-files',
-        '--no-extensions',
-        '--no-skills',
-        '--no-prompt-templates',
-        '--no-themes',
-        '--no-tools',
-        '--mode', 'text',
-        '--thinking', 'off',
-        '--model', model,
-        '--system-prompt', RECAP_SYSTEM_PROMPT,
-        recapUserPrompt(conversation, roadmap),
-    ];
-    return argv;
+    if (override !== undefined && override.trim() !== '')
+        return override.trim();
+    if (liveModel !== undefined && liveModel.trim() !== '')
+        return liveModel.trim();
+    return DEFAULT_RECAP_MODEL;
 }
 /** Normalize model stdout to the two-line `Goal:`/`State:` briefing. Collapses
  *  intra-line whitespace and drops blank lines; the viewer paints each line
@@ -105,32 +77,26 @@ function parseRecap(stdout) {
         .filter((l) => l !== '')
         .join('\n');
 }
-/** Ask pi headlessly for a concise briefing of `conversation`, async. Invokes
- *  `onRecap` with the parsed string on success, or never (silent) on any
- *  failure — non-zero exit, timeout, empty/garbled output. Owns the subprocess
- *  mechanics — crucially it hands pi an immediate stdin EOF: `pi -p` reads stdin,
- *  and execFile's default stdin is an OPEN pipe that never closes, so without
- *  this pi blocks waiting for EOF and the call exits non-zero (the same gotcha
- *  naming.ts documents). */
+/** Ask Pi for a concise briefing of `conversation`. Invokes `onRecap` with
+ *  the parsed string on success, or never on timeout, empty, or garbled output. */
 export function generateRecap(conversation, onRecap, liveModel, roadmap) {
     const body = (conversation ?? '').trim();
     if (body === '')
         return;
-    try {
-        const child = execFile(process.execPath, [resolveBundledPiCliPath(), ...recapArgs(body, liveModel, roadmap)], { encoding: 'utf8', timeout: RECAP_TIMEOUT_MS, env: bundledPiSubprocessEnv() }, (err, stdout) => {
-            if (err || typeof stdout !== 'string')
-                return; // silent — no recap
-            const briefing = parseRecap(stdout);
-            if (briefing === '')
-                return;
-            try {
-                onRecap(briefing);
-            }
-            catch { /* best-effort */ }
-        });
-        child.stdin?.end(); // immediate EOF — see the doc above
-    }
-    catch {
-        // best-effort: no recap
-    }
+    void headlessText({
+        systemPrompt: RECAP_SYSTEM_PROMPT,
+        userPrompt: recapUserPrompt(body, roadmap),
+        modelSpec: recapModel(liveModel),
+        timeoutMs: RECAP_TIMEOUT_MS,
+    })
+        .then((reply) => {
+        const briefing = parseRecap(reply);
+        if (briefing === '')
+            return;
+        try {
+            onRecap(briefing);
+        }
+        catch { /* best-effort */ }
+    })
+        .catch(() => undefined);
 }

package/dist/core/runtime/revive.js

@@ -22,7 +22,7 @@
 // reviveNode remains the ONLY sanctioned launcher of the node engine.
 import { existsSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
-import { getNode, updateNode, clearPid, recordPid, fullName, subscribersOf, getHumanWorkRow, } from '../canvas/index.js';
+import { getNode, updateNode, clearPid, recordPid, fullName, subscribersOf, } from '../canvas/index.js';
 import { cancelCronsOnWake } from '../canvas/crons.js';
 import { transition } from './lifecycle.js';
 import { fanDoctrineWake } from './close.js';
@@ -35,6 +35,7 @@ import { boundFleet } from './fleet.js';
 import { clearFault, beginBootFaultAttempt } from './fault.js';
 import { clearInjectedDocs } from '../substrate/injected-store.js';
 import { rootOfSpine } from './nodes.js';
+import { isReviewCompanionBound } from '../review/companion.js';
 // ---------------------------------------------------------------------------
 // resumeArgs — which session source a revive resumes from
 // ---------------------------------------------------------------------------
@@ -63,15 +64,6 @@ export function resumeArgs(meta, resume) {
 // ---------------------------------------------------------------------------
 // Return type
 // ---------------------------------------------------------------------------
-function isHumanWorkTarget(value) {
-    if (value === null || typeof value !== 'object')
-        return false;
-    const target = value;
-    return ((target.work_kind === 'follow_up' || target.work_kind === 'visual') &&
-        typeof target.dir === 'string' && target.dir !== '' &&
-        typeof target.request_id === 'string' && target.request_id !== '' &&
-        typeof target.root === 'string' && target.root !== '');
-}
 /** A relaunch that has NO transcript to resume or branch from, and no durable
  *  work state on disk (no roadmap, no yield note), is not a revive at all — the
  *  node never got a conversation off the ground, so there is no "previous
@@ -106,11 +98,7 @@ export function reviveNode(nodeId, opts) {
     if (meta === null) {
         throw new Error(`reviveNode: unknown node ${nodeId}`);
     }
-    // Fresh durable snapshot immediately before the guard. A private fork's
-    // session_start hook may have atomically changed fork_pending →
-    // session_started since the caller's read; launching from a stale phase
-    // would fork provenance a second time instead of resuming the
-    // now-authoritative child session.
+    // 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
     // legitimate caller (node message send, node lifecycle revive) already checked this
@@ -153,70 +141,41 @@ export function reviveNode(nodeId, opts) {
         updateNode(nodeId, { host_kind: 'broker' });
         meta.host_kind = 'broker';
     }
-    // Private human-work forks have one explicit two-phase recipe. Before a
-    // child session is bound, every attempt MUST replay the same immutable
-    // `--fork` birth + kickoff regardless of the caller's requested resume mode.
-    // After bind, provenance is never a launch source again: recovery goes only
-    // through the recorded writable child session. The target + exact-model
-    // assertions make malformed partial claims fail closed rather than silently
-    // becoming an ordinary fresh node.
-    const privateForkPending = meta.private_fork_phase === 'fork_pending';
-    const privateForkStarted = meta.private_fork_phase === 'session_started';
-    const hasPrivateClaim = meta.human_work_target != null || meta.private_fork_phase != null || meta.private_fork_recipe != null;
-    if (hasPrivateClaim && !privateForkPending && !privateForkStarted) {
-        throw new Error(`reviveNode: private fork ${nodeId} has no recognized phase`);
-    }
-    if (privateForkPending || privateForkStarted) {
-        if (!isHumanWorkTarget(meta.human_work_target)) {
-            throw new Error(`reviveNode: private fork ${nodeId} has no recognized human_work_target`);
-        }
-        if (meta.private_fork_recipe == null || meta.private_fork_recipe.kickoff.trim() === '') {
-            throw new Error(`reviveNode: private fork ${nodeId} has no persisted kickoff recipe`);
-        }
-        if (meta.launch?.modelExact !== true || typeof meta.launch.model !== 'string' || meta.launch.model.trim() === '') {
-            throw new Error(`reviveNode: private fork ${nodeId} has no exact persisted model`);
-        }
-    }
-    if (privateForkPending) {
-        // A Visual child is deliberately born inert. Its start handler rechecks
-        // Humanloop after persisting the node, then this locked gate consumes the
-        // still-armed claim immediately before launch. A cancel changes the claim
-        // to visual_retired before it can acknowledge, so it can never wake a
-        // canceled fork after the fact.
-        const work = getHumanWorkRow(nodeId);
-        const expectedStatus = meta.human_work_target.work_kind === 'visual' ? 'visual_armed' : 'armed';
-        if (work === null || work.work_kind !== meta.human_work_target.work_kind || work.status !== expectedStatus) {
-            throw new Error(`reviveNode: private fork ${nodeId} is no longer launchable`);
-        }
-        if (typeof meta.fork_from !== 'string' || !isAbsolute(meta.fork_from)) {
-            throw new Error(`reviveNode: pending private fork ${nodeId} requires an absolute fork_from provenance file`);
-        }
-        if (meta.pi_session_id != null || meta.pi_session_file != null) {
-            throw new Error(`reviveNode: pending private fork ${nodeId} cannot already have a bound child session`);
-        }
+    // A review companion's session coordinates are valid only after its durable
+    // visible boundary. Detach any markerless child so this launch replays the
+    // immutable fork instead of resuming an inherited transcript.
+    const reviewCompanionUnbound = meta.review_binding != null && !isReviewCompanionBound(nodeId);
+    if (reviewCompanionUnbound && (meta.pi_session_id != null || meta.pi_session_file != null)) {
+        updateNode(nodeId, { pi_session_id: null, pi_session_file: null });
+        meta.pi_session_id = null;
+        meta.pi_session_file = null;
     }
-    if (privateForkStarted) {
-        if (typeof meta.pi_session_id !== 'string' || meta.pi_session_id === '' ||
-            typeof meta.pi_session_file !== 'string' || meta.pi_session_file === '' ||
-            !existsSync(meta.pi_session_file)) {
-            throw new Error(`reviveNode: bound private fork ${nodeId} requires its recorded child session file`);
-        }
+    // An ordinary fork remains a birth until session_start records the child
+    // session. Replaying the immutable branch on every pre-bind retry prevents a
+    // crash from silently turning it into a fresh conversation.
+    const forkBirthPending = typeof meta.fork_from === 'string' &&
+        isAbsolute(meta.fork_from) &&
+        meta.pi_session_id == null;
+    if (forkBirthPending && !existsSync(meta.fork_from)) {
+        throw new InputError({
+            error: 'fork_from_missing',
+            message: `${nodeId} cannot be revived — its fork source no longer exists: ${meta.fork_from}`,
+            next: `Restore ${meta.fork_from}, or update the node's fork source, then retry \`crtr node lifecycle revive ${nodeId}\`.`,
+        });
     }
     // Every (re)launch is a new cycle — bump the counter so CRTR_CYCLES and the
     // footer stay in sync. Mutate the in-memory meta too so buildPiArgv below
     // launches with the incremented count.
     meta.cycles = (meta.cycles ?? 0) + 1;
     updateNode(nodeId, { cycles: meta.cycles });
-    // Ordinary nodes choose resume/cycle/fresh from their recorded session. A
-    // pending private fork deliberately has no child session yet and takes the
-    // dedicated immutable birth branch below instead. Persisted pending-refresh
-    // state (durable across a pre-session_start crash-retry) outranks a caller's
-    // strict-resume request; a bound private fork's forced resume outranks both.
-    // resumeArgs then selects only an existing absolute session path: strict
+    // Ordinary nodes choose resume/cycle/fresh from their recorded session.
+    // Persisted pending-refresh state (durable across a pre-session_start
+    // crash-retry) outranks a caller's strict-resume request. resumeArgs then
+    // selects only an existing absolute session path: strict
     // resume continues its leaf, while fresh/cycle mode roots a new one.
     const refreshPending = meta.intent === 'refresh' || meta.cycle_pending === true;
-    const effectiveResume = privateForkStarted ? true : (refreshPending ? false : opts.resume);
-    const resume = privateForkPending ? {} : resumeArgs(meta, effectiveResume);
+    const effectiveResume = refreshPending ? false : opts.resume;
+    const resume = forkBirthPending ? {} : resumeArgs(meta, effectiveResume);
     // hasSessionPath: there is a real `.jsonl` to hand pi via `--session`, whether
     // as a true resume OR a cycling refresh-yield (resumeArgs sets `newCycle` in
     // the latter case). cycling and resuming are mutually exclusive; `resuming`
@@ -231,7 +190,7 @@ export function reviveNode(nodeId, opts) {
     const cyclePending = meta.cycle_pending === true || cycling;
     updateNode(nodeId, { cycle_pending: cyclePending });
     meta.cycle_pending = cyclePending;
-    // A truly fresh ordinary launch — no `.jsonl` to resume OR cycle from —
+    // A truly fresh launch — no `.jsonl` to resume OR cycle from —
     // starts a NEW pi session, so the old session identity is dead. Clear it from meta NOW,
     // before launch, so the recorded state matches what we're about to do. This
     // is load-bearing for exit-policy classification (classifyDeadNode row 8):
@@ -243,7 +202,7 @@ export function reviveNode(nodeId, opts) {
     // are exactly what's being reused — so a cycling broker that dies
     // pre-session_start classifies as a retryable respawn, same class as a
     // resume revive.
-    if (!privateForkPending && !hasSessionPath && (meta.pi_session_id != null || meta.pi_session_file != null)) {
+    if (!forkBirthPending && !hasSessionPath && (meta.pi_session_id != null || meta.pi_session_file != null)) {
         updateNode(nodeId, { pi_session_id: null, pi_session_file: null });
         meta.pi_session_id = null;
         meta.pi_session_file = null;
@@ -256,14 +215,12 @@ export function reviveNode(nodeId, opts) {
     // unchanged (empty for true-fresh, both set for cycling) so buildPiArgv emits
     // the right argv either way.
     let inv;
-    if (privateForkPending) {
+    if (forkBirthPending) {
+        const goal = readGoal(nodeId);
         inv = buildPiArgv(meta, {
-            prompt: meta.private_fork_recipe.kickoff,
             forkFrom: meta.fork_from,
+            ...(goal != null && goal !== '' ? { prompt: goal } : {}),
         });
-        // A fork birth creates a new LLM context just like an ordinary fresh
-        // launch; retries before bind must not inherit an injected-doc cache from
-        // a failed process.
         clearInjectedDocs(nodeId);
     }
     else if (resuming) {

package/dist/core/runtime/session-cycles.d.ts

@@ -20,6 +20,10 @@ export interface CycleSessionManagerLike {
      *  path root-first. */
     getBranch?(fromId?: string): SessionEntry[];
 }
+/** A refresh-yield deliberately aborts its own turn before the next cycle is
+ * rooted. Preserve that assistant message (including tool calls and prose), but
+ * omit the failure annotation: the cycle divider is the truthful visible seam. */
+export declare function withoutYieldAbort(message: SnapshotMessage): SnapshotMessage;
 /** The full multi-cycle message history for display: prior cycles (oldest
  *  first, each closed by a divider), then the live cycle's context. Falls back
  *  to plain `buildSessionContext()` when the session has no cycle markers, when

package/dist/core/runtime/session-cycles.js

@@ -32,6 +32,19 @@ function cycleDivider(cycle, timestamp) {
         timestamp: new Date(timestamp).getTime(),
     };
 }
+/** A refresh-yield deliberately aborts its own turn before the next cycle is
+ * rooted. Preserve that assistant message (including tool calls and prose), but
+ * omit the failure annotation: the cycle divider is the truthful visible seam. */
+export function withoutYieldAbort(message) {
+    if (message.role !== 'assistant' || message.stopReason !== 'aborted')
+        return message;
+    const { stopReason: _stopReason, errorMessage: _errorMessage, ...visible } = message;
+    return visible;
+}
+function priorCycleMessages(messages) {
+    const last = messages.at(-1);
+    return last === undefined ? messages : [...messages.slice(0, -1), withoutYieldAbort(last)];
+}
 /** The full multi-cycle message history for display: prior cycles (oldest
  *  first, each closed by a divider), then the live cycle's context. Falls back
  *  to plain `buildSessionContext()` when the session has no cycle markers, when
@@ -68,7 +81,7 @@ export function cycleAwareMessages(sm) {
             // builder — preserving compaction semantics (one compactionSummary +
             // kept + post-compaction messages only) exactly like the live cycle
             // below.
-            out.push(...buildSessionContext(entries, fromLeaf, byId).messages);
+            out.push(...priorCycleMessages(buildSessionContext(entries, fromLeaf, byId).messages));
         }
         out.push(cycleDivider(marker.data?.cycle, marker.timestamp));
     }

package/dist/core/runtime/session-visibility.d.ts

@@ -0,0 +1,37 @@
+import type { BrokerSnapshot, WireSessionTreeNode } from './broker-protocol.js';
+/** customType of the crtr-authored boundary marker that opens a review
+ *  companion's visible transcript. Data payload: `{ reviewId, originNodeId,
+ *  targetFile }` — per-review facts that complement the inheritance prefix.
+ *
+ *  The marker itself is a crtr-rendered divider shown to the person; everything
+ *  above it in the inherited session is context they cannot see.
+ */
+export declare const REVIEW_BOUNDARY_CUSTOM_TYPE = "crtr-review-boundary";
+/** True when an entry is a durable review boundary, optionally for one review. */
+export declare function isReviewBoundary(entry: unknown, reviewId?: string): boolean;
+/**
+ * Project snapshot messages to the visible window for a review companion.
+ *
+ * Contract (in evaluation order):
+ * 1. Marker present → slice from the **first** occurrence (marker included) to
+ *    the end. Everything before the marker is inherited context, hidden from
+ *    the person.
+ * 2. Not a review companion → return input unchanged (same reference). Ordinary
+ *    nodes are not filtered.
+ * 3. No marker and review companion → a leading compaction summary is replaced
+ *    with a synthetic boundary while its retained tail remains visible. Every
+ *    other markerless shape fails closed with the synthetic boundary alone.
+ */
+export declare function visibleMessages(messages: BrokerSnapshot['messages'], opts: {
+    reviewCompanion: boolean;
+}): BrokerSnapshot['messages'];
+/**
+ * Project a session tree to the review companion's visible transcript boundary.
+ *
+ * Pre-boundary ancestors are omitted rather than retained as empty structural
+ * shells, making each durable boundary a root in the returned forest. Once a
+ * boundary is crossed, its complete descendant subtree remains navigable. An
+ * absent boundary produces an empty tree, so picker previews never disclose an
+ * inherited entry before a mutation guard can reject its selection.
+ */
+export declare function boundaryRootedTree(tree: readonly WireSessionTreeNode[]): WireSessionTreeNode[];