nomarmy 0.1.0-alpha.17 → 0.1.0-alpha.19

package/README.md

@@ -4,6 +4,7 @@
   <a href="https://github.com/rayson-tech/nomarmy/actions/workflows/ci.yml"><img src="https://github.com/rayson-tech/nomarmy/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.npmjs.com/package/nomarmy"><img src="https://img.shields.io/npm/v/nomarmy/alpha?label=npm%40alpha" alt="npm"></a>
   <a href="https://github.com/rayson-tech/nomarmy/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0"></a>
+  <a href="https://github.com/rayson-tech/nomarmy/blob/main/docs/feature-runs.md"><img src="https://raw.githubusercontent.com/rayson-tech/nomarmy/main/.github/nomarmy-badge.svg" alt="nomArmy: AI worker claims checked on this repository"></a>
 </p>
 
 <p align="center"><em>Every byte verified.</em> 🍪</p>
@@ -15,6 +16,7 @@ AI coding workers are confident. Their "done, all tests pass" is a claim, not ev
 ## TL;DR
 
 1. **Have** Git, Node 24.16+ (or 26.1+) and [Podman](https://podman.io). On macOS, give Podman 8 GiB: `brew install podman && podman machine init --memory 8192 && podman machine start`.
+   Windows is supported with the engine in WSL2. Follow the [Windows setup](https://github.com/rayson-tech/nomarmy/blob/main/docs/install.md#windows).
 2. **Install and set up:**
    ```bash
    npm install -g nomarmy@alpha
@@ -50,6 +52,8 @@ Stuck? `nomarmy doctor` checks the machine and `nomarmy health` checks everythin
 
 Failing verification stays failed, unconditionally. A malformed report isn't automatically a failure: if the repository changed, nomArmy verifies independently and may recover the work. And the checks aren't the General's to waive: a repo's `.nomarmy.yml` policy (on by default for new repos) makes verification and the revert check mandatory for every job.
 
+**Showing what was checked.** When a `/feature` run finishes, the General gets a "Verified by nomArmy" block for the pull request: how many "done, tests pass" claims held up, how many nomArmy caught and why, and the new tests shown to fail without their change. `nomarmy stats --share` prints the same for any period, and `nomarmy stats --badge` writes a README badge like `nomArmy | 78 claims checked · 11 caught`. Every number comes from the verified records.
+
 **Checking without building** costs nothing: `mode: verify` runs a verification profile against any branch, with no worker and no model tokens.
 
 **Want deeper checks?** Three optional [validators](https://github.com/rayson-tech/nomarmy/blob/main/docs/validators.md) go further, each only adding review flags: mutation testing (do the tests pin down the changed lines?), Jev (do a scout's citations support its findings, does a report match its diff?) and a model judge (acceptance criteria, weakened tests).
@@ -71,7 +75,7 @@ Developed and maintained by Rayson Technologies. This is an alpha (`0.1.0-alpha`
 
 | | |
 |---|---|
-| [Install](https://github.com/rayson-tech/nomarmy/blob/main/docs/install.md) | Every setup: hosted (API keys and subscriptions), a local model on macOS, Linux, Windows or DGX Spark, a shared model server, Bedrock |
+| [Install](https://github.com/rayson-tech/nomarmy/blob/main/docs/install.md) | Every setup: hosted (API keys and subscriptions), a local model on macOS, Linux, [Windows with the engine in WSL2](https://github.com/rayson-tech/nomarmy/blob/main/docs/install.md#windows) or DGX Spark, a shared model server, Bedrock |
 | [Example setup](https://github.com/rayson-tech/nomarmy/blob/main/docs/setup/example.md) | Claude Code, Codex and an API key, command by command |
 | [Agents and the army](https://github.com/rayson-tech/nomarmy/blob/main/docs/agents-and-army.md) | Where a job can run, who does what, usage limits, picking an agent |
 | [`/feature` runs](https://github.com/rayson-tech/nomarmy/blob/main/docs/feature-runs.md) | A feature end to end, and watching what nomArmy is doing |

package/bin/nomarmy.mjs

@@ -18,11 +18,13 @@ 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, defaultInstallDir, installMcpCopy, SCOPES, claudeUserScoped, portableServerLaunch } 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 } from "../lib/validators.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, agentProviderId, AGENT_KINDS, API_PROVIDER_TYPES, RESERVED_AGENT_NAMES, BUILTIN_LOCAL_AGENT } from "../lib/agents.mjs";
@@ -32,12 +34,30 @@ import { setupSteps, formatSetupSteps, runSetupPlaybook } from "../lib/setup-ste
 import { readUsageSnapshots } 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 { pruneJobRuntime } from "../lib/prune.mjs";
 import { SUBSCRIPTION_VENDORS, parseOpenclawVersion, versionAtLeast, parseCatalogModels, parseCliLoginStatus, probeOutcome, parseMuseAuthDescriptor, extractMintedKey } from "../lib/subscription-setup.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
@@ -67,7 +87,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;
@@ -155,7 +175,7 @@ Usage: nomarmy <command> [options]
                             [--update-mcp] (api); --provider --model
                             --owner (subscription); and 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),
@@ -239,7 +259,7 @@ Usage: nomarmy <command> [options]
                   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>] [--details] [--all-suggestions]
+  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,
@@ -248,7 +268,9 @@ Usage: nomarmy <command> [options]
                   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. Today: Jev (TypeSafe). \`add jev\` asks for the
+                  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
@@ -459,7 +481,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) {
@@ -468,15 +492,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
@@ -495,6 +513,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();
@@ -527,15 +553,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,
   },
 };
@@ -588,14 +614,14 @@ function defaultLocalProfile() {
 // `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 = path.join(nomarmyRoot, "config", "common.env");
-  const chosen = readEnvValue(common, "NOMARMY_SETUP_PROFILE");
+  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 = chosen ? path.join(nomarmyRoot, "config", "profiles", `${chosen}.env`) : null;
-  const root = (process.env.NOMARMY_INSTALL_ROOT || (profileFile && readEnvValue(profileFile, "NOMARMY_INSTALL_ROOT")) || readEnvValue(common, "NOMARMY_INSTALL_ROOT") || "$HOME/.local/share/nomarmy-local-agents").replace(/\$HOME|\$\{HOME\}/g, os.homedir());
+  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"]);
@@ -603,7 +629,7 @@ function setupProfileState() {
   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 = readEnvValue(common, "NOMARMY_EXECUTION");
+  const execution = setting("NOMARMY_EXECUTION");
   const profile = chosen ?? marker?.profile
     ?? (["hosted", "remote", "bedrock"].includes(execution) ? execution : null)
     ?? (registered ? defaultLocalProfile() : null);
@@ -614,7 +640,7 @@ function setupChecklist() {
   const { common, profile, marker, version, registered } = setupProfileState();
   const project = setupProjectDir();
   return setupSteps({
-    mode: () => ({ profile, host: readEnvValue(common, "NOMARMY_LLAMA_HOST"), port: readEnvValue(common, "NOMARMY_LLAMA_PORT") }),
+    mode: () => ({ profile, host: setting("NOMARMY_LLAMA_HOST"), port: setting("NOMARMY_LLAMA_PORT") }),
     install: () => ({ marker, version, registered }),
     agents: () => Object.keys(loadAgents(globalConfigDir()).agents),
     army: () => {
@@ -647,11 +673,27 @@ function cmdInstall() {
 }
 
 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) => {
@@ -670,10 +712,8 @@ async function cmdSetup() {
       if (choice === "1") argv.push("--hosted");
       if (choice === "3") argv.push("--llama-url", (await rl.question("Server URL: ")).trim());
       if (choice === "4") {
-        const common = path.join(nomarmyRoot, "config", "common.env");
-        fs.mkdirSync(path.dirname(common), { recursive: true });
-        writeEnvLine(common, "NOMARMY_EXECUTION", "bedrock");
-        writeEnvLine(common, "NOMARMY_SETUP_PROFILE", "bedrock");
+        writeSetting("NOMARMY_EXECUTION", "bedrock");
+        writeSetting("NOMARMY_SETUP_PROFILE", "bedrock");
         console.log("Next: nomarmy install");
         return;
       }
@@ -684,7 +724,7 @@ async function cmdSetup() {
   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 = [
@@ -692,11 +732,10 @@ async function cmdSetup() {
         "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;
@@ -724,7 +763,7 @@ async function cmdSetup() {
     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;
@@ -753,10 +792,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
@@ -774,8 +813,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";
       }
@@ -794,8 +833,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) {
@@ -808,10 +847,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}`));
@@ -819,8 +858,9 @@ 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; }
       }
     }
 
@@ -842,7 +882,7 @@ 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));
@@ -851,7 +891,7 @@ async function cmdSetup() {
 
     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 {
@@ -880,7 +920,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).`);
@@ -904,17 +944,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) {
@@ -1371,8 +1411,7 @@ async function cmdAgentsAdd() {
       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);
@@ -1409,8 +1448,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 };
 
@@ -1485,8 +1523,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];
 
@@ -1860,6 +1897,9 @@ async function cmdConnect() {
   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(); }
@@ -1894,6 +1934,17 @@ async function cmdConnect() {
     }
     try {
       if (!json) console.log(c.bold(`\n🍪 Connecting nomArmy to ${target}...`));
+      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}${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.`}`));
@@ -2045,7 +2096,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] : [];
 }
 
@@ -2757,6 +2808,25 @@ async function cmdStatusline() {
   process.stdout.write(`${statusLineText({ session })}\n`);
 }
 
+// `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"));
@@ -2768,8 +2838,9 @@ function cmdStats() {
   }
   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"), agentFor, allSuggestions: flag("all-suggestions") });
+  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 }));
 }
 
@@ -2857,16 +2928,58 @@ async function cmdValidatorsJudge(sub) {
   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") {
-    const agent = value("agent"), model = value("model");
-    if (!agent || !model) throw new Error("Usage: nomarmy validators add judge --agent <name> --model <model> [--host-tools]");
+    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 (agentRunsToolsOnHost(agents[agent]) && !flag("host-tools")) throw new Error(`agent "${agent}" runs its tools on this machine, and a judge reads text the worker wrote. Pass --host-tools to accept that, or pick a sandboxed agent (an api key, Codex, Muse).`);
-    const saved = saveJudge({ agent, model, hostTools: flag("host-tools") });
+    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;
@@ -2900,12 +3013,24 @@ function cmdMcp() {
 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() });
 }
 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]();

package/docker/Dockerfile

@@ -1,9 +1,9 @@
-FROM node:24-bookworm-slim
+FROM node:26-bookworm-slim
 ENV DEBIAN_FRONTEND=noninteractive
 RUN apt-get update && apt-get install -y --no-install-recommends \
     bash ca-certificates curl git jq python3 python3-pip python3-venv ripgrep \
     && rm -rf /var/lib/apt/lists/*
-# node:24-bookworm-slim already ships a non-root "node" user at uid/gid 1000,
+# The node:*-bookworm-slim images ship a non-root "node" user at uid/gid 1000,
 # the same uid this Dockerfile used to try to create a "sandbox" user at.
 # useradd silently failed on every build (masked by `|| true`), so `USER
 # sandbox` below referred to a user that was never actually created --

package/docker/Dockerfile.go

@@ -1,4 +1,4 @@
-FROM node:24-bookworm-slim
+FROM node:26-bookworm-slim
 ENV DEBIAN_FRONTEND=noninteractive
 # Same base as docker/Dockerfile plus a Go toolchain -- the worker's own
 # tool-calling harness needs Node regardless of the target repo's language.

package/docker/Dockerfile.rust

@@ -1,4 +1,4 @@
-FROM node:24-bookworm-slim
+FROM node:26-bookworm-slim
 ENV DEBIAN_FRONTEND=noninteractive
 # Same base as docker/Dockerfile plus a Rust toolchain -- the worker's own
 # tool-calling harness needs Node regardless of the target repo's language.