@dieulc/workflow 0.3.0 → 0.3.3

package/README.md

@@ -190,6 +190,46 @@ The reviewer is an in-process child session created with `createAgentSession`, a
 
 An environment marker (`PI_WORKFLOW_REVIEW_CHILD`) is set only for the duration of session creation and restored immediately — the child runs in the same process, so leaking it would affect a later `/reload`.
 
+### Provider seeding
+
+The isolation above has one consequence: a provider that exists **only** because an extension registered it in the parent session (`pi.registerProvider(...)`) does not exist in the reviewer's freshly created runtime — every review round would fail with `No API key found for <provider>.` even though `/login` had stored a valid credential.
+
+Pi composes providers from three sources: the **built-in catalog**, the **static `~/.pi/agent/models.json`**, and **extension registrations** on the parent runtime. Only the last one is parent-only. Review Mode bridges it with a **present-probe**, not layer names (`review-providers.ts`):
+
+1. **Probe the parent** for a provider-registration surface: the session's model registry (`ctx.modelRegistry`) first, then the underlying runtime (`ctx.modelRuntime`). Both expose the same three accessors; a future Pi surface is picked up by adding one entry to the probe list.
+2. **Compare with the child.** Providers the child already composes are skipped. The built-in catalog and `~/.pi/agent/models.json` are loaded by *every* runtime by construction, so for them the seeder is a guaranteed no-op — and any future globally-composed provider source is skipped automatically, with zero layer-name drift.
+3. **Seed the difference, native-first.** For every provider the parent knows and the child does not, the seeder registers the parent's provider *object* when there is one, otherwise its config — each in its own try/catch, so a broken unrelated provider can never block a review. Idempotent: already-seeded ids are skipped on a second pass.
+4. **Preflight auth, provider-agnostically.** After seeding and before the session is created, the reviewer runtime is asked `hasConfiguredAuth(provider) || checkAuth(provider)` for the *reviewer model's own* provider. On absence the review fails fast with the provider name, the seed report, and the universal escape hatch below — never the bare mid-review error.
+
+Every bridged method is feature-detected: on a Pi version without a given accessor the seeder degrades to "nothing to seed" and the preflight reports the escape hatch instead of crashing.
+
+**The universal escape hatch (works for any provider, even without this fix):** `~/.pi/agent/models.json` is loaded by every runtime, including the reviewer's:
+
+```json
+{
+  "providers": {
+    "<provider>": {
+      "baseUrl": "https://…/v1",
+      "apiKey": "$MY_API_KEY",
+      "api": "openai-completions",
+      "models": [
+        {
+          "id": "<model-id>",
+          "name": "<display name>",
+          "reasoning": true,
+          "input": ["text"],
+          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
+          "contextWindow": 200000,
+          "maxTokens": 65536
+        }
+      ]
+    }
+  }
+}
+```
+
+A stored credential (`/login <provider>` → `auth.json`) always wins over the `apiKey` template, so `$MY_API_KEY` needs no environment variable while you are logged in. Extensions that register the same provider at runtime keep working: their live model list replaces the static one in the parent, so nothing regresses there.
+
 ### Configuration
 
 Settings live under `workflow.reviewMode` in `~/.pi/agent/settings.json` (global) or `<cwd>/.pi/settings.json` (project). Project values win field-by-field over global. Writing them preserves every other key in the file.
@@ -222,7 +262,7 @@ Review Mode settings live under `workflow.reviewMode`:
 
 ## How it works
 
-See `index.ts`, `checkpoint.ts` (shadow bare-repo), `utils.ts` (safe-command gating, todo/plan extraction, plan hashing), `roles.ts` (role registry, one model per role), and the Review Mode modules: `review.ts` (config, prompt, state, transcript, child session — no runtime imports, so it is unit-testable), `review-tools.ts` (the reviewer's tool set), `review-runtime.ts` (round orchestration), `review-ui.ts` (the main-transcript entries: line buffer, formatters, renderers). Hot-reload via `/reload` when placed in `~/.pi/agent/extensions/workflow/` or loaded via `pi.extensions` manifest.
+See `index.ts`, `checkpoint.ts` (shadow bare-repo), `utils.ts` (safe-command gating, todo/plan extraction, plan hashing), `roles.ts` (role registry, one model per role), and the Review Mode modules: `review.ts` (config, prompt, state, transcript, child session — no runtime imports, so it is unit-testable), `review-providers.ts` (parent→reviewer provider seeding and the provider-agnostic auth preflight), `review-tools.ts` (the reviewer's tool set), `review-runtime.ts` (round orchestration), `review-ui.ts` (the main-transcript entries: line buffer, formatters, renderers). Hot-reload via `/reload` when placed in `~/.pi/agent/extensions/workflow/` or loaded via `pi.extensions` manifest.
 
 ### Todo protocol (industry-aligned)
 
@@ -232,6 +272,34 @@ See `index.ts`, `checkpoint.ts` (shadow bare-repo), `utils.ts` (safe-command gat
 - **Reminder cadence** (Claude Code-style throttle): a hidden `[TODO LIST]` context block is injected only when `turnsSinceLastTodoWrite ≥ TURNS_SINCE_WRITE` **and** `turnsSinceLastReminder ≥ TURNS_BETWEEN_REMINDERS` (`=3`). Unresolved `[DONE:…]` refs from the previous turn bypass the throttle once so the model learns the right numbers. A one-line `[TODO …]` footer is appended to the first successful `edit`/`write`/`bash` result of each turn.
 - **Stale notice (no forced turns)**: if a run mutated files but recorded no todo progress, the user gets one `⚠` status marker + a `ctx.ui.notify` (30 s dedupe); plan-file `- [x]` ticks are reconciled at `agent_end` in all modes, skipped when the plan content is unchanged (path+hash guard). No auto-completion — the list is never marked done based on intent. Legacy lists that already contain duplicate rows are not auto-merged; run `/todos clear` (or approve a new plan) to reset.
 
+## Troubleshooting
+
+### `No API key found for <provider>.` in a Review Mode round
+
+The transcript shows `Review Mode: … (could not prompt the reviewer: No API key found for <provider>.)`. This means the **reviewer session** could not compose auth for the provider — your login itself is fine (Plan/Build keep working off the same `auth.json`).
+
+The reviewer runs in an isolated session without ambient extensions by design (see [Provider seeding](#provider-seeding)), so a provider registered only by an extension in the parent session is invisible to it unless seeded, and its auth must resolve on its own. Since 0.3.2 the provider is seeded automatically and a missing auth fails fast with a message naming the provider, what the seed found, and the escape hatch.
+
+Fixes, in order of preference:
+
+1. **`/login <provider>`** — a stored credential in `~/.pi/agent/auth.json` is read by every runtime, including the reviewer's. No environment variable needed.
+2. **Static provider in `~/.pi/agent/models.json`** — the universal workaround (works even on an installed version without the seeding fix): add the provider under `"providers"` with `baseUrl`, `apiKey: "$MY_API_KEY"`, `api` and its `models` (template in [Provider seeding](#provider-seeding)).
+3. **`export MY_API_KEY=…`** — only needed when the provider config references `"$MY_API_KEY"` and no credential is stored.
+
+After editing `models.json`, run `/reload` or restart `pi` so every runtime picks it up.
+
+### `the reviewer's provider failed after N retry attempt(s): …` in a Review Mode round
+
+The warning reads `review skipped (the reviewer's provider failed after 3 retry attempt(s): 429 Too Many Requests …)` and the reviewer pane shows the provider's error text live. This is the reviewer's **model provider** failing mid-run — its API returned errors until Pi's auto-retry budget (`settings.retry.maxRetries`, default 3) ran out, so the run settled without ever reaching `review_submit_plan`. It is **not** a Review Mode fault and nothing was written; the author's plan is handed over unchanged.
+
+Earlier versions mislabeled this as `the reviewer finished without submitting a plan — it has no write path…`; since 0.3.3 the real provider error is captured from the reviewer session and reported here, in the pane, and via `/review-status` (the old message now appears only when the reviewer genuinely settled without calling `review_submit_plan`).
+
+What to do:
+
+1. **Check the provider** — the truncated message is the provider's own reply (rate limit, quota, overloaded, auth). Retry the review with `/review` once the provider recovers; a review that dies this way can simply be re-run.
+2. **A long review shares one API key with the parent** — planner + reviewer often hit the same key, so a long review can exhaust rate limits. Stagger heavy Plan Mode work or raise the provider's quota.
+3. **Switch the reviewer model** if the failures recur — `/role set reviewer <provider/model>` (see [Review Mode](#review-mode)); pick a model whose provider is currently healthy.
+
 ## Development
 
 ```bash

package/index.ts

@@ -132,6 +132,7 @@ import {
   type ReviewTranscriptOp,
 } from "./review.ts";
 import { createReviewRuntime, type ReviewRuntime } from "./review-runtime.ts";
+import { findParentProviderSurface } from "./review-providers.ts";
 import {
   createReviewBandGate,
   createReviewLineBuffer,
@@ -891,6 +892,13 @@ export default function workflowExtension(pi: ExtensionAPI) {
       },
       findModel: (provider: string, id: string) =>
         (currentSessionCtx as any)?.modelRegistry?.find?.(provider, id),
+      // Structural probe of the live parent context, evaluated at reviewer
+      // session-creation time. Providers the parent registered (e.g. via an
+      // extension) that the isolated reviewer runtime does not compose yet
+      // are seeded onto it before the session exists; when the probe finds
+      // no surface, nothing is seeded and the preflight reports the escape
+      // hatch. No-op for providers every runtime composes by construction.
+      parentProviders: () => findParentProviderSurface(currentSessionCtx),
       planPath: () => currentPlanFile,
       readPlan: () => {
         const p = currentPlanFile;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dieulc/workflow",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "type": "module",
   "private": false,
   "keywords": ["pi-package", "workflow", "plan-mode", "review-mode", "questionnaire", "rewind"],
@@ -29,6 +29,7 @@
     "roles.ts",
     "permissions.ts",
     "review.ts",
+    "review-providers.ts",
     "review-tools.ts",
     "review-runtime.ts",
     "review-ui.ts",

package/review-providers.ts

@@ -0,0 +1,406 @@
+/**
+ * Provider seeding for Review Mode's reviewer session.
+ *
+ * Why this exists: `createReviewSession()` builds the reviewer as an isolated
+ * child (`noExtensions: true`, its own `ModelRuntime`). That isolation is
+ * deliberate — the reviewer must not inherit ambient extensions — but it has
+ * one consequence: a provider that is registered ONLY by an extension in the
+ * parent session (e.g. `pi.registerProvider("synthetic", …)`) does not exist in
+ * the child's runtime, so the child's prompt preflight throws
+ * `No API key found for <provider>.` even though `auth.json` holds a valid
+ * credential for it.
+ *
+ * The fix is a *present-probe*, not layer names: the seeder asks the child
+ * runtime what it already composes (`getRegisteredProviderIds()`), asks the
+ * parent surface for the same list, and registers only the difference —
+ * native provider objects first, plain provider configs otherwise. Providers
+ * the child already composes by construction (Pi's provider catalog and
+ * `~/.pi/agent/models.json` — every `ModelRuntime` loads both) never appear in
+ * these id lists at all, so the probe is automatically a no-op for them and for
+ * any future provider source Pi composes globally. No code here mentions or
+ * branches on provider layers; grep this file for "built-in"/"extension" to
+ * confirm the decision logic stays structural.
+ *
+ * Everything is feature-detected and per-provider fault-isolated:
+ * - a missing method degrades to "nothing to seed / cannot verify" — never a
+ *   crash (the dev-dependency pins a different Pi version than is installed);
+ * - a broken unrelated provider registration is recorded in `errors` and must
+ *   never block a review.
+ */
+
+/**
+ * A provider registration as the parent holds it, copied opaquely to the
+ * child. The seeder never interprets a field — the child runtime validates
+ * and composes it exactly as it would a registration of its own.
+ */
+interface ProviderRegistration {
+  /** Provider id (present on native provider objects). */
+  readonly id?: string;
+  readonly [field: string]: unknown;
+}
+
+/**
+ * The parent-side provider-registration surface the seeder reads from.
+ *
+ * Structural, not nominal: any object exposing these three accessors
+ * qualifies. Both real Pi surfaces — the session's `ModelRegistry` facade
+ * (`ctx.modelRegistry`) and its underlying `ModelRuntime` (`ctx.modelRuntime`)
+ * — expose exactly this shape; a future surface is picked up by adding one
+ * entry to `PARENT_SURFACE_KEYS`.
+ */
+export interface ParentProviderSurface {
+  getRegisteredProviderIds(): readonly string[];
+  getRegisteredProviderConfig(providerId: string): ProviderRegistration | undefined;
+  getRegisteredNativeProvider(providerId: string): ProviderRegistration | undefined;
+}
+
+/** One provider that could not be seeded, with the reason. */
+export interface ProviderSeedError {
+  name: string;
+  error: string;
+}
+
+/** What one seeding pass did (or did not) do. */
+export interface ProviderSeedResult {
+  /** Ids that were newly registered on the child runtime. */
+  seeded: string[];
+  /** Parent ids the child already composes — untouched, proving the no-op. */
+  skippedPresent: string[];
+  /** Per-provider failures; the review is never blocked by these. */
+  errors: ProviderSeedError[];
+}
+
+export interface ProviderGapScan {
+  /** Parent ids the child does not compose yet. */
+  missing: string[];
+  /** Parent ids the child already composes. */
+  present: string[];
+}
+
+/** Junk-tolerant `getRegisteredProviderIds()` reader. Empty when unavailable. */
+function registeredIdsOn(surface: unknown): string[] {
+  try {
+    const get = (surface as { getRegisteredProviderIds?: unknown } | undefined)
+      ?.getRegisteredProviderIds;
+    if (typeof get !== "function") return [];
+    const ids = (get as (this: unknown) => unknown).call(surface);
+    if (!Array.isArray(ids)) return [];
+    const seen = new Set<string>();
+    for (const id of ids) {
+      if (typeof id === "string" && id.trim()) seen.add(id.trim());
+    }
+    return [...seen];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Structural probe: does this object expose the full provider-registration
+ * surface (id list + both getters)? Both real Pi surfaces — the parent
+ * runtime and its `ModelRegistry` facade — expose all three; anything less
+ * cannot seed anything, so it is treated as "no surface".
+ */
+function isProviderSurface(value: unknown): value is ParentProviderSurface {
+  if (typeof value !== "object" || value === null) return false;
+  const s = value as Partial<ParentProviderSurface>;
+  return (
+    typeof s.getRegisteredProviderIds === "function" &&
+    typeof s.getRegisteredProviderConfig === "function" &&
+    typeof s.getRegisteredNativeProvider === "function"
+  );
+}
+
+/**
+ * Public alias for the structural probe, so callers can distinguish a parent
+ * with no surface (worth reporting) from a surface that had nothing to give
+ * (a normal no-op).
+ */
+export function isParentProviderSurface(value: unknown): boolean {
+  return isProviderSurface(value);
+}
+
+/**
+ * Find a provider-registration surface on the parent context, trying the
+ * documented public surfaces in order. Returns `undefined` when none exists —
+ * callers must treat that as "nothing to seed", never as an error.
+ *
+ * The list is the extension point for future Pi versions: add one entry and
+ * the new surface is picked up without touching the seeder.
+ */
+const PARENT_SURFACE_KEYS = ["modelRegistry", "modelRuntime"] as const;
+
+/**
+ * Find a provider-registration surface on the parent context, trying the
+ * documented public surfaces in order. Returns `undefined` when none exists —
+ * callers must treat that as "nothing to seed", never as an error.
+ */
+export function findParentProviderSurface(
+  ctxLike: unknown,
+): ParentProviderSurface | undefined {
+  if (typeof ctxLike !== "object" || ctxLike === null) return undefined;
+  const holder = ctxLike as Record<string, unknown>;
+  for (const key of PARENT_SURFACE_KEYS) {
+    try {
+      const candidate = holder[key];
+      if (isProviderSurface(candidate)) return candidate;
+    } catch {
+      /* a throwing getter is just not a usable surface */
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Compare the parent surface's registrations with what the child already
+ * composes. Never throws; a feature-detection failure on either side degrades
+ * to the safest scan (empty child set ⇒ everything in the parent counts as
+ * missing — re-registering is a merge, not a clobber).
+ */
+export function collectMissingChildProviders(
+  childRuntimeLike: unknown,
+  parentSurfaceLike: unknown,
+): ProviderGapScan {
+  const childIds = new Set(registeredIdsOn(childRuntimeLike));
+  const parentIds = registeredIdsOn(parentSurfaceLike);
+  const missing: string[] = [];
+  const present: string[] = [];
+  for (const id of parentIds) {
+    if (childIds.has(id)) present.push(id);
+    else missing.push(id);
+  }
+  return { missing, present };
+}
+
+/**
+ * Seed the child runtime with the parent surface's provider registrations.
+ *
+ * Per missing id: register the provider object when the parent has one, else
+ * the provider config. Every id is individually fault-isolated — a malformed
+ * registration is recorded in `errors` and the remaining ids are still seeded.
+ * Idempotent: ids the child already composes are skipped, so a repeated call
+ * (or a shared runtime) is a no-op for them.
+ *
+ * Never throws. On the real Pi runtime each registration also triggers a
+ * network-off, fire-and-forget catalog refresh — local composition only.
+ */
+export function seedChildRuntimeProviders(
+  modelRuntimeLike: unknown,
+  parentSurfaceLike: unknown,
+): ProviderSeedResult {
+  const result: ProviderSeedResult = {
+    seeded: [],
+    skippedPresent: [],
+    errors: [],
+  };
+  try {
+    if (!isProviderSurface(parentSurfaceLike)) return result;
+    const gap = collectMissingChildProviders(modelRuntimeLike, parentSurfaceLike);
+    result.skippedPresent = gap.present;
+    for (const id of gap.missing) {
+      try {
+        const getNative = parentSurfaceLike.getRegisteredNativeProvider as (
+          this: unknown,
+          providerId: string,
+        ) => unknown;
+        const native =
+          typeof getNative === "function" ? getNative.call(parentSurfaceLike, id) : undefined;
+        if (native !== undefined && native !== null) {
+          const registerNative = (modelRuntimeLike as {
+            registerNativeProvider?: unknown;
+          })?.registerNativeProvider;
+          if (typeof registerNative !== "function") {
+            throw new Error(
+              "the reviewer runtime does not expose registerNativeProvider",
+            );
+          }
+          (registerNative as (this: unknown, p: unknown) => void).call(
+            modelRuntimeLike,
+            native,
+          );
+        } else {
+          const getConfig = parentSurfaceLike.getRegisteredProviderConfig as (
+            this: unknown,
+            providerId: string,
+          ) => unknown;
+          const config =
+            typeof getConfig === "function"
+              ? getConfig.call(parentSurfaceLike, id)
+              : undefined;
+          if (config === undefined || config === null) {
+            throw new Error(
+              "the parent surface has no registration to copy for this id",
+            );
+          }
+          const registerProvider = (modelRuntimeLike as {
+            registerProvider?: unknown;
+          })?.registerProvider;
+          if (typeof registerProvider !== "function") {
+            throw new Error(
+              "the reviewer runtime does not expose registerProvider",
+            );
+          }
+          (registerProvider as (this: unknown, id: string, c: unknown) => void).call(
+            modelRuntimeLike,
+            id,
+            config,
+          );
+        }
+        result.seeded.push(id);
+      } catch (e: unknown) {
+        result.errors.push({
+          name: id,
+          error: e instanceof Error ? e.message : String(e),
+        });
+      }
+    }
+  } catch {
+    /* the probe itself misbehaved: report "did nothing" rather than throw */
+  }
+  return result;
+}
+
+/** Outcome of the reviewer's provider-auth preflight. */
+export interface ReviewerAuthCheck {
+  configured: boolean;
+  /** `hasConfiguredAuth` said yes (snapshot). */
+  viaSnapshot: boolean;
+  /** `checkAuth` resolved to something (credential resolution). */
+  viaCheckAuth: boolean;
+  /** True when the runtime exposes neither accessor (cannot verify — trust). */
+  unverifiable: boolean;
+}
+
+/**
+ * Provider-agnostic reviewer auth preflight, mirroring the child session's own
+ * prompt gate (`hasConfiguredAuth(provider) || checkAuth(provider) !==
+ * undefined`) but tolerating a runtime that exposes neither accessor (old or
+ * stubbed SDKs): "cannot verify" proceeds rather than blocks. Feature-detected
+ * and never throws; a throwing `checkAuth` counts as "not configured".
+ */
+export async function checkReviewerProviderAuth(
+  runtimeLike: unknown,
+  providerId: string,
+): Promise<ReviewerAuthCheck> {
+  let viaSnapshot = false;
+  let sawSnapshotAccessor = false;
+  try {
+    const has = (runtimeLike as { hasConfiguredAuth?: unknown })
+      ?.hasConfiguredAuth;
+    if (typeof has === "function") {
+      sawSnapshotAccessor = true;
+      viaSnapshot =
+        (has as (this: unknown, id: string) => unknown).call(
+          runtimeLike,
+          providerId,
+        ) === true;
+    }
+  } catch {
+    viaSnapshot = false;
+  }
+  if (viaSnapshot) {
+    return { configured: true, viaSnapshot: true, viaCheckAuth: false, unverifiable: false };
+  }
+  let viaCheckAuth = false;
+  let sawCheckAuthAccessor = false;
+  try {
+    const check = (runtimeLike as { checkAuth?: unknown })?.checkAuth;
+    if (typeof check === "function") {
+      sawCheckAuthAccessor = true;
+      const resolved = await (check as (this: unknown, id: string) => unknown).call(
+        runtimeLike,
+        providerId,
+      );
+      viaCheckAuth = resolved !== undefined && resolved !== null;
+    }
+  } catch {
+    viaCheckAuth = false;
+  }
+  const unverifiable = !sawSnapshotAccessor && !sawCheckAuthAccessor;
+  return {
+    configured: viaCheckAuth || unverifiable,
+    viaSnapshot: false,
+    viaCheckAuth,
+    unverifiable,
+  };
+}
+
+/** One-line summary of a seed result, for preflight/failure messages. */
+export function describeSeedResult(result: ProviderSeedResult): string {
+  const parts: string[] = [];
+  parts.push(
+    result.seeded.length > 0
+      ? `seeded into the reviewer runtime: ${result.seeded.join(", ")}`
+      : "nothing needed seeding",
+  );
+  parts.push(
+    result.skippedPresent.length > 0
+      ? `already present: ${result.skippedPresent.join(", ")}`
+      : "none were already present",
+  );
+  parts.push(
+    result.errors.length > 0
+      ? `failed: ${result.errors
+          .map((e) => `${e.name} (${e.error})`)
+          .join("; ")}`
+      : "no failures",
+  );
+  return parts.join("; ");
+}
+
+/**
+ * Build the fail-fast error for a reviewer provider whose auth could not be
+ * resolved after seeding. Names the provider, reports what the seed found,
+ * and gives the generic escape hatch that works for ANY provider.
+ */
+export function unconfiguredReviewerProviderMessage(input: {
+  providerId: string;
+  seed: ProviderSeedResult;
+  /** Parent surface was absent entirely (no probe hit). */
+  parentSurfaceFound: boolean;
+  modelsJsonPath?: string;
+}): string {
+  const modelsJson =
+    input.modelsJsonPath ?? "~/.pi/agent/models.json";
+  const seedSummary = input.parentSurfaceFound
+    ? describeSeedResult(input.seed)
+    : "the parent session exposed no provider-registration surface, so nothing could be seeded";
+  const lines = [
+    `the reviewer session has no usable auth for provider "${input.providerId}".`,
+    `Provider seeding: ${seedSummary}.`,
+    `The reviewer runs in an isolated session without ambient extensions, so a provider registered only in the parent session must be seeded (above) AND its auth must be resolvable on its own.`,
+    `Fix any one of:`,
+    `  1. run /login ${input.providerId} — the stored credential is read by every runtime, including the reviewer's;`,
+    `  2. add a static provider entry to ${modelsJson} — that file is loaded by every runtime, including the reviewer's:`,
+    `       { "providers": { "${input.providerId}": { "baseUrl": "…", "apiKey": "$MY_API_KEY", "api": "openai-completions", "models": [ … ] } } }`,
+    `  3. export MY_API_KEY in the environment when the provider config references "$MY_API_KEY".`,
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * Defensive hint appended to a mid-run pass-1 failure that still carries the
+ * bare provider-auth text. After seeding + preflight this path should be rare;
+ * it is the safety net for any future provider-source gap.
+ *
+ * Only fires when the error text matches the provider-auth failure shape AND
+ * the failing provider (extracted from the text) matches the reviewer's own
+ * provider id — an unrelated error must never gain a misleading hint.
+ */
+export function appendProviderAuthHint(
+  errorText: string,
+  providerId: string | undefined,
+  modelsJsonPath?: string,
+): string {
+  if (!providerId || !errorText) return errorText;
+  const match = errorText.match(/No API key found for\s+([^\s.]+)/);
+  if (!match) return errorText;
+  const failingProvider = match[1];
+  if (failingProvider !== providerId) return errorText;
+  const modelsJson = modelsJsonPath ?? "~/.pi/agent/models.json";
+  return [
+    errorText,
+    `Hint: provider "${providerId}" may only be registered in the parent session; the reviewer session starts without ambient extensions.`,
+    `Run /login ${providerId}, or add a static provider entry to ${modelsJson} (loaded by every runtime, including the reviewer's).`,
+  ].join("\n");
+}

package/review-runtime.ts

@@ -22,13 +22,17 @@
  * instructions — the reviewer only supplies judgement.
  */
 
+import * as path from "node:path";
+
 import {
   DEFAULT_REVIEW_MODE_CONFIG,
   createReviewRoundGate,
   createReviewSession,
   createReviewState,
   planHash,
+  readProviderErrorEvent,
   reviewNeedsVerification,
+  truncateErrorText,
   type CreateReviewSessionOptions,
   type CreateReviewSessionResult,
   type ReviewChildSession,
@@ -44,6 +48,7 @@ import {
   type ReviewVerdict,
   ReviewTranscript as Transcript,
 } from "./review.ts";
+import { appendProviderAuthHint } from "./review-providers.ts";
 import { createReviewTools } from "./review-tools.ts";
 import { renderReviewContextBlock, type ReviewFinding } from "./utils.ts";
 
@@ -71,6 +76,15 @@ export interface ReviewRuntimeDeps {
     | undefined;
   /** Resolve a model from the parent's registry. */
   findModel: (provider: string, id: string) => unknown;
+  /**
+   * Parent-side provider-registration surface for the reviewer runtime, found
+   * with `findParentProviderSurface(ctx)` at session-creation time. Providers
+   * the parent knows that the isolated child does not compose yet are seeded
+   * onto it before `createAgentSession`. Optional: when absent (or when the
+   * probe finds no surface) nothing is seeded and the provider-auth preflight
+   * reports the generic escape hatch instead.
+   */
+  parentProviders?: () => unknown;
   /** Plan path Plan Mode chose (absolute or cwd-relative), if known. */
   planPath: () => string | undefined;
   /** Current plan text on disk, if it exists. */
@@ -279,6 +293,29 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
   let abortController: AbortController | undefined;
   /** True while `runRound` is in flight (gates prompt routing). */
   let roundActive = false;
+  /**
+   * The reviewer's most recent provider failure, captured live from child
+   * events (`auto_retry_start`, failed `auto_retry_end`, an `agent_end` that
+   * stopped on error). Latest wins. Cleared at the start of every pass so a
+   * stale error can never mislabel a later clean settle (see runRound).
+   */
+  let lastProviderError:
+    | { message: string; retries: number; at: number }
+    | undefined;
+
+  /** Record one provider failure. The message arrives pre-decoded, non-empty. */
+  const noteProviderError = (message: string, retries: number): void => {
+    lastProviderError = {
+      message,
+      retries: Math.max(0, Math.trunc(retries)),
+      at: Date.now(),
+    };
+  };
+
+  /** Drop the captured error when a new pass starts. */
+  const clearProviderError = (): void => {
+    lastProviderError = undefined;
+  };
 
   const config = (): ReviewModeConfig => {
     try {
@@ -594,6 +631,11 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
           // Reuse the already-resolved module instead of importing twice.
           loadSdk: async () => sdk,
         };
+        // Probed lazily, at creation time: the parent context is live here.
+        const parentSurface = deps.parentProviders?.();
+        if (parentSurface !== undefined) {
+          createOptions.parentProviders = parentSurface;
+        }
 
         const created: CreateReviewSessionResult =
           await createReviewSession(createOptions);
@@ -633,6 +675,29 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
             }
           }
           const type = readEventType(event);
+          // Capture provider failures as they happen, so a pass that ends
+          // without a submission can be diagnosed with the reviewer's real
+          // API error instead of a generic "no plan" message (see runRound).
+          try {
+            const failure = readProviderErrorEvent(event);
+            if (failure.kind === "retry") {
+              noteProviderError(failure.message, failure.retries);
+            } else if (failure.kind === "exhaust") {
+              noteProviderError(
+                failure.message ||
+                  lastProviderError?.message ||
+                  "provider error (no detail)",
+                failure.retries || lastProviderError?.retries || 0,
+              );
+            } else if (failure.kind === "stop") {
+              noteProviderError(
+                failure.message,
+                lastProviderError?.retries ?? 0,
+              );
+            }
+          } catch {
+            /* error capture is diagnostics only: never break the review */
+          }
           if (type === "agent_settled") {
             noteSettled();
           } else if (type === "agent_end") {
@@ -738,6 +803,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
       // ── Pass 1 ──────────────────────────────────────────────────────
       await settleInFlight(deadline, rc);
       gate.reset();
+      clearProviderError();
       const pass1Prompt = buildPass1Prompt({
         planPath: input.planPath,
         planText: originalPlan,
@@ -755,7 +821,16 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
 
       if (p1.stop === "error") {
         await abortChild();
-        return fail(`could not prompt the reviewer: ${errorText(p1.error)}`);
+        // Safety net for any provider-source gap the preflight could not see:
+        // the bare "No API key found for <provider>." gains the actionable
+        // hint ONLY when the failing provider is the reviewer's own.
+        return fail(
+          `could not prompt the reviewer: ${appendProviderAuthHint(
+            errorText(p1.error),
+            deps.reviewerModel()?.provider,
+            path.join(deps.agentDir, "models.json"),
+          )}`,
+        );
       }
       if (p1.stop === "aborted" || rc.signal.aborted) {
         await abortChild();
@@ -773,10 +848,23 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         // The run is over (or out of time) and nothing reached the plan file.
         // Fail now — waiting longer cannot produce a submission.
         await abortChild();
+        if (p1.stop === "timeout") {
+          return fail(
+            `the reviewer did not finish within ${Math.round((limitMs ?? 0) / 1000)}s and submitted no plan`,
+            originalPlan,
+          );
+        }
+        // A provider failure settles the run without a submission — name the
+        // real cause (with the provider's own message) instead of blaming the
+        // write path. The slot only holds errors captured during THIS pass.
+        if (lastProviderError) {
+          return fail(
+            `the reviewer's provider failed after ${lastProviderError.retries} retry attempt(s): ${truncateErrorText(lastProviderError.message)}`,
+            originalPlan,
+          );
+        }
         return fail(
-          p1.stop === "timeout"
-            ? `the reviewer did not finish within ${Math.round((limitMs ?? 0) / 1000)}s and submitted no plan`
-            : "the reviewer finished without submitting a plan — it has no write path unless review_submit_plan succeeds",
+          "the reviewer finished without submitting a plan — it has no write path unless review_submit_plan succeeds",
           originalPlan,
         );
       }
@@ -802,6 +890,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         setPhase("verifying");
         await settleInFlight(deadline, rc);
         gate.reset();
+        clearProviderError();
         const pass2Prompt = buildPass2Prompt({
           planPath: input.planPath,
           originalPlan,
@@ -811,14 +900,28 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         const p2 = await runPass(2, deadline, rc, () =>
           child.followUp(pass2Prompt),
         );
+        // Name the provider when the verification pass died on one; pass 2
+        // stays best-effort either way — pass 1's plan is never lost to it.
+        const p2Provider = lastProviderError
+          ? `provider error after ${lastProviderError.retries} retry attempt(s): ${truncateErrorText(lastProviderError.message)}`
+          : undefined;
         if (p2.error !== undefined) {
           // Verification is an enhancement: never lose pass 1's plan over it.
           deps.log(
-            `Review Mode verification pass failed (${errorText(p2.error)}) — keeping pass 1's plan.`,
+            p2Provider
+              ? `Review Mode verification pass failed (${p2Provider}; send error: ${errorText(p2.error)}) — keeping pass 1's plan.`
+              : `Review Mode verification pass failed (${errorText(p2.error)}) — keeping pass 1's plan.`,
             "warning",
           );
         } else if (p2.submitted) {
           finalPlan = p2.submitted.planText;
+        } else if (p2Provider) {
+          // The run settled without a submission AND a provider error was
+          // seen this pass: say why, then keep going with pass 1's rewrite.
+          deps.log(
+            `Review Mode verification pass ended without a submission (${p2Provider}) — keeping pass 1's plan.`,
+            "warning",
+          );
         }
         if (p2.stop === "timeout") await abortChild();
       }

package/review-ui.ts

@@ -253,6 +253,7 @@ const LINE_COLORS: Record<ReviewEntryLineKind, ThemeColor> = {
   finding: "warning",
   notice: "warning",
   status: "muted",
+  error: "error",
   user: "success",
 };
 

package/review.ts

@@ -36,6 +36,13 @@ import {
   type ReviewFinding,
   type ReviewTier,
 } from "./utils.ts";
+import {
+  checkReviewerProviderAuth,
+  isParentProviderSurface,
+  seedChildRuntimeProviders,
+  unconfiguredReviewerProviderMessage,
+  type ProviderSeedResult,
+} from "./review-providers.ts";
 
 // Re-exported so `review.ts` is the single import surface for Review Mode.
 export type { ReviewDisposition, ReviewFinding, ReviewTier };
@@ -567,7 +574,8 @@ export type ReviewLineKind =
   | "tool"
   | "finding"
   | "notice"
-  | "status";
+  | "status"
+  | "error";
 
 /** One line in the reviewer pane. Kept small: the pane renders these verbatim. */
 export interface ReviewTranscriptLine {
@@ -1099,6 +1107,103 @@ function truncateLabel(s: string, max: number): string {
   return s.length <= max ? s : `${s.slice(0, max - 1).trimEnd()}…`;
 }
 
+/** Longest provider-error excerpt shown inline in a transcript line. */
+export const MAX_ERROR_TEXT = 160;
+
+/**
+ * One-line excerpt of a provider error message for `notify` and the reviewer
+ * pane. Provider errors are often multi-line JSON blobs; they must become a
+ * single line to survive a transcript entry and a `ui.notify` banner.
+ * Pure and total: empty/undefined input yields "", never throws.
+ */
+export function truncateErrorText(input: unknown, max: number = MAX_ERROR_TEXT): string {
+  const raw = typeof input === "string" ? input : "";
+  const flat = raw.replace(/\s+/g, " ").trim();
+  if (!flat) return "";
+  const cap = Math.max(1, Math.trunc(max));
+  return flat.length <= cap ? flat : `${flat.slice(0, cap - 1).trimEnd()}…`;
+}
+
+/**
+ * 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.
+ */
+export function lastAssistantErrorStop(messages: unknown): string | undefined {
+  if (!Array.isArray(messages)) return undefined;
+  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";
+  }
+  return undefined;
+}
+
+/**
+ * What a child-session event says about provider health, decoded at the
+ * boundary so callers branch on typed values instead of SDK event shapes:
+ *
+ * - `retry`   → the SDK scheduled another attempt (`auto_retry_start`) and
+ *   reported the provider's error message.
+ * - `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).
+ * - `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: "none" };
+
+/** Structural decode of one provider-failure event. Never throws. */
+export function readProviderErrorEvent(
+  event: unknown,
+): ReviewProviderFailure {
+  const e = eventRecord(event);
+  if (!e) return { kind: "none" };
+  const type = typeof e.type === "string" ? e.type : "";
+  if (type === "auto_retry_start") {
+    const message =
+      typeof e.errorMessage === "string" ? e.errorMessage.trim() : "";
+    if (!message) return { kind: "none" };
+    return {
+      kind: "retry",
+      message,
+      retries: readRetryAttempt(e.attempt),
+    };
+  }
+  if (type === "auto_retry_end") {
+    if (e.success !== false) return { kind: "none" };
+    const message = typeof e.finalError === "string" ? e.finalError.trim() : "";
+    return {
+      kind: "exhaust",
+      message,
+      retries: readRetryAttempt(e.attempt),
+    };
+  }
+  if (type === "agent_end") {
+    const message = lastAssistantErrorStop(e.messages);
+    if (message === undefined) return { kind: "none" };
+    return { kind: "stop", message };
+  }
+  return { kind: "none" };
+}
+
+/** Non-negative attempt count from a retry event; 0 when absent or junk. */
+function readRetryAttempt(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? Math.trunc(value)
+    : 0;
+}
+
 /**
  * Human-readable header for a tool call: the tool name plus a short, safe
  * excerpt of its key argument (`▸ read src/app.ts`, `▸ review_bash: git log -5`).
@@ -1170,6 +1275,12 @@ export function formatActionLabel(toolName: unknown, args: unknown): string {
  * `toolLabels` is owned by the stateful caller (`ReviewTranscript`): the end
  * event carries no args, so the start event registers `toolCallId → label` and
  * the end event consumes it. Pure otherwise; junk input never throws.
+ *
+ * Provider failures are surfaced with their real (truncated) text: the
+ * `auto_retry_start` notice carries the provider's message, and a failed
+ * `auto_retry_end` or an `agent_end` that stopped on `stopReason === "error"`
+ * appends an `error` line — a dead provider is then visible in the pane during
+ * the review instead of resurfacing later as a mysterious "no plan" failure.
  */
 export function translateReviewEvent(
   event: unknown,
@@ -1207,15 +1318,70 @@ export function translateReviewEvent(
   if (type === "agent_start") {
     return [{ op: "new", kind: "status", text: "reviewer started" }];
   }
+  return providerErrorOps(e, type);
+}
+
+/**
+ * Provider-error events → transcript lines, split out of
+ * `translateReviewEvent` to keep the dispatcher flat:
+ *
+ * - `agent_end`        → status line, plus an `error` line when the run
+ *   stopped on `stopReason === "error"` (auto-retry disabled, or the first
+ *   failure was not retryable).
+ * - `auto_retry_start` → notice carrying the provider's message (truncated).
+ * - `auto_retry_end`   → `error` line when the retry budget is exhausted
+ *   (`success: false`); a recovered retry (`success: true`) stays silent.
+ *
+ * Unknown types and junk fields degrade to empty ops; never throws.
+ */
+function providerErrorOps(
+  e: Record<string, unknown>,
+  type: string,
+): ReviewTranscriptOp[] {
   if (type === "agent_end") {
-    return [{ op: "new", kind: "status", text: "reviewer finished this run" }];
+    const ops: ReviewTranscriptOp[] = [
+      { op: "new", kind: "status", text: "reviewer finished this run" },
+    ];
+    const failed = lastAssistantErrorStop(e.messages);
+    if (failed) {
+      ops.push({
+        op: "new",
+        kind: "error",
+        text: `reviewer run ended on a provider error: ${truncateErrorText(failed)}`,
+      });
+    }
+    return ops;
   }
   if (type === "auto_retry_start") {
+    const msg = typeof e.errorMessage === "string" ? e.errorMessage : "";
     return [
-      { op: "new", kind: "notice", text: "retrying after a provider error" },
+      {
+        op: "new",
+        kind: "notice",
+        text: msg
+          ? `retrying after a provider error: ${truncateErrorText(msg)}`
+          : "retrying after a provider error",
+      },
     ];
   }
-
+  if (type === "auto_retry_end") {
+    // `success: false` ends the retry loop with the provider still failing —
+    // the run is about to settle on an error stop. `success: true` means a
+    // retry recovered; the earlier notice already covers that case.
+    if (e.success === false) {
+      const detail = truncateErrorText(e.finalError);
+      return [
+        {
+          op: "new",
+          kind: "error",
+          text: detail
+            ? `reviewer retry budget exhausted: ${detail}`
+            : "reviewer retry budget exhausted",
+        },
+      ];
+    }
+    return [];
+  }
   return [];
 }
 
@@ -1443,6 +1609,23 @@ export interface CreateReviewSessionOptions {
   reviewPrompt: string;
   /** Reviewer-only tools, built by the caller. */
   customTools: unknown[];
+  /**
+   * Parent-side provider-registration surface (structural, feature-detected),
+   * found with `findParentProviderSurface(ctx)` — the session's model registry
+   * facade or its underlying model runtime.
+   *
+   * The reviewer session is deliberately created without ambient extensions,
+   * so a provider registered only in the parent session (e.g. by a provider
+   * extension) does not exist in the reviewer's fresh runtime. When this
+   * surface is given, every provider the parent knows that the child does not
+   * yet compose is registered onto the child BEFORE `createAgentSession` —
+   * natively when the parent has a provider object, otherwise by config.
+   * Absent or surface-less ⇒ nothing is seeded and the provider-auth preflight
+   * (below) reports the generic escape hatch instead. Providers the child
+   * already composes are skipped, so this is a no-op for every provider the
+   * runtime builds in by construction.
+   */
+  parentProviders?: unknown;
   /** Injectable for tests; defaults to a real dynamic import. */
   loadSdk?: ReviewSdkLoader;
 }
@@ -1453,6 +1636,8 @@ export interface CreateReviewSessionResult {
   modelLabel: string;
   /** Tool names the child actually has enabled, when the SDK exposes them. */
   activeTools?: string[];
+  /** What provider seeding did before the session was created, when probed. */
+  providerSeed?: ProviderSeedResult;
   error?: string;
 }
 
@@ -1601,6 +1786,36 @@ export async function createReviewSession(
       };
     }
 
+    // Seed providers the child does not compose yet (e.g. providers registered
+    // only in the parent session) BEFORE the session exists. Present-probe:
+    // only the difference is registered, native-first, per-provider
+    // fault-isolated — never fatal, never layer-aware.
+    const providerSeed = seedChildRuntimeProviders(
+      modelRuntime,
+      options.parentProviders,
+    );
+
+    // Provider-agnostic auth preflight, mirroring the child session's own
+    // prompt gate: fail fast here — with the seed report and the generic
+    // escape hatch — instead of mid-review with a bare "No API key found".
+    const auth = await checkReviewerProviderAuth(
+      modelRuntime,
+      options.modelRef.provider,
+    );
+    if (!auth.configured) {
+      return {
+        ok: false,
+        modelLabel,
+        providerSeed,
+        error: unconfiguredReviewerProviderMessage({
+          providerId: options.modelRef.provider,
+          seed: providerSeed,
+          parentSurfaceFound: isParentProviderSurface(options.parentProviders),
+          modelsJsonPath: path.join(options.agentDir, "models.json"),
+        }),
+      };
+    }
+
     // No ambient extensions, no skills/prompts/themes: the reviewer gets exactly
     // the system prompt below and nothing from the user's other packages.
     // Project context files (AGENTS.md etc.) DO load — they are the framework