nomarmy 0.1.0-alpha.0

package/lib/health.mjs

@@ -0,0 +1,278 @@
+// nomArmy health checks: the mechanical problems that have actually bitten
+// a real run, found before they fail one. Deterministic, no model, cheap;
+// every external command is async and time-limited, so a check can never
+// stall the server that runs it.
+//
+//   login-expiry     an OAuth login (the ChatGPT plan's Codex import) about
+//                    to expire or already expired
+//   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
+//
+// Each issue: { id, severity: "error"|"warn"|"info", title, detail, fix,
+// short }. `id` is stable across runs, so a notification goes out once per
+// issue rather than on every check; `short` is what the status line shows.
+
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { modelRejection } from "./openclaw-errors.mjs";
+import { providerConfigured, readOpenclawConfig } from "./openclaw-config.mjs";
+
+const DAY = 86400000;
+
+/** Run a command asynchronously, bounded; resolves { ok, stdout }. Never rejects. */
+export function runBounded(cmd, args, { timeoutMs = 20000 } = {}) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { encoding: "utf8", timeout: timeoutMs, 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; };
+
+/** OAuth profiles near or past expiry, from `openclaw models auth list --json`. */
+export function loginExpiryIssues(authJson, { now = Date.now(), warnDays = 7 } = {}) {
+  const issues = [];
+  for (const p of authJson?.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` });
+  }
+  return issues;
+}
+
+/** OpenClaw behind npm's latest, and plugins behind OpenClaw. */
+export function versionIssues({ installed, latest, plugins = [] }) {
+  const issues = [];
+  const have = versionOf(installed), want = versionOf(latest);
+  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" });
+  }
+  for (const p of plugins) {
+    const pv = versionOf(p.version);
+    if (have && pv && older(pv, have)) {
+      issues.push({ id: `plugin-skew:${p.id}:${pv.join(".")}`, severity: "info", title: `OpenClaw's ${p.id} plugin (${pv.join(".")}) is older than OpenClaw (${have.join(".")})`,
+        detail: "OpenClaw tries to upgrade it on its own and warns while no matching version is published; the installed one keeps working meanwhile.",
+        fix: `openclaw update repair  (once @openclaw/${p.id} ${have.join(".")} is published)`, short: null });
+    }
+  }
+  return issues;
+}
+
+/** Roles, and the General, pointing at something unusable (from describeArmy's summary). */
+export function armyIssues(summary) {
+  const issues = [];
+  if (summary?.general?.problem) issues.push({ id: "army:general", severity: "warn", title: "The General's agent isn't set up", detail: summary.general.problem, fix: "nomarmy army general <agent>", short: null });
+  for (const [role, r] of Object.entries(summary?.roles ?? {})) {
+    if (r.problem) issues.push({ id: `army:role:${role}:${r.problem}`, severity: "warn", title: `Role ${role} can't be dispatched`, detail: r.problem, fix: `nomarmy army assign ${role} <agent> [model|auto]`, short: `${role} unusable` });
+    else if (r.hostTools?.implementRole && !r.hostTools.allowed) issues.push({ id: `army:host-tools:${role}:${r.agent}`, severity: "warn",
+      title: `Role ${role} builds on ${r.agent}, whose tools run on this machine`,
+      detail: `${r.agent}'s worker runs its own shell on your machine, with your files and the network, outside nomArmy's sandbox, so nomArmy refuses implement jobs on it.`,
+      fix: `nomarmy army assign ${role} <a sandboxed agent> [model], or set allow_host_tools: true on ${r.agent} in agents.yml to accept it`, short: `${role} unsandboxed` });
+  }
+  return issues;
+}
+
+/**
+ * Models the provider refused (model_not_found, "Unknown model") on a real job in the last day,
+ * 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).
+ */
+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
+    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}`;
+      lastOk.set(ran, Math.max(lastOk.get(ran) ?? 0, at));
+    }
+  }
+  // Fixed since: a later job on it ran, or no role uses it any more.
+  return [...failed].filter(([model, f]) => !(lastOk.get(model) > f.last) && !(inUse && !inUse.has(model))).map(([model, { n }]) => ({ id: `unknown-model:${model}`, severity: "warn",
+    title: `${model} failed as an unknown or unsupported model on ${n} job${n === 1 ? "" : "s"} today`,
+    detail: "OpenClaw or the provider won't run it (it may still be listed in the catalog), so every role on it fails.",
+    fix: "nomarmy agents list (see which roles use it), then nomarmy army assign <role> <another agent> [model]", short: `${model.split("/").pop()} not running` }));
+}
+
+/**
+ * Subscription agents whose provider has no entry in OpenClaw's config,
+ * for vendors whose plugin writes one (lib/openclaw-config.mjs): every
+ * model on them is listed but fails "Unknown model".
+ */
+export function providerConfigIssues({ agents = {}, openclawConfig = null, vendors = {} }) {
+  if (!openclawConfig) return [];
+  const issues = [];
+  for (const [vendorKey, vendor] of Object.entries(vendors)) {
+    if (!vendor.plugin?.providerConfig) continue;
+    const users = Object.entries(agents).filter(([, a]) => a?.kind === "subscription" && a.provider === vendor.provider).map(([n]) => n);
+    if (!users.length || providerConfigured(openclawConfig, vendor.provider)) continue;
+    issues.push({ id: `provider-config:${vendor.provider}`, severity: "warn",
+      title: `OpenClaw has no ${vendor.provider} provider entry, so ${users.join(", ")} can't run`,
+      detail: `Its models are listed (the catalog asks ${vendor.provider} directly) but every job fails "Unknown model": the key is linked, the provider's config isn't.`,
+      fix: `nomarmy agents add subscription ${vendorKey}  (adds it with the plugin's own setup step)`, short: `${vendor.provider} not set up` });
+  }
+  return issues;
+}
+
+/**
+ * A real test call that worked (`army assign`, `agents update --probe`), in
+ * the shared probe-ok.json: it clears a model's earlier failure warning the
+ * same way a later successful job does.
+ */
+export function recordProbeSuccess(stateRoot, model, { now = Date.now() } = {}) {
+  const file = path.join(stateRoot, "probe-ok.json");
+  let seen = {};
+  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 */ }
+}
+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 {}; }
+}
+
+/**
+ * Whether `model` ("provider/model") was refused on a job in the last day
+ * with nothing working on it since -- the admission check that stops a
+ * second job going to a model the vendor already rejected (gpt-6-sol on a
+ * ChatGPT plan failed job after job before health noticed). The issue, or null.
+ */
+export function recentModelRefusal(stateRoot, model, { now = Date.now() } = {}) {
+  const jobsRoot = path.join(stateRoot, "jobs");
+  const records = [];
+  let names = [];
+  try { names = fs.readdirSync(jobsRoot); } catch { return null; }
+  for (const name of names) {
+    const file = path.join(jobsRoot, name, "metadata.json");
+    try { if (now - fs.statSync(file).mtimeMs < DAY) records.push(JSON.parse(fs.readFileSync(file, "utf8"))); } catch { /* unfinished */ }
+  }
+  return unknownModelIssues(records, { now, probedOk: readProbeSuccesses(stateRoot) }).find((i) => i.id === `unknown-model:${model}`) ?? null;
+}
+
+/** Job storage and leftovers. */
+export function leftoverIssues({ retainedWorktrees = 0, jobsBytes = 0, staleRunning = 0 }) {
+  const issues = [];
+  if (retainedWorktrees >= 15) issues.push({ id: `leftovers:worktrees:${Math.floor(retainedWorktrees / 15)}`, severity: "info", title: `${retainedWorktrees} job worktrees are being kept`, detail: "Failed and incomplete jobs keep their worktree for review; they add up.", fix: "local_worker_sweep (empty ones), local_worker_cleanup (reviewed ones)", short: null });
+  if (jobsBytes >= 2 * 1024 ** 3) issues.push({ id: `leftovers:storage:${Math.floor(jobsBytes / 1024 ** 3)}`, severity: "warn", title: `Job storage is ${(jobsBytes / 1024 ** 3).toFixed(1)} GB`, detail: "Mostly per-job runtime directories (npm caches, harness state).", fix: "nomarmy jobs --prune --older-than 0  (removes runtime data from every finished job now; records and reports stay, only saved transcripts go). Finished jobs older than a day are pruned on their own, so what's left is recent jobs and kept worktrees (local_worker_sweep / local_worker_cleanup).", short: `jobs ${(jobsBytes / 1024 ** 3).toFixed(0)}GB` });
+  if (staleRunning > 0) issues.push({ id: `leftovers:stale:${staleRunning}`, severity: "info", title: `${staleRunning} job${staleRunning === 1 ? "" : "s"} still marked running by a server that's gone`, detail: "Its outcome is unknown; its worktree may hold work.", fix: "nomarmy jobs (shows them as orphaned), then review or clean up", short: null });
+  return issues;
+}
+
+/**
+ * Run every check. `env` supplies what each needs, with real defaults;
+ * tests pass their own.
+ */
+export async function runHealthChecks({ now = Date.now(), 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 } = {}) {
+  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"]),
+    run(openclawCmd, ["--version"]),
+    run("npm", ["view", "openclaw", "version"], { timeoutMs: 15000 }),
+    run(openclawCmd, ["plugins", "inspect", "codex"]),
+  ]);
+  if (auth.ok) { try { issues.push(...loginExpiryIssues(JSON.parse(auth.stdout.slice(auth.stdout.indexOf("{"))), { now })); } catch { /* unparseable: skip */ } }
+  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" });
+  if (armySummary) issues.push(...armyIssues(armySummary));
+  if (jobsRoot) {
+    let retainedWorktrees = 0, jobsBytes = 0, staleRunning = 0;
+    const records = [];
+    let names = [];
+    try { names = fs.readdirSync(jobsRoot); } catch { /* none */ }
+    for (const name of names) {
+      const dir = path.join(jobsRoot, name);
+      if (fs.existsSync(path.join(dir, "worktree"))) retainedWorktrees++;
+      try { const st = fs.statSync(path.join(dir, "metadata.json")); if (now - st.mtimeMs < DAY) records.push(JSON.parse(fs.readFileSync(path.join(dir, "metadata.json"), "utf8"))); } catch { /* not finished */ }
+      try {
+        const status = JSON.parse(fs.readFileSync(path.join(dir, "status.json"), "utf8"));
+        if (status.state === "running" && !pidAlive(status.serverPid)) staleRunning++;
+      } catch { /* no status */ }
+    }
+    const du = await run("du", ["-sk", jobsRoot], { timeoutMs: 30000 });
+    if (du.ok) jobsBytes = (Number(du.stdout.split(/\s/)[0]) || 0) * 1024;
+    issues.push(...unknownModelIssues(records, { now, inUse: modelsInUse, probedOk: readProbeSuccesses(path.dirname(jobsRoot)) }));
+    issues.push(...leftoverIssues({ retainedWorktrees, jobsBytes, staleRunning }));
+  }
+  const rank = { error: 0, warn: 1, info: 2 };
+  issues.sort((a, b) => rank[a.severity] - rank[b.severity]);
+  return { checkedAt: new Date(now).toISOString(), issues };
+}
+
+/**
+ * Save results to the shared health.json, returning the issues that are new
+ * enough to notify about: warn/error ones not notified in the last day by
+ * any session's server (several sessions run checks; one notification each).
+ */
+export function recordHealth(file, result, { now = Date.now() } = {}) {
+  let prev = {};
+  try { prev = JSON.parse(fs.readFileSync(file, "utf8")); } catch { /* first run */ }
+  const notified = { ...(prev.notified ?? {}) };
+  const toNotify = [];
+  for (const issue of result.issues) {
+    if (issue.severity === "info") continue;
+    if (!notified[issue.id] || now - Date.parse(notified[issue.id]) > DAY) { toNotify.push(issue); notified[issue.id] = new Date(now).toISOString(); }
+  }
+  for (const id of Object.keys(notified)) if (now - Date.parse(notified[id]) > 7 * DAY) delete notified[id];
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(`${file}.tmp`, JSON.stringify({ ...result, notified }, null, 2));
+  fs.renameSync(`${file}.tmp`, file);
+  return toNotify;
+}
+
+/**
+ * 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
+ * health.json. Returns { result, toNotify }.
+ */
+export async function checkAndRecordHealth({ projectDir, stateRoot, configDir, now = Date.now() }) {
+  const { loadAgents, describeAgent, agentProviderId } = await import("./agents.mjs");
+  const { loadArmy, describeArmy } = await import("./army.mjs");
+  const { pidAlive } = await import("./slots.mjs");
+  let agents = null, agentsError = null, armySummary = null;
+  try { agents = loadAgents(configDir).agents; } catch (error) { agentsError = String(error.message).split("\n")[0]; }
+  if (agents) { try { armySummary = describeArmy(loadArmy({ projectDir }), { agents, describeAgent }); } catch (error) { agentsError = agentsError ?? `army: ${String(error.message).split("\n")[0]}`; } }
+  const { SUBSCRIPTION_VENDORS } = await import("./subscription-setup.mjs");
+  // provider/model each role runs on, so a failure on a model no role uses
+  // any more (it was reassigned) stops warning.
+  let modelsInUse = null;
+  if (agents && armySummary) {
+    modelsInUse = new Set();
+    for (const r of Object.values(armySummary.roles ?? {})) {
+      const a = agents[r.agent];
+      if (!a || !r.model || r.modelIsAuto) continue;
+      try { modelsInUse.add(`${agentProviderId(a)}/${r.model}`); } catch { /* unknown shape: skip */ }
+    }
+  }
+  // Finished jobs' runtime data goes on its own (lib/prune.mjs): about
+  // 100 MB a job, useful for a day at most, and no decision to make. Before
+  // the checks, so the storage warning is about what's left.
+  const { pruneJobRuntime, autoPruneAgeMs } = await import("./prune.mjs");
+  const ageMs = autoPruneAgeMs();
+  let autoPruned = null;
+  if (ageMs !== null) { try { autoPruned = { ...pruneJobRuntime({ stateRoot, olderThanMs: ageMs, now }), olderThanHours: ageMs / 3600000 }; } catch { /* best-effort */ } }
+  const result = await runHealthChecks({ now, armySummary, agentsError, jobsRoot: path.join(stateRoot, "jobs"), pidAlive,
+    agents, openclawConfig: readOpenclawConfig(), vendors: SUBSCRIPTION_VENDORS, modelsInUse, autoPruned });
+  const toNotify = recordHealth(path.join(stateRoot, "health.json"), result, { now });
+  return { result, toNotify };
+}

package/lib/model-catalog.mjs

@@ -0,0 +1,71 @@
+// Reads OpenClaw's own model catalog for a hosted model's real context
+// window -- deliberately NOT a second, hand-maintained table of the same
+// numbers inside nomArmy, which would only ever go stale (this is exactly
+// the class of thing a sharp reviewer flags first). OpenClaw already tracks
+// this per "<provider>/<model>" key, the same key nomArmy already composes
+// for dispatch (see resolvePoolSelection in mcp/server.mjs), and refreshes
+// it itself (`openclaw models list --refresh`) independently of nomArmy.
+//
+// A brand-new model (verified live: xai/grok-4.7, released the same day
+// this was written) will not be in OpenClaw's CACHED catalog until that
+// refresh runs -- lib/dispatch-config.mjs's context_window override exists
+// specifically for that gap, not as a alternative to this lookup.
+import { execFile, execFileSync } from "node:child_process";
+
+// Bounded: this runs inside the MCP server, where a synchronous call with no
+// timeout blocks every request the server handles until it returns.
+const SYNC_TIMEOUT_MS = 20000;
+const ASYNC_TIMEOUT_MS = 180000;
+
+function defaultRun(cmd, args) {
+  // "Gateway is not running..." and similar operational notices land on
+  // OpenClaw's stderr, not stdout (verified live) -- stdout alone parses as
+  // clean JSON regardless of whether that notice fires.
+  return execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: SYNC_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 });
+}
+
+function parseCatalog(raw) {
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return null; }
+  const byKey = new Map();
+  for (const m of parsed?.models ?? []) {
+    if (m?.key && Number.isFinite(m.contextWindow) && m.contextWindow > 0) byKey.set(m.key, m.contextWindow);
+  }
+  return byKey;
+}
+
+/**
+ * The same query, off the caller's thread. `--refresh` contacts every
+ * provider (about 15 seconds when they're healthy, unbounded when one
+ * stalls), so the MCP server runs it this way: run synchronously, a stalled
+ * provider froze the whole server -- the likeliest cause of a status call
+ * that hung for 35 minutes in a real Senti run.
+ * @returns {Promise<Map<string, number>|null>}
+ */
+export function queryModelCatalogAsync({ openclawCmd = process.env.NOMARMY_OPENCLAW_CMD || "openclaw", refresh = false, timeoutMs = ASYNC_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    execFile(openclawCmd, ["models", "list", "--all", "--json", ...(refresh ? ["--refresh"] : [])],
+      { encoding: "utf8", timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 },
+      (error, stdout) => resolve(error ? null : parseCatalog(stdout)));
+  });
+}
+
+/**
+ * @returns {Map<string, number>|null} "<provider>/<model>" -> context window
+ *   in tokens, or null if openclaw isn't reachable/installed/erroring. Never
+ *   throws -- a missing catalog is a fallback case for the caller, not a
+ *   failure of this function.
+ */
+// `refresh` asks OpenClaw to re-discover every provider's models first
+// (about 15 seconds, confirmed live). Without it the cached catalog may hold
+// no entries at all for a provider OpenClaw hasn't refreshed yet (seen live:
+// openai, xai and meta all absent while claude-cli was present).
+export function queryModelCatalog({ openclawCmd = process.env.NOMARMY_OPENCLAW_CMD || "openclaw", run = defaultRun, refresh = false } = {}) {
+  let raw;
+  try {
+    raw = run(openclawCmd, ["models", "list", "--all", "--json", ...(refresh ? ["--refresh"] : [])]);
+  } catch {
+    return null;
+  }
+  return parseCatalog(raw);
+}

package/lib/notifier-app.mjs

@@ -0,0 +1,95 @@
+// Builds nomArmy.app, the macOS notifier (notifier/main.swift), so
+// notifications carry nomArmy's icon instead of Script Editor's.
+//
+// Built on this machine by `nomarmy connect` (swiftc, sips, iconutil and an
+// ad-hoc codesign, all part of Xcode's command-line tools), into nomArmy's
+// state directory, and only rebuilt when the source or icon changes. Two
+// things found live on macOS 26: an AppleScript applet's notifications were
+// dropped (it never registered with Notification Center), and macOS refused
+// a bundle id it had already seen refused. The bundle id below is the one
+// the person was asked about and allowed; changing it asks them again.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+export const NOTIFIER_BUNDLE_ID = "com.rayson-tech.nomarmy.notifier2";
+const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+
+/** nomArmy's state directory (job records, leases, and the notifier). */
+export function stateRoot(env = process.env) {
+  return env.NOMARMY_AGENT_STATE || path.join(env.HOME || os.homedir(), ".local", "share", "nomarmy-local-agents");
+}
+/** Where the notifier app and its spool folder live. */
+export function notifierPaths(root = stateRoot()) {
+  const dir = path.join(root, "notifier");
+  const app = path.join(dir, "nomArmy.app");
+  return { dir, app, binary: path.join(app, "Contents", "MacOS", "nomArmy"), spool: path.join(dir, "spool") };
+}
+
+export function notifierInfoPlist() {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>CFBundleIdentifier</key><string>${NOTIFIER_BUNDLE_ID}</string>
+  <key>CFBundleName</key><string>nomArmy</string>
+  <key>CFBundleDisplayName</key><string>nomArmy</string>
+  <key>CFBundleExecutable</key><string>nomArmy</string>
+  <key>CFBundleIconFile</key><string>nomArmy</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleShortVersionString</key><string>1.0</string>
+  <key>CFBundleVersion</key><string>1</string>
+  <key>LSUIElement</key><true/>
+</dict></plist>
+`;
+}
+
+/**
+ * Build (or keep) the notifier app. Never throws: a missing toolchain or a
+ * failed step leaves notifications on osascript, which still works.
+ * @returns {{ status: "built"|"current"|"skipped"|"failed", app?: string, reason?: string }}
+ */
+export function buildNotifierApp({ nomarmyRoot, root = stateRoot(), platform = process.platform, env = process.env, run = (cmd, args) => execFileSync(cmd, args, { stdio: ["ignore", "pipe", "pipe"] }) } = {}) {
+  if (platform !== "darwin") return { status: "skipped", reason: "not macOS" };
+  if (env.NOMARMY_NOTIFY === "0") return { status: "skipped", reason: "notifications are off (NOMARMY_NOTIFY=0)" };
+  const source = path.join(nomarmyRoot, "notifier", "main.swift"), icon = path.join(nomarmyRoot, "notifier", "nomarmy-icon.png");
+  const p = notifierPaths(root);
+  let digest;
+  try { digest = crypto.createHash("sha256").update(fs.readFileSync(source)).update(fs.readFileSync(icon)).update(notifierInfoPlist()).digest("hex"); }
+  catch (error) { return { status: "failed", reason: `notifier source missing: ${error.message}` }; }
+  const stamp = path.join(p.app, "Contents", "Resources", "nomarmy-build.sha256");
+  try { if (fs.existsSync(p.binary) && fs.readFileSync(stamp, "utf8").trim() === digest) return { status: "current", app: p.app }; } catch { /* rebuild */ }
+  // Built beside its final place: a rename from the system temp folder
+  // crosses volumes on macOS (EXDEV).
+  fs.mkdirSync(p.dir, { recursive: true });
+  const work = fs.mkdtempSync(path.join(p.dir, "build-"));
+  try {
+    const next = path.join(work, "nomArmy.app"), contents = path.join(next, "Contents");
+    fs.mkdirSync(path.join(contents, "MacOS"), { recursive: true });
+    fs.mkdirSync(path.join(contents, "Resources"), { recursive: true });
+    fs.writeFileSync(path.join(contents, "Info.plist"), notifierInfoPlist());
+    run("swiftc", ["-O", "-o", path.join(contents, "MacOS", "nomArmy"), source]);
+    const iconset = path.join(work, "nomArmy.iconset");
+    fs.mkdirSync(iconset);
+    for (const s of [16, 32, 128, 256, 512]) {
+      run("sips", ["-z", String(s), String(s), icon, "--out", path.join(iconset, `icon_${s}x${s}.png`)]);
+      run("sips", ["-z", String(s * 2), String(s * 2), icon, "--out", path.join(iconset, `icon_${s}x${s}@2x.png`)]);
+    }
+    run("iconutil", ["-c", "icns", iconset, "-o", path.join(contents, "Resources", "nomArmy.icns")]);
+    run("codesign", ["--force", "-s", "-", next]);
+    fs.writeFileSync(path.join(contents, "Resources", "nomarmy-build.sha256"), `${digest}\n`);
+    // Swap in place: same path and bundle id, so the permission the person
+    // gave carries over.
+    fs.mkdirSync(p.spool, { recursive: true });
+    fs.rmSync(p.app, { recursive: true, force: true });
+    fs.renameSync(next, p.app);
+    try { run(LSREGISTER, ["-f", p.app]); } catch { /* registers on first launch anyway */ }
+    return { status: "built", app: p.app };
+  } catch (error) {
+    return { status: "failed", reason: String(error.stderr ?? error.message).split("\n")[0].slice(0, 200) };
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}

package/lib/notify.mjs

@@ -0,0 +1,66 @@
+// Desktop notifications from nomArmy itself, so the person watching hears
+// about a finished job, a failure or a run limit no matter which
+// coordinator (Claude Code, Codex, Cursor) is running the General.
+//
+// macOS: nomArmy.app (lib/notifier-app.mjs), which shows nomArmy's own icon,
+// or osascript's `display notification` when the app isn't built (that one
+// shows Script Editor's icon). Linux: notify-send. Anything else, or
+// NOMARMY_NOTIFY=0: nothing. Fire-and-forget: a notification must never
+// delay or fail the job that triggered it.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { notifierPaths, stateRoot } from "./notifier-app.mjs";
+
+/** An AppleScript string literal: backslashes and double quotes escaped, newlines flattened. */
+export function appleScriptString(text) {
+  return `"${String(text ?? "").replace(/[\r\n]+/g, " ").replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** The command that would show this notification here, or null. */
+export function notificationCommand(title, message, { platform = process.platform, env = process.env, app = null } = {}) {
+  if (env.NOMARMY_NOTIFY === "0") return null;
+  const t = String(title).slice(0, 120), m = String(message).slice(0, 400);
+  if (platform === "darwin" && app) return ["open", ["-g", app.app, "--args", app.spool]];
+  if (platform === "darwin") return ["osascript", ["-e", `display notification ${appleScriptString(m)} with title ${appleScriptString(t)}`]];
+  if (platform === "linux") return ["notify-send", ["--app-name=nomArmy", t, m]];
+  return null;
+}
+
+/** The built notifier app, or null. */
+export function notifierApp(root = stateRoot()) {
+  const p = notifierPaths(root);
+  return fs.existsSync(p.binary) ? p : null;
+}
+
+/**
+ * Queue one notification for nomArmy.app: title and message on two lines,
+ * written under a temp name and renamed, so the app never reads half a file.
+ */
+export function spoolNotification(spool, title, message) {
+  fs.mkdirSync(spool, { recursive: true });
+  // A notifier that can't run (denied, broken) mustn't let the folder grow.
+  try { if (fs.readdirSync(spool).length > 50) return false; } catch { /* fresh */ }
+  const flat = (s, n) => String(s ?? "").replace(/[\r\n]+/g, " ").slice(0, n);
+  const name = `${Date.now()}-${process.pid}-${crypto.randomBytes(3).toString("hex")}`;
+  const tmp = path.join(spool, `${name}.part`);
+  fs.writeFileSync(tmp, `${flat(title, 120)}\n${flat(message, 400)}\n`);
+  fs.renameSync(tmp, path.join(spool, `${name}.txt`));
+  return true;
+}
+
+export function notify(title, message, { platform = process.platform, env = process.env, run = spawn, root = stateRoot(env) } = {}) {
+  if (env.NOMARMY_NOTIFY === "0") return false;
+  let app = platform === "darwin" ? notifierApp(root) : null;
+  try { if (app && !spoolNotification(app.spool, title, message)) return false; } catch { app = null; }
+  const cmd = notificationCommand(title, message, { platform, env, app });
+  if (!cmd) return false;
+  try {
+    const child = run(cmd[0], cmd[1], { stdio: "ignore", detached: true });
+    child.on?.("error", () => {});
+    child.unref?.();
+    return true;
+  } catch { return false; }
+}

package/lib/openclaw-config.mjs

@@ -0,0 +1,65 @@
+// A provider plugin's own config step, which `paste-api-key` never runs.
+//
+// OpenClaw runs a model only when ~/.openclaw/openclaw.json has an entry
+// for its provider under models.providers (base URL, API shape, models).
+// A plugin writes that entry in its onboarding step -- the Meta plugin's
+// applyMetaConfig -- which `openclaw onboard` calls. nomArmy links a
+// subscription key with `openclaw models auth paste-api-key`, which saves
+// the key and nothing else. So the catalog listed every Muse model (it asks
+// Meta directly) while every job on one failed "Unknown model" (a real
+// Senti run). This runs that same plugin function, only when the entry is
+// missing, with a backup of the file first.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** OpenClaw's home directory (its config, extensions and state). */
+export function openclawHome(env = process.env) {
+  return env.OPENCLAW_STATE_DIR || path.join(env.HOME || os.homedir(), ".openclaw");
+}
+
+/** OpenClaw's config file (OPENCLAW_CONFIG_PATH, as OpenClaw itself honors). */
+export function openclawConfigPath(home = openclawHome(), env = process.env) {
+  return env.OPENCLAW_CONFIG_PATH || path.join(home, "openclaw.json");
+}
+
+/** Whether OpenClaw's config has an entry for this provider. */
+export function providerConfigured(config, provider) {
+  return Boolean(config?.models?.providers && Object.prototype.hasOwnProperty.call(config.models.providers, provider));
+}
+
+/** The parsed openclaw.json, or null when it's missing or unreadable. */
+export function readOpenclawConfig(home = openclawHome()) {
+  try { return JSON.parse(fs.readFileSync(openclawConfigPath(home), "utf8")); } catch { return null; }
+}
+
+/**
+ * Apply a plugin's provider config if its entry is missing.
+ * @param {{ provider: string, pluginId: string, module: string, exportName: string, home?: string }} spec
+ *   module is relative to the plugin's directory under extensions/.
+ * @returns {Promise<{ changed: boolean, backup?: string, error?: string }>}
+ */
+export async function ensureProviderConfig({ provider, pluginId, module, exportName, home = openclawHome() }) {
+  const file = openclawConfigPath(home);
+  let config;
+  try { config = JSON.parse(fs.readFileSync(file, "utf8")); } catch (error) { return { changed: false, error: `couldn't read ${file}: ${error.message}` }; }
+  if (providerConfigured(config, provider)) return { changed: false };
+  let apply;
+  try { apply = (await import(pathToFileURL(path.join(home, "extensions", pluginId, module)).href))[exportName]; }
+  catch (error) { return { changed: false, error: `couldn't load the ${pluginId} plugin's config step: ${error.message}` }; }
+  if (typeof apply !== "function") return { changed: false, error: `the ${pluginId} plugin has no ${exportName}; it may have changed shape` };
+  let next;
+  try { next = apply(structuredClone(config)); } catch (error) { return { changed: false, error: `the ${pluginId} plugin's config step failed: ${error.message}` }; }
+  if (!providerConfigured(next, provider)) return { changed: false, error: `the ${pluginId} plugin's config step didn't add a ${provider} provider entry` };
+  // It may only add: every top-level section the file had must still be there.
+  const dropped = Object.keys(config).filter((k) => !(k in next));
+  if (dropped.length) return { changed: false, error: `refused: the ${pluginId} plugin's config step would remove ${dropped.join(", ")}` };
+  const backup = `${file}.before-nomarmy-${provider}`;
+  fs.copyFileSync(file, backup);
+  const tmp = `${file}.nomarmy-tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: fs.statSync(file).mode & 0o777 });
+  fs.renameSync(tmp, file);
+  return { changed: true, backup };
+}

package/lib/openclaw-errors.mjs

@@ -0,0 +1,40 @@
+// What a failed `openclaw agent exec` actually said, from its stderr run log.
+//
+// A model the provider refuses fails as "openclaw exited 1" with the reason
+// buried in a colored log line. Two real cases, both listed in OpenClaw's
+// catalog while every job on them failed (a Senti run):
+//
+//   ... decision=surface_error reason=model_not_found ... from=openai/gpt-6-sol
+//   rawError={... "message":"The 'gpt-6-sol' model is not supported when
+//   using Codex with a ChatGPT account."}
+//
+//   Unknown model: meta/muse-spark-1.3
+//
+// modelRejection() turns either into { model, message } so the job can say
+// model_not_found with the vendor's own sentence, and health can count it.
+
+const ANSI = /\u001b\[[0-9;]*m/g;
+
+/**
+ * The provider refusing the model itself, or null for any other failure.
+ * @param {string} text stderr (and/or stdout) of the failed call
+ * @param {string} [attemptedModel] the provider/model the job asked for
+ */
+export function modelRejection(text, attemptedModel = null) {
+  const s = String(text ?? "").replace(ANSI, "");
+  const unknown = /Unknown model:?\s+([\w.-]+\/[\w.:-]+)/.exec(s);
+  const notSupported = /The '([^'\\"]+)' model is not supported[^"\\\n]*/.exec(s);
+  const flagged = /reason=model_not_found\b/.test(s);
+  if (!unknown && !notSupported && !flagged) return null;
+  const from = /reason=model_not_found\b[^\n]*?\bfrom=([\w.-]+\/[\w.:-]+)/.exec(s)?.[1];
+  const model = (unknown?.[1] ?? from ?? attemptedModel ?? notSupported?.[1] ?? "").replace(/[.:]+$/, "") || null;
+  const message = notSupported ? notSupported[0].replace(/\.?$/, ".")
+    : unknown ? `Unknown model: ${model}.`
+    : "the provider refused this model.";
+  return { model, message };
+}
+
+/** The one-line job error for a refused model. */
+export function modelRejectionLine({ model, message }) {
+  return `model_not_found: ${model ?? "this model"}: ${message} It may still be listed in OpenClaw's catalog; reassign the role (nomarmy army assign <role> <agent> <model>).`;
+}