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

package/lib/harnesses.mjs

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+import { harnessSchemaFor } from "./harness-schema.mjs";
+import { nodeDependencyFiles } from "./sandbox-images.mjs";
+
+export const HARNESS_ROOT = fileURLToPath(new URL("../harnesses/", import.meta.url));
+
+// Resolve the whole graph before publishing any specs, including dependents
+// of broken harnesses. A partial layer stack is not a usable harness.
+function orderedNames(harnesses) {
+  const order = [], state = new Map(), failures = new Map();
+  function visit(name, trail = []) {
+    if (state.get(name) === "done") return !failures.has(name);
+    if (state.get(name) === "visiting") {
+      const cycle = [...trail.slice(trail.indexOf(name)), name];
+      for (const member of cycle) failures.set(member, `after cycle: ${cycle.join(" -> ")}`);
+      return false;
+    }
+    state.set(name, "visiting");
+    for (const parent of harnesses[name].after) {
+      if (!Object.hasOwn(harnesses, parent)) failures.set(name, `unknown after harness: ${parent}`);
+      else if (!visit(parent, [...trail, name]) && !failures.has(name)) failures.set(name, `invalid after harness: ${parent}`);
+    }
+    state.set(name, "done");
+    if (!failures.has(name)) order.push(name);
+    return !failures.has(name);
+  }
+  for (const name of Object.keys(harnesses).sort()) visit(name);
+  return { order, failures };
+}
+
+export function loadHarnesses(root = HARNESS_ROOT) {
+  const harnesses = {}, problems = [];
+  let entries;
+  try { entries = fs.readdirSync(root, { withFileTypes: true }); }
+  catch (error) { return { harnesses, problems: [{ name: path.basename(root), reason: error.message }] }; }
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || entry.name.startsWith("_")) continue;
+    try {
+      const raw = parse(fs.readFileSync(path.join(root, entry.name, "harness.yml"), "utf8"));
+      harnesses[entry.name] = harnessSchemaFor(entry.name).parse(raw);
+    } catch (error) {
+      problems.push({ name: entry.name, reason: error.message });
+    }
+  }
+  const { failures } = orderedNames(harnesses);
+  for (const [name, reason] of failures) {
+    delete harnesses[name];
+    problems.push({ name, reason });
+  }
+  return { harnesses, problems };
+}
+
+export function validateEnabledHarnesses(enabled = [], harnesses = loadHarnesses().harnesses) {
+  for (const name of enabled) {
+    if (!Object.hasOwn(harnesses, name)) throw new Error(`unknown harness '${name}'; available harnesses: ${Object.keys(harnesses).sort().join(", ")}`);
+    if (harnesses[name].network === "allowlist") throw new Error(`harness '${name}' requires allowlist; .nomarmy.yml cannot enable it (operator-local opt-in required)`);
+  }
+}
+
+export function matchHarnesses(repoDir, harnesses, enabled = []) {
+  validateEnabledHarnesses(enabled, harnesses);
+  let nodeDirs, packages;
+  function directories() {
+    if (!nodeDirs) {
+      const found = nodeDependencyFiles(repoDir);
+      nodeDirs = [...new Set([".", ...found.packages, ...(found.links ?? []), ...found.skipped.map(({ dir }) => dir)])];
+    }
+    return nodeDirs;
+  }
+  function dependencies() {
+    if (!packages) {
+      packages = new Set();
+      for (const dir of directories()) {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(path.join(repoDir, dir, "package.json"), "utf8"));
+          for (const field of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+            for (const name of Object.keys(pkg[field] ?? {})) packages.add(name);
+          }
+        } catch { /* An unreadable manifest cannot establish a match. */ }
+      }
+    }
+    return packages;
+  }
+  const isFile = (relative) => {
+    try { return fs.statSync(path.join(repoDir, relative)).isFile(); } catch { return false; }
+  };
+  const matched = Object.keys(harnesses).filter((name) => enabled.includes(name) || harnesses[name].detect.some((rule) => {
+    if (rule.package) return dependencies().has(rule.package);
+    if (rule.file) return isFile(rule.file);
+    return isFile(rule.lockfile) || directories().some((dir) => isFile(path.join(dir, rule.lockfile)));
+  }));
+  // Unmatched harnesses must not reorder unrelated matches through their after edges.
+  return orderedNames(Object.fromEntries(matched.map((name) => [name, {
+    ...harnesses[name], after: harnesses[name].after.filter((parent) => matched.includes(parent)),
+  }]))).order;
+}

package/lib/health.mjs

@@ -4,13 +4,16 @@
 // stall the server that runs it.
 //
 //   login-expiry     an OAuth login (the ChatGPT plan's Codex import) about
-//                    to expire or already expired
+//                    to expire or already expired. The import is a copy of
+//                    Codex's own login; re-import it, don't run agents add.
 //   openclaw-update  OpenClaw older than npm's latest (a stale 2026.9.5
 //                    catalog made gpt-6-sol look unavailable)
 //   plugin-skew      an OpenClaw plugin older than OpenClaw itself
 //   army             a role or the General pointing at something unusable
 //   config           agents.yml unloadable or unsafe
 //   leftovers        retained worktrees, job storage, stale "running" jobs
+//   nomarmy-update   a newer nomArmy on npm; nomarmy-copy: coordinators run
+//                    an older copy than the installed CLI (install-freshness.mjs)
 //
 // Each issue: { id, severity: "error"|"warn"|"info", title, detail, fix,
 // short }. `id` is stable across runs, so a notification goes out once per
@@ -19,37 +22,91 @@
 import { execFile } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { codexImportRecovery, codexImportIssues, modelPolicyIssues } from "./openclaw-runtime-health.mjs";
 import { executionMode } from "./execution.mjs";
 import { modelRejection } from "./openclaw-errors.mjs";
 import { providerConfigured, readOpenclawConfig } from "./openclaw-config.mjs";
+import { readUsageSnapshots, usageStatus, usageDisplayText, usageReadingIsStale, refreshStaleOverLimitReadings } from "./usage-limits.mjs";
+import { freshnessIssues, readInstallVersions } from "./install-freshness.mjs";
+
+import { PINNED_OPENCLAW_VERSION } from "./openclaw-install.mjs";
 
 const DAY = 86400000;
 
 /** Run a command asynchronously, bounded; resolves { ok, stdout }. Never rejects. */
-export function runBounded(cmd, args, { timeoutMs = 20000 } = {}) {
+export function runBounded(cmd, args, { timeoutMs = 20000, cwd } = {}) {
   return new Promise((resolve) => {
-    execFile(cmd, args, { encoding: "utf8", timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => resolve({ ok: !error, stdout: stdout ?? "" }));
+    execFile(cmd, args, { encoding: "utf8", timeout: timeoutMs, cwd, maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => resolve({ ok: !error, stdout: stdout ?? "" }));
   });
 }
 
 const versionOf = (text) => /(\d+)\.(\d+)\.(\d+)/.exec(String(text ?? ""))?.slice(1, 4).map(Number) ?? null;
 const older = (a, b) => { for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i] < b[i]; } return false; };
 
+/** Read OpenClaw's auth-list JSON, tolerating text before the JSON envelope. */
+export function parseOpenclawAuthProfiles(stdout) {
+  try {
+    const profiles = JSON.parse(stdout.slice(stdout.indexOf("{"))).profiles;
+    return Array.isArray(profiles) ? profiles : null;
+  } catch { return null; }
+}
+
+export { CODEX_IMPORT_RECOVERY, codexImportRecovery } from "./openclaw-runtime-health.mjs";
+
+function profileUsable(profile, now) {
+  if (profile?.expiresAt == null || profile.expiresAt === "") return true;
+  const expires = Date.parse(profile.expiresAt);
+  return Number.isFinite(expires) && expires > now;
+}
+
+function profileName(profile) {
+  const id = String(profile.id ?? profile.provider ?? "unknown");
+  const raw = [profile.label, profile.name, profile.displayName].find((value) => typeof value === "string" && value.trim());
+  if (!raw) return id;
+  const label = raw.trim();
+  if (label === id || label.startsWith(`${id} `)) return label;
+  return label.startsWith("(") ? `${id} ${label}` : `${id} (${label})`;
+}
+
 /** OAuth profiles near or past expiry, from `openclaw models auth list --json`. */
 export function loginExpiryIssues(authJson, { now = Date.now(), warnDays = 7 } = {}) {
+  const profiles = authJson?.profiles ?? [];
   const issues = [];
-  for (const p of authJson?.profiles ?? []) {
+  for (const p of profiles) {
     const at = Date.parse(p.expiresAt ?? "");
     if (!Number.isFinite(at)) continue;
     const days = Math.floor((at - now) / DAY);
     const who = p.provider === "openai" ? "Codex (ChatGPT plan)" : p.provider;
-    const fix = p.provider === "openai" ? "nomarmy agents add subscription codex  (then replace the existing codex agent)" : `openclaw models auth login --provider ${p.provider}`;
-    if (at <= now) issues.push({ id: `login-expired:${p.id}`, severity: "error", title: `${who} login has expired`, detail: `Auth profile ${p.provider} expired ${new Date(at).toISOString().slice(0, 10)}; every job on it will fail.`, fix, short: `${p.provider} login expired` });
-    else if (at - now <= warnDays * DAY) issues.push({ id: `login-expiring:${p.id}`, severity: "warn", title: `${who} login expires in ${days} day${days === 1 ? "" : "s"}`, detail: `Auth profile ${p.provider} expires ${new Date(at).toISOString().slice(0, 10)}.`, fix, short: `${p.provider} login ${days}d` });
+    const name = profileName(p);
+    const expired = at <= now;
+    const siblingValid = profiles.some((other) => other !== p && other.provider === p.provider && other.id !== p.id && profileUsable(other, now));
+    const fix = p.provider === "openai" ? codexImportRecovery({ profiles }) : `openclaw models auth login --provider ${p.provider}`;
+    if (expired) {
+      const detail = siblingValid
+        ? `Auth profile ${name} expired ${new Date(at).toISOString().slice(0, 10)}. OpenClaw may still pick it.`
+        : `Auth profile ${name} expired ${new Date(at).toISOString().slice(0, 10)}; every job on it will fail.`;
+      issues.push({ id: `login-expired:${p.id}`, severity: "error", title: `${who} login has expired: ${name}`, detail, fix, short: `${p.provider} login expired` });
+    } else if (at - now <= warnDays * DAY) issues.push({ id: `login-expiring:${p.id}`, severity: "warn", title: `${who} login expires in ${days} day${days === 1 ? "" : "s"}: ${name}`, detail: `Auth profile ${name} expires ${new Date(at).toISOString().slice(0, 10)}.`, fix, short: `${p.provider} login ${days}d` });
   }
   return issues;
 }
 
+/** Shared runtime preconditions for doctor and health. */
+export async function runtimeIssues({ run = runBounded, openclawCmd = process.env.NOMARMY_OPENCLAW_CMD || "openclaw", openclawAgent = "main", agents = {}, armySummary = null, modelsInUse = null, now = Date.now() } = {}) {
+  const paths = [`agents.entries.${openclawAgent}.modelPolicy.allow`, "agents.defaults.modelPolicy.allow"];
+  const [auth, ...policies] = await Promise.all([
+    run(openclawCmd, ["models", "auth", "list", "--json"]),
+    ...paths.map((p) => run(openclawCmd, ["config", "get", p, "--json"])),
+  ]);
+  const profiles = auth.ok ? parseOpenclawAuthProfiles(auth.stdout) : null;
+  const issues = profiles ? loginExpiryIssues({ profiles }, { now }) : [];
+  if (Object.values(agents ?? {}).some((a) => a.kind === "subscription" && a.provider === "openai")) {
+    issues.push(...codexImportIssues(profiles ?? [], { now }));
+  }
+  issues.push(...modelPolicyIssues({ policies, paths, agents, armySummary, modelsInUse }));
+  return issues;
+}
+
 /** OpenClaw behind npm's latest, and plugins behind OpenClaw. */
 export function versionIssues({ installed, latest, plugins = [] }) {
   const issues = [];
@@ -57,7 +114,7 @@ export function versionIssues({ installed, latest, plugins = [] }) {
   if (have && want && older(have, want)) {
     issues.push({ id: `openclaw-update:${want.join(".")}`, severity: "info", title: `OpenClaw ${want.join(".")} is out (you have ${have.join(".")})`,
       detail: "Its bundled model catalog lags new models; an old one made a working model look unavailable and budgeted new ones at the 32k fallback.",
-      fix: "npm update -g openclaw && openclaw doctor --fix  (when no nomArmy jobs are running)", short: "openclaw update" });
+      fix: older(have, versionOf(PINNED_OPENCLAW_VERSION)) ? "nomarmy doctor --fix  (installs the tested OpenClaw release, when no nomArmy jobs are running)" : "No automatic upgrade: nomArmy keeps the tested release or a newer installed version", short: "openclaw update" });
   }
   for (const p of plugins) {
     const pv = versionOf(p.version);
@@ -93,16 +150,21 @@ export function armyIssues(summary, mode = "local") {
  * from job records. A listed model isn't proof it runs: Muse was listed
  * while every job on it failed this way (a real Senti review).
  */
+/** The "<provider>/<model>" a job record says its vendor refused, or null. */
+export function refusedModelIn(record) {
+  const text = `${record?.workerError ?? ""} ${record?.worker?.error ?? ""}`;
+  // A job's own model_not_found line first (mcp/server.mjs names the model
+  // it attempted), then any raw vendor wording in older records.
+  const tagged = /model_not_found: ([\w.-]+\/[\w.:-]+)/.exec(text)?.[1];
+  return (tagged ?? modelRejection(text)?.model)?.replace(/[.:]+$/, "") ?? null; // the sentence's own trailing period isn't part of the name
+}
+
 export function unknownModelIssues(jobRecords, { now = Date.now(), inUse = null, probedOk = {} } = {}) {
   const failed = new Map(), lastOk = new Map(Object.entries(probedOk));
   for (const m of jobRecords) {
     const at = Date.parse(m.finishedAt ?? "");
     if (now - at > DAY) continue;
-    const text = `${m.workerError ?? ""} ${m.worker?.error ?? ""}`;
-    // A job's own model_not_found line first (mcp/server.mjs names the model
-    // it attempted), then any raw vendor wording in older records.
-    const tagged = /model_not_found: ([\w.-]+\/[\w.:-]+)/.exec(text)?.[1];
-    const model = (tagged ?? modelRejection(text)?.model)?.replace(/[.:]+$/, ""); // the sentence's own trailing period isn't part of the name
+    const model = refusedModelIn(m);
     if (model) { const f = failed.get(model) ?? { n: 0, last: 0 }; f.n++; f.last = Math.max(f.last, at); failed.set(model, f); }
     else if (m.worker?.provider && m.worker?.model && !m.workerError) {
       const ran = `${m.worker.provider}/${m.worker.model}`;
@@ -147,6 +209,43 @@ export function recordProbeSuccess(stateRoot, model, { now = Date.now() } = {})
   try { seen = JSON.parse(fs.readFileSync(file, "utf8")); } catch { /* first */ }
   seen[model] = new Date(now).toISOString();
   try { fs.writeFileSync(file, JSON.stringify(seen, null, 2)); } catch { /* best-effort */ }
+  clearModelRefusal(stateRoot, model);
+}
+
+// Models a vendor refused on a job, kept until a job or test call on them
+// works. A plan's model limit doesn't expire overnight (gpt-6-luna was
+// refused again days after the first time), so this isn't a 24-hour memory.
+// <stateRoot>/model-refusals.json: { "<provider>/<model>": { at, reason, retriedAt? } }.
+export const REFUSAL_RETRY_MS = 24 * 60 * 60 * 1000;
+const REFUSALS_FILE = "model-refusals.json";
+export function modelRefusals(stateRoot) {
+  try { const data = JSON.parse(fs.readFileSync(path.join(stateRoot, REFUSALS_FILE), "utf8")); return data && typeof data === "object" && !Array.isArray(data) ? data : {}; } catch { return {}; }
+}
+function writeRefusals(stateRoot, data) {
+  try { fs.mkdirSync(stateRoot, { recursive: true }); fs.writeFileSync(path.join(stateRoot, REFUSALS_FILE), JSON.stringify(data, null, 2)); } catch { /* best-effort */ }
+}
+export function recordModelRefusal(stateRoot, model, reason = null, { now = Date.now() } = {}) {
+  writeRefusals(stateRoot, { ...modelRefusals(stateRoot), [model]: { at: new Date(now).toISOString(), reason } });
+}
+/** Claim a stale refusal before a retry so overlapping calls do not re-test it. */
+export function claimModelRefusalRetry(stateRoot, model, { now = Date.now() } = {}) {
+  const data = modelRefusals(stateRoot);
+  const entry = data[model];
+  if (!entry || now - Date.parse(entry.at) < REFUSAL_RETRY_MS ||
+      (entry.retriedAt && now - Date.parse(entry.retriedAt) < REFUSAL_RETRY_MS)) return false;
+  data[model] = { ...entry, retriedAt: new Date(now).toISOString() };
+  writeRefusals(stateRoot, data);
+  return true;
+}
+export function clearModelRefusal(stateRoot, model) {
+  const data = modelRefusals(stateRoot);
+  if (!(model in data)) return;
+  delete data[model];
+  writeRefusals(stateRoot, data);
+}
+/** Whether a test call or a finished job has worked on `model` ("provider/model"). */
+export function modelProven(stateRoot, model) {
+  return Object.hasOwn(readProbeSuccesses(stateRoot), model);
 }
 function readProbeSuccesses(stateRoot) {
   try { return Object.fromEntries(Object.entries(JSON.parse(fs.readFileSync(path.join(stateRoot, "probe-ok.json"), "utf8"))).map(([k, v]) => [k, Date.parse(v)])); } catch { return {}; }
@@ -159,6 +258,8 @@ function readProbeSuccesses(stateRoot) {
  * ChatGPT plan failed job after job before health noticed). The issue, or null.
  */
 export function recentModelRefusal(stateRoot, model, { now = Date.now() } = {}) {
+  const kept = modelRefusals(stateRoot)[model];
+  if (kept) return { id: `unknown-model:${model}`, severity: "warn", title: `${model} was refused on a job (${kept.at.slice(0, 10)}) and hasn't worked since`, detail: kept.reason ?? "The provider won't run it, though it may be listed in the catalog.", fix: "nomarmy army assign <role> <agent> <another model>", short: `${model.split("/").pop()} not running` };
   const jobsRoot = path.join(stateRoot, "jobs");
   const records = [];
   let names = [];
@@ -183,19 +284,41 @@ export function leftoverIssues({ retainedWorktrees = 0, jobsBytes = 0, staleRunn
  * Run every check. `env` supplies what each needs, with real defaults;
  * tests pass their own.
  */
-export async function runHealthChecks({ now = Date.now(), mode = "local", openclawCmd = process.env.NOMARMY_OPENCLAW_CMD || "openclaw", run = runBounded, armySummary = null, agentsError = null, jobsRoot = null, pidAlive = () => true, agents = null, openclawConfig = null, vendors = {}, modelsInUse = null, autoPruned = null } = {}) {
+export async function runHealthChecks({ now = Date.now(), mode = "local", openclawCmd = process.env.NOMARMY_OPENCLAW_CMD || "openclaw", run = runBounded, armySummary = null, agentsError = null, jobsRoot = null, pidAlive = () => true, agents = null, openclawConfig = null, vendors = {}, modelsInUse = null, autoPruned = null, usageSnapshots = null, stateRoot = null, install = null } = {}) {
   const issues = [];
   if (autoPruned?.freedBytes) issues.push({ id: `auto-prune:${new Date(now).toISOString()}`, severity: "info",
     title: `Freed ${(autoPruned.freedBytes / 1024 ** 3).toFixed(2)} GB: ${[autoPruned.pruned ? `runtime data of ${autoPruned.pruned} finished job${autoPruned.pruned === 1 ? "" : "s"} older than ${autoPruned.olderThanHours}h` : null, autoPruned.scratchCleared ? `OpenClaw scratch files of ${autoPruned.scratchCleared} more` : null].filter(Boolean).join(", ")}`,
     detail: "Automatic; each job's record and report are kept. NOMARMY_AUTO_PRUNE_HOURS sets the age (0 turns it off).", fix: null, short: null });
   if (agents) issues.push(...providerConfigIssues({ agents, openclawConfig, vendors }));
-  const [auth, version, latest, plugins] = await Promise.all([
-    run(openclawCmd, ["models", "auth", "list", "--json"]),
+  usageSnapshots ??= stateRoot ? readUsageSnapshots(stateRoot) : null;
+  const staleOver = usageSnapshots && Object.values(usageSnapshots).some((snapshot) => usageReadingIsStale(usageStatus(snapshot, now)));
+  const [runtime, version, latest, plugins, nomarmyLatest, refreshed] = await Promise.all([
+    runtimeIssues({ run, openclawCmd, agents, armySummary, modelsInUse, now }),
     run(openclawCmd, ["--version"]),
     run("npm", ["view", "openclaw", "version"], { timeoutMs: 15000 }),
     run(openclawCmd, ["plugins", "inspect", "codex"]),
+    install ? run("npm", ["view", "nomarmy", "dist-tags.alpha"], { timeoutMs: 15000 }) : null,
+    staleOver ? refreshStaleOverLimitReadings(stateRoot, { run, now, snapshots: usageSnapshots, openclawCmd }) : null,
   ]);
-  if (auth.ok) { try { issues.push(...loginExpiryIssues(JSON.parse(auth.stdout.slice(auth.stdout.indexOf("{"))), { now })); } catch { /* unparseable: skip */ } }
+  const snapshots = refreshed?.snapshots ?? usageSnapshots;
+  const failedProviders = new Set(refreshed?.failedProviders ?? []);
+  if (snapshots) {
+    for (const [provider, snapshot] of Object.entries(snapshots)) {
+      const status = usageStatus(snapshot, now);
+      if (status.level === "ok") continue;
+      const short = `${provider} ${status.short}`;
+      const stale = usageReadingIsStale(status);
+      const detail = stale
+        ? `${usageDisplayText(status)}.${failedProviders.has(provider) ? ` ${refreshed.error}.` : ""}`
+        : `${status.text} (reading ${status.ageMinutes} minutes old).`;
+      issues.push({ id: `usage:${provider}:${status.level}`, severity: "warn", title: status.level === "over" ? `${provider} is at its usage limit` : `${provider} usage is ${status.short}`,
+        detail,
+        fix: status.level === "over" ? "wait for the reset, or move its roles with nomarmy army assign" : "plan remaining work or move its roles with nomarmy army assign",
+        short });
+    }
+  }
+  if (install) issues.push(...freshnessIssues({ ...install, latestVersion: nomarmyLatest?.ok ? nomarmyLatest.stdout : null }));
+  issues.push(...runtime);
   const pluginVersion = /Version:\s*(\S+)/.exec(plugins.stdout ?? "")?.[1];
   if (version.ok) issues.push(...versionIssues({ installed: version.stdout, latest: latest.ok ? latest.stdout : null, plugins: pluginVersion ? [{ id: "codex", version: pluginVersion }] : [] }));
   if (agentsError) issues.push({ id: `config:agents:${agentsError}`, severity: "error", title: "agents.yml can't be loaded", detail: agentsError, fix: "nomarmy agents list (shows the problem)", short: "agents.yml broken" });
@@ -245,6 +368,18 @@ export function recordHealth(file, result, { now = Date.now() } = {}) {
   return toNotify;
 }
 
+/** Read versions and harnesses only from MCP registrations that launch nomArmy. */
+export async function readRegisteredInstall({ projectDir, run = runBounded, installDir, cursorConfigPath, homeDir } = {}) {
+  const { registeredMcpCopies } = await import("./connect.mjs");
+  const { loadHarnesses } = await import("./harnesses.mjs");
+  const registered = await registeredMcpCopies({ projectDir, run, installDir, cursorConfigPath, homeDir });
+  if (!registered.length) return null;
+  return { registrations: registered.map(({ target, scope, serverPath }) => {
+    const copyDir = path.dirname(path.dirname(serverPath));
+    return { target, scope, ...readInstallVersions(copyDir), copyHarnesses: Object.keys(loadHarnesses(path.join(copyDir, "harnesses")).harnesses).length };
+  }) };
+}
+
 /**
  * Everything a check run needs, gathered the same way for the server's
  * periodic run and `nomarmy health`, then run and recorded to the shared
@@ -277,8 +412,17 @@ export async function checkAndRecordHealth({ projectDir, stateRoot, configDir, n
   let autoPruned = null;
   if (ageMs !== null) { try { autoPruned = { ...pruneJobRuntime({ stateRoot, olderThanMs: ageMs, now }), olderThanHours: ageMs / 3600000 }; } catch { /* best-effort */ } }
   const mode = executionMode(env).mode;
+  const install = await readRegisteredInstall({ projectDir });
   const result = await runHealthChecks({ now, mode, armySummary, agentsError, jobsRoot: path.join(stateRoot, "jobs"), pidAlive,
-    agents, openclawConfig: readOpenclawConfig(), vendors: SUBSCRIPTION_VENDORS, modelsInUse, autoPruned });
+    agents, openclawConfig: readOpenclawConfig(), vendors: SUBSCRIPTION_VENDORS, modelsInUse, autoPruned, usageSnapshots: readUsageSnapshots(stateRoot), stateRoot, install });
+  try {
+    const { loadJobRecords, agentLookup } = await import("./stats.mjs");
+    const { recentSuggestions } = await import("./suggestions.mjs");
+    for (const s of recentSuggestions(loadJobRecords(path.join(stateRoot, "jobs")), { projectDir, agentFor: agents ? agentLookup(agents, agentProviderId) : () => null, now })) {
+      if (s.level !== "warn" && s.level !== "act") continue;
+      result.issues.push({ id: `suggestion:${s.key}`, severity: "warn", title: s.title, detail: s.evidence, fix: s.command ?? "nomarmy stats (routing suggestions)", short: s.level === "act" ? "review needed" : "routing tip" });
+    }
+  } catch { /* suggestions never break a health check */ }
   const toNotify = recordHealth(path.join(stateRoot, "health.json"), result, { now });
   return { result, toNotify };
 }

package/lib/install-freshness.mjs

@@ -0,0 +1,114 @@
+// Whether the nomArmy a coordinator runs is current. Claude Code, Codex and
+// Cursor run a copy of the server that `nomarmy connect` puts in the install
+// dir, and each session keeps the code it started with. So an upgrade can
+// stall at three points, each checked here:
+//
+//   nomarmy-update  npm's alpha release is newer than the installed CLI
+//   nomarmy-copy    the CLI is newer than the copy coordinators run
+//                   (`nomarmy connect` wasn't re-run)
+//   restart         the copy on disk changed after this server started
+//                   (the session wasn't restarted); per session, so it is
+//                   reported by that session's server, not in health.json
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/** Written into the install dir by `nomarmy connect`: where the copy came from. */
+export const SOURCE_FILE = "source.json";
+
+export function readPackageVersion(root) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version ?? null; }
+  catch { return null; }
+}
+
+/** The checkout's commit, for a git install; null for an npm install. */
+export function readSourceCommit(root) {
+  if (!fs.existsSync(path.join(root, ".git"))) return null;
+  try { return execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null; }
+  catch { return null; }
+}
+
+export function recordCopySource(installDir, nomarmyRoot) {
+  const commit = readSourceCommit(nomarmyRoot);
+  fs.writeFileSync(path.join(installDir, SOURCE_FILE), JSON.stringify({ root: nomarmyRoot, version: readPackageVersion(nomarmyRoot), ...(commit ? { commit } : {}) }, null, 2) + "\n");
+}
+
+/**
+ * Whether the copy in installDir is behind the checkout or package at
+ * nomarmyRoot: an older version, a different commit (a git install moves on
+ * without a version bump), or no record of its source at all.
+ */
+export function copyIsStale(installDir, nomarmyRoot) {
+  let source = null;
+  try { source = JSON.parse(fs.readFileSync(path.join(installDir, SOURCE_FILE), "utf8")); } catch { return true; }
+  const copyVersion = readPackageVersion(installDir), rootVersion = readPackageVersion(nomarmyRoot);
+  if (!copyVersion || !rootVersion || copyVersion !== rootVersion) return true;
+  const commit = readSourceCommit(nomarmyRoot);
+  return Boolean(commit && source.commit !== commit);
+}
+
+/** The copy's version and, when connect recorded it, the version now at its source. */
+export function readInstallVersions(installDir) {
+  let source = null;
+  try { source = JSON.parse(fs.readFileSync(path.join(installDir, SOURCE_FILE), "utf8")); } catch { /* connected before source.json existed */ }
+  return { copyVersion: readPackageVersion(installDir), sourceVersion: source?.root ? readPackageVersion(source.root) : null };
+}
+
+/** Semver order, prerelease included (0.1.0-alpha.7 < 0.1.0-alpha.10 < 0.1.0). */
+export function compareVersions(a, b) {
+  const split = (v) => { const [main, pre] = String(v).trim().replace(/^v/, "").split("-", 2); return { main: main.split(".").map(Number), pre: pre ? pre.split(".") : null }; };
+  const x = split(a), y = split(b);
+  for (let i = 0; i < 3; i++) if ((x.main[i] || 0) !== (y.main[i] || 0)) return (x.main[i] || 0) < (y.main[i] || 0) ? -1 : 1;
+  if (!x.pre || !y.pre) return x.pre === y.pre ? 0 : x.pre ? -1 : 1;
+  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+    const p = x.pre[i], q = y.pre[i];
+    if (p === undefined || q === undefined) return p === undefined ? -1 : 1;
+    if (p === q) continue;
+    const pn = /^\d+$/.test(p), qn = /^\d+$/.test(q);
+    if (pn && qn) return Number(p) < Number(q) ? -1 : 1;
+    if (pn !== qn) return pn ? -1 : 1;
+    return p < q ? -1 : 1;
+  }
+  return 0;
+}
+
+const valid = (v) => typeof v === "string" && /^v?\d+\.\d+\.\d+/.test(v.trim());
+
+/** Health issues for a stale CLI, a stale installed copy, or a copy missing its harnesses. */
+export function freshnessIssues({ copyVersion = null, sourceVersion = null, latestVersion = null, copyHarnesses = null, registrations = null, target = "claude", scope = "user" }) {
+  if (registrations) return registrations.flatMap((copy, index) => freshnessIssues({ ...copy, latestVersion: index === 0 ? latestVersion : null }));
+  const reconnect = `nomarmy connect ${target}${scope === "user" ? "" : ` --scope ${scope}`}`;
+  const fix = registrations === null && target === "claude" && scope === "user" ? "nomarmy connect claude (and codex, cursor), then restart those sessions" : `${reconnect}, then restart that session`;
+  const issues = [];
+  if (valid(copyVersion) && copyHarnesses === 0) {
+    issues.push({ id: `nomarmy-harnesses:${copyVersion}`, severity: "error", title: "The nomArmy your coordinators run has no harnesses",
+      detail: "Jobs match no harness, so they run in the plain base image: no dependencies, fake services, browser tests or artifacts.",
+      fix, short: "no harnesses" });
+  }
+  if (valid(latestVersion) && valid(sourceVersion) && compareVersions(sourceVersion, latestVersion) < 0) {
+    const latest = latestVersion.trim();
+    issues.push({ id: `nomarmy-update:${latest}`, severity: "info", title: `nomArmy ${latest} is out (you have ${sourceVersion})`,
+      detail: "Updating installs it, reconnects your coordinators and tells you which sessions to restart.",
+      fix: "nomarmy update", short: "nomarmy update" });
+  }
+  if (valid(sourceVersion) && valid(copyVersion) && compareVersions(copyVersion, sourceVersion) < 0) {
+    issues.push({ id: `nomarmy-copy:${sourceVersion}`, severity: "warn", title: `Your coordinators run nomArmy ${copyVersion}, but ${sourceVersion} is installed`,
+      detail: "Claude Code, Codex and Cursor run a copy of nomArmy that only `nomarmy connect` refreshes.",
+      fix, short: "nomarmy reconnect" });
+  }
+  return issues;
+}
+
+/**
+ * For the running server: a notice when its copy on disk changed after it
+ * started, so this session still runs the old code. Null when current.
+ */
+export function restartNotice({ serverFile, startedAtMs, runningVersion, stat = fs.statSync, readVersion = readPackageVersion }) {
+  let changedMs;
+  try { changedMs = stat(serverFile).mtimeMs; } catch { return null; }
+  if (!(changedMs > startedAtMs)) return null;
+  const onDisk = readVersion(path.join(path.dirname(serverFile), ".."));
+  const versions = onDisk && onDisk !== runningVersion ? ` (this session runs ${runningVersion}; ${onDisk} is installed)` : "";
+  return `nomArmy was updated after this session started${versions}. Restart this session to use the new version; until then it runs the old code.`;
+}

package/lib/jev-checks.mjs

@@ -0,0 +1,110 @@
+// nomArmy's Jev checks (see lib/validators.mjs): narrow judgments on evidence
+// nomArmy already has, each able only to add a review flag.
+//
+//   scout-citations  nomArmy verifies a scout's [path:line] exists and attaches
+//                    the lines; this asks whether those lines support the
+//                    finding (the shape of TypeSafe's citation-check cookbook).
+//   report-claims    whether a worker's report matches its diff. Found live: a
+//                    worker's note said "restored check.js to base commit"
+//                    while its diff rewrote check.js.
+
+import { askJev, jevBreaker, tripJevBreaker } from "./validators.mjs";
+
+// A flag needs the model to lean clearly; the rest is left to the General.
+export const FLAG_AT = 0.7;
+const DIFF_CHARS = 60000;           // well inside the 32k-token state budget
+const MAX_FINDINGS = 24;
+// The report's excerpts are capped at 12 lines for the General's context; Jev
+// judges the whole cited range (to this cap), or a long range looks
+// unrelated when the supporting line is past the excerpt.
+const CITED_LINES = 80;
+const CONCURRENCY = 4;
+// However many findings, a job never waits longer than this on Jev.
+const JOB_BUDGET_MS = 45000;
+
+// The answer, or null with the breaker tripped: any failure means TypeSafe
+// isn't answering well right now, so stop asking (lib/validators.mjs).
+async function guarded(ask, request, errors) {
+  if (jevBreaker().open) { errors.push(`skipped: Jev failed recently (${jevBreaker().reason}); retrying after ${jevBreaker().retryAt}`); return null; }
+  try { return await ask(request); }
+  catch (error) { const why = error?.name === "AbortError" ? "timed out" : error.message; tripJevBreaker(why); errors.push(why); return null; }
+}
+
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (next < items.length) { const i = next++; out[i] = await fn(items[i], i); }
+  }));
+  return out;
+}
+
+const SUPPORT_QUESTION = {
+  type: "choice",
+  instructions: "A code researcher made the claim in `finding` and cited the source lines in `cited` as evidence. Judge only what the cited lines show, not whether the claim might be true elsewhere in the codebase. How do the cited lines relate to the claim?",
+  criteria: {
+    supports: "The cited lines directly show what the claim says.",
+    contradicts: "The cited lines show something different from, or opposite to, the claim.",
+    unrelated: "The cited lines don't address the claim: they're about something else, or too little of the claim is visible in them.",
+  },
+};
+
+/**
+ * For each finding with verified cited lines: does the evidence support it?
+ * @returns {Promise<{ flags: {index: number, verdict: string, probability: number}[], checked: number, errors: string[], usage: number }>}
+ */
+export async function checkScoutCitations({ findings = [], settings, ask = askJev, readFile = null }) {
+  const fileCache = new Map();
+  const fullRange = async (c) => {
+    if (!readFile) return null;
+    if (!fileCache.has(c.path)) fileCache.set(c.path, readFile(c.path).then((t) => (typeof t === "string" ? t.split("\n") : null)).catch(() => null));
+    const lines = await fileCache.get(c.path);
+    if (!lines) return null;
+    const end = Math.min(c.end, c.start + CITED_LINES - 1, lines.length);
+    return Array.from({ length: Math.max(0, end - c.start + 1) }, (_, k) => `${c.start + k}: ${lines[c.start + k - 1]}`).join("\n");
+  };
+  const candidates = findings.map((f, index) => ({ f, index }))
+    .filter(({ f }) => (f.citations ?? []).some((c) => c.status === "ok" && c.excerpt?.length)).slice(0, MAX_FINDINGS);
+  const errors = [];
+  let usage = 0;
+  const deadline = Date.now() + JOB_BUDGET_MS;
+  const verdicts = await mapLimit(candidates, CONCURRENCY, async ({ f, index }) => {
+    if (Date.now() > deadline) { errors.push("skipped the rest: over the job's time budget for Jev"); return null; }
+    const cited = await Promise.all(f.citations.filter((c) => c.status === "ok" && c.excerpt?.length)
+      .map(async (c) => ({ file: c.path, lines: `${c.start}-${c.end}`, text: (await fullRange(c)) ?? c.excerpt.map((l) => `${l.line}: ${l.text}`).join("\n") })));
+    const r = await guarded(ask, { key: settings.key, model: settings.model, state: { finding: f.text, cited }, questions: { support: SUPPORT_QUESTION } }, errors);
+    if (!r) return null;
+    usage += r.usage?.input_tokens ?? 0;
+    const a = r.answers?.support;
+    return a ? { index, verdict: a.choice, probability: a.probabilities?.[a.choice] ?? 0 } : null;
+  });
+  const flags = verdicts.filter((v) => v && v.verdict !== "supports" && v.probability >= FLAG_AT);
+  return { flags, checked: verdicts.filter(Boolean).length, errors: [...new Set(errors)].slice(0, 3), usage, verdicts: verdicts.filter(Boolean) };
+}
+
+const CLAIMS_QUESTION = {
+  type: "choice",
+  instructions: "A coding worker wrote the report in `report` about the change it made. `diff` shows every change from the base commit it started from: a file that isn't in the diff is exactly as it was at the base commit, and a file restored to the base commit wouldn't appear. Judge only the concrete things the report says were done or changed. Does the diff match them?",
+  criteria: {
+    consistent: "The concrete things the report says were done are what the diff shows.",
+    contradicts: "The diff shows a concrete claim in the report is false: something said to be done, restored, removed or left alone wasn't, or was done differently.",
+    unclear: "The report makes no concrete claim the diff can confirm or refute, or the diff shown is too partial to tell.",
+  },
+};
+
+/**
+ * Does the worker's report match its diff?
+ * @returns {Promise<{ flag: {verdict: string, probability: number}|null, verdict: object|null, error: string|null, usage: number, truncated: boolean }>}
+ */
+export async function checkReportClaims({ report, diff, settings, ask = askJev }) {
+  const note = [report?.note, report?.notDone && report.notDone !== "none" ? `Not done: ${report.notDone}` : null].filter(Boolean).join("\n");
+  if (!note.trim() || !String(diff ?? "").trim()) return { flag: null, verdict: null, error: null, usage: 0, truncated: false };
+  const truncated = diff.length > DIFF_CHARS;
+  const state = { report: { status: report.status ?? null, tests: report.tests ?? null, note }, diff: truncated ? `${diff.slice(0, DIFF_CHARS)}\n[diff truncated]` : diff };
+  const errors = [];
+  const r = await guarded(ask, { key: settings.key, model: settings.model, state, questions: { claims: CLAIMS_QUESTION } }, errors);
+  if (!r) return { flag: null, verdict: null, error: errors[0] ?? "no answer", usage: 0, truncated };
+  const a = r.answers?.claims;
+  const verdict = a ? { verdict: a.choice, probability: a.probabilities?.[a.choice] ?? 0 } : null;
+  return { flag: verdict && verdict.verdict === "contradicts" && verdict.probability >= FLAG_AT ? verdict : null, verdict, error: null, usage: r.usage?.input_tokens ?? 0, truncated };
+}