@ouro.bot/cli 0.1.0-alpha.395 → 0.1.0-alpha.397

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.397",
+      "changes": [
+        "`ouro up` provider repair output now uses compact readiness cards and `need repair` progress labels instead of dense degraded-agent prose.",
+        "Guided readiness repair and post-repair summaries now share the same typed issue renderer, so locked vaults, missing provider credentials, and generic repair hints show consistent `next`/`or` commands.",
+        "`ouro vault replace` now prompts for a `new` unlock secret and prints a short recovery handoff to `ouro repair --agent <agent>` instead of dumping generic provider/runtime credential commands into the middle of `ouro up`.",
+        "`ouro vault recover` also prompts for a `new` unlock secret while continuing to avoid printing credential values or portable unlock material.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the provider repair visual cleanup release."
+      ]
+    },
+    {
+      "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": [

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,15 +129,49 @@ 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);
 }
+function readinessIssueFromDegraded(entry) {
+    return entry.issue ?? (0, readiness_repair_1.genericReadinessIssue)({
+        summary: `${entry.agent}: ${entry.errorReason}`,
+        ...(entry.fixHint ? { fix: entry.fixHint } : {}),
+    });
+}
+function writeProviderRepairSummary(deps, title, degraded) {
+    deps.writeStdout(title);
+    for (const entry of degraded) {
+        for (const line of (0, readiness_repair_1.renderReadinessIssueNextSteps)(readinessIssueFromDegraded(entry))) {
+            deps.writeStdout(line);
+        }
+    }
+}
+function providerRepairCountSummary(count) {
+    if (count === 0)
+        return "ok";
+    return `${count} ${count === 1 ? "needs" : "need"} repair`;
+}
 async function reportPostRepairProviderHealth(deps, repairedAgents) {
     const remainingDegraded = await checkAgentProviders(deps, repairedAgents);
     (0, runtime_1.emitNervesEvent)({
@@ -149,20 +185,15 @@ 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) {
-        deps.writeStdout(`  ${d.agent}: ${d.errorReason}`);
-        if (d.fixHint) {
-            deps.writeStdout(`    fix: ${d.fixHint}`);
-        }
-    }
-    deps.writeStdout("run `ouro up` again after applying the remaining fixes.");
+    writeProviderRepairSummary(deps, "Still blocked:", remainingDegraded);
+    deps.writeStdout("Run `ouro up` again after these are fixed.");
+    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 +217,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 +261,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,13 +717,6 @@ function readVaultRecoverSource(sourcePath) {
         runtimeConfig: recoverRuntimeConfig(parsed),
     };
 }
-function defaultStableVaultEmail(agentName) {
-    const local = agentName
-        .toLowerCase()
-        .replace(/[^a-z0-9._-]+/g, "-")
-        .replace(/^-+|-+$/g, "") || "agent";
-    return `${local}@ouro.bot`;
-}
 function isGeneratedRepairVaultEmail(email) {
     const [local, domain] = email.trim().split("@");
     return domain?.toLowerCase() === "ouro.bot" && /\+(?:replaced|recovered)-\d{14}(?:$|\+)/i.test(local);
@@ -701,7 +725,7 @@ function defaultRepairVaultEmail(agentName, config) {
     const configuredEmail = config.vault?.email?.trim();
     if (configuredEmail && !isGeneratedRepairVaultEmail(configuredEmail))
         return configuredEmail;
-    return defaultStableVaultEmail(agentName);
+    return (0, identity_1.defaultStableVaultEmail)(agentName);
 }
 function ensureVaultSecretPrompt(promptSecret, action) {
     if (promptSecret)
@@ -765,13 +789,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();
@@ -818,7 +838,7 @@ async function executeVaultReplace(command, deps) {
     const configuredVault = (0, identity_1.resolveVaultConfig)(command.agent, config.vault);
     const email = command.email ?? defaultRepairVaultEmail(command.agent, config);
     const serverUrl = command.serverUrl ?? config.vault?.serverUrl ?? configuredVault.serverUrl;
-    const unlockSecret = (await promptSecret(`Choose Ouro vault unlock secret for ${email}: `)).trim();
+    const unlockSecret = (await promptSecret(`Choose new Ouro vault unlock secret for ${email}: `)).trim();
     if (!unlockSecret) {
         throw new Error("vault replace requires an unlock secret. Re-run in an interactive terminal and enter a human-chosen unlock secret.");
     }
@@ -839,13 +859,8 @@ async function executeVaultReplace(command, deps) {
         `vault replaced for ${command.agent}`,
         `vault: ${email} at ${serverUrl}`,
         `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:",
-        `  ouro auth --agent ${command.agent} --provider <provider>`,
-        `  ouro vault config set --agent ${command.agent} --key <field>`,
-        `  ouro provider refresh --agent ${command.agent}`,
-        `  ouro auth verify --agent ${command.agent}`,
+        "imported: none",
+        `next: ouro repair --agent ${command.agent}`,
         "Keep the vault unlock secret saved outside Ouro. Another machine will need it once.",
     ].join("\n");
     deps.writeStdout(message);
@@ -864,7 +879,7 @@ async function executeVaultRecover(command, deps) {
     const configuredVault = (0, identity_1.resolveVaultConfig)(command.agent, config.vault);
     const email = command.email ?? defaultRepairVaultEmail(command.agent, config);
     const serverUrl = command.serverUrl ?? config.vault?.serverUrl ?? configuredVault.serverUrl;
-    const unlockSecret = (await promptSecret(`Choose Ouro vault unlock secret for ${email}: `)).trim();
+    const unlockSecret = (await promptSecret(`Choose new Ouro vault unlock secret for ${email}: `)).trim();
     if (!unlockSecret) {
         throw new Error("vault recover requires an unlock secret. Re-run in an interactive terminal and enter a human-chosen unlock secret.");
     }
@@ -1356,6 +1371,103 @@ 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: [readinessIssueFromDegraded(entry)],
+    }));
+}
+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
@@ -2119,6 +2231,36 @@ 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", providerRepairCountSummary(preflightProviderDegraded.length));
+            if (preflightProviderDegraded.length > 0) {
+                progress.end();
+                if (command.noRepair) {
+                    writeProviderRepairSummary(deps, "Provider checks need repair:", preflightProviderDegraded);
+                    const message = "daemon not started: provider checks need repair. Run `ouro repair` or rerun `ouro up` to choose a repair path.";
+                    deps.writeStdout(message);
+                    return message;
+                }
+                const repairResult = await runReadinessRepairForDegraded(preflightProviderDegraded, deps);
+                if (!repairResult.repairsAttempted) {
+                    writeProviderRepairSummary(deps, "Provider checks still need repair:", preflightProviderDegraded);
+                    const message = "daemon not started: provider checks need repair. Run `ouro repair` or rerun `ouro up` to choose a repair path.";
+                    deps.writeStdout(message);
+                    return message;
+                }
+                const remainingDegraded = await reportPostRepairProviderHealth(deps, preflightProviderDegraded.map((entry) => entry.agent));
+                if (remainingDegraded.length > 0) {
+                    const message = "daemon not started: provider checks still need repair.";
+                    deps.writeStdout(message);
+                    return message;
+                }
+            }
+        }
         progress.startPhase("starting daemon");
         const daemonResult = await ensureDaemonRunning({
             ...deps,
@@ -2126,12 +2268,12 @@ 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);
-            progress.completePhase("provider checks", providerDegraded.length > 0 ? `${providerDegraded.length} degraded` : "ok");
+            progress.completePhase("provider checks", providerRepairCountSummary(providerDegraded.length));
         }
         progress.end();
         deps.writeStdout(daemonResult.message);
@@ -2139,13 +2281,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         if (daemonResult.stability?.degraded && daemonResult.stability.degraded.length > 0) {
             if (command.noRepair) {
                 // --no-repair: write degraded summary and skip interactive repair
-                deps.writeStdout("degraded agents:");
-                for (const d of daemonResult.stability.degraded) {
-                    deps.writeStdout(`  ${d.agent}: ${d.errorReason}`);
-                    if (d.fixHint) {
-                        deps.writeStdout(`    fix: ${d.fixHint}`);
-                    }
-                }
+                writeProviderRepairSummary(deps, "Provider checks need repair:", daemonResult.stability.degraded);
                 (0, runtime_1.emitNervesEvent)({
                     level: "warn",
                     component: "daemon",
@@ -2794,6 +2930,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",

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,216 @@
+"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.renderReadinessIssueNextSteps = renderReadinessIssueNextSteps;
+exports.runGuidedReadinessRepair = runGuidedReadinessRepair;
+const runtime_1 = require("../../nerves/runtime");
+function vaultLockedIssue(agentName) {
+    return {
+        kind: "vault-locked",
+        severity: "blocked",
+        actor: "human-required",
+        summary: `${agentName}: vault locked`,
+        detail: "Pick the path that matches what the human actually has. Ouro will not print or store the unlock secret as a portable file.",
+        actions: [
+            {
+                kind: "vault-unlock",
+                label: "Unlock with saved secret",
+                command: `ouro vault unlock --agent ${agentName}`,
+                actor: "human-required",
+            },
+            {
+                kind: "vault-replace",
+                label: "Create empty replacement vault",
+                command: `ouro vault replace --agent ${agentName}`,
+                actor: "human-required",
+            },
+            {
+                kind: "vault-recover",
+                label: "Recover from JSON 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}: missing ${input.provider} credentials (${input.lane}, ${input.model})`,
+        detail: `source: ${input.credentialPath}`,
+        actions: [
+            {
+                kind: "provider-auth",
+                label: `Authenticate ${input.provider}`,
+                command: `ouro auth --agent ${input.agentName} --provider ${input.provider}`,
+                actor: "human-required",
+                provider: input.provider,
+            },
+            {
+                kind: "provider-use",
+                label: "Choose another provider/model",
+                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}: ${input.lane} provider ${input.provider} / ${input.model} failed 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(`   ${action.command}`);
+    });
+    lines.push(`${issue.actions.length + 1}. Skip for now`);
+    return lines.join("\n");
+}
+function renderReadinessIssueNextSteps(issue) {
+    const lines = [`  ${issue.summary}`];
+    if (issue.detail && issue.kind !== "vault-locked") {
+        lines.push(`    ${issue.detail}`);
+    }
+    issue.actions.forEach((action, index) => {
+        lines.push(`    ${index === 0 ? "next" : "or"}: ${action.command}`);
+    });
+    return lines;
+}
+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(`skipped ${report.agent} for now.`);
+                continue;
+            }
+            if (!action) {
+                deps.writeStdout(`invalid 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 step finished 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/package.json

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