@0dai-dev/cli 4.3.5 → 4.3.7

package/README.md

@@ -43,39 +43,36 @@ Daily (regular work):
 0dai run <goal>                     # split a backlog item into agent tasks [--dry-run] [--dry-cost] [--agent claude|codex|gemini]
 0dai swarm status                   # show queued, active, and done tasks
 0dai swarm add                      # queue one task [--task '...' --to agent]
-0dai swarm-run                      # add, dispatch, and wait for one swarm task as JSON
+0dai swarm pick                     # pick one queued task [--agent codex]
+0dai swarm-run                      # repo-checkout helper: add, dispatch, and wait for one swarm task as JSON
 0dai harvest                        # convert experience events into candidate lessons
 0dai watch                          # live task monitor [--interval N]
 0dai reflect                        # session reflection: delivered, delegation, blockers
-0dai standup                        # morning voice briefing about overnight agent work
-0dai feedback push                  # send feedback to 0dai
+0dai standup                        # repo-checkout helper: morning voice briefing about overnight agent work
+0dai feedback push --target .       # send feedback to 0dai
 0dai feedback retry                 # retry queued feedback after a failed push
-0dai persona-simulate "topic"       # focus-group report and optional issue drafts
 ```
 
 Pro / advanced:
 
 ```bash
 0dai init-existing                  # existing-repo setup alias for init
-0dai project bind                   # bind repository to your 0dai account [--json]
+0dai project bind                   # bind repository to your 0dai account [--name NAME] [--json]
 0dai project status                 # local project binding and health [--json]
 0dai graph push                     # upload local graph (Pro: edges, Free: nodes)
 0dai graph pull                     # download server graph and merge locally
 0dai graph status                   # local graph stats and sync state
-0dai ci                             # portable CI pipelines and AI-MQ [list|plan|mq-status]
 0dai heatmap                        # repo treemap: LOC × agent-edit intensity
 0dai session save                   # save session for roaming
-0dai provider                       # local provider profiles and direct invoke
+0dai provider                       # provider profiles and local BYOK registry [status|list|switch|clear]
 0dai models                         # model ratings (--fast/--balanced/--deep/--available)
 0dai quota                          # agent subscription usage [--refresh] [--json]
 0dai usage                          # local token, task, and USD ledger [status|daily|monthly]
 0dai workspace                      # tmux workspace sessions (init|up|status)
-0dai runner                         # runner/host architecture and queues [--json]
-0dai report                         # privacy-safe project reports (preview|push|status)
+0dai report                         # repo-checkout helper: privacy-safe project reports (preview|push|status)
 0dai compliance                     # SOC2/ISO evidence and ADR audit-trail export
-0dai experience                     # structured experience events (list|stats|sync|warnings|dismiss)
+0dai experience                     # structured experience events (list|stats|record-json|sync|warnings|dismiss)
 0dai receipt                        # session receipt PNG [--last|--active|--session ID]
-0dai boneyard                       # weekly digest of worst agent moves [--week YYYY-WW|current]
 0dai gh branch-protection           # GitHub branch protection [print|apply|install]
 0dai import claude-code-agents      # import .claude/agents/*.md as personas [--dry-run]
 0dai auth logout                    # remove credentials
@@ -100,6 +97,10 @@ Global flags: `--target PATH`, `--version`, `--help`, `--json`, `--quiet`. See `
 
 Your source code is never sent. Only file names and package/build manifests.
 
+## Privacy
+
+Local activation and experience records stay on your machine: `ai/meta/telemetry/activation.jsonl`, `ai/experience/`, and the generated `ai/` layer/project agent configs are local files. Server-side activation sends one `free_tier_activated` event when you run `0dai activate free` unless telemetry is opted out. See https://0dai.dev/legal/privacy.
+
 ## Why 0dai, not just Cursor or Copilot?
 
 Cursor and Copilot are editors. They help inside one coding session. 0dai writes a project layer that Claude Code, Codex, OpenCode, Gemini, and Aider can all read. The point is not another autocomplete box; it is one manifest, one set of agent roles, one task queue, and one health check for the repo.

package/bin/0dai.js

@@ -26,23 +26,63 @@ if ((earlyParsed.args[0] || "help") === "swarm-run") {
 }
 
 const shared = require("../lib/shared");
-const { T, R, D, log, VERSION, fs, path, spawnSync, findRepoScript, checkVersion } = shared;
+const { T, R, D, log, VERSION, fs, path, spawnSync, findRepoScript, repoScriptCandidates, checkVersion } = shared;
 
 /**
  * Hot-path Go binary fallback (issue #2424).
  *
- * For read-only hot-path commands (status/doctor/version) we attempt to delegate
- * to a Go binary when:
+ * For read-only hot-path commands we attempt to delegate to a Go binary when:
  *   1. ODAI_GO_BIN is set and points at an executable file, OR a binary called
  *      `0dai-go` is found on PATH.
- *   2. The binary reports `binary_version` matching the dispatcher VERSION
- *      (we accept exact match only — drift means fall back to Python/Node).
+ *   2. The binary reports `dispatcher_compat_version` matching the dispatcher
+ *      VERSION (legacy binaries may still use `binary_version` for this).
  *   3. ODAI_GO_DISABLE is NOT set to a truthy value.
+ *   4. The command's batch flag is not disabled. SPEC-035 rollback Level 1
+ *      is `ODAI_GO_BATCH_<N>=0`, which transparently routes the whole batch
+ *      back to the Node/Python implementation without reinstalling.
+ *
+ * Only commands listed in GO_HOT_PATH_COMMANDS are eligible for automatic
+ * delegation. `status` moved into batch 2 only after the #4098 Go↔Node
+ * payload parity proof landed. Base `doctor` moved into the same batch only
+ * after #4111 made the local `doctor_checks` shadow contract explicit;
+ * `doctor --drift` stays on the full Node implementation.
  *
  * If any of these checks fail we silently fall through to the existing
  * Python/Node implementations. The goal is zero behaviour change when the Go
  * binary is missing, broken, or version-skewed.
  */
+const GO_HOT_PATH_COMMANDS = new Set(["version", "status", "doctor"]);
+const GO_HOT_PATH_BATCHES = Object.freeze({
+  version: 1,
+  status: 2,
+  doctor: 2,
+});
+
+function goFlagDisabled(raw) {
+  if (raw === undefined || raw === null || raw === "") return false;
+  const value = String(raw).trim().toLowerCase();
+  return ["0", "false", "no", "off"].includes(value);
+}
+
+function goCommandEnvName(cmdName) {
+  return `ODAI_GO_COMMAND_${String(cmdName).toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+}
+
+function goBatchEnvName(batch) {
+  return `ODAI_GO_BATCH_${batch}`;
+}
+
+function goBatchEnabled(cmdName) {
+  const batch = GO_HOT_PATH_BATCHES[cmdName];
+  if (!batch) return false;
+  if (goFlagDisabled(process.env[goBatchEnvName(batch)])) return false;
+
+  // Drill-only per-command rollback override. Batch flags remain the release
+  // contract; this override is intentionally narrower for staging drills.
+  if (goFlagDisabled(process.env[goCommandEnvName(cmdName)])) return false;
+  return true;
+}
+
 function locateGoBinary() {
   if (process.env.ODAI_GO_DISABLE && process.env.ODAI_GO_DISABLE !== "0") return null;
   const explicit = process.env.ODAI_GO_BIN;
@@ -68,7 +108,11 @@ function goBinaryCompatible(binPath) {
     if (res.status !== 0 || !res.stdout) return false;
     const info = JSON.parse(res.stdout.toString());
     if (!info || typeof info.binary_version !== "string") return false;
-    return info.binary_version === VERSION;
+    const compatVersion =
+      typeof info.dispatcher_compat_version === "string"
+        ? info.dispatcher_compat_version
+        : info.binary_version;
+    return compatVersion === VERSION;
   } catch {
     return false;
   }
@@ -80,18 +124,32 @@ function goBinaryCompatible(binPath) {
  * caller must fall back to the existing Python/Node path.
  */
 function tryGoHotPath(cmdName, target, argv) {
+  if (!GO_HOT_PATH_COMMANDS.has(cmdName)) return false;
+  if (!goBatchEnabled(cmdName)) return false;
   const bin = locateGoBinary();
   if (!bin) return false;
   if (!goBinaryCompatible(bin)) return false;
   const forwarded = [cmdName, "--target", target, ...argv];
-  const res = spawnSync(bin, forwarded, { stdio: "inherit" });
+  const res = spawnSync(bin, forwarded, {
+    stdio: "inherit",
+    env: { ...process.env, ODAI_NODE_PTY_PROBE_DIR: path.join(__dirname, "..") },
+  });
   if (res.error) return false;
   if (typeof res.status === "number") process.exit(res.status);
   process.exit(0);
 }
 
 // Export for tests; harmless at runtime.
-module.exports = { locateGoBinary, goBinaryCompatible, tryGoHotPath };
+module.exports = {
+  locateGoBinary,
+  goBinaryCompatible,
+  goBatchEnabled,
+  goBatchEnvName,
+  goCommandEnvName,
+  tryGoHotPath,
+  GO_HOT_PATH_BATCHES,
+  GO_HOT_PATH_COMMANDS,
+};
 const { loadCanonicalCounts, mcpToolsLabel } = require("../lib/utils/canonical-counts");
 
 // --- Command imports ---
@@ -99,7 +157,10 @@ const { cmdAuthLogin, cmdAuthLogout, cmdRedeem, cmdAuthStatus, cmdAuthMcp, cmdAc
 const { cmdInit, cmdSync, cmdProjectBind } = require("../lib/commands/init");
 const { cmdDetect } = require("../lib/commands/detect");
 const { cmdAudit } = require("../lib/commands/audit");
-const { cmdDoctor } = require("../lib/commands/doctor");
+const { cmdExport } = require("../lib/commands/export");
+const { cmdMcp } = require("../lib/commands/mcp");
+const { cmdVault } = require("../lib/commands/vault");
+const { cmdDoctor, collectLayerVersionFreshness } = require("../lib/commands/doctor");
 const { cmdValidate } = require("../lib/commands/validate");
 const { cmdUpdate } = require("../lib/commands/update");
 const { cmdUpgrade } = require("../lib/commands/upgrade");
@@ -110,7 +171,7 @@ const { cmdStatus } = require("../lib/commands/status");
 const { cmdPortfolio } = require("../lib/commands/portfolio");
 const { cmdRun } = require("../lib/commands/run");
 const { cmdWatch } = require("../lib/commands/watch");
-const { cmdModels } = require("../lib/commands/models");
+const { cmdModels, cmdModelsRecommend } = require("../lib/commands/models");
 const { cmdSession } = require("../lib/commands/session");
 const { cmdSwarm, cmdSwarmRun } = require("../lib/commands/swarm");
 const { cmdStandup } = require("../lib/commands/standup");
@@ -135,10 +196,18 @@ const { cmdLoop } = require("../lib/commands/loop");
 const { cmdImportClaudeCodeAgents } = require("../lib/commands/import_claude_code_agents");
 const { cmdRunner } = require("../lib/commands/runner");
 const { cmdCi } = require("../lib/commands/ci");
+const { cmdTrust } = require("../lib/commands/trust");
 
 function printHelp() {
   const counts = loadCanonicalCounts();
   console.log(`\n  ${T}0dai${R} v${VERSION} — One config for ${counts.agent_clis_total} AI agent CLIs · ${mcpToolsLabel(counts)}\n`);
+  console.log("First-run sequence (canonical):");
+  console.log("  npm install -g @0dai-dev/cli   # install once, globally");
+  console.log("  0dai auth login                # sign in (OAuth / device code)");
+  console.log("  0dai activate free             # claim free-tier license");
+  console.log("  0dai init                      # generate ai/ layer in cwd");
+  console.log("  0dai doctor                    # verify health and drift");
+  console.log("");
   console.log("Start (first 5 minutes):");
   console.log("  init           Create ai/ layer + MCP [--local] [--dry-run] [--minimal]");
   console.log("  doctor         Check health, credentials, and drift [--drift]");
@@ -155,36 +224,38 @@ function printHelp() {
   console.log("  run <goal>     Split a backlog item into agent tasks [--dry-run] [--dry-cost] [--max-cost N] [--agent claude|codex|gemini] [--provider X]");
   console.log("  swarm status   Show queued, active, and done tasks");
   console.log("  swarm add      Queue one task for an agent [--task '...' --to agent]");
-  console.log("  swarm-run      Add, dispatch, and wait for one swarm task as JSON");
+  console.log("  swarm pick     Pick one queued task for this agent [--agent codex]");
+  console.log("  swarm-run      Repo-checkout helper: add, dispatch, and wait for one swarm task as JSON");
   console.log("  harvest        Convert experience events into candidate lessons");
   console.log("  watch          Live task monitor: queue, active, recently done [--interval N]");
   console.log("  reflect        Session reflection: delivered, delegation rate, blockers");
-  console.log("  standup        Morning voice briefing about overnight agent work");
+  console.log("  standup        Repo-checkout helper: morning voice briefing about overnight agent work");
   console.log("  feedback push  Send feedback to 0dai");
+  console.log("  feedback submit Send one feedback report file [--file ai/feedback/codex-report.json]");
   console.log("  feedback retry Retry queued feedback after a failed push");
   console.log("");
   console.log("Pro / advanced:");
-  console.log("  init-existing  Existing-repo setup alias for init [--minimal] [--dry-run]");
-  console.log("  project bind   Bind current repository to your 0dai account [--json]");
+  console.log("  init-existing  Legacy alias for init (older docs / scripted bootstraps); use 'init' [--minimal] [--dry-run]");
+  console.log("  project bind   Bind current repository to your 0dai account [--name NAME] [--json]");
   console.log("  project status Show local project binding and health state [--json]");
   console.log("  graph push     Upload local graph to server (Pro: edges, Free: nodes)");
   console.log("  graph pull     Download server graph and merge locally");
   console.log("  graph status   Show local graph stats and sync state");
-  console.log("  ci             Plan portable 0dai CI pipelines and inspect AI-MQ [list|plan|mq-status] [--json]");
+  console.log("  mcp            MCP server, tools, and health [list|catalog|doctor|call] [--json]");
+  console.log("  vault          Local age-encrypted secrets vault [init|add|get] [--json]");
   console.log("  heatmap        Repo treemap: LOC x agent-edit intensity");
   console.log("  session save   Save session for roaming");
-  console.log("  provider       Local provider profiles, bindings, and direct invoke");
+  console.log("  provider       Local provider profiles and BYOK registry [status|list|switch|clear]");
   console.log("  models         Show model ratings (--fast/--balanced/--deep/--available)");
+  console.log("  models recommend  Ledger-ranked model pick for a task type [--task TYPE] [--goal '...'] [--json]");
   console.log("  quota          Agent subscription usage table [--refresh] [--json]");
   console.log("  usage          Local token, task, and USD usage ledger [status|daily|monthly]");
   console.log("  workspace      Manage tmux workspace sessions (init|up|status)");
-  console.log("  runner         Show runner/project-host architecture, queues, labels, and burst routing [status|plan|queue-status|label-audit|route-dry-run] [--json]");
-  console.log("  report         Privacy-safe project reports (preview|push|status)");
+  console.log("  report         Repo-checkout helper: privacy-safe project reports (preview|push|status)");
+  console.log("  trust          Pre-run blast-radius: protected paths, authority matrix, egress [--json]");
   console.log("  compliance     SOC2/ISO evidence and ADR audit-trail export");
-  console.log("  experience     Structured experience events (list|stats|sync|warnings|dismiss)");
-  console.log("  persona-simulate  Produce a focus-group report and optional issue drafts");
+  console.log("  experience     Structured experience events (list|stats|record-json|sync|warnings|dismiss)");
   console.log("  receipt        Render a 1200×630 session receipt PNG [--last|--active|--session ID]");
-  console.log("  boneyard       Weekly digest of worst agent moves [--week YYYY-WW|current]");
   console.log("  gh branch-protection [print|apply|install]  Manage generated GitHub branch protection");
   console.log("  import claude-code-agents  Import .claude/agents/*.md as 0dai personas [--source DIR] [--target DIR] [--dry-run]");
   console.log("  auth logout    Remove credentials");
@@ -200,29 +271,105 @@ function printHelp() {
   console.log("https://0dai.dev");
 }
 
+function explainMissingHarvestHelper(target, args) {
+  const candidates = repoScriptCandidates(target, "harvest_experience.py");
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({
+      error: "harvest_helper_unavailable",
+      helper: "harvest_experience.py",
+      target,
+      looked_in: candidates,
+      fallback_inputs: [
+        "ai/experience/events/*.json",
+        "ai/experience/events/*.jsonl",
+        "ai/experience/outbox/*.json",
+        "ai/experience/outbox/*.jsonl",
+      ],
+      required_fallback_fields: [
+        "schema",
+        "event_id",
+        "timestamp",
+        "event_type",
+        "tool",
+        "task_type",
+        "summary",
+        "paths",
+        "ci_passed",
+        "source",
+      ],
+    }, null, 2));
+    return;
+  }
+
+  log("harvest helper unavailable");
+  if (!args.includes("--explain")) return;
+
+  console.log(`  ${D}looked for scripts/harvest_experience.py at:${R}`);
+  for (const candidate of candidates) {
+    console.log(`  - ${candidate}`);
+  }
+  console.log(`  ${D}fallback event inputs:${R}`);
+  console.log("  - ai/experience/events/*.json");
+  console.log("  - ai/experience/events/*.jsonl");
+  console.log("  - ai/experience/outbox/*.json");
+  console.log("  - ai/experience/outbox/*.jsonl");
+  console.log(`  ${D}fallback schema fields:${R}`);
+  console.log("  schema, event_id, timestamp, event_type, tool, task_type, summary, paths, ci_passed, source");
+}
+
 const SYNC_ALLOWED_FLAGS = new Set([
+  "--check",
   "--dry-run",
   "--yes",
   "-y",
   "--quiet",
   "-q",
   "--force",
+  "--force-template-reset",
   "--no-diff",
   "--no-mcp-auth",
   "--skip-link-check",
   "--strict-links",
 ]);
 
+function printInitHelp(commandName = "init") {
+  console.log(`\n  ${T}0dai ${commandName}${R} — Create or refresh the managed ai/ layer\n`);
+  console.log("Usage:");
+  console.log(`  0dai ${commandName} [--local] [--minimal] [--dry-run] [--no-wizard] [--auth-code CODE] [--code LICENSE] [--no-mcp-auth] [--mcp-host HOST] [--reset] [--target PATH]`);
+  console.log("");
+  console.log("Options:");
+  console.log("  --local        Generate the ai/ layer offline without signing in");
+  console.log("  --minimal      Generate the smallest starter layer");
+  console.log("  --dry-run      Preview init changes without writing them");
+  console.log("  --no-wizard    Skip the interactive first-run wizard");
+  console.log("  --auth-code    Exchange a browser/device auth code before init");
+  console.log("  --code         Redeem an activation/license code before init");
+  console.log("  --no-mcp-auth  Skip MCP cloud-token bootstrap during init");
+  console.log("  --mcp-host     Use a custom MCP cloud host");
+  console.log("  --reset        Overwrite managed MCP entries during bootstrap");
+  console.log("  --target PATH  Run init against another project path");
+  console.log("");
+}
+
+function handleInitHelp(args) {
+  const initArgs = args.slice(1);
+  if (!initArgs.includes("--help") && !initArgs.includes("-h")) return false;
+  printInitHelp(args[0] || "init");
+  return true;
+}
+
 function printSyncHelp() {
   console.log(`\n  ${T}0dai sync${R} — Update the managed ai/ layer\n`);
   console.log("Usage:");
-  console.log("  0dai sync [--dry-run] [--yes|-y] [--quiet|-q] [--force] [--no-diff] [--no-mcp-auth] [--target PATH]");
+  console.log("  0dai sync [--check] [--dry-run] [--yes|-y] [--quiet|-q] [--force] [--force-template-reset] [--no-diff] [--no-mcp-auth] [--target PATH]");
   console.log("");
   console.log("Options:");
+  console.log("  --check        CI-friendly alias for --dry-run --quiet");
   console.log("  --dry-run      Preview managed file changes without writing them");
   console.log("  --yes, -y      Apply changes without an interactive confirmation prompt");
   console.log("  --quiet, -q    Reduce non-essential output");
   console.log("  --force        Also overwrite native config files from managed ai/ sources");
+  console.log("  --force-template-reset  Allow replacing project-owned roadmap/manifest state");
   console.log("  --no-diff      Hide unified diff output in previews/prompts");
   console.log("  --no-mcp-auth  Skip MCP cloud-token bootstrap during sync");
   console.log("  --skip-link-check  Skip the SPEC-028 doc cross-link scan after sync");
@@ -248,6 +395,24 @@ function handleSyncHelpOrInvalidArgs(args) {
   return false;
 }
 
+function printActivateHelp() {
+  console.log(`\n  ${T}0dai activate${R} — Claim or inspect a 0dai activation\n`);
+  console.log("Usage:");
+  console.log("  0dai activate [free|status|code <CODE>] [--target PATH]");
+  console.log("");
+  console.log("Privacy:");
+  console.log("  Local files stay local; 'activate free' sends one free_tier_activated event unless telemetry is opted out.");
+  console.log("  https://0dai.dev/legal/privacy");
+  console.log("");
+}
+
+function handleActivateHelp(args) {
+  const activateArgs = args.slice(1);
+  if (!activateArgs.includes("--help") && !activateArgs.includes("-h")) return false;
+  printActivateHelp();
+  return true;
+}
+
 async function main() {
   const { args, target } = parseTargetAndArgs(process.argv.slice(2), process.cwd());
 
@@ -263,8 +428,18 @@ async function main() {
     return;
   }
 
-  // Non-blocking version check (runs in background, once per day)
-  checkVersion();
+  if ((cmd === "init" || cmd === "init-existing") && handleInitHelp(args)) {
+    return;
+  }
+
+  if (cmd === "activate" && handleActivateHelp(args)) {
+    return;
+  }
+
+  // Non-blocking version check (runs in background, once per day). Skip
+  // machine-readable commands so update network I/O never holds JSON output
+  // open or pollutes stdout.
+  if (!args.includes("--json") && cmd !== "init" && cmd !== "init-existing") checkVersion();
 
   // Track first run for time-to-init telemetry
   try { require("../lib/onboarding").trackFirstRun(target); } catch {}
@@ -288,6 +463,8 @@ async function main() {
     case "run": await cmdRun(args[1] || "", target, args.slice(2)); break;
     case "watch": cmdWatch(target, args.slice(1)); break;
     case "audit": cmdAudit(target); break;
+    case "export": await cmdExport(target, args); break;
+    case "vault": cmdVault(target, args[1], args.slice(2)); break;
     case "security": {
       const subSec = args[1] || "";
       if (subSec === "install-hook") {
@@ -328,24 +505,15 @@ async function main() {
       const driftMode = args.includes("--drift");
       // Go fast-path covers only the base read-only doctor (no --drift, no
       // network). Anything else falls through to the full Node implementation.
-      if (!driftMode) {
+      const layerFreshness = collectLayerVersionFreshness(target);
+      if (!driftMode && layerFreshness.status !== "stale") {
         tryGoHotPath("doctor", target, args.slice(1));
       }
-      cmdDoctor(target, { drift: driftMode });
-      if (args.includes("--drift")) {
-        const ds = findRepoScript(target, "drift_detector.py");
-        console.log("\n  drift report:");
-        if (ds) {
-          const result = spawnSync("python3", [ds, "report", "--target", target], { stdio: "inherit" });
-          if (typeof result.status === "number" && result.status !== 0) process.exit(result.status);
-        } else {
-          console.log(`  ${D}drift detector unavailable in this environment${R}`);
-        }
-      }
+      cmdDoctor(target, { drift: driftMode, json: args.includes("--json") });
       break;
     }
     case "drift": {
-      const ds = findRepoScript(target, "drift_detector.py");
+      const ds = shared.resolvePythonScript(target, "drift_detector.py");
       if (!ds) { log("drift detector unavailable"); break; }
       if (sub === "accept" && args[2]) {
         spawnSync("python3", [ds, "accept", args[2], "--target", target], { stdio: "inherit" });
@@ -370,7 +538,7 @@ async function main() {
     case "project":
       if (sub === "status") cmdStatus(target, { json: args.includes("--json") });
       else if (sub === "bind") await cmdProjectBind(target, args.slice(2));
-      else console.log("Usage: 0dai project [bind [--json]|status [--json]] [--target PATH]");
+      else console.log("Usage: 0dai project [bind [--name NAME] [--json]|status [--json]] [--target PATH]");
       break;
     case "auth":
       if (sub === "login") await cmdAuthLogin(args.slice(2));
@@ -385,6 +553,8 @@ async function main() {
       else if (sub === "code" || sub === "redeem") await cmdRedeem(args[2]);
       else console.log("Usage: 0dai activate [free|status|code <CODE>]");
       break;
+    case "mcp": cmdMcp(target, sub, args); break;
+    case "vault": cmdVault(target, args[1], args.slice(2)); break;
     case "session": cmdSession(target, sub, args); break;
     case "swarm": cmdSwarm(target, sub, args); break;
     case "workspace": cmdWorkspace(target, sub, args.slice(2)); break;
@@ -406,7 +576,7 @@ async function main() {
     case "feedback": await cmdFeedback(target, sub, args); break;
     case "harvest": {
       const harvestScript = findRepoScript(target, "harvest_experience.py");
-      if (!harvestScript) { log("harvest helper unavailable"); break; }
+      if (!harvestScript) { explainMissingHarvestHelper(target, args); break; }
       const result = spawnSync("python3", [harvestScript, "--target", target, ...args.slice(1)], { stdio: "inherit", timeout: 15000 });
       if (typeof result.status === "number" && result.status !== 0) process.exit(result.status);
       break;
@@ -438,11 +608,15 @@ async function main() {
       break;
     }
     case "report": cmdReport(target, sub, args); break;
+    case "trust": cmdTrust(target, args.slice(1)); break;
     case "compliance": cmdCompliance(target, args.slice(1)); break;
     case "experience": cmdExperience(target, sub, args); break;
     case "persona-simulate": cmdPersonaSimulate(target, args.slice(1)); break;
     case "graph": await cmdGraph(target, sub, args); break;
-    case "models": cmdModels(sub || args[1]); break;
+    case "models":
+      if (sub === "recommend") await cmdModelsRecommend(target, args.slice(2));
+      else cmdModels(sub || args[1]);
+      break;
     case "delegate": case "delegation": {
       const deScript = findRepoScript(target, "delegation_engine.py");
       if (!deScript) { log("delegation engine unavailable"); break; }

package/lib/ai/manifest/mcp-exposure-contract.json

@@ -0,0 +1,121 @@
+{
+  "schema_version": 1,
+  "updated_at": "2026-05-28",
+  "purpose": "Expected MCP exposure contract for agent runtimes. Health checks compare observed tool names against this manifest and scripts/mcp_tier_config.py.",
+  "project_server": {
+    "name": "0dai",
+    "config_path": ".mcp.json",
+    "tool_count_source": "scripts/mcp_tier_config.py",
+    "expected_tool_count": 113
+  },
+  "normalization": {
+    "accepted_examples": [
+      "memory_search",
+      "mcp__0dai__memory_search",
+      "mcp__0dai_internal__.memory_search",
+      "mcp__0dai_internal__memory_search"
+    ],
+    "rule": "Compare by canonical tool basename after MCP namespace prefixes."
+  },
+  "agents": {
+    "default": {
+      "required": [
+        "memory_search",
+        "get_project_health",
+        "get_codebase_map",
+        "record_experience"
+      ],
+      "recommended": [
+        "get_anomaly_taxonomy",
+        "get_anomaly_events",
+        "get_anomaly_summary",
+        "memory_add",
+        "memory_inject",
+        "search_experience",
+        "get_project_graph",
+        "get_specs",
+        "get_session",
+        "save_session",
+        "get_wal"
+      ]
+    },
+    "codex": {
+      "inherits": "default",
+      "required": [
+        "memory_search",
+        "get_project_health",
+        "get_codebase_map",
+        "record_experience"
+      ],
+      "recommended": [
+        "get_anomaly_taxonomy",
+        "get_anomaly_events",
+        "get_anomaly_summary",
+        "record_anomaly",
+        "memory_add",
+        "memory_inject",
+        "search_experience",
+        "get_project_graph",
+        "get_specs",
+        "get_session",
+        "save_session",
+        "swarm_delegate",
+        "watch_tasks",
+        "get_portfolio",
+        "get_wal"
+      ]
+    },
+    "claude": {
+      "inherits": "default",
+      "required": [
+        "memory_search",
+        "get_project_health",
+        "get_codebase_map",
+        "record_experience",
+        "get_session",
+        "save_session"
+      ],
+      "recommended": [
+        "get_anomaly_taxonomy",
+        "get_anomaly_events",
+        "get_anomaly_summary",
+        "record_anomaly",
+        "memory_add",
+        "memory_inject",
+        "search_experience",
+        "swarm_delegate",
+        "watch_tasks",
+        "get_portfolio",
+        "gh_label_create",
+        "gh_issue_edit_body"
+      ]
+    },
+    "pool": {
+      "inherits": "default",
+      "required": [
+        "memory_search",
+        "get_project_health",
+        "get_codebase_map",
+        "record_experience",
+        "watch_tasks"
+      ],
+      "recommended": [
+        "get_anomaly_taxonomy",
+        "get_anomaly_events",
+        "get_anomaly_summary",
+        "memory_add",
+        "search_experience",
+        "swarm_delegate",
+        "run_task",
+        "get_swarm_status",
+        "save_session"
+      ]
+    }
+  },
+  "statuses": {
+    "green": "All required and recommended tools for the agent were observed.",
+    "yellow": "Required tools were observed, but recommended tools or full server count evidence is missing.",
+    "red": "One or more required tools are missing from the observed runtime.",
+    "unknown": "No observed tool evidence was supplied by the runtime."
+  }
+}