@0dai-dev/cli 4.3.6 → 4.3.7

package/lib/commands/runner.js

@@ -376,6 +376,31 @@ function runRouteDryRunController(target, configPath, forwarded) {
   }
 }
 
+function runHostPoolPlanController(target, forwarded) {
+  const script = findRepoScript(target, "runner_host_pool_autosize.py");
+  if (!script) {
+    log("runner host-pool plan controller not found");
+    console.log(`  ${D}expected: scripts/runner_host_pool_autosize.py${R}`);
+    process.exitCode = 1;
+    return;
+  }
+  const result = spawnSync("python3", [script, "host-pool-plan", ...forwarded], {
+    encoding: "utf8",
+    timeout: 30000,
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  if (result.error) {
+    log(`runner host-pool plan controller failed: ${result.error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (typeof result.status === "number" && result.status !== 0) {
+    process.exitCode = result.status;
+  }
+}
+
 function runLabelAuditController(target, configPath, forwarded) {
   const script = findRepoScript(target, "runner_label_audit.py");
   if (!script) {
@@ -468,6 +493,11 @@ function cmdRunner(target, sub, args) {
     return;
   }
 
+  if (command === "host-pool-plan" || command === "host-pool-autosize") {
+    runHostPoolPlanController(target, forwarded);
+    return;
+  }
+
   if (command === "label-audit") {
     runLabelAuditController(target, configPath, forwarded);
     return;
@@ -485,7 +515,7 @@ function cmdRunner(target, sub, args) {
   }
 
   if (command !== "status" && command !== "plan") {
-    console.log("Usage: 0dai runner [status|plan|queue-status|label-audit|burst-plan|route-dry-run|burst-apply|burst-preflight|burst-reap|burst-reap-plan] [--json] [--offline]");
+    console.log("Usage: 0dai runner [status|plan|queue-status|label-audit|burst-plan|route-dry-run|host-pool-plan|burst-apply|burst-preflight|burst-reap|burst-reap-plan] [--json] [--offline]");
     process.exitCode = 1;
     return;
   }

package/lib/commands/status.js

@@ -9,6 +9,10 @@ const {
   getActivationMergedPrStats,
   printActivationStats,
 } = require("../utils/activation_telemetry");
+const {
+  collectMcpExposurePayload,
+  formatMcpExposureLine,
+} = require("./doctor");
 
 function countJson(dir) {
   try { return fs.readdirSync(dir).filter(f => f.endsWith(".json")).length; } catch { return 0; }
@@ -19,17 +23,32 @@ function loadJson(file) {
 }
 
 function loadProjectBinding(target) {
-  return loadJson(path.join(target, ".0dai", "project-binding.json"));
+  return shared.loadProjectBinding(target);
 }
 
-function collectStatusPayload(target) {
+function collectStatusPayload(target, options = {}) {
   const ai = path.join(target, "ai");
-  const identity = shared.buildProjectIdentity(target, shared.collectMetadata(target));
+  const baseIdentity = shared.buildProjectIdentity(target, shared.collectMetadata(target));
   const binding = loadProjectBinding(target);
-  const bindingStatus = (binding && binding.binding_status) || "local-only";
-  const bindingReason = binding
-    ? (binding.binding_status ? "" : "project-binding.json has no binding_status")
-    : "no .0dai/project-binding.json";
+  const identity = shared.applyBoundProjectIdentity(target, baseIdentity, binding);
+  // A binding whose stored target no longer matches this path (the project was
+  // moved/copied) must not report "bound" — the identity already falls back to
+  // the path-derived one, so the status must say "moved" and prompt a re-bind,
+  // not silently claim a stale project_id/name (#4363).
+  const bindingHasTarget =
+    !!binding &&
+    !!(binding.target || binding.current_target || (Array.isArray(binding.target_aliases) && binding.target_aliases.length));
+  const boundButMoved =
+    !!binding &&
+    binding.binding_status === "bound" &&
+    bindingHasTarget &&
+    !shared.bindingTargetMatches(target, binding);
+  const bindingStatus = boundButMoved ? "moved" : ((binding && binding.binding_status) || "local-only");
+  const bindingReason = boundButMoved
+    ? "binding target does not match this path — project moved or copied; re-bind to refresh identity"
+    : binding
+      ? (binding.binding_status ? "" : "project-binding.json has no binding_status")
+      : "no .0dai/project-binding.json";
   const bindingNextAction = bindingStatus === "bound" ? "" : "run 0dai project bind";
   let v = "?", stack = "?";
   try { v = fs.readFileSync(path.join(ai, "VERSION"), "utf8").trim(); } catch {}
@@ -64,7 +83,7 @@ function collectStatusPayload(target) {
   } catch {}
 
   try {
-    const ds = findRepoScript(target, "drift_detector.py");
+    const ds = shared.resolvePythonScript(target, "drift_detector.py");
     if (ds) {
       const dr = spawnSync("python3", [ds, "report", "--target", target],
                            { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8", timeout: 5000 });
@@ -93,7 +112,7 @@ function collectStatusPayload(target) {
       queued: q,
       active: a,
       done: d,
-      quota_state: quota.plan === "free" ? "locked" : "available",
+      quota_state: Number(quota.daily_limit || 0) === 0 ? "locked" : "available",
       quota_plan: quota.plan,
       used_today: Number(quota.used_today || 0),
       daily_limit: Number(quota.daily_limit || 0),
@@ -120,6 +139,7 @@ function collectStatusPayload(target) {
     drift: {
       detected: driftDetected,
     },
+    mcp_exposure: collectMcpExposurePayload(target, options.mcpExposureOptions || {}),
     warnings: warningCount,
     activation_ttfv: getActivationDurationStats(target),
     activation_first_merged_pr: getActivationMergedPrStats(target),
@@ -127,7 +147,7 @@ function collectStatusPayload(target) {
 }
 
 function cmdStatus(target, options = {}) {
-  const payload = collectStatusPayload(target);
+  const payload = collectStatusPayload(target, options);
   if (options.json) {
     console.log(JSON.stringify(payload, null, 2));
     return payload;
@@ -151,6 +171,14 @@ function cmdStatus(target, options = {}) {
     console.log(`  session roaming: ${T}available (${payload.session.roaming_plan})${R}`);
   }
 
+  const mcpExposure = payload.mcp_exposure || {};
+  if (mcpExposure.status && mcpExposure.status !== "green") {
+    console.log(`  mcp exposure: ${formatMcpExposureLine(mcpExposure)}`);
+    if (mcpExposure.next_step) console.log(`    → ${mcpExposure.next_step}`);
+  } else if (mcpExposure.status === "green") {
+    console.log(`  mcp exposure: ${formatMcpExposureLine(mcpExposure)}`);
+  }
+
   if (payload.session.name) {
     console.log(`  session: ${payload.session.name} (agent: ${payload.session.agent || "?"})`);
   }

package/lib/commands/swarm.js

@@ -2,32 +2,121 @@
 const shared = require("../shared");
 const { log, T, R, D, fs, path, https, requirePlan, spawnSync, findRepoScript } = shared;
 
+// The npm package ships the lightweight swarm client; the Python orchestration
+// behind pick/run/quality/sessions runs from a 0dai repo checkout or dev install
+// (it needs the full toolchain + heavier deps). Emit an honest, actionable line
+// instead of dev-internal "probed: <path>" noise that npm users can't act on.
+function logSwarmOrchestrationUnavailable(capability, envVar) {
+  log(`${capability} is not available in the npm package`);
+  console.log(`  ${D}It runs from a 0dai repo checkout with the full Python toolchain.${R}`);
+  console.log(`  ${D}You need: the repo checkout + python3 + an installed agent CLI (claude/codex/...) + the gh CLI.${R}`);
+  console.log(`  ${D}Run 0dai doctor to see which prerequisites are missing.${R}`);
+  const power = envVar ? `  ·  power users: point ${envVar} at a local helper` : "";
+  console.log(`  ${D}Docs: https://0dai.dev/docs${power}${R}`);
+}
+
+function printSwarmHelp() {
+  console.log("Usage: 0dai swarm [status|pick|run|budget|estimate|quality|sessions|swarm-run]");
+  console.log("       0dai swarm add --task '...' [--for agent]");
+  console.log("       0dai swarm delegate --task '...' [--to agent]");
+  console.log("  pick      Pick one queued task for this agent: 0dai swarm pick --agent codex");
+  console.log("  run       One-shot: 0dai swarm run \"<goal>\" creates a task and dispatches it (queue-drains if no goal)");
+  console.log("  sessions  Show live session registry table (idle/busy/stale per session) [--json]");
+  console.log("  swarm-run Repo-checkout helper: add, dispatch, and wait for one swarm task as JSON");
+}
+
+function printSwarmRunHelp() {
+  console.log("Usage: 0dai swarm swarm-run --task '...' [--agent codex] [--files path ...] [--json]");
+  console.log("");
+  console.log("Adds, dispatches, and waits for one swarm task through scripts/swarm_run.py.");
+  console.log("Requires a full repo checkout helper or ODAI_SWARM_RUN_SCRIPT; otherwise use queue-only swarm commands.");
+}
+
+function swarmRunAvailability(target) {
+  const override = process.env.ODAI_SWARM_RUN_SCRIPT || "";
+  if (override) {
+    if (fs.existsSync(override)) return { available: true, source: "ODAI_SWARM_RUN_SCRIPT", path: override };
+    return {
+      available: false,
+      source: "ODAI_SWARM_RUN_SCRIPT",
+      path: override,
+      reason: "override path does not exist",
+    };
+  }
+  const script = findRepoScript(target, "swarm_run.py");
+  if (script) return { available: true, source: "auto", path: script };
+  return {
+    available: false,
+    source: "auto",
+    reason: "swarm_run.py not found",
+    probed: [
+      path.join(target, "scripts", "swarm_run.py"),
+      path.join(process.cwd(), "scripts", "swarm_run.py"),
+    ],
+  };
+}
+
+function printSwarmRunnerHint(target) {
+  const runner = swarmRunAvailability(target);
+  if (runner.available) {
+    console.log(`  ${D}runner: available (${runner.path})${R}`);
+    return runner;
+  }
+  console.log(`  ${D}runner: queue-only (${runner.reason}; set ODAI_SWARM_RUN_SCRIPT or sync scripts/swarm_run.py)${R}`);
+  return runner;
+}
+
 function cmdSwarm(target, sub, args) {
   const swarmDir = path.join(target, "ai", "swarm");
   const queueDir = path.join(swarmDir, "queue");
 
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+    printSwarmHelp();
+    return;
+  }
+
+  if (sub === "pick") {
+    cmdPythonSwarm(target, "pick", args.slice(2));
+    return;
+  }
   if (sub === "swarm-run") {
     cmdSwarmRun(target, args.slice(2));
     return;
   }
+  if (sub === "run") {
+    cmdRun(target, args.slice(2));
+    return;
+  }
   if (sub === "status") {
     const count = (d) => { try { return fs.readdirSync(d).filter(f => f.endsWith(".json")).length; } catch { return 0; } };
     const q = count(path.join(swarmDir, "queue"));
     const a = count(path.join(swarmDir, "active"));
     const d = count(path.join(swarmDir, "done"));
     log(`swarm: ${q} queued, ${a} active, ${d} done`);
+    printSwarmRunnerHint(target);
     return;
   }
   if (sub === "add" || sub === "delegate") {
+    if (args.includes("--help") || args.includes("-h")) {
+      printSwarmHelp();
+      return;
+    }
+    const taskIndex = args.indexOf("--task");
+    const task = taskIndex >= 0 ? args[taskIndex + 1] : "";
+    if (!task || task.startsWith("--")) {
+      log(`Usage: 0dai swarm ${sub} --task '...' [--for agent]`);
+      process.exitCode = 1;
+      return;
+    }
     const gate = requirePlan("pro", "Swarm", target);
     if (gate) { log(gate.error); log(gate.hint); return; }
     fs.mkdirSync(queueDir, { recursive: true });
-    const task = args.find((_, i) => args[i - 1] === "--task") || "untitled";
     const forAgent = args.find((_, i) => ["--for", "--to"].includes(args[i - 1])) || "any";
     const id = `swarm-${Date.now()}`;
     const t = { id, title: task, assigned_to: forAgent, status: "pending", created_at: new Date().toISOString(), created_by: "cli" };
     fs.writeFileSync(path.join(queueDir, `${id}.json`), JSON.stringify(t, null, 2));
     log(`task created: ${id} → ${forAgent}`);
+    printSwarmRunnerHint(target);
     return;
   }
   if (sub === "webhook") {
@@ -185,7 +274,7 @@ function cmdSwarm(target, sub, args) {
   }
   if (sub === "quality") {
     const scorerScript = findRepoScript(target, "quality_scorer.py");
-    if (!scorerScript) { log("quality scorer unavailable"); return; }
+    if (!scorerScript) { logSwarmOrchestrationUnavailable("swarm quality scoring"); return; }
     const fwd = [scorerScript, "--target", target];
     if (args.includes("--json")) fwd.push("--json");
     for (let i = 2; i < args.length; i++) {
@@ -198,7 +287,7 @@ function cmdSwarm(target, sub, args) {
   }
   if (sub === "sessions") {
     const script = findRepoScript(target, "swarm_session_registry.py");
-    if (!script) { log("swarm session registry unavailable"); return; }
+    if (!script) { logSwarmOrchestrationUnavailable("the swarm session registry"); return; }
     const fwd = [script, "rebuild", "--stale-after", "600"];
     const asJson = args.includes("--json");
     if (!asJson) fwd.push("--write", path.join(swarmDir, "session_registry.json"));
@@ -250,12 +339,44 @@ function cmdSwarm(target, sub, args) {
     console.log(`  ${G2}idle${reset}: ${idle}  ${W2}busy${reset}: ${busy}  ${M2}stale${reset}: ${stale}  total: ${rows.length}\n`);
     return;
   }
-  console.log("Usage: 0dai swarm [status|add|delegate|budget|estimate|quality|sessions|swarm-run] [--task '...'] [--to agent]");
-  console.log("  sessions  Show live session registry table (idle/busy/stale per session) [--json]");
-  console.log("  swarm-run Add, dispatch, and wait for one swarm task as JSON");
+  printSwarmHelp();
+}
+
+function cmdPythonSwarm(target, subcommand, args) {
+  // Forward Python-backed swarm operations through scripts/swarm.py so quota,
+  // dispatch gates, pick semantics, and preflight messaging have one source of
+  // truth. `swarm-run` (hyphenated add+wait helper) stays on swarm_run.py.
+  let script = process.env.ODAI_SWARM_SCRIPT || "";
+  if (script && !fs.existsSync(script)) {
+    log(`swarm helper unavailable: ODAI_SWARM_SCRIPT=${script} does not exist`);
+    process.exit(1);
+  }
+  if (!script) script = findRepoScript(target, "swarm.py");
+  if (!script) {
+    logSwarmOrchestrationUnavailable("swarm orchestration", "ODAI_SWARM_SCRIPT");
+    process.exit(1);
+  }
+  const python = process.env.ODAI_SWARM_RUN_PYTHON || "python3";
+  const result = spawnSync(python, [script, "--target", target, subcommand, ...args], { stdio: "inherit" });
+  if (result.error) {
+    log(`swarm ${subcommand} failed: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (typeof result.status === "number" && result.status !== 0) process.exit(result.status);
+}
+
+function cmdRun(target, args) {
+  // `0dai swarm run "<goal>"` — one-shot: forward to the python swarm.py `run`
+  // subcommand so the per-tier daily quota (check_swarm_quota / record_swarm_task)
+  // governs identically for the goal path and the queue-drain.
+  cmdPythonSwarm(target, "run", args);
 }
 
 function cmdSwarmRun(target, args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    printSwarmRunHelp();
+    return;
+  }
   // #2143 hardening:
   // 1. `ODAI_SWARM_RUN_SCRIPT` env override lets tests inject a deterministic
   //    script path, bypassing the `findRepoScript` heuristic that walks up
@@ -269,15 +390,12 @@ function cmdSwarmRun(target, args) {
   let script = process.env.ODAI_SWARM_RUN_SCRIPT || "";
   if (script && !fs.existsSync(script)) {
     log(`swarm-run helper unavailable: ODAI_SWARM_RUN_SCRIPT=${script} does not exist`);
+    log(`  hint: set ODAI_SWARM_RUN_SCRIPT to a valid helper, unset it, or create the helper at that exact path`);
     process.exit(1);
   }
   if (!script) script = findRepoScript(target, "swarm_run.py");
   if (!script) {
-    const cwd = process.cwd();
-    log("swarm-run helper unavailable");
-    log(`  probed: ${path.join(target, "scripts", "swarm_run.py")}`);
-    log(`  probed: ${path.join(cwd, "scripts", "swarm_run.py")}`);
-    log(`  hint: set ODAI_SWARM_RUN_SCRIPT to override the lookup`);
+    logSwarmOrchestrationUnavailable("the swarm-run helper", "ODAI_SWARM_RUN_SCRIPT");
     process.exit(1);
   }
   const python = process.env.ODAI_SWARM_RUN_PYTHON || "python3";
@@ -289,4 +407,4 @@ function cmdSwarmRun(target, args) {
   if (typeof result.status === "number" && result.status !== 0) process.exit(result.status);
 }
 
-module.exports = { cmdSwarm, cmdSwarmRun };
+module.exports = { cmdSwarm, cmdSwarmRun, cmdRun, cmdPythonSwarm, swarmRunAvailability };

package/lib/commands/update.js

@@ -1,10 +1,123 @@
 "use strict";
 const shared = require("../shared");
-const { log, SUPPORTED_CLIS } = shared;
+const { log, SUPPORTED_CLIS, cliDisplayName } = shared;
+
+function installCommand(cli) {
+  if (cli.pkgType === "npm" && cli.pkg) return `npm install -g ${cli.pkg}@latest`;
+  if (cli.pkgType === "pip" && cli.pkg) return `pip install --upgrade ${cli.pkg}`;
+  return cli.install || "";
+}
+
+function latestCommand(cli) {
+  if (cli.pkgType === "npm" && cli.pkg) return `npm view ${cli.pkg} version`;
+  if (cli.pkgType === "pip" && cli.pkg) return `pip index versions ${cli.pkg}`;
+  return "";
+}
+
+function parseVersion(out) {
+  const m = String(out || "").match(/(\d+\.\d+\.\d+)/);
+  return m ? m[1] : null;
+}
+
+function readInstalledVersion(cli, execFileSync) {
+  try {
+    const out = execFileSync(cli.bin, ["--version"], { timeout: 8000 }).toString().trim();
+    return { installed: true, version: parseVersion(out), raw: out };
+  } catch {
+    return { installed: false, version: null, raw: "" };
+  }
+}
+
+function readLatestVersion(cli, execFileSync) {
+  if (cli.pkgType === "npm" && cli.pkg) {
+    try {
+      const latest = execFileSync("npm", ["view", cli.pkg, "version"], { timeout: 5000 })
+        .toString()
+        .trim();
+      return { latest, error: null };
+    } catch (error) {
+      return { latest: null, error };
+    }
+  }
+  if (cli.pkgType === "pip" && cli.pkg) {
+    try {
+      const out = execFileSync("pip", ["index", "versions", cli.pkg], { timeout: 8000, encoding: "utf8" });
+      const m = String(out).match(/LATEST:\s*(\d+\.\d+\.\d+)/i) || String(out).match(/(\d+\.\d+\.\d+)/);
+      return { latest: m ? m[1] : null, error: null };
+    } catch (error) {
+      return { latest: null, error };
+    }
+  }
+  return { latest: null, error: null };
+}
+
+function verifyUpdatedVersion(cli, expected, execFileSync) {
+  const after = readInstalledVersion(cli, execFileSync);
+  if (!after.installed) {
+    return {
+      ok: false,
+      version: null,
+      error: `post-update verification failed: ${cli.bin} is not available after install`,
+    };
+  }
+  if (after.version === expected) {
+    return { ok: true, version: after.version, error: null };
+  }
+  const actual = after.version
+    ? after.version
+    : (after.raw ? `unparseable output ${JSON.stringify(after.raw)}` : "unknown");
+  return {
+    ok: false,
+    version: after.version,
+    error: `post-update verification failed: ${cli.name} is still ${actual} (expected ${expected})`,
+  };
+}
+
+function updateEntry(cli, current, latest, status, extra = {}) {
+  return {
+    name: cli.name,
+    bin: cli.bin,
+    current: current || "",
+    latest: latest || "",
+    status,
+    ...(extra.error ? { error: extra.error } : {}),
+    ...(extra.next ? { next: extra.next } : {}),
+  };
+}
+
+function formatEntry(entry) {
+  const current = entry.current ? String(entry.current) : "";
+  const latest = entry.latest ? String(entry.latest) : "";
+  const name = cliDisplayName(entry);
+  const version = latest && current && latest !== current
+    ? `${current} -> ${latest}`
+    : (current || latest || "unknown");
+  return `${name} ${version}`;
+}
+
+function printSummary(summary) {
+  log("update summary");
+  for (const key of ["updated", "would_update", "failed", "unchanged"]) {
+    const entries = summary[key] || [];
+    if (!entries.length) continue;
+    console.log(`  ${key.replace("_", " ")}: ${entries.map(formatEntry).join(", ")}`);
+    for (const entry of entries) {
+      const name = cliDisplayName(entry);
+      if (entry.next) console.log(`    next ${name}: ${entry.next}`);
+      if (entry.error) console.log(`    error ${name}: ${entry.error}`);
+    }
+  }
+  const nextEntries = ["would_update", "failed"]
+    .flatMap((key) => summary[key] || []);
+  if (nextEntries.some((entry) => entry.next && entry.next.startsWith("npm install "))) {
+    console.log("  note: global npm may need sudo/admin");
+  }
+}
 
 function cmdUpdate(args) {
   const { execFileSync: _ef3, execSync } = require("child_process");
   const dryRun = args.includes("--dry-run");
+  const wantJson = args.includes("--json");
 
   // 0dai self-update entry, then all supported agent CLIs.
   const CLIS = [
@@ -12,58 +125,91 @@ function cmdUpdate(args) {
     ...SUPPORTED_CLIS,
   ];
 
-  let updated = 0;
+  const summary = {
+    dry_run: dryRun,
+    updated: [],
+    would_update: [],
+    failed: [],
+    unchanged: [],
+    skipped: [],
+  };
   for (const cli of CLIS) {
-    let installed = false, ver = null;
-    try {
-      const out = _ef3(cli.bin, ["--version"], { timeout: 8000 }).toString().trim();
-      installed = true;
-      const m = out.match(/(\d+\.\d+\.\d+)/);
-      if (m) ver = m[1];
-    } catch {}
-
-    if (!installed) continue;
-
-    let latest = null;
-    if (cli.pkgType === "npm" && cli.pkg) {
-      try { latest = _ef3("npm", ["view", cli.pkg, "version"], { timeout: 5000 }).toString().trim(); } catch {}
-    } else if (cli.pkgType === "pip" && cli.pkg) {
-      try {
-        const out = _ef3("pip", ["index", "versions", cli.pkg], { timeout: 8000, encoding: "utf8" });
-        const m = out.match(/LATEST:\s*(\d+\.\d+\.\d+)/i) || out.match(/(\d+\.\d+\.\d+)/);
-        if (m) latest = m[1];
-      } catch {}
+    const label = cliDisplayName(cli);
+    const installedInfo = readInstalledVersion(cli, _ef3);
+    const ver = installedInfo.version;
+
+    if (!installedInfo.installed) {
+      summary.skipped.push(updateEntry(cli, "", "", "not_installed"));
+      continue;
+    }
+
+    const latestInfo = readLatestVersion(cli, _ef3);
+    const latest = latestInfo.latest;
+    const latestError = latestInfo.error;
+
+    if (latestError) {
+      const error = `latest check failed: ${String(latestError && latestError.message ? latestError.message : latestError).split("\n")[0]}`;
+      summary.failed.push(updateEntry(cli, ver, latest, "latest_unknown", { error, next: latestCommand(cli) }));
+      if (!wantJson) log(`failed to check ${label}: ${error}`);
+      continue;
     }
 
     if (!latest || latest === ver) {
-      console.log(`  ${cli.name} ${ver || ""} — up to date`);
+      summary.unchanged.push(updateEntry(cli, ver, latest, "unchanged"));
+      if (!wantJson) console.log(`  ${label} ${ver || ""} — up to date`);
       continue;
     }
 
-    console.log(`  ${cli.name} ${ver} → ${latest}`);
-    if (dryRun) { updated++; continue; }
+    if (!wantJson) console.log(`  ${label} ${ver} → ${latest}`);
+    if (dryRun) {
+      summary.would_update.push(updateEntry(cli, ver, latest, "would_update", { next: installCommand(cli) }));
+      continue;
+    }
 
     try {
-      if (cli.pkgType === "npm") {
-        log(`updating ${cli.name}...`);
-        execSync(`npm install -g ${cli.pkg}@latest`, { timeout: 60000, stdio: "pipe" });
-        log(`${cli.name} updated to ${latest}`);
-        updated++;
-      } else if (cli.pkgType === "pip") {
-        log(`updating ${cli.name}...`);
-        execSync(`pip install --upgrade ${cli.pkg}`, { timeout: 60000, stdio: "pipe" });
-        log(`${cli.name} updated to ${latest}`);
-        updated++;
+      if (cli.pkgType === "npm" || cli.pkgType === "pip") {
+        const next = installCommand(cli);
+        if (!wantJson) log(`updating ${label}...`);
+        execSync(next, { timeout: 60000, stdio: "pipe" });
+        const verified = verifyUpdatedVersion(cli, latest, _ef3);
+        if (!verified.ok) {
+          summary.failed.push(updateEntry(cli, ver, latest, "verify_failed", { error: verified.error, next }));
+          if (!wantJson) log(`failed to verify ${label}: ${verified.error}`);
+          continue;
+        }
+        if (!wantJson) log(`${label} updated to ${latest}`);
+        summary.updated.push(updateEntry(cli, ver, latest, "updated"));
+      } else {
+        summary.skipped.push(updateEntry(cli, ver, latest, "unsupported"));
       }
     } catch (e) {
-      log(`failed to update ${cli.name}: ${e.message.split("\n")[0]}`);
+      const error = String(e && e.message ? e.message : e).split("\n")[0];
+      summary.failed.push(updateEntry(cli, ver, latest, "failed", { error, next: installCommand(cli) }));
+      if (!wantJson) log(`failed to update ${label}: ${error}`);
     }
   }
-  if (updated) {
-    log(`${dryRun ? "would update" : "updated"} ${updated} CLI(s)`);
+
+  summary.counts = {
+    updated: summary.updated.length,
+    would_update: summary.would_update.length,
+    failed: summary.failed.length,
+    unchanged: summary.unchanged.length,
+    skipped: summary.skipped.length,
+  };
+
+  if (wantJson) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else if (summary.updated.length || summary.would_update.length || summary.failed.length) {
+    printSummary(summary);
   } else {
     log("all CLIs are up to date");
   }
+  return summary;
 }
 
-module.exports = { cmdUpdate };
+module.exports = {
+  cmdUpdate,
+  installCommand,
+  latestCommand,
+  formatEntry,
+};

package/lib/commands/usage.js

@@ -67,7 +67,7 @@ function cmdUsage(target, rawArgs = []) {
     process.exit(1);
   }
 
-  const script = findRepoScript(target, "usage_ledger.py");
+  const script = shared.resolvePythonScript(target, "usage_ledger.py");
   if (!script) {
     log("usage ledger unavailable");
     console.log(`  ${D}Expected scripts/usage_ledger.py in this project${R}`);