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

package/mcp/server.mjs

@@ -32,8 +32,37 @@ import { liveLeases } from "../lib/slots.mjs";
 import { createRun, loadRun, runTotals, finishRun, resolveRunLimits, describeLoweredLimits } from "../lib/runs.mjs";
 import { agentDispatchFields, resolveAgentModel, agentProviderId, describeAgent } from "../lib/agents.mjs";
 import { OUTCOMES, COORDINATOR_STATUS_BY_OUTCOME } from "../lib/outcomes.mjs";
+import { readUsageSnapshots, usageStatus, usageDisplayText, refreshStaleOverLimitReadings } from "../lib/usage-limits.mjs";
+import { modelRefusals } from "../lib/health.mjs";
+import { retryRefusedModelsInBackground } from "../lib/refusal-retry.mjs";
+import { podmanProblem, podmanVmStartedAt } from "../lib/podman-health.mjs";
+import { restartNotice } from "../lib/install-freshness.mjs";
+import { requestJobStop } from "../lib/openclaw-run.mjs";
+import { loadJobRecords, computeStats, formatStats, formatStatsSummary, parseSince, resolveRepo, agentLookup } from "../lib/stats.mjs";
+import { shareMarkdown } from "../lib/share.mjs";
+import { recentSuggestions } from "../lib/suggestions.mjs";
+import { probeModel } from "../lib/model-probe.mjs";
+import { jevSettings, judgeSettings } from "../lib/validators.mjs";
+import { agentRunsToolsOnHost } from "../lib/dispatch-schema.mjs";
 import { createBuildMetrics, resolveOutcome, finalText, workerMetadata, usageMetrics, policyAdmissionProblems, applyRefactorContract, applyVerificationPolicy, resolveVerifyRegression } from "../lib/outcome.mjs";
-import { compactJobRecord, formatResult, formatUnion, testChangeBanner, regressionCheckBanner, decomposeOverlapBanner } from "../lib/job-format.mjs";
+import { jobLabel, compactJobRecord, formatResult, reportView, formatUnion, testChangeBanner, regressionCheckBanner, decomposeOverlapBanner } from "../lib/job-format.mjs";
+import { ensureOpenClawOnPath } from "../lib/openclaw-path.mjs";
+import { THINKING_LEVELS } from "../lib/thinking.mjs";
+import { samePath } from "../lib/same-path.mjs";
+import { withWindowsPaths, dropWindowsPath } from "../lib/wsl.mjs";
+export { withWindowsPaths };
+
+function coordinatorJson(value) { return JSON.stringify(withWindowsPaths(value), null, 2); }
+function coordinatorResult(result) {
+  const paths = withWindowsPaths({ jobDir: result.jobDir, worktree: result.manifest?.worktree });
+  const windows = ["jobDirWindows", "worktreeWindows"].filter(key => paths[key]).map(key => `${key}: ${paths[key]}`);
+  return formatResult(withWindowsPaths(result)) + (windows.length ? `\n\n${windows.join("\n")}` : "");
+}
+
+// Inside WSL, only the distro's own tools (see lib/wsl.mjs).
+dropWindowsPath();
+// OpenClaw in ~/.npm-global/bin (no writable npm prefix) is found without the operator editing PATH.
+ensureOpenClawOnPath();
 
 export { run, mapLimit };
 export { readsMeasurable, measureReads };
@@ -54,6 +83,7 @@ export { TEST_PATH_PATTERNS, isTestPath, testPatternFor, classifyTestChanges, de
 // package.json to the same relative location next to the installed
 // mcp/server.mjs, so this resolves identically in a dev checkout or an
 // installed copy.
+const SERVER_STARTED_MS = Date.now();
 const VERSION = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
 // Sent to every coordinator on connect, so no project needs a copied CLAUDE.md.
 const server = new McpServer({ name: "nomarmy-local-worker", version: VERSION }, { instructions: COORDINATOR_INSTRUCTIONS });
@@ -77,7 +107,8 @@ function slug(prefix = "local") {
 }
 async function assertRepo() {
   const root = await git(["rev-parse", "--show-toplevel"]);
-  if (path.resolve(root) !== projectDir) throw new Error(`CLAUDE_PROJECT_DIR must be the Git root. Expected ${root}, got ${projectDir}`);
+  // Git may print a long, forward-slashed path while Windows supplies an 8.3 path.
+  if (!samePath(root, projectDir)) throw new Error(`CLAUDE_PROJECT_DIR must be the Git root. Expected ${root}, got ${projectDir}`);
 }
 async function resolveBase(baseRef) {
   const ref = baseRef || "HEAD";
@@ -208,6 +239,17 @@ export function makeHeartbeatTick(jobDir) { return heartbeatTick(jobDir, livePro
 // Senti run none were tagged, so a 4-hour run went 8.46 hours unchecked.
 let activeRunId = null;
 
+export const DEFAULT_TIMEOUT_SECONDS = 600;
+export const REVIEW_SCOUT_TIMEOUT_SECONDS = 1200;
+/** A review scout (reviews set, or a review-phase role) gets longer: reviews trace across the codebase. */
+export function defaultTimeoutSeconds(job, getArmyFn) {
+  if (job.mode !== "scout") return DEFAULT_TIMEOUT_SECONDS;
+  if (job.reviews) return REVIEW_SCOUT_TIMEOUT_SECONDS;
+  if (!job.army_role) return DEFAULT_TIMEOUT_SECONDS;
+  try { return getArmyFn()?.roles?.[job.army_role]?.phase === "review" ? REVIEW_SCOUT_TIMEOUT_SECONDS : DEFAULT_TIMEOUT_SECONDS; }
+  catch { return DEFAULT_TIMEOUT_SECONDS; }
+}
+
 export function expandJobs(jobs, { getArmy = currentArmy, getAgents = () => agentsConfig().agents, getActiveRun = () => activeRunId, env = process.env } = {}) {
   const problems = [];
   let army = null, agents = null;
@@ -215,6 +257,11 @@ export function expandJobs(jobs, { getArmy = currentArmy, getAgents = () => agen
   const expanded = jobs.map((job, i) => {
     try {
       let j = runId && !job.run_id ? { ...job, run_id: runId } : job;
+      if (j.timeout_seconds == null) j = { ...j, timeout_seconds: defaultTimeoutSeconds(j, () => (army ??= getArmy().army)) };
+      if (j.mode === "verify") {
+        const { agent, model, army_role, on_behalf_of, agentName, pool, subscription_worker, roleModel, ...rest } = j;
+        return { ...rest, ...(army_role ? { armyRole: army_role } : {}) };
+      }
       if (j.army_role) { army ??= getArmy().army; j = expandArmyRole(j, army); }
       const { agent, roleModel = null, ...rest } = j;
       if (!agent) {
@@ -228,6 +275,7 @@ export function expandJobs(jobs, { getArmy = currentArmy, getAgents = () => agen
       const out = { ...rest, ...fields, agentName: agent };
       if (model) out.model = model; else delete out.model;
       if (!fields.subscription_worker) delete out.on_behalf_of;
+      if (out.mode === "scout" && out.report == null && (fields.pool || fields.subscription_worker)) out.report = "full";
       out.profile ??= "coder";
       return out;
     } catch (error) {
@@ -244,7 +292,12 @@ const verificationFlow = createVerificationFlow({
 const { registerVerificationRunner, normalizeVerification, runIndependentVerification, runRegressionCheck, selectUnionCandidates, buildUnionBranch } = verificationFlow;
 export { registerVerificationRunner, normalizeVerification, runRegressionCheck, selectUnionCandidates, buildUnionBranch };
 
+// Podman checks, wired at startup below (a test importing this module gets none).
+let podmanChecks = null;
 const { executeJob, executeImplement, executeScout, executeDecompose } = createExecutor({
+  podmanVmStartedAt: () => podmanChecks?.vmStartedAt() ?? null,
+  jevSettings: () => jevSettings(),
+  judgeSettings: () => judgeSettings({ agents: agentsConfig().agents, providerOf: agentProviderId, runsOnHost: agentRunsToolsOnHost }),
   VERSION, projectDir, jobsRoot, run, git, gitRaw,
   collectGitRecord, createCoordinatorCommit, ensureJobsRoot, slug, assertRepo,
   resolveBase, workerModelThinkingSupported, budgetState, execution, buildMetrics,
@@ -254,9 +307,11 @@ const { executeJob, executeImplement, executeScout, executeDecompose } = createE
 });
 export { executeJob };
 
-const { WORKER_START_STAGGER_MS, activeJobs, runningCount, agentMaxConcurrent, withAgentSlot, track, notifyJobFinished, capacitySnapshot, admit, refusal, runBrief, recordJobInRun, trackInRun, launch, liveProgress, summarize } = createJobRuntime({
+const { WORKER_START_STAGGER_MS, activeJobs, runningCount, agentMaxConcurrent, withAgentSlot, track, notifyJobFinished, capacitySnapshot, displayedCapacity, admit, refusal, runBrief, recordJobInRun, trackInRun, launch, liveProgress, summarize } = createJobRuntime({
   projectDir, stateRoot, jobsRoot, runsRoot, leasesRoot, slotsRoot, run, currentMaxWorkers, slug, agentsConfig, modelCatalogReady, budgetsForJob, resolveSubscriptionSelection, executeJob, subscriptionJobFieldProblems, repoPolicy, jobArgs,
   env: process.env, budgetState, getActiveRunId: () => activeRunId,
+  sandboxProblem: () => podmanChecks?.problem() ?? null,
+  probeModel,
 });
 export { runningCount, track };
 
@@ -272,20 +327,24 @@ export const jobSchema = z.object({
   verify_regression: z.boolean().optional().describe(
     "implement only: after the diff passes `verification` and touches production files, temporarily revert just those production files, re-run the SAME verification profile (expected to fail without the fix), then restore them. A re-run that still PASSES proves no test would catch this regression, and the outcome is downgraded to NEEDS_REVIEW regardless of the worker's report -- never silently committed as done. This is the ONLY mechanism that catches a verification profile that passes for the wrong reason (a test-selection flag that accidentally excludes the changed file's own tests reports a real, honest, green run that never touched the diff -- exit-code checking alone cannot see the difference). Defaults to true whenever `verification` is set, since that gap is exactly what nomArmy's trust boundary claims to close; pass `false` explicitly to skip the doubled wall-clock cost (can matter on repos with thousands of tests) and accept the risk instead. No effect with no `verification` profile -- there is nothing to re-run. Ignored by scouts."
   ),
-  mode: z.enum(["scout", "implement", "decompose"]).default("implement").describe("implement: edit in an isolated worktree, coordinator commits on a valid report. scout: read-only research; every finding must cite [path:start-end] and nomArmy attaches the cited lines after verifying them against the base commit. decompose: read-only; proposes 2+ independent, evidence-grounded subtasks for a broad objective instead of doing everything in one worker turn. Never auto-dispatched -- the proposal is reviewed like a scout's findings, and the coordinator makes its own separate dispatch call with whatever subtasks it chooses to use."),
+  mode: z.enum(["scout", "implement", "decompose", "verify"]).default("implement").describe("verify: run a required verification profile with no worker and no model tokens; base_ref selects the branch or commit (default current HEAD), task is a short record label, agent/model are unused and army_role is only a label. implement: edit in an isolated worktree, coordinator commits on a valid report. scout: read-only research; every finding must cite [path:start-end] and nomArmy attaches the cited lines after verifying them against the base commit. decompose: read-only; proposes 2+ independent, evidence-grounded subtasks for a broad objective instead of doing everything in one worker turn. Never auto-dispatched -- the proposal is reviewed like a scout's findings, and the coordinator makes its own separate dispatch call with whatever subtasks it chooses to use."),
   base_ref: z.string().optional(),
-  timeout_seconds: z.number().int().min(30).max(1800).default(600),
-  reasoning: z.enum(["low", "medium", "high"]).default("medium").describe("Thinking level passed to the worker model. On the local model it takes effect when that model supports thinking (NOMARMY_MODEL_THINKING); on an api or subscription agent it applies per that agent's own `thinking` setting (false = off, a fixed level = always that level). Default is medium, not high, on real measured evidence: on an identical ticket, gpt-oss-20b at high took 318s with 21 tool calls and 4 failures, and at medium took 62s with 9 calls and 0 failures -- high did not produce a better answer, it thrashed. A separate open-ended task made Qwen3.6-27B time out completely at high (630s, zero output) and succeed at medium. Do not raise this to high by default reasoning that more thinking should help -- it has only ever hurt or timed out in testing so far. Reach for high only after a task has already failed once at medium and the failure looks like an under-thinking problem specifically (wrong root cause, not a formatting or scope issue)."),
+  timeout_seconds: z.number().int().min(30).max(1800).optional().describe("Default 600; 1200 for a review scout (one with `reviews`, or an army role in the review phase), since a real security review read for the full 10 minutes and was cut off."),
+  reasoning: z.enum(THINKING_LEVELS).default("medium").describe("Thinking level passed to the worker model: off, minimal, low, medium, high, xhigh, adaptive, max or ultra (the higher ones only where the vendor offers them, e.g. xhigh on Codex models; a level the model lacks falls back once to its nearest supported level). Higher levels spend a subscription's usage limits faster. On the local model it takes effect when that model supports thinking (NOMARMY_MODEL_THINKING); on an api or subscription agent it applies per that agent's own `thinking` setting (false = off, a fixed level = always that level). Default is medium, not high, on real measured evidence: on an identical ticket, gpt-oss-20b at high took 318s with 21 tool calls and 4 failures, and at medium took 62s with 9 calls and 0 failures -- high did not produce a better answer, it thrashed. A separate open-ended task made Qwen3.6-27B time out completely at high (630s, zero output) and succeed at medium. Do not raise this to high by default reasoning that more thinking should help -- it has only ever hurt or timed out in testing so far. Reach for high only after a task has already failed once at medium and the failure looks like an under-thinking problem specifically (wrong root cause, not a formatting or scope issue)."),
   agent: z.string().regex(/^[A-Za-z0-9._-]{1,64}$/).optional().describe("Run on this agent from the operator's agents.yml, by name (e.g. \"codex\", \"grok\", \"local\"): the local model, a metered api key, or one person's subscription. Omit agent and army_role to use the local model. Refuses an unknown name, never falls back. Mutually exclusive with army_role. A subscription agent also requires on_behalf_of."),
   model: z.string().regex(/^\S{1,200}$/).optional().describe("The model to run on the job's agent (an api or subscription agent), e.g. \"gpt-6-sol\". Overrides the role's model and the agent's default. Required when the role's model is \"auto\" or the agent has no default. The `army` tool lists each agent's models. Refused on the local agent, whose model `nomarmy model` sets."),
   run_id: z.string().regex(/^run-[a-z0-9-]{1,80}$/).optional().describe("The /feature run this job belongs to (from run_start). Admission then enforces the run's limits (jobs, api spend, hours) and refuses an agent the run has paused after a vendor usage-limit error; the finished job is recorded into the run."),
-  report: z.enum(["brief", "standard", "full"]).optional().describe("How much the worker may report back, capped by its agent's tier: brief (today's local-sized report), standard (the default), full (the frontier ceiling: about 2k tokens for implement, 4k for a scout). The report lands in your own context and is re-read every later turn, so ask for full only when the job's findings are the point (a broad review). No effect on the local model, whose caps are calibrated."),
+  report: z.enum(["brief", "standard", "full"]).optional().describe("How much the worker may report back, capped by its agent's tier: brief (today's local-sized report), standard (the default), full (the frontier ceiling: about 2k tokens for implement, 4k for a scout). An api or subscription scout defaults to full because its findings are the point; other jobs default to standard. The report lands in your own context and is re-read every later turn. No effect on the local model, whose caps are calibrated."),
+  stakes: z.enum(["normal", "high"]).optional().describe("implement: how much a mistake would cost, separate from how hard the work is. high for anything touching security or access control, personal or tenant data, data loss, money, or changes that can't be undone: a verification profile is then required, the revert check can't be turned off, and the job always comes back needing review until an independent review (a scout on another vendor with reviews: <job id>, or a judge on another vendor) has looked at it. A one-line auth change is simple and high-stakes."),
+  reviews: z.string().regex(/^[A-Za-z0-9._-]{1,120}$/).optional().describe("scout: the job id this scout independently reviews, so the review is recorded against that job (nomarmy stats shows high-stakes jobs with and without one). Use a different vendor than the job's worker."),
   commit_subject: z.string().max(200).optional().describe("implement: the subject line of the commit nomArmy makes on the worker branch, e.g. \"Keep held-back tables in the list_tables cache\". Defaults to the task's first sentence; the body is the worker's NOTE, and the job id is a trailer."),
   army_role: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/).optional().describe("Dispatch by army role (e.g. \"sr-dev\", \"security-analyst\"): nomArmy runs it on the agent this repo assigns to that role and puts the role's description at the top of the brief. Call the `army` tool first to see this repo's roles. Mutually exclusive with agent. Add on_behalf_of in case the role's agent is a subscription; it's ignored otherwise."),
+  confirm_over_limit: z.boolean().optional().describe("Override a reached usage limit: the General must ask the operator before resubmitting with confirm_over_limit: true, or send the job to another agent. nomArmy never sets it itself."),
   on_behalf_of: z.string().min(1).max(254).optional().describe("Required when the job's agent is a subscription: must exactly match that agent's owner in agents.yml, or nomArmy refuses the job. A self-reported attestation, not an independently verified identity check -- nomArmy has no caller-identity boundary today, so what this guarantees is explicit, auditable intent and hard refusal on mismatch or omission, not cryptographic proof of who issued the call. Ignored for a local or api agent."),
   evidence: z.string().max(maxEvidenceChars,
     `Evidence exceeds the ${maxEvidenceChars}-character budget. This is for facts already resolved (e.g. with repo_evidence), not more description of the task -- if it needs more than this, resolve less per job or put the pointer (a path and line range) here instead of the material itself.`
   ).optional().describe("implement only: facts YOU already resolved (e.g. via repo_evidence) that the worker should trust and not re-derive -- exact signatures, call sites, line ranges, existing behavior. Cuts exploration that would otherwise burn the worker's own context budget on something you already know. Not a substitute for a clear objective and acceptance criteria."),
+  continue_from: z.string().regex(/^[A-Za-z0-9._-]{1,120}$/).optional().describe("implement only: the job id of a retained, uncommitted implement job (partial, blocked, or failed verification) whose unfinished work this job should finish. The new worktree starts from that job's base with its changes in place, so brief only the correction; the finished whole, that work included, is verified and committed together. Use this instead of fixing a worker's files yourself, which would land them unverified. Leave base_ref out."),
   worker_id: z.string().regex(/^[A-Za-z0-9._-]+$/).optional()
 });
 // A plain function, not jobSchema.superRefine: server.tool(...) registers
@@ -329,17 +388,18 @@ function jobArgs(args, workerId) {
   return { task: args.task, acceptance: args.acceptance, verification: args.verification, mode: args.mode, baseRef: args.base_ref,
     timeoutSeconds: args.timeout_seconds, profile: args.profile, reasoning: args.reasoning, pool: args.pool,
     subscriptionWorker, onBehalfOf: args.on_behalf_of, model: args.model ?? null, reportSize: args.report ?? null, evidence: args.evidence,
-    verifyRegression: resolveVerifyRegression(args), commitSubject: args.commit_subject ?? null, refactor: Boolean(args.refactor), workerId };
+    verifyRegression: resolveVerifyRegression(args), commitSubject: args.commit_subject ?? null, refactor: Boolean(args.refactor), continueFrom: args.continue_from ?? null, stakes: args.stakes ?? null, reviews: args.reviews ?? null, workerId };
 }
 server.tool("local_worker", "Run one isolated local worker and wait for it. mode=implement edits in its own worktree and the coordinator commits only on a valid done report (or a recovered job that passed independent verification); failed or incomplete worktrees are retained. mode=scout answers a question from a read-only snapshot with mandatory [path:line] citations that nomArmy verifies and expands. mode=decompose (also read-only) proposes 2+ independent subtasks for a broad objective instead of one worker turn trying to do too much; the proposal is never auto-dispatched, review it and make a separate call with the subtasks you choose. Refuses under memory pressure or over capacity; use local_worker_start + local_worker_status to avoid blocking.", jobSchema.shape,
   async rawArgs => {
     const expanded = expandJobs([rawArgs]);
     if (expanded.problems.length) return refusal(expanded.problems);
     const [args] = expanded.jobs;
-    const { problems } = await admit([args]);
+    const { problems, admission } = await admit([args]);
     if (problems.length) return refusal(problems);
     const r = await launch(args).promise;
-    return toolText(formatResult(r), !r.ok);
+    const refreshed = (admission.reasons ?? []).filter((line) => line.startsWith("stale usage reading "));
+    return toolText(refreshed.length ? `${coordinatorResult(r)}\n\n${refreshed.join("\n")}` : coordinatorResult(r), !r.ok);
   });
 server.tool("local_worker_start", "Start one worker or scout in the background and return immediately with a job_id. Poll it with local_worker_status (optionally long-polling with wait_seconds). Same admission rules as local_worker: refuses under memory pressure or when NOMARMY_MAX_WORKERS jobs are already running.", jobSchema.shape,
   async rawArgs => {
@@ -349,14 +409,15 @@ server.tool("local_worker_start", "Start one worker or scout in the background a
     const { problems, admission } = await admit([args]);
     if (problems.length) return refusal(problems);
     const entry = launch(args);
-    return toolText(JSON.stringify({ started: true, jobId: entry.jobId, workerId: entry.workerId, mode: entry.mode, state: "running",
+    return toolText(coordinatorJson({ started: true, jobId: entry.jobId, workerId: entry.workerId, mode: entry.mode, state: "running",
       jobDir: path.join(jobsRoot, entry.jobId), timeoutSeconds: args.timeout_seconds,
       poll: { tool: "local_worker_status", job_id: entry.jobId, wait_seconds: MAX_STATUS_WAIT_SECONDS },
+      wait: `nomarmy jobs --wait ${entry.jobId}`,
       // This job's own lane and budget: a subscription job used to be
       // reported with the local model's figures.
-      lane: jobLane(args), agent: args.agentName ?? "local", model: args.model ?? null,
+      lane: jobLane(args), agent: args.mode === "verify" ? null : args.agentName ?? "local", model: args.model ?? null,
       ...(args.run_id ? { run: runBrief(args.run_id) } : {}),
-      admission: { level: admission.level, notes: admission.reasons }, budgets: describeBudgets(budgetsForJob(args)) }, null, 2));
+      admission: { level: admission.level, notes: admission.reasons }, budgets: args.mode === "verify" ? null : describeBudgets(budgetsForJob(args)) }));
   });
 // A long poll must return inside the MCP client's own idle-timeout: it aborts
 // a tool call after N seconds with no response or progress notification,
@@ -373,9 +434,10 @@ server.tool("local_worker_start", "Start one worker or scout in the background a
 // always crossed; 110s returns in-line with margin. Raise it only for a
 // client that neither backgrounds nor times out that early.
 export const MAX_STATUS_WAIT_SECONDS = Number.parseInt(process.env.NOMARMY_MAX_STATUS_WAIT_SECONDS ?? "", 10) || 110;
-server.tool("local_worker_status", `Status of one job started by this server: phase (starting, worktree, worker, verification, commit, record, finished), elapsed time against its timeout, and the result once finished. wait_seconds long-polls up to that long for completion (max ${MAX_STATUS_WAIT_SECONDS}, to stay inside MCP client request timeouts; poll again for longer jobs). full=true returns the complete formatted result instead of a summary.`, {
-  job_id: z.string().min(1), wait_seconds: z.number().int().min(0).max(MAX_STATUS_WAIT_SECONDS).default(0), full: z.boolean().default(false)
-}, async ({ job_id, wait_seconds, full }) => {
+server.tool("local_worker_status", `Status of one job started by this server: phase (starting, worktree, worker, verification, commit, record, finished), elapsed time against its timeout, and the result once finished. wait_seconds long-polls up to that long for completion (max ${MAX_STATUS_WAIT_SECONDS}, to stay inside MCP client request timeouts; poll again for longer jobs). report=true returns just the worker's report (a scout's findings with their verified citations), the outcome, issues, verification and commit. full=true returns the complete execution record.`, {
+  job_id: z.string().min(1), wait_seconds: z.number().int().min(0).max(MAX_STATUS_WAIT_SECONDS).default(0), full: z.boolean().default(false),
+  report: z.boolean().default(false).describe("Just the report and nomArmy's verdict on it, without the rest of the record. Prefer this to full."),
+}, async ({ job_id, wait_seconds, full, report }) => {
   const jobId = path.basename(job_id), entry = activeJobs.get(jobId), jobDir = path.join(ensureJobsRoot(), jobId);
   if (entry && !entry.settled && wait_seconds > 0) await Promise.race([entry.promise.catch(() => {}), sleep(wait_seconds * 1000)]);
   const files = { status: readJson(path.join(jobDir, "status.json")), meta: readJson(path.join(jobDir, "metadata.json")), failure: readJson(path.join(jobDir, "failure.json")) };
@@ -386,15 +448,54 @@ server.tool("local_worker_status", `Status of one job started by this server: ph
     summarize(entry, files, jobDir),
     sleep(15000).then(() => summarize(entry, files, null)),
   ]);
-  if (summary.state === "running") return toolText(JSON.stringify({ ...summary, jobDir, hint: `poll again with wait_seconds up to ${MAX_STATUS_WAIT_SECONDS}; lastTool/filesChangedLive are best-effort and may be absent early in a run` }, null, 2));
-  if (entry?.error) return toolText(JSON.stringify({ ...summary, jobDir }, null, 2), true);
-  if (full && entry?.result) return toolText(formatResult(entry.result), !entry.result.ok);
-  if (full && files.meta) return toolText(JSON.stringify(files.meta, null, 2), summary.coordinatorStatus !== "complete");
-  return toolText(JSON.stringify({ ...summary, jobDir, hint: entry?.result || files.meta ? "call again with full=true for the complete report" : null }, null, 2), summary.state === "orphaned" || summary.state === "failed");
+  if (summary.state === "running") return toolText(coordinatorJson({ ...summary, jobDir, hint: `poll again with wait_seconds up to ${MAX_STATUS_WAIT_SECONDS}; lastTool/filesChangedLive are best-effort and may be absent early in a run` }));
+  if (entry?.error) return toolText(coordinatorJson({ ...summary, jobDir }), true);
+  if (report && files.meta) return toolText(coordinatorJson(reportView(files.meta)), summary.coordinatorStatus !== "complete");
+  if (full && entry?.result) return toolText(coordinatorResult(entry.result), !entry.result.ok);
+  if (full && files.meta) return toolText(coordinatorJson(files.meta), summary.coordinatorStatus !== "complete");
+  return toolText(coordinatorJson({ ...summary, jobDir, hint: entry?.result || files.meta ? "call again with report=true for the worker's report, or full=true for the complete record" : null }), summary.state === "orphaned" || summary.state === "failed");
 });
+// Set when this session's copy of nomArmy changed on disk after it started
+// (nomarmy connect or update ran): shown first in army and capacity, and
+// notified once, since only a restart of this session picks it up.
+let restartNotified = false;
+function currentRestartNotice() {
+  const notice = restartNotice({ serverFile: fileURLToPath(import.meta.url), startedAtMs: SERVER_STARTED_MS, runningVersion: VERSION });
+  if (notice && !restartNotified) { restartNotified = true; try { notify("nomArmy: restart this session", notice); } catch { /* best-effort */ } }
+  return notice;
+}
+const withRestartNotice = (value) => { const notice = currentRestartNotice(); return notice ? { restartNeeded: notice, ...value } : value; };
+
+server.tool("stats", "What nomArmy's own job records show for this repository (or all repositories): jobs by mode, role and model; code committed; worker and job time; tokens and API spend; claim vs evidence (how often a \"done, tests pass\" report failed independent verification, or passed with tests that couldn't catch the change); what didn't complete; reviewer outcomes; and review flags. Every number comes from nomArmy's verified records, never a worker's report. Defects you find at integration aren't in the records: add your own count. Read-only.", {
+  since: z.string().max(40).optional().describe("Only jobs started since this: a date (2026-09-25) or an age (7d, 24h). Default: all."),
+  until: z.string().max(40).optional().describe("Only jobs started before this date."),
+  all_repos: z.boolean().optional().describe("Every repository this machine's nomArmy has run jobs for, not just this one."),
+  repo: z.string().max(400).optional().describe("Another repository, by path or folder name (\"senti\" matches rayson-senti if unambiguous)."),
+  role: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/).optional().describe("Only jobs dispatched as this army role (e.g. sr-dev)."),
+  model: z.string().regex(/^\S{1,200}$/).optional().describe("Only jobs that ran on this model (e.g. grok-4.7)."),
+  format: z.enum(["text", "json"]).optional().describe("text (default) is the report; json is the raw numbers."),
+  details: z.boolean().optional().describe("The full report (volume, reviewers, flags, what didn't finish). Default is the one-screen summary: what nomArmy caught, high-stakes work needing review, the top routing tips, spend."),
+}, async ({ since, until, all_repos, repo, role, model, format, details }) => {
+  try {
+    const records = loadJobRecords(jobsRoot);
+    let agentFor = () => null;
+    try { agentFor = agentLookup(agentsConfig().agents, agentProviderId); } catch { /* commands name <agent> */ }
+    const stats = computeStats(records, { repo: repo ? resolveRepo(records, repo) : all_repos ? null : projectDir, sinceMs: parseSince(since), untilMs: parseSince(until), role: role ?? null, model: model ?? null, agentFor });
+    return toolText(format === "json" ? JSON.stringify(stats, null, 2) : details ? formatStats(stats) : formatStatsSummary(stats));
+  } catch (error) { return toolText(error.message, true); }
+});
+
+server.tool("local_worker_stop", "Stop a running job's worker, for example one burning a frontier model's usage on the wrong track. Its worker ends within about 15 seconds, without the report-recovery call a timeout gets and without running verification; its worktree is kept uncommitted, so a new job with continue_from: <job_id> (and a cheaper model if you like) can finish the work. Works for a job started by any session. Refuses a job that isn't running or is already past its worker.", {
+  job_id: z.string().regex(/^[A-Za-z0-9._-]{1,120}$/),
+  reason: z.string().max(300).optional().describe("Why it's being stopped; recorded in the job's issues."),
+}, async ({ job_id, reason }) => {
+  const r = requestJobStop({ jobsRoot, jobId: job_id, reason: reason ?? null });
+  return toolText(r.message, !r.ok);
+});
+
 server.tool("local_worker_capacity", "What this host can take right now: context per nom and the brief/report budgets derived from it, memory pressure and whether another job would be admitted, and the jobs currently running. Read-only.", {}, async () => {
   await budgetState.refresh();
-  return toolText(JSON.stringify(capacitySnapshot(), null, 2));
+  return toolText(JSON.stringify(withRestartNotice(await displayedCapacity()), null, 2));
 });
 // The only way to know what `verification`/`union_verification`/
 // `verify_regression` profile names are actually valid for this repo used to
@@ -468,20 +569,37 @@ server.tool("run_finish", "Close a /feature run as complete or stopped, with a o
   try {
     const run = finishRun(runsRoot, run_id, { status, summary });
     if (activeRunId === run_id) activeRunId = null;
-    return toolText(JSON.stringify({ id: run.id, status: run.status, ...runTotals(run) }, null, 2));
+    // What nomArmy verified in this run, ready for the pull request's description (lib/share.mjs).
+    let prBlock = null;
+    try { prBlock = shareMarkdown(computeStats(loadJobRecords(jobsRoot), { runId: run_id }), { scope: "this feature run" }); } catch { /* the totals stand without it */ }
+    return toolText(JSON.stringify({ id: run.id, status: run.status, ...runTotals(run), ...(prBlock ? { prBlock, prBlockNote: "Put prBlock in the pull request's description as it is: every number is from nomArmy's verified records." } : {}) }, null, 2));
   } catch (error) { return toolText(error.message, true); }
 });
 server.tool("army", "Who you, the General, are and who you call for what in this repository: your fixed charter and the agent you're defined as, the army's workflow, then each role's description, phase (build, review, acceptance), suggested mode, and the agent it runs on, with which config layer set each value (global, project .nomarmy.yml, local .nomarmy.local.yml). Flags roles with no usable agent, and roles that share your model or subscription (not an independent review). Dispatch a role with `army_role`, or an agent directly with `agent`. Read-only, re-read on every call.", {}, async () => {
   try {
     const agents = agentsConfig().agents;
-    const summary = describeArmy(currentArmy(), { agents, describeAgent });
+    const usageRefresh = await refreshStaleOverLimitReadings(stateRoot);
+    const usageSnapshots = usageRefresh.snapshots;
+    const summary = describeArmy(currentArmy(), { agents, describeAgent, usageSnapshots, agentProviderId, usageRefreshError: usageRefresh.error, usageRefreshFailed: usageRefresh.failedProviders });
     // Each agent's models, from OpenClaw's catalog, so the General can pick
     // one for a role set to "auto". The catalog can lag a brand-new model.
     const catalog = await modelCatalogReady();
+    // A model its vendor refused on a job is listed apart, so a role on
+    // "auto" isn't sent to it (the catalog lists what a plan may refuse).
+    retryRefusedModelsInBackground(stateRoot, { probeModel });
+    const refusals = modelRefusals(stateRoot);
     summary.agents = Object.fromEntries(Object.entries(agents).map(([name, agent]) => {
       const provider = agentProviderId(agent);
-      const models = provider && catalog ? [...catalog.keys()].filter((k) => k.startsWith(`${provider}/`)).map((k) => k.slice(provider.length + 1)) : [];
-      return [name, { runsOn: describeAgent(agent), defaultModel: agent.model ?? null, models }];
+      const listed = provider && catalog ? [...catalog.keys()].filter((k) => k.startsWith(`${provider}/`)).map((k) => k.slice(provider.length + 1)) : [];
+      const models = listed.filter((m) => !refusals[`${provider}/${m}`]);
+      const refusedModels = listed.filter((m) => refusals[`${provider}/${m}`]);
+      const snapshot = usageSnapshots[provider];
+      const usage = snapshot ? (() => {
+        const status = usageStatus(snapshot);
+        const failed = usageRefresh.failedProviders.includes(provider);
+        return { level: status.level, text: `${usageDisplayText(status)}${failed ? `. ${usageRefresh.error}` : ""}` };
+      })() : null;
+      return [name, { runsOn: describeAgent(agent), defaultModel: agent.model ?? null, models, ...(refusedModels.length ? { refusedModels } : {}), usage }];
     }));
     // A pinned model missing from the catalog isn't necessarily wrong:
     // `army assign` proves an unlisted model with a real test call, and the
@@ -493,7 +611,13 @@ server.tool("army", "Who you, the General, are and who you call for what in this
         role.modelNote = `${role.model} isn't in OpenClaw's catalog for ${role.agent}; \`army assign\` checked it with a real test call when it was set, and the catalog can lag new models. Use it as assigned; if a job reports "Unknown model", reassign.`;
       }
     }
-    return toolText(JSON.stringify(summary, null, 2));
+    // Routing suggestions from this repo's recent jobs (lib/suggestions.mjs):
+    // tell the operator about them; never apply one without their say-so.
+    try {
+      const list = recentSuggestions(loadJobRecords(jobsRoot), { projectDir, agentFor: agentLookup(agents, agentProviderId) });
+      if (list.length) summary.suggestions = { note: "From this repo's last 14 days of jobs. Tell the operator; change routing only with their say-so (nomarmy army assign).", items: list.map(({ level, title, evidence, command }) => ({ level, title, evidence, command })) };
+    } catch { /* suggestions are a bonus; the army summary stands without them */ }
+    return toolText(JSON.stringify(withRestartNotice(summary), null, 2));
   } catch (error) {
     return toolText(error.message, true);
   }
@@ -503,7 +627,7 @@ server.tool("local_worker_config", "What this checkout's .nomarmy.yml defines --
   return toolText(JSON.stringify(summary, null, 2), summary.valid === false);
 });
 server.tool("local_workers", "Run independent jobs (implement or scout) with bounded parallelism and wait for all of them. Every implement job receives its own branch, worktree, sandbox session, logs, validation, and coordinator-owned commit. This tool never merges any branch into the developer's branch. With auto_union: true, implement jobs that reach a valid outcome and touch non-overlapping files are additionally merged (git merge --no-ff) into ONE new integration branch -- a review artifact alongside the untouched per-job branches, still not the developer's branch, still reviewed and integrated explicitly. Jobs that overlap or did not finish validly are excluded from the union and reported individually exactly as without auto_union. For long batches prefer local_worker_start per job and poll.", {
-  jobs: z.array(jobSchema).min(1).max(8), max_parallel: z.number().int().min(1).max(8).optional().describe("A cap on how many of this batch run at once. Omit it: local jobs then use the local ceiling and api/subscription jobs theirs (NOMARMY_MAX_POOL_WORKERS), with each agent's own max_concurrent on top. It used to default to the local ceiling, which ran an all-remote batch one job at a time."),
+  jobs: z.array(jobSchema).min(1).max(8), max_parallel: z.number().int().min(1).max(8).optional().describe("A cap on how many of this batch run at once. Omit it: local jobs then use the local ceiling and api/subscription jobs theirs (`nomarmy config max-jobs`, default 4), with each agent's own max_concurrent on top. It used to default to the local ceiling, which ran an all-remote batch one job at a time."),
   auto_union: z.boolean().default(false).describe(
     "After all jobs finish, mechanically merge (git merge --no-ff) implement jobs that reached a valid outcome and touched non-overlapping files into ONE new integration branch for review -- never into the developer's branch. Overlapping or invalid-outcome jobs are excluded and still reported individually, unchanged. All jobs must share one base_ref (or omit it); it is resolved once, before any job starts, and forced onto every job so the union is provably rooted at a single base."
   ),
@@ -514,7 +638,7 @@ server.tool("local_workers", "Run independent jobs (implement or scout) with bou
   const expanded = expandJobs(rawJobs);
   if (expanded.problems.length) return refusal(expanded.problems);
   const { jobs } = expanded;
-  const { problems } = await admit(jobs);
+  const { problems, admission } = await admit(jobs);
   let forcedBase = null;
   if (auto_union) {
     const refs = [...new Set(jobs.map(j => j.base_ref).filter(Boolean))];
@@ -547,7 +671,7 @@ server.tool("local_workers", "Run independent jobs (implement or scout) with bou
       // so it was invisible to both ceilings while it ran.
       // A batch job waits for its agent's slot (up to its own timeout) rather
       // than failing because an earlier job in the same batch holds it.
-      return trackInRun(j, track(jobId, { mode: j.mode, workerId, lane: jobLane(j), agent: j.agentName ?? null, runId: j.run_id ?? null, role: j.armyRole ?? null, model: j.model ?? null },
+      return trackInRun(j, track(jobId, { mode: j.mode, workerId, lane: jobLane(j), agent: j.agentName ?? null, runId: j.run_id ?? null, role: j.armyRole ?? null, model: j.model ?? null, label: jobLabel(j) },
         withAgentSlot(j, jobId, () => executeJob({ ...jobArgs(effectiveJob, workerId), jobId }), { waitMs: (j.timeout_seconds ?? 600) * 1000 }))).promise;
     }, { staggerMs: WORKER_START_STAGGER_MS });
     indices.forEach((i, laneI) => { results[i] = laneResults[laneI]; });
@@ -578,8 +702,9 @@ server.tool("local_workers", "Run independent jobs (implement or scout) with bou
     reviewRequired: results.filter(r => r.manifest?.reviewRequired).length,
     jobs: results.map(r => ({ jobId: r.manifest.jobId, workerId: r.manifest.workerId, mode: r.manifest.mode, outcome: r.manifest.outcome || OUTCOMES.WORKER_FAILED, recovered: Boolean(r.manifest.recovered), status: r.manifest.coordinatorStatus || "failed", branch: r.manifest.branch, commit: r.manifest.commit?.sha || null, worktree: r.manifest.worktree, jobDir: r.jobDir })),
     ...(union ? { union } : {}) };
-  const unionSection = union ? `UNION\n\n${formatUnion(union)}\n\n` : "";
-  const text = `BATCH EXECUTION RECORD\n${JSON.stringify(summary, null, 2)}\n\n${unionSection}WORKER RESULTS\n\n${results.map((r, i) => `===== WORKER ${i + 1} =====\n${formatResult(r)}`).join("\n\n")}`;
+  const unionSection = union ? `UNION\n\n${formatUnion(withWindowsPaths(union))}\n\n` : "";
+  const refreshed = (admission?.reasons ?? []).filter((line) => line.startsWith("stale usage reading "));
+  const text = `BATCH EXECUTION RECORD\n${coordinatorJson(summary)}\n\n${unionSection}WORKER RESULTS\n\n${results.map((r, i) => `===== WORKER ${i + 1} =====\n${coordinatorResult(r)}`).join("\n\n")}${refreshed.length ? `\n\n${refreshed.join("\n")}` : ""}`;
   return toolText(text, results.some(r => !r.ok) || union?.status === "union_verification_failed" || union?.status === "union_error");
 });
 // No model, no sandbox, no tokens spent on a worker: the coordinator asks the
@@ -604,7 +729,7 @@ server.tool("local_worker_jobs", "List recent job records for review/recovery, i
     if (status) return summarize(activeJobs.get(name) ?? null, { status, meta: null, failure: null }, dir);
     return { jobId: name, state: "unknown" };
   }));
-  return toolText(JSON.stringify(rows, null, 2));
+  return toolText(coordinatorJson(rows));
 });
 // The sandbox writes skill/guardrail files under .openclaw/ with permissions
 // meant to stop the SANDBOXED AGENT from deleting them. On macOS, the
@@ -736,7 +861,7 @@ server.tool("local_worker_sweep", "Bulk-reap job worktrees/branches that are PRO
       skipped.push({ jobId, reason: `removal failed: ${error.message}` });
     }
   }
-  return toolText(JSON.stringify({ examined: dirs.length, reapedCount: reaped.length, skippedCount: skipped.length, dryRun: dry_run, reaped, skipped }, null, 2));
+  return toolText(coordinatorJson({ examined: dirs.length, reapedCount: reaped.length, skippedCount: skipped.length, dryRun: dry_run, reaped, skipped }));
 });
 server.tool("local_worker_cleanup", "Remove a retained worker worktree and optionally its agent branch after Claude has reviewed/integrated or deliberately discarded it. Refuses to delete the current branch. A branch whose commits were cherry-picked (not merged) into the current branch -- nomArmy's own integration model -- is recognized as integrated by comparing PATCH CONTENT (git cherry), not git's own ancestry-only check, so a genuinely-integrated job's cleanup does not need force: true. Reserve force for a branch you are actually discarding unintegrated work from.", {
   job_id: z.string().min(1), delete_branch: z.boolean().default(false), force: z.boolean().default(false)
@@ -791,6 +916,12 @@ if (isMain) {
   // sqlglot, so verification could never pass), and a worker could edit its
   // own worktree's copy to weaken the checks that judge it.
   registerVerificationRunner(createVerificationRunner({ hostProjectDir: projectDir, loadConfig: () => loadConfig(projectDir) }));
+  // A healthy answer is reused for 20 seconds, so a batch doesn't ask Podman per job.
+  let podmanOkUntil = 0;
+  podmanChecks = {
+    problem: () => { if (Date.now() < podmanOkUntil) return null; const p = podmanProblem(); if (!p) podmanOkUntil = Date.now() + 20000; return p; },
+    vmStartedAt: () => podmanVmStartedAt(),
+  };
   // Warm the budget from the profile or the running llama-server. Not awaited:
   // admission refreshes it anyway, and a slow hardware probe must not delay
   // the MCP handshake.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "nomarmy",
-  "description": "A harness for AI coding workers whose claims are never trusted: your coding assistant stays in charge while workers implement and test in sandboxes, on local models, API keys or your own subscriptions.",
+  "description": "Every byte verified: a harness for AI coding workers whose claims are never trusted. Your coding assistant stays in charge while workers implement and test in sandboxes, and nomArmy checks every change before it is committed.",
   "author": "Rayson Technologies",
   "license": "Apache-2.0",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.21",
   "private": false,
   "type": "module",
   "engines": {
@@ -21,14 +21,15 @@
     "tag": "alpha"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.30.1",
     "@secretlint/node": "^13.0.5",
     "@secretlint/secretlint-rule-preset-recommend": "^13.0.5",
     "yaml": "^2.5.0",
-    "zod": "^3.24.0"
+    "zod": "^4.6.5"
   },
   "scripts": {
-    "test": "node --test tests/*.test.mjs"
+    "test": "node --test tests/*.test.mjs",
+    "docs:harnesses": "node scripts/generate-harness-docs.mjs"
   },
   "bin": {
     "nomarmy": "bin/nomarmy.mjs"
@@ -43,6 +44,7 @@
     "scripts",
     "policies",
     "docker",
+    "harnesses",
     "install.sh",
     "e2e.sh",
     "LICENSE",

package/playbooks/feature.md

@@ -12,10 +12,11 @@ You are the General. Build this feature end to end with nomArmy's army and come
 
 Follow the army's workflow, calling only the roles the work needs:
 
+0. **Routing.** The `army` tool's `suggestions` come from this repo's recent jobs (a role that keeps failing, a cheaper model doing as well, unreviewed high-stakes work). Tell the operator about any at the start and in your final summary; change routing only if they say so.
 1. **Plan.** Scout the repo as needed (`repo_evidence` first; a scout only for research that would pull many files into your context). Write the plan into the run log: the outcome, acceptance criteria, the pieces, and which role gets each.
-2. **Build.** Dispatch with `army_role` (and `on_behalf_of` when the role's agent is a subscription). The Sr Dev takes the core and harder work; the Jr Dev takes simple, fully specified pieces; UI/UX takes UI. For a role on `auto`, pick the model from the agent's list in the `army` tool: the lighter model for routine work, the frontier one for subtle work.
-3. **Review.** When the build is in, call the specialists that apply (data architect for data work, security analyst for anything touching auth, input, secrets or data exposure), then the PM against the plan. Send what they find back to the builders as new, bounded jobs.
-4. **Acceptance.** PO and stakeholder test end to end. Fix what they find the same way.
+2. **Build.** Dispatch with `army_role` (and `on_behalf_of` when the role's agent is a subscription). The Sr Dev takes the core and harder work; the Jr Dev takes simple, fully specified pieces; UI/UX takes UI. For a role on `auto`, pick the model from the agent's list in the `army` tool: the lighter model for routine work, the frontier one for subtle work. Mark a job `stakes: high` when a mistake would be costly (security or access control, personal or tenant data, data loss, money, anything irreversible), however small the change: that's separate from how hard it is.
+3. **Review.** When the build is in, call the specialists that apply (data architect for data work, security analyst for anything touching auth, input, secrets or data exposure), then the PM against the plan. Every `stakes: high` build job gets an independent review before you accept it: a scout on a different vendor than its worker, with `reviews: <that job id>`. Send what they find back to the builders as new, bounded jobs. A build job that comes back partial, blocked or failing verification is finished with `continue_from: <its job id>` and a brief of just the correction, never by fixing its files yourself: only verified work lands.
+4. **Acceptance.** PO and stakeholder test end to end. Checks that only run existing tests use mode: verify; writing new e2e checks is still an implement job. Fix what they find the same way.
 5. **Integrate.** Review every diff against nomArmy's verified record -- a worker's report is a claim, not evidence -- and bring the accepted work together on one branch. **Never merge into the developer's branch, and never push.** The finished state is a branch ready for the operator to review and merge.
 
 ## Decisions along the way
@@ -24,9 +25,11 @@ When you hit a choice you'd normally ask the operator about, don't stop: pick th
 
 Stop and ask only for something irreversible or outside this repository: merging or pushing, deploying, anything needing cloud or production credentials, deleting data, or changing another repository.
 
+A gate's result is not yours to reinterpret. When a check the plan or the operator set (an exact expected output, a count, a checksum, a contract) doesn't match, that's a failure, even when the difference looks cosmetic: whitespace from BSD versus GNU `wc`, line endings, ordering, a trailing newline. Don't judge it "equivalent" and pass it. Either fix the check so it compares what was meant (normalize both sides, and write that change into the run log as a decision), or send the mismatch back as a failed job. A gate the General can wave through is no gate.
+
 ## Watching jobs
 
-Don't poll in a loop: each status call costs your own usage. Where your coordinator can watch a background command (Claude Code's monitor), watch `nomarmy jobs --events` -- one line per job start, phase change and finish -- and act when a line arrives. Otherwise use `local_worker_status` with the longest `wait_seconds` it allows. `run_status` lists the run's running jobs as well as finished ones. The operator gets a desktop notification whenever a job finishes and whenever the run crosses a limit, so you don't need to relay each one.
+Prefer `local_worker_start`. Right after starting a job, if your coordinator can run a background command, run `nomarmy jobs --wait <job_id>` in the background so you're told the moment it finishes and can tell the operator. Otherwise poll `local_worker_status` with the longest `wait_seconds` it allows. For several jobs at once, `nomarmy jobs --wait <id> <id> ...` exits when every one has finished. For a whole run, use `nomarmy jobs --events --until-done --run <run-id>`. Never use unscoped `--until-done` when other sessions may have jobs. The plain `nomarmy jobs --events` stream never exits on its own while jobs run, so don't run it as a background command (you'd only hear when it exits); use it only with a monitor that wakes on each line. `run_status` lists the run's running jobs as well as finished ones. The operator gets a desktop notification whenever a job finishes and whenever the run crosses a limit, so you don't need to relay each one.
 
 ## Limits
 
@@ -40,4 +43,4 @@ The `logPath` from `run_start`. Markdown, updated after every phase: the plan; e
 
 ## When it's done
 
-Call `run_finish` (`complete` or `stopped`), then report in one message: what was built and on which branch; what each role found and how it was resolved; the decisions made on the operator's behalf; test and verification results; and the run's cost from `run_status` (jobs and api spend per agent). If a push-notification tool is available, notify the operator that the run finished or stopped.
+Call `run_finish` (`complete` or `stopped`). Its result has a `prBlock`: when you or the operator open a pull request for the run's branch, put it in the description as it is (every number is from nomArmy's verified records). Then report in one message: what was built and on which branch; what each role found and how it was resolved; the decisions made on the operator's behalf; test and verification results; and the run's cost from `run_status` (jobs and api spend per agent). If a push-notification tool is available, notify the operator that the run finished or stopped.

package/scripts/configure-openclaw.sh

@@ -57,7 +57,9 @@ else
     if [[ -n "$REMOTE_MODEL" && "$REMOTE_MODEL" != "${NOMARMY_WORKER_MODEL:-}" ]]; then
       # Jobs ask for NOMARMY_WORKER_MODEL, so record the name this server
       # actually serves (`nomarmy connect`, run next by install.sh, reads it).
-      COMMON="$ROOT/config/common.env"
+      # Your settings file, so an update can't reset it (lib/user-config.mjs).
+      COMMON="$(nomarmy_user_config_dir)/common.env"
+      mkdir -p "$(dirname "$COMMON")"; touch "$COMMON"
       for key in NOMARMY_MODEL_ALIAS NOMARMY_WORKER_MODEL; do
         if grep -q "^$key=" "$COMMON"; then
           KEY="$key" VALUE="$REMOTE_MODEL" node -e 'const fs=require("fs"),f=process.argv[1];fs.writeFileSync(f,fs.readFileSync(f,"utf8").replace(new RegExp(`^${process.env.KEY}=.*$`,"m"),`${process.env.KEY}=${process.env.VALUE}`))' "$COMMON"
@@ -66,7 +68,7 @@ else
         fi
       done
       export NOMARMY_MODEL_ALIAS="$REMOTE_MODEL" NOMARMY_WORKER_MODEL="$REMOTE_MODEL"
-      echo "==> The server serves '$REMOTE_MODEL'; recorded it in config/common.env"
+      echo "==> The server serves '$REMOTE_MODEL'; recorded it in $COMMON"
     fi
     # llama-server reports the context of one slot, which is one nom's share.
     REMOTE_CTX="$(curl -fsS --max-time 5 "$SERVER/props" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const n=JSON.parse(s).default_generation_settings?.n_ctx;if(Number.isInteger(n)&&n>0)process.stdout.write(String(n))}catch{}})' || true)"

package/scripts/generate-harness-docs.mjs

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { HARNESS_ROOT, loadHarnesses } from "../lib/harnesses.mjs";
+
+export const HARNESS_DOCS = fileURLToPath(new URL("../docs/harnesses.md", import.meta.url));
+const cell = (value) => String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("|", "&#124;").replaceAll("\n", " ").replaceAll("\r", " ");
+
+export function generateHarnessDocs(root = HARNESS_ROOT) {
+  const { harnesses, problems } = loadHarnesses(root);
+  if (problems.length) throw new Error(problems.map(({ name, reason }) => `${name}: ${reason}`).join("\n"));
+  const rows = Object.values(harnesses).sort((a, b) => a.name.localeCompare(b.name)).map((spec) => {
+    const detects = spec.detect.map((rule) => Object.entries(rule).map(([kind, value]) => `${kind}: ${value}`).join(", ")).join("; ") || "none";
+    const requires = Object.entries(spec.requires).map(([key, value]) => `${key}: ${value}`).join(", ") || "none";
+    return `| [${spec.name}](https://github.com/rayson-tech/nomarmy/blob/main/harnesses/${spec.name}/README.md) | ${cell(spec.summary)} | ${cell(detects)} | ${spec.network} | ${cell(requires)} |`;
+  });
+  return `<!-- Generated by npm run docs:harnesses. Do not edit by hand. -->
+# Harnesses
+
+A harness is a data-only folder describing detection, image layers, and proposed verification profiles. Matched harnesses compose one cached image for workers and verification: toolchains first, then Python, Node, and declarative layers, respecting \`after\`. Tags hash the recipe and copied dependency files. Verification profiles remain proposals. Repositories can explicitly enable harnesses with \`harnesses: [names]\` in \`.nomarmy.yml\`; service networks are used only for nomArmy verification.
+
+- **none**: offline verification (default).
+- **services**: fake services on a private network with no route out.
+- **allowlist**: verification-only access to operator-approved hosts, with dedicated test tenants and throwaway credentials, never production (planned).
+
+Workers always remain offline. See the [plan](plans/2026-09-25-sandbox-dependencies.md) and [Adding a harness](../CONTRIBUTING.md#adding-a-harness).
+
+| Harness | Summary | Detects | Network | Requires |
+|---------|---------|---------|---------|----------|
+${rows.join("\n")}
+`;
+}
+
+export function checkHarnessDocs(root = HARNESS_ROOT, output = HARNESS_DOCS) {
+  if (fs.readFileSync(output, "utf8") !== generateHarnessDocs(root)) {
+    throw new Error("Harness docs are stale. Run npm run docs:harnesses.");
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  fs.writeFileSync(HARNESS_DOCS, generateHarnessDocs());
+}

package/scripts/install-openclaw.mjs

@@ -0,0 +1,23 @@
+// install.sh has already installed nomArmy's dependencies. Nothing is ready
+// until the configured vendors and read-only OpenClaw diagnostics pass.
+import { loadAgents } from "../lib/agents.mjs";
+import { globalConfigDir } from "../lib/army.mjs";
+import { ensureOpenClawOnPath } from "../lib/openclaw-path.mjs";
+import { configuredSubscriptionVendors, openclawInstallPlan, repairOpenclaw, runOpenclawCommand, PINNED_OPENCLAW_VERSION } from "../lib/openclaw-install.mjs";
+
+ensureOpenClawOnPath();
+const command = process.env.NOMARMY_OPENCLAW_CMD || "openclaw";
+const version = runOpenclawCommand(command, ["--version"]);
+const [major, minor] = process.versions.node.split(".").map(Number);
+if (openclawInstallPlan(version.ok ? version.stdout : null).length &&
+    !((major === 24 && minor >= 16) || (major === 26 && minor >= 1) || major > 26)) {
+  console.error(`OpenClaw ${PINNED_OPENCLAW_VERSION} needs Node 24.16+ or 26.1+. Upgrade Node first.`);
+  process.exitCode = 1;
+} else {
+  const prefixIndex = process.argv.indexOf("--prefix");
+  const result = await repairOpenclaw({
+    command, yes: true, prefix: prefixIndex < 0 ? null : process.argv[prefixIndex + 1],
+    vendors: configuredSubscriptionVendors(loadAgents(globalConfigDir()).agents),
+  });
+  process.exitCode = result.ok ? 0 : 1;
+}