nomarmy 0.1.0-alpha.0

package/lib/propose.mjs

@@ -0,0 +1,110 @@
+// Turns scan evidence into a conservative `.nomarmy.yml` PROPOSAL for
+// `nomarmy init` to show a human, never a finished answer.
+//
+// lib/evidence.mjs's own header already says the evidence shape is meant for
+// an LLM's judgment, not a deterministic mapper -- picking an `environment`
+// level and a service's `source` are judgment calls evidence alone can't
+// answer. So this mapper deliberately stays narrow:
+//   * only ever proposes `source: "compose"` services, mapped 1:1 from
+//     evidence (mechanical, not a judgment call) -- never `shared`/`remote`,
+//     the schema's elevated sources that require explicit human policy
+//     approval (see lib/schema.mjs's ELEVATED_SERVICE_SOURCES);
+//   * verification always needs review: the schema requires at least one
+//     command, so a repo with no detected command gets an explicit,
+//     fail-loud placeholder rather than a fake one that would silently
+//     "pass" every job;
+//   * evidence flagged fixture-like by lib/scan.mjs's fixturePaths is never
+//     included.
+import { validateConfig } from "./config.mjs";
+
+const PLACEHOLDER_COMMAND = "echo 'REPLACE ME: no verification command configured yet' && exit 1";
+
+/**
+ * @param {object} evidence  scanRepository()'s return value
+ * @returns {{ proposal: object, valid: boolean, errors: string[], excludedFixturePaths: string[], notes: string[] }}
+ */
+export function buildConfigProposal(evidence) {
+  const fixturePaths = new Set(evidence?.fixturePaths ?? []);
+  const notes = [];
+  const excludedFixturePaths = new Set();
+
+  const allServices = evidence?.services?.items ?? [];
+  const services = allServices.filter((s) => {
+    if (fixturePaths.has(s.source)) { excludedFixturePaths.add(s.source); return false; }
+    return true;
+  });
+
+  const proposal = {};
+
+  // --- environment.services (compose only, mechanical) --------------------
+  const composeFiles = [...new Set(services.map((s) => s.source))];
+  if (composeFiles.length > 0) {
+    const file = composeFiles[0];
+    if (composeFiles.length > 1) {
+      notes.push(`found real (non-fixture) services across ${composeFiles.length} different compose files (${composeFiles.join(", ")}); only ${file} was used -- review the others by hand.`);
+    }
+    const fromFile = services.filter((s) => s.source === file);
+    const environmentServices = {};
+    for (const s of fromFile) environmentServices[s.name] = { source: "compose", service: s.name };
+    proposal.environment = { compose: { file }, services: environmentServices };
+  }
+
+  // --- environment.python.requirements -------------------------------------
+  // lib/sandbox-images.mjs's ensurePythonImageBuilt only ever `pip install
+  // -r <file>`s whatever this proposes -- it cannot install from
+  // pyproject.toml/poetry/uv directly, so this stays scoped to the same
+  // requirements.txt-shaped evidence handleRequirements records (tooling
+  // name "pip"), never pyproject.toml evidence alone; proposing something
+  // the sandbox builder can't actually act on would be worse than proposing
+  // nothing. A repo whose real Python dependency source is poetry/uv with no
+  // requirements.txt anywhere gets no proposal here -- a distinct, real gap
+  // (the sandbox has no poetry/uv install path at all yet), not this one.
+  const pipTooling = (evidence?.tooling?.items ?? []).filter((t) => t.name === "pip" && t.category === "package-manager" && t.source);
+  for (const t of pipTooling) if (fixturePaths.has(t.source)) excludedFixturePaths.add(t.source);
+  const requirementsFiles = [...new Set(pipTooling.filter((t) => !fixturePaths.has(t.source)).map((t) => t.source))].sort();
+  if (requirementsFiles.length === 1) {
+    proposal.environment = { ...proposal.environment, python: { requirements: requirementsFiles } };
+  } else if (requirementsFiles.length > 1) {
+    // The exact ambiguity this file's own header already treats as a human
+    // judgment call for compose files: several requirements.txt-shaped files
+    // (app, dev, a sub-package's own) with no single conventional
+    // combination this could guess -- a wrong guess here is worse than no
+    // proposal, since a worker's correct diff would fail verification for
+    // an infrastructure reason indistinguishable from broken code (this is
+    // exactly the failure this whole field exists to prevent in the first
+    // place: silently omitting it entirely did the same thing).
+    notes.push(`found ${requirementsFiles.length} requirements files (${requirementsFiles.join(", ")}) -- none was proposed automatically since the right combination is your call; add environment.python.requirements by hand, or verification will silently run in a base image with no Python dependencies installed.`);
+  }
+
+  // --- verification (always needs review) ----------------------------------
+  // Only ever seed from a command evidence itself already labels "test" --
+  // evidence.commands also carries start/build/lint/seed/migrate commands
+  // (e.g. a Dockerfile's CMD, "sleep infinity", keeping a container alive),
+  // and picking any command regardless of purpose picked exactly that once.
+  const testCommandItems = evidence?.commands?.items?.filter((c) => c.kind === "test") ?? [];
+  for (const c of testCommandItems) if (fixturePaths.has(c.source)) excludedFixturePaths.add(c.source);
+  const commandItems = testCommandItems.filter((c) => !fixturePaths.has(c.source));
+  const firstCommand = commandItems.find((c) => c.command)?.command;
+  if (firstCommand) {
+    notes.push(`verification.quick.commands was seeded from a command found in evidence (${firstCommand}) -- confirm this is actually the right check before trusting it.`);
+    proposal.verification = { quick: { environment: "none", commands: [firstCommand] } };
+  } else {
+    notes.push("no command was found anywhere in evidence; verification.quick.commands is a fail-loud placeholder -- replace it before this profile is usable.");
+    proposal.verification = { quick: { environment: "none", commands: [PLACEHOLDER_COMMAND] } };
+  }
+
+  // A bundle or packaging step (Lambda assets, SAM, Serverless, CDK): unit
+  // tests pass while a module the bundle leaves out crashes the deployed
+  // function on import. A real Senti branch had exactly that, and pytest,
+  // nomArmy's verification and the revert check were all green. Only a
+  // repo-specific check catches it, so say so; the command is the repo's own.
+  const BUNDLE_RE = /\bbundle[\w-]*|\bpackage-[\w-]+|prepare-[\w-]*packages?\b|\bsam (?:build|package)\b|\b(?:serverless|sls) package\b|\bcdk synth\b/i;
+  const bundleCommands = [...new Set((evidence?.commands?.items ?? []).filter((c) => !fixturePaths.has(c.source) && BUNDLE_RE.test(c.command ?? "")).map((c) => c.command.trim()))];
+  if (bundleCommands.length) {
+    const shown = bundleCommands.slice(0, 3).join("; ");
+    notes.push(`found a bundle/packaging step (${shown}${bundleCommands.length > 3 ? "; ..." : ""}). Tests pass even when a module is left out of the bundle, so consider a verification profile that runs it and then imports each entry point from inside the built bundle (e.g. \`python -c "import handler"\` in each asset directory): that catches a deploy-time import crash before it ships.`);
+  }
+
+  const { valid, errors } = validateConfig(proposal);
+  return { proposal, valid, errors, excludedFixturePaths: [...excludedFixturePaths].sort(), notes };
+}

package/lib/prune.mjs

@@ -0,0 +1,77 @@
+// Removing finished jobs' runtime/ directories: each job's npm cache and
+// harness state (Codex's, OpenClaw's transcript), about 100 MB a job, and
+// 2 GB after a busy day of real runs. Shared by `nomarmy jobs --prune` and
+// the health check's automatic prune (lib/health.mjs).
+//
+// Only a job with a final record (metadata.json with finishedAt) and no
+// live lease is touched. A running job's status.json heartbeat is always in
+// the past, and treating it as a finish time deleted a live job's state
+// with --older-than 0. The record, logs, report and any kept worktree stay.
+
+import fs from "node:fs";
+import path from "node:path";
+
+function readJson(file) { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } }
+
+function sizeOf(dir) {
+  let n = 0;
+  const stack = [dir];
+  while (stack.length) {
+    const d = stack.pop();
+    let entries = [];
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) stack.push(p);
+      else { try { n += fs.lstatSync(p).size; } catch { /* gone */ } }
+    }
+  }
+  return n;
+}
+
+/**
+ * @param {{ stateRoot: string, olderThanMs: number, now?: number }} input
+ * @returns {{ pruned: number, scratchCleared: number, freedBytes: number }}
+ */
+export function pruneJobRuntime({ stateRoot, olderThanMs, now = Date.now() }) {
+  const jobsRoot = path.join(stateRoot, "jobs"), leasesRoot = path.join(stateRoot, "leases");
+  const cutoff = now - olderThanMs;
+  let pruned = 0, scratchCleared = 0, freedBytes = 0, names = [];
+  try { names = fs.readdirSync(jobsRoot); } catch { return { pruned, scratchCleared, freedBytes }; }
+  for (const name of names) {
+    const dir = path.join(jobsRoot, name), runtime = path.join(dir, "runtime");
+    if (!fs.existsSync(runtime)) continue;
+    const finishedAt = Date.parse(readJson(path.join(dir, "metadata.json"))?.finishedAt ?? "");
+    if (!Number.isFinite(finishedAt)) continue;
+    if (fs.existsSync(path.join(leasesRoot, `${name}.json`))) continue;
+    if (finishedAt <= cutoff) {
+      freedBytes += sizeOf(runtime);
+      fs.rmSync(runtime, { recursive: true, force: true });
+      pruned++;
+      continue;
+    }
+    // OpenClaw's scratch space (plugin build copies, 1.2 GB for a Codex
+    // job) is of no use once the job is done, whatever its age; the
+    // transcript a recent job might still need isn't in it.
+    const scratch = path.join(runtime, "state", "tmp");
+    if (fs.existsSync(scratch)) {
+      freedBytes += sizeOf(scratch);
+      fs.rmSync(scratch, { recursive: true, force: true });
+      scratchCleared++;
+    }
+  }
+  return { pruned, scratchCleared, freedBytes };
+}
+
+/**
+ * How old a finished job must be before the health check prunes it on its
+ * own: NOMARMY_AUTO_PRUNE_HOURS (default 24, the window a report recovery
+ * could still want the transcript), or null when set to 0 or "off".
+ */
+export function autoPruneAgeMs(env = process.env) {
+  const raw = env.NOMARMY_AUTO_PRUNE_HOURS;
+  if (raw === undefined || raw === "") return 24 * 3600000;
+  if (/^(0|off|false|no)$/i.test(String(raw).trim())) return null;
+  const hours = Number(raw);
+  return Number.isFinite(hours) && hours > 0 ? hours * 3600000 : 24 * 3600000;
+}

package/lib/repo-query.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// Deterministic repository evidence. No model, no network, no dependencies.
+//
+// Most "scout-shaped" questions are not questions for a language model:
+// where is X defined, who references it, what does this file declare, which
+// files match this pattern. Answering them by reading files into a frontier
+// model's context is the most expensive way to do it, and answering them with
+// a small local model adds latency and invented citations on top. This module
+// answers them from the files, in milliseconds, with an exact [path:line] on
+// every hit.
+//
+// It runs in two places with the same code: on the host as the coordinator's
+// `repo_evidence` MCP tool, and inside the worker sandbox as a CLI a scout can
+// call. Inside the sandbox the output lines ARE citations in the scout
+// contract's syntax, so the model copies real locations instead of a template.
+//
+// Definitions are found heuristically per language family. That is stated in
+// every result; a heuristic hit is still a real line in a real file.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_IGNORES = Object.freeze([
+  "node_modules", ".git", ".openclaw", ".npm", ".npm-cache", "dist", "build", "out", "coverage", ".next", ".nuxt",
+  "target", "vendor", "__pycache__", ".venv", "venv", ".tox", ".mypy_cache", ".pytest_cache", ".cache", ".idea", ".vscode",
+]);
+export const LIMITS = Object.freeze({ maxFiles: 20000, maxFileBytes: 2 * 1024 * 1024, maxResults: 200, maxLineChars: 200, binarySniffBytes: 8192 });
+
+const TEXT_EXT_HINT = /\.(mjs|cjs|js|jsx|ts|tsx|py|go|rs|java|kt|kts|cs|rb|php|sh|bash|zsh|ps1|c|h|cpp|hpp|cc|swift|m|scala|sql|yml|yaml|json|toml|ini|cfg|env|md|txt|html|css|scss|vue|svelte|tf|hcl|dockerfile|make|gradle|xml|proto|graphql)$/i;
+
+// ---------------------------------------------------------------------------
+// File walk
+// ---------------------------------------------------------------------------
+function globToRegex(glob) {
+  // Minimal glob: ** any path, * within a segment, ? one char, {a,b} alternation.
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "*") { if (glob[i + 1] === "*") { re += "(?:.*\\/)?"; i++; if (glob[i + 1] === "/") { i++; } } else re += "[^/]*"; }
+    else if (ch === "?") re += "[^/]";
+    else if (ch === "{") { const j = glob.indexOf("}", i); if (j > i) { re += "(" + glob.slice(i + 1, j).split(",").map(s => s.replace(/[.+^$()|[\]\\]/g, "\\$&")).join("|") + ")"; i = j; } else re += "\\{"; }
+    else if (/[.+^$()|[\]\\]/.test(ch)) re += "\\" + ch;
+    else re += ch;
+  }
+  return new RegExp("^(?:.*/)?" + re + "$");
+}
+export function matchesGlob(rel, glob) {
+  if (!glob) return true;
+  return globToRegex(glob.replace(/\\/g, "/")).test(rel);
+}
+
+export function listFiles(root, { glob = null, ignores = DEFAULT_IGNORES, maxFiles = LIMITS.maxFiles } = {}) {
+  const files = [];
+  const ignore = new Set(ignores);
+  const stack = [""];
+  let truncated = false;
+  while (stack.length && !truncated) {
+    const rel = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true }); } catch { continue; }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (ignore.has(e.name)) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) stack.push(r);
+      else if (e.isFile()) {
+        if (glob && !matchesGlob(r, glob)) continue;
+        files.push(r);
+        if (files.length >= maxFiles) { truncated = true; break; }
+      }
+    }
+  }
+  return { files: files.sort(), truncated };
+}
+
+function readTextFile(root, rel) {
+  const abs = path.join(root, rel);
+  let stat;
+  try { stat = fs.statSync(abs); } catch { return null; }
+  if (stat.size > LIMITS.maxFileBytes) return null;
+  let buf;
+  try { buf = fs.readFileSync(abs); } catch { return null; }
+  const sniff = buf.subarray(0, LIMITS.binarySniffBytes);
+  if (sniff.includes(0) && !TEXT_EXT_HINT.test(rel)) return null;
+  return buf.toString("utf8");
+}
+
+function clip(text, max = LIMITS.maxLineChars) {
+  const t = text.replace(/\t/g, "  ").trimEnd();
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+// ---------------------------------------------------------------------------
+// grep
+// ---------------------------------------------------------------------------
+export function grepRepo(root, { pattern, regex = true, ignoreCase = false, wholeWord = false, glob = null, maxResults = LIMITS.maxResults, ignores = DEFAULT_IGNORES } = {}) {
+  if (!pattern) throw new Error("grep needs a pattern");
+  let src = regex ? pattern : pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (wholeWord) src = `\\b(?:${src})\\b`;
+  let re;
+  try { re = new RegExp(src, ignoreCase ? "i" : ""); } catch (e) { throw new Error(`invalid pattern: ${e.message}`); }
+  const { files, truncated: filesTruncated } = listFiles(root, { glob, ignores });
+  const hits = [];
+  let filesScanned = 0, truncated = false;
+  for (const rel of files) {
+    const text = readTextFile(root, rel);
+    if (text === null) continue;
+    filesScanned++;
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      if (!re.test(lines[i])) continue;
+      hits.push({ path: rel, line: i + 1, text: clip(lines[i]) });
+      if (hits.length >= maxResults) { truncated = true; break; }
+    }
+    if (truncated) break;
+  }
+  return { hits, truncated: truncated || filesTruncated, filesScanned };
+}
+
+// ---------------------------------------------------------------------------
+// definitions / references / outline (heuristic, per language family)
+// ---------------------------------------------------------------------------
+const esc = s => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Definition patterns. `S` is the escaped symbol, or a capture for outline. */
+export function definitionPatterns(S) {
+  const n = S; // already escaped or a capture group
+  return [
+    { kind: "function", lang: "js", re: `^\\s*(?:export\\s+)?(?:default\\s+)?(?:async\\s+)?function\\s*\\*?\\s*${n}\\s*[(<]` },
+    { kind: "const", lang: "js", re: `^\\s*(?:export\\s+)?(?:const|let|var)\\s+${n}\\s*(?::[^=]+)?=` },
+    { kind: "class", lang: "js", re: `^\\s*(?:export\\s+)?(?:default\\s+)?(?:abstract\\s+)?class\\s+${n}\\b` },
+    { kind: "type", lang: "ts", re: `^\\s*(?:export\\s+)?(?:declare\\s+)?(?:interface|type|enum)\\s+${n}\\b` },
+    { kind: "method", lang: "js", re: `^\\s+(?:public\\s+|private\\s+|protected\\s+|static\\s+|async\\s+|override\\s+)*${n}\\s*\\([^)]*\\)\\s*(?::\\s*[^{]+)?\\{` },
+    { kind: "function", lang: "py", re: `^\\s*(?:async\\s+)?def\\s+${n}\\s*\\(` },
+    { kind: "class", lang: "py", re: `^\\s*class\\s+${n}\\s*[(:]` },
+    { kind: "function", lang: "go", re: `^func\\s+(?:\\([^)]*\\)\\s*)?${n}\\s*[(\\[]` },
+    { kind: "type", lang: "go", re: `^type\\s+${n}\\s+` },
+    { kind: "function", lang: "rust", re: `^\\s*(?:pub(?:\\([^)]*\\))?\\s+)?(?:async\\s+)?(?:unsafe\\s+)?fn\\s+${n}\\s*[(<]` },
+    { kind: "type", lang: "rust", re: `^\\s*(?:pub(?:\\([^)]*\\))?\\s+)?(?:struct|enum|trait|type)\\s+${n}\\b` },
+    // A typed declaration `Type name(`; the lookahead stops `return foo(` and
+    // `await foo(` from reading as a definition named foo.
+    { kind: "method", lang: "jvm", re: `^\\s*(?!(?:return|new|throw|await|yield|else|case|typeof|delete|void|if|while|for|switch|catch|const|let|var|import|export|from|not|and|or|is|print|assert|raise|in|of|do|goto|defer|go)\\s)(?:(?:public|private|protected|internal|static|final|abstract|override|virtual|async|open|suspend)\\s+)*(?:[\\w<>\\[\\],.?]+\\s+)${n}\\s*\\(` },
+    { kind: "class", lang: "jvm", re: `^\\s*(?:(?:public|private|protected|internal|static|final|abstract|sealed|data|open|partial)\\s+)*(?:class|interface|enum|record|object|struct)\\s+${n}\\b` },
+    { kind: "function", lang: "rb", re: `^\\s*def\\s+(?:self\\.)?${n}\\b` },
+    { kind: "class", lang: "rb", re: `^\\s*(?:class|module)\\s+${n}\\b` },
+    { kind: "function", lang: "sh", re: `^\\s*(?:function\\s+)?${n}\\s*\\(\\)\\s*\\{` },
+  ];
+}
+
+export function findDefinitions(root, symbol, { glob = null, maxResults = LIMITS.maxResults, ignores = DEFAULT_IGNORES } = {}) {
+  if (!symbol) throw new Error("definitions needs a symbol");
+  const pats = definitionPatterns(esc(symbol)).map(p => ({ ...p, rx: new RegExp(p.re) }));
+  const { files, truncated: filesTruncated } = listFiles(root, { glob, ignores });
+  const hits = [];
+  let truncated = false;
+  for (const rel of files) {
+    const text = readTextFile(root, rel);
+    if (text === null) continue;
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length && !truncated; i++) {
+      const p = pats.find(p => p.rx.test(lines[i]));
+      if (!p) continue;
+      hits.push({ path: rel, line: i + 1, text: clip(lines[i]), kind: p.kind, lang: p.lang });
+      if (hits.length >= maxResults) truncated = true;
+    }
+    if (truncated) break;
+  }
+  return { symbol, hits, truncated: truncated || filesTruncated, heuristic: true };
+}
+
+export function findReferences(root, symbol, { glob = null, maxResults = LIMITS.maxResults, ignores = DEFAULT_IGNORES } = {}) {
+  if (!symbol) throw new Error("references needs a symbol");
+  const defs = findDefinitions(root, symbol, { glob, maxResults: LIMITS.maxResults, ignores });
+  const defKeys = new Set(defs.hits.map(h => `${h.path}:${h.line}`));
+  const all = grepRepo(root, { pattern: esc(symbol), wholeWord: true, glob, maxResults: maxResults + defKeys.size, ignores });
+  const hits = all.hits.filter(h => !defKeys.has(`${h.path}:${h.line}`)).slice(0, maxResults);
+  return { symbol, hits, definitions: defs.hits, truncated: all.truncated || hits.length >= maxResults, filesScanned: all.filesScanned };
+}
+
+export function outlineFile(root, rel) {
+  if (!rel) throw new Error("outline needs a path");
+  const clean = String(rel).replace(/\\/g, "/").replace(/^\.\//, "");
+  if (clean.startsWith("/") || clean.split("/").includes("..")) throw new Error("outline path must be inside the repository");
+  const text = readTextFile(root, clean);
+  if (text === null) return { path: clean, exists: fs.existsSync(path.join(root, clean)), items: [], reason: "not a readable text file" };
+  const pats = definitionPatterns("([A-Za-z_$][\\w$]*)").map(p => ({ ...p, rx: new RegExp(p.re) }));
+  const lines = text.split(/\r?\n/);
+  const items = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || /^\s*(\/\/|#|\*|\/\*)/.test(line)) continue;
+    for (const p of pats) {
+      const m = line.match(p.rx);
+      if (!m) continue;
+      // Methods and nested definitions are kept, but only shallowly indented
+      // ones, so an outline is an outline and not every callback.
+      const indent = line.match(/^\s*/)[0].length;
+      if (indent > 4 && p.kind !== "method") break;
+      const exported = /^\s*(export|pub|public)\b/.test(line);
+      items.push({ line: i + 1, kind: p.kind, name: m[1], exported, text: clip(line, 120) });
+      break;
+    }
+  }
+  return { path: clean, exists: true, lines: lines.length, items, heuristic: true };
+}
+
+// ---------------------------------------------------------------------------
+// Dispatcher and citation formatting
+// ---------------------------------------------------------------------------
+export const OPS = Object.freeze(["grep", "definitions", "references", "outline", "files"]);
+
+export function runQuery(root, op, args = {}) {
+  const max = Math.max(1, Math.min(Number(args.max_results) || LIMITS.maxResults, 1000));
+  switch (op) {
+    case "grep": return { op, ...grepRepo(root, { pattern: args.query, regex: args.regex !== false, ignoreCase: Boolean(args.ignore_case), wholeWord: Boolean(args.whole_word), glob: args.glob ?? null, maxResults: max }) };
+    case "definitions": return { op, ...findDefinitions(root, args.query, { glob: args.glob ?? null, maxResults: max }) };
+    case "references": return { op, ...findReferences(root, args.query, { glob: args.glob ?? null, maxResults: max }) };
+    case "outline": return { op, ...outlineFile(root, args.path ?? args.query) };
+    case "files": { const r = listFiles(root, { glob: args.glob ?? args.query ?? null, maxFiles: max }); return { op, files: r.files, truncated: r.truncated }; }
+    default: throw new Error(`unknown op '${op}'; expected one of ${OPS.join(", ")}`);
+  }
+}
+
+/** Render results as lines the scout contract accepts verbatim: [path:line] text. */
+export function formatCitations(result) {
+  const out = [];
+  if (result.op === "files") {
+    for (const f of result.files) out.push(`[${f}]`);
+    if (!result.files.length) out.push("(no files matched)");
+  } else if (result.op === "outline") {
+    if (!result.items?.length) out.push(result.exists ? `(no definitions recognized in ${result.path}; ${result.lines ?? "?"} lines)` : `(no such file: ${result.path})`);
+    for (const it of result.items ?? []) out.push(`[${result.path}:${it.line}] ${it.kind}${it.exported ? " (exported)" : ""} ${it.name}`);
+  } else {
+    if (result.op === "references" && result.definitions?.length) {
+      out.push(`definitions of ${result.symbol}:`);
+      for (const h of result.definitions) out.push(`[${h.path}:${h.line}] ${h.text}`);
+      out.push(`references:`);
+    }
+    for (const h of result.hits) out.push(`[${h.path}:${h.line}] ${h.text}`);
+    if (!result.hits.length) out.push(`(no matches${result.op === "grep" ? "" : ` for ${result.symbol}`})`);
+  }
+  if (result.truncated) out.push("(results truncated; narrow the query or add --glob)");
+  if (result.heuristic) out.push("(definitions are matched heuristically by language family)");
+  return out.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// CLI: node repo-query.mjs <op> <query|path> [--glob <g>] [--max <n>] [--json] [--root <dir>]
+// ---------------------------------------------------------------------------
+const isMain = (() => { try { return Boolean(process.argv[1]) && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); } catch { return false; } })();
+if (isMain) {
+  const argv = process.argv.slice(2);
+  const flag = n => argv.includes(`--${n}`);
+  const val = (n, d = null) => { const i = argv.indexOf(`--${n}`); return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : d; };
+  const op = argv[0], query = argv[1] && !argv[1].startsWith("--") ? argv[1] : null;
+  if (!op || !OPS.includes(op)) {
+    console.log(`usage: node repo-query.mjs <${OPS.join("|")}> <query|path> [--glob <pattern>] [--max <n>] [--ignore-case] [--json]\n\n` +
+      `  grep <regex>          lines matching a pattern\n  definitions <symbol>  where a symbol is defined (heuristic)\n` +
+      `  references <symbol>   where a symbol is used, definitions listed first\n  outline <path>        what one file declares\n  files <glob>          files matching a glob\n\n` +
+      `Every output line starts with a [path:line] citation you can copy verbatim.`);
+    process.exit(op ? 2 : 0);
+  }
+  try {
+    const root = path.resolve(val("root", process.cwd()));
+    const result = runQuery(root, op, { query, path: query, glob: val("glob"), max_results: val("max"), ignore_case: flag("ignore-case"), whole_word: flag("word") });
+    console.log(flag("json") ? JSON.stringify(result, null, 2) : formatCitations(result));
+  } catch (err) { console.error(`repo-query ${op}: ${err.message}`); process.exit(1); }
+}

package/lib/runs.mjs

@@ -0,0 +1,150 @@
+// nomArmy runs: one feature, end to end, with limits.
+//
+// A run groups every job the General dispatches for one feature (`run_id`
+// on each job). It carries limits -- jobs, api spend, wall-clock hours --
+// that admission enforces, warning at `warn_at` and refusing at the cap. It
+// also watches for a vendor's usage-limit error: that agent is paused for
+// the rest of the run and the General is told, rather than nomArmy quietly
+// sending the role's work to some other vendor (which would change who did
+// the work, and could be pooling).
+//
+// What a run can't see: the General's own seat. No tool reports a Claude
+// subscription's remaining usage to the session using it, so the run log
+// exists for the other half -- if the General's seat runs out mid-feature,
+// a fresh session resumes from the log instead of starting over.
+//
+// Limits come from the army's `run_limits` (global or local layer only: a
+// committed project file must never be able to raise what a run may spend
+// of your money). The General may lower them for one run, never raise them.
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+export const DEFAULT_RUN_LIMITS = Object.freeze({ max_jobs: 40, max_api_usd: 10, max_hours: 6, warn_at: 0.8 });
+const LIMIT_KEYS = ["max_jobs", "max_api_usd", "max_hours"];
+
+/** A vendor's "you've hit your limit" error, as opposed to any other failure. */
+const USAGE_LIMIT_RE = /\b(rate[ _-]?limit(?:ed)?|usage[ _-]limit|quota(?: exceeded)?|insufficient[_ ]quota|too many requests|limit (?:reached|exceeded)|hit your (?:usage |rate )?limit|\b429\b)/i;
+
+/**
+ * The usage-limit message in a failed job's error text, or null. Only
+ * error text is ever passed here -- never the worker's report or tool
+ * output, where "rate limit" could simply be the code under discussion.
+ */
+export function detectUsageLimit(errorText) {
+  const text = String(errorText ?? "");
+  const match = USAGE_LIMIT_RE.exec(text);
+  if (!match) return null;
+  const line = text.split(/\r?\n/).find((l) => USAGE_LIMIT_RE.test(l)) ?? match[0];
+  return line.replace(/\u001b\[[0-9;]*m/g, "").trim().slice(0, 300);
+}
+
+/**
+ * What the General asked for that it didn't get, as plain sentences: the
+ * configured ceiling (or the default, when none is configured) always
+ * wins. A $15 request silently becoming $10 read as a bug.
+ */
+export function describeLoweredLimits(configured = {}, requested = {}, resolved) {
+  const label = { max_jobs: "jobs", max_api_usd: "api spend ($)", max_hours: "hours" };
+  return LIMIT_KEYS.filter((k) => Number.isFinite(requested?.[k]) && requested[k] > resolved[k]).map((k) => {
+    const source = configured?.[k] !== undefined ? "your configured run_limits" : "the default (no run_limits configured)";
+    return `${label[k]} capped at ${resolved[k]}, not ${requested[k]}: that's the ceiling from ${source}. Raise it with army.run_limits.${k} in ~/.config/nomarmy/config.yml or .nomarmy.local.yml.`;
+  });
+}
+
+/** The configured limits, tightened (never loosened) by the General's per-run request. */
+export function resolveRunLimits(configured = {}, requested = {}) {
+  const base = { ...DEFAULT_RUN_LIMITS, ...Object.fromEntries(Object.entries(configured ?? {}).filter(([, v]) => v !== undefined)) };
+  const out = { ...base };
+  for (const key of LIMIT_KEYS) {
+    const want = requested?.[key];
+    if (Number.isFinite(want) && want > 0) out[key] = Math.min(base[key], want);
+  }
+  return out;
+}
+
+function runPath(runsDir, id) {
+  if (!/^run-[a-z0-9-]{1,80}$/.test(String(id))) throw new Error(`"${id}" is not a run id`);
+  return path.join(runsDir, `${id}.json`);
+}
+
+function writeRun(runsDir, run) {
+  fs.mkdirSync(runsDir, { recursive: true });
+  const file = runPath(runsDir, run.id);
+  fs.writeFileSync(`${file}.tmp`, JSON.stringify(run, null, 2));
+  fs.renameSync(`${file}.tmp`, file);
+  return run;
+}
+
+export function createRun(runsDir, { name, repo, limits, now = Date.now() }) {
+  const slug = String(name ?? "feature").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "feature";
+  const id = `run-${slug}-${crypto.randomBytes(3).toString("hex")}`;
+  return writeRun(runsDir, {
+    id, name: name ?? slug, repo, status: "running", createdAt: new Date(now).toISOString(),
+    limits, jobs: [], pausedAgents: {}, logPath: path.join(runsDir, `${id}.md`), finishedAt: null, summary: null,
+  });
+}
+
+export function loadRun(runsDir, id) {
+  const file = runPath(runsDir, id);
+  if (!fs.existsSync(file)) throw new Error(`unknown run "${id}"`);
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+/** Totals so far, each limit's share used, and the warnings to surface. */
+export function runTotals(run, { now = Date.now() } = {}) {
+  const apiUsd = run.jobs.reduce((sum, j) => sum + (j.kind === "api" && Number.isFinite(j.costUsd) ? j.costUsd : 0), 0);
+  const hours = (now - Date.parse(run.createdAt)) / 3600000;
+  const used = { max_jobs: run.jobs.length, max_api_usd: +apiUsd.toFixed(4), max_hours: +hours.toFixed(2) };
+  const share = Object.fromEntries(LIMIT_KEYS.map((k) => [k, run.limits[k] > 0 ? used[k] / run.limits[k] : 0]));
+  const byAgent = {};
+  for (const j of run.jobs) {
+    const a = (byAgent[j.agent] ??= { jobs: 0, apiUsd: 0, tokens: 0 });
+    a.jobs += 1;
+    if (j.kind === "api" && Number.isFinite(j.costUsd)) a.apiUsd = +(a.apiUsd + j.costUsd).toFixed(4);
+    if (Number.isFinite(j.tokens)) a.tokens += j.tokens;
+  }
+  const label = { max_jobs: "jobs", max_api_usd: "api spend ($)", max_hours: "hours" };
+  // Past a limit is the loudest case, not a silent one: warnings used to
+  // stop at 100%, so a run at 8.46 of its 4 hours reported nothing.
+  const warnings = [
+    ...LIMIT_KEYS.filter((k) => share[k] >= 1).map((k) => `run is OVER its ${label[k]} limit (${used[k]} of ${run.limits[k]}); no more jobs are admitted`),
+    ...LIMIT_KEYS.filter((k) => share[k] >= run.limits.warn_at && share[k] < 1).map((k) => `run is at ${Math.round(share[k] * 100)}% of its ${label[k]} limit (${used[k]} of ${run.limits[k]})`),
+  ];
+  for (const [agent, reason] of Object.entries(run.pausedAgents)) warnings.push(`agent "${agent}" is paused for this run: ${reason}`);
+  return { used, share, byAgent, warnings };
+}
+
+/**
+ * Why a job may not start in this run, or []. `agentName` is the job's
+ * resolved agent ("local" when it names none).
+ */
+export function runAdmissionProblems(run, { agentName = "local", now = Date.now(), running = 0 } = {}) {
+  if (run.status !== "running") return [`run "${run.id}" is ${run.status}; start a new run (or resume by reading its log) rather than adding jobs to it`];
+  const problems = [];
+  const { used } = runTotals(run, { now });
+  // Jobs still running count too: a job is recorded into its run only when
+  // it finishes, so jobs started together could otherwise overshoot.
+  if (used.max_jobs + running >= run.limits.max_jobs) problems.push(`run "${run.id}" has used all ${run.limits.max_jobs} of its jobs${running ? ` (${running} still running)` : ""}`);
+  if (used.max_api_usd >= run.limits.max_api_usd) problems.push(`run "${run.id}" has spent $${used.max_api_usd} of its $${run.limits.max_api_usd} api limit`);
+  if (used.max_hours >= run.limits.max_hours) problems.push(`run "${run.id}" has run ${used.max_hours} of its ${run.limits.max_hours} hours`);
+  if (run.pausedAgents[agentName]) problems.push(`agent "${agentName}" is paused for run "${run.id}" (${run.pausedAgents[agentName]}); stop and tell the operator rather than moving this role to a different vendor`);
+  return problems;
+}
+
+/** Add a finished job; pause its agent on a usage-limit error. Returns the updated run. */
+export function recordRunJob(runsDir, id, job) {
+  const run = loadRun(runsDir, id);
+  run.jobs.push({ ...job, recordedAt: new Date().toISOString() });
+  if (job.usageLimit) run.pausedAgents[job.agent] = job.usageLimit;
+  return writeRun(runsDir, run);
+}
+
+export function finishRun(runsDir, id, { status, summary }) {
+  const run = loadRun(runsDir, id);
+  run.status = status;
+  run.summary = summary ?? null;
+  run.finishedAt = new Date().toISOString();
+  return writeRun(runsDir, run);
+}