@hu3rror/pi-failover 0.4.0 → 0.5.0

package/README.md

@@ -8,7 +8,7 @@ Automatic credential and provider failover for [Pi coding agent](https://github.
 pi install npm:@hu3rror/pi-failover
 ```
 
-`pi-failover` helps a Pi session keep going when the current credential or provider becomes unavailable. It works with Pi's existing `auth.json` and adds one extension field, `backupKeys`, for API-key providers. The legacy `key-backup` spelling is still recognized on read.
+`pi-failover` helps a Pi session keep going when the current credential or provider becomes unavailable. It works with Pi's existing `auth.json` and adds two extension fields: `backupKeys` (spare keys for an API-key provider) and `isFallback` (marks a provider as an eligible provider-failover target). The legacy `key-backup` spelling is still recognized on read.
 
 ## About this fork
 
@@ -35,14 +35,15 @@ pi install npm:@hu3rror/pi-failover
 
 If `PI_CODING_AGENT_DIR` is set, Pi's own agent-directory resolution still applies.
 
-Keep Pi's primary credential as-is and add `backupKeys` to any API-key provider that should have same-provider backups. The field accepts either one literal, non-empty string or a non-empty array of literal, non-empty strings:
+Keep Pi's primary credential as-is and add `backupKeys` to any API-key provider that should have same-provider backups. To let a provider be switched to when the current provider fails, mark it with `isFallback: true`. The field accepts either one literal, non-empty string or a non-empty array of literal, non-empty strings:
 
 ```json
 {
   "anthropic": {
     "type": "api_key",
     "key": "primary-api-key",
-    "backupKeys": ["backup-api-key-1", "backup-api-key-2"]
+    "backupKeys": ["backup-api-key-1", "backup-api-key-2"],
+    "isFallback": true
   },
   "openai-codex": {
     "type": "oauth",
@@ -55,6 +56,7 @@ Keep Pi's primary credential as-is and add `backupKeys` to any API-key provider
 
 The existing string form remains equivalent to a one-item array. Array entries are tried in order. If the array is empty or any item is invalid, the entire backup field is ignored and the provider remains available only through its primary credential. The legacy `key-backup` spelling is read only when `backupKeys` is absent; when both fields are present, `backupKeys` wins.
 
+`isFallback` defaults to absent (equivalent to `false`): by default `pi-failover` only retries keys within the current provider and hands the failure back to Pi's built-in retry, never switching providers. Mark one or more providers with `isFallback: true` to opt into provider failover.
 ### 3. Verify that failover is active
 
 Start Pi and run:
@@ -68,10 +70,10 @@ The command shows redacted runtime status only. It never prints raw credential v
 If the active key receives a handled failure during a user request, `pi-failover` can:
 
 - switch to the next backup key for the same provider
-- switch to the next configured provider (after every backup key of the current provider is exhausted; a provider without `backupKeys` never switches providers)
+- switch to a marked fallback provider (`isFallback: true`) after every backup key of the current provider is exhausted; provider failover never happens unless at least one provider is marked
 - retry the same user request automatically after a successful switch
-- hand a failure back to Pi's built-in retry when the active provider has no backup keys
-- show only the final provider error when every configured option is exhausted
+- hand a failure back to Pi's built-in retry when no fallback provider is available
+- show only the final provider error when every failover option is exhausted
 
 Intermediate provider errors are replaced by a hidden continuation, so no second user message is required. TUI and RPC modes still show one redacted warning for each applied credential or provider switch.
 
@@ -86,28 +88,26 @@ If all failover options are exhausted while Pi still has a built-in automatic re
 
 - `pi-failover` never reads or writes `keyrouter.json`.
 - `backupKeys` contains one or more keys for the same provider, not provider fallbacks. The legacy `key-backup` spelling is still recognized on read when `backupKeys` is absent.
-- Provider fallback order follows the top-level insertion order in `auth.json`.
-- OAuth entries can participate in provider fallback, but they do not support backup fields.
+- Provider fallback order follows the top-level insertion order in `auth.json`. Only providers marked `isFallback: true` are fallback targets; unmarked providers are never switched to.
+- OAuth entries can be marked as fallback targets, but they do not support backup fields.
 - Every `backupKeys` value is treated as a literal string. Values are not expanded from environment variables or commands.
-- Pi's `/login` flow can rewrite `auth.json` and remove unknown extension fields, so `backupKeys` may need to be re-added after logging in again.
-
+- Pi's `/login` flow can rewrite `auth.json` and remove unknown extension fields, so `backupKeys` and `isFallback` may need to be re-added after logging in again.
 ## How Failover Works
 
 Within one user request, failed credentials and providers are disabled or cooled before the hidden continuation runs. A successful `2xx` response marks the active credential or provider healthy.
 
 | Failure | What pi-failover does |
 | --- | --- |
-| `401` / `403` | Disables the current credential for the session, switches to the next backup key or the next provider, then retries the same request. A provider without `backupKeys` hands the failure back to Pi's own retry instead of switching providers. |
-| `429` | Cools down the current credential by `Retry-After`, or by 60 seconds when the header is absent, switches to the next backup key, then retries. Without `backupKeys` the failure is handed back to Pi's built-in retry. |
-| `529` or overloaded responses | Cools down the provider by `Retry-After`, or by 30 seconds when the header is absent, changes provider, then retries. |
-| `500`, `502`, `503`, `504`, network, timeout | Cools down the provider for 30 seconds, changes provider, then retries. |
+| `401` / `403` | Disables the current credential for the session, switches to the next backup key, or to a marked fallback provider once keys are exhausted, then retries the same request. With no marked fallback provider the failure is handed back to Pi's own retry. |
+| `429` | Cools down the current credential by `Retry-After`, or by 60 seconds when the header is absent, switches to the next backup key, then retries. Once every backup key is exhausted, the failure is handed back to Pi's built-in retry unless a marked fallback provider exists. |
+| `529` or overloaded responses | Cools down the provider by `Retry-After`, or by 30 seconds when the header is absent, changes to a marked fallback provider, then retries. |
+| `500`, `502`, `503`, `504`, network, timeout | Cools down the provider for 30 seconds, changes to a marked fallback provider, then retries. |
 | Other failures | Leaves Pi's normal error handling unchanged. |
-
 When switching providers, `pi-failover` prefers the current model ID. If that model is unavailable on the next provider, it uses that provider's first available model. The extension calls Pi's `setModel()`, so the new default model persists. There is no automatic failback to the original provider later.
 
 Status and warning messages identify credential slots without exposing values: the primary credential is `primary`, the first backup is `backup`, and later backups are `backup-2`, `backup-3`, and so on.
 
-An `api_key` provider without `backupKeys` never triggers provider failover: when its credential fails, `pi-failover` leaves the error message untouched and hands the failure back to Pi's own retry (`settings.retry`). OAuth providers, which structurally cannot hold backup keys, keep participating in provider failover and remain reachable as fallback targets.
+Provider failover is opt-in. A provider becomes a fallback target only when its credential record in `auth.json` carries `isFallback: true`; without any marked provider, `pi-failover` never switches providers and hands the failure back to Pi's own retry (`settings.retry`) once the active provider's backup keys (if any) are exhausted. OAuth providers can be marked too, but they never hold `backupKeys`.
 
 ## Working with Pi's Retry Settings
 
@@ -115,18 +115,19 @@ An `api_key` provider without `backupKeys` never triggers provider failover: whe
 
 | Setting | Recommended | Why |
 | --- | --- | --- |
-| `retry.enabled` | `true` | Backstop for failures `pi-failover` deliberately does not touch (e.g. a provider without `backupKeys`). |
+| `retry.enabled` | `true` | Backstop for failures `pi-failover` deliberately does not touch (e.g. when no provider is marked as a fallback target). |
 | `retry.maxRetries` | `3` (default) | Higher budgets only delay the final error after every failover option is exhausted. |
 | `retry.provider.maxRetries` | `0` (default) | SDK-level retries swallow failures before Pi sees them, so failover never observes the error. |
 | `retry.provider.timeoutMs` | e.g. `60000` | The SDK default is one hour; a hung provider blocks failover's network classification for that long. |
 
-When the active provider has no `backupKeys` and fails, `pi-failover` does not replace the error message, so Pi's built-in retry runs with its own exponential backoff (`retry.baseDelayMs`). With backups, `pi-failover` switches the key or provider and retries immediately, then returns control to Pi.
+When no fallback provider is marked and the active provider's backup keys (if any) are exhausted, `pi-failover` does not replace the error message, so Pi's built-in retry runs with its own exponential backoff (`retry.baseDelayMs`). With a marked fallback provider, `pi-failover` switches the key or provider and retries immediately, then returns control to Pi.
 
 
 ## Commands
 
 - `/failover login`: interactively add a backup API key to an `api_key` provider; run it bare to pick from the current providers, or pass a provider name (`/failover login <provider>`, with autocompletion); the key is entered in a prompt (never on the command line), confirmed, then written to `auth.json` and the catalog is rebuilt
 - `/failover status`: shows redacted failover state
+- `/failover fallback <provider> [off]`: mark a provider as a fallback target (`isFallback: true`), or clear the marker with `off`; provider names autocomplete, the flag is not secret so it is passed on the command line, and the catalog is rebuilt after the write
 - `/failover reload`: restores extension-owned overrides, then rereads `auth.json`
 
 ## Output Modes
@@ -141,7 +142,7 @@ When the active provider has no `backupKeys` and fails, `pi-failover` does not r
 ## Migration Notes
 
 If migrating from `~/.pi/keyrouter.json`, move each provider's primary credential into Pi's `auth.json`, then place either one backup string or an ordered backup array in `backupKeys`. Reorder the top-level entries in `auth.json` to control provider fallback order.
-
+Mark one or more providers you want as failover targets with `isFallback: true`; unmarked providers are never switched to.
 There is no dual-read migration path. `pi-failover` uses only `auth.json`.
 
 ## Security Notes

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 pi install npm:@hu3rror/pi-failover
 ```
 
-`pi-failover` 用于在当前凭证或 provider 不可用时，继续让 Pi 会话向下执行。它直接复用 Pi 现有的 `auth.json`，并为 API key provider 增加一个扩展字段 `backupKeys`。旧拼写 `key-backup` 在读取时仍会被识别。
+`pi-failover` 用于在当前凭证或 provider 不可用时，继续让 Pi 会话向下执行。它直接复用 Pi 现有的 `auth.json`，并增加两个扩展字段：`backupKeys`（API-key provider 的备用 key）与 `isFallback`（把某 provider 标记为 provider 级切换的合格目标）。旧拼写 `key-backup` 在读取时仍会被识别。
 
 ## 关于本分支（fork）
 
@@ -34,14 +34,15 @@ pi install npm:@hu3rror/pi-failover
 
 如果设置了 `PI_CODING_AGENT_DIR`，仍然沿用 Pi 自身的 agent 目录解析规则。
 
-保留 Pi 原有的主凭证，并在需要同 provider 备用 key 的 API-key provider 上增加 `backupKeys` 字段。该字段既可以是一个字面量、非空字符串，也可以是由字面量、非空字符串组成的非空数组：
+保留 Pi 原有的主凭证，并在需要同 provider 备用 key 的 API-key provider 上增加 `backupKeys` 字段。若希望当前 provider 失败时可以切换到某个 provider，请给它加 `isFallback: true`。`backupKeys` 既可以是一个字面量、非空字符串，也可以是由字面量、非空字符串组成的非空数组：
 
 ```json
 {
   "anthropic": {
     "type": "api_key",
     "key": "primary-api-key",
-    "backupKeys": ["backup-api-key-1", "backup-api-key-2"]
+    "backupKeys": ["backup-api-key-1", "backup-api-key-2"],
+    "isFallback": true
   },
   "openai-codex": {
     "type": "oauth",
@@ -54,6 +55,7 @@ pi install npm:@hu3rror/pi-failover
 
 现有字符串形式等价于只含一项的数组，数组中的凭证按书写顺序尝试。如果数组为空或任一元素无效，整个备用字段都会被忽略，该 provider 仍只能使用主凭证。旧拼写 `key-backup` 仅在 `backupKeys` 缺失时才会被读取；两字段同时存在时，`backupKeys` 优先。
 
+`isFallback` 默认为缺省（等价于 `false`）：默认情况下 `pi-failover` 只会在当前 provider 内重试 key，之后把失败交还给 Pi 的内置重试，绝不切换 provider。要给一个或多个 provider 加 `isFallback: true` 才会启用 provider 级切换。
 ### 3. 验证故障切换已启用
 
 启动 Pi 后执行：
@@ -67,10 +69,10 @@ pi install npm:@hu3rror/pi-failover
 当当前 key 在一次用户请求中遇到已接管的故障时，`pi-failover` 会按情况执行：
 
 - 切到同一 provider 的下一把备用 key
-- 切到下一个已配置 provider（当前 provider 的所有备用 key 都用尽之后；没有 `backupKeys` 的 provider 永远不会切换 provider）
+- 在当前 provider 的所有备用 key 用尽之后，切到标记了 `isFallback: true` 的 provider；只要没有任何 provider 被标记，就永远不会发生 provider 级切换
 - 成功切换后自动重试同一次用户请求
-- 当当前 provider 没有备用 key 时，把失败交还给 Pi 的内置重试
-- 当所有可选项都耗尽时，只显示最后一次 provider 错误
+- 当不存在可用的 fallback provider 时，把失败交还给 Pi 的内置重试
+- 当所有 failover 选项都耗尽时，只显示最后一次 provider 错误
 
 中间 provider 错误会被替换为隐藏的续跑消息，因此用户无需再次发送相同内容。TUI 和 RPC 模式仍会为每次实际生效的凭据或 provider 切换显示一条脱敏警告。
 
@@ -86,10 +88,10 @@ pi install npm:@hu3rror/pi-failover
 
 - `pi-failover` 不会读取或写入 `keyrouter.json`。
 - `backupKeys` 表示同一 provider 的一把或多把备用 key，不表示 provider 级切换。旧拼写 `key-backup` 在 `backupKeys` 缺失时仍会被识别。
-- provider 的切换顺序由 `auth.json` 顶层字段的插入顺序决定。
-- OAuth 条目可以参与 provider 级切换，但不支持备用字段。
+- provider 的切换顺序由 `auth.json` 顶层字段的插入顺序决定。只有标记为 `isFallback: true` 的 provider 才是切换目标；未标记的 provider 永远不会被切换过去。
+- OAuth 条目可以标记为切换目标，但不支持备用字段。
 - `backupKeys` 中的每个值都按字面量字符串处理，不支持从环境变量或命令动态展开。
-- Pi 的 `/login` 流程可能会重写 `auth.json` 并移除未知扩展字段，因此重新登录后可能需要再次补上 `backupKeys`。
+- Pi 的 `/login` 流程可能会重写 `auth.json` 并移除未知扩展字段，因此重新登录后可能需要再次补上 `backupKeys` 与 `isFallback`。
 
 ## 故障切换规则
 
@@ -97,17 +99,17 @@ pi install npm:@hu3rror/pi-failover
 
 | 故障类型 | `pi-failover` 的处理方式 |
 | --- | --- |
-| `401` / `403` | 将当前凭证在本次会话中标记为不可用，切换到下一把备用 key 或下一个 provider，然后重试同一次请求。没有 `backupKeys` 的 provider 会把失败交还给 Pi 自己的重试，而不是切换 provider。 |
-| `429` | 按 `Retry-After` 冷却当前凭证；如果没有该响应头，则冷却 60 秒，切换到下一把备用 key 后重试。没有 `backupKeys` 时，失败交还给 Pi 的内置重试。 |
-| `529` 或 overloaded 响应 | 按 `Retry-After` 冷却当前 provider；如果没有该响应头，则冷却 30 秒，切换 provider 后重试。 |
-| `500`、`502`、`503`、`504`、网络错误、超时 | 将当前 provider 冷却 30 秒，切换 provider 后重试。 |
+| `401` / `403` | 将当前凭证在本次会话中标记为不可用，切换到下一把备用 key；key 用尽后切到标记了 `isFallback` 的 provider，然后重试同一次请求。没有标记任何 fallback provider 时，失败交还给 Pi 自己的重试。 |
+| `429` | 按 `Retry-After` 冷却当前凭证；如果没有该响应头，则冷却 60 秒，切换到下一把备用 key 后重试。备用 key 全部用尽后，除非存在标记了 `isFallback` 的 provider，否则失败交还给 Pi 的内置重试。 |
+| `529` 或 overloaded 响应 | 按 `Retry-After` 冷却当前 provider；如果没有该响应头，则冷却 30 秒，切到标记了 `isFallback` 的 provider 后重试。 |
+| `500`、`502`、`503`、`504`、网络错误、超时 | 将当前 provider 冷却 30 秒，切到标记了 `isFallback` 的 provider 后重试。 |
 | 其他故障 | 保持 Pi 原有的错误处理逻辑，不额外接管。 |
 
 发生 provider 切换时，`pi-failover` 会优先保留当前 model ID；如果目标 provider 没有该 model，则退回到该 provider 的第一个可用 model。扩展内部会调用 Pi 的 `setModel()`，因此新的默认 model 会持续生效；后续不会自动切回原 provider。
 
 状态和警告信息只显示脱敏后的凭证槽位：主凭证为 `primary`，第一把备用凭证为 `backup`，后续依次为 `backup-2`、`backup-3`……
 
-没有 `backupKeys` 的 `api_key` provider 永远不会触发 provider 级切换：其凭证失败时，`pi-failover` 不修改错误消息，直接把失败交还给 Pi 自己的重试（`settings.retry`）。OAuth provider 结构上无法持有备用 key，仍然参与 provider 级切换，并且始终可以作为被切换的目标。
+provider 级切换是显式开启的。只有当某 provider 的 credential 记录在 `auth.json` 中带有 `isFallback: true` 时，它才会成为切换目标；没有任何标记 provider 时，`pi-failover` 绝不切换 provider，而是在当前 provider 的备用 key（如有）用尽后把失败交还给 Pi 自己的重试（`settings.retry`）。OAuth provider 也可以被标记，但它们永远不会持有 `backupKeys`。
 
 ## 与 Pi 的 retry 设置配合
 
@@ -115,18 +117,19 @@ pi install npm:@hu3rror/pi-failover
 
 | 设置项 | 推荐值 | 原因 |
 | --- | --- | --- |
-| `retry.enabled` | `true` | 作为 `pi-failover` 刻意不接管的失败（例如没有 `backupKeys` 的 provider）的兜底。 |
+| `retry.enabled` | `true` | 作为 `pi-failover` 刻意不接管的失败（例如没有标记任何 fallback provider 时）的兜底。 |
 | `retry.maxRetries` | `3`（默认值） | 更大的预算只会在所有 failover 选项耗尽后拖延最终错误出现的时间。 |
 | `retry.provider.maxRetries` | `0`（默认值） | SDK 层的重试会在 Pi 看到错误之前把失败吞掉，failover 将永远观察不到该错误。 |
 | `retry.provider.timeoutMs` | 例如 `60000` | SDK 默认是 1 小时；provider 挂起时，failover 的网络故障分类会被阻塞同样长的时间。 |
 
-当当前 provider 没有 `backupKeys` 且请求失败时，`pi-failover` 不替换错误消息，Pi 的内置重试会按自己的指数退避（`retry.baseDelayMs`）执行。配置了备用 key 时，`pi-failover` 会立即切换 key 或 provider 并重试，随后把控制权交还给 Pi。
+当没有标记任何 fallback provider、且当前 provider 的备用 key（如有）已用尽时，`pi-failover` 不替换错误消息，Pi 的内置重试会按自己的指数退避（`retry.baseDelayMs`）执行。存在标记了 `isFallback` 的 provider 时，`pi-failover` 会立即切换 key 或 provider 并重试，随后把控制权交还给 Pi。
 
 
 ## 命令
 
 - `/failover login`：交互式地为 `api_key` provider 添加备用 key；不带参数时从现有 provider 中选择，也可直接指定 provider（`/failover login <provider>`，支持自动补全）；key 在输入框中录入（绝不通过命令行参数传入），经确认后写入 `auth.json` 并立即重建 failover catalog，新 key 立即可用
 - `/failover status`：查看脱敏后的故障切换状态
+- `/failover fallback <provider> [off]`：把某 provider 标记为 fallback 目标（`isFallback: true`），或用 `off` 清除标记；provider 名支持自动补全，该标记非机密，可直接作为命令行参数传入，写入成功后立即重建 catalog
 - `/failover reload`：恢复扩展接管的 override，然后重新读取 `auth.json`
 
 ## 输出模式
@@ -142,6 +145,8 @@ pi install npm:@hu3rror/pi-failover
 
 如果从 `~/.pi/keyrouter.json` 迁移，需要把每个 provider 的主凭证搬到 Pi 的 `auth.json` 中，再把一把备用 key 字符串或按顺序排列的备用 key 数组写入 `backupKeys`。如需控制 provider 切换顺序，可直接调整 `auth.json` 顶层条目的顺序。
 
+把希望作为切换目标的 provider 标记为 `isFallback: true`；未标记的 provider 永远不会被切换过去。
+
 当前没有双读迁移模式，`pi-failover` 只读取 `auth.json`。
 
 ## 安全说明

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hu3rror/pi-failover",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Automatic API credential and provider failover for Pi coding agent.",
 	"repository": {
 		"type": "git",

package/src/add-backup-key.ts

@@ -1,7 +1,11 @@
 import * as fs from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { lockSync } from "proper-lockfile";
+import {
+	AUTH_FILE_WRITE_OPTIONS,
+	isRecord,
+	withAuthFileLock,
+} from "./auth-file.ts";
 import {
 	isApiKeyCredential,
 	isLiteralBackupKey,
@@ -9,7 +13,6 @@ import {
 	normalizeBackupKeys,
 	pickBackupField,
 } from "./auth-catalog.ts";
-
 export type AddBackupKeyRejection =
 	| "invalid-key"
 	| "unknown-provider"
@@ -27,9 +30,6 @@ export interface AddBackupKeyOptions {
 	authPath?: string;
 }
 
-// The mode applies only on file creation, mirroring Pi's FileAuthStorageBackend.
-const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf-8", mode: 0o600 } as const;
-
 /**
  * Appends a validated backup key to a provider's `backupKeys` in `auth.json`.
  *
@@ -47,30 +47,7 @@ export function addBackupKey(
 
 	if (!isLiteralBackupKey(backupKey)) return { ok: false, reason: "invalid-key" };
 
-	let release: (() => void) | undefined;
-	try {
-		release = acquireLockSync(authPath);
-	} catch (error) {
-		return lockFailureResult(error);
-	}
-
-	try {
-		let content: string;
-		try {
-			content = fs.readFileSync(authPath, "utf-8");
-		} catch (error) {
-			if (isNodeErrorWithCode(error, "ENOENT")) return { ok: false, reason: "unknown-provider" };
-			return { ok: false, reason: "unreadable" };
-		}
-
-		let parsed: unknown;
-		try {
-			parsed = JSON.parse(content);
-		} catch {
-			return { ok: false, reason: "malformed" };
-		}
-		if (!isRecord(parsed)) return { ok: false, reason: "malformed" };
-
+	const access = withAuthFileLock<AddBackupKeyResult>(authPath, (parsed) => {
 		const credential = parsed[providerId];
 		if (credential === undefined) return { ok: false, reason: "unknown-provider" };
 		if (!isRecord(credential)) return { ok: false, reason: "malformed" };
@@ -86,41 +63,8 @@ export function addBackupKey(
 		const updated = { ...parsed, [providerId]: { ...credential, backupKeys } };
 		fs.writeFileSync(authPath, JSON.stringify(updated, null, 2), AUTH_FILE_WRITE_OPTIONS);
 		return { ok: true, changed: true, provider: providerId, backupKeys };
-	} finally {
-		release?.();
-	}
-}
+	});
 
-/**
- * Acquires the `<authPath>.lock` guard, retrying `ELOCKED` briefly, mirroring
- * Pi's FileAuthStorageBackend retry loop.
- */
-function acquireLockSync(authPath: string): () => void {
-	const maxAttempts = 10;
-	const delayMs = 20;
-	for (let attempt = 1; ; attempt++) {
-		try {
-			return lockSync(authPath, { realpath: false });
-		} catch (error) {
-			if (!isNodeErrorWithCode(error, "ELOCKED") || attempt >= maxAttempts) throw error;
-			const start = Date.now();
-			while (Date.now() - start < delayMs) {
-				// Synchronous busy-wait to keep the whole operation a plain function.
-			}
-		}
-	}
-}
-
-function lockFailureResult(error: unknown): AddBackupKeyResult {
-	if (isNodeErrorWithCode(error, "ENOENT")) return { ok: false, reason: "unknown-provider" };
-	if (isNodeErrorWithCode(error, "ELOCKED")) return { ok: false, reason: "locked" };
-	return { ok: false, reason: "unreadable" };
-}
-
-function isNodeErrorWithCode(error: unknown, code: string): boolean {
-	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+	if (!access.ok) return { ok: false, reason: access.reason };
+	return access.value;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/auth-catalog.ts

@@ -8,14 +8,14 @@ export interface AuthProviderEntry {
 	provider: string;
 	type: ProviderType;
 	backupKeys?: string[];
+	isFallback?: boolean;
 }
 
 export interface AuthCatalogDiagnostic {
 	message: string;
 	provider?: string;
-	field?: "backupKeys" | "key-backup";
+	field?: "backupKeys" | "key-backup" | "isFallback";
 }
-
 export interface AuthCatalog {
 	enabled: boolean;
 	providers: AuthProviderEntry[];
@@ -48,6 +48,11 @@ export function loadAuthCatalog(options: LoadAuthCatalogOptions = {}): AuthCatal
 	for (const [provider, credential] of Object.entries(parsed)) {
 		if (!isRecord(credential)) continue;
 
+		const fallback = readIsFallback(credential);
+		if (fallback.invalid) {
+			diagnostics.push({ provider, field: "isFallback", message: "Ignored invalid isFallback" });
+		}
+
 		if (isApiKeyCredential(credential)) {
 			const entry: AuthProviderEntry = { provider, type: "api_key" };
 			const backupField = pickBackupField(credential);
@@ -57,12 +62,17 @@ export function loadAuthCatalog(options: LoadAuthCatalogOptions = {}): AuthCatal
 			} else if (backupField.value !== undefined) {
 				diagnostics.push({ provider, field: backupField.name, message: `Ignored invalid ${backupField.name}` });
 			}
+			if (fallback.value !== undefined) entry.isFallback = fallback.value;
 			providers.push(entry);
 			continue;
 		}
 
 		if (isOAuthCredential(credential)) {
-			providers.push({ provider, type: "oauth" });
+			providers.push({
+				provider,
+				type: "oauth",
+				...(fallback.value !== undefined ? { isFallback: fallback.value } : {}),
+			});
 		}
 	}
 
@@ -77,6 +87,12 @@ export function pickBackupField(credential: AuthCredential): { name: "backupKeys
 	return { name: "key-backup", value: credential["key-backup"] };
 }
 
+function readIsFallback(credential: AuthCredential): { value: boolean | undefined; invalid: boolean } {
+	const raw = credential["isFallback"];
+	if (raw === undefined) return { value: undefined, invalid: false };
+	if (typeof raw === "boolean") return { value: raw, invalid: false };
+	return { value: undefined, invalid: true };
+}
 export function normalizeBackupKeys(value: unknown): string[] | undefined {
 	if (isLiteralBackupKey(value)) return [value];
 	if (!Array.isArray(value) || value.length === 0) return undefined;

package/src/auth-file.ts

@@ -0,0 +1,91 @@
+import * as fs from "node:fs";
+import { lockSync } from "proper-lockfile";
+
+// Shared helpers for lockfile-guarded writes to Pi's auth.json, mirroring
+// Pi's official FileAuthStorageBackend (lockfile guard, 0600 mode, 2-space JSON).
+
+// The mode applies only on file creation, mirroring Pi's FileAuthStorageBackend.
+export const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf-8", mode: 0o600 } as const;
+
+export type LockFailureReason = "unknown-provider" | "locked" | "unreadable";
+
+export type AuthFileAccessFailure = "unknown-provider" | "locked" | "unreadable" | "malformed";
+
+export type AuthFileAccessResult<T> =
+	| { ok: true; value: T }
+	| { ok: false; reason: AuthFileAccessFailure };
+
+export function isNodeErrorWithCode(error: unknown, code: string): boolean {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Acquires the `<authPath>.lock` guard, retrying `ELOCKED` briefly, mirroring
+ * Pi's FileAuthStorageBackend retry loop.
+ */
+export function acquireLockSync(authPath: string): () => void {
+	const maxAttempts = 10;
+	const delayMs = 20;
+	for (let attempt = 1; ; attempt++) {
+		try {
+			return lockSync(authPath, { realpath: false });
+		} catch (error) {
+			if (!isNodeErrorWithCode(error, "ELOCKED") || attempt >= maxAttempts) throw error;
+			const start = Date.now();
+			while (Date.now() - start < delayMs) {
+				// Synchronous busy-wait to keep the whole operation a plain function.
+			}
+		}
+	}
+}
+
+export function lockFailureReason(error: unknown): LockFailureReason {
+	if (isNodeErrorWithCode(error, "ENOENT")) return "unknown-provider";
+	if (isNodeErrorWithCode(error, "ELOCKED")) return "locked";
+	return "unreadable";
+}
+
+/**
+ * Runs `mutate` under the `<authPath>.lock` guard with `auth.json` already
+ * locked, read, and parsed as a top-level object. The mutation writes back
+ * through `AUTH_FILE_WRITE_OPTIONS` and preserves provider order; failures to
+ * lock, read, or parse are mapped to structured `AuthFileAccessFailure`
+ * reasons. Mirrors Pi's official `FileAuthStorageBackend.withLock` sequence.
+ */
+export function withAuthFileLock<T>(
+	authPath: string,
+	mutate: (parsed: Record<string, unknown>) => T,
+): AuthFileAccessResult<T> {
+	let release: (() => void) | undefined;
+	try {
+		release = acquireLockSync(authPath);
+	} catch (error) {
+		return { ok: false, reason: lockFailureReason(error) };
+	}
+
+	try {
+		let content: string;
+		try {
+			content = fs.readFileSync(authPath, "utf-8");
+		} catch (error) {
+			if (isNodeErrorWithCode(error, "ENOENT")) return { ok: false, reason: "unknown-provider" };
+			return { ok: false, reason: "unreadable" };
+		}
+
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(content);
+		} catch {
+			return { ok: false, reason: "malformed" };
+		}
+		if (!isRecord(parsed)) return { ok: false, reason: "malformed" };
+
+		return { ok: true, value: mutate(parsed) };
+	} finally {
+		release?.();
+	}
+}

package/src/failover-engine.ts

@@ -55,6 +55,7 @@ export interface FailoverProvider {
 	id: string;
 	backupKeyCount?: number;
 	type: ProviderType;
+	isFallback?: boolean;
 }
 export interface FailoverEngineOptions {
 	providers: readonly FailoverProvider[];
@@ -76,6 +77,7 @@ interface ProviderState {
 	id: string;
 	type: ProviderType;
 	backupKeyCount: number;
+	isFallback: boolean;
 	keys: KeyState[];
 	cooldownUntil: number;
 }
@@ -105,6 +107,7 @@ export class FailoverEngine {
 	private readonly nextProvider: FailoverEngineOptions["nextProvider"];
 	private visitedKeys = new Set<string>();
 	private visitedProviders = new Set<string>();
+	private fellBackOnce = false;
 	private active?: ActiveAttempt;
 	private decision: FailoverDecision = { kind: "none" };
 
@@ -113,6 +116,7 @@ export class FailoverEngine {
 			id: provider.id,
 			type: provider.type,
 			backupKeyCount: provider.backupKeyCount ?? 0,
+			isFallback: provider.isFallback ?? false,
 			keys: [
 				{ slot: "primary" as const, disabled: false, cooldownUntil: 0 },
 				...Array.from({ length: provider.backupKeyCount ?? 0 }, (_, index) => ({
@@ -130,6 +134,7 @@ export class FailoverEngine {
 	startTurn(initial: ProviderPlan): FailoverDecision {
 		this.visitedKeys = new Set();
 		this.visitedProviders = new Set();
+		this.fellBackOnce = false;
 		this.active = undefined;
 
 		return this.selectPlan(initial, "switch-key") ?? this.selectFallback(initial);
@@ -220,14 +225,11 @@ export class FailoverEngine {
 	}
 
 	private selectFallback(current: ProviderPlan): FailoverDecision {
-		// A provider without backup keys never triggers provider failover: hand the
-		// failure back to Pi's own retry instead of switching providers. Providers
-		// without backups remain reachable as fallback *targets* (selectPlan does
-		// not apply this gate); only the active provider's own escape is blocked.
-		const activeProvider = this.provider(current.providerId);
-		if (activeProvider?.type === "api_key" && activeProvider.backupKeyCount === 0) {
-			return this.setDecision({ kind: "none" });
-		}
+		// Provider failover is opt-in: only providers marked `isFallback` are
+		// eligible targets. With no fallback target, hand the failure back to
+		// Pi's built-in retry (kind: "none") instead of switching providers.
+		const hasTarget = this.providers.some((provider) => provider.isFallback && provider.id !== current.providerId);
+		if (!hasTarget) return this.setDecision({ kind: "none" });
 
 		const considered = new Set<string>();
 		for (let remaining = this.providers.length; remaining > 0; remaining -= 1) {
@@ -237,10 +239,20 @@ export class FailoverEngine {
 			});
 			if (!plan) break;
 			considered.add(plan.providerId);
+			const target = this.provider(plan.providerId);
+			if (!target?.isFallback) continue;
 			const decision = this.selectPlan(plan, "switch-model");
-			if (decision) return decision;
+			if (decision) {
+				this.fellBackOnce = true;
+				return decision;
+			}
 		}
 
+		// The walk produced nothing this time. When no marked target was ever
+		// reached this turn (none was usable, e.g. unconfigured in the runtime),
+		// hand the failure back to Pi's built-in retry; only a genuine walk of
+		// marked targets is "exhausted".
+		if (!this.fellBackOnce) return this.setDecision({ kind: "none" });
 		return this.setDecision({ kind: "exhausted" });
 	}
 

package/src/index.ts

@@ -18,10 +18,15 @@ import {
 	notifyProviderSwitch,
 } from "./notification.ts";
 import { createPiRuntimeAdapter, type PiRuntimeAdapter } from "./pi-runtime.ts";
-
+import {
+	runSetFallback,
+	setProviderFallback,
+	type SetProviderFallbackResult,
+} from "./set-provider-fallback.ts";
 export interface FailoverExtensionOptions {
 	loadCatalog?: () => AuthCatalog;
 	writeBackupKey?: (providerId: string, backupKey: string) => AddBackupKeyResult;
+	writeFallback?: (providerId: string, enabled: boolean) => SetProviderFallbackResult;
 	now?: () => number;
 }
 
@@ -70,8 +75,8 @@ function retryAfterMilliseconds(headers: Record<string, string>, now: number): n
 export function createFailoverExtension(options: FailoverExtensionOptions = {}) {
 	const readCatalog = options.loadCatalog ?? loadAuthCatalog;
 	const writeBackupKey = options.writeBackupKey ?? addBackupKey;
+	const writeFallback = options.writeFallback ?? setProviderFallback;
 	const now = options.now ?? Date.now;
-
 	return function registerFailover(pi: ExtensionAPI): void {
 		let catalog: AuthCatalog = { enabled: false, providers: [], diagnostics: [] };
 		let engine: FailoverEngine | undefined;
@@ -127,6 +132,7 @@ export function createFailoverExtension(options: FailoverExtensionOptions = {})
 						id: provider.provider,
 						type: provider.type,
 						backupKeyCount: provider.backupKeys?.length ?? 0,
+						isFallback: provider.isFallback,
 					})),
 					now,
 					nextProvider: ({ current, unavailableProviderIds }) => nextProvider(current, unavailableProviderIds),
@@ -341,6 +347,29 @@ export function createFailoverExtension(options: FailoverExtensionOptions = {})
 				});
 			},
 		});
+
+		pi.registerCommand("failover-fallback", {
+			description: "mark or unmark a provider as a fallback target in auth.json",
+			getArgumentCompletions: (prefix) => {
+				const items = [
+					...readCatalog().providers.map((provider) => ({ value: provider.provider, label: provider.provider })),
+					{ value: "off", label: "off" },
+				];
+				const matches = items.filter((item) => item.value.startsWith(prefix));
+				return matches.length > 0 ? matches : null;
+			},
+			handler: async (args, ctx) => {
+				await runSetFallback(args, {
+					readCatalog,
+					writeFallback,
+					rebuild: async () => {
+						await restoreOwnedOverrides();
+						rebuild(ctx);
+					},
+					notify: (message, level) => notify(ctx, message, level),
+				});
+			},
+		});
 	};
 }
 

package/src/notification.ts

@@ -33,9 +33,11 @@ export function formatStatus(catalog: AuthCatalog, snapshot: FailoverSnapshot |
 		lines.push(`current: ${snapshot.active.providerId}/${snapshot.active.model}; key=${snapshot.active.keySlot}`);
 	}
 	for (const provider of snapshot.providers) {
+		const catalogEntry = catalog.providers.find((entry) => entry.provider === provider.providerId);
 		const providerCooldown = provider.cooldownUntil === undefined ? "" : ` until=${provider.cooldownUntil}`;
 		const keys = provider.keys.map((key) => `${key.slot}=${key.status}${key.cooldownUntil === undefined ? "" : ` until=${key.cooldownUntil}`}`).join(", ");
-		lines.push(`${provider.providerId}: ${provider.status}${providerCooldown}; ${keys}`);
+		const marker = catalogEntry?.isFallback ? " (fallback target)" : "";
+		lines.push(`${provider.providerId}${marker}: ${provider.status}${providerCooldown}; ${keys}`);
 	}
 	lines.push(`visited providers: ${snapshot.visitedProviders.join(", ") || "none"}`);
 	lines.push(`visited keys: ${snapshot.visitedKeys.map((key) => `${key.providerId}:${key.keySlot}`).join(", ") || "none"}`);

package/src/set-provider-fallback.ts

@@ -0,0 +1,131 @@
+import * as fs from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import {
+	AUTH_FILE_WRITE_OPTIONS,
+	isRecord,
+	withAuthFileLock,
+} from "./auth-file.ts";
+import type { AuthCatalog } from "./auth-catalog.ts";
+import type { NotificationLevel } from "./notification.ts";
+
+export type SetProviderFallbackRejection = "unknown-provider" | "malformed" | "unreadable" | "locked";
+
+export type SetProviderFallbackResult =
+	| { ok: true; changed: boolean; provider: string; isFallback: boolean }
+	| { ok: false; reason: SetProviderFallbackRejection };
+
+export interface SetProviderFallbackOptions {
+	authPath?: string;
+}
+
+/**
+ * Sets or clears the `isFallback` marker on a provider's credential record in
+ * `auth.json`, marking it as an eligible provider-failover target.
+ *
+ * Mirrors Pi's official write method (`FileAuthStorageBackend.withLock`) exactly
+ * like `addBackupKey`: lockfile-guarded read-modify-write, `0600` permissions,
+ * 2-space JSON, other credentials and provider order preserved. The default
+ * `authPath` mirrors the catalog loader's injection point.
+ */
+export function setProviderFallback(
+	providerId: string,
+	enabled: boolean,
+	options: SetProviderFallbackOptions = {},
+): SetProviderFallbackResult {
+	const authPath = options.authPath ?? join(getAgentDir(), "auth.json");
+
+	const access = withAuthFileLock<SetProviderFallbackResult>(authPath, (parsed) => {
+		const credential = parsed[providerId];
+		if (credential === undefined) return { ok: false, reason: "unknown-provider" };
+		if (!isRecord(credential)) return { ok: false, reason: "malformed" };
+
+		const changed = credential["isFallback"] !== enabled;
+		if (!changed) return { ok: true, changed: false, provider: providerId, isFallback: enabled };
+
+		const updated = { ...parsed, [providerId]: { ...credential, isFallback: enabled } };
+		fs.writeFileSync(authPath, JSON.stringify(updated, null, 2), AUTH_FILE_WRITE_OPTIONS);
+		return { ok: true, changed: true, provider: providerId, isFallback: enabled };
+	});
+
+	if (!access.ok) return { ok: false, reason: access.reason };
+	return access.value;
+}
+
+export interface SetFallbackDependencies {
+	readCatalog: () => AuthCatalog;
+	writeFallback: (providerId: string, enabled: boolean) => SetProviderFallbackResult;
+	rebuild: () => void | Promise<void>;
+	notify: (message: string, level: NotificationLevel) => void;
+}
+
+/**
+ * Argument-based `/failover-fallback` flow: `/failover-fallback <provider>`
+ * marks the provider as a fallback target, `/failover-fallback <provider> off`
+ * clears the marker. The flag is not secret, so it is passed on the command
+ * line (unlike `/failover-login`, which keeps keys out of the command line).
+ */
+export async function runSetFallback(args: string, deps: SetFallbackDependencies): Promise<void> {
+	const tokens = args.trim().split(/\s+/).filter((token) => token !== "");
+	if (tokens.length === 0) {
+		deps.notify("pi-failover: usage: /failover-fallback <provider> [off]", "error");
+		return;
+	}
+	if (tokens.length > 2 || (tokens.length === 2 && tokens[1] !== "off")) {
+		deps.notify(
+			tokens.length === 2
+				? `pi-failover: unknown option ${tokens[1]}; use "off" to unmark a fallback provider`
+				: "pi-failover: usage: /failover-fallback <provider> [off]",
+			"error",
+		);
+		return;
+	}
+
+	const providerId = tokens[0];
+	const enabled = tokens.length === 1;
+
+	const catalog = deps.readCatalog();
+	if (!catalog.providers.some((provider) => provider.provider === providerId)) {
+		deps.notify(`pi-failover: unknown provider ${providerId}`, "error");
+		return;
+	}
+
+	const result = deps.writeFallback(providerId, enabled);
+	if (!result.ok) {
+		deps.notify(`pi-failover: could not update ${providerId}: ${describeRejection(result.reason)}`, "error");
+		return;
+	}
+
+	await deps.rebuild();
+
+	if (enabled) {
+		deps.notify(
+			result.changed
+				? `pi-failover: ${providerId} is now a fallback target`
+				: `pi-failover: ${providerId} is already a fallback target`,
+			"info",
+		);
+	} else {
+		deps.notify(
+			result.changed
+				? `pi-failover: ${providerId} is no longer a fallback target`
+				: `pi-failover: ${providerId} is not marked as a fallback target`,
+			"info",
+		);
+	}
+}
+
+function describeRejection(reason: SetProviderFallbackRejection): string {
+	switch (reason) {
+		case "unknown-provider":
+			return "provider not found in auth.json";
+		case "malformed":
+			return "auth.json malformed";
+		case "unreadable":
+			return "auth.json unreadable";
+		case "locked":
+			return "auth.json locked by another process";
+	}
+}
+