@mono-agent/agent-app 0.12.0 → 0.13.0

package/dist/channel-runtime-controls.d.ts

@@ -0,0 +1,23 @@
+import type { MonoAgentConfig } from "@mono-agent/config";
+export interface ChannelRuntimeEffortOption {
+    readonly value: string;
+    readonly label: string;
+}
+export interface ChannelRuntimeModelOption {
+    readonly value: string;
+    readonly label: string;
+    readonly efforts: readonly ChannelRuntimeEffortOption[];
+}
+export interface ChannelRuntimeControls {
+    readonly defaultModel: string;
+    readonly defaultEffort?: string;
+    readonly models: readonly ChannelRuntimeModelOption[];
+}
+/**
+ * Build the display-ready runtime catalog shared by native channel controls.
+ * Adapters still own their interaction/state behavior; the host owns which
+ * configured routes are safe to expose and which effort values each route can
+ * actually accept.
+ */
+export declare function buildChannelRuntimeControls(coreConfig: MonoAgentConfig): ChannelRuntimeControls;
+//# sourceMappingURL=channel-runtime-controls.d.ts.map

package/dist/channel-runtime-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-runtime-controls.d.ts","sourceRoot":"","sources":["../src/channel-runtime-controls.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAY1D,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACzD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACvD;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,eAAe,GAAG,sBAAsB,CA6B/F"}

package/dist/channel-runtime-controls.js

@@ -0,0 +1,63 @@
+import { EFFORT_LEVELS } from "@mono-agent/config";
+import { modelReferenceKey, resolveModelEffortLevels, } from "@mono-agent/runtime-adapter";
+import { configuredRuntimeFallbackModels, configuredRuntimeModels, } from "./runtime-routes.js";
+/**
+ * Build the display-ready runtime catalog shared by native channel controls.
+ * Adapters still own their interaction/state behavior; the host owns which
+ * configured routes are safe to expose and which effort values each route can
+ * actually accept.
+ */
+export function buildChannelRuntimeControls(coreConfig) {
+    const refs = [];
+    const seen = new Set();
+    for (const ref of configuredRuntimeModels(coreConfig.runtime)) {
+        const value = modelReferenceKey(ref);
+        if (seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        refs.push(ref);
+    }
+    const directOpenCodeInFallbacks = configuredRuntimeFallbackModels(coreConfig.runtime)
+        .some((ref) => ref.sdk === "opencode");
+    return {
+        defaultModel: modelReferenceKey(coreConfig.runtime.model),
+        ...(coreConfig.runtime.effort === undefined ? {} : { defaultEffort: coreConfig.runtime.effort }),
+        models: refs.map((ref) => {
+            const value = modelReferenceKey(ref);
+            return {
+                value,
+                label: value,
+                efforts: channelEffortOptions(ref, coreConfig.providers?.local, ref.sdk === "opencode" || directOpenCodeInFallbacks),
+            };
+        }),
+    };
+}
+function channelEffortOptions(ref, localProviders, directOpenCodeInResultingChain) {
+    if (directOpenCodeInResultingChain) {
+        return [];
+    }
+    const resolved = resolveModelEffortLevels(ref, localProviders);
+    if (!resolved.reasoning || resolved.reasoningMode === "none") {
+        return [];
+    }
+    if (resolved.reasoningMode === "toggle") {
+        return [
+            { value: "high", label: "Thinking on" },
+            { value: "none", label: "Thinking off" },
+        ];
+    }
+    const allowed = new Set(EFFORT_LEVELS);
+    const values = resolved.effortLevels ?? EFFORT_LEVELS;
+    return [...new Set(values)]
+        .filter((value) => allowed.has(value))
+        .map((value) => ({ value, label: channelEffortLabel(value) }));
+}
+function channelEffortLabel(value) {
+    if (value === "xhigh")
+        return "Extra high";
+    if (value === "max")
+        return "Maximum";
+    return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+}
+//# sourceMappingURL=channel-runtime-controls.js.map

package/dist/channel-runtime-controls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-runtime-controls.js","sourceRoot":"","sources":["../src/channel-runtime-controls.ts"],"names":[],"mappings":"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"}

package/dist/channel-status-display.d.ts

@@ -0,0 +1,15 @@
+export interface HumanChannelStatus {
+    readonly id: string;
+    readonly kind: string;
+    readonly text: string;
+}
+export interface HumanChannelSection {
+    readonly title: "channels" | "operator";
+    readonly lines: readonly string[];
+}
+/**
+ * Keep transport ids stable in config/JSON while giving humans the product
+ * name and purpose they actually interact with.
+ */
+export declare function formatHumanChannelSections(entries: readonly HumanChannelStatus[]): readonly HumanChannelSection[];
+//# sourceMappingURL=channel-status-display.d.ts.map

package/dist/channel-status-display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-status-display.d.ts","sourceRoot":"","sources":["../src/channel-status-display.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAID;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,SAAS,mBAAmB,EAAE,CAoBhC"}

package/dist/channel-status-display.js

@@ -0,0 +1,48 @@
+import * as ui from "./ui.js";
+const OPERATOR_CHANNEL_IDS = new Set(["tui", "live"]);
+/**
+ * Keep transport ids stable in config/JSON while giving humans the product
+ * name and purpose they actually interact with.
+ */
+export function formatHumanChannelSections(entries) {
+    const sections = [];
+    for (const title of ["channels", "operator"]) {
+        const selected = entries.filter(({ id }) => OPERATOR_CHANNEL_IDS.has(id) === (title === "operator"));
+        if (selected.length === 0)
+            continue;
+        const lines = selected
+            .filter(({ kind }) => kind !== "disabled")
+            .map((entry) => formatHumanChannelLine(entry));
+        const disabled = selected
+            .filter(({ kind }) => kind === "disabled")
+            .map(({ id }) => displayChannelId(id));
+        if (disabled.length > 0) {
+            lines.push(`  ${ui.channelBadge("disabled")}${ui.style.bold("disabled".padEnd(11))} ${disabled.join(", ")}`);
+        }
+        sections.push({ title, lines });
+    }
+    return sections;
+}
+function formatHumanChannelLine(entry) {
+    const id = displayChannelId(entry.id);
+    return `  ${ui.channelBadge(entry.kind)}${ui.style.bold(id.padEnd(11))} ${describeOperatorPurpose(entry)}`;
+}
+function displayChannelId(id) {
+    return id === "tui" ? "gui" : id;
+}
+function describeOperatorPurpose(entry) {
+    const purpose = entry.id === "tui"
+        ? "TUI + Web"
+        : entry.id === "live"
+            ? "read-only events"
+            : undefined;
+    if (purpose === undefined || entry.kind !== "running")
+        return entry.text;
+    if (entry.text === "running")
+        return `running (${purpose})`;
+    if (entry.text.startsWith("running (") && entry.text.endsWith(")")) {
+        return `running (${purpose}; ${entry.text.slice("running (".length, -1)})`;
+    }
+    return entry.text;
+}
+//# sourceMappingURL=channel-status-display.js.map

package/dist/channel-status-display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-status-display.js","sourceRoot":"","sources":["../src/channel-status-display.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAa9B,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;AAEtD;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAsC;IAEtC,MAAM,QAAQ,GAA0B,EAAE,CAAC;IAC3C,KAAK,MAAM,KAAK,IAAI,CAAC,UAAU,EAAE,UAAU,CAAU,EAAE,CAAC;QACtD,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC;QACrG,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAEpC,MAAM,KAAK,GAAG,QAAQ;aACnB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,KAAK,UAAU,CAAC;aACzC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;QACjD,MAAM,QAAQ,GAAG,QAAQ;aACtB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,KAAK,UAAU,CAAC;aACzC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;QACzC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CACR,KAAK,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACjG,CAAC;QACJ,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAyB;IACvD,MAAM,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACtC,OAAO,KAAK,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;AAC7G,CAAC;AAED,SAAS,gBAAgB,CAAC,EAAU;IAClC,OAAO,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACnC,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAyB;IACxD,MAAM,OAAO,GAAG,KAAK,CAAC,EAAE,KAAK,KAAK;QAChC,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,KAAK,CAAC,EAAE,KAAK,MAAM;YACnB,CAAC,CAAC,kBAAkB;YACpB,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC;IACzE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,YAAY,OAAO,GAAG,CAAC;IAC5D,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACnE,OAAO,YAAY,OAAO,KAAK,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IAC7E,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC;AACpB,CAAC"}

package/dist/cli-args.d.ts

@@ -1,23 +1,20 @@
 import type { EffortLevel, RouteSafetyMode } from "@mono-agent/config";
 import type { InstallSkillTarget } from "./install-skill.js";
 import type { CodexLoginMode } from "./provider-setup.js";
-declare const KNOWN_COMMANDS: readonly ["init", "setup", "validate", "doctor", "auth", "sandbox", "config", "recipes", "presets", "start", "restart", "stop", "status", "logs", "tui", "web", "sessions", "install-skill", "backfill", "audit-runs", "metrics", "memory", "continuations", "__launchd-log-maintenance"];
-type CliCommand = Exclude<(typeof KNOWN_COMMANDS)[number], "doctor" | "setup" | "recipes"> | "help" | "version";
+declare const KNOWN_COMMANDS: readonly ["init", "setup", "validate", "doctor", "auth", "sandbox", "config", "presets", "start", "restart", "stop", "status", "logs", "tui", "web", "install-skill", "backfill", "runs", "audit-runs", "metrics", "memory", "continuations", "__launchd-log-maintenance"];
+export declare const REMOVED_COMMANDS: Map<string, string>;
+type CliCommand = Exclude<(typeof KNOWN_COMMANDS)[number], "doctor" | "setup" | "audit-runs" | "metrics"> | "help" | "version";
 export interface ParsedCliArgs {
     readonly command: CliCommand;
     readonly configPath?: string;
     readonly name?: string;
     readonly model?: string;
-    /** @deprecated Removed in v2.0.0; use repeated `--fallback` entries. */
-    readonly fallbackModels?: readonly string[];
     readonly fallbacks?: readonly CliFallbackArg[];
     readonly routeSafety?: RouteSafetyMode;
     readonly effort?: string;
     readonly memory?: "lite" | "journal" | "bujo";
     /** init/validate: build/check against this preset id. */
     readonly preset?: string;
-    /** @deprecated Removed in v2.0.0; use `--preset`. */
-    readonly recipe?: string;
     /** init: additional channels to enable on top of the preset/default config. */
     readonly withChannels?: readonly string[];
     /** init: skip the interactive wizard and write the default/preset scaffold. */
@@ -35,8 +32,12 @@ export interface ParsedCliArgs {
     readonly envFile?: string;
     /** Internal owner-private launchd transport; never a public start option. */
     readonly expectedBackgroundSnapshot?: string;
+    /** Internal finalized-runtime proof; never a public start option. */
+    readonly expectedManagedRuntimeLaunch?: string;
     readonly target?: InstallSkillTarget;
     readonly force: boolean;
+    /** restart: canonical spelling that clears pi sessions + active conversation history. */
+    readonly clearSessions?: boolean;
     /** start: run the blocking foreground worker instead of backgrounding. */
     readonly foreground: boolean;
     /** logs: keep streaming new output (tail -F). */
@@ -53,13 +54,13 @@ export interface ParsedCliArgs {
     readonly until?: string;
     /** backfill: map + serialize but do not POST. */
     readonly dryRun: boolean;
-    /** audit-runs/metrics/backfill/sessions: include memory-run artifacts. */
+    /** runs/backfill: include memory-run artifacts. */
     readonly includeMemory: boolean;
-    /** audit-runs: read this artifact directory directly. */
+    /** runs: read this artifact directory directly. */
     readonly artifactDir?: string;
-    /** metrics: group totals by this summary dimension. */
+    /** runs report: group totals by this summary dimension. */
     readonly groupBy?: "model" | "channel" | "failureKind";
-    /** validate/audit-runs: resolve config, env, artifacts, and checks relative to this consumer folder. */
+    /** validate/runs audit: resolve config, env, artifacts, and checks relative to this consumer folder. */
     readonly consumerPath?: string;
     /** tui: connect to this running agent (label or sourceId) directly. */
     readonly agent?: string;
@@ -75,9 +76,11 @@ export interface ParsedCliArgs {
     readonly check?: boolean;
     /** install-skill --project: safely update unchanged managed copies. */
     readonly update?: boolean;
-    /** audit-runs: override the stale-running cutoff interval. */
+    /** install-skill: copy the skill without pairing the version-matched documentation MCP. */
+    readonly noDocsMcp?: boolean;
+    /** runs audit: override the stale-running cutoff interval. */
     readonly staleAfterMs?: number;
-    /** audit-runs: print the full machine-readable report. */
+    /** runs: print the full machine-readable report. */
     readonly json?: boolean;
     /** memory audit: fail closed on degraded or unknown health. */
     readonly strict?: boolean;
@@ -93,20 +96,12 @@ export interface ParsedCliArgs {
     readonly planPath?: string;
     /** memory forget restore: owner-private backup directory. */
     readonly backupPath?: string;
-    /** web/sessions: bind host (web defaults to 0.0.0.0; sessions to 127.0.0.1). */
+    /** web: bind host (defaults to 0.0.0.0). */
     readonly host?: string;
-    /** web/sessions: bind port (web defaults to 5050; sessions to 4599). */
+    /** web: bind port (defaults to 5050). */
     readonly port?: number;
     /** web: narrow the default LAN bind to 127.0.0.1. */
     readonly loopback?: boolean;
-    /** sessions: `--no-open` sets this false to suppress the browser launch. */
-    readonly open?: boolean;
-    /** sessions: `--allow-non-loopback` permits a non-loopback bind. */
-    readonly allowNonLoopback?: boolean;
-    /** sessions: reveal a configured auth token only to an interactive terminal. */
-    readonly showAuthUrl?: boolean;
-    /** sessions: `--max-runs` caps the per-instance in-memory working set (default 200). */
-    readonly maxRunsPerInstance?: number;
 }
 interface CliFallbackArg {
     readonly model: string;

package/dist/cli-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"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"}

package/dist/cli-args.js

@@ -1,30 +1,71 @@
 import process from "node:process";
 import { EFFORT_LEVELS, MAX_AGENT_NAME_LENGTH, } from "@mono-agent/config";
 import { INTERNAL_LAUNCHD_LOG_MAINTENANCE_COMMAND } from "./launchd.js";
-const PUBLIC_COMMANDS = ["init", "setup", "validate", "doctor", "auth", "sandbox", "config", "recipes", "presets", "start", "restart", "stop", "status", "logs", "tui", "web", "sessions", "install-skill", "backfill", "audit-runs", "metrics", "memory", "continuations"];
+const PUBLIC_COMMANDS = ["init", "setup", "validate", "doctor", "auth", "sandbox", "config", "presets", "start", "restart", "stop", "status", "logs", "tui", "web", "install-skill", "backfill", "runs", "audit-runs", "metrics", "memory", "continuations"];
 const KNOWN_COMMANDS = [...PUBLIC_COMMANDS, INTERNAL_LAUNCHD_LOG_MAINTENANCE_COMMAND];
+// Canonical (post-normalization) commands that emit a `--json` envelope. This is
+// an allowlist so future commands fail closed until they opt in explicitly. The
+// `install-skill`/`sandbox` entries carry an extra subcommand guard below.
+const JSON_CAPABLE_COMMANDS = [
+    "validate",
+    "config",
+    "presets",
+    "status",
+    "sandbox",
+    "install-skill",
+    "runs",
+    "memory",
+    "continuations",
+];
+// Human-facing list for the rejection message: the two subcommand-gated surfaces
+// are qualified so the error points at the exact invocation that accepts `--json`.
+const JSON_CAPABLE_COMMANDS_DISPLAY = "validate, config, presets, status, sandbox status, install-skill --project --check, runs, memory, continuations";
+// Commands removed outright before the KNOWN_COMMANDS gate. Parsing throws with the
+// replacement, and runCli maps that parse error to exit code 2 (usage-error).
+// `renderHelpTopic` reuses these so `help <removed>` prints the same pointer.
+export const REMOVED_COMMANDS = new Map([
+    ["recipes", "`recipes` was removed; use `mono-agent presets`."],
+    ["sessions", "`sessions` was removed; use `mono-agent tui` (recorded-run replay) or `mono-agent web` (live console)."],
+]);
 export function parseCliArgs(argv) {
     const [command, ...rest] = argv;
-    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+    // `--help`/`-h` and a bare invocation render the plain grouped summary (no topic).
+    if (command === undefined || command === "--help" || command === "-h") {
         return { command: "help", positionals: [], force: false, foreground: false, follow: false, all: false, dryRun: false, includeMemory: false };
     }
+    // `help <topic>` keeps the remaining tokens as positionals so the command
+    // handler can render `help <command>` / `help notes` detail views.
+    if (command === "help") {
+        return { command: "help", positionals: [...rest], 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 };
     }
+    const removed = REMOVED_COMMANDS.get(command);
+    if (removed !== undefined) {
+        throw new Error(removed);
+    }
     if (!KNOWN_COMMANDS.includes(command)) {
         throw new Error(`Unknown command \`${command}\`. Expected ${PUBLIC_COMMANDS.join(", ")}.`);
     }
-    // `doctor`/`setup`/`recipes` are aliases; normalize here so every downstream
-    // path (routing, env-file resolution, --consumer) applies unchanged. `doctor`
-    // → `validate`, `setup` → `init`, `recipes` → `presets`. The deprecated
-    // `recipes` branch is removed in v2.0.0; no sunset is set for the other two.
+    // `doctor`/`setup` are aliases; normalize here so every downstream path
+    // (routing, env-file resolution, --consumer) applies unchanged. `doctor` →
+    // `validate`, `setup` → `init`. No sunset is set for either.
+    //
+    // `audit-runs`/`metrics` are deprecated forwarding aliases for the merged
+    // `runs` command: `audit-runs` → `runs` with a leading `audit` mode positional,
+    // `metrics` → `runs` with a leading `report` mode positional. The injected mode
+    // is prepended after the flag loop so user-supplied positionals are preserved,
+    // and the dispatcher routes on `positionals[0]`. writeCliDeprecationHints keys
+    // the sunset hint off the original argv token (lost after this normalization).
     const cmd = (command === "doctor"
         ? "validate"
         : command === "setup"
             ? "init"
-            : command === "recipes"
-                ? "presets"
+            : command === "audit-runs" || command === "metrics"
+                ? "runs"
                 : command);
+    const injectedRunsMode = command === "audit-runs" ? "audit" : command === "metrics" ? "report" : undefined;
     if (cmd === INTERNAL_LAUNCHD_LOG_MAINTENANCE_COMMAND
         && !(rest.length === 2
             && rest[0] === "--config"
@@ -36,14 +77,12 @@ export function parseCliArgs(argv) {
     let configPath;
     let name;
     let model;
-    let fallbackModels;
     const fallbacks = [];
     let canAssignFallbackEffort = false;
     let routeSafety;
     let effort;
     let memory;
     let preset;
-    let recipe;
     let withChannels;
     let yes = false;
     let auth = false;
@@ -53,8 +92,10 @@ export function parseCliArgs(argv) {
     const positionals = [];
     let envFile;
     let expectedBackgroundSnapshot;
+    let expectedManagedRuntimeLaunch;
     let target;
     let force = false;
+    let clearSessions = false;
     let foreground = false;
     let follow = false;
     let lines;
@@ -74,6 +115,7 @@ export function parseCliArgs(argv) {
     let project = false;
     let check = false;
     let update = false;
+    let noDocsMcp = false;
     let staleAfterMs;
     let json = false;
     let strict = false;
@@ -86,10 +128,6 @@ export function parseCliArgs(argv) {
     let host;
     let port;
     let loopback = false;
-    let open;
-    let allowNonLoopback;
-    let showAuthUrl;
-    let maxRunsPerInstance;
     for (let i = 0; i < rest.length; i += 1) {
         const flag = rest[i];
         if (flag !== "--fallback-effort")
@@ -154,6 +192,9 @@ export function parseCliArgs(argv) {
             case "--update":
                 update = true;
                 break;
+            case "--no-docs-mcp":
+                noDocsMcp = true;
+                break;
             case "--stale-after-ms": {
                 const raw = requireValue(rest, ++i, flag);
                 const parsed = Number(raw);
@@ -211,24 +252,6 @@ export function parseCliArgs(argv) {
             case "--loopback":
                 loopback = true;
                 break;
-            case "--no-open":
-                open = false;
-                break;
-            case "--allow-non-loopback":
-                allowNonLoopback = true;
-                break;
-            case "--show-auth-url":
-                showAuthUrl = 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;
@@ -241,13 +264,10 @@ export function parseCliArgs(argv) {
                 }
                 break;
             case "--fallback-models":
-                // Deprecated CLI spelling removed in v2.0.0. The similarly named JSON
-                // and environment compatibility inputs are separate and remain supported.
-                fallbackModels = requireValue(rest, ++i, flag)
-                    .split(",")
-                    .map((entry) => entry.trim())
-                    .filter((entry) => entry.length > 0);
-                break;
+                // Removed CLI spelling. The similarly named JSON `runtime.fallbackModels`
+                // and `MONO_AGENT_FALLBACK_MODELS` compatibility inputs are separate and
+                // remain supported; only this CLI flag is gone.
+                throw new Error("`--fallback-models` was removed; repeat `--fallback <ref>` instead.");
             case "--fallback": {
                 const fallbackModel = requireValue(rest, ++i, flag).trim();
                 if (fallbacks.some((entry) => entry.model === fallbackModel)) {
@@ -303,9 +323,8 @@ export function parseCliArgs(argv) {
                 preset = requireValue(rest, ++i, flag);
                 break;
             case "--recipe":
-                // Deprecated init/validate alias removed in v2.0.0.
-                recipe = requireValue(rest, ++i, flag);
-                break;
+                // Removed init/validate alias.
+                throw new Error("`--recipe` was removed; use `--preset <id>`.");
             case "--yes":
                 yes = true;
                 break;
@@ -338,6 +357,9 @@ export function parseCliArgs(argv) {
             case "--expected-background-snapshot":
                 expectedBackgroundSnapshot = requireValue(rest, ++i, flag);
                 break;
+            case "--expected-managed-runtime-launch":
+                expectedManagedRuntimeLaunch = requireValue(rest, ++i, flag);
+                break;
             case "--target": {
                 const raw = requireValue(rest, ++i, flag);
                 if (raw !== "claude" && raw !== "codex" && raw !== "both") {
@@ -349,19 +371,23 @@ export function parseCliArgs(argv) {
             case "--force":
                 force = true;
                 break;
+            case "--clear-sessions":
+                clearSessions = true;
+                break;
             case "--foreground":
                 foreground = true;
                 break;
             case "--follow":
                 follow = true;
                 break;
-            // `-f` is foreground for start, follow for logs.
+            // `-f` means `--follow` on logs only. Its former `start` meaning
+            // (`--foreground`) is gone: `-f` on anything else is a usage error.
             case "-f":
                 if (isLogs) {
                     follow = true;
                 }
                 else {
-                    foreground = true;
+                    throw new Error("`-f` means `--follow` on `logs`; use `--foreground` with `start`.");
                 }
                 break;
             case "--lines": {
@@ -380,13 +406,19 @@ export function parseCliArgs(argv) {
                 if (flag.startsWith("--")) {
                     throw new Error(`Unknown flag \`${flag}\` for \`mono-agent ${command}\`.`);
                 }
-                // Non-flag tokens are positional arguments (e.g. `recipes show <id>`).
+                // Non-flag tokens are positional arguments (e.g. `presets 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`.");
+    // Prepend the forwarding-alias mode so `audit-runs`/`metrics` reach the `runs`
+    // dispatcher as `runs audit`/`runs report` without clobbering any positionals a
+    // user typed after the legacy command name.
+    if (injectedRunsMode !== undefined) {
+        positionals.unshift(injectedRunsMode);
+    }
+    if (consumerPath !== undefined && cmd !== "validate" && cmd !== "runs") {
+        throw new Error("--consumer is only supported for `mono-agent validate` and `mono-agent runs`.");
     }
     if ((local || configure) && cmd !== "tui") {
         throw new Error("--local and --configure are only supported for `mono-agent tui`.");
@@ -403,27 +435,17 @@ export function parseCliArgs(argv) {
     if (check && update) {
         throw new Error("Choose either --check or --update for project skills.");
     }
-    if ((host !== undefined
-        || port !== undefined
-        || loopback
-        || open !== undefined
-        || allowNonLoopback !== undefined
-        || showAuthUrl !== undefined
-        || maxRunsPerInstance !== undefined) &&
-        cmd !== "web" && cmd !== "sessions") {
-        throw new Error("--host and --port are only supported for `mono-agent web` or `mono-agent sessions`; --loopback is web-only; Session Recorder flags are sessions-only.");
-    }
-    if (loopback && cmd !== "web") {
-        throw new Error("--loopback is only supported for `mono-agent web`.");
+    if (noDocsMcp && cmd !== "install-skill") {
+        throw new Error("--no-docs-mcp is only supported for `mono-agent install-skill`.");
     }
-    if ((open !== undefined || allowNonLoopback !== undefined || showAuthUrl !== undefined || maxRunsPerInstance !== undefined) && cmd !== "sessions") {
-        throw new Error("--no-open, --allow-non-loopback, --show-auth-url, and --max-runs are only supported for `mono-agent sessions`.");
+    if ((host !== undefined || port !== undefined || loopback) && cmd !== "web") {
+        throw new Error("--host, --port, and --loopback are only supported for `mono-agent web`.");
     }
     if (cmd === "web" && (configPath !== undefined || envFile !== undefined)) {
-        throw new Error("The machine-wide `mono-agent web` console does not load an agent --config or --env-file; use `mono-agent sessions` for the recorder.");
+        throw new Error("The machine-wide `mono-agent web` console does not load an agent --config or --env-file.");
     }
-    if (includeMemory && cmd !== "audit-runs" && cmd !== "metrics" && cmd !== "backfill" && cmd !== "sessions") {
-        throw new Error("--include-memory is only supported for `mono-agent audit-runs`, `mono-agent metrics`, `mono-agent backfill`, and `mono-agent sessions`.");
+    if (includeMemory && cmd !== "runs" && cmd !== "backfill") {
+        throw new Error("--include-memory is only supported for `mono-agent runs` and `mono-agent backfill`.");
     }
     if (limit !== undefined && cmd !== "memory" && cmd !== "continuations") {
         throw new Error("--limit is only supported for `mono-agent memory` and `mono-agent continuations list`.");
@@ -453,13 +475,26 @@ export function parseCliArgs(argv) {
     if (codexAuthMode !== undefined && cmd !== "init" && cmd !== "auth") {
         throw new Error("--codex-auth is only supported for `mono-agent init` and `mono-agent auth login codex`.");
     }
-    if (fallbackModels !== undefined && fallbacks.length > 0) {
-        throw new Error("Use either legacy --fallback-models or repeated --fallback flags, not both.");
+    if (clearSessions && cmd !== "restart") {
+        throw new Error("--clear-sessions is only supported for `mono-agent restart`.");
+    }
+    // `--json` is uniform on the read/status surfaces only. Reject it on the
+    // lifecycle/interactive commands (init, auth, start, stop, restart, logs, tui,
+    // web, backfill) rather than silently ignoring it. `doctor`/`setup`/
+    // `audit-runs`/`metrics` already normalized to their canonical `cmd` above.
+    if (json && !JSON_CAPABLE_COMMANDS.includes(cmd)) {
+        throw new Error(`--json is not supported for \`mono-agent ${cmd}\`; it is available on ${JSON_CAPABLE_COMMANDS_DISPLAY}.`);
+    }
+    // `install-skill` exposes JSON only for its read-only drift check.
+    if (json && cmd === "install-skill" && !(project && check)) {
+        throw new Error("--json is only supported for `mono-agent install-skill --project --check`.");
     }
-    if (fallbackModels !== undefined && new Set(fallbackModels).size !== fallbackModels.length) {
-        throw new Error("--fallback-models contains a duplicate model reference.");
+    // `sandbox setup`/`sandbox check` are interactive/side-effecting; only the
+    // read-only `sandbox status` emits JSON.
+    if (json && cmd === "sandbox" && (positionals[0] === "setup" || positionals[0] === "check")) {
+        throw new Error("--json is only supported for `mono-agent sandbox status`, not setup or check.");
     }
-    const selectedFallbackModels = fallbackModels ?? fallbacks.map((fallback) => fallback.model);
+    const selectedFallbackModels = fallbacks.map((fallback) => fallback.model);
     if (model !== undefined && selectedFallbackModels.includes(model)) {
         throw new Error(`Primary --model \`${model}\` cannot also be a fallback.`);
     }
@@ -468,13 +503,11 @@ export function parseCliArgs(argv) {
         ...(configPath === undefined ? {} : { configPath }),
         ...(name === undefined ? {} : { name }),
         ...(model === undefined ? {} : { model }),
-        ...(fallbackModels === undefined ? {} : { fallbackModels }),
         ...(fallbacks.length === 0 ? {} : { fallbacks }),
         ...(routeSafety === undefined ? {} : { routeSafety }),
         ...(effort === undefined ? {} : { effort }),
         ...(memory === undefined ? {} : { memory }),
         ...(preset === undefined ? {} : { preset }),
-        ...(recipe === undefined ? {} : { recipe }),
         ...(withChannels === undefined ? {} : { withChannels }),
         ...(yes ? { yes } : {}),
         ...(auth ? { auth } : {}),
@@ -484,8 +517,10 @@ export function parseCliArgs(argv) {
         positionals,
         ...(envFile === undefined ? {} : { envFile }),
         ...(expectedBackgroundSnapshot === undefined ? {} : { expectedBackgroundSnapshot }),
+        ...(expectedManagedRuntimeLaunch === undefined ? {} : { expectedManagedRuntimeLaunch }),
         ...(target === undefined ? {} : { target }),
         force,
+        ...(clearSessions ? { clearSessions } : {}),
         foreground,
         follow,
         ...(lines === undefined ? {} : { lines }),
@@ -514,13 +549,10 @@ export function parseCliArgs(argv) {
         ...(project ? { project } : {}),
         ...(check ? { check } : {}),
         ...(update ? { update } : {}),
+        ...(noDocsMcp ? { noDocsMcp } : {}),
         ...(host === undefined ? {} : { host }),
         ...(port === undefined ? {} : { port }),
         ...(loopback ? { loopback } : {}),
-        ...(open === undefined ? {} : { open }),
-        ...(allowNonLoopback === undefined ? {} : { allowNonLoopback }),
-        ...(showAuthUrl === undefined ? {} : { showAuthUrl }),
-        ...(maxRunsPerInstance === undefined ? {} : { maxRunsPerInstance }),
     };
 }
 /**