model-orchestrator 0.1.34 → 1.0.0

package/templates/common/protocols/propagate.md

@@ -1,34 +1,25 @@
-# Propagate: change completeness
+# Propagate: complete a shared change
 
-**A rename is a refactor, not a single-file edit.** Any change to a name, term, path, slug, schema field, routing rule or shared convention reaches everything that uses it, and the goal is zero silent strays.
+When changing a name, term, path, slug, schema field, routing rule or shared convention, treat every consumer as part of the change. Use scoped search or a cheap worker to collect references before asking a planning model to decide anything.
 
-This is retrieval work. It stays with the orchestrator (or a cheap worker for the grep sweep). It never goes to the deep tier: a judgment model re-deriving a file list is the most expensive routing mistake there is.
+## Map consumers before editing
 
-## 1. Map everything it touches (before editing anything)
+- Search code, configuration, hooks, scheduled jobs and CI within the authorized repositories.
+- Search project instructions and any authorized record store for the old term and link forms.
+- Check documented external consumers such as webhooks, dashboards or generated outputs.
+- When obsidian-tc is selected, use backlinks and text search; when absent, use file search and the project's own link checker.
+- Scope recursive searches away from `.git`, `node_modules` and generated build output unless that output is explicitly part of verification.
 
-- **Docs and notes:** backlinks to the thing being renamed; literal search for the old term and its link forms. With obsidian-tc: `get_backlinks`, `search_text`, then `find_unresolved_links` after the change (`protocols/memory-and-record.md`).
-- **Memory / instructions:** grep every instructions file your agents read (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `QWEN.md`, custom instructions) and any memory store.
-- **Code / config:** grep the repos, settings files, hooks, scheduled jobs, CI, and the files this installer wrote.
-- **Other people's surfaces:** anything that consumes the old name from outside (webhooks, dashboards, bookmarks).
+## Update the affected surfaces
 
-```bash
-grep -rniE "<old-term>" --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=dist .
-```
+- Turn each hit into a checklist item with its owner and needed permission.
+- Use a supported refactor or link-rewrite tool when one exists; otherwise apply scoped edits.
+- Update indexes and documentation in the same change.
+- When a consumer is outside the granted scope, return the exact required handoff and keep it visible in coverage.
 
-## 2. Build the checklist
+## Verify old and new references
 
-Every hit becomes a line, grouped by surface. Nothing closes until the list is empty. Mark which items are approval-gated (production deploys, database migrations, anything public).
-
-## 3. Execute on all fronts
-
-Change every item. Use the tool's own governed rename where one exists (a link rewriter, an IDE refactor) over hand edits. If an index or README lists the renamed thing, that index is part of the change, not a follow-up.
-
-## 4. Verify: the loud negative (non-negotiable)
-
-Re-grep the OLD identifier across every surface. **Expect zero**, except historical records you name explicitly. Then check for dangling references the rename created (unresolved links, 404s, failing imports).
-
-Paste the final grep output as proof. If any stray survives, it is not done.
-
-## Why the last step is the one that matters
-
-Steps 1 to 3 find what you thought of. Step 4 finds what you did not. A rename that "looks complete" and leaves one stray is worse than an unstarted one, because the stray is now believed.
+- Search the old identifier again in every declared scope.
+- Require zero active references, except named compatibility paths or historical records.
+- Verify the new links, imports and consumer behavior with the relevant checker.
+- Return the search command, exit status and any intentional retained matches as evidence.

package/templates/intermediate/CLI-RUN.md

@@ -1,165 +1,135 @@
-# CLI-RUN.md: exit 0 means a structurally accepted, non-empty response
+# Lane runner (`aunx cli-run`)
 
-`bin/cli-run.mjs` is one entrypoint for the agent CLI lanes. It builds the right invocation per lane, reads that lane's native terminal event, and exits non-zero unless a structurally accepted, non-empty response came back.
+When assigning work to a CLI lane, use `aunx cli-run` or the installed `bin/cli-run.mjs`. The runner builds the vendor invocation, reads its terminal event and returns an exit code for the response and any explicit output contract.
 
-## The guarantee, exactly
+Enabled lanes (edit `bin/lanes.json`): {{CLI_RUN_LANES}}.
 
-Exit 0 means: the lane's native terminal event says it finished, the response is non-empty, and the lane-specific error checks passed. **It does not mean the task was done.** A refusal that parses cleanly is exit 0. When your task has a real contract, state it:
+## Call a lane with a task brief
 
 ```bash
-node bin/cli-run.mjs codex "Write the report to out/report.md" --expect-file out/report.md   # must exist, be non-empty, and be written during this run
-node bin/cli-run.mjs grok  "Return the table as JSON" --expect-json                          # the response must parse as JSON
+aunx cli-run {{EXAMPLE_LANE}} --brief TASK_BRIEF.md --timeout 900
+node bin/cli-run.mjs {{EXAMPLE_LANE}} --brief TASK_BRIEF.md --timeout 900
 ```
 
-An unmet contract is exit 10 with reason `contract_unmet`. `--expect-file` snapshots the target before the lane starts (existence, size, mtime, content hash) and afterwards requires a non-empty regular file that is new or changed: a different hash, or a later mtime. A file that existed before and was not touched fails, however recent it is; a rewrite with identical bytes and an unchanged mtime also fails, because nothing distinguishes it from no write. Timestamps and hashes are evidence of change, not proof of authorship: if another process could write the same path during the run, use a per-attempt path. Text-only callers need nothing new: without a contract flag the behaviour is the structural check above.
+When `aunx` runs, it uses the packaged runner. Use `--dir <rules-directory>` to select an installed project runner and its lane configuration explicitly. An absent project runner falls back to the package runner.
 
-Enabled lanes (edit `bin/lanes.json`): {{CLI_RUN_LANES}}
+When requesting a particular route, inspect the lane's current roster and select the model and effort for the job:
 
 ```bash
-node bin/cli-run.mjs <grok|codex|agy|hermes|qwen> "<prompt>" [--brief FILE] [--timeout SECS] [--quiet]
-node bin/cli-run.mjs codex --audit "<prompt>"                  # read-only sandbox, the audit shape
-node bin/cli-run.mjs codex "<prompt>" --model gpt-6-astra --effort high
-node bin/cli-run.mjs codex "<prompt>" --effort auto                 # medium or high, bounded heuristic
-node bin/cli-run.mjs qwen [--safe-mode] "<prompt>"             # qwen-only flag
+aunx cli-run {{EXAMPLE_LANE}} "<prompt>" --model '<model-id>'{{EXAMPLE_EFFORT_FLAGS}}
+node bin/cli-run.mjs {{EXAMPLE_LANE}} "<prompt>" --model '<model-id>'{{EXAMPLE_EFFORT_FLAGS}}
 ```
 
-Put it on your PATH if you like: `ln -s "$PWD/bin/cli-run.mjs" ~/.local/bin/cli-run`.
+{{EXAMPLE_AUDIT_BLOCK}}
 
-## First run: `--doctor`
+{{QWEN_SAFE_MODE_NOTE}}`--quiet` suppresses human-readable status lines. `--timeout SECS` bounds each call.
+
+## Check availability before work depends on it
 
 ```bash
-node bin/cli-run.mjs --doctor          # which lanes are enabled and which binaries are on PATH; runs nothing
-node bin/cli-run.mjs --doctor --run    # also sends each enabled lane one tiny prompt and judges the reply (uses a little quota)
+aunx cli-run --doctor
+node bin/cli-run.mjs --doctor
+aunx cli-run --doctor --run
+node bin/cli-run.mjs --doctor --run
 ```
 
-With zero enabled lanes, doctor reports inactive and exits 13. Use level 1 or select a supported CLI. Binary presence does not verify authentication or that your primary loaded its instructions.
-
-A lane that is enabled but not on PATH, or that answers with no deliverable, shows up here before it shows up mid-task.
-
-## Why it exists
-
-Every agent CLI can exit 0 having produced nothing. The symptom (confident preamble, exit 0, no deliverable) is indistinguishable from a model failure, so it gets blamed on the model. Four wrong diagnoses in one week came from exactly that.
+Use `--doctor` to inspect enabled lanes, binaries and requested defaults. Use `--doctor --run` for a small live prompt on each enabled lane, consuming vendor quota. When no lanes are enabled, the doctor exits 13; choose a supported CLI or use level 1. Verify authentication and loaded project instructions separately from binary presence.
 
-Byte count is not a deliverable check either: a run can emit hundreds of kilobytes and contain no conclusion.
+## Verify the result contract
 
-## The success signal per lane
-
-| Lane | Invocation built | Success = |
-|---|---|---|
-| grok | `--output-format json -p` | `stopReason == "end_turn"` and non-empty `text` |
-| codex | `exec --json --color never --skip-git-repo-check -o FILE` | terminal `{"type":"turn.completed"}` and non-empty FILE |
-| agy | `--print-timeout Nm --output-format stream-json -p` | terminal `{"event":"result"}`, `status == "SUCCESS"`, non-empty `response` |
-| hermes | `-z … --usage-file FILE` | its exit code is already honest: 0 response · 1 none · 2 bad args |
-| qwen | `-o json [-m ID] [--safe-mode] -p` | terminal `{"type":"result"}`, `subtype == "success"`, `is_error` false, non-empty `result` not starting with `[API Error:`, and every `stats.models.*.api.totalErrors == 0` |
+When exit 0 returns, the native terminal event indicates completion, the response is non-empty and lane-specific error checks passed. Verify the task's actual acceptance checks separately: a structurally valid refusal can still satisfy that response shape.
 
-qwen is the lane whose own success flags lie: an upstream 400 comes back as exit 0, `subtype: success`, `is_error: false`, with the error text inside `result`. The two extra checks are the honest ones. Absent telemetry is refused, not read as zero.
+When the task requires a file or structured output, add an explicit contract:
 
-## Exit codes
+```bash
+aunx cli-run {{EXAMPLE_LANE}} "Write out/report.md" --expect-file out/report.md
+node bin/cli-run.mjs {{EXAMPLE_LANE}} "Write out/report.md" --expect-file out/report.md
+aunx cli-run {{EXAMPLE_LANE}} "Return the table as JSON" --expect-json
+node bin/cli-run.mjs {{EXAMPLE_LANE}} "Return the table as JSON" --expect-json
+```
 
-| Code | Class | Meaning | What to do |
-|---|---|---|---|
-| 0 | `ok` | structurally accepted non-empty response, every `--expect-*` contract met | use it; if `refused=N` is above 0, read the problem line |
-| 10 | `empty` | ran and delivered nothing, or a contract was unmet | rerun once, or use another lane |
-| 11 | `no_output` | no output at all | rerun once; check the lane runs on its own |
-| 12 | `timeout` | timed out; the lane and every descendant in its process group were killed | raise `--timeout` or split the brief |
-| 13 | `unavailable` | binary missing, disabled in `lanes.json`, or `lanes.json` malformed | install or enable the lane |
-| 14 | `auth` | the lane's own error says a credential is missing or it is not logged in | set the credential; retrying cannot help |
-| 15 | `quota` | the lane's own error says usage limit, credits or rate limit | switch lanes or wait for the reset |
-| 16 | `rejected` | the upstream rejected the request: an unknown model id, a malformed request | fix the id, flag or request it names |
-| 17 | `refused` | no deliverable, and the lane reports tool calls a hook or deny rule blocked | adjust the rule, or give the lane the tool |
-| 18 | `cut_short` | no trustworthy finish: a missing or non-success terminal event, a lane killed by a signal, output past the 16 MiB buffer, or a nonzero vendor exit nothing above explains (hermes' own exit 2, bad args or an empty response, stays `empty`) | rerun once, then read the lane's stderr |
-| 130 / 143 | `interrupted` | cli-run itself received SIGINT / SIGTERM; the lane's process group was killed first, then the temp dir removed | |
-| 2 | | usage error in cli-run itself | |
+`--expect-file` records existence, size, mtime and content hash before the run. It then requires a non-empty regular file that is new or changed by hash or later mtime. Use a unique per-attempt path when another process might write the same file. `--expect-json` requires parseable JSON. An unmet contract exits 10 with reason `contract_unmet`.
 
-A nonzero vendor exit is never `ok`, even when parseable text came back; the vendor's own code is kept in the log as `cli_rc`, and the bounded head of its stderr is shown on your terminal.
+## Read each lane's completion signal
 
-## Why a run failed: the class
+The runner supports these lanes whether or not you selected them.
 
-Exit 10 used to cover causes that need opposite responses. A missing API key is not a model fault, and retrying a spent quota cannot help. So every run lands in exactly one class, and on the terminal every failure (and every `ok` with refused calls) gets two more lines:
+| Lane | Invocation built | Accepted response |
+|---|---|---|
+| grok | `--output-format json -p` | `stopReason == "end_turn"` and non-empty `text` |
+| codex | `exec --json --color never --skip-git-repo-check -o FILE` | terminal `turn.completed` event and non-empty output file |
+| agy | `--print-timeout Nm --output-format stream-json -p` | terminal `result` event, `status == "SUCCESS"`, non-empty `response` |
+| hermes | `-z` with a usage file | vendor exit 0 and a non-empty response |
+| qwen | `-o json`, optional model and safe-mode flags, `-p` | successful terminal result, no error flag or API-error result, non-empty text and every model's `api.totalErrors == 0` |
 
-```
-cli-run[qwen] exit_nonzero rc=14 class=auth refused=0 0.8s raw=212B route=lane default :: lane exited 1; subtype="error_during_execution": Missing API key ...
-cli-run problem: cli-run[qwen] auth: Missing API key ...
-cli-run fix: set the credential the message above names (its environment variable, or the lane's own login command), then rerun
-```
+When Qwen's error telemetry is absent, the runner refuses the response. These checks distinguish response structure from successful task execution.
 
-A calling agent relays both lines and asks before fixing anything.
+## Respond to the exit class
 
-- **Signals come from each lane's authoritative error fields only.** codex: its own `error`, `turn.failed` and error-item events plus stderr. agy: the terminal result's status and error plus stderr. qwen: the terminal event's full error text (never the clipped display line) plus stderr. hermes: stderr on a nonzero exit, never its stdout. Never the model's prose, so an answer that explains what "rate limit" means is not a quota failure. grok and hermes have no native auth signal, and none is invented.
-- **Precedence** when several are present: `auth`, `quota`, `rejected`, `refused`, `cut_short`, `empty`. A missing credential explains everything downstream of it.
-- **`refused`** counts tool calls a hook or deny rule blocked: qwen's `permission_denials`, agy's deny-rule `TOOL_ERROR` steps, one per codex router `Rejected(` line on stderr, and grok's session transcript (`~/.grok/sessions/<cwd>/<sessionId>/updates.jsonl`: hook runs with `blocked`, and "Denied by permission policy"). grok's `sessionId` comes from lane output, so it must match `^[A-Za-z0-9-]{8,64}$`, the resolved path must stay inside the sessions root, every counted line must name that session, and the read stops at 5 MiB. `null` means the lane gave no readable signal (hermes always), which is an unknown, never 0.
-- **Refused with a deliverable is still exit 0.** The deliverable exists; `refused=N` and the problem and fix lines say what was blocked.
-- **Redacted.** The status, problem and stderr lines pass through one redaction pass before they are printed: JSON credential keys (escaped quotes, unterminated values and JSON escaped inside a string included), `Authorization:` values of any scheme, bearer values, URL query credentials, and the `sk-`, `xai-`, `ghp_` and `AIza` key prefixes. Redaction runs before any clipping, so a long token is never cut into an unrecognisable fragment. Denial text is searched in at most the first 256 KiB of stdout and of stderr, with bounded patterns, so hostile output cannot stall the wrapper after the lane has exited. None of these lines is ever logged.
+| Code | Class | Action |
+|---|---|---|
+| 0 | `ok` | Verify task acceptance; read the problem line if `refused` is positive |
+| 10 | `empty` | Inspect the missing response or unmet output contract |
+| 11 | `no_output` | Check the lane directly before another attempt |
+| 12 | `timeout` | Diagnose progress, then adjust the bound or split the work |
+| 13 | `unavailable` | Resolve binary presence, lane enablement or malformed configuration |
+| 14 | `auth` | Use the vendor's login or configured credential path |
+| 15 | `quota` | Select another authorized lane or wait for quota renewal |
+| 16 | `rejected` | Correct the model, flag or request named by the vendor |
+| 17 | `refused` | Inspect the denied tool call and route it within authorized permissions |
+| 18 | `cut_short` | Inspect a missing terminal event, signal, output overrun or unexplained nonzero vendor exit |
+| 130 / 143 | `interrupted` | The wrapper received SIGINT / SIGTERM; inspect cleanup before resuming |
+| 2 | usage error | Correct the runner arguments |
 
-## The route: which model, and how hard it thinks
+When a run fails, read the problem and fix lines and relay the actionable cause. Resolve it within existing authorization; request approval only for a change outside that scope. A nonzero vendor exit remains a failure even if text was produced; `cli_rc` preserves that vendor exit in the local log.
 
-A lane you do not pin runs on **its own config file**, which this tool cannot see. That is the quiet failure this section exists for: a CLI configured months ago at `reasoning_effort = "low"` keeps auditing at low effort while your routing docs describe a second-opinion pass, and nothing anywhere says so.
+The runner classifies authoritative vendor error fields, with precedence `auth`, `quota`, `rejected`, `refused`, `cut_short`, `empty`. It excludes ordinary model prose from those error signals. A readable result with refused tool calls can remain exit 0; read the reported refusal alongside the result. `refused: null` means the lane supplied no readable refusal signal.
 
-Pin it per call, or per lane:
+## Record the requested route
 
-```bash
-node bin/cli-run.mjs codex "<prompt>" --model gpt-6-astra --effort high   # this call only
-node bin/cli-run.mjs --doctor                                            # prints what each lane is pinned to
-```
+When a command flag is present, it overrides `bin/lanes.json` defaults. When both are absent, the lane uses its own configuration. Inspect that configuration when the model or effort matters.
 
 ```json
-{
-  "enabled": ["codex", "grok"],
-  "defaults": { "codex": { "model": "gpt-6-astra", "effort": "high" } }
-}
+{{EXAMPLE_LANES_JSON}}
 ```
 
-A flag beats `defaults`; `defaults` beats nothing. Each vendor spells these differently and `cli-run` translates:
+Replace the placeholder with a current vendor model ID before using this example. Model and effort values are bounded to the supported safe character set.
+
+The runner supports these lanes whether or not you selected them.
 
-| Lane | Model | Reasoning effort |
+| Lane | Model flag | Effort flag |
 |---|---|---|
 | grok | `-m` | `--reasoning-effort` |
 | codex | `-m` | `-c model_reasoning_effort="LEVEL"` |
-| agy | `--model` | `--effort` (low, medium, high) |
-| hermes | `-m` | `--reasoning` (none, minimal, ...) |
-| qwen | `-m` | none: this lane has no reasoning flag |
-
-Three rules that keep this honest:
-
-- **A level `cli-run` does not recognise is not rejected here.** Levels are the vendor's, they change, and guessing the valid set would date this tool. An unknown level is refused by the lane and surfaces as a class (codex reports it as `rejected`, exit 16; a lane with no rejection signal as `cut_short`, exit 18), with the lane's own exit code in the log as `cli_rc` and its stderr on your terminal.
-- **`--effort` on qwen is a usage error, not a silent drop.** A flag that vanishes leaves you believing a route that never ran.
-- **`--effort auto` is bounded.** It uses prompt size, or an audit's changed-file evidence, and resolves only medium or high. An audit is always high. Auto is a heuristic, not a measurement: name `xhigh` explicitly for security-critical or irreversible work.
-- **Values are charset-bounded** (letters, digits, and `. _ : @ / + -`, no leading dash, 64 characters). A model id becomes an argv element and, on codex, part of a TOML value; bounding it is what stops either from being escaped.
-
-## Permissions are a separate layer
-
-`cli-run` never injects permission flags. Each CLI carries its own config, so every caller gets the same behaviour. Use each vendor's deny-list as the base layer; allow-lists only hold if every binary is enumerable in advance.
-
-## Log
-
-`~/.ai-orchestrator/cli-run.log.jsonl`, one line per run: lane, verdict, `class` (one of the classes above), rc, the lane's own exit code (`cli_rc`), signal, `refused` (an integer, or `null` when the lane gives no signal), seconds, raw bytes, deliverable bytes, a 12-hex sha256 prefix of the prompt and its length, the route (`model_requested`, `effort_requested`, and `model_source` / `effort_source`, each one of `flag`, `lanes.json` or `lane_default`), auto-sizing evidence (`effort_resolved`, `effort_basis`, `effort_scope`), and `reason`: one of a fixed set of codes (`ok`, `not_json`, `bad_stop_reason`, `empty_text`, `no_terminal_event`, `bad_status`, `api_error_in_result`, `total_errors`, `contract_unmet`, `exit_nonzero`, `timeout`, `killed`, `disabled`, `lanes_json_malformed`, ...). `effort_basis` is exactly one of `explicit`, `prompt_chars`, `audit_floor`, or `none`. Never the prompt text, never a provider-supplied value, never free text: a value the log does not recognise is written as `unknown`. The human-readable detail, which may quote the provider, goes to your terminal only (and nowhere with `--quiet`). "This lane is flaky" becomes a query instead of an argument, and so does "we route audits at high effort".
-
-The log records what was **requested**, on every record including a run refused before the lane started. It does not record an actual. Reporting is inconsistent: grok returns a `modelUsage` block naming a model, the other four lanes return nothing of the kind, so an `actual` field would be populated for one lane and empty for four. It would also be a provider-supplied string, and this log holds fixed codes and bounded caller-supplied values only. `model_source: "lane_default"` is the honest way to say this run inherited something invisible from here.
-
-## The prompt travels in argv
-
-That is each vendor's documented headless shape (`-p`, `exec`). Two consequences: argv is visible to other processes on the machine, so a prompt is never the place for a key; and argv is bounded by the OS (`ARG_MAX`), so a very large brief should be referenced by path inside the prompt rather than pasted whole.
+| agy | `--model` | `--effort` |
+| hermes | `-m` | `--reasoning` |
+| qwen | `-m` | Unsupported; an effort request is a usage error |
 
-## lanes.json refuses by default
+When using `--effort auto`, treat its medium/high selection as a bounded heuristic; an audit has a high floor. Use explicit high for builds and xhigh where supported for security-critical or irreversible work. The vendor validates its own effort names and reports unsupported values through the failure class.
 
-Absent: every lane enabled, nothing pinned. Present but malformed or unreadable: every lane refused (exit 13) until it is fixed. A half-written config never re-enables a lane the installer disabled. `defaults` is optional and held to the same standard: a malformed entry, an unknown lane, an unknown key, a value outside the charset, or an effort pinned on a lane that has no reasoning flag all make the whole file refuse by default rather than being skipped quietly.
+## Preserve permissions and secrets
 
-## A killed lane is not a deliverable
+The runner never adds permission flags. Keep each vendor's permissions in its own configuration and route work within the task's granted scope. A denied write becomes a handoff to an authorized writer.
 
-A lane that dies by signal has no honest exit status. Whatever it printed first is discarded; the run reports `killed`, class `cut_short`, exit 18.
+Prompts travel in argv, which other processes may inspect. Never put secrets in a prompt. For large task inputs, give the worker a brief with authorized source paths instead of exceeding the operating system's argument-size limit.
 
-## Interrupting cli-run kills the lane too
+Terminal status and error details are redacted before clipping. Local logs exclude prompt text and provider free text. `--quiet` also suppresses the human-readable details.
 
-Ctrl-C or a `kill` on the wrapper kills the lane's whole process group before the wrapper exits (130 for SIGINT, 143 for SIGTERM). A second signal during cleanup kills again and exits at once. Handlers are installed per run and removed when it finishes, so `--doctor --run` does not accumulate them. Uncatchable SIGKILL to the wrapper leaves the lane running; that is the operating system, not a promise this tool can make. Under systemd, `KillMode=control-group` covers that case.
+## Inspect the local log
 
-## Output is decoded as a UTF-8 stream
+Read `~/.ai-orchestrator/cli-run.log.jsonl` for one record per run: lane, verdict, class, return codes, signal, refusal count, timing, byte counts, prompt hash and length, requested model and effort, source of those requests, auto-effort evidence and a fixed reason code.
 
-Vendor output is decoded with a streaming decoder, so a multibyte character split across two chunks is preserved byte for byte. The 16 MiB cap and the `raw_bytes` field count bytes, not characters.
+Use `model_source: "lane_default"` to identify an inherited route. These fields record requested settings; verifying the vendor's actual model requires vendor evidence. Keep task success grounded in the acceptance checks.
 
-## Timeouts kill the whole process group
+## Configuration and process boundaries
 
-The lane is started detached, as the leader of its own process group. On timeout, or when output overruns the buffer, the group is killed, so a tool the agent shelled out to cannot keep writing after the wrapper reported 12. A child that calls `setsid()` itself escapes this boundary; nothing user-space can promise more without a cgroup, which is what the level 3 systemd unit adds.
+- When `lanes.json` is absent, all supported lanes are enabled with inherited defaults. When it is malformed or unreadable, the runner refuses every lane with exit 13 until corrected.
+- When a lane dies by signal, discard its partial response and handle `cut_short` exit 18.
+- On POSIX, timeout, output overrun and catchable interruption kill the lane's process group. A child that creates its own session can escape that boundary; use a service-level process boundary where needed.
+- On Windows, lanes use a direct executable or a resolved Node shim, never `cmd.exe`. Windows termination behavior differs from POSIX signal cleanup.
+- When the wrapper receives uncatchable SIGKILL, use a supervisor such as systemd with `KillMode=control-group` to clean up its process tree.
+- Vendor output uses streaming UTF-8 decoding and a 16 MiB cap counted in bytes.
 
-## Lane choice is not automated
+## Choose the lane
 
-`cli-run` runs the lane it is given. Which lane fits the job is `ROUTING.md` and `DELEGATION_MATRIX.md`, or a question to the human.
+When selecting a lane, apply `ROUTING.md` and `DELEGATION_MATRIX.md`, optionally starting with `aunx route "<task>"`. The runner executes the lane named by the caller. Its response checks work independently of optional companion software.

package/templates/intermediate/DELEGATION_MATRIX.md

@@ -1,7 +1,13 @@
-# DELEGATION_MATRIX.md: task → lane → pick
+# DELEGATION_MATRIX.md: choose a lane for the task
 
 Generated {{DATE}} from the AIs you said you have: `{{AI_IDS}}`.
 
+{{STACK_TABLE}}
+
+{{STACK_FALLBACK_NOTE}}
+
+{{STACK_GAPS}}
+
 ## Your lanes
 
 {{LANES_TABLE}}
@@ -10,7 +16,7 @@ Generated {{DATE}} from the AIs you said you have: `{{AI_IDS}}`.
 
 {{PLAN_GUIDANCE}}
 
-## Task → lane
+## Match the task to an available lane
 
 {{TASK_LANES_TABLE}}
 
@@ -24,4 +30,4 @@ Generated {{DATE}} from the AIs you said you have: `{{AI_IDS}}`.
 
 ## Privacy gate
 
-No private notes, client data, or personal records go to a metered third-party bulk lane or a fan-out lane. Name the barred lanes explicitly in your own rules; an unnamed bar is not enforced.
+Before dispatching protected data, check the project's named allowed and barred lanes. Never send private notes, client data or personal records to an unapproved third-party bulk or fan-out lane. When the required permission or tool is absent, keep the data local and return the needed decision.

package/templates/intermediate/README.md

@@ -5,9 +5,9 @@ Written at level 2 and above, on top of `common/` and `beginner/`.
 | File | What it adds |
 |---|---|
 | `ROUTING.md` | the multi-lane decision tree; supersedes `ORCHESTRATOR.md` when present |
-| `TIERS.md` | capability tiers, the three cost levers, the escalation rule, slotting rules |
+| `TIERS.md` | capability tiers, the three cost levers, job fit, model availability and effort selection |
 | `DELEGATION_MATRIX.md` | task → lane → pick, generated from the user's selection |
-| `RESEARCH_TRIAGE.md` | three engines in parallel, one triager |
-| `CLI-RUN.md` | how `bin/cli-run.mjs` judges each lane |
+| `RESEARCH_TRIAGE.md` | selected engines in parallel, one source-checking writer |
+| `CLI-RUN.md` | how `aunx cli-run` and `bin/cli-run.mjs` verify each response |
 
 `bin/cli-run.mjs` and `bin/lanes.json` are written by the installer from `bin/cli-run.mjs` in this repo and the user's selection; they are not templates.

package/templates/intermediate/RESEARCH_TRIAGE.md

@@ -1,30 +1,38 @@
-# RESEARCH_TRIAGE.md: engines in parallel, one triager
+# RESEARCH_TRIAGE.md: parallel research with source verification
 
-{{RESEARCH_SELECTION_ADVICE}} Then triage against primary sources you open yourself.
+When a question needs outside evidence, {{RESEARCH_SELECTION_ADVICE}} Then open the primary sources that support decisions.
 
-Your `cli-run` lanes: {{CLI_RUN_LANES}} ({{RESEARCH_ENGINES}} research engine(s) below). Everything in this file was rendered from that selection; a lane that is not listed is not one you have.
+Use the selected `cli-run` lanes: {{CLI_RUN_LANES}} ({{RESEARCH_ENGINES}} research engine(s) below). When a needed lane is absent, use an available authorized research tool and name the resulting coverage limit.
 
-## Roles
+## Assign the research roles
 
 | Role | Typical lane | Job |
 |---|---|---|
-{{RESEARCH_ROLES}} opens primary sources, marks every claim, writes the artifact |
+{{RESEARCH_ROLES}}
 
-Run each engine as one `cli-run` call with a task bundle in `--brief`. A run that produced nothing exits 10 and is a missing engine, not an empty finding.
+Give each engine a task brief through `--brief`, with the same context file, bounded questions, source standard and stopping condition. When a run returns no usable result, record that engine as unavailable and continue independent source checks.
 
-## One run
+## Run the selected engines
 
 ```bash
-BRIEF=research/brief.md      # purpose, sub-questions, source standard, report contract, exit parameters
+BRIEF=research/brief.md
 {{RESEARCH_RUN}}
 ```
 
-Then the orchestrator reads the available outputs, opens every primary source that carries a decision, and writes one dated brief with marks: **CONFIRMED** (two engines + primary source) · **DISAGREEMENT** (both readings kept) · **REPORTED** (someone's own post, quoted not trusted) · **UNVERIFIED**.
+When using the installed script directly, `aunx cli-run` accepts the same runner arguments as `node bin/cli-run.mjs`.
 
-## Triage discipline
+When outputs arrive, have one writer inspect the primary sources carrying each decision and produce a dated synthesis:
 
-- Plant one deliberately wrong figure in one brief. An engine that does not correct it has confirmations worth less than they look.
-- Expect one engine to return confident unsourced numerics and claim full coverage. Downgrade to hypothesis. Weight the engines that report their own gaps.
-- Agreement is weak evidence. Disagreement is the signal.
-- Only the orchestrator writes the durable record. Every other engine proposes.
-- Count dispositions, not briefs.
+- **CONFIRMED:** verified against the primary source, with independent corroboration where the question needs it.
+- **DISAGREEMENT:** preserve conflicting readings and identify the evidence that would resolve them.
+- **REPORTED:** attribute a source's statement to that source.
+- **UNVERIFIED:** name the missing evidence or access.
+
+## Verify claims and coverage
+
+- When engines agree, verify the shared premise against source.
+- When engines disagree, preserve both claims until evidence resolves them.
+- When a report gives a number, open its source or recompute it with an available tool.
+- When testing a research method, use a labelled false-premise fixture and confirm the method rejects it before relying on it.
+- When recording results, use one writer and return claim dispositions with citations.
+- When Context7 or another companion is absent, use official documentation, source and the project's own runtime checks.

package/templates/intermediate/ROUTING.md

@@ -1,8 +1,16 @@
-# ROUTING.md: the multi-lane decision tree
+# ROUTING.md: model router for your available tools
 
-Primary agent (the orchestrator): **{{PRIMARY_NAME}}**. It routes, maps, builds, verifies and records. Every other AI is a lane it calls.
+Main agent: **{{PRIMARY_NAME}}**. A **lane** is an AI tool or model the main agent can hand work to. A **tier** describes a model's capability and cost: planning model, working model or cheap model.
 
-Your lanes:
+When a task arrives, choose its route from the live tools and these rules. `aunx route "<task>"` prints a deterministic keyword suggestion; verify that suggestion against the task's scope, required tools and stakes before dispatching.
+
+{{STACK_TABLE}}
+
+{{STACK_FALLBACK_NOTE}}
+
+{{STACK_GAPS}}
+
+## Your lanes
 
 {{LANES_TABLE}}
 
@@ -10,76 +18,71 @@ Your lanes:
 
 {{PLAN_GUIDANCE}}
 
-Two kinds of lane. **Lane A** = subscription CLIs: $0 marginal, already paid for, used for interactive and agentic work. **Lane B** = metered APIs: per token, used for programmatic bulk where a subscription CLI cannot serve. **Local** = stays on the machine; a privacy lane, never a cost lane.
+When choosing a billing route, distinguish **subscription lanes** (usage covered by a subscription, subject to its limits) from **pay-per-token lanes** (metered API usage). When data must stay on the machine, choose a verified **local lane** and check its network behavior.
 
-Rule of thumb: never spend a frontier token on a task a cheap tier finishes correctly. Escalate on signal (low confidence, explicit complexity, a failed verification), not by default. And an external lane must earn the hop with a real strength; when in doubt, stay in-house.
+When a cheaper eligible route can complete and verify the task, select it. When verification fails, complexity emerges or tool reach is insufficient, escalate with a named reason.
 
 ## Decision tree (first match wins)
 
-0. **Is there a cheaper or better external lane for this?** Check `DELEGATION_MATRIX.md`. Your enabled lanes, every one called through `bin/cli-run.mjs`:
+0. **An external lane offers useful reach or capacity:** check `DELEGATION_MATRIX.md` and call the selected CLI through `aunx cli-run` or the installed `bin/cli-run.mjs`.
 {{LANE_STEP0}}
-1. **Bulk and mechanical?** → fast tier{{BULK_LANE}}.{{FAN_OUT_ADVICE}}
-1a. **Reading or digesting many files or notes, not writing?** → reader. Different from a bulk pass: reader reports, it does not classify, tag or transform.
-2. **Needs live data?** → {{LIVE_LANE}} standard tier with web tools.
-3. **Reviewing without changing?** → standard tier read-only. Security-critical → {{ATTACK_LANE}}.
-3a. **Holding findings from a review or a scanner?** → finding-verifier before any of them cause a repair. A finding is a claim, not a fact.
-3b. **Checking a tracker item or task against its stated done-signal?** → done-verifier. It probes the named artifact and returns MET, NOT_MET or UNVERIFIABLE; it never closes anything itself.
-4. **Ambiguous, strategic, expensive to get wrong?** → deep tier (deep-planner). Then hand the plan down.
+1. **Bulk or mechanical work:** classify, tag, extract, rename or reformat -> cheap model tier / {{BULK_ROLE}}{{BULK_LANE}}.{{FAN_OUT_ADVICE}}
+1a. **Read or digest many files:** -> {{READER_ROLE}}; return facts, quotes or an index within the brief's scope.
+2. **Current data is required:** -> {{LIVE_LANE}} working model tier with live tools.
+3. **Review code without changing it:** -> {{REVIEW_ROLE}}, working model tier. For security-critical scope -> {{ATTACK_LANE}} with appropriate effort.
+3a. **A reviewer or scanner has returned findings:** -> {{FINDING_ROLE}}; reproduce each claim before repair.
+3b. **Check a task's definition of done:** -> {{DONE_ROLE}}; probe the named artifact and return MET, NOT_MET or UNVERIFIABLE.
+4. **Ambiguity, architecture or an unknown cause:** -> planning model tier / {{PLANNER_ROLE}}. Return a concrete plan for execution.
 {{DECISION_RULE5}}
 
 {{WHO_BUILDS}}
 
-## The Build Protocol, with lanes bound
+## Build process and ownership
 
-| Stage | Binding |
-|---|---|
-| 0 Route | live probe for access; `cli-run` lanes are $0 and uncapped |
-| 1 Map | the orchestrator sweeps{{STAGE1_LANES}} |
-| 2 Judge | deep tier, on the finished map: one named weak spot and one gap in the request |
-| 3 Build | the orchestrator, against the installed dependency's source |
-| 4 Scan | secret + static + dependency scanners, diff-scoped, refuses by default |
-| 5 Challenge | security-shaped diff → {{ATTACK_LANE}}. Architecture-shaped → deep tier, build against plan. Never both |
-| 5a Verify findings | finding-verifier, a different model family where you have one: CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE per finding. Only CONFIRMED earns a repair |
-| 5b Ship | rollback id recorded, explicit human yes |
-| 6 Verify | real test, negative test seen red, old identifier re-grepped to zero |
-| 7 Record | one end-to-end doc, tracker Done with evidence, plan doc deleted |
+When a task builds or changes a system, run `protocols/build-protocol.md`.
 
-Caps: two deep-tier checkpoints per build. CLI lanes are $0 and do not count.
-
-## Numbers and logic
-
-Every number, comparison, complexity or equivalence claim goes through a tool that computes (`protocols/numbers-and-logic.md`; companion: codecalc, {{CODECALC_STATUS}}).{{METERED_CITATION_NOTE}}
-
-## Memory and record
+| Step | Action |
+|---|---|
+| Frame and probe | Quote the ask, freeze acceptance checks and verify required availability |
+| Ordering | Dependencies first, invalidators early, deterministic checks before judgment, irreversible actions last |
+| Research | Vet sources, inspect current interfaces and spike risky assumptions |
+| Context file | Map affected surfaces once; every brief reads the same context file |
+| Assign | Choose each section's lane, model and effort by live capability and job fit |
+| Build | Execute the approved scope; hand refused writes to an authorized writer |
+| Split and merge | Keep the whole scope in each brief; merge sections and name conflicts |
+| Audit | One pass on the merged artifact plus a companion consult asking scope versus ask |
+| Ship | Record rollback, confirm authorization, replay checks and verify the change in use |
+| Record | Return coverage and evidence, update documentation and name what watches it |
 
-One writer per run; every other lane proposes. Search before writing, index in the same pass (`protocols/memory-and-record.md`; companion, optional: obsidian-tc, {{OBSIDIAN_TC_STATUS}}).
+When work runs in the background, check liveness and output growth every five minutes. Two checks without growth call for diagnosis and a report. When an audit finding is confirmed, assign its fix to a non-author and show the regression failing before the fix. Verify the fix; no second audit pass.
 
-## Docs, then prove
+## Tools and fallbacks
 
-A lane's recall of a library's API is a lead, not a verdict, the same as its arithmetic. Pull current, version-specific docs before writing a call against anything you have not confirmed this session (`protocols/docs-then-prove.md`; companion, optional: Context7, {{CONTEXT7_STATUS}}). Then prove the doc was right by running it, the same tool that already owns numbers: codecalc, {{CODECALC_STATUS}}. Where the two disagree, the run wins.
+- When reporting consequential arithmetic or code equivalence, use a computing tool (`protocols/numbers-and-logic.md`). codecalc: {{CODECALC_STATUS}}. When absent, use the local runtime, test suite or spreadsheet.{{METERED_CITATION_NOTE}}
+- When writing durable records, search first, update the index and keep one writer (`protocols/memory-and-record.md`). obsidian-tc: {{OBSIDIAN_TC_STATUS}}. When absent, use project files, search and version control.
+- When using a changing library or API, read current documentation and verify behavior (`protocols/docs-then-prove.md`). Context7: {{CONTEXT7_STATUS}}. When absent, read official docs or installed source; use the local runtime when codecalc is absent.
 
-## Modifier rules
+## Choose effort and verify the route
 
 {{PLAN_BIG_LINE}}{{INLINE_THRESHOLD_NOTE}}
-- **Escalation:** never silently retry at the same tier. Escalate one tier or consult deep once, and say which. Two consults that do not unstick it → stop and tell the human.
-- **De-escalation:** a request that sounds deep but is a lookup routes down.
-- **Long context:** mechanical digestion → fast tier in chunks; judgment over a long input → standard tier.
-- **Token discipline on every delegation:** pass only the context the delegate needs, never the conversation.
-- **Effort per agent:** deep xhigh, review, verification and build high, live research medium, bulk low.
-- **Three inputs, not one:** role picks the agent, complexity moves the effort, stakes move the tier and who reads it. A one-line auth change is simple and high-stakes at once, and the stakes decide. See `TIERS.md`.
-- **Pin the route when it matters:** a lane with no `--model`/`--effort` and no `defaults` entry in `bin/lanes.json` runs on its own config, which may be nothing like what this file describes. `cli-run --doctor` prints what each lane is pinned to, and every run logs the value requested and where it came from.
+- When a lookup is sufficient, use the cheap model tier; when the task needs judgment, choose the working or planning model tier by evidence.
+- When an attempt fails, identify the failure class before retrying; change the route or resolve the cause explicitly.
+- When delegating, pass the context file and task brief with scoped source references and acceptance checks.
+- When role, complexity or stakes change, reassess model, effort and reviewer together. See `TIERS.md`.
+- Before each build, inspect the lane's live roster and any configured pin. Flag stale pins and record the model and effort selected for this task.
+- When the route matters, set `--model` and `--effort` or verify `bin/lanes.json` defaults. Run `aunx cli-run --doctor` to inspect requested defaults; an unpinned lane uses its own configuration.
 
 ## Example routings
 
 | Task | Route |
 |---|---|
-| "Design the architecture for X" | deep-planner |
-| "Review this service for bugs" | code-reviewer |
+| Design the architecture for a service | {{PLANNER_ROLE}}, planning model tier |
+| Review this service for bugs | {{REVIEW_ROLE}}, working model tier |
 {{ADD_ENDPOINT_ROW}}
-| "Why does this silently drop rows sometimes" | deep-planner (unknown cause), then build the fix directly |
-| "Summarize these 30 notes into one index" | bulk-worker |
-| "Read every note in this folder and pull out every mention of X" | reader |
-| "The audit returned 6 findings" | finding-verifier first; repair only what comes back CONFIRMED |
-| "Is issue #123 actually done" | done-verifier |
+| Find why this silently drops rows | {{PLANNER_ROLE}}, then a scoped build |
+| Summarize similar notes into one index | {{BULK_ROLE}}, cheap model tier |
+| Read every file and extract mentions of a topic | {{READER_ROLE}}, cheap model tier |
+| Verify the audit's findings | {{FINDING_ROLE}} before repairs |
+| Check whether the stated definition of done holds | {{DONE_ROLE}} |
 {{LANE_EXAMPLES}}
 {{ROUTE_GATE_SECTION}}