nomarmy 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -13,21 +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
    ```
-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.
 
@@ -47,19 +50,37 @@ 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 GPU, or no local inference | [Cloud (Bedrock)](#cloud-bedrock) |
+| 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
+```
 
-**From npm:** `npm install -g nomarmy@alpha` gives you the `nomarmy` command; `nomarmy setup` then picks a profile and model and prints the `install.sh` command to run. Installing from a clone, as in the TL;DR, is the most tested path.
+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)
 
@@ -103,7 +124,7 @@ CPU-only Linux works but is slow for interactive use: see [Sizing](#sizing).
 
 1. **WSL2** (the supported path): install a Linux distro under WSL2, install Podman inside it, and follow the [Linux](#linux) guide entirely inside the distro. Watch WSL2's default cap of about half your RAM (`.wslconfig`), and set `git config --global core.longpaths true` (`nomarmy doctor` checks this).
 2. **Native llama.cpp on Windows**, built from source: more RAM, more setup. Prebuilt binaries aren't a safe shortcut; some CPUs crash every backend at startup.
-3. **No local inference**: `./install.sh --profile bedrock` (see [Cloud (Bedrock)](#cloud-bedrock)), or hosted agents only.
+3. **No local inference**: [hosted workers only](#hosted-workers-only), or [Bedrock](#cloud-bedrock).
 
 `nomarmy sizing` reports what your hardware can support.
 
@@ -119,6 +140,18 @@ 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.
 
+### 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`).
+
+```bash
+nomarmy setup --llama-url http://gpu-box:8080   # checks /health, records the address
+./install.sh --profile remote                   # no llama.cpp build; OpenClaw points at that server
+./e2e.sh --profile remote
+```
+
+nomArmy doesn't start, stop or size that server: whoever runs it sets its model, context and slots, and `install.sh` reads the model name and context from the server. Your machine still runs the sandbox and verification for your jobs. Several people sharing one server share its slots, so keep `NOMARMY_MAX_WORKERS` low (the profile sets 1). Run the server itself with any local profile's `install.sh` on the GPU machine, with `NOMARMY_LLAMA_HOST=0.0.0.0` so others can reach it, on a network you trust: llama-server has no authentication.
+
 ### Cloud (Bedrock)
 
 No GPU, no local build:
@@ -177,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.
@@ -470,7 +505,7 @@ What we've learned from real runs, including where delegating pays and where it
 - **Deploy-time failures need your own check.** See [Add a check for what unit tests can't see](#nomarmyyml).
 - **Node dependencies install only from npm lockfiles**, one per package (no workspaces, yarn, pnpm or bun yet), and only from the public registry: the image build has no credentials for a private one.
 - **Verification needing services** (a database, a mock server) reports `not_run` instead of running without them. The compose parser doesn't resolve YAML anchors.
-- **Same-host only**: the MCP server and OpenClaw run on the machine with the coordinator. There's no remote-worker mode yet.
+- **Same-host sandboxes**: the MCP server, OpenClaw and every job's sandbox run on the machine with the coordinator. Only the model can be elsewhere (an agent, or [a shared model server](#a-shared-model-server)).
 
 ## Troubleshooting
 

package/bin/nomarmy.mjs

@@ -18,10 +18,11 @@ import { buildConfigProposal } from "../lib/propose.mjs";
 import { detectHardware } from "../lib/hardware.mjs";
 import { readGGUFMetadata, resolveModelPath, totalSplitBytes } from "../lib/gguf.mjs";
 import { recommend, customRecommendation, evaluateConfig, bytesPerKvElementForCacheTypes, MIN_CONTEXT_PER_NOM } from "../lib/sizing.mjs";
-import { connectClaude, connectCodex, connectCursor, cursorAlreadyConnected } from "../lib/connect.mjs";
+import { connectClaude, connectCodex, connectCursor, cursorAlreadyConnected, deriveWorkerModelEnv } from "../lib/connect.mjs";
 import { ID_RE, AUTH_ENV_NAME_RE, OPENCLAW_PROVIDER_ID_RE, openclawProviderId, isNativeProviderType } from "../lib/dispatch-schema.mjs";
-import { loadAgents, readAgentsFile, writeAgentsFile, agentsConfigPath, apiAgentAsPoolEntry, describeAgent as describeAgentLabel, AGENT_KINDS, API_PROVIDER_TYPES, RESERVED_AGENT_NAMES, BUILTIN_LOCAL_AGENT } from "../lib/agents.mjs";
+import { loadAgents, readAgentsFile, writeAgentsFile, agentsConfigPath, apiAgentAsPoolEntry, describeAgent as describeAgentLabel, agentRunsToolsOnHost, AGENT_KINDS, API_PROVIDER_TYPES, RESERVED_AGENT_NAMES, BUILTIN_LOCAL_AGENT } from "../lib/agents.mjs";
 import { loadArmy, describeArmy, readArmyFile, updateArmyInFile, assignRoleInFile, parseTargetSpec, armyLayerPath, globalConfigDir, DEFAULT_ARMY, ARMY_PHASES, LOCAL_CONFIG_FILENAME } from "../lib/army.mjs";
+import { parseLlamaUrl } from "../lib/execution.mjs";
 import { ensureProviderConfig } from "../lib/openclaw-config.mjs";
 import { recordProbeSuccess } from "../lib/health.mjs";
 import { pruneJobRuntime } from "../lib/prune.mjs";
@@ -93,6 +94,8 @@ Usage: nomarmy <command> [options]
                   write config/profiles/<name>.env (+ config/common.env).
                   Prints the install.sh command; never runs it.
                   --tier <more|nominal>   with --json, skip the prompt
+                  --hosted               skip hardware/model questions
+                  --llama-url <url>       use a llama-server on another machine
   model           Change the configured model later, without the rest of
                   setup's questions. Offers to also resync the MCP
                   registration's worker-routing env vars, and to restart
@@ -168,7 +171,9 @@ Usage: nomarmy <command> [options]
                             UI/UX, data architect, security analyst, PM,
                             PO, stakeholder, all on \`local\`) to --global
                             (default), --project or --local; --force
-                            replaces an existing one
+                            replaces an existing one; --agent <name>
+                            starts every role there, optionally with
+                            --model <model|auto>
                   assign <role> <agent|none> [model|auto]
                             give a role an agent, and optionally the model
                             to run on it ("auto" lets the General pick per
@@ -516,6 +521,55 @@ async function chooseModel(rl) {
  * command itself does.
  */
 async function cmdSetup() {
+  const hosted = flag("hosted");
+  const hasLlamaUrl = flag("llama-url");
+  if (hosted && hasLlamaUrl) throw new Error("--hosted and --llama-url cannot be used together.");
+
+  if (hosted || hasLlamaUrl) {
+    const commonPath = path.join(nomarmyRoot, "config", "common.env");
+
+    if (hosted) {
+      const next = [
+        `${path.join(nomarmyRoot, "install.sh")} --profile hosted`,
+        "nomarmy agents add",
+        "nomarmy army init --agent <name>",
+      ];
+      fs.mkdirSync(path.dirname(commonPath), { recursive: true });
+      writeEnvLine(commonPath, "NOMARMY_EXECUTION", "hosted");
+      if (json) return out({ written: commonPath, execution: "hosted", next });
+      console.log(c.green(`✓ Wrote NOMARMY_EXECUTION=hosted to ${path.relative(nomarmyRoot, commonPath)}.`));
+      console.log(c.dim("\nNext:"));
+      for (const step of next) console.log(`  ${c.bold(step)}`);
+      return;
+    }
+
+    const llamaInput = value("llama-url");
+    if (!llamaInput) throw new Error("--llama-url requires an http:// URL, for example http://server:8080.");
+    const { host: llamaHost, port: llamaPort } = parseLlamaUrl(llamaInput);
+    const urlHost = llamaHost.includes(":") ? `[${llamaHost}]` : llamaHost;
+    const healthUrl = `http://${urlHost}:${llamaPort}/health`;
+    let reachable = false;
+    try {
+      await fetch(healthUrl, { signal: AbortSignal.timeout(5000) });
+      reachable = true;
+    } catch {
+      // A server may simply be offline during setup; retain its validated address.
+    }
+    fs.mkdirSync(path.dirname(commonPath), { recursive: true });
+    writeEnvLine(commonPath, "NOMARMY_EXECUTION", "remote");
+    writeEnvLine(commonPath, "NOMARMY_LLAMA_HOST", llamaHost);
+    writeEnvLine(commonPath, "NOMARMY_LLAMA_PORT", llamaPort);
+    const next = `${path.join(nomarmyRoot, "install.sh")} --profile remote`;
+    if (json) return out({ written: commonPath, execution: "remote", llamaHost, llamaPort, reachable, next });
+    console.log(reachable
+      ? c.green(`✓ llama-server is reachable at ${healthUrl}.`)
+      : c.yellow(`⚠ llama-server is not reachable at ${healthUrl} right now; configuration was still written.`));
+    console.log(c.green(`✓ Wrote the remote llama-server settings to ${path.relative(nomarmyRoot, commonPath)}.`));
+    console.log(c.dim("\nNext:"));
+    console.log(`  ${c.bold(next)}`);
+    return;
+  }
+
   const execution = value("execution", process.env.NOMARMY_EXECUTION || "local");
   const isCloud = execution !== "local";
   const hardware = isCloud ? null : await detectHardware();
@@ -1962,16 +2016,45 @@ async function cmdArmyShow() {
 async function cmdArmyInit() {
   const layer = armyLayerFlag("global");
   const filePath = armyLayerPath(layer, { projectDir: repoDir });
+  const agentName = value("agent");
+  let selectedAgent = null;
+  let roleModel = null;
+  if (flag("agent") && !agentName) throw new Error("--agent requires a name from agents.yml.");
+  if (agentName) {
+    const agents = loadAgentsOrExit().agents;
+    if (!Object.prototype.hasOwnProperty.call(agents, agentName)) {
+      throw new Error(`Unknown agent "${agentName}". Pick one of: ${Object.keys(agents).join(", ")}`);
+    }
+    selectedAgent = agents[agentName];
+    if (flag("model") && !value("model")) throw new Error("--model requires a model name or auto.");
+    roleModel = value("model") ?? (selectedAgent.model ? null : "auto");
+  }
   const existing = readArmyFile(filePath, { armyOnly: layer !== "project" });
   if (existing?.roles && Object.keys(existing.roles).length && !flag("force")) {
     throw new Error(`${filePath} already defines an army (${Object.keys(existing.roles).join(", ")}). Re-run with --force to replace it.`);
   }
   // Keep a General already defined in this layer; the roster is what init resets.
-  updateArmyInFile(filePath, (army) => ({ ...structuredClone(DEFAULT_ARMY), ...(army.general ? { general: army.general } : {}) }));
+  const roster = structuredClone(DEFAULT_ARMY);
+  if (agentName) {
+    for (const role of Object.values(roster.roles)) {
+      role.agent = agentName;
+      if (roleModel) role.model = roleModel;
+    }
+  }
+  updateArmyInFile(filePath, (army) => ({ ...roster, ...(army.general ? { general: army.general } : {}) }));
   if (layer === "local") ensureLocalLayerIgnored();
   if (json) return out({ written: filePath, layer, roles: Object.keys(DEFAULT_ARMY.roles) });
   console.log(c.green(`✓ Wrote the default army to ${filePath} (${layer}).`));
-  console.log(c.dim("Every role starts on the local model. Next: `nomarmy army general <agent>` (the agent your coordinator session runs on), then `nomarmy army assign <role> <agent>` for any role you want elsewhere."));
+  if (!agentName) {
+    console.log(c.dim("Every role starts on the local model. Next: `nomarmy army general <agent>` (the agent your coordinator session runs on), then `nomarmy army assign <role> <agent>` for any role you want elsewhere."));
+    return;
+  }
+  console.log(c.dim(roleModel === "auto"
+    ? `Every role starts on ${agentName} with model auto; the coordinator picks a model per job.`
+    : `Every role starts on ${agentName}${roleModel ? ` with model ${roleModel}` : ` using its default model ${selectedAgent.model}`}.`));
+  if (agentRunsToolsOnHost(selectedAgent)) {
+    console.log(c.yellow(`⚠ ${agentName} runs its tools on the host. Build roles on it will be refused unless allow_host_tools is set in agents.yml.`));
+  }
 }
 
 async function cmdArmyAssign() {
@@ -2206,10 +2289,18 @@ async function cmdJobs() {
 
 // `nomarmy health`: run the checks now (the MCP server also runs them every
 // 6 hours) and record them, which also refreshes the status line's warning.
+// This install's settings from config/common.env (the execution mode and the
+// model server's address, as `nomarmy connect` gives the MCP server), under
+// anything set (non-empty) in the environment.
+function installEnv() {
+  const set = Object.fromEntries(Object.entries(process.env).filter(([, v]) => v !== ""));
+  return { ...deriveWorkerModelEnv(nomarmyRoot), ...set };
+}
+
 async function cmdHealth() {
   const { checkAndRecordHealth } = await import("../lib/health.mjs");
   const stateRoot = process.env.NOMARMY_AGENT_STATE || path.join(os.homedir(), ".local", "share", "nomarmy-local-agents");
-  const { result } = await checkAndRecordHealth({ projectDir: repoDir, stateRoot, configDir: globalConfigDir() });
+  const { result } = await checkAndRecordHealth({ projectDir: repoDir, stateRoot, configDir: globalConfigDir(), env: installEnv() });
   if (json) return out(result);
   console.log(c.bold("🍪 nomArmy health") + c.dim(`  ${new Date(result.checkedAt).toLocaleString()}`));
   if (!result.issues.length) { console.log(c.green("\n✓ Nothing to fix.")); return; }
@@ -2234,7 +2325,7 @@ const commands = { scan: cmdScan, validate: cmdValidate, sizing: cmdSizing, init
 async function cmdDoctor() {
   // Import lazily to avoid circular dependencies
   const { runDoctor } = await import("../lib/doctor.mjs");
-  await runDoctor({ json, exit: true });
+  await runDoctor({ json, exit: true, env: installEnv() });
 }
 commands.doctor = cmdDoctor;
 if (!command || flag("help") || !commands[command]) usage(command && !commands[command] ? 2 : 0);

package/config/common.env

@@ -16,8 +16,10 @@ NOMARMY_MAX_WORKERS=1
 NOMARMY_AGENT_IMAGE=openclaw-nomarmy-coder:bookworm
 NOMARMY_INSTALL_ROOT=$HOME/.local/share/nomarmy-local-agents
 
-# Execution layer: 'local' runs llama-server on this machine, 'bedrock' calls a
-# hosted OpenAI-compatible endpoint. Profiles override this.
+# Where models run: 'local' runs llama-server on this machine, 'remote' uses
+# one nomArmy doesn't run (nomarmy setup --llama-url), 'hosted' has no local
+# model at all (nomarmy setup --hosted), 'bedrock' calls Bedrock. Profiles
+# override this.
 NOMARMY_EXECUTION=local
 
 # Worker model routing. The MCP server composes "<provider>/<model>" for

package/config/profiles/hosted.env

@@ -0,0 +1,6 @@
+# Hosted workers only: no local model on this machine. Every job runs on an
+# api or subscription agent (nomarmy agents add); the sandbox, git worktrees
+# and verification still run here. `nomarmy setup --hosted` writes this
+# mode into config/common.env as well, so the MCP server knows it.
+NOMARMY_PROFILE=hosted
+NOMARMY_EXECUTION=hosted

package/config/profiles/remote.env

@@ -0,0 +1,9 @@
+# A llama-server nomArmy doesn't run, e.g. a team's GPU server or an SSH
+# tunnel to one. Set its address with `nomarmy setup --llama-url
+# http://host:8080`, which writes NOMARMY_LLAMA_HOST / NOMARMY_LLAMA_PORT
+# into config/common.env. nomArmy
+# doesn't start, stop or size that server; the sandbox, git worktrees and
+# verification still run on this machine.
+NOMARMY_PROFILE=remote
+NOMARMY_EXECUTION=remote
+NOMARMY_MAX_WORKERS=1

package/e2e.sh

@@ -24,6 +24,12 @@ load_profile "$PROFILE"
 
 echo "=== nomArmy E2E: $NOMARMY_PROFILE ==="
 
+if [[ "$(nomarmy_execution_mode)" == hosted ]]; then
+  echo "e2e.sh runs a job on the local model, and profile '$NOMARMY_PROFILE' has none."
+  echo "Check each agent with: nomarmy doctor"
+  exit 0
+fi
+
 "$ROOT/scripts/start-inference.sh" "$NOMARMY_PROFILE"
 
 if nomarmy_is_cloud; then

package/install.sh

@@ -15,7 +15,7 @@ case "$OS_NAME" in
     command -v curl >/dev/null 2>&1 || brew install curl
     command -v git >/dev/null 2>&1 || brew install git
     command -v node >/dev/null 2>&1 || brew install node
-    if ! nomarmy_is_cloud; then
+    if nomarmy_manages_model_server; then
       command -v xcode-select >/dev/null 2>&1 && xcode-select -p >/dev/null 2>&1 || { echo 'ERROR: Xcode Command Line Tools are required. Run: xcode-select --install'; exit 1; }
       command -v cmake >/dev/null 2>&1 || brew install cmake
     fi
@@ -24,8 +24,8 @@ case "$OS_NAME" in
     command -v podman >/dev/null 2>&1 || brew install podman
     ;;
   Linux)
-    if nomarmy_is_cloud; then
-      # No local model is built or served, so the C++ toolchain is not needed.
+    if ! nomarmy_manages_model_server; then
+      # No model is built or served here, so the C++ toolchain is not needed.
       need curl; need git; need node; need npm
     else
       if ! command -v cmake >/dev/null 2>&1 || ! command -v c++ >/dev/null 2>&1 || ! command -v curl >/dev/null 2>&1 || ! command -v git >/dev/null 2>&1 || ! command -v node >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1; then install_build_dependencies; fi
@@ -105,7 +105,7 @@ if ! command -v openclaw >/dev/null 2>&1; then
   export PATH="$HOME/.local/bin:$HOME/.npm-global/bin:$PATH"
 fi
 need openclaw
-if ! nomarmy_is_cloud; then openclaw plugins install @openclaw/llama-cpp-provider || true; fi
+if nomarmy_has_local_model; then openclaw plugins install @openclaw/llama-cpp-provider || true; fi
 "$ROOT/scripts/start-inference.sh" "$NOMARMY_PROFILE"
 # Sandbox before provider config: configure-openclaw.sh refuses to store a real
 # Bedrock credential unless the coder sandbox is already network-isolated.
@@ -122,4 +122,8 @@ if nomarmy_is_cloud && [[ "${NOMARMY_ORCHESTRATOR_RUNTIME:-}" == "claude-code" ]
   echo "    ./scripts/configure-orchestrator.sh $NOMARMY_PROFILE          # print the settings"
   echo "    ./scripts/configure-orchestrator.sh $NOMARMY_PROFILE --apply  # write them to Claude Code"
 fi
-echo "==> Install complete. Run: ./e2e.sh --profile $NOMARMY_PROFILE"
+if [[ "$(nomarmy_execution_mode)" == hosted ]]; then
+  echo "==> Install complete. Add an agent (nomarmy agents add), give roles to it (nomarmy army init --agent <name>), then run: nomarmy doctor"
+else
+  echo "==> Install complete. Run: ./e2e.sh --profile $NOMARMY_PROFILE"
+fi

package/lib/admission.mjs

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { executionMode } from "./execution.mjs";
 import { clampInt } from "./budget-state.mjs";
 import { checkBrief, assessAdmission, describeBudgets } from "./budget.mjs";
 import { parseStatusPorcelainZ, isRuntimeJunk } from "./git-record.mjs";
@@ -7,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";
@@ -139,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, " ");
@@ -147,8 +154,11 @@ export function createJobRuntime(deps) {
     const ok = !error && (result?.ok || m.coordinatorStatus === "complete");
     notify(`nomArmy: ${entry.role ?? entry.mode ?? "job"} ${ok ? "done" : outcome}`, `${entry.workerId ?? entry.jobId} on ${who}: ${outcome} after ${took}m. ${ok ? "Ready for the General's review." : "Needs a look."}`);
   }
+  function admissionHardware() {
+    return executionMode(deps.env).managesModelServer ? deps.budgetState.hardwareSnapshot : null;
+  }
   function capacitySnapshot() {
-    const admission = assessAdmission({ hardware: deps.budgetState.hardwareSnapshot, runningJobs: runningCount("local"), slots: deps.budgetState.contextInfo.slots, maxWorkers: currentMaxWorkers() });
+    const admission = assessAdmission({ hardware: admissionHardware(), runningJobs: runningCount("local"), slots: deps.budgetState.contextInfo.slots, maxWorkers: currentMaxWorkers() });
     return {
       // The local model's budget. An api or subscription job's scales with
       // its own model; local_worker_start reports that job's.
@@ -157,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" }
     };
@@ -165,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
@@ -241,14 +262,16 @@ export function createJobRuntime(deps) {
       } catch (error) { problems.push(jobs.length > 1 ? `job ${i + 1}: ${error.message}` : error.message); }
     });
     // Slot capacity only concerns local jobs: a remote job's inference runs
-    // at its vendor and never competes for llama-server's slots. Free memory
-    // still applies to every job (each one runs a local sandbox), so a
-    // remote-only batch is checked for memory alone. Remote jobs have their
-    // own, additive ceiling (currentMaxPoolWorkers).
+    // at its vendor and never competes for llama-server's slots. When this
+    // install runs llama-server itself, free memory applies to every job
+    // (the model and each job's sandbox share it), so a remote-only batch is
+    // checked for memory alone. A remote or hosted install has no model
+    // here to size memory against. Remote jobs have their own, additive
+    // ceiling (currentMaxPoolWorkers).
     const anyLocal = jobs.some((j) => jobLane(j) === "local");
     const admission = anyLocal
-      ? assessAdmission({ hardware: deps.budgetState.hardwareSnapshot, runningJobs: runningCount("local"), slots: deps.budgetState.contextInfo.slots, maxWorkers: currentMaxWorkers() })
-      : assessAdmission({ hardware: deps.budgetState.hardwareSnapshot, runningJobs: 0, slots: null, maxWorkers: Infinity });
+      ? assessAdmission({ hardware: admissionHardware(), runningJobs: runningCount("local"), slots: deps.budgetState.contextInfo.slots, maxWorkers: currentMaxWorkers() })
+      : assessAdmission({ hardware: admissionHardware(), runningJobs: 0, slots: null, maxWorkers: Infinity });
     if (!admission.admit) problems.push(...admission.reasons.map(r => `not admitted (${admission.level}): ${r}`));
     if (jobs.some((j) => jobLane(j) === "remote")) {
       const remoteCeiling = currentMaxPoolWorkers(), runningRemote = runningCount("remote");

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/budget-state.mjs

@@ -1,4 +1,5 @@
 import { deriveBudgets, resolveContextPerNom } from "./budget.mjs";
+import { executionMode } from "./execution.mjs";
 
 export function clampInt(value, min, max, fallback) {
   const n = Number.parseInt(value ?? "", 10);
@@ -12,8 +13,10 @@ export function createBudgetState({ env = process.env } = {}) {
   function currentBudgets() { return budgets; }
   async function refresh() {
     try {
-      contextInfo = await resolveContextPerNom({ env });
-      budgets = deriveBudgets({ contextPerNom: contextInfo.contextPerNom, source: contextInfo.source, env });
+      if (executionMode(env).hasLocalModel) {
+        contextInfo = await resolveContextPerNom({ env });
+        budgets = deriveBudgets({ contextPerNom: contextInfo.contextPerNom, source: contextInfo.source, env });
+      }
     } catch { /* keep the previous budgets; a failed probe is not a reason to refuse work */ }
     try {
       const { detectHardware } = await import("./hardware.mjs");

package/lib/budget.mjs

@@ -16,6 +16,7 @@
 // Everything here is pure except `resolveContextPerNom`, which may ask a
 // running llama-server what its slots actually are; the probe is injectable.
 import { DEFAULT_TARGET_CONTEXT_PER_NOM, MIN_CONTEXT_PER_NOM, RESERVES, GIB, formatBytes, isCloudExecution } from "./sizing.mjs";
+import { executionMode } from "./execution.mjs";
 
 /**
  * Hard ceilings the MCP tool schema enforces regardless of hardware. The
@@ -309,7 +310,9 @@ async function defaultProbe(env) {
 export async function resolveContextPerNom({ env = process.env, probe = defaultProbe } = {}) {
   const direct = envInt(env, "NOMARMY_CONTEXT_PER_NOM");
   if (direct) return { contextPerNom: direct, slots: envInt(env, "NOMARMY_LLAMA_PARALLEL"), source: "profile (NOMARMY_CONTEXT_PER_NOM)" };
-  const total = envInt(env, "NOMARMY_LLAMA_CONTEXT"), parallel = envInt(env, "NOMARMY_LLAMA_PARALLEL");
+  // A remote server's context is its own, not this machine's settings.
+  const remote = executionMode(env).mode === "remote";
+  const total = remote ? null : envInt(env, "NOMARMY_LLAMA_CONTEXT"), parallel = remote ? null : envInt(env, "NOMARMY_LLAMA_PARALLEL");
   if (total && parallel) return { contextPerNom: Math.floor(total / parallel), slots: parallel, source: "profile (NOMARMY_LLAMA_CONTEXT / NOMARMY_LLAMA_PARALLEL)" };
   if (!isCloudExecution(env.NOMARMY_EXECUTION || "local")) {
     const probed = await probe(env);

package/lib/connect.mjs

@@ -240,6 +240,10 @@ export function deriveWorkerModelEnv(nomarmyRoot) {
   const env = {};
   if (model) env.NOMARMY_WORKER_MODEL = model;
   if (thinking !== null) env.NOMARMY_WORKER_MODEL_THINKING = thinking;
+  for (const key of ["NOMARMY_EXECUTION", "NOMARMY_LLAMA_HOST", "NOMARMY_LLAMA_PORT"]) {
+    const value = readEnvValue(commonPath, key);
+    if (value !== null) env[key] = value;
+  }
   return env;
 }
 

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).