@ouro.bot/cli 0.1.0-alpha.301 → 0.1.0-alpha.303

package/changelog.json

@@ -2,9 +2,15 @@
   "_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.301",
+      "version": "0.1.0-alpha.303",
       "changes": [
-        "fix(daemon): add an injectable `statusWriter` seam to `DaemonProcessManager` so human-visible config-failure lines still default to stderr in production, but tests can route or silence them intentionally. Status-writer failures are now swallowed with a `daemon.status_writer_error` nerves event instead of breaking agent startup bookkeeping. `process-manager.test.ts` now passes a no-op writer in the snapshot-focused config-check tests that were leaking expected fixture noise into the full coverage log, and adds a regression test proving a throwing status writer does not prevent the crashed snapshot/fix hint from being recorded."
+        "feat(cli): overhaul CLI help and error handling. `ouro --help` now shows commands grouped into 9 categories (Lifecycle, Agents, Chat, Tasks, Habits, Friends, Auth, Internal, System) instead of a flat wall of text. `ouro help <command>` and `ouro <command> --help` show per-command help with description, usage syntax, subcommands, and an example. Unknown commands get Levenshtein-based typo suggestions when distance <= 2 (e.g., `ouro stauts` -> `Did you mean 'status'?`). `ouro up` now prints progress messages: 'Checking for updates...' -> 'Installing <version>...' or 'Up to date.' -> 'Starting daemon...'. New command metadata registry in `src/heart/daemon/cli-help.ts` covers 32 commands. 50+ new tests at 100% coverage on all new code."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.302",
+      "changes": [
+        "feat(cli): add `ouro doctor` system health check command. New command runs 6 diagnostic categories — daemon (socket existence + responsiveness), agents (bundle discovery, agent.json validation for version/humanFacing/agentFacing/enabled), senses (BlueBubbles and Teams config presence and well-formedness), habits (launchd plist discovery, degraded state), security (secrets.json permissions, credential leak detection in agent.json), and disk (log size thresholds at 100MB warn / 500MB critical, bundle root existence). Output is a colored checklist with per-category grouping and a summary line. Works without daemon running — daemon checks fail gracefully while all other categories still execute, making it useful for cold diagnostics. 3 new files (doctor.ts, doctor-types.ts, cli-render-doctor.ts), 3 modified (cli-types.ts, cli-parse.ts, cli-exec.ts), 4 test files with 61 tests at 100% coverage on new code."
       ]
     },
     {

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

@@ -66,8 +66,11 @@ const auth_flow_1 = require("../auth/auth-flow");
 const ouro_version_manager_1 = require("../versioning/ouro-version-manager");
 const cli_parse_1 = require("./cli-parse");
 const cli_parse_2 = require("./cli-parse");
+const cli_help_1 = require("./cli-help");
 const cli_render_1 = require("./cli-render");
 const cli_defaults_1 = require("./cli-defaults");
+const doctor_1 = require("./doctor");
+const cli_render_doctor_1 = require("./cli-render-doctor");
 // ── ensureDaemonRunning ──
 async function ensureDaemonRunning(deps) {
     const alive = await deps.checkSocketAlive(deps.socketPath);
@@ -645,7 +648,7 @@ function resolveClonePath(options, checkExists, deps) {
 // ── Main CLI execution ──
 async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDeps)()) {
     if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
-        const text = (0, cli_parse_2.usage)();
+        const text = (0, cli_help_1.getGroupedHelp)();
         deps.writeStdout(text);
         return text;
     }
@@ -723,6 +726,13 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         message: "ouro CLI command invoked",
         meta: { kind: command.kind },
     });
+    if (command.kind === "help") {
+        const text = command.command
+            ? ((0, cli_help_1.getCommandHelp)(command.command) ?? `Unknown command: ${command.command}\n\n${(0, cli_help_1.getGroupedHelp)()}`)
+            : (0, cli_help_1.getGroupedHelp)();
+        deps.writeStdout(text);
+        return text;
+    }
     if (command.kind === "bluebubbles.replay") {
         const { replayBlueBubblesMessage, formatBlueBubblesReplayText } = await Promise.resolve().then(() => __importStar(require("../../senses/bluebubbles/replay")));
         const replay = await replayBlueBubblesMessage({
@@ -771,10 +781,12 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         const linkedVersionBeforeUp = deps.getCurrentCliVersion?.() ?? null;
         // ── versioned CLI update check ──
         if (deps.checkForCliUpdate) {
+            deps.writeStdout("checking for updates...");
             let pendingReExec = false;
             try {
                 const updateResult = await deps.checkForCliUpdate();
                 if (updateResult.available && updateResult.latestVersion) {
+                    deps.writeStdout(`installing ${updateResult.latestVersion}...`);
                     /* v8 ignore next -- fallback: getCurrentCliVersion always injected in tests @preserve */
                     const currentVersion = linkedVersionBeforeUp ?? "unknown";
                     await deps.installCliVersion(updateResult.latestVersion);
@@ -802,6 +814,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             if (pendingReExec) {
                 deps.reExecFromNewVersion(args);
             }
+            else {
+                deps.writeStdout("up to date.");
+            }
         }
         await performSystemSetup(deps);
         // Track whether we've already printed the "ouro updated to" message
@@ -871,6 +886,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             const count = agents.length;
             deps.writeStdout(`updated ${count} agent${count === 1 ? "" : "s"} to runtime ${to}${fromStr}`);
         }
+        deps.writeStdout("starting daemon...");
         const daemonResult = await ensureDaemonRunning(deps);
         deps.writeStdout(daemonResult.message);
         // Persist boot startup AFTER daemon is running — bootstrap is safe now
@@ -1912,6 +1928,32 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         deps.writeStdout(message);
         return message;
     }
+    // ── doctor (local, no daemon socket needed) ──
+    if (command.kind === "doctor") {
+        const doctorDeps = {
+            /* v8 ignore start -- thin fs wrappers tested via doctor.test.ts with injected deps @preserve */
+            existsSync: (p) => fs.existsSync(p),
+            readFileSync: (p) => fs.readFileSync(p, "utf-8"),
+            readdirSync: (p) => fs.readdirSync(p),
+            statSync: (p) => fs.statSync(p),
+            /* v8 ignore stop */
+            checkSocketAlive: deps.checkSocketAlive,
+            socketPath: deps.socketPath,
+            bundlesRoot: deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(),
+            secretsRoot: deps.secretsRoot ?? path.join(os.homedir(), ".agentsecrets"),
+            homedir: os.homedir(),
+        };
+        const doctorResult = await (0, doctor_1.runDoctorChecks)(doctorDeps);
+        const output = (0, cli_render_doctor_1.formatDoctorOutput)(doctorResult);
+        deps.writeStdout(output);
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.doctor_run",
+            message: "ouro doctor completed",
+            meta: { passed: doctorResult.summary.passed, warnings: doctorResult.summary.warnings, failed: doctorResult.summary.failed },
+        });
+        return output;
+    }
     const daemonCommand = toDaemonCommand(command);
     let response;
     try {

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

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * CLI help system — command registry, grouped help output, and per-command help.
+ *
+ * Pure data + formatting: no side effects, no daemon communication.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMAND_REGISTRY = void 0;
+exports.levenshteinDistance = levenshteinDistance;
+exports.suggestCommand = suggestCommand;
+exports.getGroupedHelp = getGroupedHelp;
+exports.getCommandHelp = getCommandHelp;
+// ── Registry ──
+exports.COMMAND_REGISTRY = {
+    up: {
+        category: "Lifecycle",
+        description: "Start the ouro daemon (default command)",
+        usage: "ouro [up]",
+        example: "ouro up",
+    },
+    stop: {
+        category: "Lifecycle",
+        description: "Stop the running daemon",
+        usage: "ouro stop",
+        example: "ouro stop",
+    },
+    down: {
+        category: "Lifecycle",
+        description: "Stop the running daemon (alias for stop)",
+        usage: "ouro down",
+        example: "ouro down",
+    },
+    status: {
+        category: "Lifecycle",
+        description: "Show daemon status",
+        usage: "ouro status",
+        example: "ouro status",
+    },
+    logs: {
+        category: "Lifecycle",
+        description: "View or prune daemon logs",
+        usage: "ouro logs [prune]",
+        example: "ouro logs",
+        subcommands: ["prune"],
+    },
+    dev: {
+        category: "Lifecycle",
+        description: "Start daemon in development mode from a local repo",
+        usage: "ouro dev [--repo-path <path>] [--clone [--clone-path <path>]]",
+        example: "ouro dev --repo-path ~/code/ouroboros",
+    },
+    hatch: {
+        category: "Lifecycle",
+        description: "Create a new agent",
+        usage: "ouro hatch [--agent <name>] [--human <name>] [--provider <provider>]",
+        example: "ouro hatch --agent Sprout --human Ari --provider anthropic",
+    },
+    rollback: {
+        category: "Lifecycle",
+        description: "Roll back to a previous CLI version",
+        usage: "ouro rollback [<version>]",
+        example: "ouro rollback 0.1.0-alpha.250",
+    },
+    versions: {
+        category: "Lifecycle",
+        description: "List installed CLI versions",
+        usage: "ouro versions",
+        example: "ouro versions",
+    },
+    doctor: {
+        category: "Lifecycle",
+        description: "Run diagnostic checks on the ouro installation",
+        usage: "ouro doctor",
+        example: "ouro doctor",
+    },
+    outlook: {
+        category: "Agents",
+        description: "Show the agent's current outlook",
+        usage: "ouro outlook [--json]",
+        example: "ouro outlook --json",
+    },
+    whoami: {
+        category: "Agents",
+        description: "Show current agent identity info",
+        usage: "ouro whoami [--agent <name>]",
+        example: "ouro whoami",
+    },
+    config: {
+        category: "Agents",
+        description: "View or change agent configuration",
+        usage: "ouro config <subcommand> --agent <name>",
+        example: "ouro config models --agent ouroboros",
+        subcommands: ["model", "models"],
+    },
+    changelog: {
+        category: "Agents",
+        description: "View the agent changelog",
+        usage: "ouro changelog [--from <version>] [--agent <name>]",
+        example: "ouro changelog --from 0.1.0-alpha.250",
+    },
+    chat: {
+        category: "Chat",
+        description: "Open an interactive chat session with an agent",
+        usage: "ouro chat <agent>",
+        example: "ouro chat ouroboros",
+    },
+    msg: {
+        category: "Chat",
+        description: "Send a single message to an agent",
+        usage: "ouro msg --to <agent> [--session <id>] [--task <ref>] <message>",
+        example: "ouro msg --to ouroboros hello there",
+    },
+    task: {
+        category: "Tasks",
+        description: "Manage agent tasks",
+        usage: "ouro task <subcommand> [--agent <name>]",
+        example: "ouro task board",
+        subcommands: ["board", "create", "update", "show", "actionable", "deps", "sessions", "fix"],
+    },
+    poke: {
+        category: "Tasks",
+        description: "Poke an agent about a task or habit",
+        usage: "ouro poke <agent> --task <task-id> | --habit <name>",
+        example: "ouro poke ouroboros --task abc123",
+    },
+    reminder: {
+        category: "Tasks",
+        description: "Create reminders for an agent",
+        usage: "ouro reminder create <title> --body <body> [--at <iso>] [--cadence <interval>]",
+        example: "ouro reminder create standup --body 'daily standup' --cadence '1d'",
+        subcommands: ["create"],
+    },
+    habit: {
+        category: "Habits",
+        description: "Manage agent habits",
+        usage: "ouro habit <subcommand> [--agent <name>]",
+        example: "ouro habit list",
+        subcommands: ["list", "create", "poke"],
+    },
+    friend: {
+        category: "Friends",
+        description: "Manage agent friends and identity links",
+        usage: "ouro friend <subcommand> [--agent <name>]",
+        example: "ouro friend list",
+        subcommands: ["list", "show", "create", "update", "link", "unlink"],
+    },
+    link: {
+        category: "Friends",
+        description: "Link an external identity to an agent friend",
+        usage: "ouro link <agent> --friend <id> --provider <provider> --external-id <eid>",
+        example: "ouro link ouroboros --friend f1 --provider aad --external-id user@example.com",
+    },
+    auth: {
+        category: "Auth",
+        description: "Set up, verify, or switch agent credentials",
+        usage: "ouro auth [verify|switch] --agent <name> [--provider <provider>]",
+        example: "ouro auth --agent ouroboros",
+        subcommands: ["verify", "switch"],
+    },
+    thoughts: {
+        category: "Internal",
+        description: "View agent inner dialog thoughts",
+        usage: "ouro thoughts [--last <n>] [--json] [--follow] [--agent <name>]",
+        example: "ouro thoughts --last 5 --follow",
+    },
+    inner: {
+        category: "Internal",
+        description: "Show inner dialog status",
+        usage: "ouro inner [--agent <name>]",
+        example: "ouro inner",
+    },
+    attention: {
+        category: "Internal",
+        description: "View agent attention items",
+        usage: "ouro attention [show <id>|history] [--agent <name>]",
+        example: "ouro attention history",
+        subcommands: ["show", "history"],
+    },
+    session: {
+        category: "Internal",
+        description: "Manage agent sessions",
+        usage: "ouro session list [--agent <name>]",
+        example: "ouro session list",
+        subcommands: ["list"],
+    },
+    mcp: {
+        category: "System",
+        description: "Interact with MCP servers",
+        usage: "ouro mcp <subcommand>",
+        example: "ouro mcp list",
+        subcommands: ["list", "call"],
+    },
+    "mcp-serve": {
+        category: "System",
+        description: "Start an MCP server for dev tool integration",
+        usage: "ouro mcp-serve --agent <name> [--friend <id>]",
+        example: "ouro mcp-serve --agent ouroboros",
+    },
+    setup: {
+        category: "System",
+        description: "Register MCP server and hooks for a dev tool",
+        usage: "ouro setup --tool <claude-code|codex> --agent <name>",
+        example: "ouro setup --tool claude-code --agent ouroboros",
+    },
+    hook: {
+        category: "System",
+        description: "Fire a dev tool lifecycle hook",
+        usage: "ouro hook <event> --agent <name>",
+        example: "ouro hook session-start --agent ouroboros",
+    },
+    bluebubbles: {
+        category: "System",
+        description: "BlueBubbles integration commands",
+        usage: "ouro bluebubbles replay --agent <name> --message-guid <guid> [--event-type <type>] [--json]",
+        example: "ouro bluebubbles replay --agent ouroboros --message-guid abc123",
+        subcommands: ["replay"],
+    },
+};
+// ── Levenshtein distance ──
+function levenshteinDistance(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const matrix = [];
+    for (let i = 0; i <= a.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= b.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, // deletion
+            matrix[i][j - 1] + 1, // insertion
+            matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[a.length][b.length];
+}
+// ── Command suggestion ──
+function suggestCommand(input) {
+    if (!input)
+        return null;
+    let bestMatch = null;
+    let bestDistance = Infinity;
+    for (const name of Object.keys(exports.COMMAND_REGISTRY)) {
+        const distance = levenshteinDistance(input, name);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            bestMatch = name;
+        }
+    }
+    return bestDistance <= 2 ? bestMatch : null;
+}
+// ── Category display order ──
+const CATEGORY_ORDER = [
+    "Lifecycle",
+    "Agents",
+    "Chat",
+    "Tasks",
+    "Habits",
+    "Friends",
+    "Auth",
+    "Internal",
+    "System",
+];
+// ── Grouped help output ──
+function getGroupedHelp() {
+    const lines = ["Usage: ouro <command> [options]", ""];
+    for (const category of CATEGORY_ORDER) {
+        lines.push(`  ${category}:`);
+        for (const [name, entry] of Object.entries(exports.COMMAND_REGISTRY)) {
+            if (entry.category === category) {
+                lines.push(`    ${name.padEnd(16)} ${entry.description}`);
+            }
+        }
+        lines.push("");
+    }
+    lines.push("Run 'ouro help <command>' for details on a specific command.");
+    return lines.join("\n");
+}
+// ── Per-command help ──
+function getCommandHelp(name) {
+    const entry = exports.COMMAND_REGISTRY[name];
+    if (!entry)
+        return null;
+    const lines = [
+        `${name} - ${entry.description}`,
+        "",
+        `Usage: ${entry.usage}`,
+    ];
+    if (entry.subcommands && entry.subcommands.length > 0) {
+        lines.push("");
+        lines.push("Subcommands:");
+        for (const sub of entry.subcommands) {
+            lines.push(`  ${sub}`);
+        }
+    }
+    if (entry.example) {
+        lines.push("");
+        lines.push(`Example: ${entry.example}`);
+    }
+    return lines.join("\n");
+}

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

@@ -13,6 +13,7 @@ exports.usage = usage;
 exports.parseMcpServeCommand = parseMcpServeCommand;
 exports.parseOuroCommand = parseOuroCommand;
 const types_1 = require("../../mind/friends/types");
+const cli_help_1 = require("./cli-help");
 // ── Shared helpers ──
 function extractAgentFlag(args) {
     const idx = args.indexOf("--agent");
@@ -78,6 +79,7 @@ function usage() {
         "  ouro mcp call <server> <tool> [--args '{...}']",
         "  ouro rollback [<version>]",
         "  ouro versions",
+        "  ouro doctor",
     ].join("\n");
 }
 // ── Per-group parsers ──
@@ -685,6 +687,14 @@ function parseOuroCommand(args) {
     const [head, second] = args;
     if (!head)
         return { kind: "daemon.up" };
+    // ── help command ──
+    if (head === "help") {
+        return second ? { kind: "help", command: second } : { kind: "help" };
+    }
+    // ── per-command --help ──
+    if (args.includes("--help")) {
+        return { kind: "help", command: head };
+    }
     if (head === "--agent" && second) {
         return parseOuroCommand(args.slice(2));
     }
@@ -802,7 +812,11 @@ function parseOuroCommand(args) {
         return parseMcpServeCommand(args.slice(1));
     if (head === "setup")
         return parseSetupCommand(args.slice(1));
+    if (head === "doctor")
+        return { kind: "doctor" };
     if (head === "bluebubbles")
         return parseBlueBubblesCommand(args.slice(1));
-    throw new Error(`Unknown command '${args.join(" ")}'.\n${usage()}`);
+    const suggestion = (0, cli_help_1.suggestCommand)(head);
+    const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
+    throw new Error(`Unknown command '${args.join(" ")}'.${hint}\n${usage()}`);
 }

package/dist/heart/daemon/cli-render-doctor.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Rendering for `ouro doctor` output.
+ *
+ * Pure function: takes a DoctorResult and returns a formatted string
+ * with ANSI colors, category grouping, and a summary line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDoctorOutput = formatDoctorOutput;
+// ── ANSI color helpers ──
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[38;2;46;204;64m";
+const RED = "\x1b[38;2;231;76;60m";
+const YELLOW = "\x1b[38;2;230;190;50m";
+const TEAL = "\x1b[38;2;78;201;176m";
+function green(text) { return `${GREEN}${text}${RESET}`; }
+function red(text) { return `${RED}${text}${RESET}`; }
+function yellow(text) { return `${YELLOW}${text}${RESET}`; }
+function bold(text) { return `${BOLD}${text}${RESET}`; }
+function dim(text) { return `${DIM}${text}${RESET}`; }
+function teal(text) { return `${TEAL}${text}${RESET}`; }
+// ── Check status symbols ──
+function statusSymbol(status) {
+    switch (status) {
+        case "pass": return green("\u2714"); // checkmark
+        case "warn": return yellow("\u26A0"); // warning
+        case "fail": return red("\u2718"); // X
+    }
+}
+// ── Main formatter ──
+function formatDoctorOutput(result) {
+    const lines = [];
+    lines.push("");
+    lines.push(`  ${bold("ouro doctor")}`);
+    lines.push("");
+    for (const category of result.categories) {
+        lines.push(`  ${teal("--")} ${bold(category.name)} ${teal("-".repeat(Math.max(1, 40 - category.name.length)))}`);
+        for (const check of category.checks) {
+            const symbol = statusSymbol(check.status);
+            const detail = check.detail ? `  ${dim(check.detail)}` : "";
+            lines.push(`    ${symbol} ${check.label}${detail}`);
+        }
+        lines.push("");
+    }
+    // Summary line
+    const { passed, warnings, failed } = result.summary;
+    const parts = [
+        green(`${passed} passed`),
+        yellow(`${warnings} warning${warnings === 1 ? "" : "s"}`),
+        red(`${failed} failed`),
+    ];
+    lines.push(`  ${parts.join(dim("  |  "))}`);
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/heart/daemon/doctor-types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Type definitions for the `ouro doctor` system health check.
+ *
+ * Describes the structure of health check results: individual checks,
+ * grouped categories, and the aggregated result.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/heart/daemon/doctor.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * System health check ("ouro doctor") — runs all diagnostic categories
+ * and aggregates results into a structured DoctorResult.
+ *
+ * Each category checker is isolated: if one throws, it produces a single
+ * "fail" check and the remaining categories still run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkDaemon = checkDaemon;
+exports.checkAgents = checkAgents;
+exports.checkSenses = checkSenses;
+exports.checkHabits = checkHabits;
+exports.checkSecurity = checkSecurity;
+exports.checkDisk = checkDisk;
+exports.runDoctorChecks = runDoctorChecks;
+const runtime_1 = require("../../nerves/runtime");
+// ── Category checkers ──
+async function checkDaemon(deps) {
+    const checks = [];
+    const socketExists = deps.existsSync(deps.socketPath);
+    checks.push({
+        label: "daemon socket exists",
+        status: socketExists ? "pass" : "fail",
+        detail: socketExists ? deps.socketPath : `not found at ${deps.socketPath}`,
+    });
+    if (socketExists) {
+        const alive = await deps.checkSocketAlive(deps.socketPath);
+        checks.push({
+            label: "daemon is responsive",
+            status: alive ? "pass" : "fail",
+            detail: alive ? "socket responded" : "socket exists but daemon unresponsive",
+        });
+    }
+    else {
+        checks.push({
+            label: "daemon is responsive",
+            status: "fail",
+            detail: "skipped — socket missing",
+        });
+    }
+    return { name: "Daemon", checks };
+}
+/** Discover all *.ouro directories under bundlesRoot. */
+function discoverAgents(deps) {
+    if (!deps.existsSync(deps.bundlesRoot))
+        return [];
+    return deps.readdirSync(deps.bundlesRoot).filter((name) => name.endsWith(".ouro"));
+}
+function checkAgents(deps) {
+    const checks = [];
+    if (!deps.existsSync(deps.bundlesRoot)) {
+        checks.push({ label: "bundles directory", status: "fail", detail: `${deps.bundlesRoot} not found` });
+        return { name: "Agents", checks };
+    }
+    const agents = discoverAgents(deps);
+    if (agents.length === 0) {
+        checks.push({ label: "agent bundles", status: "warn", detail: "no *.ouro bundles found" });
+        return { name: "Agents", checks };
+    }
+    for (const agentDir of agents) {
+        const agentPath = `${deps.bundlesRoot}/${agentDir}`;
+        const configPath = `${agentPath}/agent.json`;
+        if (!deps.existsSync(configPath)) {
+            checks.push({ label: `${agentDir}/agent.json`, status: "fail", detail: "missing" });
+            continue;
+        }
+        let config;
+        try {
+            config = JSON.parse(deps.readFileSync(configPath));
+        }
+        catch {
+            checks.push({ label: `${agentDir}/agent.json`, status: "fail", detail: "unparseable JSON" });
+            continue;
+        }
+        const missing = [];
+        if (!config.version)
+            missing.push("version");
+        if (!config.humanFacing || typeof config.humanFacing !== "object") {
+            missing.push("humanFacing");
+        }
+        else {
+            const hf = config.humanFacing;
+            if (!hf.provider)
+                missing.push("humanFacing.provider");
+            if (!hf.model)
+                missing.push("humanFacing.model");
+        }
+        if (!config.agentFacing || typeof config.agentFacing !== "object") {
+            missing.push("agentFacing");
+        }
+        else {
+            const af = config.agentFacing;
+            if (!af.provider)
+                missing.push("agentFacing.provider");
+            if (!af.model)
+                missing.push("agentFacing.model");
+        }
+        if (missing.length > 0) {
+            checks.push({ label: `${agentDir}/agent.json`, status: "warn", detail: `missing fields: ${missing.join(", ")}` });
+        }
+        else {
+            checks.push({ label: `${agentDir}/agent.json`, status: "pass", detail: "valid" });
+        }
+    }
+    return { name: "Agents", checks };
+}
+function checkSenses(deps) {
+    const checks = [];
+    const agents = discoverAgents(deps);
+    for (const agentDir of agents) {
+        const configPath = `${deps.bundlesRoot}/${agentDir}/agent.json`;
+        if (!deps.existsSync(configPath))
+            continue;
+        let config;
+        try {
+            config = JSON.parse(deps.readFileSync(configPath));
+        }
+        catch {
+            checks.push({ label: `${agentDir} senses`, status: "fail", detail: "agent.json unparseable" });
+            continue;
+        }
+        if (!config.senses || typeof config.senses !== "object") {
+            checks.push({ label: `${agentDir} senses`, status: "warn", detail: "no senses config block" });
+            continue;
+        }
+        const senses = config.senses;
+        const senseNames = ["cli", "teams", "bluebubbles"];
+        for (const sense of senseNames) {
+            if (!(sense in senses))
+                continue;
+            const entry = senses[sense];
+            if (!entry || typeof entry !== "object") {
+                checks.push({ label: `${agentDir} ${sense}`, status: "fail", detail: "malformed sense entry" });
+                continue;
+            }
+            const senseObj = entry;
+            if (typeof senseObj.enabled !== "boolean") {
+                checks.push({ label: `${agentDir} ${sense}`, status: "warn", detail: "missing enabled boolean" });
+            }
+            else {
+                checks.push({
+                    label: `${agentDir} ${sense}`,
+                    status: "pass",
+                    detail: senseObj.enabled ? "enabled" : "disabled",
+                });
+            }
+        }
+    }
+    if (checks.length === 0) {
+        checks.push({ label: "senses", status: "warn", detail: "no agents with senses config found" });
+    }
+    return { name: "Senses", checks };
+}
+function checkHabits(deps) {
+    const checks = [];
+    const agents = discoverAgents(deps);
+    for (const agentDir of agents) {
+        const agentName = agentDir.replace(/\.ouro$/, "");
+        const habitsDir = `${deps.bundlesRoot}/${agentDir}/habits`;
+        if (!deps.existsSync(habitsDir)) {
+            checks.push({ label: `${agentDir} habits dir`, status: "warn", detail: "no habits directory" });
+            continue;
+        }
+        checks.push({ label: `${agentDir} habits dir`, status: "pass", detail: habitsDir });
+        // Check for launchd plists on macOS
+        const launchAgentsDir = `${deps.homedir}/Library/LaunchAgents`;
+        if (deps.existsSync(launchAgentsDir)) {
+            const plists = deps.readdirSync(launchAgentsDir).filter((f) => f.startsWith(`bot.ouro.${agentName}.`) && f.endsWith(".plist"));
+            if (plists.length > 0) {
+                checks.push({ label: `${agentDir} launchd plists`, status: "pass", detail: `${plists.length} plist(s)` });
+            }
+            else {
+                checks.push({ label: `${agentDir} launchd plists`, status: "fail", detail: "no matching plists in LaunchAgents" });
+            }
+        }
+    }
+    if (checks.length === 0) {
+        checks.push({ label: "habits", status: "warn", detail: "no agents found" });
+    }
+    return { name: "Habits", checks };
+}
+function checkSecurity(deps) {
+    const checks = [];
+    const agents = discoverAgents(deps);
+    for (const agentDir of agents) {
+        const agentName = agentDir.replace(/\.ouro$/, "");
+        const secretsPath = `${deps.secretsRoot}/${agentName}/secrets.json`;
+        if (!deps.existsSync(secretsPath)) {
+            checks.push({ label: `${agentDir} secrets.json`, status: "fail", detail: "missing" });
+            continue;
+        }
+        // Check file permissions
+        const stat = deps.statSync(secretsPath);
+        const worldReadable = (stat.mode & 0o004) !== 0;
+        if (worldReadable) {
+            checks.push({ label: `${agentDir} secrets.json perms`, status: "warn", detail: "world-readable — consider chmod 600" });
+        }
+        else {
+            checks.push({ label: `${agentDir} secrets.json perms`, status: "pass", detail: "not world-readable" });
+        }
+        // Check agent.json for leaked credential keys
+        const configPath = `${deps.bundlesRoot}/${agentDir}/agent.json`;
+        if (deps.existsSync(configPath)) {
+            try {
+                const raw = deps.readFileSync(configPath);
+                const sensitiveKeys = ["apiKey", "token", "secret", "password"];
+                const found = sensitiveKeys.filter((key) => raw.includes(`"${key}"`));
+                if (found.length > 0) {
+                    checks.push({ label: `${agentDir} credential leak`, status: "warn", detail: `agent.json contains keys: ${found.join(", ")}` });
+                }
+                else {
+                    checks.push({ label: `${agentDir} credential leak`, status: "pass", detail: "no credential keys in agent.json" });
+                }
+            }
+            catch {
+                checks.push({ label: `${agentDir} credential leak`, status: "fail", detail: "could not read agent.json" });
+            }
+        }
+    }
+    if (checks.length === 0) {
+        checks.push({ label: "security", status: "warn", detail: "no agents found" });
+    }
+    return { name: "Security", checks };
+}
+function checkDisk(deps) {
+    const checks = [];
+    // Check daemon logs directory
+    const logsDir = `${deps.homedir}/.ouro-cli/logs`;
+    if (!deps.existsSync(logsDir)) {
+        checks.push({ label: "daemon logs dir", status: "warn", detail: `${logsDir} not found` });
+    }
+    else {
+        let totalSize = 0;
+        try {
+            const files = deps.readdirSync(logsDir);
+            for (const file of files) {
+                try {
+                    const stat = deps.statSync(`${logsDir}/${file}`);
+                    totalSize += stat.size;
+                }
+                catch {
+                    // skip unreadable files
+                }
+            }
+        }
+        catch {
+            // readdirSync failure handled below
+        }
+        const sizeMB = totalSize / (1024 * 1024);
+        if (sizeMB > 500) {
+            checks.push({ label: "daemon log size", status: "fail", detail: `${sizeMB.toFixed(1)}MB — exceeds 500MB limit` });
+        }
+        else if (sizeMB > 100) {
+            checks.push({ label: "daemon log size", status: "warn", detail: `${sizeMB.toFixed(1)}MB — consider pruning with \`ouro logs prune\`` });
+        }
+        else {
+            checks.push({ label: "daemon log size", status: "pass", detail: `${sizeMB.toFixed(1)}MB` });
+        }
+    }
+    // Check AgentBundles root
+    if (deps.existsSync(deps.bundlesRoot)) {
+        checks.push({ label: "bundles root", status: "pass", detail: deps.bundlesRoot });
+    }
+    else {
+        checks.push({ label: "bundles root", status: "warn", detail: `${deps.bundlesRoot} not found` });
+    }
+    return { name: "Disk", checks };
+}
+// ── Orchestrator ──
+function computeSummary(categories) {
+    let passed = 0;
+    let warnings = 0;
+    let failed = 0;
+    for (const cat of categories) {
+        for (const check of cat.checks) {
+            /* v8 ignore next 3 -- all three branches tested; v8 misreports compound if/else-if chain @preserve */
+            if (check.status === "pass")
+                passed++;
+            else if (check.status === "warn")
+                warnings++;
+            else
+                failed++;
+        }
+    }
+    return { passed, warnings, failed };
+}
+const CATEGORY_CHECKERS = [
+    { name: "Daemon", fn: checkDaemon },
+    { name: "Agents", fn: checkAgents },
+    { name: "Senses", fn: checkSenses },
+    { name: "Habits", fn: checkHabits },
+    { name: "Security", fn: checkSecurity },
+    { name: "Disk", fn: checkDisk },
+];
+async function runDoctorChecks(deps) {
+    const categories = [];
+    for (const checker of CATEGORY_CHECKERS) {
+        try {
+            const category = await Promise.resolve(checker.fn(deps));
+            categories.push(category);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "daemon",
+                event: "daemon.doctor_check_error",
+                message: `doctor check ${checker.name} failed`,
+                meta: { category: checker.name, error: error instanceof Error ? error.message : String(error) },
+            });
+            categories.push({
+                name: checker.name,
+                checks: [{
+                        label: checker.name.toLowerCase(),
+                        status: "fail",
+                        detail: `check crashed: ${error instanceof Error ? error.message : String(error)}`,
+                    }],
+            });
+        }
+    }
+    return { categories, summary: computeSummary(categories) };
+}

package/dist/nerves/coverage/file-completeness.js

@@ -59,9 +59,10 @@ const DISPATCH_EXEMPT_PATTERNS = [
     "repertoire/tools-config",
     "repertoire/tools-base",
     // CLI sub-modules: cli-exec.ts is the router with emitNervesEvent calls;
-    // cli-parse and cli-render are pure functions with no side effects.
+    // cli-parse, cli-render, and cli-help are pure functions/data with no side effects.
     "daemon/cli-parse",
     "daemon/cli-render",
+    "daemon/cli-help",
     // Shared utility modules: pure helpers consumed by modules that own observability.
     "arc/json-store",
     "repertoire/api-client",

package/package.json

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