specpi 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.28.0 - 2026-09-18
+
+- Read the key Pi already has. The layer resolved its credential from `OPENROUTER_API_KEY` and nothing else, while Pi had long since stored an OpenRouter key where it stores every provider credential — the `openrouter` entry that `/login openrouter` writes to `auth.json`. So a person who had logged in, whose every model call was working, was told `key: missing` by the one component that had opted out of Pi's credential store, and there was no interface anywhere that would have explained the gap. The advisor now follows Pi's own documented resolution order, the store first and then the environment, which is what makes `/login openrouter` the answer to "how do I configure the API key" rather than a second thing to set up. `/jev status` lists every source and marks the one in force, because "missing" with nothing to act on is what sent people looking for a key field that does not exist.
+- Make turning the layer on turn the layer on. `/jev on` set the master switch and left all seven systems off, so the layer ran and did nothing; the notification said so and then asked for seven more commands. Enabling it now enables every system that is off, and only when none are on, so a deliberate subset survives being toggled. The command guard is one of the eight and comes on with them, and because it is the only system that can refuse a tool call, the notification now says so in as many words rather than listing it among seven that only ever add advice.
+- Remember the switch. `/jev on` changed one session and wrote nothing, so the layer had to be re-enabled from scratch every time Pi started — the startup preference was a separate command most people never found. Turning the layer on or off now writes the preference, with `--session` for the one-off case that must not change tomorrow.
+- Stop storing one intention as two switches that can cancel each other. `master` and `startup` are both written whenever either changes, because the advisor only acts when both are true: a file saying `master: true, startup: false` describes a layer that is on and never runs, which is exactly the state the Chat panel's two independent checkboxes made it easy to save.
+- Drop the `specpi-jev-guard` package and build the command guard into the layer natively, as its eighth system. Four review rounds kept returning to the same handful of causes, and all of them were properties of that package rather than of the feature: its configuration was one global file with no session scope, so there was no such thing as enabling it for a session and `--session` could not scope it; it read its key from the environment only, so the credential `/login openrouter` had already stored was invisible to it; and it was fail-closed, so a missing or stale key turned every shell call in the session into a refusal. As `systems.guard` it is gated, budgeted, reported and toggled by exactly the same code as the other seven — `/jev enable guard`, one key, one budget, one switch — and the separate `guard: { enabled, startup }` pair is gone with the persistence disagreements it caused. Schema 3 migrates `guard.startup` into `systems.guard`, and the base drops from eight pinned packages to seven. An install that already has the package is unpinned on update, by name and only when the entry is the one SpecPi wrote, because dropping a line from the template would otherwise leave a fail-closed gate running on every machine that already had it with the command to disarm it deleted. `specpi doctor` reports a retired entry that is still configured. Its downloaded files stay where Pi put them; Pi stops loading it.
+- Invert the failure posture. The native guard **fails open**: no key, no budget, a timeout, an unconfident answer or a middle-band verdict with nobody to ask all hand the call to `@gotgenes/pi-permission-system`, which decides it exactly as it did before the layer existed. That is not a weakening — the guard sits in front of the permission system, so fail-closed meant an outage stopped work while fail-open returns policy to the component that owned it anyway. It is also the rule the rest of the extension already followed.
+- Hold the local allowlist to one rule: a binary is admitted only if it is simple whatever flags it is given. `rg --pre` runs an arbitrary preprocessor, `date -s` sets the clock, `hostname` with an argument sets the hostname, `file -C` writes a compiled magic file — none reads as dangerous, all four were admitted, and each was a general bypass. The list is a *budget* mechanism rather than a safety one, which is the thing that had gone unsaid: the guard has 208 calls, so a fast path exists to stop a session of `ls` and `grep` spending them all and leaving nothing for the calls that matter. That makes the admission test "would asking about this spend the budget without learning anything", and under it a rare binary is never worth a silent hole. Jev is the analyser; anything that merely looks simple belongs to it.
+- Say why the two local lists are maintained under opposite pressures, in the file itself. A wrong `safe` is a silent permanent hole, because it is the one verdict with no second reader; a wrong `unknown` costs one call out of 208 and Jev decides; a wrong `dangerous` blocks real work with no recourse but switching the guard off. Six review rounds treated both lists as one thing called "the guard" and hardened them the same way, which is backwards.
+- Stop writing fixture credentials in real vendor shapes. Every "secret" in the suite was a fixture and always had been, but they were spelled like genuine OpenRouter and Anthropic keys, so GitGuardian failed the pull request on them — the scanner working exactly as intended and the fixtures being wrong. They are named for what they are now, and a test refuses any tracked file containing a vendor prefix followed by a plausible key body, because a scanner that cries wolf on your own test data is one people learn to click past.
+- Close the ways round the guard that its own first implementation left open. A read-only binary was judged by its name and never its arguments, so `cat ~/.ssh/id_rsa` and `grep -r . ~/.aws/credentials` took the free path — leaving the exfiltration half of the question the guard asks unreachable for the commands that answer it; `printenv` was on the same list for the same reason and is not any more. `env`, `find`, `fd`, `sort` and `uniq` sat there too, each one a general bypass: `env rm -rf build` begins with a binary that changes nothing. The catastrophic delete rule anchored on the end of the line, so it matched `rm -rf /`, which GNU `rm` refuses on its own, and missed `rm -rf / --no-preserve-root`, which does not. And a shell tool's text was read from `input.command` alone, so `write_stdin` — which types into a live shell — was classified as the empty string and spent a budgeted call asking about nothing.
+- Stop two failures from turning into consent. `ctx.ui.notify` reaches the host over RPC and can throw; called inline inside the guard's fail-open catch, one failed notification unwound a decided refusal into an allow. And a `ctx.ui.select` that rejected — a host without the method, a disconnect, a cancel that throws rather than resolving — was swallowed by the same catch and read as approval, on the single path in the feature where a human was asked directly. The announcement can no longer change a decision, and a question that could not be put is a refusal. Which answer counts as consent is now one exported function with a test, rather than a string comparison inside a closure nothing imports.
+- Say that the guard can refuse a command on every path that arms it, not only on `/jev on`. `/jev enable guard` and `/jev startup on` armed the same system in silence, so the first thing either taught you was a blocked call — the outcome the rule exists to prevent.
+- Give the command guard the history it is documented to weigh. `recent` was appended to in exactly one place, inside retention's success path, so a session running the guard with retention off evaluated the intent half of the block rule against an empty history for its whole length. Every tool result is recorded now; retention refines its own entry rather than adding a second.
+- Cache an unparseable `auth.json` as firmly as a parseable one. Recording only successful parses left the worst case uncached: a truncated store threw on every call, so every request paid a fresh stat, a 256 KiB read and a failing parse inside the same latency budget the cache was added to protect, forever.
+- Unpin a retired package whatever shape its entry has, and keep that write inside the installer's transaction. Preserving a user-modified `specpi-jev-guard` entry preserved the fail-closed gate this release deleted the controls for — the deliberate exception to "a modified entry is yours", and the only one. The write also ran outside the watched set on the `--skip-package-install` path, so it was neither backed up nor rolled back when a later step in the same run failed.
+- Stop the Chat panel re-arming eight systems when someone turns the last one off. `couple` read that as the broken dead-layer file it repairs and ticked every box back on, the blocking command guard included, with a note describing a file that never existed — while `/jev disable` read the identical situation as "switch the layer off". The panel now does the same, and still repairs a file that genuinely arrives dead.
+- Give the guard its own gate thresholds. It asked under the name `gap`, which `thresholdsFor` resolves identically by falling through its default — so adding a `guard` entry, the natural change for the one system whose action takes a tool call away, would have changed nothing at all and said nothing about it.
+- Stop `/jev off` reading Pi's credential store to discard the answer, and stop `applyLayer` accepting two arguments it never looked at.
+- Settle most calls locally, for nothing. Read-only commands and ordinary project writes never leave the machine, and a deliberately tiny list of catastrophic, unambiguous commands is blocked with no call at all. A `ls` costs nothing; a command carrying any shell control character never takes the fast path, because `ls; rm -rf ~` begins with `ls`. Blocking on a Jev verdict needs two answers to agree — a confident destructive reading *and* a confident reading that the request does not account for the call — because the likeliest way to be wrong is a destructive-looking command the person asked for in as many words. Both answers must survive the confidence gate: reading a missing intent answer as agreement would have made the safeguard apply to about one call in five, since roughly four Score answers in five do not gate. The shell tools are gated under every alias the harness maps onto `bash`, the write tools under every name `multi_edit`, `apply_patch`, `create_file` and `str_replace` arrive as, and a write whose target cannot be read is asked about rather than waved through. When the guard asks a human, only the affirmative runs the call; dismissing the dialog is not consent.
+- Make Chat and the advisor agree about a symlinked `auth.json`. One reader was fixed to follow links and the other was not, so `/jev status` reported "in use from auth.json" beside a panel reporting "No key anywhere" — the drift the pin test exists to catch, which it missed because it never created a link. It does now.
+- Merge `/jev enable` and `/jev disable` into the stored systems rather than overwriting them with the session's copy, which silently turned off systems enabled on disk since the session started. Disabling the last system now switches the layer off and says so, instead of writing the dead-layer state that four other code paths exist to prevent.
+- Cache the parsed credential store against the file's size and modification time. `ask()` resolves a key per request and retention fires on every large tool result, so the store was being stat'd, read and parsed inside a 1500 ms latency budget on the tool path, where it used to be one environment lookup.
+- Move `/jev on` and `/jev off` out of `index.ts` and into a module a test can call. Nothing imported that file, so the ~200 lines that are this feature were covered by prose alone while the suite reported green — which is how two review rounds found, among other things, a stored preference destroyed by a command that had decided nothing about it, a notification reporting a gate "left off" while it was on and blocking every call, and a rollback that never ran because the flag was set before the write. `layer.mjs` takes its world as an argument and holds no state, so what `/jev on` means is now something a test can call rather than something the prose asserts.
+- Bind the backend in `keyPresent`, `keySource`, `keySources` and `keyEnvName`, not just `apiKey`. All five were re-exported with a `"openrouter"` parameter default, so `keyPresent()` reported a key on the direct TypeSafe route that `resolveKey()` would never return. `backend()` moved into `key-source.mjs` so each one binds it rather than defaulting to a literal.
+- Read a symlinked `auth.json`. Refusing links recreated the exact divergence this layer was written to remove: a dotfile manager links the file, Pi resolves the credential, every model call works, and this layer alone reports "key: none found". Links are refused where SpecPi *writes*; this is a bounded read of a file Pi owns.
+- Stop the Chat panel throwing while opening the very file it exists to repair. A layer on with no systems was a validation error, so the panel rendered red with Save disabled before anything was touched, and the one mechanism that could fix it skipped the case. The rule now lives where the write happens: the form repairs and announces it, and the host refuses it on save.
+- Persist `/jev enable` and `/jev disable`. They announced a session-scoped change that a later `/jev on` copied to disk anyway, so a choice described as temporary became permanent through an unrelated command.
+- Write both halves of the startup preference in `/jev startup`, which had been the one command still writing `startup` without `master` — the exact two-keys-for-one-intention trap this release removes, left in the command named after it, while its own notification claimed new sessions would start on. It also fills in the systems when none are chosen, for the same reason `/jev on` does.
+- Bind `apiKey()` to the active backend again. Re-exporting the resolver under that name rebound every no-arg caller — the calibration and triage scripts among them — to the OpenRouter default, so with `JEV_BACKEND=typesafe` a script's `if (!apiKey())` guard passed on a stored OpenRouter key while every request underneath it returned `no-key`.
+- Keep measured runs off a personal account. With the credential store consulted first, `scripts/jev-calibrate.mjs` and `scripts/jev-triage.mjs` would have billed a developer's own `/login openrouter` credential rather than the key in `evals/.env`, and `--probe` would have verified a key the run did not use. Both now set `JEV_KEY_SOURCE=environment`, which restricts resolution to the environment.
+- Refuse a layer that is switched on with nothing to run. The Chat panel filled in the systems in its form, but the full-configuration textarea bypassed that, so the dead-layer state this release exists to remove stayed one hand-edit from disk. It is refused rather than silently corrected.
+- Report the key from one place in the Chat panel. `saveJev` resolved `auth.json` from a different agent directory than `loadJev`, so with a workspace-relative `PI_CODING_AGENT_DIR` pressing Save flipped a working panel to "No key anywhere"; and the report named the credential store even on the direct TypeSafe API, which has no entry there. Both now follow the advisor's own conditions.
+- Stop the advisor's tests from writing to the real agent directory, which they had been doing for as long as any of them were async. `withAgentDir` wrapped its callback in `try/finally` around a bare `return run(dir)`, and an async callback returns its promise at the first `await` — so the cleanup ran there, restoring `PI_CODING_AGENT_DIR`, `HOME` and `USERPROFILE` to the developer's real values and deleting the temporary directory while the test body was still going. Nineteen tests in that file pass an async callback, so most of the suite was isolated only up to its first suspension point. It destroyed a real credential store before it was found: a fixture `auth.json` written after an `await` landed in a developer's own `~/.pi/agent`, and because Pi's `AuthStorage` merges onto whatever it reads, one write replaced three logged-in providers with the single fake entry the fixture held. The suite reported every test passing while doing it, which is what kept it invisible. Cleanup now waits for a returned promise, and the fixture writer refuses any path outside the temporary directory: OAuth tokens cannot be recovered, so a failed test is the only acceptable cost of that check.
+- Isolate the key variables in the advisor's tests. `withAgentDir` restored `OPENROUTER_API_KEY` afterwards but never cleared it for the body of a test, so "a missing key reads as unavailable" passed or failed depending on the shell the suite was started from.
+
 ## 0.27.0 - 2026-09-18
 
 - Put a measured number on the rule the whole layer is built around. "Any tool-set decision happens once, before the first request, or not at all" rested on a cache argument that was reasoned about here for months and never weighed. Three arms on `t3-cascade-ledger` differing only in when Browser QA's fourteen tools reach the request settle it: flipping them on at turn 6 collapsed cached tokens to 3,200 at the very next request in three attempts out of three — from 25,984, 17,792 and 21,120 — while the prompt kept climbing, one request going from 3,673 fresh tokens to 31,337. The re-warm cost 14.6%, 21.6% and 23.9% of the attempt, against a 10% threshold written down before the run. Arming the same group from turn 1 cost 16% more than never arming it, against 47% for flipping mid-session, so paying up front is about three times cheaper than paying when the need appears. Recorded to `evals/runs/cache-probe/`; `scripts/cache-probe.mjs` reproduces the analysis.

package/README.md

@@ -44,7 +44,7 @@ Everything it touches is written down, versioned, and easy to undo.
 
 ## Measured context
 
-This chart shows first-call context from a clean install: all seven pinned packages, the working agreement, and the skills Pi finds. It predates `specpi-jev-guard`, the eighth pin, and has not been re-measured since. "Enabled" means browser QA, delegation, and web access are switched on, with no goal, scope, or improvement selection active.
+This chart shows first-call context from a clean install: all seven pinned packages, the working agreement, and the skills Pi finds. It has not been re-measured since the command guard became a native system rather than an eighth pinned package. "Enabled" means browser QA, delegation, and web access are switched on, with no goal, scope, or improvement selection active.
 
 The solid rows are measured by us, from the request each setup actually sends through one local test provider. That includes OpenCode, the DeepSeek Harness, and Oh My Pi, all measured as installed. The faded Codex CLI and Claude Code rows come from HarnessTax's published numbers, measured under their own setup. Treat those as a rough reference, not a head-to-head test. These are character counts. They say nothing about tokens, cost, or how well each tool does the job. The research page [breaks down the enabled setup by feature](https://tannermidd.github.io/SpecPi/research/#specpi), so you can see what each switch costs on its own.
 
@@ -123,7 +123,7 @@ Full setup options, package details, and requirements: [website](https://tannerm
 
 | | |
 | --- | --- |
-| [Packages](https://tannermidd.github.io/SpecPi/#packages) | The eight pinned packages and what each provides |
+| [Packages](https://tannermidd.github.io/SpecPi/#packages) | The seven pinned packages and what each provides |
 | [Scope control](https://tannermidd.github.io/SpecPi/wiki/#scope) | `/scope` commands and drift monitoring |
 | [Improvement loop](https://tannermidd.github.io/SpecPi/#loop) | Local wishlist, `/harness-improvement`, and retirement with evidence |
 | [SpecPi Chat](https://tannermidd.github.io/SpecPi/#vscode-chat) | VS Code frontend and VSIX install · [Chat guide](https://github.com/TannerMidd/SpecPi/blob/main/vscode/README.md) |

package/SECURITY_MODEL.md

@@ -1,6 +1,6 @@
 # Security model
 
-SpecPi provides scope monitoring, an explicit harness improvement loop and an optional Jev advisor, and installs eight pinned packages as its default base. Extensions run as trusted code with Pi's permissions. Scope is not an OS sandbox or a general command guard. Use OS isolation for hostile code.
+SpecPi provides scope monitoring, an explicit harness improvement loop and an optional Jev advisor, and installs seven pinned packages as its default base. Extensions run as trusted code with Pi's permissions. Scope is not an OS sandbox or a general command guard. Use OS isolation for hostile code.
 
 ## Scope monitoring
 
@@ -30,23 +30,29 @@ The advisor also keeps `<agent-dir>/specpi/jev/usage.json`, the running call cou
 
 The advisor holds no authority. It never grants a capability, never calls a tool and never allows one. Its only blocking action is to refuse a capability-gap report that looks like it carries a credential, which asks the model to rewrite its own text and discards nothing. Failure is silent, not closed: a timeout, HTTP error, missing key, missing consent, an exhausted per-system or session budget, or ungated confidence produces no advice, and the existing code path runs unchanged. Tool-result retention can shorten a large read-only result before it is appended; it never alters a write, edit or error result, and the replacement says the output is recoverable by re-running.
 
-Two of the seven systems do something the other five do not, and both are off by default like everything else here.
+Three of the eight systems do something the other five do not, and all three are off by default like everything else here.
 
 **System 5, progress detection**, is the only one that can change what the model does. On a confident verdict that a session has stopped making progress it adds one fixed, code-written line at a turn boundary. It ships set to `notify`, which tells the person and cannot change the session; `message`, which appends the line for the model to read, is a deliberate opt-in. It is written once per session and never retracted, it never aborts or blocks, and it is suppressed entirely when the same call reports that a person would have to answer something first. Nothing the model produced ever enters the transcript: the line is chosen from a fixed table by failure mode.
 
+**System 8, the command guard**, is the only one that can refuse a tool call, and it has its own section below. It is named here because the rest of this layer never blocks anything, and a reader who took "the advisor holds no authority" to cover every system would be wrong about exactly one of them. `/jev on` enables it with the other seven and says in the same notification that it can refuse a command; `/jev disable guard` turns it off. An unattended schema migration never arms it.
+
 **System 7, untrusted-content classification**, prepends a fixed warning line to externally fetched content that confidently reads as instructions addressed to an agent. It applies only to web and browser tool results, never to the agent's own shell output or file reads. It is defence in depth and explicitly not a control: it never blocks, it has no authority over what the model then does, and it should not be relied on to stop prompt injection. Its value is that untrusted content in a fetched page is currently owned by nothing at all.
 
 An earlier version of this document said its false-positive rate was measurable on tier 5 of the eval suite. It is not, and the re-run that checked found out why: **this system has never been called once**. It rides on a web or browser tool result, no task in any tier produces one, and the run that would have exercised Browser QA keeps it withdrawn because capability arming needs an interactive human. So the honest statement is that system 7 ships unmeasured, and the eval suite as it stands cannot measure it. That is a gap in the suite, not a property of the system, and it is stated here rather than left as an absent number that would read as a zero.
 
-Settings live in `<agent-dir>/specpi/jev/settings.json`, written atomically with owner-only permissions. Links, irregular files, oversize files, an unrecognised schema and unparseable contents all read as off. The one exception is the layer's own previous schema: a `schema: 1` file is migrated forward rather than read as unrecognised, because "collapse to all-off" is a rule for corrupt input and applying it to our own earlier version would silently disable a layer the user had switched on. Call budgets are per system under a session total, so one busy system cannot exhaust the allowance of the others and leave them dead for the rest of the session with event ordering deciding which one won. Session toggles write no startup preference. The key is read from the environment only; Pi authentication, credentials, trust decisions, sessions and history are never read.
+Settings live in `<agent-dir>/specpi/jev/settings.json`, written atomically with owner-only permissions. Links, irregular files, oversize files, an unrecognised schema and unparseable contents all read as off. The one exception is the layer's own previous schema: a `schema: 1` file is migrated forward rather than read as unrecognised, because "collapse to all-off" is a rule for corrupt input and applying it to our own earlier version would silently disable a layer the user had switched on. Call budgets are per system under a session total, so one busy system cannot exhaust the allowance of the others and leave them dead for the rest of the session with event ordering deciding which one won. Turning the layer on or off writes that preference, because a switch that forgets is not a switch; `--session` is how a one-off change is kept out of the file. The key is resolved the way Pi resolves every provider credential, in Pi's own documented order: the `openrouter` entry that `/login openrouter` writes to `<agent-dir>/auth.json`, then the environment variable. That is a deliberate, narrow exception to the rule that Pi state is never read, and it is bounded to exactly one question &mdash; the one `api_key` entry for the one provider this layer calls. Be precise about when: the key's *value* is read only on a call path the master switch already gates, but whether an entry *exists* is checked whenever status is displayed, including with the layer off, because that is the answer someone needs in order to configure it in the first place. A presence check reports a source name and nothing else. An `oauth` entry is ignored rather than unwrapped, because Pi refreshes those under its own lock and a second reader would race a rotation. The value is returned by a single function straight into a request header; nothing else in the layer receives it, and status output, the ledger and the Chat panel carry source names only. Pi trust decisions, sessions, missions and history are never read. `JEV_KEY_SOURCE=environment` restricts resolution to the environment, which is what this repository's own eval scripts set so a measured run cannot silently bill a developer's personal account.
 
 ## Command policy and the Jev guard
 
-`specpi-jev-guard` is pinned in the base set but ships **inert**. Its own default is `enabled: true`, so left alone a fresh install would begin gating shell and file calls through a third-party service immediately; SpecPi writes `enabled: false` and `/jev guard on` is how a human opts in. `@gotgenes/pi-permission-system` stays pinned and, while the guard is off, decides every tool call exactly as it did before the guard existed.
+The command guard is the layer's eighth system, native since schema 3, and ships off like the other seven. It was a pinned third-party package until that package's shape proved to be its own source of defects: a global configuration file with no session scope, a key read from the environment only — so a credential `/login` had stored was invisible to it — and a fail-closed posture, which meant an outage or a missing key stopped shell work rather than degrading. `@gotgenes/pi-permission-system` stays pinned and decides every call the guard defers, which is every call it does not confidently judge destructive.
+
+The guard **fails open**, which is the deliberate inversion of what it replaced. Local rules settle most calls without sending anything: simple commands and ordinary project writes pass for nothing, and a very short list of catastrophic, unambiguous commands is blocked with no call at all. The allowlist is a budget mechanism and not a safety one &mdash; it exists so a session of `ls` and `grep` cannot spend the guard's whole call budget and leave nothing for the calls that matter &mdash; so a binary is admitted only when it is simple whatever flags it is given. Anything that can launch a program, write a file or change machine state under any flag goes to the model, however harmless its name reads. The catastrophic list is separate and deliberately tiny: its real job is the case where Jev is unreachable, since a model that can weigh intent catches everything a pattern would and more. Anything else is scored, and a call is blocked only on a confident destructive verdict that the request does not account for — both, because a destructive-looking command the person asked for in as many words is the likeliest way to be wrong. A confident verdict that a write targets a real credential file blocks on its own. Everything else — no key, no budget, a timeout, an unconfident answer, or a middle-band verdict with no human to ask — hands the call to `@gotgenes/pi-permission-system`, which decides it exactly as it did before this layer existed. Deferring is not allowing.
+
+Both halves of the block rule must clear the same confidence gate. A destructive verdict alone is not enough and neither is an absent intent answer read as agreement: roughly four Score answers in five do not gate, so treating "no answer" as "not what was asked for" would have made the second half apply to about one call in five. When there is a human and the guard asks, only the affirmative reply runs the call; a dismissed dialog is not consent.
 
-Be precise about what the guard does once it is on, because it cannot be configured away. The guard is **fail-closed by design**: with no key, an unreachable endpoint, or a middle-band verdict in a session with no UI, it blocks the call and reports why. There is no setting that hands the decision back to the permission system instead. So switching it on accepts that an outage stops gated work until it is switched off again. That trade is the user's to make, which is why it ships off and why `/jev status` and `specpi doctor` state plainly whether it is on, which backend it uses and whether that backend's key is present.
+What is gated is stated rather than implied: the shell tools under every alias the harness maps onto `bash`, and the write tools under every name — `write`, `edit`, `multi_edit`, `apply_patch`, `create_file`, `str_replace`. A shell call's text is read from whichever field carries it, so a tool that types into a live shell is judged on what it types rather than on an empty string. A write whose target cannot be read from the tool input is asked about rather than passed, because a field this layer does not recognise should cost a question and not open a hole. A protected path is matched anywhere in a resolved path, directory as well as file, so `secrets/api.txt` is a secret and not an ordinary project file, and a read-only command pointed at one — `cat ~/.ssh/id_rsa` changes nothing and still hands over a key — leaves the free path and is asked about like anything else. Neither the guard nor the advisor is an OS sandbox.
 
-SpecPi asserts only three fields in `<home>/.pi/jev-guard.json` and merges them into whatever is already there, so a user's own thresholds, safe-command globs and protected paths survive: `enabled`, `uncertain: "ask"` so a middle-band verdict asks a human wherever there is one to ask, and `backend: "typesafe"` so the guard and the advisor read the same `TYPESAFE_API_KEY` rather than the guard needing a separate `OPENROUTER_API_KEY`. Those fields are rewritten at every session start, outside the advisor's master switch, because whether the guard is inert is a property of the install rather than a feature of the advisor — and off is a written configuration, not an absence of one. SpecPi writes only the global file; a project-local override under a workspace's `.pi/` remains the user's to make. Neither the guard nor the advisor is an OS sandbox.
+Two failures do not fail open, and both are about a person. An announcement that cannot be delivered never changes a decision already taken; and once a verdict says a call needs human approval, a host that cannot present the question has not obtained it, so the call is refused rather than run. Everything that fails open fails open *before* anyone was asked.
 
 ## Improvement authority and evidence
 
@@ -60,11 +66,11 @@ Wishlist records remain local under `<agent-dir>/specpi/`. Sanitization and salt
 
 Package acquisition requests exact npm dependency saves through the child process environment and verifies the installed top-level versions before completing the transaction. A mismatch fails the operation and triggers managed-state rollback. Upstream transitive dependency ranges remain outside this pinning guarantee.
 
-`plan` is read-only. Installation, updates, and removal require confirmation or `--yes`. SpecPi manages its two first-party extension families, improvement skill, manifest, AGENTS marker block, and the eight package entries listed in `templates/settings.json`. Normal install/update runs `pi install npm:<name>@<pin>` for every default package. Only package entries are merged; existing resource filters and unrelated settings are retained. `--skip-package-install` allows a core-only install or preserves an already configured base during update, skipping Chromium setup too. Confirmed install/update otherwise invokes the installed Browser QA Node bin with bounded subprocesses to download Chromium and check readiness. `--skip-browser-install` skips that setup only; doctor still checks readiness. SpecPi never passes `--with-deps`, auto-installs OS libraries, or installs/removes Bun. No new shell profile integration is installed.
+`plan` is read-only. Installation, updates, and removal require confirmation or `--yes`. SpecPi manages its two first-party extension families, improvement skill, manifest, AGENTS marker block, and the seven package entries listed in `templates/settings.json`. Normal install/update runs `pi install npm:<name>@<pin>` for every default package. Only package entries are merged; existing resource filters and unrelated settings are retained. `--skip-package-install` allows a core-only install or preserves an already configured base during update, skipping Chromium setup too. Confirmed install/update otherwise invokes the installed Browser QA Node bin with bounded subprocesses to download Chromium and check readiness. `--skip-browser-install` skips that setup only; doctor still checks readiness. SpecPi never passes `--with-deps`, auto-installs OS libraries, or installs/removes Bun. No new shell profile integration is installed.
 
 Managed configuration and files are locked and backed up before mutation; first-party writes are atomic and checksum-tracked. Failure restores the saved configuration and first-party files. Package acquisition runs upstream package-manager scripts and may leave downloads, dependency changes, or external script effects even after configuration rollback. Those effects, including downloaded browser-cache bytes, are outside SpecPi's transaction and survive uninstall. Updates require `--force` before replacing modified retained resources. Retired resources are backed up before deactivation; pre-install files are restored where ownership records identify them. Old runtime directories are moved into backups without inspecting their contents. Backups and private evidence remain after uninstall and can contain sensitive local material.
 
-Legacy migration restores only recorded settings ownership, preserves differing user values, and removes only the SpecPi shell marker block before applying the new base. The installer does not enumerate or modify authentication, provider credential stores, trust, sessions, missions, history, or unrelated private evidence. Normal updates deliberately reapply the default package pins, retaining the original entry for removal. Uninstall restores only package entries that still match the last installed value; user edits are preserved. Downloaded packages and tools are not deleted. Resources that SpecPi never owned require separate human management.
+Legacy migration restores only recorded settings ownership, preserves differing user values, and removes only the SpecPi shell marker block before applying the new base. The installer does not enumerate or modify authentication, provider credential stores, trust, sessions, missions, history, or unrelated private evidence. Normal updates deliberately reapply the default package pins, retaining the original entry for removal. A package a past version pinned and this one has retired is unpinned by name on install and update, including under `--skip-package-install`, because skipping acquisition has never meant leaving an entry SpecPi wrote pointing at code whose controls SpecPi has removed; `specpi doctor` reports one that is still configured. Its downloaded files remain, as every other package's do. Uninstall restores only package entries that still match the last installed value; user edits are preserved. Downloaded packages and tools are not deleted. Resources that SpecPi never owned require separate human management.
 
 ## Browser QA package
 
@@ -72,7 +78,7 @@ Legacy migration restores only recorded settings ownership, preserves differing
 
 ## VS Code frontend
 
-SpecPi Chat is a separate VSIX, retained alongside the npm harness. It launches Pi only in a trusted filesystem workspace and communicates over local RPC. Provider credentials stay with Pi. Sign-in is delegated rather than implemented: Chat can start the configured Pi executable in a user-visible VS Code terminal, without RPC flags or a session, and Pi alone prompts, runs any OAuth flow, and writes `auth.json`. Chat sends no input to that terminal, reads no credential store, runs no Pi auth subcommand, and accepts no credential over RPC; it observes only the terminal's closure, and restarts the connection so Pi re-resolves its catalogue. Its sign-in prompt is derived from Pi's own available-model list and missing-credential error text. The frontend manages only its own workspace-storage conversation catalog and sessions for user-directed history, branching, and export; it does not import unrelated Pi histories. Attachments, images, webview messages, and file navigation are validated and bounded. Rendered model and tool output is untrusted text, never executable HTML.
+SpecPi Chat is a separate VSIX, retained alongside the npm harness. It launches Pi only in a trusted filesystem workspace and communicates over local RPC. Provider credentials stay with Pi. Sign-in is delegated rather than implemented: Chat can start the configured Pi executable in a user-visible VS Code terminal, without RPC flags or a session, and Pi alone prompts, runs any OAuth flow, and writes `auth.json`. Chat sends no input to that terminal, runs no Pi auth subcommand, and accepts no credential over RPC; it reads `auth.json` for one question only &mdash; whether an `openrouter` api_key entry is present &mdash; and the host sends the webview a boolean per source and never a value, so the panel reports where a key would come from without being a place one could leak from; it observes only the terminal's closure, and restarts the connection so Pi re-resolves its catalogue. Its sign-in prompt is derived from Pi's own available-model list and missing-credential error text. The frontend manages only its own workspace-storage conversation catalog and sessions for user-directed history, branching, and export; it does not import unrelated Pi histories. Attachments, images, webview messages, and file navigation are validated and bounded. Rendered model and tool output is untrusted text, never executable HTML.
 
 Approval replies are tied to the current conversation, client, and request ID. Disconnect, cancellation, and expiry never grant permission. Multiline package approval context is shown in the dialog body; requests exceeding the display budget are cancelled rather than approved against incomplete context. The Permissions editor can change only the package's documented global/project `config.json`, with bounded UTF-8/schema validation, explicit native confirmation, connection/scope binding, stale-revision checks, private backups, and atomic replacement. It reads no permission logs, trust decisions, credentials, or agent frontmatter. Symlinks, hardlinks, and special files are refused. Backups remain local and may contain sensitive policy; another same-user process can still race filesystem operations. Saving does not claim runtime activation: the user can restart the selected chat and inspect `/permission-system show`. Global/project changes may affect other chats as upstream reloads them; session approvals are cleared by restart. Delegated agent activity comes from a read-only, connection-local widget the delegation package publishes; Chat registers no tools or commands of its own for it. The VSIX does not install packages or duplicate their enforcement; only Permission System configuration has an explicit editing UI. TUI-only custom components are outside Pi's RPC rendering support.
 

package/THIRD_PARTY.md

@@ -24,7 +24,6 @@ SpecPi requests exact npm dependency saves for these pins and checks installed t
 | pi-goal-x                      | 0.31.2  | [tmonk/pi-goal-x](https://github.com/tmonk/pi-goal-x)                     |
 | @sreetej510/pi-usage           | 0.10.0  | [Sreetej510/pi-extensions](https://github.com/Sreetej510/pi-extensions)   |
 | @gotgenes/pi-permission-system | 32.0.2  | [gotgenes/pi-packages](https://github.com/gotgenes/pi-packages)           |
-| specpi-jev-guard               | 0.1.0   | [TannerMidd/specpi-jev-guard](https://github.com/TannerMidd/specpi-jev-guard) |
 
 Transitive dependencies and their notices remain in Pi's npm installation tree. Top-level pins do not freeze upstream dependency ranges or constitute a full transitive security audit. Pi invokes npm with its upstream package-management semantics, including dependency lifecycle scripts. Browser QA has no install hook: confirmed SpecPi install/update explicitly invokes its installed Node setup bin, unless acquisition or browser setup is skipped. It downloads package-pinned Chromium without installing OS libraries. BetterWright is optional/manual and retains its own Bun-based setup; SpecPi neither removes Bun nor deletes user-owned tools. Usage reporting and web packages make their own provider/service connections. Consult upstream licenses and security policies before redistributing their components.
 
@@ -34,7 +33,7 @@ The combined base is tested with Pi 0.84.4. Pi Goal X declares Pi `>=0.83.0 <0.8
 
 ## Network services
 
-The optional Jev advisor and `specpi-jev-guard` both reach TypeSafe's System One endpoint. Neither is a bundled dependency: the advisor is first-party source that uses Node's built-in `fetch` and declares no package, and the guard is a pinned MIT package with no declared dependencies. Both require a key supplied by the user through the environment -- `OPENROUTER_API_KEY` on the default OpenRouter route, `TYPESAFE_API_KEY` when `JEV_BACKEND=typesafe` selects the direct API. The two are not interchangeable: the other service rejects the wrong one with a bare 401. SpecPi never provisions, stores or reads provider credentials for them.
+The optional Jev layer, command guard included, reaches TypeSafe's System One endpoint. It is not a bundled dependency: it is first-party source that uses Node's built-in `fetch` and declares no package. The guard used to be a separate pinned package; it is now the layer's eighth system, so one switch, one budget and one key serve the whole thing. That key is resolved the way every other Pi provider credential is resolved, in Pi's own documented order: the `openrouter` entry that `/login openrouter` writes to `<agent-dir>/auth.json`, then `OPENROUTER_API_KEY` from the environment (`TYPESAFE_API_KEY` when `JEV_BACKEND=typesafe` selects the direct API). The two keys are not interchangeable: the other service rejects the wrong one with a bare 401. SpecPi never provisions or stores a provider credential, and reads one only to place it in the request header of the call the user has switched on.
 
 Requests go to `openrouter.ai` by default, or to `api.typesafe.ai` on the direct backend, unless `TYPESAFE_BASE_URL` redirects them, which exists so tests never reach the network and the eval proxy can price advisor traffic. Retention and processing of what is sent are governed by TypeSafe and, on the default route, by OpenRouter as well -- not by SpecPi; the advisor ships off, asks before its first transmission and records a hash of every payload locally. The frozen eval price list carries `jev-1.13.0` at $0.042/MTok input and free output so a measured SpecPi + Jev row never reports a cost that excludes its own advisor.
 

package/extensions/jev-advisor/broker.mjs

@@ -28,6 +28,7 @@ export const SYSTEM_LABELS = Object.freeze({
     progress: "Progress and thrash detection",
     untrusted: "Untrusted-content classification",
     capability: "Turn-zero capability arming",
+    guard: "Command guard",
 });
 
 export function createBroker(options = {}) {

package/extensions/jev-advisor/client.mjs

@@ -6,6 +6,22 @@
 // the path it would have run before this extension existed. That is fail-silent, not fail-closed —
 // nothing here is ever the reason a tool is blocked.
 
+import { backend, resolveKey } from "./key-source.mjs";
+
+/**
+ * Where a key comes from is resolved in key-source.mjs, which follows Pi's own order: the
+ * `auth.json` entry `/login openrouter` writes, then the environment variable.
+ *
+ * Every one of these defaults its route to `backend()` rather than to the string "openrouter", so a
+ * no-arg call resolves against the backend actually in force. That matters because it briefly did
+ * not: when `apiKey` was first replaced by a re-export of a function whose parameter defaulted to a
+ * literal, `apiKey()` returned a stored OpenRouter key under `JEV_BACKEND=typesafe` -- a script's
+ * `if (!apiKey())` guard passed and it spent a run, while every request underneath came back
+ * `no-key`. The fix belongs at the definition, which is where it now is; a wrapper here would only
+ * have hidden that three sibling exports had the same defect.
+ */
+export { backend, keyEnvName, keyPresent, keySource, keySources, resolveKey as apiKey } from "./key-source.mjs";
+
 export const DEFAULT_MODEL = "jev-1.13.0";
 export const OPENROUTER_MODEL = "typesafe/jev-1.13";
 // Measured round trip is ~250-400ms through OpenRouter. 800ms left no headroom for a slow call,
@@ -14,32 +30,6 @@ export const OPENROUTER_MODEL = "typesafe/jev-1.13";
 export const DEFAULT_TIMEOUT_MS = 1500;
 const MAX_TIMEOUT_MS = 5000;
 
-/**
- * Jev is reached through OpenRouter by default: that is where it is published, it is what
- * specpi-jev-guard already uses, and an OpenRouter key (`sk-or-...`) is rejected by the direct
- * TypeSafe API with a bare 401. `JEV_BACKEND=typesafe` selects the direct API for a TypeSafe key.
- */
-export function backend() {
-    return process.env.JEV_BACKEND === "typesafe" ? "typesafe" : "openrouter";
-}
-
-/**
- * The key variable follows the backend, matching specpi-jev-guard's own `keyEnvName`, so one key
- * serves the whole layer. TYPESAFE_API_KEY is still accepted on the OpenRouter path so an existing
- * env file keeps working.
- */
-export function apiKey() {
-    const name = backend() === "openrouter" ? "OPENROUTER_API_KEY" : "TYPESAFE_API_KEY";
-    const direct = process.env[name];
-    if (typeof direct === "string" && direct.trim().length > 0) {
-        return direct.trim();
-    }
-
-    const legacy = backend() === "openrouter" ? process.env.TYPESAFE_API_KEY : undefined;
-
-    return typeof legacy === "string" && legacy.trim().length > 0 ? legacy.trim() : undefined;
-}
-
 /** Overridable so tests never reach the network and the eval proxy can price the traffic. */
 export function baseUrl() {
     const configured = process.env.TYPESAFE_BASE_URL;
@@ -119,7 +109,7 @@ function normalizeAnswer(raw) {
  * every question that state can answer rather than paying for the state again.
  */
 export async function ask(state, questions, options = {}) {
-    const key = apiKey();
+    const key = resolveKey(backend());
     if (!key) {
         return unavailable("no-key");
     }

package/extensions/jev-advisor/config.mjs

@@ -1,7 +1,9 @@
 // Jev is the first thing in SpecPi that talks to a third party, so its switch is the first thing
-// every other module in this directory consults. Master off means no key read, no consent read, no
-// network call and no prompt injection: the harness behaves exactly as it did before the extension
-// existed.
+// every other module in this directory consults. Master off means no key value read, no consent
+// read, no network call and no prompt injection: the harness behaves exactly as it did before the
+// extension existed. `/jev status` still reports whether a key exists while the layer is off, by
+// name and never by value, because "how do I configure this" is a question asked before enabling
+// anything -- see key-source.mjs.
 //
 // The file is SpecPi's own, hardened the same way as web-access and capability-policy: atomic
 // write, mode 0600, symlinks refused, and a missing or unreadable file read as off.
@@ -20,6 +22,14 @@ export const SYSTEM_NAMES = Object.freeze([
     "progress",
     "untrusted",
     "capability",
+    // The command guard, native since schema 3. It used to be a separate pinned package with its own
+    // global configuration file, which is why it used to carry its own switch here: a second switch,
+    // outside the master, with its own startup preference and its own persistence rules. Those rules
+    // disagreed with the layer's often enough to be their own source of defects -- a preference
+    // erased by a command that had decided nothing about the guard, a state written by one command
+    // and reverted by the next session. As a system it is gated, budgeted, reported and toggled by
+    // exactly the same code as the other seven.
+    "guard",
 ]);
 
 /**
@@ -91,6 +101,12 @@ export const DEFAULT_BUDGETS = Object.freeze({
     // Once per session by construction, and only when local signals already suggest it. Two rather
     // than one so a retried first turn is not silently un-served.
     capability: 2,
+    // Per gated tool call that local rules could not settle, so its frequency is retention's rather
+    // than compaction's -- and like retention, most calls never reach it: read-only commands and
+    // ordinary project writes are answered locally for nothing. Running out means the guard defers
+    // to the permission system for the rest of the session, which is what it does for every other
+    // kind of unavailability.
+    guard: 208,
 });
 
 /** 0 is a real budget meaning no calls. Switching a system off is what `systems[name] = false` is for. */
@@ -127,16 +143,12 @@ export function regularFile(file, label) {
 /** Every unknown shape collapses to the same all-off default rather than a partial enable. */
 export function defaultSettings() {
     return {
-        schema: 2,
+        schema: 3,
         master: false,
         startup: false,
         systems: Object.fromEntries(SYSTEM_NAMES.map((name) => [name, false])),
         budgets: { ...DEFAULT_BUDGETS },
         progressNudge: "notify",
-        // The guard is a separate package with its own gate, so it carries its own switch rather
-        // than riding the advisor's master. Both ship off: nothing in the Jev layer is active on a
-        // fresh install, and `startup` is how a user chooses to default one on.
-        guard: { enabled: false, startup: false },
     };
 }
 
@@ -174,22 +186,42 @@ function migrate(raw) {
     return { ...raw, schema: 2, budgets, callBudgetPerSession: undefined };
 }
 
+/**
+ * Schema 2 carried the command guard as a separate `guard: { enabled, startup }` pair, because it
+ * was a separate package with its own global configuration file. Schema 3 makes it the eighth
+ * system, so the stored preference becomes `systems.guard`.
+ *
+ * `guard.startup` is what migrates, not `guard.enabled`: the former is what the user chose for new
+ * sessions, and the latter was a session flag that happened to be written to disk. A file where the
+ * guard was wanted at startup but the layer itself was not produces a system that is on inside a
+ * layer that is off, which is inactive -- the guard used to sit outside the master switch and now
+ * does not. That direction is deliberate: a gate quietly becoming inactive is recoverable in one
+ * command, and a gate quietly becoming active is how a session stops being able to run anything.
+ */
+function migrateToThree(raw) {
+    const systems = { ...(raw?.systems ?? {}), guard: raw?.guard?.startup === true };
+
+    const { guard: _guard, ...rest } = raw ?? {};
+
+    return { ...rest, schema: 3, systems };
+}
+
 function normalize(raw) {
-    const source = raw?.schema === 1 ? migrate(raw) : raw;
-    if (source?.schema !== 2) {
+    const one = raw?.schema === 1 ? migrate(raw) : raw;
+    const source = one?.schema === 2 ? migrateToThree(one) : one;
+    if (source?.schema !== 3) {
         return defaultSettings();
     }
 
     const systems = Object.fromEntries(SYSTEM_NAMES.map((name) => [name, source.systems?.[name] === true]));
 
     return {
-        schema: 2,
+        schema: 3,
         master: source.master === true,
         startup: source.startup === true,
         systems,
         budgets: normalizeBudgets(source.budgets),
         progressNudge: NUDGE_MODES.includes(source.progressNudge) ? source.progressNudge : "notify",
-        guard: { enabled: source.guard?.enabled === true, startup: source.guard?.startup === true },
     };
 }
 
@@ -222,7 +254,7 @@ export function writeFileAtomic(file, contents) {
 export function saveSettings(settings) {
     // A caller handing back a schema-1 shape is migrated rather than reset, so a round trip through
     // an old reader cannot quietly disable the layer.
-    const next = normalize(settings?.schema === 1 ? settings : { ...settings, schema: 2 });
+    const next = normalize(settings?.schema === 1 || settings?.schema === 2 ? settings : { ...settings, schema: 3 });
     const file = settingsFile();
     if (fs.existsSync(file)) {
         regularFile(file, "Jev settings");
@@ -236,19 +268,3 @@ export function saveSettings(settings) {
 export function settingsPath() {
     return settingsFile();
 }
-
-/**
- * The key is never read into any structure that gets logged or serialized. Callers only ever ask
- * whether one is present; the client reads it directly at call time.
- */
-export function keyPresent() {
-    // OPENROUTER_API_KEY on the default path, TYPESAFE_API_KEY on the direct one; see client.mjs.
-    for (const name of ["OPENROUTER_API_KEY", "TYPESAFE_API_KEY"]) {
-        const value = process.env[name];
-        if (typeof value === "string" && value.trim().length > 0) {
-            return true;
-        }
-    }
-
-    return false;
-}

package/extensions/jev-advisor/gate.mjs

@@ -156,6 +156,20 @@ export const THRESHOLDS = Object.freeze({
         high: 0.85,
         low: 0.15,
     }),
+    guard: Object.freeze({
+        // The same measured Score operating point as every other system, written out rather than
+        // inherited by falling through `thresholdsFor`'s default. The guard asked under the name
+        // "gap" for exactly as long as it took to notice that adding a `guard` entry would then have
+        // changed nothing -- a silent no-op on the one system whose action takes a tool call away.
+        scoreConfidence: 0.6,
+        boundary: 0.3,
+        choiceConfidence: 0.75,
+        margin: 0.2,
+        // Unused: this system reads only the Score side. Kept so every system has a full set, and
+        // so the calibration tests cover this entry like any other.
+        high: 0.85,
+        low: 0.15,
+    }),
     sources: Object.freeze({
         scoreConfidence: 0.6,
         boundary: 0.3,