@mono-agent/agent-app 0.4.0 → 0.5.0

package/dist/cli.js

@@ -1,16 +1,29 @@
 #!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
 import { stat } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { basename, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { buildMonoAgentConfigView, findJsonSecretConfigWarnings, findRemovedConfigWarnings, readMonoAgentConfigJson, redactMonoAgentConfig, } from "@mono-agent/config";
+import { listRecordedRuns } from "@mono-agent/observability";
+import { describeSandboxEffectiveState, sandboxEffectiveStateWarning, } from "@mono-agent/runtime-adapter";
 import { startMonoAgentApp } from "./app.js";
-import { phoenixAppBaseUrl } from "./app-config.js";
+import { describeSensitiveDataExportWarning, isAppCoreConfigError, loadAppCoreConfig, phoenixAppBaseUrl, } from "./app-config.js";
+import { runAuditRuns } from "./audit-runs.js";
 import { runBackfill } from "./backfill.js";
 import { defaultBackgroundDeps, resolveInstanceTarget, restartBackground, startBackground, statusBackground, stopBackground, tailLogs, } from "./background.js";
+import { collectChannelConfigViews } from "./channel-config-view.js";
+import { resolveChannelDrivers } from "./channels.js";
+import { findUnknownAppConfigWarnings } from "./config-reference.js";
 import { validateMonoAgentFolder } from "./doctor.js";
-import { initMonoAgentFolder } from "./init.js";
+import { initMonoAgentFolder, isWithChannel } from "./init.js";
 import { installComposerSkill } from "./install-skill.js";
+import { runMetrics } from "./metrics.js";
+import { findRecipe, RECIPE_CATALOG, recipeIds, resolveRecipeInputs } from "./recipes/index.js";
+import { buildRunsHealthDisplay, RUNS_HEALTH_MAX_RUNS } from "./runs-health.js";
 import { purgeSessions } from "./sessions.js";
+import { collectSetupOptions } from "./setup.js";
 import * as ui from "./ui.js";
 const DEFAULT_LOG_LINES = 200;
 // Node's maximum setInterval/setTimeout delay (2^31 - 1 ms, ~24.8 days). A
@@ -18,21 +31,29 @@ const DEFAULT_LOG_LINES = 200;
 // busy-waiting; larger values silently overflow to a 1ms delay.
 const KEEP_ALIVE_INTERVAL_MS = 2_147_483_647;
 const BACKGROUND_COMMANDS = ["start", "restart", "stop", "status", "logs"];
-const KNOWN_COMMANDS = ["init", "validate", "start", "restart", "stop", "status", "logs", "install-skill", "backfill"];
+const KNOWN_COMMANDS = ["init", "setup", "validate", "doctor", "config", "recipes", "start", "restart", "stop", "status", "logs", "tui", "web", "install-skill", "backfill", "audit-runs", "metrics", "memory"];
 export function parseCliArgs(argv) {
     const [command, ...rest] = argv;
     if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-        return { command: "help", force: false, foreground: false, follow: false, all: false, dryRun: false };
+        return { command: "help", positionals: [], force: false, foreground: false, follow: false, all: false, dryRun: false, includeMemory: false };
+    }
+    if (command === "version" || command === "--version" || command === "-v") {
+        return { command: "version", positionals: [], force: false, foreground: false, follow: false, all: false, dryRun: false, includeMemory: false };
     }
     if (!KNOWN_COMMANDS.includes(command)) {
         throw new Error(`Unknown command \`${command}\`. Expected ${KNOWN_COMMANDS.join(", ")}.`);
     }
-    const cmd = command;
+    // `doctor` is an alias of `validate`; normalize here so every downstream
+    // validate path (env-file resolution, --consumer, routing) applies unchanged.
+    const cmd = (command === "doctor" ? "validate" : command);
     const isLogs = cmd === "logs";
     let configPath;
     let model;
     let fallbackModels;
     let memory;
+    let recipe;
+    let withChannels;
+    const positionals = [];
     let envFile;
     let target;
     let force = false;
@@ -44,6 +65,20 @@ export function parseCliArgs(argv) {
     let since;
     let until;
     let dryRun = false;
+    let includeMemory = false;
+    let artifactDir;
+    let groupBy;
+    let consumerPath;
+    let agent;
+    let conversation;
+    let staleAfterMs;
+    let json = false;
+    let limit;
+    let host;
+    let port;
+    let open;
+    let allowNonLoopback;
+    let maxRunsPerInstance;
     for (let i = 0; i < rest.length; i += 1) {
         const flag = rest[i];
         switch (flag) {
@@ -65,6 +100,80 @@ export function parseCliArgs(argv) {
             case "--dry-run":
                 dryRun = true;
                 break;
+            case "--include-memory":
+                includeMemory = true;
+                break;
+            case "--artifact-dir":
+                artifactDir = requireValue(rest, ++i, flag);
+                break;
+            case "--artifacts":
+                artifactDir = requireValue(rest, ++i, flag);
+                break;
+            case "--by": {
+                const raw = requireValue(rest, ++i, flag);
+                if (raw !== "model" && raw !== "channel" && raw !== "failureKind") {
+                    throw new Error("--by must be model, channel, or failureKind.");
+                }
+                groupBy = raw;
+                break;
+            }
+            case "--consumer":
+                consumerPath = requireValue(rest, ++i, flag);
+                break;
+            case "--agent":
+                agent = requireValue(rest, ++i, flag);
+                break;
+            case "--conversation":
+                conversation = requireValue(rest, ++i, flag);
+                break;
+            case "--stale-after-ms": {
+                const raw = requireValue(rest, ++i, flag);
+                const parsed = Number(raw);
+                if (!Number.isInteger(parsed) || parsed < 1) {
+                    throw new Error("--stale-after-ms must be a positive integer.");
+                }
+                staleAfterMs = parsed;
+                break;
+            }
+            case "--json":
+                json = true;
+                break;
+            case "--limit": {
+                const raw = requireValue(rest, ++i, flag);
+                const parsed = Number(raw);
+                if (!Number.isInteger(parsed) || parsed < 1 || parsed > 100) {
+                    throw new Error("--limit must be an integer between 1 and 100.");
+                }
+                limit = parsed;
+                break;
+            }
+            case "--host":
+                host = requireValue(rest, ++i, flag);
+                break;
+            case "--port": {
+                const raw = requireValue(rest, ++i, flag);
+                const parsed = Number(raw);
+                if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+                    throw new Error("--port must be an integer between 0 and 65535.");
+                }
+                port = parsed;
+                break;
+            }
+            case "--no-open":
+                open = false;
+                break;
+            case "--allow-non-loopback":
+                allowNonLoopback = true;
+                break;
+            case "--max-runs": {
+                const raw = requireValue(rest, ++i, flag);
+                const parsed = Number(raw);
+                if (!Number.isInteger(parsed) || parsed < 1) {
+                    throw new Error("--max-runs must be a positive integer.");
+                }
+                maxRunsPerInstance = parsed;
+                break;
+            }
             case "--model":
                 model = requireValue(rest, ++i, flag);
                 break;
@@ -82,6 +191,15 @@ export function parseCliArgs(argv) {
                 memory = raw;
                 break;
             }
+            case "--recipe":
+                recipe = requireValue(rest, ++i, flag);
+                break;
+            case "--with":
+                withChannels = requireValue(rest, ++i, flag)
+                    .split(",")
+                    .map((entry) => entry.trim())
+                    .filter((entry) => entry.length > 0);
+                break;
             case "--env-file":
                 envFile = requireValue(rest, ++i, flag);
                 break;
@@ -121,15 +239,39 @@ export function parseCliArgs(argv) {
                 break;
             }
             default:
-                throw new Error(`Unknown flag \`${flag}\` for \`mono-agent ${command}\`.`);
+                if (flag === undefined) {
+                    break;
+                }
+                if (flag.startsWith("--")) {
+                    throw new Error(`Unknown flag \`${flag}\` for \`mono-agent ${command}\`.`);
+                }
+                // Non-flag tokens are positional arguments (e.g. `recipes show <id>`).
+                positionals.push(flag);
+                break;
         }
     }
+    if (consumerPath !== undefined && cmd !== "validate" && cmd !== "audit-runs") {
+        throw new Error("--consumer is only supported for `mono-agent validate` and `mono-agent audit-runs`.");
+    }
+    if ((host !== undefined || port !== undefined || open !== undefined || allowNonLoopback !== undefined || maxRunsPerInstance !== undefined) &&
+        cmd !== "web") {
+        throw new Error("--host, --port, --no-open, --allow-non-loopback, and --max-runs are only supported for `mono-agent web`.");
+    }
+    if (includeMemory && cmd !== "audit-runs" && cmd !== "metrics" && cmd !== "backfill" && cmd !== "web") {
+        throw new Error("--include-memory is only supported for `mono-agent audit-runs`, `mono-agent metrics`, `mono-agent backfill`, and `mono-agent web`.");
+    }
+    if (limit !== undefined && cmd !== "memory") {
+        throw new Error("--limit is only supported for `mono-agent memory`.");
+    }
     return {
         command: cmd,
         ...(configPath === undefined ? {} : { configPath }),
         ...(model === undefined ? {} : { model }),
         ...(fallbackModels === undefined ? {} : { fallbackModels }),
         ...(memory === undefined ? {} : { memory }),
+        ...(recipe === undefined ? {} : { recipe }),
+        ...(withChannels === undefined ? {} : { withChannels }),
+        positionals,
         ...(envFile === undefined ? {} : { envFile }),
         ...(target === undefined ? {} : { target }),
         force,
@@ -141,6 +283,20 @@ export function parseCliArgs(argv) {
         ...(since === undefined ? {} : { since }),
         ...(until === undefined ? {} : { until }),
         dryRun,
+        includeMemory,
+        ...(artifactDir === undefined ? {} : { artifactDir }),
+        ...(groupBy === undefined ? {} : { groupBy }),
+        ...(consumerPath === undefined ? {} : { consumerPath }),
+        ...(staleAfterMs === undefined ? {} : { staleAfterMs }),
+        ...(json ? { json } : {}),
+        ...(limit === undefined ? {} : { limit }),
+        ...(agent === undefined ? {} : { agent }),
+        ...(conversation === undefined ? {} : { conversation }),
+        ...(host === undefined ? {} : { host }),
+        ...(port === undefined ? {} : { port }),
+        ...(open === undefined ? {} : { open }),
+        ...(allowNonLoopback === undefined ? {} : { allowNonLoopback }),
+        ...(maxRunsPerInstance === undefined ? {} : { maxRunsPerInstance }),
     };
 }
 /**
@@ -157,6 +313,15 @@ export function loadCliEnvFile(path) {
         return false;
     }
 }
+function resolveValidateContext(args, invocationCwd) {
+    const cwd = resolve(invocationCwd, args.consumerPath ?? ".");
+    return {
+        cwd,
+        configPath: resolve(cwd, args.configPath ?? "mono-agent.config.json"),
+        envFilePath: resolve(cwd, args.envFile ?? ".env"),
+        allowFilesystemWrites: args.consumerPath === undefined,
+    };
+}
 function requireValue(args, index, flag) {
     const value = args[index];
     if (value === undefined || value.startsWith("--")) {
@@ -166,15 +331,45 @@ function requireValue(args, index, flag) {
 }
 const HELP_COMMANDS = [
     {
-        signature: "mono-agent init [--model <ref>] [--fallback-models <csv>] [--memory lite|journal|bujo]",
+        signature: "mono-agent init [--recipe <id>] [--with <csv>] [--dry-run]\n" +
+            "                [--model <ref>] [--fallback-models <csv>] [--memory lite|journal|bujo]",
         lines: [
             "Scaffold mono-agent.config.json, IDENTITY.md, and .mono-agent/ in the",
-            "current folder. Existing files are never overwritten.",
+            "current folder. With --recipe, build from a blueprint (+ .env.example);",
+            "--with adds channels, --dry-run previews. Existing files are never overwritten.",
         ],
     },
     {
-        signature: "mono-agent validate [--config <path>] [--env-file <path>]",
-        lines: ["Load every config section and report what would run, wait, or fail."],
+        signature: "mono-agent setup [--recipe <id>] [--with <csv>] [--dry-run]\n" +
+            "                 [--model <ref>] [--fallback-models <csv>] [--memory lite|journal|bujo]",
+        lines: [
+            "Guided setup when attached to a TTY: choose a recipe, answer non-secret",
+            "inputs, select channel add-ons, scaffold, validate, and print the secrets",
+            "checklist. In non-TTY contexts it falls back to init-style flags.",
+        ],
+    },
+    {
+        signature: "mono-agent recipes list | show <id>",
+        lines: [
+            "List the executable config blueprints, or show one's generated config,",
+            ".env.example, and follow-up checklist.",
+        ],
+    },
+    {
+        signature: "mono-agent validate [--recipe <id>] [--consumer <path>] [--config <path>] [--env-file <path>]",
+        lines: [
+            "Load every config section and report what would run, wait, or fail.",
+            "--consumer validates another agent folder read-only, including its .env.",
+            "With --recipe, also report whether the recipe's capabilities are live.",
+            "`mono-agent doctor` is an alias for this command.",
+        ],
+    },
+    {
+        signature: "mono-agent config [--config <path>] [--env-file <path>]",
+        lines: [
+            "Print the resolved config field-by-field, tagging each value with where",
+            "it came from (env / json / default), plus the channel summary. Read-only.",
+        ],
     },
     {
         signature: "mono-agent start [--config <path>] [--env-file <path>] [--foreground|-f]",
@@ -205,21 +400,70 @@ const HELP_COMMANDS = [
         signature: "mono-agent logs [--config <path>] [--follow|-f] [--lines <n>]",
         lines: ["Print (and optionally follow) the background instance's log files."],
     },
+    {
+        signature: "mono-agent tui [--agent <label|sourceId>] [--conversation <id>]",
+        lines: [
+            "Open the operator console from any directory: live chat with full",
+            "thinking/tool/telemetry insight, recorded-run replay, and config view.",
+            "Discovers running agents via the trace-source registry; one running",
+            "agent connects directly, several open a picker.",
+        ],
+    },
+    {
+        signature: "mono-agent web [--host <addr>] [--port <n>] [--no-open] [--allow-non-loopback] [--include-memory] [--max-runs <n>]",
+        lines: [
+            "Serve the read-only Session Recorder web PWA from any directory: a live",
+            "flight-recorder over every agent's runs (prompt, reasoning, tools, cost).",
+            "Discovers running agents via the trace-source registry — the same",
+            "mechanism as `tui` — and streams new/updated runs in real time.",
+            "--include-memory also shows memory-maintenance runs. --max-runs (default",
+            "200) bounds the in-memory working set; the UI still pages the full",
+            "on-disk history via \"Load older\".",
+        ],
+    },
     {
         signature: "mono-agent install-skill [--target claude|codex|both] [--force]",
         lines: [
             "Copy the bundled mono-agent-composer skill into ~/.claude/skills and",
-            "~/.codex/skills (default: both). Refuses to overwrite without --force.",
+            "~/.agents/skills (default: both). Refuses to overwrite without --force.",
         ],
     },
     {
         signature: "mono-agent backfill (--run <id> | --all) [--since <iso>] [--until <iso>]\n" +
-            "                    [--dry-run] [--config <path>] [--env-file <path>]",
+            "                    [--include-memory] [--dry-run] [--config <path>] [--env-file <path>]",
         lines: [
-            "Export already-recorded run artifacts to the configured Phoenix exporter",
+            "Export already-recorded agent-run artifacts to the configured Phoenix exporter",
             "with their historical timestamps. Trace ids are deterministic per run, so",
             "re-running overwrites rather than duplicating. --dry-run maps and",
-            "serializes without sending.",
+            "serializes without sending. --include-memory adds memory-run artifacts",
+            "for --all; explicit --run can target a memory run directly.",
+        ],
+    },
+    {
+        signature: "mono-agent audit-runs [--artifact-dir <path> | --consumer <path>]\n" +
+            "                      [--include-memory] [--config <path>] [--env-file <path>] [--stale-after-ms <n>] [--json]",
+        lines: [
+            "Read local agent-run summary artifacts without rewriting them. Reports parse",
+            "failures, status and failure-kind histograms, stale running summaries,",
+            "and per-failure-kind rates. --include-memory includes memory-run artifacts.",
+        ],
+    },
+    {
+        signature: "mono-agent metrics [--artifacts <path>] [--since <iso>] [--until <iso>]\n" +
+            "                   [--include-memory] [--by model|channel|failureKind] [--json] [--config <path>] [--env-file <path>]",
+        lines: [
+            "Aggregate local agent-run summaries into status rates, failure-kind rates,",
+            "duration percentiles, and total/per-run cost. Read-only and offline.",
+            "--include-memory includes memory-run artifacts.",
+        ],
+    },
+    {
+        signature: "mono-agent memory [stats|today|show <date>|search <query>|top]\n" +
+            "                  [--limit <n>] [--json] [--config <path>] [--env-file <path>]",
+        lines: [
+            "Preview the configured memory store from an agent folder. Reads the",
+            "memory block from mono-agent.config.json, not the standalone memory-bujo",
+            "env workflow. Human-first output by default; --json is for scripts.",
         ],
     },
 ];
@@ -252,6 +496,22 @@ export function renderHelp() {
     out += ui.style.dim(HELP_NOTES);
     return out;
 }
+/**
+ * The published CLI version, read from this package's own package.json at
+ * runtime. `../package.json` resolves the same from both `src/cli.ts` (tests) and
+ * the built `dist/cli.js` (one level below the package root in both layouts), and
+ * npm always ships package.json in the tarball. Best-effort: a read failure yields
+ * "unknown" rather than crashing `--version`.
+ */
+export function monoAgentVersion() {
+    try {
+        const pkg = createRequire(import.meta.url)("../package.json");
+        return typeof pkg.version === "string" && pkg.version.length > 0 ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 export async function runCli(argv) {
     let args;
     try {
@@ -262,15 +522,27 @@ export async function runCli(argv) {
         process.stdout.write(`\n${renderHelp()}`);
         return 2;
     }
-    loadCliEnvFile(resolve(process.cwd(), args.envFile ?? ".env"));
+    const invocationCwd = process.cwd();
+    loadCliEnvFile(args.command === "validate"
+        ? resolveValidateContext(args, invocationCwd).envFilePath
+        : resolve(invocationCwd, args.envFile ?? ".env"));
     switch (args.command) {
         case "help":
             process.stdout.write(renderHelp());
             return 0;
+        case "version":
+            process.stdout.write(`mono-agent ${monoAgentVersion()}\n`);
+            return 0;
         case "init":
             return await runInit(args);
+        case "setup":
+            return await runSetup(args);
         case "validate":
             return await runValidate(args);
+        case "config":
+            return await runConfig(args);
+        case "recipes":
+            return runRecipes(args);
         case "start":
             return await runStart(args);
         case "restart":
@@ -278,6 +550,32 @@ export async function runCli(argv) {
         case "status":
         case "logs":
             return await runBackgroundCommand(args, args.command);
+        case "tui": {
+            // Lazy import: the operator console (and pi-tui) load only on demand.
+            const { runTui } = await import("./tui-command.js");
+            return await runTui({
+                configPath: resolve(process.cwd(), args.configPath ?? "mono-agent.config.json"),
+                cwd: process.cwd(),
+                env: process.env,
+                ...(args.agent === undefined ? {} : { agent: args.agent }),
+                ...(args.conversation === undefined ? {} : { conversationId: args.conversation }),
+            });
+        }
+        case "web": {
+            // Lazy import: the web server (and express/session-web) load only on demand.
+            const { runWeb } = await import("./web-command.js");
+            return await runWeb({
+                configPath: resolve(process.cwd(), args.configPath ?? "mono-agent.config.json"),
+                cwd: process.cwd(),
+                env: process.env,
+                ...(args.host === undefined ? {} : { host: args.host }),
+                ...(args.port === undefined ? {} : { port: args.port }),
+                ...(args.open === undefined ? {} : { open: args.open }),
+                ...(args.allowNonLoopback === undefined ? {} : { allowNonLoopback: args.allowNonLoopback }),
+                includeMemory: args.includeMemory,
+                ...(args.maxRunsPerInstance === undefined ? {} : { maxRunsPerInstance: args.maxRunsPerInstance }),
+            });
+        }
         case "install-skill":
             return await runInstallSkill(args);
         case "backfill":
@@ -288,31 +586,182 @@ export async function runCli(argv) {
                 ...(args.since === undefined ? {} : { since: args.since }),
                 ...(args.until === undefined ? {} : { until: args.until }),
                 dryRun: args.dryRun,
+                includeMemory: args.includeMemory,
+            });
+        case "audit-runs":
+            return await runAuditRuns({
+                ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
+                ...(args.artifactDir === undefined ? {} : { artifactDir: args.artifactDir }),
+                ...(args.consumerPath === undefined ? {} : { consumerPath: args.consumerPath }),
+                ...(args.staleAfterMs === undefined ? {} : { staleAfterMs: args.staleAfterMs }),
+                json: args.json === true,
+                includeMemory: args.includeMemory,
+            });
+        case "metrics":
+            return await runMetrics({
+                ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
+                ...(args.artifactDir === undefined ? {} : { artifactDir: args.artifactDir }),
+                ...(args.since === undefined ? {} : { since: args.since }),
+                ...(args.until === undefined ? {} : { until: args.until }),
+                ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
+                json: args.json === true,
+                includeMemory: args.includeMemory,
+            });
+        case "memory": {
+            // Lazy import: the memory preview path pulls SQLite/backend clients only on demand.
+            const { runMemoryCommand } = await import("./memory-command.js");
+            return await runMemoryCommand({
+                cwd: process.cwd(),
+                env: process.env,
+                ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
+                positionals: args.positionals,
+                json: args.json === true,
+                ...(args.limit === undefined ? {} : { limit: args.limit }),
             });
+        }
     }
 }
 async function runInit(args) {
+    const recipe = resolveRecipeArg(args);
+    if (recipe === "unknown") {
+        return 1;
+    }
+    const withChannels = resolveWithChannels(args);
+    if (withChannels === "invalid") {
+        return 1;
+    }
     const result = await initMonoAgentFolder({
         dir: process.cwd(),
         ...(args.model === undefined ? {} : { model: args.model }),
         ...(args.fallbackModels === undefined ? {} : { fallbackModels: args.fallbackModels }),
         ...(args.memory === undefined ? {} : { memory: args.memory }),
+        ...(recipe === undefined ? {} : { recipe }),
+        ...(withChannels === undefined ? {} : { withChannels }),
+        dryRun: args.dryRun,
+    });
+    printInitResult(result, recipe);
+    printNextSteps(result.configPath, recipe);
+    return 0;
+}
+async function runSetup(args) {
+    if (process.stdin.isTTY !== true) {
+        return await runInit(args);
+    }
+    const recipeArg = resolveRecipeArg(args);
+    if (recipeArg === "unknown") {
+        return 1;
+    }
+    const withChannelsArg = resolveWithChannels(args);
+    if (withChannelsArg === "invalid") {
+        return 1;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let collected;
+    try {
+        collected = await collectSetupOptions({
+            prompt: { question: (prompt) => rl.question(prompt) },
+            ...(recipeArg === undefined ? {} : { recipe: recipeArg }),
+            ...(args.model === undefined ? {} : { model: args.model }),
+            ...(args.fallbackModels === undefined ? {} : { fallbackModels: args.fallbackModels }),
+            ...(withChannelsArg === undefined ? {} : { withChannels: withChannelsArg }),
+        });
+    }
+    finally {
+        rl.close();
+    }
+    const result = await initMonoAgentFolder({
+        dir: process.cwd(),
+        ...(collected.fallbackModels.length === 0 ? {} : { fallbackModels: collected.fallbackModels }),
+        ...(args.memory === undefined ? {} : { memory: args.memory }),
+        recipe: collected.recipe,
+        recipeInputs: collected.recipeInputs,
+        withChannels: collected.withChannels,
+        dryRun: args.dryRun,
     });
+    printInitResult(result, collected.recipe);
+    if (!result.dryRun) {
+        const report = await validateMonoAgentFolder({
+            env: process.env,
+            cwd: process.cwd(),
+            configPath: result.configPath,
+        });
+        process.stdout.write("\n" + ui.heading("Validation"));
+        for (const section of report.sections) {
+            process.stdout.write(formatSection(section));
+        }
+        process.stdout.write(renderRecipeCompleteness(collected.recipe, report));
+        printSecretsChecklist(collected.secrets);
+        printNextSteps(result.configPath, collected.recipe);
+        return report.ok ? 0 : 1;
+    }
+    printSecretsChecklist(collected.secrets);
+    printNextSteps(result.configPath, collected.recipe);
+    return 0;
+}
+function resolveRecipeArg(args) {
+    if (args.recipe === undefined) {
+        return undefined;
+    }
+    const recipe = findRecipe(args.recipe);
+    if (recipe === undefined) {
+        process.stderr.write(ui.errorLine(`Unknown recipe \`${args.recipe}\`.`));
+        process.stderr.write(ui.hint("Run `mono-agent recipes list` to see available recipes."));
+        return "unknown";
+    }
+    return recipe;
+}
+function resolveWithChannels(args) {
+    if (args.withChannels === undefined) {
+        return undefined;
+    }
+    const invalid = args.withChannels.filter((channel) => !isWithChannel(channel));
+    if (invalid.length > 0) {
+        process.stderr.write(ui.errorLine(`Unknown --with channel(s): ${invalid.join(", ")}.`));
+        process.stderr.write(ui.hint("Valid channels: telegram, slack, webhook, openaiApi, cron."));
+        return "invalid";
+    }
+    return args.withChannels.filter(isWithChannel);
+}
+function printInitResult(result, recipe) {
+    if (result.dryRun) {
+        process.stdout.write(ui.style.dim("Dry run — nothing was written.\n"));
+    }
+    const verb = result.dryRun ? "would create" : "created";
     for (const path of result.created) {
-        process.stdout.write(`${ui.badge("ok")}${ui.style.green("created")}  ${path}\n`);
+        process.stdout.write(`${ui.badge("ok")}${ui.style.green(verb.padEnd(12))}  ${path}\n`);
     }
     for (const path of result.skipped) {
-        process.stdout.write(ui.style.dim(`  kept     ${path}`) + "\n");
+        process.stdout.write(ui.style.dim(`  kept          ${path}`) + "\n");
     }
     if (result.knowledgeFiles.length > 0) {
         process.stdout.write(`\nIdentity references existing knowledge: ${ui.style.cyan(result.knowledgeFiles.join(", "))}\n`);
     }
+    if (recipe !== undefined) {
+        process.stdout.write(`\n${ui.style.bold("Recipe:")} ${ui.style.cyan(recipe.id)} ${ui.style.dim(`(risk: ${recipe.riskLevel})`)}\n`);
+        if (recipe.envExample !== undefined) {
+            process.stdout.write(ui.style.dim("Fill the secret placeholders in .env.example, then copy it to .env.\n"));
+        }
+    }
+}
+function printSecretsChecklist(secrets) {
+    process.stdout.write("\n" + ui.heading("Secrets checklist"));
+    if (secrets.length === 0) {
+        process.stdout.write(ui.style.dim("No secret recipe inputs were prompted. Review .env.example if the recipe created one.\n"));
+        return;
+    }
+    process.stdout.write(ui.style.dim("Copy .env.example to .env, then fill these variables. Secret values were not prompted or written to JSON.\n"));
+    for (const secret of secrets) {
+        const key = secret.envVar ?? secret.id;
+        process.stdout.write(`  ${ui.style.bold(key)} ${ui.style.dim(`- ${secret.label}: ${secret.description}`)}\n`);
+    }
+}
+function printNextSteps(configPath, recipe) {
+    const validateCmd = recipe === undefined ? "mono-agent validate" : `mono-agent validate --recipe ${recipe.id}`;
     process.stdout.write("\n" +
         ui.heading("Next steps") +
-        `  ${ui.style.bold("1.")} Edit ${result.configPath} ${ui.style.dim("(model, channels, skills, memory, sandbox)")}\n` +
-        `  ${ui.style.bold("2.")} mono-agent validate\n` +
+        `  ${ui.style.bold("1.")} Edit ${configPath} ${ui.style.dim("(model, channels, skills, memory, sandbox)")}\n` +
+        `  ${ui.style.bold("2.")} ${validateCmd}\n` +
         `  ${ui.style.bold("3.")} mono-agent start\n`);
-    return 0;
 }
 async function runInstallSkill(args) {
     let result;
@@ -332,20 +781,219 @@ async function runInstallSkill(args) {
     return 0;
 }
 async function runValidate(args) {
-    const cwd = process.cwd();
+    const context = resolveValidateContext(args, process.cwd());
     const report = await validateMonoAgentFolder({
         env: process.env,
-        cwd,
-        configPath: resolve(cwd, args.configPath ?? "mono-agent.config.json"),
+        cwd: context.cwd,
+        configPath: context.configPath,
+        allowFilesystemWrites: context.allowFilesystemWrites,
     });
     for (const section of report.sections) {
         process.stdout.write(formatSection(section));
     }
+    if (args.recipe !== undefined) {
+        const recipe = findRecipe(args.recipe);
+        if (recipe === undefined) {
+            process.stderr.write(ui.errorLine(`Unknown recipe \`${args.recipe}\`.`));
+            process.stderr.write(ui.hint("Run `mono-agent recipes list` to see available recipes."));
+            return 1;
+        }
+        process.stdout.write(renderRecipeCompleteness(recipe, report));
+    }
     process.stdout.write(report.ok
-        ? `\n${ui.style.green("✓ Config is ready to start.")}\n`
+        ? `\n${ui.style.green("✓ Config is ready to start.")}\n${ui.style.dim("Run `mono-agent config` for the full field-by-field view.")}\n`
         : `\n${ui.hint("Fix the errors above, then re-run mono-agent validate.")}`);
+    process.stdout.write(ui.style.dim("Core sections activate by presence; channels need `enabled: true` — see docs/config (How sections activate).\n"));
     return report.ok ? 0 : 1;
 }
+/**
+ * Capability-aware recipe check: for each capability the recipe promises, report
+ * whether the matching doctor section has reached the expected status. `waiting`
+ * stays non-fatal (it never changes the validate exit code) but is surfaced as
+ * "selected recipe incomplete" so the operator knows what is left to wire up.
+ */
+function renderRecipeCompleteness(recipe, report) {
+    let out = "\n" + ui.heading(`Recipe: ${recipe.id}`);
+    let incomplete = 0;
+    for (const expectation of recipe.validateExpectations) {
+        const section = report.sections.find((entry) => entry.id === expectation.sectionId);
+        const status = section?.status ?? "missing";
+        const met = status === expectation.mustBe;
+        if (!met) {
+            incomplete += 1;
+        }
+        const badge = met ? ui.badge("ok") : ui.badge(status === "error" ? "error" : "waiting");
+        out += `${badge}${ui.style.bold(expectation.sectionId)} ${ui.style.dim(`(${status}, expected ${expectation.mustBe})`)}\n`;
+        if (!met && expectation.note !== undefined) {
+            out += `    ${ui.style.dim(expectation.note)}\n`;
+        }
+    }
+    out += incomplete === 0
+        ? `${ui.style.green(`✓ Recipe ${recipe.id} is fully configured.`)}\n`
+        : ui.style.yellow(`⚠ Selected recipe incomplete: ${incomplete} capability(ies) not yet live.\n`);
+    return out;
+}
+function riskColor(risk) {
+    if (risk === "high") {
+        return ui.style.red(risk);
+    }
+    if (risk === "medium") {
+        return ui.style.yellow(risk);
+    }
+    return ui.style.green(risk);
+}
+/** `mono-agent recipes list` — one line per recipe. */
+export function renderRecipeList() {
+    let out = ui.banner("mono-agent", "recipes") + "\n";
+    for (const recipe of RECIPE_CATALOG) {
+        out += `${ui.style.bold(ui.style.cyan(recipe.id))} ${ui.style.dim(`[${riskColor(recipe.riskLevel)}]`)}\n`;
+        out += `    ${recipe.title}\n`;
+        out += `    ${ui.style.dim(recipe.tags.join(", "))}\n`;
+    }
+    out += "\n" + ui.style.dim("Scaffold one with: mono-agent init --recipe <id> [--dry-run] [--with slack,cron]\n");
+    return out;
+}
+/** `mono-agent recipes show <id>` — description, generated JSON, env example, checklist. */
+export function renderRecipeShow(recipe) {
+    const inputs = resolveRecipeInputs(recipe);
+    let out = ui.banner("mono-agent", `recipe: ${recipe.id}`) + "\n";
+    out += `${ui.style.bold(recipe.title)} ${ui.style.dim(`(risk: ${riskColor(recipe.riskLevel)})`)}\n`;
+    out += `${recipe.description}\n`;
+    if (recipe.playbook !== undefined) {
+        out += ui.style.dim(`Playbook: docs/playbooks/${recipe.playbook}\n`);
+    }
+    out += "\n" + ui.heading("Generated mono-agent.config.json");
+    out += JSON.stringify(recipe.config(inputs), null, 2) + "\n";
+    const envExample = recipe.envExample?.(inputs);
+    if (envExample !== undefined && envExample.trim().length > 0) {
+        out += "\n" + ui.heading(".env.example");
+        out += envExample.endsWith("\n") ? envExample : envExample + "\n";
+    }
+    const files = recipe.files?.(inputs) ?? [];
+    if (files.length > 0) {
+        out += "\n" + ui.heading("Scaffolded files");
+        for (const file of files) {
+            out += `  ${ui.style.cyan(file.path)}\n`;
+        }
+    }
+    if (recipe.validateExpectations.length > 0) {
+        out += "\n" + ui.heading("Follow-up checklist");
+        for (const expectation of recipe.validateExpectations) {
+            const note = expectation.note === undefined ? "" : ` — ${expectation.note}`;
+            out += `  ${ui.style.gray("•")} ${expectation.sectionId} ${ui.style.dim(`must be ${expectation.mustBe}`)}${ui.style.dim(note)}\n`;
+        }
+    }
+    return out;
+}
+/** Dispatch `mono-agent recipes list|show <id>`. */
+function runRecipes(args) {
+    const [sub, id] = args.positionals;
+    if (sub === undefined || sub === "list") {
+        process.stdout.write(renderRecipeList());
+        return 0;
+    }
+    if (sub === "show") {
+        if (id === undefined) {
+            process.stderr.write(ui.errorLine("Usage: mono-agent recipes show <id>."));
+            process.stderr.write(ui.hint(`Available: ${recipeIds().join(", ")}.`));
+            return 2;
+        }
+        const recipe = findRecipe(id);
+        if (recipe === undefined) {
+            process.stderr.write(ui.errorLine(`Unknown recipe \`${id}\`.`));
+            process.stderr.write(ui.hint("Run `mono-agent recipes list` to see available recipes."));
+            return 1;
+        }
+        process.stdout.write(renderRecipeShow(recipe));
+        return 0;
+    }
+    process.stderr.write(ui.errorLine(`Unknown recipes subcommand \`${sub}\`. Expected list or show.`));
+    return 2;
+}
+const SOURCE_TAG = {
+    env: ui.style.green("[env]"),
+    json: ui.style.cyan("[json]"),
+    default: ui.style.dim("[default]"),
+};
+/**
+ * Render the complete, source-annotated config view: every core section and
+ * field with its resolved value and whether it came from an env var, the JSON
+ * file, or the built-in default. This is the single discovery surface that
+ * replaced the old partial config panes.
+ */
+export function renderConfigView(sections) {
+    let out = "";
+    for (const section of sections) {
+        const badgeStatus = section.status === "active" ? "ok" : "disabled";
+        out += `${ui.badge(badgeStatus)}${ui.style.bold(section.label)}\n`;
+        const width = section.fields.reduce((max, field) => Math.max(max, field.label.length), 0);
+        for (const field of section.fields) {
+            const tag = SOURCE_TAG[field.source];
+            const lock = field.redacted === true ? ` ${ui.style.dim("(secret)")}` : "";
+            const defaultRestatement = field.restatesDefault === true ? ` ${ui.style.dim("(same as default)")}` : "";
+            out += `    ${ui.style.gray(field.label.padEnd(width))}  ${field.value}${lock}${defaultRestatement}  ${tag}\n`;
+        }
+    }
+    return out;
+}
+/**
+ * `mono-agent config`: print the resolved configuration field-by-field with the
+ * source (env / json / default) of every value, then the channel summary. Read
+ * only — edits go in mono-agent.config.json and take effect on the next restart.
+ */
+async function runConfig(args) {
+    const cwd = process.cwd();
+    const configPath = resolve(cwd, args.configPath ?? "mono-agent.config.json");
+    const env = process.env;
+    const jsonResult = await readMonoAgentConfigJson(configPath);
+    let config;
+    try {
+        config = await loadAppCoreConfig({ env, cwd, configPath });
+    }
+    catch (error) {
+        if (isAppCoreConfigError(error)) {
+            process.stderr.write(ui.errorLine(error.message));
+            if (jsonResult.missing) {
+                process.stderr.write(ui.hint(`No mono-agent config found at ${configPath}. Run \`mono-agent init\` to scaffold one.`));
+            }
+            else {
+                process.stderr.write(ui.hint("Fix the config above, then re-run `mono-agent config`."));
+            }
+            return 1;
+        }
+        throw error;
+    }
+    const sections = buildMonoAgentConfigView({
+        redacted: redactMonoAgentConfig(config),
+        json: jsonResult.json,
+        env,
+    });
+    const drivers = await resolveChannelDrivers({ env, cwd, configPath });
+    const channelViews = await collectChannelConfigViews(drivers, { env, cwd, configPath });
+    process.stdout.write(ui.banner("mono-agent", "resolved config") + "\n");
+    process.stdout.write(renderConfigView(sections));
+    if (channelViews.length > 0) {
+        process.stdout.write("\n" + ui.heading("Channels"));
+        process.stdout.write(renderConfigView(channelViews));
+    }
+    for (const warning of [
+        ...findUnknownAppConfigWarnings(jsonResult.json),
+        ...findJsonSecretConfigWarnings([...sections, ...channelViews]),
+        ...findRemovedConfigWarnings({ json: jsonResult.json, env }),
+    ]) {
+        process.stdout.write(`${ui.style.yellow(warning)}\n`);
+    }
+    const report = await validateMonoAgentFolder({ env, cwd, configPath, liveness: false, drivers });
+    const channels = report.sections.filter((section) => section.id.startsWith("channel:"));
+    if (channels.length > 0) {
+        process.stdout.write("\n" + ui.heading("Channel status"));
+        for (const section of channels) {
+            process.stdout.write(formatSection(section));
+        }
+    }
+    process.stdout.write("\n" + ui.style.dim("Source precedence: [env] > [json] > [default]. Edit mono-agent.config.json and run `mono-agent restart` to apply.") + "\n");
+    return 0;
+}
 /** Render one validation section: a status badge, a bold label, and its details. */
 function formatSection(section) {
     let out = `${ui.badge(section.status)}${ui.style.bold(section.label)}\n`;
@@ -358,7 +1006,7 @@ function colorDetail(status, detail) {
     if (status === "error") {
         return ui.style.red(detail);
     }
-    if (detail.startsWith("[WARN]")) {
+    if (detail.startsWith("[WARN]") || detail.startsWith("WARNING:")) {
         return ui.style.yellow(detail);
     }
     return ui.style.dim(detail);
@@ -429,7 +1077,7 @@ async function runForeground(args) {
         ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
         logger: consoleLogger(),
     });
-    printAppStatus(app);
+    await printAppStatus(app);
     // Block until a shutdown signal. Returning here (the old behavior) let the
     // process exit immediately whenever no channel owned a live handle — e.g. a
     // traceability-only config, now that the operator console is retired and the
@@ -508,7 +1156,7 @@ function requireDarwin(command) {
     process.stderr.write(ui.hint("Run `mono-agent start --foreground` to run in the foreground on this platform."));
     return 1;
 }
-export function printAppStatus(app) {
+export async function printAppStatus(app, options = {}) {
     const trace = app.traceabilityStatus;
     process.stdout.write(ui.rule("instance"));
     process.stdout.write(ui.keyValue([
@@ -519,6 +1167,8 @@ export function printAppStatus(app) {
         ],
     ], 2));
     const artifactDir = app.traceabilityStatus.kind === "running" ? app.traceabilityStatus.artifactDir : undefined;
+    process.stdout.write(ui.rule("sandbox"));
+    process.stdout.write(`  ${describeSandboxStatus(app.sandboxStatus)}\n`);
     process.stdout.write(ui.rule("observability"));
     process.stdout.write(`  ${describeExporter(app.exporterStatus, artifactDir)}\n`);
     const channels = [...app.channelStatuses()];
@@ -528,6 +1178,43 @@ export function printAppStatus(app) {
             process.stdout.write(`  ${ui.channelBadge(status.kind)}${ui.style.bold(id.padEnd(11))} ${describeChannelStatus(status)}\n`);
         }
     }
+    await writeAppRunsHealthDetail(app, options);
+}
+async function writeAppRunsHealthDetail(app, options) {
+    const artifactDir = app.traceabilityStatus.kind === "running" ? app.traceabilityStatus.artifactDir : undefined;
+    if (artifactDir === undefined || artifactDir.trim().length === 0) {
+        return;
+    }
+    const reader = options.listRecordedRuns ?? listRecordedRuns;
+    let result;
+    try {
+        result = await reader({ artifactDir, maxRuns: RUNS_HEALTH_MAX_RUNS, scope: "agent" });
+    }
+    catch (error) {
+        result = {
+            totalRuns: 0,
+            runs: [],
+            warnings: [`Unable to read run summaries: ${reasonOf(error)}`],
+        };
+    }
+    const display = buildRunsHealthDisplay({
+        artifactDir,
+        totalRuns: result.totalRuns,
+        runs: result.runs,
+        warnings: result.warnings,
+        includeSelectedSkills: true,
+        runOwnerAlive: true,
+        maxRuns: RUNS_HEALTH_MAX_RUNS,
+        ...(app.selectedSkills === undefined ? {} : { selectedSkills: app.selectedSkills }),
+        ...(options.nowMs === undefined ? {} : { nowMs: options.nowMs }),
+    });
+    process.stdout.write(ui.rule("runs health"));
+    for (const detail of display.details) {
+        process.stdout.write(`  ${detail}\n`);
+    }
+}
+function reasonOf(error) {
+    return error instanceof Error ? error.message : String(error);
 }
 function describeExporter(status, artifactDir) {
     if (status.kind !== "configured") {
@@ -539,7 +1226,7 @@ function describeExporter(status, artifactDir) {
         parts.push(`app ${appUrl}`);
     }
     if (status.includeSensitiveData) {
-        parts.push("includeSensitiveData=true");
+        parts.push(ui.style.yellow(describeSensitiveDataExportWarning(status.endpoint)));
     }
     if (status.lastWarning !== undefined) {
         parts.push(`last warning: ${status.lastWarning}`);
@@ -552,15 +1239,53 @@ function describeExporter(status, artifactDir) {
         : `JSONL artifacts remain local at ${artifactDir}`);
     return parts.join("; ");
 }
-function describeChannelStatus(status) {
+function describeSandboxStatus(status) {
+    const engineAvailability = status.engineAvailable === true
+        ? "present"
+        : status.engineAvailable === false
+            ? "absent"
+            : "not checked";
+    const parts = [
+        `effective: ${status.effective}`,
+        `engine: ${status.engine ?? "none"} (${engineAvailability})`,
+        ...(status.fallback === undefined ? [] : [`fallback: ${status.fallback}`]),
+        `fallback active: ${status.fallbackActive ? "yes" : "no"}`,
+        status.detail,
+    ];
+    const warning = status.warning ?? sandboxEffectiveStateWarning(status);
+    if (warning !== undefined) {
+        parts.push(ui.style.yellow(warning));
+    }
+    return parts.join("; ");
+}
+export function describeChannelStatus(status) {
     if (status.kind === "running") {
         const facts = Object.entries(status.summary)
-            .map(([key, value]) => `${key}=${String(value)}`)
+            .map(([key, value]) => `${key}=${formatChannelFactValue(value)}`)
             .join(" ");
         return facts.length === 0 ? "running" : `running (${facts})`;
     }
     return `${status.kind}: ${status.reason}`;
 }
+/**
+ * Render a channel-status summary value for the human-readable status line.
+ * Objects and arrays are expanded to `key: value` pairs instead of the useless
+ * `[object Object]` that a bare `String()` produced (E4: the webhook summary's
+ * `invokeUrls` map printed `invokeUrls=[object Object]`).
+ */
+function formatChannelFactValue(value) {
+    if (value === null || typeof value !== "object") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(formatChannelFactValue).join(", ")}]`;
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+        return "{}";
+    }
+    return `{${entries.map(([key, inner]) => `${key}: ${formatChannelFactValue(inner)}`).join(", ")}}`;
+}
 /**
  * Block the foreground process until SIGINT/SIGTERM, then stop the app and
  * resolve the exit code. A referenced no-op timer owns the event loop so the