@expo/code-review-cli 0.3.0 → 0.5.0

package/build/core/opencode.js

@@ -1,6 +1,8 @@
-import { createOpencode } from '@opencode-ai/sdk';
-import { toolMap } from './tools.js';
-import { errorMessage, sleep } from './util.js';
+import { createRequire } from "node:module";
+import path from "node:path";
+import { createOpencode } from "@opencode-ai/sdk";
+import { toolMap } from "./tools.js";
+import { errorMessage, sleep } from "./util.js";
 /** Sum token usage across attempts (for per-task/run totals). */
 export function addTokenUsage(into, from) {
     if (!from) {
@@ -17,27 +19,32 @@ export function addTokenUsage(into, from) {
 }
 // The coordinator consolidates findings; it needs no repo tools.
 const COORDINATOR_TOOLS = toolMap([]);
+// Every tool disabled, passed per-REQUEST (not per-agent) to make a "reply now,
+// don't investigate" prompt physically unable to call tools. A prompt-level plea is
+// not enough: in eas-cli#4084 the finalize ("stop and return what you have") reply
+// opened 7 more files and then blew its window, losing the whole pass.
+const NO_TOOLS = toolMap([]);
 // Agent id for the single combined cross-cutting pass (see review.ts). It MUST be
 // defined here so OpenCode uses this restricted tool set — otherwise the model
 // falls back to a default agent with full tools and crawls the whole repo, which
 // is why the cross-file pass used to wander for its entire time budget.
-export const CROSS_CUTTING_AGENT = 'cross-cutting';
+export const CROSS_CUTTING_AGENT = "cross-cutting";
 // Deliberately NO `glob`/`list`: the cross-file pass is given the changed files'
 // patch paths already, and directory crawling is exactly what made it wander into
 // unrelated packages. `read` (open a known file) + `grep` (find a cross-reference
 // among the changed files) are enough to trace interactions.
-const CROSS_CUTTING_TOOLS = toolMap(['read', 'grep']);
+const CROSS_CUTTING_TOOLS = toolMap(["read", "grep"]);
 // Verifies a finding by re-reading the actual file (adversarial refute pass). Same
 // restricted tool set — it opens the cited file and checks the claim.
-export const VERIFIER_AGENT = 'verifier';
-const VERIFIER_TOOLS = toolMap(['read', 'grep']);
+export const VERIFIER_AGENT = "verifier";
+const VERIFIER_TOOLS = toolMap(["read", "grep"]);
 /** Build the inline OpenCode config (agents + coordinator) from a repo config. */
 export function buildOpencodeConfig(config) {
     const agent = {};
     for (const reviewer of config.agents) {
         agent[reviewer.id] = {
             description: `${reviewer.id} reviewer`,
-            mode: 'all',
+            mode: "all",
             model: reviewer.model,
             temperature: reviewer.temperature,
             prompt: `You are the ${reviewer.id} code reviewer. Follow the user message exactly and return only the requested JSON.`,
@@ -45,50 +52,261 @@ export function buildOpencodeConfig(config) {
         };
     }
     agent[CROSS_CUTTING_AGENT] = {
-        description: 'Cross-file reviewer: issues spanning multiple changed files.',
-        mode: 'all',
+        description: "Cross-file reviewer: issues spanning multiple changed files.",
+        mode: "all",
         // Use the default reviewing model (agents share it unless overridden).
         model: config.agents[0]?.model ?? config.coordinator.model,
         temperature: config.agents[0]?.temperature ?? 0.1,
-        prompt: 'You are the cross-file code reviewer. Follow the user message exactly and return only the requested JSON.',
+        prompt: "You are the cross-file code reviewer. Follow the user message exactly and return only the requested JSON.",
         tools: CROSS_CUTTING_TOOLS,
     };
     agent[VERIFIER_AGENT] = {
-        description: 'Verifies a finding against the real file (adversarial refute pass).',
-        mode: 'all',
+        description: "Verifies a finding against the real file (adversarial refute pass).",
+        mode: "all",
         model: config.agents[0]?.model ?? config.coordinator.model,
         temperature: config.agents[0]?.temperature ?? 0.1,
-        prompt: 'You verify code-review findings against the actual source. Follow the user message exactly and return only the requested JSON.',
+        prompt: "You verify code-review findings against the actual source. Follow the user message exactly and return only the requested JSON.",
         tools: VERIFIER_TOOLS,
     };
-    agent['coordinator'] = {
-        description: 'Consolidates specialist findings into one decision.',
-        mode: 'all',
+    agent["coordinator"] = {
+        description: "Consolidates specialist findings into one decision.",
+        mode: "all",
         model: config.coordinator.model,
         temperature: config.coordinator.temperature,
-        prompt: 'You are the review coordinator. Follow the user message exactly and return only the requested JSON.',
+        prompt: "You are the review coordinator. Follow the user message exactly and return only the requested JSON.",
         tools: COORDINATOR_TOOLS,
     };
-    return { $schema: 'https://opencode.ai/config.json', agent };
+    // Synthesize a provider block for each upstream-alias auth entry, so one
+    // upstream can be reached with two credentials at once (e.g. "openai" on a
+    // ChatGPT/Codex subscription for the default models, plus an "openai-api"
+    // alias holding a metered API key for pro-tier models the subscription
+    // doesn't offer). The alias's model list is exactly the ids the roster
+    // references under that provider — OpenCode needs custom providers' models
+    // declared, and declaring only what's used keeps the preflight meaningful.
+    const provider = {};
+    const referencedModels = [
+        ...config.agents.map((reviewer) => reviewer.model),
+        config.coordinator.model,
+    ];
+    for (const entry of config.auth) {
+        if (!entry.upstream || !entry.tokenEnv) {
+            continue;
+        }
+        const models = {};
+        for (const id of referencedModels) {
+            const slash = id.indexOf("/");
+            if (slash > 0 && id.slice(0, slash) === entry.provider) {
+                models[id.slice(slash + 1)] = {};
+            }
+        }
+        provider[entry.provider] = {
+            npm: entry.upstream === "openai"
+                ? "@ai-sdk/openai"
+                : entry.upstream === "anthropic"
+                    ? "@ai-sdk/anthropic"
+                    : "@ai-sdk/openai-compatible",
+            name: entry.provider,
+            options: { apiKey: `{env:${entry.tokenEnv}}` },
+            models,
+        };
+    }
+    return {
+        $schema: "https://opencode.ai/config.json",
+        agent,
+        ...(Object.keys(provider).length > 0 ? { provider } : {}),
+    };
 }
 /** hey-api style responses come back as { data, error }; unwrap or throw. */
 function unwrap(res) {
-    if (res && typeof res === 'object' && ('data' in res || 'error' in res)) {
+    if (res && typeof res === "object" && ("data" in res || "error" in res)) {
         if (res.error) {
-            throw new Error(typeof res.error === 'string' ? res.error : JSON.stringify(res.error));
+            throw new Error(typeof res.error === "string" ? res.error : JSON.stringify(res.error));
         }
         return res.data;
     }
     return res;
 }
+/**
+ * Directory holding the `opencode` binary from OUR dependency tree, or null if it
+ * can't be resolved.
+ *
+ * The SDK spawns the server with a bare `launch("opencode", …)`, i.e. whatever comes
+ * first on PATH. That silently couples every run to the machine's global install:
+ * in CI, `npx -p @expo/code-review-cli` puts the temp prefix's `.bin` first and the
+ * pinned version wins, but on a developer machine an older global `opencode` shadows
+ * it and the pair drifts (a 1.18.1 CLI against a 1.18.4 SDK surfaced as
+ * `ProviderModelNotFoundError: Model not found: anthropic/claude-opus-4-8` — the CLI
+ * resolving a model id the SDK considered valid). Prepending this directory to PATH
+ * makes the version we declare in package.json the version we actually run.
+ */
+function bundledOpencodeBinDir() {
+    try {
+        const require = createRequire(import.meta.url);
+        // <…>/node_modules/opencode-ai/package.json → <…>/node_modules/.bin, which holds
+        // the correctly-named `opencode` shim (the package's own bin file is
+        // `opencode.exe`, so the package dir itself is NOT a usable PATH entry).
+        const pkg = require.resolve("opencode-ai/package.json");
+        return path.join(path.dirname(pkg), "..", ".bin");
+    }
+    catch {
+        return null;
+    }
+}
+/** The `opencode` the SDK will actually spawn: ours if resolvable, else PATH's. */
+export function opencodeBinSource() {
+    const dir = bundledOpencodeBinDir();
+    return { dir, pinned: dir !== null };
+}
 /** Start an in-process OpenCode server with the given inline config. */
 export async function startOpencode(config) {
+    // Make our pinned CLI win over any global install (see bundledOpencodeBinDir).
+    // The SDK takes no `env`, so PATH is the only lever; it spreads `process.env` at
+    // spawn time, so setting it here reaches the child.
+    const binDir = bundledOpencodeBinDir();
+    if (binDir) {
+        process.env.PATH = `${binDir}${path.delimiter}${process.env.PATH ?? ""}`;
+    }
     const { client, server } = await createOpencode({
-        hostname: '127.0.0.1',
+        hostname: "127.0.0.1",
+        // Port 0 = let the OS pick a free one. The SDK defaults to a FIXED 4096 and reads
+        // the real URL back from the server's startup line, so the default meant any
+        // already-running opencode (a developer's own session is the common case) made
+        // every local run die with an opaque `ServeError`.
+        port: 0,
         config: config,
     });
     return { client, url: server.url, close: () => server.close() };
 }
+/** `provider/model` as the server reported it, or undefined if it reported neither. */
+export function formatModel(providerID, modelID) {
+    if (!providerID && !modelID) {
+        return undefined;
+    }
+    return `${providerID ?? "?"}/${modelID ?? "?"}`;
+}
+/**
+ * Check configured model ids against what the server can resolve. Pure so the
+ * matching rules are testable without a live server.
+ *
+ * A wrong model id is a CONFIG error: it hits every pass identically, no retry or
+ * smaller scope can fix it, and the run should say so once instead of reporting N
+ * indistinguishable "pass failed" gaps (or, worse, burning the whole budget first).
+ */
+export function findUnknownModels(models, available, 
+/** Provider(s) we supplied a credential for, if any (see reason: "credential"). */
+credentialedProvider) {
+    const credentialed = new Set(typeof credentialedProvider === "string"
+        ? [credentialedProvider]
+        : (credentialedProvider ?? []));
+    const unknown = [];
+    for (const model of new Set(models)) {
+        // OpenCode model ids are `provider/model`; a model id may itself contain slashes
+        // (e.g. openrouter's `vendor/name`), so only the FIRST segment is the provider.
+        const slash = model.indexOf("/");
+        const providerID = slash === -1 ? model : model.slice(0, slash);
+        const modelID = slash === -1 ? "" : model.slice(slash + 1);
+        const providerModels = available[providerID];
+        if (!providerModels) {
+            unknown.push({
+                model,
+                // We configured this provider's credential and the server still doesn't
+                // offer it ⇒ the credential was refused, not the provider misnamed.
+                reason: credentialed.has(providerID) ? "credential" : "provider",
+                suggestions: Object.keys(available).sort(),
+            });
+            continue;
+        }
+        if (!providerModels.includes(modelID)) {
+            // Suggest ids that share a prefix with what was asked for, else the whole list.
+            const stem = modelID.split(/[-/]/)[0] ?? "";
+            const near = stem ? providerModels.filter((id) => id.startsWith(stem)) : [];
+            unknown.push({
+                model,
+                reason: "model",
+                suggestions: (near.length > 0 ? near : providerModels).slice(0, 8).sort(),
+            });
+        }
+    }
+    return unknown;
+}
+/** Ask the running server which providers/models it can resolve. */
+export async function fetchProviderModels(handle) {
+    const data = unwrap(await handle.client.config.providers());
+    const available = {};
+    for (const provider of data?.providers ?? []) {
+        if (provider?.id) {
+            available[provider.id] = Object.keys(provider.models ?? {});
+        }
+    }
+    return available;
+}
+/** Human-readable, copy-pasteable explanation of unresolvable model ids. */
+export function formatUnknownModels(unknown, auths) {
+    // A refused credential is one fact about the run, not one per model: report it once
+    // and name the token to check, rather than repeating it for every configured model.
+    const refused = unknown.filter((entry) => entry.reason === "credential");
+    if (refused.length > 0) {
+        const refusedProvider = refused[0].model.split("/")[0];
+        const entries = auths ? (Array.isArray(auths) ? auths : [auths]) : [];
+        const auth = entries.find((entry) => entry.provider === refusedProvider) ?? entries[0];
+        const provider = auth?.provider ?? refusedProvider;
+        const tokenEnv = auth?.tokenEnv;
+        // Do NOT blame the token alone: the most common causes have nothing to do with
+        // the credential's validity (see below). An earlier version of this message sent
+        // us to re-issue two perfectly good tokens.
+        const oauth = auth?.mode === "oauth";
+        const deadOauth = oauth && provider === "anthropic";
+        return (`The OpenCode server does not offer the "${provider}" provider, even though this run ` +
+            `supplied a ${auth?.mode ?? "configured"} credential for it. OpenCode drops a provider whose ` +
+            `credential it could not use, which makes every ${provider} model look nonexistent: ` +
+            `${refused.map((entry) => entry.model).join(", ")}.\n` +
+            `The credential itself is often FINE. Check these in order:\n` +
+            (deadOauth
+                ? `  1. anthropic OAuth cannot work through OpenCode at all. Anthropic does not permit ` +
+                    `Pro/Max subscription tokens in third-party tools, and OpenCode (since 1.3.0) ships no ` +
+                    `anthropic OAuth support — an oauth credential never registers the provider, no matter ` +
+                    `how valid the token is. Switch auth in .expo-code-review/config.jsonc to ` +
+                    `{ "mode": "api-key", "provider": "anthropic", "tokenEnv": "ANTHROPIC_API_KEY" } with a ` +
+                    `Console API key, or run with REVIEWER_MODEL set to a model you are logged into ` +
+                    `(e.g. REVIEWER_MODEL=openai/gpt-5.5).\n`
+                : "") +
+            (tokenEnv
+                ? `  ${deadOauth ? "2" : "1"}. The credential is wrong for the mode. ` +
+                    `auth.mode "api-key" expects a plain API key for ${provider}; an OAuth/subscription ` +
+                    `token is not an API key. A truncated or half-pasted ${tokenEnv} fails the same way.\n`
+                : `  ${deadOauth ? "2" : "1"}. The credential is wrong for the configured auth.mode.\n`) +
+            `Providers the server does offer: ${refused[0].suggestions.join(", ") || "(none)"}.`);
+    }
+    const lines = unknown.map((entry) => entry.reason === "provider"
+        ? `  ${entry.model} — unknown provider "${entry.model.split("/")[0]}". Configured providers: ${entry.suggestions.join(", ") || "(none — is the credential set?)"}`
+        : `  ${entry.model} — that provider has no such model. Close matches: ${entry.suggestions.join(", ") || "(none)"}`);
+    return (`The configured model id(s) do not exist on the running OpenCode server:\n${lines.join("\n")}\n` +
+        `Fix the model in .expo-code-review/config.jsonc (agents' \`model\`, \`coordinator.model\`) ` +
+        `or REVIEWER_MODEL. Note that a model id must be "provider/model" (e.g. anthropic/claude-sonnet-5), ` +
+        `and that an out-of-date \`opencode\` can reject an id a newer one accepts — run \`ecr doctor\`.`);
+}
+/**
+ * Fail fast when a configured model can't be resolved, BEFORE any pass runs. Never
+ * blocks the run on its own failure: if the providers endpoint can't be read (an
+ * older server, a transport blip), the review proceeds and any real problem surfaces
+ * per-pass as before.
+ */
+export async function assertModelsResolvable(handle, models, auths) {
+    let available;
+    try {
+        available = await fetchProviderModels(handle);
+    }
+    catch {
+        return;
+    }
+    if (Object.keys(available).length === 0) {
+        return;
+    }
+    const unknown = findUnknownModels(models, available, auths?.map((entry) => entry.provider));
+    if (unknown.length > 0) {
+        throw new Error(formatUnknownModels(unknown, auths));
+    }
+}
 const POLL_INTERVAL_MS = 1000;
 // Emit a "still working" heartbeat if this long passes with no tool activity, so
 // a long model-thinking stretch doesn't look hung in the logs.
@@ -100,12 +318,62 @@ const HEARTBEAT_MS = 45_000;
 // over. Callers must treat AgentTimeoutError as "abandon", never "retry".
 const DEFAULT_MAX_WAIT_MS = 8 * 60 * 1000;
 // Extra budget for the "stop and summarize what you have" finalization prompt.
-const FINALIZE_WAIT_MS = 90 * 1000;
-const FINALIZE_PROMPT = 'You have reached your time budget. STOP investigating now — do NOT read, grep, ' +
-    'glob, list, or open any more files, and do not call any tools. Based ONLY on ' +
-    'what you have already examined, reply with the single JSON object exactly as ' +
-    'specified in your instructions, containing whatever findings you are already ' +
-    'confident about. If you have nothing solid, return an empty findings array.';
+// Deliberately generous: this is the ONLY chance to salvage a pass that ran out of
+// time, and at 90s it was losing that race. Tools are disabled for the request
+// (NO_TOOLS), so the reply is a single emit and normally lands in seconds.
+const FINALIZE_WAIT_MS = 3 * 60 * 1000;
+// ---- stall detection ----
+//
+// A pass is STALLED when its in-progress assistant message stops changing at all:
+// no new tool call, no streamed text or reasoning, no token growth. A model that is
+// genuinely thinking still grows that message every few seconds, so a gap this long
+// means the provider request is wedged (or stuck in an internal retry we cannot
+// see) — not that the work is hard.
+//
+// Motivating incident (eas-cli#4084, 2026-07-26): the cross-file pass ran 7 `read`
+// calls in its first 6 seconds and then sat completely silent for 25 minutes,
+// recording ZERO tokens (input, output, reasoning and cache all 0 in the run log),
+// until its wall-clock cap fired. The finalize salvage then also went silent, so the
+// pass's entire work product was lost and the PR got a coverage gap. Nothing in the
+// run distinguished "wedged" from "thinking" — the heartbeat just printed elapsed
+// seconds. A wall-clock cap alone cannot fix this: raising it only buys a longer
+// silence, which is why the cap is NOT the lever here.
+//
+// Unlike the wall-clock cap (non-convergence → abandon, never retry), a stall is
+// transient, so it earns ONE clean-slate retry inside the pass's existing budget.
+const STALL_MS = 4 * 60 * 1000;
+// Never let the watchdog outlast the pass it guards: a short pass (the 3m verifier,
+// a 4m no-tools fallback) would otherwise hit its deadline before the watchdog could
+// fire, and get none of this protection. Half the cap, with a floor that leaves room
+// for a slow first token.
+const MIN_STALL_MS = 30 * 1000;
+/** Exported for tests. */
+export function stallWindowMs(maxWaitMs) {
+    return Math.min(STALL_MS, Math.max(MIN_STALL_MS, Math.floor(maxWaitMs / 2)));
+}
+// The finalize reply does no investigation and cannot call tools, so it should
+// stream within seconds; a much shorter silence already means wedged.
+const FINALIZE_STALL_MS = 60 * 1000;
+// Breathing room before the retry: if the silence came from provider-side throttling
+// or backoff, reconnecting instantly is the worst move.
+const STALL_RETRY_BACKOFF_MS = 20 * 1000;
+// Only retry when enough of the pass's budget remains for the fresh attempt to
+// plausibly finish; otherwise go straight to the soft landing.
+const STALL_RETRY_MIN_REMAINING_MS = STALL_MS + 60 * 1000;
+/**
+ * What to do about a stalled attempt: start over from a clean session, or stop and
+ * try to salvage findings. Exactly ONE retry, and only with enough budget left for it
+ * to land — a second wedged attempt would just spend the rest of the pass's window,
+ * which is the failure this whole mechanism exists to end. Exported for tests.
+ */
+export function stallAction(attempt, remainingMs) {
+    return attempt === 0 && remainingMs > STALL_RETRY_MIN_REMAINING_MS ? "retry" : "soft-land";
+}
+const FINALIZE_PROMPT = "You have reached your time budget. STOP investigating now — do NOT read, grep, " +
+    "glob, list, or open any more files, and do not call any tools. Based ONLY on " +
+    "what you have already examined, reply with the single JSON object exactly as " +
+    "specified in your instructions, containing whatever findings you are already " +
+    "confident about. If you have nothing solid, return an empty findings array.";
 /**
  * Internal signal that a poll loop passed its deadline. Carries the best-effort
  * cost/tokens of the in-progress (never-completed) assistant message so a
@@ -115,12 +383,52 @@ class DeadlineReached extends Error {
     cost;
     tokens;
     constructor(cost = 0, tokens) {
-        super('deadline reached');
+        super("deadline reached");
+        this.cost = cost;
+        this.tokens = tokens;
+    }
+}
+/**
+ * Internal signal that an in-progress reply went silent (see STALL_MS). Distinct
+ * from DeadlineReached: the pass's time budget is NOT spent, so the caller can spend
+ * what's left on a fresh attempt instead of abandoning the work.
+ */
+class NoProgress extends Error {
+    cost;
+    tokens;
+    idleMs;
+    constructor(cost = 0, tokens, 
+    /** How long the reply had been unchanged when we gave up on it. */
+    idleMs = 0) {
+        super("no progress");
         this.cost = cost;
         this.tokens = tokens;
+        this.idleMs = idleMs;
     }
 }
-const DEADLINE_SENTINEL = Symbol('deadline');
+/**
+ * A cheap signature of how far along an in-progress reply is: its parts (count,
+ * type, streamed length, tool status) plus the message's token/cost counters. ANY
+ * real progress — a new tool call, another chunk of text or reasoning, a tool
+ * advancing pending → running → completed — changes it; a wedged request leaves it
+ * byte-identical poll after poll. Exported for tests.
+ */
+export function progressFingerprint(message) {
+    const shape = (message.parts ?? [])
+        .map((part) => `${part.type ?? ""}:${(part.text ?? "").length}:${part.state?.status ?? ""}`)
+        .join("|");
+    const tokens = message.info?.tokens;
+    return [
+        shape,
+        tokens?.input ?? 0,
+        tokens?.output ?? 0,
+        tokens?.reasoning ?? 0,
+        tokens?.cache?.read ?? 0,
+        tokens?.cache?.write ?? 0,
+        message.info?.cost ?? 0,
+    ].join("~");
+}
+const DEADLINE_SENTINEL = Symbol("deadline");
 /**
  * Race a promise against the poll deadline. Without this, a stalled message fetch
  * (a wedged/overloaded OpenCode server) blocks the poll loop past its deadline,
@@ -134,7 +442,7 @@ async function raceDeadline(work, deadline) {
         return DEADLINE_SENTINEL;
     }
     let timer;
-    const timeout = new Promise(resolve => {
+    const timeout = new Promise((resolve) => {
         timer = setTimeout(() => resolve(DEADLINE_SENTINEL), remaining);
     });
     try {
@@ -153,11 +461,22 @@ async function raceDeadline(work, deadline) {
 export class AgentTimeoutError extends Error {
     cost;
     tokens;
-    constructor(agent, minutes, cost = 0, tokens) {
-        super(`Agent "${agent}" timed out after ${minutes} minutes (including finalize)`);
-        this.name = 'AgentTimeoutError';
+    /**
+     * Why the pass was abandoned: it investigated without converging ("time"), or its
+     * model request went silent and did not recover after a fresh attempt ("stall").
+     * The caller's handling is the same (abandon), but the two have different causes —
+     * a wander is ours to bound, a stall is the provider's — so logs and coverage
+     * notes must not conflate them.
+     */
+    reason;
+    constructor(agent, minutes, cost = 0, tokens, reason = "time") {
+        super(reason === "stall"
+            ? `Agent "${agent}" stalled: its model request went silent and produced nothing after a retry (${minutes} minutes)`
+            : `Agent "${agent}" timed out after ${minutes} minutes (including finalize)`);
+        this.name = "AgentTimeoutError";
         this.cost = cost;
         this.tokens = tokens;
+        this.reason = reason;
     }
 }
 /**
@@ -171,72 +490,117 @@ export class AgentTimeoutError extends Error {
  * message completes.
  */
 export async function promptAgent(handle, args) {
-    const session = unwrap(await handle.client.session.create({ body: { title: args.title } }));
-    const reportedTools = new Set();
-    await sendSessionPrompt(handle, session.id, {
-        agent: args.agent,
-        system: args.system,
-        text: args.text,
-    });
     const maxWaitMs = args.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
-    try {
-        return await pollForCompletion(handle, session.id, {
-            agent: args.agent,
-            fromIndex: 0,
-            deadline: Date.now() + maxWaitMs,
-            onActivity: args.onActivity,
-            reportedTools,
-            maxToolCalls: args.maxToolCalls,
-        });
-    }
-    catch (error) {
-        if (!(error instanceof DeadlineReached)) {
-            throw error;
-        }
-        // Cost/tokens burned during the (never-completed) investigation, so the
-        // finalize reply or the abandon path still accounts for them.
-        const spentCost = error.cost;
-        const spentTokens = error.tokens;
-        // Time budget hit. Interrupt the wandering run first.
-        await abortQuietly(handle, session.id);
+    // ONE deadline for the whole pass, shared by the first attempt and any stall
+    // retry, so retrying a wedged request can never push the pass past its declared
+    // cap (the budget math in review.ts depends on that being true).
+    const deadline = Date.now() + maxWaitMs;
+    // Spend from abandoned attempts, carried forward so a wedged attempt's cost and
+    // tokens still land in the run's metrics instead of vanishing.
+    let carriedCost = 0;
+    let carriedTokens;
+    const carry = (result) => ({
+        ...result,
+        cost: result.cost + carriedCost,
+        tokens: addTokenUsage(addTokenUsage({}, carriedTokens), result.tokens),
+    });
+    const absorb = (spent) => {
+        carriedCost += spent.cost;
+        carriedTokens = addTokenUsage(addTokenUsage({}, carriedTokens), spent.tokens);
+    };
+    /**
+     * Last chance to get something out of a pass that hit its ceiling: interrupt the
+     * run and ask the SAME (context-carrying) session for whatever it already has.
+     * Tools are disabled for this request, so it cannot resume investigating — the
+     * only thing it can do is emit.
+     */
+    const softLand = async (sessionID, reason, reportedTools) => {
+        await abortQuietly(handle, sessionID);
+        const minutes = Math.round(maxWaitMs / 60000);
         if (!args.finalizeOnTimeout) {
-            throw new AgentTimeoutError(args.agent, Math.round(maxWaitMs / 60000), spentCost, spentTokens);
+            throw new AgentTimeoutError(args.agent, minutes, carriedCost, carriedTokens, reason);
         }
-        // Soft landing: ask the (same, context-carrying) session to return whatever
-        // it has now. Only messages after this point count as the answer.
-        const baseline = (await fetchMessages(handle, session.id)).length;
-        args.onActivity?.('time budget reached — asking for findings so far');
-        await sendSessionPrompt(handle, session.id, {
+        // Only messages after this point count as the answer.
+        const baseline = (await fetchMessages(handle, sessionID)).length;
+        args.onActivity?.(reason === "stall"
+            ? "no output after a retry — asking for findings so far"
+            : "time budget reached — asking for findings so far");
+        await sendSessionPrompt(handle, sessionID, {
             agent: args.agent,
             system: args.system,
             text: FINALIZE_PROMPT,
+            tools: NO_TOOLS,
         });
         try {
-            const result = await pollForCompletion(handle, session.id, {
+            const result = await pollForCompletion(handle, sessionID, {
                 agent: args.agent,
                 fromIndex: baseline,
                 deadline: Date.now() + FINALIZE_WAIT_MS,
                 onActivity: args.onActivity,
                 reportedTools,
+                stallMs: FINALIZE_STALL_MS,
             });
-            return {
-                ...result,
-                cost: result.cost + spentCost,
-                tokens: addTokenUsage(addTokenUsage({}, spentTokens), result.tokens),
-                truncated: true,
-            };
+            return { ...carry(result), truncated: true };
         }
         catch (finalizeError) {
-            if (finalizeError instanceof DeadlineReached) {
-                await abortQuietly(handle, session.id);
-                throw new AgentTimeoutError(args.agent, Math.round((maxWaitMs + FINALIZE_WAIT_MS) / 60000), spentCost + finalizeError.cost, addTokenUsage(addTokenUsage({}, spentTokens), finalizeError.tokens));
+            if (finalizeError instanceof DeadlineReached || finalizeError instanceof NoProgress) {
+                await abortQuietly(handle, sessionID);
+                absorb(finalizeError);
+                throw new AgentTimeoutError(args.agent, Math.round((maxWaitMs + FINALIZE_WAIT_MS) / 60000), carriedCost, carriedTokens, reason);
             }
             throw finalizeError;
         }
+    };
+    for (let attempt = 0;; attempt++) {
+        const session = unwrap(await handle.client.session.create({
+            body: { title: attempt === 0 ? args.title : `${args.title}-retry${attempt}` },
+        }));
+        const reportedTools = new Set();
+        await sendSessionPrompt(handle, session.id, {
+            agent: args.agent,
+            system: args.system,
+            text: args.text,
+        });
+        try {
+            return carry(await pollForCompletion(handle, session.id, {
+                agent: args.agent,
+                fromIndex: 0,
+                deadline,
+                onActivity: args.onActivity,
+                reportedTools,
+                maxToolCalls: args.maxToolCalls,
+                stallMs: stallWindowMs(maxWaitMs),
+            }));
+        }
+        catch (error) {
+            // Went silent. The request is wedged, not slow, so the first move is a clean
+            // slate — a fresh session, not the finalize prompt, which would be asking the
+            // wedged request to answer. Exactly one retry, and only when enough budget
+            // remains for it to land; after that the finalize is still worth a try as the
+            // only remaining salvage (in eas-cli#4084 the session did respond once aborted).
+            if (error instanceof NoProgress) {
+                await abortQuietly(handle, session.id);
+                absorb(error);
+                const remaining = deadline - Date.now();
+                if (stallAction(attempt, remaining) === "retry") {
+                    args.onActivity?.(`stalled — no output for ${Math.round(error.idleMs / 1000)}s; ` +
+                        `retrying once from a clean session (${Math.round(remaining / 60000)}m of budget left)`);
+                    await sleep(STALL_RETRY_BACKOFF_MS);
+                    continue;
+                }
+                return await softLand(session.id, "stall", reportedTools);
+            }
+            // Ran the clock down while investigating: converge on what it has.
+            if (error instanceof DeadlineReached) {
+                absorb(error);
+                return await softLand(session.id, "time", reportedTools);
+            }
+            throw error;
+        }
     }
 }
-const CORRECTIVE = '\n\nIMPORTANT: your previous reply could not be parsed. Reply with ONLY the single ' +
-    'JSON object described above — no prose, no code fences, no partial output.';
+const CORRECTIVE = "\n\nIMPORTANT: your previous reply could not be parsed. Reply with ONLY the single " +
+    "JSON object described above — no prose, no code fences, no partial output.";
 // Budget for a corrective "re-emit the JSON" reply — no fresh investigation, so
 // it should return almost immediately.
 const CORRECTIVE_WAIT_MS = 2 * 60 * 1000;
@@ -270,7 +634,7 @@ export function isTransientApiError(error) {
         return false;
     }
     const message = errorMessage(error);
-    return TRANSIENT_PATTERNS.some(pattern => pattern.test(message));
+    return TRANSIENT_PATTERNS.some((pattern) => pattern.test(message));
 }
 /**
  * Run a model call, retrying with bounded backoff on a transient API error. This
@@ -307,16 +671,19 @@ async function withTransientRetry(label, onActivity, fn) {
 export async function promptAndParse(handle, args, parse) {
     let cost = 0;
     let truncated = false;
+    let model;
     const tokens = {};
     const record = (result) => {
         cost += result.cost;
         truncated = truncated || (result.truncated ?? false);
         addTokenUsage(tokens, result.tokens);
+        // Keep the model from whichever attempt actually answered.
+        model = result.model ?? model;
     };
     const first = await withTransientRetry(`Agent "${args.agent}"`, args.onActivity, () => promptAgent(handle, args));
     record(first);
     try {
-        return { value: parse(first.text), cost, truncated, tokens };
+        return { value: parse(first.text), cost, truncated, tokens, model };
     }
     catch {
         // Same-session corrective retry: send the nudge as a follow-up and wait for
@@ -327,6 +694,9 @@ export async function promptAndParse(handle, args, parse) {
                 agent: args.agent,
                 system: args.system,
                 text: CORRECTIVE,
+                // Re-emit only: the investigation is done, so no tools are needed and
+                // disabling them keeps the corrective from turning into a second wander.
+                tools: NO_TOOLS,
             });
             const retry = await pollForCompletion(handle, first.sessionID, {
                 agent: args.agent,
@@ -334,9 +704,10 @@ export async function promptAndParse(handle, args, parse) {
                 deadline: Date.now() + CORRECTIVE_WAIT_MS,
                 onActivity: args.onActivity,
                 reportedTools: new Set(),
+                stallMs: FINALIZE_STALL_MS,
             });
             record(retry);
-            return { value: parse(retry.text), cost, truncated, tokens };
+            return { value: parse(retry.text), cost, truncated, tokens, model };
         }
         catch {
             // Fresh-session last resort: a clean slate for a genuinely confused run.
@@ -347,7 +718,7 @@ export async function promptAndParse(handle, args, parse) {
             });
             record(fresh);
             try {
-                return { value: parse(fresh.text), cost, truncated, tokens };
+                return { value: parse(fresh.text), cost, truncated, tokens, model };
             }
             catch (finalError) {
                 throw new Error(`Agent "${args.agent}" did not return parseable JSON after retries: ${finalError instanceof Error ? finalError.message : String(finalError)}`);
@@ -364,7 +735,8 @@ async function sendSessionPrompt(handle, sessionID, args) {
         body: {
             agent: args.agent,
             system: args.system,
-            parts: [{ type: 'text', text: args.text }],
+            parts: [{ type: "text", text: args.text }],
+            ...(args.tools ? { tools: args.tools } : {}),
         },
     }));
 }
@@ -380,7 +752,8 @@ async function abortQuietly(handle, sessionID) {
  * Poll a session for the first assistant message at or after `fromIndex` to
  * complete. `fromIndex` lets a follow-up prompt (finalize, corrective retry)
  * skip the earlier completed message and wait for the NEW reply instead. Throws
- * DeadlineReached once `deadline` passes.
+ * DeadlineReached once `deadline` passes, or NoProgress once the reply has been
+ * unchanged for `stallMs` (see STALL_MS).
  */
 async function pollForCompletion(handle, sessionID, opts) {
     // Best-effort usage of the in-progress assistant message, so a task that times
@@ -389,6 +762,11 @@ async function pollForCompletion(handle, sessionID, opts) {
     let lastTokens;
     const startedAt = Date.now();
     let lastEmitAt = startedAt;
+    // Stall watchdog state: when the reply last changed in any way, and what it looked
+    // like then. Starts at "now" so a prompt that never produces an assistant message
+    // at all (a wedged submission) also trips the watchdog.
+    let lastProgressAt = startedAt;
+    let lastFingerprint = "";
     const emit = (line) => {
         lastEmitAt = Date.now();
         opts.onActivity?.(line);
@@ -399,9 +777,14 @@ async function pollForCompletion(handle, sessionID, opts) {
         }
         await sleep(POLL_INTERVAL_MS);
         // Heartbeat if nothing has been reported for a while (e.g. the model is
-        // reasoning without calling tools), so a long pass doesn't look hung.
+        // reasoning without calling tools), so a long pass doesn't look hung. Say how
+        // long the reply has been unchanged, not just how long the pass has run — that
+        // distinction is what tells a slow investigation apart from a wedged request,
+        // and its absence is why eas-cli#4084 took a forensic dig to explain.
         if (opts.onActivity && Date.now() - lastEmitAt >= HEARTBEAT_MS) {
-            emit(`still working… ${Math.round((Date.now() - startedAt) / 1000)}s elapsed`);
+            const idleMs = Date.now() - lastProgressAt;
+            emit(`still working… ${Math.round((Date.now() - startedAt) / 1000)}s elapsed` +
+                (idleMs >= HEARTBEAT_MS ? ` (no new output for ${Math.round(idleMs / 1000)}s)` : ""));
         }
         // Bound the fetch by the deadline: a stalled server can't push the task past
         // its time cap (the overshoot we saw when the server was overloaded).
@@ -410,28 +793,34 @@ async function pollForCompletion(handle, sessionID, opts) {
             throw new DeadlineReached(lastCost, lastTokens);
         }
         const recent = messages.slice(opts.fromIndex);
-        const assistant = [...recent].reverse().find(message => message.info?.role === 'assistant');
+        const assistant = [...recent].reverse().find((message) => message.info?.role === "assistant");
         if (!assistant) {
             continue;
         }
-        if (typeof assistant.info?.cost === 'number') {
+        if (typeof assistant.info?.cost === "number") {
             lastCost = assistant.info.cost;
         }
         if (assistant.info?.tokens) {
             lastTokens = assistant.info.tokens;
         }
+        // Stall watchdog: did the reply change AT ALL since the last poll?
+        const fingerprint = progressFingerprint(assistant);
+        if (fingerprint !== lastFingerprint) {
+            lastFingerprint = fingerprint;
+            lastProgressAt = Date.now();
+        }
         // Track each distinct tool call once (for the tool-call cap) and, the first
         // time it starts, emit a live line so a long run shows what the agent is doing.
         for (const part of assistant.parts ?? []) {
-            if (part?.type !== 'tool') {
+            if (part?.type !== "tool") {
                 continue;
             }
             const key = part.callID ?? part.id;
             const status = part.state?.status;
-            if (key && status && status !== 'pending' && !opts.reportedTools.has(key)) {
+            if (key && status && status !== "pending" && !opts.reportedTools.has(key)) {
                 opts.reportedTools.add(key);
                 if (opts.onActivity) {
-                    const tool = part.tool ?? 'tool';
+                    const tool = part.tool ?? "tool";
                     const title = part.state?.title;
                     emit(title ? `${tool}: ${title}` : tool);
                 }
@@ -444,15 +833,16 @@ async function pollForCompletion(handle, sessionID, opts) {
         // work is done, so there's nothing to finalize.
         if (assistant.info?.time?.completed != null) {
             const text = (assistant.parts ?? [])
-                .filter(part => part?.type === 'text' && typeof part.text === 'string')
-                .map(part => part.text)
-                .join('\n')
+                .filter((part) => part?.type === "text" && typeof part.text === "string")
+                .map((part) => part.text)
+                .join("\n")
                 .trim();
             return {
                 text,
                 cost: assistant.info?.cost ?? 0,
                 sessionID,
                 tokens: assistant.info?.tokens,
+                model: formatModel(assistant.info?.providerID, assistant.info?.modelID),
             };
         }
         // Still in progress: enforce the tool-call cap. An agent that has made this
@@ -462,5 +852,15 @@ async function pollForCompletion(handle, sessionID, opts) {
             emit(`made ${opts.reportedTools.size} tool calls — wrapping up to stay on budget`);
             throw new DeadlineReached(lastCost, lastTokens);
         }
+        // Still in progress and completely silent: the request is wedged, not slow.
+        // Bail out NOW rather than spending the rest of the cap on a dead request —
+        // the caller retries a stall from a clean session (see promptAgent).
+        if (opts.stallMs != null) {
+            const idleMs = Date.now() - lastProgressAt;
+            if (idleMs >= opts.stallMs) {
+                emit(`no new output for ${Math.round(idleMs / 1000)}s — treating the model request as stalled`);
+                throw new NoProgress(lastCost, lastTokens, idleMs);
+            }
+        }
     }
 }