nomarmy 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -13,22 +13,24 @@
 ## TL;DR
 
 1. **Have** Git, Node 20+ and [Podman](https://podman.io) (on macOS: `brew install podman && podman machine init && podman machine start`).
-2. **Install** (builds the local model server, OpenClaw and the sandbox, and registers nomArmy with Claude Code):
+2. **Install** (OpenClaw and the sandbox, and registers nomArmy with Claude Code):
    ```bash
    git clone https://github.com/rayson-tech/nomarmy.git && cd nomarmy
-   ./install.sh --profile macbook-pro   # or nvidia-linux, cpu-linux, dgx-spark, bedrock
-   ./e2e.sh --profile macbook-pro       # should end with: === E2E PASS ===
+   npm install && npm link
+   nomarmy setup --hosted
+   ./install.sh --profile hosted
    ```
-   No local model? See [hosted workers only](#hosted-workers-only) or [a shared model server](#a-shared-model-server).
-3. **Set up your repo:** in the project, run `nomarmy init`. It proposes a `.nomarmy.yml` with your test command.
-4. **Use it:** restart Claude Code in that project and ask it to use nomArmy for one small bug that has a test. When that works, try `/feature <what you want built>`.
-5. **Optional:** add hosted workers with `nomarmy agents add`, give roles to them with `nomarmy army init`, or connect Codex or Cursor with `nomarmy connect codex cursor`.
+3. **Add your workers:** `nomarmy agents add` (an API key, or your ChatGPT or Muse Code subscription), then `nomarmy army init --agent <name>` to put every role on it. `nomarmy doctor` checks the lot.
+4. **Set up your repo:** in the project, run `nomarmy init`. It proposes a `.nomarmy.yml` with your test command.
+5. **Use it:** restart Claude Code in that project and ask it to use nomArmy for one small bug that has a test. When that works, try `/feature <what you want built>`.
+
+**Have a GPU or a Mac with plenty of memory?** Workers can also run free on a local model: `./install.sh --profile macbook-pro` (or `nvidia-linux`, `cpu-linux`, `dgx-spark`) builds llama.cpp and starts it; see [Install](#install). A team GPU server works too: [a shared model server](#a-shared-model-server). Codex or Cursor as the coordinator: `nomarmy connect codex cursor`.
 
 Stuck? `nomarmy doctor` checks the machine, and `nomarmy health` checks everything nomArmy runs on.
 
 ## What it is
 
-Your coding assistant (Claude Code, Codex or Cursor) stays in charge as the **General**: it decides what gets built and whether the result is acceptable. The work goes to **noms**, workers that implement, test and repair in their own git worktree and sandbox, on a local model, an API key, or your own ChatGPT or Muse Code subscription. nomArmy owns everything in between: worktrees, git, sandboxes, verification, and the evidence that decides whether work is accepted.
+Your coding assistant (Claude Code, Codex or Cursor) stays in charge as the **General**: it decides what gets built and whether the result is acceptable. The work goes to **noms**, workers that implement, test and repair in their own git worktree and sandbox, on an API key, your own ChatGPT or Muse Code subscription, or a local model. nomArmy owns everything in between: worktrees, git, sandboxes, verification, and the evidence that decides whether work is accepted.
 
 **What you get is work you don't have to take on faith**, not cheaper work. Delegating costs the General tokens too: briefing and reviewing. On small, already-diagnosed tickets we measured 4 to 8 times more of the General's tokens than fixing the bug directly, and break-even at roughly 150 lines of context a fix needs to read ([the measurements](docs/experiments/2026-09-20-model-bakeoff-and-economics.md)). It pays off on bigger tickets, on parallel work, and anywhere you'd otherwise have to trust an agent's say-so.
 
@@ -48,22 +50,38 @@ Around that core: **agents** say where a job can run, the **army** says which ro
 
 ## Install
 
-| Platform | Guide |
+| Setup | Guide |
 |---|---|
-| macOS (Apple Silicon) | [macOS](#macos-apple-silicon) |
-| Linux, with or without an NVIDIA GPU | [Linux](#linux) |
+| API keys and subscriptions, no local model (most people) | [Hosted workers only](#hosted-workers-only) |
+| A local model on macOS (Apple Silicon) | [macOS](#macos-apple-silicon) |
+| A local model on Linux, with or without an NVIDIA GPU | [Linux](#linux) |
 | Windows | [Windows](#windows) |
 | NVIDIA DGX Spark | [DGX Spark](#dgx-spark) |
-| No local model: API keys and subscriptions only | [Hosted workers only](#hosted-workers-only) |
 | A shared GPU server (or a tunnel to one) | [A shared model server](#a-shared-model-server) |
 | No GPU, with Bedrock | [Cloud (Bedrock)](#cloud-bedrock) |
 
 Every platform needs Git and Podman. `nomarmy doctor` checks the host and prints a fix for anything missing.
 
-`install.sh` builds llama.cpp for local inference, installs and configures [OpenClaw](https://github.com/openclaw/openclaw) (the host-side broker every model call goes through), builds the sandbox image, and registers the MCP server if Claude Code is installed. `nomarmy connect` (run by `install.sh`, or by hand for Codex and Cursor) also installs the `/feature` command, Claude Code's status line and, on macOS, nomArmy's notifier. The coordinator gets nomArmy's instructions from the MCP server itself, so there's nothing to copy into your projects.
+`install.sh` builds llama.cpp when you run a local model, installs and configures [OpenClaw](https://github.com/openclaw/openclaw) (the host-side broker every model call goes through), builds the sandbox image, and registers the MCP server if Claude Code is installed. `nomarmy connect` (run by `install.sh`, or by hand for Codex and Cursor) also installs the `/feature` command, Claude Code's status line and, on macOS, nomArmy's notifier. The coordinator gets nomArmy's instructions from the MCP server itself, so there's nothing to copy into your projects.
 
 **From npm:** `npm install -g nomarmy@alpha` gives you the `nomarmy` command; `nomarmy setup` then picks a profile and model and prints the `install.sh` command to run (`nomarmy setup --hosted` or `--llama-url <server>` without a local model). Installing from a clone, as in the TL;DR, is the most tested path.
 
+### Hosted workers only
+
+No GPU and no local model: every job runs on an API key or a subscription (ChatGPT, Muse Code) you add as an agent. Git worktrees, the sandbox and verification still run on your machine, so you still need Git, Node and Podman.
+
+```bash
+git clone https://github.com/rayson-tech/nomarmy.git && cd nomarmy
+npm install && npm link              # or: npm install -g nomarmy@alpha
+nomarmy setup --hosted               # records that this install has no local model
+./install.sh --profile hosted        # OpenClaw, the sandbox, and the Claude Code registration; no llama.cpp
+nomarmy agents add                   # an API key or a subscription login
+nomarmy army init --agent <name>     # every role on that agent (add --model <model> to pick one)
+nomarmy doctor
+```
+
+A hosted install refuses a job that names no role or agent, rather than falling back to a local model that isn't there. `nomarmy health` warns about any role still on `local`. `e2e.sh` tests the local model, so it has nothing to do here; `nomarmy army assign` tests each role's route instead.
+
 ### macOS (Apple Silicon)
 
 ```bash
@@ -122,22 +140,6 @@ chmod +x install.sh e2e.sh scripts/*.sh
 
 Moving from a Mac install? Don't copy a Mac binary or model cache over: clone fresh and let `install.sh` build llama.cpp for CUDA on that machine.
 
-### Hosted workers only
-
-No GPU and no local model: every job runs on an API key or a subscription (ChatGPT, Muse Code) you add as an agent. Git worktrees, the sandbox and verification still run on your machine, so you still need Git, Node and Podman.
-
-```bash
-git clone https://github.com/rayson-tech/nomarmy.git && cd nomarmy
-npm install && npm link              # or: npm install -g nomarmy@alpha
-nomarmy setup --hosted               # records that this install has no local model
-./install.sh --profile hosted        # OpenClaw, the sandbox, and the Claude Code registration; no llama.cpp
-nomarmy agents add                   # an API key or a subscription login
-nomarmy army init --agent <name>     # every role on that agent (add --model <model> to pick one)
-nomarmy doctor
-```
-
-A hosted install refuses a job that names no role or agent, rather than falling back to a local model that isn't there. `nomarmy health` warns about any role still on `local`. `e2e.sh` tests the local model, so it has nothing to do here; `nomarmy army assign` tests each role's route instead.
-
 ### A shared model server
 
 A team GPU box (a DGX, a workstation) runs one llama-server; everyone else points nomArmy at it. That works through an SSH tunnel too (`ssh -L 8080:localhost:8080 gpu-box`, then `http://127.0.0.1:8080`).
@@ -208,6 +210,8 @@ Changes apply to the next job with no restart. The exception is a **new** api ag
 
 **Your plan decides which models run.** A model can be listed and still refused: on a ChatGPT plan, the Codex route runs gpt-6-astra and the gpt-5.6 models but refuses gpt-6-sol and gpt-6-luna. `army assign` and `agents update --probe` test the exact route a job takes, so they catch this before a job does.
 
+**Usage limits.** nomArmy reads how much of a subscription's limit is used where the vendor reports it: Codex in every job's session log, Claude in what Claude Code passes to the status line (Pro and Max plans). It shows in `army`, `local_worker_capacity` and the status line (`⚠ openai 85% wk`), and `nomarmy health` warns from 80%. At the limit, a job on that agent is held rather than left to fail: the General asks you, and resubmits with `confirm_over_limit: true` if you say go. Muse, Grok and API keys don't report their limits; a job that hits one in a `/feature` run pauses that agent for the run.
+
 **Vendor terms and platform risk.** Every model call goes through [OpenClaw](https://github.com/openclaw/openclaw), and subscriptions are reached through each vendor's own CLI or login. We've read the terms that apply (see above), but using a personal subscription through a harness is exactly the kind of use vendors tighten, and a change in a vendor's terms or in OpenClaw can stop a subscription agent from working. Local models and API keys don't carry that risk. Plan on subscriptions as a convenience, not the only way your roles can run.
 
 **Picking an agent.** Build work goes to a sandboxed agent: `local`, an api key, Codex or Muse. `local` for a bounded change against a written spec with a test; your code never leaves your machine. An api or subscription agent when the work needs more than the local model, knowing it sends code to that vendor. That's a decision about where your source travels, separate from the trust boundary, which is the same for every agent. The General itself when the answer isn't known yet.

package/lib/admission.mjs

@@ -8,6 +8,7 @@ import { readJson } from "./openclaw-run.mjs";
 import { readOpenClawTranscriptTail } from "./transcript.mjs";
 import { readClaudeSessionTranscript } from "./claude-transcript.mjs";
 import { notify } from "./notify.mjs";
+import { readCodexRateLimits, recordUsageSnapshot, readUsageSnapshots, usageStatus } from "./usage-limits.mjs";
 import { recentModelRefusal } from "./health.mjs";
 import { writeLease, removeLease, liveLeases, liveSlots, acquireSlot } from "./slots.mjs";
 import { loadRun, runTotals, runAdmissionProblems, recordRunJob, detectUsageLimit } from "./runs.mjs";
@@ -140,6 +141,11 @@ export function createJobRuntime(deps) {
    * watching hears about it from any coordinator without polling.
    */
   function notifyJobFinished(entry, result, error) {
+    try {
+      const provider = entry.agent ? agentProviderId(agentsConfig().agents[entry.agent]) : null;
+      const snapshot = provider ? readCodexRateLimits(path.join(jobsRoot, entry.jobId)) : null;
+      if (snapshot) recordUsageSnapshot(stateRoot, provider, snapshot);
+    } catch { /* Usage telemetry must never affect the job result. */ }
     if (!entry.lane) return; // only tracked jobs, never internal helpers
     const m = result?.manifest ?? {};
     const outcome = error ? "failed" : String(m.outcome ?? (result?.ok ? "done" : "finished")).toLowerCase().replace(/_/g, " ");
@@ -161,6 +167,7 @@ export function createJobRuntime(deps) {
       admission,
       memory: deps.budgetState.hardwareSnapshot?.memory ?? null,
       running: [...activeJobs.values()].filter(j => !j.settled).map(j => ({ jobId: j.jobId, workerId: j.workerId, mode: j.mode, lane: j.lane, startedAt: j.startedAt, phase: readJson(path.join(jobsRoot, j.jobId, "status.json"))?.phase ?? "starting" })),
+      usageLimits: Object.fromEntries(Object.entries(readUsageSnapshots(stateRoot)).map(([provider, snapshot]) => [provider, usageStatus(snapshot)])),
       maxWorkers: currentMaxWorkers(),
       remote: { running: runningCount("remote"), maxWorkers: currentMaxPoolWorkers(), note: "api and subscription agents; each agent's own max_concurrent also applies" }
     };
@@ -169,6 +176,16 @@ export function createJobRuntime(deps) {
     await deps.budgetState.refresh();
     if (jobs.some((j) => jobLane(j) === "remote")) await modelCatalogReady();
     const problems = [];
+    const snapshots = readUsageSnapshots(stateRoot);
+    jobs.forEach((j, i) => {
+      if (!j.agentName || j.confirm_over_limit === true) return;
+      let provider;
+      try { provider = agentProviderId(agentsConfig().agents[j.agentName]); } catch { return; }
+      const snapshot = snapshots[provider];
+      if (!snapshot) return;
+      const status = usageStatus(snapshot);
+      if (status.level === "over") problems.push(`${jobs.length > 1 ? `job ${i + 1}: ` : ""}agent "${j.agentName}" is held at its usage limit: ${status.text} (reading ${status.ageMinutes} minutes old). Ask the operator before resubmitting with confirm_over_limit: true, or send the job to another agent.`);
+    });
     // A pool-routed job is checked against that pool's OWN (model-dependent)
     // budget, not the local-derived global one -- see budgetsForPool. Which
     // specific entry pickProvider will land on isn't known yet at admission

package/lib/army.mjs

@@ -30,6 +30,7 @@ import path from "node:path";
 import YAML from "yaml";
 import { z } from "zod";
 import { agentRunsToolsOnHost } from "./dispatch-schema.mjs";
+import { usageStatus } from "./usage-limits.mjs";
 
 export const GLOBAL_CONFIG_FILENAME = "config.yml";
 export const PROJECT_CONFIG_FILENAMES = Object.freeze([".nomarmy.yml", ".nomarmy.yaml"]);
@@ -361,11 +362,20 @@ export function generalOverlap(army, agents = {}) {
  * description, phase, suggested mode, agent, any problem or overlap with
  * the General, and which layer set each field.
  */
-export function describeArmy(loaded, { agents = {}, describeAgent = null } = {}) {
+export function describeArmy(loaded, { agents = {}, describeAgent = null, usageSnapshots = null, agentProviderId = null, now = Date.now() } = {}) {
   const army = loaded.army;
   const problems = armyTargetProblems(army, agents);
   const overlap = generalOverlap(army, agents);
   const runsOn = (name) => (name && agents[name] && describeAgent ? describeAgent(agents[name]) : null);
+  const usage = (name) => {
+    if (!name || !agents[name] || !usageSnapshots || !agentProviderId) return null;
+    let provider;
+    try { provider = agentProviderId(agents[name]); } catch { return null; }
+    const snapshot = usageSnapshots[provider];
+    if (!snapshot) return null;
+    const { level, text } = usageStatus(snapshot, now);
+    return { level, text };
+  };
   // A subscription whose owner isn't the General's own is worth a word,
   // not a refusal: it may be the same person's other account (a real Senti
   // General skipped a role's agent for exactly this, unsure whose it was).
@@ -378,7 +388,7 @@ export function describeArmy(loaded, { agents = {}, describeAgent = null } = {})
   const roles = Object.fromEntries(Object.entries(army.roles).map(([name, role]) => [name, {
     description: role.description ?? null, phase: role.phase ?? null, mode: role.mode ?? null,
     agent: role.agent ?? null, model: role.model ?? agents[role.agent]?.model ?? null, modelIsAuto: role.model === "auto",
-    agentRunsOn: runsOn(role.agent),
+    agentRunsOn: runsOn(role.agent), usage: usage(role.agent),
     // Its agent's own tools run on this machine (dispatch-schema.mjs): an
     // implement role there is refused per job unless the agent allows it.
     hostTools: agentRunsToolsOnHost(agents[role.agent]) ? { allowed: agents[role.agent].allow_host_tools === true, implementRole: (role.mode ?? "implement") === "implement" } : null,
@@ -388,7 +398,7 @@ export function describeArmy(loaded, { agents = {}, describeAgent = null } = {})
     ? "not defined -- run `nomarmy army general <agent>` so nomArmy can flag roles that share the General's model or usage"
     : !Object.prototype.hasOwnProperty.call(agents, army.general) ? `agent "${army.general}" is not defined in your agents.yml` : null;
   return {
-    general: { ...GENERAL, agent: army.general, agentRunsOn: runsOn(army.general), problem: generalProblem, setBy: loaded.sources.general },
+    general: { ...GENERAL, agent: army.general, agentRunsOn: runsOn(army.general), usage: usage(army.general), problem: generalProblem, setBy: loaded.sources.general },
     workflow: army.workflow,
     runLimits: army.runLimits ?? {},
     roles,

package/lib/coordinator-instructions.mjs

@@ -11,6 +11,7 @@ export const COORDINATOR_INSTRUCTIONS = `nomArmy runs bounded engineering jobs (
 Before dispatching:
 - Answer where-is / who-calls / grep questions with repo_evidence (deterministic, [path:line] on every hit). Use mode: scout only for read-only research that would otherwise pull many files into your own context.
 - Call army to see this repo's roles and which agent each runs on; dispatch by army_role when a role fits. A job on a subscription agent needs on_behalf_of set to that agent's owner.
+- Agents' usage limits show in army and local_worker_capacity; a job on an agent at its limit is held. Ask the operator before resubmitting with confirm_over_limit: true, or move the job to another agent. Never set it on your own.
 - A Claude subscription agent (claude-cli) runs its tools on this machine, outside the sandbox: use it for scout and review work. nomArmy refuses implement jobs on it unless the operator set allow_host_tools; send build work to a sandboxed agent.
 - Brief outcomes, not edits: a task, explicit acceptance criteria, and the tests that prove it. Put facts you've already resolved in evidence.
 - Prefer local_worker_start + local_worker_status for anything longer than a few minutes. For a whole feature, use /feature (run_start keeps a run's jobs, spend and hours bounded).

package/lib/health.mjs

@@ -22,6 +22,7 @@ import path from "node:path";
 import { executionMode } from "./execution.mjs";
 import { modelRejection } from "./openclaw-errors.mjs";
 import { providerConfigured, readOpenclawConfig } from "./openclaw-config.mjs";
+import { readUsageSnapshots, usageStatus } from "./usage-limits.mjs";
 
 const DAY = 86400000;
 
@@ -183,12 +184,23 @@ 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 } = {}) {
   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 }));
+  if (usageSnapshots) {
+    for (const [provider, snapshot] of Object.entries(usageSnapshots)) {
+      const status = usageStatus(snapshot, now);
+      if (status.level === "ok") continue;
+      const short = `${provider} ${status.short}`;
+      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: `${status.text} (reading ${status.ageMinutes} minutes old).`,
+        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 });
+    }
+  }
   const [auth, version, latest, plugins] = await Promise.all([
     run(openclawCmd, ["models", "auth", "list", "--json"]),
     run(openclawCmd, ["--version"]),
@@ -278,7 +290,7 @@ export async function checkAndRecordHealth({ projectDir, stateRoot, configDir, n
   if (ageMs !== null) { try { autoPruned = { ...pruneJobRuntime({ stateRoot, olderThanMs: ageMs, now }), olderThanHours: ageMs / 3600000 }; } catch { /* best-effort */ } }
   const mode = executionMode(env).mode;
   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) });
   const toNotify = recordHealth(path.join(stateRoot, "health.json"), result, { now });
   return { result, toNotify };
 }

package/lib/statusline.mjs

@@ -27,6 +27,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { mergeUsageSnapshot, normalizeClaudeRateLimits, readUsageSnapshots, recordUsageSnapshot, usageStatus } from "./usage-limits.mjs";
 
 function readJson(file) { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } }
 function pidAlive(pid) {
@@ -47,6 +48,17 @@ const minutes = (ms) => (ms < 60000 ? `${Math.max(1, Math.round(ms / 1000))}s` :
  */
 export function statusLineText({ session = {}, stateRoot, now = Date.now(), maxLength = Number(process.env.NOMARMY_STATUSLINE_MAX) || 90 } = {}) {
   const root = stateRoot ?? (process.env.NOMARMY_AGENT_STATE || path.join(os.homedir(), ".local", "share", "nomarmy-local-agents"));
+  // Every Claude Code window redraws this line with its own last-seen
+  // limits, idle ones included, so a reading is merged rather than trusted
+  // (mergeUsageSnapshot), and written only when it moves the figure.
+  try {
+    const snapshot = normalizeClaudeRateLimits(session.rate_limits);
+    if (snapshot) {
+      const previous = readUsageSnapshots(root)["claude-cli"];
+      const merged = mergeUsageSnapshot(previous, { ...snapshot, observedAt: now }, now);
+      if (merged !== previous) recordUsageSnapshot(root, "claude-cli", merged);
+    }
+  } catch { /* usage capture must never break the status line */ }
   // workspace.project_dir is where Claude Code was launched -- the repo that
   // session's nomArmy server works in; current_dir can be a subdirectory.
   const cwd = session.workspace?.project_dir ?? session.workspace?.current_dir ?? session.cwd ?? process.cwd();
@@ -99,23 +111,37 @@ export function statusLineText({ session = {}, stateRoot, now = Date.now(), maxL
   try {
     const health = readJson(path.join(root, "health.json"));
     if (health && now - Date.parse(health.checkedAt) < 2 * 86400000) {
-      const top = (health.issues ?? []).find((i) => i.severity !== "info" && i.short);
+      // Usage warnings get their own part below, so they aren't repeated here.
+      const top = (health.issues ?? []).find((i) => i.severity !== "info" && i.short && !String(i.id).startsWith("usage:"));
       if (top) healthPart = ` │ ⚠ ${top.short}`;
     }
   } catch { /* no health yet */ }
   runPart += healthPart;
-  // As many jobs as fit, then "+N": the run summary is never what gets cut.
+  let usageParts = [];
+  try {
+    const warnings = Object.entries(readUsageSnapshots(root)).map(([provider, snapshot]) => {
+      const status = usageStatus(snapshot, now);
+      if (status.level === "ok") return null;
+      return { level: status.level, text: ` │ ${status.level === "over" ? "⛔" : "⚠"} ${provider} ${status.short}` };
+    }).filter(Boolean).sort((a, b) => (a.level === "over" ? 0 : 1) - (b.level === "over" ? 0 : 1));
+    usageParts = warnings.map((warning) => warning.text);
+  } catch { /* usage display is best-effort */ }
+  // As many jobs as fit, then "+N". Only after every job is collapsed may
+  // lower-priority usage warnings be omitted to honor the hard cap.
   const prefix = `${head ? `${head} │ ` : ""}🍪 `;
   const count = jobs.length > 1 ? `${jobs.length}: ` : "";
-  let shown = jobs.length, army;
+  let shown = jobs.length, army, suffix;
   for (;;) {
     const rest = jobs.length - shown;
     army = (!jobs.length ? "idle" : `${count}${jobs.slice(0, shown).join(" · ")}${rest ? `${shown ? " " : ""}+${rest}` : ""}`)
       + (elsewhere ? ` · ${elsewhere} in other repo${elsewhere === 1 ? "" : "s"}` : "");
-    if (shown === 0 || [...`${prefix}${army}${runPart}`].length <= maxLength) break;
-    shown--;
+    suffix = runPart + usageParts.join("");
+    if ([...`${prefix}${army}${suffix}`].length <= maxLength) break;
+    if (shown > 0) { shown--; continue; }
+    if (usageParts.length) { usageParts.pop(); continue; }
+    break;
   }
-  return `${prefix}${army}${runPart}`;
+  return `${prefix}${army}${suffix}`;
 }
 
 const isMain = (() => { try { return path.resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url); } catch { return false; } })();

package/lib/usage-limits.mjs

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+// How much of each subscription's usage limit is used, as its vendor reports
+// it: Codex writes rate_limits into every job's session log, and Claude Code
+// passes them to the status line. Kept per OpenClaw provider id (one host
+// login per provider) in <stateRoot>/usage-limits.json. Admission holds a job
+// on an agent that's over its limit until the General confirms.
+
+const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+const finite = value => typeof value === "number" && Number.isFinite(value);
+const windowName = minutes => ({ 300: "5h", 10080: "week", 1440: "day" })[minutes] ?? `${minutes}m`;
+function window(value, name, minutes, percentKey) {
+  if (!object(value) || !finite(value[percentKey]) || value[percentKey] < 0) return null;
+  return { name, usedPercent: value[percentKey], windowMinutes: minutes,
+    resetsAt: finite(value.resets_at) ? value.resets_at * 1000 : null };
+}
+
+/** Read the last rate-limit event from the newest rollout (by modification time). */
+export function readCodexRateLimits(jobDir) {
+  try {
+    const files = [];
+    function walk(dir) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const file = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(file);
+        else if (entry.isFile() && /^rollout-.*\.jsonl$/.test(entry.name)) files.push({ file, mtime: fs.statSync(file).mtimeMs });
+      }
+    }
+    const agents = path.join(jobDir, "runtime/state/agents");
+    for (const agent of fs.readdirSync(agents, { withFileTypes: true })) {
+      if (!agent.isDirectory()) continue;
+      const sessions = path.join(agents, agent.name, "agent/codex-home/sessions");
+      if (fs.existsSync(sessions)) walk(sessions);
+    }
+    files.sort((a, b) => b.mtime - a.mtime || b.file.localeCompare(a.file));
+    if (!files.length) return null;
+    let last = null;
+    for (const line of fs.readFileSync(files[0].file, "utf8").split(/\r?\n/)) {
+      try {
+        const event = JSON.parse(line);
+        if (event.type === "event_msg" && event.payload?.type === "token_count" && object(event.payload.rate_limits)) last = event;
+      } catch { /* A partial trailing write is not an event. */ }
+    }
+    if (!last) return null;
+    const limits = last.payload.rate_limits;
+    const windows = [limits.primary, limits.secondary].map(value => {
+      const minutes = finite(value?.window_minutes) ? value.window_minutes : null;
+      return window(value, minutes === null ? "unknown" : windowName(minutes), minutes, "used_percent");
+    }).filter(Boolean);
+    const limitReached = limits.rate_limit_reached_type != null || Boolean(limits.spend_control_reached);
+    if (!windows.length && !limitReached) return null;
+    const timestamp = Date.parse(last.timestamp);
+    return { source: "codex", plan: typeof limits.plan_type === "string" ? limits.plan_type : null,
+      limitReached, observedAt: Number.isFinite(timestamp) ? timestamp : files[0].mtime, windows };
+  } catch { return null; }
+}
+
+export function normalizeClaudeRateLimits(rateLimits) {
+  if (!object(rateLimits)) return null;
+  const windows = [["five_hour", "5h", 300], ["seven_day", "week", 10080], ["spend_limit", "spend", null]]
+    .map(([key, name, minutes]) => window(rateLimits[key], name, minutes, "used_percentage")).filter(Boolean);
+  // Claude supplies percentages, not an independent provider-wide reached flag.
+  return windows.length ? { source: "claude", plan: null, limitReached: false, observedAt: Date.now(), windows } : null;
+}
+
+/**
+ * Combine a stored snapshot with a new reading that may be stale. Every
+ * Claude Code window passes the status line the limits from its own last
+ * response, so an idle window keeps reporting an old, lower figure. Usage
+ * only rises within a window, so per window: a later reset wins, and at the
+ * same reset the higher figure wins. A stored window the reading lacks is
+ * kept while it's live. Returns the stored snapshot itself when nothing
+ * changed, so callers can skip the write.
+ */
+export function mergeUsageSnapshot(previous, incoming, now = Date.now()) {
+  if (!previous) return incoming;
+  const key = (w) => [w.resetsAt ?? 0, w.usedPercent];
+  const newer = (a, b) => { const [ra, pa] = key(a), [rb, pb] = key(b); return ra > rb || (ra === rb && pa > pb); };
+  const byName = new Map(previous.windows.filter((w) => w.resetsAt === null || w.resetsAt > now).map((w) => [w.name, w]));
+  let changed = byName.size !== previous.windows.length;
+  for (const w of incoming.windows) {
+    const stored = byName.get(w.name);
+    if (!stored || newer(w, stored)) { byName.set(w.name, w); changed = true; }
+  }
+  const limitReached = incoming.limitReached || previous.limitReached;
+  if (!changed && limitReached === previous.limitReached) return previous;
+  return { ...incoming, limitReached, observedAt: now, windows: [...byName.values()] };
+}
+
+export function readUsageSnapshots(stateRoot) {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(stateRoot, "usage-limits.json"), "utf8"));
+    if (!object(data)) return {};
+    return Object.fromEntries(Object.entries(data).filter(([, s]) => object(s) && ["codex", "claude"].includes(s.source)
+      && finite(s.observedAt) && typeof s.limitReached === "boolean" && (s.plan === null || typeof s.plan === "string")
+      && Array.isArray(s.windows) && s.windows.every(w => object(w) && typeof w.name === "string" && finite(w.usedPercent)
+        && (w.windowMinutes === null || finite(w.windowMinutes)) && (w.resetsAt === null || finite(w.resetsAt)))));
+  } catch { return {}; }
+}
+
+/** Save a provider's snapshot, unless the one on file is newer (jobs finish out of order). */
+export function recordUsageSnapshot(stateRoot, provider, snapshot) {
+  const current = readUsageSnapshots(stateRoot);
+  if (current[provider]?.observedAt > snapshot.observedAt) return;
+  const snapshots = { ...current, [provider]: snapshot };
+  fs.mkdirSync(stateRoot, { recursive: true });
+  const file = path.join(stateRoot, "usage-limits.json"), tmp = `${file}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(snapshots, null, 2));
+    fs.renameSync(tmp, file);
+  } finally { fs.rmSync(tmp, { force: true }); }
+}
+
+export function usageStatus(snapshot, now = Date.now()) {
+  const live = snapshot.windows.filter(w => w.resetsAt === null || w.resetsAt > now).sort((a, b) => b.usedPercent - a.usedPercent);
+  const reached = snapshot.limitReached && (snapshot.windows.length === 0 || live.length > 0);
+  const highest = live[0];
+  const level = reached || highest?.usedPercent >= 100 ? "over" : highest?.usedPercent >= 80 ? "high" : "ok";
+  const text = live.length ? live.map(w => `${w.usedPercent}% of ${w.name}, resets ${w.resetsAt === null ? "unknown" : new Date(w.resetsAt).toLocaleString("en-US", { weekday: "short", hour: "2-digit", minute: "2-digit", hour12: false })}`).join("; ") : reached ? "limit reached, reset unknown" : "no live usage windows";
+  // A short label for tight spaces (status line, health): "85% wk".
+  const short = highest ? `${highest.usedPercent}% ${highest.name === "week" ? "wk" : highest.name}` : reached ? "limit" : null;
+  return { level, text, short, resetsAt: level === "over" ? highest?.resetsAt ?? null : null,
+    ageMinutes: Math.max(0, Math.floor((now - snapshot.observedAt) / 60000)) };
+}

package/mcp/server.mjs

@@ -32,6 +32,7 @@ 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 } from "../lib/usage-limits.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";
 
@@ -282,6 +283,7 @@ export const jobSchema = z.object({
   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."),
   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.`
@@ -474,14 +476,17 @@ server.tool("run_finish", "Close a /feature run as complete or stopped, with a o
 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 usageSnapshots = readUsageSnapshots(stateRoot);
+    const summary = describeArmy(currentArmy(), { agents, describeAgent, usageSnapshots, agentProviderId });
     // 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();
     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 snapshot = usageSnapshots[provider];
+      const usage = snapshot ? (() => { const { level, text } = usageStatus(snapshot); return { level, text }; })() : null;
+      return [name, { runsOn: describeAgent(agent), defaultModel: agent.model ?? null, models, 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

package/package.json

@@ -3,7 +3,7 @@
   "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.",
   "author": "Rayson Technologies",
   "license": "Apache-2.0",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "private": false,
   "type": "module",
   "engines": {