model-orchestrator 0.1.34 → 1.0.0

package/docs/part-2-intermediate.md

@@ -1,79 +1,61 @@
-# Part 2 · Intermediate: many AIs, called through their CLIs
+# Part 2: delegate across your AI CLIs
 
-Everything in Part 1, plus lanes. One agent stays the orchestrator; every other AI becomes a lane it calls from the terminal.
+Keep one main agent coordinating the work. Each other AI is a **lane**: a CLI or model the main agent can call with a scoped task brief.
 
-## Plans and automatic effort
-
-The installer can record plans with `--plans codex=pro-20x,agy=ultra-5x`. Plan headroom changes volume allocation only, never capability or the independent-review rule. `--effort-auto` is explicit consent to write `auto` for eligible high or max headroom CLI lanes. Auto resolves to medium or high from prompt size, and a codex audit is always high. It is a heuristic, not a measurement: name xhigh explicitly for security-critical or irreversible work.
-
-## 1. Two kinds of lane
-
-**Lane A, subscription CLIs.** Claude Code, Codex, Antigravity, Grok, Hermes. Already paid for, $0 per call, used for interactive and agentic work. **Lane B, metered APIs.** Per token, used for programmatic bulk where a subscription CLI cannot serve. **Local.** A privacy lane, never a cost lane.
-
-Rule: never spend a frontier token on a task a cheap tier finishes correctly. Escalate on signal, not by default. And an external lane must earn the hop with a real strength; when in doubt, stay in-house.
-
-## 2. One job per lane
+## Subscription lanes, pay-per-token lanes and local models
 
-| Lane | Wins at |
-|---|---|
-| the orchestrator (Claude Code, or whichever you chose) | routes, maps, builds, verifies, records; drives the others as CLIs |
-| Codex | second coder and second-opinion reviewer: a different model family reading your diff |
-| Antigravity `agy` | deep research sweeps; concurrent fan-out (its subagent call takes an array) |
-| Grok CLI | X and live web reads at $0 (the same search on the API bills per call) |
-| Hermes | the free tier: rough drafts, first-pass summaries, divergent reads, cron jobs |
-| Qwen Code + a cheap metered model | structured bulk output; never anything that cites a line, number or source |
-| Ollama | anything that must not leave the machine |
+- **Subscription lanes:** use the tools and quota included in your vendor plan. Check that plan's current limits before assigning volume.
+- **Pay-per-token lanes:** use metered APIs for programmatic work, with an explicit budget and model choice.
+- **Local models:** keep private input on your machine when the task requires that boundary.
 
-One driver, no second AI in the mix: the orchestrator invokes the CLIs; it never hands control to another agent.
+The generated **Your stack: who does what** table assigns roles using capability facts, billing and selection order. The delegation matrix states each assignment and its reason. An independent reviewer needs a known different model family from the main agent; an unknown family cannot establish independence. Check current model names, permissions and tool reach before assigning a section. [Assignment rules](how-it-routes.md#your-stack-who-does-what).
 
-## 3. Exit 0 is a lie on every lane
+## Lane runner (`aunx cli-run`)
 
-Every agent CLI can report success and deliver nothing. `bin/cli-run.mjs` builds the right invocation per lane, reads that lane's **native** terminal event, and exits `10` when a run produced no deliverable, `12` on timeout, `13` when the lane is missing, and `14` to `18` when the lane's own error says why (auth, quota, rejected, refused, cut short), so a missing API key is never blamed on the model. Byte count is not a check either; a run can emit hundreds of kilobytes and no conclusion. One lane's own success flags lie outright (an upstream 400 reported as success), so its judge reads the two honest signals instead.
+Replace `<lane>` with a supported CLI named in your installed stack table.
 
-Every call goes through it. "This lane is flaky" becomes a query over its log instead of an argument. `node bin/cli-run.mjs --doctor` is the first thing to run after install: enabled lanes, binaries on PATH, the route each lane is pinned to, and with `--run` a one-word canary per lane.
+```bash
+aunx cli-run --doctor
+# Direct form from the installed rules folder:
+node bin/cli-run.mjs --doctor
+aunx cli-run '<lane>' --brief TASK_BRIEF.md --effort high
+# Direct form: node bin/cli-run.mjs '<lane>' --brief TASK_BRIEF.md --effort high
+```
 
-There is a second thing a lane can be quietly wrong about. Left unpinned, it runs on **its own config file**, which the runner cannot see: a CLI set up months ago at a low reasoning effort keeps auditing at that effort while your routing docs describe a second-opinion pass, and no error is ever raised. `--model` and `--effort` pin it per call, `defaults` in `bin/lanes.json` pins it per lane, and every run records the value requested and where it came from (`flag`, `lanes.json`, `lane_default`). The log claims no actual: grok reports a model id in its output, the other four lanes report none, so the field would be populated for one lane and empty for four, and it would be a provider-supplied string the durable log never holds.
+`cli-run` reads each vendor's terminal result and returns nonzero when the response is missing, interrupted, timed out or rejected by an output contract. It distinguishes authentication, quota and unavailable-tool failures so the next action can address the cause. Use `--expect-file` or `--expect-json` when your task needs a specific output shape.
 
-## 4. Every delegation carries a task bundle, on both surfaces
+`--model` and `--effort` set a request for one call. `defaults` in `bin/lanes.json` supplies per-tool defaults. The local log records requested values and their source; the vendor's own output is the place to confirm actual model execution.
 
-Subagents and CLI lanes are close to the same problem: something that may hold none of your rules, and broad tool access. A Claude Code subagent is the one documented exception, loading the project's CLAUDE.md hierarchy at start, so it keeps the standing rules but not this task's scope; a CLI lane and a fresh chat window get no such credit. The brief (purpose, task class, scope, capabilities, denied actions, conventions, report contract, exit parameters) goes in the prompt or in the file passed to `--brief` either way. If you can, gate it mechanically: a pre-dispatch hook that refuses a brief missing purpose, denied actions or a report contract. On claude-code, a `SubagentStart` hook can inject the essentials (where the rules and the brief format live) automatically; `.claude/hooks/subagent-context.mjs` is the generated example. A third hook, `.claude/hooks/route-metrics.mjs`, turns that same delegation into a measurement instead of an assumption: it logs every turn, dispatch, subagent start/stop and the lane named in the reply's hidden route marker, and `--summary` reports route-marker coverage, dispatches with no matching start, and duration per agent type.
-
-## 5. Research: three engines, one triager
-
-Fan the same plan to three model families (web sweep, second-opinion read, live data), each as one `cli-run` call. The orchestrator opens the primary sources itself, marks every claim, and writes the only durable record. Expect one engine to return confident unsourced numerics; downgrade it. Weight the engines that report their own gaps. Count dispositions, not briefs.
-
-## 5a. A finding is a claim, not a fact
-
-An audit that returns six findings has returned six claims. Hand them to `finding-verifier` before any of them causes a repair: it reads the cited line, states what would trigger the problem, then hunts for the guard, caller or test that makes it impossible, and answers CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE. Only CONFIRMED earns a change. Use a different family from the one that produced the finding, and let INCONCLUSIVE stand: rounding it up to be safe buys unnecessary repairs, rounding it down to be tidy hides real ones.
+## Plans and automatic effort
 
-## 6. Gap analysis gets a second family
+`--plans codex=pro-20x,agy=ultra-5x` records plan headroom for volume allocation. Capability and independent review still follow the task and available tools. `--effort-auto` opts eligible high-headroom tools into the runner's prompt-size heuristic. Explicitly choose higher effort for security or irreversible work when the heuristic is insufficient. [Runner reference](../bin/README.md).
 
-The second pass is now a different model reading the same artifact, in read-only audit mode. Disagreement between families is the cheapest signal that something is soft.
+## Task brief (`aunx brief`)
 
-## 7. The build protocol, bound to lanes
+Each worker reads the shared context file and a brief naming the whole build, its own section, permissions, non-goals, interfaces to preserve and acceptance commands. On a split build, identify who merges and require conflicts to be named before the audit of the final combined result.
 
-Stage 1 Map: the orchestrator sweeps; CLI lanes critique the map at $0. Stage 2: deep tier, one named weak spot and one gap in the request. Stage 4: scanners on the added lines, refuses by default. Stage 5: security-shaped diff → the second coder in read-only audit mode; architecture-shaped → deep tier reviewing build against plan; never both. Two deep checkpoints per build; CLI lanes are uncapped.
+When a requested write is refused by the worker's sandbox, hand that exact file change to an authorized writer and continue independent work. For a background call, arrange a heartbeat; the protocol defines when unchanged output requires investigation.
 
-## 8. Privacy gate
+## Review and verify
 
-Name the lanes that never see private notes, client data or personal records. An unnamed bar is not enforced.
+Use one audit step. One reviewer checks build against scope; a companion reviewer checks scope against the user's request at the same time. Prefer different model families from the author. If an independent reviewer is unavailable, record that limitation and arrange the required review before release.
 
-## 9. Re-derive every figure a cheap lane returns
+The verification role tries to reproduce each claim and probe the named definition of done. Where your main agent has an installed agent set, `finding-verifier` and `done-verifier` supply these prompts. Repairs follow confirmed findings and each fix gets a regression that is demonstrated to fail before the fix.
 
-Measured on the cheapest metered lane: conclusions right, 0 of 11 line citations correct, fabricated arithmetic attached to true observations. That survives a skim. So a number from a lane is a lead until a tool computes it: [codecalc](https://github.com/The-40-Thieves/codecalc) on the orchestrator's side, registered for Codex, Antigravity and Qwen Code with the snippets in `CODECALC.md`.
+## Research and shared notes
 
-## 10. One writer, and a store the lanes can all read
+Give independent research questions to tools that can answer them, then inspect primary sources before accepting the claims. Compute consequential figures independently. Use one writer for the final shared record.
 
-With several lanes proposing, the store is where they meet. obsidian-tc (optional) gives every CLI the same `semantic_search`, `get_backlinks` and compare-and-swap `write_note`, with folder ACLs so a research lane can read what it needs and write nothing. The orchestrator stays the one writer.
+Optional companions can help: codecalc for execution and calculations, obsidian-tc for searchable notes, Context7 for current library docs. Without them, use the runtime, notes and official documentation already available to your agent.
 
-## 11. Docs, then prove, across lanes
+## Measure your own routing
 
-Every lane's recall of a library's API is a lead, the same as its arithmetic (see item 9 above). Context7 (optional) gives every CLI the same current, version-aware docs lookup, registered for Claude Code, Cursor, Codex and Qwen Code with the snippets in `CONTEXT7.md`. It pairs with codecalc: a lane's claim about what a library does, cited from memory or from a doc, is confirmed by a run before code ships on it.
+`aunx route-metrics --summary` reads your local Claude Code routing log. It reports where work went, route-marker coverage and subagent durations. Your own measurements are the basis for changing assignments and checking whether the rules are being followed.
 
 ## What the installer gives you at this level
 
-Everything from Part 1, plus `ROUTING.md` · `TIERS.md` · `DELEGATION_MATRIX.md` (generated from your selection) · `RESEARCH_TRIAGE.md` · `CLI-RUN.md` · `bin/cli-run.mjs` · `bin/lanes.json`.
+Everything from [Part 1](part-1-beginner.md), plus `ROUTING.md`, `TIERS.md`, `DELEGATION_MATRIX.md`, `RESEARCH_TRIAGE.md`, `CLI-RUN.md`, `bin/cli-run.mjs` and `bin/lanes.json`.
 
-## When you have outgrown it
+## Run scheduled work
 
-You want the audit to run on a Monday without you, a gateway so nothing but one process holds a key, and a machine that is always on. That is [Part 3](part-3-advanced.md).
+When the setup needs an always-on host or scheduled review, move to [Part 3](part-3-advanced.md).

package/docs/part-3-advanced.md

@@ -1,50 +1,60 @@
-# Part 3 · Advanced: everything above, plus a virtual machine
+# Part 3 · Advanced: templates for your always-on Linux machine
 
-A small always-on Linux box owns the schedule. Your laptop stays the interactive driver.
+Level 3 gives configuration and setup scripts for a Linux machine you provision. The box owns the schedule; your laptop stays the interactive driver.
 
-## 1. Only the gateway holds keys
+## 1. Keep provider keys in the gateway
 
-One OpenAI-compatible gateway (LiteLLM) fronts every metered provider. Nothing else on the box holds a credential: not the orchestrator, not a job, not a container. Rotating a key is a change in one place. The gateway binds to loopback or a private mesh, never to the public interface.
+One OpenAI-compatible gateway (LiteLLM) fronts your selected pay-per-token providers. Inject provider keys into the gateway and have jobs use its authenticated endpoint. Keep the gateway's access key in your secrets manager and supply it to authorized jobs. The supplied Compose ports bind to loopback; keep any private-network access within your authorized boundary.
 
-Subscription CLIs keep their own sign-in state and stay off the gateway; they are already $0.
+Subscription CLIs keep their own sign-in state and use the access and quota included in your plan.
 
-## 1b. A subscription is not an API key
+## 1b. Configure subscription access and API access separately
 
-The installer asks which metered API keys you hold separately from which CLIs you use. A Claude Code plan gives you `claude`; it does not give you an Anthropic API key, and the gateway only serves what a key unlocks. Gateway lanes and the variable names in `vm/ENVIRONMENT.md` are rendered from the keys, never from the CLI list.
+Choose metered API providers with `--apis` or the level 3 edit menu, separately from the CLIs you use. A Claude Code plan gives you `claude`; it does not give you an Anthropic API key. API-backed gateway lanes and their variable names in `vm/ENVIRONMENT.md` come from the selected API providers. Selecting Ollama adds the local alias separately. Level 3 always needs an explicit level choice.
 
-## 2. Bind to aliases, pin the cheapest lane
+## 2. Bind to aliases and configure job policies
 
-Each gateway lane is an alias (`bulk-cheap`, `standard`, `deep`, `long-context`, `live-fast`, `local-small`), so a vendor rename is a one-line repoint. Each job is pinned to the cheapest lane that does its work, with a token cap, and climbs the ladder (local → free → cheap → standard → deep) only on failure, low confidence, or an explicit "expensive to get wrong".
+Selected providers and the optional local runtime get gateway aliases such as `bulk-cheap`, `standard`, `deep` and `local-small`. Update an alias's configured model when changing providers or models.
+
+For jobs you add, configure an eligible lane, token limits, spending limits and any escalation policy. Define the checks that justify a retry or a stronger model and the authorization each step needs.
+
+The supplied weekly audit uses the assigned review lane, falling back to the assigned bulk lane when review is unavailable. The installed stack table explains which capabilities and billing facts chose it. Each run calls that fixed lane through `cli-run` with a timeout. Its behavior is a single report request to that selected lane; token caps and escalation require your own job configuration. A bulk-lane fallback does not establish independent review.
 
 ## 3. Dispatch on the box
 
-1. Deterministic pre-triage at zero tokens: a keyword table routes the obvious cases.
-2. Judgment dispatch for the rest, by the orchestrator, with a logged reason.
-3. Free lane first.
-4. **Unattended means no human-gated escalation.** An unresolved irreversible call is surfaced and stopped, never executed on a model's confidence.
-5. One writer. Every other engine proposes.
+Use `vm/box-CLAUDE.md` as the starting policy for your main agent:
+
+1. When the task is obvious, use the routing table or `aunx route` suggestion, then verify tools and scope.
+2. When judgment is needed, apply `ROUTING.md` and `DELEGATION_MATRIX.md` and record the choice with a reason.
+3. When a cheaper eligible lane can satisfy the acceptance checks, select it. When checks fail, diagnose and choose an authorized fallback.
+4. When an unattended action exceeds the existing authorization, preserve the result and request approval through your configured channel.
+5. When recording shared state, keep one writer and have other workers propose updates.
 
 ## 4. The weekly gap analysis becomes a job
 
-A timer enumerates live state (gateway lanes, timers, CLI versions), diffs it against the delegation matrix, and lets the free lane draft the report. It catches the dead lane and the silently renamed model. Its "watched by" line starts as `nothing`, and that line is the one that tells you what to build next.
+The timer runs a script that collects gateway alias IDs, the user timer listing and version strings for CLIs found on its `PATH`. It passes those observations, `DELEGATION_MATRIX.md` and the gap-analysis protocol to the fixed CLI lane. The lane drafts a report comparing the supplied observations with the intended configuration and names what it could not assess. Failed probes are marked `UNVERIFIED`.
+
+Successful output replaces the dated report; a failed run preserves the previous report and keeps partial output separately. Nothing watches the weekly job until you configure a notifier and record it in `vm/jobs/README.md`.
 
 ## 5. What runs where
 
 | Surface | Role |
 |---|---|
 | the orchestrator CLI | interactive driver over SSH; dispatch brain for jobs |
-| `cli-run` lanes | the other agent CLIs, headless, signed in by device code |
-| the gateway | every metered provider behind one endpoint |
+| `cli-run` lanes | supported agent CLIs, headless, using their vendor sign-ins |
+| the gateway | selected pay-per-token providers behind one endpoint |
 | a local runtime | the privacy lane |
 | user-level systemd timers | the schedule |
 
-Headless Linux gotchas the setup script handles: install a keyring or the CLIs re-prompt for auth on every launch; run device-code sign-ins inside `tmux`; invoke CLIs by absolute path from non-login shells.
+Review `vm/setup-vm.sh` before running it: that separately invoked deployment script installs system dependencies, including a keyring, and selected npm vendor CLIs. Complete vendor sign-ins inside `tmux` and inject the names in `vm/ENVIRONMENT.md`. Then, from `vm/`, run `bash setup-vm.sh --start-services`. It starts Compose; when Ollama is selected, it pulls the configured model inside that service and verifies a completion through `local-small`.
+
+Before enabling the timer, check `command -v node` and the selected CLI on the box. The service supplies `Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"`; add their actual absolute directories there when needed. The script resolves `node` and vendor CLIs through that `PATH`. systemd does not expand `$PATH`, `$HOME` or `~` in this setting. Follow `vm/jobs/README.md` to configure the unit and verify a manual run.
 
-## 6. Rules that do not bend on a box
+## 6. Set spending and privacy boundaries
 
-- No payment card on any compute lane without a human saying so. Free credit only.
-- Local first; cloud only when local genuinely cannot.
-- Private notes, client data and personal records never go to a third-party bulk lane. Name the barred lanes.
+- Configure spending and token limits before scheduling a compute job. Include a check that stops for approval when a job would exceed its approved budget.
+- Choose local or hosted execution from capacity, privacy and the approved budget.
+- Fill in `vm/PRIVACY_GATES.md`: classify the data and name the allowed and barred lanes. Confidential data needs explicitly approved processors or a local runtime; personal data needs explicitly authorized processing with the required privacy boundary. Keep protected data out of unapproved bulk lanes.
 - Nothing binds to `0.0.0.0`.
 - A secret is never printed, never in argv, never in a file in the repo.
 
@@ -54,15 +64,15 @@ What and why · trigger · invocation chain · dependencies · reads · writes
 
 ## 8. codecalc on the box
 
-Runs as a stdio MCP server next to the orchestrator CLI: offline, no key, nothing to bind. The weekly audit's figures (lane counts, version deltas, spend) are computed there, not estimated by the free lane that drafts the report. See [codecalc](https://github.com/The-40-Thieves/codecalc).
+If selected and separately installed, codecalc runs as a stdio MCP server next to the orchestrator CLI: offline, no key, nothing to bind. For jobs that need arithmetic, configure calculation through codecalc or an available calculator or runtime and supply the inputs to verify. The weekly audit collects the observations listed above and asks its selected lane to compare them with the delegation matrix. See [codecalc](https://github.com/The-40-Thieves/codecalc).
 
 ## 9. obsidian-tc on the box
 
-Stdio next to the orchestrator, or the upstream Docker service against a bind-mounted vault. Embeddings on the box's Ollama, so nothing leaves the machine. HTTP transport stays off unless every caller is on the private mesh and auth is on.
+If selected, use stdio next to the orchestrator, or the upstream Docker service against a bind-mounted vault. Without it, use a searchable notes folder with one writer. Embeddings on the box's Ollama, so nothing leaves the machine. HTTP transport stays off unless every caller is on the private mesh and auth is on.
 
-## 10. context7 on the box
+## 10. Context7 on the box
 
-Unlike the other two companions, it is never fully local: the hosted endpoint is a network call over HTTPS from the box, or a local `npx` server over stdio still needs no cloud account to run anonymously. Either way, only the library name and the query text leave the box, never source code. Scheduled jobs that write code against a vendored dependency pull its current docs through Context7 first, then prove the shape with codecalc before it ships.
+If selected, Context7 retrieves documentation over the network, including when its MCP server runs locally. Keep private source and secrets out of query text. Without it, read current official docs or upstream source. Then test the API shape with your local runtime before release.
 
 ## What the installer gives you at this level
 

package/docs/security-review-history.md

@@ -0,0 +1,38 @@
+# Security review history
+
+This page summarizes completed reviews recorded in the [changelog](../CHANGELOG.md) and their regression checks. It records the releases reviewed, what failed and what changed. It carries no claim that a past review verifies a later release.
+
+## Review rounds and fixes
+
+| Release | Review recorded | What the review found | What changed and where it is checked |
+|---|---|---|---|
+| 0.1.0 | Initial review and follow-up round, with a second model-family review | Paths could escape the write roots, partial writes could remain, malformed arguments could proceed, and empty results could appear successful | Containment preflight, exclusive writes with rollback, strict flag parsing and vendor-specific result checks; `test/install.test.js`, `test/cli.test.js`, `test/judges.test.js` |
+| 0.1.1 | Follow-up on issues #1 through #10 | Child processes could survive timeouts; a failed scheduled run could replace a good report; logs could contain provider text | Process-group cleanup, temporary report plus rename, bounded probes and fixed log codes; `test/cli.test.js`, `test/install.test.js` |
+| 0.1.2 | Follow-up on issues #12 through #15 | Interrupt cleanup, split UTF-8 output and stale existing files could produce misleading results | Interrupt handlers, streaming decoders and a pre-run snapshot for `--expect-file`; `test/cli.test.js` |
+| 0.1.3 | Independent repository review | Version pins, runtime-upgrade reporting and setup documentation disagreed | Shared catalog rendering, explicit upgrade reports and catalog checks; `test/catalog.test.js`, `test/install.test.js` |
+| 0.1.15 | Pre-release review of routing hooks | Open stdin and non-regular rules files could hang hooks; some review agents were described more restrictively than their tools enforced | Bounded asynchronous stdin, regular-file checks and bounded reads; tool-grant wording corrected; `test/hooks.test.js`, `test/install.test.js` |
+| 0.1.16 | Permission-claim follow-up | Agents with Bash were described as read-only without qualifying the command permission | Every such claim now distinguishes prompt instructions from actual tool restrictions; `test/install.test.js` |
+| 0.1.18 | Windows execution checks and CI follow-up | npm shims needed safe direct execution; watchdog ordering could hide a timeout | Resolve supported shims to Node, refuse unresolved batch targets for runner calls, preserve timeout markers; `test/judges.test.js`, `test/cli.test.js`, `test/install.test.js` |
+| 0.1.20 | Pre-release plugin review | Fallback hook text could exceed the output cap; the safety test missed asynchronous writes and subprocesses | Bound emitted strings and expand the guard with failing examples; `test/hooks.test.js`, `test/plugin.test.js` |
+| 0.1.23 | Pre-release review of failure classification | Redaction order, escaped strings, unbounded scans, transcript containment and clipped-error classification could fail | Redact before clipping, bound scans, resolve containment with path semantics, classify full trusted error fields; `test/classify.test.js` |
+| 0.1.31 | Uninstall validation recorded with release | Managed removal needed full manifest validation and preservation of user edits | Validate paths, hashes and target roots before removing anything; retain edited and foreign files; `test/uninstall.test.js` |
+
+The current suite prints its own counts when you run `npm test`. [Platform support](../README.md) documents the tests that require POSIX behavior and the Windows limitations.
+
+## Incident: a successful exit with no new file
+
+A worker could finish successfully while leaving an old output file untouched. A filesystem snapshot taken before the call made that observable: `--expect-file` now requires a new or changed file. The regression checks the old-file case as well as a real update. Source: [0.1.2 release record](../CHANGELOG.md#012---2026-09-05), `test/cli.test.js`.
+
+## Incident: a hook waiting forever for input
+
+A routing hook waited for stdin to close, and a non-regular rules path could block a file read. The hook now bounds its stdin wait, verifies that a target is a regular file and reads into a bounded buffer. The tests leave stdin open and place a FIFO at the rules path on supported platforms. Source: [0.1.15 release record](../CHANGELOG.md#0115---2026-09-10), `test/hooks.test.js`.
+
+## Incident: clipping before redaction
+
+A shortened error string could lose the delimiter needed to recognize a sensitive value. Redacting the complete bounded text before shortening it fixed the ordering problem. The regression covers escaped and unterminated values without publishing real credentials. Source: [0.1.23 release record](../CHANGELOG.md#0123---2026-09-15), `test/classify.test.js`.
+
+## Verify your own installation
+
+Run `npm test` for fixtures and stubs. Run `aunx cli-run --doctor --run` through your own sign-ins to check current vendor behavior (direct form from the installed rules folder: `node bin/cli-run.mjs --doctor --run`). Fixture checks establish the behavior they exercise; a live run adds evidence about your installed vendors, credentials and quota.
+
+Review current guarantees in [guarantees.md](guarantees.md). Report a vulnerability through the private channel in [SECURITY.md](../SECURITY.md).

package/llms.txt

@@ -1,40 +1,39 @@
 # model-orchestrator
 
-> Model orchestrator for AI coding agents and LLMs (Claude Code, Codex, Antigravity (Google), Grok, Qwen, Ollama). One installer writes routing rules, subagent definitions and a CLI lane runner for the AI tools you already have. The rules tell your agent which model, subagent or CLI to use for each task, so small work goes to cheap tiers and fewer tokens go to frontier models. It sits above the request layer: your agent reads the rules and picks the lane, so the decision stays readable, versioned and editable. Request-level routers and gateways compose underneath it.
+> Model router for AI coding agents: installs routing rules, 8 subagents, hooks and a CLI runner so your AI picks model and effort per task and saves tokens. A lane is an AI tool or model that can receive work; a tier describes model strength and cost. It sits above the request layer: your agent reads the rules and picks the lane. Request-level proxies and gateways can carry API calls underneath it.
 
-Install and run: `npx model-orchestrator` (interactive), or headless: `npx model-orchestrator --yes --level 2 --ais claude-code,codex --project . --dir ./ai-orchestrator`. Preview without writing: add `--dry-run`. List every supported AI: `npx model-orchestrator --list`. Node 18 or newer, zero runtime dependencies, MIT licence.
+Install: `npx model-orchestrator`. Interactive installation applies the main agent's catalog-supported project rules and settings with backups under one confirmation. Use `--no-apply` or the edit screen to keep activation manual. Headless: `npx model-orchestrator --yes --level 2 --ais claude-code,codex --project . --dir ./ai-orchestrator`. Headless activation requires `--apply-snippets`; add `--dry-run` to preview. Every non-dry install runs a local CLI presence health check; live canaries require `--doctor --run` explicitly. "What's left for you" lists only remaining actions, including one paste step for a chat app.
 
-Levels: 1 beginner (one agent or chat app), 2 intermediate (several agent CLIs, each called through `cli-run`), 3 advanced (adds a virtual machine with a gateway and a scheduled audit job). On Claude Code the install also delegates execution to subagents by default and ships three hooks: `route-gate` (UserPromptSubmit) and `subagent-context` (SubagentStart) inject the routing table every turn, and `route-metrics` logs route markers and subagent dispatches.
+Companions default to none, including with `--yes`. With activation enabled, supported project MCP configuration is merged with backups; global configuration stays manual. The installer prints third-party setup commands and never runs installs or login flows. Codex's reliable status check removes an already-completed sign-in from the list; other CLIs receive conditional sign-in instructions. Uninstall removes unchanged recorded activation blocks and added hook or MCP entries while preserving surrounding content and backups.
 
-Claude Code plugin: `/plugin marketplace add aunysillyme/model-orchestrator`, then `/plugin install model-orchestrator@model-orchestrator`. It installs the two read-only hooks (`route-gate`, `subagent-context`) and eight subagents; the routing rules still come from `npx model-orchestrator`, and the routing log (`route-metrics.mjs`) is npm-only.
+Command: `npm install -g model-orchestrator` makes `aunx` available. `aunx` alone runs the installer; `aunx cli-run` runs an AI CLI; `aunx route-metrics --summary` shows local routing activity; `aunx brief`, `aunx context` and `aunx checks` scaffold task context and verification. `aunx checks run ACCEPTANCE_CHECKS.json` executes trusted check commands and exits 1 on any failure. `aunx route "rename this file"` prints an explained suggestion without launching a worker.
 
-Pick a model proxy (LiteLLM, Portkey, OpenRouter, claude-code-router) for per-request model routing underneath an agent; pick model-orchestrator for installed routing rules, subagents, hooks and a lane runner for coding agents and subscription CLIs. They compose.
+Pick a model proxy (LiteLLM, Portkey, OpenRouter, claude-code-router) for per-request model routing underneath an agent; pick model-orchestrator for task delegation using installed rules, subagents, hooks and a CLI runner. They compose.
 
 ## Docs
 
-- [README](https://github.com/aunysillyme/model-orchestrator/blob/main/README.md): what it is, a real dry-run plan, the levels, the AIs, the principles
-- [Installing](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/install.md): every flag, the two folders a run writes to, headless examples, the full file list
-- [How it routes](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/how-it-routes.md): role, complexity and stakes; the three verifier agents; pinning model and effort per lane
-- [Guarantees](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/guarantees.md): what is enforced by code, what is delegated to a vendor flag, what is only an instruction
-- [Companion tools](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/companions.md): codecalc, obsidian-tc and Context7, what each closes and what it needs first
-- [Part 1: beginner](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-1-beginner.md): one agent, tiers, the task bundle every delegation carries
-- [Part 2: intermediate](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-2-intermediate.md): several agent CLIs, the lane runner, pinning model and effort per lane
-- [Part 3: advanced](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-3-advanced.md): the VM, the gateway, scheduled jobs, privacy gates
-- [AI catalog](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/catalog.md): every supported AI, how to sign in, how each is detected
+- [Start here](https://github.com/aunysillyme/model-orchestrator/blob/main/README.md): model routing, activation, commands, search-phrased FAQ and related projects
+- [Install and upgrade](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/install.md): flags, walkthrough, 0.1.x upgrades, project commands and uninstall
+- [How routing works](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/how-it-routes.md): role, complexity, stakes, model and effort, independent verification
+- [Guarantees](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/guarantees.md): code-enforced properties, vendor permissions and agent instructions
+- [Optional companions](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/companions.md): other authors' tools, upstream setup and support, fallback tools
+- [Beginner](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-1-beginner.md): model tiers, a task brief, a context file and acceptance checks inside one agent
+- [Intermediate](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-2-intermediate.md): subscription lanes, pay-per-token lanes, research and shared work
+- [Advanced](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-3-advanced.md): Linux host, gateway templates, scheduled work and privacy boundaries
+- [Catalog](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/catalog.md): supported AIs, install commands, sign-in and detection
 
 ## Reference
 
-- [Claude Code plugin](https://github.com/aunysillyme/model-orchestrator/blob/main/plugin/README.md): installing the hooks and subagents with `/plugin install`, what the plugin reads, and what it leaves to the installer
-- [CLI runner](https://github.com/aunysillyme/model-orchestrator/blob/main/bin/README.md): `cli-run` lanes, exit codes, the route logged per run
-- [Templates](https://github.com/aunysillyme/model-orchestrator/blob/main/templates/README.md): the routing, tiers, task bundle and protocol files the installer renders
-- [Changelog](https://github.com/aunysillyme/model-orchestrator/blob/main/CHANGELOG.md): every release and the issue behind each fix
-- [Agent instructions](https://github.com/aunysillyme/model-orchestrator/blob/main/AGENTS.md): running the installer from an agent, and contributing
-
-## Plans and automatic effort
-
-- [Plans and automatic effort](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/install.md#plans-and-automatic-effort): `--plans AI=plan` states a subscription plan so the guidance allocates volume by headroom; opt-in `--effort-auto` sizes effort per call on high or max headroom CLI lanes, medium or high, with xhigh named explicitly for security-critical or irreversible work
+- [Commands](https://github.com/aunysillyme/model-orchestrator/blob/main/bin/README.md): aunx subcommands, CLI runner exit codes and output contracts
+- [Templates](https://github.com/aunysillyme/model-orchestrator/blob/main/templates/README.md): routing rules, task brief, context, acceptance checks and protocols
+- [Claude Code plugin](https://github.com/aunysillyme/model-orchestrator/blob/main/plugin/README.md): installing read-only routing hooks and subagents through the plugin marketplace
+- [Proof](https://github.com/aunysillyme/model-orchestrator/blob/main/proof/README.md): dated measurements, methods, sample sizes, expiry and reproduction scripts
+- [Security review history](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/security-review-history.md): completed review rounds, incident summaries and regression evidence
+- [Changelog](https://github.com/aunysillyme/model-orchestrator/blob/main/CHANGELOG.md): release changes and upgrade notes
+- [Agent instructions](https://github.com/aunysillyme/model-orchestrator/blob/main/AGENTS.md): headless setup and contributor checks
 
 ## Optional
 
-- [Security policy](https://github.com/aunysillyme/model-orchestrator/blob/main/SECURITY.md)
-- [Audit brief](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/audit-brief.md): the security notes and what has already been security-reviewed
+- [Security policy](https://github.com/aunysillyme/model-orchestrator/blob/main/SECURITY.md): private vulnerability reporting
+- [agent-personalizer](https://github.com/aunysillyme/agent-personalizer): one interview writes the profile and rules every AI reads, kept in sync from one source
+- [website-build-skill](https://github.com/aunysillyme/website-build-skill): current website-building expertise for your AI, from research and design through accessibility and security

package/package.json

@@ -1,23 +1,25 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.34",
-  "description": "Model orchestrator: rules and subagents tell your agent which model does each task, so small work goes to cheap tiers and fewer tokens go to frontier models.",
+  "version": "1.0.0",
+  "description": "Model router for AI coding agents: installs routing rules, 8 subagents, hooks and a CLI runner so your AI picks model and effort per task and saves tokens",
   "type": "module",
   "bin": {
-    "model-orchestrator": "bin/cli.js"
+    "model-orchestrator": "bin/cli.js",
+    "aunx": "bin/aunx.js"
   },
   "files": [
     "bin",
     "src",
     "templates",
     "docs",
+    "!docs/router-trailer.gif",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
     "SECURITY.md",
-    "scripts",
     "llms.txt",
-    "AGENTS.md"
+    "AGENTS.md",
+    "proof"
   ],
   "scripts": {
     "start": "node bin/cli.js",
@@ -25,7 +27,10 @@
     "prepublishOnly": "npm test",
     "dry-run": "node bin/cli.js --yes --level 2 --ais claude-code,codex,grok --dir ./tmp-dry-run --dry",
     "gen:catalog": "node scripts/gen-catalog.js",
-    "gen:plugin": "node scripts/gen-plugin.js"
+    "gen:plugin": "node scripts/gen-plugin.js",
+    "proof:measure": "node proof/scripts/measure.js",
+    "proof:render": "node proof/scripts/render.js",
+    "proof:demo": "node proof/scripts/record-gate.js"
   },
   "engines": {
     "node": ">=18"
@@ -80,8 +85,11 @@
     "agent-routing",
     "prompt-routing",
     "coding-agent",
-    "ai-coding"
+    "ai-coding",
+    "coding-agents",
+    "aunx"
   ],
   "author": "aunysillyme (https://github.com/aunysillyme)",
-  "license": "MIT"
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/aunysillyme"
 }

package/proof/README.md

@@ -0,0 +1,100 @@
+# Reproduce the measurements
+
+Generated from [results.json](results.json). Each figure has a method, sample size, measurement date and expiry. Run the scripts on your own machine to compare.
+
+Environment: Node v22.22.3, darwin arm64. Timing varies with startup caches and other work on the machine. Synthetic cases show what those fixtures exercise.
+
+| Measurement | Result | Sample size | Measured | Expires | Reproduce |
+|---|---|---|---|---|---|
+| Dry install wall time | 42.22 ms median | 7 | 2026-09-27 | 2026-10-11 | [script](../proof/scripts/install-time.js) |
+| Lane runner overhead | 63.74 ms median difference | 7 | 2026-09-27 | 2026-10-11 | [script](../proof/scripts/runner-overhead.js) |
+| Empty results flagged | 10 fixtures rejected | 10 | 2026-09-27 | 2026-10-11 | [script](../proof/scripts/missing-results.js) |
+| Acceptance failures blocked | 4 fixtures rejected | 4 | 2026-09-27 | 2026-10-11 | [script](../proof/scripts/check-gate.js) |
+| Main conversation browser tokens | 408147 tokens per browser step (median) | 9775 | 2026-09-26 | 2026-10-27 | author setup, re-measured locally |
+| Small browser subagent tokens | 17197 tokens per step (highest of 5 runs) | 5 | 2026-09-27 | 2026-10-27 | author setup, re-measured locally |
+
+## Run the proof scripts
+
+```sh
+node proof/scripts/measure.js
+node proof/scripts/render.js
+npm test
+```
+
+The measurement command refreshes reproducible entries and preserves separately sourced author-setup entries. The test suite rejects expired, future-dated or incomplete entries and checks this page against the data. The weekly [refresh workflow](../.github/workflows/proof.yml) reruns the scripts and commits their data and generated page.
+
+## Try the acceptance gate
+
+```sh
+aunx checks ACCEPTANCE_CHECKS.json
+aunx checks run ACCEPTANCE_CHECKS.json
+```
+
+The scaffold starts red. Replace the sample with commands that prove your requirements, then put `aunx checks run ACCEPTANCE_CHECKS.json && <your-release-command>` in your own release sequence. Commands are local code you review before running. Manual evidence stays UNVERIFIED and blocks the gate.
+
+![Acceptance gate rejects a missing output, then passes after the output exists](gate-demo.gif)
+
+The [recording script](scripts/record-gate.js) captures real command output into an asciicast, then renders it with an already installed agg. Companion tools are installed by their users.
+
+## Measurement methods
+
+### Dry install wall time
+
+Spawn a fresh Node installer process per sample; level 2, Claude Code + Codex, no companions, --dry. Includes Node startup and planning; writes no install files. Isolated home and PATH, no real vendors.
+
+Kind: reproducible local measurement. Sample size: 7. Measured: 2026-09-27. Expires: 2026-10-11.
+
+Source: [proof/scripts/install-time.js](../proof/scripts/install-time.js).
+
+### Lane runner overhead
+
+Paired fresh processes: direct Node stub versus cli-run hermes with the same stub. Alternates pair order. Includes wrapper startup, validation and local log writes; excludes vendor/network/model time.
+
+Kind: reproducible local measurement. Sample size: 7. Measured: 2026-09-27. Expires: 2026-10-11.
+
+Source: [proof/scripts/runner-overhead.js](../proof/scripts/runner-overhead.js).
+
+### Empty results flagged
+
+Run cli-run against an exit-0 stub for every supported lane, once with empty stdout and once with an empty native final result. Count exit 10/11 only. A successful Hermes response is the positive control. Synthetic fixtures measure these shapes only.
+
+Kind: reproducible local measurement. Sample size: 10. Measured: 2026-09-27. Expires: 2026-10-11.
+
+Source: [proof/scripts/missing-results.js](../proof/scripts/missing-results.js).
+
+### Acceptance failures blocked
+
+Run aunx checks run against nonzero, manual, missing-program and timeout fixtures. Each must exit 1; a passing command must exit 0. This is a local command gate, activated by the user in their release sequence.
+
+Kind: reproducible local measurement. Sample size: 4. Measured: 2026-09-27. Expires: 2026-10-11.
+
+Source: [proof/scripts/check-gate.js](../proof/scripts/check-gate.js).
+
+### Main conversation browser tokens
+
+Measured on the author's Claude Code sessions: every browser tool call in the transcripts, counting tokens re-read by the main conversation per step. Median: 408,147 tokens per browser step across 145 sessions and 9,775 browser steps. Sample size counts browser steps.
+
+Kind: measured on the author's setup. Sample size: 9775. Measured: 2026-09-26. Expires: 2026-10-27.
+
+Source: author setup, re-measured locally.
+
+### Small browser subagent tokens
+
+At least 23x fewer tokens per step in this sample: the main conversation median of 408,147 divided by the highest subagent run of 17,197 is 23.73x. Measured on the author's Claude Code sessions, with the same kind of work handed to a small browser subagent. Five runs, tokens divided by steps or tool calls per run: 17,197 (206,369 tokens / 12 steps, 2026-09-26); 4,077 (93,773 / 23), 4,201 (105,034 / 25), 4,585 (91,709 / 20), and 4,489 (94,263 / 21), all four on 2026-09-27. Range: 4,077 to 17,197; median of 5 runs: 4,489. Typical context, using the median of 5 runs: about 91x fewer tokens per step. These are measurements from the author's own sessions, not a controlled comparison or a guarantee for other setups. The four 2026-09-27 runs shared one browser pane, so some steps were spent recovering a drifting tab, which raises the step count and lowers per-step tokens. The first run counted steps; the later runs counted tool calls. Sample size counts runs.
+
+Kind: measured on the author's setup. Sample size: 5. Measured: 2026-09-27. Expires: 2026-10-27.
+
+Source: author setup, re-measured locally.
+
+## Operation and verification
+
+- **What and why:** executable measurements keep public figures traceable to current output.
+- **Trigger:** weekly schedule, workflow dispatch, or `node proof/scripts/measure.js`.
+- **Invocation chain:** workflow -> measurement functions -> isolated Node fixtures -> results.json -> this page -> npm test.
+- **Dependencies:** Node and the repository. The optional GIF recorder uses agg from the asciinema project.
+- **Reads:** package scripts, the installer, runner and acceptance-check runner. Fixture tests use an isolated home and PATH.
+- **Writes:** results.json, this generated page, temporary fixture directories and local fixture logs. The recorder writes gate-demo.cast and gate-demo.gif.
+- **Closed loop:** the workflow fails when measurement or tests fail. GitHub Actions records the failure; repository notification settings decide who receives it. No separate alert service is configured.
+- **Failure modes:** runner behavior changes, an expired catalog snapshot, missing runtime, unavailable write permission, or timing noise. Review the failed job, rerun locally, and send a reproducible issue to the repository maintainers.
+- **Run and verify:** run the commands above, inspect sample arrays and fixture exit codes in results.json, and require npm test to pass. A future-time unit test proves expiry can fail.
+- **Source of truth:** results.json and the scripts it names. Author-setup evidence is added separately by its owner.

package/proof/gate-demo.cast

@@ -0,0 +1,9 @@
+{"version":2,"width":86,"height":15,"title":"Acceptance checks: red, then green","env":{"TERM":"xterm-256color"}}
+[0,"o","\u001b[1;32m$\u001b[0m aunx checks run checks.json\r\n"]
+[0.6,"o","\u001b[31mFAIL output-exists: exit 1\r\n\u001b[0m"]
+[1.2,"o","$ echo $?\r\n1\r\n"]
+[3,"o","\r\n$ node -e 'require(\"node:fs\").writeFileSync(\"output.txt\",\"verified output\")'\r\n"]
+[4.5,"o","\r\n\u001b[1;32m$\u001b[0m aunx checks run checks.json\r\n"]
+[5,"o","\u001b[32mPASS output-exists: exit 0\r\n\u001b[0m"]
+[5.5,"o","$ echo $?\r\n0\r\n"]
+[7,"o","\r\nThe exit code gates the next command in your release sequence.\r\n"]