@ouro.bot/cli 0.1.0-alpha.394 → 0.1.0-alpha.396

package/changelog.json

@@ -1,6 +1,27 @@
 {
   "_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.396",
+      "changes": [
+        "Added `ouro repair [--agent <agent>]`, a deterministic vault/provider readiness guide that uses typed repair issues and clear human choices instead of asking for AI diagnosis on known failures.",
+        "Provider health checks now attach shared typed repair metadata for locked vaults, missing provider credentials, and failed live provider/model pings, keeping CLI repair, `ouro up`, and agent-facing guidance aligned.",
+        "`ouro up` now always runs the live provider-check phase after startup, not only when the daemon was already running, so broken selected providers are surfaced during startup instead of later through confusing agent crashes.",
+        "`ouro vault create --agent <agent>` now defaults to the stable agent vault email when no vault locator exists, while still requiring a non-echoing human-provided unlock secret.",
+        "Cross-machine and auth/provider docs now include `ouro repair --agent <agent>` in the continuation path for existing bundles and old auth-style agents.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the typed readiness repair release."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.395",
+      "changes": [
+        "`ouro vault replace` and `ouro vault recover` now default to the stable agent vault email, `<agent>@ouro.bot`, instead of timestamped `+replaced` or `+recovered` addresses.",
+        "Vault repair now treats previously generated repair emails as stale defaults and repairs back to the stable agent email unless the human explicitly supplies `--email <email>`.",
+        "Existing-account repair guidance now tells operators to unlock the stable vault when possible and use `--email` only when intentionally moving an agent to a different vault account.",
+        "Auth/provider docs and CLI help now describe stable vault identity repair for old auth-style agents without implying that Ouro can recover a forgotten unlock secret.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the stable vault identity repair release."
+      ]
+    },
     {
       "version": "0.1.0-alpha.394",
       "changes": [

package/dist/heart/daemon/agent-config-check.js

@@ -45,6 +45,7 @@ const machine_identity_1 = require("../machine-identity");
 const provider_state_1 = require("../provider-state");
 const provider_credentials_1 = require("../provider-credentials");
 const vault_unlock_1 = require("../../repertoire/vault-unlock");
+const readiness_repair_1 = require("./readiness-repair");
 function isAgentProvider(value) {
     return Object.prototype.hasOwnProperty.call(identity_1.PROVIDER_CREDENTIALS, value);
 }
@@ -233,6 +234,13 @@ function missingCredentialResult(agentName, lane, provider, model, credentialPat
         ok: false,
         error: `${lane} provider ${provider} model ${model} has no credentials in ${agentName}'s vault at ${credentialPath}`,
         fix: `Run 'ouro auth --agent ${agentName} --provider ${provider}' to authenticate this machine, or run 'ouro use --agent ${agentName} --lane ${lane} --provider <provider> --model <model>' to choose a working provider/model.`,
+        issue: (0, readiness_repair_1.providerCredentialMissingIssue)({
+            agentName,
+            lane,
+            provider,
+            model,
+            credentialPath,
+        }),
     };
 }
 function invalidPoolResult(agentName, lane, provider, model, pool) {
@@ -241,6 +249,7 @@ function invalidPoolResult(agentName, lane, provider, model, pool) {
             ok: false,
             error: `${lane} provider ${provider} model ${model} cannot read provider credentials because ${agentName}'s credential vault is locked on this machine.`,
             fix: vaultUnlockOrRecoverFix(agentName),
+            issue: (0, readiness_repair_1.vaultLockedIssue)(agentName),
         };
     }
     if (pool.reason === "invalid") {
@@ -268,6 +277,13 @@ function failedPingResult(agentName, lane, provider, model, result) {
         ok: false,
         error: `${lane} provider ${provider} model ${model} failed live check: ${result.message}`,
         fix: `Run 'ouro auth --agent ${agentName} --provider ${provider}' to refresh credentials, or run 'ouro use --agent ${agentName} --lane ${lane} --provider <provider> --model <model>' to switch this lane.`,
+        issue: (0, readiness_repair_1.providerLiveCheckFailedIssue)({
+            agentName,
+            lane,
+            provider,
+            model,
+            message: result.message,
+        }),
     };
 }
 function credentialRecordForLane(pool, provider) {

package/dist/heart/daemon/agentic-repair.js

@@ -12,6 +12,7 @@ exports.runAgenticRepair = runAgenticRepair;
 const runtime_1 = require("../../nerves/runtime");
 const interactive_repair_1 = require("./interactive-repair");
 const provider_ping_1 = require("../provider-ping");
+const readiness_repair_1 = require("./readiness-repair");
 function buildSystemPrompt(degraded) {
     const agentList = degraded
         .map((d) => `- ${d.agent}: error="${d.errorReason}", hint="${d.fixHint}"`)
@@ -114,11 +115,18 @@ async function runAgenticRepair(degraded, deps) {
         return { repairsAttempted: false, usedAgentic: false };
     }
     const hasLocalRepair = degraded.some(interactive_repair_1.hasRunnableInteractiveRepair);
+    const hasKnownTypedRepair = degraded.some((entry) => (0, readiness_repair_1.isKnownReadinessIssue)(entry.issue));
     if (hasLocalRepair) {
         const interactiveResult = await runDeterministicRepair(degraded, deps);
         if (interactiveResult.repairsAttempted) {
             return { repairsAttempted: true, usedAgentic: false };
         }
+        if (hasKnownTypedRepair) {
+            return { repairsAttempted: false, usedAgentic: false };
+        }
+    }
+    else if (hasKnownTypedRepair) {
+        return { repairsAttempted: false, usedAgentic: false };
     }
     // Try to discover a working provider for agentic diagnosis
     let discoveredProvider = null;

package/dist/heart/daemon/cli-exec.js

@@ -85,10 +85,12 @@ const doctor_1 = require("./doctor");
 const cli_render_doctor_1 = require("./cli-render-doctor");
 const interactive_repair_1 = require("./interactive-repair");
 const agentic_repair_1 = require("./agentic-repair");
+const readiness_repair_1 = require("./readiness-repair");
 const startup_tui_1 = require("./startup-tui");
 const stale_bundle_prune_1 = require("./stale-bundle-prune");
 const up_progress_1 = require("./up-progress");
 const provider_ping_1 = require("../provider-ping");
+const agent_discovery_1 = require("./agent-discovery");
 // ── ensureDaemonRunning ──
 const DEFAULT_DAEMON_STARTUP_TIMEOUT_MS = 10_000;
 const DEFAULT_DAEMON_STARTUP_POLL_INTERVAL_MS = 500;
@@ -96,23 +98,23 @@ const DEFAULT_DAEMON_STARTUP_STABILITY_WINDOW_MS = 1_500;
 const DEFAULT_DAEMON_STARTUP_RETRY_LIMIT = 1;
 const DEFAULT_DAEMON_STARTUP_LOG_LINES = 10;
 async function checkAgentProviders(deps, agentsOverride) {
-    const agents = agentsOverride ?? await Promise.resolve(deps.listDiscoveredAgents ? deps.listDiscoveredAgents() : (0, cli_defaults_1.defaultListDiscoveredAgents)());
+    const agents = agentsOverride ?? await listCliAgents(deps);
     const bundlesRoot = deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
     const degraded = [];
     for (const agent of [...new Set(agents)]) {
         try {
-            const result = await (0, agent_config_check_1.checkAgentConfigWithProviderHealth)(agent, bundlesRoot);
+            const result = await checkAgentProviderHealth(agent, bundlesRoot, deps);
             if (result.ok)
                 continue;
             const errorReason = result.error ?? "agent provider health check failed";
             const fixHint = result.fix ?? "";
-            degraded.push({ agent, errorReason, fixHint });
+            degraded.push({ agent, errorReason, fixHint, ...(result.issue ? { issue: result.issue } : {}) });
             (0, runtime_1.emitNervesEvent)({
                 level: "error",
                 component: "daemon",
                 event: "daemon.agent_config_invalid",
                 message: errorReason,
-                meta: { agent, fix: fixHint, source: "already-running-provider-check" },
+                meta: { agent, fixProvided: fixHint.length > 0, source: "already-running-provider-check" },
             });
         }
         catch (error) {
@@ -127,12 +129,27 @@ async function checkAgentProviders(deps, agentsOverride) {
                 component: "daemon",
                 event: "daemon.agent_config_invalid",
                 message: errorReason,
-                meta: { agent, fix: "ouro doctor", source: "already-running-provider-check" },
+                meta: { agent, fixProvided: true, source: "already-running-provider-check" },
             });
         }
     }
     return degraded;
 }
+async function checkAgentProviderHealth(agentName, bundlesRoot, deps) {
+    if (deps.homeDir) {
+        return (0, agent_config_check_1.checkAgentConfigWithProviderHealth)(agentName, bundlesRoot, { homeDir: deps.homeDir });
+    }
+    return (0, agent_config_check_1.checkAgentConfigWithProviderHealth)(agentName, bundlesRoot);
+}
+async function listCliAgents(deps) {
+    if (deps.listDiscoveredAgents) {
+        return Promise.resolve(deps.listDiscoveredAgents());
+    }
+    if (deps.bundlesRoot) {
+        return (0, agent_discovery_1.listEnabledBundleAgents)({ bundlesRoot: deps.bundlesRoot });
+    }
+    return [];
+}
 async function checkAlreadyRunningAgentProviders(deps) {
     return checkAgentProviders(deps);
 }
@@ -149,7 +166,7 @@ async function reportPostRepairProviderHealth(deps, repairedAgents) {
     });
     if (remainingDegraded.length === 0) {
         deps.writeStdout("provider checks recovered after repair");
-        return;
+        return remainingDegraded;
     }
     deps.writeStdout("provider checks still degraded after repair:");
     for (const d of remainingDegraded) {
@@ -159,10 +176,11 @@ async function reportPostRepairProviderHealth(deps, repairedAgents) {
         }
     }
     deps.writeStdout("run `ouro up` again after applying the remaining fixes.");
+    return remainingDegraded;
 }
 async function checkProviderHealthBeforeChat(agentName, deps) {
     const bundlesRoot = deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
-    const result = await (0, agent_config_check_1.checkAgentConfigWithProviderHealth)(agentName, bundlesRoot);
+    const result = await checkAgentProviderHealth(agentName, bundlesRoot, deps);
     if (!result.ok) {
         const output = `${result.error}\n${result.fix ? `      fix:   ${result.fix}` : ""}`;
         deps.writeStdout(output);
@@ -186,7 +204,7 @@ function mergeStartupStability(stability, extraDegraded) {
     }
     return { stable, degraded };
 }
-async function ensureDaemonRunning(deps) {
+async function ensureDaemonRunning(deps, options = {}) {
     const readLatestDaemonStartupEvent = () => {
         try {
             // The daemon writes structured events to daemon.ndjson in the first
@@ -230,7 +248,7 @@ async function ensureDaemonRunning(deps) {
         }
         return null;
     };
-    const alive = await deps.checkSocketAlive(deps.socketPath);
+    const alive = options.initialAlive ?? await deps.checkSocketAlive(deps.socketPath);
     if (alive) {
         const localRuntime = (0, runtime_metadata_1.getRuntimeMetadata)();
         let runningRuntimePromise = null;
@@ -686,19 +704,15 @@ function readVaultRecoverSource(sourcePath) {
         runtimeConfig: recoverRuntimeConfig(parsed),
     };
 }
-function defaultReplacementVaultEmail(agentName, now, action) {
-    const local = agentName
-        .toLowerCase()
-        .replace(/[^a-z0-9._-]+/g, "-")
-        .replace(/^-+|-+$/g, "") || "agent";
-    const stamp = now.toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
-    return `${local}+${action}-${stamp}@ouro.bot`;
-}
-function defaultRecoveredVaultEmail(agentName, now) {
-    return defaultReplacementVaultEmail(agentName, now, "recovered");
+function isGeneratedRepairVaultEmail(email) {
+    const [local, domain] = email.trim().split("@");
+    return domain?.toLowerCase() === "ouro.bot" && /\+(?:replaced|recovered)-\d{14}(?:$|\+)/i.test(local);
 }
-function defaultReplacedVaultEmail(agentName, now) {
-    return defaultReplacementVaultEmail(agentName, now, "replaced");
+function defaultRepairVaultEmail(agentName, config) {
+    const configuredEmail = config.vault?.email?.trim();
+    if (configuredEmail && !isGeneratedRepairVaultEmail(configuredEmail))
+        return configuredEmail;
+    return (0, identity_1.defaultStableVaultEmail)(agentName);
 }
 function ensureVaultSecretPrompt(promptSecret, action) {
     if (promptSecret)
@@ -708,13 +722,17 @@ function ensureVaultSecretPrompt(promptSecret, action) {
 function rejectGeneratedVaultUnlockSecret(action) {
     throw new Error(`vault ${action} no longer supports --generate-unlock-secret. Re-run without that flag and enter a human-chosen unlock secret; Ouro will not print vault unlock secrets.`);
 }
-async function createReplacementVaultForAgent(input) {
+async function createRepairVaultForAgent(input) {
     const result = await (0, vault_setup_1.createVaultAccount)("Ouro credential vault", input.serverUrl, input.email, input.unlockSecret);
     if (!result.success) {
         const message = [
             `vault ${input.action} failed for ${input.agentName}: ${result.error}`,
             "",
-            "This creates a replacement vault. If that vault account already exists, retry with a fresh --email value.",
+            "Could not create the selected vault account.",
+            "If this is the existing vault, run:",
+            `  ouro vault unlock --agent ${input.agentName}`,
+            "If the unlock secret is lost and you intentionally need a different vault account, rerun with --email <email>.",
+            "If this looks like a server or network issue, check --server and retry.",
         ].join("\n");
         input.deps.writeStdout(message);
         return { ok: false, message };
@@ -758,13 +776,9 @@ async function executeVaultCreate(command, deps) {
     }
     if (command.generateUnlockSecret)
         rejectGeneratedVaultUnlockSecret("create");
-    const prompt = deps.promptInput;
     const { configPath, config } = (0, auth_flow_1.readAgentConfigForAgent)(command.agent, deps.bundlesRoot);
     const configuredVault = (0, identity_1.resolveVaultConfig)(command.agent, config.vault);
-    const email = command.email ?? config.vault?.email ?? (prompt ? (await prompt("Ouro credential vault email: ")).trim() : "");
-    if (!email) {
-        throw new Error("vault create requires --email <email> when the agent bundle has no vault.email");
-    }
+    const email = command.email ?? config.vault?.email ?? configuredVault.email;
     const promptSecret = ensureVaultSecretPrompt(deps.promptSecret, "create");
     const serverUrl = command.serverUrl ?? config.vault?.serverUrl ?? configuredVault.serverUrl;
     const unlockSecret = (await promptSecret(`Choose Ouro vault unlock secret for ${email}: `)).trim();
@@ -807,16 +821,15 @@ async function executeVaultReplace(command, deps) {
     if (command.generateUnlockSecret)
         rejectGeneratedVaultUnlockSecret("replace");
     const promptSecret = ensureVaultSecretPrompt(deps.promptSecret, "replace");
-    const now = providerCliNow(deps);
     const { configPath, config } = (0, auth_flow_1.readAgentConfigForAgent)(command.agent, deps.bundlesRoot);
     const configuredVault = (0, identity_1.resolveVaultConfig)(command.agent, config.vault);
-    const email = command.email ?? defaultReplacedVaultEmail(command.agent, now);
+    const email = command.email ?? defaultRepairVaultEmail(command.agent, config);
     const serverUrl = command.serverUrl ?? config.vault?.serverUrl ?? configuredVault.serverUrl;
-    const unlockSecret = (await promptSecret(`Choose replacement Ouro vault unlock secret for ${email}: `)).trim();
+    const unlockSecret = (await promptSecret(`Choose Ouro vault unlock secret for ${email}: `)).trim();
     if (!unlockSecret) {
-        throw new Error("vault replace requires a replacement unlock secret. Re-run in an interactive terminal and enter a human-chosen unlock secret.");
+        throw new Error("vault replace requires an unlock secret. Re-run in an interactive terminal and enter a human-chosen unlock secret.");
     }
-    const replacement = await createReplacementVaultForAgent({
+    const repair = await createRepairVaultForAgent({
         action: "replace",
         agentName: command.agent,
         email,
@@ -827,12 +840,12 @@ async function executeVaultReplace(command, deps) {
         configPath,
         config,
     });
-    if (!replacement.ok)
-        return replacement.message;
+    if (!repair.ok)
+        return repair.message;
     const message = [
         `vault replaced for ${command.agent}`,
         `vault: ${email} at ${serverUrl}`,
-        `local unlock store: ${replacement.store.kind}${replacement.store.secure ? "" : " (explicit plaintext fallback)"}`,
+        `local unlock store: ${repair.store.kind}${repair.store.secure ? "" : " (explicit plaintext fallback)"}`,
         "credentials imported: none",
         "This is the no-export path for agents that predate vault auth or lost an unsaved unlock secret.",
         "Re-auth/re-enter the credentials this agent should use:",
@@ -840,7 +853,7 @@ async function executeVaultReplace(command, deps) {
         `  ouro vault config set --agent ${command.agent} --key <field>`,
         `  ouro provider refresh --agent ${command.agent}`,
         `  ouro auth verify --agent ${command.agent}`,
-        "Keep the replacement vault unlock secret saved outside Ouro. Another machine will need it once.",
+        "Keep the vault unlock secret saved outside Ouro. Another machine will need it once.",
     ].join("\n");
     deps.writeStdout(message);
     return message;
@@ -856,13 +869,13 @@ async function executeVaultRecover(command, deps) {
     const now = providerCliNow(deps);
     const { configPath, config } = (0, auth_flow_1.readAgentConfigForAgent)(command.agent, deps.bundlesRoot);
     const configuredVault = (0, identity_1.resolveVaultConfig)(command.agent, config.vault);
-    const email = command.email ?? defaultRecoveredVaultEmail(command.agent, now);
+    const email = command.email ?? defaultRepairVaultEmail(command.agent, config);
     const serverUrl = command.serverUrl ?? config.vault?.serverUrl ?? configuredVault.serverUrl;
-    const unlockSecret = (await promptSecret(`Choose replacement Ouro vault unlock secret for ${email}: `)).trim();
+    const unlockSecret = (await promptSecret(`Choose Ouro vault unlock secret for ${email}: `)).trim();
     if (!unlockSecret) {
-        throw new Error("vault recover requires a replacement unlock secret. Re-run in an interactive terminal and enter a human-chosen unlock secret.");
+        throw new Error("vault recover requires an unlock secret. Re-run in an interactive terminal and enter a human-chosen unlock secret.");
     }
-    const replacement = await createReplacementVaultForAgent({
+    const repair = await createRepairVaultForAgent({
         action: "recover",
         agentName: command.agent,
         email,
@@ -873,8 +886,8 @@ async function executeVaultRecover(command, deps) {
         configPath,
         config,
     });
-    if (!replacement.ok)
-        return replacement.message;
+    if (!repair.ok)
+        return repair.message;
     const importedProviders = new Set();
     let mergedRuntimeConfig = {};
     for (const source of sourceImports) {
@@ -899,12 +912,12 @@ async function executeVaultRecover(command, deps) {
     const message = [
         `vault recovered for ${command.agent}`,
         `vault: ${email} at ${serverUrl}`,
-        `local unlock store: ${replacement.store.kind}${replacement.store.secure ? "" : " (explicit plaintext fallback)"}`,
+        `local unlock store: ${repair.store.kind}${repair.store.secure ? "" : " (explicit plaintext fallback)"}`,
         `sources imported: ${sourceImports.length}`,
         `provider credentials imported: ${providerList.length === 0 ? "none" : providerList.join(", ")}`,
         `runtime credentials imported: ${runtimeFields.length === 0 ? "none" : runtimeFields.join(", ")}`,
         "credential values were not printed",
-        "Keep the replacement vault unlock secret saved outside Ouro. Another machine will need it once.",
+        "Keep the vault unlock secret saved outside Ouro. Another machine will need it once.",
     ].join("\n");
     deps.writeStdout(message);
     return message;
@@ -1350,6 +1363,108 @@ async function executeProviderRefresh(command, deps) {
     deps.writeStdout(message);
     return message;
 }
+async function readinessReportForAgent(agent, deps) {
+    const bundlesRoot = deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
+    try {
+        const result = await checkAgentProviderHealth(agent, bundlesRoot, deps);
+        if (result.ok) {
+            return { agent, ok: true, issues: [] };
+        }
+        else {
+            const issue = result.issue ?? (0, readiness_repair_1.genericReadinessIssue)({
+                summary: result.error ?? `${agent} is not ready.`,
+                ...(result.fix ? { fix: result.fix } : {}),
+            });
+            return { agent, ok: false, issues: [issue] };
+        }
+    }
+    catch (error) {
+        return {
+            agent,
+            ok: false,
+            issues: [(0, readiness_repair_1.genericReadinessIssue)({
+                    summary: `${agent} readiness check failed.`,
+                    detail: error instanceof Error ? error.message : String(error),
+                    fix: "Run 'ouro doctor' for diagnostics, then retry 'ouro repair'.",
+                })],
+        };
+    }
+}
+async function executeReadinessRepairAction(agent, action, deps) {
+    if (action.kind === "vault-unlock") {
+        await executeVaultUnlock({ kind: "vault.unlock", agent }, deps);
+        return;
+    }
+    if (action.kind === "vault-replace") {
+        await executeVaultReplace({ kind: "vault.replace", agent }, deps);
+        return;
+    }
+    if (action.kind === "provider-auth") {
+        const provider = action.provider;
+        const authRunner = deps.runAuthFlow ?? auth_flow_1.runRuntimeAuthFlow;
+        const result = await authRunner({
+            agentName: agent,
+            provider,
+            promptInput: deps.promptInput,
+        });
+        deps.writeStdout(result.message);
+        await executeProviderRefresh({ kind: "provider.refresh", agent }, deps);
+        return;
+    }
+    deps.writeStdout(`manual step for ${agent}: ${action.command}`);
+}
+async function executeRepair(command, deps) {
+    const agents = command.agent
+        ? [command.agent]
+        : await listCliAgents(deps);
+    const uniqueAgents = [...new Set(agents)];
+    const lines = [];
+    const repairDeps = {
+        ...deps,
+        writeStdout: (text) => {
+            lines.push(text);
+            deps.writeStdout(text);
+        },
+    };
+    if (uniqueAgents.length === 0) {
+        const message = "no agents found to repair.";
+        repairDeps.writeStdout(message);
+        return message;
+    }
+    else {
+        const reports = await Promise.all(uniqueAgents.map((agent) => readinessReportForAgent(agent, repairDeps)));
+        for (const report of reports) {
+            if (report.ok) {
+                repairDeps.writeStdout(`${report.agent}: ready`);
+            }
+        }
+        await (0, readiness_repair_1.runGuidedReadinessRepair)(reports, {
+            promptInput: deps.promptInput,
+            writeStdout: repairDeps.writeStdout,
+            runRepairAction: async (agentName, action) => executeReadinessRepairAction(agentName, action, repairDeps),
+        });
+        return lines.join("\n");
+    }
+}
+function readinessReportsFromDegraded(degraded) {
+    return degraded.map((entry) => ({
+        agent: entry.agent,
+        ok: false,
+        issues: [
+            entry.issue ?? (0, readiness_repair_1.genericReadinessIssue)({
+                summary: entry.errorReason,
+                ...(entry.fixHint ? { fix: entry.fixHint } : {}),
+            }),
+        ],
+    }));
+}
+async function runReadinessRepairForDegraded(degraded, deps) {
+    return (0, readiness_repair_1.runGuidedReadinessRepair)(readinessReportsFromDegraded(degraded), {
+        promptInput: deps.promptInput,
+        writeStdout: deps.writeStdout,
+        runRepairAction: async (agentName, action) => executeReadinessRepairAction(agentName, action, deps),
+    });
+}
 async function executeLegacyAuthSwitch(command, deps) {
     const { state } = readOrBootstrapProviderState(command.agent, deps);
     const lanes = command.facing
@@ -2113,6 +2228,41 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             bundlesRoot: deps.bundlesRoot ?? bundlesRoot,
             promptInput: deps.promptInput,
         });
+        const daemonAliveBeforeStart = await deps.checkSocketAlive(deps.socketPath);
+        let providerChecksAlreadyRun = false;
+        if (!daemonAliveBeforeStart) {
+            progress.startPhase("provider checks");
+            const preflightProviderDegraded = await checkAgentProviders(deps);
+            providerChecksAlreadyRun = true;
+            progress.completePhase("provider checks", preflightProviderDegraded.length > 0 ? `${preflightProviderDegraded.length} degraded` : "ok");
+            if (preflightProviderDegraded.length > 0) {
+                progress.end();
+                if (command.noRepair) {
+                    deps.writeStdout("degraded agents:");
+                    for (const d of preflightProviderDegraded) {
+                        deps.writeStdout(`  ${d.agent}: ${d.errorReason}`);
+                        if (d.fixHint) {
+                            deps.writeStdout(`    fix: ${d.fixHint}`);
+                        }
+                    }
+                    const message = "daemon not started because provider checks are degraded; run `ouro repair` after applying the fixes.";
+                    deps.writeStdout(message);
+                    return message;
+                }
+                const repairResult = await runReadinessRepairForDegraded(preflightProviderDegraded, deps);
+                if (!repairResult.repairsAttempted) {
+                    const message = "daemon not started because provider checks are degraded; run `ouro repair` after applying the fixes.";
+                    deps.writeStdout(message);
+                    return message;
+                }
+                const remainingDegraded = await reportPostRepairProviderHealth(deps, preflightProviderDegraded.map((entry) => entry.agent));
+                if (remainingDegraded.length > 0) {
+                    const message = "daemon not started because provider checks are still degraded.";
+                    deps.writeStdout(message);
+                    return message;
+                }
+            }
+        }
         progress.startPhase("starting daemon");
         const daemonResult = await ensureDaemonRunning({
             ...deps,
@@ -2120,8 +2270,8 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
                 ;
                 progress.announceStep?.(label);
             },
-        });
-        if (daemonResult.alreadyRunning) {
+        }, { initialAlive: daemonAliveBeforeStart });
+        if (!providerChecksAlreadyRun || daemonResult.alreadyRunning) {
             progress.startPhase("provider checks");
             const providerDegraded = await checkAlreadyRunningAgentProviders(deps);
             daemonResult.stability = mergeStartupStability(daemonResult.stability, providerDegraded);
@@ -2788,6 +2938,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     if (command.kind === "provider.refresh") {
         return executeProviderRefresh(command, deps);
     }
+    if (command.kind === "repair") {
+        return executeRepair(command, deps);
+    }
     if (command.kind === "vault.unlock") {
         return executeVaultUnlock(command, deps);
     }

package/dist/heart/daemon/cli-help.js

@@ -175,6 +175,12 @@ exports.COMMAND_REGISTRY = {
         usage: "ouro check --agent <name> --lane outward|inner",
         example: "ouro check --agent ouroboros --lane outward",
     },
+    repair: {
+        category: "Auth",
+        description: "Guide vault and provider readiness repair without invoking AI diagnosis for known issues",
+        usage: "ouro repair [--agent <name>]",
+        example: "ouro repair --agent ouroboros",
+    },
     provider: {
         category: "Auth",
         description: "Refresh daemon provider credentials from an agent vault",
@@ -270,12 +276,12 @@ const SUBCOMMAND_HELP = {
         example: "ouro vault create --agent ouroboros --email ouroboros@ouro.bot",
     },
     "vault replace": {
-        description: "Create an empty replacement agent vault when no unlock secret or JSON export exists",
+        description: "Create an empty agent vault at the stable agent email when no unlock secret or JSON export exists",
         usage: "ouro vault replace --agent <name> [--email <email>] [--server <url>] [--store <store>]",
         example: "ouro vault replace --agent ouroboros",
     },
     "vault recover": {
-        description: "Create a replacement agent vault and import local JSON credential exports",
+        description: "Create an agent vault at the stable agent email and import local JSON credential exports",
         usage: "ouro vault recover --agent <name> --from <json> [--from <json>] [--email <email>] [--server <url>] [--store <store>]",
         example: "ouro vault recover --agent ouroboros --from ./credentials.json",
     },

package/dist/heart/daemon/cli-parse.js

@@ -76,6 +76,7 @@ function usage() {
         "  ouro status --agent <name>",
         "  ouro use --agent <name> --lane outward|inner --provider <provider> --model <model> [--force]",
         "  ouro check --agent <name> --lane outward|inner",
+        "  ouro repair [--agent <name>]",
         "  ouro provider refresh --agent <name>",
         "  ouro outlook [--json]",
         "  ouro -v|--version",
@@ -1033,6 +1034,12 @@ function parseOuroCommand(args) {
         return parseProviderUseCommand(args.slice(1));
     if (head === "check")
         return parseProviderCheckCommand(args.slice(1));
+    if (head === "repair") {
+        const { agent, rest } = extractAgentFlag(args.slice(1));
+        if (rest.length > 0)
+            throw new Error("Usage: ouro repair [--agent <name>]");
+        return agent ? { kind: "repair", agent } : { kind: "repair" };
+    }
     if (head === "provider")
         return parseProviderCommand(args.slice(1));
     if (head === "logs") {

package/dist/heart/daemon/interactive-repair.js

@@ -24,6 +24,9 @@ function isConfigError(degraded) {
     return degraded.fixHint.length > 0 && !isVaultUnlockIssue(degraded) && !isCredentialIssue(degraded);
 }
 function hasRunnableInteractiveRepair(degraded) {
+    if (degraded.issue?.actions.some((action) => typedActionToRunnable(degraded, action) !== undefined)) {
+        return true;
+    }
     return isVaultUnlockIssue(degraded) || isCredentialIssue(degraded);
 }
 function isAgentProvider(value) {
@@ -68,6 +71,11 @@ function writeDeclinedRepair(degraded, command, deps) {
     }
 }
 function runnableRepairActionFor(degraded) {
+    const typedAction = degraded.issue?.actions
+        .map((action) => typedActionToRunnable(degraded, action))
+        .find((action) => action !== undefined);
+    if (typedAction)
+        return typedAction;
     if (isVaultUnlockIssue(degraded)) {
         return { kind: "vault-unlock", label: "vault unlock", command: vaultUnlockCommandFor(degraded) };
     }
@@ -81,6 +89,22 @@ function runnableRepairActionFor(degraded) {
     }
     return undefined;
 }
+function typedActionToRunnable(degraded, action) {
+    if (action.executable === false || action.command.includes("<"))
+        return undefined;
+    if (action.kind === "vault-unlock") {
+        return { kind: "vault-unlock", label: "vault unlock", command: action.command };
+    }
+    if (action.kind === "provider-auth") {
+        return {
+            kind: "provider-auth",
+            label: "provider auth",
+            command: action.command || `ouro auth --agent ${degraded.agent}`,
+            provider: action.provider,
+        };
+    }
+    return undefined;
+}
 function writeRepairQueueSummary(degraded, deps) {
     const repairable = degraded
         .map((entry) => ({ entry, action: runnableRepairActionFor(entry) }))

package/dist/heart/daemon/readiness-repair.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vaultLockedIssue = vaultLockedIssue;
+exports.providerCredentialMissingIssue = providerCredentialMissingIssue;
+exports.providerLiveCheckFailedIssue = providerLiveCheckFailedIssue;
+exports.genericReadinessIssue = genericReadinessIssue;
+exports.isKnownReadinessIssue = isKnownReadinessIssue;
+exports.renderReadinessIssue = renderReadinessIssue;
+exports.runGuidedReadinessRepair = runGuidedReadinessRepair;
+const runtime_1 = require("../../nerves/runtime");
+function vaultLockedIssue(agentName) {
+    return {
+        kind: "vault-locked",
+        severity: "blocked",
+        actor: "human-required",
+        summary: `${agentName} needs its vault unlocked on this machine.`,
+        detail: "Choose the path that matches what the human actually has. Ouro will not print or store a portable copy of the unlock secret.",
+        actions: [
+            {
+                kind: "vault-unlock",
+                label: "I have the saved vault unlock secret",
+                command: `ouro vault unlock --agent ${agentName}`,
+                actor: "human-required",
+            },
+            {
+                kind: "vault-replace",
+                label: "Nobody saved it; create an empty vault and re-enter credentials",
+                command: `ouro vault replace --agent ${agentName}`,
+                actor: "human-required",
+            },
+            {
+                kind: "vault-recover",
+                label: "I have an old JSON credential export",
+                command: `ouro vault recover --agent ${agentName} --from <json>`,
+                actor: "human-required",
+                executable: false,
+            },
+        ],
+    };
+}
+function providerCredentialMissingIssue(input) {
+    return {
+        kind: "provider-credentials-missing",
+        severity: "blocked",
+        actor: "human-required",
+        summary: `${input.agentName} is missing ${input.provider} credentials for the ${input.lane} lane.`,
+        detail: `Selected model: ${input.model}. Credential source: ${input.credentialPath}.`,
+        actions: [
+            {
+                kind: "provider-auth",
+                label: `Authenticate ${input.provider} for ${input.agentName}`,
+                command: `ouro auth --agent ${input.agentName} --provider ${input.provider}`,
+                actor: "human-required",
+                provider: input.provider,
+            },
+            {
+                kind: "provider-use",
+                label: "Choose a different working provider/model for this lane",
+                command: `ouro use --agent ${input.agentName} --lane ${input.lane} --provider <provider> --model <model>`,
+                actor: "human-choice",
+                executable: false,
+                lane: input.lane,
+            },
+        ],
+    };
+}
+function providerLiveCheckFailedIssue(input) {
+    return {
+        kind: "provider-live-check-failed",
+        severity: "blocked",
+        actor: "human-choice",
+        summary: `${input.agentName}'s ${input.lane} lane provider ${input.provider} / ${input.model} failed its live check.`,
+        detail: input.message,
+        actions: [
+            {
+                kind: "provider-auth",
+                label: `Refresh ${input.provider} credentials`,
+                command: `ouro auth --agent ${input.agentName} --provider ${input.provider}`,
+                actor: "human-required",
+                provider: input.provider,
+            },
+            {
+                kind: "provider-use",
+                label: "Choose a different working provider/model for this lane",
+                command: `ouro use --agent ${input.agentName} --lane ${input.lane} --provider <provider> --model <model>`,
+                actor: "human-choice",
+                executable: false,
+                lane: input.lane,
+            },
+        ],
+    };
+}
+function genericReadinessIssue(input) {
+    return {
+        kind: "generic",
+        severity: "degraded",
+        actor: "human-choice",
+        summary: input.summary,
+        ...(input.detail ? { detail: input.detail } : {}),
+        actions: input.fix
+            ? [{
+                    kind: "provider-use",
+                    label: "Follow the printed fix",
+                    command: input.fix,
+                    actor: "human-choice",
+                    executable: false,
+                }]
+            : [],
+    };
+}
+function isKnownReadinessIssue(issue) {
+    return !!issue && issue.kind !== "generic";
+}
+function renderReadinessIssue(issue) {
+    const lines = [issue.summary];
+    if (issue.detail) {
+        lines.push(`  ${issue.detail}`);
+    }
+    issue.actions.forEach((action, index) => {
+        lines.push(`${index + 1}. ${action.label}`);
+        lines.push(`   runs: ${action.command}`);
+    });
+    lines.push(`${issue.actions.length + 1}. Skip for now`);
+    return lines.join("\n");
+}
+function selectedActionFor(answer, issue) {
+    const selected = Number.parseInt(answer.trim(), 10);
+    if (!Number.isFinite(selected))
+        return null;
+    if (selected === issue.actions.length + 1)
+        return "skip";
+    if (selected < 1 || selected > issue.actions.length)
+        return null;
+    /* v8 ignore next -- defensive: bounds were checked above, but keep sparse arrays harmless @preserve */
+    return issue.actions[selected - 1] ?? null;
+}
+function isExecutableAction(action) {
+    if (action.executable === false)
+        return false;
+    return !action.command.includes("<");
+}
+async function runGuidedReadinessRepair(reports, deps) {
+    (0, runtime_1.emitNervesEvent)({
+        level: "info",
+        component: "daemon",
+        event: "daemon.readiness_repair_start",
+        message: "guided readiness repair started",
+        meta: { reportCount: reports.length },
+    });
+    let repairsAttempted = false;
+    for (const report of reports) {
+        if (report.ok || report.issues.length === 0)
+            continue;
+        for (const issue of report.issues) {
+            deps.writeStdout(renderReadinessIssue(issue));
+            if (!deps.promptInput) {
+                deps.writeStdout(`manual repair required for ${report.agent}; run one of the commands above.`);
+                continue;
+            }
+            const answer = await deps.promptInput(`Choose [1-${issue.actions.length + 1}]: `);
+            const action = selectedActionFor(answer, issue);
+            if (action === "skip") {
+                deps.writeStdout(`repair skipped for ${report.agent}.`);
+                continue;
+            }
+            if (!action) {
+                deps.writeStdout(`invalid repair choice for ${report.agent}; no repair attempted.`);
+                continue;
+            }
+            if (!isExecutableAction(action)) {
+                deps.writeStdout(`manual step for ${report.agent}: ${action.command}`);
+                continue;
+            }
+            if (!deps.runRepairAction) {
+                deps.writeStdout(`repair runner unavailable for ${report.agent}; run \`${action.command}\` manually.`);
+                continue;
+            }
+            try {
+                await deps.runRepairAction(report.agent, action, issue);
+                repairsAttempted = true;
+                deps.writeStdout(`repair attempted for ${report.agent}`);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                repairsAttempted = true;
+                deps.writeStdout(`repair error for ${report.agent}: ${message}`);
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "daemon",
+                    event: "daemon.readiness_repair_error",
+                    message: "guided readiness repair action failed",
+                    meta: { agent: report.agent, issue: issue.kind, action: action.kind, error: message },
+                });
+            }
+        }
+    }
+    (0, runtime_1.emitNervesEvent)({
+        level: "info",
+        component: "daemon",
+        event: "daemon.readiness_repair_end",
+        message: "guided readiness repair completed",
+        meta: { repairsAttempted },
+    });
+    return { repairsAttempted };
+}

package/dist/heart/identity.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HARNESS_CANONICAL_REPO_URL = exports.DEFAULT_AGENT_SENSES = exports.DEFAULT_VAULT_SERVER_URL = exports.DEFAULT_AGENT_PHRASES = exports.DEFAULT_AGENT_CONTEXT = exports.PROVIDER_CREDENTIALS = void 0;
+exports.defaultStableVaultEmail = defaultStableVaultEmail;
 exports.resolveVaultConfig = resolveVaultConfig;
 exports.normalizeSenses = normalizeSenses;
 exports.buildDefaultAgentTemplate = buildDefaultAgentTemplate;
@@ -76,13 +77,20 @@ exports.DEFAULT_AGENT_PHRASES = {
     followup: ["processing"],
 };
 exports.DEFAULT_VAULT_SERVER_URL = "https://vault.ouroboros.bot";
+function defaultStableVaultEmail(agentName) {
+    const local = agentName
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "agent";
+    return `${local}@ouro.bot`;
+}
 /**
  * Resolve the vault config for an agent, applying defaults.
  * If vault is not configured in agent.json, returns default values.
  */
 function resolveVaultConfig(agentName, config) {
     return {
-        email: config?.email ?? `${agentName}@ouro.bot`,
+        email: config?.email ?? defaultStableVaultEmail(agentName),
         serverUrl: config?.serverUrl ?? exports.DEFAULT_VAULT_SERVER_URL,
     };
 }

package/dist/repertoire/vault-unlock.js

@@ -100,7 +100,7 @@ function vaultUnlockReplaceRecoverFix(agentName, nextStep = "Then run 'ouro up'
     return [
         `Run 'ouro vault unlock --agent ${agentName}' if you have the saved vault unlock secret.`,
         `If this agent predates vault auth or nobody saved the unlock secret, run 'ouro vault replace --agent ${agentName}' to create a new empty vault, then re-auth/re-enter credentials.`,
-        `If you do have a local JSON credential export, run 'ouro vault recover --agent ${agentName} --from <json>' to create a replacement vault and import it.`,
+        `If you do have a local JSON credential export, run 'ouro vault recover --agent ${agentName} --from <json>' to create the agent vault and import it.`,
         nextStep,
     ].join(" ");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.394",
+  "version": "0.1.0-alpha.396",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",