pi-ccswitch-auto-switch 0.1.7 → 0.3.0

package/README.md

@@ -13,13 +13,15 @@ The extension observes real Pi requests, records sanitized health signals, and
 - Endpoint circuit breakers for DNS, connection, server, and streaming failures.
 - Endpoint platform isolation: when several models on the same endpoint (same BaseURL/provider) fail within one round, the whole endpoint is isolated so sibling models from the same platform are not tried one by one.
 - Model-only isolation for missing models and incompatible parameters.
-- Prefers a healthy model from another provider before considering a sibling model.
+- Learns model-family content-policy constraints from real failures (`glm-4.5` and `GLM-4.6`, for example, are both `glm`) and avoids the entire family during current and future content-policy failover chains. Evidence expires after 30 days.
+- Applies hard health, failure-domain, policy-family, input-modality, and context filters before ranking candidates by provider diversity, model equivalence, capability compatibility, and historical reliability.
   - Independent-provider semantics: a copied vendor (e.g. `my-provider-copy`) shares the BaseURL but is a distinct provider with its own endpoint key, so isolating one never blocks the other.
 - 90-second first-response and 120-second streaming-idle watchdogs.
 - Exponential cooldowns, `Retry-After` support, and one persisted half-open probe lease per provider.
 - Persistent, atomic, cross-process health state with error redaction and bounded logs.
 - Compact Pi status bar and interactive health panel.
 - Non-interactive `--print` / JSON runs monitor and record failures but do not inject a competing retry.
+- `pi-ccswitch-run` keeps one headless Pi RPC session alive and returns only the final successful answer after automatic model failover.
 
 ## Requirements
 
@@ -45,6 +47,18 @@ Restart Pi or run `/reload` after installing or updating. To update the Git inst
 
 CC Switch should be configured normally. This extension deliberately does not write Pi model settings or CC Switch data.
 
+### Headless / automation use
+
+Install the package as an npm dependency, then run its binary (or invoke the packaged `runner.mjs` with Node):
+
+```bash
+pi-ccswitch-run --no-tools --no-context-files @prompt.md "Summarize the attached text"
+```
+
+The runner starts one `pi --mode rpc --no-session --no-extensions --extension <this package>/index.ts` process, so only CCSwitch is loaded. `PI_BIN` may point to the real Pi executable; it must not point to `pi-ccswitch-run`. The default deadline is ten minutes and can be changed with `--timeout-ms`.
+
+Exit codes are `0` for success, `1` when candidates are exhausted, `2` for invocation/RPC configuration failures, `124` for timeout, and `130`/`143` for interruption. Text `@files` are supported in the first release; images and stdin input are intentionally not.
+
 ## Commands
 
 | Command | What it does |
@@ -54,7 +68,7 @@ CC Switch should be configured normally. This extension deliberately does not wr
 | `/ccswitch refresh` | Refresh Pi's model registry and the status display. |
 | `/ccswitch reactivate <provider/model\|all>` | Clear a breaker and let the next real request verify recovery, while preserving history. |
 | `/ccswitch disable <provider/model>` | Manually exclude a model from failover. |
-| `/ccswitch reset <provider/model\|all>` | Delete selected health history after confirmation. |
+| `/ccswitch reset <provider/model\|all>` | Delete selected health history after confirmation; `all` also clears learned content-policy constraints. |
 | `/ccswitch-test` | Inspect candidate discovery without changing models. |
 
 Examples:
@@ -80,7 +94,7 @@ CCS ✓70/131 · ⏳61 · ⛔0 · 🔄3 · provider/model-id
 
 四个状态（健康/冷却/禁用/切换）即使为 0 也始终显示，便于确认扩展处于监控中。All-healthy still shows zero counters, e.g. `CCS ✓131/131 · ⏳0 · ⛔0 · 🔄0 · provider/model-id`. Use `/ccswitch` or `/ccswitch-test` to see Pi's raw scope entry count, the deduplicated model count, affected model counts, and the underlying breaker-record count.
 
-切换成功后扩展还会通过 `appendEntry` 向会话注入一条 `ccswitch-switch` custom entry（不参与 LLM 上下文），触发 TUI 底栏重绘——这样 Pi 右下角的模型名显示也会同步为切换后的模型。
+切换成功后扩展还会通过 `appendEntry` 向会话注入一条 `ccswitch-switch` custom entry（不参与 LLM 上下文），触发 TUI 底栏重绘——这样 Pi 右下角的模型名显示也会同步为切换后的模型。RPC 模式还会发出协议版本为 `1` 的 `ccswitch-complete` 或 `ccswitch-exhausted` 终态 entry；runner 用它们区分中间失败轮和最终结果。
 
 ## Failover behavior
 
@@ -90,15 +104,16 @@ The state machine waits for Pi's native retry cycle to settle before switching.
 | --- | --- | --- |
 | `401`, `403`, quota, billing | Provider | 30 minutes |
 | `429` | Provider | `Retry-After` when present; otherwise 5 minutes |
-| DNS, network, `5xx`, interrupted stream | Endpoint | 2 minutes |
+| DNS, network, `408`, `5xx`, interrupted stream | Endpoint | 2 minutes |
 | `404`, invalid model, incompatible parameters | Model | 15 minutes |
-| Content filtering or context overflow | Current round only | None |
+| Content-policy or sensitive-content rejection | Current model + learned model-family constraint | 2-minute model cooldown; 30-day family evidence |
+| Context overflow | Current round only | None |
 
-Cooldowns grow exponentially within bounded limits. Context-overflow retries only consider models with a larger context window. User cancellations are not recorded as failures; watchdog cancellations are recorded as timeouts.
+Cooldowns grow exponentially within bounded limits. Learned policy-constrained families are excluded only after a content-policy rejection; they remain eligible during ordinary rate-limit, network, and model-configuration failovers. Context-overflow retries only consider models with a larger context window, and image requests do not move to a model that explicitly supports text only. Unknown errors are isolated to the current model and still fail over normally. A user cancellation is the only aborted turn that does not trigger failover; watchdog cancellations are recorded as timeouts.
 
 ## Data and privacy
 
-Health state is stored in Pi's agent directory as `ccswitch-auto-switch-state.json`. The extension stores counters, timestamps, cooldowns, and redacted/truncated error summaries. It does not access credentials, authorization headers, CC Switch's database, or Pi's `auth.json`.
+Health state is stored in Pi's agent directory as `ccswitch-auto-switch-state.json`. The extension stores counters, timestamps, cooldowns, learned model-family policy constraints, and redacted/truncated error summaries. It does not access credentials, authorization headers, CC Switch's database, or Pi's `auth.json`.
 
 ## Development
 
@@ -108,7 +123,7 @@ npm run typecheck
 npm test
 ```
 
-Tests use Node's built-in test runner and cover failure classification, provider-first selection, cooldowns, state persistence, and Windows-compatible paths.
+Tests use Node's built-in test runner and cover the failure matrix, family-level policy avoidance, provider-first selection, input compatibility, cooldowns, state persistence, and Windows-compatible paths.
 
 ## License
 

package/README.zh-CN.md

@@ -12,12 +12,14 @@
 - 对认证、额度、账单和限流实施 Provider 优先熔断。
 - 对 DNS、连接、服务端和流中断实施端点熔断。
 - 模型不存在或参数不兼容时仅隔离该模型。
-- 优先选择不同 Provider 的健康模型；同 Provider 的模型排在后面。
+- 内容审查失败会学习模型系列约束（例如 `glm-4.5`、`GLM-4.6` 同属 `glm`），本轮及后续内容审查故障转移会避开整个受限系列；证据 30 天后自动过期。
+- 候选模型先经过健康、故障域、审查系列、输入模态和上下文窗口硬过滤，再按跨 Provider、模型等价性、能力兼容和历史稳定性排序。
 - 首响应 90 秒、流式停滞 120 秒看门狗。
 - 指数退避、`Retry-After` 支持和跨进程 half-open 单探针租约。
 - 原子持久化状态、错误脱敏和有上限的日志。
 - Pi 紧凑状态栏与健康管理面板。
 - `--print` / JSON 非交互运行只监控和记录，不会注入可能与进程退出竞争的新请求。
+- `pi-ccswitch-run` 使用单个 Pi RPC 会话完成无头自动故障转移，只输出最终成功模型的回答。
 
 ## 要求
 
@@ -41,6 +43,16 @@ pi install npm:pi-ccswitch-auto-switch
 
 安装或更新后重启 Pi，或执行 `/reload`。后续更新 Git 版本可执行 `pi update --extensions`。
 
+### 无头自动化调用
+
+将本包作为 npm 依赖安装后，可调用：
+
+```bash
+pi-ccswitch-run --no-tools --no-context-files @prompt.md "请总结附件"
+```
+
+runner 内部只显式加载本扩展并启动一次 Pi RPC；`PI_BIN` 只能指定内部真实 `pi`，不能指向 runner。默认总超时为 10 分钟，可用 `--timeout-ms` 调整。退出码：成功 `0`、候选耗尽 `1`、参数/RPC 配置错误 `2`、超时 `124`、中断 `130/143`。首版只支持文本 `@文件`，不支持图片和 stdin。
+
 正常使用 CC Switch 配置 Provider 即可；本插件不会修改 Pi 模型设置或 CC Switch 数据。
 
 ## 命令
@@ -52,7 +64,7 @@ pi install npm:pi-ccswitch-auto-switch
 | `/ccswitch refresh` | 刷新 Pi 模型注册表和状态栏。 |
 | `/ccswitch reactivate <provider/model\|all>` | 解除熔断，下一次真实请求验证恢复情况；保留历史。 |
 | `/ccswitch disable <provider/model>` | 手动排除模型。 |
-| `/ccswitch reset <provider/model\|all>` | 确认后删除相应健康历史。 |
+| `/ccswitch reset <provider/model\|all>` | 确认后删除相应健康历史；`all` 同时清除已学习的审查约束。 |
 | `/ccswitch-test` | 仅检查候选发现，不切换模型。 |
 
 ## 状态栏
@@ -70,7 +82,7 @@ CCS ✓70/131 · ⏳61 · ⛔0 · 🔄3 · provider/model-id
 
 四个状态（健康/冷却/禁用/切换）即使为 0 也始终显示，便于确认扩展处于监控中；全部健康时仍显示零计数，例如 `CCS ✓131/131 · ⏳0 · ⛔0 · 🔄0 · provider/model-id`。通过 `/ccswitch` 或 `/ccswitch-test` 可同时查看 Pi 原始 scope 条目数、去重模型数、受影响模型数、底层熔断记录数、本 session 切换数与累计切换数。
 
-切换成功后扩展还会通过 `appendEntry` 向会话注入一条 `ccswitch-switch` custom entry（不参与 LLM 上下文），触发 TUI 底栏重绘——这样 Pi 右下角的模型名显示也会同步为切换后的模型。
+切换成功后扩展还会通过 `appendEntry` 向会话注入一条 `ccswitch-switch` custom entry（不参与 LLM 上下文），触发 TUI 底栏重绘——这样 Pi 右下角的模型名显示也会同步为切换后的模型。RPC 模式还会发出协议版本为 `1` 的 `ccswitch-complete` 或 `ccswitch-exhausted` 终态 entry，供 runner 判定最终结果。
 
 ## 故障转移逻辑
 
@@ -80,15 +92,16 @@ CCS ✓70/131 · ⏳61 · ⛔0 · 🔄3 · provider/model-id
 | --- | --- | --- |
 | `401`、`403`、额度或账单问题 | Provider | 30 分钟 |
 | `429` | Provider | 优先使用 `Retry-After`，否则 5 分钟 |
-| DNS、网络、`5xx`、流中断 | 端点 | 2 分钟 |
+| DNS、网络、`408`、`5xx`、流中断 | 端点 | 2 分钟 |
 | `404`、模型不存在、参数不兼容 | 模型 | 15 分钟 |
-| 内容过滤、上下文溢出 | 仅本轮 | 无 |
+| 内容审查/敏感拦截 | 当前模型 + 模型系列约束 | 模型冷却 2 分钟；系列避让证据 30 天 |
+| 上下文溢出 | 仅本轮 | 无 |
 
-冷却时间会指数增长但有上限。上下文溢出时只会选择上下文窗口更大的模型。用户主动取消不计失败；看门狗取消会记录为超时。
+冷却时间会指数增长但有上限。发生内容审查时，插件只在审查故障转移链中避开已标记系列，普通限流、网络或模型配置故障仍可选择这些模型。上下文溢出时只会选择上下文窗口更大的模型；带图片的请求不会切到明确仅支持文本的模型。无法归类的异常按单模型故障处理并正常切换。用户主动取消是唯一不会触发故障转移的异常终止；看门狗取消会记录为超时。
 
 ## 数据与隐私
 
-健康状态保存在 Pi agent 目录的 `ccswitch-auto-switch-state.json`。其中只有计数、时间、冷却信息和脱敏/截断的错误摘要；插件不会访问凭据、Authorization 请求头、CC Switch 数据库或 Pi 的 `auth.json`。
+健康状态保存在 Pi agent 目录的 `ccswitch-auto-switch-state.json`。其中只有计数、时间、冷却信息、模型系列审查约束和脱敏/截断的错误摘要；插件不会访问凭据、Authorization 请求头、CC Switch 数据库或 Pi 的 `auth.json`。
 
 ## 开发
 
@@ -98,7 +111,7 @@ npm run typecheck
 npm test
 ```
 
-测试使用 Node 内置测试运行器，覆盖失败分类、Provider 优先选择、冷却、状态持久化以及 Windows 路径。
+测试使用 Node 内置测试运行器，覆盖失败分类矩阵、系列级审查避让、Provider 优先选择、输入兼容、冷却、状态持久化以及 Windows 路径。
 
 ## 许可证
 

package/candidates.ts

@@ -1,12 +1,16 @@
-import type { ModelRef, ScopedModel } from './types.ts'
+import type { FailureClass, ModelRef, ScopedModel } from './types.ts'
 import { endpointKey, modelKey, type HealthState } from './health.ts'
 
 export interface CandidateOptions {
   current?: ModelRef
   tried: Set<string>
-  failureKind?: string
+  failureKind?: FailureClass
   health: HealthState
   avoidEndpoints?: Set<string>
+  /** 模型系列已被证实存在内容审查约束时，本轮不再选择该系列。 */
+  avoidFamilies?: ReadonlySet<string>
+  /** 本轮输入真正需要的模态；显式声明不支持的候选会被排除。 */
+  requiredInputs?: readonly string[]
 }
 
 export interface CandidateSnapshot {
@@ -76,22 +80,64 @@ export function chooseCandidate(models: ModelRef[], options: CandidateOptions):
   const candidates = models.filter(model => {
     if (options.tried.has(modelKey(model)) || blocked(model, options.health)) return false
     if (options.avoidEndpoints?.has(endpointKey(model))) return false
+    if (options.avoidFamilies?.has(modelFamily(model))) return false
+    if (!supportsRequiredInputs(model, options.requiredInputs)) return false
     if (options.failureKind === 'context_overflow' && current && (model.contextWindow ?? 0) <= (current.contextWindow ?? 0)) return false
     return true
   })
-  return candidates.sort((a, b) => score(a, current) - score(b, current))[0]
+  return candidates.sort((a, b) => score(a, current, options.health) - score(b, current, options.health))[0]
 }
 
-function score(candidate: ModelRef, current?: ModelRef): number {
+/**
+ * 返回跨 Provider 稳定的模型系列标识。内容审查通常是模型系列的能力约束，而不是某个 API Key
+ * 或单一部署的瞬时故障，因此已知系列使用显式规则；未知模型则保守地按版本号前的 id 归组。
+ */
+export function modelFamily(model: Pick<ModelRef, 'id' | 'name'>): string {
+  const identity = `${model.id} ${model.name ?? ''}`.toLowerCase()
+  const knownFamilies: Array<[string, RegExp]> = [
+    ['glm', /(?:^|[^a-z0-9])(?:chat)?glm(?:$|[^a-z])/],
+    ['qwen', /(?:^|[^a-z0-9])qwen(?:$|[^a-z])/],
+    ['deepseek', /(?:^|[^a-z0-9])deepseek(?:$|[^a-z])/],
+    ['kimi', /(?:^|[^a-z0-9])(?:kimi|moonshot)(?:$|[^a-z])/],
+    ['gpt', /(?:^|[^a-z0-9])gpt(?:$|[^a-z])/],
+    ['claude', /(?:^|[^a-z0-9])claude(?:$|[^a-z])/],
+    ['gemini', /(?:^|[^a-z0-9])gemini(?:$|[^a-z])/],
+    ['llama', /(?:^|[^a-z0-9])llama(?:$|[^a-z])/],
+    ['mistral', /(?:^|[^a-z0-9])mistral(?:$|[^a-z])/],
+    ['minimax', /(?:^|[^a-z0-9])minimax(?:$|[^a-z])/],
+    ['ernie', /(?:^|[^a-z0-9])ernie(?:$|[^a-z])/],
+    ['doubao', /(?:^|[^a-z0-9])doubao(?:$|[^a-z])/],
+    ['hunyuan', /(?:^|[^a-z0-9])hunyuan(?:$|[^a-z])/],
+  ]
+  for (const [family, pattern] of knownFamilies) if (pattern.test(identity)) return family
+
+  const leaf = model.id.toLowerCase().split('/').pop() ?? model.id.toLowerCase()
+  return leaf
+    .replace(/(?:[-_.]v)?\d+(?:[.-]\d+)*(?:[-_.].*)?$/, '')
+    .replace(/[-_.:]+$/, '') || leaf
+}
+
+function supportsRequiredInputs(candidate: ModelRef, required: readonly string[] | undefined): boolean {
+  if (!required?.length || !candidate.input?.length) return true
+  return required.every(input => candidate.input!.includes(input))
+}
+
+function score(candidate: ModelRef, current: ModelRef | undefined, health: HealthState): number {
   if (!current) return 0
+  // 排序优先级：故障域多样性 > 原模型等价性 > 输入/推理/上下文兼容性 > 历史稳定性。
+  // 硬约束（冷却、审查系列、输入模态、上下文溢出）已在上方 filter 中处理。
   const sameProvider = candidate.provider === current.provider ? 1000 : 0
   const differentId = candidate.id === current.id ? 0 : 100
   const inputMismatch = sameInputs(candidate, current) ? 0 : 20
   const reasoningMismatch = candidate.reasoning === current.reasoning ? 0 : 10
   const contextPenalty = (candidate.contextWindow ?? 0) < (current.contextWindow ?? 0) ? 5 : 0
-  return sameProvider + differentId + inputMismatch + reasoningMismatch + contextPenalty
+  const records = [health.models[modelKey(candidate)], health.providers[candidate.provider], health.endpoints[endpointKey(candidate)]]
+  const historicalPenalty = Math.min(80, records.reduce((sum, record) => sum + Math.log2((record?.totalFailures ?? 0) + 1) * 4, 0))
+  return sameProvider + differentId + inputMismatch + reasoningMismatch + contextPenalty + historicalPenalty
 }
 
 function sameInputs(a: ModelRef, b: ModelRef): boolean {
-  return (a.input ?? []).join(',') === (b.input ?? []).join(',')
+  const left = a.input ?? []
+  const right = b.input ?? []
+  return left.length === right.length && left.every(input => right.includes(input))
 }

package/classify.ts

@@ -7,10 +7,11 @@ export interface Classification {
   retryAfterMs?: number
 }
 
-const content = /content[ _-]?filter|sensitive|guardrail|policy[_ ]?violation|content[_ ]?blocked/i
+const content = /content[ _-]?(?:filter|policy|blocked|moderation)|sensitive|guardrail|policy[_ -]?violation|responsibleai|safety[_ -]?(?:policy|filter|violation)|security[_ -]?policy|moderation[_ -]?(?:blocked|failed)|blocked by.{0,20}(?:policy|safety|moderation)|data[_ -]?inspection[_ -]?failed|内容(?:审查|审核|安全|违规|被拦截)|安全审核|安全(?:策略|风控).{0,12}(?:阻断|拦截|拒绝)|审核(?:未通过|不通过|失败)|敏感(?:内容|词|信息)?|政治敏感|涉政|不合规|违反.{0,12}(?:安全|政策|规定)/i
 const quota = /quota|billing|insufficient.?balance|out of budget|usage.?limit|credit.?balance|monthly.?limit/i
 const context = /context.?window|context.?length|too many tokens|prompt is too long|input is too long|token limit/i
-const transport = /dns|enotfound|eai_again|socket|connection|network|fetch failed|timed? ?out|timeout|stream ended|terminated|websocket/i
+const transport = /dns|enotfound|eai_again|econn(?:reset|refused|aborted)|epipe|socket|connection|network|fetch failed|tls|certificate|timed? ?out|timeout|stream ended|terminated|websocket|und_err/i
+const overloaded = /overload|server busy|service unavailable|temporarily unavailable|capacity|upstream|bad gateway/i
 
 export function classifyFailure(observation: FailureObservation): Classification {
   const text = `${observation.rawStopReason ?? ''} ${observation.message ?? ''}`
@@ -21,12 +22,15 @@ export function classifyFailure(observation: FailureObservation): Classification
   // chooseCandidate 会排除后自动切换到其他模型，而不是同一内容原样重试到本轮上限。
   if (content.test(text)) return { kind: 'content_policy', scope: 'model', roundOnly: false }
   if (context.test(text)) return { kind: 'context_overflow', roundOnly: true }
+  if (status === 413) return { kind: 'context_overflow', roundOnly: true }
   if (status === 429) return { kind: 'rate_limit', scope: 'provider', roundOnly: false, retryAfterMs: observation.retryAfterMs }
+  if (status === 402) return { kind: 'quota', scope: 'provider', roundOnly: false }
   if (status === 401 || status === 403) return { kind: 'auth', scope: 'provider', roundOnly: false }
   if (quota.test(text)) return { kind: 'quota', scope: 'provider', roundOnly: false }
+  if (status === 408) return { kind: 'timeout', scope: 'endpoint', roundOnly: false }
   if (status !== undefined && status >= 500) return { kind: 'endpoint', scope: 'endpoint', roundOnly: false }
+  if (transport.test(text) || overloaded.test(text)) return { kind: 'endpoint', scope: 'endpoint', roundOnly: false }
   if (status === 400 || status === 404 || status === 422) return { kind: 'model_config', scope: 'model', roundOnly: false }
-  if (transport.test(text)) return { kind: 'endpoint', scope: 'endpoint', roundOnly: false }
   return { kind: 'unknown', scope: 'model', roundOnly: false }
 }
 

package/health.ts

@@ -24,12 +24,25 @@ export interface HealthRecord {
   leaseUntil?: number
 }
 
+export interface ContentPolicyConstraint {
+  observations: number
+  lastObservedAt: number
+  avoidUntil: number
+  lastModel: string
+  lastError?: string
+}
+
 export interface HealthState {
   schemaVersion: 2
   updatedAt: number
   models: Record<string, HealthRecord>
   providers: Record<string, HealthRecord>
   endpoints: Record<string, HealthRecord>
+  /**
+   * 已从真实失败中学到的模型系列内容审查约束。它不会影响普通故障选模，只在本轮已经
+   * 发生 content_policy 失败时用于避开同类系列。
+   */
+  contentPolicyFamilies?: Record<string, ContentPolicyConstraint>
   /** 累计成功切换次数（跨 session 持久化，用于衡量扩展有效程度） */
   switches?: number
   /** 最近成功切换日志（有限条，环形保留） */
@@ -64,7 +77,7 @@ function safeEndpoint(value: string): string {
 }
 
 function blank(): HealthState {
-  return { schemaVersion: 2, updatedAt: Date.now(), models: {}, providers: {}, endpoints: {}, switches: 0, switchLog: [] }
+  return { schemaVersion: 2, updatedAt: Date.now(), models: {}, providers: {}, endpoints: {}, contentPolicyFamilies: {}, switches: 0, switchLog: [] }
 }
 
 function redact(text: string | undefined): string | undefined {
@@ -91,6 +104,7 @@ export class HealthStore {
   private state: HealthState = blank()
   private dirty = false
   private replaceOnFlush = false
+  private resetModels = new Set<string>()
 
   constructor(dir = agentDir()) { this.dir = dir }
   get file(): string { return join(this.dir, STATE_FILE) }
@@ -143,6 +157,24 @@ export class HealthStore {
     this.touch()
   }
 
+  /**
+   * 内容审查约束比限流/网络故障稳定得多，但仍设置 30 天证据有效期，避免模型策略升级后
+   * 永久污染路由。再次观察到同系列审查会增加证据计数并刷新有效期。
+   */
+  recordContentPolicyConstraint(family: string, model: ModelRef, message?: string): void {
+    const constraints = this.state.contentPolicyFamilies ??= {}
+    const previous = constraints[family]
+    const now = Date.now()
+    constraints[family] = {
+      observations: (previous?.observations ?? 0) + 1,
+      lastObservedAt: now,
+      avoidUntil: now + 30 * 24 * 60 * 60_000,
+      lastModel: modelKey(model),
+      lastError: redact(message),
+    }
+    this.touch()
+  }
+
   recordSuccess(model: ModelRef): void {
     this.close('model', modelKey(model))
     this.close('provider', model.provider)
@@ -192,9 +224,14 @@ export class HealthStore {
   }
 
   reset(target: string | 'all'): void {
-    if (target === 'all') this.state = blank()
-    else delete this.state.models[target]
-    this.replaceOnFlush = true
+    if (target === 'all') {
+      this.state = blank()
+      this.replaceOnFlush = true
+      this.resetModels.clear()
+    } else {
+      delete this.state.models[target]
+      this.resetModels.add(target)
+    }
     this.touch()
   }
 
@@ -221,7 +258,8 @@ export class HealthStore {
   async flush(): Promise<void> {
     if (!this.dirty) return
     await this.withLock(async () => {
-      this.state = mergeState(await this.readDisk(), this.state)
+      if (!this.replaceOnFlush) this.state = mergeState(await this.readDisk(), this.state)
+      for (const key of this.resetModels) delete this.state.models[key]
       await this.commit()
     }).catch(() => {})
   }
@@ -259,6 +297,7 @@ export class HealthStore {
     await rename(temp, this.file)
     this.dirty = false
     this.replaceOnFlush = false
+    this.resetModels.clear()
   }
   private bucket(scope: HealthScope): Record<string, HealthRecord> {
     return scope === 'model' ? this.state.models : scope === 'provider' ? this.state.providers : this.state.endpoints
@@ -314,5 +353,20 @@ function mergeState(a: HealthState, b: HealthState): HealthState {
     .sort((x, y) => y.at - x.at)
     .filter((entry, index, all) => index === 0 || all[index - 1].at !== entry.at || all[index - 1].from !== entry.from || all[index - 1].to !== entry.to)
     .slice(0, 20)
-  return { schemaVersion: 2, updatedAt: Math.max(a.updatedAt ?? 0, b.updatedAt ?? 0), models: mergeBucket(a.models ?? {}, b.models ?? {}), providers: mergeBucket(a.providers ?? {}, b.providers ?? {}), endpoints: mergeBucket(a.endpoints ?? {}, b.endpoints ?? {}), switches, switchLog: log }
+  const contentPolicyFamilies: Record<string, ContentPolicyConstraint> = {}
+  for (const family of new Set([...Object.keys(a.contentPolicyFamilies ?? {}), ...Object.keys(b.contentPolicyFamilies ?? {})])) {
+    const left = a.contentPolicyFamilies?.[family]
+    const right = b.contentPolicyFamilies?.[family]
+    if (!left) contentPolicyFamilies[family] = right!
+    else if (!right) contentPolicyFamilies[family] = left
+    else {
+      const newest = right.lastObservedAt >= left.lastObservedAt ? right : left
+      contentPolicyFamilies[family] = {
+        ...newest,
+        observations: Math.max(left.observations, right.observations),
+        avoidUntil: Math.max(left.avoidUntil, right.avoidUntil),
+      }
+    }
+  }
+  return { schemaVersion: 2, updatedAt: Math.max(a.updatedAt ?? 0, b.updatedAt ?? 0), models: mergeBucket(a.models ?? {}, b.models ?? {}), providers: mergeBucket(a.providers ?? {}, b.providers ?? {}), endpoints: mergeBucket(a.endpoints ?? {}, b.endpoints ?? {}), contentPolicyFamilies, switches, switchLog: log }
 }

package/index.ts

@@ -1,12 +1,13 @@
 import type { ExtensionAPI, ExtensionContext, FailureObservation, ModelRef } from './types.ts'
 import { classifyFailure, parseRetryAfter } from './classify.ts'
-import { candidateSnapshot, effectiveCandidates, chooseCandidate, summarizeCandidateHealth } from './candidates.ts'
-import { HealthStore, endpointKey, modelKey } from './health.ts'
+import { candidateSnapshot, effectiveCandidates, chooseCandidate, modelFamily, summarizeCandidateHealth } from './candidates.ts'
+import { HealthStore, endpointKey, modelKey, type HealthState } from './health.ts'
 
 const FIRST_RESPONSE_TIMEOUT = 90_000
 const STREAM_IDLE_TIMEOUT = 120_000
 const MAX_ATTEMPTS = 5
 const ROUND_LIMIT = 8 * 60_000
+const RPC_PROTOCOL_VERSION = 1
 // 同端点（BaseURL 相同）连续失败达到该次数即隔离该端点，避免同一个平台的多个模型逐个试错耗尽本轮切换
 const ENDPOINT_FAIL_THRESHOLD = 3
 
@@ -32,12 +33,26 @@ interface Round {
   observation?: FailureObservation
   model?: ModelRef
   endpointFails?: EndpointFailTracker
+  /** 本轮内容审查故障转移中必须避开的模型系列（包含持久化学到的约束）。 */
+  avoidFamilies?: Set<string>
   /** 本轮内最后一次成功切换的时间；用于刷新 ROUND_LIMIT 窗口，避免供应商内部重试耗时导致误判“达到上限” */
   lastSwitchAt?: number
 }
 
 function key(model: ModelRef | undefined): string | undefined { return model && modelKey(model) }
 function canRetry(ctx: ExtensionContext): boolean { return ctx.mode === 'tui' || ctx.mode === 'rpc' }
+function activePolicyFamilies(state: HealthState, now = Date.now()): Set<string> {
+  return new Set(Object.entries(state.contentPolicyFamilies ?? {})
+    .filter(([, record]) => record.avoidUntil > now)
+    .map(([family]) => family))
+}
+
+function resolveModel(ctx: ExtensionContext, provider: string, id: string, previous?: ModelRef): ModelRef {
+  // 优先使用注册表/scope 中的完整元数据，避免 turn_end 消息只有 provider/id 时丢失 BaseURL、
+  // 上下文窗口和输入模态；previous/ctx.model 作为注册表未命中时的后备。
+  const refs = [...ctx.scopedModels.map(item => item.model), ...ctx.modelRegistry.getAvailable(), previous, ctx.model]
+  return refs.find(model => model?.provider === provider && model.id === id) ?? { provider, id }
+}
 
 export default function (pi: ExtensionAPI) {
   const health = new HealthStore()
@@ -51,10 +66,9 @@ export default function (pi: ExtensionAPI) {
   const armWatchdog = (ctx: ExtensionContext, ms: number, roundId: number) => {
     clearWatchdog()
     timer = setTimeout(() => {
-      if (!round || round.id !== roundId || (!ctx.isIdle() && !round.inTool)) {
-        round && (round.watchdog = true)
-        ctx.abort()
-      }
+      if (!round || round.id !== roundId || ctx.isIdle() || round.inTool) return
+      round.watchdog = true
+      ctx.abort()
     }, ms)
     timer.unref?.()
   }
@@ -90,7 +104,7 @@ export default function (pi: ExtensionAPI) {
       '/ccswitch refresh — 刷新 Pi 模型注册表和状态',
       '/ccswitch reactivate <provider/model|all> — 解除熔断，保留历史',
       '/ccswitch disable <provider/model> — 手动禁用模型',
-      '/ccswitch reset <provider/model|all> — 清除健康历史（需确认）',
+      '/ccswitch reset <provider/model|all> — 清除健康历史；all 也会清除已学习的审查约束（需确认）',
       '/ccswitch-test — 自检候选模型，不实际切换',
     ].join('\n'), 'info')
   }
@@ -104,16 +118,19 @@ export default function (pi: ExtensionAPI) {
     const candidates = snapshot.models
     const counts = summarizeCandidateHealth(candidates, state)
     const now = Date.now()
+    const policyFamilies = activePolicyFamilies(state, now)
     const rows = candidates.slice(0, 10).map(model => {
       const modelRecord = state.models[modelKey(model)]
       const records = [modelRecord, state.providers[model.provider], state.endpoints[endpointKey(model)]]
       const blockedUntil = Math.max(0, ...records.flatMap(record => [record?.cooldownUntil ?? 0, record?.leaseUntil ?? 0]))
-      const suffix = modelRecord?.disabled ? '手动禁用' : blockedUntil > now ? `自动冷却 ${Math.max(1, Math.ceil((blockedUntil - now) / 60_000))}m` : '健康'
+      const policySuffix = policyFamilies.has(modelFamily(model)) ? ' · 内容审查约束' : ''
+      const baseSuffix = modelRecord?.disabled ? '手动禁用' : blockedUntil > now ? `自动冷却 ${Math.max(1, Math.ceil((blockedUntil - now) / 60_000))}m` : '健康'
+      const suffix = `${baseSuffix}${policySuffix}`
       return `${modelKey(model)}  ${suffix}`
     })
     if (!ctx.ui.select) {
       const source = snapshot.source === 'scoped' ? `Pi scope ${snapshot.sourceEntries} 条` : `Pi 注册表 ${snapshot.sourceEntries} 条`
-      notify(ctx, `CCSwitch：${source} · 唯一模型 ${counts.total} · 健康 ${counts.healthy} · 自动冷却 ${counts.cooling} · 手动禁用 ${counts.disabled} · 本session切换 ${sessionSwitches} · 累计切换 ${state.switches ?? 0}`, 'info')
+      notify(ctx, `CCSwitch：${source} · 唯一模型 ${counts.total} · 健康 ${counts.healthy} · 自动冷却 ${counts.cooling} · 手动禁用 ${counts.disabled} · 审查约束系列 ${policyFamilies.size} · 本session切换 ${sessionSwitches} · 累计切换 ${state.switches ?? 0}`, 'info')
       return
     }
     const scopeLabel = snapshot.source === 'scoped' ? `Pi scope：${snapshot.sourceEntries} 条` : `Pi 可用注册表：${snapshot.sourceEntries} 条`
@@ -123,7 +140,8 @@ export default function (pi: ExtensionAPI) {
       return `  ${time} ${entry.from} 🔄 ${entry.to}`
     })
     const switchPanel = recentSwitches.length ? `\n最近切换：\n${recentSwitches.join('\n')}` : ''
-    const action = await ctx.ui.select(`CCSwitch 健康面板\n当前：${key(ctx.model) ?? '无'}\n${scopeLabel} · 唯一模型：${counts.total} · 健康：${counts.healthy} · 自动冷却：${counts.cooling} · 手动禁用：${counts.disabled}\n熔断记录：${counts.breakerRecords}\n${switchSummary}${switchPanel}\n${rows.join('\n') || '没有可用模型'}`, ['刷新', '重新激活当前模型', '禁用当前模型', '重置当前模型历史', '关闭'])
+    const policySummary = policyFamilies.size ? [...policyFamilies].join(', ') : '无'
+    const action = await ctx.ui.select(`CCSwitch 健康面板\n当前：${key(ctx.model) ?? '无'}\n${scopeLabel} · 唯一模型：${counts.total} · 健康：${counts.healthy} · 自动冷却：${counts.cooling} · 手动禁用：${counts.disabled}\n熔断记录：${counts.breakerRecords} · 审查约束系列：${policySummary}\n${switchSummary}${switchPanel}\n${rows.join('\n') || '没有可用模型'}`, ['刷新', '重新激活当前模型', '禁用当前模型', '重置当前模型历史', '关闭'])
     if (action === '刷新') await refresh(ctx)
     if (action === '重新激活当前模型' && ctx.model) { health.reactivate(ctx.model); await health.flush(); status(ctx); notify(ctx, '已重新激活当前模型') }
     if (action === '禁用当前模型' && ctx.model) { health.disable(modelKey(ctx.model), true); await health.flush(); status(ctx); notify(ctx, '已禁用当前模型', 'warning') }
@@ -139,6 +157,23 @@ export default function (pi: ExtensionAPI) {
     ctx.ui.setWorkingMessage()
     await health.report(`# CCSwitch 自动故障转移失败\n\n时间：${new Date().toISOString()}\n原因：${reason}\n\n已尝试：\n${[...round.tried].map(item => `- ${item}`).join('\n')}\n\n可使用 /ccswitch status 查看状态，/ccswitch reactivate <provider/model> 重新激活。`)
     await health.log(`round exhausted: ${reason}; tried=${[...round.tried].join(',')}`)
+    // RPC runner relies on an explicit terminal signal instead of guessing from
+    // agent_settled. Keep this RPC-only so ordinary TUI transcripts stay quiet.
+    if (ctx.mode === 'rpc') {
+      const lastFailure = round.observation ? classifyFailure(round.observation).kind : undefined
+      try {
+        pi.appendEntry?.('ccswitch-exhausted', {
+          protocolVersion: RPC_PROTOCOL_VERSION,
+          roundId: round.id,
+          reason,
+          lastFailure,
+          model: key(round.model),
+          attempts: round.attempts,
+          tried: [...round.tried],
+          sessionSwitches,
+        })
+      } catch { /* reporting must not prevent the regular exhausted path */ }
+    }
     notify(ctx, `CCSwitch：自动切换停止（${reason}），请用 /ccswitch 查看详情`, 'error')
     status(ctx)
   }
@@ -161,20 +196,35 @@ export default function (pi: ExtensionAPI) {
       failTracker.isolated.add(ep)
       await health.log(`endpoint ${ep} failed ${epFails} times this round, isolating endpoint`)
     }
+    if (classification.kind === 'content_policy') {
+      health.recordContentPolicyConstraint(modelFamily(round.model), round.model, round.observation.message)
+      round.avoidFamilies ??= new Set()
+      for (const family of activePolicyFamilies(health.snapshot)) round.avoidFamilies.add(family)
+    }
     if (!classification.roundOnly && classification.scope) health.recordFailure(classification.scope, classification.scope === 'model' ? modelKey(round.model) : classification.scope === 'provider' ? round.model.provider : endpointKey(round.model), classification.kind, round.observation.message, classification.retryAfterMs)
     await health.flush()
     await refresh(ctx)
     const candidates = effectiveCandidates(ctx.scopedModels, ctx.modelRegistry.getAvailable())
-    let next = chooseCandidate(candidates, { current: round.model, tried: round.tried, failureKind: classification.kind, health: health.snapshot, avoidEndpoints: failTracker.isolated })
+    const candidateOptions = () => ({
+      current: round!.model,
+      tried: round!.tried,
+      failureKind: classification.kind,
+      health: health.snapshot,
+      avoidEndpoints: failTracker.isolated,
+      avoidFamilies: round!.avoidFamilies,
+      requiredInputs: round!.images?.length ? ['text', 'image'] : ['text'],
+    })
+    let next = chooseCandidate(candidates, candidateOptions())
     while (next) {
-      if (!await health.claimProvider(next)) { round.tried.add(modelKey(next)); next = chooseCandidate(candidates, { current: round.model, tried: round.tried, failureKind: classification.kind, health: health.snapshot, avoidEndpoints: failTracker.isolated }); continue }
+      if (!await health.claimProvider(next)) { round.tried.add(modelKey(next)); next = chooseCandidate(candidates, candidateOptions()); continue }
       round.attempts++
       ctx.ui.setWorkingMessage(`模型异常，正在切换到 ${modelKey(next)}…`)
+      const previousModel = round.model
       const set = await pi.setModel(next).catch(() => false)
       if (!set) {
         health.recordFailure('model', modelKey(next), 'model_config', 'Pi refused model selection')
         round.tried.add(modelKey(next)); await health.flush()
-        next = chooseCandidate(candidates, { current: round.model, tried: round.tried, failureKind: classification.kind, health: health.snapshot, avoidEndpoints: failTracker.isolated })
+        next = chooseCandidate(candidates, candidateOptions())
         continue
       }
       round.model = next
@@ -183,7 +233,7 @@ export default function (pi: ExtensionAPI) {
       round.lastSwitchAt = Date.now()
       // 本次 session 成功切换计数 + 持久化累计/日志（衡量扩展有效程度）
       sessionSwitches += 1
-      const fromKey = key(round.model ?? ctx.model)
+      const fromKey = key(previousModel ?? ctx.model)
       health.recordSwitch(fromKey ?? '', modelKey(next), classification.kind)
       await health.flush()
       notify(ctx, `CCSwitch：已切换至 ${modelKey(next)}（${round.attempts}/${MAX_ATTEMPTS}）`, 'info')
@@ -191,7 +241,15 @@ export default function (pi: ExtensionAPI) {
       // interactive-mode 收到后执行 footer.invalidate() + requestRender()，footer 从 session.state.model 重新读取，
       // 从而让右下角模型名同步显示新模型（setModel 只改 state，不直接触发 footer 刷新）。
       try {
-        pi.appendEntry?.('ccswitch-switch', { from: fromKey ?? '', to: modelKey(next), reason: classification.kind, sessionSwitches })
+        pi.appendEntry?.('ccswitch-switch', {
+          protocolVersion: RPC_PROTOCOL_VERSION,
+          roundId: round.id,
+          from: fromKey ?? '',
+          to: modelKey(next),
+          reason: classification.kind,
+          attempts: round.attempts,
+          sessionSwitches,
+        })
       } catch { /* appendEntry 失败不影响切换 */ }
       const continuation = round.hadTool || round.hadOutput
         ? '请从当前会话状态继续完成上一条请求；不要重复已经完成的工具操作。'
@@ -213,7 +271,7 @@ export default function (pi: ExtensionAPI) {
     if (event.source === 'extension') return { action: 'continue' }
     clearWatchdog()
     lastStatus = {}
-    round = { id: (round?.id ?? 0) + 1, phase: 'monitoring', startedAt: Date.now(), text: event.text, images: event.images, tried: new Set(), attempts: 0, hadTool: false, inTool: false, hadOutput: false, watchdog: false, cleanRetry: false, model: ctx.model, endpointFails: undefined }
+    round = { id: (round?.id ?? 0) + 1, phase: 'monitoring', startedAt: Date.now(), text: event.text, images: event.images, tried: new Set(), attempts: 0, hadTool: false, inTool: false, hadOutput: false, watchdog: false, cleanRetry: false, model: ctx.model, endpointFails: undefined, avoidFamilies: undefined }
     status(ctx)
     return { action: 'continue' }
   })
@@ -240,7 +298,7 @@ export default function (pi: ExtensionAPI) {
     const message = event.message
     if (message?.role !== 'assistant' || !round) return
     clearWatchdog()
-    round.model = { provider: message.provider, id: message.model }
+    round.model = resolveModel(ctx, message.provider, message.model, round.model)
     round.hadOutput ||= Boolean(message.content?.length)
     if (message.stopReason === 'error' || message.stopReason === 'aborted') {
       round.phase = 'settled-error'
@@ -249,6 +307,20 @@ export default function (pi: ExtensionAPI) {
     } else {
       health.recordSuccess(round.model); await health.flush()
       round.phase = 'idle'; round.observation = undefined; ctx.ui.setWorkingMessage(); status(ctx)
+      // agent_settled is also emitted after intermediate failed turns. An
+      // explicit terminal entry lets the headless RPC runner return only after
+      // this final successful assistant turn has settled.
+      if (ctx.mode === 'rpc') {
+        try {
+          pi.appendEntry?.('ccswitch-complete', {
+            protocolVersion: RPC_PROTOCOL_VERSION,
+            roundId: round.id,
+            model: key(round.model),
+            attempts: round.attempts,
+            sessionSwitches,
+          })
+        } catch { /* completion reporting is best-effort */ }
+      }
     }
   })
   pi.on('agent_settled', async (_event, ctx) => {
@@ -256,6 +328,7 @@ export default function (pi: ExtensionAPI) {
     if (!ctx.isIdle()) return
     if (!canRetry(ctx) && round.observation && round.model) {
       const classification = classifyFailure(round.observation)
+      if (classification.kind === 'content_policy') health.recordContentPolicyConstraint(modelFamily(round.model), round.model, round.observation.message)
       if (!classification.roundOnly && classification.scope) {
         const domain = classification.scope === 'model' ? modelKey(round.model) : classification.scope === 'provider' ? round.model.provider : endpointKey(round.model)
         health.recordFailure(classification.scope, domain, classification.kind, round.observation.message, classification.retryAfterMs)
@@ -293,7 +366,8 @@ export default function (pi: ExtensionAPI) {
     const snapshot = candidateSnapshot(ctx.scopedModels, ctx.modelRegistry.getAvailable())
     const counts = summarizeCandidateHealth(snapshot.models, health.snapshot)
     const state = health.snapshot
+    const policyFamilies = activePolicyFamilies(state)
     const source = snapshot.source === 'scoped' ? `Pi scope ${snapshot.sourceEntries} 条` : `Pi 注册表 ${snapshot.sourceEntries} 条`
-    notify(ctx, `CCSwitch 自检：${source} · 唯一模型 ${counts.total} · 健康 ${counts.healthy} · 自动冷却 ${counts.cooling} · 手动禁用 ${counts.disabled} · 熔断记录 ${counts.breakerRecords} · 本session切换 ${sessionSwitches} · 累计切换 ${state.switches ?? 0}`, counts.total ? 'info' : 'warning')
+    notify(ctx, `CCSwitch 自检：${source} · 唯一模型 ${counts.total} · 健康 ${counts.healthy} · 自动冷却 ${counts.cooling} · 手动禁用 ${counts.disabled} · 熔断记录 ${counts.breakerRecords} · 审查约束系列 ${policyFamilies.size} · 本session切换 ${sessionSwitches} · 累计切换 ${state.switches ?? 0}`, counts.total ? 'info' : 'warning')
   }})
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ccswitch-auto-switch",
-  "version": "0.1.7",
+  "version": "0.3.0",
   "description": "Provider-first automatic model failover extension for Pi and CC Switch",
   "license": "MIT",
   "keywords": [
@@ -20,11 +20,15 @@
   "homepage": "https://github.com/JunyWuuuu91/pi-ccswitch-auto-switch#readme",
   "files": [
     "index.ts",
+    "runner.mjs",
     "types.ts",
     "classify.ts",
     "candidates.ts",
     "health.ts"
   ],
+  "bin": {
+    "pi-ccswitch-run": "./runner.mjs"
+  },
   "pi": {
     "extensions": [
       "./index.ts"
@@ -35,7 +39,7 @@
     "node": ">=22.19.0"
   },
   "scripts": {
-    "test": "node --test test/*.test.ts",
+    "test": "node --test test/*.test.ts test/*.test.mjs",
     "typecheck": "tsc --noEmit --allowImportingTsExtensions --module nodenext --moduleResolution nodenext --target es2022 --skipLibCheck *.ts"
   },
   "devDependencies": {

package/runner.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * Headless Pi runner that keeps one RPC session alive while the CCSwitch
+ * extension retries a failed turn on another model.
+ */
+import { spawn } from 'node:child_process'
+import { access, readFile, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { basename, delimiter, dirname, extname, isAbsolute, join, resolve } from 'node:path'
+
+export const EXIT = Object.freeze({ SUCCESS: 0, EXHAUSTED: 1, CONFIG: 2, TIMEOUT: 124, INTERRUPTED: 130, TERMINATED: 143 })
+export const DEFAULT_TIMEOUT_MS = 600_000
+
+const usage = `Usage: pi-ccswitch-run [options] [--] [@text-file ...] <prompt>
+
+Options:
+  --timeout-ms <ms>       Total runner timeout (default: ${DEFAULT_TIMEOUT_MS})
+  --no-tools              Disable Pi tools
+  --no-context-files      Disable AGENTS.md / CLAUDE.md discovery
+  --provider <name>       Initial Pi provider
+  --model <name>          Initial Pi model
+  --thinking <level>      Initial Pi thinking level
+  --models <patterns>     Limit the failover candidate scope
+  -p, --print             Accepted for migration compatibility
+  --no-session            Accepted; sessions are always ephemeral
+  --no-extensions         Accepted; external discovery is always disabled
+  -h, --help              Show this help`
+
+const passthroughWithValue = new Set(['--provider', '--model', '--thinking', '--models'])
+const acceptedNoops = new Set(['-p', '--print', '--no-session', '--no-extensions'])
+
+export function parseArgs(argv) {
+  const piArgs = []
+  const files = []
+  const prompt = []
+  let timeoutMs = DEFAULT_TIMEOUT_MS
+  let positional = false
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--') { positional = true; continue }
+    if (!positional && (arg === '-h' || arg === '--help')) return { help: true }
+    if (!positional && arg === '--timeout-ms') {
+      const raw = argv[++index]
+      const value = Number(raw)
+      if (!Number.isSafeInteger(value) || value <= 0) throw new Error('--timeout-ms must be a positive integer')
+      timeoutMs = value
+      continue
+    }
+    if (!positional && (arg === '--no-tools' || arg === '--no-context-files')) { piArgs.push(arg); continue }
+    if (!positional && passthroughWithValue.has(arg)) {
+      const value = argv[++index]
+      if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`)
+      piArgs.push(arg, value)
+      continue
+    }
+    if (!positional && acceptedNoops.has(arg)) continue
+    if (!positional && arg.startsWith('-')) throw new Error(`unsupported option: ${arg}`)
+    if (!positional && arg.startsWith('@')) {
+      if (arg.length === 1) throw new Error('@file requires a path')
+      files.push(arg.slice(1))
+      continue
+    }
+    prompt.push(arg)
+  }
+  if (prompt.length === 0) throw new Error('a prompt is required')
+  return { timeoutMs, piArgs, files, prompt: prompt.join(' ') }
+}
+
+export async function readTextFiles(fileArgs, cwd = process.cwd()) {
+  let text = ''
+  for (const raw of fileArgs) {
+    const path = resolve(cwd, raw)
+    try { await access(path) } catch { throw new Error(`file not found: ${path}`) }
+    const info = await stat(path)
+    if (!info.isFile()) throw new Error(`not a regular text file: ${path}`)
+    if (info.size === 0) continue
+    let content
+    try { content = await readFile(path, 'utf8') } catch { throw new Error(`not a UTF-8 text file: ${path}`) }
+    if (content.includes('\0')) throw new Error(`binary files are not supported: ${path}`)
+    text += `<file name="${path}">\n${content.replace(/^\uFEFF/, '')}\n</file>\n`
+  }
+  return text
+}
+
+export function buildMessage(fileText, prompt) {
+  return fileText ? `${fileText}\n${prompt}` : prompt
+}
+
+function validPiBinary(value) {
+  const normalized = basename(value).toLowerCase().replace(/\.(cmd|exe|bat)$/, '')
+  return normalized === 'pi'
+}
+
+async function resolveWindowsShim(command) {
+  const candidates = []
+  if (isAbsolute(command) || command.includes('\\') || command.includes('/')) candidates.push(command)
+  else {
+    for (const dir of (process.env.PATH || '').split(delimiter).filter(Boolean)) {
+      candidates.push(join(dir, command))
+      if (!/\.(cmd|bat)$/i.test(command)) candidates.push(join(dir, `${command}.cmd`))
+    }
+  }
+  for (const candidate of candidates) {
+    if (!existsSync(candidate) || !/\.(cmd|bat)$/i.test(candidate)) continue
+    const source = await readFile(candidate, 'utf8').catch(() => '')
+    const match = source.match(/["']([^"']+\.js)["']/i)
+    if (!match) continue
+    const target = match[1].replace(/%~dp0/ig, `${dirname(candidate)}\\`)
+    const entry = resolve(target.replace(/\\/g, '/'))
+    if (existsSync(entry)) return { command: process.execPath, prefix: [entry] }
+  }
+  return { command, prefix: [] }
+}
+
+async function resolvePiCommand() {
+  const configured = String(process.env.PI_BIN || '').trim()
+  if (configured && !validPiBinary(configured)) throw new Error('PI_BIN must name the real pi executable, not an arbitrary command')
+  const command = configured || 'pi'
+  if (process.platform === 'win32') return resolveWindowsShim(command)
+  return { command, prefix: [] }
+}
+
+function terminateTree(child, signal = 'SIGTERM') {
+  if (!child || child.exitCode !== null) return
+  if (process.platform === 'win32' && child.pid) {
+    const killer = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true })
+    killer.on('error', () => { try { child.kill('SIGKILL') } catch {} })
+    return
+  }
+  try { child.kill(signal) } catch {}
+  setTimeout(() => { try { child.kill('SIGKILL') } catch {} }, 1_000).unref()
+}
+
+function customEntry(event) {
+  if (event?.type !== 'entry_appended' || event.entry?.type !== 'custom') return undefined
+  return { type: event.entry.customType, data: event.entry.data || {} }
+}
+
+export async function run(options, runtime = {}) {
+  const spawnImpl = runtime.spawn || spawn
+  const extensionPath = runtime.extensionPath || fileURLToPath(new URL('./index.ts', import.meta.url))
+  const resolvePi = runtime.resolvePiCommand || resolvePiCommand
+  const log = runtime.log || ((message) => process.stderr.write(`[ccswitch] ${message}\n`))
+  const resolved = await resolvePi()
+  const args = [...resolved.prefix, '--mode', 'rpc', '--no-session', '--no-extensions', '--extension', extensionPath, ...options.piArgs]
+  const child = spawnImpl(resolved.command, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, env: process.env })
+  let buffer = ''
+  let closed = false
+  let terminal
+  let retryPending = false
+  let protocolError
+  let nextId = 1
+  const pending = new Map()
+  const closeStdin = () => { try { child.stdin?.end() } catch {} }
+  const request = (type, payload = {}) => new Promise((resolveRequest, rejectRequest) => {
+    const id = String(nextId++)
+    pending.set(id, { resolve: resolveRequest, reject: rejectRequest })
+    try { child.stdin.write(`${JSON.stringify({ id, type, ...payload })}\n`) } catch (error) { pending.delete(id); rejectRequest(error) }
+  })
+  const failPending = (error) => {
+    for (const item of pending.values()) item.reject(error)
+    pending.clear()
+  }
+  const handleEvent = (event) => {
+    if (event?.type === 'extension_error') { protocolError = `extension error: ${event.error}`; return }
+    if (event?.type === 'turn_start') retryPending = false
+    const entry = customEntry(event)
+    if (!entry) {
+      if (event?.type === 'agent_settled' && !terminal && !retryPending) {
+        protocolError = 'Pi settled without a CCSwitch terminal event'
+      }
+      return
+    }
+    if (entry.data?.protocolVersion !== 1) return
+    if (entry.type === 'ccswitch-switch') {
+      retryPending = true
+      log(`switch ${entry.data.from || '?'} → ${entry.data.to || '?'} (${entry.data.attempts ?? '?'}/5)`)
+    } else if (entry.type === 'ccswitch-complete') {
+      terminal = { kind: 'complete', data: entry.data }
+    } else if (entry.type === 'ccswitch-exhausted') {
+      terminal = { kind: 'exhausted', data: entry.data }
+    }
+  }
+  const processLine = (line) => {
+    if (!line.trim()) return
+    let event
+    try { event = JSON.parse(line) } catch { protocolError = 'Pi RPC emitted malformed JSONL'; return }
+    if (event?.type === 'response' && event.id !== undefined) {
+      const item = pending.get(String(event.id))
+      if (item) {
+        pending.delete(String(event.id))
+        if (event.success) item.resolve(event.data)
+        else item.reject(new Error(event.error || `${event.command || 'RPC'} failed`))
+      }
+      return
+    }
+    handleEvent(event)
+  }
+  child.stdout?.setEncoding('utf8')
+  child.stdout?.on('data', (chunk) => {
+    buffer += chunk
+    let newline
+    while ((newline = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newline)
+      buffer = buffer.slice(newline + 1)
+      processLine(line)
+    }
+  })
+  child.stderr?.on('data', () => {})
+  const exit = new Promise((resolveExit, rejectExit) => {
+    child.once('error', rejectExit)
+    child.once('close', (code, signal) => { closed = true; resolveExit({ code, signal }) })
+  })
+  const timeout = setTimeout(() => { protocolError = 'runner timed out'; terminateTree(child) }, options.timeoutMs)
+  timeout.unref?.()
+  const onSignal = (signal, code) => {
+    protocolError = signal
+    terminateTree(child, signal)
+    process.exitCode = code
+  }
+  const onSigint = () => onSignal('SIGINT', EXIT.INTERRUPTED)
+  const onSigterm = () => onSignal('SIGTERM', EXIT.TERMINATED)
+  process.once('SIGINT', onSigint)
+  process.once('SIGTERM', onSigterm)
+  try {
+    const commands = await request('get_commands')
+    if (!Array.isArray(commands?.commands) || !commands.commands.some((entry) => entry.name === 'ccswitch')) {
+      throw new Error('CCSwitch extension did not load')
+    }
+    await request('prompt', { message: options.message })
+    while (!terminal && !protocolError && !closed) await new Promise(resolveWait => setTimeout(resolveWait, 10))
+    if (protocolError) {
+      closeStdin()
+      await exit.catch(() => {})
+      if (protocolError === 'runner timed out') return { code: EXIT.TIMEOUT, error: protocolError }
+      if (protocolError === 'SIGINT') return { code: EXIT.INTERRUPTED, error: protocolError }
+      if (protocolError === 'SIGTERM') return { code: EXIT.TERMINATED, error: protocolError }
+      return { code: EXIT.CONFIG, error: protocolError }
+    }
+    if (!terminal) return { code: EXIT.CONFIG, error: 'Pi exited before CCSwitch reached a terminal state' }
+    if (terminal.kind === 'exhausted') {
+      closeStdin()
+      await exit.catch(() => {})
+      return { code: EXIT.EXHAUSTED, error: terminal.data.reason || 'all candidate models were exhausted' }
+    }
+    const last = await request('get_last_assistant_text')
+    const text = String(last?.text || '').trim()
+    closeStdin()
+    await exit.catch(() => {})
+    if (!text) return { code: EXIT.CONFIG, error: 'CCSwitch completed but Pi returned no assistant text' }
+    return { code: EXIT.SUCCESS, text }
+  } catch (error) {
+    terminateTree(child)
+    closeStdin()
+    await exit.catch(() => {})
+    return { code: EXIT.CONFIG, error: error instanceof Error ? error.message : String(error) }
+  } finally {
+    clearTimeout(timeout)
+    process.off('SIGINT', onSigint)
+    process.off('SIGTERM', onSigterm)
+    if (!closed) { failPending(new Error('runner stopped')); terminateTree(child) }
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  let options
+  try { options = parseArgs(argv) } catch (error) { process.stderr.write(`pi-ccswitch-run: ${error.message}\n${usage}\n`); return EXIT.CONFIG }
+  if (options.help) { process.stdout.write(`${usage}\n`); return EXIT.SUCCESS }
+  try {
+    const fileText = await readTextFiles(options.files)
+    const result = await run({ ...options, message: buildMessage(fileText, options.prompt) })
+    if (result.text) process.stdout.write(`${result.text}\n`)
+    if (result.error) process.stderr.write(`pi-ccswitch-run: ${result.error}\n`)
+    return result.code
+  } catch (error) {
+    process.stderr.write(`pi-ccswitch-run: ${error instanceof Error ? error.message : String(error)}\n`)
+    return EXIT.CONFIG
+  }
+}
+
+const invoked = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (invoked) main().then(code => { process.exitCode = code })