@dieulc/workflow 0.9.2 → 0.11.0

package/review.ts

@@ -64,6 +64,15 @@ export const REVIEW_SUBMITTED_ENTRY_TYPE = "workflow-review-submitted";
 // ── Step 2: Review Mode configuration ────────────────────────────────
 
 export type ReviewFallbackOnError = "skip" | "block";
+export type ReviewProviderRecovery = "fallback" | "off";
+export type ReviewChunkedSubmit = "auto" | "off";
+
+/** A reviewer model reference used by the recovery chain or an explicit fallback. */
+export interface ReviewFallbackModel {
+  provider: string;
+  id: string;
+  thinking: string;
+}
 
 export interface ReviewModeConfig {
   /** Master toggle. When false every Review Mode code path is a no-op. */
@@ -76,6 +85,22 @@ export interface ReviewModeConfig {
   verify: boolean;
   /** What to do if the reviewer model is unavailable or the review fails. */
   fallbackOnError: ReviewFallbackOnError;
+  /**
+   * Provider recovery: after a recoverable stream failure, try the fallback
+   * chain instead of failing the round immediately. `off` restores the old
+   * single-model behaviour.
+   */
+  providerRecovery: ReviewProviderRecovery;
+  /** SDK retries per reviewer model before the chain advances (0-2). */
+  providerRetries: number;
+  /** Explicit first fallback; the runtime still dedupes and clamps it. */
+  fallbackModel?: ReviewFallbackModel;
+  /** Chunked rewrite submission for long plans (default automatic by size). */
+  chunkedSubmit: ReviewChunkedSubmit;
+  /** Max characters per `review_plan_chunk`; also sets the auto threshold. */
+  chunkChars: number;
+  /** Overall recovery budget; 0 uses the round deadline. */
+  recoveryBudgetMs: number;
   /** Max `review_explore` subagents per review round (cost ceiling). */
   exploreBudget: number;
   /**
@@ -103,6 +128,11 @@ export const DEFAULT_REVIEW_MODE_CONFIG: Readonly<ReviewModeConfig> = {
   passes: 2,
   verify: true,
   fallbackOnError: "skip",
+  providerRecovery: "fallback",
+  providerRetries: 1,
+  chunkedSubmit: "auto",
+  chunkChars: 6_000,
+  recoveryBudgetMs: 0,
   exploreBudget: 1,
   timeoutMs: 300_000,
   contextChars: 15_000,
@@ -125,6 +155,83 @@ const CONTEXT_ENTRIES_MAX = 120;
 const CONTEXT_TOOL_CHARS_MIN = 200;
 const CONTEXT_TOOL_CHARS_MAX = 4_000;
 
+/**
+ * Build the automatic fallback list: the parent session's model first (it just
+ * planned successfully), then the base reviewer and planner roles from
+ * roles.json (ignoring the active profile). The caller supplies the clamp so
+ * this stays independent of Pi's model registry.
+ */
+export function buildReviewerFallbacks(input: {
+  parentModel?: ReviewFallbackModel;
+  baseReviewer?: ReviewFallbackModel;
+  basePlanner?: ReviewFallbackModel;
+  clampThinking?: (model: ReviewFallbackModel) => string;
+}): ReviewFallbackModel[] {
+  const out: ReviewFallbackModel[] = [];
+  const seen = new Set<string>();
+  const push = (candidate: ReviewFallbackModel | undefined): void => {
+    if (!candidate) return;
+    const provider = candidate.provider.trim();
+    const id = candidate.id.trim();
+    if (!provider || !id) return;
+    const key = `${provider}/${id}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    let thinking = candidate.thinking.trim() || "high";
+    if (input.clampThinking) {
+      try {
+        thinking = input.clampThinking({ ...candidate, provider, id }) || thinking;
+      } catch {
+        /* a registry miss keeps the stored level */
+      }
+    }
+    out.push({ provider, id, thinking });
+  };
+  push(input.parentModel);
+  push(input.baseReviewer);
+  push(input.basePlanner);
+  return out;
+}
+
+/**
+ * The bounded attempt chain for one review round: the selected reviewer model,
+ * an explicit fallback, then the automatic fallback list. Duplicate
+ * provider/id pairs are rejected so a retry never repeats the same model.
+ */
+export function buildReviewerAttempts(input: {
+  base?: ReviewFallbackModel;
+  explicitFallback?: ReviewFallbackModel;
+  fallbacks?: readonly ReviewFallbackModel[];
+  max?: number;
+}): ReviewFallbackModel[] {
+  const out: ReviewFallbackModel[] = [];
+  const seen = new Set<string>();
+  const push = (candidate: ReviewFallbackModel | undefined): void => {
+    if (!candidate) return;
+    const provider = candidate.provider.trim();
+    const id = candidate.id.trim();
+    if (!provider || !id) return;
+    const key = `${provider}/${id}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({
+      provider,
+      id,
+      thinking: candidate.thinking.trim() || "high",
+    });
+  };
+  push(input.base);
+  push(input.explicitFallback);
+  for (const model of input.fallbacks ?? []) push(model);
+  return out.slice(0, Math.max(1, Math.trunc(input.max ?? 4)));
+}
+const PROVIDER_RETRIES_MIN = 0;
+const PROVIDER_RETRIES_MAX = 2;
+const CHUNK_CHARS_MIN = 1_000;
+const CHUNK_CHARS_MAX = 20_000;
+const RECOVERY_BUDGET_MIN = 0;
+const RECOVERY_BUDGET_MAX = 3_600_000;
+
 /** A JSON object parsed from an untrusted source (settings file, fragment). */
 export type JsonObject = Record<string, unknown>;
 
@@ -149,6 +256,19 @@ function asBool(value: unknown, fallback: boolean): boolean {
   return typeof value === "boolean" ? value : fallback;
 }
 
+function sanitizeFallbackModel(value: unknown): ReviewFallbackModel | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const raw = value as Record<string, unknown>;
+  const provider = typeof raw.provider === "string" ? raw.provider.trim() : "";
+  const id = typeof raw.id === "string" ? raw.id.trim() : "";
+  if (!provider || !id) return undefined;
+  const thinking =
+    typeof raw.thinking === "string" && raw.thinking.trim()
+      ? raw.thinking.trim()
+      : "high";
+  return { provider, id, thinking };
+}
+
 /**
  * Coerce an untrusted settings fragment into a complete ReviewModeConfig.
  * Accepts an object, or the boolean shorthand `true`/`false` for
@@ -168,12 +288,42 @@ export function coerceReviewModeConfig(
     r.fallbackOnError === "block" || r.fallbackOnError === "skip"
       ? r.fallbackOnError
       : base.fallbackOnError;
+  const providerRecovery: ReviewProviderRecovery =
+    r.providerRecovery === "off" || r.providerRecovery === "fallback"
+      ? r.providerRecovery
+      : base.providerRecovery;
+  const chunkedSubmit: ReviewChunkedSubmit =
+    r.chunkedSubmit === "off" || r.chunkedSubmit === "auto"
+      ? r.chunkedSubmit
+      : base.chunkedSubmit;
+  const fallbackModel = sanitizeFallbackModel(r.fallbackModel);
   return {
     enabled: asBool(r.enabled, base.enabled),
     rounds: clampInt(r.rounds, ROUNDS_MIN, ROUNDS_MAX, base.rounds),
     passes: clampInt(r.passes, PASSES_MIN, PASSES_MAX, base.passes),
     verify: asBool(r.verify, base.verify),
     fallbackOnError,
+    providerRecovery,
+    providerRetries: clampInt(
+      r.providerRetries,
+      PROVIDER_RETRIES_MIN,
+      PROVIDER_RETRIES_MAX,
+      base.providerRetries,
+    ),
+    ...(fallbackModel ? { fallbackModel } : {}),
+    chunkedSubmit,
+    chunkChars: clampInt(
+      r.chunkChars,
+      CHUNK_CHARS_MIN,
+      CHUNK_CHARS_MAX,
+      base.chunkChars,
+    ),
+    recoveryBudgetMs: clampInt(
+      r.recoveryBudgetMs,
+      RECOVERY_BUDGET_MIN,
+      RECOVERY_BUDGET_MAX,
+      base.recoveryBudgetMs,
+    ),
     exploreBudget: clampInt(
       r.exploreBudget,
       EXPLORE_MIN,
@@ -478,6 +628,22 @@ export function formatReviewStatusLines(input: ReviewStatusInput): string[] {
       c.timeoutMs,
       input.timeoutSource,
     )}`,
+    `  recovery       : ${c.providerRecovery}${
+      c.providerRecovery === "fallback"
+        ? ` (${c.providerRetries} SDK retry/model; budget ${
+            c.recoveryBudgetMs === 0
+              ? "round deadline"
+              : `${Math.round(c.recoveryBudgetMs / 1000)}s`
+          }${
+            c.fallbackModel
+              ? `; explicit ${c.fallbackModel.provider}/${c.fallbackModel.id} (${c.fallbackModel.thinking})`
+              : ""
+          })`
+        : ""
+    }`,
+    `  chunked submit : ${c.chunkedSubmit}${
+      c.chunkedSubmit === "auto" ? ` (${c.chunkChars} chars/chunk)` : ""
+    }`,
   ];
   if (
     input.timeoutSource !== "default" &&
@@ -682,6 +848,10 @@ export interface ReviewState {
   rewrittenPlan?: string;
   /** Reviewer passes completed in this round. */
   passes: ReviewPassResult[];
+  /** Recovery attempts made in this round, in order (model labels). */
+  recoveryAttempts?: string[];
+  /** Last provider error text captured during the round. */
+  providerError?: string;
   /** Number of `review_explore` subagents used this round. */
   exploreUsed: number;
   /** Input tokens reported by the child session, when available. */
@@ -1440,9 +1610,14 @@ export function reviewEscapeAction(input: {
 export function reviewFooterSegment(
   state: ReviewState | undefined,
   paused: boolean,
+  /** A round owns the turn before its first state event (cold boot). */
+  starting = false,
+  /** The reviewer finished; the plan is waiting for Approve/Revise. */
+  handoff = false,
 ): string {
   if (paused) return "🔍 review paused — /review-resume to continue";
-  if (!state) return "";
+  if (handoff) return "🔍 review · awaiting decision";
+  if (!state) return starting ? "🔍 review · starting" : "";
   return reviewStateSummary(state);
 }
 
@@ -1460,6 +1635,8 @@ export function reviewStatusVisible(input: {
   roundInFlight?: boolean;
   roundActive?: boolean;
   paused?: boolean;
+  /** The reviewer finished and the browser/inline handoff owns the turn. */
+  handoff?: boolean;
   /**
    * The retained round state's phase, when one exists. A retained *terminal*
    * phase must not make the line visible during a new round's cold boot
@@ -1468,6 +1645,7 @@ export function reviewStatusVisible(input: {
   phase?: ReviewPhase;
 }): boolean {
   if (input.paused === true) return true;
+  if (input.handoff === true) return true;
   if (input.roundInFlight !== true && input.roundActive !== true) return false;
   // `undefined` means the round has not emitted a state yet; there is nothing
   // stale to paint and the lock/working message still describe the round.
@@ -1487,14 +1665,23 @@ export function reviewStatusText(input: {
   roundInFlight?: boolean;
   roundActive?: boolean;
   paused?: boolean;
+  handoff?: boolean;
 }): string {
   const visible = reviewStatusVisible({
     roundInFlight: input.roundInFlight,
     roundActive: input.roundActive,
     paused: input.paused,
+    handoff: input.handoff,
     phase: input.state?.phase,
   });
-  return visible ? reviewFooterSegment(input.state, input.paused === true) : "";
+  return visible
+    ? reviewFooterSegment(
+        input.state,
+        input.paused === true,
+        input.roundInFlight === true,
+        input.handoff === true,
+      )
+    : "";
 }
 
 /**
@@ -1545,18 +1732,77 @@ export function nextReviewRound(input: {
   return { round, allowed: round <= max };
 }
 
-// ── Mode-switch lock (plan 2026-10-25) ───────────────────────────────
+// ── Review turn + mode-switch lock (plan 2026-11-14) ─────────────────
+//
+// Review is an exclusive turn, not a background job: from the moment the
+// planner hands its plan to the reviewer until the browser/inline decision is
+// applied, no prompt and no mode transition is accepted. The turn is an
+// explicit state (unlike the old derived lock) because the handoff phase has
+// no running child session and must still be locked.
+//
+//   idle -> running -> paused -> running -> ... -> handoff -> transition -> idle
+//                 \-> handoff (reviewer failed/skipped) -> transition -> idle
 //
-// While a review owns the turn, mode transitions are refused: switching to
-// Build mid-review would swap the tool set and suspend the reviewer, and
-// switching to Default would leave the reviewer running outside Plan Mode.
-// The lock is a PROJECTION over existing state (never persisted), so every
-// existing exit — land, fail, pause/resume, abort, suspend, teardown —
-// releases it automatically. The post-review handoff prompt is deliberately
-// NOT part of the lock: the independent reviewer has already finished.
+// `transition` is the short, internal window while a decision stops the
+// reviewer, applies Build/Plan and sends the follow-up. It is locked so a
+// queued prompt cannot race the mode change.
+
+/** The exclusive Review turn. `idle` means no review owns the session. */
+export type ReviewTurnPhase =
+  | "idle"
+  | "running"
+  | "paused"
+  | "handoff"
+  | "transition";
+
+export function reviewTurnOwns(phase: ReviewTurnPhase): boolean {
+  return phase !== "idle";
+}
+
+/** Commands a user may run while Review owns the turn. */
+export function reviewInputAllowed(text: string): boolean {
+  const value = text.trim();
+  if (!value.startsWith("/")) return false;
+  return (
+    /^\/review(?:\s|-|$)/i.test(value) ||
+    /^\/model(?:\s|$)/i.test(value) ||
+    /^\/thinking(?:\s|$)/i.test(value) ||
+    /^\/profile(?:\s|$)/i.test(value) ||
+    /^\/role(?:\s|$)/i.test(value)
+  );
+}
+
+export type ReviewInputDecision =
+  | { action: "allow" }
+  | { action: "block"; notice: string };
+
+/** One decision for `pi.on("input")`; pure so the matrix is testable. */
+export function reviewInputDecision(
+  text: string,
+  phase: ReviewTurnPhase,
+): ReviewInputDecision {
+  if (!reviewTurnOwns(phase)) return { action: "allow" };
+  if (reviewInputAllowed(text)) return { action: "allow" };
+  const state =
+    phase === "paused"
+      ? "paused"
+      : phase === "handoff"
+        ? "awaiting a decision"
+        : phase === "transition"
+          ? "applying the decision"
+          : "running";
+  return {
+    action: "block",
+    notice: `Review is ${state} — prompts are locked. /review-pause, /review-resume, /review-abort, or change model/profile.`,
+  };
+}
 
 /** Which mode-switch lock is active, if any. Derived, never persisted. */
-export type ReviewModeLockKind = "running" | "paused";
+export type ReviewModeLockKind =
+  | "running"
+  | "paused"
+  | "handoff"
+  | "transition";
 
 export interface ReviewModeLockInput {
   /** `activeReview !== undefined` — set before the child session boots. */
@@ -1567,6 +1813,10 @@ export interface ReviewModeLockInput {
   paused?: boolean;
   /** The gated handoff phase; `"auditing"` counts as running. */
   gatePhase?: ReviewHandoffPhase;
+  /** The browser/inline decision owns the session. */
+  handoff?: boolean;
+  /** A decision is being applied (stop reviewer -> mode -> follow-up). */
+  transition?: boolean;
 }
 
 /**
@@ -1589,9 +1839,30 @@ export function reviewModeLockKind(
   }
   if (input.gatePhase === "paused") return "paused";
   if (input.gatePhase === "auditing") return "running";
+  if (input.transition === true) return "transition";
+  if (input.handoff === true) return "handoff";
   return undefined;
 }
 
+/**
+ * The narrower "a reviewer round or pause owns the turn" predicate.
+ * Decision handlers must use this (not the full lock): the handoff they are
+ * about to consume is not a stale decision.
+ */
+export function reviewRoundOwnsTurn(input: {
+  roundInFlight?: boolean;
+  roundActive?: boolean;
+  paused?: boolean;
+  gatePhase?: ReviewHandoffPhase;
+}): boolean {
+  return (
+    input.paused === true ||
+    input.roundInFlight === true ||
+    input.roundActive === true ||
+    input.gatePhase === "auditing"
+  );
+}
+
 /**
  * Phase to use when `/review-resume` starts a paused gated round.
  * A gated pause becomes an active audit again; a manual review (idle gate)
@@ -1625,9 +1896,16 @@ export function reviewHandoffParks(input: {
 
 /** One short notice for a blocked mode transition. */
 export function reviewModeLockNotice(kind: ReviewModeLockKind): string {
-  return kind === "paused"
-    ? "Review is paused — mode switching stays locked. /review-resume to continue, /review-abort to stop, /review-mode off to end review."
-    : "Review is running — mode switching is locked. ESC or /review-pause to pause, /review-resume to continue, /review-abort to stop, /review-mode off to end review.";
+  if (kind === "paused") {
+    return "Review is paused — mode switching stays locked. /review-resume to continue, /review-abort to stop.";
+  }
+  if (kind === "handoff") {
+    return "Review decision pending — mode switching is locked. Approve or annotate in the review tab, or /review-abort to skip.";
+  }
+  if (kind === "transition") {
+    return "Review decision is being applied — mode switching is briefly locked.";
+  }
+  return "Review is running — mode switching is locked. ESC or /review-pause to pause, /review-resume to continue, /review-abort to stop.";
 }
 
 /** Footer marker appended to the single `"workflow"` status while locked. */
@@ -1696,23 +1974,80 @@ export function truncateErrorText(input: unknown, max: number = MAX_ERROR_TEXT):
 }
 
 /**
- * Extract the provider error message when a run stopped on an error: scan an
- * `agent_end` event's messages from the end for the last assistant message
- * with `stopReason === "error"`. Structural on purpose — SDK message shapes
- * are not imported here. Returns undefined for clean runs and junk input.
+ * True when an error text describes an *abort*, not a provider failure.
+ *
+ * Review Mode deliberately aborts the reviewer's tail after `review_pass_done`
+ * (and on pause/teardown). Node rejects an aborted operation with its default
+ * reason (`DOMException: This operation was aborted`); provider SDKs use
+ * `Request was aborted`; the Pi SDK's backoff cancellation reports
+ * `Retry cancelled`. The SDK's `lazyStream` setup path can record any of those
+ * as a `stopReason: "error"` assistant message, so a stop-reason check alone
+ * is not enough to tell an abort from a provider fault.
+ *
+ * Timeouts are deliberately NOT aborts: `AbortSignal.timeout()` rejects with
+ * `The operation was aborted due to timeout`, which is a transient provider
+ * failure and must keep its recovery semantics.
+ *
+ * Matching is anchored at the start of the flattened text so a provider payload
+ * that merely mentions "aborted" is not downgraded. Pure and total.
+ */
+export function isAbortStopText(input: unknown): boolean {
+  const text =
+    typeof input === "string" ? input.replace(/\s+/g, " ").trim() : "";
+  if (!text) return false;
+  // Checked first: "The operation was aborted due to timeout" is a timeout.
+  if (/\b(?:timed?\s*out|timeout)\b/i.test(text)) return false;
+  // `AgentSession._finishCancelledRetry()` reports a cancelled backoff this
+  // way; it is our own abort, never provider health.
+  if (/^retry\s+cancell?ed\b/i.test(text)) return true;
+  return (
+    /^(?:this|the|request|operation|signal)\b[^.\n]{0,40}abort(?:ed|ing)?\b/i.test(
+      text,
+    ) ||
+    /^abort(?:ed)?\s*error\b/i.test(text) ||
+    /^aborted\b/i.test(text)
+  );
+}
+
+/** How the reviewer's last assistant message stopped. */
+export type ReviewStopClassification =
+  | { kind: "clean" }
+  | { kind: "aborted"; message?: string }
+  | { kind: "provider-error"; message: string };
+
+/**
+ * Classify the outcome of a child run from an `agent_end` event's messages.
+ *
+ * Structural on purpose — SDK message shapes are not imported here. Scans
+ * backwards to the last assistant message (the only one that decides the run's
+ * outcome); a missing assistant message or junk input is `clean`. An error stop
+ * with an abort-shaped message is `aborted` even when the SDK labelled it
+ * `error` (its setup path does not check the abort signal), so callers never
+ * report a host cancellation as provider health.
  */
-export function lastAssistantErrorStop(messages: unknown): string | undefined {
-  if (!Array.isArray(messages)) return undefined;
+export function classifyAssistantStop(
+  messages: unknown,
+): ReviewStopClassification {
+  if (!Array.isArray(messages)) return { kind: "clean" };
   for (let i = messages.length - 1; i >= 0; i--) {
     const rec = messages[i] as Record<string, unknown> | null | undefined;
     if (!rec || typeof rec !== "object") continue;
     if (rec.role !== "assistant") continue;
-    // Last assistant message reached: a non-error stop means a clean run.
-    if (rec.stopReason !== "error") return undefined;
-    const err = typeof rec.errorMessage === "string" ? rec.errorMessage : "";
-    return err || "unknown provider error";
+    // Last assistant message reached: this one decides the run outcome.
+    const stopReason = rec.stopReason;
+    if (stopReason === "aborted") {
+      const message =
+        typeof rec.errorMessage === "string" ? rec.errorMessage.trim() : "";
+      return message ? { kind: "aborted", message } : { kind: "aborted" };
+    }
+    if (stopReason !== "error") return { kind: "clean" };
+    const err = typeof rec.errorMessage === "string" ? rec.errorMessage.trim() : "";
+    if (isAbortStopText(err)) {
+      return err ? { kind: "aborted", message: err } : { kind: "aborted" };
+    }
+    return { kind: "provider-error", message: err || "unknown provider error" };
   }
-  return undefined;
+  return { kind: "clean" };
 }
 
 /**
@@ -1724,14 +2059,19 @@ export function lastAssistantErrorStop(messages: unknown): string | undefined {
  * - `exhaust` → the retry budget ran out (`auto_retry_end`, `success: false`);
  *   the run is about to settle on an error. `message` may be empty when the
  *   event carries no `finalError` — callers then keep their earlier message.
- * - `stop`    → the run itself ended with `stopReason === "error"` on its last
- *   assistant message (auto-retry disabled, or a non-retryable failure).
+ * - `stop`    → the run itself ended on a provider error
+ *   (`stopReason === "error"` with a non-abort message; auto-retry disabled,
+ *   or a non-retryable failure).
+ * - `aborted` → the run ended on an abort (`stopReason === "aborted"`, or an
+ *   error stop whose message is abort-shaped — the SDK's setup path mislabels
+ *   a host cancellation as `error`). Never provider health.
  * - `none`    → anything else, including a retry that recovered.
  */
 export type ReviewProviderFailure =
   | { kind: "retry"; message: string; retries: number }
   | { kind: "exhaust"; message: string; retries: number }
   | { kind: "stop"; message: string }
+  | { kind: "aborted"; message?: string }
   | { kind: "none" };
 
 /** Structural decode of one provider-failure event. Never throws. */
@@ -1745,6 +2085,8 @@ export function readProviderErrorEvent(
     const message =
       typeof e.errorMessage === "string" ? e.errorMessage.trim() : "";
     if (!message) return { kind: "none" };
+    // A cancelled retry is our own abort, not provider health.
+    if (isAbortStopText(message)) return { kind: "none" };
     return {
       kind: "retry",
       message,
@@ -1754,6 +2096,7 @@ export function readProviderErrorEvent(
   if (type === "auto_retry_end") {
     if (e.success !== false) return { kind: "none" };
     const message = typeof e.finalError === "string" ? e.finalError.trim() : "";
+    if (isAbortStopText(message)) return { kind: "none" };
     return {
       kind: "exhaust",
       message,
@@ -1761,9 +2104,14 @@ export function readProviderErrorEvent(
     };
   }
   if (type === "agent_end") {
-    const message = lastAssistantErrorStop(e.messages);
-    if (message === undefined) return { kind: "none" };
-    return { kind: "stop", message };
+    const stop = classifyAssistantStop(e.messages);
+    if (stop.kind === "aborted") {
+      return stop.message
+        ? { kind: "aborted", message: stop.message }
+        : { kind: "aborted" };
+    }
+    if (stop.kind !== "provider-error") return { kind: "none" };
+    return { kind: "stop", message: stop.message };
   }
   return { kind: "none" };
 }
@@ -1916,18 +2264,25 @@ function providerErrorOps(
     const ops: ReviewTranscriptOp[] = [
       { op: "new", kind: "status", text: "reviewer run ended" },
     ];
-    const failed = lastAssistantErrorStop(e.messages);
-    if (failed) {
+    // An abort is our own cancellation (pass complete / pause / teardown),
+    // never provider health. The SDK's setup path can label it `error` with an
+    // abort-shaped message, so classification cannot rely on `stopReason`.
+    const stop = classifyAssistantStop(e.messages);
+    if (stop.kind === "provider-error") {
       ops.push({
         op: "new",
         kind: "error",
-        text: `reviewer run ended on a provider error: ${truncateErrorText(failed)}`,
+        text: `reviewer run ended on a provider error: ${truncateErrorText(
+          stop.message,
+        )}`,
       });
     }
     return ops;
   }
   if (type === "auto_retry_start") {
     const msg = typeof e.errorMessage === "string" ? e.errorMessage : "";
+    // A cancelled backoff is an abort, not a provider notice.
+    if (isAbortStopText(msg)) return [];
     return [
       {
         op: "new",
@@ -1944,6 +2299,7 @@ function providerErrorOps(
     // retry recovered; the earlier notice already covers that case.
     if (e.success === false) {
       const detail = truncateErrorText(e.finalError);
+      if (isAbortStopText(detail)) return [];
       return [
         {
           op: "new",
@@ -2186,6 +2542,12 @@ export interface CreateReviewSessionOptions {
   reviewPrompt: string;
   /** Reviewer-only tools, built by the caller. */
   customTools: unknown[];
+  /**
+   * SDK retries per reviewer model (0-2). Applied through a runtime-only child
+   * SettingsManager override so the recovery chain advances after one doomed
+   * long request instead of spending the parent's 3-retry budget first.
+   */
+  providerRetries?: number;
   /**
    * Parent-side provider-registration surface (structural, feature-detected),
    * found with `findParentProviderSurface(ctx)` — the session's model registry
@@ -2246,6 +2608,53 @@ function readActiveToolNames(session: unknown): string[] | undefined {
   }
 }
 
+function clampProviderRetries(value: number | undefined): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 1;
+  return Math.min(2, Math.max(0, Math.trunc(value)));
+}
+
+/**
+ * Build the child's runtime-only SettingsManager so its SDK retry budget is
+ * bounded. `applyOverrides` is in-memory: the shared settings.json is never
+ * written. Feature-detected for older Pi runtimes; a failure here means the
+ * child keeps the parent's settings and the chain simply waits that budget out.
+ */
+function createChildSettingsManager(
+  sdk: unknown,
+  cwd: string,
+  agentDir: string,
+  providerRetries: number | undefined,
+): unknown | undefined {
+  try {
+    const holder = sdk as {
+      SettingsManager?: { create?: (...args: unknown[]) => unknown };
+    };
+    const SettingsManager = holder?.SettingsManager;
+    const create = SettingsManager?.create;
+    if (typeof create !== "function") return undefined;
+    const manager = create.call(SettingsManager, cwd, agentDir) as {
+      getRetrySettings?: () => Record<string, unknown>;
+      applyOverrides?: (overrides: unknown) => void;
+    };
+    if (!manager || typeof manager !== "object") return undefined;
+    if (typeof manager.applyOverrides !== "function") return manager;
+    const base =
+      typeof manager.getRetrySettings === "function"
+        ? manager.getRetrySettings()
+        : { enabled: true, maxRetries: 3, baseDelayMs: 2_000, maxAgentDelayMs: 60_000 };
+    manager.applyOverrides({
+      retry: {
+        ...base,
+        enabled: true,
+        maxRetries: clampProviderRetries(providerRetries),
+      },
+    });
+    return manager;
+  } catch {
+    return undefined;
+  }
+}
+
 function wrapAgentSession(
   raw: unknown,
   modelLabel: string,
@@ -2421,6 +2830,14 @@ export async function createReviewSession(
     // custom tools too, so a built-ins-only list would silently remove
     // `review_submit_plan` and make every review fail (see REVIEW_BUILTIN_TOOLS).
     const expectedTools = reviewToolAllowlist(options.customTools);
+    // The child gets its own retry budget. The shared settings file is not
+    // touched: applyOverrides is runtime-only.
+    const settingsManager = createChildSettingsManager(
+      sdk,
+      options.cwd,
+      options.agentDir,
+      options.providerRetries,
+    );
 
     process.env[REVIEW_CHILD_MARKER_ENV] = "1";
     let created: { session?: unknown; modelFallbackMessage?: string };
@@ -2435,6 +2852,7 @@ export async function createReviewSession(
         customTools: options.customTools as never,
         resourceLoader: loader,
         sessionManager,
+        ...(settingsManager ? { settingsManager } : {}),
         sessionStartEvent: { type: "session_start", reason: "startup" },
       } as never);
     } finally {