model-orchestrator 0.1.20 → 0.1.21

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [0.1.21] - 2026-09-12
+
+### Added
+
+- **Subscription plans, stated by you and never guessed.** The installer asks which plan you hold for Claude Code, Codex, `agy` and `grok` (interactive, or `--plans codex=pro-20x,agy=ultra-5x`; `--plans none` clears). Each plan row in `src/catalog.js` carries only a name, a headroom level (`base`, `high`, `max`), its official source page and the date it was checked; no prices and no model ids, because both change faster than releases. `--list` prints them.
+- **Plan guidance in the generated docs.** The lanes table gains a `Plan` column, and `ROUTING.md` and `DELEGATION_MATRIX.md` gain a plan guidance block: high and max headroom lanes take volume (scoped builds, pre-ship second-family audits, first-pass research), base headroom lanes keep short second opinions. Headroom moves volume only; who reviews what does not change.
+- **`--effort auto` in `cli-run`.** Accepted as a flag or as a `lanes.json` default on every lane with an effort flag (qwen still refuses it). A call sizes from prompt length: under 4,000 characters is `medium`, otherwise `high`. A codex `--audit` always runs at `high` and logs the larger of prompt length and changed lines as evidence. Auto never resolves above `high`: `xhigh`, `max` and `ultra` are sent only when named. The durable log gains `effort_resolved`, `effort_basis` (`explicit`, `prompt_chars`, `audit_floor`, `none`), `effort_scope` and `effort_truncated`.
+- **Bounded change counting for audits.** Untracked files are listed NUL-delimited, only regular files are opened (FIFOs, devices and symlinks are skipped by `lstat`), and the pass stops at 200 files, 256 KiB per file, 2 MiB total or 2 seconds, marking the evidence truncated. An unborn `HEAD` or any git failure falls back to prompt length.
+
+### Changed
+
+- **Automatic effort is opt-in.** A high or max headroom plan does not change `bin/lanes.json` by itself; `--effort-auto` (or yes to the question) writes `"effort": "auto"` for exactly those cli-run lanes. Claude Code is never written there, since it is not a cli-run lane and an entry for it would fail the whole file closed. With no plan stated, `bin/lanes.json` is byte-identical to 0.1.20 and `MANIFEST.json` records no plan keys. A re-run that omits `--plans` keeps the previous plans.
+- **Five documented Windows skips, not four.** The FIFO half of the new untracked-file test needs `mkfifo`; its symlink half runs everywhere.
+
 ## [0.1.20] - 2026-09-12
 
 ### Added
@@ -315,7 +329,8 @@ 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.20...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.21...HEAD
+[0.1.21]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.20...v0.1.21
 [0.1.20]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.19...v0.1.20
 [0.1.19]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.18...v0.1.19
 [0.1.18]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.17...v0.1.18

package/README.md

@@ -30,6 +30,10 @@ The installer asks a few things, then writes a folder:
 
 It never writes a secret, never runs a vendor shell script for you, and never overwrites a document you already have unless you pass `--force`. Two exceptions, both stated when they happen: `MANIFEST.json` and `bin/lanes.json` are machine-owned and rewritten on every run so a changed selection applies; runtime files (`cli-run`, the audit job, compose, gateway config, setup script) are upgraded when the installed copy matches the hash a previous run recorded, kept and reported as a conflict when you edited them, and kept as unverifiable when no manifest exists (`--upgrade-runtime` replaces runtime files only). The same hash rule is available for documents on request: `--update-docs` regenerates the documents a previous run wrote and nobody edited, so a changed selection reaches `ROUTING.md` and the delegation matrix without `--force`; edited documents are kept and named. Docs and protocols go to `--dir` (default `./ai-orchestrator`); subagent definitions (and, on Claude Code, two hook scripts) go to the project root your agent runs from (`--project`, default the current directory), because that is the only place Claude Code and Antigravity read them. It ends with an activation summary: what to copy where, which sign-ins, and one smoke command. Uninstall: follow the generated README. Inspect the manifest and remove only the individual managed subagent files you no longer need, preserve edited or pre-existing files, and remove your manually pasted activation block. Never delete a shared subagent folder.
 
+## Plans and automatic effort
+
+State known subscription plans with `--plans codex=pro-20x,agy=ultra-5x`. The generated guidance uses plan headroom to allocate volume only. It never changes capability or independent-review rules. `--effort-auto` is explicit consent to set `auto` only for selected high or max headroom CLI lanes. Auto chooses medium below 4,000 prompt characters and high otherwise, never higher. A codex audit is always high. Name `xhigh` explicitly for security-critical or irreversible work.
+
 ## The three levels
 
 | Level | You have | You get |
@@ -278,7 +282,7 @@ Yes. `--yes` with `--level`, `--ais` and `--project` runs headless, `--dry-run`
 
 ## Requirements
 
-Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu. Windows: CI runs the suite on `windows-latest` (Node 18, 20, 22), including lane execution end to end through `cli-run` against a fake CLI installed the same way npm installs a real one (a `.cmd` shim). `cli-run` never runs a lane through `cmd.exe` when it can avoid it: it resolves the shim to the Node script underneath and spawns Node directly, so a prompt reaching a real lane never passes through a Windows shell. A `.cmd` or `.bat` lane that cannot be resolved that way (an old or hand-edited shim) is refused with exit 13 and a message saying how to fix it, rather than run through `cmd.exe`: a batch file re-reads its arguments after `cmd.exe` has parsed them once, and no escaping fully contains a prompt through both passes. Install, detection, the hooks and `cli-run`'s `taskkill` tree kill are tested on Windows too, including SIGTERM/SIGINT to the wrapper (Windows has no OS-level signals: both terminate it unconditionally, verified there rather than treated the same as POSIX). Four narrow skips remain on Windows, each for a POSIX behavior the OS or the CI shell genuinely does not have, and each named here because a test that is quietly skipped reads as a test that passed: `statSync().mode`'s executable bit (NTFS has none, so that one assertion is conditional inside a test that otherwise runs everywhere); a lane dying mid-run from a real POSIX signal (a real Windows lane cannot die "by signal"); running `weekly-audit.sh`'s watchdog functions for real under Git Bash's job control, both the end-to-end run and the `bounded()` timeout check (the script itself only ever runs on the Ubuntu box it targets); and a `mkfifo` FIFO at the rules path, the one case that proves `route-gate.mjs` cannot HANG on a non-regular file, since Windows has no `mkfifo` to build one (the guard behind it is covered on every OS by a directory at the same path). The list is not prose on trust: `test/prose.test.js` counts every `skip:` in the suite and fails if one of them is not documented here.
+Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu. Windows: CI runs the suite on `windows-latest` (Node 18, 20, 22), including lane execution end to end through `cli-run` against a fake CLI installed the same way npm installs a real one (a `.cmd` shim). `cli-run` never runs a lane through `cmd.exe` when it can avoid it: it resolves the shim to the Node script underneath and spawns Node directly, so a prompt reaching a real lane never passes through a Windows shell. A `.cmd` or `.bat` lane that cannot be resolved that way (an old or hand-edited shim) is refused with exit 13 and a message saying how to fix it, rather than run through `cmd.exe`: a batch file re-reads its arguments after `cmd.exe` has parsed them once, and no escaping fully contains a prompt through both passes. Install, detection, the hooks and `cli-run`'s `taskkill` tree kill are tested on Windows too, including SIGTERM/SIGINT to the wrapper (Windows has no OS-level signals: both terminate it unconditionally, verified there rather than treated the same as POSIX). Five narrow skips remain on Windows, each for a POSIX behavior the OS or the CI shell genuinely does not have, and each named here because a test that is quietly skipped reads as a test that passed: `statSync().mode`'s executable bit (NTFS has none, so that one assertion is conditional inside a test that otherwise runs everywhere); a lane dying mid-run from a real POSIX signal (a real Windows lane cannot die "by signal"); running `weekly-audit.sh`'s watchdog functions for real under Git Bash's job control, both the end-to-end run and the `bounded()` timeout check (the script itself only ever runs on the Ubuntu box it targets); and a `mkfifo` FIFO at the rules path, the one case that proves `route-gate.mjs` cannot HANG on a non-regular file, since Windows has no `mkfifo` to build one (the guard behind it is covered on every OS by a directory at the same path); and an untracked `mkfifo` FIFO in the repository `cli-run --audit` sizes, the case that proves `--effort auto` never opens a non-regular file (the symlink half of that test runs on every OS). The list is not prose on trust: `test/prose.test.js` counts every `skip:` in the suite and fails if one of them is not documented here.
 
 **Privacy.** The installer sends no telemetry and makes no network call of its own once it is running. Two things around that are worth being exact about:
 

package/bin/cli-run.mjs

@@ -51,10 +51,10 @@
 // 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 { spawn, spawnSync } from 'node:child_process';
 import { StringDecoder } from 'node:string_decoder';
 import { createHash } from 'node:crypto';
-import { readFileSync, existsSync, mkdirSync, appendFileSync, mkdtempSync, rmSync, accessSync, constants, realpathSync, statSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync, appendFileSync, mkdtempSync, rmSync, accessSync, constants, realpathSync, statSync, lstatSync, openSync, readSync, closeSync } from 'node:fs';
 import { join, dirname, delimiter, resolve } from 'node:path';
 import { tmpdir, homedir } from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -233,6 +233,82 @@ export const LANE_FLAGS = {
   qwen: { model: (v) => ['-m', v], effort: null }
 };
 
+// Auto is deliberately a small, static ladder. It is not a vendor capability
+// probe and it never chooses the top of a vendor's effort range.
+export const AUTO_EFFORT = {
+  codex: { small: 'medium', large: 'high' },
+  grok: { small: 'medium', large: 'high' },
+  agy: { small: 'medium', large: 'high' },
+  hermes: { small: 'medium', large: 'high' }
+};
+
+export function gitChangedLines(cwd) {
+  try {
+    const r = spawnSync('git', ['diff', '--numstat', '-z', 'HEAD'], { cwd, timeout: 5000, maxBuffer: 1024 * 1024 });
+    if (r.error || r.status !== 0) return null;
+    let total = 0;
+    for (const row of String(r.stdout).split('\0')) {
+      if (!row) continue;
+      const [added, removed] = row.split('\t');
+      total += (Number.isFinite(Number(added)) ? Number(added) : 0) + (Number.isFinite(Number(removed)) ? Number(removed) : 0);
+    }
+    const listed = spawnSync('git', ['ls-files', '--others', '--exclude-standard', '-z'], { cwd, timeout: 5000, maxBuffer: 1024 * 1024 });
+    if (listed.error || listed.status !== 0) return null;
+    const root = realpathSync(cwd);
+    const deadline = Date.now() + 2000;
+    let files = 0, bytes = 0, truncated = false;
+    for (const rel of String(listed.stdout).split('\0')) {
+      if (!rel) continue;
+      if (files >= 200 || Date.now() > deadline) { truncated = true; break; }
+      const p = resolve(root, rel);
+      if (p !== root && !p.startsWith(root + '/') && !p.startsWith(root + '\\')) continue;
+      let st;
+      try { st = lstatSync(p); } catch { continue; }
+      if (!st.isFile()) continue;
+      const limit = Math.min(st.size, 256 * 1024, 2 * 1024 * 1024 - bytes);
+      if (limit <= 0) { truncated = true; break; }
+      let fd;
+      try {
+        fd = openSync(p, 'r');
+        const buf = Buffer.alloc(Math.min(limit, 64 * 1024));
+        let read = 0, last = -1;
+        while (read < limit && Date.now() <= deadline) {
+          const n = readSync(fd, buf, 0, Math.min(buf.length, limit - read), read);
+          if (!n) break;
+          for (let i = 0; i < n; i++) if (buf[i] === 10) total++;
+          last = buf[n - 1];
+          read += n;
+        }
+        if (read && last !== 10) total++;
+        bytes += read;
+        if (read < st.size || Date.now() > deadline) truncated = true;
+      } catch {
+        // A changed file disappearing is ordinary repository churn. The caller
+        // falls back to prompt sizing only when the git probes themselves fail.
+      } finally { if (fd !== undefined) try { closeSync(fd); } catch {} }
+      files++;
+      if (bytes >= 2 * 1024 * 1024) { truncated = true; break; }
+    }
+    return { lines: total, truncated };
+  } catch {
+    return null;
+  }
+}
+
+export function resolveAutoEffort(lane, requested, prompt, audit, cwd = process.cwd()) {
+  if (requested !== 'auto') return { resolved: requested || null, basis: requested ? 'explicit' : 'none', scope: null, truncated: false };
+  const promptScope = prompt.length;
+  if (!audit) {
+    const bucket = promptScope < 4000 ? 'small' : 'large';
+    return { resolved: AUTO_EFFORT[lane][bucket], basis: 'prompt_chars', scope: promptScope, truncated: false };
+  }
+  const git = gitChangedLines(cwd);
+  const scope = Math.max(promptScope, git ? git.lines : 0);
+  // Audit is a stakes floor. Scope records the larger independently observed
+  // input, but never moves an audit above or below high.
+  return { resolved: 'high', basis: 'audit_floor', scope, truncated: !!(git && git.truncated) };
+}
+
 // 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
@@ -579,6 +655,7 @@ export function laneConfig(here = dirname(fileURLToPath(import.meta.url))) {
         if (model !== undefined && badRouteValue('model', model)) return null;
         if (effort !== undefined) {
           if (badRouteValue('effort', effort)) return null;
+          if (effort.startsWith('auto') && effort !== 'auto') 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 };
@@ -618,6 +695,7 @@ function usage(msg) {
   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.
+  auto sizes per call: below 4,000 prompt characters is medium, otherwise high; a codex audit is always high. Auto never resolves above high.
   Pin them per lane instead of per call with "defaults" in bin/lanes.json.`);
   return USAGE;
 }
@@ -665,7 +743,7 @@ export async function doctor(run) {
     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)';
+    const route = !on ? '' : d.effort === 'auto' ? `route ${d.model || 'lane default'}/auto (sized per call)` : 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) {
@@ -771,6 +849,7 @@ export async function main(argv) {
     if (v == null) continue;
     const bad = badRouteValue(kind, v);
     if (bad) return usage(bad);
+    if (kind === 'effort' && v.startsWith('auto') && v !== 'auto') return usage('--effort auto must be spelled exactly');
   }
   // 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.
@@ -784,13 +863,18 @@ export async function main(argv) {
   // 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);
+  const sizing = resolveAutoEffort(lane, route.effort, prompt, opts.audit);
   opts.model = route.model;
-  opts.effort = route.effort;
+  opts.effort = sizing.resolved;
   Object.assign(base, {
     model_requested: route.model,
     effort_requested: route.effort,
     model_source: route.model_source,
-    effort_source: route.effort_source
+    effort_source: route.effort_source,
+    effort_resolved: sizing.resolved,
+    effort_basis: sizing.basis,
+    effort_scope: sizing.scope,
+    effort_truncated: sizing.truncated
   });
   const enabled = cfg === null ? null : cfg.enabled;
   if (enabled === null) {
@@ -810,6 +894,8 @@ export async function main(argv) {
     return UNAVAILABLE;
   }
 
+  if (route.effort === 'auto' && !opts.quiet) console.error(`cli-run: effort auto -> ${sizing.resolved} (${sizing.basis})`);
+
   const tmp = mkdtempSync(join(tmpdir(), 'cli-run-'));
   const before = opts.expectFile ? snapshotFile(resolve(opts.expectFile)) : null;
   try {

package/bin/cli.js

@@ -22,8 +22,8 @@ import { windowsSpawnPlan } from './cli-run.mjs';
 // errors (exit 2) before anything is planned, so a typo like --dryy can never
 // turn a dry run into a real one.
 const SPEC = {
-  level: 'value', ais: 'value', primary: 'value', dir: 'value', project: 'value', tools: 'value', apis: 'value',
-  yes: 'bool', force: 'bool', dry: 'bool', 'dry-run': 'bool', 'no-install': 'bool', 'no-tools': 'bool', 'no-apis': 'bool', 'upgrade-runtime': 'bool', 'update-docs': 'bool', list: 'bool', help: 'bool', h: 'bool', version: 'bool', v: 'bool'
+  level: 'value', ais: 'value', primary: 'value', dir: 'value', project: 'value', tools: 'value', apis: 'value', plans: 'value',
+  yes: 'bool', force: 'bool', dry: 'bool', 'dry-run': 'bool', 'no-install': 'bool', 'no-tools': 'bool', 'no-apis': 'bool', 'effort-auto': 'bool', 'upgrade-runtime': 'bool', 'update-docs': 'bool', list: 'bool', help: 'bool', h: 'bool', version: 'bool', v: 'bool'
 };
 export function parseArgs(argv) {
   const out = {};
@@ -104,6 +104,8 @@ Flags
   --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.
+  --plans a=plan,b=plan  stated subscription plans for guidance; --plans none clears prior stated plans
+  --effort-auto      consent to write auto effort defaults for selected high or max plan cli-run lanes
   --dir path         where to write the docs and protocols (default ./ai-orchestrator)
   --project path     the project root your agent runs from; subagent definitions go here (default: current directory,
                      so set it: a run from your home folder otherwise drops the subagent files there)
@@ -129,6 +131,7 @@ if (flag('list')) {
   for (const a of AIS) {
     const here = a.bin ? (which(a.bin) ? 'installed' : 'not on PATH') : 'app';
     console.log(`${a.id.padEnd(13)} ${a.name}\n${''.padEnd(13)} level ${a.minLevel}+ · ${a.access} · ${here}\n${''.padEnd(13)} ${a.role}`);
+    if (a.plans) for (const p of a.plans) console.log(`${''.padEnd(13)} plan ${p.id}: ${p.name} (${p.headroom} headroom, checked ${p.checked}, ${p.source})`);
   }
   console.log('\nmetered API providers (--apis a,b, level 3 gateway only):');
   for (const prov of PROVIDERS) console.log(`${prov.id.padEnd(13)} ${prov.name}  (variable name: ${prov.envName})`);
@@ -146,6 +149,29 @@ function bad(msg) {
   process.exit(2);
 }
 
+function plansFromIds(raw, selected) {
+  if (raw === 'none') return {};
+  const out = {};
+  for (const part of raw.split(',')) {
+    const [id, plan, ...extra] = part.split('=');
+    if (!id || !plan || extra.length) bad(`--plans entry must be AI=plan: ${part}`);
+    if (Object.hasOwn(out, id)) bad(`--plans names ${id} more than once`);
+    const ai = byId[id];
+    if (!ai) bad(`--plans names unknown AI id: ${id}`);
+    if (!selected.includes(ai)) bad(`--plans names ${id}, which is not selected`);
+    const found = (ai.plans || []).find((p) => p.id === plan);
+    if (!found) bad(`--plans names unknown plan ${plan} for ${id}`);
+    out[id] = found;
+  }
+  return Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function plansFromManifest(manifest, selected) {
+  const raw = manifest && manifest.plans;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
+  return plansFromIds(Object.entries(raw).map(([id, plan]) => `${id}=${plan}`).join(','), selected);
+}
+
 async function main() {
   // Says what this generates, not what it guarantees. The old line promised
   // routing this package does not perform: lane choice is an instruction an
@@ -278,11 +304,51 @@ async function main() {
   const projectBad = dirProblems(project);
   if (projectBad.length) bad('--project: ' + projectBad.join('; '));
 
+  // A prior manifest is read before planning so an omitted reconfiguration
+  // preserves consent and stated plans instead of silently clearing either.
+  const prev = readManifest(dir);
+  let plans;
+  let plansKept = false;
+  if (opt('plans') !== null) {
+    plans = plansFromIds(opt('plans'), selected);
+  } else if (prev) {
+    plans = plansFromManifest(prev, selected);
+    plansKept = Object.keys(plans).length > 0;
+  } else if (!yes) {
+    plans = {};
+    for (const ai of selected.filter((a) => a.plans)) {
+      const first = ai.plans[0];
+      console.log(`\nWhich ${ai.vendor} plan? (checked ${first.checked}, source ${first.source})`);
+      ai.plans.forEach((p, i) => console.log(`  ${i + 1}  ${p.name} (${p.headroom} headroom)`));
+      console.log(`  ${ai.plans.length + 1}  not sure`);
+      const answer = Number(await ask(`Plan [${ai.plans.length + 1}]: `, String(ai.plans.length + 1)));
+      if (!Number.isInteger(answer) || answer < 1 || answer > ai.plans.length + 1) bad('pick a listed plan number');
+      if (answer <= ai.plans.length) plans[ai.id] = ai.plans[answer - 1];
+    }
+  } else {
+    plans = {};
+  }
+
+  const eligibleAuto = selected.filter((a) => a.cliRun && plans[a.id] && ['high', 'max'].includes(plans[a.id].headroom)).map((a) => a.id).sort();
+  let effortAuto;
+  if (flag('effort-auto')) {
+    effortAuto = eligibleAuto;
+  } else if (prev && Array.isArray(prev.effortAuto)) {
+    effortAuto = prev.effortAuto.filter((id) => selected.some((a) => a.id === id && a.cliRun));
+  } else if (!yes && eligibleAuto.length) {
+    const answer = await ask(`\nSize reasoning effort per task automatically on ${eligibleAuto.join(', ')}? [y/N] `, 'n');
+    effortAuto = /^y/i.test(answer) ? eligibleAuto : [];
+  } else {
+    effortAuto = [];
+  }
+
   // 5. Plan
-  const files = planFiles({ level, selected, primary, dir, project, tools, apis });
+  const files = planFiles({ level, selected, primary, dir, project, tools, apis, plans, effortAuto });
   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'}${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}`);
+  const statedPlans = Object.entries(plans).map(([id, p]) => `${id}=${p.id}`).join(', ');
+  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'}\n  plans    ${statedPlans || 'none stated'}` + (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 (plansKept) console.log('  plans kept from the previous run');
   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.`);
   }
@@ -303,10 +369,11 @@ async function main() {
   }
 
   // Reconfiguration: compare what a previous run recorded with what was asked now.
-  const prev = readManifest(dir);
   const changed = prev
     ? ['level', 'primary'].filter((k) => String(prev[k]) !== String(k === 'level' ? level : primary ? primary.id : null))
         .concat(['ais', 'tools', 'apis'].filter((k) => JSON.stringify(prev[k] || []) !== JSON.stringify({ ais: selected, tools, apis }[k].map((x) => x.id))))
+        .concat(JSON.stringify(prev.plans || {}) !== JSON.stringify(Object.fromEntries(Object.entries(plans).map(([id, p]) => [id, p.id]))) ? ['plans'] : [])
+        .concat(JSON.stringify((prev.effortAuto || []).slice().sort()) !== JSON.stringify(effortAuto.slice().sort()) ? ['effortAuto'] : [])
     : [];
 
   let written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable;

package/docs/catalog.md

@@ -19,6 +19,10 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Install:** `npm install -g @anthropic-ai/claude-code@2.1.226`
 - **Sign in:** run `claude` once and sign in with your Anthropic account
 - **Reads rules from:** `CLAUDE.md` · subagents in `.claude/agents/`
+- **Plans:**
+  - Claude Pro (base headroom, checked 2026-09-12): https://support.claude.com/en/articles/11049762-choose-a-claude-plan
+  - Claude Max 5x (high headroom, checked 2026-09-12): https://support.claude.com/en/articles/11049762-choose-a-claude-plan
+  - Claude Max 20x (max headroom, checked 2026-09-12): https://support.claude.com/en/articles/11049762-choose-a-claude-plan
 - **Built against:** 2.1.226 (the same number the npm pin uses)
 
 ### `codex` · Codex CLI (OpenAI, ChatGPT plan)
@@ -29,6 +33,10 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Sign in:** `codex login` (add `--device-auth` on a machine with no browser)
 - **Reads rules from:** `AGENTS.md`
 - **cli-run lane:** yes
+- **Plans:**
+  - ChatGPT Plus (base headroom, checked 2026-09-12): https://learn.chatgpt.com/codex/pricing.md
+  - ChatGPT Pro 5x (high headroom, checked 2026-09-12): https://learn.chatgpt.com/codex/pricing.md
+  - ChatGPT Pro 20x (max headroom, checked 2026-09-12): https://learn.chatgpt.com/codex/pricing.md
 - **Built against:** 0.153.4 (the same number the npm pin uses)
 
 ### `agy` · Antigravity CLI `agy` (Google AI plan)
@@ -39,6 +47,10 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Sign in:** first run opens a device-code sign-in with your Google account
 - **Reads rules from:** `GEMINI.md` · subagents in `.agents/agents/`
 - **cli-run lane:** yes
+- **Plans:**
+  - Google AI Pro (base headroom, checked 2026-09-12): https://gemini.google/subscriptions/
+  - Google AI Ultra 5x (high headroom, checked 2026-09-12): https://gemini.google/subscriptions/
+  - Google AI Ultra 20x (max headroom, checked 2026-09-12): https://gemini.google/subscriptions/
 - **Built against:** 1.1.27
 - **Note:** Gemini CLI was retired by Google in June 2026. agy is the successor. Do not install `gemini`.
 
@@ -49,6 +61,9 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Install:** vendor script (read it first): `https://x.ai/cli/install.sh`
 - **Sign in:** `grok login` (add `--device-auth` on a headless machine)
 - **cli-run lane:** yes
+- **Plans:**
+  - SuperGrok (base headroom, checked 2026-09-12): https://x.ai/news/grok-build-cli
+  - X Premium Plus (base headroom, checked 2026-09-12): https://x.ai/news/grok-build-cli
 - **Built against:** 1.0.5
 
 ### `hermes` · Hermes Agent (Nous Research)

package/docs/part-2-intermediate.md

@@ -2,6 +2,10 @@
 
 Everything in Part 1, plus lanes. One agent stays the orchestrator; every other AI becomes a lane it calls from the terminal.
 
+## Plans and automatic effort
+
+The installer can record plans with `--plans codex=pro-20x,agy=ultra-5x`. Plan headroom changes volume allocation only, never capability or the independent-review rule. `--effort-auto` is explicit consent to write `auto` for eligible high or max headroom CLI lanes. Auto resolves to medium or high from prompt size, and a codex audit is always high. It is a heuristic, not a measurement: name xhigh explicitly for security-critical or irreversible work.
+
 ## 1. Two kinds of lane
 
 **Lane A, subscription CLIs.** Claude Code, Codex, Antigravity, Grok, Hermes. Already paid for, $0 per call, used for interactive and agentic work. **Lane B, metered APIs.** Per token, used for programmatic bulk where a subscription CLI cannot serve. **Local.** A privacy lane, never a cost lane.

package/llms.txt

@@ -20,6 +20,10 @@ Claude Code plugin: `/plugin marketplace add aunysillyme/model-orchestrator`, th
 
 - [Claude Code plugin](https://github.com/aunysillyme/model-orchestrator/blob/main/plugin/README.md): installing the hooks and subagents with `/plugin install`, what the plugin reads, and what it leaves to the installer
 - [CLI runner](https://github.com/aunysillyme/model-orchestrator/blob/main/bin/README.md): `cli-run` lanes, exit codes, the route logged per run
+
+## Plans and automatic effort
+
+Use `--plans AI=plan` to state a subscription plan and receive volume-allocation guidance. `--effort-auto` is opt-in and writes bounded `auto` effort only for selected high or max headroom CLI lanes. Auto is medium or high, never above high; name xhigh explicitly for security-critical or irreversible work.
 - [Templates](https://github.com/aunysillyme/model-orchestrator/blob/main/templates/README.md): the routing, tiers, task bundle and protocol files the installer renders
 - [Changelog](https://github.com/aunysillyme/model-orchestrator/blob/main/CHANGELOG.md): every release and the issue behind each fix
 - [Agent instructions](https://github.com/aunysillyme/model-orchestrator/blob/main/AGENTS.md): running the installer from an agent, and contributing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Model orchestrator for AI coding agents and LLMs: Claude Code, Codex, Gemini, Grok, Qwen, Ollama. Routing rules tell your agent which model, subagent or CLI to use for each task, so small work goes to cheap tiers and fewer tokens go to frontier models. One installer, plus a CLI runner that logs every route.",
   "type": "module",
   "bin": {

package/scripts/gen-catalog.js

@@ -22,6 +22,10 @@ export function catalogMarkdown() {
     md += `### \`${a.id}\` · ${a.name}\n\n- **Kind:** ${a.kind} · **Access:** ${a.access} · **Lane:** ${a.lane} · **Level:** ${a.minLevel}+\n- **Wins at:** ${a.role}\n- **Install:** ${how}\n- **Sign in:** ${a.auth}\n`;
     if (a.rulesFile) md += `- **Reads rules from:** \`${a.rulesFile}\`` + (a.agentsDir ? ` · subagents in \`${a.agentsDir}/\`` : '') + '\n';
     if (a.cliRun) md += '- **cli-run lane:** yes\n';
+    if (a.plans) {
+      md += '- **Plans:**\n';
+      for (const p of a.plans) md += `  - ${p.name} (${p.headroom} headroom, checked ${p.checked}): ${p.source}\n`;
+    }
     if (a.builtAgainst) md += `- **Built against:** ${a.builtAgainst}` + (a.install.npm ? ' (the same number the npm pin uses)' : '') + '\n';
     if (a.note) md += `- **Note:** ${a.note}\n`;
     md += '\n';

package/src/catalog.js

@@ -27,6 +27,8 @@
 //              "(chat only, no CLI)" catalog note, so the activation line stays
 //              a sentence you can read once (#22)
 //   chatSurface chat apps only: where the pasted block goes in that app
+//   plans      optional known subscription plans: { id, name, headroom,
+//              source, checked }. Guidance uses headroom only, never prices.
 
 export const LEVELS = [
   {
@@ -70,6 +72,11 @@ export const AIS = [
     agentsDir: '.claude/agents',
     cliRun: false,
     models: { deep: 'opus', standard: 'sonnet', fast: 'haiku' },
+    plans: [
+      { id: 'pro', name: 'Claude Pro', headroom: 'base', source: 'https://support.claude.com/en/articles/11049762-choose-a-claude-plan', checked: '2026-09-12' },
+      { id: 'max-5x', name: 'Claude Max 5x', headroom: 'high', source: 'https://support.claude.com/en/articles/11049762-choose-a-claude-plan', checked: '2026-09-12' },
+      { id: 'max-20x', name: 'Claude Max 20x', headroom: 'max', source: 'https://support.claude.com/en/articles/11049762-choose-a-claude-plan', checked: '2026-09-12' }
+    ],
     // Verified at code.claude.com/docs/en/sub-agents (fetched 2026-09-10): "A
     // non-fork subagent's initial context contains: CLAUDE.md files: every
     // level of the CLAUDE.md hierarchy the main conversation loads ... The
@@ -95,6 +102,11 @@ export const AIS = [
     rulesFile: 'AGENTS.md',
     agentsDir: null,
     cliRun: true
+    , plans: [
+      { id: 'plus', name: 'ChatGPT Plus', headroom: 'base', source: 'https://learn.chatgpt.com/codex/pricing.md', checked: '2026-09-12' },
+      { id: 'pro-5x', name: 'ChatGPT Pro 5x', headroom: 'high', source: 'https://learn.chatgpt.com/codex/pricing.md', checked: '2026-09-12' },
+      { id: 'pro-20x', name: 'ChatGPT Pro 20x', headroom: 'max', source: 'https://learn.chatgpt.com/codex/pricing.md', checked: '2026-09-12' }
+    ]
   },
   {
     id: 'agy',
@@ -113,6 +125,11 @@ export const AIS = [
     agentsDir: '.agents/agents',
     cliRun: true,
     models: { deep: 'pro', standard: 'flash', fast: 'flash' },
+    plans: [
+      { id: 'ai-pro', name: 'Google AI Pro', headroom: 'base', source: 'https://gemini.google/subscriptions/', checked: '2026-09-12' },
+      { id: 'ultra-5x', name: 'Google AI Ultra 5x', headroom: 'high', source: 'https://gemini.google/subscriptions/', checked: '2026-09-12' },
+      { id: 'ultra-20x', name: 'Google AI Ultra 20x', headroom: 'max', source: 'https://gemini.google/subscriptions/', checked: '2026-09-12' }
+    ],
     note: 'Gemini CLI was retired by Google in June 2026. agy is the successor. Do not install `gemini`.'
   },
   {
@@ -131,6 +148,10 @@ export const AIS = [
     rulesFile: null,
     agentsDir: null,
     cliRun: true
+    , plans: [
+      { id: 'supergrok', name: 'SuperGrok', headroom: 'base', source: 'https://x.ai/news/grok-build-cli', checked: '2026-09-12' },
+      { id: 'x-premium-plus', name: 'X Premium Plus', headroom: 'base', source: 'https://x.ai/news/grok-build-cli', checked: '2026-09-12' }
+    ]
   },
   {
     id: 'hermes',

package/src/install.js

@@ -37,14 +37,26 @@ function table(rows, header) {
   return [line(header), line(header.map(() => '---')), ...rows.map(line)].join('\n');
 }
 
-export function lanesTable(selected) {
+export function lanesTable(selected, plans = {}) {
   const rows = selected.map((a) => [
     a.name,
     a.lane === 'A' ? 'A (subscription, $0 per call)' : a.lane === 'B' ? 'B (metered)' : a.lane === 'local' ? 'local' : 'chat',
     a.role,
-    a.cliRun ? '`cli-run ' + a.id + '`' : a.bin ? '`' + a.bin + '`' : 'the app'
+    a.cliRun ? '`cli-run ' + a.id + '`' : a.bin ? '`' + a.bin + '`' : 'the app',
+    plans[a.id] ? `${plans[a.id].name} (${plans[a.id].headroom} headroom)` : 'not stated'
   ]);
-  return table(rows, ['AI', 'Lane', 'Wins at', 'Call it with']);
+  return table(rows, ['AI', 'Lane', 'Wins at', 'Call it with', 'Plan']);
+}
+
+function planGuidance(selected, plans = {}) {
+  const lines = selected.filter((a) => plans[a.id]).map((a) => {
+    const p = plans[a.id];
+    const volume = p.headroom === 'base'
+      ? 'Keep this base-headroom lane for short second opinions. If it is primary, delegate volume to high or max headroom lanes.'
+      : 'Use this high or max headroom lane for volume: scoped well-specified builds, pre-ship second-family checks through cli-run, and first-pass research.';
+    return `- **${a.name}: ${p.name} (${p.headroom} headroom).** ${volume} Capability and independent-review rules are unchanged. Checked ${p.checked}.`;
+  });
+  return lines.length ? lines.join('\n') : 'State subscription plans with `--plans` to receive volume-allocation guidance. Capability and independent-review rules stay unchanged.';
 }
 
 export function installTable(selected) {
@@ -398,6 +410,7 @@ export function proofSteps(opts) {
 
 function vars(opts) {
   const { level, selected, primary } = opts;
+  const plans = opts.plans || {};
   const tools = opts.tools || [];
   const apis = opts.apis || [];
   const lvl = LEVELS.find((l) => l.id === level);
@@ -506,7 +519,8 @@ function vars(opts) {
     PRIMARY_FAST: primary && primary.models ? primary.models.fast : 'your cheapest model',
     AIS_LIST: selected.map((a) => '- ' + a.name + ': ' + a.role).join('\n'),
     AI_IDS: selected.map((a) => a.id).join(','),
-    LANES_TABLE: lanesTable(selected),
+    LANES_TABLE: lanesTable(selected, plans),
+    PLAN_GUIDANCE: planGuidance(selected, plans),
     INSTALL_TABLE: installTable(selected),
     CLI_RUN_LANES: selected.filter((a) => a.cliRun).map((a) => a.id).join(', ') || 'none selected',
     GATEWAY_MODELS: gatewayModels(selected, apis),
@@ -605,7 +619,7 @@ export function planFiles(opts) {
       JSON.stringify(
         {
           enabled: selected.filter((a) => a.cliRun).map((a) => a.id),
-          defaults: {},
+          defaults: Object.fromEntries((opts.effortAuto || []).map((lane) => [lane, { effort: 'auto' }])),
           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.'
         },
@@ -640,6 +654,8 @@ export function planFiles(opts) {
           primary: primary ? primary.id : null,
           tools: (opts.tools || []).map((t) => t.id),
           apis: (opts.apis || []).map((p) => p.id),
+          ...(Object.keys(opts.plans || {}).length ? { plans: Object.fromEntries(Object.entries(opts.plans).sort(([a], [b]) => a.localeCompare(b)).map(([id, p]) => [id, p.id])) } : {}),
+          ...((opts.effortAuto || []).length ? { effortAuto: [...opts.effortAuto].sort() } : {}),
           dir: resolve(opts.dir || 'ai-orchestrator'),
           project: resolve(opts.project || process.cwd()),
           files: fileHashes,

package/templates/intermediate/CLI-RUN.md

@@ -19,6 +19,7 @@ Enabled lanes (edit `bin/lanes.json`): {{CLI_RUN_LANES}}
 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
 ```
 
@@ -98,6 +99,7 @@ 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.
+- **`--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
@@ -106,7 +108,7 @@ Three rules that keep this honest:
 
 ## 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, 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".
+`~/.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`), 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.
 

package/templates/intermediate/DELEGATION_MATRIX.md

@@ -6,6 +6,10 @@ Generated {{DATE}} from the AIs you said you have: `{{AI_IDS}}`.
 
 {{LANES_TABLE}}
 
+## Plan guidance
+
+{{PLAN_GUIDANCE}}
+
 ## Task → lane
 
 | Task type | Pick | Why |

package/templates/intermediate/ROUTING.md

@@ -6,6 +6,10 @@ Your lanes:
 
 {{LANES_TABLE}}
 
+## Plan guidance
+
+{{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.
 
 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.

package/templates/intermediate/TIERS.md

@@ -15,6 +15,8 @@ Non-primary lanes are owned by `DELEGATION_MATRIX.md`.
 
 Tier sets the price per token. Token discipline sets how many tokens. **Effort sets how hard each call thinks.**
 
+`cli-run --effort auto` is a heuristic, not a measurement: prompts below 4,000 characters resolve to medium and longer prompts resolve to high. A codex `--audit` always resolves to high because stakes set the floor. Auto never resolves above high. Name `xhigh` explicitly for a security-critical or irreversible audit.
+
 | Agent | Tier | Effort | Why |
 |---|---|---|---|
 | deep-planner | deep | xhigh | judges every build twice; expensive to get wrong |