@crouton-kit/crouter 0.3.40 → 0.3.41

package/dist/core/runtime/launch.js

@@ -3,8 +3,9 @@
 // pi-only. No claude branch — we are a super-opinionated system. A node's
 // LaunchSpec (persisted in meta.json) is the canonical recipe the daemon
 // replays to revive it faithfully: `--session <path>` (the saved conversation's
-// absolute .jsonl) to wake a done/idle node, or fresh (against the context dir)
-// for a refresh-yield.
+// absolute .jsonl) to wake a done/idle node — a refresh-yield reuses the SAME
+// path plus `--crtr-new-cycle`, resetting the session tree's leaf and rooting a
+// fresh cycle as a new branch rather than starting a new file.
 // The spec is rewritten on every polymorph (base→orchestrator) so a node
 // always comes back as its *current* self.
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
@@ -102,6 +103,7 @@ const STRENGTH_ALIASES = {
 };
 const MODEL_PROVIDER_KEYS = ['anthropic', 'openai'];
 const MODEL_STRENGTHS = ['ultra', 'strong', 'medium', 'light'];
+const MODEL_STRENGTH_RANK = { light: 0, medium: 1, strong: 2, ultra: 3 };
 const THINKING_SUFFIXES = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh']);
 function stripThinkingSuffix(spec) {
     const i = spec.lastIndexOf(':');
@@ -141,6 +143,49 @@ export function equivalentOtherProviderModel(currentModel, failedProviders = new
  *   3. Bare family alias (opus/sonnet/haiku) → the Anthropic ladder's
  *      strong/medium/light, ALWAYS anthropic (ignores the env/config default).
  *   4. Anything else → pass through unchanged. */
+function modelTokenStrength(model) {
+    const rest = model.includes('/') ? model.slice(model.indexOf('/') + 1) : model;
+    const strength = STRENGTH_ALIASES[rest];
+    if (strength !== undefined)
+        return strength;
+    if (rest === 'opus')
+        return 'strong';
+    if (rest === 'sonnet')
+        return 'medium';
+    if (rest === 'haiku')
+        return 'light';
+    return null;
+}
+function resolvedModelStrength(model) {
+    const tokenStrength = modelTokenStrength(model);
+    if (tokenStrength !== null)
+        return tokenStrength;
+    const ladders = modelLadders();
+    const comparable = stripThinkingSuffix(normalizeModel(model));
+    for (const provider of MODEL_PROVIDER_KEYS) {
+        for (const strength of MODEL_STRENGTHS) {
+            if (stripThinkingSuffix(ladders[provider][strength]) === comparable)
+                return strength;
+        }
+    }
+    return null;
+}
+function isReviewQualityKind(kind) {
+    return kind === 'review' || kind.startsWith('plan/reviewers/');
+}
+function floorReviewModel(kind, requestedModel, kindModel) {
+    if (requestedModel === undefined)
+        return kindModel;
+    if (!isReviewQualityKind(kind) || kindModel === undefined)
+        return requestedModel;
+    const requestedStrength = resolvedModelStrength(requestedModel);
+    const floorStrength = resolvedModelStrength(kindModel);
+    if (requestedStrength === null || floorStrength === null)
+        return requestedModel;
+    return MODEL_STRENGTH_RANK[requestedStrength] < MODEL_STRENGTH_RANK[floorStrength]
+        ? kindModel
+        : requestedModel;
+}
 export function normalizeModel(model) {
     const ladders = modelLadders();
     // 1. Qualified provider/rest.
@@ -201,7 +246,7 @@ export const LAUNCH_SYSTEM_PROMPT = 'You are a node in the crtr canvas — an ag
 export function buildLaunchSpec(kind, mode, opts) {
     const kindConfig = resolveKindConfig(kind);
     const kindModel = mode === 'orchestrator' ? kindConfig?.orchestratorModel ?? kindConfig?.model : kindConfig?.model;
-    const chosenModel = opts.model ?? kindModel;
+    const chosenModel = floorReviewModel(kind, opts.model, kindModel);
     const launch = {
         model: chosenModel !== undefined ? normalizeModel(chosenModel) : undefined,
         tools: kindConfig?.tools ?? [],
@@ -243,7 +288,11 @@ function writeSystemPromptFile(nodeId, prompt) {
  *    `headlessBrokerHost`'s preflight (host.ts) fatally rejects a bare
  *    `--session` id before ever spawning the broker, so a real revive only
  *    ever resumes by path (or falls through to fresh when no path exists).
- *  - refresh-yield: fresh again (no resume) — the node re-reads its roadmap. */
+ *  - refresh-yield: same `.jsonl` (`resumeSessionPath`) PLUS `newCycle` —
+ *    emits the valueless `--crtr-new-cycle` token alongside `--session`. The
+ *    broker resets the session-tree leaf and roots the new cycle as a fresh
+ *    sibling branch instead of starting a new file; the node re-reads its
+ *    roadmap exactly as a fresh launch would. */
 export function buildPiArgv(meta, opts = {}) {
     const spec = meta.launch;
     const argv = [];
@@ -272,6 +321,8 @@ export function buildPiArgv(meta, opts = {}) {
         const resumeArg = opts.resumeSessionPath ?? opts.resumeSessionId;
         if (resumeArg !== undefined)
             argv.push('--session', resumeArg);
+        if (opts.newCycle === true)
+            argv.push('--crtr-new-cycle');
     }
     if (spec?.model !== undefined)
         argv.push('--model', spec.model);
@@ -341,6 +392,9 @@ export function piInvocationToSdkConfig(inv) {
             case '--append-system-prompt':
                 cfg.appendSystemPromptPath = argv[++i];
                 break;
+            case '--crtr-new-cycle':
+                cfg.newCycle = true;
+                break;
             default:
                 // buildPiArgv consumes every flag's value via the cases above, so any
                 // token reaching here is the single trailing positional (the prompt).

package/dist/core/runtime/naming.js

@@ -17,6 +17,7 @@
 // prompt, so a node always gets a sane name.
 import { execFile } from 'node:child_process';
 import { getNode, updateNode } from '../canvas/index.js';
+import { resolveBundledPiCliPath } from './pi-cli.js';
 /** Cap on prompt text fed to the namer — a name needs only the gist. */
 const PROMPT_CAP = 2000;
 /** Wall-clock budget for the headless pi call before we fall back to a slug. */
@@ -106,7 +107,7 @@ function nameArgs(prompt) {
 function headlessName(body) {
     return new Promise((resolve) => {
         try {
-            const child = execFile('pi', nameArgs(body), { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
+            const child = execFile(process.execPath, [resolveBundledPiCliPath(), ...nameArgs(body)], { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
                 if (err || typeof stdout !== 'string')
                     return resolve('');
                 resolve(sanitizeSessionName(stdout));
@@ -187,7 +188,7 @@ export function generateIssueTitle(note) {
         return Promise.resolve('untitled');
     return new Promise((resolve) => {
         try {
-            const child = execFile('pi', piTextArgs(TITLE_SYSTEM_PROMPT, titleUserPrompt(body)), { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
+            const child = execFile(process.execPath, [resolveBundledPiCliPath(), ...piTextArgs(TITLE_SYSTEM_PROMPT, titleUserPrompt(body))], { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
                 if (err || typeof stdout !== 'string')
                     return resolve(firstLineTitle(body));
                 const t = stdout.trim().split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';

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

@@ -1,4 +1,4 @@
-import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec } from '../canvas/index.js';
+import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec, type ManagedWorktree } from '../canvas/index.js';
 /** Generate a node id in the same shape as job ids (time-sortable + random). */
 export declare function newNodeId(): string;
 /** The root of a node's spine: walk the `parent` column up to `parent == null`.
@@ -54,6 +54,8 @@ export interface SpawnNodeOpts {
      *  resolve/validate the operand (via `loadProfileManifest`) before it reaches
      *  here; this layer just persists the already-resolved id. */
     profile_id?: string | null;
+    /** Managed worktree already created for this node, if any. */
+    managedWorktree?: ManagedWorktree;
     /** Override the generated id (e.g. when a caller pre-allocates one). */
     nodeId?: string;
 }

package/dist/core/runtime/nodes.js

@@ -124,6 +124,7 @@ export function spawnNode(opts) {
         fork_from: opts.forkFrom,
         model_override: opts.modelOverride ?? null,
         passive_default: opts.passiveDefault ?? false,
+        ...(opts.managedWorktree !== undefined ? { managed_worktree: opts.managedWorktree } : {}),
         intent: null,
         pi_session_id: null,
         pi_session_file: null,

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

@@ -0,0 +1,2 @@
+export declare function resolveBundledPiCliPath(): string;
+export declare function bundledPiCommandForShell(quote: (value: string) => string): string;

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

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function findPackageRootFromEntry(entryPath, expectedName) {
+    let dir = dirname(entryPath);
+    const root = parse(dir).root;
+    while (true) {
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                if (pkg.name === expectedName)
+                    return dir;
+            }
+            catch {
+                return null;
+            }
+        }
+        if (dir === root)
+            return null;
+        dir = dirname(dir);
+    }
+}
+export function resolveBundledPiCliPath() {
+    const packageName = '@earendil-works/pi-coding-agent';
+    let entryPath;
+    try {
+        entryPath = fileURLToPath(import.meta.resolve(packageName));
+    }
+    catch (error) {
+        throw new Error(`crouter install is missing bundled ${packageName}; reinstall @crouton-kit/crouter. ${error.message}`);
+    }
+    const packageRoot = findPackageRootFromEntry(entryPath, packageName);
+    if (packageRoot === null) {
+        throw new Error(`could not locate bundled ${packageName} package root from ${entryPath}`);
+    }
+    const pkgPath = join(packageRoot, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const bin = pkg.bin && typeof pkg.bin === 'object' ? pkg.bin.pi : undefined;
+    if (typeof bin !== 'string' || bin.trim() === '') {
+        throw new Error(`bundled ${packageName} does not declare a pi binary in ${pkgPath}`);
+    }
+    const cliPath = join(packageRoot, bin);
+    if (!existsSync(cliPath)) {
+        throw new Error(`bundled pi binary is missing at ${cliPath}`);
+    }
+    return cliPath;
+}
+export function bundledPiCommandForShell(quote) {
+    return `${quote(process.execPath)} ${quote(resolveBundledPiCliPath())}`;
+}

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

@@ -1,6 +1,6 @@
 import { type FocusRow } from '../canvas/index.js';
 export type { FocusRow };
-export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, installMenuBinding, setPaneOption, getPaneOption, piCommand, respawnPaneSync, closePane, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, installMenuBinding, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
 export type { RespawnPaneOpts } from './tmux.js';
 /** The viewer a node has on screen, or null. UNIQUE(node_id) ⇒ at most one. */
 export declare function focusOf(nodeId: string): FocusRow | null;

package/dist/core/runtime/placement.js

@@ -44,8 +44,11 @@ import { isPidAlive } from '../canvas/pid.js';
 // (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.)
-export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, installMenuBinding, setPaneOption, getPaneOption, piCommand, respawnPaneSync, closePane, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
+// "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.
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, installMenuBinding, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
 // ---------------------------------------------------------------------------
 // Viewer registry reads — COMPOSE over the canvas focuses table (§2.3/§4).
 //

package/dist/core/runtime/recap.js

@@ -15,6 +15,7 @@
 // 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 { resolveBundledPiCliPath } from './pi-cli.js';
 /** Wall-clock budget for the headless pi call before we give up (no recap). */
 const RECAP_TIMEOUT_MS = 25_000;
 /** Default recap model — Haiku. A recap is a one-shot summarization, so we pin
@@ -88,7 +89,7 @@ export function generateRecap(conversation, onRecap) {
     if (body === '')
         return;
     try {
-        const child = execFile('pi', recapArgs(body), { encoding: 'utf8', timeout: RECAP_TIMEOUT_MS }, (err, stdout) => {
+        const child = execFile(process.execPath, [resolveBundledPiCliPath(), ...recapArgs(body)], { encoding: 'utf8', timeout: RECAP_TIMEOUT_MS }, (err, stdout) => {
             if (err || typeof stdout !== 'string')
                 return; // silent — no recap
             const lines = parseRecap(stdout);

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

@@ -1,21 +1,25 @@
 import { type NodeMeta } from '../canvas/index.js';
 import type { WakeOrigin } from './bearings.js';
 import { headlessBrokerHost } from './host.js';
-/** Pick the `--session` source for a revive. resume=true resumes by the
- *  absolute session-file path (immune to cwd; pi opens it directly) — but ONLY
- *  when that file actually exists on disk. A node's `pi_session_file` can be
- *  recorded in meta with nothing ever written there (e.g. its first-boot engine
- *  died before session_start ever ran), and `headlessBrokerHost.launch`'s
- *  preflight (host.ts) fatally rejects handing pi a `--session` for a missing
- *  path OR a bare id — either would crash the revive and strand the node dead
- *  with nothing to recover it. So when there is no real `.jsonl` to resume,
- *  this selects NEITHER source: the caller then falls through to a fresh
- *  (`--fresh`-equivalent) launch, which is always safe. resume=false (a
- *  refresh-yield) also selects neither — the node re-reads its roadmap fresh.
- *  Pure so the decision is unit-testable without tmux or a real filesystem
- *  fixture beyond a temp file. */
+/** Pick the `--session` source for a revive. Both resume=true (a true resume)
+ *  and resume=false (a refresh-yield) resume by the absolute session-file path
+ *  (immune to cwd; pi opens it directly) — but ONLY when that file actually
+ *  exists on disk. A node's `pi_session_file` can be recorded in meta with
+ *  nothing ever written there (e.g. its first-boot engine died before
+ *  session_start ever ran), and `headlessBrokerHost.launch`'s preflight
+ *  (host.ts) fatally rejects handing pi a `--session` for a missing path OR a
+ *  bare id — either would crash the revive and strand the node dead with
+ *  nothing to recover it. So when there is no real `.jsonl` to resume, this
+ *  selects NEITHER source regardless of `resume`: the caller then falls
+ *  through to a truly fresh (`--fresh`-equivalent) launch, which is always
+ *  safe. The only difference between the two `resume` values (when the file
+ *  DOES exist) is `newCycle`: resume=false additionally roots a fresh cycle
+ *  branch (`--crtr-new-cycle`) rather than continuing the existing leaf. Pure
+ *  so the decision is unit-testable without tmux or a real filesystem fixture
+ *  beyond a temp file. */
 export declare function resumeArgs(meta: NodeMeta, resume: boolean): {
     resumeSessionPath?: string;
+    newCycle?: boolean;
 };
 export interface ReviveResult {
     /** Always null — the broker engine is never placed in a tmux window. Kept on
@@ -24,8 +28,10 @@ export interface ReviveResult {
     /** The node's last live LOCATION session, or null — the broker engine has no
      *  tmux session of its own (it opens no viewer). Kept for caller back-compat. */
     session: string | null;
-    /** True when pi was instructed to resume its saved conversation by its
-     *  absolute session-file path (`--session <path>`). */
+    /** True only for a TRUE resume — pi replays the saved conversation history
+     *  from its absolute session-file path. False for a fresh launch AND for an
+     *  in-place cycle (which also passes `--session <path>`, but to open a new
+     *  branch rather than replay the old one). */
     resumed: boolean;
     /** Launch handle for the detached broker, so callers can fail fast on its real
      *  exit before the socket appears. */

package/dist/core/runtime/revive.js

@@ -13,11 +13,17 @@
 //                  absolute session-file path (cwd-immune), but only when that
 //                  file actually exists on disk; otherwise falls through to a
 //                  fresh launch (see resumeArgs).
-//   resume=false → fresh pi invocation — the node re-reads its roadmap/context dir.
+//   resume=false → a refresh-yield. When the node's `.jsonl` already exists,
+//                  this REUSES it — `pi --session <path> --crtr-new-cycle` —
+//                  resetting the session-tree leaf and rooting the new cycle
+//                  as a fresh sibling branch, so the node re-reads its
+//                  roadmap/context dir against a clean LLM context while every
+//                  cycle still lives in one session file. Only a node with no
+//                  `.jsonl` yet gets a truly fresh pi invocation.
 //
 // reviveNode remains the ONLY sanctioned launcher of the node engine.
 import { existsSync } from 'node:fs';
-import { getNode, updateNode, clearPid, fullName, cancelDeadlinesFor, subscribersOf, } from '../canvas/index.js';
+import { getNode, updateNode, clearPid, recordPid, fullName, cancelDeadlinesFor, subscribersOf, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { fanDoctrineWake } from './close.js';
 import { buildPiArgv } from './launch.js';
@@ -30,27 +36,27 @@ import { clearInjectedDocs } from '../substrate/injected-store.js';
 // ---------------------------------------------------------------------------
 // resumeArgs — which session source a revive resumes from
 // ---------------------------------------------------------------------------
-/** Pick the `--session` source for a revive. resume=true resumes by the
- *  absolute session-file path (immune to cwd; pi opens it directly) — but ONLY
- *  when that file actually exists on disk. A node's `pi_session_file` can be
- *  recorded in meta with nothing ever written there (e.g. its first-boot engine
- *  died before session_start ever ran), and `headlessBrokerHost.launch`'s
- *  preflight (host.ts) fatally rejects handing pi a `--session` for a missing
- *  path OR a bare id — either would crash the revive and strand the node dead
- *  with nothing to recover it. So when there is no real `.jsonl` to resume,
- *  this selects NEITHER source: the caller then falls through to a fresh
- *  (`--fresh`-equivalent) launch, which is always safe. resume=false (a
- *  refresh-yield) also selects neither — the node re-reads its roadmap fresh.
- *  Pure so the decision is unit-testable without tmux or a real filesystem
- *  fixture beyond a temp file. */
+/** Pick the `--session` source for a revive. Both resume=true (a true resume)
+ *  and resume=false (a refresh-yield) resume by the absolute session-file path
+ *  (immune to cwd; pi opens it directly) — but ONLY when that file actually
+ *  exists on disk. A node's `pi_session_file` can be recorded in meta with
+ *  nothing ever written there (e.g. its first-boot engine died before
+ *  session_start ever ran), and `headlessBrokerHost.launch`'s preflight
+ *  (host.ts) fatally rejects handing pi a `--session` for a missing path OR a
+ *  bare id — either would crash the revive and strand the node dead with
+ *  nothing to recover it. So when there is no real `.jsonl` to resume, this
+ *  selects NEITHER source regardless of `resume`: the caller then falls
+ *  through to a truly fresh (`--fresh`-equivalent) launch, which is always
+ *  safe. The only difference between the two `resume` values (when the file
+ *  DOES exist) is `newCycle`: resume=false additionally roots a fresh cycle
+ *  branch (`--crtr-new-cycle`) rather than continuing the existing leaf. Pure
+ *  so the decision is unit-testable without tmux or a real filesystem fixture
+ *  beyond a temp file. */
 export function resumeArgs(meta, resume) {
-    if (!resume)
-        return {};
     const path = meta.pi_session_file;
-    if (path != null && path !== '' && existsSync(path)) {
-        return { resumeSessionPath: path };
-    }
-    return {};
+    if (path == null || path === '' || !existsSync(path))
+        return {};
+    return resume ? { resumeSessionPath: path } : { resumeSessionPath: path, newCycle: true };
 }
 // ---------------------------------------------------------------------------
 // reviveNode
@@ -99,44 +105,71 @@ export function reviveNode(nodeId, opts) {
     // launches with the incremented count.
     meta.cycles = (meta.cycles ?? 0) + 1;
     updateNode(nodeId, { cycles: meta.cycles });
-    // Decide whether to wake the saved pi conversation or start fresh. resumeArgs
-    // resumes ONLY by the absolute session-file path (cwd-immune) and ONLY when
-    // that .jsonl actually exists; there is no bare-id fallback (the broker
-    // preflight rejects a bare `--session`). Anything else is a fresh launch.
+    // Decide whether to wake the saved pi conversation, cycle it in place (a
+    // refresh-yield reusing the same `.jsonl`), or start fresh. resumeArgs
+    // resumes/cycles ONLY by the absolute session-file path (cwd-immune) and ONLY
+    // when that .jsonl actually exists; there is no bare-id fallback (the broker
+    // preflight rejects a bare `--session`). No file on disk yet ⇒ a fresh launch.
     const resume = resumeArgs(meta, opts.resume);
-    const resuming = resume.resumeSessionPath !== undefined;
-    // A fresh (non-resuming) launch starts a NEW pi session — 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 boot-failure
-    // classification: if this fresh broker dies BEFORE session_start (recording
-    // no new pid and no new session), the daemon's pid-null branch keys on
-    // pi_session_id — a leftover stale id would be misread as a "stranded
-    // relaunch" and retried forever instead of surfaced via transition('crash') +
-    // surfaceBootFailure. Clearing it makes the failure show as pid=NULL +
-    // session=NULL → boot failure, the correct terminal outcome.
-    if (!resuming && (meta.pi_session_id != null || meta.pi_session_file != null)) {
+    // 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`
+    // keeps the STRICT true-resume-only meaning `ReviveResult.resumed` and the
+    // launch-placement hint below have always carried.
+    const hasSessionPath = resume.resumeSessionPath !== undefined;
+    const cycling = hasSessionPath && resume.newCycle === true;
+    const resuming = hasSessionPath && !cycling;
+    // Mirror THIS launch attempt's cycling-ness durably, BEFORE launching, so a
+    // pre-session_start crash-retry (crtrd.ts) can tell "was the attempt I'm
+    // retrying a cycle" apart from an ordinary resume/crash. Cleared by
+    // canvas-stophook's session_start handler the instant this boot is confirmed.
+    // Written unconditionally (true for cycling, false otherwise) so it never
+    // goes stale across launch kinds.
+    updateNode(nodeId, { cycle_pending: cycling });
+    meta.cycle_pending = cycling;
+    // 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 boot-failure classification: if this fresh broker dies
+    // BEFORE session_start (recording no new pid and no new session), the
+    // daemon's pid-null branch keys on pi_session_id — a leftover stale id would
+    // be misread as a "stranded relaunch" and retried forever instead of surfaced
+    // via transition('crash') + surfaceBootFailure. Clearing it makes the failure
+    // show as pid=NULL + session=NULL → boot failure, the correct terminal
+    // outcome. A cycling refresh keeps BOTH ids — the `.jsonl` and its recorded
+    // session id are exactly what's being reused — so a cycling broker that dies
+    // pre-session_start reads as a "stranded relaunch" and is retried, same class
+    // as a resume revive today.
+    if (!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;
     }
-    // A fresh revive (no resume) gets a kickoff prompt so it re-reads its roadmap
-    // and continues; resuming a saved conversation needs none. drainBearings is the
-    // one-shot consuming step (yield note + feed cursor + persona ack); the builder
-    // is then pure.
+    // A true resume needs no kickoff — the saved conversation just continues. A
+    // fresh revive OR a cycling refresh-yield both get one so the (re-rooted)
+    // window re-reads its roadmap and continues: drainBearings is the one-shot
+    // consuming step (yield note + feed cursor + persona ack); the builder is
+    // then pure. `resume` carries `resumeSessionPath`/`newCycle` through
+    // unchanged (empty for true-fresh, both set for cycling) so buildPiArgv emits
+    // the right argv either way.
     let inv;
     if (resuming) {
         inv = buildPiArgv(meta, resume);
     }
     else {
-        // A fresh revive: drain the one-shot bearings, then build the kickoff. When
-        // a scheduled bare self-alarm drove this revive, opts.wakeReason carries the
-        // wake provenance so the kickoff leads with a <crtr-wake> block ("a timer
-        // woke you"); every other reviveNode caller passes nothing → no block.
+        // Fresh or cycling: drain the one-shot bearings, then build the kickoff.
+        // When a scheduled bare self-alarm drove this revive, opts.wakeReason
+        // carries the wake provenance so the kickoff leads with a <crtr-wake> block
+        // ("a timer woke you"); every other reviveNode caller passes nothing → no
+        // block.
         const bearings = drainBearings(meta);
-        inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta, bearings, opts.wakeReason) });
-        // Fresh (no-resume) revive starts a NEW transcript — reset the on-read doc
-        // dedup so the new conversation surfaces docs from scratch (a resume below
-        // would instead KEEP the persisted set, continuing the same transcript).
+        inv = buildPiArgv(meta, {
+            ...resume,
+            prompt: buildReviveKickoff(meta, bearings, opts.wakeReason),
+        });
+        // Fresh or cycling revive starts a NEW LLM context — reset the on-read doc
+        // dedup so it surfaces docs from scratch (a true resume above instead KEEPS
+        // the persisted set, continuing the same transcript).
         clearInjectedDocs(nodeId);
     }
     // The broker host launches the detached engine. reviveNode keeps
@@ -178,9 +211,11 @@ export function reviveNode(nodeId, opts) {
         clearPid(nodeId);
         throw new Error(`[broker] refusing to revive ${nodeId}: ${error.message}`);
     }
-    // Clear the stale pid so the daemon won't re-fire on it during the new
-    // broker's boot. The fresh broker re-records its pid during extension bind; if
-    // it never boots, the daemon's boot-grace + surfaceBootFailure own that case.
-    clearPid(nodeId);
+    // Record the real broker pid immediately. session_start will re-record the
+    // same pid after extension bind, but the daemon must supervise the process
+    // during the cold-boot window too; otherwise a slow-but-alive broker reads as
+    // pid=null+session=null and can be falsely crashed by the boot-grace path.
+    if (launched.pid !== null)
+        recordPid(nodeId, launched.pid);
     return { window: null, session: meta.tmux_session ?? null, resumed: resuming, launch: launched };
 }

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

@@ -0,0 +1,30 @@
+import { type SessionEntry } from '@earendil-works/pi-coding-agent';
+import type { BrokerSnapshot } from './broker-protocol.js';
+/** customType of the persisted tree entry that ROOTS each post-yield cycle.
+ *  Data payload: `{ cycle, fromLeaf }` — `cycle` is the node's cycle counter at
+ *  relaunch, `fromLeaf` the previous cycle's leaf entry id. */
+export declare const CRTR_CYCLE_CUSTOM_TYPE = "crtr-cycle";
+/** customType of the SYNTHETIC divider message spliced between cycles in
+ *  snapshot rendering. Never persisted to the session file. */
+export declare const CRTR_CYCLE_DIVIDER_CUSTOM_TYPE = "crtr-cycle-divider";
+type SnapshotMessage = BrokerSnapshot['messages'][number];
+/** The structural slice of pi's SessionManager cycle rendering needs. The
+ *  broker's fake-engine test fixture implements only `buildSessionContext`, so
+ *  the tree accessors are optional — absent ⇒ single-cycle behavior. */
+export interface CycleSessionManagerLike {
+    buildSessionContext(): {
+        messages: SnapshotMessage[];
+    };
+    getEntries?(): SessionEntry[];
+    /** Walk from `fromId` (default: the current leaf) to its root; returns the
+     *  path root-first. */
+    getBranch?(fromId?: string): SessionEntry[];
+}
+/** 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
+ *  the manager lacks tree accessors (fake engine), or when the current leaf was
+ *  tree-navigated back into a pre-yield branch (pi's active-branch semantics
+ *  then apply unchanged). */
+export declare function cycleAwareMessages(sm: CycleSessionManagerLike): SnapshotMessage[];
+export {};

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

@@ -0,0 +1,77 @@
+// Cycle-aware session history — one node, one `.jsonl`, many cycles.
+//
+// A refresh-yield does not start a new session file: reviveNode reuses the
+// node's existing `.jsonl` (buildPiArgv's `--crtr-new-cycle`), and the broker
+// resets the session-tree leaf, appending a `crtr-cycle` custom entry as the
+// new cycle's ROOT. Custom entries never participate in LLM context, so the
+// refreshed window is exactly as clean as a brand-new session — but every
+// cycle lives in the same tree as a sibling root branch, so the /tree
+// navigator shows previous cycles natively.
+//
+// `cycleAwareMessages()` is the display-side counterpart: it rebuilds the FULL
+// node history — each prior cycle's messages (via pi's own `buildSessionContext`,
+// so a compacted prior cycle renders correctly), a synthetic divider message per
+// boundary, then the live cycle's context — so the broker welcome snapshot
+// (broker.ts) and the dormant snapshot (node-snapshot.ts) both render one
+// continuous conversation.
+import { buildSessionContext } from '@earendil-works/pi-coding-agent';
+/** customType of the persisted tree entry that ROOTS each post-yield cycle.
+ *  Data payload: `{ cycle, fromLeaf }` — `cycle` is the node's cycle counter at
+ *  relaunch, `fromLeaf` the previous cycle's leaf entry id. */
+export const CRTR_CYCLE_CUSTOM_TYPE = 'crtr-cycle';
+/** customType of the SYNTHETIC divider message spliced between cycles in
+ *  snapshot rendering. Never persisted to the session file. */
+export const CRTR_CYCLE_DIVIDER_CUSTOM_TYPE = 'crtr-cycle-divider';
+function cycleDivider(cycle, timestamp) {
+    const label = cycle !== undefined ? `cycle ${cycle}` : 'new cycle';
+    return {
+        role: 'custom',
+        customType: CRTR_CYCLE_DIVIDER_CUSTOM_TYPE,
+        content: `yielded — ${label} begins with a fresh context window`,
+        display: true,
+        timestamp: new Date(timestamp).getTime(),
+    };
+}
+/** 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
+ *  the manager lacks tree accessors (fake engine), or when the current leaf was
+ *  tree-navigated back into a pre-yield branch (pi's active-branch semantics
+ *  then apply unchanged). */
+export function cycleAwareMessages(sm) {
+    const current = sm.buildSessionContext().messages;
+    if (typeof sm.getEntries !== 'function' || typeof sm.getBranch !== 'function')
+        return current;
+    // File order = append order = chronological cycle order.
+    const entries = sm.getEntries();
+    const markers = entries.filter((e) => e.type === 'custom' && e.customType === CRTR_CYCLE_CUSTOM_TYPE);
+    if (markers.length === 0)
+        return current;
+    // The current cycle's root: first entry on the leaf→root path. When it is
+    // not a cycle marker, the leaf sits in the ORIGINAL (pre-yield) branch —
+    // render just that branch. Otherwise replay every cycle up to and including
+    // the one the marker closes.
+    const currentRootId = sm.getBranch()[0]?.id;
+    const rootMarkerIndex = markers.findIndex((m) => m.id === currentRootId);
+    if (rootMarkerIndex === -1)
+        return current;
+    // Shared byId map — buildSessionContext would otherwise rebuild one from
+    // `entries` on every call; one pass here amortizes it across every replayed
+    // marker.
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    const out = [];
+    for (let i = 0; i <= rootMarkerIndex; i++) {
+        const marker = markers[i];
+        const fromLeaf = marker.data?.fromLeaf;
+        if (typeof fromLeaf === 'string' && fromLeaf !== '') {
+            // Replay this prior cycle's own branch through pi's canonical context
+            // 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(cycleDivider(marker.data?.cycle, marker.timestamp));
+    }
+    out.push(...current);
+    return out;
+}