model-orchestrator 0.1.34 → 1.0.0

package/proof/results.json

@@ -0,0 +1,198 @@
+{
+  "schemaVersion": 1,
+  "environment": {
+    "node": "v22.22.3",
+    "platform": "darwin",
+    "arch": "arm64"
+  },
+  "entries": [
+    {
+      "id": "install-dry-ms",
+      "label": "Dry install wall time",
+      "kind": "reproducible",
+      "value": 42.220875,
+      "unit": "ms median",
+      "measuredAt": "2026-09-27",
+      "method": "Spawn a fresh Node installer process per sample; level 2, Claude Code + Codex, no companions, --dry. Includes Node startup and planning; writes no install files. Isolated home and PATH, no real vendors.",
+      "sampleSize": 7,
+      "script": "proof/scripts/install-time.js",
+      "expiresAt": "2026-10-11",
+      "samples": [
+        51.577042,
+        48.655542,
+        46.568834,
+        42.220875,
+        41.573667,
+        39.881333,
+        40.983417
+      ]
+    },
+    {
+      "id": "runner-overhead-ms",
+      "label": "Lane runner overhead",
+      "kind": "reproducible",
+      "value": 63.742250999999996,
+      "unit": "ms median difference",
+      "measuredAt": "2026-09-27",
+      "method": "Paired fresh processes: direct Node stub versus cli-run hermes with the same stub. Alternates pair order. Includes wrapper startup, validation and local log writes; excludes vendor/network/model time.",
+      "sampleSize": 7,
+      "script": "proof/scripts/runner-overhead.js",
+      "expiresAt": "2026-10-11",
+      "pairs": [
+        {
+          "directMs": 26.925375,
+          "wrappedMs": 409.562,
+          "overheadMs": 382.63662500000004
+        },
+        {
+          "directMs": 28.554875,
+          "wrappedMs": 95.06725,
+          "overheadMs": 66.512375
+        },
+        {
+          "directMs": 28.981666,
+          "wrappedMs": 94.610209,
+          "overheadMs": 65.628543
+        },
+        {
+          "directMs": 26.295583,
+          "wrappedMs": 86.161958,
+          "overheadMs": 59.866375
+        },
+        {
+          "directMs": 28.71575,
+          "wrappedMs": 82.585583,
+          "overheadMs": 53.869833
+        },
+        {
+          "directMs": 26.668791,
+          "wrappedMs": 90.411042,
+          "overheadMs": 63.742250999999996
+        },
+        {
+          "directMs": 34.081333,
+          "wrappedMs": 82.568041,
+          "overheadMs": 48.48670799999999
+        }
+      ]
+    },
+    {
+      "id": "missing-results-caught",
+      "label": "Empty results flagged",
+      "kind": "reproducible",
+      "value": 10,
+      "unit": "fixtures rejected",
+      "measuredAt": "2026-09-27",
+      "method": "Run cli-run against an exit-0 stub for every supported lane, once with empty stdout and once with an empty native final result. Count exit 10/11 only. A successful Hermes response is the positive control. Synthetic fixtures measure these shapes only.",
+      "sampleSize": 10,
+      "script": "proof/scripts/missing-results.js",
+      "expiresAt": "2026-10-11",
+      "outcomes": [
+        {
+          "lane": "grok",
+          "fixture": "empty-stdout",
+          "exitCode": 11
+        },
+        {
+          "lane": "grok",
+          "fixture": "empty-final-result",
+          "exitCode": 10
+        },
+        {
+          "lane": "codex",
+          "fixture": "empty-stdout",
+          "exitCode": 11
+        },
+        {
+          "lane": "codex",
+          "fixture": "empty-final-result",
+          "exitCode": 10
+        },
+        {
+          "lane": "agy",
+          "fixture": "empty-stdout",
+          "exitCode": 11
+        },
+        {
+          "lane": "agy",
+          "fixture": "empty-final-result",
+          "exitCode": 10
+        },
+        {
+          "lane": "hermes",
+          "fixture": "empty-stdout",
+          "exitCode": 11
+        },
+        {
+          "lane": "hermes",
+          "fixture": "empty-final-result",
+          "exitCode": 11
+        },
+        {
+          "lane": "qwen",
+          "fixture": "empty-stdout",
+          "exitCode": 11
+        },
+        {
+          "lane": "qwen",
+          "fixture": "empty-final-result",
+          "exitCode": 10
+        }
+      ]
+    },
+    {
+      "id": "acceptance-failures-blocked",
+      "label": "Acceptance failures blocked",
+      "kind": "reproducible",
+      "value": 4,
+      "unit": "fixtures rejected",
+      "measuredAt": "2026-09-27",
+      "method": "Run aunx checks run against nonzero, manual, missing-program and timeout fixtures. Each must exit 1; a passing command must exit 0. This is a local command gate, activated by the user in their release sequence.",
+      "sampleSize": 4,
+      "script": "proof/scripts/check-gate.js",
+      "expiresAt": "2026-10-11",
+      "outcomes": [
+        {
+          "fixture": "nonzero",
+          "exitCode": 1
+        },
+        {
+          "fixture": "manual",
+          "exitCode": 1
+        },
+        {
+          "fixture": "missing",
+          "exitCode": 1
+        },
+        {
+          "fixture": "timeout",
+          "exitCode": 1
+        }
+      ]
+    },
+    {
+      "id": "author-main-browser-tokens",
+      "label": "Main conversation browser tokens",
+      "kind": "author-setup",
+      "value": 408147,
+      "unit": "tokens per browser step (median)",
+      "measuredAt": "2026-09-26",
+      "method": "Measured on the author's Claude Code sessions: every browser tool call in the transcripts, counting tokens re-read by the main conversation per step. Median: 408,147 tokens per browser step across 145 sessions and 9,775 browser steps. Sample size counts browser steps.",
+      "sampleSize": 9775,
+      "script": "author setup, re-measured locally",
+      "expiresAt": "2026-10-27"
+    },
+    {
+      "id": "author-subagent-browser-tokens",
+      "label": "Small browser subagent tokens",
+      "kind": "author-setup",
+      "value": 17197,
+      "unit": "tokens per step (highest of 5 runs)",
+      "measuredAt": "2026-09-27",
+      "method": "At least 23x fewer tokens per step in this sample: the main conversation median of 408,147 divided by the highest subagent run of 17,197 is 23.73x. Measured on the author's Claude Code sessions, with the same kind of work handed to a small browser subagent. Five runs, tokens divided by steps or tool calls per run: 17,197 (206,369 tokens / 12 steps, 2026-09-26); 4,077 (93,773 / 23), 4,201 (105,034 / 25), 4,585 (91,709 / 20), and 4,489 (94,263 / 21), all four on 2026-09-27. Range: 4,077 to 17,197; median of 5 runs: 4,489. Typical context, using the median of 5 runs: about 91x fewer tokens per step. These are measurements from the author's own sessions, not a controlled comparison or a guarantee for other setups. The four 2026-09-27 runs shared one browser pane, so some steps were spent recovering a drifting tab, which raises the step count and lowers per-step tokens. The first run counted steps; the later runs counted tool calls. Sample size counts runs.",
+      "sampleSize": 5,
+      "script": "author setup, re-measured locally",
+      "expiresAt": "2026-10-27"
+    }
+  ]
+}

package/proof/scripts/check-gate.js

@@ -0,0 +1,26 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { clean, entry, isMain, ROOT, run, scratch } from './lib.js';
+
+export function measureGate() {
+  const dir = scratch();
+  try {
+    const file = join(dir, 'checks.json');
+    const fixtures = [
+      { id: 'nonzero', command: ['node', '-e', 'process.exit(7)'] },
+      { id: 'manual', manual: true },
+      { id: 'missing', command: ['model-orchestrator-missing-fixture-program'] },
+      { id: 'timeout', timeoutMs: 50, command: ['node', '-e', 'setInterval(() => {}, 1000)'] }
+    ];
+    const outcomes = fixtures.map(check => {
+      writeFileSync(file, JSON.stringify({ version: 1, checks: [check] }));
+      return { fixture: check.id, exitCode: run([join(ROOT, 'bin', 'aunx.js'), 'checks', 'run', file]).status };
+    });
+    writeFileSync(file, JSON.stringify({ version: 1, checks: [{ id: 'positive', command: ['node', '-e', 'process.exit(0)'] }] }));
+    if (run([join(ROOT, 'bin', 'aunx.js'), 'checks', 'run', file]).status !== 0) throw new Error('Positive acceptance check control failed');
+    const caught = outcomes.filter(o => o.exitCode === 1).length;
+    if (caught !== outcomes.length) throw new Error('A failing acceptance fixture escaped the gate');
+    return entry('acceptance-failures-blocked', 'Acceptance failures blocked', caught, 'fixtures rejected', outcomes.length, 'Run aunx checks run against nonzero, manual, missing-program and timeout fixtures. Each must exit 1; a passing command must exit 0. This is a local command gate, activated by the user in their release sequence.', 'check-gate.js', { outcomes });
+  } finally { clean(dir); }
+}
+if (isMain(import.meta.url)) console.log(JSON.stringify(measureGate(), null, 2));

package/proof/scripts/install-time.js

@@ -0,0 +1,16 @@
+import { join } from 'node:path';
+import { clean, entry, fixtureEnv, isMain, median, ROOT, run, scratch, timed } from './lib.js';
+
+export function measureInstall() {
+  const dir = scratch();
+  try {
+    const samples = [];
+    for (let i = 0; i < 7; i++) {
+      const { result, ms } = timed(() => run([join(ROOT, 'bin', 'cli.js'), '--yes', '--level', '2', '--ais', 'claude-code,codex', '--primary', 'claude-code', '--dir', join(dir, 'rules'), '--project', dir, '--dry'], { env: fixtureEnv(dir) }));
+      if (result.status !== 0) throw new Error(`Dry install failed: ${result.stderr}`);
+      samples.push(ms);
+    }
+    return entry('install-dry-ms', 'Dry install wall time', median(samples), 'ms median', samples.length, 'Spawn a fresh Node installer process per sample; level 2, Claude Code + Codex, no companions, --dry. Includes Node startup and planning; writes no install files. Isolated home and PATH, no real vendors.', 'install-time.js', { samples });
+  } finally { clean(dir); }
+}
+if (isMain(import.meta.url)) console.log(JSON.stringify(measureInstall(), null, 2));

package/proof/scripts/lib.js

@@ -0,0 +1,73 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+export const ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+export const RESULTS = join(ROOT, 'proof', 'results.json');
+export const isMain = url => Boolean(process.argv[1] && resolve(process.argv[1]) === fileURLToPath(url));
+export function scratch() { return mkdtempSync(join(tmpdir(), 'model-orchestrator-proof-')); }
+export function clean(path) { rmSync(path, { recursive: true, force: true }); }
+export function run(args, options = {}) {
+  const result = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: 30000, cwd: ROOT, ...options });
+  if (result.error) throw result.error;
+  return result;
+}
+export function median(samples) {
+  const sorted = [...samples].sort((a, b) => a - b);
+  const center = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[center] : (sorted[center - 1] + sorted[center]) / 2;
+}
+export function timed(fn) {
+  const start = process.hrtime.bigint();
+  const result = fn();
+  return { result, ms: Number(process.hrtime.bigint() - start) / 1e6 };
+}
+export function fixtureEnv(dir) {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) if (['PATH', 'HOME', 'USERPROFILE'].includes(key.toUpperCase())) delete env[key];
+  return { ...env, PATH: join(dir, 'bin'), HOME: dir, USERPROFILE: dir };
+}
+export function stubLane(dir, name, source) {
+  mkdirSync(join(dir, 'bin'), { recursive: true });
+  const script = join(dir, 'bin', `${name}.cjs`);
+  writeFileSync(script, source);
+  if (process.platform === 'win32') {
+    writeFileSync(join(dir, 'bin', `${name}.cmd`), '@ECHO off\r\nSET "_prog=node"\r\n"%_prog%" "%dp0%'+name+'.cjs" %*\r\n');
+  } else {
+    writeFileSync(join(dir, 'bin', name), '#!' + process.execPath + '\n' + source, { mode: 0o755 });
+  }
+  return script;
+}
+export function entry(id, label, value, unit, sampleSize, method, script, extra = {}) {
+  const now = new Date();
+  const expires = new Date(now);
+  expires.setUTCDate(expires.getUTCDate() + 14);
+  return { id, label, kind: 'reproducible', value, unit, measuredAt: now.toISOString().slice(0, 10), method, sampleSize, script: `proof/scripts/${script}`, expiresAt: expires.toISOString().slice(0, 10), ...extra };
+}
+export function readResults() { return JSON.parse(readFileSync(RESULTS, 'utf8')); }
+export function validateResults(data, now = new Date()) {
+  const errors = [];
+  if (!data || data.schemaVersion !== 1 || !Array.isArray(data.entries) || !data.entries.length) return ['Expected schemaVersion 1 with measured entries'];
+  const today = now.toISOString().slice(0, 10);
+  const ids = new Set();
+  const validDate = value => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+  for (const item of data.entries) {
+    if (!item || typeof item.id !== 'string' || ids.has(item.id)) { errors.push('Entry id must be unique'); continue; }
+    ids.add(item.id);
+    if (typeof item.value !== 'number' || !Number.isFinite(item.value)) errors.push(`${item.id}: value must be finite`);
+    if (!Number.isInteger(item.sampleSize) || item.sampleSize < 1) errors.push(`${item.id}: sample size must be positive`);
+    if (!['reproducible', 'author-setup'].includes(item.kind)) errors.push(`${item.id}: unknown measurement kind`);
+    for (const key of ['label', 'unit', 'method', 'script']) if (typeof item[key] !== 'string' || !item[key].trim()) errors.push(`${item.id}: ${key} is required`);
+    if (!validDate(item.measuredAt) || !validDate(item.expiresAt)) errors.push(`${item.id}: valid ISO dates required`);
+    else {
+      if (item.measuredAt > today) errors.push(`${item.id}: measurement is in the future`);
+      if (item.expiresAt < item.measuredAt) errors.push(`${item.id}: expiry precedes measurement`);
+      if (item.expiresAt < today) errors.push(`${item.id}: expired ${item.expiresAt}`);
+    }
+    const localAuthorSource = item.kind === 'author-setup' && item.script === 'author setup, re-measured locally';
+    if (!localAuthorSource && (typeof item.script !== 'string' || !/^proof\/scripts\/[A-Za-z0-9_-]+\.js$/.test(item.script))) errors.push(`${item.id}: script must name a proof script`);
+  }
+  return errors;
+}

package/proof/scripts/measure.js

@@ -0,0 +1,15 @@
+import { writeFileSync } from 'node:fs';
+import { measureInstall } from './install-time.js';
+import { measureRunner } from './runner-overhead.js';
+import { measureMissingResults } from './missing-results.js';
+import { measureGate } from './check-gate.js';
+import { readResults, RESULTS } from './lib.js';
+import { renderPage } from './render.js';
+
+// Run serially: overlapping timing samples would measure this harness competing with itself.
+const entries = [measureInstall(), measureRunner(), measureMissingResults(), measureGate()];
+let author = [];
+try { author = readResults().entries.filter(e => e.kind === 'author-setup'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+writeFileSync(RESULTS, JSON.stringify({ schemaVersion: 1, environment: { node: process.version, platform: process.platform, arch: process.arch }, entries: [...entries, ...author] }, null, 2) + '\n');
+renderPage();
+for (const item of entries) console.log(`${item.id}: ${item.value} ${item.unit}; n=${item.sampleSize}; measured ${item.measuredAt}; expires ${item.expiresAt}`);

package/proof/scripts/missing-results.js

@@ -0,0 +1,30 @@
+import { join } from 'node:path';
+import { clean, entry, fixtureEnv, isMain, ROOT, run, scratch, stubLane } from './lib.js';
+
+export function measureMissingResults() {
+  const dir = scratch();
+  try {
+    const shapes = {
+      grok: JSON.stringify({ stopReason: 'end_turn', text: '' }),
+      codex: JSON.stringify({ type: 'turn.completed' }),
+      agy: JSON.stringify({ event: 'result', result: { status: 'SUCCESS', response: '' } }),
+      hermes: '   ',
+      qwen: JSON.stringify([{ type: 'result', subtype: 'success', result: '' }])
+    };
+    const outcomes = [];
+    for (const [lane, shape] of Object.entries(shapes)) {
+      for (const [fixture, text] of [['empty-stdout', ''], ['empty-final-result', shape]]) {
+        stubLane(dir, lane, `process.stdout.write(${JSON.stringify(text)});`);
+        const result = run([join(ROOT, 'bin', 'cli-run.mjs'), lane, 'fixture', '--quiet'], { env: fixtureEnv(dir) });
+        outcomes.push({ lane, fixture, exitCode: result.status });
+      }
+    }
+    // A success control makes a wrapper that rejects everything fail this measurement.
+    stubLane(dir, 'hermes', 'console.log("fixture result");');
+    if (run([join(ROOT, 'bin', 'cli-run.mjs'), 'hermes', 'control', '--quiet'], { env: fixtureEnv(dir) }).status !== 0) throw new Error('Positive runner control failed');
+    const caught = outcomes.filter(o => o.exitCode === 10 || o.exitCode === 11).length;
+    if (caught !== outcomes.length) throw new Error('An empty-result fixture escaped the expected failure class');
+    return entry('missing-results-caught', 'Empty results flagged', caught, 'fixtures rejected', outcomes.length, 'Run cli-run against an exit-0 stub for every supported lane, once with empty stdout and once with an empty native final result. Count exit 10/11 only. A successful Hermes response is the positive control. Synthetic fixtures measure these shapes only.', 'missing-results.js', { outcomes });
+  } finally { clean(dir); }
+}
+if (isMain(import.meta.url)) console.log(JSON.stringify(measureMissingResults(), null, 2));

package/proof/scripts/record-gate.js

@@ -0,0 +1,38 @@
+// Capture real fixture output, then render a terminal GIF with an already installed agg.
+// The recorder installs no tools and leaves the repository's promo trailer untouched.
+import { spawnSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { clean, ROOT, run, scratch } from './lib.js';
+
+const dir = scratch();
+try {
+  const file = join(dir, 'checks.json');
+  writeFileSync(file, JSON.stringify({ version: 1, checks: [{ id: 'output-exists', command: ['node', '-e', 'process.exit(require("node:fs").existsSync("output.txt") ? 0 : 1)'] }] }));
+  const before = run([join(ROOT, 'bin', 'aunx.js'), 'checks', 'run', file], { cwd: dir });
+  if (before.status !== 1) throw new Error('Expected the missing-output check to fail');
+  const create = run(['-e', 'require("node:fs").writeFileSync("output.txt", "verified output")'], { cwd: dir });
+  if (create.status !== 0) throw new Error('Could not create the fixture output');
+  const after = run([join(ROOT, 'bin', 'aunx.js'), 'checks', 'run', file], { cwd: dir });
+  if (after.status !== 0) throw new Error('Expected the existing-output check to pass');
+  const terminal = s => s.replace(/\r?\n/g, '\r\n');
+  const events = [
+    { version: 2, width: 86, height: 15, title: 'Acceptance checks: red, then green', env: { TERM: 'xterm-256color' } },
+    [0, 'o', '\u001b[1;32m$\u001b[0m aunx checks run checks.json\r\n'],
+    [0.6, 'o', '\u001b[31m' + terminal(before.stdout) + '\u001b[0m'],
+    [1.2, 'o', '$ echo $?\r\n' + before.status + '\r\n'],
+    [3, 'o', '\r\n$ node -e \'require("node:fs").writeFileSync("output.txt","verified output")\'\r\n'],
+    [4.5, 'o', '\r\n\u001b[1;32m$\u001b[0m aunx checks run checks.json\r\n'],
+    [5, 'o', '\u001b[32m' + terminal(after.stdout) + '\u001b[0m'],
+    [5.5, 'o', '$ echo $?\r\n' + after.status + '\r\n'],
+    [7, 'o', '\r\nThe exit code gates the next command in your release sequence.\r\n']
+  ];
+  const cast = join(ROOT, 'proof', 'gate-demo.cast');
+  const gif = join(ROOT, 'proof', 'gate-demo.gif');
+  writeFileSync(cast, events.map(e => JSON.stringify(e)).join('\n') + '\n');
+  const rendered = spawnSync('agg', ['--theme', 'monokai', '--font-size', '18', '--last-frame-duration', '3', cast, gif], { encoding: 'utf8', timeout: 60000 });
+  if (rendered.error || rendered.status !== 0) {
+    throw new Error(`The cast is saved. To render the GIF, install agg yourself from https://github.com/asciinema/agg and run this script again. ${rendered.error?.code || rendered.stderr}`);
+  }
+  console.log('Recorded proof/gate-demo.cast and proof/gate-demo.gif from real failing and passing commands.');
+} finally { clean(dir); }

package/proof/scripts/render.js

@@ -0,0 +1,18 @@
+import { writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readResults, ROOT, validateResults } from './lib.js';
+
+export function proofMarkdown(data) {
+  const source = (e, label) => e.kind === 'author-setup' && e.script === 'author setup, re-measured locally' ? e.script : `[${label}](../${e.script})`;
+  const rows = data.entries.map(e => `| ${e.label} | ${e.value.toFixed(Number.isInteger(e.value) ? 0 : 2)} ${e.unit} | ${e.sampleSize} | ${e.measuredAt} | ${e.expiresAt} | ${source(e, 'script')} |`);
+  const methods = data.entries.map(e => `### ${e.label}\n\n${e.method}\n\nKind: ${e.kind === 'author-setup' ? "measured on the author's setup" : 'reproducible local measurement'}. Sample size: ${e.sampleSize}. Measured: ${e.measuredAt}. Expires: ${e.expiresAt}.\n\nSource: ${source(e, e.script)}.`).join('\n\n');
+  return `# Reproduce the measurements\n\nGenerated from [results.json](results.json). Each figure has a method, sample size, measurement date and expiry. Run the scripts on your own machine to compare.\n\nEnvironment: Node ${data.environment.node}, ${data.environment.platform} ${data.environment.arch}. Timing varies with startup caches and other work on the machine. Synthetic cases show what those fixtures exercise.\n\n| Measurement | Result | Sample size | Measured | Expires | Reproduce |\n|---|---|---|---|---|---|\n${rows.join('\n')}\n\n## Run the proof scripts\n\n\`\`\`sh\nnode proof/scripts/measure.js\nnode proof/scripts/render.js\nnpm test\n\`\`\`\n\nThe measurement command refreshes reproducible entries and preserves separately sourced author-setup entries. The test suite rejects expired, future-dated or incomplete entries and checks this page against the data. The weekly [refresh workflow](../.github/workflows/proof.yml) reruns the scripts and commits their data and generated page.\n\n## Try the acceptance gate\n\n\`\`\`sh\naunx checks ACCEPTANCE_CHECKS.json\naunx checks run ACCEPTANCE_CHECKS.json\n\`\`\`\n\nThe scaffold starts red. Replace the sample with commands that prove your requirements, then put \`aunx checks run ACCEPTANCE_CHECKS.json && <your-release-command>\` in your own release sequence. Commands are local code you review before running. Manual evidence stays UNVERIFIED and blocks the gate.\n\n![Acceptance gate rejects a missing output, then passes after the output exists](gate-demo.gif)\n\nThe [recording script](scripts/record-gate.js) captures real command output into an asciicast, then renders it with an already installed agg. Companion tools are installed by their users.\n\n## Measurement methods\n\n${methods}\n\n## Operation and verification\n\n- **What and why:** executable measurements keep public figures traceable to current output.\n- **Trigger:** weekly schedule, workflow dispatch, or \`node proof/scripts/measure.js\`.\n- **Invocation chain:** workflow -> measurement functions -> isolated Node fixtures -> results.json -> this page -> npm test.\n- **Dependencies:** Node and the repository. The optional GIF recorder uses agg from the asciinema project.\n- **Reads:** package scripts, the installer, runner and acceptance-check runner. Fixture tests use an isolated home and PATH.\n- **Writes:** results.json, this generated page, temporary fixture directories and local fixture logs. The recorder writes gate-demo.cast and gate-demo.gif.\n- **Closed loop:** the workflow fails when measurement or tests fail. GitHub Actions records the failure; repository notification settings decide who receives it. No separate alert service is configured.\n- **Failure modes:** runner behavior changes, an expired catalog snapshot, missing runtime, unavailable write permission, or timing noise. Review the failed job, rerun locally, and send a reproducible issue to the repository maintainers.\n- **Run and verify:** run the commands above, inspect sample arrays and fixture exit codes in results.json, and require npm test to pass. A future-time unit test proves expiry can fail.\n- **Source of truth:** results.json and the scripts it names. Author-setup evidence is added separately by its owner.\n`;
+}
+export function renderPage() {
+  const data = readResults();
+  const errors = validateResults(data);
+  if (errors.length) throw new Error(errors.join('\n'));
+  writeFileSync(join(ROOT, 'proof', 'README.md'), proofMarkdown(data));
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) renderPage();

package/proof/scripts/runner-overhead.js

@@ -0,0 +1,21 @@
+import { join } from 'node:path';
+import { clean, entry, fixtureEnv, isMain, median, ROOT, run, scratch, stubLane, timed } from './lib.js';
+
+export function measureRunner() {
+  const dir = scratch();
+  try {
+    const stub = stubLane(dir, 'hermes', 'console.log("fixture result");');
+    const env = fixtureEnv(dir);
+    const pairs = [];
+    for (let i = 0; i < 7; i++) {
+      const direct = () => timed(() => run([stub], { env }));
+      const wrapped = () => timed(() => run([join(ROOT, 'bin', 'cli-run.mjs'), 'hermes', 'fixture', '--quiet'], { env }));
+      let before, after;
+      if (i % 2) { after = wrapped(); before = direct(); } else { before = direct(); after = wrapped(); }
+      if (before.result.status !== 0 || after.result.status !== 0) throw new Error('Stub runner measurement failed');
+      pairs.push({ directMs: before.ms, wrappedMs: after.ms, overheadMs: after.ms - before.ms });
+    }
+    return entry('runner-overhead-ms', 'Lane runner overhead', median(pairs.map(p => p.overheadMs)), 'ms median difference', pairs.length, 'Paired fresh processes: direct Node stub versus cli-run hermes with the same stub. Alternates pair order. Includes wrapper startup, validation and local log writes; excludes vendor/network/model time.', 'runner-overhead.js', { pairs });
+  } finally { clean(dir); }
+}
+if (isMain(import.meta.url)) console.log(JSON.stringify(measureRunner(), null, 2));

package/src/README.md

@@ -3,9 +3,15 @@
 | File | Job |
 |---|---|
 | `catalog.js` | the single list of levels and AIs. Add an AI here and the prompts, docs tables, delegation matrix, gateway config and installer all pick it up. Nothing else lists AIs. |
+| `roles.js` | pure role assignment from selected catalog capability facts, billing and selection order. Renders the stack table and manifest roles, and infers the main agent from its supported surfaces. Unknown facts remain unverified; review requires a known different model family and private work requires local execution. |
+| `aunx.js` | command dispatch for briefs, context, checks, routing and runner calls. Route suggestions read manifest roles through a capped regular-file JSON reader; symlinks and malformed files are ignored. Route lookup executes no project code. A project's runner requires explicit `--dir`. |
 | `detect.js` | PATH lookup for a binary, plus the few places vendor installers drop binaries without touching PATH. No shell-outs. |
-| `install.js` | pure planner: turns (level, selection, primary) into a list of files to write, rendering templates and computing every generated table. `writeFiles` is the only thing that touches disk. `activationSteps()` and `snippetFor()` live here so the terminal summary and the generated README render the same list. `subagentsLoadRules(primary)` gates every delegate-by-default render var (builder-by-default wording, the route-gate table, the inline-threshold note) on the one verified premise: a claude-code subagent loads CLAUDE.md. |
-| `apply-snippets.js` | validates the two Claude Code activation targets before any writes, builds a replaceable marked block and merges hook entries. `writeFiles` applies these opt-in entries with backups and rollback; they stay outside the uninstall manifest. |
-| `plugin.js` | the plan for the Claude Code plugin bundle in `plugin/`: `planPluginFiles()` renders the claude-code agents and the two read-only hooks from the same templates `install.js` uses, with plugin render vars (the installer's default rules paths, the setup hint for a project with no rules) instead of per-install ones. Pure; `scripts/gen-plugin.js` writes it and `test/plugin.test.js` checks the committed copy. |
+| `install.js` | pure planner: turns (level, selection, primary) into a list of files to write, rendering templates and computed role assignments. `writeFiles` is the only thing that touches disk. `activationSteps()` and `snippetFor()` live here so the terminal summary and the generated README render the same list. `subagentsLoadRules(primary)` selects loading guidance from catalog facts. File ownership hashes preserve edits during runtime upgrades and document updates, migrate the old brief name, and keep uninstall ownership of existing companion files. |
+| `apply-snippets.js` | validates the main agent's catalog-supported rules target and Claude Code hook settings before writes, builds a replaceable marked block and merges hook entries. `writeFiles` applies the entries with backups and rollback, and records ownership for uninstall. Interactive activation defaults on; headless `--yes` requires `--apply-snippets`, and `--no-apply` keeps activation manual. |
+| `activation-ownership.js` | validates recorded project paths and rules, hook and MCP ownership before upgrades or uninstall. The shared `globalConfigProblem()` check in `install.js` refuses home-level agent configuration targets during installation and uninstall. |
+| `apply-companions.js` | plans selected companion registration for the main agent's catalog-supported project MCP config, preserves existing server entries and emits remaining setup steps. Claude Code's `.mcp.json` is the supported automatic target; other hosts keep manual registration guidance. |
+| `postinstall.js` | runs the local presence health check and checks sign-in only through reliable catalog-listed status commands. Live canaries and vendor login flows remain explicit user actions. |
+| `uninstall.js` | validates manifest ownership and target paths before removing unedited managed files and unchanged applied rules, hooks or MCP entries; preserves user changes and backups. |
+| `plugin.js` | the plan for the Claude Code plugin bundle in `plugin/`: `planPluginFiles()` renders the claude-code agents and the two read-only hooks from the same templates `install.js` uses, with plugin render vars (the installer's default rules paths, the setup hint for a project with no rules) instead of per-install ones. Pure; `scripts/gen-plugin.js` writes it and the marketplace listing and `test/plugin.test.js` checks the committed copy. |
 | `prompt.js` | line-buffered questions for the interactive path; piped answers are queued, EOF mid-prompt aborts instead of confirming a write. |
 | `render.js` | `{{KEY}}` substitution. Throws on an unknown key, so a template typo fails the test suite instead of shipping a literal placeholder. |

package/src/activation-ownership.js

@@ -0,0 +1,19 @@
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const digest = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+
+// Shared by upgrades and uninstall: persisted ownership is untrusted input.
+export function validateActivationOwnership(key, ownership) {
+  const relative = typeof key === 'string' && key.startsWith('[project] ') ? key.slice('[project] '.length) : '';
+  if (!relative || /[\\:\x00-\x1f\x7f]/.test(relative) || relative.split('/').some((part) => !part || part === '.' || part === '..')
+      || !object(ownership) || typeof ownership.created !== 'boolean') return `invalid activation ownership: ${key}`;
+  if (ownership.kind === 'rules') {
+    if (!digest(ownership.blockHash) || !['', '\n', '\n\n'].includes(ownership.addedPrefix) || !['', '\n'].includes(ownership.addedSuffix)) return `invalid rules ownership: ${key}`;
+  } else if (ownership.kind === 'hooks') {
+    if (!Array.isArray(ownership.hooks) || typeof ownership.hadHooks !== 'boolean' || !Array.isArray(ownership.originalEvents)
+        || ownership.originalEvents.some((event) => typeof event !== 'string')
+        || ownership.hooks.some((record) => !object(record) || typeof record.event !== 'string' || !object(record.group) || !object(record.hook))) return `invalid hook ownership: ${key}`;
+  } else if (ownership.kind === 'mcp') {
+    if (ownership.key !== 'mcpServers' || !object(ownership.servers) || typeof ownership.hadKey !== 'boolean') return `invalid MCP ownership: ${key}`;
+  } else return `unknown activation ownership: ${key}`;
+  return null;
+}

package/src/apply-companions.js

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { preflight, ACTIVATION_JSON_BYTE_CAP } from './install.js';
+
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const refuse = (message) => Object.assign(new Error(message), { code: 'PREFLIGHT' });
+const configPlaceholder = '/ABSOLUTE/PATH/TO/obsidian-tc.config.json';
+const needsConfiguration = (server) => server?.env?.OBSIDIAN_TC_CONFIG === configPlaceholder;
+
+// Only cataloged project-local targets are eligible. A snippet for a vendor's
+// global config is useful setup guidance, never permission to edit that file.
+export function planCompanionApplication({ primary, tools = [], project, files, platform = process.platform }) {
+  const host = primary?.projectMcp;
+  const selected = tools.filter((tool) => tool.mcpSnippets?.[primary?.id]);
+  if (!host || !selected.length) return [];
+  const problems = preflight([{ rel: host.file }], project);
+  if (problems.length) throw refuse(problems.join('; '));
+  const path = join(project, host.file);
+  // R1: refuse an oversized pre-existing MCP config before it is read, the
+  // same way invalid JSON is refused today.
+  if (existsSync(path) && statSync(path).size > ACTIVATION_JSON_BYTE_CAP) {
+    throw refuse(`${path}: larger than the ${ACTIVATION_JSON_BYTE_CAP} byte (10 MB) cap on a pre-existing settings/MCP JSON file; nothing written`);
+  }
+  const original = existsSync(path) ? readFileSync(path) : null;
+  let settings = {};
+  if (original) {
+    try { settings = JSON.parse(original.toString('utf8')); }
+    catch { throw refuse(`${path}: invalid JSON; nothing written`); }
+  }
+  if (!object(settings) || (settings[host.key] !== undefined && !object(settings[host.key]))) {
+    throw refuse(`${path}: expected a JSON object with an optional ${host.key} object`);
+  }
+  const servers = { ...settings[host.key] };
+  const added = {};
+  const companionRegistrations = [];
+  for (const tool of selected) {
+    const rel = tool.mcpSnippets[primary.id];
+    const snippet = files.find((file) => (file.root || 'dir') === 'dir' && file.rel.split('\\').join('/') === rel);
+    if (!snippet) throw refuse(`${tool.id}: missing registration snippet ${rel}`);
+    let incoming;
+    try { incoming = JSON.parse(snippet.content.toString())[host.key]?.[tool.id]; }
+    catch { throw refuse(`${tool.id}: invalid registration snippet ${rel}`); }
+    if (!object(incoming)) throw refuse(`${tool.id}: missing server object in ${rel}`);
+    // The installed JSON templates use npx for this stdio server. Windows
+    // requires the vendor-documented cmd wrapper (OBSIDIAN-TC.md Windows).
+    if (platform === 'win32' && incoming.command === 'npx') {
+      incoming = { ...incoming, command: 'cmd', args: ['/d', '/c', 'npx', ...(incoming.args || [])] };
+    }
+    let status;
+    if (Object.hasOwn(servers, tool.id)) {
+      status = isDeepStrictEqual(servers[tool.id], incoming) ? 'present' : 'conflict';
+    } else {
+      status = 'added';
+      servers[tool.id] = incoming;
+      added[tool.id] = incoming;
+    }
+    companionRegistrations.push({ id: tool.id, status, needsConfiguration: needsConfiguration(servers[tool.id]) });
+  }
+  const content = Object.keys(added).length
+    ? JSON.stringify({ ...settings, [host.key]: servers }, null, 2) + '\n'
+    : original;
+  return [{
+    rel: host.file, root: 'project', mode: 0o644, original, content,
+    applySnippet: true,
+    activation: { kind: 'mcp', key: host.key, hadKey: Object.hasOwn(settings, host.key), servers: added },
+    companionRegistrations
+  }];
+}
+
+// The generated README can use conditional guidance before a merge is planned;
+// the terminal supplies registrations to describe the observed merge result.
+export function companionRegistrationSteps({ primary, tools = [], project, dir, applySnippets = false, registrations } = {}) {
+  const root = resolve(project || process.cwd());
+  const docs = resolve(dir || 'ai-orchestrator');
+  const host = primary?.projectMcp;
+  const states = registrations?.flatMap((entry) => entry.companionRegistrations || []);
+  const steps = [];
+  for (const tool of tools) {
+    const rel = tool.mcpSnippets?.[primary?.id];
+    const snippet = rel ? join(docs, rel) : join(docs, 'mcp');
+    const state = states?.find((item) => item.id === tool.id);
+    const registered = applySnippets && host && rel;
+    if (!registered) {
+      if (!rel) {
+        steps.push(`${tool.id}: follow ${join(docs, tool.id.toUpperCase() + '.md')} to set it up with ${primary?.chatName || primary?.name || 'your agent'}`);
+        continue;
+      }
+      const target = host ? join(root, host.file) : 'your agent\'s MCP config (user-managed)';
+      steps.push(`${tool.id}: merge ${snippet} into ${target}; follow ${join(docs, tool.id.toUpperCase() + '.md')} for prerequisites`);
+      continue;
+    }
+    if (state?.status === 'conflict') {
+      steps.push(`${tool.id}: review the existing ${tool.id} entry in ${join(root, host.file)} against ${snippet} (existing entry kept)`);
+      continue;
+    }
+    if (tool.id === 'codecalc') {
+      steps.push(`codecalc: if uv or Python 3.10+ is missing, install it using ${join(docs, 'CODECALC.md')}`);
+    } else if (tool.id === 'obsidian-tc' && (!state || state.needsConfiguration)) {
+      steps.push(`obsidian-tc: set OBSIDIAN_TC_CONFIG in ${join(root, host.file)} to your config file path; follow ${join(docs, 'OBSIDIAN-TC.md')} for vault setup`);
+    }
+  }
+  return steps;
+}