model-orchestrator 0.1.4

package/bin/cli.js

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+// model-orchestrator installer.
+// Asks which level you want and which AIs you have access to, then writes the
+// matching files into a folder. It never writes a secret, never runs a vendor
+// shell script, and never overwrites a file you already have unless --force.
+
+import { stdin, stdout } from 'node:process';
+import { makeAsker } from '../src/prompt.js';
+import { spawnSync } from 'node:child_process';
+import { resolve, join } from 'node:path';
+import { which } from '../src/detect.js';
+import { AIS, LEVELS, TOOLS, PROVIDERS, aisForLevel, agentCandidates, byId, npmSpec } from '../src/catalog.js';
+import { planFiles, writeFiles, resolveSelection, resolveTools, resolveApis, dirProblems, readManifest, MACHINE_OWNED, RUNTIME, GENERATOR_VERSION } from '../src/install.js';
+
+// One strict parse. Unknown flags, missing values and duplicates are usage
+// 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', 'no-install': 'bool', 'no-tools': 'bool', 'no-apis': 'bool', 'upgrade-runtime': 'bool', 'update-docs': 'bool', list: 'bool', help: 'bool', h: 'bool'
+};
+export function parseArgs(argv) {
+  const out = {};
+  const errors = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) {
+      errors.push(`unexpected argument: ${a}`);
+      continue;
+    }
+    let name = a.slice(2);
+    let inline = null;
+    const eq = name.indexOf('=');
+    if (eq !== -1) {
+      inline = name.slice(eq + 1);
+      name = name.slice(0, eq);
+    }
+    const kind = SPEC[name];
+    if (!kind) {
+      errors.push(`unknown flag: --${name}`);
+      continue;
+    }
+    if (name in out) errors.push(`--${name} given more than once`);
+    if (kind === 'bool') {
+      if (inline !== null) errors.push(`--${name} takes no value`);
+      out[name] = true;
+    } else {
+      let v = inline;
+      if (v === null) {
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+          errors.push(`--${name} requires a value`);
+          continue;
+        }
+        v = next;
+        i++;
+      }
+      if (v === '') errors.push(`--${name} requires a non-empty value`);
+      out[name] = v;
+    }
+  }
+  return { out, errors };
+}
+const parsed = parseArgs(process.argv.slice(2));
+if (parsed.errors.length) {
+  console.error('model-orchestrator: ' + parsed.errors.join('; ') + '\nrun with --help');
+  process.exit(2);
+}
+const flag = (name) => parsed.out[name] === true;
+const opt = (name) => (typeof parsed.out[name] === 'string' ? parsed.out[name] : null);
+
+if (flag('help') || flag('h')) {
+  console.log(`model-orchestrator: set up a model orchestrator for the AIs you actually have.
+
+Usage
+  npx model-orchestrator                      interactive
+  npx model-orchestrator --list               show the AI catalog and exit
+  npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok [--primary claude-code] [--dir ./ai-orchestrator]
+
+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)
+  --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.
+  --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)
+  --yes              skip confirmations
+  --force            overwrite every file that already exists, documents included
+  --upgrade-runtime  replace the runtime files (cli-run, the audit job, compose, gateway config, setup script) even
+                     when they cannot be verified as untouched; documents are still kept
+  --update-docs      regenerate the documents a previous run wrote and nobody edited since (hash-checked against
+                     MANIFEST.json), so a changed selection reaches ROUTING.md and friends; edited documents are kept
+                     and reported, and nothing happens without a manifest
+  --dry              print the plan, write nothing
+  --no-install       never offer to run npm installs
+  --list             print the catalog
+`);
+  process.exit(0);
+}
+
+if (flag('list')) {
+  for (const l of LEVELS) console.log(`level ${l.id}  ${l.name}: ${l.tagline}`);
+  console.log('');
+  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}`);
+  }
+  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})`);
+  console.log('\ncompanion tools (--tools a,b), all optional:');
+  for (const t of TOOLS) console.log(`${t.id.padEnd(13)} ${t.name}\n${''.padEnd(13)} ${t.role}\n${''.padEnd(13)} needs: ${t.requires}\n${''.padEnd(13)} ${t.optionalNote}\n${''.padEnd(13)} ${t.repo}`);
+  process.exit(0);
+}
+
+const yes = flag('yes');
+const rl = yes ? null : makeAsker({ input: stdin, output: stdout });
+const ask = (q, fallback) => (rl ? rl.ask(q, fallback) : Promise.resolve(fallback));
+
+function bad(msg) {
+  console.error('model-orchestrator: ' + msg);
+  process.exit(2);
+}
+
+async function main() {
+  console.log('\nmodel-orchestrator\nRoute every task to the cheapest AI that does it well.\n');
+
+  // 1. Level
+  let level = Number(opt('level'));
+  if (![1, 2, 3].includes(level)) {
+    if (yes) bad('--level must be 1, 2 or 3 when --yes is set');
+    console.log('Which level?');
+    for (const l of LEVELS) console.log(`  ${l.id}  ${l.name}: ${l.tagline}`);
+    level = Number(await ask('\nLevel [1]: ', '1'));
+    if (![1, 2, 3].includes(level)) bad('level must be 1, 2 or 3');
+  }
+
+  // 2. Access
+  const available = aisForLevel(level);
+  let ids;
+  if (opt('ais')) {
+    ids = opt('ais').split(',').map((s) => s.trim()).filter(Boolean);
+  } else {
+    if (yes) bad('--ais is required with --yes (comma-separated ids, see --list)');
+    console.log('\nWhich AIs do you have access to? (numbers, comma-separated; detected ones are marked)');
+    available.forEach((a, i) => {
+      const mark = a.bin && which(a.bin) ? '*' : ' ';
+      console.log(`  ${String(i + 1).padStart(2)} ${mark} ${a.name}`);
+    });
+    const detected = available.map((a, i) => (a.bin && which(a.bin) ? i + 1 : null)).filter(Boolean);
+    const fallback = detected.join(',');
+    const answer = await ask(`\nYour picks${fallback ? ' [' + fallback + ']' : ''}: `, fallback);
+    ids = answer
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .map((n) => {
+        const a = available[Number(n) - 1];
+        if (!a) bad(`no AI numbered ${n}`);
+        return a.id;
+      });
+  }
+  const { selected, unknown } = resolveSelection(ids);
+  if (unknown.length) bad('unknown AI id(s): ' + unknown.join(', ') + ' (see --list)');
+  if (!selected.length) bad('pick at least one AI');
+  const tooHigh = selected.filter((a) => a.minLevel > level);
+  if (tooHigh.length) bad(`${tooHigh.map((a) => a.id).join(', ')} need level ${Math.max(...tooHigh.map((a) => a.minLevel))} or higher`);
+
+  // 3. Primary agent (the one that runs the system)
+  const candidates = agentCandidates(selected);
+  let primary = null;
+  if (opt('primary')) {
+    primary = byId[opt('primary')];
+    if (!primary || !candidates.includes(primary)) bad('--primary must be one of: ' + candidates.map((a) => a.id).join(', '));
+  } else if (candidates.length === 1) {
+    primary = candidates[0];
+  } else if (candidates.length === 0) {
+    bad('pick at least one agent or chat app to be the orchestrator; a local model runtime on its own cannot run the system');
+  } else if (candidates.length > 1) {
+    if (yes) primary = candidates.find((a) => a.id === 'claude-code') || candidates[0];
+    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}`));
+      const n = Number(await ask('\nPrimary [1]: ', '1'));
+      primary = candidates[n - 1];
+      if (!primary) bad('pick a listed number');
+    }
+  }
+
+  // 3b. Companion tools (not AIs: things the AIs call)
+  let tools = [];
+  if (flag('no-tools') && opt('tools')) bad('--no-tools and --tools contradict each other');
+  if (!flag('no-tools')) {
+    if (opt('tools')) {
+      const r = resolveTools(opt('tools').split(',').map((s) => s.trim()).filter(Boolean));
+      if (r.unknown.length) bad('unknown tool id(s): ' + r.unknown.join(', ') + ' (see --list)');
+      tools = r.tools;
+    } else if (yes) {
+      tools = TOOLS.filter((t) => t.recommended);
+    } else {
+      console.log('\nCompanion tools (all optional): things your agents call. Selecting one writes docs and config snippets; it installs nothing.');
+      for (const t of TOOLS) {
+        console.log(`\n  ${t.id}: ${t.role}\n    ${t.repo}\n    needs: ${t.requires}\n    ${t.optionalNote}`);
+        const def = t.recommended ? 'y' : 'n';
+        const a = await ask(`  Set up ${t.id}? [${t.recommended ? 'Y/n' : 'y/N'}]: `, def);
+        if (/^y/i.test(a)) tools.push(t);
+      }
+    }
+  }
+
+  // 3c. Level 3: which metered API keys the user HOLDS. Separate from the CLI
+  // question on purpose: a Claude Code plan is not an Anthropic API key.
+  let apis = [];
+  if (flag('no-apis') && opt('apis')) bad('--no-apis and --apis contradict each other');
+  if (level >= 3 && !flag('no-apis')) {
+    if (opt('apis')) {
+      const r = resolveApis(opt('apis').split(',').map((s) => s.trim()).filter(Boolean));
+      if (r.unknown.length) bad('unknown provider id(s): ' + r.unknown.join(', ') + ' (see --list)');
+      apis = r.apis;
+    } else if (!yes) {
+      console.log('\nLevel 3 gateway: which metered API keys do you HOLD? (numbers, comma-separated, or none)');
+      console.log('  This is separate from the CLIs above: a subscription is not an API key. Only variable NAMES are written; you keep the values in your secrets manager.');
+      PROVIDERS.forEach((prov, i) => console.log(`  ${String(i + 1).padStart(2)}   ${prov.name}  (${prov.envName})`));
+      const a = await ask('\nYour keys [none]: ', '');
+      apis = a
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((n) => {
+          const prov = PROVIDERS[Number(n) - 1];
+          if (!prov) bad(`no provider numbered ${n}`);
+          return prov;
+        });
+    }
+  } else if (level < 3 && opt('apis')) {
+    bad('--apis only applies at level 3 (the gateway)');
+  }
+
+  // 4. Targets: the docs folder, and the project root the agent runs from
+  const dir = resolve(opt('dir') || (await ask('\nWrite docs and protocols into [./ai-orchestrator]: ', './ai-orchestrator')));
+  const dirBad = dirProblems(dir);
+  if (dirBad.length) bad(dirBad.join('; '));
+  const project = resolve(opt('project') || (primary && primary.agentsDir && !yes ? await ask(`\nProject root your agent runs from (subagents go in ${primary.agentsDir}/ there) [.]: `, '.') : '.'));
+  const projectBad = dirProblems(project);
+  if (projectBad.length) bad('--project: ' + projectBad.join('; '));
+
+  // 5. Plan
+  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}`);
+  if (flag('dry')) {
+    for (const f of files) console.log('  - ' + (f.root === 'project' ? '[project] ' : '') + f.rel);
+    console.log('\n--dry: nothing written.');
+    rl && rl.close();
+    return;
+  }
+  const go = yes ? 'y' : await ask('\nWrite these files? [Y/n]: ', 'y');
+  if (!/^y/i.test(go)) {
+    console.log('Nothing written.');
+    rl && rl.close();
+    return;
+  }
+
+  // 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))))
+    : [];
+
+  let written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable;
+  try {
+    ({ written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable } = writeFiles(files, { dir, project, force: flag('force'), upgradeRuntime: flag('upgrade-runtime'), updateDocs: flag('update-docs'), prevManifest: prev }));
+  } catch (e) {
+    if (e && e.code === 'PREFLIGHT') bad(e.message);
+    throw e;
+  }
+  const ownedWritten = written.filter((w) => MACHINE_OWNED.has(w));
+  console.log(`\nWrote ${written.length} file(s)` + (skipped.length ? `, kept ${skipped.length} existing:` : '.'));
+  for (const s of skipped) console.log('  kept ' + s);
+  const existingRuntime = files.filter((f) => f.root !== 'project' && RUNTIME.has(f.rel)).length;
+  if (prev || existingRuntime && (upgraded.length || conflicts.length || unverifiable.length) || docsUnverifiable.length) {
+    console.log(`\nExisting installation found${prev ? ` (MANIFEST.json from generator ${prev.generatorVersion || 'pre-0.1.1'}, ${prev.generatedAt || 'undated'}; this run is ${GENERATOR_VERSION})` : ' (no MANIFEST.json: it predates 0.1.1)'}.`);
+    if (prev) {
+      if (changed.length) {
+        console.log(`  selection changed: ${changed.join(', ')}`);
+        console.log(`  applied: ${ownedWritten.join(', ') || 'nothing'} (machine-owned files are always rewritten, so the new lanes are live)`);
+      } else console.log('  selection identical.');
+    }
+    if (upgraded.length) console.log(`  runtime upgraded: ${upgraded.join(', ')} ${flag('upgrade-runtime') ? '(--upgrade-runtime: replaced whether or not you had edited them)' : '(each installed copy matched the hash of a previous run, so nobody had edited it)'}`);
+    if (conflicts.length) {
+      console.log(`  runtime CONFLICT, kept: ${conflicts.join(', ')}`);
+      console.log('    these differ from what a previous run generated, so you edited them. The fixes in this release were NOT applied to them.');
+      console.log('    Options: move your copy aside and re-run; or --upgrade-runtime to replace runtime files only; or --force to replace everything.');
+    }
+    if (unverifiable.length) {
+      console.log(`  runtime kept, UNVERIFIABLE: ${unverifiable.join(', ')}`);
+      console.log('    the previous install left no manifest, so it is not possible to tell whether you edited these. Executable fixes were NOT applied.');
+      console.log('    Re-run with --upgrade-runtime to replace runtime files only (documents stay), or --force to replace everything.');
+    }
+    if (docsUpdated.length) console.log(`  documents updated: ${docsUpdated.join(', ')} (each matched the hash of a previous run, so nobody had edited them)`);
+    if (docsConflict.length) {
+      console.log(`  document CONFLICT, kept: ${docsConflict.join(', ')}`);
+      console.log('    these differ from what a previous run generated, so you edited them. Edit them by hand, or --force to replace everything.');
+    }
+    if (docsUnverifiable.length) {
+      console.log(`  documents kept, UNVERIFIABLE: ${docsUnverifiable.join(', ')}`);
+      console.log('    the previous install left no manifest, so --update-docs cannot tell your edits from generated text. --force replaces everything.');
+    }
+    if (skipped.length && prev && changed.length && !flag('update-docs')) console.log('  documents kept: they may describe the old selection. --update-docs regenerates the ones you have not edited; --force regenerates all of them (this overwrites your edits).');
+  }
+
+  // 6. Installs, opt-in per CLI, npm only. Vendor scripts are printed, never run.
+  const missing = selected.filter((a) => a.bin && !which(a.bin));
+  if (missing.length) {
+    console.log('\nNot found on this machine (presence is checked; installed versions are not validated):');
+    for (const a of missing) {
+      if (a.install.npm) {
+        const spec = npmSpec(a); // the same pinned spec the table and the box script use
+        const run = flag('no-install') || yes ? 'n' : await ask(`  ${a.name}: run \`npm install -g ${spec}\` now? [y/N]: `, 'n');
+        if (/^y/i.test(run)) {
+          const r = spawnSync('npm', ['install', '-g', spec], { stdio: 'inherit' });
+          console.log(r.status === 0 ? `  installed ${spec}` : `  npm exited ${r.status}; install it by hand`);
+        } else {
+          console.log(`  ${a.name}: npm install -g ${spec}   (pinned to the version this installer was released with)`);
+        }
+      } else if (a.install.script) {
+        console.log(`  ${a.name}: the vendor installer is a shell script. Download it, read it, then run it:\n      curl -fsSL ${a.install.script} -o /tmp/${a.id}-install.sh && less /tmp/${a.id}-install.sh && bash /tmp/${a.id}-install.sh`);
+      } else {
+        console.log(`  ${a.name}: ${a.install.url}` + (a.install.brew ? `  (or: brew install ${a.install.brew})` : ''));
+      }
+      console.log(`      sign in: ${a.auth}`);
+    }
+  }
+
+  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}`);
+  }
+
+  // 7. Activation summary: writing the folder is half the job. Say exactly what
+  // turns it on, in order, with one command that proves it.
+  const snippet = files.find((f) => /\.snippet\.md$|^PASTE-INTO-YOUR-AGENT\.md$/.test(f.rel));
+  const steps = [];
+  if (snippet && primary && primary.rulesFile) steps.push(`copy the block in ${join(dir, snippet.rel)} into ${join(project, primary.rulesFile)} (create it if missing)`);
+  else if (snippet) steps.push(`paste ${join(dir, snippet.rel)} into ${primary.name}'s custom instructions or Project`);
+  if (primary && primary.agentsDir) steps.push(`subagents are in ${join(project, primary.agentsDir)}; run ${primary.bin} from ${project} 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}`);
+  for (const t of tools) steps.push(`${t.id}: ${t.install}`);
+  if (level >= 2) steps.push(`smoke test: node ${join(dir, 'bin', 'cli-run.mjs')} --doctor   (add --run to send each lane one tiny prompt)`);
+  if (level >= 3) steps.push(`box: read ${join(dir, 'vm', 'README.md')}; keys named in vm/ENVIRONMENT.md go in your secrets manager, never a file`);
+  console.log('\nTo activate, in order:');
+  steps.forEach((st, i) => console.log(`  ${i + 1}. ${st}`));
+  console.log(`\nStart here: ${join(dir, 'README.md')} (written for level ${level} and the AIs you picked).\n`);
+  rl && rl.close();
+}
+
+import { realpathSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+function isEntryPoint() {
+  try {
+    return pathToFileURL(realpathSync(process.argv[1])).href === pathToFileURL(realpathSync(fileURLToPath(import.meta.url))).href;
+  } catch {
+    return false;
+  }
+}
+if (isEntryPoint()) main().catch((e) => {
+  console.error('model-orchestrator: ' + (e && e.message ? e.message : e));
+  process.exit(e && e.code === 'EOF' ? 2 : 1);
+});

package/docs/README.md

@@ -0,0 +1,13 @@
+# docs/
+
+The three parts, as reading. The installer writes the working files; these explain the thinking behind them and how to grow from one level to the next.
+
+| Part | Read if | File |
+|---|---|---|
+| 1 Beginner | you use one LLM or one agent and want it to route well | [part-1-beginner.md](part-1-beginner.md) |
+| 2 Intermediate | you have several AIs and want to call them through their CLIs from one orchestrator | [part-2-intermediate.md](part-2-intermediate.md) |
+| 3 Advanced | you want the whole thing running unattended on a virtual machine | [part-3-advanced.md](part-3-advanced.md) |
+| Audit brief | the threat model and the two adversarial audit rounds this shipped with | [audit-brief.md](audit-brief.md) |
+| Catalog | what each AI and companion tool in the installer is for, how it installs, how it signs in | [catalog.md](catalog.md) |
+
+Each part ends with "what the installer gives you at this level" so the doc and the files agree.

package/docs/audit-brief.md

@@ -0,0 +1,83 @@
+# AUDIT_BRIEF.md: adversarial audit of model-orchestrator (round 1)
+
+> Historical document. Counts in it (tests, files) are as of the round they describe; `npm test` prints the current number.
+
+Read-only audit. Report findings only; do not modify files. Rank by severity. For each finding: file, line, what breaks, a concrete reproduction. `CLEAN` is a valid answer for any area with no reproducible finding. Skip style.
+
+## Task bundle
+
+**Purpose.** Adversarial, read-only audit of this npm package before it is published, so that reproducible defects are fixed before strangers run it.
+**Task class.** read_only
+
+**Granted scope.**
+- Every file under this repository root: `bin/`, `src/`, `templates/`, `test/`, `scripts/`, `docs/`, `package.json`, `README.md`.
+- Anything outside this repository is out of scope. Do not widen it on your own judgment.
+
+**Capabilities.** read files, run `npm test`, run `node bin/cli.js` with `--dry`, run `node bin/cli-run.mjs` with bad arguments, run scripts against a temp directory under /tmp.
+
+**Denied actions.** Do not modify, create or delete any file in this repository. Do not run `npm install -g`. Do not run any vendor installer. Do not commit, push, or publish. Do not read files outside this repository except /tmp scratch you created. Do not call any network service.
+- Anything absent from Capabilities is denied. Absence is not permission.
+
+**Conventions you do not have.** Report in plain prose with a findings list. No style nitpicks. `CLEAN` is a valid verdict per area. Every finding needs a concrete reproduction (command + observed vs expected). Never print a value that looks like a credential.
+
+**Report contract.** Return: a severity-ranked list of findings (file, line, what breaks, reproduction, suggested fix in one or two sentences), then a `CLEAN` line for each area in "Attack these" that had no reproducible finding, then a short "not covered" list naming anything you did not check or could not verify.
+
+**Exit parameters.** Stop after 12 minutes of wall clock or after reading every file once and running at most 30 commands, whichever comes first. If you hit a bound, report what you have and name what you did not cover. Never return nothing.
+
+## What this is
+An npm package (`npx model-orchestrator`) that asks a user which level (1/2/3) and which AIs they have access to, then writes markdown + config templates into a folder, and optionally runs `npm install -g <pkg>` for known packages after an explicit per-package yes. It also ships `bin/cli-run.mjs`, a wrapper that runs one of five agent CLIs (grok, codex, agy, hermes, qwen) and exits non-zero unless the lane produced a deliverable.
+
+## Runtime
+Node >= 18, ESM, zero dependencies. Runs on a stranger's laptop (macOS/Linux) with their PATH and HOME. Level 3 writes shell/systemd/compose templates the user will run on a Linux box.
+
+## Threat model
+- The user is not an adversary but is careless: runs it in the wrong directory, passes odd flags, has files with the same names.
+- Untrusted input reaches `cli-run.mjs` through CLI stdout (JSON from third-party binaries) and through `lanes.json` on disk.
+- The installer must never: write a secret value anywhere, overwrite a user file without --force, run a remote shell script, escape the target dir (path traversal via template rel paths or --dir), or leave a placeholder unrendered.
+- `cli-run.mjs` must never: throw on malformed CLI output (a throw is misreported as a usage error), pass a secret in argv, leave temp files, hang on stdin, or report success without a deliverable.
+- Generated templates (`vm/setup-vm.sh`, `vm/jobs/weekly-audit.sh`, `docker-compose.yml`, `gateway.config.yaml`) must not put a key in argv, bind to 0.0.0.0, or pipe a remote script into bash.
+
+## Already verified (do not repeat)
+- 60 node --test cases pass, including every judge's failure shapes and a mutation check that turns one case red.
+- Placeholders: every template renders for every level and primary without a leftover `{{KEY}}`.
+- README inside `.claude/agents/` is not installed.
+
+## Attack these
+1. `bin/cli.js` argument parsing: `opt()` takes the next argv token; what happens with `--dir --force`, `--ais ""`, duplicate flags, `--level 2.5`, unicode, a `--dir` that is a file, a `--dir` of `/`?
+2. `src/install.js` `writeFiles`: path traversal if a template rel path or the --dir resolves outside; symlink in the target dir; mode handling on Windows; partial writes.
+3. `src/detect.js` `which`: PATH entries that are files, empty PATH, relative PATH entries, a directory named like the binary.
+4. `bin/cli-run.mjs`: `jsonLines` on huge output; `maxBuffer`; `spawnSync` with `timeout` and `killSignal` behaviour; `enabledLanes()` with a malicious lanes.json; `--brief` pointing at a directory or a huge file; prompt containing newlines; the codex `-o` temp file when the CLI writes elsewhere; the `import.meta.url === pathToFileURL(argv[1])` main guard when invoked via a symlink; rc pass-through logic (`if (r.status !== 0 && code === OK) code = r.status`).
+5. Templates: `vm/setup-vm.sh` (set -euo pipefail, the for loop over {{NPM_PACKAGES}} when empty), `vm/jobs/weekly-audit.sh` (curl --config - header injection if GATEWAY_MASTER_KEY contains a quote or newline), `docker-compose.yml` env pass-through, systemd unit paths.
+6. Anything that could make the installer write outside `--dir` or read a file it should not.
+
+## Design decisions to challenge, with reasoning
+- Zero dependencies (no inquirer): smaller audit surface, but the prompt code is hand-rolled. Is the readline path safe with piped stdin and EOF?
+- Vendor scripts are printed, never run: correct? Or does printing `curl | bash` still encourage the unsafe pattern?
+- `npm install -g` is run after a per-package yes, with the package name from the catalog (never user input). Confirm user input cannot reach that argv.
+- `writeFiles` refuses existing files unless --force but does not check that the target is inside cwd. Deliberate (users may want `~/project`). Is there a traversal risk from template names?
+
+## How to run
+`npm test` · `node bin/cli.js --help` · `node bin/cli.js --yes --level 3 --ais claude-code,codex,agy,grok,hermes,qwen,ollama --dir /tmp/x --dry`
+
+## ROUND 2 (after round-1 fixes)
+
+Re-audit the same scope. Every round-1 finding was reproduced before it was touched. What changed:
+
+| # | Finding | Change |
+|---|---|---|
+| 1 | writeFiles escape / symlink follow | `preflight()` in `src/install.js`: containment under the resolved root, lstat every existing component (symlink or non-directory parent refused), exclusive `wx` create unless `--force`, rollback of files this run created if a later write fails. Tests: escape, symlinked component, conflicting parent leaves nothing behind. Mutation-checked. |
+| 2 | prompt in argv + logged head | argv kept (each vendor's documented headless shape); DEFERRED as a vendor constraint, documented in `CLI-RUN.md` and the file header (no secrets in prompts, ARG_MAX, reference big briefs by path). Log now stores a 12-hex sha256 prefix and length, never text. Test: marker absent from log. |
+| 3 | unknown flags / missing values | strict `parseArgs` in `bin/cli.js`: unknown flag, missing value, empty value, duplicate, positional → exit 2 before planning. Tests for each. |
+| 4 | audit job hardcoded hermes | `auditLane()` picks the first ENABLED cli-run lane (hermes, qwen, codex, agy, grok); none → rendered guard exits 13. Tests. |
+| 5 | audit never received live state | script composes `reports/audit-brief-<date>.md` = task bundle + protocol + DELEGATION_MATRIX + live-state, and passes THAT as `--brief`. Test. |
+| 6 | `--dir` ignored by systemd paths | `INSTALL_DIR` rendered into the service and the script from the resolved `--dir`. Test. |
+| 7 | curl config injection | script refuses a key not matching `^[A-Za-z0-9._-]+$` (exit 2) before any curl; documented in ENVIRONMENT.md and vm/README. Test executes the rendered script with an injecting key. |
+| 8 | malformed lanes.json fail-open | `enabledLanes()` returns null on present-but-invalid; main refuses every lane (13) and says so. Test proves no spawn happens. |
+| 9 | signal → exit 0 | `r.signal || r.status === null` → verdict killed, exit 10, partial output discarded. Test. |
+| 10 | partial install | covered by preflight + rollback (finding 1). Test. |
+| 11 | directory detected as binary | `isFile()` check in both `which()` implementations. Test. |
+| 12 | `curl \| bash` printed | download / read / run form printed instead. |
+
+Also new since round 1: the companion-tool path (`--tools codecalc`, `--no-tools`, `templates/tools/codecalc/`, `protocols/numbers-and-logic.md`, `resolveTools`). Attack it the same way: unknown tool ids, interaction with `--yes`, the extra interactive question, and whether any written snippet could be confused for a file the installer should not touch.
+
+Report only what reproduces on the current tree. `CLEAN` per area is expected where the fix holds.

package/docs/catalog.md

@@ -0,0 +1,113 @@
+# Catalog
+
+Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrites it. Protocols shipped at every level: 6 (counted from `templates/common/protocols/`).
+
+## Levels
+
+| Level | Name | Tagline | Gives |
+|---|---|---|---|
+| 1 | Beginner | one LLM or agent, routed well | tiers, task classification, every protocol, one agent set up to follow them |
+| 2 | Intermediate | several LLMs and agents, called through their CLIs | everything in Beginner plus cli-run, a delegation matrix, task bundles and three-engine research triage |
+| 3 | Advanced | everything above, plus a virtual machine that runs it unattended | everything in Intermediate plus a gateway config, scheduled jobs, a dispatch layer and privacy gates for a box |
+
+## AIs
+
+### `claude-code` · Claude Code (Anthropic)
+
+- **Kind:** agent-cli · **Access:** subscription · **Lane:** A · **Level:** 1+
+- **Wins at:** orchestrator: routes, maps, builds, verifies, records
+- **Install:** `npm install -g @anthropic-ai/claude-code@2.1.260`
+- **Sign in:** run `claude` once and sign in with your Anthropic account
+- **Reads rules from:** `CLAUDE.md` · subagents in `.claude/agents/`
+
+### `codex` · Codex CLI (OpenAI, ChatGPT plan)
+
+- **Kind:** agent-cli · **Access:** subscription · **Lane:** A · **Level:** 1+
+- **Wins at:** second coder and adversarial auditor (a different model family reading your diff)
+- **Install:** `npm install -g @openai/codex@0.153.2`
+- **Sign in:** `codex login` (add `--device-auth` on a machine with no browser)
+- **Reads rules from:** `AGENTS.md`
+- **cli-run lane:** yes
+
+### `agy` · Antigravity CLI `agy` (Google AI plan)
+
+- **Kind:** agent-cli · **Access:** subscription · **Lane:** A · **Level:** 1+
+- **Wins at:** deep research sweeps and concurrent fan-out (its subagent call takes an array)
+- **Install:** vendor script (read it first): `https://antigravity.google/cli/install.sh`
+- **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
+- **Note:** Gemini CLI was retired by Google in June 2026. agy is the successor. Do not install `gemini`.
+
+### `grok` · Grok CLI (xAI, X Premium)
+
+- **Kind:** agent-cli · **Access:** subscription · **Lane:** A · **Level:** 1+
+- **Wins at:** X and live web reads at no per-call cost (its search tools bill on the API, not on the CLI)
+- **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
+
+### `hermes` · Hermes Agent (Nous Research)
+
+- **Kind:** agent-cli · **Access:** free · **Lane:** A · **Level:** 2+
+- **Wins at:** the free tier: rough drafts, first-pass summaries, cheap divergent reads, cron jobs on a box
+- **Install:** https://github.com/NousResearch/hermes-agent
+- **Sign in:** `hermes auth add <provider>` per provider; its own fallback chain handles outages
+- **cli-run lane:** yes
+
+### `qwen` · Qwen Code CLI (Alibaba, provider-agnostic)
+
+- **Kind:** agent-cli · **Access:** metered · **Lane:** B · **Level:** 2+
+- **Wins at:** cheapest metered bulk lane for structured output; never for anything that cites a line, a number or a source
+- **Install:** `npm install -g @qwen-code/qwen-code@0.23.0`
+- **Sign in:** a provider key in an environment variable, named (not stored) in ~/.qwen/settings.json. There is no free Qwen cloud tier any more.
+- **Reads rules from:** `QWEN.md`
+- **cli-run lane:** yes
+- **Note:** Its own success flags lie on API failures. cli-run checks the two honest signals for you.
+
+### `ollama` · Ollama (local models)
+
+- **Kind:** local · **Access:** local · **Lane:** local · **Level:** 2+
+- **Wins at:** the privacy lane: anything that must never leave the machine. Not a cost lane.
+- **Install:** https://ollama.com/download (or `brew install ollama`)
+- **Sign in:** none
+
+### `claude-app` · Claude app or claude.ai (chat only, no CLI)
+
+- **Kind:** chat · **Access:** subscription · **Lane:** chat · **Level:** 1+
+- **Wins at:** single-agent use through Projects and custom instructions
+- **Install:** https://claude.ai
+- **Sign in:** sign in
+
+### `chatgpt-app` · ChatGPT (chat only, no CLI)
+
+- **Kind:** chat · **Access:** subscription · **Lane:** chat · **Level:** 1+
+- **Wins at:** single-agent use through custom instructions and Projects
+- **Install:** https://chatgpt.com
+- **Sign in:** sign in
+
+### `gemini-app` · Gemini app (chat only, no CLI)
+
+- **Kind:** chat · **Access:** subscription · **Lane:** chat · **Level:** 1+
+- **Wins at:** single-agent use through Gems and saved instructions
+- **Install:** https://gemini.google.com
+- **Sign in:** sign in
+
+## Companion tools
+
+### `codecalc` · codecalc (calculator, code runner, logic checker for your agent)
+
+- **Repo:** https://github.com/The-40-Thieves/codecalc
+- **Gives:** exact arithmetic, code execution in 31 languages, SMT logic checks, complexity and equivalence proofs; offline, no key, no telemetry
+- **Install:** `uvx 'codecalc[full]' setup --write` (needs uv (https://docs.astral.sh/uv/) and Python 3.10+)
+- **Registers itself with:** Claude Code, Claude Desktop, Cursor, VS Code, Zed; snippets for the rest are written to `mcp/`
+- **Default:** selected
+
+### `obsidian-tc` · obsidian-tc (governed memory: an agent-ready MCP server over an Obsidian vault)
+
+- **Repo:** https://github.com/The-40-Thieves/obsidian-tc
+- **Gives:** durable memory and record for your agents: hybrid retrieval (BM25 + dense + link graph), backlinks, compare-and-swap writes with a confirmation gate, folder ACLs, a poison scan on inferred writes; 163 tools, local by default
+- **Install:** `npm install -g obsidian-tc && obsidian-tc /path/to/your/vault` (needs an Obsidian vault folder (the Obsidian app itself is only needed for live plugin bridges); Node 24+ or Bun 1.1+ (stricter than this installer); Ollama with `nomic-embed-text` for local embeddings, or a cloud embeddings key; the Local REST API plugin only for bridge tools)
+- **Registers itself with:** Cursor, VS Code; snippets for the rest are written to `mcp/`
+- **Default:** not selected
+