model-orchestrator 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [0.1.7] - 2026-09-05
+
+### Fixed
+
+- Preserve unrelated subagents in uninstall guidance and explain manual activation cleanup.
+- Provide a chat activation block below 1,500 characters and explain protocol uploads.
+- Warn about zero-lane setups; doctor reports inactive with exit 13, including with --run.
+- Add a first-task walkthrough and clarify agent-directed routing, connection checks and output contracts.
+- Correct the contributor exit-code reference.
+
+## [0.1.6] - 2026-09-05
+
+Issues #16 to #19, filed against 0.1.5. Each reproduced before the fix; each fix has a test.
+
+### Added
+
+- `--dry-run` as an alias for `--dry`; the package script was already named `dry-run` (#16).
+- `cli-run`: `killTree()` ends a lane's process tree with `taskkill /T /F` on Windows instead of killing only the root process. Windows is still not exercised by CI and stays documented as unsupported; the branch is unit-tested by argv capture (#18).
+
+### Fixed
+
+- `cli-run --expect-json` accepts a response that is exactly one markdown code fence around JSON (`\`\`\`json ... \`\`\``, CRLF included). Prose before or after the fence still fails the contract, because then the deliverable is not the JSON (#17).
+- `--yes` with several candidate agents and no `--primary` now prefers claude-code, then the first agent that can load subagent definitions, then the first listed. `--ais codex,agy` used to pick codex and write no subagents (#19).
+
 ## [0.1.5] - 2026-09-05
 
 First release published by the workflow, with provenance.
@@ -97,7 +121,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.5...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.7...HEAD
+[0.1.7]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.6...v0.1.7
+[0.1.6]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.2...v0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/model-orchestrator.svg)](https://www.npmjs.com/package/model-orchestrator) [![test](https://github.com/aunysillyme/model-orchestrator/actions/workflows/test.yml/badge.svg)](https://github.com/aunysillyme/model-orchestrator/actions/workflows/test.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
 
-**A model orchestrator you can `npm run`.** Route every task to the cheapest AI that does it well, whether you have one chat app, five agent CLIs, or a virtual machine running them unattended. One installer asks what you have access to and writes only what fits.
+**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. Your primary agent follows the instructions to choose a tier or lane; the runner executes the lane it is given. It does not automatically compare prices or select models.
 
 Built from a working system, not a diagram: the routing rules, the protocols and the lane runner here run in production, generalized so they transfer to any stack.
 
@@ -10,7 +10,7 @@ Built from a working system, not a diagram: the routing rules, the protocols and
 npx model-orchestrator
 ```
 
-That runs the latest published release from the npm registry. To run a specific release or the current main straight from GitHub: `npx github:aunysillyme/model-orchestrator#v0.1.5` (drop `#v0.1.5` for main).
+That runs the latest published release from the npm registry. To run a specific release or the current main straight from GitHub: `npx github:aunysillyme/model-orchestrator#v0.1.7` (drop `#v0.1.7` for main).
 
 The installer asks a few things, then writes a folder:
 
@@ -18,7 +18,7 @@ The installer asks a few things, then writes a folder:
 2. **Which AIs do you have access to?** (it marks the ones already on your PATH)
 3. **Which one is your primary agent?** (the one that runs the system)
 
-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 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: delete the folder, the subagent folder it named, and `~/.ai-orchestrator/cli-run.log.jsonl` if you used `cli-run`.
+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 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.
 
 ## The three levels
 
@@ -120,7 +120,7 @@ If you need a property in the third row to be enforced, that is a router, a poli
 
 ## Requirements
 
-Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu.
+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.
 
 **Privacy.** The installer makes no network call of its own and sends no telemetry; the only network activity is the `npm install -g` you approve per package. `cli-run` talks to nothing but the vendor CLI you name.
 

package/bin/cli-run.mjs

@@ -244,6 +244,27 @@ export function judge(lane, rc, out, err, outFile) {
 // an agent CLI that shelled out to a tool must not keep working after the
 // wrapper has reported 12. A child that calls setsid() itself escapes this
 // boundary; that is documented, not hidden.
+// Models often wrap JSON in one markdown fence. --expect-json accepts exactly that shape:
+// the whole trimmed response is one fenced block, optionally tagged json. Prose before or
+// after the fence still fails, because then the deliverable is not the JSON (#17).
+export function unfence(text) {
+  const t = String(text).trim();
+  const m = /^```(?:json|JSON)?[ \t]*\r?\n([\s\S]*?)\r?\n?```$/.exec(t);
+  return m ? m[1].trim() : t;
+}
+
+// Kill a lane and everything it spawned. POSIX: the detached process group.
+// Windows has no process groups a signal can reach, so taskkill walks the tree (#18).
+// Windows is not exercised by CI; this branch is unit-tested by argv capture only.
+export function killTree(pid, platform = process.platform, deps = { kill: (p, sig) => process.kill(p, sig), spawn }) {
+  if (platform === 'win32') {
+    deps.spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+    return 'taskkill';
+  }
+  deps.kill(-pid, 'SIGKILL');
+  return 'group';
+}
+
 export function runBounded(argv, timeoutSec, maxBuffer = 16 * 1024 * 1024) {
   return new Promise((resolveRun) => {
     const t0 = Date.now();
@@ -257,8 +278,7 @@ export function runBounded(argv, timeoutSec, maxBuffer = 16 * 1024 * 1024) {
     const killGroup = () => {
       if (!child) return;
       try {
-        if (process.platform !== 'win32') process.kill(-child.pid, 'SIGKILL');
-        else child.kill('SIGKILL');
+        killTree(child.pid);
       } catch {
         try {
           child.kill('SIGKILL');
@@ -404,7 +424,11 @@ export async function doctor(run) {
   let bad = 0;
   console.log(`doctor: ${enabled.length} enabled lane(s): ${enabled.join(', ') || 'none'}`);
   const primary = installedPrimary();
-  if (primary && !enabled.includes(primary)) console.log(`  note: ${primary} is the primary agent; it calls cli-run and is not a lane`);
+  if (primary && !enabled.includes(primary)) console.log(`  note: ${primary} is the primary agent and is not an executable lane`);
+  if (!enabled.length) {
+    console.error('doctor: inactive: no executable lanes enabled. Use level 1 for a single-agent setup, or re-run the installer with a supported CLI selected.');
+    return UNAVAILABLE;
+  }
   for (const lane of LANES) {
     const on = enabled.includes(lane);
     const bin = which(lane);
@@ -452,9 +476,9 @@ export function checkContracts(opts, text, before) {
   }
   if (opts.expectJson) {
     try {
-      JSON.parse(text);
+      JSON.parse(unfence(text));
     } catch {
-      return '--expect-json: the response is not valid JSON';
+      return '--expect-json: the response is not valid JSON (a single ```json fence around the whole response is accepted; prose around it is not)';
     }
   }
   return null;

package/bin/cli.js

@@ -17,7 +17,7 @@ import { planFiles, writeFiles, resolveSelection, resolveTools, resolveApis, dir
 // 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'
+  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'
 };
 export function parseArgs(argv) {
   const out = {};
@@ -93,7 +93,7 @@ Flags
   --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
+  --dry, --dry-run   print the plan, write nothing
   --no-install       never offer to run npm installs
   --list             print the catalog
 `);
@@ -178,7 +178,10 @@ async function main() {
   } 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];
+    // --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];
     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}`));
@@ -250,7 +253,10 @@ async function main() {
   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')) {
+  if (level >= 2 && !selected.some((a) => a.cliRun)) {
+    console.log('\nWarning: no executable lanes selected; delegation is inactive. Use level 1 for a single-agent setup, or add a supported CLI. Doctor will exit 13 until a lane is enabled.');
+  }
+  if (flag('dry') || flag('dry-run')) {
     for (const f of files) console.log('  - ' + (f.root === 'project' ? '[project] ' : '') + f.rel);
     console.log('\n--dry: nothing written.');
     rl && rl.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "A model orchestrator you can npm run: route every task to the cheapest AI that does it well, across one agent, many CLIs, or a whole virtual machine. Three levels, one installer that asks what you have access to.",
   "type": "module",
   "bin": {

package/templates/agents/snippets/chat.md

@@ -3,23 +3,13 @@
 {{PRIMARY_NAME}} has no project instructions file, so the rules travel by paste. Put the block below into the custom instructions, a Project, a Gem, or the first message of a working session.
 
 ```
-You are running a model orchestrator inside one agent.
-
-TIERS (capability, not model names): deep = ambiguous planning, architecture, root-cause debugging, anything expensive to get wrong. standard = writing, review, executing a known plan, research synthesis. fast = classification, extraction, formatting, bulk summaries. Think hardest on deep, least on fast. Default down, escalate on evidence, and never silently retry a failed attempt at the same level.
-
-ROUTE, first match wins: bulk and mechanical -> fast. Needs live data -> standard with tools; anything a search returns is a lead, not a fact. Review without changing -> standard, read-only, findings ranked by severity. Ambiguous or expensive to get wrong -> deep, then hand the plan down. Everything else -> do it directly at standard.
-
-EVERY BUILD: (1) map what it touches and what could break, in writing. (2) Ask at deep level: simplest way? single biggest risk? where is the request wrong? A named risk and a named flaw, or it does not pass. (3) Build, then check it against the real thing. (4) In a fresh turn, attack it: bad input, failing dependency, drift from the plan. CLEAN is a valid answer. (5) Before anything irreversible, name the rollback and get an explicit yes. (6) After: re-check the old name everywhere and expect zero.
-
-EVERY HAND-OFF to a fresh context carries a brief: purpose, task class (read_only / draft_only / mutating), granted scope, capabilities, denied actions, conventions it does not have, report contract (what was NOT done, what is unverified), exit parameters. Absence is denial.
-
-AFTER ANY COMPREHENSIVE TASK: a second pass in a fresh turn that hunts for what is MISSING, not what is present.
-
-NUMBERS AND LOGIC: any figure someone will act on, any comparison you state, any complexity or equivalence claim is computed with a tool (a code interpreter, a calculator), never estimated. Give the exact form and the decimal and name the tool. Trivial single-digit sums are exempt; nothing else is.
-
-MEMORY AND RECORD: before writing anything durable, search for it; after writing, correct the index that lists it; one writer per session; mark inferred content as inferred.
-
-A gate you cannot fail is not a gate. Exit 0 is not a deliverable.
+You follow a model-orchestrator workflow inside this chat. Tiers describe effort, not automatic model switching or cost savings.
+Route first: bulk/formatting -> fast; live data -> standard with tools; review -> standard, read-only; ambiguous/high-risk -> deep; otherwise standard. State the tier. Escalate on failure instead of silently retrying.
+For builds: map affected parts; identify the biggest risk and any flaw in the request (none is valid with reasons); build and verify; use a fresh turn to challenge the result. Before irreversible actions, explain rollback and ask for approval.
+For hand-offs: include purpose, scope, allowed and denied actions, required output, and stopping conditions. A fresh context has none of these instructions.
+After comprehensive work, check for omissions. Compute consequential numbers and comparisons with a tool; report what was checked and what remains unverified.
+Before durable writes, search existing records, update their index, use one writer, and label inferences.
+Check the actual deliverable; exit 0 alone is not evidence of completion. Do not claim to have read local files that were not uploaded or pasted.
 ```
 
-The full text of each rule is in this folder: `ORCHESTRATOR.md`, `TASK_BUNDLE.md`, `protocols/`.
+This compact block fits within 1,500 characters. For the full workflow, upload or paste the following files into your Project or working session; a local path alone does not give a chat access to them: `ORCHESTRATOR.md`, `TASK_BUNDLE.md`, `protocols/`.

package/templates/common/README.md

@@ -11,7 +11,15 @@ Companion tools:
 
 ## The idea in one line
 
-Every task goes to the cheapest AI that does it well, and every gate on the way is a question that can be answered wrong.
+This folder gives your agent routing instructions and, at level 2+, a runner for explicitly selected CLI lanes. The agent chooses the tier or lane; the runner does not automatically compare prices or choose a model.
+
+## Your first task
+
+1. Activate the snippet using the instructions below. For a chat app, paste the block in `PASTE-INTO-YOUR-AGENT.md`; upload any full protocols you want it to read because local paths alone do not share files.
+2. 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."
+3. 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.
+4. 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.
+5. 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.
 
 ## What is in this folder
 
@@ -32,7 +40,7 @@ Level 2 adds `ROUTING.md`, `TIERS.md`, `DELEGATION_MATRIX.md`, `RESEARCH_TRIAGE.
 
 ## Load it into your agent
 
-Your primary agent reads `{{PRIMARY_RULES_FILE}}` from a project root. The installer wrote a snippet file next to this README (`*.snippet.md`, or `PASTE-INTO-YOUR-AGENT.md` for a chat app). Copy its contents into that file, or paste it into the agent's custom instructions. Nothing was appended to a file you already had.
+For a CLI primary, the project rules file is `{{PRIMARY_RULES_FILE}}`. Chat apps use pasted instructions instead. The installer wrote a snippet file next to this README (`*.snippet.md`, or `PASTE-INTO-YOUR-AGENT.md` for a chat app). Copy its contents into that file, or paste it into the agent's custom instructions. Nothing was appended to a file you already had.
 
 ## The three rules that carry everything
 
@@ -49,4 +57,4 @@ Your primary agent reads `{{PRIMARY_RULES_FILE}}` from a project root. The insta
 
 ## Uninstall
 
-Delete this folder and the subagent folder named above. `cli-run` keeps one log at `~/.ai-orchestrator/cli-run.log.jsonl`; delete that too if you used it.
+Before deleting anything, inspect `MANIFEST.json`: entries beginning with `[project] ` identify the subagent files managed by this installation. Review those individual files and remove only the ones you no longer want, preserving edited or pre-existing files. Never delete the shared `.claude/agents` or `.agents/agents` folder; it may contain unrelated agents. If the manifest is missing, inspect files individually rather than deleting a folder. Remove the orchestrator block you manually copied into your project rules file or chat instructions. Then delete this generated docs folder only after preserving any work you added to it. The optional log at `~/.ai-orchestrator/cli-run.log.jsonl` is shared across installations; remove it only if you no longer need that history.

package/templates/intermediate/CLI-RUN.md

@@ -30,6 +30,8 @@ node bin/cli-run.mjs --doctor          # which lanes are enabled and which binar
 node bin/cli-run.mjs --doctor --run    # also sends each enabled lane one tiny prompt and judges the reply (uses a little quota)
 ```
 
+With zero enabled lanes, doctor reports inactive and exits 13. Use level 1 or select a supported CLI. Binary presence does not verify authentication or that your primary loaded its instructions.
+
 A lane that is enabled but not on PATH, or that answers with no deliverable, shows up here before it shows up mid-task.
 
 ## Why it exists