model-orchestrator 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-09-27
+
+### Security
+
+- `aunx route-metrics` always runs the packaged metrics implementation. A checkout can no longer substitute its own JavaScript when a user requests a summary.
+- Installer and uninstall manifests use bounded regular-file reads with symlink refusal. Acceptance-check and routing JSON reads share the same bounded reader.
+- Acceptance-check timeouts and interrupts clean up the command's process group or Windows process tree, including ordinary descendants.
+- Weekly gateway probes pass credentials through stdin instead of temporary files, reject multiline keys, and remove gateway/provider credentials from audit subprocesses. The service now reads a separate `weekly-audit.env`; see the generated jobs README when upgrading.
+- Newly generated companion launch commands use the catalog's exact versions, and npm publication uses a reviewed exact npm version. Existing client entries are preserved; follow the [companion upgrade steps](docs/install.md#upgrading-companion-launch-commands).
+
+### Fixed
+
+- Security and installation documentation now match current activation rules, model inheritance, companion setup and credential boundaries.
+
 ## [1.0.0] - 2026-09-27
 
 ### Added
@@ -499,7 +513,8 @@ First release.
 - Tests: a case per fix, judges proven to go red, mutation checks; `npm test` prints the current count.
 - Adversarial audit: two Codex rounds plus a two-engine review (Codex, Antigravity); findings and fixes in `docs/audit-brief.md`. After the review: subagents go to the project root (`--project`), snippet paths computed from `--dir`, lane sections rendered from the selection, a primary agent required, level 3 asks for API keys separately from CLIs, images and CLI installs pinned, an activation summary at the end of every install.
 
-[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/aunysillyme/model-orchestrator/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.35...v1.0.0
 [0.1.35]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.34...v0.1.35
 [0.1.34]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.33...v0.1.34

package/README.md

@@ -209,6 +209,8 @@ Run `npx model-orchestrator --uninstall --dir ./ai-orchestrator --project .` (ad
 
 Node 18 or newer, with zero runtime dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu. Windows: CI runs the suite on `windows-latest` (Node 18, 20, 22), including lane execution end to end through `cli-run` against a fake CLI installed the same way npm installs a real one (a `.cmd` shim). `cli-run` never runs a lane through `cmd.exe`: it resolves the shim to the Node script underneath and spawns Node directly, so a prompt reaching a real lane never passes through a Windows shell. A `.cmd` or `.bat` lane that cannot be resolved that way (an old or hand-edited shim) is refused with exit 13 and a message saying how to fix it, rather than run through `cmd.exe`: a batch file re-reads its arguments after `cmd.exe` has parsed them once, and no escaping fully contains a prompt through both passes. Install, detection, the hooks and `cli-run`'s `taskkill` tree kill are tested on Windows too, including SIGTERM/SIGINT to the wrapper (Windows has no OS-level signals: both terminate it unconditionally, verified there rather than treated the same as POSIX). The Windows skip list covers POSIX behavior, with each skip pinned by `test/prose.test.js`: `statSync().mode`'s executable bit (NTFS has none, so that one assertion is conditional inside a test that otherwise runs everywhere); a lane dying mid-run from a real POSIX signal (a real Windows lane cannot die "by signal"); running `weekly-audit.sh`'s watchdog functions for real under Git Bash's job control, both the end-to-end run and the `bounded()` timeout check (the script itself only ever runs on the Ubuntu box it targets); and a `mkfifo` FIFO at the rules path, the one case that proves `route-gate.mjs` cannot HANG on a non-regular file, since Windows has no `mkfifo` to build one (the guard behind it is covered on every OS by a directory at the same path); and an untracked `mkfifo` FIFO in the repository `cli-run --audit` sizes, the case that proves `--effort auto` never opens a non-regular file (the symlink half of that test runs on every OS). `test/prose.test.js` counts every `skip:` in the suite and requires this list to document each one.
 
+Additional security regressions skip Windows for the project-hook symlink and manifest FIFO fixtures (symlink privileges and POSIX special files), the POSIX shell descendant timeout fixture (the argv equivalent still runs on Windows), and four weekly credential and report lifecycle runtime checks (the Ubuntu watchdog requires POSIX process-tree semantics). Their configuration and generated syntax remain covered on every platform.
+
 **Privacy.** The installer sends no telemetry and makes no network call of its own once it is running. Two things around that are worth being exact about:
 
 - `npx model-orchestrator` is itself a download: npm fetches this package from the registry before any of it runs. `npm install -g model-orchestrator` once, then run `model-orchestrator`, if you would rather that happen exactly one time.

package/SECURITY.md

@@ -1,8 +1,12 @@
 # Security policy
 
-This tool writes files into folders you name (`--dir` and `--project`) and, only after you say yes per package, runs `npm install -g <package>` for packages pinned in `src/catalog.js`. It never runs a vendor shell script, never writes a credential, and never overwrites a document without `--force`; the two stated exceptions (machine-owned config, hash-verified runtime files) are in the README. `bin/cli-run.mjs` spawns the agent CLI you name with the prompt you give it, in its own process group, and kills that group on timeout, overrun or signal. Nothing here makes a network call of its own; the vendor CLIs and `npm install` do.
+The installer writes files inside the folders you name (`--dir` and `--project`). It never installs third-party packages, runs vendor shell scripts or writes credentials. Companion tools are opt-in; their guides and launch snippets use the exact versions in `src/catalog.js`. You run any third-party installation yourself. Home-level agent configuration is outside the installer scope.
 
-Threat model and the audit rounds that shipped with each release: `docs/audit-brief.md` and `CHANGELOG.md`.
+Existing documents stay by default. `--force` explicitly replaces them; `--update-docs` replaces only unchanged managed documents. Machine-owned manifests and lane configuration refresh on every run, and unchanged managed runtime files upgrade automatically. `--upgrade-runtime` explicitly replaces runtime files. Project activation merges supported rules, hooks and companion entries with backups; interactive confirmation enables it by default, while `--yes` requires `--apply-snippets`. See [installation and ownership rules](docs/install.md).
+
+`bin/cli-run.mjs` spawns the agent CLI you name with your prompt in its own process group and kills that group on timeout, overrun or signal. Vendor CLIs and companion tools may access the network and local data under their own permissions. The separately invoked level 3 setup and weekly audit scripts have their own installation and network behavior; inspect their generated instructions before running them.
+
+Completed reviews and current guarantees: [security review history](docs/security-review-history.md), [guarantees](docs/guarantees.md) and [changelog](CHANGELOG.md).
 
 ## Reporting a vulnerability
 
@@ -14,4 +18,4 @@ Findings are reproduced before they are acted on; `CLEAN` is an acceptable outco
 
 ## Scope
 
-In scope: `bin/`, `src/`, `scripts/`, the templates, and the files the installer writes from them (the weekly audit job, compose file, gateway config and setup script included). Out of scope: the agent CLIs, models and companion tools this package installs or links to; report those to their own projects.
+In scope: `bin/`, `src/`, `scripts/`, the templates, and the files the installer writes from them (the weekly audit job, compose file, gateway config and setup script included). Out of scope: the agent CLIs, models and companion tools this package links to; report those to their own projects.

package/docs/catalog.md

@@ -308,27 +308,29 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 
 ## Companion tools
 
+Model-orchestrator project activation merges supported MCP entries for selected companions when activation is enabled. The vendor command auto-registration field below describes what the listed vendor command does when you run it yourself. Global client configuration remains manual.
+
 ### `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/`
+- **Install:** `uvx 'codecalc[full]==0.5.0' setup --write` (needs uv (https://docs.astral.sh/uv/) and Python 3.10+)
+- **Vendor command auto-registration:** Claude Code, Claude Desktop, Cursor, VS Code, Zed; snippets for the rest are written to `mcp/`
 - **Default:** not 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/`
+- **Install:** `npm install -g obsidian-tc@1.26.0 && 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)
+- **Vendor command auto-registration:** Cursor, VS Code; snippets for the rest are written to `mcp/`
 - **Default:** not selected
 
 ### `context7` · Context7 (Upstash: version-aware docs for the libraries your agent calls)
 
 - **Repo:** https://github.com/upstash/context7
 - **Gives:** up-to-date, version-specific documentation and code examples for libraries, SDKs, APIs and CLIs, pulled into the prompt; tells the agent what the code is SUPPOSED to do. Paired with codecalc, which runs the code and proves what it actually does: docs never stand as proof, and where they disagree the run wins
-- **Install:** `npx ctx7 setup` (needs Node.js 18+ for the local server or the ctx7 CLI; a free CONTEXT7_API_KEY is optional, for higher rate limits (it works anonymously at the base rate))
-- **Registers itself with:** Claude Code, Cursor, Codex CLI, Qwen Code; snippets for the rest are written to `mcp/`
+- **Install:** `npx -y @upstash/context7-mcp@4.1.1` (needs Node.js 18+ for the local server or the ctx7 CLI; a free CONTEXT7_API_KEY is optional, for higher rate limits (it works anonymously at the base rate))
+- **Vendor command auto-registration:** none; use project activation or merge the supplied snippets in `mcp/` using the tool guide
 - **Default:** not selected
 

package/docs/install.md

@@ -2,6 +2,12 @@
 
 Everything the installer asks, writes and accepts as a flag. The short version is in the [README](../README.md).
 
+## Upgrading companion launch commands
+
+Version 1.0.1 pins newly generated companion launch commands. Existing MCP server entries remain yours and are not silently replaced. Preview your existing selection and paths with `--update-docs --dry`, then apply that update after checking the plan. Unchanged managed snippets in `mcp/` refresh; edited snippets are preserved and named. Compare the refreshed snippets with each client's configuration and manually replace any preserved floating package command with its catalog-pinned form. Keep unrelated server settings and credentials unchanged.
+
+For a level 3 weekly job, also follow the generated `vm/jobs/README.md` migration to the separate `weekly-audit.env` file and reload any copied systemd unit.
+
 ## Install walkthrough
 
 ![Terminal walkthrough of the installer](demo.gif)
@@ -71,7 +77,7 @@ An install has two targets, and a scripted run should set both.
 | `--dir` | `./ai-orchestrator` | the docs, protocols and (level 2+) `bin/cli-run.mjs`. Named after what it contains, not after this package, so a project can hold one without looking like a checkout of it. Pass `--dir ./model-orchestrator` if you prefer the package name. |
 | `--project` | the current directory | the main agent's supported subagent definitions: `.claude/agents/` for Claude Code or `.agents/agents/` for Antigravity; Claude Code's hook scripts in `.claude/hooks/`. With activation enabled, the catalog-supported rules file, Claude Code's `.claude/settings.json` and selected companion entries in its `.mcp.json` are merged with backups. |
 
-`--project` defaulting to the current directory is the one that surprises people: run the command from your home folder with Claude Code as the main agent and the subagent and hook files land in your home folder. The installer prints the resolved project path in the plan and says when you left it at the default. Set it.
+`--project` defaults to the current directory. Home-level agent configuration is refused: a Claude Code install targeting your home folder cannot write its subagents, hooks or project settings there. Choose a project folder below your home directory and set `--project` explicitly. The installer prints the resolved project path in the plan and says when you left it at the default.
 
 Rules inside the project use project-relative snippet paths, so moving the whole project preserves them. Rules outside the project use absolute paths and carry a relocation note. After moving those rules, re-run the installer or set `MODEL_ORCHESTRATOR_RULES_DIR` for the installed rule-reading hooks, and update your agent instruction paths. An absolute override names the new folder; a relative override is relative to `CLAUDE_PROJECT_DIR`. `route-metrics` reads no rules and keeps its home-directory log. The separately installed Claude Code plugin keeps its existing default-path lookup.
 

package/docs/security-review-history.md

@@ -6,6 +6,7 @@ This page summarizes completed reviews recorded in the [changelog](../CHANGELOG.
 
 | Release | Review recorded | What the review found | What changed and where it is checked |
 |---|---|---|---|
+| 1.0.1 | Codex Security scan and regression-backed remediation | A metrics summary executed project code; manifest reads and check descendants needed bounds; weekly jobs inherited gateway credentials | Packaged metrics dispatch, bounded file readers, check process-tree cleanup, stdin-only gateway probe and separate audit environment; `test/security-cli.test.js`, `test/security-vm.test.js`, `test/security-pins.test.js` |
 | 0.1.0 | Initial review and follow-up round, with a second model-family review | Paths could escape the write roots, partial writes could remain, malformed arguments could proceed, and empty results could appear successful | Containment preflight, exclusive writes with rollback, strict flag parsing and vendor-specific result checks; `test/install.test.js`, `test/cli.test.js`, `test/judges.test.js` |
 | 0.1.1 | Follow-up on issues #1 through #10 | Child processes could survive timeouts; a failed scheduled run could replace a good report; logs could contain provider text | Process-group cleanup, temporary report plus rename, bounded probes and fixed log codes; `test/cli.test.js`, `test/install.test.js` |
 | 0.1.2 | Follow-up on issues #12 through #15 | Interrupt cleanup, split UTF-8 output and stale existing files could produce misleading results | Interrupt handlers, streaming decoders and a pre-run snapshot for `--expect-file`; `test/cli.test.js` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-orchestrator",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Model router for AI coding agents: installs routing rules, 8 subagents, hooks and a CLI runner so your AI picks model and effort per task and saves tokens",
   "type": "module",
   "bin": {

package/src/README.md

@@ -2,6 +2,7 @@
 
 | File | Job |
 |---|---|
+| `bounded-file.js` | shared regular-file reader for manifests and check configuration: no-follow/nonblocking open, identity checks and a fixed byte cap even if a file grows. Unsafe files are refused; callers decide how to handle missing or malformed data. |
 | `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`. |

package/src/aunx.js

@@ -1,8 +1,9 @@
-import { spawn, spawnSync } from 'node:child_process';
-import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, parse, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { windowsSpawnPlan } from '../bin/cli-run.mjs';
+import { killTree, windowsSpawnPlan } from '../bin/cli-run.mjs';
+import { MANIFEST_BYTE_CAP, readRegularFile } from './bounded-file.js';
 import { byId } from './catalog.js';
 import { ROLE_SPECS } from './roles.js';
 
@@ -85,13 +86,7 @@ export function scaffold(template, target) {
 }
 
 function readChecks(path) {
-  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
-  let config;
-  try {
-    const stat = fstatSync(fd);
-    if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error('checks file must be a regular JSON file of at most 1 MiB');
-    config = JSON.parse(readFileSync(fd, 'utf8'));
-  } finally { closeSync(fd); }
+  const config = JSON.parse(readRegularFile(path, MANIFEST_BYTE_CAP).toString('utf8'));
   if (!config || config.version !== 1 || !Array.isArray(config.checks) || !config.checks.length) throw new Error('expected version: 1 and a non-empty checks array');
   const ids = new Set();
   for (const check of config.checks) {
@@ -105,7 +100,39 @@ function readChecks(path) {
   return config.checks;
 }
 
-export function runChecks(file) {
+function runCheck(command, args, options, cwd, timeoutMs) {
+  return new Promise(resolveCheck => {
+    let child, timer, settled = false, timedOut = false, interrupted;
+    const stop = () => {
+      if (!child?.pid) return;
+      try { killTree(child.pid); }
+      catch { try { child.kill('SIGKILL'); } catch { /* already exited */ } }
+    };
+    const finish = (status, signal, error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      process.off('SIGINT', onInterrupt);
+      process.off('SIGTERM', onTerminate);
+      stop();
+      resolveCheck({ status, signal, error: timedOut ? { code: 'ETIMEDOUT' } : error, interrupted });
+    };
+    const onSignal = signal => { interrupted ||= signal; stop(); };
+    const onInterrupt = () => onSignal('SIGINT');
+    const onTerminate = () => onSignal('SIGTERM');
+    process.on('SIGINT', onInterrupt);
+    process.on('SIGTERM', onTerminate);
+    try {
+      child = spawn(command, args, { ...options, cwd, stdio: 'inherit', detached: process.platform !== 'win32' });
+      child.once('error', error => finish(null, null, error));
+      child.once('exit', (status, signal) => finish(status, signal));
+      timer = setTimeout(() => { timedOut = true; stop(); }, timeoutMs);
+      if (interrupted) stop();
+    } catch (error) { finish(null, null, error); }
+  });
+}
+
+export async function runChecks(file) {
   const path = resolve(file);
   // Validate the whole file before the first command can mutate anything.
   const checks = readChecks(path);
@@ -133,10 +160,11 @@ export function runChecks(file) {
       }
       ({ command, args, options = {} } = plan);
     }
-    const result = spawnSync(command, args, { ...options, cwd, stdio: 'inherit', timeout: check.timeoutMs || 30000, killSignal: 'SIGKILL' });
+    const result = await runCheck(command, args, options, cwd, check.timeoutMs || 30000);
     const pass = !result.error && result.status === 0;
     failed ||= !pass;
     console.log(`${pass ? 'PASS' : 'FAIL'} ${check.id}: ${result.error ? result.error.code : result.signal ? `signal ${result.signal}` : `exit ${result.status}`}`);
+    if (result.interrupted) return result.interrupted === 'SIGINT' ? 130 : 143;
   }
   return failed ? 1 : 0;
 }
@@ -149,25 +177,10 @@ export function readManifestRoles({ dir, cwd = process.cwd() } = {}) {
     join(cwd, 'ai-orchestrator', 'MANIFEST.json'),
     join(cwd, 'MANIFEST.json')
   ];
-  const maxBytes = 1024 * 1024;
   const roleIds = new Set(ROLE_SPECS.map(spec => spec.id));
   for (const path of new Set(candidates)) {
-    let fd;
     try {
-      const before = lstatSync(path);
-      if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes) continue;
-      fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
-      const after = fstatSync(fd);
-      if (!after.isFile() || after.size > maxBytes || after.dev !== before.dev || after.ino !== before.ino) continue;
-      const buffer = Buffer.alloc(maxBytes + 1);
-      let length = 0;
-      while (length < buffer.length) {
-        const count = readSync(fd, buffer, length, buffer.length - length, null);
-        if (!count) break;
-        length += count;
-      }
-      if (length > maxBytes) continue;
-      const manifest = JSON.parse(buffer.toString('utf8', 0, length));
+      const manifest = JSON.parse(readRegularFile(path, MANIFEST_BYTE_CAP).toString('utf8'));
       const roles = manifest?.roles;
       if (!roles || typeof roles !== 'object' || Array.isArray(roles) || !Object.keys(roles).length) continue;
       if (Object.entries(roles).some(([id, role]) => !roleIds.has(id) || !role || typeof role !== 'object' || Array.isArray(role)
@@ -177,8 +190,6 @@ export function readManifestRoles({ dir, cwd = process.cwd() } = {}) {
       return roles;
     } catch {
       // Missing, invalid, non-regular or unreadable JSON is an absent manifest.
-    } finally {
-      if (fd !== undefined) closeSync(fd);
     }
   }
   return null;
@@ -233,8 +244,7 @@ export async function main(args) {
     return runNode(join(ROOT, 'bin', 'cli-run.mjs'), parsed.rest);
   }
   if (command === 'route-metrics') {
-    const local = join(process.cwd(), '.claude', 'hooks', 'route-metrics.mjs');
-    return runNode(regular(local) ? local : join(ROOT, 'templates', 'agents', 'snippets', 'route-metrics.mjs'), rest.length ? rest : ['--summary']);
+    return runNode(join(ROOT, 'templates', 'agents', 'snippets', 'route-metrics.mjs'), rest.length ? rest : ['--summary']);
   }
   if (command === 'brief' && rest.length === 0) { process.stdout.write(readFileSync(join(COMMON, 'TASK_BRIEF.md'), 'utf8')); return 0; }
   if (['brief', 'context', 'checks'].includes(command)) {

package/src/bounded-file.js

@@ -0,0 +1,31 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from 'node:fs';
+
+export const MANIFEST_BYTE_CAP = 1024 * 1024;
+const refused = message => Object.assign(new Error(message), { code: 'UNSAFE_FILE' });
+
+// A fixed buffer also bounds files that grow after the initial size check.
+export function readBounded(fd, maxBytes) {
+  const stat = fstatSync(fd);
+  if (!stat.isFile()) throw refused('expected a regular file');
+  if (stat.size > maxBytes) throw refused(`file exceeds byte limit ${maxBytes}`);
+  const buffer = Buffer.alloc(maxBytes + 1);
+  let length = 0;
+  while (length < buffer.length) {
+    const count = readSync(fd, buffer, length, buffer.length - length, null);
+    if (!count) break;
+    length += count;
+  }
+  if (length > maxBytes) throw refused(`file exceeds byte limit ${maxBytes}`);
+  return buffer.subarray(0, length);
+}
+
+export function readRegularFile(path, maxBytes) {
+  const before = lstatSync(path);
+  if (!before.isFile() || before.isSymbolicLink()) throw refused('expected a regular file, not a symlink');
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+  try {
+    const after = fstatSync(fd);
+    if (!after.isFile() || after.dev !== before.dev || after.ino !== before.ino) throw refused('file changed during inspection');
+    return readBounded(fd, maxBytes);
+  } finally { closeSync(fd); }
+}

package/src/catalog.js

@@ -400,7 +400,7 @@ export const TOOLS = [
     name: 'codecalc (calculator, code runner, logic checker for your agent)',
     repo: 'https://github.com/The-40-Thieves/codecalc',
     role: '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",
+    get install() { return `uvx 'codecalc[full]==${this.pin}' setup --write`; },
     pin: '0.5.0',
     mcpSnippets: { 'claude-code': 'mcp/mcpServers.json', codex: 'mcp/codex.config.toml', agy: 'mcp/agy.mcp_config.json', qwen: 'mcp/mcpServers.json' },
     requires: 'uv (https://docs.astral.sh/uv/) and Python 3.10+',
@@ -413,7 +413,7 @@ export const TOOLS = [
     name: 'obsidian-tc (governed memory: an agent-ready MCP server over an Obsidian vault)',
     repo: 'https://github.com/The-40-Thieves/obsidian-tc',
     role: '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',
+    get install() { return `npm install -g obsidian-tc@${this.pin} && obsidian-tc /path/to/your/vault`; },
     pin: '1.26.0',
     mcpSnippets: { 'claude-code': 'mcp/obsidian-tc.mcpServers.json', codex: 'mcp/obsidian-tc.codex.config.toml', agy: 'mcp/obsidian-tc.agy.mcp_config.json', qwen: 'mcp/obsidian-tc.mcpServers.json' },
     requires: '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',
@@ -426,11 +426,11 @@ export const TOOLS = [
     name: 'Context7 (Upstash: version-aware docs for the libraries your agent calls)',
     repo: 'https://github.com/upstash/context7',
     role: 'up-to-date, version-specific documentation and code examples for libraries, SDKs, APIs and CLIs, pulled into the prompt; tells the agent what the code is SUPPOSED to do. Paired with codecalc, which runs the code and proves what it actually does: docs never stand as proof, and where they disagree the run wins',
-    install: 'npx ctx7 setup',
+    get install() { return `npx -y @upstash/context7-mcp@${this.pin}`; },
     pin: '4.1.1',
     mcpSnippets: { 'claude-code': 'mcp/context7.claude-code.mcp.json', codex: 'mcp/context7.codex.config.toml', agy: 'mcp/context7.agy.mcp_config.json', qwen: 'mcp/context7.qwen.settings.json' },
     requires: 'Node.js 18+ for the local server or the ctx7 CLI; a free CONTEXT7_API_KEY is optional, for higher rate limits (it works anonymously at the base rate)',
-    autoClients: ['Claude Code', 'Cursor', 'Codex CLI', 'Qwen Code'],
+    autoClients: [], // The pinned MCP server does not register itself; merge its snippets.
     recommended: false,
     optionalNote: 'Optional, and from a different maintainer than codecalc and obsidian-tc (Upstash, not The-40-Thieves). Needs a network call even at the anonymous rate; skip it offline. MIT.'
   }

package/src/install.js

@@ -9,6 +9,7 @@ import { ROLE_SPECS, assignRoles, roleTable, roleRoute, manifestRoles, inferPrim
 import { LANE_FLAGS } from '../bin/cli-run.mjs';
 import { AIS, LEVELS, TOOLS, PROVIDERS, IMAGES, byId, toolById, providerById, npmSpec, summaryWithEvidence } from './catalog.js';
 import { companionRegistrationSteps } from './apply-companions.js';
+import { MANIFEST_BYTE_CAP, readRegularFile } from './bounded-file.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const GENERATOR_VERSION = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version;
@@ -1007,10 +1008,11 @@ export function fileClass(rel, separator = sep) {
 
 export function readManifest(dir) {
   try {
-    const j = JSON.parse(readFileSync(join(resolve(dir), 'MANIFEST.json'), 'utf8'));
+    const j = JSON.parse(readRegularFile(join(resolve(dir), 'MANIFEST.json'), MANIFEST_BYTE_CAP).toString('utf8'));
     return j && typeof j === 'object' ? j : null;
-  } catch {
-    return null;
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) return null;
+    throw error;
   }
 }
 

package/src/uninstall.js

@@ -4,6 +4,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32 } fr
 import { dirProblems, globalConfigProblem, realRoot } from './install.js';
 import { START, END } from './apply-snippets.js';
 import { validateActivationOwnership } from './activation-ownership.js';
+import { MANIFEST_BYTE_CAP, readBounded } from './bounded-file.js';
 
 const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
@@ -70,7 +71,7 @@ function readRegular(item) {
   try {
     const actual = fstatSync(fd);
     if (!actual.isFile() || actual.dev !== expected.dev || actual.ino !== expected.ino) throw refused(`file changed during inspection: ${item.abs}`);
-    return { bytes: readFileSync(fd), stat: actual };
+    return { bytes: item.maxBytes ? readBounded(fd, item.maxBytes) : readFileSync(fd), stat: actual };
   } finally { closeSync(fd); }
 }
 
@@ -176,7 +177,7 @@ function applyRemoval(item, plan) {
 // inventory, never authority to expand the two roots supplied by the caller.
 export function uninstallFiles({ dir, project, dry = false }) {
   const roots = { dir: targetRoot(dir), project: targetRoot(project) };
-  const manifest = entry('MANIFEST.json', roots);
+  const manifest = { ...entry('MANIFEST.json', roots), maxBytes: MANIFEST_BYTE_CAP };
   const saved = readRegular(manifest);
   if (!saved) throw refused(`missing manifest: ${join(resolve(dir), 'MANIFEST.json')}`);
   let data;

package/templates/advanced/vm/ENVIRONMENT.md

@@ -10,6 +10,14 @@ These are variable **names**. The values live in a secrets manager and are injec
 
 `GATEWAY_MASTER_KEY` is the bearer every client presents to the gateway. Generate it once (`openssl rand -hex 32`), store it in the manager, never paste it into a file here. It must be a single token matching `^[A-Za-z0-9._-]+$`: the audit job interpolates it into curl's config grammar and refuses anything else.
 
+## Gateway and scheduled audit environments
+
+Inject the provider names above only into the environment used to launch the gateway with Compose. The weekly audit service instead reads `~/.config/ai-orchestrator/weekly-audit.env`, outside the installation and mode 600, containing only `GATEWAY_MASTER_KEY`. Do not point that service at the gateway's provider-key file. Existing installations must update and reload their copied systemd unit when adopting this template.
+
+The audit script removes `GATEWAY_MASTER_KEY`, `LITELLM_MASTER_KEY`, and the gateway provider names `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, and `OPENROUTER_API_KEY` from child environments. It supplies the gateway header to curl through stdin, without a credential temp file or an argv value. Newlines anywhere in the key are rejected before collection.
+
+Vendor version probes and the report worker retain `HOME`, `PATH`, stored vendor sign-ins, and unrelated authentication variables. Configure the selected lane's own sign-in in the systemd user's account, such as `hermes auth add <provider>` for Hermes. An API-only lane relying solely on one of the removed provider variables needs vendor-supported stored authentication before this scheduled job can run; gateway keys are not a substitute for that setup.
+
 ## Rules
 
 - Never print a value in a terminal or a log. Verify by length or by a hash prefix.

package/templates/advanced/vm/docker-compose.yml

@@ -1,4 +1,5 @@
-# The gateway is the ONLY holder of provider credentials on this box.
+# This gateway receives provider credentials from its own launch environment.
+# The weekly audit uses a separate environment containing only the gateway bearer.
 # It is bound to loopback. Put it behind a private mesh network if other
 # machines need it; never publish it on 0.0.0.0.
 services:

package/templates/advanced/vm/jobs/README.md

@@ -21,7 +21,27 @@ systemctl --user list-timers        # it should be listed with a next-run time
 loginctl enable-linger "$USER"      # so user timers run without a login session
 ```
 
-The service reads `GATEWAY_MASTER_KEY` from an `EnvironmentFile` that lives outside this folder (mode 600). Point the `EnvironmentFile=` line at yours before installing. The key must be a single token matching `^[A-Za-z0-9._-]+$`; the script refuses anything else.
+The service reads only `GATEWAY_MASTER_KEY` from `~/.config/ai-orchestrator/weekly-audit.env`, outside this folder with mode 600. Provision that audit-only file from your secrets manager and point `EnvironmentFile=` at it before installing. Keep the gateway's provider-key environment separate. Existing installs must replace or edit their copied service, then run `systemctl --user daemon-reload`; updating the source template alone does not update the installed unit. The key must be a single token matching `^[A-Za-z0-9._-]+$`; any embedded or trailing newline is refused.
+
+Sign the selected vendor CLI in under the same user before enabling the timer. The job preserves `HOME`, `PATH`, stored sign-in state and unrelated authentication variables, but removes `GATEWAY_MASTER_KEY`, `LITELLM_MASTER_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, and `OPENROUTER_API_KEY` from all child environments. An API-only lane dependent on a removed variable needs vendor-supported stored authentication, such as `hermes auth add <provider>`, before scheduling it. Those provider keys belong in the gateway launch environment.
+
+## Invocation, dependencies, reads and writes
+
+The Monday timer starts the user service, which runs Bash on `vm/jobs/weekly-audit.sh`. The script queries the local gateway using curl, collects user timers and installed CLI versions, assembles a brief, and invokes `node bin/cli-run.mjs` with the selected audit lane. Dependencies are Bash, Node, curl, jq, pgrep, standard shell utilities, the systemd user session, and the selected signed-in CLI. The gateway probe may fail without preventing the report: that section becomes `UNVERIFIED`.
+
+The script reads `protocols/gap-analysis.md`, `DELEGATION_MATRIX.md` (falling back to `ORCHESTRATOR.md`), and collected live state. It writes `reports/live-state-<stamp>.md`, the `live-state.md` symlink, `audit-brief-<stamp>.md`, and a dated report or retained failed output. Credential headers travel only through a pipe into curl's stdin. No gateway credential temp file is created.
+
+## The closed loop
+
+The timer schedules the job; the script records unknown probes in its brief; the worker returns a report; a clean, non-empty result replaces the dated report. The journal records its exit code and report path. **Watched by: nothing.** The operator must inspect the journal and report after a failed service or add a notifier, then update the table above. Automatic notification and remediation are not configured.
+
+## Failure modes
+
+- **Invalid key:** exit 2 before collection; correct the audit-only environment through the secrets manager.
+- **Missing environment file:** systemd cannot start the service; provision the file and check its path and permissions.
+- **Failed probe:** the live-state section says `UNVERIFIED`; check the named dependency and retry.
+- **Missing lane or sign-in:** cli-run returns its failure code, retaining failed output and preserving the last good report. Configure that user's vendor sign-in and PATH.
+- **Timeout:** the watchdog stops probe descendants, and the service's whole-job deadline kills its cgroup. A killed run can leave a non-secret report temp file; a later run sweeps report temps older than a day.
 
 ## Verify a job ran
 
@@ -31,11 +51,18 @@ journalctl --user -u weekly-audit.service -n 50
 ls -la {{INSTALL_DIR}}/reports/
 ```
 
+For a manual check, start `systemctl --user start weekly-audit.service`, then run the checks above. Confirm a new dated report contains the expected gap analysis and read any `UNVERIFIED` sections before treating the run as healthy. Verify the service uses the audit-only environment by inspecting its `EnvironmentFile=` path, never by printing environment values. Test coverage in the package's `test/security-vm.test.js` uses synthetic runtime credentials and stub CLIs to check stdin delivery, child environment isolation, invalid keys, and report preservation; it calls no vendor service.
+
 ## What the job guarantees
 
 - **Bounded:** every probe (gateway, `systemctl`, each CLI `--version`) runs under a 10 s watchdog; the model call under 600 s; the unit under `TimeoutStartSec=900`, which kills the whole cgroup.
 - **Previous report preserved:** output goes to a temp file and is renamed over `audit-<date>.md` only on a clean, non-empty run. A failed run leaves `failed-audit-<stamp>-rc<N>.md` beside it and the last good report untouched.
 - **Boundary:** the lane runs with the strongest restriction it offers ({{AUDIT_LANE_BOUNDARY_NOTE}}). The brief's denied-actions list is an instruction, not an enforcement, for lanes without a sandbox flag.
 - **Honest unknowns:** a probe that times out writes an `UNVERIFIED` line, which the brief tells the lane to treat as unknown, never clean.
+- **Credential separation:** the gateway bearer is never written to a temp file or passed on argv, and gateway/provider keys are absent from version probes and the report worker's environment. Stored vendor sign-ins remain available.
 
 A timer that has never been seen to fire is not known to work. Run `systemctl --user start weekly-audit.service` once by hand and read the journal before trusting the schedule.
+
+## Source of truth
+
+The installed `vm/jobs/weekly-audit.sh`, `weekly-audit.service`, and `weekly-audit.timer` define behavior; the copied unit in `~/.config/systemd/user/` is what systemd runs. This README describes that job end to end. Live scheduling and vendor authentication remain UNVERIFIED until the manual run succeeds on your VM.

package/templates/advanced/vm/jobs/weekly-audit.service

@@ -8,8 +8,10 @@ WorkingDirectory={{INSTALL_DIR_SYSTEMD}}
 # Add absolute Node and vendor CLI directories if they live outside these defaults.
 # systemd does not expand shell variables in Environment=.
 Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
-# Names come from a file OUTSIDE this repo, mode 600. Edit the path.
-EnvironmentFile=%h/.config/ai-orchestrator/gateway.env
+# Audit-only file OUTSIDE this repo, mode 600: GATEWAY_MASTER_KEY only.
+# Provider credentials stay in the separate gateway/Compose environment.
+# Vendor CLIs use this user's stored sign-in state. Edit the path if needed.
+EnvironmentFile=%h/.config/ai-orchestrator/weekly-audit.env
 ExecStart=/bin/bash "{{INSTALL_DIR_SYSTEMD}}/vm/jobs/weekly-audit.sh"
 # Whole-job deadline: collection probes (6 x 10 s) + the 600 s model call + cleanup.
 # On expiry systemd kills the whole cgroup, so nothing the job spawned survives.

package/templates/advanced/vm/jobs/weekly-audit.sh

@@ -14,6 +14,20 @@ AUDIT_LANE="{{AUDIT_LANE}}"
 AUDIT_LANE_FLAGS="{{AUDIT_LANE_FLAGS}}"
 PROBE_SECS="${PROBE_SECS:-10}"      # per collection probe
 RUNNER_SECS="${RUNNER_SECS:-600}"   # the model call; TimeoutStartSec in the unit covers the whole job
+# Keep the probe credential in this shell only. Gateway provider keys belong to
+# Compose, not to collection tools or the scheduled vendor CLI. Stored vendor
+# sign-ins, HOME, PATH, and unrelated authentication variables remain available.
+KEY="${GATEWAY_MASTER_KEY:-}"
+export -n KEY
+unset GATEWAY_MASTER_KEY LITELLM_MASTER_KEY ANTHROPIC_API_KEY OPENAI_API_KEY GEMINI_API_KEY XAI_API_KEY OPENROUTER_API_KEY
+
+# A shell pattern checks the whole value, including embedded/trailing newlines.
+# Line-oriented grep accepts a valid line even when another line is malformed.
+case "$KEY" in
+  *[!A-Za-z0-9._-]*)
+    echo "weekly-audit: GATEWAY_MASTER_KEY must match ^[A-Za-z0-9._-]+$ (generate it with: openssl rand -hex 32)" >&2
+    exit 2 ;;
+esac
 {{AUDIT_LANE_GUARD}}
 cd "$INSTALL_DIR" || { echo "weekly-audit: $INSTALL_DIR missing" >&2; exit 2; }
 mkdir -p reports
@@ -47,7 +61,9 @@ killtree() {
 bounded() {
   local secs="$1"; shift
   local fired; fired="$(mktemp "${TMPDIR:-/tmp}/wa-fired.XXXXXX" 2>/dev/null)" && rm -f "$fired"
-  ( "$@" ) & local pid=$!
+  # Bash otherwise replaces stdin with /dev/null for asynchronous commands.
+  # Preserve the caller's pipe explicitly so curl can read its config on stdin.
+  ( "$@" ) <&0 & local pid=$!
   ( sleep "$secs"; [ -n "$fired" ] && : > "$fired"; killtree "$pid" ) >/dev/null 2>&1 & local wd=$!
   wait "$pid" 2>/dev/null; local rc=$?
   killtree "$wd" >/dev/null 2>&1; wait "$wd" 2>/dev/null
@@ -55,29 +71,19 @@ bounded() {
   return $rc
 }
 
-# The gateway key must be a single token: it is interpolated into curl's config
-# grammar, and a quote or newline in it would become a second directive.
-KEY="${GATEWAY_MASTER_KEY:-}"
-if [ -n "$KEY" ] && ! printf '%s' "$KEY" | grep -Eq '^[A-Za-z0-9._-]+$'; then
-  echo "weekly-audit: GATEWAY_MASTER_KEY must match ^[A-Za-z0-9._-]+$ (generate it with: openssl rand -hex 32)" >&2
-  exit 2
-fi
-
 DATE="$(date -u +%F)"
 STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
 {
   echo "# live state $DATE"; echo
   echo "## gateway lanes"
   if [ -n "$KEY" ]; then
-    # The key never enters argv: curl reads the header from a 0600 config file that
-    # exists only for this probe. curl's own timeouts AND the watchdog bound it.
-    CFG="$(umask 077 && mktemp "${TMPDIR:-/tmp}/audit-curl-XXXXXX")"
-    printf 'header = "Authorization: Bearer %s"\n' "$KEY" > "$CFG"
-    if ! bounded "$PROBE_SECS" curl -s --connect-timeout 5 --max-time "$PROBE_SECS" --max-filesize 1048576 --config "$CFG" http://127.0.0.1:4000/v1/models \
+    # No secret file or argv value: the builtin printf feeds curl through a pipe.
+    # curl's own timeouts AND the watchdog bound it, including a hung reader.
+    if ! printf 'header = "Authorization: Bearer %s"\n' "$KEY" \
+      | bounded "$PROBE_SECS" curl -s --connect-timeout 5 --max-time "$PROBE_SECS" --max-filesize 1048576 --config - http://127.0.0.1:4000/v1/models \
       | jq -r '.data[].id' 2>/dev/null; then
       echo "UNVERIFIED: gateway unreachable or timed out within ${PROBE_SECS}s"
     fi
-    rm -f "$CFG"
   else
     echo "UNVERIFIED: GATEWAY_MASTER_KEY not set; gateway not queried"
   fi
@@ -91,6 +97,7 @@ STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
     fi
   done
 } > "reports/live-state-$STAMP.md"
+unset KEY
 ln -sfn "live-state-$STAMP.md" reports/live-state.md
 
 # The brief the worker actually reads: the protocol, the intended configuration,

package/templates/common/protocols/acceptance-checks.md

@@ -4,6 +4,7 @@
 - Scaffold a checks file with `aunx checks`. Replace the intentionally failing example with a real verifier before using the file.
 - Prefer an argv array for `command`, for example `["node", "--test", "test/example.test.js"]`. String commands run through the local shell, so review them as executable code before running a checks file.
 - Set `cwd` relative to the checks file. Keep checks inside the task's authorized scope.
+- Checks run sequentially with inherited terminal output. A timeout stops the command and its ordinary descendants; interrupts stop the run. A finished check must not leave a background service running. This lifecycle cleanup is not a sandbox for hostile programs that escape their process group.
 - Demonstrate a failing case for each new gate before trusting a passing result.
 - Include availability facts when later work depends on a tool, permission or service remaining accessible.
 - Run `aunx checks run ACCEPTANCE_CHECKS.json` against the final artifact. A failed command gives the gate exit code 1.

package/templates/tools/codecalc/CODECALC.md

@@ -9,13 +9,13 @@ What it gives every agent in this folder: exact arithmetic (`evaluate_expression
 Needs `uv` (https://docs.astral.sh/uv/) and Python 3.10+.
 
 ```bash
-uvx 'codecalc[full]' setup            # prints what it would do, changes nothing
-uvx 'codecalc[full]' setup --write    # merges the codecalc entry into your client's config, copies the skill
+uvx 'codecalc[full]=={{CODECALC_PIN}}' setup            # prints what it would do, changes nothing
+uvx 'codecalc[full]=={{CODECALC_PIN}}' setup --write    # merges the codecalc entry into your client's config, copies the skill
 ```
 
-`setup` detects Claude Desktop, Claude Code, Cursor, VS Code and Zed (`--client=NAME` if several), runs two real canaries and ends in one verdict: `ready` / `degraded` / `not-ready`. It backs up the client config it touches. `uvx 'codecalc[full]' doctor` prints a config block with your absolute paths.
+`setup` detects Claude Desktop, Claude Code, Cursor, VS Code and Zed (`--client=NAME` if several), runs two real canaries and ends in one verdict: `ready` / `degraded` / `not-ready`. It backs up the client config it touches. `uvx 'codecalc[full]=={{CODECALC_PIN}}' doctor` prints a config block with your absolute paths.
 
-Pinned form, if you want the version this installer was released with: `uvx 'codecalc[full]=={{CODECALC_PIN}}' setup --write`. `[full]` is the edition that actually runs everything documented (about 120 MB). Base `codecalc` is execution only; symbolic tools then return a `dependency_missing` error naming the extra, never a silent failure.
+These commands and the shipped launch snippets use the catalog version this installer was released with. Review a newer release before changing that pin. `[full]` is the edition that actually runs everything documented (about 120 MB). Base `codecalc` is execution only; symbolic tools then return a `dependency_missing` error naming the extra, never a silent failure.
 
 ## Register more agents with `mcp/` snippets
 

package/templates/tools/codecalc/mcp/agy.mcp_config.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "codecalc": {
       "command": "uvx",
-      "args": ["codecalc[full]"]
+      "args": ["codecalc[full]=={{CODECALC_PIN}}"]
     }
   }
 }

package/templates/tools/codecalc/mcp/codex.config.toml

@@ -1,4 +1,4 @@
 # Merge into ~/.codex/config.toml
 [mcp_servers.codecalc]
 command = "uvx"
-args = ["codecalc[full]"]
+args = ["codecalc[full]=={{CODECALC_PIN}}"]

package/templates/tools/codecalc/mcp/mcpServers.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "codecalc": {
       "command": "uvx",
-      "args": ["codecalc[full]"]
+      "args": ["codecalc[full]=={{CODECALC_PIN}}"]
     }
   }
 }

package/templates/tools/codecalc/mcp/vscode.mcp.json

@@ -2,7 +2,7 @@
   "servers": {
     "codecalc": {
       "command": "uvx",
-      "args": ["codecalc[full]"]
+      "args": ["codecalc[full]=={{CODECALC_PIN}}"]
     }
   }
 }

package/templates/tools/codecalc/mcp/zed.settings.json

@@ -2,7 +2,7 @@
   "context_servers": {
     "codecalc": {
       "command": "uvx",
-      "args": ["codecalc[full]"],
+      "args": ["codecalc[full]=={{CODECALC_PIN}}"],
       "env": {}
     }
   }

package/templates/tools/context7/CONTEXT7.md

@@ -35,19 +35,15 @@ Two ways to connect, remote first (Context7's own documented default, and the on
 # (mcp.context7.com/mcp/oauth), as an alternative to an API key, not required either.
 
 # Local alternative: runs the MCP server on your machine over stdio.
-npx -y @upstash/context7-mcp
-
-# Or the one-command setup Context7 itself ships, which authenticates via OAuth,
-# writes an API key, and can install a CLI-based skill instead of MCP:
-npx ctx7 setup
+npx -y @upstash/context7-mcp@{{CONTEXT7_PIN}}
 ```
 
-Pinned form, if you want the version this installer was released against: `npx -y @upstash/context7-mcp@{{CONTEXT7_PIN}}`. Drop the pin for latest; `npx` always resolves fresh, so pinning only matters when you want a reproducible version rather than whatever shipped this week.
-
-`npx ctx7 setup` is upstream's own guided installer; it is not run by this installer, only documented here, the same way this project never runs a vendor script for you.
+The local command and shipped launch snippets use the catalog version this installer was released against. Review a newer release before changing that pin. The remote endpoint is operated by Upstash and cannot be version-pinned by this package. This installer runs neither connection nor a third-party setup command for you.
 
 ## Register it with your agent (snippets in `mcp/`)
 
+When Context7 is selected and project activation is enabled, model-orchestrator merges its entry into a supported project MCP configuration, including Claude Code's `.mcp.json`. Existing conflicting entries are kept for review. With activation disabled or a global client configuration, merge the relevant snippet manually.
+
 Every snippet below ships **keyless**: the remote ones point at the hosted endpoint with no `Authorization` header at all (Qwen Code's snippet keeps the non-credential `Accept` header upstream itself ships), and both Zed snippets run the local, version-pinned `npx` server with no key in its `env` block. That is deliberate, not an oversight: see "Higher rate limits" next for why a header is not shipped by default.
 
 | Agent | File to edit | Snippet |
@@ -87,12 +83,12 @@ Anonymous works. If you hit the rate limit and want a key, add it the correct wa
 - **Codex CLI**: under the `[mcp_servers.context7]` table in `~/.codex/config.toml`, add a `bearer_token_env_var` entry naming the environment variable `CONTEXT7_API_KEY`. Codex reads the token from that variable at connect time and sends it as the `Authorization` header itself; the config file never holds the value ([Codex MCP docs](https://developers.openai.com/codex/mcp)).
 - **Claude Code** (`mcp/context7.claude-code.mcp.json`): add a `headers` object to the `context7` entry with an `Authorization` field whose value is `Bearer` followed by a `${CONTEXT7_API_KEY}` reference. Claude Code expands `${VAR}` references in a remote server's `headers` at load time, and `CONTEXT7_API_KEY` is not one of the credential names it deliberately reads as empty (those are Claude/Anthropic-specific). Set the variable in your environment before launching; an unset variable still loads with the literal, unexpanded reference sent as the header, and Context7 answers every call with "Invalid API key" instead of running anonymously ([Claude Code MCP docs](https://code.claude.com/docs/en/mcp)). That failure, not a missing feature, is why this snippet ships with no header at all.
 - **Claude Desktop**: the Connectors UI has its own key field; use it there rather than editing a file.
-- **Any local `npx` connection** (Zed, or the local alternative for any other client): export `CONTEXT7_API_KEY` in the shell that launches your editor or agent. A spawned stdio child process inherits its parent's environment by default, so `npx -y @upstash/context7-mcp` picks it up with no config edit; this is the same environment variable name Context7's own Docker MCP Toolkit config and its GitHub Copilot integration use to feed the server a key. If your client does not pass its environment through to the child (uncommon), either stay anonymous, or check whether that client's own config format has an `env` block that itself supports an environment-variable reference (Claude Code's does, described above; not every client's does) rather than typing the key in.
+- **Any local `npx` connection** (Zed, or the local alternative for any other client): export `CONTEXT7_API_KEY` in the shell that launches your editor or agent. A spawned stdio child process inherits its parent's environment by default, so `npx -y @upstash/context7-mcp@{{CONTEXT7_PIN}}` picks it up with no config edit; this is the same environment variable name Context7's own Docker MCP Toolkit config and its GitHub Copilot integration use to feed the server a key. If your client does not pass its environment through to the child (uncommon), either stay anonymous, or check whether that client's own config format has an `env` block that itself supports an environment-variable reference (Claude Code's does, described above; not every client's does) rather than typing the key in.
 - **Cursor, VS Code, Qwen Code, Antigravity `agy`, or any other client using the `mcpServers.json`/`vscode.mcp.json`/`qwen.settings.json`/`agy.mcp_config.json` snippet**: check that client's own docs for whether it expands an environment-variable reference inside a remote server's `headers` before adding one. This is not confirmed for any of them here. If it does not expand, the literal, unexpanded text becomes the header value and every call fails with "Invalid API key" instead of running anonymously, which is worse than shipping no header at all.
 
 ## Security posture, read before you send anything through it
 
-Only the library name and your query text reach Context7's API; your source code is never uploaded. It is still a third-party network call on every lookup, unlike codecalc (offline) and obsidian-tc (local by default): do not route a query that would leak a private project name, an internal library name, or anything else you would not put in a public search box. The docs it indexes are community-contributed, not vetted by Context7 or by this installer; a suspicious or malicious-looking result is reportable upstream from the project's page. An API key raises your rate limit; it is not a secret worth protecting the way a database credential is, but it still never belongs in a committed file, only in your environment.
+Library names and query text are sent to Context7's API. If an agent includes source code, credentials or private context in a query, that content leaves the machine too. Review what your agent sends and use public library names and non-sensitive queries. The local stdio server still calls the remote service; it does not make lookups private or offline. The docs it indexes are community-contributed, not vetted by this installer; report suspicious results upstream. Keep API keys in your environment or your client's supported credential store, never in committed files.
 
 ## Level 3
 

package/templates/tools/obsidian-tc/OBSIDIAN-TC.md

@@ -29,7 +29,7 @@ A durable, searchable, governed store that the protocols can call by name:
 ## Install
 
 ```bash
-npm install -g obsidian-tc@{{OBSIDIAN_TC_PIN}}   # the version this installer was released with; drop the pin for latest
+npm install -g obsidian-tc@{{OBSIDIAN_TC_PIN}}   # reviewed catalog version; review an upgrade before changing the pin
 ollama pull nomic-embed-text
 obsidian-tc /path/to/your/vault          # zero-config: one vault named "main", local only
 obsidian-tc plugin install --vault /path/to/your/vault   # optional companion plugin, then enable it in Obsidian
@@ -68,7 +68,7 @@ Every snippet here spawns `npx`, and on Windows `npx` is a batch file (`npx.cmd`
 
 The SDK point covers more than these two clients: every published `@modelcontextprotocol/sdk` from 1.23.0 through 1.30.0 depends on `cross-spawn ^7.0.5` and uses it in the stdio client, so any client that connects through the stock TypeScript SDK inherits the same `PATHEXT` resolution. `shell: false` in that transport is not the whole story, and reading only that line is how a client gets mistaken for one that cannot start `npx`.
 
-One Windows case can still fail, and it is not about `.cmd`. Zed prefers PowerShell for the system shell (`get_windows_system_shell` in `crates/gpui_util/src/lib.rs` falls back to `cmd.exe` only when PowerShell is missing), and PowerShell resolves a bare `npx` to npm's `npx.ps1` shim when one is installed. Under the `Restricted` execution policy that is Windows' client default, running a `.ps1` is blocked. If Zed reports that the server would not start, check `Get-ExecutionPolicy` first, and if that is the cause, change the Zed entry by hand to `"command": "cmd"` with `"args": ["/d", "/c", "npx", "-y", "obsidian-tc"]`, keeping the rest of the block. `/d` is there on purpose: it skips any Command Processor `AutoRun` command, which would otherwise run first and can print non-JSON into the protocol stream.
+One Windows case can still fail, and it is not about `.cmd`. Zed prefers PowerShell for the system shell (`get_windows_system_shell` in `crates/gpui_util/src/lib.rs` falls back to `cmd.exe` only when PowerShell is missing), and PowerShell resolves a bare `npx` to npm's `npx.ps1` shim when one is installed. Under the `Restricted` execution policy that is Windows' client default, running a `.ps1` is blocked. If Zed reports that the server would not start, check `Get-ExecutionPolicy` first, and if that is the cause, change the Zed entry by hand to `"command": "cmd"` with `"args": ["/d", "/c", "npx", "-y", "obsidian-tc@{{OBSIDIAN_TC_PIN}}"]`, keeping the rest of the block. `/d` is there on purpose: it skips any Command Processor `AutoRun` command, which would otherwise run first and can print non-JSON into the protocol stream.
 
 None of this was run on a Windows machine by this project. The five verdicts are from each client's own shipped code; the PowerShell case is from Zed's shell choice plus documented `Restricted` behaviour, and is the one worth reporting back if you hit it.
 

package/templates/tools/obsidian-tc/mcp/obsidian-tc.agy.mcp_config.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "obsidian-tc": {
       "command": "npx",
-      "args": ["-y", "obsidian-tc"],
+      "args": ["-y", "obsidian-tc@{{OBSIDIAN_TC_PIN}}"],
       "env": { "OBSIDIAN_TC_CONFIG": "/ABSOLUTE/PATH/TO/obsidian-tc.config.json" }
     }
   }

package/templates/tools/obsidian-tc/mcp/obsidian-tc.codex.config.toml

@@ -1,7 +1,7 @@
 # Merge into ~/.codex/config.toml
 [mcp_servers.obsidian-tc]
 command = "npx"
-args = ["-y", "obsidian-tc"]
+args = ["-y", "obsidian-tc@{{OBSIDIAN_TC_PIN}}"]
 
 [mcp_servers.obsidian-tc.env]
 OBSIDIAN_TC_CONFIG = "/ABSOLUTE/PATH/TO/obsidian-tc.config.json"

package/templates/tools/obsidian-tc/mcp/obsidian-tc.mcpServers.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "obsidian-tc": {
       "command": "npx",
-      "args": ["-y", "obsidian-tc"],
+      "args": ["-y", "obsidian-tc@{{OBSIDIAN_TC_PIN}}"],
       "env": { "OBSIDIAN_TC_CONFIG": "/ABSOLUTE/PATH/TO/obsidian-tc.config.json" }
     }
   }

package/templates/tools/obsidian-tc/mcp/obsidian-tc.vscode.mcp.json

@@ -3,7 +3,7 @@
     "obsidian-tc": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "obsidian-tc"],
+      "args": ["-y", "obsidian-tc@{{OBSIDIAN_TC_PIN}}"],
       "env": { "OBSIDIAN_TC_CONFIG": "/ABSOLUTE/PATH/TO/obsidian-tc.config.json" }
     }
   }

package/templates/tools/obsidian-tc/mcp/obsidian-tc.zed.settings.json

@@ -2,7 +2,7 @@
   "context_servers": {
     "obsidian-tc": {
       "command": "npx",
-      "args": ["-y", "obsidian-tc"],
+      "args": ["-y", "obsidian-tc@{{OBSIDIAN_TC_PIN}}"],
       "env": { "OBSIDIAN_TC_CONFIG": "/ABSOLUTE/PATH/TO/obsidian-tc.config.json" }
     }
   }