nomarmy 0.1.0-alpha.0 → 0.1.0-alpha.1

package/README.md

@@ -8,9 +8,28 @@
 
 <p align="center"><em>Tiny coders, big appetites for bounded tickets.</em> 🍪</p>
 
-**An agent harness where a worker's claims are never trusted, and the environment your tests need is declared, disposable and reproducible.**
+**Your coding assistant plans; sandboxed workers build; nothing counts until nomArmy has checked it.**
 
-Your coding assistant (Claude Code, Codex or Cursor) stays in charge as the **General**: it decides what gets built and whether the result is acceptable. The work goes to **noms**, workers that implement, test and repair in their own git worktree and sandbox. A nom can run on a local model at no token cost, on an API key, or on your own Claude, ChatGPT or Muse Code subscription. nomArmy owns everything in between: worktrees, git, sandboxes, verification, and the evidence that decides whether work is accepted.
+## TL;DR
+
+1. **Have** Git, Node 20+ and [Podman](https://podman.io) (on macOS: `brew install podman && podman machine init && podman machine start`).
+2. **Install** (builds the local model server, OpenClaw and the sandbox, and registers nomArmy with Claude Code):
+   ```bash
+   git clone https://github.com/rayson-tech/nomarmy.git && cd nomarmy
+   ./install.sh --profile macbook-pro   # or nvidia-linux, cpu-linux, dgx-spark, bedrock
+   ./e2e.sh --profile macbook-pro       # should end with: === E2E PASS ===
+   ```
+3. **Set up your repo:** in the project, run `nomarmy init`. It proposes a `.nomarmy.yml` with your test command.
+4. **Use it:** restart Claude Code in that project and ask it to use nomArmy for one small bug that has a test. When that works, try `/feature <what you want built>`.
+5. **Optional:** add hosted workers with `nomarmy agents add`, give roles to them with `nomarmy army init`, or connect Codex or Cursor with `nomarmy connect codex cursor`.
+
+Stuck? `nomarmy doctor` checks the machine, and `nomarmy health` checks everything nomArmy runs on.
+
+## What it is
+
+Your coding assistant (Claude Code, Codex or Cursor) stays in charge as the **General**: it decides what gets built and whether the result is acceptable. The work goes to **noms**, workers that implement, test and repair in their own git worktree and sandbox, on a local model, an API key, or your own ChatGPT or Muse Code subscription. nomArmy owns everything in between: worktrees, git, sandboxes, verification, and the evidence that decides whether work is accepted.
+
+**What you get is work you don't have to take on faith**, not cheaper work. Delegating costs the General tokens too: briefing and reviewing. On small, already-diagnosed tickets we measured 4 to 8 times more of the General's tokens than fixing the bug directly, and break-even at roughly 150 lines of context a fix needs to read ([the measurements](docs/experiments/2026-09-20-model-bakeoff-and-economics.md)). It pays off on bigger tickets, on parallel work, and anywhere you'd otherwise have to trust an agent's say-so.
 
 Developed and maintained by Rayson Technologies. This is an alpha (`0.1.0-alpha`).
 
@@ -22,35 +41,10 @@ Developed and maintained by Rayson Technologies. This is an alpha (`0.1.0-alpha`
 4. nomArmy treats that report as a claim. It reads the real diff from git, runs your verification profile itself in a fresh sandbox, reverts the production change to check the tests actually fail without it, and scans for secrets.
 5. Only then does it commit, on the worker's own branch. It never merges into yours: reviewing and integrating stay with the General, and with you.
 
-A malformed report isn't automatically a failure: if the repository changed, nomArmy verifies independently and may recover the work. Failing verification stays failed, unconditionally.
+A malformed report isn't automatically a failure: if the repository changed, nomArmy verifies independently and may recover the work. Failing verification stays failed, unconditionally. And the checks aren't the General's to waive: a repo's `.nomarmy.yml` policy (on by default for new repos) makes verification and the revert check mandatory for every job.
 
 Around that core: **agents** say where a job can run, the **army** says which role runs on which agent, and **`/feature`** runs a whole feature end to end, from plan through build, review and acceptance, handing you a branch to merge.
 
-## Quick start
-
-You need Git, Node 20+, and [Podman](https://podman.io).
-
-```bash
-npm install -g nomarmy@alpha
-nomarmy doctor          # what's missing on this machine, and how to fix it
-nomarmy setup           # pick a profile and model; prints the install.sh command to run
-nomarmy connect claude  # or codex, cursor: registers nomArmy with your coordinator
-```
-
-Installing from a clone is the most tested path, and it's what `install.sh` expects: see [Install](#install). `install.sh` builds llama.cpp for local inference, installs and configures [OpenClaw](https://github.com/openclaw/openclaw) (the host-side broker every model call goes through), builds the sandbox image and registers the MCP server.
-
-`nomarmy connect` also installs the `/feature` command, Claude Code's status line and (on macOS) nomArmy's notifier. The coordinator gets nomArmy's instructions from the MCP server itself, so there's nothing to copy into your projects.
-
-Then, in any git repository:
-
-```bash
-nomarmy init                  # propose a .nomarmy.yml with your test command
-nomarmy agents add            # optional: an API key or a subscription
-nomarmy army init             # optional: the default roster of roles
-```
-
-Ask your coordinator to delegate one small, well-tested ticket before anything bigger. When that works, try `/feature <what you want built>`.
-
 ## Install
 
 | Platform | Guide |
@@ -63,6 +57,10 @@ Ask your coordinator to delegate one small, well-tested ticket before anything b
 
 Every platform needs Git and Podman. `nomarmy doctor` checks the host and prints a fix for anything missing.
 
+`install.sh` builds llama.cpp for local inference, installs and configures [OpenClaw](https://github.com/openclaw/openclaw) (the host-side broker every model call goes through), builds the sandbox image, and registers the MCP server if Claude Code is installed. `nomarmy connect` (run by `install.sh`, or by hand for Codex and Cursor) also installs the `/feature` command, Claude Code's status line and, on macOS, nomArmy's notifier. The coordinator gets nomArmy's instructions from the MCP server itself, so there's nothing to copy into your projects.
+
+**From npm:** `npm install -g nomarmy@alpha` gives you the `nomarmy` command; `nomarmy setup` then picks a profile and model and prints the `install.sh` command to run. Installing from a clone, as in the TL;DR, is the most tested path.
+
 ### macOS (Apple Silicon)
 
 ```bash
@@ -179,6 +177,8 @@ Changes apply to the next job with no restart. The exception is a **new** api ag
 
 **Your plan decides which models run.** A model can be listed and still refused: on a ChatGPT plan, the Codex route runs gpt-6-astra and the gpt-5.6 models but refuses gpt-6-sol and gpt-6-luna. `army assign` and `agents update --probe` test the exact route a job takes, so they catch this before a job does.
 
+**Vendor terms and platform risk.** Every model call goes through [OpenClaw](https://github.com/openclaw/openclaw), and subscriptions are reached through each vendor's own CLI or login. We've read the terms that apply (see above), but using a personal subscription through a harness is exactly the kind of use vendors tighten, and a change in a vendor's terms or in OpenClaw can stop a subscription agent from working. Local models and API keys don't carry that risk. Plan on subscriptions as a convenience, not the only way your roles can run.
+
 **Picking an agent.** Build work goes to a sandboxed agent: `local`, an api key, Codex or Muse. `local` for a bounded change against a written spec with a test; your code never leaves your machine. An api or subscription agent when the work needs more than the local model, knowing it sends code to that vendor. That's a decision about where your source travels, separate from the trust boundary, which is the same for every agent. The General itself when the answer isn't known yet.
 
 ## The army: who does what
@@ -270,6 +270,18 @@ verification:
 
 `nomarmy validate` checks the file against the schema; `nomarmy scan --check` diffs it against what the repo actually contains.
 
+**Policy: what no job can skip.**
+
+```yaml
+policy:
+  require_verification: true       # every implement job needs a verification profile; only passing work commits
+  require_regression_check: true   # verify_regression can't be switched off per job
+```
+
+`nomarmy init` proposes both for new repos. Without them, a job with no verification profile still commits (flagged for review, not blocked), and the General decides per job whether to run the revert check. With them, those are the repo's rules, not the General's judgment calls, and since nomArmy reads this file only from your checkout, neither the General nor a worker can relax it.
+
+**Refactors.** Reverting a behavior-preserving change restores code that works, so the revert check can't prove anything about it. A job can declare `refactor: true` instead: nomArmy then commits it only if verification passes **and no test file was added, changed or deleted**. The existing tests passing unchanged is the evidence. A change that alters behavior has to alter tests to show it, so it can't pass as a refactor.
+
 **Add a check for what unit tests can't see.** A module left out of a deploy bundle passes every unit test and crashes at deploy. When `nomarmy init` sees a bundle or packaging step (Lambda asset scripts, SAM, Serverless, CDK), it suggests a profile that runs it and then imports each entry point from the built bundle.
 
 ### Languages and dependencies

package/e2e.sh

@@ -56,18 +56,35 @@ fi
 # bind-mounting paths under the host home directory, and the cleanup step
 # below bind-mounts this directory into a container.
 TMP="$(mktemp -d "$HOME/.nomarmy-e2e.XXXXXX")"
+# OpenClaw's own state for this run, also under $HOME, the way nomArmy's
+# real dispatch keeps it (--state-dir). Left unset, OpenClaw puts its
+# working files in the system temp folder, which the Podman sandbox can't
+# mount on macOS, and it uses the operator's main state, whose memory index
+# holds their past sessions.
+STATE="$(mktemp -d "$HOME/.nomarmy-e2e-state.XXXXXX")"
 
 cleanup() {
   local exit_code=$?
 
-  if [[ -n "${TMP:-}" && -d "$TMP" ]]; then
+  # OpenClaw leaves this run's sandbox container running; its name carries
+  # the hash recorded under the state dir (as nomArmy's job cleanup does).
+  if [[ -n "${STATE:-}" && -d "$STATE/state/sandbox/skills-workspaces" ]] && command -v podman >/dev/null 2>&1; then
+    for ws in "$STATE"/state/sandbox/skills-workspaces/workspace-*; do
+      [[ -d "$ws" ]] || continue
+      podman ps -a --filter "name=${ws##*/workspace-}" --format '{{.Names}}' 2>/dev/null \
+        | xargs -r podman rm -f -v >/dev/null 2>&1 || true
+    done
+  fi
+
+  for dir in "${TMP:-}" "${STATE:-}"; do
+  if [[ -n "$dir" && -d "$dir" ]]; then
 
     # OpenClaw's Podman sandbox may create files that the host user
     # cannot delete directly. Use a disposable container to clean
     # the temporary workspace first.
     if command -v podman >/dev/null 2>&1 && podman info >/dev/null 2>&1; then
       podman run --rm \
-        -v "$TMP:/cleanup" \
+        -v "$dir:/cleanup" \
         alpine:3.20 \
         sh -c '
           find /cleanup -mindepth 1 -maxdepth 1 -exec rm -rf -- {} + \
@@ -76,13 +93,14 @@ cleanup() {
         >/dev/null 2>&1 || true
     fi
 
-    rm -rf "$TMP" 2>/dev/null || true
+    rm -rf "$dir" 2>/dev/null || true
 
-    if [[ -d "$TMP" ]]; then
+    if [[ -d "$dir" ]]; then
       echo "WARN: E2E temporary directory could not be completely removed:"
-      echo "      $TMP"
+      echo "      $dir"
     fi
   fi
+  done
 
   exit "$exit_code"
 }
@@ -126,15 +144,29 @@ PROMPT='Fix the bug so npm test passes. Work only in the workspace. Run npm test
 
 OUT="$TMP/openclaw.json"
 
+# The same privacy settings every nomArmy job gets (lib/openclaw-run.mjs
+# withJobPrivacy): OpenClaw's memory search and session-memory hook off, so
+# nothing is indexed or sent for embedding.
+CONFIG="$STATE/openclaw.job.json"
+mkdir -p "$STATE/state"
+node --input-type=module -e '
+  import fs from "node:fs";
+  import { readOpenclawConfig } from "'"$ROOT"'/lib/openclaw-config.mjs";
+  import { withJobPrivacy } from "'"$ROOT"'/lib/openclaw-run.mjs";
+  fs.writeFileSync(process.argv[1], JSON.stringify(withJobPrivacy(readOpenclawConfig() ?? {})), { mode: 0o600 });
+' "$CONFIG"
+
 openclaw agent exec "$PROMPT" \
   --model "$NOMARMY_WORKER_PROVIDER/$NOMARMY_WORKER_MODEL" \
   --cwd "$TMP" \
+  --state-dir "$STATE/state" \
+  --config "$CONFIG" \
   --code-mode direct \
   --local-model-lean \
   --thinking off \
   --timeout 600 \
   --json \
-  > "$OUT"
+  > "$OUT" 2> "$STATE/openclaw.stderr.log"
 
 # Independent verification. We do not trust the worker's claim
 # that its implementation is correct.

package/lib/admission.mjs

@@ -0,0 +1,370 @@
+import fs from "node:fs";
+import path from "node:path";
+import { clampInt } from "./budget-state.mjs";
+import { checkBrief, assessAdmission, describeBudgets } from "./budget.mjs";
+import { parseStatusPorcelainZ, isRuntimeJunk } from "./git-record.mjs";
+import { readJson } from "./openclaw-run.mjs";
+import { readOpenClawTranscriptTail } from "./transcript.mjs";
+import { readClaudeSessionTranscript } from "./claude-transcript.mjs";
+import { notify } from "./notify.mjs";
+import { recentModelRefusal } from "./health.mjs";
+import { writeLease, removeLease, liveLeases, liveSlots, acquireSlot } from "./slots.mjs";
+import { loadRun, runTotals, runAdmissionProblems, recordRunJob, detectUsageLimit } from "./runs.mjs";
+import { agentProviderId, hostToolsImplementProblem } from "./agents.mjs";
+import { policyAdmissionProblems } from "./outcome.mjs";
+
+// `lane` is "local" (the local model on llama-server) or "remote" (an api
+// or subscription agent: the inference runs at the vendor). The local-slot
+// admission check must only ever count the local lane. A subscription job
+// used to land in "local" (the lane was decided by `pool` alone), so a
+// Claude or Codex job took llama-server's only slot and blocked local work
+// it never competed with -- reported from a real Senti run.
+export function jobLane(job) {
+  return job.pool || job.subscription_worker ? "remote" : "local";
+}
+
+// A static, operator-declared ceiling on how many remote jobs (api and
+// subscription agents) may run at once, independent of and additive to
+// currentMaxWorkers()'s local ceiling. Each still runs a sandbox and a
+// worktree on this machine, which is what this bounds; each agent's own
+// max_concurrent bounds its vendor. The env name predates agents.yml
+// (remote jobs were all "pool" jobs then) -- exactly the "more real concurrency, not just diversity"
+// benefit of spreading load across providers with their own separate rate
+// limits. Not rate-limit-aware (see config/providers.yml.example); read
+// fresh each call, matching currentMaxWorkers()'s own env-read pattern.
+export function currentMaxPoolWorkers() {
+  return clampInt(process.env.NOMARMY_MAX_POOL_WORKERS, 1, 32, 4);
+}
+
+// Pure partition of a batch's ORIGINAL indices by lane -- pulled out of
+// local_workers' handler so this specific invariant (every job lands in
+// exactly one lane, indices preserved) is directly testable without also
+// exercising the full async dispatch/mapLimit machinery around it. This is
+// the exact split that used to not exist at all: every job in a batch
+// shared one `parallel` slot count derived only from the local ceiling,
+// which let an all-pool batch ignore NOMARMY_MAX_POOL_WORKERS entirely.
+export function splitJobsByLane(jobs) {
+  const localIndices = [], remoteIndices = [];
+  jobs.forEach((j, i) => (jobLane(j) === "remote" ? remoteIndices : localIndices).push(i));
+  return { localIndices, remoteIndices };
+}
+
+export function toolText(text, isError = false) { return { content: [{ type: "text", text }], isError }; }
+
+// The capacity snapshot only when a problem is about capacity: a
+// model_not_found or bad-field refusal came with ~60 lines of local-model
+// capacity JSON that had nothing to do with it (a Senti review).
+export function refusalText(problems, snapshot) {
+  const aboutCapacity = problems.some((p) => /capacity|memory|context|slot|MAX_(POOL_)?WORKERS|max_concurrent/i.test(p));
+  return `REFUSED - nothing was started.\n${problems.map(p => `- ${p}`).join("\n")}${aboutCapacity ? `\n\nCapacity right now:\n${JSON.stringify(snapshot(), null, 2)}` : ""}`;
+}
+
+export function createJobRuntime(deps) {
+  const { projectDir, stateRoot, jobsRoot, runsRoot, leasesRoot, slotsRoot, run, currentMaxWorkers, slug, agentsConfig, modelCatalogReady, budgetsForJob, resolveSubscriptionSelection, executeJob, subscriptionJobFieldProblems, repoPolicy, jobArgs } = deps;
+
+  // Staggers concurrent job starts by `slot * staggerMs` before each runner
+  // begins pulling work. Verified root cause: two OpenClaw sandbox containers
+  // created in the same instant reliably hit a podman/crun race ("crun: mount
+  // `devpts` to `dev/pts`: Invalid argument"), even with ample host and VM
+  // memory free -- reproduced twice, unrelated to memory pressure. A short
+  // stagger between concurrent `podman create`/`run` invocations gives crun's
+  // container-creation critical section enough separation to not collide.
+  //
+  // That original fix/measurement was only verified at 2-way concurrency.
+  // Re-verified at 4-way (this session): the same race still fired with the
+  // stagger active -- one job failed on this exact error within 5.2s of a
+  // 4-job concurrent dispatch. 1500ms of separation between ADJACENT slot
+  // starts is not consistently enough once 4 containers are all competing for
+  // the same crun critical section under real system load, not 2. Raised to
+  // 3000ms as a direct response to that reproduction; RETRY_TRANSIENT_SANDBOX_ERRORS
+  // below is the second, more robust layer -- no fixed stagger value can be
+  // proven sufficient for every load condition, only likely-sufficient.
+  const WORKER_START_STAGGER_MS = Number.parseInt(process.env.NOMARMY_WORKER_START_STAGGER_MS ?? "", 10) || 3000;
+
+  // ---------------------------------------------------------------------------
+  // Job registry and admission. Every job, blocking or backgrounded, is tracked
+  // here so capacity counts all of them. Admission re-reads the budget (a
+  // restarted llama-server or changed profile is picked up) and refuses under
+  // memory pressure rather than shrinking the brief and hoping.
+  // ---------------------------------------------------------------------------
+  const activeJobs = new Map();
+  // Counted across every session on this machine, not just this server's own
+  // jobs: each coordinator session runs its own server, and per-process
+  // counts let six sessions each run their "one" local job at once. Idle
+  // sessions hold no leases and count for nothing.
+  function runningCount(lane = null) {
+    return liveLeases(leasesRoot, lane ? { lane } : {}).length;
+  }
+
+  /** An api or subscription agent's max_concurrent (1 for a subscription, 2 for api by default); null for local. */
+  function agentMaxConcurrent(agentName) {
+    try {
+      const agent = agentsConfig().agents[agentName];
+      return agent && agent.kind !== "local" ? agent.max_concurrent ?? (agent.kind === "subscription" ? 1 : 2) : null;
+    } catch { return null; }
+  }
+
+  /**
+   * Run a job holding one of its agent's max_concurrent slots, machine-wide
+   * (lib/slots.mjs), so `max_concurrent: 1` on a subscription means one job
+   * on it across every session -- per-session counting never enforced that,
+   * and for subscriptions the count was never checked at all. `waitMs` lets a
+   * batch queue for a slot instead of failing.
+   */
+  function withAgentSlot(args, jobId, fn, { waitMs = 0 } = {}) {
+    const max = args.agentName ? agentMaxConcurrent(args.agentName) : null;
+    if (!max) return fn();
+    return (async () => {
+      const slot = await acquireSlot(slotsRoot, args.agentName, max, { jobId, waitMs });
+      if (!slot) throw new Error(`agent "${args.agentName}" is at its max_concurrent (${max}) across every nomArmy session on this machine; try again when one of its jobs finishes`);
+      try { return await fn(); } finally { slot.release(); }
+    })();
+  }
+  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
+    // admission counts it (runningCount); released however the job ends.
+    // `repo` lets each session's status line show its own repo's jobs.
+    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; },
+      e => { entry.settled = true; entry.error = e; release(); notifyJobFinished(entry, null, e); throw e; });
+    entry.promise.catch(() => {});
+    activeJobs.set(jobId, entry);
+    return entry;
+  }
+  /**
+   * A desktop notification when a job ends (lib/notify.mjs), so the person
+   * watching hears about it from any coordinator without polling.
+   */
+  function notifyJobFinished(entry, result, error) {
+    if (!entry.lane) return; // only tracked jobs, never internal helpers
+    const m = result?.manifest ?? {};
+    const outcome = error ? "failed" : String(m.outcome ?? (result?.ok ? "done" : "finished")).toLowerCase().replace(/_/g, " ");
+    const who = entry.agent ? `${entry.agent}${entry.model ? `/${entry.model}` : ""}` : "local model";
+    const took = Math.round((Date.now() - Date.parse(entry.startedAt)) / 60000);
+    const ok = !error && (result?.ok || m.coordinatorStatus === "complete");
+    notify(`nomArmy: ${entry.role ?? entry.mode ?? "job"} ${ok ? "done" : outcome}`, `${entry.workerId ?? entry.jobId} on ${who}: ${outcome} after ${took}m. ${ok ? "Ready for the General's review." : "Needs a look."}`);
+  }
+  function capacitySnapshot() {
+    const admission = assessAdmission({ hardware: deps.budgetState.hardwareSnapshot, runningJobs: runningCount("local"), slots: deps.budgetState.contextInfo.slots, maxWorkers: currentMaxWorkers() });
+    return {
+      // The local model's budget. An api or subscription job's scales with
+      // its own model; local_worker_start reports that job's.
+      budgets: { ...deps.budgetState.budgets, describe: describeBudgets(deps.budgetState.budgets) },
+      context: deps.budgetState.contextInfo,
+      admission,
+      memory: deps.budgetState.hardwareSnapshot?.memory ?? null,
+      running: [...activeJobs.values()].filter(j => !j.settled).map(j => ({ jobId: j.jobId, workerId: j.workerId, mode: j.mode, lane: j.lane, startedAt: j.startedAt, phase: readJson(path.join(jobsRoot, j.jobId, "status.json"))?.phase ?? "starting" })),
+      maxWorkers: currentMaxWorkers(),
+      remote: { running: runningCount("remote"), maxWorkers: currentMaxPoolWorkers(), note: "api and subscription agents; each agent's own max_concurrent also applies" }
+    };
+  }
+  async function admit(jobs) {
+    await deps.budgetState.refresh();
+    if (jobs.some((j) => jobLane(j) === "remote")) await modelCatalogReady();
+    const problems = [];
+    // A pool-routed job is checked against that pool's OWN (model-dependent)
+    // budget, not the local-derived global one -- see budgetsForPool. Which
+    // specific entry pickProvider will land on isn't known yet at admission
+    // time, so this is the conservative minimum across the pool's currently
+    // available entries, not any one entry's precise number. A
+    // subscription_worker job budgets against that one named entry directly
+    // (see budgetsForSubscriptionWorker) -- there's no "which entry" unknown
+    // the way a weighted pool has, since the name given IS the entry.
+    jobs.forEach((j, i) => {
+      const jobBudgets = budgetsForJob(j);
+      for (const p of checkBrief(j, jobBudgets)) problems.push(jobs.length > 1 ? `job ${i + 1}: ${p}` : p);
+    });
+    // verify_regression re-runs `verification`; with no profile set there is
+    // nothing to re-run. Refuse before starting anything, matching every other
+    // admission check here, rather than silently no-op at runtime.
+    jobs.forEach((j, i) => {
+      if (j.verify_regression && !j.verification) {
+        problems.push(`${jobs.length > 1 ? `job ${i + 1}: ` : ""}verify_regression requires a verification profile; there is nothing to run twice without one`);
+      }
+    });
+    // subscription_worker/on_behalf_of: the owner-match attestation refusal
+    // happens here, before a container is ever provisioned -- matching how a
+    // bad `pool` name is already caught before dispatch, not mid-flight. Only
+    // attempted once the plain field-presence problems above are already
+    // clean, so a missing on_behalf_of is never reported twice in two
+    // different shapes.
+    jobs.forEach((j, i) => {
+      const fieldProblems = subscriptionJobFieldProblems(j);
+      for (const p of fieldProblems) problems.push(jobs.length > 1 ? `job ${i + 1}: ${p}` : p);
+      if (fieldProblems.length === 0 && j.on_behalf_of) {
+        try {
+          if (j.subscription_worker) resolveSubscriptionSelection(j.subscription_worker, j.on_behalf_of, j.reasoning, { model: j.model });
+        } catch (error) { problems.push(jobs.length > 1 ? `job ${i + 1}: ${error.message}` : error.message); }
+      }
+    });
+    // The repo's own policy: verification required, revert check required.
+    const policy = repoPolicy();
+    jobs.forEach((j, i) => { for (const p of policyAdmissionProblems(j, policy)) problems.push(`${jobs.length > 1 ? `job ${i + 1}: ` : ""}${p}`); });
+    // An implement job on an agent whose own tools run on this machine (the
+    // Claude CLI) isn't bounded by the sandbox, so it's refused unless that
+    // agent says allow_host_tools (lib/agents.mjs). Scouts and reviews still run.
+    jobs.forEach((j, i) => {
+      if (!j.agentName || (j.mode ?? "implement") !== "implement") return;
+      let problem = null;
+      try { problem = hostToolsImplementProblem(j.agentName, agentsConfig().agents[j.agentName]); } catch { return; }
+      if (problem) problems.push(`${jobs.length > 1 ? `job ${i + 1}: ` : ""}${problem}`);
+    });
+    // A model its vendor refused on a job today, with nothing working on it
+    // since, isn't sent another job (lib/health.mjs recentModelRefusal).
+    jobs.forEach((j, i) => {
+      if (!j.agentName || !j.model) return;
+      let provider = null;
+      try { provider = agentProviderId(agentsConfig().agents[j.agentName]); } catch { return; }
+      if (!provider) return;
+      const refusal = recentModelRefusal(stateRoot, `${provider}/${j.model}`);
+      if (refusal) problems.push(`${jobs.length > 1 ? `job ${i + 1}: ` : ""}model_not_found: ${provider}/${j.model} was refused on an earlier job today and hasn't worked since, so this job wasn't sent. Use another model (the job's \`model\`, or \`nomarmy army assign\`); \`nomarmy army assign <role> ${j.agentName} ${j.model}\` re-tests it, and a passing test clears this.`);
+    });
+    // An agent's max_concurrent, machine-wide. Batch jobs on the same agent
+    // queue for its slot at launch instead (withAgentSlot's waitMs).
+    if (jobs.length === 1) {
+      const [j] = jobs;
+      const max = j.agentName ? agentMaxConcurrent(j.agentName) : null;
+      const held = max ? liveSlots(slotsRoot, j.agentName) : 0;
+      if (max && held >= max) problems.push(`not admitted (capacity): agent "${j.agentName}" already has ${held} job(s) running across this machine's nomArmy sessions, at its max_concurrent of ${max}`);
+    }
+    // A job in a /feature run: the run's own limits and paused agents.
+    jobs.forEach((j, i) => {
+      if (!j.run_id) return;
+      try {
+        const run = loadRun(runsRoot, j.run_id);
+        if (run.repo !== projectDir) problems.push(`${jobs.length > 1 ? `job ${i + 1}: ` : ""}run "${run.id}" belongs to ${run.repo}, not this repository`);
+        const running = liveLeases(leasesRoot, { runId: run.id }).length + jobs.slice(0, i).filter((o) => o.run_id === run.id).length;
+        for (const p of runAdmissionProblems(run, { agentName: j.agentName ?? "local", running })) problems.push(jobs.length > 1 ? `job ${i + 1}: ${p}` : p);
+      } catch (error) { problems.push(jobs.length > 1 ? `job ${i + 1}: ${error.message}` : error.message); }
+    });
+    // Slot capacity only concerns local jobs: a remote job's inference runs
+    // at its vendor and never competes for llama-server's slots. Free memory
+    // still applies to every job (each one runs a local sandbox), so a
+    // remote-only batch is checked for memory alone. Remote jobs have their
+    // own, additive ceiling (currentMaxPoolWorkers).
+    const anyLocal = jobs.some((j) => jobLane(j) === "local");
+    const admission = anyLocal
+      ? assessAdmission({ hardware: deps.budgetState.hardwareSnapshot, runningJobs: runningCount("local"), slots: deps.budgetState.contextInfo.slots, maxWorkers: currentMaxWorkers() })
+      : assessAdmission({ hardware: deps.budgetState.hardwareSnapshot, runningJobs: 0, slots: null, maxWorkers: Infinity });
+    if (!admission.admit) problems.push(...admission.reasons.map(r => `not admitted (${admission.level}): ${r}`));
+    if (jobs.some((j) => jobLane(j) === "remote")) {
+      const remoteCeiling = currentMaxPoolWorkers(), runningRemote = runningCount("remote");
+      if (runningRemote >= remoteCeiling) {
+        problems.push(`not admitted (capacity): ${runningRemote} remote job(s) (api or subscription agents) already running, at NOMARMY_MAX_POOL_WORKERS=${remoteCeiling}`);
+      }
+    }
+    return { problems, admission };
+  }
+
+  function refusal(problems) {
+    return toolText(refusalText(problems, capacitySnapshot), true);
+  }
+  /** A run's totals and warnings, for a tool response. */
+  function runBrief(runId) {
+    try {
+      const run = loadRun(runsRoot, runId);
+      const totals = runTotals(run);
+      return { id: run.id, status: run.status, limits: run.limits, used: totals.used, warnings: totals.warnings };
+    } catch (error) { return { id: runId, error: error.message }; }
+  }
+
+  /**
+   * Record a finished job into its run. A usage-limit message is looked for
+   * only in error text (OpenClaw's failure envelope, and the error lines of
+   * a thrown run), never in the worker's report or tool output, where "rate
+   * limit" may just be the code under review.
+   */
+  function recordJobInRun(args, jobId, result, error = null) {
+    if (!args.run_id) return;
+    const kind = args.pool ? "api" : args.subscription_worker ? "subscription" : "local";
+    const m = result?.manifest ?? {};
+    const errorLines = [m.worker?.error, error?.message,
+      ...String(m.workerError ?? "").split(/\r?\n/).filter((l) => /error|limit|429/i.test(l))].filter(Boolean).join("\n");
+    const usageLimit = kind === "local" ? null : detectUsageLimit(errorLines);
+    try {
+      const before = runTotals(loadRun(runsRoot, args.run_id)).warnings;
+      const updated = recordRunJob(runsRoot, args.run_id, {
+        jobId, agent: args.agentName ?? "local", kind, model: args.model ?? null, role: args.armyRole ?? null, mode: args.mode,
+        outcome: m.outcome ?? (error ? "ERROR" : null), costUsd: m.metrics?.worker_cost_usd ?? null,
+        tokens: m.metrics?.worker_tokens_total ?? null, usageLimit,
+      });
+      // A limit crossed or an agent paused by this job is worth interrupting for.
+      const fresh = runTotals(updated).warnings.filter((w) => !before.includes(w) && /OVER|paused/.test(w));
+      if (fresh.length) notify(`nomArmy run ${updated.name}: stopped short`, fresh.join("; "));
+    } catch (recordError) {
+      fs.appendFileSync(path.join(jobsRoot, jobId, "coordinator.log"), `${new Date().toISOString()} could not record into run ${args.run_id}: ${recordError.message}\n`);
+    }
+  }
+  function trackInRun(args, entry) {
+    if (args.run_id) entry.promise.then((r) => recordJobInRun(args, entry.jobId, r), (e) => recordJobInRun(args, entry.jobId, null, e));
+    return entry;
+  }
+  function launch(args) {
+    const workerId = args.worker_id || null;
+    const jobId = slug(workerId || (args.mode === "scout" ? "scout" : "worker"));
+    return trackInRun(args, track(jobId, { mode: args.mode, workerId: workerId || jobId, lane: jobLane(args), agent: args.agentName ?? null, runId: args.run_id ?? null, role: args.armyRole ?? null, model: args.model ?? null },
+      withAgentSlot(args, jobId, () => executeJob({ ...jobArgs(args, workerId), jobId }))));
+  }
+  // Best-effort progress signal for a job still mid-run: a plain "phase: worker,
+  // elapsed: Ns" told a caller nothing about whether the worker was still
+  // reading or already editing, short of running `git status` on the worktree
+  // by hand. Both lookups here are read-only and disposable -- a job's worktree
+  // mid-write or a transcript sqlite file mid-append can legitimately fail to
+  // read, and that must never fail the status call, only omit the field.
+  async function liveProgress(jobDir) {
+    const out = {};
+    try {
+      const worktree = path.join(jobDir, "worktree");
+      if (fs.existsSync(worktree)) {
+        // --untracked-files=normal, not all: "all" descends into every
+        // untracked directory (a virtualenv, a cache) a job creates. Bounded:
+        // a live progress read must never hold anything up.
+        const statusOut = (await run("git", ["status", "--porcelain=v1", "-z", "--untracked-files=normal"], { cwd: worktree, trim: false, timeoutMs: 10000 })).stdout;
+        // Same runtime-junk filter as collectGitRecord/makeIdleDiffTick: .npm/
+        // etc. is the sandbox's own churn, not the worker's progress, and
+        // counting it made a job that had made zero real edits report
+        // filesChangedLive: 1 anyway.
+        out.filesChangedLive = parseStatusPorcelainZ(statusOut).map(e => e.file).filter(f => !isRuntimeJunk(f)).length;
+      }
+    } catch { /* worktree not ready yet, or mutated mid-read; omit */ }
+    try {
+      const stateDir = path.join(jobDir, "runtime", "state");
+      const transcript = await readOpenClawTranscriptTail(stateDir, { limit: 6 });
+      if (transcript.available) {
+        const last = transcript.toolCalls.at(-1);
+        if (last) out.lastTool = { tool: last.tool, target: last.path ?? last.command ?? null };
+      }
+      // A claude-cli worker's tools only appear in Claude Code's own session
+      // transcript, not OpenClaw's.
+      if (!out.lastTool) {
+        const startedMs = Date.parse(readJson(path.join(jobDir, "status.json"))?.startedAt ?? "") || 0;
+        const claude = readClaudeSessionTranscript(path.join(jobDir, "worktree"), { sinceMs: startedMs, tailBytes: 262144 });
+        const last = claude.available ? claude.toolCalls.at(-1) : null;
+        if (last) { out.lastTool = { tool: last.tool, target: last.path ?? last.command ?? null }; out.toolCallsLive = claude.toolCalls.length; }
+      }
+    } catch { /* transcript not created yet, or locked mid-write; omit */ }
+    return out;
+  }
+
+  async function summarize(entry, files, jobDir = null) {
+    const status = files.status, meta = files.meta ?? files.failure;
+    const elapsedSeconds = status?.startedAt ? Math.round((Date.now() - Date.parse(status.startedAt)) / 1000) : entry ? Math.round((Date.now() - Date.parse(entry.startedAt)) / 1000) : null;
+    const out = { jobId: entry?.jobId ?? status?.jobId ?? meta?.jobId ?? null, workerId: entry?.workerId ?? status?.workerId ?? meta?.workerId ?? null,
+      mode: entry?.mode ?? status?.mode ?? meta?.mode ?? null, state: null, phase: status?.phase ?? "starting", elapsedSeconds,
+      timeoutSeconds: status?.timeoutSeconds ?? null, coordinatorStatus: meta?.coordinatorStatus ?? null, outcome: meta?.outcome ?? null,
+      reviewRequired: meta?.reviewRequired ?? null, issues: (meta?.issues ?? []).slice(0, 6), worktree: meta?.worktree ?? null, branch: meta?.branch ?? null,
+      commit: meta?.commit?.sha ?? null, scout: meta?.scout ? { supported: meta.scout.supported, unsupported: meta.scout.unsupported } : null };
+    if (entry && !entry.settled) out.state = "running";
+    else if (entry?.error) { out.state = "failed"; out.error = String(entry.error.message ?? entry.error).split("\n")[0]; }
+    else if (meta) out.state = "finished";
+    else if (status?.state === "running") { out.state = status.serverPid === process.pid ? "running" : "orphaned"; if (out.state === "orphaned") out.error = `the MCP server that ran this job (pid ${status.serverPid}) is gone; outcome unknown, see the job directory logs`; }
+    else out.state = "unknown";
+    if (out.state === "running" && jobDir) Object.assign(out, await liveProgress(jobDir));
+    return out;
+  }
+
+  return { WORKER_START_STAGGER_MS, activeJobs, runningCount, agentMaxConcurrent, withAgentSlot, track, notifyJobFinished, capacitySnapshot, admit, refusal, runBrief, recordJobInRun, trackInRun, launch, liveProgress, summarize };
+}