nomarmy 0.1.0-alpha.10 → 0.1.0-alpha.12

package/bin/nomarmy.mjs

@@ -18,8 +18,11 @@ 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 } from "../lib/connect.mjs";
+import { 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, parseSince, resolveRepo } from "../lib/stats.mjs";
+import { loadValidators, saveJevKey, removeJev, jevSettings, askJev, validatorsPath, JEV_CHECKS, saveJudge, removeJudge, judgeSettings } 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";
 import { loadArmy, mergeArmy, describeArmy, readArmyFile, updateArmyInFile, assignRoleInFile, parseTargetSpec, armyLayerPath, globalConfigDir, DEFAULT_ARMY, ARMY_PHASES, LOCAL_CONFIG_FILENAME } from "../lib/army.mjs";
@@ -40,10 +43,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}`);
 }
 
@@ -214,10 +217,34 @@ 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>]
+        [--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. Today: Jev (TypeSafe). \`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
@@ -1709,6 +1736,13 @@ async function cmdUpdate() {
 // this process loaded. Returns the targets reconnected.
 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 [];
+  }
   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" });
@@ -1717,7 +1751,7 @@ function reconnectCoordinators() {
 }
 
 function connectedTargets() {
-  return [commandExists("claude") && "claude", commandExists("codex") && "codex", cursorAlreadyConnected() && "cursor"].filter(Boolean);
+  return [commandExists("claude") && claudeUserScoped() && "claude", commandExists("codex") && "codex", cursorAlreadyConnected() && "cursor"].filter(Boolean);
 }
 
 async function updateFromNpm() {
@@ -1788,7 +1822,20 @@ 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}".`);
+  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));
@@ -1813,9 +1860,12 @@ async function cmdConnect() {
     }
     try {
       if (!json) console.log(c.bold(`\n🍪 Connecting nomArmy to ${target}...`));
-      const result = connectTarget(target, { nomarmyRoot, run });
+      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`));
@@ -2617,7 +2667,145 @@ async function cmdStatusline() {
   process.stdout.write(`${statusLineText({ session })}\n`);
 }
 
-const commands = { 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) };
+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`); }
+  }
+  const stats = computeStats(records, { repo, sinceMs: parseSince(value("since")), untilMs: parseSince(value("until")), role: value("role"), model: value("model") });
+  if (json) return out(stats);
+  console.log(formatStats(stats));
+}
+
+// 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") {
+    const agent = value("agent"), model = value("model");
+    if (!agent || !model) throw new Error("Usage: nomarmy validators add judge --agent <name> --model <model> [--host-tools]");
+    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") });
+    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}.`));
+    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() {
   // Import lazily to avoid circular dependencies

package/lib/admission.mjs

@@ -126,6 +126,19 @@ export function createJobRuntime(deps) {
       try { return await fn(); } finally { slot.release(); }
     })();
   }
+  // Who ran the job and for whom, onto its finished record, so `nomarmy
+  // stats` can count by role and agent, and by repo for verify runs too
+  // (their records didn't carry the repo). Best-effort; never fails the job.
+  function stampJobRecord(entry, result) {
+    const file = path.join(result?.jobDir ?? path.join(jobsRoot, entry.jobId), "metadata.json");
+    try {
+      const record = JSON.parse(fs.readFileSync(file, "utf8"));
+      record.labels = { role: entry.role ?? null, agent: entry.agent ?? null, label: entry.label ?? null, runId: entry.runId ?? null };
+      record.projectDir = record.projectDir ?? projectDir;
+      fs.writeFileSync(`${file}.tmp`, JSON.stringify(record, null, 2));
+      fs.renameSync(`${file}.tmp`, file);
+    } catch { /* no record (a refused or crashed job): nothing to label */ }
+  }
   function track(jobId, meta, promise) {
     const entry = { ...meta, jobId, startedAt: new Date().toISOString(), settled: false, result: null, error: null, promise: null };
     // A machine-wide lease for as long as the job runs, so every session's
@@ -134,7 +147,7 @@ export function createJobRuntime(deps) {
     if (meta.lane) writeLease(leasesRoot, jobId, { lane: meta.lane, agent: meta.agent ?? null, runId: meta.runId ?? null, role: meta.role ?? null, model: meta.model ?? null, repo: projectDir });
     const release = () => removeLease(leasesRoot, jobId);
     entry.promise = promise.then(
-      r => { entry.settled = true; entry.result = r; release(); notifyJobFinished(entry, r, null); return r; },
+      r => { entry.settled = true; entry.result = r; release(); stampJobRecord(entry, r); notifyJobFinished(entry, r, null); return r; },
       e => { entry.settled = true; entry.error = e; release(); notifyJobFinished(entry, null, e); throw e; });
     entry.promise.catch(() => {});
     activeJobs.set(jobId, entry);

package/lib/connect.mjs

@@ -261,6 +261,50 @@ export function deriveWorkerModelEnv(nomarmyRoot) {
 
 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()));
+  const added = relPaths.map((p) => `/${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 [];
+  const drop = new Set(relPaths.map((p) => `/${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
@@ -302,7 +346,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 });
@@ -340,13 +385,62 @@ 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 } };
+}
+
+/** 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, configDir = globalConfigDir(), skillsDir = defaultCommandDirs().codex, legacySkillsDir = path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "skills") }) {
+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);
@@ -410,7 +504,13 @@ export function readCursorConfig(configPath) {
 /**
  * @param {{ nomarmyRoot: string, installDir?: string, configPath?: string }} input
  */
-export function connectCursor({ nomarmyRoot, installDir = defaultInstallDir(), configPath = defaultCursorConfigPath(), run = defaultRun, configDir = globalConfigDir(), 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 });
@@ -427,10 +527,15 @@ export function connectCursor({ nomarmyRoot, installDir = defaultInstallDir(), c
   // 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] = { command: "node", args: [serverPath], env: preservedEnv };
+  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