nomarmy 0.1.0-alpha.2 → 0.1.0-alpha.21

package/bin/nomarmy.mjs

@@ -2,10 +2,10 @@
 // nomArmy CLI. Every command proposes before it writes anything -- init,
 // setup, model and update all show exactly what would change and write only
 // after explicit confirmation ([y/N]) or an explicit non-interactive flag
-// (--write, --json with the required choices given up front). Nothing here
-// provisions SYSTEM-level infrastructure on its own: install.sh (builds
-// llama.cpp, installs OpenClaw, configures the sandbox) stays a separate,
-// manual step in every case, printed but never run.
+// (--write, --json with the required choices given up front). System-level
+// setup (install.sh: OpenClaw, the sandbox, llama.cpp for a local model)
+// runs only when asked: `nomarmy install`, or `nomarmy setup` after it has
+// shown the exact command and the operator said yes.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -18,15 +18,48 @@ import { buildConfigProposal } from "../lib/propose.mjs";
 import { detectHardware } from "../lib/hardware.mjs";
 import { readGGUFMetadata, resolveModelPath, totalSplitBytes } from "../lib/gguf.mjs";
 import { recommend, customRecommendation, evaluateConfig, bytesPerKvElementForCacheTypes, MIN_CONTEXT_PER_NOM } from "../lib/sizing.mjs";
-import { connectClaude, connectCodex, connectCursor, cursorAlreadyConnected, deriveWorkerModelEnv } from "../lib/connect.mjs";
+import { windowsFrontEnd, dropWindowsPath, markWindowsCoordinator, pickDistro, resolveWslNomarmy, mcpBridgeLaunch, writeWindowsSettings } from "../lib/wsl.mjs";
+import { windowsPlan, windowsForward, windowsSetup, windowsDoctor } from "../lib/wsl-cli.mjs";
+import { connectViaWsl, connectClaude, connectCodex, connectCursor, cursorAlreadyConnected, deriveWorkerModelEnv, defaultInstallDir, installMcpCopy, SCOPES, claudeUserScoped, portableServerLaunch } from "../lib/connect.mjs";
+import { compareVersions, readPackageVersion, readInstallVersions, copyIsStale } from "../lib/install-freshness.mjs";
+import { loadJobRecords, computeStats, formatStats, formatStatsSummary, parseSince, resolveRepo, agentLookup } from "../lib/stats.mjs";
+import { requestJobStop } from "../lib/openclaw-run.mjs";
+import { loadValidators, saveJevKey, removeJev, jevSettings, askJev, validatorsPath, JEV_CHECKS, saveJudge, removeJudge, judgeSettings, judgeAgentChoices, chooseJudgeAgent, confirmJudgeHostTools } from "../lib/validators.mjs";
+import { probeModel } from "../lib/model-probe.mjs";
 import { ID_RE, AUTH_ENV_NAME_RE, OPENCLAW_PROVIDER_ID_RE, openclawProviderId, isNativeProviderType } from "../lib/dispatch-schema.mjs";
-import { loadAgents, readAgentsFile, writeAgentsFile, agentsConfigPath, apiAgentAsPoolEntry, describeAgent as describeAgentLabel, agentRunsToolsOnHost, AGENT_KINDS, API_PROVIDER_TYPES, RESERVED_AGENT_NAMES, BUILTIN_LOCAL_AGENT } from "../lib/agents.mjs";
-import { loadArmy, describeArmy, readArmyFile, updateArmyInFile, assignRoleInFile, parseTargetSpec, armyLayerPath, globalConfigDir, DEFAULT_ARMY, ARMY_PHASES, LOCAL_CONFIG_FILENAME } from "../lib/army.mjs";
+import { loadAgents, readAgentsFile, writeAgentsFile, agentsConfigPath, apiAgentAsPoolEntry, describeAgent as describeAgentLabel, agentRunsToolsOnHost, agentProviderId, AGENT_KINDS, API_PROVIDER_TYPES, RESERVED_AGENT_NAMES, BUILTIN_LOCAL_AGENT } from "../lib/agents.mjs";
+import { loadArmy, mergeArmy, describeArmy, readArmyFile, updateArmyInFile, assignRoleInFile, parseTargetSpec, armyLayerPath, globalConfigDir, DEFAULT_ARMY, ARMY_PHASES, LOCAL_CONFIG_FILENAME } from "../lib/army.mjs";
 import { parseLlamaUrl } from "../lib/execution.mjs";
+import { setupSteps, formatSetupSteps, runSetupPlaybook } from "../lib/setup-steps.mjs";
+import { readUsageSnapshots, refreshStaleOverLimitReadings } from "../lib/usage-limits.mjs";
+import { pickMachine, planResize } from "../lib/sandbox-vm.mjs";
+import { listProcesses, staleSessions, formatStaleSessions } from "../lib/stale-sessions.mjs";
+import { readSetting, writeSetting, writeEnvLine, userCommonPath, userProfilePath, profilePathFor, tildePath } from "../lib/user-config.mjs";
+import { MIN_PODMAN_VM_MB } from "../lib/doctor.mjs";
+import { liveLeases } from "../lib/slots.mjs";
 import { ensureProviderConfig } from "../lib/openclaw-config.mjs";
-import { recordProbeSuccess } from "../lib/health.mjs";
+import { linkCodex } from "../lib/codex-link.mjs";
+import { recordProbeSuccess, parseOpenclawAuthProfiles, codexImportRecovery } from "../lib/health.mjs";
 import { pruneJobRuntime } from "../lib/prune.mjs";
-import { SUBSCRIPTION_VENDORS, parseOpenclawVersion, versionAtLeast, parseCatalogModels, parseCliLoginStatus, probeOutcome, parseMuseAuthDescriptor, extractMintedKey } from "../lib/subscription-setup.mjs";
+import { SUBSCRIPTION_VENDORS, parseOpenclawVersion, versionAtLeast, parseCatalogModels, parseCliLoginStatus, probeOutcome, openclawSignInFailure, parseMuseAuthDescriptor, extractMintedKey } from "../lib/subscription-setup.mjs";
+import { PINNED_OPENCLAW_VERSION, repairOpenclaw, verifyOpenclaw, configuredSubscriptionVendors } from "../lib/openclaw-install.mjs";
+import { ensureOpenClawOnPath } from "../lib/openclaw-path.mjs";
+import { THINKING_LEVELS } from "../lib/thinking.mjs";
+import { fileURLToPath } from "node:url";
+// Inside WSL, only the distro's own tools (see lib/wsl.mjs).
+dropWindowsPath();
+// The Windows front end: whatever it forwards knows the coordinators are on Windows.
+if (windowsFrontEnd()) markWindowsCoordinator();
+// OpenClaw in ~/.npm-global/bin (no writable npm prefix) is found without the operator editing PATH.
+ensureOpenClawOnPath();
+// Windows starts the engine as `wsl.exe --exec <node> nomarmy.mjs`, with no
+// login shell, so an nvm Node's directory isn't on PATH. Children that need
+// `node` (install.sh, OpenClaw's `#!/usr/bin/env node`) get the one running.
+{
+  const nodeDir = path.dirname(process.execPath);
+  const entries = (process.env.PATH ?? "").split(path.delimiter);
+  if (!entries.includes(nodeDir)) process.env.PATH = [nodeDir, ...entries.filter(Boolean)].join(path.delimiter);
+}
 
 // Add a new coordinator: add its name here, teach commandExists/connectTarget
 // about it below (a JSON-file target like Cursor has no PATH binary to check
@@ -34,10 +67,10 @@ import { SUBSCRIPTION_VENDORS, parseOpenclawVersion, versionAtLeast, parseCatalo
 // "already connected, so resync" detection if it has no CLI to probe.
 const KNOWN_TARGETS = ["claude", "codex", "cursor"];
 
-function connectTarget(target, { nomarmyRoot, run }) {
-  if (target === "claude") return connectClaude({ nomarmyRoot, run });
-  if (target === "codex") return connectCodex({ nomarmyRoot, run });
-  if (target === "cursor") return connectCursor({ nomarmyRoot, run });
+function connectTarget(target, { nomarmyRoot, run, scope = "user", projectDir = null }) {
+  if (target === "claude") return connectClaude({ nomarmyRoot, run, scope, projectDir });
+  if (target === "codex") return connectCodex({ nomarmyRoot, run, scope });
+  if (target === "cursor") return connectCursor({ nomarmyRoot, run, scope, projectDir });
   throw new Error(`unknown connect target: ${target}`);
 }
 
@@ -56,7 +89,7 @@ const repoDir = path.resolve(value("repo", process.cwd()));
 // through the job's requested reasoning); `--no-thinking` is always false.
 // Returns undefined when none of these flags were passed at all, so the
 // caller can tell "not touched" apart from "explicitly set".
-const THINKING_LEVELS = ["low", "medium", "high"];
+// Every level OpenClaw accepts (lib/thinking.mjs).
 function resolveThinkingFlag() {
   const level = value("thinking");
   if (level && THINKING_LEVELS.includes(level)) return level;
@@ -89,13 +122,16 @@ Usage: nomarmy <command> [options]
                   and write it after confirmation.
                   --force   overwrite an existing .nomarmy.yml
                   --write   with --json, write without prompting (needs a valid proposal)
-  setup           Detect this machine, recommend a profile (offering "more
-                  noms" vs "nominal" when they differ), choose a model, and
-                  write config/profiles/<name>.env (+ config/common.env).
-                  Prints the install.sh command; never runs it.
-                  --tier <more|nominal>   with --json, skip the prompt
+  setup           Show setup progress and run the next unfinished step.
+                  --status [--json]      print the checklist only
+                  --choose               choose hosted/local/remote/Bedrock
                   --hosted               skip hardware/model questions
-                  --llama-url <url>       use a llama-server on another machine
+                  --llama-url <url>       use a shared llama-server
+                  --json --profile-name <name> [--model <model>] [--tier <more|nominal>]
+                                         write a profile non-interactively
+  install         Run the bundled installer for the chosen setup profile.
+                  --profile <name>       override NOMARMY_SETUP_PROFILE
+                  --no-claude            skip Claude Code registration
   model           Change the configured model later, without the rest of
                   setup's questions. Offers to also resync the MCP
                   registration's worker-routing env vars, and to restart
@@ -107,8 +143,9 @@ Usage: nomarmy <command> [options]
                                       registration (never done silently)
                   --restart-inference with --json, also stop/start local
                                       inference (never done silently)
-  update          Pull the latest nomArmy code and re-sync the installed
-                  MCP copy (fast-forward only; refuses on local changes).
+  update          Update nomArmy and reconnect your coordinators: installs
+                  npm's latest alpha, or for a git checkout pulls (fast-forward
+                  only; refuses on local changes). Then restart open sessions.
   agents <list|add|update|remove>
                   Every account a job can run on, in one list:
                   ~/.config/nomarmy/agents.yml (or NOMARMY_CONFIG_DIR).
@@ -138,9 +175,14 @@ Usage: nomarmy <command> [options]
                             --model --auth-env [--base-url]
                             [--openclaw-provider --plugin] [--register]
                             [--update-mcp] (api); --provider --model
-                            --owner (subscription); and optionally
+                            --owner (subscription). Codex JSON setup can
+                            --link-openclaw after CLI login; removing a
+                            capturing email profile non-interactively needs
+                            --remove-email-profiles. Interactive Codex setup
+                            offers removal (default yes), then imports the
+                            CLI login. For any kind, optionally
                             --max-concurrent --context-window
-                            --thinking [low|medium|high] --no-thinking
+                            --thinking [minimal|low|medium|high|xhigh|adaptive|max|ultra] --no-thinking
                   update <name>
                             change the model (picked from what OpenClaw
                             lists; a subscription gets a real test call),
@@ -150,7 +192,7 @@ Usage: nomarmy <command> [options]
                             --no-model clears the default model, so every
                             role or job names its own.
                             (--json with the matching flags; --probe to
-                            test-call a subscription's new model first)
+                            test-call the agent; without a name, all agents)
                   remove <name>
                             remove one agent
   army <show|init|assign|general>
@@ -185,15 +227,32 @@ Usage: nomarmy <command> [options]
                             which agent the General is, in --global
                             (default) or --local
   config paths    where agents.yml and the three army layers live
-  jobs [--watch|--events|--prune] [--interval N] [--older-than DAYS]
+  config max-jobs [n]
+                  how many api and subscription jobs run at once, across
+                  every session (default 4); with n, sets it in limits.yml.
+                  Warns when the Podman VM is too small for that many.
+  jobs [--watch|--events [--until-done] [--run <run-id>] [--repo <path>]|--prune|--wait <jobId> [<jobId> ...]|--stop <jobId> [--reason <text>]] [--interval N] [--older-than DAYS]
                   what's running across every session (agent, model, phase,
                   last tool call, files changed, heartbeat) and what just
                   finished; --watch redraws every N seconds (default 3);
                   --events prints one line per start, phase change and
-                  finish (for Claude Code's background monitor; --json for
-                  JSON lines); --prune removes the bulky runtime data
+                  finish (--json for JSON lines). It's a stream: read it
+                  with a monitor that wakes on each line. A background
+                  command is only reported when it exits, so there use
+                  --events --until-done --run <run-id> for a whole run,
+                  or --wait <id> <id> ... for specific jobs. Unscoped
+                  --until-done watches every job on this machine. The plain
+                  stream ends on its own after 30 minutes with nothing
+                  running (--idle-minutes N); --prune removes the bulky runtime data
                   from finished jobs older than DAYS (default 2), keeping
-                  their records, reports and any retained worktree
+                  their records, reports and any retained worktree;
+                  --wait <jobId> [<jobId> ...] [--timeout <seconds>]
+                  blocks until all finish; comma-separated ids also work
+                  (default timeout 1800; --json is supported);
+                  --events --repo <path> limits events to one repository;
+                  --stop <jobId> stops a running job's worker (no report
+                  recovery, no verification), keeping its worktree for
+                  continue_from
   health          check what's likely to break a run before it does:
                   expiring logins, an outdated OpenClaw or plugin, roles
                   that can't be dispatched, an unloadable agents.yml,
@@ -202,10 +261,42 @@ Usage: nomarmy <command> [options]
   statusline      the one-line summary Claude Code's status line shows
                   (installed by \`nomarmy connect claude\` when no status
                   line is set); reads the session JSON on stdin
-  connect [claude] [codex] [cursor]
+  connect [claude] [codex] [cursor] [--scope user|local|project]
                   (Re-)register the MCP server with one or more coordinators.
                   With no target and not --json, prompts an interactive
-                  multi-select instead.
+                  multi-select instead. --scope user (default) registers it
+                  for every project; local for this repository, only you;
+                  project for this repository, committed for the team
+                  (.mcp.json or .cursor/mcp.json, running \`nomarmy mcp\`).
+                  Codex has only the user scope.
+  stats [--since 7d|<date>] [--until <date>] [--role <role>] [--model <model>] [--run <id>] [--details] [--all-suggestions] [--share] [--badge [path]]
+        [--repo <path|name>] [--all-repos] [--json]
+                  What nomArmy's job records show for this repository (or
+                  all): volume by role and model, code committed, time,
+                  tokens and spend, how often a "done" report failed
+                  independent verification, what didn't finish, reviewers,
+                  and review flags. From verified records, never reports.
+  validators <list|add jev|test jev|remove jev|add judge|test judge|remove judge>
+                  Optional semantic checks from a model you configure with
+                  your own key. Jev checks focused claims with TypeSafe;
+                  Judge reviews diffs with one of your configured agents.
+                  Setup asks for any consent it needs. \`add jev\` asks for the
+                  key without echoing it (or reads --key-stdin), saves it
+                  where only you can read it, and makes one test call. Its
+                  answers only add review flags, and it sends excerpts of
+                  your code to TypeSafe. \`add judge --agent <name> --model
+                  <model>\` makes one of your agents a model judge: does the
+                  diff meet each acceptance criterion, match the report, keep
+                  its tests as strong? An agent whose tools run on this
+                  machine needs --host-tools.
+  mcp             Start nomArmy's MCP server on stdio with this machine's
+                  settings. What a --scope project registration runs.
+  sandbox         The Podman VM every sandbox shares (macOS, Windows): its
+                  memory, disk and images. --memory <GiB> resizes it (stops,
+                  sets, restarts; refused while jobs run); --prune removes
+                  images no container uses (nomArmy rebuilds its own on
+                  demand); --repair restores missing subordinate ID
+                  ranges (refused while jobs run); --yes skips confirming
   start <profile> Start local inference (wraps scripts/start-inference.sh).
   stop <profile>  Stop local inference (wraps scripts/stop-inference.sh).
   uninstall       Remove the MCP registration and install directory.
@@ -272,7 +363,7 @@ function cmdScan() {
   const notes = evidence.notes?.items ?? [];
   if (notes.length) {
     console.log("\nNotes:");
-    for (const n of notes) console.log(`  ${n.message ?? n}`);
+    for (const n of notes) console.log(`  ${typeof n === "string" ? n : n.message ?? JSON.stringify(n)}`);
   }
   console.log("\nThis is deterministic evidence only - nothing here was executed.");
   console.log("Describe the environment in .nomarmy.yml, then run 'nomarmy validate'.");
@@ -295,12 +386,12 @@ function scanCheck(evidence) {
     process.exit(1);
   }
   console.log(`Comparing ${path.basename(loaded.path)} against repository evidence\n`);
-  if (drift.summary) console.log(`${drift.summary}\n`);
+  if (drift.summary) console.log(`Drift: ${drift.summary.missingFromConfig} missing from config, ${drift.summary.missingFromRepo} missing from repo (${drift.summary.total} total)\n`);
   for (const section of ["services", "ports", "environment", "commandKinds"]) {
     const d = drift[section];
     if (!d) continue;
-    for (const m of d.missingFromConfig ?? []) console.log(`  repo has, config omits:  ${section}: ${m}`);
-    for (const m of d.missingFromRepo ?? []) console.log(`  config has, repo lacks:  ${section}: ${m}`);
+    for (const m of d.missingFromConfig ?? []) console.log(`  repo has, config omits:  ${section}: ${typeof m === "object" ? JSON.stringify(m) : m}`);
+    for (const m of d.missingFromRepo ?? []) console.log(`  config has, repo lacks:  ${section}: ${typeof m === "object" ? JSON.stringify(m) : m}`);
   }
   process.exit(drift.ok ? 0 : 1);
 }
@@ -400,7 +491,9 @@ async function cmdInit() {
 // This file's own location, not --repo (the target repo being scanned) --
 // setup/model need to find THIS package's config/ and scripts/ as siblings
 // of bin/, the same way select-model.mjs resolves its own root.
-const nomarmyRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+// fileURLToPath, not URL.pathname: on Windows that gave "/C:/Users/Jason%20Pugh/...",
+// a stray slash and an encoded space, and connect failed copying from C:\\C:\\...
+const nomarmyRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 /** Read one KEY=VALUE line's value, or null if the file or key doesn't exist. */
 function readEnvValue(filePath, key) {
@@ -409,15 +502,9 @@ function readEnvValue(filePath, key) {
   return m ? m[1].trim() : null;
 }
 
-/** Read-modify-write one KEY=VALUE line, replacing it if present, appending if not -- the exact pattern scripts/select-model.mjs already uses for config/common.env. */
-function writeEnvLine(filePath, key, value) {
-  const existingText = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
-  const line = `${key}=${value}`;
-  const updated = new RegExp(`^${key}=.*$`, "m").test(existingText)
-    ? existingText.replace(new RegExp(`^${key}=.*$`, "m"), line)
-    : `${existingText.trimEnd()}\n${line}\n`.replace(/^\n/, "");
-  fs.writeFileSync(filePath, updated);
-}
+// Your settings live in ~/.config/nomarmy/, over the package's config/
+// defaults, so an update can't reset them (lib/user-config.mjs).
+const setting = (key) => readSetting(key, { nomarmyRoot });
 
 // Each entry's repo/quant/alias is verified against this project's own real
 // usage (downloaded, loaded, dispatched against), not guessed from a model
@@ -436,6 +523,14 @@ function writeEnvLine(filePath, key, value) {
  * not left to fail only at the very end via schema validation with no
  * indication of which of several answers was the problem.
  */
+/** A numbered choice, asked again until it's one of 1..count (an empty or mistyped answer used to end the whole flow). */
+async function askChoice(rl, count) {
+  const answer = await askUntilValid(rl, "Choice: ", { pattern: new RegExp(`^([1-9]|[1-9][0-9])$`), invalidMessage: `Choose a number from 1 to ${count}.` });
+  if (Number(answer) >= 1 && Number(answer) <= count) return Number(answer) - 1;
+  console.log(c.red(`  ✗ Choose a number from 1 to ${count}.`));
+  return askChoice(rl, count);
+}
+
 async function askUntilValid(rl, prompt, { pattern, invalidMessage, allowEmpty = false, fallback = "" }) {
   for (;;) {
     const answer = (await rl.question(c.bold(prompt))).trim();
@@ -468,15 +563,15 @@ async function askSecret(rl, prompt) {
 
 const KNOWN_MODELS = {
   default: {
-    label: "Qwen3-Coder-Next (shipped default; no thinking mode -- 0 failures across every case tested tonight)",
+    label: "Qwen3-Coder-Next · 48 GB download · the most reliable in our tests (recommended)",
     repo: "Qwen/Qwen3-Coder-Next-GGUF", quant: "Q4_K_M", alias: "qwen3-coder-next", thinking: false, recommended: true,
   },
   "gpt-oss-20b": {
-    label: "gpt-oss-20b (thinking, use reasoning: medium -- fastest of every model tested on the hardest case: 62s/0 failures; reasoning: high on the SAME ticket was the worst result measured: 318s/4 failures)",
+    label: "gpt-oss-20b · 12 GB download · the fastest; keep reasoning at medium",
     repo: "ggml-org/gpt-oss-20b-GGUF", quant: "MXFP4", alias: "gpt-oss-20b", thinking: true,
   },
   "qwen3.6-27b": {
-    label: "Qwen3.6-27B (thinking, use reasoning: medium -- best measured reliability, noticeably slower per-token; reasoning: high caused a full timeout on an open-ended task)",
+    label: "Qwen3.6-27B · 17 GB download · very reliable, slower; keep reasoning at medium",
     repo: "unsloth/Qwen3.6-27B-GGUF", quant: "Q4_K_M", alias: "qwen3.6-27b", thinking: true,
   },
 };
@@ -509,35 +604,148 @@ async function chooseModel(rl) {
   return { kind: "search", thinking: thinkingAnswer === "y" || thinkingAnswer === "yes" };
 }
 
-/**
- * `nomarmy setup`: detect hardware, recommend a profile the same way
- * `nomarmy sizing` already does, let the user pick a model, then write the
- * result to config/profiles/<name>.env and (for the two curated model
- * choices) config/common.env. Stops there -- prints the exact `install.sh`
- * command rather than running it. install.sh builds llama.cpp, curl-pipes an
- * installer and touches sandbox/provider config; that is not a proportionate
- * thing for an opt-in flag on a CLI whose whole brand is "reports or
- * proposes" to cross, unlike the cheap, reversible, single-file writes this
- * command itself does.
- */
+function setupProjectDir() {
+  let project = process.cwd();
+  while (!fs.existsSync(path.join(project, ".git"))) {
+    const parent = path.dirname(project);
+    if (parent === project) { project = null; break; }
+    project = parent;
+  }
+  return project;
+}
+
+/** The profile install.sh picks when given none (scripts/lib.sh load_profile). */
+function defaultLocalProfile() {
+  if (process.platform === "darwin") return "macbook-pro";
+  return spawnSync("nvidia-smi", ["-L"], { stdio: "ignore", timeout: 5000 }).status === 0 ? "nvidia-linux" : "cpu-linux";
+}
+
+// Which profile this machine is set up for, the same way for `setup` and
+// `install`: the one setup recorded, else the install marker's, else the
+// execution mode's, else (a working local install) install.sh's default.
+function setupProfileState() {
+  const common = userCommonPath();
+  const chosen = setting("NOMARMY_SETUP_PROFILE");
+  const probeCommand = (binary, args) => {
+    const result = spawnSync(binary, args, { encoding: "utf8", timeout: 10000 });
+    return result.status === 0 ? result.stdout.trim() : "";
+  };
+  const profileFile = profilePathFor(chosen, { nomarmyRoot });
+  const root = (process.env.NOMARMY_INSTALL_ROOT || (profileFile && readEnvValue(profileFile, "NOMARMY_INSTALL_ROOT")) || setting("NOMARMY_INSTALL_ROOT") || "$HOME/.local/share/nomarmy-local-agents").replace(/\$HOME|\$\{HOME\}/g, os.homedir());
+  let marker = null;
+  try { marker = JSON.parse(fs.readFileSync(path.join(root, "install.json"), "utf8")); } catch (error) { if (error.code !== "ENOENT") marker = {}; }
+  const version = probeCommand("openclaw", ["--version"]);
+  // `mcp list` would connect to every server; `mcp get` only looks this one up.
+  const registered = !marker && Boolean(version) && ["claude", "codex"].some((name) => spawnSync(name, ["mcp", "get", "nomarmy-local-worker"], { stdio: "ignore", timeout: 10000 }).status === 0);
+  // An install from before setup recorded its profile: the marker's, else the
+  // execution mode's, else (a working local install) install.sh's default.
+  const execution = setting("NOMARMY_EXECUTION");
+  const profile = chosen ?? marker?.profile
+    ?? (["hosted", "remote", "bedrock"].includes(execution) ? execution : null)
+    ?? (registered ? defaultLocalProfile() : null);
+  return { common, profile, marker, version, registered };
+}
+
+function setupChecklist() {
+  const { common, profile, marker, version, registered } = setupProfileState();
+  const project = setupProjectDir();
+  return setupSteps({
+    mode: () => ({ profile, host: setting("NOMARMY_LLAMA_HOST"), port: setting("NOMARMY_LLAMA_PORT") }),
+    install: () => ({ marker, version, registered }),
+    agents: () => Object.keys(loadAgents(globalConfigDir()).agents),
+    army: () => {
+      const global = readArmyFile(armyLayerPath("global"), { armyOnly: true });
+      const local = project ? readArmyFile(armyLayerPath("project", { projectDir: project })) : null;
+      const merged = mergeArmy([{ layer: "global", army: global }, { layer: "project", army: local }]).army;
+      // Repair the layer that would otherwise keep overriding a global init.
+      const repairLayer = profile === "hosted" && Object.values(local?.roles ?? {}).some((role) => role.agent === "local") ? "project" : null;
+      return { ...merged, repairLayer };
+    },
+    repo: () => ({ inside: Boolean(project), configured: Boolean(project && fs.existsSync(path.join(project, ".nomarmy.yml"))) }),
+  });
+}
+
+function runSetupChild(args) {
+  // Work from the repository root even when setup was started in a subdirectory;
+  // the child's cwd remains unchanged, as it does for every other step.
+  const project = setupProjectDir();
+  if (project && ["init", "army"].includes(args[0])) args = [...args, "--repo", project];
+  const result = spawnSync(process.execPath, [path.join(nomarmyRoot, "bin", "nomarmy.mjs"), ...args], { stdio: "inherit", cwd: process.cwd() });
+  return result.status ?? 1;
+}
+
+function cmdInstall() {
+  const profile = value("profile", null) ?? setupProfileState().profile;
+  if (!profile) throw new Error("Choose a profile first: nomarmy setup --choose (or install --profile <name>).");
+  if (!value("profile", null)) console.log(`Installing for profile ${profile} (from nomarmy setup; pass --profile to choose another).`);
+  const result = spawnSync("bash", [path.join(nomarmyRoot, "install.sh"), "--profile", profile, ...(flag("no-claude") ? ["--no-claude"] : [])], { stdio: "inherit", cwd: nomarmyRoot });
+  process.exitCode = result.status ?? 1;
+}
+
 async function cmdSetup() {
+  if (windowsFrontEnd()) {
+    process.exitCode = await windowsSetup(argv, { ask: async (prompt) => {
+      const rl = createInterface({ input, output });
+      try { return await rl.question(prompt); } finally { rl.close(); }
+    } });
+    return;
+  }
+  if (flag("status") || (!flag("choose") && !flag("hosted") && !flag("llama-url") && !json)) {
+    if (flag("status") || !process.stdin.isTTY) {
+      const steps = setupChecklist();
+      return json ? out(steps) : console.log(formatSetupSteps(steps));
+    }
+    // What's ahead, before the first question: a practice run found setup
+    // felt heavy mostly because nothing said how much of it there was.
+    if (setupChecklist().find((step) => step.status === "todo")?.id === "mode") {
+      console.log(`${c.bold("🍪 nomArmy setup")}\n\nAbout 10 to 20 minutes, one step at a time; stop any time and ${c.cyan("nomarmy setup")} picks up where you left off.`);
+      console.log(c.dim("  1. Where models run: your API and subscription agents, or a model on this machine"));
+      console.log(c.dim("  2. Install: OpenClaw (runs the models) and Podman (the sandbox every job runs in; on macOS a small VM, about a 1 GB download)"));
+      console.log(c.dim("  3. Agents: log in to your subscription or add an API key"));
+      console.log(c.dim("  4. Roles, this repo's checks, and a final health check\n"));
+    }
+    process.exitCode = await runSetupPlaybook({
+      evaluate: setupChecklist, print: console.log, run: runSetupChild,
+      ask: async (prompt) => {
+        const rl = createInterface({ input, output });
+        try { return await rl.question(prompt); } finally { rl.close(); }
+      },
+    });
+    return;
+  }
+  if (flag("choose")) {
+    if (!process.stdin.isTTY) throw new Error("setup --choose needs an interactive terminal.");
+    const rl = createInterface({ input, output });
+    try {
+      console.log("1. hosted (API keys and subscriptions, most people)\n2. a local model on this machine\n3. a shared model server\n4. Bedrock");
+      const choice = await askUntilValid(rl, "Choice [1]: ", { pattern: /^[1-4]$/, invalidMessage: "Choose 1, 2, 3 or 4.", allowEmpty: true, fallback: "1" });
+      if (choice === "1") argv.push("--hosted");
+      if (choice === "3") argv.push("--llama-url", (await rl.question("Server URL: ")).trim());
+      if (choice === "4") {
+        writeSetting("NOMARMY_EXECUTION", "bedrock");
+        writeSetting("NOMARMY_SETUP_PROFILE", "bedrock");
+        console.log("Next: nomarmy install");
+        return;
+      }
+    } finally { rl.close(); }
+  }
   const hosted = flag("hosted");
   const hasLlamaUrl = flag("llama-url");
   if (hosted && hasLlamaUrl) throw new Error("--hosted and --llama-url cannot be used together.");
 
   if (hosted || hasLlamaUrl) {
-    const commonPath = path.join(nomarmyRoot, "config", "common.env");
+    const commonPath = userCommonPath();
 
     if (hosted) {
       const next = [
-        `${path.join(nomarmyRoot, "install.sh")} --profile hosted`,
+        "nomarmy install",
         "nomarmy agents add",
         "nomarmy army init --agent <name>",
       ];
-      fs.mkdirSync(path.dirname(commonPath), { recursive: true });
       writeEnvLine(commonPath, "NOMARMY_EXECUTION", "hosted");
+      writeEnvLine(commonPath, "NOMARMY_SETUP_PROFILE", "hosted");
       if (json) return out({ written: commonPath, execution: "hosted", next });
-      console.log(c.green(`✓ Wrote NOMARMY_EXECUTION=hosted to ${path.relative(nomarmyRoot, commonPath)}.`));
+      console.log(c.green(`✓ Jobs will run on your API and subscription agents (saved in ${tildePath(commonPath)}).`));
       console.log(c.dim("\nNext:"));
       for (const step of next) console.log(`  ${c.bold(step)}`);
       return;
@@ -557,20 +765,21 @@ async function cmdSetup() {
     }
     fs.mkdirSync(path.dirname(commonPath), { recursive: true });
     writeEnvLine(commonPath, "NOMARMY_EXECUTION", "remote");
+    writeEnvLine(commonPath, "NOMARMY_SETUP_PROFILE", "remote");
     writeEnvLine(commonPath, "NOMARMY_LLAMA_HOST", llamaHost);
     writeEnvLine(commonPath, "NOMARMY_LLAMA_PORT", llamaPort);
-    const next = `${path.join(nomarmyRoot, "install.sh")} --profile remote`;
+    const next = "nomarmy install";
     if (json) return out({ written: commonPath, execution: "remote", llamaHost, llamaPort, reachable, next });
     console.log(reachable
       ? c.green(`✓ llama-server is reachable at ${healthUrl}.`)
       : c.yellow(`⚠ llama-server is not reachable at ${healthUrl} right now; configuration was still written.`));
-    console.log(c.green(`✓ Wrote the remote llama-server settings to ${path.relative(nomarmyRoot, commonPath)}.`));
+    console.log(c.green(`✓ Wrote the remote llama-server settings to ${tildePath(commonPath)}.`));
     console.log(c.dim("\nNext:"));
     console.log(`  ${c.bold(next)}`);
     return;
   }
 
-  const execution = value("execution", process.env.NOMARMY_EXECUTION || "local");
+  const execution = flag("choose") ? "local" : value("execution", process.env.NOMARMY_EXECUTION || "local");
   const isCloud = execution !== "local";
   const hardware = isCloud ? null : await detectHardware();
   const modelPath = isCloud ? null : findModel();
@@ -593,10 +802,10 @@ async function cmdSetup() {
       console.log(isCloud
         ? `Execution is '${execution}' -- hosted inference, local hardware does not bound this.\n`
         : `Hardware: ${c.cyan(`${hardware.platform}/${hardware.arch}`)}, ${hardware.cpu?.logicalCores ?? "?"} logical cores, ${(hardware.memory?.totalBytes / 1024 ** 3).toFixed(1)} GiB RAM\n`);
-      console.log(`More noms ${c.dim(`(confidence: ${res.confidence})`)}: ${c.green(res.summary ?? JSON.stringify(res.env))}`);
-      if (res.nominal && !res.nominal.sameAsRecommended) {
-        console.log(`Nominal: ${res.nominal.fits ? c.dim(res.nominal.summary) : c.red(`${res.nominal.summary} DOES NOT FIT either -- nothing on this machine does.`)}`);
-      }
+      // Plain words; the exact settings are shown before anything is written.
+      const plain = (env) => { const n = Number(env?.NOMARMY_MAX_WORKERS ?? env?.NOMARMY_LLAMA_PARALLEL ?? 1), ctx = Math.round(Number(env?.NOMARMY_LLAMA_CONTEXT ?? 0) / Math.max(1, Number(env?.NOMARMY_LLAMA_PARALLEL ?? 1)) / 1024); return `${n} local job${n === 1 ? "" : "s"} at a time${ctx ? `, ${ctx}K tokens of context each` : ""}`; };
+      console.log(`This machine fits ${c.green(plain(res.env))}${res.confidence === "low" ? c.dim(" (an estimate)") : ""}.`);
+      if (res.nominal && !res.nominal.fits) console.log(c.red("Even one local job doesn't fit in this machine's memory: choose hosted instead (nomarmy setup --choose)."));
     }
 
     // "More noms" fits as many noms as memory allows; "nominal" is 1 worker
@@ -614,8 +823,8 @@ async function cmdSetup() {
         if (sizingTier !== "more" && sizingTier !== "nominal") throw new Error('--tier must be "more" or "nominal".');
       } else {
         console.log(`\n${c.bold("Which sizing?")}`);
-        console.log(`  ${c.cyan("1.")} More noms -- as many as fit in memory`);
-        console.log(`  ${c.cyan("2.")} Nominal -- 1 nom, matching this project's own shipped profiles`);
+        console.log(`  ${c.cyan("1.")} As many at once as fit in memory`);
+        console.log(`  ${c.cyan("2.")} One at a time (lighter on the machine)`);
         const choice = (await rl.question(c.bold("Choice [1]: "))).trim() || "1";
         sizingTier = choice === "2" ? "nominal" : "more";
       }
@@ -634,8 +843,8 @@ async function cmdSetup() {
     }
 
     const profileName = nonInteractive ? value("profile-name") : (await rl.question(`\nProfile name [${hardware?.appleSilicon ? "macbook-pro" : "custom"}]: `)).trim() || (hardware?.appleSilicon ? "macbook-pro" : "custom");
-    const profilePath = path.join(nomarmyRoot, "config", "profiles", `${profileName}.env`);
-    const commonPath = path.join(nomarmyRoot, "config", "common.env");
+    const profilePath = userProfilePath(profileName);
+    const commonPath = userCommonPath();
 
     const profileWrites = { ...sizingEnv };
     if (!isCloud) {
@@ -648,10 +857,10 @@ async function cmdSetup() {
     }
 
     if (!json) {
-      console.log(c.bold(`\nAbout to write ${path.relative(nomarmyRoot, profilePath)}:`));
+      console.log(c.bold(`\nAbout to write ${tildePath(profilePath)}:`));
       for (const [k, v] of Object.entries(profileWrites)) console.log(c.dim(`  ${k}=${v}`));
       if (model?.kind === "known") {
-        console.log(c.bold(`\nAnd ${path.relative(nomarmyRoot, commonPath)}:`));
+        console.log(c.bold(`\nAnd ${tildePath(commonPath)}:`));
         console.log(c.dim(`  NOMARMY_MODEL_REPO=${model.repo}`));
         console.log(c.dim(`  NOMARMY_MODEL_QUANT=${model.quant}`));
         console.log(c.dim(`  NOMARMY_MODEL_ALIAS=${model.alias}`));
@@ -659,13 +868,17 @@ async function cmdSetup() {
         console.log(c.dim(`  NOMARMY_MODEL_THINKING=${model.thinking}`));
       }
       if (!nonInteractive) {
-        const answer = (await rl.question(c.bold("\nWrite this configuration? [y/N] "))).trim().toLowerCase();
-        if (answer !== "y") { console.log(c.dim("Canceled; nothing written.")); return; }
+        // Yes by default: someone who accepted every suggestion shouldn't lose it all at the last Enter.
+        const answer = (await rl.question(c.bold("\nWrite this configuration? [Y/n] "))).trim().toLowerCase();
+        if (answer === "n" || answer === "no") { console.log(c.dim("Canceled; nothing written.")); return; }
       }
     }
 
     fs.mkdirSync(path.dirname(profilePath), { recursive: true });
     for (const [k, v] of Object.entries(profileWrites)) writeEnvLine(profilePath, k, v);
+    writeEnvLine(commonPath, "NOMARMY_EXECUTION", execution);
+    if (execution === "local") writeEnvLine(commonPath, "NOMARMY_LLAMA_HOST", "127.0.0.1");
+    writeEnvLine(commonPath, "NOMARMY_SETUP_PROFILE", execution === "bedrock" ? "bedrock" : profileName);
     if (model?.kind === "known" && model.repo) {
       writeEnvLine(commonPath, "NOMARMY_MODEL_REPO", model.repo);
       writeEnvLine(commonPath, "NOMARMY_MODEL_QUANT", model.quant);
@@ -679,16 +892,16 @@ async function cmdSetup() {
       writeEnvLine(commonPath, "NOMARMY_WORKER_MODEL", model.alias);
       writeEnvLine(commonPath, "NOMARMY_MODEL_THINKING", String(model.thinking));
     } else if (model?.kind === "search") {
-      const searchedAlias = readEnvValue(commonPath, "NOMARMY_MODEL_ALIAS");
+      const searchedAlias = setting("NOMARMY_MODEL_ALIAS");
       if (searchedAlias) {
         writeEnvLine(commonPath, "NOMARMY_WORKER_MODEL", searchedAlias);
         writeEnvLine(commonPath, "NOMARMY_MODEL_THINKING", String(model.thinking));
       }
     }
 
-    const installCmd = `./install.sh --profile ${profileName}${isCloud ? "" : ""}`;
+    const installCmd = "nomarmy install";
     if (json) return out({ written: { profile: profilePath, common: model?.kind === "known" ? commonPath : null }, env: profileWrites, sizingTier, installCommand: installCmd });
-    console.log(c.green(`\n✓ Wrote ${path.relative(nomarmyRoot, profilePath)}${model?.kind === "known" ? ` and ${path.relative(nomarmyRoot, commonPath)}` : ""}.`));
+    console.log(c.green(`\n✓ Wrote ${tildePath(profilePath)}${model?.kind === "known" ? ` and ${tildePath(commonPath)}` : ""}.`));
     console.log(c.dim("\nThis proposes; it does not install. Run:\n"));
     console.log(`  ${c.bold(installCmd)}\n`);
   } finally {
@@ -717,7 +930,7 @@ function restartInference() {
   runScript("start-inference.sh", []);
 }
 async function cmdModel() {
-  const commonPath = path.join(nomarmyRoot, "config", "common.env");
+  const commonPath = userCommonPath();
   if (json) {
     const which = value("model");
     if (!KNOWN_MODELS[which]) throw new Error(`--json requires --model one of ${Object.keys(KNOWN_MODELS).join(", ")} (Hugging Face search is interactive-only).`);
@@ -741,17 +954,17 @@ async function cmdModel() {
     const model = await chooseModel(rl);
     let alias;
     if (model.kind === "search") {
-      console.log(c.green("\n✓ Done") + " -- config/common.env was already updated by the search above.");
-      alias = readEnvValue(commonPath, "NOMARMY_MODEL_ALIAS");
+      console.log(c.green("\n✓ Done") + ` -- ${tildePath(commonPath)} was already updated by the search above.`);
+      alias = setting("NOMARMY_MODEL_ALIAS");
     } else {
-      console.log(c.bold(`\nAbout to write ${path.relative(nomarmyRoot, commonPath)}:`));
+      console.log(c.bold(`\nAbout to write ${tildePath(commonPath)}:`));
       console.log(c.dim(`  NOMARMY_MODEL_REPO=${model.repo}\n  NOMARMY_MODEL_QUANT=${model.quant}\n  NOMARMY_MODEL_ALIAS=${model.alias}`));
       const answer = (await rl.question(c.bold("\nApply this model configuration? [y/N] "))).trim().toLowerCase();
       if (answer !== "y") { console.log(c.dim("Canceled; nothing changed.")); return; }
       writeEnvLine(commonPath, "NOMARMY_MODEL_REPO", model.repo);
       writeEnvLine(commonPath, "NOMARMY_MODEL_QUANT", model.quant);
       writeEnvLine(commonPath, "NOMARMY_MODEL_ALIAS", model.alias);
-      console.log(c.green(`✓ Wrote ${path.relative(nomarmyRoot, commonPath)}.`));
+      console.log(c.green(`✓ Wrote ${tildePath(commonPath)}.`));
       alias = model.alias;
     }
     if (alias) {
@@ -975,23 +1188,24 @@ async function ensureVendorAuth(rl, vendorKey) {
   let status = readLoginStatus(vendorKey);
   if (!status.loggedIn) {
     console.log(c.yellow(`You're not logged in to ${vendor.cli.bin} yet -- this opens its own login (a browser or a device code).`));
-    if (!(await confirm(rl, "Log in now?"))) return { ok: false };
-    runInteractive(vendor.cli.bin, vendor.cli.loginArgs);
+    if (!(await confirm(rl, "Log in now?"))) { console.log(c.red(`✗ Sign-in canceled. Retry with \`nomarmy agents add subscription ${vendorKey}\`.`)); return { ok: false }; }
+    const loginOk = runInteractive(vendor.cli.bin, vendor.cli.loginArgs);
+    if (!loginOk) { console.log(c.red(`✗ ${vendor.cli.bin} sign-in failed or was canceled. Retry with \`nomarmy agents add subscription ${vendorKey}\`.`)); return { ok: false }; }
     status = readLoginStatus(vendorKey);
-    if (!status.loggedIn) { console.log(c.red(`✗ Still not logged in to ${vendor.cli.bin}.`)); return { ok: false }; }
+    if (!status.loggedIn) { console.log(c.red(`✗ Still not logged in to ${vendor.cli.bin}. Retry with \`nomarmy agents add subscription ${vendorKey}\`.`)); return { ok: false }; }
   }
   console.log(c.green(`✓ Logged in to ${vendor.cli.bin}${status.email ? ` as ${status.email}` : ""}${status.subscriptionType ? ` (${status.subscriptionType})` : ""}.`));
 
   if (vendor.plugin) {
     step("OpenClaw plugin");
     const version = parseOpenclawVersion(runQuiet(openclawCmd(), ["--version"]).out);
-    if (!versionAtLeast(version, vendor.plugin.minOpenclaw)) {
-      console.log(c.yellow(`OpenClaw ${version ? version.join(".") : "(unknown version)"} is older than the ${vendor.plugin.minOpenclaw} this vendor's plugin needs.`));
-      if (!(await confirm(rl, "Update OpenClaw now (npm update -g openclaw)?"))) return { ok: false };
-      if (!runInteractive("npm", ["update", "-g", "openclaw"])) {
-        console.log(c.red("✗ Update failed. If npm reports EACCES, your global npm directory has root-owned files from an old sudo install: `sudo chown -R $(whoami) ~/.npm ~/.npm-global` fixes it."));
-        return { ok: false };
-      }
+    if (!versionAtLeast(version, PINNED_OPENCLAW_VERSION)) {
+      const repaired = await repairOpenclaw({
+        command: openclawCmd(),
+        vendors: configuredSubscriptionVendors(loadAgentsOrExit().agents, [vendorKey]),
+        isTTY: Boolean(input.isTTY), ask: (prompt) => rl.question(prompt),
+      });
+      if (!repaired.ok) return { ok: false };
     }
     if (!runQuiet(openclawCmd(), ["plugins", "inspect", vendor.plugin.id]).ok) {
       console.log(c.dim(`Installing ${vendor.plugin.spec}...`));
@@ -1001,6 +1215,12 @@ async function ensureVendorAuth(rl, vendorKey) {
       }
       runQuiet(openclawCmd(), ["plugins", "registry", "--refresh"]);
     }
+    const checks = verifyOpenclaw({ command: openclawCmd(), vendors: configuredSubscriptionVendors(loadAgentsOrExit().agents, [vendorKey]) });
+    const failed = checks.filter((check) => !check.ok);
+    if (failed.length) {
+      for (const check of failed) console.log(c.red(`✗ ${check.message} Fix: ${check.fix}`));
+      return { ok: false };
+    }
     console.log(c.green(`✓ OpenClaw's ${vendor.plugin.id} plugin is ready.`));
   }
   if (vendor.credential.kind === "minted-key") {
@@ -1022,13 +1242,27 @@ async function ensureVendorAuth(rl, vendorKey) {
   return { ok: true, email: status.email };
 }
 
+function hasUsableOpenclawAuthProfile(provider) {
+  // Same OpenClaw command and JSON shape used by health's login-expiry check.
+  const result = runQuiet(openclawCmd(), ["models", "auth", "list", "--json"]);
+  if (!result.ok) return false;
+  const profiles = parseOpenclawAuthProfiles(result.stdout);
+  return profiles?.some((profile) => {
+    if (profile.provider !== provider) return false;
+    if (profile.expiresAt == null) return true;
+    const expires = Date.parse(profile.expiresAt);
+    return Number.isFinite(expires) && expires > Date.now();
+  }) ?? false;
+}
+
 function catalogModelsFor(provider) {
   return parseCatalogModels(runQuiet(openclawCmd(), ["models", "list", "--refresh"]).out, provider);
 }
 
-/** One real, one-token completion through OpenClaw -- the only proof a credential actually works. */
+/** One real, one-token completion through OpenClaw to test a model. */
 // Why the last probeWorker() call failed, in the vendor's words when it said.
 let lastProbeFailure = null;
+let lastProbeText = "";
 function probeWorker(provider, model) {
   // The route a job takes: the ambient OpenClaw config and a state dir of
   // its own, never --isolated. --isolated skips that config, and with it the
@@ -1044,7 +1278,10 @@ function probeWorker(provider, model) {
       "--json", "--cwd", cwd, "--state-dir", stateDir, "--timeout", "90"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], cwd });
     // Streams kept apart: OpenClaw logs a "run ... ended" line to stderr
     // AFTER the JSON envelope, and the merged text doesn't parse.
-    const outcome = probeOutcome({ stdout: result.stdout ?? "", stderr: result.stderr ?? "" });
+    const stdout = result.stdout ?? "";
+    const stderr = result.stderr ?? "";
+    const outcome = probeOutcome({ stdout, stderr });
+    lastProbeText = `${stderr}\n${stdout}`;
     lastProbeFailure = outcome.ok ? null : outcome.reason;
     if (outcome.ok) recordProbeSuccess(agentStateRoot(), `${provider}/${model}`);
     return outcome.ok;
@@ -1076,10 +1313,15 @@ function reapProbeSandbox(stateDir) {
 /**
  * OpenClaw's own provider login, for the vendors whose plugin wants one on
  * top of the vendor CLI's login (Claude doesn't: OpenClaw reuses the CLI
- * session directly). Only ever run when a probe or catalog lookup has
- * already shown it's needed -- never preemptively.
+ * session directly). Codex always refreshes its imported copy after CLI
+ * login is confirmed; other providers link when catalog or auth checks fail.
  */
-function openclawProviderLogin(vendor) {
+async function openclawProviderLogin(vendor, rl) {
+  if (vendor === SUBSCRIPTION_VENDORS.codex) return linkCodex({
+    run: runQuiet, command: openclawCmd(), isTTY: Boolean(input.isTTY),
+    removeEmailProfiles: flag("remove-email-profiles"),
+    confirm: (prompt, opts) => confirm(rl, prompt, opts), print: (message) => console.log(c.dim(message)),
+  });
   const provider = vendor.credential.loginProvider ?? vendor.provider;
   console.log(c.dim(`Linking OpenClaw to it (\`openclaw models auth login --provider ${provider}\`) -- follow its prompts:`));
   const ok = runInteractive(openclawCmd(), ["models", "auth", "login", "--provider", provider]);
@@ -1092,8 +1334,9 @@ function openclawProviderLogin(vendor) {
 // One list in ~/.config/nomarmy/agents.yml (lib/agents.mjs): the local
 // model, api keys, and individual subscriptions. `add` walks through what
 // each kind needs -- a key registered with OpenClaw, or the vendor's own
-// login -- and proves it with a real test call before saving. Changes apply
-// to the next job; the MCP server re-reads the file when it changes.
+// login -- and tests the selected model before saving, with an explicit
+// opt-in to save after a failed model call. Changes apply to the next job;
+// the MCP server re-reads the file when it changes.
 
 function loadAgentsOrExit() {
   try { return loadAgents(globalConfigDir()); }
@@ -1205,11 +1448,10 @@ async function cmdAgentsAdd() {
     let kind = argv[2];
     if (!AGENT_KINDS.includes(kind)) {
       console.log("\n" + c.bold("What kind of agent?"));
-      console.log(`  ${c.cyan("1.")} local         ${c.dim("the local model on this machine (free, private)")}`);
+      console.log(`  ${c.cyan("1.")} local         ${c.dim("the local model on this machine (no per-token bill, private; slower)")}`);
       console.log(`  ${c.cyan("2.")} api           ${c.dim("a metered API key (xAI, OpenAI, Anthropic, DeepSeek, ...)")}`);
       console.log(`  ${c.cyan("3.")} subscription  ${c.dim("your own Claude, ChatGPT or Muse Code plan (never shared)")}`);
-      kind = AGENT_KINDS[Number((await rl.question(c.bold("Choice: "))).trim()) - 1];
-      if (!kind) throw new Error("Not a valid choice.");
+      kind = AGENT_KINDS[await askChoice(rl, AGENT_KINDS.length)];
     }
     if (kind === "local") return await addLocalAgent(rl, agents);
     if (kind === "api") return await addApiAgent(rl, agents);
@@ -1246,8 +1488,7 @@ async function addLocalAgent(rl, agents) {
 async function addApiAgent(rl, agents) {
   console.log("\n" + c.bold("Which provider?"));
   API_PROVIDER_TYPES.forEach((t, i) => console.log(`  ${c.cyan(`${i + 1}.`)} ${KNOWN_PROVIDERS[t]?.label ?? t}`));
-  const provider = API_PROVIDER_TYPES[Number((await rl.question(c.bold("Choice: "))).trim()) - 1];
-  if (!provider) throw new Error("Not a valid choice.");
+  const provider = API_PROVIDER_TYPES[await askChoice(rl, API_PROVIDER_TYPES.length)];
   const info = KNOWN_PROVIDERS[provider] ?? {};
   const agent = { kind: "api", provider };
 
@@ -1313,6 +1554,14 @@ async function addApiAgent(rl, agents) {
   console.log(c.dim(`Use it with \`nomarmy army assign <role> ${name}\` or agent: "${name}" on a job.`));
 }
 
+const OWNER_EMAIL_RE = /^[^@\s]+@[^@\s]+$/;
+function validOwnerEmail(email) { return typeof email === "string" && OWNER_EMAIL_RE.test(email); }
+function gitUserEmail() {
+  const result = spawnSync("git", ["config", "user.email"], { cwd: repoDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  const email = result.status === 0 ? result.stdout.trim() : "";
+  return validOwnerEmail(email) ? email : "";
+}
+
 const SUBSCRIPTION_AGENT_DEFAULT_NAMES = { claude: "claude", codex: "codex", meta: "muse" };
 
 async function addSubscriptionAgent(rl, agents) {
@@ -1322,8 +1571,7 @@ async function addSubscriptionAgent(rl, agents) {
   if (!SUBSCRIPTION_VENDORS[vendorKey]) {
     console.log("\n" + c.bold("Which subscription?"));
     vendorKeys.forEach((k, i) => console.log(`  ${c.cyan(`${i + 1}.`)} ${SUBSCRIPTION_VENDORS[k].label}`));
-    vendorKey = vendorKeys[Number((await rl.question(c.bold("Choice: "))).trim()) - 1];
-    if (!vendorKey) throw new Error(`Not a valid choice. Supported: ${vendorKeys.join(", ")}. DeepSeek and others without a plan are api agents.`);
+    vendorKey = vendorKeys[await askChoice(rl, vendorKeys.length)];
   }
   const vendor = SUBSCRIPTION_VENDORS[vendorKey];
 
@@ -1337,16 +1585,34 @@ async function addSubscriptionAgent(rl, agents) {
   }
 
   const auth = await ensureVendorAuth(rl, vendorKey);
-  if (!auth.ok) { console.log(c.dim("\nStopped; nothing was written.")); return; }
+  if (!auth.ok) { console.log(c.dim("\nStopped; nothing was written.")); process.exitCode = 1; return; }
 
   console.log(`\n${c.bold("→")} Models`);
   const needsOpenclawLogin = vendor.credential.kind === "openclaw-login";
   let linkedOpenclaw = false;
+  if (vendorKey === "codex") {
+    linkedOpenclaw = await openclawProviderLogin(vendor, rl);
+    if (!linkedOpenclaw) {
+      console.log(c.red("✗ Sign-in has no usable auth profile. Retry with `nomarmy agents add subscription codex`."));
+      process.exitCode = 1; return;
+    }
+  }
   let models = catalogModelsFor(vendor.provider);
-  if (!models.length && needsOpenclawLogin) {
-    linkedOpenclaw = openclawProviderLogin(vendor);
+  if (!models.length && needsOpenclawLogin && !linkedOpenclaw) {
+    linkedOpenclaw = await openclawProviderLogin(vendor, rl);
+    if (!linkedOpenclaw) { console.log(c.red(`✗ Sign-in failed or was canceled. Retry with \`nomarmy agents add subscription ${vendorKey}\`.`)); process.exitCode = 1; return; }
     models = catalogModelsFor(vendor.provider);
   }
+  // Catalog entries can be cached, and a particular model can refuse a
+  // working login. Check OpenClaw's auth profile before asking for details.
+  if (needsOpenclawLogin && !hasUsableOpenclawAuthProfile(vendor.provider)) {
+    if (linkedOpenclaw || !(await openclawProviderLogin(vendor, rl)) || !hasUsableOpenclawAuthProfile(vendor.provider)) {
+      console.log(c.red(`✗ Sign-in has no usable auth profile. Retry with \`nomarmy agents add subscription ${vendorKey}\`.`));
+      process.exitCode = 1;
+      return;
+    }
+    linkedOpenclaw = true;
+  }
   // The agent is the account; the model is only a default. Roles pick
   // their own model (or "auto" for the General to choose per job).
   if (models.length) models.forEach((m, i) => console.log(`  ${c.cyan(`${i + 1}.`)} ${m}`));
@@ -1354,27 +1620,38 @@ async function addSubscriptionAgent(rl, agents) {
   const pick = (await rl.question(c.bold(`Default model, optional${models.length ? " (a number or an id)" : ""}; blank = pick per role: `))).trim();
   const model = /^\d+$/.test(pick) && models.length ? models[Number(pick) - 1] : pick || null;
   if (pick && !model) throw new Error(`Not a valid choice: "${pick}".`);
-  // The test call needs some model; it proves the login, not the choice.
+  // A usable profile is only a fast precondition. The test call is what
+  // proves sign-in: an unexpired Codex import can still answer 401.
   const probeModel = model ?? models[0] ?? vendor.defaultModel;
 
-  const knownOwners = [...new Set(Object.values(agents).filter((a) => a.kind === "subscription").map((a) => a.owner))];
-  const ownerDefault = auth.email ?? (knownOwners.length === 1 ? knownOwners[0] : "");
-  const owner = (await rl.question(c.bold(`Whose subscription is this${ownerDefault ? ` [${ownerDefault}]` : ""}: `))).trim() || ownerDefault;
-  if (!owner) throw new Error("An owner is required -- every job on this agent must name them in on_behalf_of.");
+  const ownerDefault = validOwnerEmail(auth.email) ? auth.email : gitUserEmail();
+  const owner = await askUntilValid(rl, `Whose subscription is this${ownerDefault ? ` [${ownerDefault}]` : ""}: `, {
+    allowEmpty: Boolean(ownerDefault), fallback: ownerDefault, pattern: OWNER_EMAIL_RE,
+    invalidMessage: "enter an email address (one @, no spaces).",
+  });
 
   const name = await askAgentName(rl, agents, SUBSCRIPTION_AGENT_DEFAULT_NAMES[vendorKey] ?? vendorKey);
   if (!name) { console.log(c.dim("Stopped; nothing was written.")); return; }
 
   console.log(`\n${c.bold("→")} Test call`);
-  let works = probeModel ? probeWorker(vendor.provider, probeModel) : false;
-  if (!works && needsOpenclawLogin && !linkedOpenclaw && probeModel) {
-    openclawProviderLogin(vendor);
-    works = probeWorker(vendor.provider, probeModel);
-  }
+  const probed = Boolean(probeModel);
+  const works = probed ? probeWorker(vendor.provider, probeModel) : false;
   if (works) console.log(c.green(`✓ ${vendor.provider}/${probeModel} answered a real test prompt.`));
-  else {
-    console.log(c.red(probeModel ? `✗ A real test prompt to ${vendor.provider}/${probeModel} didn't come back.` : "✗ No model to make a test call with."));
-    if (!(await confirm(rl, "Save the agent anyway?", { defaultYes: false }))) { console.log(c.dim("Stopped; nothing was written.")); return; }
+  else if (needsOpenclawLogin && probed && openclawSignInFailure(`${lastProbeFailure ?? ""}\n${lastProbeText}`)) {
+    const why = lastProbeFailure ? `: ${lastProbeFailure}` : "";
+    console.log(c.red(`✗ Sign-in failed${why}.`));
+    console.log(`  fix: ${codexImportRecovery()}`);
+    console.log(c.dim("Stopped; nothing was written."));
+    process.exitCode = 1;
+    return;
+  } else {
+    console.log(c.yellow(probeModel ? `⚠ The login works, but ${vendor.provider}/${probeModel} didn't answer a real test prompt.` : "⚠ The login works, but no model is available for a test call."));
+    console.log(c.dim(`You can retry later with \`nomarmy agents update ${name} --probe\`.`));
+    if (!(await confirm(rl, "Save the agent anyway?", { defaultYes: false }))) {
+      console.log(c.dim("Stopped; nothing was written."));
+      process.exitCode = 1;
+      return;
+    }
   }
   const written = saveAgents({ ...agents, [name]: { kind: "subscription", provider: vendor.provider, owner, ...(model ? { model } : {}) } });
   savedAgentMessage(name, written);
@@ -1387,6 +1664,7 @@ async function cmdAgentsAddJson() {
   const kind = value("kind") ?? (AGENT_KINDS.includes(argv[2]) ? argv[2] : null);
   if (!name || !kind) throw new Error(`--json requires --name <agent> and --kind <${AGENT_KINDS.join("|")}>, plus that kind's fields (see \`nomarmy help\`).`);
   if (RESERVED_AGENT_NAMES.includes(name)) throw new Error(`"${name}" is a reserved name.`);
+  if (kind === "subscription" && value("owner") !== null && !validOwnerEmail(value("owner"))) throw new Error("--owner must be an email address (one @, no spaces).");
   const agent = { kind };
   const num = (flagName) => (value(flagName) !== null ? Number(value(flagName)) : undefined);
   if (kind === "local") {
@@ -1401,6 +1679,15 @@ async function cmdAgentsAddJson() {
     const thinking = resolveThinkingFlag();
     if (thinking !== undefined) agent.thinking = thinking;
   }
+  if (kind === "subscription" && agent.provider === "openai" && (flag("link-openclaw") || flag("remove-email-profiles"))) {
+    if (!readLoginStatus("codex").loggedIn) throw new Error("Confirm Codex CLI login first: codex login");
+    const linked = await linkCodex({ run: runQuiet, command: openclawCmd(),
+      removeEmailProfiles: flag("remove-email-profiles"), print: (message) => console.error(message) });
+    if (!linked) throw new Error("Codex import failed; nothing was written.");
+    if (!probeWorker("openai", agent.model ?? SUBSCRIPTION_VENDORS.codex.defaultModel)) {
+      throw new Error(`Codex test call failed; nothing was written. Fix: ${codexImportRecovery()}`);
+    }
+  }
   const written = saveAgents({ ...agents, [name]: agent });
   const saved = written[name];
   let registered = null, mcpUpdated = false;
@@ -1412,6 +1699,43 @@ async function cmdAgentsAddJson() {
   return out({ written: agentsConfigPath(globalConfigDir()), name, agent: saved, ...(kind === "api" ? { registered, mcpUpdated } : {}) });
 }
 
+// A probe-only update checks credentials without changing agents.yml.
+function probeConfiguredAgent(name, agent) {
+  const provider = agentProviderId(agent);
+  let model = agent.model;
+  let source = "";
+  if (!model && provider) {
+    const role = agentAssignments()[name]?.roles.find((r) => r.model && r.model !== "auto");
+    if (role) { model = role.model; source = `${role.role}'s model`; }
+    if (!model) {
+      const vendor = Object.values(SUBSCRIPTION_VENDORS).find((v) => v.provider === provider);
+      if (vendor?.defaultModel) { model = vendor.defaultModel; source = "vendor default"; }
+    }
+    if (!model) {
+      model = catalogModelsFor(provider)[0];
+      if (model) source = "first catalog model";
+    }
+  }
+  if (!provider || !model) {
+    console.log(c.red(`✗ ${name}  ${provider ?? agent.kind}/${model ?? "no model"}  no model available; set one with \`nomarmy agents update ${name} --model <m>\``));
+    process.exitCode = 1;
+    return;
+  }
+  const selected = `${provider}/${model}${source ? ` (${source})` : ""}`;
+  const start = performance.now();
+  const ok = probeWorker(provider, model);
+  const elapsed = ((performance.now() - start) / 1000).toFixed(1);
+  console.log(ok ? c.green(`✓ ${name}  ${selected}  answered in ${elapsed}s`)
+    : c.red(`✗ ${name}  ${selected}  failed: ${lastProbeFailure ?? "no answer"}`));
+  if (!ok) process.exitCode = 1;
+}
+
+function cmdAgentsProbeAll() {
+  const agents = fileAgentsOrExit();
+  if (!Object.keys(agents).length) { console.log("No configured agents to probe."); return; }
+  for (const [name, agent] of Object.entries(agents)) probeConfiguredAgent(name, agent);
+}
+
 // --- update ---
 
 // Kind, provider and owner are fixed: changing any of them is a different
@@ -1420,7 +1744,8 @@ async function cmdAgentsAddJson() {
 // test call `add` makes (interactive always; --json only with --probe,
 // since it spends a real request on the subscription).
 async function cmdAgentsUpdate() {
-  const name = argv[2];
+  const name = argv[2]?.startsWith("--") ? null : argv[2];
+  if (!name && flag("probe")) return cmdAgentsProbeAll();
   if (!name) throw new Error("Usage: nomarmy agents update <name> [--model <m>|--no-model] [--slot coder|gpt] [--auth-env <NAME>] [--base-url <url>] [--max-concurrent <n>] [--context-window <tokens>] [--thinking [low|medium|high]|--no-thinking] [--probe]");
   const agents = fileAgentsOrExit();
   const current = Object.prototype.hasOwnProperty.call(agents, name) ? agents[name] : name === "local" ? { ...BUILTIN_LOCAL_AGENT } : undefined;
@@ -1428,7 +1753,9 @@ async function cmdAgentsUpdate() {
 
   const changes = {};
   let probe = false;
-  if (json) {
+  // Flags alone are enough; without any, it asks field by field.
+  const flagged = ["model", "no-model", "slot", "auth-env", "base-url", "max-concurrent", "context-window", "thinking", "no-thinking", "probe"].some((f) => flag(f));
+  if (json || flagged) {
     const num = (flagName) => (value(flagName) !== null ? Number(value(flagName)) : undefined);
     if (value("model") !== null) changes.model = value("model");
     // Back to no default model: every role (or job) then names its own.
@@ -1443,10 +1770,10 @@ async function cmdAgentsUpdate() {
     if (flag("owner") || value("owner") !== null || value("provider") !== null || value("kind") !== null) {
       throw new Error("Kind, provider and owner can't be changed -- that's a different agent. Use `nomarmy agents add`.");
     }
-    probe = flag("probe") && current.kind === "subscription";
-    if (!Object.keys(changes).length) throw new Error("Nothing to update -- pass at least one field flag (see `nomarmy agents update` usage).");
+    probe = flag("probe");
+    if (!Object.keys(changes).length && !probe) throw new Error("Nothing to update -- pass at least one field flag (see `nomarmy agents update` usage).");
   } else {
-    if (!process.stdin.isTTY) throw new Error("nomarmy agents update needs an interactive terminal, or --json with explicit flags.");
+    if (!process.stdin.isTTY) throw new Error("nomarmy agents update needs an interactive terminal, or the flags to change (e.g. --max-concurrent 3).");
     const rl = createInterface({ input, output });
     try {
       console.log(c.bold("🍪 nomArmy agents update") + c.dim(`  (${name}: ${describeAgentLabel(current)})`));
@@ -1491,7 +1818,8 @@ async function cmdAgentsUpdate() {
     if (!Object.keys(changes).length) { console.log(c.dim("\nNothing changed.")); return; }
   }
 
-  if (probe && changes.model && !probeWorker(current.provider, changes.model)) {
+  if (probe && !Object.keys(changes).length) { probeConfiguredAgent(name, current); return; }
+  if (probe && changes.model && !probeWorker(agentProviderId(current), changes.model)) {
     out({ error: `a real test prompt to ${current.provider}/${changes.model} didn't come back -- nothing was written` });
     process.exit(1);
   }
@@ -1529,14 +1857,9 @@ function git(args) {
  */
 async function cmdUpdate() {
   const say = (s) => { if (!json) console.log(s); };
-  // Installed from npm: there's no checkout to pull. npm updates the
-  // package; connect resyncs the copy each coordinator runs.
-  if (!fs.existsSync(path.join(nomarmyRoot, ".git"))) {
-    const how = "npm install -g nomarmy@alpha && nomarmy connect";
-    if (json) return out({ error: "installed from npm, not a git checkout", fix: how });
-    console.log(`This nomArmy was installed from npm, so there's nothing to pull. Update with:\n  ${how}`);
-    return;
-  }
+  // Installed from npm: npm updates the package, then connect resyncs the
+  // copy each coordinator runs.
+  if (!fs.existsSync(path.join(nomarmyRoot, ".git"))) return updateFromNpm();
   const status = git(["status", "--porcelain"]);
   if (status) {
     if (json) { out({ error: "working tree is not clean; refusing to pull over local changes", status }); process.exit(1); }
@@ -1550,8 +1873,19 @@ async function cmdUpdate() {
   const remote = git(["rev-parse", "@{u}"]);
   const base = git(["merge-base", "HEAD", "@{u}"]);
   if (local === remote) {
-    if (json) return out({ updated: false, reason: "already up to date" });
-    console.log(c.green("✓ Already up to date."));
+    // Nothing to pull, but the copy coordinators run can still be behind
+    // this checkout (commits made or pulled here without a reconnect).
+    if (!copyIsStale(defaultInstallDir(), nomarmyRoot)) {
+      if (json) return out({ updated: false, reason: "already up to date" });
+      console.log(c.green("✓ Already up to date, and your coordinators run this checkout."));
+      printSessionRestarts({ quietWhenNone: true });
+      return;
+    }
+    say(c.bold("🍪 nomArmy update\n"));
+    say("Nothing to pull, but your coordinators run an older copy of this checkout.");
+    const resynced = reconnectCoordinators();
+    if (json) return out({ updated: false, resynced, sha: local });
+    printSessionRestarts();
     return;
   }
   if (base !== local) {
@@ -1567,28 +1901,81 @@ async function cmdUpdate() {
   say("\nInstalling dependencies...");
   execFileSync("npm", ["install", "--omit=dev", "--no-audit", "--no-fund"], { cwd: nomarmyRoot, stdio: json ? "ignore" : "inherit" });
 
-  const resynced = [];
-  const runInherit = (cmd, args, opts = {}) => execFileSync(cmd, args, { stdio: json ? "ignore" : "inherit", ...opts });
-  if (commandExists("claude")) {
-    say("\nRe-syncing the Claude Code MCP install...");
-    connectClaude({ nomarmyRoot, run: runInherit });
-    resynced.push("claude");
+  const resynced = reconnectCoordinators();
+
+  if (json) return out({ updated: true, sha: git(["rev-parse", "HEAD"]), resynced });
+  console.log(c.yellow("\nThe MCP server is a per-session child process: every open Claude Code / Codex / Cursor session needs a restart to pick this up, not just this one."));
+}
+
+// The coordinators nomArmy is registered with. Cursor has no CLI to probe,
+// so it counts when its own config already lists nomArmy.
+// Reconnect every connected coordinator through a child process, so it runs
+// the code now on disk (just pulled or installed) rather than the old code
+// this process loaded. Returns the targets reconnected.
+// Each open session keeps the nomArmy it started with: name the ones that
+// started before the installed copy, rather than a blanket "restart".
+function printSessionRestarts({ quietWhenNone = false } = {}) {
+  let list = null;
+  try {
+    const installedAt = fs.statSync(path.join(defaultInstallDir(), "source.json")).mtimeMs;
+    const procs = listProcesses();
+    if (procs) list = staleSessions(procs, { installedAt });
+  } catch { /* no installed copy yet, or ps unavailable */ }
+  if (list === null) {
+    if (!quietWhenNone) console.log(c.yellow("\nRestart every open Claude Code, Codex and Cursor session: each keeps the code it started with until then."));
+    return;
   }
-  if (commandExists("codex")) {
-    say("\nRe-syncing the Codex MCP install...");
-    connectCodex({ nomarmyRoot, run: runInherit });
-    resynced.push("codex");
+  if (!list.length) { if (!quietWhenNone) console.log(c.green("\n✓ No open session runs an older nomArmy.")); return; }
+  console.log(c.yellow(`\n${list.length} open session(s) still run an older nomArmy, until each is restarted:`));
+  for (const line of formatStaleSessions(list)) console.log(line);
+  console.log(c.dim("In Claude Code: /exit, then claude --resume (or /mcp → nomarmy-local-worker → Reconnect). Close any you no longer use."));
+}
+
+function reconnectCoordinators() {
+  const targets = connectedTargets();
+  // Per-repo registrations run the installed copy (or `nomarmy mcp`), so a
+  // refreshed copy is all they need; re-registering them at user scope would
+  // add nomArmy to every project.
+  if (!targets.length) {
+    execFileSync(process.execPath, [path.join(nomarmyRoot, "bin", "nomarmy.mjs"), "connect", "--copy-only", ...(json ? ["--json"] : [])], { stdio: json ? "ignore" : "inherit" });
+    return [];
   }
-  // Cursor has no CLI/PATH binary to probe with commandExists -- "already
-  // connected" is read from its own config file instead.
-  if (cursorAlreadyConnected()) {
-    say("\nRe-syncing the Cursor MCP install...");
-    connectCursor({ nomarmyRoot, run: runInherit });
-    resynced.push("cursor");
+  if (targets.length) {
+    if (!json) console.log(`\nReconnecting ${targets.join(", ")}...`);
+    execFileSync(process.execPath, [path.join(nomarmyRoot, "bin", "nomarmy.mjs"), "connect", ...targets, ...(json ? ["--json"] : [])], { stdio: json ? "ignore" : "inherit" });
   }
+  return targets;
+}
 
-  if (json) return out({ updated: true, sha: git(["rev-parse", "HEAD"]), resynced });
-  console.log(c.yellow("\nThe MCP server is a per-session child process: every open Claude Code / Codex / Cursor session needs a restart to pick this up, not just this one."));
+function connectedTargets() {
+  return [commandExists("claude") && claudeUserScoped() && "claude", commandExists("codex") && "codex", cursorAlreadyConnected() && "cursor"].filter(Boolean);
+}
+
+async function updateFromNpm() {
+  const current = readPackageVersion(nomarmyRoot);
+  let latest = null;
+  try { latest = execFileSync("npm", ["view", "nomarmy", "dist-tags.alpha"], { encoding: "utf8", timeout: 20000 }).trim(); } catch { /* offline */ }
+  if (!latest) {
+    const fix = "npm install -g nomarmy@alpha && nomarmy connect claude";
+    if (json) { out({ error: "could not read nomarmy's latest release from npm", fix }); process.exit(1); }
+    console.log(c.red("Couldn't reach npm to find nomArmy's latest release.") + ` Update by hand:\n  ${fix}`);
+    process.exit(1);
+  }
+  const { copyVersion } = readInstallVersions(defaultInstallDir());
+  const upgrade = compareVersions(current, latest) < 0;
+  const staleCopy = !copyVersion || compareVersions(copyVersion, upgrade ? latest : current) < 0;
+  if (!upgrade && !staleCopy) {
+    if (json) return out({ updated: false, version: current, reason: "already up to date" });
+    console.log(c.green(`✓ nomArmy ${current} is the latest, and your coordinators run it.`));
+    return;
+  }
+  if (upgrade) {
+    if (!json) console.log(c.bold(`🍪 Updating nomArmy ${current} → ${latest}\n`));
+    execFileSync("npm", ["install", "-g", `nomarmy@${latest}`, "--no-audit", "--no-fund"], { stdio: json ? "ignore" : "inherit" });
+  }
+  const targets = reconnectCoordinators();
+  if (json) return out({ updated: upgrade, from: current, version: upgrade ? latest : current, resynced: targets });
+  printSessionRestarts();
 }
 
 function commandExists(cmd) {
@@ -1632,7 +2019,23 @@ async function cmdConnect() {
   // scan the whole argv), and `nomarmy connect --json claude` once broke
   // that promise by reading argv[1] directly -- --json landed in target's
   // slot instead. Multiple bare tokens are now allowed too, for multi-select.
-  const requested = argv.slice(1).filter((a) => !a.startsWith("--"));
+  const flagValues = new Set(["--scope", "--repo"].map((name) => argv.indexOf(name)).filter((i) => i >= 0).map((i) => i + 1));
+  const requested = argv.slice(1).filter((a, i) => !a.startsWith("--") && !flagValues.has(i + 1));
+  const scope = value("scope", "user");
+  if (!SCOPES.includes(scope)) throw new Error(`--scope must be one of ${SCOPES.join(", ")}, got "${scope}".`);
+  const nativeWindows = windowsFrontEnd();
+  if (nativeWindows && scope !== "user") throw new Error("per-repo registration on Windows isn't supported yet; use the default --scope user");
+  if (nativeWindows && flag("copy-only")) throw new Error("Windows runs nomArmy inside WSL; run nomarmy connect <target> instead of --copy-only");
+  let projectDir = null;
+  if (scope !== "user") {
+    try { projectDir = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: repoDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); }
+    catch { throw new Error(`--scope ${scope} registers nomArmy for one repository, and ${repoDir} isn't inside a git repository. Run it from the repository (or pass --repo <dir>).`); }
+  }
+  if (flag("copy-only")) {
+    // `nomarmy update` with only per-repo registrations: refresh the copy they run.
+    installMcpCopy({ nomarmyRoot, installDir: defaultInstallDir(), run: (cmd, args, opts = {}) => execFileSync(cmd, args, { stdio: json ? "ignore" : "inherit", ...opts }) });
+    return json ? out({ refreshed: defaultInstallDir() }) : console.log(c.green(`✓ Refreshed the nomArmy copy in ${defaultInstallDir()}.`));
+  }
   let targets;
   if (requested.length > 0) {
     const unknown = requested.filter((t) => !KNOWN_TARGETS.includes(t));
@@ -1657,9 +2060,23 @@ async function cmdConnect() {
     }
     try {
       if (!json) console.log(c.bold(`\n🍪 Connecting nomArmy to ${target}...`));
-      const result = connectTarget(target, { nomarmyRoot, run });
+      if (nativeWindows) {
+        const capture = (cmd, args, opts = {}) => execFileSync(cmd, args, { stdio: ["ignore", "pipe", "pipe"], ...opts });
+        const distro = pickDistro({ run: capture });
+        const resolved = resolveWslNomarmy({ distro, run: capture });
+        const launch = mcpBridgeLaunch({ distro, ...resolved });
+        const result = connectViaWsl({ target, distro, launch, run, nomarmyRoot });
+        writeWindowsSettings({ distro, ...resolved });
+        results.push({ target, connected: true, ...result });
+        if (!json) console.log(c.green(`✓ Registered nomArmy with ${target}, running inside WSL (${distro})`));
+        continue;
+      }
+      const result = connectTarget(target, { nomarmyRoot, run, scope, projectDir });
       results.push({ target, connected: true, ...result });
-      if (!json) console.log(c.green(`✓ Registered nomarmy-local-worker with ${target}.`));
+      if (!json) console.log(c.green(`✓ Registered nomarmy-local-worker with ${target}${scope === "user" ? "." : scope === "local" ? ` for ${projectDir} only (not committed).` : ` in ${path.relative(projectDir, result.configPath ?? path.join(projectDir, ".mcp.json"))}, for everyone who clones this repository.`}`));
+      if (!json && scope === "local" && result?.excluded?.length) console.log(c.dim(`  Kept out of git (.git/info/exclude): ${result.excluded.join(", ")}`));
+      if (!json && scope === "project") console.log(c.dim(`  Commit it along with the playbook in ${path.relative(projectDir, result.commands.dir)}. Each teammate needs nomArmy installed and set up (npm install -g nomarmy@alpha, then nomarmy setup); the registration runs \`nomarmy mcp\`, which uses their own settings.`));
+      if (!json && scope !== "user" && target === "claude" && result?.userScoped) console.log(c.yellow(`  nomArmy is also registered for all your projects (user scope). To use it only where you register it per repository: claude mcp remove nomarmy-local-worker -s user`));
       if (!json && result?.commands?.installed?.length) console.log(c.green(`✓ Playbooks: ${result.commands.installed.join(", ")}`) + c.dim(` in ${result.commands.dir} (restart ${target} to pick up a new one)`));
       if (!json && result?.notifier?.status === "built") console.log(c.green("✓ Notifications: nomArmy.app, with nomArmy's icon") + c.dim(" (macOS asks once whether to allow it)"));
       if (!json && result?.notifier?.status === "failed") console.log(c.yellow(`⚠ Couldn't build nomArmy.app (${result.notifier.reason}); notifications still work, with Script Editor's icon. Xcode's command-line tools provide swiftc: xcode-select --install`));
@@ -1681,6 +2098,82 @@ async function cmdConnect() {
 function runScript(name, args = []) {
   execFileSync("bash", [path.join(nomarmyRoot, "scripts", name), ...args], { cwd: nomarmyRoot, stdio: "inherit" });
 }
+// `nomarmy sandbox`: see lib/sandbox-vm.mjs.
+async function cmdSandbox() {
+  const stateRoot = process.env.NOMARMY_AGENT_STATE || path.join(os.homedir(), ".local", "share", "nomarmy-local-agents");
+  const podman = (args, opts = {}) => spawnSync("podman", args, { encoding: "utf8", ...opts });
+  const machine = process.platform === "linux" ? null : pickMachine(podman(["machine", "inspect"]).stdout);
+  let images = null;
+  try {
+    const rows = JSON.parse(podman(["system", "df", "--format", "json"]).stdout || "[]");
+    const row = rows.find((r) => /image/i.test(r.Type ?? ""));
+    if (row) images = { count: row.Total ?? null, size: row.Size ?? null, reclaimable: row.Reclaimable ?? null };
+  } catch { /* podman missing or old */ }
+  const runningJobs = liveLeases(path.join(stateRoot, "leases")).length;
+  const memoryGib = value("memory");
+
+  if (!memoryGib && !flag("prune") && !flag("repair")) {
+    if (json) return out({ platform: process.platform, machine, images, runningJobs, minimumMb: MIN_PODMAN_VM_MB });
+    console.log(c.bold("🍪 nomArmy sandbox"));
+    if (process.platform === "linux") console.log("\nPodman runs natively on Linux: there's no VM to size.");
+    else if (!machine) console.log(c.yellow("\nNo Podman machine found. Run: podman machine init && podman machine start"));
+    else {
+      const low = machine.memoryMb && machine.memoryMb < MIN_PODMAN_VM_MB;
+      console.log(`\nVM ${machine.name} (${machine.state}): ${machine.cpus} CPUs, ${low ? c.red(`${machine.memoryMb / 1024} GiB memory`) : `${machine.memoryMb / 1024} GiB memory`}, ${machine.diskGb} GB disk`);
+      if (low) console.log(c.yellow(`  Too small: worker commands get cut off below ${MIN_PODMAN_VM_MB / 1024} GiB. Fix: nomarmy sandbox --memory 8`));
+      const { maxJobs, jobsThatFit, vmGibFor } = await import("../lib/limits.mjs");
+      const limit = maxJobs().value, fit = jobsThatFit(machine.memoryMb);
+      if (fit !== null) console.log(limit > fit
+        ? c.yellow(`  Fits about ${fit} sandboxes at once, but up to ${limit} api and subscription jobs may run. Fix: nomarmy sandbox --memory ${vmGibFor(limit)}, or nomarmy config max-jobs ${fit}`)
+        : c.dim(`  Fits about ${fit} sandboxes at once; up to ${limit} api and subscription jobs may run (nomarmy config max-jobs).`));
+    }
+    if (images) console.log(`Images: ${images.count}, ${images.size}${images.reclaimable ? `, ${images.reclaimable} reclaimable (nomarmy sandbox --prune)` : ""}`);
+    console.log(c.dim(runningJobs ? `${runningJobs} nomArmy job(s) running.` : "No nomArmy jobs running."));
+    return;
+  }
+
+  const ask = async (question) => {
+    if (flag("yes")) return true;
+    if (!process.stdin.isTTY) throw new Error(`${question} Re-run with --yes to confirm without a terminal.`);
+    const rl = createInterface({ input, output });
+    try { return await confirm(rl, question, { defaultYes: false }); } finally { rl.close(); }
+  };
+  const runPodman = (args) => {
+    console.log(c.dim(`$ podman ${args.join(" ")}`));
+    const r = podman(args, { stdio: "inherit" });
+    if (r.status !== 0) throw new Error(`podman ${args.join(" ")} failed (exit ${r.status ?? "none"}).`);
+  };
+
+  if (flag("repair")) {
+    // Restore the subordinate ID ranges a Podman machine ships with, only
+    // where they're missing, then let Podman re-read them.
+    if (process.platform === "linux") throw new Error("On Linux, add a range for your user to /etc/subuid and /etc/subgid (e.g. `sudo usermod --add-subuids 100000-1099999 --add-subgids 100000-1099999 $USER`), then run `podman system migrate`.");
+    if (!machine) throw new Error("No Podman machine found. Run: podman machine init && podman machine start");
+    // podman system migrate stops every container, a running job's sandbox included.
+    if (runningJobs > 0) throw new Error(`${runningJobs} nomArmy job(s) are running; the repair restarts Podman's containers and would kill their sandboxes. Run it when they're done.`);
+    const script = 'set -e; restored=0; for f in /etc/subuid /etc/subgid; do if ! grep -q "^$(id -un):" "$f" 2>/dev/null; then echo "$(id -un):100000:1000000" | sudo tee -a "$f" >/dev/null; echo "restored $f"; restored=1; else echo "$f already has a range"; fi; done; if [ "$restored" = 1 ]; then podman system migrate; else echo "nothing to repair"; fi';
+    if (!(await ask(`Restore missing subordinate ID ranges in the ${machine.name} VM and run podman system migrate?`))) { console.log(c.dim("Nothing changed.")); return; }
+    const r = spawnSync("podman", ["machine", "ssh", machine.name, script], { stdio: "inherit" });
+    if (r.status !== 0) throw new Error(`the repair failed (exit ${r.status ?? "none"}).`);
+    console.log(c.green("✓ Done. Check with: nomarmy doctor"));
+    return;
+  }
+
+  if (memoryGib) {
+    const plan = planResize({ gib: memoryGib, machine, hostMemoryMb: os.totalmem() / 1024 / 1024, runningJobs });
+    if (!plan.ok) throw new Error(plan.problems.join("; "));
+    for (const w of plan.warnings) console.log(c.yellow(`⚠ ${w}`));
+    if (!(await ask(`Restart the Podman VM with ${memoryGib} GiB (from ${machine.memoryMb / 1024})?`))) { console.log(c.dim("Nothing changed.")); return; }
+    for (const args of plan.commands) runPodman(args);
+    console.log(c.green(`✓ The Podman VM now has ${memoryGib} GiB.`));
+  }
+  if (flag("prune")) {
+    if (runningJobs > 0) throw new Error(`${runningJobs} nomArmy job(s) are running; prune when they're done.`);
+    if (!(await ask(`Remove every image no container uses${images?.reclaimable ? ` (about ${images.reclaimable})` : ""}? nomArmy rebuilds its own when a job needs them.`))) { console.log(c.dim("Nothing removed.")); return; }
+    runPodman(["image", "prune", "--all", "--force"]);
+  }
+}
+
 async function cmdStart() { console.log(c.bold("🍪 Starting inference...\n")); runScript("start-inference.sh", argv.slice(1)); }
 async function cmdStop() { runScript("stop-inference.sh", argv.slice(1)); }
 function safeDu(dir) {
@@ -1729,7 +2222,7 @@ async function maybeRemoveAgentsDir({ force }) {
  * needs manual cleanup -- an honest, bounded scope beats guessing at which
  * cache entries are "ours". */
 function resolveConfiguredModelRepos() {
-  const repo = readEnvValue(path.join(nomarmyRoot, "config", "common.env"), "NOMARMY_MODEL_REPO");
+  const repo = setting("NOMARMY_MODEL_REPO");
   return repo ? [repo] : [];
 }
 
@@ -1952,10 +2445,17 @@ function armyLayerFlag(fallback = "global") {
   return chosen[0] ?? fallback;
 }
 
-function loadArmyForCli() {
+function loadArmyForCli({ globalOnly = false, usageRefresh = null } = {}) {
   const agents = loadAgentsOrExit().agents;
-  const loaded = loadArmy({ projectDir: repoDir });
-  return { loaded, agents, summary: describeArmy(loaded, { agents, describeAgent: describeAgentLabel }) };
+  const loaded = globalOnly
+    ? (() => {
+        const filePath = armyLayerPath("global", { projectDir: repoDir });
+        const army = readArmyFile(filePath, { armyOnly: true });
+        return { ...mergeArmy([{ layer: "global", army }]), layers: [{ layer: "global", path: filePath, exists: fs.existsSync(filePath), hasArmy: Boolean(army) }] };
+      })()
+    : loadArmy({ projectDir: repoDir });
+  const usageSnapshots = usageRefresh?.snapshots ?? readUsageSnapshots(process.env.NOMARMY_AGENT_STATE || path.join(os.homedir(), ".local", "share", "nomarmy-local-agents"));
+  return { loaded, agents, summary: describeArmy(loaded, { agents, describeAgent: describeAgentLabel, usageSnapshots, agentProviderId, usageRefreshError: usageRefresh?.error ?? null, usageRefreshFailed: usageRefresh?.failedProviders ?? null }) };
 }
 
 // Claude Code adds settings.local.json to .gitignore for the same reason:
@@ -1975,15 +2475,36 @@ function agentCell(name, runsOn, role = null) {
   return `${name}${model ? ` ${c.bold(model)}` : ""}${runsOn ? c.dim(`  ${runsOn}`) : ""}`;
 }
 
+/** An agent's usage-limit reading (lib/usage-limits.mjs), colored by level. */
+function usageLine(usage, indent) {
+  const text = `${indent}usage: ${usage.text}`;
+  return usage.level === "over" ? c.red(`${text} (at the limit)`) : usage.level === "high" ? c.yellow(text) : c.dim(text);
+}
+
+function repositoryHere(dir) {
+  let current = path.resolve(dir);
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) return true;
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
+
 async function cmdArmyShow() {
-  const { summary } = loadArmyForCli();
+  const inRepository = repositoryHere(repoDir);
+  const stateRoot = process.env.NOMARMY_AGENT_STATE || path.join(os.homedir(), ".local", "share", "nomarmy-local-agents");
+  const usageRefresh = await refreshStaleOverLimitReadings(stateRoot);
+  const { summary } = loadArmyForCli({ globalOnly: !inRepository, usageRefresh });
   if (json) return out(summary);
   const g = summary.general;
-  console.log(c.bold("🪖 nomArmy") + c.dim(`  (${repoDir})`));
+  console.log(c.bold("🪖 nomArmy") + (inRepository ? c.dim(`  (${repoDir})`) : ""));
+  if (!inRepository) console.log(c.dim("no repository here: showing global settings"));
   console.log(`\n${c.bold("General")}  ${g.agent ? agentCell(g.agent, g.agentRunsOn) : ""}${g.setBy ? c.dim(`  [${g.setBy}]`) : ""}`);
   console.log(c.dim(`  ${g.who}`));
   for (const line of g.responsibilities) console.log(c.dim(`  - ${line}`));
   if (g.problem) console.log(c.yellow(`  ⚠ ${g.problem}`));
+  if (g.usage) console.log(usageLine(g.usage, "  "));
   if (summary.workflow) console.log(`\n${c.bold("Workflow")}\n${summary.workflow.split("\n").map((l) => `  ${l}`).join("\n")}`);
   const names = Object.keys(summary.roles);
   if (!names.length) {
@@ -2003,11 +2524,12 @@ async function cmdArmyShow() {
         if (role.description) console.log(c.dim(`    ${role.description}`));
         if (role.problem && role.agent) console.log(c.red(`    ✗ ${role.problem}`));
         if (role.overlapsGeneral) console.log(c.yellow(`    ⚠ ${role.overlapsGeneral}`));
+        if (role.usage) console.log(usageLine(role.usage, "    "));
       }
     }
   }
   console.log(`\n${c.bold("Layers")}  ${c.dim("(later ones win)")}`);
-  for (const layer of summary.layers) {
+  for (const layer of summary.layers.filter((entry) => inRepository || entry.layer === "global")) {
     const state = layer.hasArmy ? c.green("● army section") : layer.exists ? c.dim("○ file exists, no army section") : c.dim("○ no file");
     console.log(`  ${layer.layer.padEnd(8)} ${state.padEnd(40)} ${c.dim(layer.path)}`);
   }
@@ -2057,14 +2579,31 @@ async function cmdArmyInit() {
   }
 }
 
+function armyPositionals() {
+  const result = [];
+  const args = argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (["--repo", "--agent", "--model"].includes(arg)) {
+      if (!args[i + 1] || args[i + 1].startsWith("--")) throw new Error(`${arg} requires a value`);
+      i++;
+    } else if (["--global", "--project", "--local", "--json", "--no-check"].includes(arg)) {
+      continue;
+    } else if (arg.startsWith("--")) {
+      throw new Error(`Unknown army option ${arg}`);
+    } else result.push(arg);
+  }
+  return result;
+}
+
 async function cmdArmyAssign() {
-  // Positionals only: argv also holds flags, and `--json` must never be read as a model.
-  const positional = argv.slice(2);
-  const firstFlag = positional.findIndex((a) => a.startsWith("--"));
-  const [roleName, agentName, model] = firstFlag === -1 ? positional : positional.slice(0, firstFlag);
-  if (!roleName || !agentName) throw new Error("Usage: nomarmy army assign <role> <agent|none> [model|auto] [--global|--project|--local]");
+  const positional = armyPositionals();
+  const [roleName, agentName, model] = positional;
+  if (!roleName || !agentName || positional.length > 3) throw new Error("Usage: nomarmy army assign <role> <agent|none> [model|auto] [--global|--project|--local]");
   const layer = armyLayerFlag("global");
   const filePath = armyLayerPath(layer, { projectDir: repoDir });
+  const defined = Object.prototype.hasOwnProperty.call(loadArmy({ projectDir: repoDir }).army.roles, roleName);
+  if (!defined) throw new Error(`Role "${roleName}" is not defined in any army roster. Run nomarmy army init first.`);
   const target = parseTargetSpec(agentName, model);
   const check = flag("no-check") ? { status: "skipped" } : checkRoleModel(agentName, model);
   if (check.status === "failed") {
@@ -2120,8 +2659,9 @@ function checkRoleModel(agentName, model) {
 // Which agent the General is. Global or local only: it describes the
 // person's own coordinator session, which a committed project file can't know.
 async function cmdArmyGeneral() {
-  const agentName = argv[2];
-  if (!agentName) throw new Error("Usage: nomarmy army general <agent> [--global|--local]");
+  const positional = armyPositionals();
+  const [agentName] = positional;
+  if (!agentName || positional.length !== 1) throw new Error("Usage: nomarmy army general <agent> [--global|--local]");
   const layer = armyLayerFlag("global");
   if (layer === "project") throw new Error("The General is your own coordinator session, so it's set in --global or --local, never in a committed project file.");
   const agents = loadAgentsOrExit().agents;
@@ -2156,14 +2696,38 @@ async function cmdConfigPaths() {
   if (json) return out({ globalDir: globalConfigDir(), agents: { path: agentsPath, exists: fs.existsSync(agentsPath) }, army });
   console.log(c.bold("nomArmy config") + c.dim(`  (global dir: ${globalConfigDir()})`));
   console.log(`  ${fs.existsSync(agentsPath) ? c.green("●") : c.dim("○")} ${"agents".padEnd(8)} ${c.dim(agentsPath)}`);
+  const { limitsPath } = await import("../lib/limits.mjs");
+  console.log(`  ${fs.existsSync(limitsPath()) ? c.green("●") : c.dim("○")} ${"limits".padEnd(8)} ${c.dim(limitsPath())}`);
   console.log(c.bold("\nArmy layers"));
   for (const a of army) console.log(`  ${a.exists ? c.green("●") : c.dim("○")} ${a.layer.padEnd(8)} ${c.dim(a.path)}`);
 }
 
+// `nomarmy config max-jobs [n]`: api and subscription jobs at once, machine-wide.
+async function cmdConfigMaxJobs() {
+  const { maxJobs, setMaxJobs, jobsThatFit, vmGibFor } = await import("../lib/limits.mjs");
+  const given = argv[2];
+  if (given !== undefined) {
+    if (!/^\d+$/.test(given)) throw new Error(`max-jobs must be a whole number, got "${given}"`);
+    setMaxJobs(Number(given));
+  }
+  const limit = maxJobs();
+  const machine = process.platform === "linux" ? null : pickMachine(spawnSync("podman", ["machine", "inspect"], { encoding: "utf8" }).stdout);
+  const fit = jobsThatFit(machine?.memoryMb);
+  if (json) return out({ maxJobs: limit.value, source: limit.source, path: limit.path, problem: limit.problem, podmanVmMemoryMb: machine?.memoryMb ?? null, jobsThatFit: fit });
+  const from = { file: `set in ${limit.path}`, env: "from NOMARMY_MAX_POOL_WORKERS in this shell (limits.yml doesn't set it)", default: "the default" }[limit.source];
+  if (limit.problem) console.log(c.yellow(`⚠ ${limit.problem}`));
+  console.log(`${given !== undefined ? c.green("✓ ") : ""}Up to ${c.bold(String(limit.value))} api and subscription jobs at once, across every session (${from}).`);
+  console.log(c.dim("Each agent's max_concurrent in agents.yml also applies, and local-model jobs have their own limit."));
+  if (given !== undefined) console.log(c.dim("Applies to the next job in every session on this version, no restart."));
+  if (fit !== null && limit.value > fit) console.log(c.yellow(`⚠ The Podman VM (${machine.memoryMb / 1024} GiB) fits about ${fit} sandboxes at once; more get refused for memory or cut off. Fix: nomarmy sandbox --memory ${vmGibFor(limit.value)}`));
+  if (given === undefined) console.log(c.dim("Change it with `nomarmy config max-jobs <n>` (1 to 32)."));
+}
+
 async function cmdConfig() {
   const sub = argv[1] ?? "paths";
   if (sub === "paths") return cmdConfigPaths();
-  throw new Error(`Unknown config subcommand "${sub}". Use: nomarmy config paths`);
+  if (sub === "max-jobs") return cmdConfigMaxJobs();
+  throw new Error(`Unknown config subcommand "${sub}". Use: nomarmy config <paths|max-jobs [n]>`);
 }
 
 // --- `nomarmy jobs [--watch]`: what's running, from any session -----------
@@ -2183,7 +2747,7 @@ function pidIsAlive(pid) {
   try { process.kill(pid, 0); return true; } catch (error) { return error.code === "EPERM"; }
 }
 
-function collectJobs({ recent = 8 } = {}) {
+function collectJobs({ recent = 8, runId = null, projectDir = null } = {}) {
   const root = jobsRootDir();
   let names = [];
   try { names = fs.readdirSync(root); } catch { return { running: [], recent: [] }; }
@@ -2191,6 +2755,10 @@ function collectJobs({ recent = 8 } = {}) {
     const dir = path.join(root, name);
     const status = readJsonSafe(path.join(dir, "status.json")) ?? {};
     const meta = readJsonSafe(path.join(dir, "metadata.json"));
+    const lease = readJsonSafe(path.join(agentStateRoot(), "leases", `${name}.json`));
+    const jobRunId = meta?.labels?.runId ?? lease?.runId ?? null;
+    const jobProjectDir = meta?.projectDir ?? lease?.repo ?? null;
+    if ((runId && jobRunId !== runId) || (projectDir && (!jobProjectDir || path.resolve(jobProjectDir) !== projectDir))) return null;
     const started = Date.parse(status.startedAt ?? meta?.startedAt ?? "") || fs.statSync(dir).mtimeMs;
     const running = status.state === "running" && pidIsAlive(status.serverPid);
     return {
@@ -2203,7 +2771,7 @@ function collectJobs({ recent = 8 } = {}) {
       heartbeatAgeSeconds: status.heartbeatAt ? Math.round((Date.now() - Date.parse(status.heartbeatAt)) / 1000) : null,
       started, dir,
     };
-  }).sort((a, b) => b.started - a.started);
+  }).filter(Boolean).sort((a, b) => b.started - a.started);
   return { running: jobs.filter((j) => j.running), recent: jobs.filter((j) => !j.running).slice(0, recent) };
 }
 
@@ -2232,6 +2800,19 @@ function renderJobs({ running, recent }) {
  */
 async function streamJobEvents() {
   const interval = Math.max(1, Number(value("interval", "3")) || 3) * 1000;
+  // A stream nobody reads must still end: a General that ran this as a
+  // background command (reported only on exit) was never told jobs had
+  // finished, and eight of these streams were left running for days.
+  const untilDone = flag("until-done");
+  const runId = value("run");
+  const projectDir = flag("repo") ? repoDir : null;
+  if (!runId && !projectDir) {
+    const detail = "watching every job on this machine; use --wait <ids> or --run <id> to scope the watch";
+    if (json) console.log(JSON.stringify({ at: new Date().toISOString(), event: "scope", detail }));
+    else console.log(detail);
+  }
+  const idleLimitMs = Math.max(1, Number(value("idle-minutes", "30")) || 30) * 60000;
+  let idleSinceMs = Date.now(), sawRunning = false;
   const seen = new Map();
   const emit = (event, job, detail = "") => {
     if (json) console.log(JSON.stringify({ at: new Date().toISOString(), event, jobId: job.jobId, agent: job.agent, model: job.model, phase: job.phase, detail }));
@@ -2240,7 +2821,7 @@ async function streamJobEvents() {
   process.on("SIGINT", () => process.exit(0));
   let first = true;
   for (;;) {
-    const { running, recent } = collectJobs({ recent: 20 });
+    const { running, recent } = collectJobs({ recent: 20, runId, projectDir });
     const now = new Map([...running, ...recent].map((j) => [j.jobId, j]));
     for (const j of running) {
       const prev = seen.get(j.jobId);
@@ -2251,13 +2832,85 @@ async function streamJobEvents() {
       const j = now.get(id);
       if (prev.running && j && !j.running) emit("finished", j, `${j.phase} after ${fmtSeconds(j.elapsedSeconds)}`);
     }
+    // A finished record can briefly lack its run label after its lease is removed.
+    // Keep the running snapshot until the stamped record becomes visible.
+    const pending = (runId || projectDir) ? [...seen].filter(([id, j]) => j.running && !now.has(id)) : [];
     seen.clear();
-    for (const [id, j] of now) seen.set(id, j);
+    for (const [id, j] of [...now, ...pending]) seen.set(id, j);
     first = false;
+    if (running.length || pending.length) { sawRunning = true; idleSinceMs = Date.now(); }
+    else if (untilDone && sawRunning) {
+      if (json) console.log(JSON.stringify({ at: new Date().toISOString(), event: "done", detail: "every job seen running has finished" }));
+      else console.log(`${new Date().toLocaleTimeString()}  done      every job seen running has finished`);
+      return;
+    } else if (Date.now() - idleSinceMs >= (untilDone ? Math.min(idleLimitMs, 120000) : idleLimitMs)) {
+      const why = untilDone ? "no job was running to wait for" : `nothing has run for ${Math.round(idleLimitMs / 60000)} minutes`;
+      if (json) console.log(JSON.stringify({ at: new Date().toISOString(), event: "idle", detail: why }));
+      else console.log(`${new Date().toLocaleTimeString()}  idle      ${why}; exiting`);
+      return;
+    }
     await new Promise((r) => setTimeout(r, interval));
   }
 }
 
+const commitSha = (commit) => (typeof commit === "string" ? commit : typeof commit?.sha === "string" ? commit.sha : null);
+
+/** Wait for selected jobs in the shared, cross-session state directory. */
+async function waitForJobCli() {
+  const waitIndex = argv.indexOf("--wait");
+  const requested = [];
+  for (let i = waitIndex + 1; i < argv.length && !argv[i].startsWith("--"); i++) requested.push(...argv[i].split(","));
+  const jobIds = [...new Set(requested)];
+  const timeoutSeconds = Number(value("timeout", "1800"));
+  const errorOut = (message) => {
+    if (json) out({ error: message });
+    else console.error(`nomarmy jobs: ${message}`);
+    process.exitCode = 2;
+  };
+  if (!jobIds.length) return errorOut("--wait needs a job id");
+  if (jobIds.some((id) => !id || path.basename(id) !== id || id === "." || id === "..")) return errorOut("--wait needs valid job ids");
+  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 0) return errorOut("--timeout must be a non-negative number of seconds");
+  for (const jobId of jobIds) {
+    if (!fs.existsSync(path.join(jobsRootDir(), jobId)) && !fs.existsSync(path.join(agentStateRoot(), "leases", `${jobId}.json`))) {
+      return errorOut(`unknown job id: ${jobId}`);
+    }
+  }
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  const results = await Promise.all(jobIds.map(async (jobId) => {
+    const jobDir = path.join(jobsRootDir(), jobId);
+    for (;;) {
+      const status = readJsonSafe(path.join(jobDir, "status.json")) ?? {};
+      const meta = readJsonSafe(path.join(jobDir, "metadata.json")) ?? {};
+      if (status.state === "finished" || meta.outcome) {
+        const issues = Array.isArray(meta.issues) ? meta.issues : Array.isArray(status.issues) ? status.issues : [];
+        const result = {
+          jobId,
+          outcome: meta.outcome ?? status.outcome ?? null,
+          coordinatorStatus: meta.coordinatorStatus ?? status.coordinatorStatus ?? null,
+          branch: meta.branch ?? status.branch ?? null,
+          commit: commitSha(meta.commit) ?? commitSha(status.commit),
+          issues,
+        };
+        if (json) out(result);
+        else {
+          const firstIssue = issues[0];
+          const issueText = firstIssue == null ? null : typeof firstIssue === "string" ? firstIssue : firstIssue.message ?? JSON.stringify(firstIssue);
+          console.log([result.jobId, result.outcome ?? "unknown", result.coordinatorStatus ?? "unknown",
+            result.branch ? `branch=${result.branch}` : null, result.commit ? `commit=${result.commit}` : null,
+            issueText ? `issue=${issueText}` : null].filter(Boolean).join(" "));
+        }
+        return result.coordinatorStatus === "complete" ? 0 : 1;
+      }
+      if (Date.now() >= deadline) {
+        errorOut(`timed out waiting for job ${jobId}`);
+        return 2;
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.min(2000, Math.max(1, deadline - Date.now()))));
+    }
+  }));
+  process.exitCode = Math.max(...results);
+}
+
 /**
  * `nomarmy jobs --prune [--older-than DAYS]`: remove runtime/ (per-job npm
  * cache, harness state such as Codex's, OpenClaw's transcript) from
@@ -2274,6 +2927,14 @@ function pruneJobRuntimeCli() {
 }
 
 async function cmdJobs() {
+  if (flag("wait")) return waitForJobCli();
+  if (flag("stop")) {
+    const r = requestJobStop({ jobsRoot: jobsRootDir(), jobId: value("stop"), reason: value("reason") });
+    if (json) return out(r);
+    console.log(r.ok ? c.green(`✓ ${r.message}`) : c.red(`✗ ${r.message}`));
+    if (!r.ok) process.exitCode = 1;
+    return;
+  }
   if (flag("events")) return streamJobEvents();
   if (flag("prune")) return pruneJobRuntimeCli();
   if (json) return out(collectJobs());
@@ -2301,6 +2962,7 @@ async function cmdHealth() {
   const { checkAndRecordHealth } = await import("../lib/health.mjs");
   const stateRoot = process.env.NOMARMY_AGENT_STATE || path.join(os.homedir(), ".local", "share", "nomarmy-local-agents");
   const { result } = await checkAndRecordHealth({ projectDir: repoDir, stateRoot, configDir: globalConfigDir(), env: installEnv() });
+  if (result.issues.some((i) => i.severity === "error")) process.exitCode = 1;
   if (json) return out(result);
   console.log(c.bold("🍪 nomArmy health") + c.dim(`  ${new Date(result.checkedAt).toLocaleString()}`));
   if (!result.issues.length) { console.log(c.green("\n✓ Nothing to fix.")); return; }
@@ -2320,15 +2982,249 @@ async function cmdStatusline() {
   process.stdout.write(`${statusLineText({ session })}\n`);
 }
 
-const commands = { scan: cmdScan, validate: cmdValidate, sizing: cmdSizing, init: cmdInit, setup: cmdSetup, model: cmdModel, agents: cmdAgents, army: cmdArmy, jobs: cmdJobs, statusline: cmdStatusline, health: cmdHealth, config: cmdConfig, update: cmdUpdate, connect: cmdConnect, start: cmdStart, stop: cmdStop, uninstall: cmdUninstall, help: () => usage(0) };
+// `stats --share`: markdown for a PR description or README; `--badge [path]`:
+// an SVG badge to commit, with the README line for it (lib/share.mjs).
+async function shareStats(stats) {
+  const { shareMarkdown, badgeSvg, badgeMarkdown } = await import("../lib/share.mjs");
+  const scope = value("run") ? "this feature run" : value("since") ? `since ${value("since")}` : null;
+  if (flag("share")) console.log(shareMarkdown(stats, { scope }));
+  if (flag("badge")) {
+    const given = value("badge");
+    const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
+    const root = top.status === 0 ? top.stdout.trim() : process.cwd();
+    const file = path.resolve(root, given ?? path.join(".github", "nomarmy-badge.svg"));
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, badgeSvg(stats));
+    const rel = path.relative(root, file).split(path.sep).join("/");
+    console.log(`${flag("share") ? "\n" : ""}${c.green("✓")} Wrote ${rel}. Commit it and add this to your README:\n\n  ${badgeMarkdown(rel)}\n`);
+    console.log(c.dim("Re-run nomarmy stats --badge after more jobs to refresh the numbers."));
+  }
+}
+
+function cmdStats() {
+  const stateRoot = process.env.NOMARMY_AGENT_STATE || path.join(os.homedir(), ".local", "share", "nomarmy-local-agents");
+  const records = loadJobRecords(path.join(stateRoot, "jobs"));
+  let repo = null;
+  if (value("repo")) repo = resolveRepo(records, value("repo"));
+  else if (!flag("all-repos")) {
+    try { repo = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: repoDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); }
+    catch { throw new Error(`${repoDir} isn't inside a git repository; run nomarmy stats from one, or pass --repo <name> or --all-repos`); }
+  }
+  let agentFor = () => null;
+  try { agentFor = agentLookup(loadAgents(globalConfigDir()).agents, agentProviderId); } catch { /* no agents.yml: commands name <agent> */ }
+  const stats = computeStats(records, { repo, sinceMs: parseSince(value("since")), untilMs: parseSince(value("until")), role: value("role"), model: value("model"), runId: value("run"), agentFor, allSuggestions: flag("all-suggestions") });
+  if (json) return out(stats);
+  if (flag("share") || flag("badge")) return shareStats(stats);
+  console.log(flag("details") ? formatStats(stats) : formatStatsSummary(stats, { c }));
+}
+
+// Read one line without echoing it: stty -echo around the read, restored
+// even if the read fails. Windows has no stty, so it says the input shows.
+async function readHiddenLine(prompt) {
+  const hide = process.stdin.isTTY && process.platform !== "win32";
+  if (!hide) console.log(c.yellow("(your input will be visible as you type)"));
+  const rl = createInterface({ input, output });
+  try {
+    if (hide) spawnSync("stty", ["-echo"], { stdio: ["inherit", "ignore", "ignore"] });
+    return (await rl.question(prompt)).trim();
+  } finally {
+    if (hide) { spawnSync("stty", ["echo"], { stdio: ["inherit", "ignore", "ignore"] }); process.stdout.write("\n"); }
+    rl.close();
+  }
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+
+// One tiny System One request, to prove the key and the route work.
+async function testJev(settings) {
+  const { answers } = await askJev({ key: settings.key, model: settings.model, state: { text: "The build finished and all 12 tests passed." },
+    questions: { passed: { type: "noul", instructions: "Does the text say the tests passed?", criteria: { true: "It says the tests passed", false: "It doesn't" } } } });
+  return typeof answers.passed?.noul === "number";
+}
+
+async function cmdValidators() {
+  const [sub = "list", name] = argv.slice(1).filter((a) => !a.startsWith("--"));
+  if (sub === "list") {
+    let config = {};
+    try { config = loadValidators(); } catch (error) { if (json) return out({ error: error.message }); console.log(c.red(error.message)); process.exitCode = 1; return; }
+    const judge = config.judge ? { enabled: config.judge.enabled, agent: config.judge.agent, model: config.judge.model, checks: config.judge.checks, hostTools: config.judge.host_tools } : null;
+    const jev = config.jev ? { enabled: config.jev.enabled, checks: config.jev.checks, model: config.jev.model, key: config.jev.key_env ? `env ${config.jev.key_env}` : config.jev.key_file, keyReadable: Boolean(jevSettings()) } : null;
+    if (json) return out({ path: validatorsPath(), jev, judge });
+    if (!jev && !judge) { console.log("No validators configured. Add one with: nomarmy validators add jev, or nomarmy validators add judge --agent <name> --model <model>"); return; }
+    if (jev) console.log(`Jev: ${jev.enabled ? c.green("on") : "off"} (${jev.model}); checks: ${jev.checks.join(", ")}; key: ${jev.key}${jev.keyReadable ? "" : c.red(" (not readable)")}`);
+    if (judge) console.log(`Judge: ${judge.enabled ? c.green("on") : "off"} (${judge.agent}/${judge.model}); checks: ${judge.checks.join(", ")}${judge.hostTools ? c.yellow("; host tools allowed") : ""}`);
+    return;
+  }
+  if (name === "judge") return cmdValidatorsJudge(sub);
+  if (name !== "jev") throw new Error("Usage: nomarmy validators <list|add jev|test jev|remove jev|add judge|test judge|remove judge>");
+  if (sub === "add") {
+    if (!json) {
+      console.log(c.bold("🍪 Jev (TypeSafe) for nomArmy's semantic checks\n"));
+      console.log("It checks that a scout's cited lines support its finding, and that a worker's report matches its diff.");
+      console.log("Its answers only add review flags; they never pass a check or allow a commit.");
+      console.log(c.yellow("It sends excerpts of your code (findings, cited lines, diffs, worker reports) to TypeSafe.\n"));
+    }
+    const key = flag("key-stdin") ? await readStdin() : await readHiddenLine("TypeSafe API key (not shown): ");
+    const saved = saveJevKey(key);
+    let ok = false, why = null;
+    try { ok = await testJev(jevSettings()); } catch (error) { why = error.message; }
+    if (json) return out({ saved: true, keyFile: saved.keyFile, configPath: saved.configPath, test: ok ? "pass" : "fail", reason: why });
+    console.log(c.green(`✓ Saved the key to ${saved.keyFile} (readable only by you) and turned Jev on in ${saved.configPath}.`));
+    console.log(ok ? c.green("✓ Test call answered. New jobs use it; restart open coordinator sessions to pick it up.") : c.red(`✗ Test call failed: ${why ?? "no answer"}. Check the key, then: nomarmy validators test jev`));
+    if (!ok) process.exitCode = 1;
+    return;
+  }
+  if (sub === "test") {
+    const settings = jevSettings();
+    if (!settings) throw new Error("Jev isn't configured, or its key isn't readable. Add it with: nomarmy validators add jev");
+    let ok = false, why = null;
+    try { ok = await testJev(settings); } catch (error) { why = error.message; }
+    if (json) return out({ test: ok ? "pass" : "fail", reason: why });
+    console.log(ok ? c.green("✓ Jev answered.") : c.red(`✗ Jev test call failed: ${why ?? "no answer"}`));
+    if (!ok) process.exitCode = 1;
+    return;
+  }
+  if (sub === "remove") {
+    const result = removeJev();
+    if (json) return out(result);
+    console.log(c.green(`✓ Jev is off${result.removedKey ? ", and its saved key is deleted" : ""}.`));
+    return;
+  }
+  throw new Error("Usage: nomarmy validators <list|add jev|test jev|remove jev>");
+}
+
+async function cmdValidatorsJudge(sub) {
+  const agents = loadAgents(globalConfigDir()).agents;
+  const resolve = () => judgeSettings({ agents, providerOf: agentProviderId, runsOnHost: agentRunsToolsOnHost });
+  const probe = async (settings) => probeModel({ provider: settings.provider, model: settings.model, stateRoot: process.env.NOMARMY_AGENT_STATE || path.join(os.homedir(), ".local", "share", "nomarmy-local-agents") });
+  if (sub === "add") {
+    let agent = value("agent"), model = value("model"), dominantBuilderVendor = null;
+    let rl = null;
+    const question = async (prompt) => {
+      rl ??= createInterface({ input, output });
+      return rl.question(c.bold(prompt));
+    };
+    if (!agent) {
+      if (!process.stdin.isTTY || json) throw new Error("Usage: nomarmy validators add judge --agent <name> --model <model> [--host-tools]");
+      const roles = loadArmy({ projectDir: repoDir }).army.roles;
+      const guided = judgeAgentChoices({ agents, roles, providerOf: agentProviderId, runsOnHost: agentRunsToolsOnHost });
+      dominantBuilderVendor = guided.dominantBuilderVendor;
+      if (!guided.choices.length) throw new Error("No api or subscription agents are configured in agents.yml.");
+      agent = (await chooseJudgeAgent({ choices: guided.choices, ask: question, write: (line) => console.log(line) })).name;
+    }
+    if (!agents[agent]) throw new Error(`"${agent}" isn't an agent in agents.yml. Agents: ${Object.keys(agents).join(", ") || "(none)"}`);
+    if (!model) {
+      if (!process.stdin.isTTY || json) throw new Error("Usage: nomarmy validators add judge --agent <name> --model <model> [--host-tools]");
+      const listed = catalogModelsFor(agentProviderId(agents[agent]));
+      if (listed.length) {
+        console.log(`Models for ${agent}:`);
+        listed.forEach((item, index) => console.log(`  ${index + 1}. ${item}`));
+      }
+      const fallback = agents[agent].model ?? "";
+      const answer = String(await question(`Model id${fallback ? ` [${fallback}]` : ""}: `)).trim();
+      model = /^\d+$/.test(answer) && listed[Number(answer) - 1] ? listed[Number(answer) - 1] : answer || fallback;
+      if (!model) { rl?.close(); throw new Error("A model id is required."); }
+    }
+    let hostTools = flag("host-tools");
+    if (agentRunsToolsOnHost(agents[agent]) && !hostTools) {
+      if (!process.stdin.isTTY || json) {
+        const quote = (arg) => /^[A-Za-z0-9_./:-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+        const rerun = ["nomarmy", ...argv, "--host-tools"].map(quote).join(" ");
+        throw new Error(`agent "${agent}" runs its tools on this machine, and a judge reads text the worker wrote. Refusing without explicit consent. Re-run: ${rerun}`);
+      }
+      const allowed = await confirmJudgeHostTools({ agent, ask: question, write: (line) => console.log(line) });
+      if (!allowed) { rl?.close(); console.log(c.dim("Canceled; nothing written.")); return; }
+      hostTools = true;
+    }
+    rl?.close();
+    const saved = saveJudge({ agent, model, hostTools });
+    const settings = resolve();
+    if (settings?.problem) throw new Error(settings.problem);
+    const test = await probe(settings);
+    if (json) return out({ saved: true, configPath: saved.configPath, test: test.ok ? "pass" : test.refused ? "refused" : "inconclusive", reason: test.reason });
+    console.log(c.green(`✓ The judge is ${agent}/${model}, in ${saved.configPath}.`));
+    if (dominantBuilderVendor === null) {
+      try {
+        const roles = loadArmy({ projectDir: repoDir }).army.roles;
+        dominantBuilderVendor = judgeAgentChoices({ agents, roles, providerOf: agentProviderId, runsOnHost: agentRunsToolsOnHost }).dominantBuilderVendor;
+      } catch { /* no readable army means there is no builder comparison */ }
+    }
+    if (dominantBuilderVendor && agentProviderId(agents[agent]) === dominantBuilderVendor) console.log(c.yellow("Note: this judge uses the same vendor as most build roles, so its verdicts are not independent of those builders."));
+    console.log(test.ok ? c.green("✓ Test call answered. New implement jobs use it; restart open coordinator sessions to pick it up.") : c.red(`✗ Test call ${test.refused ? "refused" : "didn't answer"}: ${test.reason ?? "no answer"}`));
+    if (!test.ok) process.exitCode = 1;
+    return;
+  }
+  if (sub === "test") {
+    const settings = resolve();
+    if (!settings) throw new Error("No judge configured. Add one with: nomarmy validators add judge --agent <name> --model <model>");
+    if (settings.problem) throw new Error(settings.problem);
+    const test = await probe(settings);
+    if (json) return out({ test: test.ok ? "pass" : "fail", reason: test.reason });
+    console.log(test.ok ? c.green(`✓ ${settings.agent}/${settings.model} answered.`) : c.red(`✗ ${test.reason ?? "no answer"}`));
+    if (!test.ok) process.exitCode = 1;
+    return;
+  }
+  if (sub === "remove") {
+    removeJudge();
+    return json ? out({ removed: true }) : console.log(c.green("✓ The judge is off."));
+  }
+  throw new Error("Usage: nomarmy validators <add judge --agent <name> --model <model> [--host-tools]|test judge|remove judge>");
+}
+
+// `nomarmy mcp`: what a --scope project registration runs. Nothing goes to
+// stdout but the server's own protocol.
+function cmdMcp() {
+  const { serverPath, env } = portableServerLaunch({ nomarmyRoot });
+  const child = spawn(process.execPath, [serverPath], { stdio: "inherit", env });
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, () => child.kill(signal));
+  child.on("exit", (code, signal) => { if (signal) process.kill(process.pid, signal); else process.exit(code ?? 1); });
+}
+
+const commands = { stats: cmdStats, validators: cmdValidators, mcp: cmdMcp, scan: cmdScan, validate: cmdValidate, sizing: cmdSizing, init: cmdInit, setup: cmdSetup, install: cmdInstall, model: cmdModel, agents: cmdAgents, army: cmdArmy, jobs: cmdJobs, statusline: cmdStatusline, health: cmdHealth, config: cmdConfig, update: cmdUpdate, connect: cmdConnect, sandbox: cmdSandbox, start: cmdStart, stop: cmdStop, uninstall: cmdUninstall, help: () => usage(0) };
 // doctor command
 async function cmdDoctor() {
+  if (windowsFrontEnd()) {
+    process.exitCode = windowsDoctor({ json, argv });
+    return;
+  }
   // Import lazily to avoid circular dependencies
   const { runDoctor } = await import("../lib/doctor.mjs");
-  await runDoctor({ json, exit: true, env: installEnv() });
+  const agents = loadAgentsOrExit().agents;
+  const vendors = configuredSubscriptionVendors(agents);
+  let armySummary = null;
+  try { armySummary = describeArmy(loadArmy({ projectDir: repoDir }), { agents }); } catch { /* other doctor checks still run */ }
+  let checks;
+  if (flag("fix")) {
+    const repaired = await repairOpenclaw({
+      command: openclawCmd(), vendors, yes: flag("yes"), isTTY: Boolean(input.isTTY),
+      print: json ? console.error : console.log,
+      ask: async (prompt) => {
+        const rl = createInterface({ input, output: json ? process.stderr : output });
+        try { return await rl.question(prompt); } finally { rl.close(); }
+      },
+    });
+    checks = repaired.checks;
+    if (!repaired.ok && !checks.some((check) => !check.ok)) checks.push({ id: "openclaw-repair", ok: false, message: "OpenClaw repair was declined or failed.", fix: "nomarmy doctor --fix --yes" });
+  } else {
+    checks = verifyOpenclaw({ command: openclawCmd(), vendors });
+  }
+  await runDoctor({ json, exit: true, env: installEnv(), additionalChecks: checks,
+    runtime: { agents, armySummary, openclawCmd: openclawCmd() } });
 }
 commands.doctor = cmdDoctor;
-if (!command || flag("help") || !commands[command]) usage(command && !commands[command] ? 2 : 0);
+if (windowsFrontEnd() && windowsPlan(argv) === "FORWARD") {
+  process.exit(windowsForward(argv));
+}
+if (!command && !flag("help")) {
+  // New users typed `nomarmy` and got the whole command reference.
+  console.log(`${c.bold("nomArmy")}: bounded coding workers with independently verified results.\n\n  New here?   ${c.cyan("nomarmy setup")}   walks you through it, one step at a time\n  All commands: ${c.cyan("nomarmy help")}\n  Docs: https://github.com/rayson-tech/nomarmy`);
+  process.exit(0);
+}
+if (flag("help") || !commands[command]) usage(command && !commands[command] ? 2 : 0);
 
 try {
   await commands[command]();