@north-light/crouter 0.3.295 → 0.3.297

package/dist/clients/inbox/review/document-surface.d.ts

@@ -62,6 +62,11 @@ export declare class ReviewDocumentSurface implements SurfaceComponent {
      *  `paneOrigin` is status-row copy only: teardown reads `paneId`. */
     private paneId;
     private paneOrigin;
+    /** Row increments of a half-page move still to be painted, and the timer
+     *  walking them. A fresh press settles whatever is in flight before starting
+     *  its own move, so a held key cannot pile up overlapping animations. */
+    private scrollSteps;
+    private scrollTimer;
     private state;
     private cache;
     /** Every non-deleted comment the daemon currently projects, newest last. */
@@ -98,6 +103,15 @@ export declare class ReviewDocumentSurface implements SurfaceComponent {
     /** A mounted review consumes every notch, ready or not: the transcript
      *  beneath it must never scroll while the document stands over it. */
     handleWheel(direction: 'up' | 'down', lines: number): boolean;
+    /** A half-page move of the view and the selection together, painted at three
+     *  midpoints before its destination so the document slides rather than jumps.
+     *  Whatever is still in flight lands first, keeping every press exact. */
+    private startScrollAnimation;
+    private scheduleScrollStep;
+    /** Land every step still to be painted on the state at once. */
+    private settleScrollAnimation;
+    private stopScrollAnimation;
+    private applyScrollRows;
     /** Repaints are scheduled by the host; this surface never draws directly. */
     invalidate(): void;
     /** The mounted handle is this surface's repaint and close channel, and the

package/dist/clients/inbox/review/document-surface.js

@@ -11,9 +11,15 @@ import { matchReviewKey, reviewKeyText } from './keys.js';
 import { renderInputBuffer } from '../tui/render.js';
 import { openReviewedFileInEditor } from './nvim.js';
 import { buildLineMap, remapRange } from './remap.js';
-import { cleanPastedText, closeCompose, closeHelp, closeList, commitCompose, ensureAnchorVisible, initReviewState, moveActiveUnit, moveListIndex, openComposeEdit, openComposeNew, openHelp, openList, scrollBy, textBackspace, textDelete, textEnd, textHome, textInsert, textVerticalWrapped, textWordBackspace, textWordLeft, textWordRight, deleteAtListIndex, undoLast, } from './state.js';
+import { cleanPastedText, closeCompose, closeHelp, closeList, commitCompose, ensureAnchorVisible, halfPageRows, initReviewState, moveActiveUnit, moveListIndex, moveViewRows, openComposeEdit, openComposeNew, openHelp, openList, scrollBy, textBackspace, textDelete, textEnd, textHome, textInsert, textVerticalWrapped, textWordBackspace, textWordLeft, textWordRight, deleteAtListIndex, undoLast, } from './state.js';
 /** The widest the document is ever rendered, however wide the pane is. */
 const DOC_MAX_COLS = 126;
+/** How many places a half-page move is painted at: three midpoints, then the
+ *  destination. A move of fewer rows than this uses one step per row. */
+const SCROLL_STEPS = 4;
+/** Milliseconds between painted steps. pi-tui paints at most every 16ms, so a
+ *  shorter gap would drop steps instead of showing them. */
+const SCROLL_STEP_MS = 24;
 /** The one mounted review surface: existing review rendering and navigation
  *  over a live file, with comments projected from the daemon and ranges
  *  remapped by this terminal as the file changes, plus a status row naming the
@@ -54,6 +60,11 @@ export class ReviewDocumentSurface {
      *  `paneOrigin` is status-row copy only: teardown reads `paneId`. */
     paneId;
     paneOrigin;
+    /** Row increments of a half-page move still to be painted, and the timer
+     *  walking them. A fresh press settles whatever is in flight before starting
+     *  its own move, so a held key cannot pile up overlapping animations. */
+    scrollSteps = [];
+    scrollTimer;
     state;
     cache;
     /** Every non-deleted comment the daemon currently projects, newest last. */
@@ -237,12 +248,61 @@ export class ReviewDocumentSurface {
         const state = this.state;
         if (this.status !== 'ready' || state === undefined)
             return true;
-        const doc = this.document(this.cols, state.sourceRevision);
+        this.settleScrollAnimation();
+        const current = this.state ?? state;
+        const doc = this.document(this.cols, current.sourceRevision);
         const delta = (direction === 'up' ? -1 : 1) * Math.max(1, Math.floor(lines));
-        this.state = scrollBy(state, delta, this.bodyHeight(state), doc.lines.length);
+        this.state = scrollBy(current, delta, this.bodyHeight(current), doc.lines.length);
         this.repaint();
         return true;
     }
+    /** A half-page move of the view and the selection together, painted at three
+     *  midpoints before its destination so the document slides rather than jumps.
+     *  Whatever is still in flight lands first, keeping every press exact. */
+    startScrollAnimation(rows) {
+        this.settleScrollAnimation();
+        const steps = splitScrollSteps(rows);
+        const first = steps.shift();
+        if (first === undefined)
+            return;
+        this.applyScrollRows(first);
+        this.scrollSteps = steps;
+        this.scheduleScrollStep();
+    }
+    scheduleScrollStep() {
+        if (this.scrollSteps.length === 0)
+            return;
+        this.scrollTimer = setTimeout(() => {
+            this.scrollTimer = undefined;
+            const rows = this.scrollSteps.shift();
+            if (rows === undefined || this.closed)
+                return;
+            this.applyScrollRows(rows);
+            this.repaint();
+            this.scheduleScrollStep();
+        }, SCROLL_STEP_MS);
+    }
+    /** Land every step still to be painted on the state at once. */
+    settleScrollAnimation() {
+        this.stopScrollAnimation();
+        const pending = this.scrollSteps;
+        this.scrollSteps = [];
+        for (const rows of pending)
+            this.applyScrollRows(rows);
+    }
+    stopScrollAnimation() {
+        if (this.scrollTimer === undefined)
+            return;
+        clearTimeout(this.scrollTimer);
+        this.scrollTimer = undefined;
+    }
+    applyScrollRows(rows) {
+        const state = this.state;
+        if (this.status !== 'ready' || state === undefined)
+            return;
+        const doc = this.document(this.cols, state.sourceRevision);
+        this.state = moveViewRows(state, rows, this.bodyHeight(state), doc.lines.length);
+    }
     /** Repaints are scheduled by the host; this surface never draws directly. */
     invalidate() {
         if (!this.closed)
@@ -356,6 +416,8 @@ export class ReviewDocumentSurface {
         // surface to every already-in-flight asynchronous continuation.
         this.source.close();
         this.closed = true;
+        this.stopScrollAnimation();
+        this.scrollSteps = [];
         this.unsubscribeComments();
         this.cache = undefined;
     }
@@ -797,7 +859,7 @@ export class ReviewDocumentSurface {
             this.state = ensureAnchorVisible(moveActiveUnit(state, key.delta, true), doc, bodyHeight);
         }
         else if (key.type === 'scrollPage') {
-            this.state = scrollBy(state, key.delta * bodyHeight, bodyHeight, doc.lines.length);
+            this.startScrollAnimation(key.delta * halfPageRows(bodyHeight));
         }
         else if ((key.type === 'pan' || (key.type === 'arrow' && (key.direction === 'left' || key.direction === 'right')))
             && maxHScroll(state, doc, this.cols, this.rows, this.gutterWidth()) > 0) {
@@ -1000,6 +1062,24 @@ export class ReviewDocumentSurface {
     }
 }
 // ── Pure helpers ─────────────────────────────────────────────────────────────
+/** Split a row move into increments summing exactly to it — one per painted
+ *  step, and one per row when the move is shorter than the step count (a jump
+ *  of a single row is painted once, not animated). */
+function splitScrollSteps(rows) {
+    const magnitude = Math.abs(rows);
+    if (magnitude === 0)
+        return [];
+    const direction = Math.sign(rows);
+    const count = Math.min(SCROLL_STEPS, magnitude);
+    const steps = [];
+    let painted = 0;
+    for (let i = 1; i <= count; i++) {
+        const reached = Math.round((magnitude * i) / count);
+        steps.push((reached - painted) * direction);
+        painted = reached;
+    }
+    return steps;
+}
 /** Exactly `rows` lines, each exactly `width` cells. */
 function exactRows(lines, rows, width) {
     const frame = lines.slice(0, rows).map((line) => padTo(line, width));

package/dist/clients/inbox/review/frame.js

@@ -129,7 +129,7 @@ export function renderReviewFrame(state, fileLabel, doc, cols, rows, opts) {
     else if (state.mode === 'help') {
         footer.push('  Keys:');
         footer.push(`  ${DIM}j/k${RESET}         move anchor            ${DIM}shift-j/k${RESET}   extend selection`);
-        footer.push(`  ${DIM}u/d${RESET}         scroll document        ${DIM}h/l${RESET}         pan visible wide diagrams`);
+        footer.push(`  ${DIM}u/d${RESET}         move half a page       ${DIM}h/l${RESET}         pan visible wide diagrams`);
         footer.push(`  ${DIM}space c${RESET}     compose comment        ${DIM}space l${RESET}     list comments`);
         footer.push(`  ${DIM}space u${RESET}     undo last comment      ${DIM}space e${RESET}     edit in $EDITOR`);
         footer.push(`  ${DIM}space s${RESET}     submit review`);

package/dist/clients/inbox/review/state.d.ts

@@ -80,9 +80,18 @@ export declare function anchorRowRange(units: AnchorUnit[], lo: number, hi: numb
  *  clamped to the document. */
 export declare function scrollToReveal(scroll: number, first: number, last: number, bodyHeight: number, total: number, margin?: number): number;
 /** Auto-scroll so the active unit (the moving edge of a selection) is
- *  visible. Free-scrolling (`u`/`d`) is untouched until the next anchor move. */
+ *  visible. The wheel free-scrolls and is untouched until the next anchor move. */
 export declare function ensureAnchorVisible(state: ReviewState, doc: RenderedDoc, bodyHeight: number): ReviewState;
 export declare function scrollBy(state: ReviewState, delta: number, bodyHeight: number, totalLines: number): ReviewState;
+/** Rows one `u`/`d` press travels: half the visible body, and never fewer than
+ *  one row, so a diagram taller than the pane cannot hold the document still. */
+export declare function halfPageRows(bodyHeight: number): number;
+/** Move the view by `rows` and carry the anchored unit the same distance, so
+ *  the selection keeps its place on screen rather than being left behind. The
+ *  selection lands on the unit owning the row it would occupy after the move,
+ *  clamped into the rows the frame actually paints; at the end of the document,
+ *  where the view can no longer move, the selection walks the rest on its own. */
+export declare function moveViewRows(state: ReviewState, rows: number, bodyHeight: number, totalRows: number): ReviewState;
 export declare function openComposeNew(state: ReviewState): ReviewState;
 export declare function openComposeEdit(state: ReviewState, index: number): ReviewState;
 export declare function closeCompose(state: ReviewState): ReviewState;

package/dist/clients/inbox/review/state.js

@@ -106,7 +106,7 @@ export function scrollToReveal(scroll, first, last, bodyHeight, total, margin =
     return Math.max(0, Math.min(next, maxScroll));
 }
 /** Auto-scroll so the active unit (the moving edge of a selection) is
- *  visible. Free-scrolling (`u`/`d`) is untouched until the next anchor move. */
+ *  visible. The wheel free-scrolls and is untouched until the next anchor move. */
 export function ensureAnchorVisible(state, doc, bodyHeight) {
     const range = anchorRowRange(state.units, state.activeUnit, state.activeUnit);
     if (range === null)
@@ -118,6 +118,50 @@ export function scrollBy(state, delta, bodyHeight, totalLines) {
     const maxScroll = Math.max(0, totalLines - bodyHeight);
     return { ...state, scroll: Math.max(0, Math.min(state.scroll + delta, maxScroll)) };
 }
+/** Rows one `u`/`d` press travels: half the visible body, and never fewer than
+ *  one row, so a diagram taller than the pane cannot hold the document still. */
+export function halfPageRows(bodyHeight) {
+    return Math.max(1, Math.floor(bodyHeight / 2));
+}
+/** Move the view by `rows` and carry the anchored unit the same distance, so
+ *  the selection keeps its place on screen rather than being left behind. The
+ *  selection lands on the unit owning the row it would occupy after the move,
+ *  clamped into the rows the frame actually paints; at the end of the document,
+ *  where the view can no longer move, the selection walks the rest on its own. */
+export function moveViewRows(state, rows, bodyHeight, totalRows) {
+    if (rows === 0)
+        return state;
+    const direction = rows > 0 ? 1 : -1;
+    const maxScroll = Math.max(0, totalRows - bodyHeight);
+    const scroll = Math.max(0, Math.min(state.scroll + rows, maxScroll));
+    // The frame overwrites the first and last body rows with its `more above` /
+    // `more below` indicators, and an indicator row carries no cursor, so the
+    // selection is kept inside the rows that remain the document's own.
+    const lo = scroll + (scroll > 0 ? 1 : 0);
+    const hi = Math.max(lo, scroll + bodyHeight - 1 - (scroll + bodyHeight < totalRows ? 1 : 0));
+    const anchorRow = state.units[state.activeUnit]?.firstRow ?? state.scroll;
+    const target = Math.max(lo, Math.min(anchorRow + rows, hi));
+    const activeUnit = unitNearRow(state, target, lo, hi, direction) ?? state.activeUnit;
+    if (scroll === state.scroll && activeUnit === state.activeUnit)
+        return state;
+    return { ...state, scroll, activeUnit, selectionAnchor: null };
+}
+/** The unit owning the row nearest `row` within `lo..hi`, preferring the
+ *  direction of travel. Separator rows own no unit, hence the search. */
+function unitNearRow(state, row, lo, hi, direction) {
+    const last = Math.max(0, state.units.length - 1);
+    for (let step = 0; step <= hi - lo; step++) {
+        for (const candidate of [row + step * direction, row - step * direction]) {
+            if (candidate < lo || candidate > hi)
+                continue;
+            const unit = state.rowUnits[candidate];
+            if (unit === null || unit === undefined)
+                continue;
+            return Math.max(0, Math.min(last, unit));
+        }
+    }
+    return null;
+}
 export function openComposeNew(state) {
     return { ...state, mode: 'compose', compose: { buffer: '', cursor: 0, editingId: null, returnMode: 'view', anchor: currentAnchor(state) } };
 }

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -119,6 +119,8 @@ interface FakeSessionManager {
     getLeafId: () => string | null;
     getEntry: (id: string) => TreeEntry | undefined;
     getTree: () => SessionTreeNode[];
+    getBranch: (fromId?: string) => TreeEntry[];
+    getEntries: () => TreeEntry[];
     getUserMessagesForForking: () => Array<{
         entryId: string;
         text: string;
@@ -194,6 +196,10 @@ declare class FakeSession {
     get isStreaming(): boolean;
     getSessionStats(): Record<string, unknown>;
     private syncTreeSnapshot;
+    /** Reads the crashed process's last `fake-pi.tree.json` (if any) and rebuilds
+     *  this process's tree from it. Best-effort: a first boot (no snapshot yet)
+     *  leaves the tree empty, matching today's behavior. */
+    private hydrateFromPriorSnapshot;
     setSessionName(_name: string): void;
     prompt(text: string, options?: {
         preflightResult?: (success: boolean) => void;

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

@@ -192,6 +192,20 @@ class SessionTree {
         this.leafId = entry.id;
         return entry;
     }
+    /** Reconstructs a prior process's tree from its persisted snapshot — the
+     *  fake's analog of the real SessionManager.open() reading every entry back
+     *  from the .jsonl. A genuine resume (not a fresh cycle) must see this
+     *  broker's actual history, not an empty tree, or nothing downstream that
+     *  reads the branch past a crash can ever observe real prior content. */
+    hydrate(entries, leafId) {
+        for (const entry of entries) {
+            this.entries.set(entry.id, entry);
+            const siblings = this.children.get(entry.parentId) ?? [];
+            siblings.push(entry.id);
+            this.children.set(entry.parentId, siblings);
+        }
+        this.leafId = leafId;
+    }
     /** Synthetic in-place rewind for the broker navigate_tree regression lock:
      *  drop the last turn (assistant leaf + its user parent) by re-anchoring the
      *  leaf past it. The abandoned tail is left in the map (not deleted), mirroring
@@ -228,17 +242,18 @@ class SessionTree {
     /** The active branch root→leaf — the real SessionManager.getBranch(). The
      *  extensions that scan for their own marker read THIS, not the whole file:
      *  a new cycle must not see a previous branch's markers. */
-    getBranch() {
-        return this.branchIds().map((id) => this.entries.get(id)).filter((entry) => entry !== undefined);
+    getBranch(fromId) {
+        return this.branchIds(fromId).map((id) => this.entries.get(id)).filter((entry) => entry !== undefined);
     }
     branchMessages() {
         return this.branchIds().map((id) => this.entries.get(id)?.message).filter((m) => m !== undefined);
     }
-    /** The active branch's entry ids, root→leaf. */
-    branchIds() {
+    /** One branch's entry ids, root→leaf, from `fromId` (default: the current
+     *  leaf) — the real SessionManager.getBranch(fromId?) contract. */
+    branchIds(fromId) {
         const ids = [];
-        let cur = this.leafId;
-        while (cur !== null) {
+        let cur = fromId ?? this.leafId;
+        while (cur !== null && cur !== undefined) {
             const entry = this.entries.get(cur);
             if (entry === undefined)
                 break;
@@ -324,6 +339,14 @@ class FakeSession {
         this.recordModel();
         const configured = Number(process.env['CRTR_FAKE_ENGINE_PROMPT_FAILS'] ?? '0');
         this.promptFailuresRemaining = Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : 0;
+        // A genuine resume (not a fresh cycle) must see this broker's own prior
+        // history — the fake's analog of the real SessionManager.open() replaying
+        // every persisted entry. A cycling revive has already rooted a fresh cycle
+        // marker on `sm` before this construction (broker.ts), which is exactly what
+        // distinguishes it here: `sm.getLeafId()` is non-null only on that path, so
+        // a cycling boot deliberately skips hydration and starts clean.
+        if (sm.resumed && sm.getLeafId() === null)
+            this.hydrateFromPriorSnapshot();
         this.syncTreeSnapshot();
     }
     // --- broker-read getters. buildSnapshot (on a client hello) reads messages/
@@ -348,6 +371,8 @@ class FakeSession {
             getLeafId: () => this.tree.getLeafId(),
             getEntry: (id) => this.tree.getEntry(id),
             getTree: () => this.tree.getTree(),
+            getBranch: (fromId) => this.tree.getBranch(fromId),
+            getEntries: () => this.tree.getEntries(),
             getUserMessagesForForking: () => this.tree.getUserMessagesForForking(),
             getSessionId: () => this.sm.getSessionId(),
             getSessionFile: () => this.sm.getSessionFile(),
@@ -439,6 +464,10 @@ class FakeSession {
                 leafId: this.tree.getLeafId(),
                 activeBranch: this.tree.buildSessionContext().messages,
                 tree: this.tree.getTree(),
+                // Flat entries + leafId are the reload shape a future process's
+                // hydrateFromPriorSnapshot() reads back — getTree()'s nested form is
+                // proof-only and not reconstructed from.
+                entries: this.tree.getEntries(),
                 userMessagesForForking: this.tree.getUserMessagesForForking(),
             }, null, 2));
         }
@@ -446,6 +475,21 @@ class FakeSession {
             /* best effort */
         }
     }
+    /** Reads the crashed process's last `fake-pi.tree.json` (if any) and rebuilds
+     *  this process's tree from it. Best-effort: a first boot (no snapshot yet)
+     *  leaves the tree empty, matching today's behavior. */
+    hydrateFromPriorSnapshot() {
+        try {
+            const raw = readFileSync(join(this.dir, 'fake-pi.tree.json'), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed.entries) || parsed.entries.length === 0)
+                return;
+            this.tree.hydrate(parsed.entries, parsed.leafId ?? null);
+        }
+        catch {
+            /* no prior snapshot — fresh tree */
+        }
+    }
     // naming is cosmetic (broker calls it in a try/catch)
     setSessionName(_name) {
         /* no-op recording stub */
@@ -1197,6 +1241,7 @@ const FAKE_REGISTERED_MODELS = [
     { provider: 'anthropic', id: 'claude-opus-4-8' },
     { provider: 'anthropic', id: 'claude-sonnet-5' },
     { provider: 'anthropic', id: 'claude-haiku-4-5' },
+    { provider: 'openai-codex', id: 'gpt-6-astra' },
     { provider: 'openai-codex', id: 'gpt-5.6-sol' },
     { provider: 'openai-codex', id: 'gpt-5.6-terra' },
     { provider: 'openai-codex', id: 'gpt-5.6-luna' },
@@ -1268,8 +1313,8 @@ export async function createAgentSessionFromServices(options) {
     // Parity with the real SDK: a construction-time thinking level IS the
     // session's thinking level from the first turn on. The broker formats
     // `model:thinking` off this getter, and that suffix is what distinguishes two
-    // ladder cells sharing one model id (openai ultra/strong are both
-    // gpt-5.6-sol) — dropping it here silently misroutes turn-time rotation.
+    // ladder cells sharing one model id — dropping it here silently misroutes
+    // turn-time rotation.
     if (options.thinkingLevel !== undefined)
         session.setThinkingLevel(options.thinkingLevel);
     return { session };

package/dist/core/__tests__/seam/broker-attach-multiclient.test.js

@@ -245,12 +245,18 @@ test('G10 — retained extension display state rides IN welcome.snapshot.display
     assert.equal(live.method, 'setStatus');
     assert.equal(live.statusText, 'painted while attached');
 });
-test('snapshot_tail is ignored when the session has no stable message ids', async () => {
-    const token = tok('snapshot-tail-no-ids');
+// snapshot_tail — a viewer that asks for the last N messages gets exactly them,
+// each with the stable id it needs to page the omitted history back in. The
+// broker serves a tail only when the session yields those ids; it never invents
+// one, so a tail can never strand its recipient on history it cannot reach.
+test('snapshot_tail serves the last N messages with the stable ids that page the rest back', async () => {
+    const token = tok('snapshot-tail');
     h.fakeCmd(id, { cmd: 'stream', text: token });
     const full = await attachUntil(id, 'observer', 'snapshot-tail-full', (a) => JSON.stringify(a.welcome.snapshot.messages).includes(token), 'full snapshot after a tail-less attach');
-    assert.equal(full.welcome.snapshot.messageIds, undefined, 'the fake session has no stable ids');
+    const fullIds = full.welcome.snapshot.messageIds;
+    assert.ok(fullIds !== undefined && fullIds.length > 1, 'the session yields a stable id per message');
+    assert.equal(fullIds.length, full.welcome.snapshot.messages.length, 'every message in the welcome carries an id');
     const tailed = await attach(id, 'observer', 'snapshot-tail-request', { snapshotTail: 1 });
-    assert.equal(tailed.welcome.snapshot.messageIds, undefined, 'the tail request cannot invent stable ids');
-    assert.deepEqual(tailed.welcome.snapshot.messages, full.welcome.snapshot.messages, 'a welcome without stable ids keeps the full history instead of stranding an unpageable tail');
+    assert.deepEqual(tailed.welcome.snapshot.messageIds, fullIds.slice(-1), 'the tail carries the ids of the messages it kept');
+    assert.deepEqual(tailed.welcome.snapshot.messages, full.welcome.snapshot.messages.slice(-1), 'the tail is the last message alone, not the whole history');
 });

package/dist/core/__tests__/seam/broker-provider-retry.test.js

@@ -15,6 +15,8 @@ import { defaultModelLaddersConfig } from '../../../types.js';
 import { admitProviderRetryEpisode, readFault, readProviderRetryEpisode } from '../../runtime/fault.js';
 import { buildPiArgv, normalizeModel } from '../../runtime/launch.js';
 import { encodeFrame } from '../../runtime/broker-protocol.js';
+import { CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY, generatedContextText, parseCard } from '../../../shared/generated-context.js';
+import { RUNTIME_RESTART_CONTINUATION } from '../../runtime/kickoff.js';
 const MODEL_LADDERS = defaultModelLaddersConfig();
 function resolvedModel(spec) {
     const normalized = normalizeModel(spec, MODEL_LADDERS);
@@ -131,7 +133,7 @@ test('a managed-cooling terminal authors a rate-limit auto fault whose deadline
     await new Promise((resolve) => setTimeout(resolve, 2500));
     assert.equal(agentStartCount(child), baselineStarts + 1, 'the fault-retry timer re-drives the turn exactly once');
 });
-test('a crashed broker re-drives only its pending provider episode, never admitted or invalidated episodes', { timeout: 90_000 }, async () => {
+test('a crashed broker re-drives a pending episode and a no-progress admitted one, never a progressed or invalidated episode', { timeout: 90_000 }, async () => {
     const parent = h.spawnRoot('durable provider episode parent');
     seedPool('anthropic', false);
     seedPool('openai-codex', false);
@@ -149,7 +151,13 @@ test('a crashed broker re-drives only its pending provider episode, never admitt
     await h.waitFor(() => agentStartCount(pendingNode) >= pendingStarts + 1, { label: 'replacement re-drove the pending episode' });
     await new Promise((resolve) => setTimeout(resolve, 300));
     assert.equal(agentStartCount(pendingNode), pendingStarts + 1, 'a pending episode re-drives exactly once after broker death');
-    const admittedNode = await h.spawnHeadlessChild(parent, 'admitted provider episode', { model: OPENAI_STRONG.spec });
+    // An admitted episode is re-openable, guarded by a no-progress proof: the
+    // branch segment strictly after its anchor must carry no assistant content
+    // and no tool activity. Case A proves the no-progress half re-drives exactly
+    // once, one attempt higher, with the restart continuation suppressed. Case B
+    // proves an admitted episode whose dead attempt DID produce real work is
+    // never replayed — the ordinary continuation delivers instead, unchanged.
+    const admittedNode = await h.spawnHeadlessChild(parent, 'admitted provider episode (no progress)', { model: OPENAI_STRONG.spec });
     await h.waitFor(() => agentStartCount(admittedNode) >= 1, { label: 'admitted episode fixture started' });
     const admittedKickoffObserver = await attachUntil(admittedNode, 'observer', 'admitted-provider-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'admitted provider episode kickoff settled');
     admittedKickoffObserver.close();
@@ -160,11 +168,79 @@ test('a crashed broker re-drives only its pending provider episode, never admitt
     const admittedPending = await h.waitFor(() => readProviderRetryEpisode(admittedNode)?.state === 'pending' ? readProviderRetryEpisode(admittedNode) : null, { label: 'admitted episode pending record persisted' });
     const admittedFault = readFault(admittedNode);
     assert.ok(admittedFault !== null, 'the pending episode retains its retry fault before admission');
-    assert.equal(admitProviderRetryEpisode(admittedNode, admittedPending.sessionFile, admittedFault), true, 'the dispatch boundary durably admits the matching episode');
+    // The 60s-future deadline above keeps the ORIGINAL process's own in-process
+    // timer from firing before this synthetic admission runs. The episode's own
+    // fault gets its nextAt rewritten into the past, matching production: by the
+    // time a REAL replacement broker boots, the original deadline has typically
+    // already elapsed (see the design's "effectively zero delay" note), so this
+    // proves the re-drive without a real ~60s wait.
+    const admittedFaultForEpisode = { ...admittedFault, retry: { ...admittedFault.retry, nextAt: new Date(Date.now() - 1_000).toISOString() } };
+    assert.equal(admitProviderRetryEpisode(admittedNode, admittedPending.sessionFile, admittedFaultForEpisode), true, 'the dispatch boundary durably admits the matching episode');
     assert.equal(readProviderRetryEpisode(admittedNode)?.state, 'admitted');
     await crashAndRespawn(admittedNode, h.bootCount(admittedNode));
+    await h.waitFor(() => agentStartCount(admittedNode) >= admittedStarts + 1, { label: 'replacement re-drove the no-progress admitted episode' });
+    // A persistent re-arm would re-drive again immediately (nextAt is now in the
+    // past), so a spurious second re-drive would land within a poll interval.
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+    assert.equal(agentStartCount(admittedNode), admittedStarts + 1, 'a no-progress admitted episode re-drives exactly once, never more');
+    const admittedBranch = JSON.parse(readFileSync(join(h.home, 'nodes', admittedNode, 'fake-pi.tree.json'), 'utf8')).activeBranch;
+    const admittedUserMessages = admittedBranch.filter((message) => message.role === 'user');
+    const newestAdmittedUserMessage = admittedUserMessages[admittedUserMessages.length - 1];
+    assert.ok(newestAdmittedUserMessage !== undefined, 'the re-drive delivers a user-role recovery message');
+    const expectedRecoveryBody = admittedFault.kind === 'connection' ? CONNECTION_FAULT_RECOVERY_BODY : PROVIDER_FAULT_RECOVERY_BODY;
+    const redriveCard = parseCard(newestAdmittedUserMessage);
+    assert.equal(redriveCard?.kind, 'recovery', 'the re-drive delivers the recovery card, not a duplicate failure entry');
+    assert.equal(redriveCard?.body, expectedRecoveryBody, 'the recovery card carries the body matching the fault kind');
+    // Every superseded attempt leaves the active branch, so this card is the only
+    // visible record of the sequence — it must name which attempt it is. The
+    // exact number depends on how far the ladder had already advanced, so assert
+    // that the facts are present and coherent rather than pinning a literal.
+    const redriveAttempt = Number(redriveCard?.facts['attempt']);
+    const redriveMax = Number(redriveCard?.facts['max']);
+    assert.ok(Number.isInteger(redriveAttempt) && redriveAttempt >= 1, 'the recovery card names which attempt it is');
+    assert.ok(Number.isInteger(redriveMax) && redriveMax >= redriveAttempt, 'the recovery card names the ladder length it counts against');
+    assert.ok(!admittedBranch.some((message) => generatedContextText(message) === RUNTIME_RESTART_CONTINUATION), 'a no-progress re-drive suppresses the restart continuation entirely');
+    // The fake engine's recovery-card prompt runs a genuine successful turn (no
+    // forced failure is queued for it), so the episode clears at settlement —
+    // Flow A's success ending, not another failure round. `nextFaultRetry`
+    // already advances `fault.retry.attempt` on every admission regardless of
+    // this design (unchanged, pre-existing ladder logic); this settle just
+    // proves the sequence can end cleanly through the reopened path too.
+    assert.equal(readProviderRetryEpisode(admittedNode), null, 'the successful re-drive clears the episode at settlement');
+    const progressNode = await h.spawnHeadlessChild(parent, 'admitted provider episode (progress)', { model: OPENAI_STRONG.spec });
+    await h.waitFor(() => agentStartCount(progressNode) >= 1, { label: 'progress episode fixture started' });
+    const progressKickoffObserver = await attachUntil(progressNode, 'observer', 'progress-provider-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'progress episode kickoff settled');
+    progressKickoffObserver.close();
+    h.fakeCmd(progressNode, {
+        cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 60_000,
+    });
+    const progressPending = await h.waitFor(() => readProviderRetryEpisode(progressNode)?.state === 'pending' ? readProviderRetryEpisode(progressNode) : null, { label: 'progress episode pending record persisted' });
+    const progressFault = readFault(progressNode);
+    assert.ok(progressFault !== null, 'the pending episode retains its retry fault before admission');
+    assert.equal(admitProviderRetryEpisode(progressNode, progressPending.sessionFile, progressFault), true, 'the dispatch boundary durably admits the matching episode');
+    assert.equal(readProviderRetryEpisode(progressNode)?.state, 'admitted');
+    // A real successful turn past the anchor: proves the dead attempt's slot is
+    // no longer the branch tail, so recoverOnStartup's no-progress proof must
+    // find this assistant content and refuse to roll it back.
+    const progressController = await kit.attach(progressNode, 'controller', 'progress-provider-episode');
+    progressController.send({ type: 'prompt', text: `progress past anchor ${Date.now()}` });
+    await progressController.waitFrame((f) => f.type === 'agent_end', 'the progress turn settles');
+    progressController.close();
+    // The natural settle above already clears the episode (any non-error settle
+    // clears it unconditionally) — expected, and orthogonal to what this half
+    // proves. Restore `admitted` with the SAME original anchor/fault by writing
+    // the job-dir file directly, bypassing the guarded API (mirrors the
+    // `reload_auth leaves a parked auth fault` precedent above in this file), so
+    // the crash below tests the no-progress proof against a genuine post-anchor
+    // assistant turn instead of an unreliable real-crash race.
+    await h.waitFor(() => readProviderRetryEpisode(progressNode) === null, { label: 'the settled turn cleared the episode' });
+    writeFileSync(join(h.home, 'nodes', progressNode, 'job', 'provider-retry'), JSON.stringify({ state: 'admitted', sessionFile: progressPending.sessionFile, anchorEntryId: progressPending.anchorEntryId, fault: progressFault }));
+    assert.equal(readProviderRetryEpisode(progressNode)?.state, 'admitted', 'the direct write restores the admitted episode for the crash below');
+    const progressStartsBeforeCrash = agentStartCount(progressNode);
+    await crashAndRespawn(progressNode, h.bootCount(progressNode));
     await new Promise((resolve) => setTimeout(resolve, 300));
-    assert.equal(agentStartCount(admittedNode), admittedStarts, 'an admitted episode is never replayed by replacement startup');
+    assert.equal(agentStartCount(progressNode), progressStartsBeforeCrash, 'progress past the anchor is never replayed by replacement startup');
+    assert.equal(readProviderRetryEpisode(progressNode), null, 'the progress branch clears the episode rather than leaving it inert');
     const invalidatedNode = await h.spawnHeadlessChild(parent, 'invalidated provider episode', { model: OPENAI_STRONG.spec });
     await h.waitFor(() => agentStartCount(invalidatedNode) >= 1, { label: 'invalidated episode fixture started' });
     const invalidatedKickoffObserver = await attachUntil(invalidatedNode, 'observer', 'invalidated-provider-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'invalidated provider episode kickoff settled');

package/dist/core/runtime/broker/fault-retry.d.ts

@@ -31,10 +31,26 @@ export declare class FaultRetry {
     onEvent(event: BrokerToClient): void;
     isActiveAutoFault(fault: ReturnType<typeof readFault>): fault is NonNullable<ReturnType<typeof readFault>>;
     publishSettledProviderFault(generation: SubscriptionGeneration): void;
-    /** Startup re-drive reads only a durable pending episode. Revive deliberately
-     * clears the ordinary fault marker before this boundary, so the episode is
-     * the recovery authority and admitted/invalidated records remain inert. */
-    recoverPendingOnStartup(): void;
+    /** Startup re-drive reads the durable episode surviving from the process this
+     *  replaces. Revive deliberately clears the ordinary fault marker before this
+     *  boundary, so the episode is the recovery authority. A `pending` episode
+     *  re-arms unconditionally, exactly as before. An `admitted` episode re-arms
+     *  too, but only under a no-progress proof: reopened to `pending` when the
+     *  branch segment from its anchor to the current leaf carries no assistant
+     *  content and no tool activity — the dead attempt did nothing that rolling
+     *  back would destroy. An anchor absent from the loaded branch cannot happen
+     *  in production (session-file identity and the new-cycle guard already rule
+     *  it out below), so it is treated the same as "no progress" rather than
+     *  blocking the ladder. Returns 'retry-armed' when the timer now owns the
+     *  first turn, 'none' when the caller's default kickoff should proceed. */
+    recoverOnStartup(): 'retry-armed' | 'none';
+    /** True iff the branch segment strictly after `anchorEntryId` (root→leaf,
+     *  anchor exclusive) contains an assistant message with non-empty content or
+     *  a tool result — the two shapes a runtime card and a `content: []`
+     *  error-settled assistant message are not. An anchor missing from the loaded
+     *  branch cannot be distinguished from "no progress" here; callers treat it
+     *  as no progress rather than as a positive finding. */
+    private hasProgressPastAnchor;
     schedule(): void;
     private maybeSwitchProviderForRetry;
     private maybeFallbackOnUnusableModel;