@oh-my-pi/pi-coding-agent 16.3.10 → 16.3.12

package/dist/types/advisor/runtime.d.ts

@@ -45,6 +45,17 @@ export interface AdvisorRuntimeHost {
      * one that routes `advise()` results back to the primary.
      */
     beginAdvisorUpdate?(): void;
+    /**
+     * Called with the error of every failed advisor turn, before the retry sleep
+     * or the dropped-after-3 path. Lets the host apply credential-level remedies
+     * the advisor loop lacks: the in-stream a/b/c auth retry rotates through
+     * sibling credentials within one request but never blocks the LAST failing
+     * one — the primary agent's retry pipeline does that via
+     * `markUsageLimitReached`, so without this hook the advisor re-picks the
+     * same usage-limited account on every retry. Errors thrown here are logged
+     * and swallowed.
+     */
+    onTurnError?(error: unknown): Promise<void> | void;
     /** Surface a non-recovering advisor failure to the host UI without adding model-visible context. */
     notifyFailure?(error: unknown): void;
 }

package/dist/types/config/model-registry.d.ts

@@ -189,6 +189,10 @@ export declare class ModelRegistry {
      * Check if a model selector is currently suppressed due to rate limits.
      */
     isSelectorSuppressed(selector: string): boolean;
+    /**
+     * Clear the cooldown suppression for one selector after an explicit user selection.
+     */
+    clearSuppressedSelector(selector: string): void;
     /**
      * Clear all cooldown suppressions recorded via {@link suppressSelector}.
      * Used to reset retry-fallback cooldown state without a full {@link refresh}.

package/dist/types/config/settings-schema.d.ts

@@ -1380,6 +1380,12 @@ export declare const SETTINGS_SCHEMA: {
     readonly "retry.fallbackChains": {
         readonly type: "record";
         readonly default: Record<string, string[]>;
+        readonly ui: {
+            readonly tab: "model";
+            readonly group: "Retry & Fallback";
+            readonly label: "Retry Fallback Chains";
+            readonly description: 'JSON object mapping model roles to ordered fallback model selectors, e.g. {"default":["openai/gpt-4o-mini"]}.';
+        };
     };
     readonly "retry.fallbackRevertPolicy": {
         readonly type: "enum";

package/dist/types/config/settings.d.ts

@@ -152,6 +152,8 @@ export declare class Settings {
  * can register independently without overwriting each other.
  */
 export declare const onAppendOnlyModeChanged: (cb: (value: string) => void) => () => void;
+/** Subscribe to model role changes. Returns an unsubscribe function. */
+export declare const onModelRolesChanged: (cb: () => void) => () => void;
 /**
  * Subscribe to session-accent setting changes.
  * Returns an unsubscribe function. Callers should re-read settings in the callback.

package/dist/types/discovery/helpers.d.ts

@@ -122,6 +122,15 @@ export interface ScanSkillsFromDirOptions {
     providerId: string;
     level: "user" | "project";
     requireDescription?: boolean;
+    /**
+     * When true, treat a `SKILL.md` sitting directly under `dir` as a single skill in addition to
+     * scanning `<dir>/<name>/SKILL.md` children. Matches the Claude plugin manifest convention
+     * that lets a skill path point at a directory containing `SKILL.md` directly (e.g.
+     * `"skills": ["./"]`), where the frontmatter `name` determines the invocation name and the
+     * directory basename is the fallback. Default `false` preserves the strict child-scan
+     * semantic every non-Claude provider relies on.
+     */
+    includeSelf?: boolean;
 }
 export declare function compareSkillOrder(aName: string, aPath: string, bName: string, bPath: string): number;
 export declare function scanSkillsFromDir(_ctx: LoadContext, options: ScanSkillsFromDirOptions): Promise<LoadResult<Skill>>;

package/dist/types/exec/bash-executor.d.ts

@@ -2,6 +2,7 @@ import { type MinimizerOptions } from "@oh-my-pi/pi-natives";
 import { type ShellMinimizerSettings } from "../config/settings.js";
 export interface BashExecutorOptions {
     cwd?: string;
+    /** Milliseconds before aborting the command; 0 disables the executor deadline. */
     timeout?: number;
     onChunk?: (chunk: string) => void;
     chunkThrottleMs?: number;

package/dist/types/extensibility/shared-events.d.ts

@@ -27,7 +27,7 @@ export interface SessionStartEvent {
 export interface SessionBeforeSwitchEvent {
     type: "session_before_switch";
     /** Reason for the switch */
-    reason: "new" | "resume" | "fork";
+    reason: "new" | "resume" | "fork" | "handoff";
     /** Session file we're switching to (only for "resume") */
     targetSessionFile?: string;
 }
@@ -35,7 +35,7 @@ export interface SessionBeforeSwitchEvent {
 export interface SessionSwitchEvent {
     type: "session_switch";
     /** Reason for the switch */
-    reason: "new" | "resume" | "fork";
+    reason: "new" | "resume" | "fork" | "handoff";
     /** Session file we came from */
     previousSessionFile: string | undefined;
 }

package/dist/types/internal-urls/__tests__/agent-protocol-nested.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/internal-urls/registry-helpers.d.ts

@@ -3,10 +3,12 @@ export declare function resetRegisteredArtifactDirsForTests(): void;
 /**
  * Snapshot of artifacts dirs for every registered session, deduped.
  *
- * Prefers `sessionManager.getArtifactsDir()` because subagents adopt their
- * parent's `ArtifactManager` and report the parent's dir there; dedup then
- * collapses parent + N subagents (the whole agent tree) to one entry. Falls
- * back to the raw session file (with the `.jsonl` suffix stripped) when no
- * live session reference is attached.
+ * Collects TWO candidate dirs per ref, because a subagent reads from its
+ * adopted (root-wide) `ArtifactManager.dir` but its own children are written
+ * one level deeper, under `sessionFile.slice(0, -6)` (`task/index.ts`). A
+ * depth-2+ subagent's output therefore lives in the write-time dir, not the
+ * adopted one, so `agent://` must scan both or it 404s a live nested peer.
+ * `addDir` dedup collapses the depth-0 case (both formulas agree) back to a
+ * single entry.
  */
 export declare function artifactsDirsFromRegistry(): string[];

package/dist/types/modes/components/model-selector.d.ts

@@ -7,7 +7,8 @@ interface ScopedModelItem {
     model: Model;
     thinkingLevel?: string;
 }
-type RoleSelectCallback = (model: Model, role: string | null, thinkingLevel?: ConfiguredThinkingLevel, selector?: string) => void;
+type ModelSelectorAction = "modelRole" | "retryFallback";
+type RoleSelectCallback = (model: Model, role: string | null, thinkingLevel?: ConfiguredThinkingLevel, selector?: string, action?: ModelSelectorAction) => void;
 /**
  * Component that renders a model selector with provider tabs and context menu.
  * - Tab/Arrow Left/Right: Switch between provider tabs

package/dist/types/modes/github-ref-autocomplete.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Autocomplete for GitHub issue/PR references typed as `#<number>` (e.g. `#3164`).
+ *
+ * Mirrors the `@` file-reference and `scheme://` internal-url conventions: the
+ * token is rewritten to an internal URL (`pr://3164` or `issue://3164`) plus a
+ * trailing space, and the existing tool-mediated pipeline (the `read` tool →
+ * InternalUrlRouter → `gh`) resolves it from the session cwd's git remote.
+ *
+ * No network at suggestion time — candidates are generated locally. GitHub
+ * shares the issue/PR number space and there is no cheap way to tell which a
+ * given number is while typing, so both a PR and an Issue candidate are offered
+ * by default. Naming the type first (`pr #3164` / `issue #3164`) constrains the
+ * candidates to that kind. Anything that is not a standalone `#<number>` token
+ * keeps falling through to the existing prompt-action menu.
+ */
+import type { AutocompleteItem } from "@oh-my-pi/pi-tui";
+export interface GithubRefContext {
+    /** Text to replace on accept: `#3164`, or `pr #3164` when a qualifier precedes it. */
+    prefix: string;
+    /** Type the user named (`pr`/`pull` → `pr`, `issue` → `issue`), or null to offer both. */
+    qualifier: "pr" | "issue" | null;
+    /** The numeric reference, e.g. `3164`. */
+    number: string;
+}
+export declare function getGithubRefContext(textBeforeCursor: string): GithubRefContext | null;
+/**
+ * Suggestions for a `#<number>` token. Both kinds are offered unless the user
+ * named a type (`pr #3164` / `issue #3164`), in which case only that kind is
+ * offered. Returns `null` when the text before the cursor is not a standalone
+ * `#<number>` token.
+ */
+export declare function getGithubRefSuggestions(textBeforeCursor: string): {
+    items: AutocompleteItem[];
+    prefix: string;
+} | null;

package/dist/types/modes/utils/context-usage.d.ts

@@ -24,18 +24,6 @@ export interface ContextBreakdown {
 }
 export declare function estimateSkillsTokens(skills: readonly Skill[]): number;
 export declare function estimateToolSchemaTokens(tools: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>): number;
-/**
- * Compute just the NON-MESSAGE token total: system prompt (with its skills
- * section subtracted, since skills are tokenized separately) + system context
- * (the rest of the system-prompt array) + tools + skills.
- *
- * Exposed so callers like `StatusLineComponent` can cache the non-message
- * total separately from the message total. Non-message inputs (skills,
- * tools, system prompt) change rarely; the message list grows on every
- * streaming turn. Splitting the two lets the caller refresh each on its own
- * cadence — non-message recomputed only when the inputs identity changes,
- * messages walked incrementally as new entries append.
- */
 export declare function computeNonMessageTokens(session: AgentSession): number;
 /**
  * Shared helper for the four non-message token totals used by

package/dist/types/modes/workflow.d.ts

@@ -1,6 +1,10 @@
 import { type KeywordHighlighter } from "./gradient-highlight.js";
-/** Hidden system notice appended after a user message that mentions "workflowz". */
+/** WORKFLOW_NOTICE is the default hidden notice for sessions with batched task calls enabled. */
 export declare const WORKFLOW_NOTICE: string;
+/** renderWorkflowNotice renders the workflow notice for the active task schema. */
+export declare function renderWorkflowNotice({ taskBatch }: {
+    taskBatch: boolean;
+}): string;
 /**
  * Whether `text` contains the standalone keyword "workflowz"
  * (lowercase, whitespace-delimited) in prose — never inside a code block, inline

package/dist/types/session/agent-session.d.ts

@@ -184,6 +184,8 @@ export interface AgentSessionConfig {
     toolRegistry?: Map<string, AgentTool>;
     /** Tool names whose current registry entry is still the built-in implementation. */
     builtInToolNames?: Iterable<string>;
+    /** Update tool-session predicates that render guidance from the live active tool set. */
+    setActiveToolNames?: (names: Iterable<string>) => void;
     /** Current session pre-LLM message transform pipeline */
     transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => AgentMessage[] | Promise<AgentMessage[]>;
     /**
@@ -224,6 +226,8 @@ export interface AgentSessionConfig {
     rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<{
         systemPrompt: string[];
     }>;
+    /** Local calendar date provider used by prompt-cache invalidation. Defaults to the host local date. */
+    getLocalCalendarDate?: () => string;
     /** Rebuild the SSH tool from current capability discovery results. */
     reloadSshTool?: () => Promise<AgentTool | null>;
     requestedToolNames?: ReadonlySet<string>;
@@ -366,6 +370,7 @@ export interface HandoffResult {
 export interface SessionHandoffOptions {
     autoTriggered?: boolean;
     signal?: AbortSignal;
+    onSwitchCancelled?: () => void;
 }
 /** Result from cycleModel() */
 export interface ModelCycleResult {

package/dist/types/system-prompt.d.ts

@@ -35,7 +35,7 @@ export declare function loadProjectContextFiles(options?: LoadContextFilesOption
  * Project-level SYSTEM.md overrides user-level SYSTEM.md.
  */
 export declare function loadSystemPromptFiles(options?: LoadContextFilesOptions): Promise<string | null>;
-export declare const DEFAULT_SYSTEM_PROMPT_TOOL_NAMES: readonly ["read", "bash", "eval", "edit", "write"];
+export declare const DEFAULT_SYSTEM_PROMPT_TOOL_NAMES: readonly ["read", "bash", "edit", "write"];
 export interface SystemPromptToolMetadata {
     label: string;
     description: string;

package/dist/types/tools/bash-interactive.d.ts

@@ -8,7 +8,7 @@ export interface BashInteractiveResult extends OutputSummary {
 export declare function runInteractiveBashPty(ui: NonNullable<AgentToolContext["ui"]>, options: {
     command: string;
     cwd: string;
-    timeoutMs: number;
+    timeoutMs?: number;
     signal?: AbortSignal;
     env?: Record<string, string>;
     artifactPath?: string;

package/dist/types/tools/bash-skill-urls.d.ts

@@ -25,6 +25,7 @@ export declare function resolveSkillUrlToPath(url: string, skills: readonly Skil
 export declare function expandSkillUrls(command: string, skills: readonly Skill[]): string;
 /**
  * Expand supported internal URLs in a bash command string to shell-escaped absolute paths.
+ * Unresolvable URLs and literal mentions inside larger quoted text are left unchanged.
  * Supported schemes: skill://, agent://, artifact://, memory://, rule://, local://
  */
 export declare function expandInternalUrls(command: string, options: InternalUrlExpansionOptions): Promise<string>;

package/dist/types/tools/bash.d.ts

@@ -72,6 +72,7 @@ export interface BashToolDetails {
     meta?: OutputMeta;
     timeoutSeconds?: number;
     requestedTimeoutSeconds?: number;
+    timeoutDisabled?: boolean;
     wallTimeMs?: number;
     /** Exit code of a command that ran to completion but failed (non-zero). */
     exitCode?: number;
@@ -97,7 +98,7 @@ export declare class BashTool implements AgentTool<typeof bashSchemaBase | typeo
     readonly formatApprovalDetails: (args: unknown) => string[];
     readonly label = "Bash";
     readonly loadMode = "essential";
-    readonly description: string;
+    get description(): string;
     readonly parameters: BashToolSchema;
     readonly concurrency: (args: Partial<BashToolInput>) => "shared" | "exclusive";
     readonly strict = true;

package/dist/types/tools/browser/launch.d.ts

@@ -60,6 +60,7 @@ export declare function applyStealthPatches(browser: Browser, page: Page, state:
     browserSession: CDPSession | null;
     override: UserAgentOverride | null;
 }): Promise<void>;
+export declare function stealthIgnoreDefaultArgsForTest(executablePath: string | undefined): string[];
 export declare function targetSupportsUserAgentOverrideForTest(target: Target): boolean;
 export declare function configureUserAgentTargetsForTest(browser: Browser, state: {
     browserSession: CDPSession | null;

package/dist/types/tools/grep.d.ts

@@ -8,6 +8,7 @@ import type { OutputMeta } from "./output-meta.js";
 declare const searchSchema: import("arktype/internal/variants/object.ts").ObjectType<{
     pattern: string;
     path?: string | undefined;
+    selector?: string | undefined;
     case?: boolean | undefined;
     gitignore?: boolean | undefined;
     skip?: number | null | undefined;
@@ -66,6 +67,7 @@ export declare class GrepTool implements AgentTool<typeof searchSchema, GrepTool
     readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
         pattern: string;
         path?: string | undefined;
+        selector?: string | undefined;
         case?: boolean | undefined;
         gitignore?: boolean | undefined;
         skip?: number | null | undefined;

package/dist/types/tools/index.d.ts

@@ -172,6 +172,10 @@ export interface ToolSession {
     getAgentId?: () => string | null;
     /** Look up a registered tool by name (used by the eval js backend's tool bridge). */
     getToolByName?: (name: string) => AgentTool | undefined;
+    /** Return whether a built-in tool is active in this turn's tool set. */
+    isToolActive?: (name: string) => boolean;
+    /** Update the active built-in tool predicate when a session changes tools mid-run. */
+    setActiveToolNames?: (names: Iterable<string>) => void;
     /** Agent registry for IRC routing across live sessions. */
     agentRegistry?: AgentRegistry;
     /** Get artifacts directory for artifact:// URLs */

package/dist/types/tools/path-utils.d.ts

@@ -36,6 +36,30 @@ export declare function splitPathAndSel(rawPath: string): {
     path: string;
     sel?: string;
 };
+/**
+ * Three-way probe for whether the exact filesystem entry named by `filePath`
+ * exists. `stat` (used earlier) failed for reasons other than "no such file"
+ * (dangling symlink, `EACCES` on a parent, transient I/O), and each of those
+ * silently reinterpreted a real literal path such as `test:1-2` as `test`
+ * plus selector `1-2` (issue #4618). `lstat` inspects the entry itself, so a
+ * dangling symlink is still detected as present; ambiguous errors resolve to
+ * `"unknown"` so callers keep the raw path instead of guessing.
+ */
+export declare function probeLiteralPathExists(filePath: string, cwd: string): Promise<"exists" | "missing" | "unknown">;
+/**
+ * Async sibling of {@link splitPathAndSel} that prefers a literal filesystem
+ * path over selector interpretation. Filenames whose tail matches the selector
+ * grammar (e.g. `test:1-2`, `log:raw`) are legal on POSIX; without this the
+ * strict splitter peels the tail and both `read` and `grep` refuse to open the
+ * real file (issue #4618). The literal wins on a confirmed `lstat`, and also
+ * on `"unknown"` (`EACCES` on a parent, transient I/O), so an unreachable
+ * literal is never silently reinterpreted as `path + selector`. Only a
+ * definitive `ENOENT`/`ENOTDIR` falls back to the strict split.
+ */
+export declare function splitPathAndSelPreferringLiteral(rawPath: string, cwd: string): Promise<{
+    path: string;
+    sel?: string;
+}>;
 /**
  * Variant of {@link splitPathAndSel} for internal URLs (`scheme://...`).
  *

package/dist/types/tools/read.d.ts

@@ -7,6 +7,7 @@ import { type TruncationResult } from "../session/streaming-output.js";
 import { type OutputMeta } from "./output-meta.js";
 declare const readSchema: import("arktype/internal/variants/object.ts").ObjectType<{
     path: string;
+    selector?: string | undefined;
 }, {}>;
 export type ReadToolInput = typeof readSchema.infer;
 export interface ReadToolDetails {
@@ -59,6 +60,7 @@ export declare class ReadTool implements AgentTool<typeof readSchema, ReadToolDe
     readonly description: string;
     readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
         path: string;
+        selector?: string | undefined;
     }, {}>;
     readonly strict = true;
     constructor(session: ToolSession);

package/dist/types/utils/local-date.d.ts

@@ -0,0 +1,2 @@
+/** formatLocalCalendarDate formats a Date as YYYY-MM-DD in the host local timezone. */
+export declare function formatLocalCalendarDate(date?: Date): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "16.3.10",
+	"version": "16.3.12",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -56,17 +56,17 @@
 		"@agentclientprotocol/sdk": "0.25.0",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "16.3.10",
-		"@oh-my-pi/omp-stats": "16.3.10",
-		"@oh-my-pi/pi-agent-core": "16.3.10",
-		"@oh-my-pi/pi-ai": "16.3.10",
-		"@oh-my-pi/pi-catalog": "16.3.10",
-		"@oh-my-pi/pi-mnemopi": "16.3.10",
-		"@oh-my-pi/pi-natives": "16.3.10",
-		"@oh-my-pi/pi-tui": "16.3.10",
-		"@oh-my-pi/pi-utils": "16.3.10",
-		"@oh-my-pi/pi-wire": "16.3.10",
-		"@oh-my-pi/snapcompact": "16.3.10",
+		"@oh-my-pi/hashline": "16.3.12",
+		"@oh-my-pi/omp-stats": "16.3.12",
+		"@oh-my-pi/pi-agent-core": "16.3.12",
+		"@oh-my-pi/pi-ai": "16.3.12",
+		"@oh-my-pi/pi-catalog": "16.3.12",
+		"@oh-my-pi/pi-mnemopi": "16.3.12",
+		"@oh-my-pi/pi-natives": "16.3.12",
+		"@oh-my-pi/pi-tui": "16.3.12",
+		"@oh-my-pi/pi-utils": "16.3.12",
+		"@oh-my-pi/pi-wire": "16.3.12",
+		"@oh-my-pi/snapcompact": "16.3.12",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",

package/src/advisor/__tests__/advisor.test.ts

@@ -1294,6 +1294,151 @@ describe("advisor", () => {
 			expect(failures).toHaveLength(2);
 		});
 
+		it("calls onTurnError with state.error before retrying the batch", async () => {
+			const promptInputs: string[] = [];
+			const turnErrors: unknown[] = [];
+			const events: string[] = [];
+			const state: { messages: AgentMessage[]; error?: string } = { messages: [] };
+			let promptCalls = 0;
+			const agent: AdvisorAgent = {
+				prompt: async input => {
+					promptCalls++;
+					promptInputs.push(input);
+					events.push(`prompt:${promptCalls}`);
+					state.error = promptCalls === 1 ? "provider failed" : undefined;
+				},
+				abort: () => {},
+				reset: () => {
+					state.error = undefined;
+				},
+				state,
+			};
+			const messages: AgentMessage[] = [{ role: "user", content: "aaa", timestamp: 1 } as AgentMessage];
+			const host: AdvisorRuntimeHost = {
+				snapshotMessages: () => messages,
+				enqueueAdvice: () => {},
+				onTurnError: error => {
+					turnErrors.push(error);
+					events.push(`hook:${error instanceof Error ? error.message : String(error)}`);
+				},
+			};
+			const runtime = new AdvisorRuntime(agent, host, 1);
+
+			runtime.onTurnEnd(messages);
+			await runtime.waitForCatchup(1000, 1);
+
+			expect(promptInputs).toHaveLength(2);
+			expect(turnErrors).toHaveLength(1);
+			const error = turnErrors[0];
+			if (!(error instanceof Error)) throw new Error("expected advisor turn error");
+			expect(error.message).toBe("provider failed");
+			expect(events).toEqual(["prompt:1", "hook:provider failed", "prompt:2"]);
+			expect(runtime.backlog).toBe(0);
+		});
+
+		it("calls onTurnError for each consecutive failure including the dropped third turn", async () => {
+			const promptInputs: string[] = [];
+			const turnErrors: unknown[] = [];
+			const failures: unknown[] = [];
+			const events: string[] = [];
+			const state: { messages: AgentMessage[]; error?: string } = { messages: [] };
+			let promptCalls = 0;
+			const agent: AdvisorAgent = {
+				prompt: async input => {
+					promptCalls++;
+					promptInputs.push(input);
+					events.push(`prompt:${promptCalls}`);
+					state.error = `provider failed ${promptCalls}`;
+				},
+				abort: () => {},
+				reset: () => {
+					state.error = undefined;
+				},
+				state,
+			};
+			const messages: AgentMessage[] = [{ role: "user", content: "aaa", timestamp: 1 } as AgentMessage];
+			const host: AdvisorRuntimeHost = {
+				snapshotMessages: () => messages,
+				enqueueAdvice: () => {},
+				onTurnError: error => {
+					turnErrors.push(error);
+					events.push(`hook:${error instanceof Error ? error.message : String(error)}`);
+				},
+				notifyFailure: error => {
+					failures.push(error);
+					events.push(`notify:${error instanceof Error ? error.message : String(error)}`);
+				},
+			};
+			const runtime = new AdvisorRuntime(agent, host, 1);
+
+			runtime.onTurnEnd(messages);
+			await runtime.waitForCatchup(1000, 1);
+
+			expect(promptInputs).toHaveLength(3);
+			expect(turnErrors.map(error => (error instanceof Error ? error.message : String(error)))).toEqual([
+				"provider failed 1",
+				"provider failed 2",
+				"provider failed 3",
+			]);
+			expect(failures).toHaveLength(1);
+			const failure = failures[0];
+			if (!(failure instanceof Error)) throw new Error("expected advisor failure error");
+			expect(failure.message).toBe("provider failed 3");
+			expect(events).toEqual([
+				"prompt:1",
+				"hook:provider failed 1",
+				"prompt:2",
+				"hook:provider failed 2",
+				"prompt:3",
+				"hook:provider failed 3",
+				"notify:provider failed 3",
+			]);
+			expect(runtime.backlog).toBe(0);
+		});
+
+		it("continues retrying when onTurnError rejects", async () => {
+			const promptInputs: string[] = [];
+			const turnErrors: unknown[] = [];
+			const events: string[] = [];
+			const state: { messages: AgentMessage[]; error?: string } = { messages: [] };
+			let promptCalls = 0;
+			const agent: AdvisorAgent = {
+				prompt: async input => {
+					promptCalls++;
+					promptInputs.push(input);
+					events.push(`prompt:${promptCalls}`);
+					state.error = promptCalls === 1 ? "provider failed" : undefined;
+				},
+				abort: () => {},
+				reset: () => {
+					state.error = undefined;
+				},
+				state,
+			};
+			const messages: AgentMessage[] = [{ role: "user", content: "aaa", timestamp: 1 } as AgentMessage];
+			const host: AdvisorRuntimeHost = {
+				snapshotMessages: () => messages,
+				enqueueAdvice: () => {},
+				onTurnError: async error => {
+					turnErrors.push(error);
+					events.push(`hook:${error instanceof Error ? error.message : String(error)}`);
+					throw new Error("hook failed");
+				},
+			};
+			const runtime = new AdvisorRuntime(agent, host, 1);
+
+			runtime.onTurnEnd(messages);
+			await runtime.waitForCatchup(1000, 1);
+
+			expect(promptInputs).toHaveLength(2);
+			expect(turnErrors).toHaveLength(1);
+			const error = turnErrors[0];
+			if (!(error instanceof Error)) throw new Error("expected advisor turn error");
+			expect(error.message).toBe("provider failed");
+			expect(events).toEqual(["prompt:1", "hook:provider failed", "prompt:2"]);
+			expect(runtime.backlog).toBe(0);
+		});
+
 		it("rolls advisor state back after each failed prompt so retries don't replay duplicate turns", async () => {
 			// The real `Agent` appends the user batch + a synthetic `stopReason: "error"`
 			// assistant turn before `state.error` is read. Without rollback, the runtime's

package/src/advisor/runtime.ts

@@ -48,6 +48,17 @@ export interface AdvisorRuntimeHost {
 	 * one that routes `advise()` results back to the primary.
 	 */
 	beginAdvisorUpdate?(): void;
+	/**
+	 * Called with the error of every failed advisor turn, before the retry sleep
+	 * or the dropped-after-3 path. Lets the host apply credential-level remedies
+	 * the advisor loop lacks: the in-stream a/b/c auth retry rotates through
+	 * sibling credentials within one request but never blocks the LAST failing
+	 * one — the primary agent's retry pipeline does that via
+	 * `markUsageLimitReached`, so without this hook the advisor re-picks the
+	 * same usage-limited account on every retry. Errors thrown here are logged
+	 * and swallowed.
+	 */
+	onTurnError?(error: unknown): Promise<void> | void;
 	/** Surface a non-recovering advisor failure to the host UI without adding model-visible context. */
 	notifyFailure?(error: unknown): void;
 }
@@ -352,6 +363,14 @@ export class AdvisorRuntime {
 					if (this.#epoch !== epoch) continue;
 					this.#rollbackFailedTurn(messageSnapshot);
 					logger.debug("advisor turn failed", { err: String(err) });
+					try {
+						await this.host.onTurnError?.(err);
+					} catch (hookErr) {
+						logger.debug("advisor onTurnError hook failed", { err: String(hookErr) });
+					}
+					// The hook awaits; a reset during it invalidates this batch like the
+					// prompt await above — drop it instead of requeueing stale content.
+					if (this.#epoch !== epoch) continue;
 					this.#consecutiveFailures++;
 					if (this.#consecutiveFailures >= 3) {
 						logger.warn("advisor failed consecutively 3 times; dropping backlog to prevent stall");

package/src/config/api-key-resolver.ts

@@ -49,7 +49,7 @@ export function createApiKeyResolver(
 	options: ApiKeyResolverOptions = {},
 ): ApiKeyResolver {
 	const { sessionId, baseUrl, modelId } = options;
-	return async ({ lastChance, error, signal }) => {
+	return async ({ lastChance, error, signal, previousKey }) => {
 		if (error === undefined) {
 			return registry.getApiKeyForProvider(provider, sessionId, { baseUrl, modelId });
 		}
@@ -59,7 +59,12 @@ export function createApiKeyResolver(
 			// sibling exists we switch immediately; the precise no-sibling backoff
 			// is owned by `markUsageLimitReached` (default + server usage-report
 			// reset) and the outer whole-turn retry layer.
-			await registry.authStorage.rotateSessionCredential(provider, sessionId, { error, modelId, signal });
+			await registry.authStorage.rotateSessionCredential(provider, sessionId, {
+				error,
+				modelId,
+				signal,
+				apiKey: previousKey,
+			});
 			return registry.getApiKeyForProvider(provider, sessionId, { baseUrl, modelId });
 		}
 		return registry.getApiKeyForProvider(provider, sessionId, { baseUrl, modelId, forceRefresh: true, signal });