model-orchestrator 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [0.1.14] - 2026-09-09
+
+Three refinements to the routing model, from a review by [@shawnwows](https://x.com/shawnwows). The theme is the same in all three: a routing decision that was implied, inherited or asserted is now stated, pinned or checked.
+
+### Added
+
+- **`--model` and `--effort` on every lane, and a route recorded per run.** A lane with no flag and no `defaults` entry in `bin/lanes.json` runs on its own config file, which `cli-run` cannot see: a CLI configured months ago at a low reasoning effort keeps auditing at that effort while the routing docs describe an adversarial pass, and nothing raises an error. Each vendor spells the flags differently and `cli-run` translates (`grok -m/--reasoning-effort`, `codex -m/-c model_reasoning_effort="X"`, `agy --model/--effort`, `hermes -m/--reasoning`, `qwen -m` and no reasoning flag), each one read from that CLI's own `--help`. Flags beat `defaults`, `defaults` beats nothing, `--doctor` prints what each lane is pinned to, and the log carries `model_requested`, `effort_requested`, `model_source` and `effort_source` on every record, including runs refused before the lane started. It records no "actual": one lane of five (grok) reports a model id in its own output and the other four report none, so the field would be populated for one lane and empty for four, and it would be a provider-supplied string, which the durable log never holds. `--effort` on qwen is a usage error rather than a silent drop, and route values are charset-bounded because a model id becomes an argv element and, on codex, part of a TOML value.
+- **`finding-verifier`, a sixth subagent, in both agent formats.** Review and scanner findings no longer go straight to a repair. It reads the cited line, states what would trigger the problem, hunts for the guard, caller or test that makes it impossible, and returns CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE per finding. Only CONFIRMED earns a change; INCONCLUSIVE is never rounded up to be safe or down to be tidy. Bound into the build protocol as Stage 5a, into `ROUTING.md`, and into the Claude Code activation snippet. The reproduction rule already existed in Stage 5; it had no owner, no separate model family and no way to say "I could not settle this".
+- **Complexity and risk as inputs, alongside role** (`TIERS.md`). Complexity moves the effort: a worker executing a finished plan needs less reasoning than the reviewer judging its output. Risk (security, privacy, data loss, irreversible) moves the tier and who reads the result, because none of those failures is fixable by editing the code afterwards. A one-line change to an auth check is simple and high-risk at once, and the risk decides. Deliberately two rules and two small tables rather than a role by complexity by risk matrix: an 80-cell table is not maintained, and an unmaintained routing table is worse than none because it is believed.
+
+### Changed
+
+- `--model` is no longer qwen-only. `--safe-mode` still is.
+- The route is resolved before the "lane disabled" and "binary missing" refusals, so those records carry it too. Found by the pre-release audit: a run refused for a missing binary is still a run that requested a route, and a failure record without one is the gap this release exists to close.
+- `bin/lanes.json` gains an optional `defaults` block. It fails closed with the rest of the file: an unknown lane, an unknown key, a value outside the charset, or an effort pinned on a lane with no reasoning flag refuses every lane until it is fixed, rather than being skipped quietly.
+- The generated activation list gains a step about pinning the route, and `--doctor` output gains a route column with a plain sentence about what "not pinned" means.
+
+## [0.1.13] - 2026-09-08
+
+Three issues from a fresh first-run walkthrough of 0.1.12 (#26, #27, #28). Same class as 0.1.12's five: a surface describing an install that did not happen. A fourth, #25, was filed and closed as a mistake on the reporter's side, not a defect: the warning it said was missing has been printed since 0.1.12 and the repro had been read through a truncated pipe.
+
+### Fixed
+
+- **The "Then prove it took" list no longer sends a level 1 reader to a file level 1 never wrote** (#27). Step 4 told every reader, at every level, to pick a lane out of `bin/lanes.json` and run `node bin/cli-run.mjs`. Level 1 writes no `bin/` at all, and step 3 immediately above it hedged correctly with "At level 2+" while step 4 did not. The list is now `proofSteps()` in `src/install.js`, gated on level the same way `activationSteps()` is, and the template renders it. Two tests: the README's section must equal the array exactly for every level and primary, and no `bin/` path may appear in it that the plan did not write.
+- **The box setup no longer tells you to sign in to CLIs you did not pick** (#26). `templates/advanced/vm/README.md` step 3 was a fixed sentence naming `codex login --device-auth`, `grok login --device-auth` and `agy`. A level 3 install of claude-code, codex, qwen and ollama was told to sign in to two CLIs it does not have and never told about the one it does. The step now renders each selected CLI's own `auth` string from the catalog. Everything else in that file was already computed from the selection, which is what made the one hardcoded line easy to miss.
+- **A selected local runtime is finally told to install itself** (#26). `activationSteps()` filtered on `kind === 'agent-cli'`, so Ollama, which has a binary and a download page, appeared in no ordered list at any level. Its only mention was one row of a URL table in `DELEGATION_MATRIX.md`. It now gets a step naming the download page and the `ollama pull <model>` that has to follow it.
+- **The tool block stopped saying the same word twice** (#28). Every run that selected a tool printed `optional: Optional. Needs Python 3.10+ and uv.`, because the label repeated the note's own first word. The label is `note:` now. The note keeps the word, because `--list` and the interactive picker print it bare with no label.
+
+### Changed
+
+- `--primary` is documented as what it is. `--help` called it "required when several qualify", and then a `--yes` run with several candidates silently picked one in catalog order. The run now names the choice in the plan (`primary  claude-code (chosen for you from claude-code, codex; pass --primary to decide it yourself)`) and the help says the same thing. Behaviour is unchanged: the default was sensible, only the promise was wrong.
+
 ## [0.1.12] - 2026-09-08
 
 Five issues from one first-run walkthrough of 0.1.11 (#20 to #24). Every one of them is the same failure: a page describing an install that did not happen. Each fix removes the second copy of a fact rather than correcting it.
@@ -185,7 +217,9 @@ First release.
 - Tests: a case per fix, judges proven to go red, mutation checks; `npm test` prints the current count.
 - Adversarial audit: two Codex rounds plus a two-engine review (Codex, Antigravity); findings and fixes in `docs/audit-brief.md`. After the review: subagents go to the project root (`--project`), snippet paths computed from `--dir`, lane sections rendered from the selection, a primary agent required, level 3 asks for API keys separately from CLIs, images and CLI installs pinned, an activation summary at the end of every install.
 
-[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.12...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.14...HEAD
+[0.1.14]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.13...v0.1.14
+[0.1.13]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.12...v0.1.13
 [0.1.12]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.11...v0.1.12
 [0.1.11]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.10...v0.1.11
 [0.1.10]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.9...v0.1.10

package/README.md

@@ -25,7 +25,7 @@ It never writes a secret, never runs a vendor shell script for you, and never ov
 | Level | You have | You get |
 |---|---|---|
 | **1 · Beginner** | one LLM or one agent | tiers, task classification, the two build checkpoints, the protocols (build, propagate, gap analysis, deep research, numbers and logic, memory and record), a task-bundle template, and your agent set up to follow them |
-| **2 · Intermediate** | several AIs with CLIs | everything above, plus `cli-run` (exit 0 means a structurally accepted non-empty response; opt-in `--expect-file` / `--expect-json` for real contracts), a delegation matrix generated from your selection, research triage across the lanes you have |
+| **2 · Intermediate** | several AIs with CLIs | everything above, plus `cli-run` (exit 0 means a structurally accepted non-empty response; opt-in `--expect-file` / `--expect-json` for real contracts; `--model` / `--effort` to pin the route and log it), a delegation matrix generated from your selection, research triage across the lanes you have |
 | **3 · Advanced** | a virtual machine | everything above, plus a gateway config rendered from the API keys you hold (asked separately from your CLIs), pinned images, box rules, privacy gates, and a weekly gap-analysis job with "what watches it" written down |
 
 Read the thinking behind each level in [docs/](docs/README.md): [Part 1](docs/part-1-beginner.md) · [Part 2](docs/part-2-intermediate.md) · [Part 3](docs/part-3-advanced.md).
@@ -90,7 +90,7 @@ ai-orchestrator/
   TASK_BUNDLE.md            the brief every delegation carries
   protocols/                build-protocol · propagate · gap-analysis · deep-research · numbers-and-logic · memory-and-record
   CODECALC.md  OBSIDIAN-TC.md  mcp/   companion-tool install docs + per-agent registration snippets (if selected)
-  <project>/.claude/agents/ five subagents, one per tier, at the PROJECT root (if Claude Code is primary)
+  <project>/.claude/agents/ six subagents, one per tier plus finding-verifier, at the PROJECT root (if Claude Code is primary)
   CLAUDE.snippet.md         the block to paste into your CLAUDE.md
   ROUTING.md                multi-lane decision tree (level 2+)
   TIERS.md  DELEGATION_MATRIX.md  RESEARCH_TRIAGE.md  CLI-RUN.md
@@ -162,6 +162,54 @@ It deliberately does not run in this repository's CI. A canary is only meaningfu
 6. **The orchestrator owns the main build.** Delegates hold none of your rules; they get bounded sub-parts and a brief.
 7. **Only one process holds keys.** Names in the environment, values in a secrets manager, never in a file here.
 
+## Routing by role, complexity and risk
+
+Role picks the agent. Two more inputs move the choice, and they move it in
+different directions, so `TIERS.md` states them separately rather than folding
+them into the role:
+
+- **Complexity moves the effort.** A worker executing a finished plan needs less
+  reasoning than the reviewer judging its output. When the plan is airtight the
+  spec is carrying the thinking.
+- **Risk moves the tier and the reader.** Security, privacy, data loss and
+  irreversible changes buy the attack lane, a named check, a rollback path or a
+  human yes. A one-line change to an auth check is simple and high-risk at the
+  same time, and it is the risk that decides.
+
+The top of the ladder is bought with evidence: a reproduced failure, an
+unresolved checkpoint, an irreversible change. A task that merely feels hard is
+a deep-tier task, not an escalation.
+
+## A finding is a claim, not a fact
+
+Review findings do not go straight to a repair. `finding-verifier` reads the
+cited line, states what would trigger the problem, then hunts for the guard,
+caller or test that makes it impossible, and returns **CONFIRMED**,
+**NOT_REPRODUCED** or **INCONCLUSIVE** per finding. Only CONFIRMED earns a
+change. Use a different model family from the one that produced the finding
+where you have one: a family asked to check its own claim tends to agree with
+itself.
+
+## Pin the route, or know that you did not
+
+A lane with no `--model`, no `--effort` and no `defaults` entry in
+`bin/lanes.json` runs on **its own config file**, which `cli-run` cannot see. A
+CLI configured months ago at a low reasoning effort keeps auditing at that
+effort while your routing docs describe an adversarial pass.
+
+```bash
+node bin/cli-run.mjs codex "<prompt>" --model gpt-6-astra --effort high
+node bin/cli-run.mjs --doctor     # prints what each lane is pinned to, and what is not pinned
+```
+
+Every run logs the model and effort **requested** and where the request came
+from: `flag`, `lanes.json`, or `lane_default`, on every record including the
+runs that never reached a lane. It does not log an actual. One lane of five
+(grok) reports a model id in its own output and the other four report none, so
+an actual field would be present for one lane and missing for four, and it
+would be a provider-supplied string, which the durable log deliberately never
+holds.
+
 ## Requirements
 
 Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu. Windows is untested: `cli-run` ends a lane's process tree there with `taskkill`, but nothing in CI runs on Windows, so treat it as unsupported until someone reports otherwise.
@@ -177,6 +225,14 @@ Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box tem
 
 Add an AI to `src/catalog.js` and every prompt, table, config and doc picks it up. Run `npm test`. Keep templates free of logic and free of anything that looks like a credential. The rest is in [CONTRIBUTING.md](CONTRIBUTING.md); releases in [RELEASING.md](RELEASING.md); security reports in [SECURITY.md](SECURITY.md).
 
+## Credits
+
+- [@shawnwows](https://x.com/shawnwows) reviewed the router and made the case for
+  separating role, complexity and risk instead of compressing them into one
+  scale, for recording the model and effort a lane was actually asked for, and
+  for verifying findings before they trigger repairs. All three shipped in
+  0.1.14.
+
 ## License
 
 [MIT](LICENSE)

package/bin/cli-run.mjs

@@ -39,6 +39,17 @@
 //
 // The durable log stores a FIXED reason code per run (see REASONS), never a
 // provider-supplied string. Bounded vendor stderr goes to your terminal only.
+//
+// ROUTE: which model and reasoning effort a lane ran with.
+// A lane with no --model and no lanes.json default inherits whatever its own
+// config file says, which is invisible from here and is how a documented route
+// silently stops being the route that runs. --model / --effort pin it per call,
+// `defaults` in lanes.json pins it per lane, and every run logs the value that
+// was REQUESTED plus where the request came from (flag, lanes.json, or nothing
+// at all). It does not log an "actual". One lane of five (grok) does report a
+// model id in its own output; the other four report none, and a field present
+// for one lane and absent for four is worse than no field. It would also be a
+// provider-supplied string, which this log deliberately never holds.
 
 import { spawn } from 'node:child_process';
 import { StringDecoder } from 'node:string_decoder';
@@ -190,28 +201,71 @@ export function judgeQwen(rc, out) {
   return pass(text, `subtype=success, totalErrors=0 across ${Object.keys(models).length} model(s)`);
 }
 
+// --- route: model and effort per lane --------------------------------------
+// Each vendor spells these differently, and the spelling was read from each
+// CLI's own --help, not remembered. A lane with `effort: null` has no reasoning
+// flag at all; asking for one there is a usage error, never a silent drop.
+//   grok    -m MODEL   --reasoning-effort EFFORT
+//   codex   -m MODEL   -c model_reasoning_effort="EFFORT"   (a TOML override, hence the quotes)
+//   agy     --model M  --effort EFFORT                      (low|medium|high)
+//   hermes  -m MODEL   --reasoning LEVEL                    (none|minimal|...)
+//   qwen    -m MODEL   no reasoning flag
+export const LANE_FLAGS = {
+  grok: { model: (v) => ['-m', v], effort: (v) => ['--reasoning-effort', v] },
+  codex: { model: (v) => ['-m', v], effort: (v) => ['-c', `model_reasoning_effort="${v}"`] },
+  agy: { model: (v) => ['--model', v], effort: (v) => ['--effort', v] },
+  hermes: { model: (v) => ['-m', v], effort: (v) => ['--reasoning', v] },
+  qwen: { model: (v) => ['-m', v], effort: null }
+};
+
+// A model id or effort level becomes an argv element and, for codex, part of a
+// TOML value. Bounding the charset is what makes both safe: no leading dash (a
+// value cannot become a flag), no quote, space or control character (a value
+// cannot break out of the TOML string), and a length cap so a config file
+// cannot push an unbounded string into the durable log.
+export const ROUTE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,63}$/;
+export function badRouteValue(kind, v) {
+  if (typeof v !== 'string' || !ROUTE_VALUE.test(v)) {
+    return `--${kind} must be 1 to 64 characters of letters, digits, dot, underscore, colon, at, slash, plus or dash, and may not start with a dash: ${JSON.stringify(v)}`;
+  }
+  return null;
+}
+
 // --- adapters: build argv for a lane -------------------------------------
+// Route flags go in front of the prompt for every lane, because two lanes
+// (hermes, codex) take the prompt as a positional argument and a flag after it
+// is either ignored or read as part of it.
+function routeFlags(lane, opts) {
+  const spec = LANE_FLAGS[lane];
+  const out = [];
+  if (!spec) return out;
+  if (opts.model) out.push(...spec.model(opts.model));
+  if (opts.effort && spec.effort) out.push(...spec.effort(opts.effort));
+  return out;
+}
+
 export function buildArgv(lane, binary, prompt, opts, tmp) {
   const timeout = opts.timeout;
+  const route = routeFlags(lane, opts);
   switch (lane) {
     case 'grok':
-      return { argv: [binary, '--output-format', 'json', '-p', prompt] };
+      return { argv: [binary, '--output-format', 'json', ...route, '-p', prompt] };
     case 'codex': {
       const last = join(tmp, 'last.txt');
       const argv = [binary, 'exec', '--json', '--color', 'never', '--skip-git-repo-check', '-o', last];
       if (opts.audit) argv.push('--sandbox', 'read-only'); // an audit lane that can write is a bug
+      argv.push(...route);
       argv.push(prompt);
       return { argv, outFile: last };
     }
     case 'agy': {
       const mins = Math.max(1, Math.round(timeout / 60));
-      return { argv: [binary, '--print-timeout', `${mins}m`, '--output-format', 'stream-json', '-p', prompt] };
+      return { argv: [binary, '--print-timeout', `${mins}m`, '--output-format', 'stream-json', ...route, '-p', prompt] };
     }
     case 'hermes':
-      return { argv: [binary, '-z', prompt, '--usage-file', join(tmp, 'usage.json')] };
+      return { argv: [binary, '-z', ...route, prompt, '--usage-file', join(tmp, 'usage.json')] };
     case 'qwen': {
-      const argv = [binary, '-o', 'json'];
-      if (opts.model) argv.push('-m', opts.model);
+      const argv = [binary, '-o', 'json', ...route];
       if (opts.safeMode) argv.push('--safe-mode');
       argv.push('-p', prompt);
       return { argv };
@@ -370,26 +424,67 @@ function log(rec) {
 // documented default). PRESENT BUT UNREADABLE OR MALFORMED = no lane enabled:
 // a half-written config must fail closed, never re-enable what the installer
 // disabled. Returns null when the file is bad so the caller can say so.
-export function enabledLanes(here = dirname(fileURLToPath(import.meta.url))) {
+export function laneConfig(here = dirname(fileURLToPath(import.meta.url))) {
   const p = join(here, 'lanes.json');
-  if (!existsSync(p)) return LANES;
+  if (!existsSync(p)) return { enabled: LANES, defaults: {} };
   try {
     const j = JSON.parse(readFileSync(p, 'utf8'));
     if (!j || typeof j !== 'object' || !Array.isArray(j.enabled)) return null;
     if (!j.enabled.every((l) => typeof l === 'string' && LANES.includes(l))) return null;
-    return j.enabled;
+    // `defaults` pins a model and effort per lane. It is optional; present and
+    // malformed fails closed with the rest of the file, because a half-written
+    // route is exactly the silent-inheritance problem this field exists to fix.
+    const defaults = {};
+    if (j.defaults !== undefined) {
+      if (!j.defaults || typeof j.defaults !== 'object' || Array.isArray(j.defaults)) return null;
+      for (const [lane, d] of Object.entries(j.defaults)) {
+        if (!LANES.includes(lane)) return null;
+        if (!d || typeof d !== 'object' || Array.isArray(d)) return null;
+        const { model, effort, ...rest } = d;
+        if (Object.keys(rest).length) return null;
+        if (model !== undefined && badRouteValue('model', model)) return null;
+        if (effort !== undefined) {
+          if (badRouteValue('effort', effort)) return null;
+          if (!LANE_FLAGS[lane] || !LANE_FLAGS[lane].effort) return null; // a lane with no reasoning flag cannot have one pinned
+        }
+        defaults[lane] = { model: model ?? null, effort: effort ?? null };
+      }
+    }
+    return { enabled: j.enabled, defaults };
   } catch {
     return null;
   }
 }
 
+// Kept as the narrow question most callers ask. null still means malformed.
+export function enabledLanes(here = dirname(fileURLToPath(import.meta.url))) {
+  const c = laneConfig(here);
+  return c === null ? null : c.enabled;
+}
+
+// Flag beats lanes.json beats nothing. `source` is what makes the log audit-worthy:
+// 'lane_default' means this run inherited the vendor CLI's own config, unseen from here.
+export function resolveRoute(lane, opts, defaults) {
+  const d = (defaults && defaults[lane]) || {};
+  const model = opts.model ?? d.model ?? null;
+  const effort = opts.effort ?? d.effort ?? null;
+  const src = (flag, def) => (flag != null ? 'flag' : def != null ? 'lanes.json' : 'lane_default');
+  return { model, effort, model_source: src(opts.model, d.model), effort_source: src(opts.effort, d.effort) };
+}
+
 function usage(msg) {
   if (msg) console.error('cli-run: ' + msg);
   console.error(`usage: cli-run <${LANES.join('|')}> "<prompt>" [--brief FILE] [--timeout SECS] [--quiet]
-                [--expect-file PATH] [--expect-json]
+                [--model ID] [--effort LEVEL] [--expect-file PATH] [--expect-json]
        cli-run codex --audit "<prompt>"          read-only sandbox (audit shape)
-       cli-run qwen [--model ID] [--safe-mode] "<prompt>"
-       cli-run --doctor [--run]                  enabled lanes, binaries on PATH; --run sends each a tiny prompt`);
+       cli-run qwen [--safe-mode] "<prompt>"     qwen-only flag
+       cli-run --doctor [--run]                  enabled lanes, binaries, and the route each one is pinned to
+
+  --model / --effort pin what a lane runs with, instead of letting it inherit its
+  own config. Every lane takes --model; every lane except qwen takes --effort.
+  Levels are the vendor's own (agy low|medium|high, hermes none|minimal|...): an
+  unknown level is rejected by the lane, and reported as that lane's exit code.
+  Pin them per lane instead of per call with "defaults" in bin/lanes.json.`);
   return USAGE;
 }
 
@@ -416,11 +511,12 @@ function installedPrimary(here = dirname(fileURLToPath(import.meta.url))) {
 
 // --doctor: the first thing to run after install.
 export async function doctor(run) {
-  const enabled = enabledLanes();
-  if (enabled === null) {
+  const cfg = laneConfig();
+  if (cfg === null) {
     console.error('doctor: lanes.json exists but is malformed; fix it first');
     return USAGE;
   }
+  const { enabled, defaults } = cfg;
   let bad = 0;
   console.log(`doctor: ${enabled.length} enabled lane(s): ${enabled.join(', ') || 'none'}`);
   const primary = installedPrimary();
@@ -432,7 +528,11 @@ export async function doctor(run) {
   for (const lane of LANES) {
     const on = enabled.includes(lane);
     const bin = which(lane);
-    let line = `  ${lane.padEnd(7)} ${on ? 'enabled ' : 'disabled'} ${bin ? 'binary ok' : 'binary MISSING'}`;
+    const d = defaults[lane] || {};
+    // A disabled lane has no route worth reporting; saying "not pinned" there
+    // reads as a finding about a lane that is not going to run.
+    const route = !on ? '' : d.model || d.effort ? `route ${d.model || 'lane default'}/${d.effort || 'lane default'}` : 'route not pinned (inherits the lane\'s own config)';
+    let line = `  ${lane.padEnd(7)} ${on ? 'enabled ' : 'disabled'} ${bin ? 'binary ok' : 'binary MISSING'}${route ? '  ' + route : ''}`;
     if (on && !bin) bad++;
     if (on && bin && run) {
       const rc = await main([lane, 'Reply with exactly the word OK and nothing else.', '--timeout', '120', '--quiet']);
@@ -443,6 +543,7 @@ export async function doctor(run) {
   }
   console.log(bad ? `doctor: ${bad} problem(s)` : 'doctor: all enabled lanes ' + (run ? 'answered' : 'present'));
   console.log('doctor checks presence and, with --run, a one-word canary. It does not check vendor versions.');
+  console.log('"route not pinned" means that lane runs on whatever its own config file says, which this tool cannot see. Pin it in lanes.json "defaults" if the route matters.');
   return bad ? NO_DELIVERABLE : OK;
 }
 
@@ -485,10 +586,10 @@ export function checkContracts(opts, text, before) {
 }
 
 export async function main(argv) {
-  const VALUE = new Set(['--brief', '--timeout', '--model', '--expect-file']);
+  const VALUE = new Set(['--brief', '--timeout', '--model', '--effort', '--expect-file']);
   const BOOL = new Set(['--quiet', '--audit', '--safe-mode', '--doctor', '--run', '--expect-json']);
   const args = [...argv];
-  const opts = { timeout: 900, quiet: false, audit: false, model: null, safeMode: false, brief: null, doctor: false, run: false, expectFile: null, expectJson: false };
+  const opts = { timeout: 900, quiet: false, audit: false, model: null, effort: null, safeMode: false, brief: null, doctor: false, run: false, expectFile: null, expectJson: false };
   const positional = [];
   while (args.length) {
     const a = args.shift();
@@ -498,6 +599,7 @@ export async function main(argv) {
       if (a === '--brief') opts.brief = v;
       else if (a === '--timeout') opts.timeout = Number(v);
       else if (a === '--expect-file') opts.expectFile = v;
+      else if (a === '--effort') opts.effort = v;
       else opts.model = v;
     } else if (BOOL.has(a)) {
       if (a === '--quiet') opts.quiet = true;
@@ -530,11 +632,33 @@ export async function main(argv) {
   if (!prompt) return usage('give a prompt or --brief FILE');
   if (!Number.isFinite(opts.timeout) || opts.timeout <= 0) return usage('--timeout must be a positive number of seconds');
   if (opts.audit && lane !== 'codex') return usage('--audit is codex-only');
-  if ((opts.model || opts.safeMode) && lane !== 'qwen') return usage('--model and --safe-mode are qwen-only');
+  if (opts.safeMode && lane !== 'qwen') return usage('--safe-mode is qwen-only');
+  for (const [kind, v] of [['model', opts.model], ['effort', opts.effort]]) {
+    if (v == null) continue;
+    const bad = badRouteValue(kind, v);
+    if (bad) return usage(bad);
+  }
+  // qwen has no reasoning flag. Dropping --effort silently would leave the caller
+  // believing a route that never happened, which is the defect this feature fixes.
+  if (opts.effort && !(LANE_FLAGS[lane] && LANE_FLAGS[lane].effort)) return usage(`${lane} has no reasoning-effort flag; --effort is not available on this lane`);
 
   const digest = createHash('sha256').update(prompt).digest('hex').slice(0, 12);
   const base = { lane, prompt_sha256_12: digest, prompt_chars: prompt.length };
-  const enabled = enabledLanes();
+  const cfg = laneConfig();
+  // Resolve the route BEFORE the refusals below. A run that never reached a lane
+  // was still a request for one, and a failure record with no route is the exact
+  // gap this feature exists to close. A malformed lanes.json has no usable
+  // defaults, so the flags stand alone and say so.
+  const route = resolveRoute(lane, opts, cfg === null ? {} : cfg.defaults);
+  opts.model = route.model;
+  opts.effort = route.effort;
+  Object.assign(base, {
+    model_requested: route.model,
+    effort_requested: route.effort,
+    model_source: route.model_source,
+    effort_source: route.effort_source
+  });
+  const enabled = cfg === null ? null : cfg.enabled;
   if (enabled === null) {
     console.error('cli-run: lanes.json exists but is not a valid {"enabled": [...]} file; refusing every lane until it is fixed');
     log({ ...base, verdict: 'unavailable', rc: UNAVAILABLE, reason: 'lanes_json_malformed' });
@@ -601,7 +725,8 @@ export async function main(argv) {
       }
     }
     if (text && code === OK) process.stdout.write(text + '\n');
-    if (!opts.quiet) console.error(`cli-run[${lane}] ${verdict} rc=${code} ${r.seconds.toFixed(1)}s raw=${r.outBytes || 0}B :: ${detail}`);
+    const routeNote = route.model || route.effort ? `${route.model || 'lane default'}/${route.effort || 'lane default'}` : 'lane default';
+    if (!opts.quiet) console.error(`cli-run[${lane}] ${verdict} rc=${code} ${r.seconds.toFixed(1)}s raw=${r.outBytes || 0}B route=${routeNote} :: ${detail}`);
     // Durable log: fixed reason code and structural numbers only.
     log({ ...base, verdict, rc: code, cli_rc: r.status, signal: r.signal || null, seconds: Math.round(r.seconds * 100) / 100, raw_bytes: r.outBytes || 0, deliverable_bytes: Buffer.byteLength(text), reason: REASONS.has(reason) ? reason : 'unknown' });
     return code;

package/bin/cli.js

@@ -93,7 +93,8 @@ Usage
 Flags
   --level 1|2|3      1 beginner (one agent), 2 intermediate (many CLIs), 3 advanced (plus a VM)
   --ais a,b,c        catalog ids you have access to (see --list)
-  --primary id       the agent that runs the system and receives the subagents (any level; required when several qualify)
+  --primary id       the agent that runs the system and receives the subagents (any level). When several qualify
+                     and --yes is set, the run picks one and says so in the plan; pass this to decide it yourself.
   --tools a,b        companion tools to set up, all optional (default with --yes: codecalc only); --no-tools for none
   --apis a,b         level 3 only: metered API keys you HOLD (anthropic,openai,google,xai,openrouter); --no-apis for none.
                      Asked separately from the CLIs because a subscription is not an API key.
@@ -189,6 +190,7 @@ async function main() {
   // 3. Primary agent (the one that runs the system)
   const candidates = agentCandidates(selected);
   let primary = null;
+  let primaryAutoPicked = false;
   if (opt('primary')) {
     primary = byId[opt('primary')];
     if (!primary || !candidates.includes(primary)) bad('--primary must be one of: ' + candidates.map((a) => a.id).join(', '));
@@ -200,7 +202,10 @@ async function main() {
     // --yes picks for the user: claude-code if present, else the first agent that can load subagent
     // definitions (it gets five files written for it), else the first candidate. #19: codex listed
     // before agy used to win and nothing was written to the project root.
-    if (yes) primary = candidates.find((a) => a.id === 'claude-code') || candidates.find((a) => a.agentsDir) || candidates[0];
+    if (yes) {
+      primary = candidates.find((a) => a.id === 'claude-code') || candidates.find((a) => a.agentsDir) || candidates[0];
+      primaryAutoPicked = true;
+    }
     else {
       console.log('\nWhich one is your primary agent (the one that runs the system)?');
       candidates.forEach((a, i) => console.log(`  ${i + 1}  ${a.name}`));
@@ -271,7 +276,7 @@ async function main() {
   const files = planFiles({ level, selected, primary, dir, project, tools, apis });
   const lvl = LEVELS.find((l) => l.id === level);
   const agentFiles = files.filter((f) => f.root === 'project');
-  console.log(`\nPlan\n  level    ${lvl.id} ${lvl.name}\n  access   ${selected.map((a) => a.id).join(', ')}\n  primary  ${primary ? primary.id : 'none'}\n  tools    ${tools.map((t) => t.id).join(', ') || 'none'}` + (level >= 3 ? `\n  api keys ${apis.map((p) => p.id).join(', ') || 'none'}` : '') + `\n  folder   ${dir}\n  project  ${project}${agentFiles.length ? ' (' + agentFiles.length + ' subagent files go here)' : ''}\n  files    ${files.length}`);
+  console.log(`\nPlan\n  level    ${lvl.id} ${lvl.name}\n  access   ${selected.map((a) => a.id).join(', ')}\n  primary  ${primary ? primary.id : 'none'}${primaryAutoPicked ? ` (chosen for you from ${candidates.map((a) => a.id).join(', ')}; pass --primary to decide it yourself)` : ''}\n  tools    ${tools.map((t) => t.id).join(', ') || 'none'}` + (level >= 3 ? `\n  api keys ${apis.map((p) => p.id).join(', ') || 'none'}` : '') + `\n  folder   ${dir}\n  project  ${project}${agentFiles.length ? ' (' + agentFiles.length + ' subagent files go here)' : ''}\n  files    ${files.length}`);
   if (agentFiles.length && !opt('project')) {
     console.log(`\nNote: --project was not given, so the ${agentFiles.length} subagent file(s) go to the current directory (${project}). Pass --project to put them somewhere else.`);
   }
@@ -365,7 +370,7 @@ async function main() {
 
   for (const t of tools) {
     const doc = t.id.toUpperCase() + '.md';
-    console.log(`\n${t.name}\n  optional: ${t.optionalNote}\n  needs:    ${t.requires}\n  run:      ${t.install}\n  one-click or self-registering for: ${t.autoClients.join(', ')}. Other agents and the details: ${dir}/${doc}`);
+    console.log(`\n${t.name}\n  note:     ${t.optionalNote}\n  needs:    ${t.requires}\n  run:      ${t.install}\n  one-click or self-registering for: ${t.autoClients.join(', ')}. Other agents and the details: ${dir}/${doc}`);
   }
 
   // 7. Activation summary: writing the folder is half the job. Say exactly what

package/docs/part-1-beginner.md

@@ -14,6 +14,8 @@ If your agent exposes model choice (Claude Code, Codex, Antigravity), map the ti
 
 Three cost levers, always together: tier (price per token), token discipline (how many tokens: read only what you will touch, never re-read, deliverables not narration), effort (how hard each call thinks).
 
+And three inputs into the choice, not one. **Role** picks the agent. **Complexity** moves the effort: a worker executing a finished plan needs less reasoning than the reviewer judging its output, so when the plan is airtight the spec is carrying the thinking. **Risk** moves the tier and who reads the result: security, privacy, data loss and irreversible changes are the four worth naming, because none of their failures can be fixed by editing the code afterwards. A one-line change to an auth check is simple and high-risk at once, and it is the risk that decides.
+
 Robustness first, cost second. You split tiers because the split produces better work.
 
 ## 2. Classify every task, first match wins

package/docs/part-2-intermediate.md

@@ -26,7 +26,9 @@ One driver, no second AI in the mix: the orchestrator invokes the CLIs; it never
 
 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. 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.
 
-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, and with `--run` a one-word canary per lane.
+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.
+
+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 an adversarial 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.
 
 ## 4. Every delegation carries a task bundle, on both surfaces
 
@@ -36,6 +38,10 @@ Subagents and CLI lanes are the same problem: something with none of your rules
 
 Fan the same plan to three model families (web sweep, adversarial 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.
+
 ## 6. Gap analysis gets a second family
 
 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.12",
-  "description": "Routing instructions and a CLI runner for your AI tools. One installer asks what you have access to and generates a matching setup, from one chat app to several agent CLIs or a virtual machine.",
+  "version": "0.1.14",
+  "description": "Routing instructions and a CLI runner for your AI tools. One installer asks what you have access to and generates a matching setup, from one chat app to several agent CLIs or a virtual machine. Routes by role, complexity and risk; pins and logs the model and reasoning effort each lane runs with.",
   "type": "module",
   "bin": {
     "model-orchestrator": "bin/cli.js"
@@ -51,7 +51,11 @@
     "agents",
     "subagents",
     "qwen",
-    "mcp"
+    "mcp",
+    "reasoning-effort",
+    "model-routing",
+    "code-review",
+    "ai-agents"
   ],
   "author": "aunysillyme (https://github.com/aunysillyme)",
   "license": "MIT"

package/src/install.js

@@ -219,12 +219,32 @@ export function activationSteps(opts) {
   else if (snippet) steps.push(`open ${primary.chatName || primary.name} and paste the block in ${join(dirAbs, snippet)} into its ${primary.chatSurface || 'custom instructions'}`);
   if (primary && primary.agentsDir) steps.push(`subagents are in ${join(projectAbs, primary.agentsDir)}; run ${primary.bin} from ${projectAbs} to pick them up`);
   for (const a of selected.filter((a) => a.bin && a.kind === 'agent-cli')) steps.push(`sign in to ${a.name}: ${a.auth}`);
+  // A local runtime has a bin but no sign-in, so the agent-cli loop above skips it
+  // and before this it appeared in no ordered list at any level (#26).
+  for (const a of selected.filter((a) => a.bin && a.kind === 'local')) steps.push(`install ${a.name}: ${a.install.url}, then \`${a.bin} pull <model>\` before the local lane can answer`);
   for (const t of tools) steps.push(`${t.id}: ${t.install}`);
   if (level >= 2) steps.push(`smoke test: node ${join(dirAbs, 'bin', 'cli-run.mjs')} --doctor   (add --run to send each lane one tiny prompt)`);
   if (level >= 3) steps.push(`box: read ${join(dirAbs, 'vm', 'README.md')}; keys named in vm/ENVIRONMENT.md go in your secrets manager, never a file`);
   return steps;
 }
 
+// The verification list, in order. Gated on level for the same reason
+// activationSteps is: level 1 writes no bin/, so a step naming cli-run.mjs or
+// lanes.json there described an install that did not happen (#27).
+export function proofSteps(opts) {
+  const { level } = opts;
+  const steps = [
+    'Start a fresh agent session and ask: "Read the orchestrator instructions. Quote the routing rule you will use, then sort pear, apple, banana alphabetically. Name the tier and whether you delegated."',
+    'Expect the fast tier and `apple, banana, pear`. If the agent cannot quote the routing rule, check the snippet location or chat instructions before continuing. This is a manual activation check, not proof that every future task follows the rules.'
+  ];
+  if (level >= 2) {
+    steps.push('Run `node bin/cli-run.mjs --doctor` from this folder. It checks binary presence, not authentication or loaded instructions, and prints the model and effort each lane is pinned to. `--doctor --run` additionally uses a little quota to test live responses. No enabled lanes means delegation is inactive.');
+    steps.push('Decide whether the route matters to you. Every lane starts unpinned, which means it runs on whatever its own config file says: a CLI configured months ago at a low reasoning effort will keep auditing at that effort while your docs describe something stronger. Pin it in `bin/lanes.json` under `defaults`, or per call with `--model` and `--effort`. Either way the run is recorded in the log with the value requested and where it came from.');
+    steps.push('To test a real output contract, choose an enabled lane from `bin/lanes.json` and run `node bin/cli-run.mjs <lane> \'Return only {"sorted":["apple","banana","pear"]}\' --expect-json`. This uses quota. Expect JSON and exit 0; inspect the array yourself. A non-JSON response exits 10, a missing binary exits 13, and an authentication failure reports the vendor error. The explicit lane tests execution; your primary agent still makes delegation decisions.');
+  }
+  return steps;
+}
+
 function vars(opts) {
   const { level, selected, primary } = opts;
   const tools = opts.tools || [];
@@ -240,6 +260,7 @@ function vars(opts) {
   const pinOf = (id) => (toolById[id] && toolById[id].pin) || 'latest';
   const snippet = snippetFor(primary);
   const steps = activationSteps({ level, selected, primary, tools, dir: opts.dir, project: opts.project });
+  const proofs = proofSteps({ level });
   // Only claude-code and agy put files under the project root. A chat primary
   // puts nothing there, so naming a project root would name a folder this run
   // never created (#21).
@@ -253,6 +274,7 @@ function vars(opts) {
   return {
     ...laneVars(selected),
     ACTIVATION_STEPS: steps.map((st, i) => `${i + 1}. ${st}`).join('\n'),
+    PROOF_STEPS: proofs.map((st, i) => `${i + 1}. ${st}`).join('\n'),
     LOAD_IT: readsProjectRules
       ? `${primary.name} reads its rules from \`${primary.rulesFile}\` in the project root. The installer wrote \`${snippet}\` next to this README; copy its contents into \`${join(projectAbs, primary.rulesFile)}\`, creating that file if it does not exist. Nothing was appended to a file you already had.`
       : snippet
@@ -272,6 +294,12 @@ function vars(opts) {
     INSTALL_DIR: dirAbs,
     INSTALL_DIR_SH: shellQuote(dirAbs),
     INSTALL_DIR_SYSTEMD: systemdEscape(dirAbs),
+    // vm/README.md step 3 named `grok login` and `agy` whatever you picked (#26).
+    VM_SIGNIN: (() => {
+      const lines = selected.filter((a) => a.bin && a.kind === 'agent-cli').map((a) => `   - ${a.name}: ${a.auth}`);
+      for (const a of selected.filter((a) => a.bin && a.kind === 'local')) lines.push(`   - ${a.name}: no sign-in. Install it from ${a.install.url}, then \`${a.bin} pull <model>\`.`);
+      return lines.length ? lines.join('\n') : '   - none: no CLI you selected needs a sign-in on the box.';
+    })(),
     AUDIT_LANE: lane || 'none',
     // Enforced boundary per lane: codex has a read-only sandbox flag; the others
     // run with whatever their own config allows, and the script says so.
@@ -362,7 +390,9 @@ export function planFiles(opts) {
       JSON.stringify(
         {
           enabled: selected.filter((a) => a.cliRun).map((a) => a.id),
-          note: 'Lanes cli-run may call. Edit to enable or disable a lane. A lane not listed here exits 13 (unavailable).'
+          defaults: {},
+          note: 'Lanes cli-run may call. Edit to enable or disable a lane. A lane not listed here exits 13 (unavailable).',
+          defaultsNote: 'Pin what a lane runs with, so the route in your docs is the route that runs: "defaults": {"codex": {"model": "gpt-6-astra", "effort": "high"}}. Left empty, a lane inherits its own config file, which cli-run cannot see and does not guess. `--model` and `--effort` override this per call, and `--doctor` prints what each lane is pinned to. Every lane takes a model; every lane except qwen takes an effort.'
         },
         null,
         2

package/templates/advanced/vm/README.md

@@ -23,7 +23,8 @@ Generated {{DATE}} for: `{{AI_IDS}}`. Installed at `{{INSTALL_DIR}}`; the system
 
 1. Provision a box. Ubuntu, 2+ vCPU, 8 GB is comfortable. Put it on a private mesh network if you can; do not open ports to the internet.
 2. `bash setup-vm.sh`. It installs system deps and the npm-installable CLIs, then **prints** the vendor shell installers for the rest. Read those scripts before running them.
-3. Sign each CLI in with its device-code flow (`codex login --device-auth`, `grok login --device-auth`, `agy` on first run). Run these inside `tmux` so a dropped SSH session does not kill the prompt. Headless Linux has no keyring by default; `setup-vm.sh` installs one so the CLIs stop re-prompting.
+3. Sign each CLI in, using the flow its vendor gives you. Run these inside `tmux` so a dropped SSH session does not kill the prompt. Headless Linux has no keyring by default; `setup-vm.sh` installs one so the CLIs stop re-prompting.
+{{VM_SIGNIN}}
 4. Put provider keys in your secrets manager and export the names listed in `ENVIRONMENT.md` into the gateway's environment at start time. Never write a value into a file in this folder. The gateway config was rendered from the API keys you said you hold, not from your CLI subscriptions: those are different entitlements.
 5. `docker compose up -d`, then list the lanes without putting the key in argv (the key must be a single token, `^[A-Za-z0-9._-]+$`, because it is interpolated into curl's config grammar):
    ```bash

package/templates/agents/agy/README.md

@@ -1,5 +1,5 @@
 # .agents/agents/
 
-Antigravity CLI custom agents, one per tier, in the `.agents/agents/<name>.md` format (YAML frontmatter + system prompt). `model` is a tier (`flash`, `pro`) or `inherit`. `subagent: true` lets a coordinator call them through `invoke_subagent`, which takes an array and launches concurrently; `mainAgent: true` lets you launch them directly with `agy --agent <name>`.
+Antigravity CLI custom agents, one per tier plus a finding-verifier, in the `.agents/agents/<name>.md` format (YAML frontmatter + system prompt). `model` is a tier (`flash`, `pro`) or `inherit`. `subagent: true` lets a coordinator call them through `invoke_subagent`, which takes an array and launches concurrently; `mainAgent: true` lets you launch them directly with `agy --agent <name>`.
 
 `commandExecutionPolicy` is `auto` for `builder` (it has to run builds and tests; `auto` keeps deletes and other high-risk commands gated) and `off` for the read-only agents. `model` is a tier: `pro` for deep-planner, `flash` for the rest.

package/templates/agents/agy/finding-verifier.md

@@ -0,0 +1,29 @@
+---
+name: finding-verifier
+description: Adversarial verification of review findings; tries to disprove each one and returns CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE. Read-only, never repairs.
+model: flash
+subagent: true
+mainAgent: true
+commandExecutionPolicy: off
+---
+
+# finding-verifier
+
+A finding is a claim, not a fact. You try to disprove each one before it is
+allowed to cause a repair.
+
+For each finding you are given: read the cited file and line yourself, state the
+input or sequence that would trigger it, then hunt for what makes it impossible
+(a guard upstream, a caller that never passes that value, an existing test).
+
+Return one verdict per finding, in the order given:
+- CONFIRMED: reproduced, or a concrete unblocked path. Give the path.
+- NOT_REPRODUCED: you found what stops it. Name it and where it is.
+- INCONCLUSIVE: not settleable read-only. Say what you would need.
+
+Rules:
+- Stay inside the task bundle you were given. Anything not granted is denied.
+- Verify only the findings handed to you; anything else you notice goes at the end, marked unverified.
+- Never round INCONCLUSIVE up to CONFIRMED to be safe, or down to NOT_REPRODUCED to be tidy.
+- Read-only: you never repair and never reword a finding.
+- Token discipline: read the cited code and its callers, not the repository.

package/templates/agents/claude-code/README.md

@@ -1,12 +1,13 @@
 # .claude/agents/
 
-Five subagents, one per tier. Claude Code loads project-level agents from this folder automatically.
+Six subagents. Five are one per tier; `finding-verifier` is the check that sits between a review and a repair. Claude Code loads project-level agents from this folder automatically.
 
 | Agent | Tier | Model alias | Effort | Job |
 |---|---|---|---|---|
 | deep-planner | deep | opus | xhigh | judges every build twice; never retrieves |
 | builder | standard | sonnet | high | bounded sub-parts of a build |
 | code-reviewer | standard | sonnet | high | read-only findings |
+| finding-verifier | standard | sonnet | high | tries to disprove a finding before it causes a repair |
 | live-researcher | standard | sonnet | medium | fresh data through tools |
 | bulk-worker | fast | haiku | low | mechanical volume |
 

package/templates/agents/claude-code/finding-verifier.md

@@ -0,0 +1,43 @@
+---
+name: finding-verifier
+description: Adversarial verification of review findings. Use after a review or audit returns findings and before any of them trigger a repair. Read-only. Tries to DISPROVE each finding and returns CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE per finding. Do not use to find new problems, and do not use to fix anything.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+effort: high
+---
+
+You are the verification tier of the model router.
+
+A finding is a claim, not a fact. Your job is to try to disprove each one before
+it is allowed to cause a change. A false finding is expensive twice: it buys a
+repair nobody needed, and it teaches everyone to skim the next report.
+
+You are given findings from a review or an audit. For each one, independently:
+
+1. Read the cited file and line yourself. A citation that does not point at what
+   the finding describes is already a failure of the finding, not of the code.
+2. State the exact input, state or sequence that would make it happen.
+3. Look for what makes it impossible: a guard upstream, a type that cannot hold
+   that value, a caller that never passes it, a test that already covers it, a
+   framework guarantee.
+4. Where you can run something cheap and read-only that settles it, run it.
+
+Return one verdict per finding, in the order you were given them:
+
+- **CONFIRMED** you reproduced it, or traced a concrete path to it that nothing
+  prevents. Give the path in one or two sentences.
+- **NOT_REPRODUCED** you found what stops it. Name that thing and where it is.
+  This is a success, not a failure to try.
+- **INCONCLUSIVE** you could not settle it read-only. Say exactly what you would
+  need: a test run, a credential, a live environment, a decision from a human.
+  Never round this up to CONFIRMED to be safe, and never down to
+  NOT_REPRODUCED to be tidy.
+
+Rules:
+- Verify only the findings you were given. New problems you happen to notice go
+  in a separate list at the end, clearly marked as unverified observations.
+- You are read-only. You never repair, and you never soften a finding's wording.
+- Verifying nothing is a real answer. If every finding is NOT_REPRODUCED, say
+  that plainly; a verifier that always confirms something is a rubber stamp
+  facing the other way.
+- Token discipline: read the cited code and its callers, not the repository.

package/templates/agents/snippets/claude-code.md

@@ -10,6 +10,7 @@ Routing rules live in `{{RULES_PATH}}/{{ROUTING_FILE}}`. Read them before any bu
 1. Bulk, mechanical, many similar items -> bulk-worker (fast tier).
 2. Needs live data -> live-researcher (standard tier + tools).
 3. Review without changing -> code-reviewer (standard, read-only).
+3a. Holding findings from a review or scanner -> finding-verifier before any repair. Only CONFIRMED findings earn a change.
 4. Ambiguous, architectural, or expensive to get wrong -> deep-planner (deep tier), then hand the plan down.
 5. Everything else that changes files -> build it directly. The main build is never handed off whole; bounded sub-parts go to builder.
 

package/templates/common/README.md

@@ -21,10 +21,7 @@ These are the same steps, in the same order, that the installer printed in your
 
 ## Then prove it took
 
-1. Start a fresh agent session and ask: "Read the orchestrator instructions. Quote the routing rule you will use, then sort pear, apple, banana alphabetically. Name the tier and whether you delegated."
-2. Expect the fast tier and `apple, banana, pear`. If the agent cannot quote the routing rule, check the snippet location or chat instructions before continuing. This is a manual activation check, not proof that every future task follows the rules.
-3. At level 2+, run `node bin/cli-run.mjs --doctor` from this folder. It checks binary presence, not authentication or loaded instructions. `--doctor --run` additionally uses a little quota to test live responses. No enabled lanes means delegation is inactive.
-4. To test a real output contract, choose an enabled lane from `bin/lanes.json` and run `node bin/cli-run.mjs <lane> 'Return only {"sorted":["apple","banana","pear"]}' --expect-json`. This uses quota. Expect JSON and exit 0; inspect the array yourself. A non-JSON response exits 10, a missing binary exits 13, and an authentication failure reports the vendor error. The explicit lane tests execution; your primary agent still makes delegation decisions.
+{{PROOF_STEPS}}
 
 ## What is in this folder
 

package/templates/common/protocols/build-protocol.md

@@ -66,7 +66,17 @@ Secret detection, static analysis and dependency scanning, filtered to lines thi
 
 Route by shape: security-shaped diffs (auth, tokens, routes, deletion, bulk mutation, untrusted input) go to an adversarial auditor, ideally a **different model family**. Architecture-shaped diffs go to the judgment tier reviewing build against plan. Never both on one diff.
 
-**Gate:** every finding **reproduced** before it reaches a human. Unreproduced items are dropped, not narrated. Hard cap one re-audit. `CLEAN` is a valid success state; an auditor that is not allowed to say so manufactures something.
+Findings do not go straight to a repair. Hand them to the **finding-verifier**, whose job is to DISPROVE each one: read the cited line, state what would trigger it, then hunt for the guard, caller or test that makes it impossible. It returns one of three verdicts per finding, and rounding between them is the failure mode to watch for.
+
+| Verdict | Meaning | What happens next |
+|---|---|---|
+| CONFIRMED | reproduced, or a concrete path nothing blocks | it earns a repair |
+| NOT_REPRODUCED | something prevents it, named and located | dropped, and not narrated |
+| INCONCLUSIVE | not settleable read-only | say what it would take; never round it to either side |
+
+Use a different model family from the one that produced the finding where you have one: a family asked to check its own claim tends to agree with itself.
+
+**Gate:** every finding **verified** before it reaches a human, and only CONFIRMED findings trigger a change. Hard cap one re-audit. `CLEAN` is a valid success state; an auditor that is not allowed to say so manufactures something, and so does a verifier that is expected to confirm.
 
 ### Stage 5b · Ship gate
 1. What is the rollback target? Record it before shipping.

package/templates/intermediate/CLI-RUN.md

@@ -18,7 +18,8 @@ Enabled lanes (edit `bin/lanes.json`): {{CLI_RUN_LANES}}
 ```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 qwen [--model ID] [--safe-mode] "<prompt>"
+node bin/cli-run.mjs codex "<prompt>" --model gpt-6-astra --effort high
+node bin/cli-run.mjs qwen [--safe-mode] "<prompt>"             # qwen-only flag
 ```
 
 Put it on your PATH if you like: `ln -s "$PWD/bin/cli-run.mjs" ~/.local/bin/cli-run`.
@@ -65,13 +66,49 @@ qwen is the lane whose own success flags lie: an upstream 400 comes back as exit
 | 2 | usage error in cli-run itself |
 | N | the lane exited N != 0: passed through unchanged, verdict `exit_nonzero`, even when parseable text came back. The bounded head of the lane's stderr is shown on your terminal so an auth failure reads as one |
 
+## The route: which model, and how hard it thinks
+
+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 an adversarial pass, and nothing anywhere says so.
+
+Pin it per call, or per lane:
+
+```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
+```
+
+```json
+{
+  "enabled": ["codex", "grok"],
+  "defaults": { "codex": { "model": "gpt-6-astra", "effort": "high" } }
+}
+```
+
+A flag beats `defaults`; `defaults` beats nothing. Each vendor spells these differently and `cli-run` translates:
+
+| Lane | Model | Reasoning effort |
+|---|---|---|
+| 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 that lane's own exit code and stderr.
+- **`--effort` on qwen is a usage error, not a silent drop.** A flag that vanishes leaves you believing a route that never ran.
+- **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, rc, the lane's own exit code, signal, seconds, raw bytes, deliverable bytes, a 12-hex sha256 prefix of the prompt and its length, 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`, ...). 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.
+`~/.ai-orchestrator/cli-run.log.jsonl`, one line per run: lane, verdict, rc, the lane's own exit code, 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`), 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`, ...). 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
 
@@ -79,7 +116,7 @@ That is each vendor's documented headless shape (`-p`, `exec`). Two consequences
 
 ## lanes.json fails closed
 
-Absent: every lane enabled. 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.
+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 fail the whole file closed rather than being skipped quietly.
 
 ## A killed lane is not a deliverable
 

package/templates/intermediate/ROUTING.md

@@ -17,6 +17,7 @@ Rule of thumb: never spend a frontier token on a task a cheap tier finishes corr
 1. **Bulk and mechanical?** → fast tier{{BULK_LANE}}. Many independent items each needing its own agent turn → a concurrent fan-out lane if you have one.
 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.
 4. **Ambiguous, strategic, expensive to get wrong?** → deep tier (deep-planner). Then hand the plan down.
 5. **Everything else that changes files** → the orchestrator builds it directly. Bounded sub-parts go to cheaper tiers; the main build is never handed off whole.
 
@@ -38,6 +39,7 @@ Every delegation carries `TASK_BUNDLE.md`. Its brief must restate every conventi
 | 3 Build | the orchestrator, against the installed dependency's source |
 | 4 Scan | secret + static + dependency scanners, diff-scoped, fail closed |
 | 5 Attack | 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 |
@@ -59,7 +61,9 @@ One writer per run; every other lane proposes. Search before writing, index in t
 - **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 and build high, live research medium, bulk low.
+- **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, risk moves the tier and who reads it. A one-line auth change is simple and high-risk at once, and the risk decides. 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.
 
 ## Example routings
 
@@ -70,4 +74,5 @@ One writer per run; every other lane proposes. Search before writing, index in t
 | "Add an endpoint" | the orchestrator builds it |
 | "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 |
+| "The audit returned 6 findings" | finding-verifier first; repair only what comes back CONFIRMED |
 {{LANE_EXAMPLES}}

package/templates/intermediate/TIERS.md

@@ -19,11 +19,52 @@ Tier sets the price per token. Token discipline sets how many tokens. **Effort s
 |---|---|---|---|
 | deep-planner | deep | xhigh | judges every build twice; expensive to get wrong |
 | code-reviewer | standard | high | every endpoint is internet-facing |
+| finding-verifier | standard | high | judging a claim is harder than producing it |
 | builder | standard | high | a botched deploy is the costly failure |
 | live-researcher | standard | medium | tools do the retrieval |
 | bulk-worker | fast | low | the biggest cost win |
 
-Dials: drop builder to medium when the plan is airtight; raise code-reviewer to xhigh for a security-critical audit.
+## Three inputs, not one
+
+Role alone does not decide a route. Two more inputs move it, and they move it in
+opposite directions, so state them separately instead of folding them into the
+role.
+
+**Complexity moves the effort.** The same role does not need the same reasoning
+on every task.
+
+| Complexity | What it looks like | What moves |
+|---|---|---|
+| simple | one file, one obvious edit, no unknowns | drop one effort level |
+| standard | the default | the table above |
+| complex | several surfaces, or an unknown cause | keep effort, add the deep-tier checkpoint |
+| critical | irreversible, or it rewrites a standing rule | the escalation rule below applies |
+
+The dial that pays for itself: **a worker executing a finished plan needs less
+reasoning than the reviewer judging its output.** When the plan is airtight the
+spec is carrying the thinking, so builder drops to medium. When the plan is
+vague, fix the plan; do not buy reasoning to paper over it.
+
+**Risk moves the tier and the reader, never just the effort.** These four are
+the ones worth naming, because their failures are not recoverable by editing the
+code afterwards.
+
+| Risk | Present when the change touches | What it buys |
+|---|---|---|
+| security | auth, tokens, sessions, routes, untrusted input | the attack pass, ideally a different model family |
+| privacy | personal data, anything leaving the machine | the local lane, and a named check on what is sent |
+| data loss | deletion, bulk mutation, migrations, overwrites | a reviewed rollback path before the change is written |
+| irreversible | publishing, sending, rotating, anything with an audience | a human yes at Stage 5b, never an agent's |
+
+A risk raises code-reviewer to xhigh, and a security-shaped diff goes to the
+attack lane rather than to a second read by the same family. Risk is not a
+synonym for difficulty: a one-line change to an auth check is simple and
+high-risk at the same time, and it is the risk that decides the route.
+
+**Reserve the top of the ladder for evidence.** xhigh and the escalation tier are
+bought with a named reason: a reproduced failure, a checkpoint that came back
+unresolved, an irreversible change. A task that merely feels hard is a deep-tier
+task, not an escalation.
 
 ## Why split tiers: robustness first, cost second