@ouro.bot/cli 0.1.0-alpha.714 → 0.1.0-alpha.716

package/changelog.json

@@ -1,6 +1,18 @@
 {
   "_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.716",
+      "changes": [
+        "Add durable MCP bridge doctor and repair guidance."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.715",
+      "changes": [
+        "Keep RSVP routine-specific report copy in bundle metadata while leaving harness fixtures and help generic."
+      ]
+    },
     {
       "version": "0.1.0-alpha.714",
       "changes": [

package/dist/heart/daemon/agent-service.js

@@ -60,6 +60,7 @@ const diary_1 = require("../../mind/diary");
 const record_paths_1 = require("../../mind/record-paths");
 const runtime_1 = require("../../nerves/runtime");
 const socket_client_1 = require("./socket-client");
+const mcp_canary_1 = require("./mcp-canary");
 /** Format diary hits the same way the search_facts tool does. */
 function formatDiaryHits(hits) {
     return hits.map((f) => `[diary] ${f.text} (source=${f.source}, createdAt=${f.createdAt})`);
@@ -250,7 +251,7 @@ async function readRuntimeStatus(socketPath, agent) {
         };
     }
 }
-function formatRuntimeStatusLines(runtime, mcpVersion) {
+function formatRuntimeStatusLines(runtime, mcpVersion, agent) {
     if (!runtime)
         return mcpVersion ? [`mcpVersion=${mcpVersion}`] : [];
     if (!runtime.daemonReachable) {
@@ -264,10 +265,16 @@ function formatRuntimeStatusLines(runtime, mcpVersion) {
         const versionPart = runtime.overview.version ? `\tdaemonVersion=${runtime.overview.version}` : "";
         const modePart = runtime.overview.mode ? `\tmode=${runtime.overview.mode}` : "";
         const mcpVersionPart = mcpVersion ? `\tmcpVersion=${mcpVersion}` : "";
-        const mismatchPart = mcpVersion && runtime.overview.version && mcpVersion !== runtime.overview.version
+        const hasVersionMismatch = !!(mcpVersion && runtime.overview.version && mcpVersion !== runtime.overview.version);
+        const mismatchPart = hasVersionMismatch
             ? `\tversionMismatch=mcp:${mcpVersion},daemon:${runtime.overview.version}`
             : "";
         lines.push(`daemon=${runtime.overview.daemon}\thealth=${runtime.overview.health}${versionPart}${modePart}${mcpVersionPart}${mismatchPart}`);
+        if (hasVersionMismatch) {
+            const repair = (0, mcp_canary_1.buildMcpBridgeRepairGuidance)(agent);
+            lines.push(`mcpRepair=${repair.actor}\tcodex=${repair.commands[0]}\tclaudeCode=${repair.commands[1]}`);
+            lines.push(`mcpReload=required\treason=${repair.reload}`);
+        }
     }
     for (const worker of runtime.workers) {
         lines.push(`worker=${worker.worker}:${worker.status}`);
@@ -297,6 +304,16 @@ function formatRuntimeStatusLines(runtime, mcpVersion) {
         lines.push(`mcpVersion=${mcpVersion}`);
     return lines;
 }
+function summarizeMcpBridgeHealth(agent, runtime, mcpVersion) {
+    const daemonVersion = runtime?.daemonReachable ? runtime.overview?.version ?? null : null;
+    const versionMismatch = !!(mcpVersion && daemonVersion && mcpVersion !== daemonVersion);
+    return {
+        mcpVersion,
+        daemonVersion,
+        versionMismatch,
+        ...(versionMismatch ? { repair: (0, mcp_canary_1.buildMcpBridgeRepairGuidance)(agent) } : {}),
+    };
+}
 // ─── Handlers ────────────────────────────────────────────────────────────────
 async function handleAgentStatus(params) {
     (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.agent_service_start", message: "handling agent.status", meta: { agent: params.agent } });
@@ -316,7 +333,8 @@ async function handleAgentStatus(params) {
         `sessionCount=${sessions.length}`,
         `diaryEntries=${facts.length}`,
     ].join("\t");
-    const runtimeLines = formatRuntimeStatusLines(runtime, mcpVersion);
+    const runtimeLines = formatRuntimeStatusLines(runtime, mcpVersion, params.agent);
+    const mcpHealth = summarizeMcpBridgeHealth(params.agent, runtime, mcpVersion);
     const message = [agentLine, ...runtimeLines].join("\n");
     return {
         ok: true,
@@ -330,6 +348,7 @@ async function handleAgentStatus(params) {
             factCount: facts.length,
             runtime,
             mcpVersion,
+            mcpHealth,
         },
     };
 }

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

@@ -125,6 +125,10 @@ const DEFAULT_DAEMON_STARTUP_TIMEOUT_MS = 60_000;
 const DEFAULT_DAEMON_STARTUP_POLL_INTERVAL_MS = 500;
 const DEFAULT_DAEMON_STARTUP_STABILITY_WINDOW_MS = 1_500;
 const DEFAULT_DAEMON_STARTUP_RETRY_LIMIT = 1;
+function setupReloadNotice(tool) {
+    const host = tool === "codex" ? "Codex" : "Claude Code";
+    return `  reload required: open a fresh ${host} session so the host launches the newly registered MCP bridge; existing MCP processes keep their old runtime`;
+}
 const DEFAULT_DAEMON_STARTUP_LOG_LINES = 10;
 const RSVP_CLI_KINDS = new Set([
     "rsvp.doctor",
@@ -6940,7 +6944,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             if (!existingClaudeMd.includes("Agent conversations (ouro)")) {
                 fs.writeFileSync(claudeMdPath, existingClaudeMd + agentInstructions);
             }
-            const message = `setup complete: claude-code + ${setupAgent}\n  MCP server registered\n  hooks configured\n  conversation formatting instructions added`;
+            const message = `setup complete: claude-code + ${setupAgent}\n  MCP server registered\n  hooks configured\n  conversation formatting instructions added\n${setupReloadNotice("claude-code")}`;
             deps.writeStdout(message);
             return message;
         }
@@ -6954,7 +6958,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
                 message: "dev tool setup complete",
                 meta: { tool, agent: setupAgent, runtimeMode, platform },
             });
-            const message = `setup complete: codex + ${setupAgent}\n  MCP server registered`;
+            const message = `setup complete: codex + ${setupAgent}\n  MCP server registered\n${setupReloadNotice("codex")}`;
             deps.writeStdout(message);
             return message;
         }
@@ -6981,6 +6985,32 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         deps.writeStdout(message);
         return message;
     }
+    if (command.kind === "mcp.doctor") {
+        const canarySocketPath = command.socketOverride ?? deps.socketPath;
+        const result = await (0, mcp_canary_1.runMcpStatusCanary)({
+            agent: command.agent,
+            socketPath: canarySocketPath,
+            command: process.execPath,
+            commandArgs: [
+                path.join(__dirname, "ouro-bot-entry.js"),
+                "mcp-serve",
+                "--agent",
+                command.agent,
+                "--socket",
+                canarySocketPath,
+            ],
+        });
+        if (!result.ok)
+            deps.setExitCode?.(1);
+        const jsonPayload = result.ok || result.repair
+            ? { ...result, repair: result.repair ?? (0, mcp_canary_1.buildMcpBridgeRepairGuidance)(command.agent) }
+            : { ...result, nextSteps: (0, mcp_canary_1.buildMcpDoctorNextSteps)(result, command.agent) };
+        const message = command.json
+            ? JSON.stringify(jsonPayload, null, 2)
+            : (0, mcp_canary_1.formatMcpStatusDoctorResult)(result, command.agent);
+        deps.writeStdout(message);
+        return message;
+    }
     /* v8 ignore start — mcp-serve block binds to process.stdin/stdout; tested via mcp-server unit tests */
     // ── mcp-serve: start MCP server in-process on stdin/stdout ──
     if (command.kind === "mcp-serve") {

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

@@ -148,7 +148,7 @@ exports.COMMAND_REGISTRY = {
         category: "Habits",
         description: "AislePlanner-backed RSVP habit operations, triage, receipts, ledgers, migration checks, refreshes, and smoke tests",
         usage: "ouro rsvp <doctor|incident|cutover|legacy-render|replay|config|habit|import-legacy|refresh|compare|smoke> ...",
-        example: "ouro rsvp doctor --agent slugger --json",
+        example: "ouro rsvp doctor --agent rsvp-agent --json",
         subcommands: [
             "doctor",
             "incident",
@@ -335,8 +335,8 @@ exports.COMMAND_REGISTRY = {
         category: "System",
         description: "Interact with MCP servers",
         usage: "ouro mcp <subcommand>",
-        example: "ouro mcp canary --agent ouroboros",
-        subcommands: ["list", "call", "canary"],
+        example: "ouro mcp doctor --agent ouroboros",
+        subcommands: ["list", "call", "canary", "doctor"],
     },
     "mcp-serve": {
         category: "System",
@@ -456,12 +456,12 @@ const SUBCOMMAND_HELP = {
     "rsvp doctor": {
         description: "Check native RSVP configuration, credentials, BlueBubbles attachment, ledgers, receipts, and migration readiness without sending messages; use --json --strict in triage",
         usage: "ouro rsvp doctor [--agent <name>] [--strict] [--output <path>] [--json]",
-        example: "ouro rsvp doctor --agent slugger --strict --json",
+        example: "ouro rsvp doctor --agent rsvp-agent --strict --json",
     },
     "rsvp incident": {
         description: "Collect a redacted local RSVP diagnostic incident bundle with doctor status, receipts, and ledger pointers without contacting the daemon",
         usage: "ouro rsvp incident [--agent <name>] [--output <path>] [--json]",
-        example: "ouro rsvp incident --agent slugger --output /tmp/rsvp-incident.json",
+        example: "ouro rsvp incident --agent rsvp-agent --output /tmp/rsvp-incident.json",
     },
     "rsvp cutover": {
         description: "Inspect or retire legacy RSVP sender state before native live send",
@@ -486,7 +486,7 @@ const SUBCOMMAND_HELP = {
     "rsvp habit stage": {
         description: "Stage an RSVP refresh habit with bundle-owned routine naming and report copy",
         usage: "ouro rsvp habit stage [--agent <name>] [--name <rsvp-name>] [--title <title>] [--report-title <title>] --mode shadow|live --cadence '<cron>' [--output <path>] [--json]",
-        example: "ouro rsvp habit stage --agent rsvp-agent --name rsvp-wedding --title 'Wedding RSVPs' --mode shadow --cadence '0 10 * * *'",
+        example: "ouro rsvp habit stage --agent rsvp-agent --name rsvp-updates --title 'RSVP Updates' --mode shadow --cadence '0 10 * * *'",
     },
     "rsvp import-legacy": {
         description: "Compatibility alias for `ouro rsvp config import-legacy`; mutates only with --yes",
@@ -496,17 +496,17 @@ const SUBCOMMAND_HELP = {
     "rsvp refresh": {
         description: "Run the native RSVP refresh path and write receipts; defaults to dry-run behavior unless --allow-send is explicit",
         usage: "ouro rsvp refresh [--agent <name>] [--habit <rsvp-name>] --mode shadow|live [--no-send|--allow-send] [--output <path>] [--json]",
-        example: "ouro rsvp refresh --agent rsvp-agent --habit rsvp-wedding --mode shadow --no-send --json",
+        example: "ouro rsvp refresh --agent rsvp-agent --habit rsvp-updates --mode shadow --no-send --json",
     },
     "rsvp compare": {
         description: "Compare native and legacy RSVP render outputs for migration verification",
         usage: "ouro rsvp compare [--agent <name>] --native <path> --legacy <path> [--output <path>] [--json]",
-        example: "ouro rsvp compare --agent slugger --native /tmp/native.json --legacy /tmp/legacy.json",
+        example: "ouro rsvp compare --agent rsvp-agent --native /tmp/native.json --legacy /tmp/legacy.json",
     },
     "rsvp smoke": {
         description: "Smoke-test RSVP follow-up behavior through a target sense; preflight is no-send and live mode requires --allow-send",
         usage: "ouro rsvp smoke [--agent <name>] --mode preflight|live --surface bluebubbles [--question <text>] [--allow-send] [--output <path>] [--replay-output <path>] [--json]",
-        example: "ouro rsvp smoke --agent slugger --mode preflight --surface bluebubbles --question 'who is pending?'",
+        example: "ouro rsvp smoke --agent rsvp-agent --mode preflight --surface bluebubbles --question 'who is pending?'",
     },
     "mail import-mbox": {
         description: "Import a HEY or other MBOX export into an existing delegated Mailroom source grant",

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

@@ -134,6 +134,7 @@ function usage() {
         "  ouro session list [--agent <name>]",
         "  ouro mcp list",
         "  ouro mcp call <server> <tool> [--args '{...}']",
+        "  ouro mcp doctor --agent <name> [--json]",
         "  ouro rollback [<version>]",
         "  ouro versions",
         "  ouro clone <remote> [--agent <name>]",
@@ -1458,6 +1459,31 @@ function parseMcpCommand(args) {
             ...(json ? { json: true } : {}),
         };
     }
+    if (sub === "doctor") {
+        let socketOverride;
+        let json = false;
+        for (let i = 0; i < rest.length; i++) {
+            if (rest[i] === "--socket") {
+                if (!rest[i + 1])
+                    throw new Error("mcp doctor requires a value after --socket");
+                socketOverride = rest[++i];
+                continue;
+            }
+            if (rest[i] === "--json") {
+                json = true;
+                continue;
+            }
+            throw new Error(`Unknown mcp doctor flag: ${rest[i]}`);
+        }
+        if (!agent)
+            throw new Error("mcp doctor requires --agent <name>");
+        return {
+            kind: "mcp.doctor",
+            agent,
+            ...(socketOverride ? { socketOverride } : {}),
+            ...(json ? { json: true } : {}),
+        };
+    }
     throw new Error(`Usage\n${usage()}`);
 }
 function inferAgentNameFromRemote(remote) {

package/dist/heart/daemon/mcp-canary.js

@@ -33,9 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMcpBridgeRepairGuidance = buildMcpBridgeRepairGuidance;
+exports.formatMcpBridgeRepairDetails = formatMcpBridgeRepairDetails;
+exports.buildMcpDoctorNextSteps = buildMcpDoctorNextSteps;
+exports.formatMcpDoctorNextStepDetails = formatMcpDoctorNextStepDetails;
 exports.parseMcpStatusText = parseMcpStatusText;
 exports.runMcpStatusCanary = runMcpStatusCanary;
 exports.formatMcpStatusCanaryResult = formatMcpStatusCanaryResult;
+exports.formatMcpStatusDoctorResult = formatMcpStatusDoctorResult;
 exports.createMcpStatusCanaryProbe = createMcpStatusCanaryProbe;
 const child_process_1 = require("child_process");
 const path = __importStar(require("path"));
@@ -75,6 +80,65 @@ function parseFields(line) {
     }
     return parsed;
 }
+function shellArg(value) {
+    return /^[A-Za-z0-9._/-]+$/.test(value)
+        ? value
+        : `'${value.replace(/'/g, "'\\''")}'`;
+}
+function buildMcpBridgeRepairGuidance(agent) {
+    const agentArg = shellArg(agent);
+    return {
+        actor: "agent-runnable",
+        commands: [
+            `ouro setup --tool codex --agent ${agentArg}`,
+            `ouro setup --tool claude-code --agent ${agentArg}`,
+        ],
+        reload: "open a fresh dev-tool session after setup; existing MCP processes keep their old runtime",
+        verify: `ouro mcp doctor --agent ${agentArg}`,
+    };
+}
+function formatMcpBridgeRepairDetails(repair) {
+    return [
+        `repair actor=${repair.actor}`,
+        ...repair.commands.map((command) => `repair command=${command}`),
+        `reload required: ${repair.reload}`,
+        `verify command=${repair.verify}`,
+    ];
+}
+function buildMcpDoctorNextSteps(result, agent) {
+    const agentArg = shellArg(agent);
+    const text = [result.summary, ...result.details].join("\n");
+    const daemonUnreachable = text.includes("daemon=unreachable")
+        || text.includes("ECONNREFUSED")
+        || text.includes("ENOENT");
+    if (daemonUnreachable) {
+        return {
+            actor: "agent-runnable",
+            commands: [
+                "ouro up",
+                `ouro mcp doctor --agent ${agentArg}`,
+            ],
+            note: "start or refresh the daemon before trusting bridge status",
+        };
+    }
+    return {
+        actor: "agent-runnable",
+        commands: [
+            "ouro doctor",
+            `ouro status --agent ${agentArg}`,
+            `ouro repair --agent ${agentArg}`,
+            `ouro mcp doctor --agent ${agentArg}`,
+        ],
+        note: "fix reported daemon or sense health before rerunning bridge registration repair",
+    };
+}
+function formatMcpDoctorNextStepDetails(nextSteps) {
+    return [
+        `next actor=${nextSteps.actor}`,
+        ...nextSteps.commands.map((command) => `next command=${command}`),
+        `next note=${nextSteps.note}`,
+    ];
+}
 function parseMcpStatusText(text) {
     const daemon = {};
     const senses = {};
@@ -105,9 +169,10 @@ function validateMcpStatus(parsed, requiredSenses, options = {}) {
     if (!options.ignoreOverviewHealth && parsed.daemon.health !== "ok") {
         failures.push(`health=${parsed.daemon.health ?? "missing"}`);
     }
-    if (parsed.daemon.daemonVersion &&
+    const hasVersionMismatch = !!(parsed.daemon.daemonVersion &&
         parsed.daemon.mcpVersion &&
-        parsed.daemon.daemonVersion !== parsed.daemon.mcpVersion) {
+        parsed.daemon.daemonVersion !== parsed.daemon.mcpVersion);
+    if (hasVersionMismatch) {
         failures.push(`version mismatch daemon=${parsed.daemon.daemonVersion} mcp=${parsed.daemon.mcpVersion}`);
     }
     for (const [sense, row] of Object.entries(parsed.senses)) {
@@ -133,11 +198,16 @@ function validateMcpStatus(parsed, requiredSenses, options = {}) {
     const summary = failures.length === 0
         ? `mcp canary ok: daemon=${parsed.daemon.daemon} health=${parsed.daemon.health}${options.ignoreOverviewHealth ? " (overview ignored)" : ""} senses=${senseSummary}`
         : `mcp canary failed: ${failures.join("; ")}`;
+    const repair = hasVersionMismatch && options.agent
+        ? buildMcpBridgeRepairGuidance(options.agent)
+        : undefined;
+    const repairDetails = repair ? formatMcpBridgeRepairDetails(repair) : [];
     return {
         ok: failures.length === 0,
         summary,
-        details: failures.length === 0 ? [parsed.raw] : [...failures, parsed.raw],
+        details: failures.length === 0 ? [parsed.raw] : [...failures, ...repairDetails, parsed.raw],
         parsed,
+        ...(repair ? { repair } : {}),
     };
 }
 async function runMcpStatusCanary(options) {
@@ -252,6 +322,7 @@ async function runMcpStatusCanary(options) {
         }
         const parsed = parseMcpStatusText(responseText(statusResponse));
         const canary = validateMcpStatus(parsed, requiredSenses, {
+            agent: options.agent,
             ignoreOverviewHealth: options.ignoreOverviewHealth,
         });
         (0, runtime_1.emitNervesEvent)({
@@ -286,6 +357,26 @@ function formatMcpStatusCanaryResult(result) {
         ...result.details.map((line) => `  ${line}`),
     ].join("\n");
 }
+function formatMcpStatusDoctorResult(result, agent) {
+    const rawDetails = result.details.filter((line) => !line.startsWith("repair ")
+        && !line.startsWith("reload required:")
+        && !line.startsWith("verify command="));
+    const lines = [
+        result.ok ? "mcp doctor: ok" : "mcp doctor: failed",
+        result.summary,
+        ...rawDetails.map((line) => `  ${line}`),
+    ];
+    if (result.ok || result.repair) {
+        const repair = result.repair ?? buildMcpBridgeRepairGuidance(agent);
+        lines.push("bridge registration path:");
+        lines.push(...formatMcpBridgeRepairDetails(repair).map((line) => `  ${line}`));
+    }
+    else {
+        lines.push("next checks:");
+        lines.push(...formatMcpDoctorNextStepDetails(buildMcpDoctorNextSteps(result, agent)).map((line) => `  ${line}`));
+    }
+    return lines.join("\n");
+}
 function createMcpStatusCanaryProbe(options) {
     return {
         name: `mcp-canary:${options.agent}`,

package/package.json

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