@fastagent-sh/voicenote 0.18.0 → 0.18.2

package/README.md

@@ -121,6 +121,15 @@ Optional settings:
 }
 ```
 
+`VOICENOTE_PI_PROVIDER` is a fallback chain, tried left to right. Credentials are
+resolved by `pi auth check` (covering OAuth, keys stored by `pi` → `/login`, and
+each provider's own API-key env var). A provider that deterministically cannot
+work — no credentials, or not a provider pi knows — is dropped from the chain,
+because its inevitable "No API key found" would replace the real error from the
+provider that actually failed. If that empties the chain, `vn run --mode notes`
+skips instead of paying for a transcript whose summary cannot happen.
+`vn doctor` prints the effective chain and the status of anything not ready.
+
 ## Usage
 
 ```bash
@@ -242,7 +251,7 @@ git push --follow-tags
 
 The workflow lives at `.github/workflows/release.yml`: CI explicitly runs typecheck/test/build + an artifact smoke test, then `npm publish --ignore-scripts` (deterministic publishing, no lifecycle dependence). Publishing uses **npm trusted publishing (OIDC)**: no long-lived token (`id-token: write` + a Trusted Publisher configured on npmjs.com), with provenance attached automatically. A bare local `npm publish` is still guarded by `prepublishOnly` (typecheck+test+build).
 
-> **First-release exception**: npm has no pending-publisher, so trusted publishing cannot publish a package's very first version. Publish once manually with `npm login` + `npm publish --ignore-scripts`, then add a Trusted Publisher on the package settings page at npmjs.com (repo `fastagent-sh/voicenote`, workflow `release.yml`); CI takes over afterwards (the npm account needs 2FA).
+> Both are already done for this package (Trusted Publisher configured, CI publishing since 0.18.0 with provenance), so a routine release needs nothing but the tag. Kept for forks: npm has no pending-publisher, so trusted publishing cannot publish a package's *very first* version — publish once manually with `npm login` + `npm publish --ignore-scripts`, then add a Trusted Publisher on the package settings page at npmjs.com (repo, workflow `release.yml`); CI takes over afterwards (the npm account needs 2FA).
 
 ## Desktop app (GUI, `app/`)
 

package/README.zh-CN.md

@@ -121,6 +121,13 @@ brew install ffmpeg
 }
 ```
 
+`VOICENOTE_PI_PROVIDER` 是从左到右尝试的回退链。凭证由 `pi auth check` 判定(覆盖
+OAuth、`pi` → `/login` 存下的 key、以及各 provider 自己的 API key 环境变量)。
+确定不可能工作的 provider(没凭证, 或 pi 根本不认识这个名字)会被剔除 —— 否则
+它必然抛出的 "No API key found" 会覆盖掉真正失败的那个 provider 的错误。若链因此
+变空, `vn run --mode notes` 会直接跳过, 而不是花钱转写一个注定无法生成纪要的录音。
+实际生效的链和非 ready 项的状态由 `vn doctor` 打印。
+
 ## 用法
 
 ```bash
@@ -242,7 +249,7 @@ git push --follow-tags
 
 workflow 位于 `.github/workflows/release.yml`:CI 显式跑 typecheck/test/build + 产物冒烟,再 `npm publish --ignore-scripts`(确定发布,不依赖 lifecycle)。发布走 **npm trusted publishing(OIDC)**:免长期 token(`id-token: write` + npmjs.com 上配好 Trusted Publisher),自动带 provenance。本地裸 `npm publish` 则由 `prepublishOnly`(typecheck+test+build)兼底。
 
-> **首发例外**:npm 无 pending-publisher,trusted publishing 发不了包的第一个版本。先本机 `npm login` 后手动 `npm publish --ignore-scripts` 发一次,再到 npmjs.com 包设置页加 Trusted Publisher(repo `fastagent-sh/voicenote`、workflow `release.yml`),之后 CI 自动接管(需 npm 账号开 2FA)。
+> 本包这两步都已完成(Trusted Publisher 已配置,自 0.18.0 起由 CI 发布并带 provenance),常规发版只需打 tag。以下保留给 fork 者:npm 无 pending-publisher,trusted publishing 发不了包的**第一个**版本 —— 先本机 `npm login` 后手动 `npm publish --ignore-scripts` 发一次,再到 npmjs.com 包设置页加 Trusted Publisher(repo、workflow `release.yml`),之后 CI 自动接管(需 npm 账号开 2FA)。
 
 ## 桌面客户端(GUI,`app/`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/voicenote",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Voice recordings → diarized transcripts → integrated semantic Markdown notes. Currently optimized for the PHILIPS VTR6500 recorder, but the workflow is generic.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
     "src/envConfig.ts",
     "src/jobs.ts",
     "src/runLock.ts",
+    "src/piProvider.ts",
     "README.md",
     "LICENSE"
   ],

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { cac } from 'cac'
 import { deriveNoProxy, envKeysToEmbed, hydrateFromFileEnv, parseFileEnv } from './envConfig'
 import { parseLockOwner } from './runLock'
+import { parsePiAuthStatus, parseProviderChain, usableChain, type PiAuthStatus } from './piProvider'
 import { applyOutcome, buildJobsView, classify, emptyState, localIso, MAX_ATTEMPTS, migrateLegacyState, ownsOutput, parseJobsLimit, parseStateFile, parseStrictJson, patchJob, pruneUnseen, reconcileInterrupted, startAttempt, SUMMARY_FAILED_STATUS, type CurrentJob, type JobRecord, type StateFile } from './jobs'
 import { createHash, createHmac, randomUUID } from 'node:crypto'
 import { appendFile, chmod, mkdir, readFile, writeFile, copyFile, rename, unlink, stat, readdir, rm } from 'node:fs/promises'
@@ -12,7 +13,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 import { spawn, spawnSync } from 'node:child_process'
 import os from 'node:os'
 
-const VERSION = '0.18.0'
+const VERSION = '0.18.2'
 const LAUNCH_AGENT_LABEL = 'sh.fastagent.voicenote'
 const LAUNCH_AGENT_LABEL_LEGACY = 'com.kid7st.voicenote' // pre-fastagent installs; cleaned up on install
 const TASK_NAME = 'VoiceNote'   // Windows Task Scheduler name (mac uses LAUNCH_AGENT_LABEL)
@@ -1292,10 +1293,19 @@ function piInvocation(args: string[]): { bin: string; args: string[] } {
   return cli ? { bin, args: [cli, ...args] } : { bin, args }
 }
 
-// Heuristic for "pi is logged in": the OAuth credential file exists. Used to skip
-// the pipeline before spending ASR on notes whose pi-codex summary would fail.
-function piAuthAvailable(): boolean {
-  return existsSync(PI_AUTH_PATH)
+// Gate before ASR is spent. "May work", not "will": only a chain pruned to
+// nothing (every provider deterministically unusable) stops a run — see
+// usableChain for why an unanswerable probe does not.
+function summaryMayWork(): boolean {
+  return piProviderCandidates().length > 0
+}
+
+// The one diagnostic for an empty chain, shared by the pre-ASR gate and the
+// summary call itself. Both must name the same cause: a generic "exhausted" here
+// would overwrite the truth exactly the way "No API key found for openai" did.
+function noUsableProviderMessage(): string {
+  const statuses = piConfiguredProviders().map(p => `${p}:${piProviderAuthStatus(p)}`).join(' ')
+  return `no usable summary provider (${statuses}) — each has no credentials, or is not a provider pi knows. Sign in (\`vn login\` for openai-codex, else \`pi\` → \`/login <provider>\` or its API key), or fix VOICENOTE_PI_PROVIDER.`
 }
 
 // ───────────────────────────────────────────────────────────────────────
@@ -1467,15 +1477,50 @@ async function configSet(): Promise<void> {
   }
 }
 
+// A healthy probe takes ~0.5s and the chain is re-read many times per run, so
+// cache it — but briefly: `vn serve` is long-lived, and the answer changes out of
+// band when the user runs `pi` → `/login` elsewhere, or an OAuth token expires.
+const PI_AUTH_TTL_MS = 60_000
+// Refresh is deliberately left on (no --no-refresh) so an expired OAuth that
+// cannot be renewed reads as broken rather than ready — which means the probe
+// touches the network and can hang. Probes are serial, so a hung pi blocks a
+// scheduler tick for this × the chain length. Kept impatient (a healthy probe is
+// ~0.5s) because a timeout yields 'unknown', which is neutral: the run proceeds
+// and pi reports the real error, so cutting it short costs nothing.
+const PI_AUTH_PROBE_MS = 2000
+const piAuthStatusCache = new Map<string, { status: PiAuthStatus; at: number }>()
+function piProviderAuthStatus(provider: string): PiAuthStatus {
+  const cached = piAuthStatusCache.get(provider)
+  if (cached && Date.now() - cached.at < PI_AUTH_TTL_MS) return cached.status
+  const inv = piInvocation(['auth', 'check', '--provider', provider, '--json'])
+  const out = spawnSync(inv.bin, inv.args, { encoding: 'utf8', timeout: PI_AUTH_PROBE_MS, windowsHide: true })
+  // No pi binary is deterministic evidence in its own right — next run gets the
+  // same answer — so it belongs with 'unusable', not with a probe that timed out.
+  const status = (out.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT'
+    ? 'unusable'
+    : parsePiAuthStatus(out.stdout || '')
+  // 'unknown' is neutral by design, so nothing downstream reports it. Say it here
+  // — throttled, not once-per-process: `vn serve` re-probes every TTL and a probe
+  // that never answers would otherwise go silent after its first tick.
+  if (status !== 'ready' && shouldLogIdleStatus(`pi-auth-probe:${provider}:${status}`)) {
+    console.error(`pi auth check ${provider} → ${status}: ${String(out.error?.message || out.stderr || out.stdout || 'no output').slice(0, 200)}`)
+  }
+  piAuthStatusCache.set(provider, { status, at: Date.now() })
+  return status
+}
+
+function piConfiguredProviders(): string[] {
+  return parseProviderChain(process.env.VOICENOTE_PI_PROVIDER)
+}
+
 function piProviderCandidates(): string[] {
-  const configured = process.env.VOICENOTE_PI_PROVIDER?.trim()
-  const raw = configured || 'openai-codex,openai'
-  const providers = raw.split(',').map(s => s.trim()).filter(Boolean)
-  return providers.length ? Array.from(new Set(providers)) : ['openai-codex', 'openai']
+  return usableChain(piConfiguredProviders(), piProviderAuthStatus)
 }
 
 function piProviderFor(): string {
-  return piProviderCandidates()[0] || 'openai-codex'
+  // Label for logs and metadata.llm_backend. Empty chain is a real state now, and
+  // naming a provider we already know is unusable would put a lie in the record.
+  return piProviderCandidates()[0] || 'none-usable'
 }
 
 function piCodexModelFor(): string {
@@ -1563,15 +1608,20 @@ function isTransientPiError(e: any): boolean {
   return /socket connection was closed|socket hang up|econnreset|etimedout|esockettimedout|enetunreach|econnrefused|eai_again|fetch failed|network error|timed ?out|temporarily|overloaded|\b(429|500|502|503|504)\b/.test(msg)
 }
 
-async function chatCompleteViaPiCodex(opts: Omit<Parameters<typeof chatCompleteViaPiProvider>[0], 'provider'>): Promise<string> {
+// Returns the provider that actually answered, not the one we started with: the
+// chain falls back, and metadata recording the head would misname the run.
+async function chatCompleteViaPiCodex(opts: Omit<Parameters<typeof chatCompleteViaPiProvider>[0], 'provider'>): Promise<{ text: string; provider: string }> {
   const providers = piProviderCandidates()
+  // Reachable past the pre-ASR gate: credentials can lapse mid-run, or the caller
+  // may not go through it at all.
+  if (!providers.length) throw new Error(noUsableProviderMessage())
   const maxAttempts = Math.max(1, Number(process.env.VOICENOTE_PI_RETRIES || 3))
   let lastError: any = null
   for (const [idx, provider] of providers.entries()) {
     if (idx > 0) console.error(`pi provider fallback: trying ${provider} after ${providers[idx - 1]} failed: ${lastError?.message || lastError}`)
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
       try {
-        return await chatCompleteViaPiProvider({ ...opts, provider })
+        return { text: await chatCompleteViaPiProvider({ ...opts, provider }), provider }
       } catch (e: any) {
         lastError = e
         if (attempt < maxAttempts && isTransientPiError(e)) {
@@ -1615,7 +1665,7 @@ function piSummaryToolsHint(contextDir: string): string {
 // base, so read/grep/find operate there directly. If a configured context dir is
 // missing, say so loudly and run without tools rather than searching the wrong
 // tree (tools, the cwd hint, and the spawn cwd move together).
-async function chatComplete(opts: { systemPrompt: string; userPrompt: string; config: Config }): Promise<string> {
+async function chatComplete(opts: { systemPrompt: string; userPrompt: string; config: Config }): Promise<{ text: string; provider: string }> {
   const wantTools = !!piSummaryTools()
   const ctx = wantTools ? summaryContextDir(opts.config) : undefined
   const ctxExists = ctx ? existsSync(ctx) : false
@@ -1633,14 +1683,14 @@ async function chatComplete(opts: { systemPrompt: string; userPrompt: string; co
   })
 }
 
-async function summarizeTranscript(config: Config, transcript: string, rec: Recording, localAudioPath: string): Promise<Json> {
+async function summarizeTranscript(config: Config, transcript: string, rec: Recording, localAudioPath: string): Promise<{ meta: Json; provider: string }> {
   const messages = summaryMessages(config, transcript, rec, localAudioPath)
   const systemPrompt = String(messages[0]!.content)
   const userPrompt = String(messages[1]!.content)
-  const text = await chatComplete({ systemPrompt, userPrompt, config })
+  const { text, provider } = await chatComplete({ systemPrompt, userPrompt, config })
   const jsonText = extractFirstJsonObject(text)
   try {
-    return JSON.parse(jsonText || '{}')
+    return { meta: JSON.parse(jsonText || '{}') as Json, provider }
   } catch (e: any) {
     throw new Error(`summary returned non-JSON output (${e?.message || e}). First 400 chars: ${text.slice(0, 400)}`)
   }
@@ -1731,14 +1781,16 @@ async function processRecording(config: Config, rec: Recording, opts: any): Prom
   const needsNotes = mode === 'notes'
   const resumeSummary = needsNotes && Boolean(opts.resumeFromTranscriptFiles)
   const transcribeBackendLabel = `volcano:${config.volcano?.resourceId || 'volc.seedasr.auc'}`
-  const llmBackendLabel = `pi:${piProviderFor()}`
+  // Lazy: resolving it probes pi (network, and `auth check` refreshes tokens on
+  // disk). Transcript mode never calls pi, and --dry-run promises no side effects.
+  const llmBackendLabel = needsNotes && !opts.dryRun ? `pi:${piProviderFor()}` : null
   const plan = resumeSummary
     ? 'reuse saved transcript → integrated semantic notes → write metadata/index (no auto move)'
     : `copy audio → transcribe → write transcript${needsNotes ? ' → integrated semantic notes' : ''} → write metadata/index (no auto move)`
 
   console.log(`\n=== voicenote job: ${basename(rec.sourcePath)} ===`)
   console.log(`Source: ${rec.sourcePath}`)
-  console.log(`Audio: duration=${rec.durationSeconds == null ? 'unknown' : formatSeconds(rec.durationSeconds)}, size=${formatBytes(rec.sizeBytes)}, mode=${mode}, asr=${transcribeBackendLabel}, llm=${llmBackendLabel}`)
+  console.log(`Audio: duration=${rec.durationSeconds == null ? 'unknown' : formatSeconds(rec.durationSeconds)}, size=${formatBytes(rec.sizeBytes)}, mode=${mode}, asr=${transcribeBackendLabel}${llmBackendLabel ? `, llm=${llmBackendLabel}` : ''}`)
   console.log(`Plan: ${plan}`)
   if (opts.dryRun) return { source_path: rec.sourcePath, source_id: rec.sourceId, would_copy_to: files.audio, resume_from_transcript: resumeSummary ? files.transcript : null, size_bytes: rec.sizeBytes, duration_seconds: rec.durationSeconds, mode }
 
@@ -1783,10 +1835,13 @@ async function processRecording(config: Config, rec: Recording, opts: any): Prom
   }
 
   let summaryError: any = null
+  let summaryProvider: string | null = null
   if (needsNotes) {
     progressStep(nextStep(), totalSteps, 'Generate integrated semantic notes', `model=${piCodexModelFor()} via ${llmBackendLabel}`)
     try {
-      meta = await withHeartbeat('generate integrated semantic notes', () => summarizeTranscript(config, transcript, rec, files.audio), 60)
+      const summary = await withHeartbeat('generate integrated semantic notes', () => summarizeTranscript(config, transcript, rec, files.audio), 60)
+      meta = summary.meta
+      summaryProvider = summary.provider
     } catch (e: any) {
       summaryError = e
       console.error(`Summary step failed; transcript is preserved. Error: ${e?.message || e}`)
@@ -1804,7 +1859,9 @@ async function processRecording(config: Config, rec: Recording, opts: any): Prom
   meta.asr_provider = 'volcano'
   meta.transcribe_model = config.volcano?.resourceId || 'volc.seedasr.auc'
   meta.summary_model = needsNotes && !summaryError ? piCodexModelFor() : null
-  meta.llm_backend = needsNotes ? llmBackendLabel : null
+  // The provider that actually answered, not the head of the chain it may have
+  // fallen back from. Null when no summary ran — summary_error says why.
+  meta.llm_backend = summaryProvider ? `pi:${summaryProvider}` : null
   meta.processed_at = nowIso()
   if (summaryError) meta.summary_error = String(summaryError?.message || summaryError)
 
@@ -2078,8 +2135,8 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
       if (shouldLogIdleStatus(`asr-misconfig:${config.recordDir}`)) console.error('ASR not configured: Volcano needs VOLCANO_ASR_KEY / VOLCANO_TOS_*. Skipping; run `vn doctor`, fix config, then re-run.')
       return
     }
-    if (mode === 'notes' && !piAuthAvailable()) {
-      if (shouldLogIdleStatus(`pi-noauth:${config.recordDir}`)) console.error('pi is not logged in (~/.pi/agent/auth.json missing). Skipping to avoid spending ASR on notes whose summary would fail. Run `pi` to log in, then re-run.')
+    if (mode === 'notes' && !summaryMayWork()) {
+      if (shouldLogIdleStatus(`pi-noauth:${config.recordDir}`)) console.error(`Skipping to avoid spending ASR on notes whose summary would fail: ${noUsableProviderMessage()}`)
       return
     }
   }
@@ -2696,6 +2753,12 @@ async function collectDoctor() {
   const ff = await runCommand(ffprobeBin(), ['-version'], 5000)
   const v = config.volcano
   const tools = piSummaryTools()
+  // Configured vs effective, plus per-provider status: "why did my chain shrink"
+  // and "why is my misspelled provider still listed" are the same question.
+  const configuredProviders = piConfiguredProviders()
+  const effectiveProviders = piProviderCandidates()
+  const providerStatus = Object.fromEntries(configuredProviders.map(p => [p, piProviderAuthStatus(p)]))
+  const summaryReady = effectiveProviders.length > 0
   return {
     version: VERSION,
     bun: process.versions.bun || null,
@@ -2711,13 +2774,18 @@ async function collectDoctor() {
           language: v.language ?? null,
         }
       : { configured: false as const },
-    summary: { backend: `pi:${piProviderCandidates().join('→')}`, providers: piProviderCandidates(), model: piCodexModelFor(), thinking: piThinkingLevel(), tools: tools || null, contextDir: tools ? summaryContextDir(config) : null },
-    pi: { bin: piCodexBin(), version: piCheck.code === 0 ? (piCheck.stdout.trim() || piCheck.stderr.trim() || null) : null, available: piCheck.code === 0, auth: piAuthAvailable() },
+    summary: { backend: `pi:${effectiveProviders.join('→') || 'none-usable'}`, ready: summaryReady, configuredProviders, effectiveProviders, providerStatus, model: piCodexModelFor(), thinking: piThinkingLevel(), tools: tools || null, contextDir: tools ? summaryContextDir(config) : null },
+    pi: { bin: piCodexBin(), version: piCheck.code === 0 ? (piCheck.stdout.trim() || piCheck.stderr.trim() || null) : null, available: piCheck.code === 0, auth: existsSync(PI_AUTH_PATH) },
     // Outbound proxy for HTTPS endpoints (updater/GitHub): honor the standard
     // env chain, not just lowercase http_proxy — an https_proxy-only setup must
     // still route the updater.
     proxy: { url: process.env.https_proxy || process.env.HTTPS_PROXY || process.env.http_proxy || process.env.HTTP_PROXY || null },
     identity: { self: config.speakers.self.name || null, aliases: config.speakers.self.aliases, knownCount: config.speakers.known.length },
+    // The thresholds that silently decide what never gets processed. Without
+    // them here, confirming a change to VOICENOTE_MAX_AGE_HOURS meant planting
+    // a test recording and watching the scan — not a reasonable way to check
+    // a setting.
+    filters: { maxAgeHours: config.maxAgeHours, minBytes: config.minBytes, minDurationSeconds: config.minDurationSeconds },
     deps: { ffprobe: ff.code === 0 },
     agent: await agentStatus(),
   }
@@ -2763,6 +2831,7 @@ async function doctor(opts: { json?: boolean } = {}): Promise<void> {
   console.log(`node=${s.node}`)
   console.log(`recordDir=${s.recorder.dir} exists=${s.recorder.exists}`)
   console.log(`workspace=${s.workspace}`)
+  console.log(`filters=maxAge:${s.filters.maxAgeHours > 0 ? `${s.filters.maxAgeHours}h` : 'none'} minSize:${(s.filters.minBytes / 1000).toFixed(0)}KB minDuration:${s.filters.minDurationSeconds}s`)
   if (s.volcano.configured) {
     console.log(`volcano.auth=${s.volcano.auth}`)
     console.log(`volcano.resourceId=${s.volcano.resourceId}`)
@@ -2773,12 +2842,17 @@ async function doctor(opts: { json?: boolean } = {}): Promise<void> {
     console.log(`volcano=not configured`)
   }
   console.log(`summaryBackend=${s.summary.backend}`)
-  console.log(`pi.bin=${s.pi.bin} providers=${s.summary.providers.join(',')} model.summary=${s.summary.model}`)
+  console.log(`pi.bin=${s.pi.bin} providers=${s.summary.effectiveProviders.join(',') || '<none usable>'} model.summary=${s.summary.model}`)
+  const notReady = Object.entries(s.summary.providerStatus).filter(([, st]) => st !== 'ready')
+  if (notReady.length) console.log(`pi.providerStatus=${notReady.map(([p, st]) => `${p}:${st}`).join(' ')} (unusable=pi not installed, no credentials, or no such provider — dropped from the chain; unknown=pi ran but gave no usable answer, kept anyway)`)
+  if (!s.summary.ready) console.log('summary.ready=NO — every configured provider is unusable; `vn run --mode notes` will skip rather than spend ASR')
   console.log(`pi.thinking=${s.summary.thinking}`)
   console.log(`pi.summaryTools=${s.summary.tools || '<disabled>'}`)
   if (s.summary.contextDir) console.log(`pi.contextDir=${s.summary.contextDir} (summary agent cwd + read/grep cross-reference root)`)
   console.log(`pi.version=${s.pi.version || 'missing'}`)
-  console.log(`pi.auth=${s.pi.auth ? 'logged-in' : 'NOT logged-in — run `vn login` to sign in, else the summary step will fail'}`)
+  // Neutral fact, not an instruction: an API-key user has no auth.json and needs
+  // nothing fixed. summary.ready above is what says whether anything is wrong.
+  console.log(`pi.auth=${s.pi.auth ? 'logged-in (auth.json present)' : 'no ~/.pi/agent/auth.json (fine if a provider API key is set)'}`)
   console.log(`defaultMode=notes`)
   console.log(`proxy=${s.proxy.url || '<unset>'}`)
   console.log(`speakers.self=${s.identity.self || '<unset>'}`)

package/src/piProvider.ts

@@ -0,0 +1,53 @@
+// Which pi providers the summary chain tries. Credential *detection* lives in
+// cli.ts (it shells out to `pi auth check`); only the pure logic is here.
+
+export const DEFAULT_PI_PROVIDERS = ['openai-codex', 'openai']
+
+export function parseProviderChain(raw: string | undefined): string[] {
+  const parsed = Array.from(new Set((raw ?? '').split(',').map(s => s.trim()).filter(Boolean)))
+  return parsed.length ? parsed : [...DEFAULT_PI_PROVIDERS]
+}
+
+export type PiAuthStatus = 'ready' | 'unusable' | 'unknown'
+
+// `pi auth check --json` is the one source of truth for credentials — OAuth, keys
+// stored by `/login`, and each provider's own env var (OPENAI_API_KEY,
+// GEMINI_API_KEY, …), names we must not reimplement guessing.
+//
+// 'unusable' is a DETERMINISTIC failure: no credentials, or no such provider —
+// next run gets the same answer. Note an OAuth token that has expired beyond
+// refresh lands here too: with refresh on, pi reports `credentials_not_configured`.
+//
+// 'unknown' is pi running but giving no usable answer: a timeout, non-JSON
+// output, or pi's own `status:"invalid"` — which per pi's auth-check means its
+// model runtime is in an error state or checkAuth threw, i.e. a pi-side fault,
+// not a verdict about this provider's credentials. (A missing pi binary is not
+// in here: the caller maps ENOENT to 'unusable', since it is deterministic.)
+export function parsePiAuthStatus(stdout: string): PiAuthStatus {
+  try {
+    const r = JSON.parse(stdout) as { status?: unknown; reason?: unknown }
+    if (r.status === 'ready') return 'ready'
+    if (r.reason === 'credentials_not_configured' || r.reason === 'provider_not_found') return 'unusable'
+  } catch { /* not JSON → unknown */ }
+  return 'unknown'
+}
+
+// One rule: only a deterministic failure justifies a decision.
+//
+// An 'unusable' provider can only fail — and because the chain throws its LAST
+// error, that failure ("No API key found for openai") would overwrite the real
+// error from the provider that actually broke, which is the bug this exists to
+// kill. So it is pruned, and a chain left with nothing blocks the run before ASR
+// is spent.
+//
+// 'unknown' is deliberately neutral: it neither prunes nor blocks. A probe that
+// could not answer is not evidence, and guessing on its behalf is the same
+// mistake in the other direction — let the run proceed and pi report the truth.
+//
+// Hence "may work": surviving this filter only means "not known to be broken",
+// and nothing downstream may read it as authenticated.
+const mayWork = (status: PiAuthStatus) => status !== 'unusable'
+
+export function usableChain(configured: string[], statusOf: (provider: string) => PiAuthStatus): string[] {
+  return configured.filter(p => mayWork(statusOf(p)))
+}