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

package/lib/connect.mjs

@@ -24,10 +24,15 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { mcpBridgeLaunch } from "./wsl.mjs";
+import { toPosix } from "./path-utils.mjs";
 import { execFileSync } from "node:child_process";
 import { loadAgents } from "./agents.mjs";
 import { globalConfigDir } from "./army.mjs";
 import { buildNotifierApp } from "./notifier-app.mjs";
+import { recordCopySource } from "./install-freshness.mjs";
+import { readSettings, migrateUserConfig } from "./user-config.mjs";
 
 export function defaultInstallDir() {
   return process.env.NOMARMY_AGENT_INSTALL_DIR || path.join(process.env.HOME ?? process.env.USERPROFILE ?? ".", ".local", "share", "nomarmy-local-worker");
@@ -45,8 +50,10 @@ export function defaultInstallDir() {
 // `<!-- nomarmy:... -->` marker; a same-named file WITHOUT it is the
 // operator's own and is never overwritten, only reported as skipped.
 //   Claude Code  ~/.claude/commands/feature.md          -> /feature <request>
-//   Codex        ~/.codex/skills/nomarmy-feature/SKILL.md (confirmed from
-//                codex 0.156's own $CODEX_HOME/skills loader)
+//   Codex        ~/.agents/skills/nomarmy-feature/SKILL.md (where the Codex
+//                CLI, desktop app and IDE extension all look for user
+//                skills; older nomArmy put it in $CODEX_HOME/skills, which
+//                connectCodex cleans up)
 //   Cursor       ~/.cursor/commands/feature.md (Cursor's documented
 //                user-level commands directory; not verified against a
 //                real install here)
@@ -63,7 +70,7 @@ export function defaultCommandDirs(env = process.env) {
   const home = os.homedir();
   return {
     claude: env.NOMARMY_CLAUDE_COMMANDS_DIR ? path.resolve(env.NOMARMY_CLAUDE_COMMANDS_DIR) : path.join(home, ".claude", "commands"),
-    codex: env.NOMARMY_CODEX_SKILLS_DIR ? path.resolve(env.NOMARMY_CODEX_SKILLS_DIR) : path.join(env.CODEX_HOME || path.join(home, ".codex"), "skills"),
+    codex: env.NOMARMY_CODEX_SKILLS_DIR ? path.resolve(env.NOMARMY_CODEX_SKILLS_DIR) : path.join(home, ".agents", "skills"),
     cursor: env.NOMARMY_CURSOR_COMMANDS_DIR ? path.resolve(env.NOMARMY_CURSOR_COMMANDS_DIR) : path.join(home, ".cursor", "commands"),
   };
 }
@@ -137,9 +144,13 @@ export function installClaudeStatusLine({ installDir, settingsPath = defaultClau
 }
 
 export function installMcpCopy({ nomarmyRoot, installDir, run = defaultRun }) {
+  // Settings from before they moved to ~/.config/nomarmy/ survive in the old
+  // copy's config/ until this call replaces it: rescue them first.
+  try { migrateUserConfig({ oldConfigDir: path.join(installDir, "config"), nomarmyRoot }); } catch { /* never block a connect */ }
   fs.mkdirSync(path.join(installDir, "mcp"), { recursive: true });
   fs.copyFileSync(path.join(nomarmyRoot, "package.json"), path.join(installDir, "package.json"));
   fs.copyFileSync(path.join(nomarmyRoot, "mcp", "server.mjs"), path.join(installDir, "mcp", "server.mjs"));
+  recordCopySource(installDir, nomarmyRoot);
   fs.rmSync(path.join(installDir, "lib"), { recursive: true, force: true });
   fs.cpSync(path.join(nomarmyRoot, "lib"), path.join(installDir, "lib"), { recursive: true });
   // lib/sandbox-images.mjs resolves docker/ relative to its own location
@@ -167,6 +178,14 @@ export function installMcpCopy({ nomarmyRoot, installDir, run = defaultRun }) {
     fs.rmSync(path.join(installDir, "config"), { recursive: true, force: true });
     fs.cpSync(configSrc, path.join(installDir, "config"), { recursive: true });
   }
+  // lib/harnesses.mjs finds its definitions at ../harnesses/, so the copy
+  // needs them too: without this, every connected session matched no
+  // harness and built its jobs in the plain base image, silently.
+  const harnessSrc = path.join(nomarmyRoot, "harnesses");
+  if (fs.existsSync(harnessSrc)) {
+    fs.rmSync(path.join(installDir, "harnesses"), { recursive: true, force: true });
+    fs.cpSync(harnessSrc, path.join(installDir, "harnesses"), { recursive: true });
+  }
   run("npm", ["install", "--omit=dev"], { cwd: installDir });
   run(process.execPath, ["--check", "mcp/server.mjs"], { cwd: installDir });
 }
@@ -234,21 +253,65 @@ function readEnvValue(filePath, key) {
  * such keys yet just contributes nothing here, unchanged from before.
  */
 export function deriveWorkerModelEnv(nomarmyRoot) {
-  const commonPath = path.join(nomarmyRoot, "config", "common.env");
-  const model = readEnvValue(commonPath, "NOMARMY_WORKER_MODEL");
-  const thinking = readEnvValue(commonPath, "NOMARMY_MODEL_THINKING");
+  // Your settings over the package defaults (lib/user-config.mjs).
+  const settings = readSettings({ nomarmyRoot });
   const env = {};
-  if (model) env.NOMARMY_WORKER_MODEL = model;
-  if (thinking !== null) env.NOMARMY_WORKER_MODEL_THINKING = thinking;
+  if (settings.NOMARMY_WORKER_MODEL) env.NOMARMY_WORKER_MODEL = settings.NOMARMY_WORKER_MODEL;
+  if (settings.NOMARMY_MODEL_THINKING !== undefined) env.NOMARMY_WORKER_MODEL_THINKING = settings.NOMARMY_MODEL_THINKING;
   for (const key of ["NOMARMY_EXECUTION", "NOMARMY_LLAMA_HOST", "NOMARMY_LLAMA_PORT"]) {
-    const value = readEnvValue(commonPath, key);
-    if (value !== null) env[key] = value;
+    if (settings[key] !== undefined) env[key] = settings[key];
   }
   return env;
 }
 
 const SERVER_NAME = "nomarmy-local-worker";
 
+/**
+ * Where a coordinator registers nomArmy. user: every project (the default).
+ * local: this repository, only you. project: this repository, committed for
+ * the team. A committed registration can't carry one machine's install path
+ * or settings, so it runs `nomarmy mcp`, which starts nomArmy with each
+ * person's own.
+ */
+export const SCOPES = Object.freeze(["user", "local", "project"]);
+export const PORTABLE_SERVER = Object.freeze({ command: "nomarmy", args: ["mcp"] });
+
+/** Keep repo-local files out of git without touching the committed .gitignore. */
+export function excludeFromGit(projectDir, relPaths, run = defaultRun) {
+  let excludeFile;
+  try { excludeFile = String(run("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: projectDir, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" })).trim(); } catch { return []; }
+  if (!excludeFile) return [];
+  excludeFile = path.resolve(projectDir, excludeFile);
+  const existing = fs.existsSync(excludeFile) ? fs.readFileSync(excludeFile, "utf8") : "";
+  const lines = new Set(existing.split("\n").map((l) => l.trim()));
+  // Git exclude patterns always use forward slashes, including on Windows.
+  const added = relPaths.map((p) => `/${toPosix(p)}`).filter((p) => !lines.has(p));
+  if (added.length) {
+    fs.mkdirSync(path.dirname(excludeFile), { recursive: true });
+    fs.appendFileSync(excludeFile, `${existing && !existing.endsWith("\n") ? "\n" : ""}# nomArmy, registered for this repository only\n${added.join("\n")}\n`);
+  }
+  return added;
+}
+
+/** Undo excludeFromGit for these paths: a project registration is meant to be committed. */
+export function includeInGit(projectDir, relPaths, run = defaultRun) {
+  let excludeFile;
+  try { excludeFile = path.resolve(projectDir, String(run("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: projectDir, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" })).trim()); } catch { return []; }
+  if (!fs.existsSync(excludeFile)) return [];
+  // Match the same portable spelling written by excludeFromGit on Windows.
+  const drop = new Set(relPaths.map((p) => `/${toPosix(p)}`));
+  const lines = fs.readFileSync(excludeFile, "utf8").split("\n");
+  const removed = lines.filter((l) => drop.has(l.trim()));
+  if (removed.length) fs.writeFileSync(excludeFile, lines.filter((l) => !drop.has(l.trim())).join("\n"));
+  return removed.map((l) => l.trim());
+}
+
+function repoScoped(scope, projectDir) {
+  if (!SCOPES.includes(scope)) throw new Error(`unknown scope "${scope}"; use one of ${SCOPES.join(", ")}`);
+  if (scope !== "user" && !projectDir) throw new Error(`--scope ${scope} registers nomArmy for one repository; run it inside that repository`);
+  return scope !== "user";
+}
+
 /**
  * Every distinct auth_env name declared across config/providers.yml's
  * pools, mapped to a placeholder value -- NEVER the real credential, which
@@ -290,7 +353,8 @@ export function derivePoolAuthEnvPlaceholders(configDir = globalConfigDir()) {
 /**
  * @param {{ nomarmyRoot: string, installDir?: string, run?: Function, extraEnv?: Record<string,string>, configDir?: string }} input
  */
-export function connectClaude({ nomarmyRoot, installDir = defaultInstallDir(), run = defaultRun, extraEnv = {}, configDir = globalConfigDir(), commandsDir = defaultCommandDirs().claude, settingsPath = defaultClaudeSettingsPath() }) {
+export function connectClaude({ nomarmyRoot, installDir = defaultInstallDir(), run = defaultRun, extraEnv = {}, configDir = globalConfigDir(), commandsDir = defaultCommandDirs().claude, settingsPath = defaultClaudeSettingsPath(), scope = "user", projectDir = null }) {
+  if (repoScoped(scope, projectDir)) return connectClaudeToRepo({ nomarmyRoot, installDir, run, extraEnv, configDir, scope, projectDir });
   installMcpCopy({ nomarmyRoot, installDir, run });
   const commands = installPlaybooks({ nomarmyRoot, target: "claude", dir: commandsDir });
   const notifier = buildNotifierApp({ nomarmyRoot });
@@ -328,21 +392,129 @@ export function connectClaude({ nomarmyRoot, installDir = defaultInstallDir(), r
     run("claude", ["mcp", "add", SERVER_NAME, ...envArgs, "--", "node", serverPath]);
   }
   run("claude", ["mcp", "get", SERVER_NAME]);
-  return { installDir, serverPath, preservedEnv: finalEnv, commands, statusLine, notifier };
+  return { installDir, serverPath, preservedEnv: finalEnv, commands, statusLine, notifier, scope: "user" };
+}
+
+// Claude Code's local scope (this repo, only you) or project scope (.mcp.json,
+// committed). The /feature playbook goes in the repo's .claude/commands, so it
+// shows up only where nomArmy is registered; no status line, which is a
+// user-wide setting.
+function connectClaudeToRepo({ nomarmyRoot, installDir, run, extraEnv, configDir, scope, projectDir }) {
+  installMcpCopy({ nomarmyRoot, installDir, run });
+  const commands = installPlaybooks({ nomarmyRoot, target: "claude", dir: path.join(projectDir, ".claude", "commands") });
+  const playbookPaths = commands.installed.map((f) => path.relative(projectDir, path.join(commands.dir, f)));
+  const excluded = scope === "local" ? excludeFromGit(projectDir, playbookPaths, run) : [];
+  if (scope === "project") includeInGit(projectDir, playbookPaths, run);
+  const serverPath = path.join(installDir, "mcp", "server.mjs");
+  const opts = { cwd: projectDir };
+  quietRun(run, "claude", ["mcp", "remove", SERVER_NAME, "--scope", scope], opts);
+  let env = {};
+  if (scope === "local") {
+    env = { ...derivePoolAuthEnvPlaceholders(configDir), ...extraEnv, ...deriveWorkerModelEnv(nomarmyRoot) };
+    const envArgs = Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+    run("claude", ["mcp", "add", "--scope", "local", SERVER_NAME, ...envArgs, "--", "node", serverPath], opts);
+  } else {
+    run("claude", ["mcp", "add", "--scope", "project", SERVER_NAME, "--", PORTABLE_SERVER.command, ...PORTABLE_SERVER.args], opts);
+  }
+  run("claude", ["mcp", "get", SERVER_NAME], opts);
+  return { installDir, serverPath: scope === "local" ? serverPath : null, preservedEnv: env, commands, excluded, scope, projectDir,
+    configPath: scope === "project" ? path.join(projectDir, ".mcp.json") : null, userScoped: claudeUserScoped(run) };
+}
+
+/**
+ * What `nomarmy mcp` runs: the installed copy when there is one (the code
+ * `nomarmy update` keeps current), else this package's own server, with the
+ * env connect would register (worker model, api-key placeholders) under
+ * whatever the caller already set.
+ */
+export function portableServerLaunch({ nomarmyRoot, installDir = defaultInstallDir(), configDir = globalConfigDir(), env = process.env }) {
+  const installed = path.join(installDir, "mcp", "server.mjs");
+  const serverPath = fs.existsSync(installed) ? installed : path.join(nomarmyRoot, "mcp", "server.mjs");
+  return { serverPath, env: { ...derivePoolAuthEnvPlaceholders(configDir), ...deriveWorkerModelEnv(nomarmyRoot), ...env } };
+}
+
+/** The on-disk server scripts registered by connect for this repository. */
+export async function registeredMcpCopies({ projectDir = null, installDir = defaultInstallDir(), nomarmyRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."), cursorConfigPath = defaultCursorConfigPath(), homeDir = os.homedir(), run }) {
+  const copies = [];
+  const add = (target, scope, command, args = []) => {
+    let serverPath = null;
+    if (command === "node" && typeof args[0] === "string") serverPath = path.resolve(args[0]);
+    else if (command === PORTABLE_SERVER.command && args[0] === PORTABLE_SERVER.args[0]) {
+      serverPath = portableServerLaunch({ nomarmyRoot, installDir }).serverPath;
+    }
+    if (serverPath && path.basename(serverPath) === "server.mjs" && path.basename(path.dirname(serverPath)) === "mcp") copies.push({ target, scope, serverPath });
+  };
+  const output = async (cmd, args, cwd) => {
+    try {
+      const result = await run(cmd, args, { cwd, timeoutMs: 5000 });
+      return result?.ok ? result.stdout : null;
+    } catch { return null; }
+  };
+  const claude = (value) => {
+    if (!value || !value.includes(`${SERVER_NAME}:`)) return;
+    const scope = /^\s*Scope:\s*(User|Local|Project)\b/im.exec(value)?.[1]?.toLowerCase();
+    const command = /^\s*Command:\s*(\S+)\s*$/im.exec(value)?.[1];
+    const args = /^\s*Args:\s*(.*?)\s*$/im.exec(value)?.[1];
+    if (scope && command) add("claude", scope, command, args ? [args] : []);
+  };
+  claude(await output("claude", ["mcp", "get", SERVER_NAME], projectDir || undefined));
+  if (projectDir) claude(await output("claude", ["mcp", "get", SERVER_NAME], homeDir));
+  const codex = await output("codex", ["mcp", "get", SERVER_NAME, "--json"]);
+  if (codex) {
+    try {
+      const transport = JSON.parse(codex).transport;
+      if (transport) add("codex", "user", transport.command, transport.args);
+    } catch { /* no registration */ }
+  }
+  for (const [scope, configPath] of [["user", cursorConfigPath], ...(projectDir ? [["local", path.join(projectDir, ".cursor", "mcp.json")]] : [])]) {
+    try {
+      const entry = readCursorConfig(configPath).mcpServers?.[SERVER_NAME];
+      if (entry) add("cursor", scope === "local" && entry.command === PORTABLE_SERVER.command ? "project" : scope, entry.command, entry.args);
+    } catch { /* unreadable registration */ }
+  }
+  return [...new Map(copies.map((copy) => [`${copy.target}:${copy.scope}:${copy.serverPath}`, copy])).values()];
+}
+
+/** Whether Claude Code also has nomArmy registered for every project. */
+export function claudeUserScoped(run = defaultRun) {
+  try {
+    const out = String(run("claude", ["mcp", "get", SERVER_NAME], { cwd: os.homedir(), stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" }));
+    return /Scope:\s*User/i.test(out);
+  } catch { return false; }
 }
 
 /**
  * @param {{ nomarmyRoot: string, installDir?: string, run?: Function }} input
  */
-export function connectCodex({ nomarmyRoot, installDir = defaultInstallDir(), run = defaultRun, skillsDir = defaultCommandDirs().codex }) {
+export function connectCodex({ nomarmyRoot, installDir = defaultInstallDir(), run = defaultRun, configDir = globalConfigDir(), skillsDir = defaultCommandDirs().codex, legacySkillsDir = path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "skills"), scope = "user" }) {
+  // `codex mcp add` has no scope: Codex registers MCP servers only in
+  // ~/.codex/config.toml, for every project.
+  if (scope !== "user") throw new Error(`Codex registers MCP servers only for every project (~/.codex/config.toml), so --scope ${scope} isn't available for it; connect Codex without --scope, or use Claude Code or Cursor for a per-repo registration`);
   installMcpCopy({ nomarmyRoot, installDir, run });
   const commands = installPlaybooks({ nomarmyRoot, target: "codex", dir: skillsDir });
+  removeLegacyCodexSkill(legacySkillsDir, skillsDir);
   const notifier = buildNotifierApp({ nomarmyRoot });
+  // The same environment Claude's registration gets (connectClaude): the
+  // install's execution mode and worker model always win, anything else an
+  // operator set on the old registration is kept.
+  let preservedEnv = {};
+  try { preservedEnv = JSON.parse(run("codex", ["mcp", "get", SERVER_NAME, "--json"], { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" }))?.transport?.env ?? {}; } catch { /* not registered yet */ }
+  const finalEnv = { ...derivePoolAuthEnvPlaceholders(configDir), ...preservedEnv, ...deriveWorkerModelEnv(nomarmyRoot) };
   quietRun(run, "codex", ["mcp", "remove", SERVER_NAME]);
   const serverPath = path.join(installDir, "mcp", "server.mjs");
-  run("codex", ["mcp", "add", SERVER_NAME, "--", "node", serverPath]);
+  const envArgs = Object.entries(finalEnv).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+  run("codex", ["mcp", "add", SERVER_NAME, ...envArgs, "--", "node", serverPath]);
   run("codex", ["mcp", "list"]);
-  return { installDir, serverPath, commands, notifier };
+  return { installDir, serverPath, preservedEnv: finalEnv, commands, notifier };
+}
+
+/** Remove the skill older nomArmy installed under $CODEX_HOME/skills (only nomArmy's own copy, by its marker). */
+function removeLegacyCodexSkill(legacyDir, currentDir) {
+  const file = path.join(legacyDir, "nomarmy-feature", "SKILL.md");
+  if (path.resolve(legacyDir) === path.resolve(currentDir)) return;
+  try {
+    if (fs.readFileSync(file, "utf8").includes(COMMAND_MARKER)) fs.rmSync(path.dirname(file), { recursive: true, force: true });
+  } catch { /* nothing there */ }
 }
 
 export function defaultCursorConfigPath() {
@@ -381,7 +553,13 @@ export function readCursorConfig(configPath) {
 /**
  * @param {{ nomarmyRoot: string, installDir?: string, configPath?: string }} input
  */
-export function connectCursor({ nomarmyRoot, installDir = defaultInstallDir(), configPath = defaultCursorConfigPath(), run = defaultRun, commandsDir = defaultCommandDirs().cursor }) {
+export function connectCursor({ nomarmyRoot, installDir = defaultInstallDir(), configPath = defaultCursorConfigPath(), run = defaultRun, configDir = globalConfigDir(), commandsDir = defaultCommandDirs().cursor, scope = "user", projectDir = null }) {
+  // Cursor reads a project's own .cursor/mcp.json beside the user one. local
+  // keeps it out of git; project commits it, with the portable command.
+  if (repoScoped(scope, projectDir)) {
+    configPath = path.join(projectDir, ".cursor", "mcp.json");
+    commandsDir = path.join(projectDir, ".cursor", "commands");
+  }
   installMcpCopy({ nomarmyRoot, installDir, run });
   const commands = installPlaybooks({ nomarmyRoot, target: "cursor", dir: commandsDir });
   const notifier = buildNotifierApp({ nomarmyRoot });
@@ -392,12 +570,21 @@ export function connectCursor({ nomarmyRoot, installDir = defaultInstallDir(), c
   // connectClaude's captureExistingEnv guards against: silently dropping an
   // operator-set NOMARMY_WORKER_MODEL on every reinstall) -- every OTHER
   // configured server in the file is left completely untouched.
+  // As for Claude and Codex, the install's own settings (execution mode,
+  // worker model, api-key placeholders) win over whatever the entry had.
   const existing = config.mcpServers[SERVER_NAME];
-  const preservedEnv = (existing && typeof existing.env === "object" && existing.env) || {};
-  config.mcpServers[SERVER_NAME] = { command: "node", args: [serverPath], env: preservedEnv };
+  // Cursor starts a global MCP server in the home folder, not the open
+  // project; ${workspaceFolder} is Cursor's own placeholder for the latter.
+  const preservedEnv = { ...derivePoolAuthEnvPlaceholders(configDir), ...((existing && typeof existing.env === "object" && existing.env) || {}), ...deriveWorkerModelEnv(nomarmyRoot), NOMARMY_PROJECT_DIR: "${workspaceFolder}" };
+  config.mcpServers[SERVER_NAME] = scope === "project"
+    ? { command: PORTABLE_SERVER.command, args: [...PORTABLE_SERVER.args], env: { NOMARMY_PROJECT_DIR: "${workspaceFolder}" } }
+    : { command: "node", args: [serverPath], env: preservedEnv };
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-  return { installDir, serverPath, configPath, preservedEnv, commands, notifier };
+  const repoPaths = scope === "user" ? [] : [path.relative(projectDir, configPath), ...commands.installed.map((f) => path.relative(projectDir, path.join(commands.dir, f)))];
+  const excluded = scope === "local" ? excludeFromGit(projectDir, repoPaths, run) : [];
+  if (scope === "project") includeInGit(projectDir, repoPaths, run);
+  return { installDir, serverPath, configPath, preservedEnv: scope === "project" ? config.mcpServers[SERVER_NAME].env : preservedEnv, commands, notifier, scope, excluded };
 }
 
 /** True when Cursor's config file already has a nomArmy entry -- used by
@@ -411,3 +598,29 @@ export function cursorAlreadyConnected(configPath = defaultCursorConfigPath()) {
     return false;
   }
 }
+
+
+// Windows installs only coordinator playbooks. The engine stays in WSL.
+export function connectViaWsl({ target, distro, launch, run = defaultRun, commandsDir = defaultCommandDirs()[target], configPath = defaultCursorConfigPath(), nomarmyRoot }) {
+  if (!["claude", "codex", "cursor"].includes(target)) throw new Error(`unknown connect target: ${target}`);
+  // Revalidate the direct launch before passing any values to a coordinator.
+  const checked = mcpBridgeLaunch({ distro, node: launch?.args?.[3], script: launch?.args?.[4] });
+  if (JSON.stringify(launch) !== JSON.stringify(checked)) throw new Error("Invalid WSL MCP bridge launch");
+  const { command, args } = checked;
+  const env = { ...checked.env, WSLENV: `${checked.env.WSLENV}:NOMARMY_COORDINATOR_OS/u`, NOMARMY_COORDINATOR_OS: "windows" };
+  if (target === "claude") {
+    quietRun(run, "claude", ["mcp", "remove", SERVER_NAME, "--scope", "user"]);
+    run("claude", ["mcp", "add", "--scope", "user", SERVER_NAME, "-e", `WSLENV=${env.WSLENV}`, "-e", `NOMARMY_COORDINATOR_OS=${env.NOMARMY_COORDINATOR_OS}`, "--", command, ...args]);
+  } else if (target === "codex") {
+    quietRun(run, "codex", ["mcp", "remove", SERVER_NAME]);
+    run("codex", ["mcp", "add", SERVER_NAME, "--env", `WSLENV=${env.WSLENV}`, "--env", `NOMARMY_COORDINATOR_OS=${env.NOMARMY_COORDINATOR_OS}`, "--", command, ...args]);
+  } else {
+    const config = readCursorConfig(configPath);
+    if (!config.mcpServers || typeof config.mcpServers !== "object" || Array.isArray(config.mcpServers)) config.mcpServers = {};
+    config.mcpServers[SERVER_NAME] = { command, args, env: { ...env, NOMARMY_PROJECT_DIR: "${workspaceFolder}" } };
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  }
+  const commands = installPlaybooks({ nomarmyRoot, target, dir: commandsDir });
+  return { target, bridge: { distro }, commands };
+}

package/lib/continue-from.mjs

@@ -0,0 +1,103 @@
+// continue_from: a corrective job that starts from a retained job's
+// unfinished work, so the finished whole goes through nomArmy's checks.
+//
+// From a real run: a builder's code was right but came back partial (one
+// expected value in its own test was wrong). nomArmy never commits partial
+// work, and a new job from the branch couldn't see the uncommitted changes, so
+// the General fixed the number by hand and committed the foundation itself,
+// outside verification. Now the General dispatches the correction with
+// continue_from: the new worktree starts with the old job's changes, and the
+// new job's diff, verification and revert check cover all of it.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isRuntimeJunk } from "./git-record.mjs";
+
+const JOB_ID_RE = /^[A-Za-z0-9._-]{1,120}$/;
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
+}
+
+/**
+ * Why `continueFrom` can't be continued, or null with the retained job's
+ * record. Checked at admission, before anything starts.
+ * @returns {{ problem: string|null, record: object|null }}
+ */
+export function continuationProblem({ continueFrom, mode = "implement", baseRef = null, jobsRoot, projectDir, isRunning = () => false }) {
+  const refuse = (problem) => ({ problem: `continue_from "${continueFrom}": ${problem}`, record: null });
+  if (!JOB_ID_RE.test(String(continueFrom ?? ""))) return refuse("not a job id");
+  if (mode !== "implement") return refuse("only an implement job can continue another job's work");
+  if (baseRef) return refuse("starts from that job's own base commit; leave base_ref out");
+  if (isRunning(continueFrom)) return refuse("that job is still running; wait for it to finish");
+  const jobDir = path.join(jobsRoot, continueFrom);
+  const record = readJson(path.join(jobDir, "metadata.json"));
+  if (!record) return refuse("no finished job by that id (see local_worker_jobs)");
+  if (record.mode !== "implement") return refuse(`that job is a ${record.mode} job; only implement work can be continued`);
+  if (record.projectDir && path.resolve(record.projectDir) !== path.resolve(projectDir)) return refuse("that job belongs to another repository");
+  if (record.commit?.created || record.commit?.sha) return refuse(`its work is already committed on ${record.branch}; start a new job with base_ref: "${record.branch}" instead`);
+  const worktree = record.worktree ?? path.join(jobDir, "worktree");
+  if (!fs.existsSync(worktree)) return refuse("its worktree is gone (cleaned up), so there's no unfinished work to continue");
+  if (!record.git?.baseSha && !record.gitBeforeCoordinatorCommit?.baseSha && !record.baseSha) return refuse("its record has no base commit");
+  return { problem: null, record: { ...record, worktree } };
+}
+
+/** The retained job's base commit, however its record spells it. */
+export function continuationBase(record) {
+  return record.git?.baseSha ?? record.gitBeforeCoordinatorCommit?.baseSha ?? record.baseSha;
+}
+
+/**
+ * Snapshot the retained worktree's changes against its base as a dangling
+ * commit, without touching that worktree or its index: a temporary index
+ * starts from the base, takes every change (new files and deletions too),
+ * and drops runtime junk. Worktrees share one object store, so the new
+ * worktree can check the commit out.
+ * @returns {Promise<{ commit: string, files: string[] }>}
+ */
+export async function snapshotRetainedWork({ worktree, baseSha, jobId, git }) {
+  const indexFile = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "nomarmy-continue-")), "index");
+  const env = { ...process.env, GIT_INDEX_FILE: indexFile };
+  try {
+    await git(["read-tree", baseSha], { cwd: worktree, env });
+    await git(["add", "-A"], { cwd: worktree, env });
+    const staged = (await git(["diff", "--cached", "--name-only", "-z", baseSha], { cwd: worktree, env })).split("\0").filter(Boolean);
+    const junk = staged.filter(isRuntimeJunk);
+    for (const file of junk) await git(["rm", "--cached", "-q", "-r", "--ignore-unmatch", "--", file], { cwd: worktree, env });
+    const tree = (await git(["write-tree"], { cwd: worktree, env })).trim();
+    const commit = (await git(["commit-tree", tree, "-p", baseSha, "-m", `nomArmy: unfinished work of ${jobId}`], { cwd: worktree, env })).trim();
+    return { commit, files: staged.filter((f) => !junk.includes(f)) };
+  } finally {
+    fs.rmSync(path.dirname(indexFile), { recursive: true, force: true });
+  }
+}
+
+/**
+ * Lay a snapshot into a fresh worktree at the same base as uncommitted
+ * changes: the files from the snapshot, deletions removed, index back at the
+ * base. The new job's git record then counts them as its own diff.
+ */
+export async function applyRetainedWork({ worktree, baseSha, commit, git }) {
+  await git(["checkout", commit, "--", "."], { cwd: worktree });
+  const deleted = (await git(["diff", "--name-only", "-z", "--diff-filter=D", baseSha, commit], { cwd: worktree })).split("\0").filter(Boolean);
+  for (const file of deleted) fs.rmSync(path.join(worktree, file), { force: true });
+  await git(["reset", "-q"], { cwd: worktree });
+}
+
+/** The brief's note, so the worker builds on the work instead of redoing it. */
+export function continuationNote({ continueFrom, record, files }) {
+  const listed = files.slice(0, 20).join(", ") + (files.length > 20 ? `, and ${files.length - 20} more` : "");
+  // What stopped the work, for the worker: its own NOT DONE, a failed
+  // verification, a timeout. Not the notes addressed to the General (review
+  // flags, "accept only after an independent review"): a worker handed those
+  // took the pending review as its own unfinished task and reported partial.
+  const reasons = [];
+  const notDone = record.reportValidation?.notDone;
+  if (notDone && !/^none\.?$/i.test(String(notDone).trim())) reasons.push(`its worker's NOT DONE: ${notDone}`);
+  if (record.independentVerification?.status === "fail") reasons.push(`its verification failed: ${record.independentVerification.detail ?? record.independentVerification.reason ?? "see the job record"}`);
+  if (record.outcome === "WORKER_TIMEOUT") reasons.push("it ran out of time");
+  if (!reasons.length && record.outcome) reasons.push(`it ended as ${record.outcome}`);
+  const why = reasons.map((r) => `- ${String(r).slice(0, 300)}`).join("\n");
+  return `This worktree already holds the unfinished work of job ${continueFrom} (${files.length} file(s): ${listed}). Build on it; don't redo it. Your finished diff is verified as a whole, that work included.${why ? `\nThat job stopped because:\n${why}` : ""}`;
+}

package/lib/coordinator-instructions.mjs

@@ -11,13 +11,17 @@ export const COORDINATOR_INSTRUCTIONS = `nomArmy runs bounded engineering jobs (
 Before dispatching:
 - Answer where-is / who-calls / grep questions with repo_evidence (deterministic, [path:line] on every hit). Use mode: scout only for read-only research that would otherwise pull many files into your own context.
 - Call army to see this repo's roles and which agent each runs on; dispatch by army_role when a role fits. A job on a subscription agent needs on_behalf_of set to that agent's owner.
+- Agents' usage limits show in army and local_worker_capacity; a job on an agent at its limit is held. Ask the operator before resubmitting with confirm_over_limit: true, or move the job to another agent. Never set it on your own.
 - A Claude subscription agent (claude-cli) runs its tools on this machine, outside the sandbox: use it for scout and review work. nomArmy refuses implement jobs on it unless the operator set allow_host_tools; send build work to a sandboxed agent.
+- To run tests without changing anything, use mode: verify; it costs no model usage.
+- Mark an implement job stakes: high when a mistake would be costly (security, access control, personal or tenant data, data loss, money, irreversible changes), however small it is. It then needs a verification profile, keeps the revert check, and needs an independent review before you accept it: a scout on another vendor with reviews: <job id>.
 - Brief outcomes, not edits: a task, explicit acceptance criteria, and the tests that prove it. Put facts you've already resolved in evidence.
-- Prefer local_worker_start + local_worker_status for anything longer than a few minutes. For a whole feature, use /feature (run_start keeps a run's jobs, spend and hours bounded).
+- Prefer local_worker_start for anything longer than a few minutes. Right after, if you can run a background command, run \`nomarmy jobs --wait <job_id>\` in the background so you're told the moment it finishes and can tell the operator (for several jobs, \`nomarmy jobs --wait <id> <id> ...\`; for a whole run, \`nomarmy jobs --events --until-done --run <run-id>\`); otherwise poll local_worker_status with wait_seconds. To read a finished job, use local_worker_status with report: true (the report, a scout's cited findings, the outcome, issues and commit); full: true is the whole record and rarely needed. Review scouts (reviews set, or a review-phase role) default to 20 minutes, other jobs to 10; pass timeout_seconds for more. Never use unscoped \`--until-done\` when other sessions may have jobs. Never run the plain \`nomarmy jobs --events\` stream as a background command: it only reports when it exits, so you'd never hear; it's for a monitor that reads each line. For a whole feature, use /feature (run_start keeps a run's jobs, spend and hours bounded).
 
 Trust boundary:
 - A worker's four-line report is a claim; nomArmy's verified git record and independent verification are the evidence. A job isn't complete if its report is missing or malformed, its STATUS is partial or blocked, STATUS done lacks VERIFICATION pass, or its changes aren't committed by nomArmy.
 - Read the diff of anything material before integrating it. nomArmy commits on the worker's branch and never merges into yours: integration, conflicts and pushes are yours.
+- A job on the wrong track can be stopped with local_worker_stop; it keeps its worktree. To finish a job that came back partial, blocked, failing verification or stopped, dispatch the correction with continue_from: <that job id> (a cheaper model is fine). The new job starts with its unfinished work in place and verifies the whole. Don't fix and commit a worker's files yourself: that lands them unverified. If you must, commit them on a branch, run mode: verify on it before building on it, and say so in your report.
 - Failed and incomplete worktrees are kept for review; clean up with local_worker_cleanup or local_worker_sweep once you've decided.
 
 Never delegate deployments, production access, cloud or SSH credentials, secrets, Terraform state or kubectl contexts to a worker.`;

package/lib/diff-checks.mjs

@@ -1,3 +1,5 @@
+import path from "node:path";
+
 // ---------------------------------------------------------------------------
 // Test-change classification (plan 16). One tunable constant, on purpose:
 // every heuristic about what counts as a test file lives here and nowhere else.
@@ -27,6 +29,24 @@ export function isDocumentationPath(file) {
   return DOC_EXTENSIONS.has(ext) || DOC_BASENAMES.has(dot > 0 ? base.slice(0, dot) : base);
 }
 
+export function isCiConfigPath(file) {
+  const normalized = String(file ?? "").replace(/\\/g, "/").replace(/^\.\//, "");
+  return /^\.github\/(workflows|actions)\//.test(normalized)
+    || normalized === ".github/dependabot.yml"
+    || normalized === ".gitlab-ci.yml"
+    || /^\.circleci\//.test(normalized)
+    || normalized === "azure-pipelines.yml"
+    || /^\.buildkite\//.test(normalized)
+    || normalized === "Jenkinsfile"
+    || normalized === "bitbucket-pipelines.yml";
+}
+
+export function planRegressionProductionFiles(files) {
+  // Local repository tests cannot exercise CI services, so reverting CI
+  // configuration cannot provide useful regression evidence.
+  return (files ?? []).filter((file) => !isDocumentationPath(file) && !isCiConfigPath(file));
+}
+
 export function isTestPath(file) {
   const normalized = String(file ?? "").replace(/\\/g, "/").replace(/^\.\//, "");
   if (!normalized) return false;
@@ -109,6 +129,12 @@ const TEST_SELECTION_FLAG_PATTERNS = Object.freeze([
 export function detectScopedTestSelectionRisk({ commands = [], testChanges = null } = {}) {
   const touchedTestFiles = [...(testChanges?.new_tests_added ?? []), ...(testChanges?.existing_tests_modified ?? [])];
   if (touchedTestFiles.length === 0) return null;
+  // A command that runs the changed test files by name, with no filter of its
+  // own, runs exactly the tests this diff touched: another command's -k can't
+  // exclude them. Senti's python profile does this and the warning fired on
+  // every job, which teaches people to ignore it.
+  const runsChangedTestsByName = commands.some((c) => /\$\{?NOMARMY_CHANGED_TEST_FILES\b/.test(String(c ?? "")) && !TEST_SELECTION_FLAG_PATTERNS.some((p) => p.re.test(String(c))));
+  if (runsChangedTestsByName) return null;
   const flagged = [];
   for (const command of commands) {
     const match = TEST_SELECTION_FLAG_PATTERNS.find((p) => p.re.test(String(command ?? "")));
@@ -416,3 +442,91 @@ export function mergeUntrackedIntoNameStatus(nameStatus, untrackedFiles) {
   return [...(nameStatus ?? []), ...extra];
 }
 
+
+// ---------------------------------------------------------------------------
+// Verification inputs: .nomarmy.yml is read from the operator's checkout so a
+// worker can't weaken its own checks, but the files its commands run come
+// from the worker's worktree. Found live: a worker whose verification ran
+// `node check.js` rewrote check.js to print PASS and exit 0, and the job
+// committed as done. The revert check can't see it: reverting check.js along
+// with the code makes verification fail, which reads as coverage.
+//
+// Blocking (the diff changes what a command runs): a changed non-test file a
+// command names (`node check.js`, `bash scripts/verify.sh`), a changed
+// Makefile or justfile under `make`/`just`, or a changed package.json script
+// that `npm test`/`pnpm run x`/`yarn x`/`bun run x` calls. Test files named by
+// a command are left to the test-change review, since adding cases is normal.
+// Flagged only: test-runner configuration, which is often a legitimate edit.
+// ---------------------------------------------------------------------------
+
+const RUNNER_CONFIG_RE = /(^|\/)(conftest\.py|pytest\.ini|tox\.ini|setup\.cfg|\.coveragerc|(jest|vitest|vite|playwright|karma|cypress)\.config\.[cm]?[jt]s|\.mocharc(\.[a-z]+)?|phpunit\.xml(\.dist)?|\.rspec)$/;
+const TASK_FILES = { make: ["Makefile", "makefile", "GNUmakefile"], just: ["justfile", "Justfile", ".justfile"] };
+
+function shellWords(segment) {
+  return (segment.match(/"[^"]*"|'[^']*'|\S+/g) ?? []).map((w) => w.replace(/^["']|["']$/g, ""));
+}
+
+// Which package.json script a package-manager command runs, if any.
+function packageScript(words) {
+  const [tool, first, second] = words;
+  if (!["npm", "pnpm", "yarn", "bun"].includes(tool) || !first) return null;
+  if (["run", "run-script"].includes(first)) return second && !second.startsWith("-") ? second : null;
+  if (tool === "npm") return ["test", "t", "tst"].includes(first) ? "test" : ["start", "stop", "restart"].includes(first) ? first : null;
+  if (tool === "bun") return null; // `bun test` is bun's own runner, not a script
+  return first.startsWith("-") || ["install", "add", "remove", "exec", "dlx", "x"].includes(first) ? null : first;
+}
+
+function scriptsOf(text) {
+  try { return JSON.parse(text ?? "")?.scripts ?? {}; } catch { return {}; }
+}
+
+function pytestSection(text) {
+  const match = /^\[tool\.pytest[^\]]*\]\s*$([\s\S]*?)(?=^\[|(?![\s\S]))/m.exec(String(text ?? ""));
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * @param {{ commands: string[], changedFiles: string[], readBase: (file: string) => string|null|Promise<string|null>,
+ *   readHead: (file: string) => string|null|Promise<string|null>, isTestPathFn?: (file: string) => boolean }} input
+ * @returns {Promise<{ blocked: {file: string, command: string, why: string}[], flagged: {file: string, why: string}[] } | null>}
+ */
+export async function detectVerificationInputChanges({ commands = [], changedFiles = [], readBase = () => null, readHead = () => null, isTestPathFn = isTestPath } = {}) {
+  const changed = new Set(changedFiles.map((f) => path.posix.normalize(f)));
+  if (!changed.size) return null;
+  const blocked = [], flagged = [], seen = new Set();
+  const block = (file, command, why) => { if (!seen.has(file)) { seen.add(file); blocked.push({ file, command, why }); } };
+  for (const command of commands) {
+    let dir = "";
+    for (const segment of String(command ?? "").split(/\s*(?:&&|\|\||;|\|)\s*/)) {
+      const all = shellWords(segment);
+      let lead = 0;
+      while (lead < all.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(all[lead])) lead++; // FOO=1 cmd ...
+      const words = all.slice(lead);
+      if (!words.length) continue;
+      const at = (p) => path.posix.normalize(path.posix.join(dir, p));
+      if (words[0] === "cd" && words[1]) { dir = at(words[1]); continue; }
+      for (const word of words) {
+        if (word.startsWith("-") || word.includes("$")) continue;
+        const file = at(word);
+        if (changed.has(file) && !isTestPathFn(file)) block(file, command, `run by \`${command}\``);
+      }
+      for (const name of TASK_FILES[words[0]] ?? []) {
+        const file = at(name);
+        if (changed.has(file)) block(file, command, `read by \`${command}\``);
+      }
+      const script = packageScript(words);
+      const manifest = at("package.json");
+      if (script && changed.has(manifest)) {
+        const before = scriptsOf(await readBase(manifest)), after = scriptsOf(await readHead(manifest));
+        const touched = [script, `pre${script}`, `post${script}`].filter((s) => before[s] !== after[s]);
+        if (touched.length) block(manifest, command, `its script${touched.length > 1 ? "s" : ""} ${touched.map((s) => `"${s}"`).join(", ")} changed, and \`${command}\` runs it`);
+      }
+    }
+  }
+  for (const file of changed) {
+    if (seen.has(file)) continue;
+    if (RUNNER_CONFIG_RE.test(file)) flagged.push({ file, why: "test-runner configuration" });
+    else if (/(^|\/)pyproject\.toml$/.test(file) && pytestSection(await readBase(file)) !== pytestSection(await readHead(file))) flagged.push({ file, why: "its [tool.pytest] settings changed" });
+  }
+  return blocked.length || flagged.length ? { blocked, flagged } : null;
+}