@code-yeongyu/senpi 2026.10.18-1 → 2026.10.19

package/dist/core/agent-session.js

@@ -33,6 +33,7 @@ import { sleep } from "../utils/sleep.js";
 import { normalizeToolResultImages } from "../utils/tool-result-images.js";
 import { AgentAbortProvenance } from "./agent-abort-provenance.js";
 import { AgentBusyError } from "./agent-busy-error.js";
+import { AgentRunContinuations } from "./agent-run-continuation.js";
 import { AgentSettledDelivery, DeferredTurnClaim } from "./agent-settled-delivery.js";
 import { resolveAssistantUsageScope } from "./assistant-usage-scope.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
@@ -56,6 +57,7 @@ import { environmentContextMessageIfChanged, resolveEnvironmentContext, } from "
 import { areExperimentalFeaturesEnabled } from "./experimental.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
+import { reportExtensionHandlerStall } from "./extension-handler-stall-report.js";
 import { ANTHROPIC_SUBSCRIPTION_PROVIDER_ID } from "./extensions/builtin/anthropic-subscription/account-management.js";
 import { askUserAnswerDisplayText } from "./extensions/builtin/ask-user/format.js";
 import { getPromptCachePrewarmUsage } from "./extensions/builtin/cache-keepalive/prewarm-entry.js";
@@ -85,6 +87,7 @@ import { ModelRegistry } from "./model-registry.js";
 import { getModelNarrowingPatterns, resolveModelScope } from "./model-resolver.js";
 import { ModelSwitchAuthError } from "./model-switch-auth-error.js";
 import { NestedToolCallRunner } from "./nested-tool-calls.js";
+import { SessionPendingInputs } from "./pending-input-session.js";
 import { PROMPT_CACHE_SAFE_WAIT_ENV, resolvePromptCacheSafeWaitSeconds } from "./prompt-cache-budget.js";
 import { PromptCachePrefixBuilds } from "./prompt-cache-prefix-request.js";
 import { expandPromptTemplateWithMetadata } from "./prompt-templates.js";
@@ -122,7 +125,7 @@ import { composeFilesystemPolicies } from "./tools/filesystem-policy.js";
 import { createAllToolDefinitions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 import { TranscriptWriteFailures } from "./transcript-write-failures.js";
-import { AgentDeadlineTracker, resolveTurnDeadlineSettings, TURN_DEADLINE_ENTRY_TYPE, } from "./turn-deadline.js";
+import { AgentDeadlineTracker, resolveTurnDeadlineSettings, TURN_DEADLINE_ENTRY_TYPE, TURN_DEADLINE_GRACE_MS, } from "./turn-deadline.js";
 import { commandShapedName, findUnknownCommand } from "./unknown-command.js";
 import { addUsageToTotals, combineUsage, createUsageTotals } from "./usage-totals.js";
 import { keepsTextBlocksVerbatim, userTextContent } from "./user-text-blocks.js";
@@ -318,6 +321,10 @@ export class AgentSession {
         /** Settles once the queued message_end processing (persistence included) of that exact message has run. */
         this._messageEndPersistence = new WeakMap();
         this._isAgentRunActive = false;
+        /** senpi#3650: the core may continue a run after agent_end; the settle must not wait on that continuation. */
+        this._runContinuations = new AgentRunContinuations();
+        /** senpi#3650: the turn that owns extension handler waits started now; the turn deadline releases only its own. */
+        this._handlerTurnScope = 0;
         this._toolExecutionDepth = 0;
         this._toolContextDisposers = new Set();
         this._promptStartPending = false;
@@ -341,6 +348,7 @@ export class AgentSession {
         this._queuedInputOrder = [];
         this._nextQueuedInputOrder = 0;
         this._nextQueuedId = 0;
+        this._queueClearRecorded = Promise.resolve();
         /** The exact message object queued for each `queuedId`, so removal and edits hit the native queue by identity. */
         this._queuedMessages = new Map();
         /** Recently delivered `queuedId`s (bounded), so a late dequeue answers `already_delivered`, not `not_found`. */
@@ -465,6 +473,7 @@ export class AgentSession {
         this._lastAssistantMessage = undefined;
         /** Internal handler for agent events - shared by subscribe and reconnect */
         this._handleAgentEvent = (event, signal) => {
+            this._runContinuations.observe(event);
             // Record the calls a tool made through ctx.executeTool() and their usage on its result message,
             // synchronously so the message carries them before any listener or persistence sees it.
             if (this._nestedToolCalls) {
@@ -540,6 +549,12 @@ export class AgentSession {
         this._browserEngine = config.browserEngine;
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
+        this._pendingInputs = new SessionPendingInputs({
+            sessionManager: this.sessionManager,
+            nextQueuedId: () => this._mintQueuedId(),
+            onChange: (update) => this._emit({ type: "pending_input_update", ...update }),
+        });
+        this.agent.queuedInputPort = this._pendingInputs.queuedInputPort();
         this.settingsManager = config.settingsManager;
         this._unsubscribeSettingsSource = this.settingsManager.subscribeToSourceSelection((source) => {
             this._emit({ type: "settings_source_selected", ...source });
@@ -1706,9 +1721,12 @@ export class AgentSession {
         this._resolveIdleWait = undefined;
         resolve();
     }
-    async _emitAgentSettled() {
-        if (this.agent.state.isStreaming) {
-            await this.agent.waitForIdle();
+    async _emitAgentSettled(agentEnd) {
+        if (this.agent.state.isStreaming &&
+            (await this._runContinuations.idleOrContinued(agentEnd, () => this.agent.waitForIdle()))) {
+            // The core continued this run with input queued during agent_end; that continuation settles it.
+            this._abortProvenance.closeAgentEndBoundary();
+            return;
         }
         if (!this._isAgentRunActive) {
             this._abortProvenance.closeAgentEndBoundary();
@@ -1816,6 +1834,7 @@ export class AgentSession {
         this._isAgentRunActive = true;
         // A new turn admitted: arm the inactivity lease and the hard max-runtime cap.
         this._deadlineTracker.arm();
+        this._handlerTurnScope += 1;
         // A new prompt replaces any retry that compaction before it scheduled.
         this._failedResponse = undefined;
         this._recordSelection();
@@ -2473,7 +2492,7 @@ export class AgentSession {
                 launchedContinuation = true;
             }
             if (!launchedContinuation) {
-                await this._emitAgentSettled();
+                await this._emitAgentSettled(event);
             }
             else {
                 this._abortProvenance.closeAgentEndBoundary();
@@ -3086,6 +3105,29 @@ export class AgentSession {
     /** Adapter for the deadline owner interface: end the turn through the normal system abort. */
     async abortTurnForDeadline() {
         await this._abortActiveAgentAndRetry("system");
+        // An abort that joined an open agent_end boundary returns at once; the run is still held until it settles.
+        if (!this.isIdle)
+            await this._waitForIdleAfterAbort();
+    }
+    /**
+     * An abort (Esc, or the turn deadline) that the run does not honour within the grace is held by an extension handler
+     * no abort signal reaches: release the turn's held handler waits so it settles (senpi#3650).
+     */
+    async _waitForIdleAfterAbort() {
+        const idle = this.waitForIdle();
+        let graceTimer;
+        const graceOver = new Promise((resolve) => {
+            graceTimer = setTimeout(() => resolve(true), TURN_DEADLINE_GRACE_MS);
+        });
+        const stillHeld = await Promise.race([idle.then(() => false), graceOver]);
+        clearTimeout(graceTimer);
+        if (stillHeld)
+            this._extensionRunner.releaseHeldHandlers(this._handlerTurnScope);
+        await idle;
+    }
+    /** Adapter for the deadline owner interface: stop waiting on extension handlers that hold the turn (senpi#3650). */
+    releaseHeldExtensionHandlers() {
+        return this._extensionRunner.releaseHeldHandlers(this._handlerTurnScope);
     }
     /** Record a deadline stop durably so the goal engine holds off until admitted user input. */
     _recordDeadlineStop(deadline) {
@@ -4398,17 +4440,32 @@ export class AgentSession {
      * Internal: Queue a steering message (already expanded, no extension command check).
      */
     async _queueSteer(text, images, options) {
-        this._enqueuePreparedInput({ ...options, text, images, mode: "steer" });
+        await this._enqueueQueuedInput({ ...options, text, images, mode: "steer" });
     }
     /**
      * Internal: Queue a follow-up message (already expanded, no extension command check).
      */
     async _queueFollowUp(text, images, options) {
-        this._enqueuePreparedInput({ ...options, text, images, mode: "followUp" });
+        await this._enqueueQueuedInput({ ...options, text, images, mode: "followUp" });
+    }
+    /** Identified input is admitted into durable custody and enqueued in one gated step; other input as before. */
+    async _enqueueQueuedInput(input) {
+        const clientMessageId = input.clientMessageId;
+        if (clientMessageId === undefined) {
+            this._enqueuePreparedInput(input);
+            return;
+        }
+        await this._pendingInputs.admit({ clientMessageId, text: input.text, ...(input.images ? { images: input.images } : {}), mode: input.mode }, (queuedId) => this._enqueuePreparedInput({ ...input, queuedId }));
     }
     /** Restore accepted input without re-running input transforms or changing its enqueue order. */
     async restoreQueuedInput(input) {
-        this._enqueuePreparedInput(input);
+        const restored = input.clientMessageId === undefined
+            ? undefined
+            : await this._pendingInputs.restoreHandle(input.clientMessageId);
+        // The pending-input record is the authority: an input it already retired is not queued again.
+        if (restored === "retired")
+            return;
+        this._enqueuePreparedInput(restored === undefined ? input : { ...input, queuedId: restored.queuedId });
     }
     _enqueuePreparedInput(input) {
         const enqueueOrder = input.enqueueOrder ?? this.reserveQueuedInputOrder();
@@ -4422,7 +4479,7 @@ export class AgentSession {
         input.onQueuedInput?.(prepared);
         const queue = input.mode === "steer" ? this._steeringMessages : this._followUpMessages;
         queue.push(input.text);
-        const queuedId = this._recordQueuedInput(input.text, input.mode, prepared);
+        const queuedId = this._recordQueuedInput(input.text, input.mode, prepared, undefined, input.queuedId);
         this._sessionLogger.debug("queue_enqueue", {
             mode: input.mode,
             count: queue.length,
@@ -4820,11 +4877,10 @@ export class AgentSession {
         this._nextQueuedInputOrder += 1;
         return this._nextQueuedInputOrder;
     }
-    _recordQueuedInput(text, mode, options, message) {
+    _recordQueuedInput(text, mode, options, message, admittedQueuedId) {
         const order = options?.enqueueOrder ?? this.reserveQueuedInputOrder();
         this._nextQueuedInputOrder = Math.max(this._nextQueuedInputOrder, order);
-        this._nextQueuedId += 1;
-        const queuedId = `q_${this._nextQueuedId}`;
+        const queuedId = admittedQueuedId ?? this._mintQueuedId();
         this._queuedInputOrder.push({
             text,
             mode,
@@ -4837,6 +4893,10 @@ export class AgentSession {
             this._queuedMessages.set(queuedId, message);
         return queuedId;
     }
+    _mintQueuedId() {
+        this._nextQueuedId += 1;
+        return `q_${this._nextQueuedId}`;
+    }
     /** A queued input reached a turn: forget its record and remember its id as delivered. */
     _removeQueuedInput(text, mode, clientMessageId) {
         const index = this._queuedInputOrder.findIndex((message) => clientMessageId === undefined
@@ -4866,6 +4926,23 @@ export class AgentSession {
     editQueuedInput(queuedId, text, options) {
         return this._changeQueuedInput(queuedId, text, options?.expectedRevision);
     }
+    /**
+     * Removes (`text` undefined) or edits one queued input. An input in durable custody (admitted with a client id)
+     * changes in its record first and in the native queue in the same gated step; any other input changes as
+     * `dequeueQueuedInput` / `editQueuedInput` do.
+     */
+    async changeQueuedInput(queuedId, text, options) {
+        const clientMessageId = this._queuedInputOrder.find((input) => input.queuedId === queuedId)?.clientMessageId;
+        const durable = clientMessageId === undefined
+            ? undefined
+            : await this._pendingInputs.change({
+                clientMessageId,
+                text,
+                ...(options?.expectedRevision === undefined ? {} : { expectedRevision: options.expectedRevision }),
+                ...(options?.effectId === undefined ? {} : { effectId: options.effectId }),
+            }, () => this._changeQueuedInput(queuedId, text, undefined));
+        return durable ?? this._changeQueuedInput(queuedId, text, options?.expectedRevision);
+    }
     // Synchronous from the revision check to the change: nothing else on the session loop can land in between.
     _changeQueuedInput(queuedId, nextText, expectedRevision) {
         const index = this._queuedInputOrder.findIndex((input) => input.queuedId === queuedId);
@@ -4950,6 +5027,14 @@ export class AgentSession {
         this._followUpMessages = [];
         this._queuedInputOrder = [];
         this._queuedMessages.clear();
+        const recorded = this._pendingInputs.recordCleared(ordered.flatMap((input) => (input.clientMessageId === undefined ? [] : [input.clientMessageId])));
+        // A caller that acknowledges the clear awaits `recorded` and sees a failure; this logs it when nobody does.
+        recorded.catch((error) => {
+            this._sessionLogger.warn("pending_input_clear_unrecorded", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+        this._queueClearRecorded = recorded;
         this._postCompactionDeferredSteeringMessages = [];
         this._postCompactionDeferredFollowUpMessages = [];
         this.agent.clearAllQueues();
@@ -4962,6 +5047,13 @@ export class AgentSession {
         });
         return cleared;
     }
+    /**
+     * Settles once the last `clearQueue` is recorded in the pending-input journal. `clearQueue` stays synchronous;
+     * a caller that acknowledges the clear (RPC `clear_queue`) awaits this first so its answer is durable.
+     */
+    whenQueueClearRecorded() {
+        return this._queueClearRecorded;
+    }
     /** Number of pending messages (includes both steering and follow-up) */
     get pendingMessageCount() {
         return this._steeringMessages.length + this._followUpMessages.length;
@@ -4974,6 +5066,10 @@ export class AgentSession {
     getFollowUpMessages() {
         return this._followUpMessages;
     }
+    /** The pending inputs in durable custody, and an explicit outcome for each id the caller already knows. */
+    getPendingInputs(knownClientMessageIds) {
+        return this._pendingInputs.snapshot(knownClientMessageIds);
+    }
     getQueuedInputs() {
         return [...this._queuedInputOrder].sort((left, right) => left.enqueueOrder - right.enqueueOrder);
     }
@@ -5006,6 +5102,15 @@ export class AgentSession {
         if (this._isBeforeSettle)
             this._abortDuringBeforeSettle = true;
         await this._abortActiveAgentAndRetry("user");
+        // An Esc that joined an open agent_end boundary returns at once: a boundary handler that holds the run is still
+        // released after the grace (senpi#3650), without making abort() itself wait for it.
+        if (!this.isIdle) {
+            this._waitForIdleAfterAbort().catch((error) => {
+                this._sessionLogger.warn("abort_release_failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }
         if (!shouldEmitAbort)
             return;
         try {
@@ -6023,7 +6128,7 @@ export class AgentSession {
             this._recordUserAbort();
         const abortPromise = (async () => {
             this.agent.abort();
-            await this.waitForIdle();
+            await this._waitForIdleAfterAbort();
         })();
         this._userAbortPromise = abortPromise;
         try {
@@ -7582,6 +7687,10 @@ export class AgentSession {
         runner.setToolHookLifecycleObserver((event) => {
             this._emit(event);
         });
+        runner.setEventHandlerBudget(() => ({
+            warnMs: this.settingsManager.getExtensionEventHandlerWarnMs(),
+            timeoutMs: this.settingsManager.getExtensionEventHandlerTimeoutMs(),
+        }), (stall) => reportExtensionHandlerStall(stall, this._sessionLogger, (message, type) => runner.getUIContext().notify(message, type)), () => this._handlerTurnScope);
         runner.bindCommandContext(this._extensionCommandContextActions);
         this._extensionErrorUnsubscriber?.();
         this._extensionErrorUnsubscriber = this._extensionErrorListener

package/dist/core/extension-handler-stall-report.d.ts

@@ -0,0 +1,11 @@
+import type { ExtensionHandlerStall } from "./extensions/handler-budget.ts";
+import type { SessionLogger } from "./session-log.ts";
+type Notify = (message: string, type: "warning") => void;
+/**
+ * Makes a stalled extension handler diagnosable (senpi#3650): every stage lands in session.log with the event and
+ * extension, and a handler still running past the warning is shown, because the turn is waiting on it. A timeout or
+ * deadline release is shown by the runner's extension error, so it is only logged here.
+ */
+export declare function reportExtensionHandlerStall(stall: ExtensionHandlerStall, logger: SessionLogger, notify: Notify): void;
+export {};
+//# sourceMappingURL=extension-handler-stall-report.d.ts.map

package/dist/core/extension-handler-stall-report.js

@@ -0,0 +1,26 @@
+import { basename } from "node:path";
+function seconds(ms) {
+    return `${Math.max(1, Math.round(ms / 1000))} s`;
+}
+/**
+ * Makes a stalled extension handler diagnosable (senpi#3650): every stage lands in session.log with the event and
+ * extension, and a handler still running past the warning is shown, because the turn is waiting on it. A timeout or
+ * deadline release is shown by the runner's extension error, so it is only logged here.
+ */
+export function reportExtensionHandlerStall(stall, logger, notify) {
+    const extension = basename(stall.extensionPath);
+    logger.warn("extension_handler_stalled", {
+        extension,
+        handlerEvent: stall.event,
+        stage: stall.stage,
+        durationMs: stall.elapsedMs,
+        ...(stall.error === undefined ? {} : { error: stall.error }),
+    });
+    if (stall.stage !== "warn")
+        return;
+    const cap = stall.timeoutMs > 0
+        ? ` The session continues without it after ${seconds(stall.timeoutMs)}.`
+        : " Action: set extensionEventHandlerTimeoutMs to bound it, or remove the extension.";
+    notify(`Extension ${extension} is still running its ${stall.event} handler after ${seconds(stall.elapsedMs)}, so this turn is waiting on it.${cap}`, "warning");
+}
+//# sourceMappingURL=extension-handler-stall-report.js.map

package/dist/core/extensions/builtin/anthropic-subscription/account-command.js

@@ -112,6 +112,7 @@ function showAccounts(ctx, settings, environment) {
             affinityPick = selectAccount(accounts, {
                 sessionId: ctx.sessionManager.getSessionId(),
                 pinnedAccount: pinned,
+                accountFallback: settings.accountFallback,
                 ...(credential?.order === undefined ? {} : { accountOrder: credential.order }),
             }).name;
         }

package/dist/core/extensions/builtin/anthropic-subscription/affinity.d.ts

@@ -9,12 +9,22 @@ export type AffinityOptions = {
      * session does not move accounts and re-send its whole conversation (senpi#2891).
      */
     preferredAccount?: string;
+    /** When false, a blocked pin, resident account, or HRW winner is never skipped. */
+    readonly accountFallback?: boolean;
     /** The user's account order (senpi#3591): tried after the pin and the session's own account, before HRW. */
     accountOrder?: readonly string[];
     now?: number;
     /** The requested model; an account blocked only for another model stays eligible for it. */
     model?: string;
 };
+/**
+ * The one account a request may use when account fallback is off (senpi#3465): its name, and whether it
+ * is still configured. A pin or a session's resident account can name an account that was later removed.
+ */
+export type UnavailableAccount = {
+    readonly name: string;
+    readonly configured: boolean;
+};
 export declare class AllAccountsBlockedError extends Error {
     readonly soonestUnblockAt: number | undefined;
     /**
@@ -29,7 +39,9 @@ export declare class AllAccountsBlockedError extends Error {
      * chain moves only this model and keeps the provider for the others.
      */
     readonly limitedModel: string | undefined;
-    constructor(soonestUnblockAt: number | undefined, blockReason?: "auth_error", limitedModel?: string);
+    /** Set only when account fallback is off, so the guidance names that account instead of the whole pool. */
+    readonly unavailableAccount: UnavailableAccount | undefined;
+    constructor(soonestUnblockAt: number | undefined, blockReason?: "auth_error", limitedModel?: string, unavailableAccount?: UnavailableAccount);
 }
 export declare function getAffinityKey(options: Pick<AffinityOptions, "affinityKey" | "sessionId">): string;
 /**

package/dist/core/extensions/builtin/anthropic-subscription/affinity.js

@@ -3,7 +3,7 @@ import { applyAccountOrder } from "@earendil-works/pi-ai/auth/pool/select";
 import { activeModelBlockUntil, pruneModelBlocks } from "../../../credential-pool/model-scope.js";
 export const DEFAULT_AFFINITY_KEY = "claude-sdk-oauth-default";
 export class AllAccountsBlockedError extends Error {
-    constructor(soonestUnblockAt, blockReason, limitedModel) {
+    constructor(soonestUnblockAt, blockReason, limitedModel, unavailableAccount) {
         const until = soonestUnblockAt === undefined ? undefined : new Date(soonestUnblockAt).toISOString();
         super(limitedModel !== undefined && until !== undefined
             ? `All Anthropic Subscription accounts have hit the usage limit for model ${limitedModel} until ${until}.`
@@ -14,6 +14,7 @@ export class AllAccountsBlockedError extends Error {
         this.name = "AllAccountsBlockedError";
         this.soonestUnblockAt = soonestUnblockAt;
         this.blockReason = blockReason;
+        this.unavailableAccount = unavailableAccount;
     }
 }
 export function getAffinityKey(options) {
@@ -91,15 +92,25 @@ function limitedModel(accounts, now, model) {
 /** Selects a pinned or HRW-ranked account with no provider-global selection state. */
 export function selectAccount(accounts, options = {}) {
     const now = options.now ?? Date.now();
-    const selected = selectUnblocked(accounts, options, now);
+    let candidates = accounts;
+    let unavailableAccount;
+    if (options.accountFallback === false) {
+        const name = options.pinnedAccount ??
+            options.preferredAccount ??
+            applyAccountOrder(options.accountOrder, rendezvousOrder(getAffinityKey(options), accounts))[0]?.name;
+        candidates = accounts.filter((account) => account.name === name);
+        if (name !== undefined)
+            unavailableAccount = { name, configured: candidates.length > 0 };
+    }
+    const selected = selectUnblocked(candidates, options, now);
     if (selected)
         return selected;
     // A stale persisted rate-limit entry must not dead-end the pool. Retry once
     // against the cleared view before reporting the earliest available account.
-    const cleared = clearExpiredBlocks(accounts, now);
+    const cleared = clearExpiredBlocks(candidates, now);
     const afterClear = selectUnblocked(cleared, options, now);
     if (afterClear)
         return afterClear;
-    throw new AllAccountsBlockedError(soonestUnblockAt(accounts, now, options.model), accounts.some((account) => account.blockReason === "auth_error") ? "auth_error" : undefined, limitedModel(accounts, now, options.model));
+    throw new AllAccountsBlockedError(soonestUnblockAt(candidates, now, options.model), candidates.some((account) => account.blockReason === "auth_error") ? "auth_error" : undefined, limitedModel(candidates, now, options.model), unavailableAccount);
 }
 //# sourceMappingURL=affinity.js.map

package/dist/core/extensions/builtin/anthropic-subscription/auth-lane.js

@@ -214,9 +214,11 @@ export async function* queryWithAuthLane(input) {
     });
     yield* runFailover({
         accounts: pool.accounts,
+        accountFallback: input.providerSettings.accountFallback,
         selectFn: (accounts) => selectAccount(accounts, {
             sessionId: input.sessionId,
             pinnedAccount: input.pinnedAccount ?? pool.pinnedAccount,
+            accountFallback: input.providerSettings.accountFallback,
             ...(pool.accountOrder === undefined ? {} : { accountOrder: pool.accountOrder }),
             ...(input.preferredAccount === undefined ? {} : { preferredAccount: input.preferredAccount }),
             now: activeBoundary.now(),

package/dist/core/extensions/builtin/anthropic-subscription/failover.d.ts

@@ -16,6 +16,8 @@ export type FailoverEvent = {
 };
 export type FailoverOptions<TEvent> = {
     accounts: readonly AccountSlot[];
+    /** When false, only the selected account may be attempted; same-account retries remain enabled. */
+    readonly accountFallback?: boolean;
     selectFn: (accounts: readonly AccountSlot[]) => AccountSlot;
     runAttempt: (slot: AccountSlot) => AsyncIterable<TEvent> | Promise<AsyncIterable<TEvent>>;
     classify: (error: unknown) => SdkErrorClassification;

package/dist/core/extensions/builtin/anthropic-subscription/failover.js

@@ -273,12 +273,13 @@ export async function* runFailover(options) {
     const now = options.now ?? Date.now;
     const baseBlockMs = options.baseBlockMs ?? DEFAULT_RATE_LIMIT_BLOCK_MS;
     let accounts = clearExpiredBlocks(withSessionBlocks(options.accounts, options.sessionKey, now()), now());
+    const attemptLimit = options.accountFallback === false ? Math.min(accounts.length, 1) : accounts.length;
     let lastError;
     const retriedOnStoredMaterial = new Set();
     let transientRetriesUsed = 0;
     let longContextRetried = false;
     let retryAccountName;
-    for (let attempt = 0; attempt < accounts.length; attempt++) {
+    for (let attempt = 0; attempt < attemptLimit; attempt++) {
         // Each attempt gets its own copy: prepareSlot refreshes the slot in place, and a concurrent
         // attempt holding the same stored object must still report the token it actually sent.
         const retrySlot = retryAccountName === undefined ? undefined : accounts.find((slot) => slot.name === retryAccountName);
@@ -361,7 +362,7 @@ export async function* runFailover(options) {
                 visibleDeltaEmitted,
             };
             try {
-                if (!visibleDeltaEmitted && attempt + 1 < accounts.length) {
+                if (!visibleDeltaEmitted && attempt + 1 < attemptLimit) {
                     event.nextAccount = options.selectFn(accounts);
                 }
             }

package/dist/core/extensions/builtin/anthropic-subscription/guidance.d.ts

@@ -1,7 +1,15 @@
+import type { UnavailableAccount } from "./affinity.ts";
 import type { SdkErrorKind } from "./errors.ts";
 import type { ClaudeCodeRun } from "./executable.ts";
 export declare function noAccountGuidance(hasAnthropicCredential: boolean): string;
 export declare function allAccountsBlockedGuidance(soonestUnblockAt: number | undefined, blockReason?: "auth_error"): string;
+/**
+ * With account fallback off, only one account may serve (senpi#3465), so the pool-wide advice is wrong:
+ * other accounts may be healthy, and adding one does not help because it is never used. Name the account
+ * and the remedies that do work. The cause words ("authentication error", "rate limit") stay, so the outer
+ * credential-pool classifier reads the same verdict as for the pool-wide guidance.
+ */
+export declare function singleAccountUnavailableGuidance(account: UnavailableAccount, soonestUnblockAt: number | undefined, blockReason?: "auth_error"): string;
 export declare function claudeCodeVersionFloorGuidance(text: string, ran?: ClaudeCodeRun): string | undefined;
 export declare function sdkErrorGuidance(kind: SdkErrorKind): string | undefined;
 export declare function missingBinaryGuidance(platform: string, arch: string): string;

package/dist/core/extensions/builtin/anthropic-subscription/guidance.js

@@ -35,6 +35,35 @@ export function allAccountsBlockedGuidance(soonestUnblockAt, blockReason) {
         `  /login ${PROVIDER}  - add another account`,
     ].join("\n");
 }
+const ENABLE_ACCOUNT_FALLBACK = "  Set anthropicSubscriptionProvider.accountFallback: true (or SENPI_CLAUDE_SDK_OAUTH_ACCOUNT_FALLBACK=1) to switch accounts automatically.";
+/**
+ * With account fallback off, only one account may serve (senpi#3465), so the pool-wide advice is wrong:
+ * other accounts may be healthy, and adding one does not help because it is never used. Name the account
+ * and the remedies that do work. The cause words ("authentication error", "rate limit") stay, so the outer
+ * credential-pool classifier reads the same verdict as for the pool-wide guidance.
+ */
+export function singleAccountUnavailableGuidance(account, soonestUnblockAt, blockReason) {
+    if (!account.configured) {
+        return [
+            `Claude account '${account.name}' for ${PROVIDER} is not configured, and account fallback is off, so no other account is used.`,
+            `  /claude-account list  - see the configured accounts`,
+            `  /claude-account pin <name>  - pin a configured account (or /claude-account unpin)`,
+            "  Start a new session if this session's account was removed.",
+            ENABLE_ACCOUNT_FALLBACK,
+        ].join("\n");
+    }
+    const until = soonestUnblockAt !== undefined && Number.isFinite(soonestUnblockAt)
+        ? new Date(soonestUnblockAt).toISOString()
+        : undefined;
+    const cause = blockReason === "auth_error" ? "authentication error" : "rate limit";
+    return [
+        `Claude account '${account.name}' for ${PROVIDER} is blocked (${cause})${until === undefined ? "" : ` until ${until}`}, and account fallback is off, so no other account is tried.`,
+        ...(until === undefined ? [] : [`  Wait until ${until}, when this account can serve again.`]),
+        ...(blockReason === "auth_error" ? [`  /login ${PROVIDER}  - re-authenticate this account`] : []),
+        `  /claude-account pin <name>  - switch to another account`,
+        ENABLE_ACCOUNT_FALLBACK,
+    ].join("\n");
+}
 /**
  * The remedy for a version-floor 400 depends on which binary ran: updating senpi/omo only helps
  * the bundled one, and `claude update` (which the API text suggests) only helps a `claude` on PATH.

package/dist/core/extensions/builtin/anthropic-subscription/settings.d.ts

@@ -23,6 +23,8 @@ export interface AnthropicSubscriptionProviderSettings {
     readonly settingSources?: SettingSource[];
     readonly strictMcpConfig?: boolean;
     readonly pinnedAccount?: string;
+    /** Allow automatic switching to another managed account after failure. Defaults to true. */
+    readonly accountFallback?: boolean;
     readonly tokenInjection?: AnthropicSubscriptionTokenInjection;
     readonly compactionOwner?: AnthropicSubscriptionCompactionOwner;
 }

package/dist/core/extensions/builtin/anthropic-subscription/settings.js

@@ -69,6 +69,7 @@ function parseProviderSettings(value) {
     const settingSources = parseSettingSources(value.settingSources);
     const strictMcpConfig = typeof value.strictMcpConfig === "boolean" ? value.strictMcpConfig : undefined;
     const pinnedAccount = parseNonEmptyString(value.pinnedAccount);
+    const accountFallback = typeof value.accountFallback === "boolean" ? value.accountFallback : undefined;
     const tokenInjection = parseTokenInjection(value.tokenInjection);
     const compactionOwner = parseCompactionOwner(value.compactionOwner);
     return {
@@ -80,6 +81,7 @@ function parseProviderSettings(value) {
         ...(settingSources !== undefined ? { settingSources } : {}),
         ...(strictMcpConfig !== undefined ? { strictMcpConfig } : {}),
         ...(pinnedAccount !== undefined ? { pinnedAccount } : {}),
+        ...(accountFallback !== undefined ? { accountFallback } : {}),
         ...(tokenInjection !== undefined ? { tokenInjection } : {}),
         ...(compactionOwner !== undefined ? { compactionOwner } : {}),
     };
@@ -92,6 +94,7 @@ function parseEnvironmentSettings(environment) {
     const tokenInjection = parseTokenInjection(environment.SENPI_CLAUDE_SDK_OAUTH_TOKEN_INJECTION);
     const settingSources = parseEnvironmentSettingSources(environment.SENPI_CLAUDE_SDK_OAUTH_SETTING_SOURCES);
     const pinnedAccount = parseNonEmptyString(environment.SENPI_CLAUDE_SDK_OAUTH_PINNED_ACCOUNT);
+    const accountFallback = parseEnvironmentBoolean(environment.SENPI_CLAUDE_SDK_OAUTH_ACCOUNT_FALLBACK);
     const compactionOwner = parseCompactionOwner(environment.SENPI_CLAUDE_SDK_OAUTH_COMPACTION_OWNER);
     return {
         ...(enabled !== undefined ? { enabled } : {}),
@@ -101,6 +104,7 @@ function parseEnvironmentSettings(environment) {
         ...(tokenInjection !== undefined ? { tokenInjection } : {}),
         ...(settingSources !== undefined ? { settingSources } : {}),
         ...(pinnedAccount !== undefined ? { pinnedAccount } : {}),
+        ...(accountFallback !== undefined ? { accountFallback } : {}),
         ...(compactionOwner !== undefined ? { compactionOwner } : {}),
     };
 }

package/dist/core/extensions/builtin/anthropic-subscription/stream-guidance.js

@@ -1,9 +1,11 @@
 import { AllAccountsBlockedError } from "./affinity.js";
 import { classifySdkError } from "./errors.js";
-import { allAccountsBlockedGuidance, claudeCodeVersionFloorGuidance, sdkErrorGuidance } from "./guidance.js";
+import { allAccountsBlockedGuidance, claudeCodeVersionFloorGuidance, sdkErrorGuidance, singleAccountUnavailableGuidance, } from "./guidance.js";
 export function withAuthGuidance(error, message, ran) {
     if (error instanceof AllAccountsBlockedError)
-        return allAccountsBlockedGuidance(error.soonestUnblockAt, error.blockReason);
+        return error.unavailableAccount === undefined
+            ? allAccountsBlockedGuidance(error.soonestUnblockAt, error.blockReason)
+            : singleAccountUnavailableGuidance(error.unavailableAccount, error.soonestUnblockAt, error.blockReason);
     const guidance = sdkErrorGuidance(classifySdkError(error).kind);
     const versionGuidance = claudeCodeVersionFloorGuidance(message, ran);
     const hints = [guidance, versionGuidance].filter((hint) => hint !== undefined);