nomarmy 0.1.0-alpha.0

package/lib/config.mjs

@@ -0,0 +1,193 @@
+// nomArmy repository configuration loader (v1.3).
+//
+// `.nomarmy.yml` is the environment contract for a job: what services the
+// worker's sandbox gets, how the application is started, which verification
+// profiles exist, and what happens to the environment afterwards.
+//
+// All YAML parsing lives in this file so the parser stays swappable; the shape
+// itself lives in `lib/schema.mjs`.
+
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+
+import {
+  collectElevated,
+  configSchema,
+  emptyElevated,
+  formatIssues,
+} from "./schema.mjs";
+
+export {
+  DEFAULT_RETENTION,
+  ELEVATED_SERVICE_SOURCES,
+  ENVIRONMENT_LEVELS,
+  RETENTION_ACTIONS,
+  SERVICE_SOURCES,
+} from "./schema.mjs";
+
+/** Filenames searched, in order. First hit wins. */
+export const CONFIG_FILENAMES = Object.freeze([".nomarmy.yml", ".nomarmy.yaml"]);
+
+/**
+ * Raised when a `.nomarmy.yml` exists but cannot be used. Carries the same
+ * readable `path: message` lines that `validateConfig` returns, so a caller
+ * never has to re-derive them from the message text.
+ */
+export class ConfigError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ errors?: string[], path?: string|null, cause?: unknown }} [details]
+   */
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "ConfigError";
+    this.errors = details.errors || [];
+    this.path = details.path || null;
+    if (details.cause !== undefined) this.cause = details.cause;
+  }
+}
+
+function isReadableFile(candidate) {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Absolute path of the repository's config file, or null when absent.
+ * @param {string} [repoDir]
+ * @returns {string|null}
+ */
+export function findConfigFile(repoDir = process.cwd()) {
+  const base = path.resolve(repoDir);
+  for (const filename of CONFIG_FILENAMES) {
+    const candidate = path.join(base, filename);
+    if (isReadableFile(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Parse YAML text into a plain object. The only YAML entry point in nomArmy.
+ * An empty document (or a comments-only file) becomes `{}`.
+ * @param {string} text
+ * @param {string|null} [sourcePath] used only for the error message
+ * @returns {object}
+ */
+export function parseYaml(text, sourcePath = null) {
+  let parsed;
+  try {
+    parsed = YAML.parse(text, { prettyErrors: true });
+  } catch (error) {
+    const where = sourcePath ? `${path.basename(sourcePath)}` : "configuration";
+    throw new ConfigError(`${where} is not valid YAML: ${error.message}`, {
+      path: sourcePath,
+      errors: [`config: is not valid YAML: ${error.message}`],
+      cause: error,
+    });
+  }
+  return parsed === null || parsed === undefined ? {} : parsed;
+}
+
+/**
+ * Serialize a plain object to YAML text. The only YAML *write* entry point,
+ * for the same swappable-parser reason parseYaml is the only read one.
+ * @param {object} config
+ * @returns {string}
+ */
+export function stringifyConfig(config) {
+  return YAML.stringify(config);
+}
+
+/**
+ * Validate an already-parsed plain object against the `.nomarmy.yml` schema.
+ *
+ * `elevated` lists every `shared` and `remote` service found. Those sources
+ * reach outside the job sandbox, so they are accepted here but the caller is
+ * expected to require explicit policy approval before running the job. It is
+ * structured data on purpose, not a warning string.
+ *
+ * @param {unknown} input
+ * @returns {{ valid: boolean, config: object|null, errors: string[], elevated: { shared: string[], remote: string[] } }}
+ */
+export function validateConfig(input) {
+  const candidate = input === null || input === undefined ? {} : input;
+
+  if (typeof candidate !== "object" || Array.isArray(candidate)) {
+    return {
+      valid: false,
+      config: null,
+      errors: ["config: must be a mapping of top-level sections"],
+      elevated: emptyElevated(),
+    };
+  }
+
+  const result = configSchema.safeParse(candidate);
+  if (!result.success) {
+    return {
+      valid: false,
+      config: null,
+      errors: formatIssues(result.error),
+      elevated: emptyElevated(),
+    };
+  }
+
+  return {
+    valid: true,
+    config: result.data,
+    errors: [],
+    elevated: collectElevated(result.data),
+  };
+}
+
+/**
+ * Find, parse and validate a repository's `.nomarmy.yml`.
+ *
+ * A missing file is not an error: the repo simply has no environment contract,
+ * and `{ found: false }` comes back cleanly. A file that exists but is broken
+ * throws `ConfigError`: an unusable contract must not be mistaken for none.
+ *
+ * @param {string} [repoDir] repository root to search
+ * @returns {{ found: boolean, path: string|null, config: object|null, elevated: { shared: string[], remote: string[] } }}
+ */
+export function loadConfig(repoDir = process.cwd()) {
+  const configPath = findConfigFile(repoDir);
+  if (!configPath) {
+    return { found: false, path: null, config: null, elevated: emptyElevated() };
+  }
+
+  let text;
+  try {
+    text = fs.readFileSync(configPath, "utf8");
+  } catch (error) {
+    throw new ConfigError(
+      `${path.basename(configPath)} could not be read: ${error.message}`,
+      {
+        path: configPath,
+        errors: [`config: could not be read: ${error.message}`],
+        cause: error,
+      },
+    );
+  }
+
+  const parsed = parseYaml(text, configPath);
+  const result = validateConfig(parsed);
+
+  if (!result.valid) {
+    const detail = result.errors.map((line) => `  - ${line}`).join("\n");
+    throw new ConfigError(
+      `${path.basename(configPath)} is not a valid nomArmy configuration:\n${detail}`,
+      { path: configPath, errors: result.errors },
+    );
+  }
+
+  return {
+    found: true,
+    path: configPath,
+    config: result.config,
+    elevated: result.elevated,
+  };
+}

package/lib/connect.mjs

@@ -0,0 +1,409 @@
+// Registers the nomArmy MCP server with a coordinator (Claude Code, Codex,
+// or Cursor). Originally two separate bash scripts (setup-claude-worker.sh /
+// setup-codex-worker.sh); ported to real JS and now the ONLY implementation
+// -- install.sh calls `nomarmy connect <target>` too, not the old scripts,
+// which is exactly what let a real bug (env vars silently dropped on
+// reinstall) go unnoticed in the bash version for a long time: only one of
+// the two implementations ever got fixed, and the fresh-install path kept
+// calling the other one. Unlike install.sh itself (OS package-manager
+// detection, toolchain installs, curl-piped installers, genuinely risky to
+// reimplement), this registration step is small and
+// purely mechanical: copy files, npm install, then either call one external
+// CLI's own `mcp add` (Claude, Codex) or edit a JSON config file directly
+// (Cursor, which has no CLI for this at all). Nothing here needs bash to
+// exist on the host at all.
+//
+// The registered MCP server is always a COPY under installDir, never the
+// dev checkout directly -- server.mjs resolves "../lib/verify.mjs" relative
+// to its own location, so lib/ ships as installDir's sibling of mcp/.
+//
+// Add a new coordinator here: implement connect<Name>({ nomarmyRoot,
+// installDir, run }) returning at least { installDir, serverPath }, then
+// wire it into KNOWN_TARGETS and the dispatch table in bin/nomarmy.mjs.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { loadAgents } from "./agents.mjs";
+import { globalConfigDir } from "./army.mjs";
+import { buildNotifierApp } from "./notifier-app.mjs";
+
+export function defaultInstallDir() {
+  return process.env.NOMARMY_AGENT_INSTALL_DIR || path.join(process.env.HOME ?? process.env.USERPROFILE ?? ".", ".local", "share", "nomarmy-local-worker");
+}
+
+/**
+ * Copy package.json/mcp/lib into installDir and `npm install` there.
+ * Shared by both coordinators; has no opinion about which one is registering.
+ * @param {{ nomarmyRoot: string, installDir: string, run?: Function }} input
+ */
+// --- The /feature playbook, installed into each coordinator ---------------
+//
+// One body (playbooks/*.md, with a {{REQUEST}} placeholder), rendered in
+// each coordinator's own format. Every installed copy carries a
+// `<!-- 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)
+//   Cursor       ~/.cursor/commands/feature.md (Cursor's documented
+//                user-level commands directory; not verified against a
+//                real install here)
+
+const COMMAND_MARKER = "<!-- nomarmy:";
+const PLAYBOOKS = Object.freeze({
+  feature: {
+    description: "nomArmy -- build a feature end to end with the army, then come back with a branch ready to merge",
+    argumentHint: "<the feature you want> | resume <run-id>",
+  },
+});
+
+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"),
+    cursor: env.NOMARMY_CURSOR_COMMANDS_DIR ? path.resolve(env.NOMARMY_CURSOR_COMMANDS_DIR) : path.join(home, ".cursor", "commands"),
+  };
+}
+
+/** One playbook rendered for one coordinator: { relPath, text }. */
+export function renderPlaybook(name, body, target) {
+  const meta = PLAYBOOKS[name];
+  const marker = `${COMMAND_MARKER}${name} -- installed by \`nomarmy connect ${target}\`; edits here are overwritten on the next connect -->`;
+  if (target === "claude") {
+    return { relPath: `${name}.md`, text: `---\ndescription: ${meta.description}\nargument-hint: ${meta.argumentHint}\n---\n${marker}\n\n${body.replace("{{REQUEST}}", "$ARGUMENTS")}` };
+  }
+  if (target === "codex") {
+    // A skill is invoked by the model when the request matches its
+    // description, so the description says when to use it.
+    const description = `${meta.description}. Use when the user asks nomArmy (or "the army") to build a feature end to end, or to resume a nomArmy run by its run-id.`;
+    return { relPath: path.join(`nomarmy-${name}`, "SKILL.md"), text: `---\nname: nomarmy-${name}\ndescription: ${description}\n---\n${marker}\n\n${body.replace("{{REQUEST}}", "The feature is the one the user asked for when this skill was invoked (or the run-id they asked to resume).")}` };
+  }
+  return { relPath: `${name}.md`, text: `${marker}\n\n# nomArmy: ${name}\n\n${body.replace("{{REQUEST}}", `The feature is the text the user wrote after /${name} (or \`resume <run-id>\`).`)}` };
+}
+
+/**
+ * Install every playbook for one coordinator.
+ * @returns {{ installed: string[], skipped: string[] }} relative paths
+ */
+export function installPlaybooks({ nomarmyRoot, target, dir = defaultCommandDirs()[target] }) {
+  const srcDir = path.join(nomarmyRoot, "playbooks");
+  const out = { installed: [], skipped: [], dir };
+  if (!fs.existsSync(srcDir)) return out;
+  for (const file of fs.readdirSync(srcDir).filter((f) => f.endsWith(".md"))) {
+    const name = file.replace(/\.md$/, "");
+    if (!PLAYBOOKS[name]) continue;
+    const { relPath, text } = renderPlaybook(name, fs.readFileSync(path.join(srcDir, file), "utf8"), target);
+    const dest = path.join(dir, relPath);
+    if (fs.existsSync(dest) && !fs.readFileSync(dest, "utf8").includes(COMMAND_MARKER)) { out.skipped.push(relPath); continue; }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, text);
+    out.installed.push(relPath);
+  }
+  return out;
+}
+
+const STATUS_LINE_REFRESH_SECONDS = 5;
+
+/** Claude Code's user settings file. */
+export function defaultClaudeSettingsPath(env = process.env) {
+  return env.NOMARMY_CLAUDE_SETTINGS_PATH ? path.resolve(env.NOMARMY_CLAUDE_SETTINGS_PATH) : path.join(os.homedir(), ".claude", "settings.json");
+}
+
+/**
+ * Point Claude Code's status line at nomArmy's (lib/statusline.mjs in the
+ * installed copy) -- only when no status line is configured, or when the
+ * configured one is already nomArmy's (refreshed to the current path). An
+ * operator's own status line is never replaced; they're told how to add
+ * nomArmy's to it instead.
+ * @returns {"installed"|"updated"|"kept-yours"|"unchanged"|"skipped"}
+ */
+export function installClaudeStatusLine({ installDir, settingsPath = defaultClaudeSettingsPath() }) {
+  let settings = {};
+  try { if (fs.existsSync(settingsPath)) settings = JSON.parse(fs.readFileSync(settingsPath, "utf8")); }
+  catch { return "skipped"; } // an unparseable settings file is never rewritten
+  const command = `node ${JSON.stringify(path.join(installDir, "lib", "statusline.mjs"))}`;
+  const current = settings.statusLine;
+  if (current && !String(current.command ?? "").includes("statusline.mjs")) return "kept-yours";
+  // refreshInterval: Claude Code otherwise re-runs the command only on
+  // conversation events, so an idle session's elapsed times froze.
+  if (current?.command === command && current?.refreshInterval === STATUS_LINE_REFRESH_SECONDS) return "unchanged";
+  settings.statusLine = { type: "command", command, padding: 0, refreshInterval: STATUS_LINE_REFRESH_SECONDS };
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  return current ? "updated" : "installed";
+}
+
+export function installMcpCopy({ nomarmyRoot, installDir, run = defaultRun }) {
+  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"));
+  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
+  // (lib/ and docker/ as siblings), so the installed copy needs this too,
+  // not just the dev checkout -- otherwise a lazy Go/Rust image build would
+  // work from a repo clone but silently fail to find its Dockerfile once
+  // installed.
+  const dockerSrc = path.join(nomarmyRoot, "docker");
+  if (fs.existsSync(dockerSrc)) {
+    fs.rmSync(path.join(installDir, "docker"), { recursive: true, force: true });
+    fs.cpSync(dockerSrc, path.join(installDir, "docker"), { recursive: true });
+  }
+  // mcp/server.mjs resolves config/providers.yml relative to its own
+  // location (mcp/ and config/ as siblings), the same lib/sandbox-images.mjs
+  // pattern above uses for docker/ -- without this, an installed server can
+  // never see a dispatch pool config an operator wrote into the dev
+  // checkout's config/ directory. This incidentally also copies
+  // common.env/profiles/*.env alongside it (the whole directory copies as
+  // one unit, same as docker/), but the server never relies on reading
+  // those from here: their values only ever reach it through connect-time
+  // -e env injection (see deriveWorkerModelEnv below), so a stale copy of
+  // either sitting in installDir is inert, never consulted.
+  const configSrc = path.join(nomarmyRoot, "config");
+  if (fs.existsSync(configSrc)) {
+    fs.rmSync(path.join(installDir, "config"), { recursive: true, force: true });
+    fs.cpSync(configSrc, path.join(installDir, "config"), { recursive: true });
+  }
+  run("npm", ["install", "--omit=dev"], { cwd: installDir });
+  run(process.execPath, ["--check", "mcp/server.mjs"], { cwd: installDir });
+}
+
+function defaultRun(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, { stdio: "inherit", ...opts });
+}
+// Best-effort removal of an old registration: failure (nothing registered
+// under that name yet, likely a fresh install) is expected, not an error.
+// Takes the same injected `run` every other call in this module does, so a
+// test's fake `run` sees every subprocess this module would spawn, never
+// only some of them.
+function quietRun(run, cmd, args, opts = {}) {
+  try { return run(cmd, args, opts); } catch { return null; }
+}
+
+/**
+ * Pull the "KEY=value" lines out of `claude mcp get <name>`'s "Environment:"
+ * section. Observed live: a registration carrying NOMARMY_WORKER_MODEL (an
+ * operator testing a non-default local model) silently lost that variable
+ * on the next `nomarmy connect`/`update`, because the re-add below used to
+ * pass no -e flags at all -- reinstalling the server code reset which model
+ * every dispatch actually used, with no warning. A blank line or a line that
+ * is not "KEY=value" ends the block; nothing registered yet is not an error.
+ */
+export function parseClaudeEnv(output) {
+  const lines = String(output ?? "").split(/\r?\n/);
+  const start = lines.findIndex(l => /^\s*Environment:\s*$/.test(l));
+  if (start === -1) return {};
+  const env = {};
+  for (let i = start + 1; i < lines.length; i++) {
+    const m = lines[i].match(/^\s{2,}([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!m) break;
+    env[m[1]] = m[2];
+  }
+  return env;
+}
+
+function captureExistingEnv(run, name) {
+  try {
+    const out = run("claude", ["mcp", "get", name], { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" });
+    return parseClaudeEnv(out);
+  } catch {
+    return {};
+  }
+}
+
+function readEnvValue(filePath, key) {
+  try {
+    const m = fs.readFileSync(filePath, "utf8").match(new RegExp(`^${key}=(.*)$`, "m"));
+    return m ? m[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * config/common.env's NOMARMY_WORKER_MODEL sat unused for every model choice
+ * until now -- nothing ever read it back out to actually route dispatch, so
+ * picking a non-default model in `nomarmy setup`/`model` silently had no
+ * effect on which model workers were routed to. This makes that file the
+ * real source of truth: whatever it says the configured model and its
+ * thinking support are, the MCP registration is kept in sync with, every
+ * connect. Missing file or keys is not an error -- an older checkout with no
+ * 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");
+  const env = {};
+  if (model) env.NOMARMY_WORKER_MODEL = model;
+  if (thinking !== null) env.NOMARMY_WORKER_MODEL_THINKING = thinking;
+  return env;
+}
+
+const SERVER_NAME = "nomarmy-local-worker";
+
+/**
+ * Every distinct auth_env name declared across config/providers.yml's
+ * pools, mapped to a placeholder value -- NEVER the real credential, which
+ * lives only in OpenClaw's own store from `nomarmy agents add`'s
+ * registration step.
+ *
+ * Why this needs to exist at all: an api agent's auth_env is checked for
+ * TRUTHINESS ONLY by the dispatcher (lib/dispatch-config.mjs's
+ * availableEntries), inside the MCP SERVER's own process.env -- and
+ * "export it in some shell" has no reliable path to that specific process.
+ * A GUI-launched coordinator never inherited a later shell export in the
+ * first place; a terminal-launched one only did if the export predated
+ * that specific launch. Live symptom this closes: the old providers list
+ * kept showing an entry as unset even after registration had genuinely
+ * succeeded and the variable really was exported -- just never in the
+ * shell that mattered.
+ *
+ * Called on every connect, the same way deriveWorkerModelEnv already is,
+ * so a newly added api agent is picked up the next time an operator
+ * reconnects for ANY reason (a model swap, an update, a fresh install) --
+ * not only if they remember a separate step right after `agents add`.
+ * A missing/invalid agents.yml contributes nothing here, silently -- that's
+ * `agents list`'s problem to report, not connect's to block on.
+ */
+export function derivePoolAuthEnvPlaceholders(configDir = globalConfigDir()) {
+  let loaded;
+  try {
+    loaded = loadAgents(configDir);
+  } catch {
+    return {};
+  }
+  const env = {};
+  for (const agent of Object.values(loaded.agents)) {
+    if (agent.kind === "api" && agent.auth_env) env[agent.auth_env] = "registered";
+  }
+  return env;
+}
+
+/**
+ * @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() }) {
+  installMcpCopy({ nomarmyRoot, installDir, run });
+  const commands = installPlaybooks({ nomarmyRoot, target: "claude", dir: commandsDir });
+  const notifier = buildNotifierApp({ nomarmyRoot });
+  const statusLine = installClaudeStatusLine({ installDir, settingsPath });
+  const preservedEnv = captureExistingEnv(run, SERVER_NAME);
+  // config/common.env is the source of truth for which model is configured;
+  // its worker-routing keys always win over whatever the old registration
+  // happened to have, which may be stale (a previous model swap that never
+  // made it into the registration, or vice versa). Any OTHER custom env var
+  // an operator set some other way is still preserved untouched.
+  //
+  // Precedence, lowest to highest: a freshly-derived pool placeholder fills
+  // in only when nothing already covers that key; whatever's genuinely
+  // already registered (preservedEnv) wins over that; extraEnv is an
+  // explicit, immediate ask from THIS call (e.g. `nomarmy providers add
+  // --update-mcp`, right after writing a brand-new entry, before its
+  // placeholder would otherwise show up here on this same call); and
+  // config/common.env's derived worker-model keys still win over
+  // everything, exactly as before this existed.
+  const finalEnv = { ...derivePoolAuthEnvPlaceholders(configDir), ...preservedEnv, ...extraEnv, ...deriveWorkerModelEnv(nomarmyRoot) };
+  quietRun(run, "claude", ["mcp", "remove", SERVER_NAME, "--scope", "user"]);
+  quietRun(run, "claude", ["mcp", "remove", SERVER_NAME]);
+  const serverPath = path.join(installDir, "mcp", "server.mjs");
+  // -e is variadic (`-e <env...>`): it greedily swallows every bare token
+  // after it, including the server name, until the next recognized flag or
+  // `--`. The server name and any --scope must come before -e, not after,
+  // or `claude mcp add` rejects the server name itself as a malformed
+  // "KEY=value" environment entry.
+  const envArgs = Object.entries(finalEnv).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+  try {
+    run("claude", ["mcp", "add", "--scope", "user", SERVER_NAME, ...envArgs, "--", "node", serverPath]);
+  } catch {
+    // Compatibility fallback for Claude Code versions whose MCP command
+    // does not support --scope user.
+    run("claude", ["mcp", "add", SERVER_NAME, ...envArgs, "--", "node", serverPath]);
+  }
+  run("claude", ["mcp", "get", SERVER_NAME]);
+  return { installDir, serverPath, preservedEnv: finalEnv, commands, statusLine, notifier };
+}
+
+/**
+ * @param {{ nomarmyRoot: string, installDir?: string, run?: Function }} input
+ */
+export function connectCodex({ nomarmyRoot, installDir = defaultInstallDir(), run = defaultRun, skillsDir = defaultCommandDirs().codex }) {
+  installMcpCopy({ nomarmyRoot, installDir, run });
+  const commands = installPlaybooks({ nomarmyRoot, target: "codex", dir: skillsDir });
+  const notifier = buildNotifierApp({ nomarmyRoot });
+  quietRun(run, "codex", ["mcp", "remove", SERVER_NAME]);
+  const serverPath = path.join(installDir, "mcp", "server.mjs");
+  run("codex", ["mcp", "add", SERVER_NAME, "--", "node", serverPath]);
+  run("codex", ["mcp", "list"]);
+  return { installDir, serverPath, commands, notifier };
+}
+
+export function defaultCursorConfigPath() {
+  return process.env.NOMARMY_CURSOR_CONFIG_PATH
+    || path.join(process.env.HOME ?? process.env.USERPROFILE ?? ".", ".cursor", "mcp.json");
+}
+
+/**
+ * Cursor has no CLI for this: registration is a JSON file
+ * (~/.cursor/mcp.json), read-modify-written under { mcpServers: { name: {
+ * command, args, env } } }, the same schema Claude Desktop and most other
+ * MCP hosts converged on. A file that does not exist yet is fine (fresh
+ * install); a file that exists but fails to parse is NEVER silently
+ * overwritten -- that would discard whatever else was in it (other
+ * configured servers, hand edits) without the operator ever seeing it.
+ */
+export function readCursorConfig(configPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, "utf8");
+  } catch {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${configPath} exists but is not valid JSON (${err.message}). Fix or remove it by hand, then re-run -- it is never overwritten blindly.`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${configPath} exists but its top level is not a JSON object. Fix or remove it by hand, then re-run.`);
+  }
+  return parsed;
+}
+
+/**
+ * @param {{ nomarmyRoot: string, installDir?: string, configPath?: string }} input
+ */
+export function connectCursor({ nomarmyRoot, installDir = defaultInstallDir(), configPath = defaultCursorConfigPath(), run = defaultRun, commandsDir = defaultCommandDirs().cursor }) {
+  installMcpCopy({ nomarmyRoot, installDir, run });
+  const commands = installPlaybooks({ nomarmyRoot, target: "cursor", dir: commandsDir });
+  const notifier = buildNotifierApp({ nomarmyRoot });
+  const serverPath = path.join(installDir, "mcp", "server.mjs");
+  const config = readCursorConfig(configPath);
+  if (!config.mcpServers || typeof config.mcpServers !== "object") config.mcpServers = {};
+  // Preserve this entry's own existing env vars (the same incident
+  // 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.
+  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 };
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  return { installDir, serverPath, configPath, preservedEnv, commands, notifier };
+}
+
+/** True when Cursor's config file already has a nomArmy entry -- used by
+ * `nomarmy update` to decide whether to re-sync it, since Cursor has no
+ * `commandExists` equivalent to check the way Claude/Codex do. */
+export function cursorAlreadyConnected(configPath = defaultCursorConfigPath()) {
+  try {
+    const config = readCursorConfig(configPath);
+    return Boolean(config.mcpServers && config.mcpServers[SERVER_NAME]);
+  } catch {
+    return false;
+  }
+}

package/lib/coordinator-instructions.mjs

@@ -0,0 +1,23 @@
+// What every coordinator (Claude Code, Codex, Cursor) is told when it
+// connects to nomArmy's MCP server: the MCP `instructions` field. It used
+// to live only in this repo's CLAUDE.md, which a person had to copy into
+// each project, and which an npm install doesn't even include.
+//
+// Kept short: a coordinator reads it on every session. The detail is in each
+// tool's own description.
+
+export const COORDINATOR_INSTRUCTIONS = `nomArmy runs bounded engineering jobs (noms) in isolated git worktrees and sandboxes, on a local model or on the api and subscription agents the operator configured. You are the General: you plan, brief, dispatch, review, integrate and accept. Workers never are.
+
+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.
+- 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.
+- 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).
+
+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.
+- 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.`;