larkin 0.4.28 → 0.5.0

package/dist/runtime/pi-model-catalog.cjs

@@ -41,7 +41,6 @@ exports.findExactPiModel = findExactPiModel;
 exports.discoverPiModelCatalog = discoverPiModelCatalog;
 const node_child_process_1 = require("node:child_process");
 const path = __importStar(require("node:path"));
-const builtin_pi_assets_js_1 = require("./builtin-pi-assets.cjs");
 const pi_rpc_client_js_1 = require("./pi-rpc-client.cjs");
 const runtime_readiness_js_1 = require("./runtime-readiness.cjs");
 exports.PI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
@@ -73,16 +72,16 @@ function findExactPiModel(reference, models) {
 const discoveryCache = new Map();
 /** Discover only through Pi's structured RPC protocol; no table parsing or static fallback. */
 function piCatalogChildEnv(options) {
-    const mergedEnv = {
+    const env = {
         ...process.env,
         ...options.env,
-        ...(options.agentDir ? { PI_CODING_AGENT_DIR: path.resolve(options.agentDir) } : {}),
         NO_COLOR: "1",
     };
-    return (0, builtin_pi_assets_js_1.applyPiPackageDirForChild)(mergedEnv, {
-        distribution: (0, builtin_pi_assets_js_1.catalogPiChildDistribution)(options.commandArgs),
-        explicitPackageDir: options.packageDir,
-    });
+    if (options.agentDir)
+        env.PI_CODING_AGENT_DIR = path.resolve(options.agentDir);
+    else
+        delete env.PI_CODING_AGENT_DIR;
+    return env;
 }
 async function discoverPiModelCatalog(options) {
     if (!options.spawn) {
@@ -118,7 +117,7 @@ async function discoverPiModelCatalogUncached(options) {
         ]);
         const available = [...(availableResponse?.models ?? [])].sort((left, right) => piModelId(left).localeCompare(piModelId(right)));
         if (!available.length)
-            throw new Error("Pi has no authenticated available models. Run the official `pi` login flow or configure provider credentials; Larkin will not create a fallback session.");
+            throw new Error("Pi has no authenticated available models. Run the official `pi` login flow; Larkin will not create a fallback session.");
         const effectiveModel = state.model ? piModelId(state.model) : null;
         if (!effectiveModel || !available.some((model) => piModelId(model) === effectiveModel)) {
             throw new Error(`Pi official default resolution returned an unavailable model (${effectiveModel || "none"}); refusing implicit fallback`);

package/dist/runtime/pi-model-catalog.mjs

@@ -1,6 +1,5 @@
 import { spawn as nodeSpawn } from "node:child_process";
 import * as path from "node:path";
-import { applyPiPackageDirForChild, catalogPiChildDistribution } from "./builtin-pi-assets.mjs";
 import { PiRpcClient } from "./pi-rpc-client.mjs";
 import { classifyRuntimePrerequisite, RuntimePrerequisiteError } from "./runtime-readiness.mjs";
 export const PI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
@@ -32,16 +31,16 @@ export function findExactPiModel(reference, models) {
 const discoveryCache = new Map();
 /** Discover only through Pi's structured RPC protocol; no table parsing or static fallback. */
 function piCatalogChildEnv(options) {
-    const mergedEnv = {
+    const env = {
         ...process.env,
         ...options.env,
-        ...(options.agentDir ? { PI_CODING_AGENT_DIR: path.resolve(options.agentDir) } : {}),
         NO_COLOR: "1",
     };
-    return applyPiPackageDirForChild(mergedEnv, {
-        distribution: catalogPiChildDistribution(options.commandArgs),
-        explicitPackageDir: options.packageDir,
-    });
+    if (options.agentDir)
+        env.PI_CODING_AGENT_DIR = path.resolve(options.agentDir);
+    else
+        delete env.PI_CODING_AGENT_DIR;
+    return env;
 }
 export async function discoverPiModelCatalog(options) {
     if (!options.spawn) {
@@ -77,7 +76,7 @@ async function discoverPiModelCatalogUncached(options) {
         ]);
         const available = [...(availableResponse?.models ?? [])].sort((left, right) => piModelId(left).localeCompare(piModelId(right)));
         if (!available.length)
-            throw new Error("Pi has no authenticated available models. Run the official `pi` login flow or configure provider credentials; Larkin will not create a fallback session.");
+            throw new Error("Pi has no authenticated available models. Run the official `pi` login flow; Larkin will not create a fallback session.");
         const effectiveModel = state.model ? piModelId(state.model) : null;
         if (!effectiveModel || !available.some((model) => piModelId(model) === effectiveModel)) {
             throw new Error(`Pi official default resolution returned an unavailable model (${effectiveModel || "none"}); refusing implicit fallback`);

package/dist/runtime/pi-subagent-injection.mjs

@@ -160,12 +160,25 @@ export function piVersionSupportsSubagents(version) {
         return false;
     return version.major > 0 || (version.major === 0 && version.minor >= 80);
 }
-/** 解析 external `pi --version`；无法确认版本时视为不支持，不注入。 */
+const externalPiVersionProbeCache = new Map();
+function externalPiVersionProbeKey(piCommand, env) {
+    return JSON.stringify([piCommand, env.PATH ?? ""]);
+}
+/** 测试用：清空进程内 `pi --version` 探测缓存。 */
+export function resetExternalPiVersionProbeCache() {
+    externalPiVersionProbeCache.clear();
+}
+/** 解析 external `pi --version`；无法确认版本时视为不支持，不注入。按 piCommand+PATH 缓存。 */
 export function probeExternalPiVersion(piCommand, env) {
+    const key = externalPiVersionProbeKey(piCommand, env);
+    if (externalPiVersionProbeCache.has(key))
+        return externalPiVersionProbeCache.get(key) ?? null;
     const result = spawnSync(piCommand, ["--version"], { env, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024 });
-    if (result.error || result.status !== 0)
-        return null;
-    return parsePiVersion(String(result.stdout || result.stderr || ""));
+    const version = result.error || result.status !== 0
+        ? null
+        : parsePiVersion(String(result.stdout || result.stderr || ""));
+    externalPiVersionProbeCache.set(key, version);
+    return version;
 }
 /**
  * 用户 pi 是否已自行安装 pi-subagents（settings.json packages 或包目录）。

package/dist/runtime/runtime-adapters.mjs

@@ -3,11 +3,8 @@ import crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { createInterface } from "node:readline";
-import { applyPiPackageDirForChild, piChildDistributionFromOverrides } from "./builtin-pi-assets.mjs";
 import { isPiThinkingLevel } from "./pi-model-catalog.mjs";
 import { PiRpcClient } from "./pi-rpc-client.mjs";
-import { internalCommandSpec } from "../app/internal-command.mjs";
-import { BUNDLED_PI_VERSION, piAgentDirectory } from "./pi-provider-config.mjs";
 import { recordPiRuntimeArtifactProvenance } from "./pi-artifact-provenance.mjs";
 import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 import { resolvePiSubagentExtensionArg } from "./pi-subagent-injection.mjs";
@@ -15,9 +12,12 @@ import { extractCanonicalPiSubagentNotification, ledgerStatusFromPiNotificationS
 import { resolvePiSubagentRecordWatchdogExtensionArg } from "./pi-subagent-record-watchdog-injection.mjs";
 import { effectivePiStateDir, extractBackgroundPiSubagentDispatch } from "./pi-subagent-ledger.mjs";
 import { resolvePiBashTimeoutExtensionArg } from "./pi-bash-timeout-injection.mjs";
-import { classifyRuntimePrerequisite, probeNativeRuntimeReadiness, providerAuthenticationFailureReadiness, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
+import { classifyPiMissingCredentialRejection, classifyRuntimePrerequisite, missingProviderCredentialReadiness, probeNativeRuntimeReadiness, providerAuthenticationFailureReadiness, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
 import { buildStrictProviderErrorInput, classifyStrictProviderError, INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON, } from "./provider-error-classifier.mjs";
-import { assertEffectivePiCompactionSettings, assertNoProjectPiCompactionOverride, calculatePiCompactionSettings, parsePiExecutableVersion, prepareOwnedPiDirectory, readOwnedPiSettings, verifyPiCapabilities, writeOwnedPiSettings, } from "./pi-compaction-recovery.mjs";
+import { assertEffectivePiCompactionSettings, assertNoProjectPiCompactionOverride, PINNED_PI_VERSION, calculatePiCompactionSettings, parsePiExecutableVersion, prepareOwnedPiDirectory, readOwnedPiSettings, verifyPiCapabilities, writeOwnedPiSettings, } from "./pi-compaction-recovery.mjs";
+function piAgentDirectory(configDir, agentId) {
+    return path.join(path.resolve(configDir), "providers", "pi", agentId);
+}
 class EventSession {
     listeners = new Set();
     subscribe(listener) {
@@ -462,7 +462,7 @@ class PiSession extends EventSession {
     firstOutputObserved = false;
     toolCallOpen = false;
     piPolicyManaged;
-    constructor(sdk, distribution) {
+    constructor(sdk, distribution = "external") {
         super();
         this.sdk = sdk;
         this.distribution = distribution;
@@ -537,7 +537,19 @@ class PiSession extends EventSession {
             this.awaitingAcknowledgement.delete(input.inputId);
             this.ownedInputIds.delete(input.inputId);
             this.inputEpochs.delete(input.inputId);
-            return { status: "rejected", inputId: input.inputId, retryable: true, reason: error.message };
+            const rawReason = error instanceof Error ? error.message : String(error);
+            const missing = classifyPiMissingCredentialRejection(rawReason);
+            if (missing) {
+                const classified = classifyPiProviderError({ provider: missing.provider, message: missing.diagnostic });
+                this.emit({
+                    type: "input-error", inputId: input.inputId, retryable: false, willRetry: false,
+                    message: classified.reason, errorCategory: classified.category, nextAction: classified.nextAction,
+                    upstream: { provider: missing.provider, message: missing.diagnostic },
+                });
+                // 拒绝原因保留 Pi 原文，方便 RuntimeHost 独立分类，不依赖 input-error 事件顺序。
+                return { status: "rejected", inputId: input.inputId, retryable: false, reason: rawReason };
+            }
+            return { status: "rejected", inputId: input.inputId, retryable: true, reason: rawReason };
         }
     }
     onEvent(raw) {
@@ -664,7 +676,7 @@ class PiSession extends EventSession {
             this.emitObservation("settled");
             const owned = [...this.ownedInputIds].filter((inputId) => this.inputEpochs.get(inputId) === epoch);
             if (error) {
-                const classified = classifyPiProviderError(error);
+                const classified = classifyPiProviderError(error, { distribution: this.distribution });
                 const retryable = classified.category === "rate_limit" || isRetryablePiProviderError(error.upstream.message);
                 for (const inputId of owned)
                     this.emit({
@@ -794,7 +806,7 @@ function piAssistantProviderError(message) {
         ...(typeof bodyError.type === "string" ? { type: bodyError.type } : {}),
     };
 }
-export function classifyPiProviderError(error) {
+export function classifyPiProviderError(error, scope) {
     const upstream = "upstream" in error ? error.upstream : error;
     const errorType = "type" in error ? error.type : undefined;
     const reason = safeProviderText(upstream.message, "Pi provider request failed");
@@ -818,6 +830,11 @@ export function classifyPiProviderError(error) {
         return {
             category: "rate_limit", reason, nextAction: "Wait for the provider rate-limit window, then retry.",
         };
+    const missing = classifyPiMissingCredentialRejection(reason);
+    if (missing) {
+        const readiness = missingProviderCredentialReadiness("pi", missing.provider);
+        return { category: "auth", reason: readiness.reason, nextAction: readiness.nextAction };
+    }
     if (upstream.status === 401
         || [...signal].some((value) => ["authentication_error", "invalid_api_key", "invalid_token", "token_expired", "unauthorized", "provider_auth_error"].includes(value))
         || /\bAPI key auth failed\b|\bFailed to resolve API key\b/i.test(reason)) {
@@ -983,10 +1000,6 @@ class PiRpcBackend {
     }
 }
 export function resolvePiProcessExtensionArgs(input, resolvers = {}) {
-    // Builtin factories are passed directly to Pi main on every platform. The platform
-    // field makes that invariant explicit and testable without changing process.platform.
-    if (input.distribution === "builtin")
-        return [];
     const resolverInput = { distribution: "external", piCommand: input.piCommand, env: input.env };
     const args = [];
     // Watchdog must load before the subagent extension so session_shutdown still
@@ -1024,31 +1037,23 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
         ...(session.sessionFile ? ["--session", session.sessionFile] : []),
         ...(requestedModel ? ["--model", requestedModel] : []),
         ...(requestedEffort ? ["--thinking", requestedEffort] : [])];
-    const builtin = piChildDistributionFromOverrides(dependencies.env, input.env) === "builtin";
-    if (!builtin && mergedEnv.LARKIN_PI_DISTRIBUTION === "builtin")
+    if (mergedEnv.LARKIN_PI_DISTRIBUTION === "builtin")
         delete mergedEnv.LARKIN_PI_DISTRIBUTION;
-    const builtinSpec = builtin ? internalCommandSpec("pi-rpc", [], mergedEnv) : null;
-    const command = builtinSpec?.command ?? dependencies.piCommand ?? dependencies.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
-    const commandPrefix = builtinSpec?.args ?? dependencies.piCommandArgs ?? [];
+    const command = dependencies.piCommand ?? dependencies.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
+    const commandPrefix = dependencies.piCommandArgs ?? [];
     const commandArgs = [...commandPrefix, ...args];
     mergedEnv.PI_CODING_AGENT_DIR = ownedPiDirectory;
-    if (builtin)
-        mergedEnv.PI_TELEMETRY = "0";
-    const childEnv = applyPiPackageDirForChild(mergedEnv, {
-        distribution: builtin ? "builtin" : "external",
-        explicitPackageDir: input.env?.PI_PACKAGE_DIR ?? dependencies.env?.PI_PACKAGE_DIR,
-    });
-    const reportedVersion = productionSpawn && !builtin
+    const childEnv = { ...mergedEnv };
+    const reportedVersion = productionSpawn
         ? parsePiExecutableVersion(String(spawnSync(command, [...commandPrefix, "--version"], {
             cwd: input.workspaceDir, env: childEnv, encoding: "utf8", timeout: 5_000,
         }).stdout || ""))
-        : BUNDLED_PI_VERSION;
-    const extensionArgs = (dependencies.resolvePiProcessExtensionArgs ?? resolvePiProcessExtensionArgs)({
-        distribution: builtin ? "builtin" : "external",
-        piCommand: command,
-        env: childEnv,
-        platform: process.platform,
-    });
+        : PINNED_PI_VERSION;
+    const extensionInput = { piCommand: command, env: childEnv, platform: process.platform };
+    // 假 spawn 不需要真实 extension 路径；默认 resolver 会 spawnSync(`pi --version`)。
+    const extensionArgs = dependencies.resolvePiProcessExtensionArgs
+        ? dependencies.resolvePiProcessExtensionArgs(extensionInput)
+        : productionSpawn ? resolvePiProcessExtensionArgs(extensionInput) : [];
     commandArgs.push(...extensionArgs);
     let probedModel = null;
     if (productionSpawn) {
@@ -1074,7 +1079,7 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
             client.request("get_available_models"),
         ]);
         if (!available?.models?.length)
-            throw new Error("Pi has no authenticated available models. Run the official `pi` login flow or configure provider credentials; Larkin will not create a fallback session.");
+            throw new Error("Pi has no authenticated available models. Run the official `pi` login flow; Larkin will not create a fallback session.");
         const effectiveModel = state.model?.provider && state.model.id ? `${state.model.provider}/${state.model.id}` : null;
         if (productionSpawn) {
             if (!effectiveModel || !probedModel || effectiveModel !== probedModel.model
@@ -1088,11 +1093,10 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
                     keepRecentTokens: ownedSettings.compaction?.keepRecentTokens,
                 } });
             const handshake = state.compactionCapabilities;
-            verifyPiCapabilities({ distribution: builtin ? "builtin" : "external", version: reportedVersion,
+            verifyPiCapabilities({ distribution: "external", version: reportedVersion,
                 contextWindow: state.model?.contextWindow, autoCompactionEnabled: state.autoCompactionEnabled,
                 reserveTokens: handshake?.reserveTokens, keepRecentTokens: handshake?.keepRecentTokens,
-                compactRpc: true, events: handshake?.events,
-                trustedProtocol: builtin });
+                compactRpc: true, events: handshake?.events });
         }
         // 严格对账（Owner 决策）：模型必须来自 pi 的权威可用列表，不做后缀猜测——
         // 配置的模型与 pi 可用列表不符即报错，并在错误里列出可用模型。
@@ -1227,10 +1231,9 @@ export function createNativeRuntimeAdapter(id, dependencies = {}) {
                     throw new RuntimePrerequisiteError(readiness);
             }
             if (id === "pi") {
-                const distribution = piChildDistributionFromOverrides(dependencies.env, input.env);
                 return new PiSession(await (dependencies.createPiSession
                     ? dependencies.createPiSession(input)
-                    : createPiRpcBackend(input, { ...dependencies, piCommand: resolvedExecutable }, spawn, productionSpawn)), distribution);
+                    : createPiRpcBackend(input, { ...dependencies, piCommand: resolvedExecutable }, spawn, productionSpawn)));
             }
             if (id === "codex") {
                 const codexInput = dependencies.codexModelOverride?.trim()

package/dist/runtime/runtime-host.cjs

@@ -102,6 +102,107 @@ function persistPreviousSession(agent, previous) {
         // In-memory ref still holds for this process; restart will miss it only if this write failed.
     }
 }
+function authFailureScopeOf(agent) {
+    return {
+        runtime: agent.config.runtime,
+        model: agent.config.model,
+        adapterId: agent.adapter.id,
+    };
+}
+function currentAuthFailure(agent) {
+    if (!agent.authFailureActive)
+        return null;
+    const runtime = agent.adapter.id === "codex" || agent.adapter.id === "claude" || agent.adapter.id === "pi"
+        ? agent.adapter.id : null;
+    if (!runtime)
+        return null;
+    return {
+        kind: agent.authFailureKind === "missing-provider" ? "missing-provider" : "generic",
+        runtime,
+        provider: agent.authFailureProvider,
+    };
+}
+function genericAuthProvider(agent, upstream) {
+    return (0, runtime_readiness_js_1.safeProviderId)(upstream?.provider) ?? (0, runtime_readiness_js_1.configuredProviderId)(agent.config.model);
+}
+function persistAuthFailure(agent) {
+    const store = agent.stateStore;
+    if (!store)
+        return;
+    try {
+        const write = () => {
+            const current = store.readJson("agentState", { sessions: {} });
+            if (Array.isArray(current.records) && !("sessions" in current))
+                return;
+            const { authFailureProvider: _legacy, authFailure: _scoped, ...rest } = current;
+            const failure = currentAuthFailure(agent);
+            if (!failure) {
+                if (!("authFailureProvider" in current) && !("authFailure" in current))
+                    return;
+                store.writeJson("agentState", rest);
+                return;
+            }
+            store.writeJson("agentState", {
+                ...rest,
+                authFailure: failure,
+                ...(failure.kind === "missing-provider" && failure.provider
+                    ? { authFailureProvider: failure.provider } : {}),
+            });
+        };
+        if (store.withInboxTransaction)
+            store.withInboxTransaction(write);
+        else
+            write();
+    }
+    catch {
+        // In-memory flags and the delivery ledger still hold for this process.
+    }
+}
+function loadPersistedAuthFailure(store) {
+    if (!store)
+        return null;
+    try {
+        return (0, runtime_readiness_js_1.parsePersistedAuthFailure)(store.readJson("agentState", {}));
+    }
+    catch {
+        return null;
+    }
+}
+function applyAuthFailure(agent, failure) {
+    agent.authFailureActive = true;
+    agent.authFailureKind = failure.kind;
+    agent.authFailureProvider = failure.provider ?? null;
+    agent.readiness = (0, runtime_readiness_js_1.readinessForPersistedAuthFailure)(failure);
+}
+function clearAuthFailure(agent, persist = true) {
+    agent.authFailureActive = false;
+    agent.authFailureKind = null;
+    agent.authFailureProvider = null;
+    if (persist)
+        persistAuthFailure(agent);
+}
+function restoreAuthFailure(agent) {
+    const persisted = loadPersistedAuthFailure(agent.stateStore);
+    if (!persisted)
+        return;
+    // 只恢复仍绑定当前 candidate 的当前作用域 auth；不从历史 delivery 回灌。
+    if (!(0, runtime_readiness_js_1.authFailureAppliesTo)(authFailureScopeOf(agent), persisted)) {
+        clearAuthFailure(agent);
+        return;
+    }
+    applyAuthFailure(agent, persisted);
+}
+function clearLedgerAuthProviders(agent) {
+    let changed = false;
+    for (const record of agent.records.values()) {
+        if (!record.authProvider)
+            continue;
+        delete record.authProvider;
+        changed = true;
+    }
+    if (changed)
+        persist(agent);
+}
 const REPLAY_FAILURE_CODES = new Set([
     "canonical_inbox_row_missing", "canonical_inbox_malformed", "duplicate_message_id",
     "inbox_state_conflict", "delivery_target_conflict", "structured_target_invalid",
@@ -228,7 +329,6 @@ function createRuntimeHost(options) {
             } : {}),
             LARKIN_CONFIG_DIR: process.env.LARKIN_CONFIG_DIR,
             LARKIN_HOME: process.env.LARKIN_HOME,
-            ...(config.piDistribution ? { LARKIN_PI_DISTRIBUTION: config.piDistribution } : {}),
             LARKIN_STATE_DIR: (0, pi_subagent_ledger_js_1.effectivePiStateDir)(config),
             ...(process.env.HOME ? { HOME: process.env.HOME } : {}),
             ...(process.env.SHELL ? { SHELL: process.env.SHELL } : {}),
@@ -490,6 +590,25 @@ function createRuntimeHost(options) {
                 messageId: record.messageId, status: "consumed" });
         }
     };
+    const projectAuthFailure = (agent, readiness, failure) => {
+        agent.authFailureActive = true;
+        agent.authFailureKind = failure.kind;
+        agent.authFailureProvider = failure.provider;
+        agent.readiness = {
+            ...readiness,
+            ...(agent.readiness?.executable ? { executable: agent.readiness.executable } : {}),
+            ...(agent.readiness?.version ? { version: agent.readiness.version } : {}),
+        };
+        persistAuthFailure(agent);
+        emit({ type: "agent-status", agentId: agent.config.agentId, status: "error",
+            error: `${agent.readiness.reason} ${agent.readiness.nextAction}`, readiness: agent.readiness });
+    };
+    const namedAuthProviderPresent = (agent) => {
+        if (agent.authFailureKind !== "missing-provider" || !agent.authFailureProvider)
+            return true;
+        const failure = currentAuthFailure(agent);
+        return Boolean(failure && (0, runtime_readiness_js_1.authFailureAppliesTo)(authFailureScopeOf(agent), failure));
+    };
     const resultFor = (agent, record, result) => {
         if (result.status === "accepted") {
             if (record.errorCategory !== "context_window") {
@@ -503,6 +622,28 @@ function createRuntimeHost(options) {
                     deliveryId: record.deliveryId, messageId: record.messageId, status: "accepted" });
             return { status: "accepted", deliveryId: record.deliveryId };
         }
+        const missing = result.status === "rejected" && agent.adapter.id === "pi"
+            ? (0, runtime_readiness_js_1.classifyPiMissingCredentialRejection)(result.reason)
+            : null;
+        if (missing) {
+            const readiness = (0, runtime_readiness_js_1.missingProviderCredentialReadiness)(agent.adapter.id, missing.provider);
+            const reason = readiness.reason ?? result.reason;
+            if (record.status !== "error") {
+                record.reason = reason;
+                record.retryable = false;
+                record.errorCategory = "auth";
+                record.authProvider = missing.provider;
+                const finalRecord = setRecord(agent, record, "error");
+                if (finalRecord.status !== "consumed")
+                    emit({ type: "delivery", agentId: agent.config.agentId,
+                        deliveryId: record.deliveryId, messageId: record.messageId, status: "error", reason });
+                projectAuthFailure(agent, readiness, { kind: "missing-provider", provider: missing.provider });
+            }
+            return { status: "error", deliveryId: record.deliveryId, reason: record.reason ?? reason, retryable: false };
+        }
+        if (record.status === "error") {
+            return { status: "error", deliveryId: record.deliveryId, reason: record.reason ?? result.reason, retryable: false };
+        }
         if (record.errorCategory !== "context_window")
             delete record.errorCategory;
         const retryable = result.status === "deferred" || result.retryable;
@@ -1347,7 +1488,7 @@ function createRuntimeHost(options) {
                     agent.compactionMachines.delete(inputId);
             }
             const recoveredAuthentication = agent.authFailureActive && agent.turnInProgress
-                && agent.turnHadAuthenticatedOutput && !agent.turnHadFailure;
+                && agent.turnHadAuthenticatedOutput && !agent.turnHadFailure && namedAuthProviderPresent(agent);
             agent.turnInProgress = false;
             agent.busy = false;
             emit({ type: "activity", agentId: agent.config.agentId, activity: "idle", activityKind: "idle", detailKind: "turn_ended" });
@@ -1369,7 +1510,8 @@ function createRuntimeHost(options) {
             reconcileSubagentLedger(agent);
             telemetry?.runtimeEvent(agent.config.agentId, event);
             if (recoveredAuthentication) {
-                agent.authFailureActive = false;
+                clearAuthFailure(agent);
+                clearLedgerAuthProviders(agent);
                 const prior = agent.readiness;
                 agent.readiness = {
                     runtime: agent.adapter.id,
@@ -1462,23 +1604,30 @@ function createRuntimeHost(options) {
                 record.errorCategory = classifiedCategory;
             else
                 delete record.errorCategory;
-            const finalRecord = setRecord(agent, record, event.retryable ? "pending" : "error");
+            const missing = agent.adapter.id === "pi"
+                ? (0, runtime_readiness_js_1.classifyPiMissingCredentialRejection)(event.upstream?.message)
+                    ?? (0, runtime_readiness_js_1.classifyPiMissingCredentialRejection)(event.message)
+                : null;
+            if (missing) {
+                record.retryable = false;
+                record.errorCategory = "auth";
+                record.authProvider = missing.provider;
+            }
+            const terminal = Boolean(missing) || !event.retryable;
+            const finalRecord = setRecord(agent, record, terminal ? "error" : "pending");
             if (finalRecord.status !== "consumed")
                 emit({ type: "delivery", agentId: agent.config.agentId,
                     deliveryId: record.deliveryId, messageId: record.messageId,
-                    status: event.retryable ? "deferred" : "error", reason: event.message });
-            if (event.errorCategory === "auth" && !event.retryable) {
+                    status: terminal ? "error" : "deferred", reason: event.message });
+            if (missing) {
+                const readiness = (0, runtime_readiness_js_1.missingProviderCredentialReadiness)(agent.adapter.id, missing.provider);
+                projectAuthFailure(agent, readiness, { kind: "missing-provider", provider: missing.provider });
+            }
+            else if (event.errorCategory === "auth" && !event.retryable) {
                 const readiness = (0, runtime_readiness_js_1.providerAuthenticationFailureReadiness)(agent.adapter.id, event.upstream?.provider);
-                agent.authFailureActive = true;
-                agent.readiness = {
-                    ...readiness,
-                    ...(agent.readiness?.executable ? { executable: agent.readiness.executable } : {}),
-                    ...(agent.readiness?.version ? { version: agent.readiness.version } : {}),
-                };
-                emit({ type: "agent-status", agentId: agent.config.agentId, status: "error",
-                    error: `${agent.readiness.reason} ${agent.readiness.nextAction}`, readiness: agent.readiness });
+                projectAuthFailure(agent, readiness, { kind: "generic", provider: genericAuthProvider(agent, event.upstream) });
             }
-            if (event.retryable && !agent.busy && !agent.turnInProgress)
+            if (!terminal && event.retryable && !agent.busy && !agent.turnInProgress)
                 void retryPending(agent);
         }
         else if (event.type === "configuration-error") {
@@ -1748,14 +1897,26 @@ function createRuntimeHost(options) {
                         clearTimeout(previous.backgroundCompletionRetryTimer);
                     if (previous.subagentReconcileTimer)
                         clearInterval(previous.subagentReconcileTimer);
+                    const previousFailure = currentAuthFailure(previous);
+                    const scoped = Boolean(previousFailure
+                        && (0, runtime_readiness_js_1.authFailureAppliesTo)({
+                            runtime: config.runtime,
+                            model: config.model,
+                            adapterId: adapter.id,
+                        }, previousFailure));
                     const candidate = {
                         ...previous, config, adapter, session, launchId: node_crypto_1.default.randomUUID(), busy: false, submitting: false,
                         starting: null, retryAfterSubmit: false, generation: 0, poller: null, retryTimer: null,
                         recreateAttempts: 0, stabilityTimer: null, recreateReason: null, stopped: false,
                         backgroundCompletionRetryTimer: null, subagentReconcileTimer: null,
                         disabledReason: null, configurationRecovery: null,
-                        readiness: previous.authFailureActive ? previous.readiness : readiness,
+                        authFailureActive: scoped && previous.authFailureActive,
+                        authFailureKind: scoped ? previous.authFailureKind : null,
+                        authFailureProvider: scoped ? previous.authFailureProvider : null,
+                        readiness: scoped && previous.authFailureActive ? previous.readiness : readiness,
                     };
+                    if (previous.authFailureActive && !candidate.authFailureActive)
+                        clearAuthFailure(candidate);
                     managed.set(config.agentId, candidate);
                     session.subscribe((event) => observe(candidate, session, event));
                     if (session.sessionId) {
@@ -1850,7 +2011,8 @@ function createRuntimeHost(options) {
                 agent.config.sessionId = null;
                 agent.session = fresh;
                 persistPreviousSession(agent, previousRef);
-                agent.readiness = readiness;
+                if (!agent.authFailureActive)
+                    agent.readiness = readiness;
                 agent.disabledReason = null;
             };
             try {
@@ -1871,7 +2033,13 @@ function createRuntimeHost(options) {
                     ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}),
                     ...(agent.previousSession ? { previousSession: agent.previousSession } : {}) });
             }
-            emit({ type: "agent-status", agentId, status: "active", readiness });
+            emit({
+                type: "agent-status",
+                agentId,
+                status: agent.authFailureActive ? "error" : "active",
+                ...(agent.authFailureActive ? { error: `${agent.readiness?.reason} ${agent.readiness?.nextAction}` } : {}),
+                readiness: agent.authFailureActive ? agent.readiness ?? readiness : readiness,
+            });
             agent.piSessionOwner = probeEnv[pi_subagent_ledger_js_1.PI_SUBAGENT_SESSION_OWNER_ENV];
             await oldSession.close("fresh session reset committed")
                 .catch((error) => log("previous runtime close after fresh reset failed", String(error)));
@@ -2009,7 +2177,8 @@ function createRuntimeHost(options) {
                     agent.config.sessionId = null;
                     agent.session = fresh;
                     persistPreviousSession(agent, previousRef);
-                    agent.readiness = readiness;
+                    if (!agent.authFailureActive)
+                        agent.readiness = readiness;
                     agent.disabledReason = null;
                     for (const record of agent.records.values()) {
                         if (!messageIds.includes(record.messageId))
@@ -2027,7 +2196,13 @@ function createRuntimeHost(options) {
                         ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}),
                         ...(agent.previousSession ? { previousSession: agent.previousSession } : {}) });
                 }
-                emit({ type: "agent-status", agentId, status: "active", readiness });
+                emit({
+                    type: "agent-status",
+                    agentId,
+                    status: agent.authFailureActive ? "error" : "active",
+                    ...(agent.authFailureActive ? { error: `${agent.readiness?.reason} ${agent.readiness?.nextAction}` } : {}),
+                    readiness: agent.authFailureActive ? agent.readiness ?? readiness : readiness,
+                });
                 durableRollback = null;
                 agent.piSessionOwner = probeEnv[pi_subagent_ledger_js_1.PI_SUBAGENT_SESSION_OWNER_ENV];
                 await oldSession.close("context-window recovery committed")
@@ -2117,11 +2292,13 @@ function createRuntimeHost(options) {
                     piProactiveCompactionFailedGeneration: null,
                     previousSession: loadPersistedPreviousSession(config, stateStore), readiness: null,
                     turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false,
+                    authFailureKind: null, authFailureProvider: null,
                     promotedInboxUpdateIds: new Set(),
                     backgroundCompletionQueue: [], backgroundCompletionKeys: new Set(),
                     backgroundCompletionInFlight: null, backgroundCompletionWakeInputId: null,
                     backgroundCompletionRejectStreak: 0, backgroundCompletionRetryTimer: null,
                     subagentLedger: loadSubagentLedger(config), subagentReconcileTimer: null };
+                restoreAuthFailure(agent);
                 const startupConsumed = [];
                 const startupQuarantined = [];
                 for (const record of agent.records.values()) {