@0dai-dev/cli 4.3.6 → 4.3.7

package/lib/commands/mcp.js

@@ -5,9 +5,10 @@
  *
  * Subcommands (all read-only / inspection):
  *   - list [--plan free|pro|team|enterprise] [--json]
- *       Enumerate MCP tools exposed by scripts/mcp_server.py.
+ *       Enumerate MCP tools exposed by the MCP tier manifest.
  *       Resolves from ai/meta/manifest/mcp-tool-tiers.json when present,
- *       falls back to scanning @mcp.tool decorators in scripts/mcp_server.py.
+ *       falls back to package metadata, then scans @mcp.tool decorators in
+ *       scripts/mcp_server.py for repo checkouts.
  *   - catalog [--stack NAME] [--json]
  *       Show the per-stack MCP server catalog (common + stack servers)
  *       from templates/layer/ai/registry/mcp-catalog.json.
@@ -16,6 +17,8 @@
  *   - call <tool> [--json '<args>'] [--json-out]
  *       Invoke a single MCP tool synchronously via scripts/mcp_server.py
  *       (no daemon spawn — direct in-process call inside the helper subprocess).
+ *       This is a repo-checkout helper; npm installs use the OAuth HTTP /mcp
+ *       entry for live MCP calls.
  *
  * This command never mutates project state. It is the documented
  * counterpart of the `mcp list` / `mcp call` / `mcp catalog` docs and the
@@ -31,9 +34,9 @@ function _printHelp() {
   console.log("  0dai mcp list     [--plan free|pro|team|enterprise] [--json]");
   console.log("  0dai mcp catalog  [--stack NAME] [--json]");
   console.log("  0dai mcp doctor   [--json]");
-  console.log("  0dai mcp call <tool> [--json '<json-args>'] [--json-out]");
+  console.log("  0dai mcp call <tool> [--json '<json-args>'] [--json-out]  (repo-checkout helper)");
   console.log("");
-  console.log("Read-only inspection of the project's MCP server (scripts/mcp_server.py).");
+  console.log("Read-only inspection of MCP metadata; live npm MCP calls use the claude_ai_0dai HTTP /mcp entry.");
   console.log("");
 }
 
@@ -59,12 +62,20 @@ function _readJsonFile(filePath) {
   }
 }
 
-function _toolsFromTierManifest(target, plan) {
-  const candidates = [
+function _packageDataPath(...parts) {
+  return path.join(__dirname, "..", ...parts);
+}
+
+function _tierManifestCandidates(target) {
+  return [
     path.join(target, "ai", "meta", "manifest", "mcp-tool-tiers.json"),
     path.join(target, "ai", "manifest", "mcp-tool-tiers.json"),
+    _packageDataPath("ai", "meta", "manifest", "mcp-tool-tiers.json"),
   ];
-  for (const candidate of candidates) {
+}
+
+function _toolsFromTierManifest(target, plan) {
+  for (const candidate of _tierManifestCandidates(target)) {
     if (!fs.existsSync(candidate)) continue;
     const data = _readJsonFile(candidate);
     if (!data || typeof data !== "object") continue;
@@ -125,6 +136,7 @@ function _resolveCatalogPath(target) {
   const candidates = [
     path.join(target, "ai", "registry", "mcp-catalog.json"),
     path.join(target, "templates", "layer", "ai", "registry", "mcp-catalog.json"),
+    _packageDataPath("ai", "registry", "mcp-catalog.json"),
   ];
   // Also look next to the npm package (when run from a sync'd repo elsewhere).
   const repoRoot = path.resolve(__dirname, "..", "..", "..", "..");
@@ -203,14 +215,12 @@ function _cmdCatalog(target, args) {
   console.log(`\n  ${T}available stacks${R}: ${available.join(", ")}\n`);
 }
 
-// Flag MCP server entries left behind by a pre-4.3 `0dai sync` that no longer
-// connect. Two dead patterns: the deprecated `/sse` operator endpoint (HTTP 404,
-// 0dai-dev/docs#56) and the `transport: "sse"` form. `mergeMcpConfig` only manages
-// its own servers and never prunes unknown user entries -- even with --reset -- so
-// these persist after upgrade until removed by hand. The current generator connects
-// operator-MCP via the headerless "claude.ai 0dai" (OAuth /mcp) entry, so the stale
-// block is dead weight. Detection stays on the unambiguous /sse signal to avoid
-// false positives on a legitimately-wired bearer host-pool config (#57).
+// Flag MCP server entries left behind by older `0dai sync` runs that no longer
+// connect. `mergeMcpConfig` only manages its own servers and never prunes unknown
+// user entries -- even with --reset -- so these persist after upgrade until
+// removed by hand. The current generator connects operator-MCP via the headerless
+// "claude_ai_0dai" OAuth /mcp entry; local stdio entries must point at an
+// existing helper script inside the project or at an absolute helper path.
 function _detectStaleMcpServers(mcpServers) {
   const stale = [];
   for (const [name, cfg] of Object.entries(mcpServers || {})) {
@@ -224,10 +234,45 @@ function _detectStaleMcpServers(mcpServers) {
   return stale;
 }
 
+function _mcpServerScriptArg(cfg) {
+  const args = Array.isArray(cfg && cfg.args) ? cfg.args : [];
+  for (const arg of args) {
+    const value = String(arg || "");
+    if (/(^|[/\\])mcp_server\.py$/.test(value)) return value;
+  }
+  const command = typeof (cfg && cfg.command) === "string" ? cfg.command : "";
+  return /(^|[/\\])mcp_server\.py$/.test(command) ? command : "";
+}
+
+function _resolveMcpConfigPath(rawPath, target) {
+  const value = String(rawPath || "").trim();
+  if (!value) return "";
+  return path.resolve(path.isAbsolute(value) ? value : path.join(target, value));
+}
+
+function _detectMissingMcpServerScripts(mcpServers, target) {
+  const stale = [];
+  for (const [name, cfg] of Object.entries(mcpServers || {})) {
+    if (!cfg || typeof cfg !== "object") continue;
+    const scriptArg = _mcpServerScriptArg(cfg);
+    if (!scriptArg) continue;
+    const resolved = _resolveMcpConfigPath(scriptArg, target);
+    if (!fs.existsSync(resolved)) {
+      stale.push({
+        name,
+        reason: `missing MCP server script referenced by config (${scriptArg})`,
+        path: resolved,
+      });
+    }
+  }
+  return stale;
+}
+
 function _cmdDoctor(target, args) {
   const wantJson = args.includes("--json");
   const report = {
     target,
+    local_server_bundled: false,
     server_script: { path: "", ok: false },
     mcp_config: { path: "", ok: false, servers: [], stale: [] },
     tier_manifest: { path: "", ok: false, free_count: 0, pro_count: 0 },
@@ -236,6 +281,7 @@ function _cmdDoctor(target, args) {
 
   const script = findRepoScript(target, "mcp_server.py");
   if (script) {
+    report.local_server_bundled = true;
     report.server_script.path = script;
     report.server_script.ok = fs.existsSync(script);
   }
@@ -247,13 +293,15 @@ function _cmdDoctor(target, args) {
     if (data && data.mcpServers && typeof data.mcpServers === "object") {
       report.mcp_config.ok = true;
       report.mcp_config.servers = Object.keys(data.mcpServers);
-      report.mcp_config.stale = _detectStaleMcpServers(data.mcpServers);
+      report.mcp_config.stale = [
+        ..._detectStaleMcpServers(data.mcpServers),
+        ..._detectMissingMcpServerScripts(data.mcpServers, target),
+      ];
     }
   }
 
   const tierCandidates = [
-    path.join(target, "ai", "meta", "manifest", "mcp-tool-tiers.json"),
-    path.join(target, "ai", "manifest", "mcp-tool-tiers.json"),
+    ..._tierManifestCandidates(target),
   ];
   for (const candidate of tierCandidates) {
     if (!fs.existsSync(candidate)) continue;
@@ -278,6 +326,18 @@ function _cmdDoctor(target, args) {
     }
   }
 
+  // The local stdio server script is a repo-checkout artifact that the
+  // published npm package intentionally does not bundle: npm users get live MCP
+  // calls over the OAuth "claude_ai_0dai" HTTP /mcp entry, not a local server.
+  // Read-only list/catalog metadata may be package-bundled, but only treat the
+  // server script absence as a failure when we ARE in a repo checkout.
+  const allOk = report.local_server_bundled
+    ? (report.server_script.ok && report.mcp_config.ok
+      && report.mcp_config.stale.length === 0
+      && (report.tier_manifest.ok || report.catalog.ok))
+    : report.mcp_config.stale.length === 0;
+  if (!allOk) process.exitCode = 1;
+
   if (wantJson) {
     console.log(JSON.stringify(report));
     return;
@@ -285,31 +345,47 @@ function _cmdDoctor(target, args) {
 
   const ok = (b) => (b ? G + "ok" + R : W + "missing" + R);
   console.log(`\n  ${T}0dai mcp doctor${R}  target=${target}\n`);
-  console.log(`  server script   ${ok(report.server_script.ok)}  ${D}${report.server_script.path || "(not found)"}${R}`);
+
+  // npm-installed package: the local stdio server is never shipped, so don't
+  // dead-end on a bare "missing" line. Explain WHY and point at the actual MCP
+  // path npm users have (the OAuth HTTP /mcp entry).
+  if (!report.local_server_bundled) {
+    console.log(`  local stdio MCP server   ${D}not bundled (npm install)${R}`);
+    console.log(`    ${D}The published 0dai package does not ship the local stdio MCP server${R}`);
+    console.log(`    ${D}(scripts/mcp_server.py). MCP tools are served over the OAuth${R}`);
+    console.log(`    ${D}"claude_ai_0dai" HTTP /mcp entry instead.${R}`);
+    console.log(`    ${D}Read-only list/catalog metadata is package-bundled when available.${R}`);
+    console.log(`    ${G}→${R} run ${T}/mcp${R} in Claude Code and Authenticate the ${T}claude_ai_0dai${R} server`);
+    console.log(`    ${G}→${R} if that entry is absent, run ${T}0dai sync --target ${target}${R} to write it`);
+    console.log("");
+  } else {
+    console.log(`  server script   ${ok(report.server_script.ok)}  ${D}${report.server_script.path || "(not found)"}${R}`);
+  }
+
   console.log(`  .mcp.json       ${ok(report.mcp_config.ok)}  ${D}${report.mcp_config.path || "(not found)"}${R}`);
   if (report.mcp_config.ok) {
     console.log(`    servers: ${report.mcp_config.servers.join(", ")}`);
   }
   if (report.mcp_config.stale.length) {
-    console.log(`    ${W}stale${R} (remove from .mcp.json — superseded by the "claude.ai 0dai" OAuth /mcp entry):`);
+    console.log(`    ${W}stale${R} (remove from .mcp.json — superseded by the "claude_ai_0dai" OAuth /mcp entry):`);
     for (const s of report.mcp_config.stale) {
-      console.log(`      ${W}!${R} ${s.name} ${D}— ${s.reason}${R}`);
+      const detail = s.path ? `${s.reason}: ${s.path}` : s.reason;
+      console.log(`      ${W}!${R} ${s.name} ${D}— ${detail}${R}`);
     }
   }
-  console.log(`  tier manifest   ${ok(report.tier_manifest.ok)}  ${D}${report.tier_manifest.path || "(not found)"}${R}`);
-  if (report.tier_manifest.ok) {
-    console.log(`    free=${report.tier_manifest.free_count} pro=${report.tier_manifest.pro_count}`);
-  }
-  console.log(`  catalog         ${ok(report.catalog.ok)}  ${D}${report.catalog.path || "(not found)"}${R}`);
-  if (report.catalog.ok) {
-    console.log(`    stacks: ${report.catalog.stacks}`);
+
+  if (report.local_server_bundled) {
+    console.log(`  tier manifest   ${ok(report.tier_manifest.ok)}  ${D}${report.tier_manifest.path || "(not found)"}${R}`);
+    if (report.tier_manifest.ok) {
+      console.log(`    free=${report.tier_manifest.free_count} pro=${report.tier_manifest.pro_count}`);
+    }
+    console.log(`  catalog         ${ok(report.catalog.ok)}  ${D}${report.catalog.path || "(not found)"}${R}`);
+    if (report.catalog.ok) {
+      console.log(`    stacks: ${report.catalog.stacks}`);
+    }
   }
   console.log("");
 
-  const allOk = report.server_script.ok && report.mcp_config.ok
-    && report.mcp_config.stale.length === 0
-    && (report.tier_manifest.ok || report.catalog.ok);
-  if (!allOk) process.exitCode = 1;
 }
 
 function _cmdCall(target, toolName, args) {
@@ -323,7 +399,9 @@ function _cmdCall(target, toolName, args) {
 
   const script = findRepoScript(target, "mcp_server.py");
   if (!script) {
-    log("scripts/mcp_server.py not found in this repo");
+    const message = "mcp call is a repo-checkout helper: scripts/mcp_server.py is not bundled in npm installs. Use the claude_ai_0dai OAuth HTTP /mcp entry for live MCP tool calls.";
+    if (wantJsonOut) console.log(JSON.stringify({ error: message, repo_checkout_required: true }));
+    else log(message);
     process.exitCode = 1;
     return;
   }

package/lib/commands/models.js

@@ -1,45 +1,114 @@
 "use strict";
 const shared = require("../shared");
-const { T, R, SUPPORTED_CLIS } = shared;
+const { log, T, R, D, SUPPORTED_CLIS, spawnSync } = shared;
 const {
   probeInstalledCliNames,
   summarizeModelAvailability,
   formatAvailableFooter,
 } = require("../utils/model_ratings");
 
+// Scores from benchmark_models.py (3-task: read/count/review) + field-tested ledger.
+// Catalog refreshed 2026-04-19; prior benchmark baseline 2026-04-06.
+// Since then: native claude `--model opus` alias routes to opus-4.7 1M-ctx (CC extended);
+//             gpt-5.5 promoted to primary in agent-matrix/model_registry;
+//             gpt-5.3-codex empirically verified — does heavy internal reasoning
+//             (66k tokens on trivial "hello" prompt), pick deliberately for architecture.
+// Billing: native claude/codex/gemini = subscription (marginal $0/call but tokens tracked
+//          for opportunity cost per operator 2026-04-19). RuAPI / opencode-go = pay-per-use.
+const MODELS = [
+  { name: "Claude Opus 4.7 (1M)", tier: "deep", score: 98, cli: "claude",   flag: "--model opus",              tested: true },
+  { name: "Claude Opus 4.7",   tier: "deep",     score: 97, cli: "opencode", flag: "-m RuAPI/claude-opus-4.7",      tested: true },
+  { name: "GPT-5.5",           tier: "deep",     score: 96, cli: "codex",    flag: "-m gpt-5.5",           tested: true },
+  { name: "Claude Opus 4.6",   tier: "deep",     score: 95, cli: "claude",   flag: "--model claude-opus-4-6" },
+  { name: "Opus 4.6 (RuAPI)",  tier: "deep",     score: 95, cli: "opencode", flag: "-m RuAPI/claude-opus-4.6",      tested: true },
+  { name: "GPT-5.4-mini",      tier: "fast",     score: 93, cli: "codex",    flag: "-m gpt-5.4-mini",      tested: true },
+  { name: "MiniMax M2.7",      tier: "balanced", score: 93, cli: "opencode", flag: "-m opencode-go/minimax-m2.7",   tested: true },
+  { name: "Claude Sonnet 4.6", tier: "balanced", score: 90, cli: "claude",   flag: "--model sonnet" },
+  { name: "Sonnet 4.6 (RuAPI)",tier: "balanced", score: 90, cli: "opencode", flag: "-m RuAPI/claude-sonnet-4.6",    tested: true },
+  { name: "GPT-5.4",           tier: "balanced", score: 90, cli: "codex",    flag: "-m gpt-5.4",           tested: true },
+  { name: "Gemini 3.1 Pro",    tier: "deep",     score: 89, cli: "opencode", flag: "-m RuAPI/gemini-3.1-pro-preview", tested: true },
+  { name: "Kimi K2.5",         tier: "balanced", score: 88, cli: "opencode", flag: "-m opencode-go/kimi-k2.5",      tested: true },
+  { name: "Qwen 3.6+ Free",    tier: "free",     score: 88, cli: "opencode", flag: "-m opencode/qwen3.6-plus-free", tested: true },
+  { name: "GPT-5.2",           tier: "balanced", score: 87, cli: "codex",    flag: "-m gpt-5.2",           tested: true },
+  { name: "Gemini 3.1 Pro",    tier: "balanced", score: 85, cli: "gemini",   flag: "-m gemini-3.1-pro" },
+  { name: "GPT-5.3 Codex",     tier: "deep",     score: 83, cli: "codex",    flag: "-m gpt-5.3-codex",      tested: true },
+  { name: "GPT-5.3 Spark",     tier: "fast",     score: 82, cli: "codex",    flag: "-m gpt-5.3-codex-spark" },
+  { name: "Claude Haiku 4.5",  tier: "fast",     score: 78, cli: "claude",   flag: "--model haiku" },
+  { name: "Gemini 3 Flash",    tier: "fast",     score: 77, cli: "gemini",   flag: "-m gemini-3-flash" },
+  { name: "Mimo v2 Pro",       tier: "fast",     score: 74, cli: "opencode", flag: "-m opencode-go/mimo-v2-pro",    tested: true },
+  { name: "GPT-5.4 (opencode)",tier: "fast",     score: 74, cli: "opencode", flag: "-m openai/gpt-5.4",            tested: true },
+  { name: "MiniMax M2.5",      tier: "slow",     score: 57, cli: "opencode", flag: "-m opencode-go/minimax-m2.5",   tested: true },
+];
+
+function fallbackTierForTask(taskType) {
+  const normalized = String(taskType || "").toLowerCase();
+  if (["docs", "doc", "test", "tests", "lint"].includes(normalized)) return "fast";
+  if (["planning", "plan", "architecture", "design", "review"].includes(normalized)) return "deep";
+  return "balanced";
+}
+
+function localRecommendation(taskType, options = {}) {
+  const minQuality = Number(options.minQuality || 0);
+  const installedCliNames = options.installedCliNames || probeInstalledCliNames(SUPPORTED_CLIS);
+  const preferredTier = fallbackTierForTask(taskType);
+  const sorted = [...MODELS]
+    .filter((model) => !minQuality || model.score >= minQuality)
+    .sort((a, b) => b.score - a.score);
+  const available = sorted.filter((model) => installedCliNames.has(model.cli));
+  const pool = available.length ? available : sorted;
+  const tierPool = pool.filter((model) => model.tier === preferredTier);
+  const recommendation = tierPool[0] || pool[0] || sorted[0] || null;
+  if (!recommendation) return null;
+  return {
+    ...recommendation,
+    command: `${recommendation.cli} ${recommendation.flag}`.trim(),
+    fallback_reason: available.length ? "local_available_ratings" : "local_static_ratings",
+    preferred_tier: preferredTier,
+  };
+}
+
+function printLocalRecommendation(rec, reason) {
+  console.log(`  ${T}${rec.name}${R} (${rec.tier}, score ${rec.score})`);
+  console.log(`  command: ${rec.command}`);
+  console.log(`  ${D}${reason}; fallback=${rec.fallback_reason}${R}`);
+}
+
+function firstOutputLine(result) {
+  if (!result) return "";
+  const text = `${result.stderr || ""}\n${result.stdout || ""}`.trim();
+  return text.split("\n").map((line) => line.trim()).find(Boolean) || "";
+}
+
+function emitLocalRecommendationFallback(taskType, goal, minQuality, asJson, reasonCode, message, routerError = "") {
+  const recommendation = localRecommendation(taskType, { minQuality });
+  if (asJson) {
+    console.log(JSON.stringify({
+      status: "fallback",
+      reason: reasonCode,
+      task: taskType,
+      goal,
+      ...(routerError ? { router_error: routerError } : {}),
+      recommendation,
+    }, null, 2));
+  } else {
+    log(message);
+    if (routerError) console.log(`  ${D}router: ${routerError}${R}`);
+    if (recommendation) printLocalRecommendation(recommendation, message);
+  }
+}
+
+function runModelRouter(args) {
+  const result = spawnSync("python3", args, { encoding: "utf8" });
+  if (result.error) return { ok: false, result: { stderr: result.error.message, stdout: "" } };
+  if (typeof result.status === "number" && result.status === 0) {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    return { ok: true, result };
+  }
+  return { ok: false, result };
+}
+
 function cmdModels(filter) {
-  // Scores from benchmark_models.py (3-task: read/count/review) + field-tested ledger.
-  // Catalog refreshed 2026-04-19; prior benchmark baseline 2026-04-06.
-  // Since then: native claude `--model opus` alias routes to opus-4.7 1M-ctx (CC extended);
-  //             gpt-5.5 promoted to primary in agent-matrix/model_registry;
-  //             gpt-5.3-codex empirically verified — does heavy internal reasoning
-  //             (66k tokens on trivial "hello" prompt), pick deliberately for architecture.
-  // Billing: native claude/codex/gemini = subscription (marginal $0/call but tokens tracked
-  //          for opportunity cost per operator 2026-04-19). RuAPI / opencode-go = pay-per-use.
-  const MODELS = [
-    { name: "Claude Opus 4.7 (1M)", tier: "deep", score: 98, cli: "claude",   flag: "--model opus",              tested: true },
-    { name: "Claude Opus 4.7",   tier: "deep",     score: 97, cli: "opencode", flag: "-m RuAPI/claude-opus-4.7",      tested: true },
-    { name: "GPT-5.5",           tier: "deep",     score: 96, cli: "codex",    flag: "-m gpt-5.5",           tested: true },
-    { name: "Claude Opus 4.6",   tier: "deep",     score: 95, cli: "claude",   flag: "--model claude-opus-4-6" },
-    { name: "Opus 4.6 (RuAPI)",  tier: "deep",     score: 95, cli: "opencode", flag: "-m RuAPI/claude-opus-4.6",      tested: true },
-    { name: "GPT-5.4-mini",      tier: "fast",     score: 93, cli: "codex",    flag: "-m gpt-5.4-mini",      tested: true },
-    { name: "MiniMax M2.7",      tier: "balanced", score: 93, cli: "opencode", flag: "-m opencode-go/minimax-m2.7",   tested: true },
-    { name: "Claude Sonnet 4.6", tier: "balanced", score: 90, cli: "claude",   flag: "--model sonnet" },
-    { name: "Sonnet 4.6 (RuAPI)",tier: "balanced", score: 90, cli: "opencode", flag: "-m RuAPI/claude-sonnet-4.6",    tested: true },
-    { name: "GPT-5.4",           tier: "balanced", score: 90, cli: "codex",    flag: "-m gpt-5.4",           tested: true },
-    { name: "Gemini 3.1 Pro",    tier: "deep",     score: 89, cli: "opencode", flag: "-m RuAPI/gemini-3.1-pro-preview", tested: true },
-    { name: "Kimi K2.5",         tier: "balanced", score: 88, cli: "opencode", flag: "-m opencode-go/kimi-k2.5",      tested: true },
-    { name: "Qwen 3.6+ Free",    tier: "free",     score: 88, cli: "opencode", flag: "-m opencode/qwen3.6-plus-free", tested: true },
-    { name: "GPT-5.2",           tier: "balanced", score: 87, cli: "codex",    flag: "-m gpt-5.2",           tested: true },
-    { name: "Gemini 3.1 Pro",    tier: "balanced", score: 85, cli: "gemini",   flag: "-m gemini-3.1-pro" },
-    { name: "GPT-5.3 Codex",     tier: "deep",     score: 83, cli: "codex",    flag: "-m gpt-5.3-codex",      tested: true },
-    { name: "GPT-5.3 Spark",     tier: "fast",     score: 82, cli: "codex",    flag: "-m gpt-5.3-codex-spark" },
-    { name: "Claude Haiku 4.5",  tier: "fast",     score: 78, cli: "claude",   flag: "--model haiku" },
-    { name: "Gemini 3 Flash",    tier: "fast",     score: 77, cli: "gemini",   flag: "-m gemini-3-flash" },
-    { name: "Mimo v2 Pro",       tier: "fast",     score: 74, cli: "opencode", flag: "-m opencode-go/mimo-v2-pro",    tested: true },
-    { name: "GPT-5.4 (opencode)",tier: "fast",     score: 74, cli: "opencode", flag: "-m openai/gpt-5.4",            tested: true },
-    { name: "MiniMax M2.5",      tier: "slow",     score: 57, cli: "opencode", flag: "-m opencode-go/minimax-m2.5",   tested: true },
-  ];
 
   const installedCliNames = probeInstalledCliNames(SUPPORTED_CLIS);
   const availability = summarizeModelAvailability(MODELS, SUPPORTED_CLIS, installedCliNames);
@@ -75,7 +144,7 @@ function cmdModels(filter) {
 
 async function cmdModelsRecommend(target, args) {
   const shared = require("../shared");
-  const { log, T, R, D, findRepoScript, spawnSync, requirePlan } = shared;
+  const { findRepoScript, requirePlan } = shared;
 
   const gate = requirePlan("pro", "Model Recommend", target);
   if (gate) { log(gate.error); log(gate.hint); return; }
@@ -92,8 +161,18 @@ async function cmdModelsRecommend(target, args) {
     return;
   }
 
-  const recScript = findRepoScript(target, "model_router.py");
-  if (!recScript) { log("model router unavailable"); return; }
+  const recScript = shared.resolvePythonScript(target, "model_router.py");
+  if (!recScript) {
+    emitLocalRecommendationFallback(
+      taskType,
+      goal,
+      minQuality,
+      asJson,
+      "model_router_unavailable",
+      "model router unavailable; using local ratings fallback",
+    );
+    return;
+  }
 
   // Ledger-recommend: pair per-repo outcome ledger (PR #509) with the static
   // experience-event ranking. Falls back to the legacy `recommend` subcommand
@@ -103,8 +182,8 @@ async function cmdModelsRecommend(target, args) {
   if (taskType) ledgerArgs.push("--task", taskType);
   if (asJson) ledgerArgs.push("--json");
 
-  const ledgerResult = spawnSync("python3", ledgerArgs, { stdio: "inherit" });
-  if (typeof ledgerResult.status === "number" && ledgerResult.status === 0) return;
+  const ledgerResult = runModelRouter(ledgerArgs);
+  if (ledgerResult.ok) return;
 
   const fwd = [recScript, "recommend", "--target", target];
   if (taskType) fwd.push("--task", taskType);
@@ -113,8 +192,26 @@ async function cmdModelsRecommend(target, args) {
   if (minQuality > 0) fwd.push("--min-quality", String(minQuality));
   if (asJson) fwd.push("--json");
 
-  const result = spawnSync("python3", fwd, { stdio: "inherit" });
-  if (typeof result.status === "number" && result.status !== 0) process.exit(result.status);
+  const result = runModelRouter(fwd);
+  if (result.ok) return;
+
+  const routerError = firstOutputLine(result.result) || firstOutputLine(ledgerResult.result);
+  emitLocalRecommendationFallback(
+    taskType,
+    goal,
+    minQuality,
+    asJson,
+    "model_router_failed",
+    "model router failed; using local ratings fallback",
+    routerError,
+  );
 }
 
-module.exports = { cmdModels, cmdModelsRecommend };
+module.exports = {
+  cmdModels,
+  cmdModelsRecommend,
+  localRecommendation,
+  fallbackTierForTask,
+  MODELS,
+  emitLocalRecommendationFallback,
+};

package/lib/commands/provider.js

@@ -1,84 +1,55 @@
 "use strict";
 
 const shared = require("../shared");
-const { log, spawnSync, findRepoScript } = shared;
+const { D, R, log, spawnSync, resolvePythonScript } = shared;
+
+function hasTargetArg(args) {
+  return args.some((arg, index) => arg === "--target" || arg.startsWith("--target=") || args[index - 1] === "--target");
+}
+
+function providerProfileArgs(target, args) {
+  const subcommand = args[0] || "";
+  const forwarded = [...args];
+  if (target && !hasTargetArg(forwarded) && ["bind", "bindings", "invoke", "status"].includes(subcommand)) {
+    forwarded.push("--target", target);
+  }
+  return forwarded;
+}
+
+function providerRegistryArgs(target, args) {
+  const forwarded = [...args];
+  if (target && !hasTargetArg(forwarded)) {
+    forwarded.push("--target", target);
+  }
+  return forwarded;
+}
 
 function cmdProvider(target, args) {
   // Check for per-repo provider commands first
   const subcommand = args[0] || "";
 
   if (subcommand === "list" || subcommand === "switch" || subcommand === "clear") {
-    // New per-repo provider profile commands — use provider_registry.py
-    const script = findRepoScript(target, "provider_registry_cli.py");
+    // Per-repo provider profile commands: repo-first, bundled fallback.
+    const script = resolvePythonScript(target, "provider_registry_cli.py");
     if (!script) {
-      // Fallback: inline Python call to provider_registry module
-      const pyCode = `
-import sys
-import json
-import pathlib
-sys.path.insert(0, '${target}/scripts')
-import provider_registry as pr
-
-target = pathlib.Path('${target}')
-args = ${JSON.stringify(args)}
-subcmd = args[0] if args else 'list'
-
-try:
-    if subcmd == 'list':
-        providers = pr.list_providers_for_repo(target)
-        print('Provider Status for', target.name)
-        print('=' * 60)
-        for p in providers:
-            active = '→' if p['active'] else ' '
-            source = f"[{p['source']}]" if p['source'] else ''
-            creds = '✓' if p['has_credentials'] else '✗'
-            print(f"  {active} {p['name']:<12} {creds} creds  {source:<10} {p['base_url']}")
-        print()
-        try:
-            resolved = pr.resolve_for_repo(target)
-            print(f"Active: {resolved['provider_name']} (source={resolved['source']})")
-        except pr.ProviderRegistryError as e:
-            print(f"No active provider: {e}")
-    elif subcmd == 'switch':
-        provider_name = ''
-        for i, a in enumerate(args):
-            if a == '--provider' and i + 1 < len(args):
-                provider_name = args[i + 1]
-        if not provider_name:
-            print('Usage: 0dai provider switch --target . --provider NAME')
-            sys.exit(1)
-        result = pr.switch_provider(target, provider_name)
-        print(f"Switched {target.name} to provider: {result['provider_name']}")
-        print(f"  base_url: {result['base_url']}")
-        print(f"  audit log: ~/.0dai/audit/provider-changes.jsonl")
-    elif subcmd == 'clear':
-        cleared = pr.clear_repo_profile(target)
-        if cleared:
-            print(f"Cleared per-repo profile for {target.name}")
-            print(f"Will fall back to global default or env vars")
-        else:
-            print(f"No per-repo profile to clear for {target.name}")
-except pr.ProviderRegistryError as e:
-    print(f"Error: {e}")
-    sys.exit(1)
-`;
-      const result = spawnSync("python3", ["-c", pyCode], { stdio: "inherit" });
-      if (typeof result.status === "number") process.exit(result.status);
+      log("provider registry unavailable in this environment");
+      console.log(`  ${D}Expected bundled lib/python/provider_registry_cli.py or scripts/provider_registry_cli.py in repo checkout${R}`);
       process.exit(1);
     }
-    const forwarded = [script, ...args];
+    const forwarded = [script, ...providerRegistryArgs(target, args)];
     const result = spawnSync("python3", forwarded, { stdio: "inherit" });
     if (typeof result.status === "number") process.exit(result.status);
     process.exit(1);
   }
 
   // Legacy provider_profiles.py commands
-  const script = findRepoScript(target, "provider_profiles.py");
+  const script = resolvePythonScript(target, "provider_profiles.py");
   if (!script) {
     log("provider profiles unavailable in this environment");
+    console.log(`  ${D}Expected bundled lib/python/provider_profiles.py or scripts/provider_profiles.py in repo checkout${R}`);
     process.exit(1);
   }
-  const forwarded = [script, ...args];
+  const forwarded = [script, ...providerProfileArgs(target, args)];
   const result = spawnSync("python3", forwarded, { stdio: "inherit" });
   if (typeof result.status === "number") process.exit(result.status);
   process.exit(1);

package/lib/commands/quota.js

@@ -22,7 +22,7 @@ function _pad(s, n) { s = String(s); return s + " ".repeat(Math.max(0, n - s.len
 function _loadEnvelope(target, opts = {}) {
   const cachePath = path.join(target, "ai", "manifest", "agent-quotas.json");
   const force = !!opts.refresh;
-  const script = findRepoScript(target, "agent_quotas.py");
+  const script = shared.resolvePythonScript(target, "agent_quotas.py");
   if (script) {
     const args = [script, "--target", target, "--json"];
     if (force) args.push("--refresh");

package/lib/commands/receipt.js

@@ -18,7 +18,7 @@ function _findArg(args, flag) {
 }
 
 function cmdReceipt(target, args) {
-  const script = findRepoScript(target, "receipt_png.py");
+  const script = shared.resolvePythonScript(target, "receipt_png.py");
   if (!script) {
     log("receipt generator unavailable — missing scripts/receipt_png.py");
     console.log(`  ${D}Run from a 0dai-initialized project root.${R}`);

package/lib/commands/run.js

@@ -9,12 +9,20 @@ const {
 } = require("../utils/run_cost");
 const { recordActivationFirstTask } = require("../utils/activation_telemetry");
 
+function printRunHelp() {
+  console.log(`Usage: 0dai run <goal> [--dry-run] [--dry-cost] [--max-cost N] [--agent claude|codex|gemini] [--provider deepseek|gemini-direct|codex|claude-opus]`);
+  console.log(`  Example: 0dai run "add dark mode to settings page"`);
+  console.log(`  Example: 0dai run "fix login bug" --dry-cost`);
+  console.log(`  Example: 0dai run "refactor auth" --max-cost 0.50`);
+}
+
+function isRunHelpRequest(goal, args = []) {
+  return goal === "--help" || goal === "-h" || args.includes("--help") || args.includes("-h");
+}
+
 async function cmdRun(goal, target, args = []) {
-  if (!goal) {
-    console.log(`Usage: 0dai run <goal> [--dry-run] [--dry-cost] [--max-cost N] [--agent claude|codex|gemini] [--provider deepseek|gemini-direct|codex|claude-opus]`);
-    console.log(`  Example: 0dai run "add dark mode to settings page"`);
-    console.log(`  Example: 0dai run "fix login bug" --dry-cost`);
-    console.log(`  Example: 0dai run "refactor auth" --max-cost 0.50`);
+  if (!goal || isRunHelpRequest(goal, args)) {
+    printRunHelp();
     return;
   }
 
@@ -174,4 +182,4 @@ function providerAgent(provider) {
   return null;
 }
 
-module.exports = { cmdRun, printCostPreview };
+module.exports = { cmdRun, printCostPreview, printRunHelp };