@0dai-dev/cli 4.3.6 → 4.3.8

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 };

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,133 @@ function loadJson(file) {
 }
 
 function loadProjectBinding(target) {
-  return loadJson(path.join(target, ".0dai", "project-binding.json"));
+  return shared.loadProjectBinding(target);
+}
+
+// Open sprint:current issues are the authoritative work queue (SPRINT.md
+// retired as SoT). Probe gh; degrade quietly when gh is absent or the token
+// is not authenticated — never throw out of status.
+function collectSprintPayload(target, options = {}) {
+  const out = { available: false, authenticated: false, issues: [], reason: "" };
+  try {
+    const r = spawnSync(
+      "gh",
+      [
+        "issue", "list",
+        "--label", "sprint:current",
+        "--state", "open",
+        "--json", "number,title",
+        "--limit", "20",
+      ],
+      {
+        cwd: target,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf8",
+        timeout: options.ghTimeout || 8000,
+      },
+    );
+    if (r.error && r.error.code === "ENOENT") {
+      out.reason = "gh CLI not installed";
+      return out;
+    }
+    out.available = true;
+    if (r.status !== 0) {
+      const err = String(r.stderr || "").trim();
+      out.reason = /auth|logged in|token/i.test(err)
+        ? "gh not authenticated — run: gh auth login"
+        : (err.split("\n").slice(-1)[0] || "gh issue list failed");
+      return out;
+    }
+    out.authenticated = true;
+    const parsed = JSON.parse(String(r.stdout || "[]").trim() || "[]");
+    out.issues = Array.isArray(parsed)
+      ? parsed.map((i) => ({ number: i.number, title: i.title || "" }))
+      : [];
+  } catch (e) {
+    out.reason = String((e && e.message) || e).split("\n").slice(-1)[0] || "sprint probe failed";
+  }
+  return out;
+}
+
+// Active flight = newest flight plan under ai/meta/reports/flight-F*.md, ranked
+// by flight number (F17 > F6) then by the trailing date in the filename.
+function findActiveFlight(target) {
+  const dir = path.join(target, "ai", "meta", "reports");
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((f) => /^flight-F\d+.*\.md$/.test(f));
+  } catch {
+    return null;
+  }
+  if (!names.length) return null;
+  const parse = (name) => {
+    const m = name.match(/^flight-F(\d+)/);
+    const dateM = name.match(/(\d{4}-\d{2}-\d{2})/);
+    return { name, num: m ? Number(m[1]) : -1, date: dateM ? dateM[1] : "" };
+  };
+  const newest = names
+    .map(parse)
+    .sort((a, b) => (b.num - a.num) || b.date.localeCompare(a.date))[0];
+  const file = path.join(dir, newest.name);
+  let id = `F${newest.num}`, title = "", flightStatus = "";
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    const fm = text.match(/^---\n([\s\S]*?)\n---/);
+    const block = fm ? fm[1] : text;
+    const idM = block.match(/^id:\s*(.+)$/m);
+    const titleM = block.match(/^title:\s*(.+)$/m);
+    const statusM = block.match(/^status:\s*(.+)$/m);
+    if (idM) id = idM[1].trim().replace(/^["']|["']$/g, "");
+    if (titleM) title = titleM[1].trim().replace(/^["']|["']$/g, "");
+    if (statusM) flightStatus = statusM[1].trim().replace(/^["']|["']$/g, "");
+  } catch {}
+  return { id, title, status: flightStatus, file: path.relative(target, file) };
 }
 
-function collectStatusPayload(target) {
+// Drift signal: roadmap.json is generated from ROADMAP.md. If the source is
+// newer than the generated artifact, the JSON is stale and should be regenerated.
+function collectRoadmapDrift(target) {
+  const out = { detected: false, reason: "" };
+  const jsonPath = path.join(target, "ai", "meta", "manifest", "roadmap.json");
+  const mdPath = path.join(target, "ROADMAP.md");
+  let jsonMtime, mdMtime;
+  try { jsonMtime = fs.statSync(jsonPath).mtimeMs; } catch { return out; }
+  try { mdMtime = fs.statSync(mdPath).mtimeMs; } catch { return out; }
+  // Prefer an explicit updated_at/generated_at in the JSON over file mtime when present.
+  const j = loadJson(jsonPath);
+  const stamp = j && (j.updated_at || j.generated_at);
+  const jsonTime = stamp ? Date.parse(stamp) : NaN;
+  const jsonEffective = Number.isFinite(jsonTime) ? jsonTime : jsonMtime;
+  if (mdMtime > jsonEffective) {
+    out.detected = true;
+    out.reason = "ROADMAP.md is newer than roadmap.json — run: python3 scripts/roadmap_to_json.py";
+  }
+  return out;
+}
+
+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 +184,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 +213,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 +240,10 @@ function collectStatusPayload(target) {
     drift: {
       detected: driftDetected,
     },
+    sprint: collectSprintPayload(target, options),
+    flight: findActiveFlight(target),
+    roadmap_drift: collectRoadmapDrift(target),
+    mcp_exposure: collectMcpExposurePayload(target, options.mcpExposureOptions || {}),
     warnings: warningCount,
     activation_ttfv: getActivationDurationStats(target),
     activation_first_merged_pr: getActivationMergedPrStats(target),
@@ -127,7 +251,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;
@@ -139,6 +263,33 @@ function cmdStatus(target, options = {}) {
     console.log(`  swarm: ${payload.swarm.queued} queued, ${payload.swarm.active} active, ${payload.swarm.done} done`);
   }
 
+  const sprint = payload.sprint || {};
+  if (sprint.authenticated) {
+    if (sprint.issues.length) {
+      console.log(`  sprint:current — ${sprint.issues.length} open:`);
+      for (const i of sprint.issues.slice(0, 8)) {
+        console.log(`    #${i.number} ${i.title}`);
+      }
+      if (sprint.issues.length > 8) {
+        console.log(`    …and ${sprint.issues.length - 8} more`);
+      }
+    } else {
+      console.log(`  sprint:current — none open`);
+    }
+  } else if (sprint.reason) {
+    console.log(`  sprint:current — ${D}unavailable (${sprint.reason})${R}`);
+  }
+
+  if (payload.flight) {
+    const ftitle = payload.flight.title ? ` ${payload.flight.title}` : "";
+    const fstatus = payload.flight.status ? ` [${payload.flight.status}]` : "";
+    console.log(`  flight: ${payload.flight.id}${ftitle}${fstatus}`);
+  }
+
+  if (payload.roadmap_drift && payload.roadmap_drift.detected) {
+    console.log(`  roadmap: ${D}${payload.roadmap_drift.reason}${R}`);
+  }
+
   if (payload.swarm.quota_state === "locked") {
     console.log(`  swarm quota: ${D}locked (Free) — upgrade for ${payload.swarm.daily_limit} tasks/day${R}`);
   } else {
@@ -151,6 +302,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 || "?"})`);
   }
@@ -170,4 +329,10 @@ function cmdStatus(target, options = {}) {
   return payload;
 }
 
-module.exports = { cmdStatus, collectStatusPayload };
+module.exports = {
+  cmdStatus,
+  collectStatusPayload,
+  collectSprintPayload,
+  findActiveFlight,
+  collectRoadmapDrift,
+};

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/trust.js

@@ -283,4 +283,4 @@ function cmdTrust(target, args) {
   process.exit(1);
 }
 
-module.exports = { cmdTrust, renderColdScope };
+module.exports = { cmdTrust, renderColdScope, _buildColdPayload };