model-orchestrator 0.1.35 → 1.0.1

package/templates/intermediate/TIERS.md

@@ -1,93 +1,54 @@
-# TIERS.md: capability tiers and the three cost levers
+# TIERS.md: choose capability, effort and tool reach
 
-The router routes by capability tier, not model name. Each tier maps to a family alias where the vendor offers one, so a routine version bump needs no file change.
+{{STACK_SUMMARY}}
 
-| Tier | Purpose | On {{PRIMARY_NAME}} |
-|---|---|---|
-| deep | ambiguous planning, architecture, strategy, hard debugging | {{PRIMARY_DEEP}} |
-| standard | code writing, code review, execution, live research synthesis | {{PRIMARY_STANDARD}} |
-| fast | classification, extraction, formatting, bulk summarization | {{PRIMARY_FAST}} |
-| escalation | above deep: only when the human asks, or when deep has already run, the call is still unresolved, and the change is irreversible | your vendor's strongest model, if you have one |
-
-Non-primary lanes are owned by `DELEGATION_MATRIX.md`.
-
-## Effort per agent (the third lever)
-
-Tier sets the price per token. Token discipline sets how many tokens. **Effort sets how hard each call thinks.**
-
-`cli-run --effort auto` is a heuristic, not a measurement: prompts below 4,000 characters resolve to medium and longer prompts resolve to high. A codex `--audit` always resolves to high because stakes set the floor. Auto never resolves above high. Name `xhigh` explicitly for a security-critical or irreversible audit.
-
-| Agent | Tier | Effort | Why |
-|---|---|---|---|
-| deep-planner | deep | xhigh | judges every build twice; expensive to get wrong |
-| code-reviewer | standard | high | every endpoint is internet-facing |
-| finding-verifier | standard | high | judging a claim is harder than producing it |
-| builder | standard | high | a botched deploy is the costly failure |
-| live-researcher | standard | medium | tools do the retrieval |
-| bulk-worker | fast | low | the biggest cost win |
-| done-verifier | fast | low | a done-signal check is a lookup, not a judgment call |
-| reader | fast | low | digestion, not judgment |
-
-## Three inputs, not one
-
-Role alone does not decide a route. Two more inputs move it, and they move it in
-opposite directions, so state them separately instead of folding them into the
-role.
+When choosing a model, use the job's required capability and the lane's live roster. A tier names a job; a current family alias or explicit model choice implements it.
 
-**Complexity moves the effort.** The same role does not need the same reasoning
-on every task.
-
-| Complexity | What it looks like | What moves |
+| Tier | Use for | On {{PRIMARY_NAME}} |
 |---|---|---|
-| simple | one file, one obvious edit, no unknowns | drop one effort level |
-| standard | the default | the table above |
-| complex | several surfaces, or an unknown cause | keep effort, add the deep-tier checkpoint |
-| critical | irreversible, or it rewrites a standing rule | the escalation rule below applies |
+| planning model | ambiguous planning, architecture, strategy, unknown causes | {{PRIMARY_DEEP}} |
+| working model | code writing, review, execution and research synthesis | {{PRIMARY_STANDARD}} |
+| cheap model | classification, extraction, formatting and bulk summaries | {{PRIMARY_FAST}} |
 
-The dial that pays for itself: **a worker executing a finished plan needs less
-reasoning than the reviewer judging its output.** When the plan is airtight the
-spec is carrying the thinking, so builder drops to medium. When the plan is
-vague, fix the plan; do not buy reasoning to paper over it.
+When selecting another AI tool, use `DELEGATION_MATRIX.md` and verify its current availability. When data must remain local, choose a local runtime with the required privacy boundary.
 
-**Stakes move the tier and the reader, never just the effort.** These four are
-the ones worth naming, because their failures are not recoverable by editing the
-code afterwards.
+## Model and effort per job
 
-Stakes means what a mistake would cost: a security hole, leaked personal data,
-lost data, or something you can't undo. Most tasks are low-stakes and route
-normally.
+When routing, consider three levers together: tier sets capability and price; scoped context limits token use; effort sets how much reasoning the call applies.
 
-| Stakes | Present when the change touches | What it buys |
-|---|---|---|
-| security | auth, tokens, sessions, routes, untrusted input | the challenge pass, ideally a different model family |
-| privacy | personal data, anything leaving the machine | the local lane, and a named check on what is sent |
-| data loss | deletion, bulk mutation, migrations, overwrites | a reviewed rollback path before the change is written |
-| irreversible | publishing, sending, rotating, anything with an audience | a human yes at Stage 5b, never an agent's |
+| Role | Starting tier | Starting effort | Reassess when |
+|---|---|---|---|
+| {{TIER_PLANNER_ROLE}} | planning model | xhigh where supported | The decision can be resolved from a known plan or needs a new capability |
+| {{TIER_REVIEW_ROLE}} | working model | high | Security, privacy or irreversible effects raise the review scope |
+| {{TIER_FINDING_ROLE}} | working model | high | Reproduction needs another runtime or access path |
+| {{TIER_BUILDER_ROLE}} | working model | high | Architecture, security or irreversible work needs xhigh and suitable model capability |
+| {{TIER_LIVE_ROLE}} | working model | medium | Synthesis becomes complex or sources disagree |
+| {{TIER_BULK_ROLE}} | cheap model | low | The input stops fitting the given categories |
+| {{TIER_DONE_ROLE}} | cheap model | low | The definition of done requires interpretation or unavailable tools |
+| {{TIER_READER_ROLE}} | cheap model | low | The requested result needs judgment across sources |
 
-High stakes raise code-reviewer to xhigh, and a security-shaped diff goes to
-the challenge lane rather than to a second read by the same family. Stakes are
-not a synonym for difficulty: a one-line change to an auth check is simple and
-high-stakes at the same time, and it is the stakes that decide the route.
+When the vendor uses different effort names, choose its equivalent after reading its current capabilities. Before each build, probe the live model roster, compare the configured pin with the lane's default, and record the selected model and effort with a reason. A pin below the current default calls for review; a newer model still needs to fit the job.
 
-**Reserve the top of the ladder for evidence.** xhigh and the escalation tier are
-bought with a named reason: a reproduced failure, a checkpoint that came back
-unresolved, an irreversible change. A task that merely feels hard is a deep-tier
-task, not an escalation.
+## Role, complexity and stakes
 
-## Why split tiers: robustness first, cost second
+- **Role:** choose the agent whose tools and task match the work.
+- **Complexity:** increase reasoning for ambiguity, interacting systems or an unknown cause; lower it for bounded retrieval and mechanical work.
+- **Stakes:** choose the reviewer and verification needed for the consequence of a mistake.
+- **Reach:** choose a lane that can read the required sources, run the relevant checks and hold enough context.
+- **Capacity:** account for context headroom, concurrency and the lane's current usage limits.
 
-The split produces better work. The deep tier steers every build twice, and what it steers is **judgment, never retrieval**: the orchestrator sweeps everything it touches itself and hands the deep tier a finished map. Paying deep-tier rates for a file list is the most expensive routing mistake available.
+When security, personal data, deletion, bulk mutation or irreversible actions are involved, name the boundary and test it. Use a different model family for the build's single audit pass, with a companion reviewer asking scope versus ask in the same step. Reserve authorization for actions outside the user's existing mandate.
 
-Against a baseline of "standard tier with no consults", default checkpoints are a spend increase. That is the accepted trade, not a saving to claim.
+## Effort through the lane runner
 
-## Escalation above deep
+When using `aunx cli-run --effort auto`, treat its result as a prompt-size or audit-scope heuristic. It resolves to medium or high, and an audit lane may impose its own effort floor; check the lane's configuration. For a build, select high explicitly; for security-critical or irreversible work, select xhigh explicitly where the lane supports it.
 
-Fires on exactly two conditions: (a) the human asks for it directly; or (b) all three of: deep has already run on this task, the decision is still unresolved, and the change is irreversible or rewrites a standing rule. (b) is a conjunction, not a mood. A failed attempt is an escalation-ladder event; a hard problem is a deep-tier event; neither reaches the top model alone. It replaces the second deep consult, never adds a third. Say so whenever it fires.
+When a lane lacks an effort flag, choose its model and task scope directly. The runner reports an unsupported effort request as a usage error.
 
-## Slotting a new model
+## Reassess a route
 
-1. Newer version of an existing family: same tier; aliases pick it up.
-2. New family above your deep model: candidate for deep. Confirm with the human before touching agent files.
-3. New family between tiers: slot by the vendor's own positioning; confirm if it would change who handles a task type.
-4. New cheap family below fast: candidate for fast if quality holds.
-5. Deprecation notice on a slotted model: move the tier immediately and note it here.
+- When a check fails, diagnose its failure before another attempt and state any route change.
+- When the lane lacks required access, hand that part to a lane with authorized reach and continue independent work.
+- When a vendor deprecates a model, verify the replacement from the current roster and update the affected configuration.
+- When changing a model would change cost, privacy or authority beyond the approved scope, present the choice to the user.
+- When the strongest eligible route still cannot resolve the task, return the evidence, partial result and needed decision.

package/templates/tools/README.md

@@ -4,7 +4,7 @@ Companion tools: not AIs, but things the AIs call. Each subfolder is written onl
 
 | Folder | Written | Contents |
 |---|---|---|
-| `codecalc/` | when codecalc is selected (recommended, default yes) | `CODECALC.md` (install, per-client registration, the skill) and `mcp/` snippets for the agents its own `setup --write` does not cover |
+| `codecalc/` | when codecalc is selected (optional, default no) | `CODECALC.md` (install, per-client registration, the skill) and `mcp/` snippets for the agents its own `setup --write` does not cover |
 | `obsidian-tc/` | when obsidian-tc is selected (optional, default no; needs an Obsidian vault, Node 24+, Ollama or a cloud embeddings key) | `OBSIDIAN-TC.md` (what you need first, install, per-agent registration, security posture) and `mcp/` snippets |
 | `context7/` | when context7 is selected (optional, default no; needs a network call, a Node 18+ local alternative, an optional API key) | `CONTEXT7.md` (what you need first, install, per-agent registration, security posture) and `mcp/` snippets |
 

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

@@ -12,7 +12,7 @@ A durable, searchable, governed store that the protocols can call by name:
 |---|---|
 | find what exists before writing (deep research dedupe, gap analysis) | `semantic_search`, `search_text`, `search_regex` |
 | map everything a rename touches (propagate) | `get_backlinks`, `find_unresolved_links`, `rewrite_link` |
-| record the end-to-end doc (build Stage 7) | `write_note` (compare-and-swap, confirmation on overwrite), `patch_note`, `append_note` |
+| record the end-to-end doc (build Record step) | `write_note` (compare-and-swap, confirmation on overwrite), `patch_note`, `append_note` |
 | keep inferred content honest | `write_note` with `provenance: "agent_synthesis"` runs a poison scan before the write lands |
 | keep a shared vault safe for several agents | JWT scopes, per-vault folder ACLs, a read-only kill switch, human-in-the-loop tokens |
 
@@ -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" }
     }
   }

package/docs/audit-brief.md

@@ -1,148 +0,0 @@
-# AUDIT_BRIEF.md: adversarial audit of model-orchestrator (round 1)
-
-> Historical document. Counts in it (tests, files) are as of the round they describe; `npm test` prints the current number.
-
-Read-only audit. Report findings only; do not modify files. Rank by severity. For each finding: file, line, what breaks, a concrete reproduction. `CLEAN` is a valid answer for any area with no reproducible finding. Skip style.
-
-## Task bundle
-
-**Purpose.** Adversarial, read-only audit of this npm package before it is published, so that reproducible defects are fixed before strangers run it.
-**Task class.** read_only
-
-**Granted scope.**
-- Every file under this repository root: `bin/`, `src/`, `templates/`, `test/`, `scripts/`, `docs/`, `package.json`, `README.md`.
-- Anything outside this repository is out of scope. Do not widen it on your own judgment.
-
-**Capabilities.** read files, run `npm test`, run `node bin/cli.js` with `--dry`, run `node bin/cli-run.mjs` with bad arguments, run scripts against a temp directory under /tmp.
-
-**Denied actions.** Do not modify, create or delete any file in this repository. Do not run `npm install -g`. Do not run any vendor installer. Do not commit, push, or publish. Do not read files outside this repository except /tmp scratch you created. Do not call any network service.
-- Anything absent from Capabilities is denied. Absence is not permission.
-
-**Conventions you do not have.** Report in plain prose with a findings list. No style nitpicks. `CLEAN` is a valid verdict per area. Every finding needs a concrete reproduction (command + observed vs expected). Never print a value that looks like a credential.
-
-**Report contract.** Return: a severity-ranked list of findings (file, line, what breaks, reproduction, suggested fix in one or two sentences), then a `CLEAN` line for each area in "Attack these" that had no reproducible finding, then a short "not covered" list naming anything you did not check or could not verify.
-
-**Exit parameters.** Stop after 12 minutes of wall clock or after reading every file once and running at most 30 commands, whichever comes first. If you hit a bound, report what you have and name what you did not cover. Never return nothing.
-
-## What this is
-An npm package (`npx model-orchestrator`) that asks a user which level (1/2/3) and which AIs they have access to, then writes markdown + config templates into a folder, and optionally runs `npm install -g <pkg>` for known packages after an explicit per-package yes. It also ships `bin/cli-run.mjs`, a wrapper that runs one of five agent CLIs (grok, codex, agy, hermes, qwen) and exits non-zero unless the lane produced a deliverable.
-
-## Runtime
-Node >= 18, ESM, zero dependencies. Runs on a stranger's laptop (macOS/Linux) with their PATH and HOME. Level 3 writes shell/systemd/compose templates the user will run on a Linux box.
-
-## Threat model
-- The user is not an adversary but is careless: runs it in the wrong directory, passes odd flags, has files with the same names.
-- Untrusted input reaches `cli-run.mjs` through CLI stdout (JSON from third-party binaries) and through `lanes.json` on disk.
-- The installer must never: write a secret value anywhere, overwrite a user file without --force, run a remote shell script, escape the target dir (path traversal via template rel paths or --dir), or leave a placeholder unrendered.
-- `cli-run.mjs` must never: throw on malformed CLI output (a throw is misreported as a usage error), pass a secret in argv, leave temp files, hang on stdin, or report success without a deliverable.
-- Generated templates (`vm/setup-vm.sh`, `vm/jobs/weekly-audit.sh`, `docker-compose.yml`, `gateway.config.yaml`) must not put a key in argv, bind to 0.0.0.0, or pipe a remote script into bash.
-
-## Already verified (do not repeat)
-- 60 node --test cases pass, including every judge's failure shapes and a mutation check that turns one case red.
-- Placeholders: every template renders for every level and primary without a leftover `{{KEY}}`.
-- README inside `.claude/agents/` is not installed.
-
-## Attack these
-1. `bin/cli.js` argument parsing: `opt()` takes the next argv token; what happens with `--dir --force`, `--ais ""`, duplicate flags, `--level 2.5`, unicode, a `--dir` that is a file, a `--dir` of `/`?
-2. `src/install.js` `writeFiles`: path traversal if a template rel path or the --dir resolves outside; symlink in the target dir; mode handling on Windows; partial writes.
-3. `src/detect.js` `which`: PATH entries that are files, empty PATH, relative PATH entries, a directory named like the binary.
-4. `bin/cli-run.mjs`: `jsonLines` on huge output; `maxBuffer`; `spawnSync` with `timeout` and `killSignal` behaviour; `enabledLanes()` with a malicious lanes.json; `--brief` pointing at a directory or a huge file; prompt containing newlines; the codex `-o` temp file when the CLI writes elsewhere; the `import.meta.url === pathToFileURL(argv[1])` main guard when invoked via a symlink; rc pass-through logic (`if (r.status !== 0 && code === OK) code = r.status`).
-5. Templates: `vm/setup-vm.sh` (set -euo pipefail, the for loop over {{NPM_PACKAGES}} when empty), `vm/jobs/weekly-audit.sh` (curl --config - header injection if GATEWAY_MASTER_KEY contains a quote or newline), `docker-compose.yml` env pass-through, systemd unit paths.
-6. Anything that could make the installer write outside `--dir` or read a file it should not.
-
-## Design decisions to challenge, with reasoning
-- Zero dependencies (no inquirer): smaller audit surface, but the prompt code is hand-rolled. Is the readline path safe with piped stdin and EOF?
-- Vendor scripts are printed, never run: correct? Or does printing `curl | bash` still encourage the unsafe pattern?
-- `npm install -g` is run after a per-package yes, with the package name from the catalog (never user input). Confirm user input cannot reach that argv.
-- `writeFiles` refuses existing files unless --force but does not check that the target is inside cwd. Deliberate (users may want `~/project`). Is there a traversal risk from template names?
-
-## How to run
-`npm test` · `node bin/cli.js --help` · `node bin/cli.js --yes --level 3 --ais claude-code,codex,agy,grok,hermes,qwen,ollama --dir /tmp/x --dry`
-
-## ROUND 2 (after round-1 fixes)
-
-Re-audit the same scope. Every round-1 finding was reproduced before it was touched. What changed:
-
-| # | Finding | Change |
-|---|---|---|
-| 1 | writeFiles escape / symlink follow | `preflight()` in `src/install.js`: containment under the resolved root, lstat every existing component (symlink or non-directory parent refused), exclusive `wx` create unless `--force`, rollback of files this run created if a later write fails. Tests: escape, symlinked component, conflicting parent leaves nothing behind. Mutation-checked. |
-| 2 | prompt in argv + logged head | argv kept (each vendor's documented headless shape); DEFERRED as a vendor constraint, documented in `CLI-RUN.md` and the file header (no secrets in prompts, ARG_MAX, reference big briefs by path). Log now stores a 12-hex sha256 prefix and length, never text. Test: marker absent from log. |
-| 3 | unknown flags / missing values | strict `parseArgs` in `bin/cli.js`: unknown flag, missing value, empty value, duplicate, positional → exit 2 before planning. Tests for each. |
-| 4 | audit job hardcoded hermes | `auditLane()` picks the first ENABLED cli-run lane (hermes, qwen, codex, agy, grok); none → rendered guard exits 13. Tests. |
-| 5 | audit never received live state | script composes `reports/audit-brief-<date>.md` = task bundle + protocol + DELEGATION_MATRIX + live-state, and passes THAT as `--brief`. Test. |
-| 6 | `--dir` ignored by systemd paths | `INSTALL_DIR` rendered into the service and the script from the resolved `--dir`. Test. |
-| 7 | curl config injection | script refuses a key not matching `^[A-Za-z0-9._-]+$` (exit 2) before any curl; documented in ENVIRONMENT.md and vm/README. Test executes the rendered script with an injecting key. |
-| 8 | malformed lanes.json fail-open | `enabledLanes()` returns null on present-but-invalid; main refuses every lane (13) and says so. Test proves no spawn happens. |
-| 9 | signal → exit 0 | `r.signal || r.status === null` → verdict killed, exit 10, partial output discarded. Test. |
-| 10 | partial install | covered by preflight + rollback (finding 1). Test. |
-| 11 | directory detected as binary | `isFile()` check in both `which()` implementations. Test. |
-| 12 | `curl \| bash` printed | download / read / run form printed instead. |
-
-Also new since round 1: the companion-tool path (`--tools codecalc`, `--no-tools`, `templates/tools/codecalc/`, `protocols/numbers-and-logic.md`, `resolveTools`). Attack it the same way: unknown tool ids, interaction with `--yes`, the extra interactive question, and whether any written snippet could be confused for a file the installer should not touch.
-
-Report only what reproduces on the current tree. `CLEAN` per area is expected where the fix holds.
-
-## New in 0.1.15: two claude-code-only hooks
-
-`route-gate.mjs` (`UserPromptSubmit`) and `subagent-context.mjs` (`SubagentStart`) ship to `.claude/hooks/` only when claude-code is the primary. Both are plain Node, zero deps, and installed with mode `0o755`.
-
-- **Reads.** `route-gate.mjs` reads at most 64 KB from one file: the routing rules file (`ROUTING.md` or `ORCHESTRATOR.md`) at a path rendered in at install time relative to `CLAUDE_PROJECT_DIR`, never a hardcoded absolute path. Before opening it, it `statSync`s the resolved path (following a symlink to its target) and refuses anything that is not `isFile()`, a FIFO, socket, device or directory included, so the read never touches a path that could block on open. The read itself is one `openSync` + one bounded `readSync` into a fixed 64 KB buffer, closed in a `finally`, so neither the time nor the memory this hook uses depends on how large the file on disk actually is. It then extracts the text between `<!-- route-gate:start -->` and `<!-- route-gate:end -->` and nothing else. `subagent-context.mjs` reads nothing from disk; its context is static text plus the same two rendered paths. Neither parses or executes anything it reads; the extracted block is passed through as a string.
-- **Stdin.** Neither hook uses a field from the JSON input Claude Code sends on stdin, but both must still consume the pipe rather than ignore it. Both drain stdin asynchronously against a 250ms hard cap: whichever comes first, the real `end` event or the timeout, the hook proceeds. Neither ever calls a blocking, synchronous read of stdin.
-- **Writes.** Neither writes a file. Both write one JSON object to stdout: `{"hookSpecificOutput":{"hookEventName":"...","additionalContext":"..."}}`, and both exit only after that write's callback fires, so a buffered write to a pipe is not truncated by an exit racing ahead of it.
-- **Fail-open, on purpose.** A missing `CLAUDE_PROJECT_DIR`, a missing rules file, a non-regular file at the rules path, or a missing block each produce a one-line fallback `additionalContext` naming what was found, and the script still exits 0. This is acceptable because a miss here is a stray context string reaching the model, not a security gate: nothing downstream trusts the hook's output for anything but a routing suggestion, and the settings snippet that wires it in is a document the user merges by hand, never written automatically over an existing `settings.json`.
-- **Bounded.** `route-gate.mjs` caps the read at 64 KB regardless of the file's reported size and the injected string at 4000 characters, so a rules file bloated by a bad edit, or truncated to an arbitrary length, cannot balloon the context or the read time on every turn. Both hooks cap stdin drain at 250ms.
-- **Not yet attacked.** Untested here: a rules file with a `route-gate:start` marker but no matching end marker very far into the file (bounded by `MAX_READ`, so the end marker past that point is treated as absent, which is the intended fail-open path, but worth a deliberate case); a `CLAUDE_PROJECT_DIR` pointing at a path with no read permission; behavior under the Windows exec-form `node` + `args` invocation named in the settings snippet; a `statSync` that itself hangs (a stalled network filesystem, for instance) rather than the FIFO-at-open case this round fixed.
-
-### Round 1 (pre-release), fixed before shipping
-
-Three findings reproduced against the 0.1.15 branch before it shipped, none of them ever released:
-
-| # | Finding | Fix |
-|---|---|---|
-| 1 | HIGH. `readFileSync(0)` in both hooks blocked until stdin reached EOF (`sleep 3 \| ... node route-gate.mjs` still running past 1.5s); `route-gate.mjs` also read the whole rules file into memory before bounding it, so a FIFO planted at the rules path blocked forever on open. | Stdin is drained asynchronously against a 250ms hard cap in both hooks. `route-gate.mjs` refuses anything that is not `isFile()` via `statSync` before ever calling open, then reads through one fixed 64 KB buffer via `openSync`/`readSync`. Tests: an open, never-closed stdin pipe exits within 1s for both hooks; a FIFO at the rules path returns the fallback instead of hanging; a 200 MB sparse rules file completes in well under a second with output still capped. |
-| 2 | MEDIUM. `done-verifier`'s description, both agent-folder READMEs, and the root README called it "read-only" without qualification, while its claude-code file carries an unrestricted `Bash` grant; nothing in that grant stops it from running a mutating command. | Every one of those surfaces now says plainly that `done-verifier` carries no file-editing tools and that its Bash use is bound by its own prompt, not by the tool grant; `reader` is named as the one that is read-only by tool grant (no Bash) on both formats. |
-| 3 | MEDIUM. Three generated surfaces still stated the pre-0.1.15 premise on a claude-code install: `builder.md`'s description ("... or the main build itself"), `build-protocol.md`'s roles table and its "why the builder does not hand off" note, and `ROUTING.md`'s "Plan big, execute small" line ("the orchestrator executes"). | All three now render through `subagentsLoadRules(primary)`, the same gate the decision tree and "Who builds" already used; every other primary is unchanged. A semantic-regression test asserts a claude-code install contains none of the old phrasing and a codex install still does. |
-
-## New in 0.1.16: a third hook, route-metrics.mjs
-
-`route-metrics.mjs` ships to `.claude/hooks/` alongside `route-gate.mjs` and `subagent-context.mjs`, only when claude-code is the primary. Same shape as the other two: plain Node, zero deps, mode `0o755`. Unlike them, it is wired to five events at once (`UserPromptSubmit`, `PreToolUse` matched to `Agent|Task`, `SubagentStart`, `SubagentStop`, `Stop`), and it does write, deliberately: one JSON line per event, appended to `~/.ai-orchestrator/route-metrics.jsonl`.
-
-- **Reads.** Only its own stdin (the JSON Claude Code sends per event) and, for `--summary`, its own log file. It never reads `transcript_path` even though that field is present on every event: the documented source for the route marker is `last_assistant_message`, and the docs say the transcript can lag, so a hook that read it instead could log a stale or absent marker as if it were current. It never reads the rules file, the task bundle, or any other project file.
-- **Writes.** `~/.ai-orchestrator/route-metrics.jsonl` (append-only, rotated to `.jsonl.1` above 5 MB) and `~/.ai-orchestrator/route-metrics.state/<sha256(agent_id)>.json`, a small file recording a subagent's start time and type so `SubagentStop` can compute a duration; it is deleted on stop, and anything older than 24h is pruned on the next `SubagentStart`. Nothing outside `~/.ai-orchestrator/`. It never writes to stdout: on `UserPromptSubmit` and `SubagentStart`, stdout becomes model context, and this hook has nothing to say there, so it stays silent on every event, not just those two.
-- **What it never logs.** Prompt text, tool descriptions, the full `tool_input`, `last_assistant_message` itself, or the "why" half of a route marker. Only six named fields ever reach a record: `session_id`, `subagent_type`, `agent_type`, and the parsed `lane`, each stripped to `[A-Za-z0-9_.+-]` and capped at 64 characters (128 for `session_id`) before being written, plus the event name and a `duration_s` number it computed itself. This mirrors `bin/cli-run.mjs`'s own log, which stores a fixed reason code and never a provider-supplied string.
-- **Fail-open, on purpose.** Every code path that can fail (a malformed state file, a full disk, a rotation race, invalid JSON on stdin, an unrecognized event) is caught and produces no record rather than a thrown error or a non-zero exit; the process always exits 0. A miss here is a missing line in a telemetry log, never a blocked turn, so there is nothing to gate.
-- **Bounded.** Stdin is drained asynchronously against a combined 1s time cap and 8 MB size cap; a payload that exceeds either is treated as truncated and parsed as nothing, never partially. `--summary` reads the log directly (never spawns anything, never executes a line in it).
-- **Not yet attacked.** Untested here: two processes racing the same rotation at once (a rename plus an append landing on the same file); a state directory with thousands of leaked files from a long-lived session with a crashed hook (pruning runs, but only on `SubagentStart`, so an install that never starts a subagent again would never prune); behavior if `agent_id` collides across two concurrent subagents (sha256 makes this astronomically unlikely, not impossible).
-
-## New in 0.1.18: the Windows spawn path
-
-`bin/cli-run.mjs` runs a lane's binary through `windowsSpawnPlan()` before every `spawn()` call. On POSIX, and for a plain `.exe` or extensionless binary on Windows, this is a no-op: the same argv reaches `spawn()` with no shell, exactly as before. What changed is the two shapes Windows can hand it that used to reach `spawn()` unchanged and throw `EINVAL` (Node's fix for CVE-2024-27980: a `.bat`/`.cmd` target without `shell: true` is refused rather than run through an unsafely-escaped `cmd.exe`).
-
-- **What runs, in order.** `resolveCmdShim(cmdPath)` reads the `.cmd` file and looks for the exact line npm's `cmd-shim` package writes: `"%_prog%" ... "<path>" %*`, where `<path>` is `%dp0%`-relative (verified against the real, byte-for-byte output of `cmd-shim@9.0.2`, the package npm itself uses to write a shim from a package.json `bin` entry with a `#!/usr/bin/env node` shebang; `test/judges.test.js` pins that exact fixture). If it matches, the `%dp0%`-relative path is resolved against the `.cmd` file's own directory and checked with `statSync` (must exist, must be a file, must end in `.js`/`.mjs`/`.cjs`); on success, `windowsSpawnPlan()` returns `{ command: process.execPath, args: [scriptPath, ...args] }`, and `spawn()` runs `node <script> <args>` directly. A lane's prompt (argv[1] and on) is text this tool does not control the contents of; this path never puts it anywhere a shell parses it.
-- **Why no shell, ever, for a lane.** Every real lane (grok, codex, agy, hermes, qwen) is an npm-installed Node CLI, so on a real Windows install the resolved-shim branch is the one every run takes. If `resolveCmdShim` returns nothing for a lane (an old cmd-shim layout, a hand-written `.cmd`, or a `.bat`), `windowsSpawnPlan()` returns `{ refuse }` and `cli-run` reports the lane unavailable (exit 13) with a message saying how to fix it. It does not fall back to `cmd.exe`: a batch file re-reads its arguments through `%*` after `cmd.exe` has parsed them once, which is the case CVE-2024-27980 is about, and no escaping fully contains user text through both passes. Removing that path was chosen over guarding it.
-- **The one opt-in `cmd.exe` path, and how its arguments are escaped.** Only a caller passing `{ allowCmdFallback: true }` with arguments it fully controls gets the `cmd.exe` path: today that is the installer's own `npm install -g <pinned spec>` (`npm.cmd` is not a cmd-shim, and every argument comes from the catalog, none from a user). For that caller, `windowsSpawnPlan()` builds one command-line string with `escapeCmdArg`/`buildCmdExeCommand` and returns `{ command: <ComSpec>, args: ['/d', '/s', '/c', <built string>], options: { windowsVerbatimArguments: true } }`. The algorithm is the one documented at [qntm.org/cmd](https://qntm.org/cmd) (the reference writeup of `cmd.exe`'s quoting behavior) and used by the widely-deployed `cross-spawn` package: each argument is quoted the way `CommandLineToArgvW` expects (backslash-doubling before an embedded quote or at the end of the string, then wrapped in `"`), and THEN every `cmd.exe` metacharacter in that quoted text (`( ) % ! ^ " < > & | ; ,` and space) is caret-escaped, because `cmd.exe`'s own line scanner reads those characters off the raw command line before the quoting is honored, quote or no quote. `windowsVerbatimArguments: true` tells Node not to re-quote the string a second, conflicting way. `test/judges.test.js` pins exact expected output for `&`, `|`, `^`, `%`, a literal `"`, a trailing backslash and a literal newline (the last one deliberately unescaped: it is not a `cmd.exe` metacharacter).
-- **`killTree` needs no change for which process it targets, either path.** `taskkill /pid <pid> /T /F` walks the whole descendant tree regardless of whether the direct child is `node` (the resolved-shim path) or `cmd.exe` (the fallback); there is no intermediate shell layer to lose track of in the common case, since there is no shell there at all. It DID need a change for how `taskkill` itself is found: `windows-latest` CI caught a bare `spawn('taskkill', ...)` failing `ENOENT` the first time a lane actually ran end to end there (this project's own test harness deliberately narrows PATH to isolate a fake lane, and that narrowed PATH does not include `System32`; a sandboxed or otherwise stripped-down real environment might not either), and the resulting unheard `error` event on the returned process crashed the whole run over what should be a best-effort cleanup step. `taskkillPath()` resolves the executable under `%SystemRoot%` (falling back through `%windir%` to a fixed path) instead of relying on PATH, built with a literal backslash rather than `node:path`'s `join()`, which picks its separator from the HOST running the code, not the OS the path describes; `killTree` now attaches an `error` listener so any future spawn failure stays a missed cleanup, never a crash.
-- **`bin/cli.js`'s own `npm install -g` prompt reuses this, rather than duplicating it.** The installer's opt-in "run `npm install -g <ai>` now?" prompt had the identical `EINVAL`-shaped defect (`spawnSync('npm', ...)` with no shell), found the same way: it failed the moment its own test actually ran on `windows-latest`. It now resolves `npm` with `which()` and calls `windowsSpawnPlan()`, the same function above, instead of a second copy of the fix.
-- **Not yet attacked for real.** `windowsSpawnPlan`, `resolveCmdShim` and the escaping functions are unit-tested (pure string logic, runs on every CI host) and the resolved-shim path is exercised end to end on `windows-latest` through the fake-lane fixtures in `test/cli.test.js` (installed as a real npm-style `.cmd` shim). A lane can no longer reach `cmd.exe` at all (a unit test pins the refusal). The opt-in `cmd.exe` branch, used only by the installer's own `npm install -g`, is not exercised end to end through a live Windows process in this suite; its escaping is proven by exact-string unit tests only, and its arguments never include user text.
-- **A platform limit found the same way, unrelated to the spawn path itself: Windows has no OS-level signals at all.** `cli-run.mjs`'s graceful shutdown (`process.on('SIGTERM', ...)`, kill the lane's process group, then exit 143/130) is a POSIX guarantee only: `ChildProcess.kill(sig)` on Windows calls `TerminateProcess()` unconditionally for SIGTERM AND SIGINT alike, giving the target process no chance to run any handler at all, proven on `windows-latest` CI (the wrapper died as `{code: null, signal: sig}` for both; a hypothesis that SIGINT gets a real, catchable console-control event on Windows was tried first and measured false in this exact scenario, not assumed). `test/cli.test.js`'s `#13` now expects an unhandled termination for either signal on win32, and the original graceful-exit assertion elsewhere.
-- **Two narrow, individually-verified Windows skips remain, neither in the spawn path itself.** (1) A lane dying mid-run from a real POSIX signal cannot be reproduced on win32: a real Windows lane is a plain `node <script>` process, so it cannot die "by signal" any more than the product being tested can, and the only way a test fixture can even simulate one (a nested `sh -c "...; kill -TERM $$"`) puts an extra node process between cli-run.mjs and the dying shell, so cli-run.mjs observes only that node's translated exit code (measured: MSYS bash's self-kill status leaks through as a plain nonzero exit code, 3840, which this tool already handles honestly via `exit_nonzero`). (2) `weekly-audit.sh`'s watchdog (`bounded()`/`killtree()`, `pgrep -P` plus killing a backgrounded subshell's tree) relies on real bash job control this script only ever runs under on the Ubuntu box it targets; actually executing it against a genuinely hanging stub under Git Bash's job-control emulation hung past a 20s outer timeout on `windows-latest` CI, a known class of MSYS/Cygwin limitation (a `kill -KILL` not reliably reaching the underlying Windows process tree of a backgrounded subshell), not a defect in the generated script, which still renders and syntax-checks correctly.
-
-## New in 0.1.23: failure classes in cli-run
-
-`bin/cli-run.mjs` now puts every run in a closed failure class that owns the exit code (`auth` 14, `quota` 15, `rejected` 16, `refused` 17, `cut_short` 18, beside `ok` 0, `empty` 10, `no_output` 11, `timeout` 12, `unavailable` 13), counts refused tool calls per lane (including a read of grok's session transcript, whose `sessionId` comes from lane stdout), and prints redacted problem and fix lines. The durable log gains only `class` and `refused`. Threat model: a false exit 0, provider text or a secret reaching the log or the terminal, a transcript read escaping the sessions root, misclassification that sends a user the wrong way, and anything that throws or stalls.
-
-### Round 1 (pre-release, GPT-6 Astra at xhigh), fixed before shipping
-
-Every finding was reproduced as a failing case in `test/classify.test.js` against the unfixed code (all seven red), then fixed; the suite is green after. One round, by rule; the regression cases verify the fixes.
-
-| # | Sev | Finding | Fix | Test |
-|---|---|---|---|---|
-| 1 | HIGH | qwen's display detail clipped an error message at 120 characters before redaction, so a long JSON password lost its closing quote and printed its prefix | redact before every clip: judge detail, API-error text, denial text, deliverable snippet, problem cause | R1 |
-| 2 | HIGH | the JSON credential pattern ended at an escaped quote and missed unterminated values | match JSON string escapes, run an unterminated value to the end, and accept a JSON body escaped inside a string | R2 |
-| 3 | HIGH | `firstDenialText` scanned 16 MiB with an unbounded `[^)]*`: 1 MiB of unclosed `Permission denied for command(` took 15.6 s after the lane had exited | scan at most 256 KiB of stdout and of stderr, with bounded repeats | R3 |
-| 4 | MEDIUM | transcript containment was a string prefix with both separators, so on POSIX a directory literally named `sessions\outside` passed | `isInsideRoot()` via `path.relative`, rejecting `..`, absolute and cross-drive results; tested with `path.posix` and `path.win32` on every OS | R4 |
-| 5 | MEDIUM | qwen signals were searched in the clipped display detail, so a quota error after 120 characters read as `empty`, and a model name in the detail could fake a signal | classify on `qwenErrorText()`: the terminal event's full error and an API-error result only | R5 |
-| 6 | MEDIUM | hermes fell back to stdout when stderr was empty, so an answer saying "no rate limit" read as `quota` | stderr only | R6 |
-| 7 | MEDIUM | a nonzero vendor exit with a recognised empty shape (agy exit 7, `SUCCESS`, empty response) returned `empty`, contradicting the documented `cut_short` fallback | an unexplained nonzero exit is `cut_short`, except hermes' own exit 2 | R7 |
-
-Reported clean by the same audit: no false exit 0 across 675 malformed probes and five lanes; no provider text or secret fragment in probed log records; the real codex 0.153.4 fixture's non-fatal error item still succeeds; grok traversal, symlink, FIFO, session-match and read-cap guards; timeout, interrupt, overrun, killed lane, JSON contract, `--quiet` and the doctor canary. Not verified by it: native Windows execution, live vendors, filesystem races.

package/scripts/README.md

@@ -1,7 +0,0 @@
-# scripts/
-
-| File | Job |
-|---|---|
-| `gen-catalog.js` | regenerates `docs/catalog.md` AND the vendor compatibility table in `README.md` (between the `vendor-table` markers) from `src/catalog.js`; `npm run gen:catalog`. `test/catalog.test.js` fails if either generated surface disagrees with the catalog. |
-| `record-demo.sh` | re-records `docs/demo.gif` by installing the published package into a temp folder and running it under `asciinema`, then rendering the cast with `agg`. Pass a version to pin one: `bash scripts/record-demo.sh 0.1.27`. Needs `brew install asciinema agg`. The frames are the installer's own output, so the GIF stays true to what the command prints. |
-| `gen-plugin.js` | regenerates the Claude Code plugin bundle in `plugin/` (agents, the two read-only hooks, `plugin.json`, `LICENSE`) from `templates/`, using the plan in `src/plugin.js`; `npm run gen:plugin`. `test/plugin.test.js` fails if the committed bundle disagrees. `plugin/README.md` and `plugin/hooks/hooks.json` are hand-owned. |