@ouro.bot/cli 0.1.0-alpha.363 → 0.1.0-alpha.365

package/README.md

@@ -11,8 +11,8 @@ Ouroboros is a TypeScript harness for daemon-managed agents that live in externa
 - `ouro up` starts the daemon from the installed production version, syncs the launcher, installs workflow helpers, and reconciles stale runtime state.
 - `ouro dev` starts the daemon from a local repo build. It auto-builds from source, disables launchd auto-restart (so the installed daemon doesn't respawn underneath you), persists the repo path in `~/.ouro-cli/dev-config.json` for next time, and force-restarts the daemon. If you run `ouro dev` from inside the repo, it detects the CWD automatically. Run `ouro up` to return to production mode (this also cleans up `dev-config.json`).
 - Agent bundles live outside the repo at `~/AgentBundles/<agent>.ouro/`.
-- Provider credentials live outside the repo at `~/.agentsecrets/providers.json`.
-- Sense-specific secrets live outside the repo at `~/.agentsecrets/<agent>/secrets.json`.
+- Provider credentials live in the owning agent's Bitwarden/Vaultwarden vault. Tool/sense credential vault migration is a follow-up.
+- Vault coordinates and local runtime state live in the agent bundle; raw credentials do not.
 - Machine-scoped test and runtime spillover lives under `~/.agentstate/...`.
 
 Current first-class senses:
@@ -91,10 +91,11 @@ Task docs do not live in this repo anymore. Planning and doing docs live in the
 
 ## Runtime Truths
 
-- `agent.json` is the source of truth for phrase pools, context settings, enabled senses, and the agent's `configPath`. Legacy `humanFacing`/`agentFacing` values are bootstrap inputs, not live machine fallback.
-- `configPath` must point to `~/.agentsecrets/<agent>/secrets.json` for sense-specific secrets.
+- `agent.json` is the source of truth for identity, phrase pools, context settings, enabled senses, and vault coordinates. Legacy `humanFacing`/`agentFacing` values are bootstrap inputs, not live machine fallback.
 - `state/providers.json` is the local source of truth for provider+model selection on this machine. It has two lanes: `outward` for CLI, Teams, and BlueBubbles turns, and `inner` for inner dialogue.
-- `~/.agentsecrets/providers.json` is the machine credential pool. It stores provider credentials only, records which agent contributed them, and is shared by all agents on that machine.
+- Each agent has one credential vault for provider credentials. There is no machine-wide provider credential pool.
+- Vault unlock material is local machine state. Prefer macOS Keychain, Windows DPAPI, or Linux Secret Service; plaintext fallback is allowed only by explicit human choice.
+- Provider credentials are loaded into daemon memory at startup/auth/unlock/refresh and reused. The remote vault is not queried for every model request.
 - The daemon discovers bundles dynamically from `~/AgentBundles`.
 - `ouro status` reports version, last-updated time, discovered agents, senses, and workers.
 - `bundle-meta.json` tracks the runtime version that last touched a bundle.
@@ -114,7 +115,7 @@ ouro auth --agent <name>
 ouro auth --agent <name> --provider <provider>
 ```
 
-`ouro auth` stores credentials only. It does not switch a lane or write provider/model selection.
+`ouro auth` stores credentials in the owning agent's vault. It does not switch a lane or write provider/model selection.
 
 When you want this machine to use a provider/model for a lane, use:
 
@@ -124,6 +125,8 @@ ouro use --agent <name> --lane <outward|inner> --provider <provider> --model <mo
 
 The outward lane handles user-facing senses. The inner lane handles the agent's private thinking. `ouro use` performs the provider/model check before committing the lane, so a broken local choice fails fast with a repair path instead of surprising the next turn.
 
+For the full locked auth/provider contract, including refresh, repair actors, caching, and SerpentGuide hatch bootstrap, see `docs/auth-and-providers.md`.
+
 ## Quickstart
 
 ### Use The Published Runtime
@@ -165,8 +168,12 @@ ouro dev --clone                 # clone repo to ~/Projects/ouroboros, build, st
 ouro status
 ouro logs
 ouro stop
+ouro vault unlock --agent <name>
+ouro vault status --agent <name>
 ouro auth --agent <name>
 ouro auth --agent <name> --provider <provider>
+ouro auth verify --agent <name> [--provider <provider>]
+ouro provider refresh --agent <name>
 ouro use --agent <name> --lane <outward|inner> --provider <provider> --model <model>
 ouro hatch
 ouro clone <remote> [--agent <name>]   # clone an existing agent from a git remote (see docs/cross-machine-setup.md)
@@ -186,7 +193,7 @@ ouro hook <event> --agent <name>          # fire a lifecycle hook (SessionStart,
 
 ## Setting Up On Another Machine
 
-To clone an existing agent onto a new machine (macOS, Linux, or Windows via WSL2), see **[docs/cross-machine-setup.md](docs/cross-machine-setup.md)**. The short version: `npx ouro.bot`, pick "clone", enter the bundle's git remote URL, run `ouro auth run`, then `ouro up`.
+To clone an existing agent onto a new machine (macOS, Linux, or Windows via WSL2), see **[docs/cross-machine-setup.md](docs/cross-machine-setup.md)**. The short version: `npx ouro.bot`, pick "clone", enter the bundle's git remote URL, and follow the guided prompts (auth, daemon start, dev tool setup are all offered inline).
 
 ## The Agent's Inner Life
 
@@ -233,6 +240,8 @@ See `skills/configure-dev-tools.md` for the full tool inventory and troubleshoot
   Current daemon, bundle, sense, and update model.
 - `docs/testing-guide.md`
   Operator smoke flow for bootstrap, daemon, hatch, chat, and messaging.
+- `docs/auth-and-providers.md`
+  Locked credential, provider selection, refresh, repair, and hatch bootstrap contract.
 
 ## A Note To Future Maintainers
 

package/changelog.json

@@ -1,6 +1,23 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.365",
+      "changes": [
+        "Provider credentials now live in the owning agent's Bitwarden/Vaultwarden vault instead of a machine-wide provider pool; runtime uses daemon-memory credential snapshots and machine-local `state/providers.json` provider/model lanes.",
+        "`ouro auth`, `ouro use`, provider status/check/refresh, startup health checks, interactive repair, and failover guidance now share the same agent-vault/local-lane contract with clearer human repair paths.",
+        "SerpentGuide bootstrap no longer persists its own provider credentials; hatch flows keep bootstrap credentials in memory and store them only in the hatchling agent vault.",
+        "Vault unlock bootstrap supports macOS Keychain, Windows DPAPI, Linux Secret Service, and explicit plaintext fallback, with docs aligned across AGENTS, README, OAuth setup, testing guide, and auth/provider reference."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.364",
+      "changes": [
+        "Cross-machine polish: bash PATH writes to .bashrc on Linux/WSL instead of .bash_profile (which non-login shells skip on Debian/Ubuntu). Shell hint message matches.",
+        "Agent prompt: never guess about harness behavior — consult docs first, investigate in code, fix stale docs via PR.",
+        "Agent prompt: harness docs pointer distinguishes dev mode (local read) vs production (fetch from GitHub)."
+      ]
+    },
     {
       "version": "0.1.0-alpha.363",
       "changes": [

package/dist/heart/auth/auth-flow.js

@@ -35,8 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readAgentConfigForAgent = readAgentConfigForAgent;
 exports.writeAgentProviderSelection = writeAgentProviderSelection;
-exports.loadAgentSecrets = loadAgentSecrets;
-exports.writeProviderCredentials = writeProviderCredentials;
+exports.storeProviderCredentials = storeProviderCredentials;
 exports.writeAgentModel = writeAgentModel;
 exports.collectRuntimeAuthCredentials = collectRuntimeAuthCredentials;
 exports.resolveHatchCredentials = resolveHatchCredentials;
@@ -49,71 +48,13 @@ const runtime_1 = require("../../nerves/runtime");
 const identity_1 = require("../identity");
 const migrate_config_1 = require("../migrate-config");
 const provider_models_1 = require("../provider-models");
+const provider_credentials_1 = require("../provider-credentials");
 const ANTHROPIC_SETUP_TOKEN_PREFIX = "sk-ant-oat01-";
 const ANTHROPIC_SETUP_TOKEN_MIN_LENGTH = 80;
-const DEFAULT_SECRETS_TEMPLATE = {
-    providers: {
-        azure: {
-            apiKey: "",
-            endpoint: "",
-            deployment: "",
-            apiVersion: "2025-04-01-preview",
-        },
-        minimax: {
-            apiKey: "",
-        },
-        anthropic: {
-            setupToken: "",
-            refreshToken: "",
-            expiresAt: 0,
-        },
-        "openai-codex": {
-            oauthAccessToken: "",
-        },
-        "github-copilot": {
-            githubToken: "",
-            baseUrl: "",
-        },
-    },
-    teams: {
-        clientId: "",
-        clientSecret: "",
-        tenantId: "",
-    },
-    oauth: {
-        graphConnectionName: "graph",
-        adoConnectionName: "ado",
-        githubConnectionName: "",
-    },
-    teamsChannel: {
-        skipConfirmation: true,
-        port: 3978,
-    },
-    vault: {
-        masterPassword: "",
-    },
-    integrations: {
-        perplexityApiKey: "",
-        openaiEmbeddingsApiKey: "",
-    },
-};
-function deepMerge(defaults, partial) {
-    const result = { ...defaults };
-    for (const key of Object.keys(partial)) {
-        const left = result[key];
-        const right = partial[key];
-        if (right !== null &&
-            typeof right === "object" &&
-            !Array.isArray(right) &&
-            left !== null &&
-            typeof left === "object" &&
-            !Array.isArray(left)) {
-            result[key] = deepMerge(left, right);
-            continue;
-        }
-        result[key] = right;
+function assertPersistentProviderCredentialsAllowed(agentName) {
+    if (agentName === "SerpentGuide") {
+        throw new Error("SerpentGuide uses provider credentials in memory during hatch bootstrap; persistent SerpentGuide auth is not supported.");
     }
-    return result;
 }
 function readJsonRecord(filePath, label) {
     try {
@@ -196,38 +137,18 @@ function writeAgentProviderSelection(agentName, facing, provider, bundlesRoot =
     });
     return configPath;
 }
-function resolveAgentSecretsPath(agentName, deps = {}) {
-    if (deps.secretsRoot)
-        return path.join(deps.secretsRoot, agentName, "secrets.json");
-    const homeDir = deps.homeDir ?? os.homedir();
-    return (0, identity_1.getAgentSecretsPath)(agentName).replace(os.homedir(), homeDir);
-}
-function loadAgentSecrets(agentName, deps = {}) {
-    const secretsPath = resolveAgentSecretsPath(agentName, deps);
-    const secretsDir = path.dirname(secretsPath);
-    fs.mkdirSync(secretsDir, { recursive: true });
-    let onDisk = {};
-    try {
-        onDisk = readJsonRecord(secretsPath, "secrets config");
-    }
-    catch (error) {
-        const message = error.message;
-        if (!message.includes("ENOENT"))
-            throw error;
-    }
-    return {
-        secretsPath,
-        secrets: deepMerge(DEFAULT_SECRETS_TEMPLATE, onDisk),
-    };
-}
-function writeSecrets(secretsPath, secrets) {
-    fs.writeFileSync(secretsPath, `${JSON.stringify(secrets, null, 2)}\n`, "utf8");
-}
-function writeProviderCredentials(agentName, provider, credentials, deps = {}) {
-    const { secretsPath, secrets } = loadAgentSecrets(agentName, deps);
-    applyCredentials(secrets, provider, credentials);
-    writeSecrets(secretsPath, secrets);
-    return { secretsPath, secrets };
+async function storeProviderCredentials(agentName, provider, credentials, deps = {}) {
+    assertPersistentProviderCredentialsAllowed(agentName);
+    const split = (0, provider_credentials_1.splitProviderCredentialFields)(provider, credentials);
+    await (0, provider_credentials_1.upsertProviderCredential)({
+        agentName,
+        provider,
+        credentials: split.credentials,
+        config: split.config,
+        provenance: { source: "auth-flow" },
+        now: deps.now,
+    });
+    return { credentialPath: (0, provider_credentials_1.providerCredentialItemName)(provider) };
 }
 function writeAgentModel(agentName, facing, modelName, deps = {}) {
     const { configPath, config } = readAgentConfigForAgent(agentName, deps.bundlesRoot);
@@ -427,36 +348,30 @@ async function resolveHatchCredentials(input) {
     }
     return credentials;
 }
-function applyCredentials(secrets, provider, credentials) {
-    const target = secrets.providers[provider];
-    // Copy all non-empty credential fields to the provider's secrets block
-    for (const [key, value] of Object.entries(credentials)) {
-        /* v8 ignore next -- guard: skip null/empty fields from partial credential objects @preserve */
-        if (value != null && value !== "") {
-            target[key] = typeof value === "string" ? value.trim() : value;
-        }
-    }
-}
 async function runRuntimeAuthFlow(input, deps = {}) {
+    assertPersistentProviderCredentialsAllowed(input.agentName);
     (0, runtime_1.emitNervesEvent)({
         component: "daemon",
         event: "daemon.auth_flow_start",
         message: "starting runtime auth flow",
         meta: { agentName: input.agentName, provider: input.provider },
     });
-    const homeDir = deps.homeDir ?? os.homedir();
+    const vault = await (0, provider_credentials_1.refreshProviderCredentialPool)(input.agentName);
+    if (!vault.ok && vault.reason === "unavailable") {
+        throw new Error(`${vault.error}\nRun \`ouro vault unlock --agent ${input.agentName}\`, then retry auth.`);
+    }
     const credentials = await collectRuntimeAuthCredentials(input, deps);
-    const { secretsPath } = writeProviderCredentials(input.agentName, input.provider, credentials, { homeDir });
+    const { credentialPath } = await storeProviderCredentials(input.agentName, input.provider, credentials);
     (0, runtime_1.emitNervesEvent)({
         component: "daemon",
         event: "daemon.auth_flow_end",
         message: "completed runtime auth flow",
-        meta: { agentName: input.agentName, provider: input.provider, secretsPath },
+        meta: { agentName: input.agentName, provider: input.provider, credentialPath },
     });
     return {
         agentName: input.agentName,
         provider: input.provider,
-        secretsPath,
+        credentialPath,
         message: `authenticated ${input.agentName} with ${input.provider}`,
         credentials,
     };

package/dist/heart/config.js

@@ -41,7 +41,6 @@ exports.getMinimaxConfig = getMinimaxConfig;
 exports.getAnthropicConfig = getAnthropicConfig;
 exports.getOpenAICodexConfig = getOpenAICodexConfig;
 exports.getGithubCopilotConfig = getGithubCopilotConfig;
-exports.getProviderConfig = getProviderConfig;
 exports.getTeamsConfig = getTeamsConfig;
 exports.getTeamsSecondaryConfig = getTeamsSecondaryConfig;
 exports.getContextConfig = getContextConfig;
@@ -62,30 +61,9 @@ exports.logPath = logPath;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const identity_1 = require("./identity");
+const provider_credentials_1 = require("./provider-credentials");
 const runtime_1 = require("../nerves/runtime");
-const DEFAULT_SECRETS_TEMPLATE = {
-    providers: {
-        azure: {
-            apiKey: "",
-            endpoint: "",
-            deployment: "",
-            apiVersion: "2025-04-01-preview",
-            managedIdentityClientId: "",
-        },
-        minimax: {
-            apiKey: "",
-        },
-        anthropic: {
-            setupToken: "",
-        },
-        "openai-codex": {
-            oauthAccessToken: "",
-        },
-        "github-copilot": {
-            githubToken: "",
-            baseUrl: "",
-        },
-    },
+const DEFAULT_LOCAL_RUNTIME_CONFIG = {
     teams: {
         clientId: "",
         clientSecret: "",
@@ -127,26 +105,20 @@ const DEFAULT_SECRETS_TEMPLATE = {
 };
 function defaultRuntimeConfig() {
     return {
-        providers: {
-            azure: { ...DEFAULT_SECRETS_TEMPLATE.providers.azure },
-            minimax: { ...DEFAULT_SECRETS_TEMPLATE.providers.minimax },
-            anthropic: { ...DEFAULT_SECRETS_TEMPLATE.providers.anthropic },
-            "openai-codex": { ...DEFAULT_SECRETS_TEMPLATE.providers["openai-codex"] },
-            "github-copilot": { ...DEFAULT_SECRETS_TEMPLATE.providers["github-copilot"] },
-        },
-        teams: { ...DEFAULT_SECRETS_TEMPLATE.teams },
-        teamsSecondary: { ...DEFAULT_SECRETS_TEMPLATE.teamsSecondary },
-        oauth: { ...DEFAULT_SECRETS_TEMPLATE.oauth },
+        teams: { ...DEFAULT_LOCAL_RUNTIME_CONFIG.teams },
+        teamsSecondary: { ...DEFAULT_LOCAL_RUNTIME_CONFIG.teamsSecondary },
+        oauth: { ...DEFAULT_LOCAL_RUNTIME_CONFIG.oauth },
         context: { ...identity_1.DEFAULT_AGENT_CONTEXT },
-        teamsChannel: { ...DEFAULT_SECRETS_TEMPLATE.teamsChannel },
-        bluebubbles: { ...DEFAULT_SECRETS_TEMPLATE.bluebubbles },
-        bluebubblesChannel: { ...DEFAULT_SECRETS_TEMPLATE.bluebubblesChannel },
-        vault: { ...DEFAULT_SECRETS_TEMPLATE.vault },
-        integrations: { ...DEFAULT_SECRETS_TEMPLATE.integrations },
+        teamsChannel: { ...DEFAULT_LOCAL_RUNTIME_CONFIG.teamsChannel },
+        bluebubbles: { ...DEFAULT_LOCAL_RUNTIME_CONFIG.bluebubbles },
+        bluebubblesChannel: { ...DEFAULT_LOCAL_RUNTIME_CONFIG.bluebubblesChannel },
+        vault: { ...DEFAULT_LOCAL_RUNTIME_CONFIG.vault },
+        integrations: { ...DEFAULT_LOCAL_RUNTIME_CONFIG.integrations },
     };
 }
 let _runtimeConfigOverride = null;
 let _testContextOverride = null;
+let _providerConfigOverride = null;
 function resolveConfigPath() {
     return (0, identity_1.getAgentSecretsPath)();
 }
@@ -185,7 +157,7 @@ function loadConfig() {
             : undefined;
         if (errorCode === "ENOENT") {
             try {
-                fs.writeFileSync(configPath, JSON.stringify(DEFAULT_SECRETS_TEMPLATE, null, 2) + "\n", "utf-8");
+                fs.writeFileSync(configPath, JSON.stringify(DEFAULT_LOCAL_RUNTIME_CONFIG, null, 2) + "\n", "utf-8");
             }
             catch (writeError) {
                 (0, runtime_1.emitNervesEvent)({
@@ -214,6 +186,19 @@ function loadConfig() {
         // ENOENT or parse error -- use defaults
     }
     const sanitizedFileData = { ...fileData };
+    if ("providers" in sanitizedFileData) {
+        delete sanitizedFileData.providers;
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            event: "config_identity.error",
+            component: "config/identity",
+            message: "ignored legacy providers block in secrets config",
+            meta: {
+                phase: "loadConfig",
+                path: configPath,
+            },
+        });
+    }
     if ("context" in sanitizedFileData) {
         delete sanitizedFileData.context;
         (0, runtime_1.emitNervesEvent)({
@@ -246,38 +231,67 @@ function loadConfig() {
 function resetConfigCache() {
     _runtimeConfigOverride = null;
     _testContextOverride = null;
+    _providerConfigOverride = null;
+    (0, provider_credentials_1.resetProviderCredentialCache)();
+}
+function seedProviderCredentialCache(providers) {
+    if (!providers)
+        return;
+    _providerConfigOverride = deepMerge((_providerConfigOverride ?? {}), providers);
+    const records = Object.entries(_providerConfigOverride).map(([provider, rawConfig]) => {
+        const split = (0, provider_credentials_1.splitProviderCredentialFields)(provider, rawConfig);
+        return (0, provider_credentials_1.createProviderCredentialRecord)({
+            provider: provider,
+            credentials: split.credentials,
+            config: split.config,
+            provenance: { source: "manual" },
+            now: new Date(0),
+        });
+    });
+    (0, provider_credentials_1.cacheProviderCredentialRecords)((0, identity_1.getAgentName)(), records, new Date(0));
 }
 function patchRuntimeConfig(partial) {
+    const { providers, ...runtimePartial } = partial;
+    seedProviderCredentialCache(providers);
     const contextPatch = partial.context;
     if (contextPatch) {
         const base = _testContextOverride ?? identity_1.DEFAULT_AGENT_CONTEXT;
         _testContextOverride = deepMerge(base, contextPatch);
     }
-    _runtimeConfigOverride = deepMerge((_runtimeConfigOverride ?? {}), partial);
+    _runtimeConfigOverride = deepMerge((_runtimeConfigOverride ?? {}), runtimePartial);
+}
+function readProviderConfig(provider) {
+    const cached = (0, provider_credentials_1.readCachedProviderCredentialRecord)((0, identity_1.getAgentName)(), provider);
+    return cached.ok ? { ...cached.record.config, ...cached.record.credentials } : {};
 }
 function getAzureConfig() {
-    const config = loadConfig();
-    return { ...config.providers.azure };
+    const raw = readProviderConfig("azure");
+    return {
+        apiKey: typeof raw.apiKey === "string" ? raw.apiKey : "",
+        endpoint: typeof raw.endpoint === "string" ? raw.endpoint : "",
+        deployment: typeof raw.deployment === "string" ? raw.deployment : "",
+        apiVersion: typeof raw.apiVersion === "string" ? raw.apiVersion : "2025-04-01-preview",
+        managedIdentityClientId: typeof raw.managedIdentityClientId === "string" ? raw.managedIdentityClientId : "",
+    };
 }
 function getMinimaxConfig() {
-    const config = loadConfig();
-    return { ...config.providers.minimax };
+    const raw = readProviderConfig("minimax");
+    return { apiKey: typeof raw.apiKey === "string" ? raw.apiKey : "" };
 }
 function getAnthropicConfig() {
-    const config = loadConfig();
-    return { ...config.providers.anthropic };
+    const raw = readProviderConfig("anthropic");
+    return { setupToken: typeof raw.setupToken === "string" ? raw.setupToken : "" };
 }
 function getOpenAICodexConfig() {
-    const config = loadConfig();
-    return { ...config.providers["openai-codex"] };
+    const raw = readProviderConfig("openai-codex");
+    return { oauthAccessToken: typeof raw.oauthAccessToken === "string" ? raw.oauthAccessToken : "" };
 }
 function getGithubCopilotConfig() {
-    const config = loadConfig();
-    return { ...config.providers["github-copilot"] };
-}
-function getProviderConfig(provider) {
-    const config = loadConfig();
-    return { ...config.providers[provider] };
+    const raw = readProviderConfig("github-copilot");
+    return {
+        githubToken: typeof raw.githubToken === "string" ? raw.githubToken : "",
+        baseUrl: typeof raw.baseUrl === "string" ? raw.baseUrl : "",
+    };
 }
 function getTeamsConfig() {
     const config = loadConfig();

package/dist/heart/core.js

@@ -32,43 +32,80 @@ const tool_loop_1 = require("./tool-loop");
 const packets_1 = require("../arc/packets");
 const tool_friction_1 = require("./tool-friction");
 const provider_models_1 = require("./provider-models");
+const provider_credentials_1 = require("./provider-credentials");
+const provider_state_1 = require("./provider-state");
 const provider_attempt_1 = require("./provider-attempt");
 const _providerRuntimes = {
     human: null,
     agent: null,
 };
-function getProviderRuntimeFingerprint(facing) {
+function providerLaneForFacing(facing) {
+    return facing === "human" ? "outward" : "inner";
+}
+function resolveRuntimeProviderBinding(facing) {
+    const agentName = (0, identity_2.getAgentName)();
+    const lane = providerLaneForFacing(facing);
+    const stateResult = (0, provider_state_1.readProviderState)((0, identity_2.getAgentRoot)(agentName));
+    if (stateResult.ok) {
+        const binding = stateResult.state.lanes[lane];
+        return { lane, provider: binding.provider, model: binding.model };
+    }
+    if (stateResult.reason === "invalid") {
+        throw new Error(`provider state for ${agentName} is invalid at ${stateResult.statePath}: ${stateResult.error}`);
+    }
+    // First-run and SerpentGuide bootstrap path. Daemon startup normally
+    // bootstraps state/providers.json from agent.json before model calls.
     const config = (0, identity_1.loadAgentConfig)();
     const facingConfig = facing === "human" ? config.humanFacing : config.agentFacing;
-    const provider = facingConfig.provider;
-    const model = facingConfig.model;
-    const providerConfig = (0, config_1.getProviderConfig)(provider);
-    return JSON.stringify({ provider, model, ...providerConfig });
+    return { lane, provider: facingConfig.provider, model: facingConfig.model };
 }
-function createProviderRegistry() {
-    const factories = {
-        azure: azure_1.createAzureProviderRuntime,
-        anthropic: anthropic_1.createAnthropicProviderRuntime,
-        minimax: minimax_1.createMinimaxProviderRuntime,
-        "openai-codex": openai_codex_1.createOpenAICodexProviderRuntime,
-        "github-copilot": github_copilot_1.createGithubCopilotProviderRuntime,
+async function getProviderRuntimeFingerprint(facing) {
+    const agentName = (0, identity_2.getAgentName)();
+    const binding = resolveRuntimeProviderBinding(facing);
+    const credential = await (0, provider_credentials_1.readProviderCredentialRecord)(agentName, binding.provider);
+    if (!credential.ok) {
+        throw new Error([
+            `${binding.lane} provider ${binding.provider} (${binding.model}) has no credentials for ${agentName}.`,
+            credential.error,
+            `Run \`ouro auth --agent ${agentName} --provider ${binding.provider}\`.`,
+        ].join("\n"));
+    }
+    return {
+        binding,
+        fingerprint: JSON.stringify({
+            lane: binding.lane,
+            provider: binding.provider,
+            model: binding.model,
+            credentialRevision: credential.record.revision,
+        }),
+        credential: credential.record,
     };
+}
+function createProviderRegistry() {
     return {
-        resolve(provider, model) {
-            const resolvedProvider = provider ?? (0, identity_1.loadAgentConfig)().humanFacing.provider;
-            const resolvedModel = model ?? (0, identity_1.loadAgentConfig)().humanFacing.model;
-            return factories[resolvedProvider](resolvedModel);
+        resolve(provider, model, credential) {
+            const providerConfig = { ...credential.config, ...credential.credentials };
+            switch (provider) {
+                case "azure":
+                    return (0, azure_1.createAzureProviderRuntime)(model, providerConfig);
+                case "anthropic":
+                    return (0, anthropic_1.createAnthropicProviderRuntime)(model, providerConfig);
+                case "minimax":
+                    return (0, minimax_1.createMinimaxProviderRuntime)(model, providerConfig);
+                case "openai-codex":
+                    return (0, openai_codex_1.createOpenAICodexProviderRuntime)(model, providerConfig);
+                case "github-copilot":
+                    return (0, github_copilot_1.createGithubCopilotProviderRuntime)(model, providerConfig);
+            }
         },
     };
 }
-function getProviderRuntime(facing = "human") {
+async function getProviderRuntime(facing = "human") {
     try {
-        const fingerprint = getProviderRuntimeFingerprint(facing);
+        const { binding, fingerprint, credential } = await getProviderRuntimeFingerprint(facing);
         const cached = _providerRuntimes[facing];
         if (!cached || cached.fingerprint !== fingerprint) {
-            const config = (0, identity_1.loadAgentConfig)();
-            const facingConfig = facing === "human" ? config.humanFacing : config.agentFacing;
-            const runtime = createProviderRegistry().resolve(facingConfig.provider, facingConfig.model);
+            const runtime = createProviderRegistry().resolve(binding.provider, binding.model, credential);
             _providerRuntimes[facing] = runtime ? { fingerprint, runtime } : null;
         }
     }
@@ -109,14 +146,14 @@ function resetProviderRuntime() {
     _providerRuntimes.agent = null;
 }
 function getModel(facing = "human") {
-    return getProviderRuntime(facing).model;
+    return resolveRuntimeProviderBinding(facing).model;
 }
 function getProvider(facing = "human") {
-    return getProviderRuntime(facing).id;
+    return resolveRuntimeProviderBinding(facing).provider;
 }
 function createSummarize(facing = "human") {
     return async (transcript, instruction) => {
-        const runtime = getProviderRuntime(facing);
+        const runtime = await getProviderRuntime(facing);
         const client = runtime.client;
         const response = await client.chat.completions.create({
             model: runtime.model,
@@ -130,14 +167,12 @@ function createSummarize(facing = "human") {
     };
 }
 function getProviderDisplayLabel(facing = "human") {
-    const config = (0, identity_1.loadAgentConfig)();
-    const facingConfig = facing === "human" ? config.humanFacing : config.agentFacing;
-    const provider = facingConfig.provider;
-    const model = facingConfig.model || "unknown";
+    const binding = resolveRuntimeProviderBinding(facing);
+    const provider = binding.provider;
+    const model = binding.model || "unknown";
     const providerLabelBuilders = {
         azure: () => {
-            const azureCfg = (0, config_1.getAzureConfig)();
-            return `azure openai (${azureCfg.deployment || "default"}, model: ${model})`;
+            return `azure openai (model: ${model})`;
         },
         anthropic: () => `anthropic (${model})`,
         minimax: () => `minimax (${model})`,
@@ -426,7 +461,7 @@ function buildAuthFailureGuidance(provider, model, agentName, detail) {
 }
 async function runAgent(messages, callbacks, channel, signal, options) {
     const facing = (0, channel_1.channelToFacing)(channel);
-    const providerRuntime = getProviderRuntime(facing);
+    let providerRuntime = await getProviderRuntime(facing);
     const provider = providerRuntime.id;
     const toolChoiceRequired = options?.toolChoiceRequired ?? true;
     const traceId = options?.traceId;
@@ -485,7 +520,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         await (0, kept_notes_1.injectKeptNotes)(messages, {
             channel,
             friend: currentContext?.friend,
-            judge: async (input) => (0, kept_notes_1.createKeptNotesJudge)(getProviderRuntime("agent"), signal)(input),
+            judge: async (input) => (0, kept_notes_1.createKeptNotesJudge)(await getProviderRuntime("agent"), signal)(input),
             signal,
             traceId,
         });
@@ -648,10 +683,25 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 model: providerRuntime.model,
                 run: callProviderTurnWithOverflowRecovery,
                 classifyError: (error) => providerRuntime.classifyError(error),
-                onRetry: (record, maxAttempts) => {
+                onRetry: async (record, maxAttempts) => {
                     const delayMs = record.delayMs;
                     const seconds = delayMs / 1000;
                     const cause = RETRY_LABELS[record.classification];
+                    try {
+                        await (0, provider_credentials_1.refreshProviderCredentialPool)((0, identity_2.getAgentName)(), { preserveCachedOnFailure: true });
+                        _providerRuntimes[facing] = null;
+                        providerRuntime = await getProviderRuntime(facing);
+                        providerRuntime.resetTurnState(messages);
+                    }
+                    catch (refreshError) {
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "warn",
+                            component: "engine",
+                            event: "engine.provider_retry_refresh_failed",
+                            message: "provider credential refresh failed during retry",
+                            meta: { provider: record.provider, model: record.model, reason: refreshError instanceof Error ? refreshError.message : String(refreshError) },
+                        });
+                    }
                     callbacks.onError(new Error(`${cause}, retrying in ${seconds}s (${record.attempt}/${maxAttempts})...`), "transient");
                 },
                 sleep: async (delayMs) => {