model-orchestrator 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [1.0.3] - 2026-09-28
+
+### Security
+
+- Weekly audit jobs use an explicit child environment allowlist, keep selected worker configuration overrides out of probes, and preserve stored sign-in paths. See the generated jobs README for migration (#45).
+- Catalog package and container pins get advisory checks with explicit coverage, dated machine-readable results and expiring advisory-specific exceptions. See [catalog advisory checks](docs/catalog-advisories.md) for operation and limitations (#46).
+
+### Added
+
+- `aunx route-metrics --summary` compares the route your agent named in each reply with the delegation that actually followed, from data the log already records: the share of sessions that match, sessions that named a route and dispatched nothing, and sessions that dispatched without naming one.
+
+### Fixed
+
+- The product website navigation follows the section being read, keeps the active sidebar link visible, and labels its portfolio breadcrumb Home.
+
+## [1.0.2] - 2026-09-28
+
+### Fixed
+
+- A refused symlinked or changing file (such as `MANIFEST.json`) now names its path and the fix: replace the link with the file it points to. Since 1.0.1, rerunning the installer over a symlinked manifest stops instead of treating it as a fresh install.
+- A path shown in a refusal escapes control characters, so a crafted file name cannot write terminal escape sequences; a directory or other non-file gets "expected a regular file" without symlink advice.
+- The acceptance-check protocol states the timeout's reach: it stops the command's process group, and a descendant that starts its own session (for example with `setsid`) keeps running.
+
+### Added
+
+- Product website at `model-orchestrator.aunysillyme.dev`, with repository-generated documentation, changelog, and the model-orchestrator trailer. Main-branch pushes rebuild the site through Vercel; the published version is checked against npm.
+
 ## [1.0.1] - 2026-09-27
 
 ### Security
@@ -513,7 +540,9 @@ First release.
 - Tests: a case per fix, judges proven to go red, mutation checks; `npm test` prints the current count.
 - Adversarial audit: two Codex rounds plus a two-engine review (Codex, Antigravity); findings and fixes in `docs/audit-brief.md`. After the review: subagents go to the project root (`--project`), snippet paths computed from `--dir`, lane sections rendered from the selection, a primary agent required, level 3 asks for API keys separately from CLIs, images and CLI installs pinned, an activation summary at the end of every install.
 
-[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v1.0.3...HEAD
+[1.0.3]: https://github.com/aunysillyme/model-orchestrator/compare/v1.0.2...v1.0.3
+[1.0.2]: https://github.com/aunysillyme/model-orchestrator/compare/v1.0.1...v1.0.2
 [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

package/README.md

@@ -209,7 +209,7 @@ 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.
+Additional security regressions skip Windows for the project-hook symlink and manifest FIFO fixtures and the symlinked-manifest refusal message (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:
 

package/docs/README.md

@@ -12,6 +12,7 @@ Use these pages for setup, operation and evidence. The [front page](../README.md
 | [Intermediate](part-2-intermediate.md) | Delegation across several AI CLIs |
 | [Advanced](part-3-advanced.md) | Gateway templates and scheduled work on a Linux host |
 | [Catalog](catalog.md) | Supported tools, capability facts, unverified values, installation and sign-in notes |
+| [Catalog advisory checks](catalog-advisories.md) | Package and container coverage, report statuses, exceptions and manual verification |
 | [Security review history](security-review-history.md) | Review rounds, reproduced findings, fixes and regression tests |
 | [Proof](../proof/README.md) | Dated measurements, methods, sample sizes and reproduction scripts |
 | [Commands](../bin/README.md) | `aunx` subcommands and lane-runner exit codes |

package/docs/catalog-advisories.md

@@ -0,0 +1,114 @@
+# Catalog advisory checks
+
+## What and why
+
+The repository checks exact executable package and container pins in `src/catalog.js`. OSV API v1 answers direct npm and PyPI package/version queries. Trivy examines OS and language packages in the selected container image. This check gives dated advisory evidence for its stated coverage. A clean result does not prove safety.
+
+The owning files are `scripts/catalog-advisory-inventory.mjs`, `scripts/check-catalog-advisories.mjs`, `scripts/catalog-advisory-http.mjs`, `scripts/catalog-advisory-containers.mjs`, `docs/catalog-advisory-exceptions.json` and `.github/workflows/catalog-advisories.yml`. This document describes the complete operating procedure.
+
+## Trigger
+
+The `catalog advisories` workflow runs on every push to main, on pull requests changing the catalog, checker, exceptions, tests or workflow, and by manual dispatch. It has read-only repository permissions. There is no periodic schedule; a maintainer can dispatch a fresh check when advisory data changes. Existing Dependabot automation continues to update GitHub Actions separately.
+
+## Invocation chain
+
+1. The workflow checks out the source and selects Node 22.
+2. The inventory imports `AIS`, `TOOLS`, `IMAGES` and `PROVIDERS` directly from the catalog. npm names come from `install.npm`; companion ecosystem, package and extras come from their `advisory` metadata. Every version comes from the existing pin field.
+3. The package adapter posts exact package/version queries to `https://api.osv.dev/v1/querybatch`, then retrieves each returned advisory from `/v1/vulns/<id>` to retain ranges and fixed versions.
+4. The container adapter resolves target tags to a platform-specific SHA-256 manifest digest, checks the manifest and image configuration, and records the platform. Docker Hub and GHCR public images are supported; another registry is unknown until its adapter is implemented.
+5. The adapter resolves the Trivy scanner image to a digest too, asserts its reported version, and runs that scanner against the target digest. It starts no target image or vendor service. Scanning uses registry access, with no host mounts or Docker socket passed into the scanner.
+6. Exact, unexpired exceptions are applied. The checker writes `report.json` and `summary.md`, then exits with its result code. The workflow appends the summary to the job and uploads both files even if the scan step fails.
+
+## Dependencies
+
+A repository checkout, Node 18+ with built-in fetch, Docker with a running Linux-container daemon, public HTTPS registry access, OSV, and the Trivy vulnerability databases are needed for a complete local check. CI supplies Node 22 and Docker. Package checks need only Node and OSV. A missing scanner, daemon or database produces unknown container results while retaining available package results.
+
+Trivy is version-pinned in `scripts/catalog-advisory-containers.mjs`. Each run resolves that scanner tag to an immutable digest and records it in each container result. Runtime version verification rejects a binary that reports a different version. The version probe has a 60-second deadline; image scans have Trivy's 10-minute deadline and a 12-minute client deadline, followed by bounded container cleanup. The scanner tag itself can move between runs; the recorded digest is the reproducible scanner identity for that run. For exact reproduction, fetch the scanner and target digests from the report before investigating.
+
+Pin provenance, checked 2026-09-28 against upstream: `actions/checkout` `3d3c42e` is tag v7.0.1, `actions/setup-node` `8207627` is tag v7.0.0, and `actions/upload-artifact` `043fb46` is tag v7.0.1 in each action owner's repository. Trivy 0.74.0 is the latest release in Aqua Security's official repository (2026-08-14) and its public image tag resolves to `sha256:62b1e65e8869bc4b4c6aa4fa2b21595256c7c2f6018a9d9ad61caf87187c1969`. The first successful main-branch artifact is the check that the JSON parser matches this Trivy version.
+
+To update the scanner, verify the desired release in Aqua Security's official Trivy repository, resolve its public registry tag to a digest, and inspect the pinned version's `image --help`, JSON report schema and database requirements. Change `TRIVY` in `scripts/catalog-advisory-containers.mjs`, run the offline fixtures, then run the real checker and inspect its recorded scanner digest and version. This builder could not compare the JSON parser with current official Trivy source; that compatibility is **UNVERIFIED** until a real scan passes. To update an action, compare its full commit SHA against the release tag in the action owner's repository and update the SHA and version comment together. Run the workflow and download the artifact before accepting either upgrade.
+
+## Reads
+
+- `src/catalog.js`: package names, ecosystems, extras, exact versions, image references and excluded inputs. A new companion without advisory metadata becomes unknown.
+- `docs/catalog-advisory-exceptions.json`: the reviewed exception array, initially empty.
+- OSV: current direct-package advisory matches and their details. No project files are sent.
+- Public container registries: manifests, configurations, layers and anonymous pull authorization. Anonymous registry tokens stay in memory. User sign-ins are not read by the resolver; the Docker client receives an empty temporary configuration directory.
+- Trivy databases: current OS and language advisories. All severities and unfixed findings are retained.
+
+Direct package checks do not resolve dependency trees. Each such input has an explicit transitive-dependency exclusion. `codecalc[full]` also has an optional-extras exclusion: querying the base distribution does not cover dependencies selected by `full`. Vendor installer scripts, unpinned downloads/package-manager inputs, chat apps and hosted model services are named exclusions. Compatibility snapshots such as `builtAgainst` are not installation pins. Image coverage is the OS and language packages Trivy recognizes; unsupported OS images and empty package results are unknown.
+
+## Writes
+
+The default output directory is `.release-work/catalog-advisories/`. The checker writes:
+
+- `report.json`: source commit, timestamp, scanner versions, catalog input, ecosystem, exact version, image/scanner digest, platform, coverage, status, advisory IDs, ranges, fixed versions and matched exception expiry.
+- `summary.md`: the same result in a concise human-readable form, with explicit exclusions.
+
+CI retains these as `catalog-advisories-<commit>-<attempt>` for 30 days and shows the summary in the job. An early workflow failure creates an unknown fallback report instead of presenting a missing report as success. The checker creates and removes an empty temporary Docker configuration directory. Scanner cache data lives under `/tmp/trivy` in its disposable writable container layer; `--rm` removes that layer. A disk-backed layer accommodates large image scans without a small RAM-backed cache cap. The scanner runs as a nonroot user with capabilities dropped, no new privileges, and no host filesystem or socket mounts. Live disk usage is **UNVERIFIED** here. Catalog pins and installed dependencies are never changed.
+
+## The closed loop
+
+GitHub Actions is the watcher. A maintainer reviews every affected or unknown result before merging or releasing. No automatic issue, upgrade, exception or release is created by this workflow. Branch-protection configuration is repository administration: **UNVERIFIED** here. To make a green check mandatory, require the `catalog advisories / scan` check in the repository's branch rules.
+
+| Status | Meaning | Exit behavior |
+|---|---|---|
+| clean | Complete adapter response with no advisory match in stated coverage | 0 if every result is clean or excepted |
+| affected | At least one advisory match lacks a valid exception | 1 unless another result is unknown |
+| unknown | Missing, unavailable, unsupported or malformed evidence, or an invalid exception policy | 2 |
+| excepted | Every advisory match has an exact, reviewed, unexpired exception | 0 if every result is clean or excepted |
+
+Any unknown takes precedence over affected for the exit code. Known advisory IDs are still retained when a detail lookup fails. Empty results never pass. Read the exclusions alongside the status; exclusions are never counted as clean pins.
+
+## Failure modes
+
+- **OSV timeout, HTTP error or malformed response:** package results become unknown. A valid empty query result (`{}`) means no returned match; a missing result array or missing position is unknown.
+- **Registry failure, bad image reference, missing platform or digest mismatch:** the image is unknown. The checker retains the other results.
+- **Docker, scanner or database failure:** the image is unknown. No exception suppresses unknown status. Check network access and the daemon, then rerun the same source.
+- **Incomplete scanner JSON, mismatched digest/platform or unsupported image OS:** the image is unknown even if the process exited successfully.
+- **Advisory outage:** keep the failing result, retry after recovery, and inspect the provider's status through its normal support channel. An outage is not an exception for a package.
+- **Expired or malformed exception:** expired entries stop matching at 00:00 UTC on their expiry date; malformed policy blocks success. Expired entries are retained in `expiredExceptions` for review.
+- **Interrupted job:** `always()` upload and summary steps preserve available evidence. A runner outage can still prevent artifact upload; verify artifact presence in the run itself.
+
+## Exception review
+
+The exception file is a JSON array. Every entry requires `ecosystem`, `package`, `version`, `advisory`, `rationale` and `expires` (`YYYY-MM-DD`). Wildcards and unknown fields are rejected. Match the exact advisory ID emitted by the adapter, not an alias. A package exception optionally names its exact catalog `source` in `target`. A container exception requires `target` equal to the exact catalog image reference and identifies the vulnerable component package and installed version, not every component in the image.
+
+For example, a metadata-only example is:
+
+```json
+[
+  {
+    "ecosystem": "npm",
+    "package": "fixture-package",
+    "version": "1.0.0",
+    "advisory": "TEST-2026-0001",
+    "rationale": "Example only: replace with a reviewed reason and tracking reference.",
+    "expires": "2026-10-01"
+  }
+]
+```
+
+A maintainer reviews the affected range, fixed versions, applicability, expiry and rationale in a normal pull request. Use a short explicit expiry and a tracking reference in the rationale. Never add an exception merely because the database or scanner is unavailable. Review expired entries and remove those whose pin or advisory is no longer relevant. A matched exception remains visible as excepted with its expiry; it is never relabeled clean. Fixing a package requires a separate deliberate catalog-pin change and the usual installer validation.
+
+## Run and verify by hand
+
+From the repository checkout:
+
+```bash
+node --test test/catalog-advisories.test.js
+node scripts/check-catalog-advisories.mjs --report-dir .release-work/catalog-advisories
+```
+
+The fixture tests use metadata only and make no network request. The second command makes real advisory and registry requests and may start the pinned scanner container. Use `--platform linux/arm64` to inspect another declared image platform; the default is `linux/amd64`. Use `--exceptions <path>` for a reviewed alternate policy and retain that file with the evidence.
+
+1. Read both output files and check `sourceCommit`, `generatedAt`, every catalog source, scanner identity, platform and exclusions.
+2. For a package finding, retrieve its recorded OSV detail URL and compare the affected package, ranges and fixed versions. The fixture's affected result must exit 1; an unavailable-data result must exit 2.
+3. For an image finding, pull the recorded scanner digest and run its `image --scanners vuln --list-all-pkgs --format json --platform <platform> --image-src remote <image>@<digest>` command. Compare the component name, installed version, advisory ID and database evidence. A later database can change matches while the image stays identical.
+4. Inspect the GitHub run on main and download its report artifact. A local report is not proof of main-branch retention. Re-run the workflow after an outage and confirm a new timestamp.
+5. Run `npm test` before releasing. Existing OIDC publication and installer flags are unchanged by this check.
+
+## Source of truth
+
+Catalog pins and companion metadata: `src/catalog.js`. Exception decisions: `docs/catalog-advisory-exceptions.json` and its reviewed change. Operational behavior: this document and the checker modules. Dated evidence: the uploaded GitHub run artifact. Upstream evidence: each report's OSV URL and Trivy data-source URL. A report describes the source commit, selected platform and database responses at its recorded time; it is not a permanent certificate.

package/docs/catalog-advisory-exceptions.json

@@ -0,0 +1 @@
+[]

package/docs/part-2-intermediate.md

@@ -50,7 +50,7 @@ Optional companions can help: codecalc for execution and calculations, obsidian-
 
 ## Measure your own routing
 
-`aunx route-metrics --summary` reads your local Claude Code routing log. It reports where work went, route-marker coverage and subagent durations. Your own measurements are the basis for changing assignments and checking whether the rules are being followed.
+`aunx route-metrics --summary` reads your local Claude Code routing log. It reports where work went, route-marker coverage, subagent durations, and whether the route each reply named matches the delegation that followed. Your own measurements are the basis for changing assignments and checking whether the rules are being followed.
 
 ## What the installer gives you at this level
 

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.2 | Independent review of 1.0.1 by a second model family, then an audit of its fix | A detached check descendant outlived the timeout while the notes said descendants stop; a symlinked-manifest refusal named no file or fix; refusal paths could carry terminal escapes; a directory got symlink advice | The protocol states the process-group limit; refusals name the path, escape control characters and give advice by file type; `test/security-messages.test.js` |
 | 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` |

package/llms.txt

@@ -29,6 +29,7 @@ Pick a model proxy (LiteLLM, Portkey, OpenRouter, claude-code-router) for per-re
 - [Claude Code plugin](https://github.com/aunysillyme/model-orchestrator/blob/main/plugin/README.md): installing read-only routing hooks and subagents through the plugin marketplace
 - [Proof](https://github.com/aunysillyme/model-orchestrator/blob/main/proof/README.md): dated measurements, methods, sample sizes, expiry and reproduction scripts
 - [Security review history](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/security-review-history.md): completed review rounds, incident summaries and regression evidence
+- [Catalog advisory checks](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/catalog-advisories.md): package and container inventory, coverage, report statuses, exceptions and manual verification
 - [Changelog](https://github.com/aunysillyme/model-orchestrator/blob/main/CHANGELOG.md): release changes and upgrade notes
 - [Agent instructions](https://github.com/aunysillyme/model-orchestrator/blob/main/AGENTS.md): headless setup and contributor checks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-orchestrator",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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

@@ -3,7 +3,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. |
+| `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. Package pins, companion advisory metadata and image references also supply the repository's advisory inventory. |
 | `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. |

package/src/bounded-file.js

@@ -2,6 +2,8 @@ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from '
 
 export const MANIFEST_BYTE_CAP = 1024 * 1024;
 const refused = message => Object.assign(new Error(message), { code: 'UNSAFE_FILE' });
+// A path is printed to a terminal; control characters (escape sequences) are shown escaped.
+const shown = path => String(path).replace(/[\u0000-\u001f\u007f-\u009f]/g, c => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`);
 
 // A fixed buffer also bounds files that grow after the initial size check.
 export function readBounded(fd, maxBytes) {
@@ -21,11 +23,12 @@ export function readBounded(fd, maxBytes) {
 
 export function readRegularFile(path, maxBytes) {
   const before = lstatSync(path);
-  if (!before.isFile() || before.isSymbolicLink()) throw refused('expected a regular file, not a symlink');
+  if (before.isSymbolicLink()) throw refused(`${shown(path)}: expected a regular file, not a symlink; replace the link with the file it points to, then run the command again`);
+  if (!before.isFile()) throw refused(`${shown(path)}: expected a regular file; point the command at a file`);
   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');
+    if (!after.isFile() || after.dev !== before.dev || after.ino !== before.ino) throw refused(`${shown(path)}: file changed during inspection; run the command again`);
     return readBounded(fd, maxBytes);
   } finally { closeSync(fd); }
 }

package/src/catalog.js

@@ -402,6 +402,7 @@ export const TOOLS = [
     role: 'exact arithmetic, code execution in 31 languages, SMT logic checks, complexity and equivalence proofs; offline, no key, no telemetry',
     get install() { return `uvx 'codecalc[full]==${this.pin}' setup --write`; },
     pin: '0.5.0',
+    advisory: { ecosystem: 'PyPI', package: 'codecalc', extras: ['full'] },
     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+',
     autoClients: ['Claude Code', 'Claude Desktop', 'Cursor', 'VS Code', 'Zed'],
@@ -415,6 +416,7 @@ export const TOOLS = [
     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',
     get install() { return `npm install -g obsidian-tc@${this.pin} && obsidian-tc /path/to/your/vault`; },
     pin: '1.26.0',
+    advisory: { ecosystem: 'npm', package: 'obsidian-tc' },
     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',
     autoClients: ['Cursor', 'VS Code'],
@@ -428,6 +430,7 @@ export const TOOLS = [
     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',
     get install() { return `npx -y @upstash/context7-mcp@${this.pin}`; },
     pin: '4.1.1',
+    advisory: { ecosystem: 'npm', package: '@upstash/context7-mcp' },
     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: [], // The pinned MCP server does not register itself; merge its snippets.

package/templates/advanced/vm/ENVIRONMENT.md

@@ -12,11 +12,17 @@ These are variable **names**. The values live in a secrets manager and are injec
 
 ## 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.
+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 `GATEWAY_MASTER_KEY` and optional documented runtime/location settings. 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.
+The audit script builds an explicit allowed environment with shell builtins before its first external command. 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. All provider keys, unrelated exported names, token variables and exported shell functions are absent from child environments.
 
-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.
+The allowed runtime names are `HOME`, `PATH`, `USER`, `LOGNAME`, `SHELL`; `LANG`, `LANGUAGE`, `TZ`; `LC_ALL`, `LC_CTYPE`, `LC_COLLATE`, `LC_MESSAGES`, `LC_MONETARY`, `LC_NUMERIC`, `LC_TIME`, `LC_ADDRESS`, `LC_IDENTIFICATION`, `LC_MEASUREMENT`, `LC_NAME`, `LC_PAPER`, `LC_TELEPHONE`; `TMPDIR`, `TMP`, `TEMP`; `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `XDG_RUNTIME_DIR`, `DBUS_SESSION_BUS_ADDRESS`; and the Windows shell runtime names `SystemRoot`, `SYSTEMROOT`, `WINDIR`. User-service access and stored sign-ins use those same locations.
+
+Only the selected report worker additionally receives its location override: `CODEX_HOME` for `codex`, `HERMES_HOME` for `hermes`. These names are removed from collection/version probes. `agy`, `grok` and `qwen` use stored sign-ins in the common user/configuration locations, with no additional exported authentication name. Configure the selected vendor's sign-in in the systemd user's account, such as `hermes auth add <provider>` for Hermes. API-only setups that depend on exported provider keys need vendor-supported stored authentication before this job can run. Claude Code is not a cli-run worker in this catalog, so its session-token export is removed as well.
+
+`PROBE_SECS` and `RUNNER_SECS` remain shell-only deadline overrides. Set documented runtime and location overrides in the service's `Environment=` settings or audit-only environment file. The key and any selected worker settings stay out of command arguments and logs. There is no arbitrary variable pass-through option.
+
+When migrating, use `--update-docs` for unchanged managed documents, review preserved edited files, apply the new script and docs, update the copied service, then reload systemd. Reconfigure any sign-in that depended on an unrelated export and manually start the service. [The jobs README](jobs/README.md) owns the invocation chain, exact environment contract, migration and verification steps. The environment boundary preserves access to files under HOME/XDG; it does not isolate those files or undo Bash startup files. Real vendor sign-in and systemd behavior remain unverified until the manual run.
 
 ## Rules
 

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

@@ -21,9 +21,28 @@ 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 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.
+The service reads `GATEWAY_MASTER_KEY` and optional documented runtime/location settings 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.
+Sign the selected vendor CLI in under the same user before enabling the timer. Before its first external command, the script uses shell builtins to remove every export except the runtime settings below. It also removes exported shell functions and disables inherited tracing and automatic export. Collection commands and version probes receive this same allowed environment.
+
+| Purpose | Allowed names |
+|---|---|
+| User and executable lookup | `HOME`, `PATH`, `USER`, `LOGNAME`, `SHELL` |
+| Locale and time | `LANG`, `LANGUAGE`, `TZ`, `LC_ALL`, `LC_CTYPE`, `LC_COLLATE`, `LC_MESSAGES`, `LC_MONETARY`, `LC_NUMERIC`, `LC_TIME`, `LC_ADDRESS`, `LC_IDENTIFICATION`, `LC_MEASUREMENT`, `LC_NAME`, `LC_PAPER`, `LC_TELEPHONE` |
+| Temporary directories | `TMPDIR`, `TMP`, `TEMP` |
+| Stored configuration and sign-ins | `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME` |
+| User service and keyring session | `XDG_RUNTIME_DIR`, `DBUS_SESSION_BUS_ADDRESS` |
+| Windows shell runtime compatibility | `SystemRoot`, `SYSTEMROOT`, `WINDIR` |
+
+The report worker additionally receives `CODEX_HOME` when the selected worker is `codex`, or `HERMES_HOME` when it is `hermes`, if that name was set. These location overrides are absent from collection and version probes. The `agy`, `grok` and `qwen` workers use their stored sign-ins under the common user/configuration directories. No token or provider-key variable is allowed for any current worker; `CLAUDE_CODE_OAUTH_TOKEN` is also removed because Claude Code is not a supported cli-run worker in this catalog. Configure authentication with the selected vendor's sign-in flow, such as `codex login`, `grok login`, `hermes auth add <provider>`, `agy`, or Qwen's `/auth`.
+
+`GATEWAY_MASTER_KEY` stays in a private shell variable until the stdin probe finishes and is then removed. `PROBE_SECS` and `RUNNER_SECS` override the shell's deadlines without becoming child exports. Configure the allowed names and worker location overrides through the service's `Environment=` settings or its audit-only environment file. Keep that file limited to the gateway key and the documented runtime/location settings; keep provider credentials in the gateway launch environment. The script provides no arbitrary extra-variable override.
+
+### Migrate an existing job
+
+Preview your existing selection and paths with `--update-docs --dry-run`, then apply the update. Unchanged managed runtime files upgrade automatically; `--update-docs` refreshes unchanged documents. Review any edited files the installer preserves and merge the environment change into those copies, or use `--upgrade-runtime` when you intend to replace edited runtime files. Apply the new script and both environment documents to your installation, then replace or edit the copied service and run `systemctl --user daemon-reload`. Move sign-in setups that depend on other exported names to the vendor's stored sign-in flow under the service user. Reapply only the documented runtime/location overrides, confirm the selected CLI is on the service's explicit PATH, then perform the manual service check below. Changing `AUDIT_LANE` also requires matching that worker's runner configuration and flags.
+
+This boundary limits child environment inheritance. Files under `HOME` and XDG directories remain readable, including stored sign-ins, and Bash startup files run before the script can filter exports. Live vendor authentication must be verified in the service user's account.
 
 ## Invocation, dependencies, reads and writes
 
@@ -59,7 +78,7 @@ For a manual check, start `systemctl --user start weekly-audit.service`, then ru
 - **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.
+- **Credential separation:** the gateway bearer is never written to a temp file or passed on argv. Only the named runtime environment reaches probes, and only the selected worker receives its documented location override. 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.
 

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

@@ -8,7 +8,8 @@ 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"
-# Audit-only file OUTSIDE this repo, mode 600: GATEWAY_MASTER_KEY only.
+# Audit-only file OUTSIDE this repo, mode 600: GATEWAY_MASTER_KEY and optional
+# runtime/location settings from jobs/README.md. Other exports are removed.
 # 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

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

@@ -8,18 +8,32 @@
 #     renamed into place only on a clean exit; failed output is kept beside it for diagnosis
 #   - the lane runs with the strongest boundary it offers ({{AUDIT_LANE_BOUNDARY_NOTE}})
 #   - any nonzero rc from cli-run (10 to 18) means no report was produced; the timer's journal shows it
+# Disable inherited tracing and automatic export before handling credentials.
+set +a +x +v
 set -uo pipefail
 INSTALL_DIR={{INSTALL_DIR_SH}}
 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:-}"
+# Builtins only until the exported environment is reduced to these named runtime
+# settings. De-exporting also handles shell-owned readonly variables. Keep home
+# overrides private until the selected worker runs; stored sign-ins stay on disk.
 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
+KEY="${GATEWAY_MASTER_KEY:-}"
+while IFS= read -r name; do
+  case "$name" in
+    HOME|PATH|USER|LOGNAME|SHELL|LANG|LANGUAGE|TZ|TMPDIR|TMP|TEMP|\
+    LC_ALL|LC_CTYPE|LC_COLLATE|LC_MESSAGES|LC_MONETARY|LC_NUMERIC|LC_TIME|\
+    LC_ADDRESS|LC_IDENTIFICATION|LC_MEASUREMENT|LC_NAME|LC_PAPER|LC_TELEPHONE|\
+    XDG_CONFIG_HOME|XDG_DATA_HOME|XDG_STATE_HOME|XDG_CACHE_HOME|\
+    XDG_RUNTIME_DIR|DBUS_SESSION_BUS_ADDRESS|SystemRoot|SYSTEMROOT|WINDIR) ;;
+    *) export -n "$name" ;;
+  esac
+done < <(compgen -e)
+# Exported shell functions are also outside the child environment contract.
+while IFS= read -r name; do export -nf "$name"; done < <(compgen -A function)
+unset name 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.
@@ -118,8 +132,16 @@ BRIEF="reports/audit-brief-$STAMP.md"
 # Write to a temp file; the dated report is replaced only by a clean, non-empty run.
 FINAL="reports/audit-$DATE.md"
 TMP="$(mktemp "reports/.audit-$STAMP-XXXXXX")"
-# shellcheck disable=SC2086
-node bin/cli-run.mjs "$AUDIT_LANE" $AUDIT_LANE_FLAGS --brief "$BRIEF" --timeout "$RUNNER_SECS" --quiet < /dev/null > "$TMP"
+(
+  # These are configuration locations, not provider keys. All current scheduled
+  # lanes use stored sign-ins; no token variable is part of this contract.
+  case "$AUDIT_LANE" in
+    codex) if [ "${CODEX_HOME+x}" ]; then export CODEX_HOME; fi ;;
+    hermes) if [ "${HERMES_HOME+x}" ]; then export HERMES_HOME; fi ;;
+  esac
+  # shellcheck disable=SC2086
+  exec node bin/cli-run.mjs "$AUDIT_LANE" $AUDIT_LANE_FLAGS --brief "$BRIEF" --timeout "$RUNNER_SECS" --quiet
+) < /dev/null > "$TMP"
 rc=$?
 if [ "$rc" -eq 0 ] && [ -s "$TMP" ]; then
   mv -f "$TMP" "$FINAL"

package/templates/agents/snippets/route-metrics.mjs

@@ -342,6 +342,40 @@ function runSummary(args) {
   const starts = records.filter((r) => r.event === 'start').length;
   const noMatchingStart = Math.max(0, dispatches.length - starts);
 
+  // Reconciliation: does the marker's claim match what the session actually did?
+  // Both halves are already in this log -- the Stop marker says which lane the turn
+  // DECLARED, and the PreToolUse event says what was actually DISPATCHED -- and until
+  // now nothing compared them. A declared lane is a claim; a dispatch is the act.
+  // Grouped by session because a marker is written once per turn while a dispatch can
+  // land on any turn of the same session, so turn-level pairing would report drift
+  // that is only ordering.
+  // PRESENCE, not identity, and the name says so: this asks whether a session that
+  // NAMED a lane went on to dispatch at all, not whether it dispatched the lane it named. A
+  // session that named builder and dispatched reader matches here. Lane identity is
+  // not recoverable from this log, because the marker names a lane from the user's own
+  // ROUTING.md while a dispatch names a subagent_type, and the two vocabularies do not
+  // have to line up.
+  const sessions = new Map();
+  for (const r of records) {
+    if (!r.session_id) continue;
+    if (!sessions.has(r.session_id)) sessions.set(r.session_id, { declaredOff: false, dispatched: false, sawLane: false });
+    const acc = sessions.get(r.session_id);
+    if (r.event === 'dispatch') acc.dispatched = true;
+    if (r.event === 'route' && Array.isArray(r.lane)) {
+      // 'missing' is what the hook writes when a turn carried NO marker, so it is the
+      // absence of a claim, not a claim of inline. Counting it here would double-report
+      // the gap the coverage line above already reports.
+      const named = r.lane.filter((l) => l !== 'missing');
+      if (named.length > 0) acc.sawLane = true;
+      if (named.some((l) => !inlineNames.has(String(l).trim().toLowerCase()))) acc.declaredOff = true;
+    }
+  }
+  const reconcilable = [...sessions.values()].filter((a) => a.sawLane);
+  const claimedNotDone = reconcilable.filter((a) => a.declaredOff && !a.dispatched).length;
+  const doneNotClaimed = reconcilable.filter((a) => !a.declaredOff && a.dispatched).length;
+  const agreed = reconcilable.length - claimedNotDone - doneNotClaimed;
+  const agreedPct = reconcilable.length > 0 ? (agreed / reconcilable.length) * 100 : null;
+
   const ends = records.filter((r) => r.event === 'end' && r.agent_type && typeof r.duration_s === 'number');
   const durationsByType = new Map();
   for (const r of ends) {
@@ -366,6 +400,15 @@ function runSummary(args) {
   if (dispatchCounts.size === 0) lines.push('  (none)');
   for (const [type, count] of [...dispatchCounts.entries()].sort((a, b) => b[1] - a[1])) lines.push('  ' + type + ': ' + count);
   lines.push('dispatches with no matching start: ' + noMatchingStart + ' (a hook or guard blocked them before launch)');
+  lines.push(
+    'delegation claimed vs observed: ' +
+      (agreedPct === null ? 'no session named a lane yet' : formatNumber(agreedPct) + '% of sessions match') +
+      ' (' + agreed + '/' + reconcilable.length + ' sessions that named a lane)'
+  );
+  lines.push('  named a lane, no dispatch in this window: ' + claimedNotDone);
+  lines.push('  dispatched, but every named lane was inline: ' + doneNotClaimed);
+  lines.push('  presence only: a session that named one lane, then dispatched a different one, still counts as matching,');
+  lines.push('  and --since or a rotated log can split a session so one half lands in the counts above.');
   lines.push('duration by agent_type (mean / max, seconds):');
   if (durationsByType.size === 0) lines.push('  (none)');
   for (const [type, durs] of durationsByType) {

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

@@ -4,7 +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.
+- 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: a descendant that starts its own session (for example with `setsid`) leaves the process group and keeps running after the timeout.
 - 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.