specpi 0.28.0 → 0.29.0

package/extensions/jev-advisor/index.ts

@@ -2,12 +2,11 @@ import fs from "node:fs";
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { SYSTEM_NAMES, loadSettings, saveSettings, settingsPath } from "./config.mjs";
 import { keySources } from "./key-source.mjs";
-import { applyLayer, guardWarning, layerScopeLine, layerToPersist, startupToPersist } from "./layer.mjs";
+import { applyLayer, layerScopeLine, layerToPersist, startupToPersist } from "./layer.mjs";
 import { consentPath, granted, revokeConsent } from "./consent.mjs";
 import { createBroker } from "./broker.mjs";
 import { ledgerPath, read as readLedger } from "./ledger.mjs";
 import { usagePath } from "./usage.mjs";
-import { GATED_TOOLS, SHELL_TOOLS, callTargets, classifyCall, commandText } from "./risk.mjs";
 import * as retention from "./questions/retention.mjs";
 import * as compaction from "./questions/compaction.mjs";
 import * as gap from "./questions/gap.mjs";
@@ -15,42 +14,13 @@ import * as sources from "./questions/sources.mjs";
 import * as progress from "./questions/progress.mjs";
 import * as untrusted from "./questions/untrusted.mjs";
 import * as capabilities from "./questions/capabilities.mjs";
-import * as guard from "./questions/guard.mjs";
 
 const MAX_RECENT = 8;
 
-/** One line of a call, for a notification or a block reason. Never a digest; never sent anywhere. */
-function short(value: string, limit: number) {
-    const text = String(value ?? "")
-        .replace(/\s+/gu, " ")
-        .trim();
-
-    return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
-}
-
 function safeMessage(error: unknown) {
     return String((error as any)?.message ?? error ?? "unknown error").slice(0, 200);
 }
 
-/**
- * Tell the person something, and never let the telling change what happens.
- *
- * `ctx.ui.notify` reaches the host over RPC and can throw -- a disconnected client, a torn-down UI,
- * a host without the method. Called inline inside the guard's fail-open catch, one such throw
- * unwound a decided refusal into an allow, so the announcement is isolated from the decision here.
- */
-function announce(ctx: ExtensionContext, message: string) {
-    if (!ctx.hasUI) {
-        return;
-    }
-
-    try {
-        ctx.ui.notify(message, "error");
-    } catch {
-        // A failed notification is not a reason to run a command, or not to.
-    }
-}
-
 export default function jevAdvisor(pi: ExtensionAPI) {
     // Session switches live in memory. A session toggle must never write the startup preference,
     // so the saved file is read once per session and only /jev startup ever writes it.
@@ -254,111 +224,6 @@ export default function jevAdvisor(pi: ExtensionAPI) {
         }
     });
 
-    // System 8: the command guard, before a shell or file call runs.
-    //
-    // Fail open at every step. Local triage settles most calls for nothing; anything else is asked
-    // about, and a call is blocked only on a confident verdict that the request does not account
-    // for. Every other outcome -- no key, no budget, a timeout, an unconfident answer, no human to
-    // ask -- returns the call to @gotgenes/pi-permission-system, which decides it exactly as it did
-    // before this layer existed. The package this replaced was fail-closed, so an outage or a
-    // missing key stopped work; that is the single behaviour most worth not reproducing.
-    pi.on("tool_call", async (event: any, ctx: ExtensionContext) => {
-        if (!enabled("guard") || !GATED_TOOLS.includes(event?.toolName)) {
-            return undefined;
-        }
-
-        const shell = SHELL_TOOLS.includes(event.toolName);
-        // Not `input.command`: `write_stdin` types into a live shell under another name, so reading
-        // one key classified every such call as the empty string -- spending a guard call on nothing
-        // while the text actually being run went unexamined.
-        const command = shell ? commandText(event?.input) : "";
-        // Every file the call names, because `multi_edit` and `apply_patch` do not carry one `path`
-        // and a target the guard cannot see is a target it never asks the credential question about.
-        const targets = callTargets(event?.input);
-        const local = classifyCall({ tool: event.toolName, command, targets, cwd: ctx.cwd });
-        const subject = shell
-            ? command || "(command unknown)"
-            : `${event.toolName} ${targets.join(", ") || "(target unknown)"}`;
-
-        // Built once, and nothing inside it may throw. A refusal that has already been decided must
-        // reach the harness: an exception raised while announcing it would unwind into the fail-open
-        // catch below and turn the layer's only blocking action into an allow.
-        const refuse = (reason: string) => {
-            announce(ctx, `Jev guard blocked ${event.toolName}: ${reason}.`);
-
-            return { block: true, reason: `Jev guard: ${reason}. Call: ${short(subject, 160)}` };
-        };
-
-        if (local.decision === "safe") {
-            return undefined;
-        }
-
-        if (local.decision === "dangerous") {
-            // Catastrophic and unambiguous, so it needs neither a network call nor a human. This is
-            // the one path that blocks without asking Jev, which is why its rule list is tiny.
-            return refuse(local.reason);
-        }
-
-        let verdict;
-        try {
-            const result = await broker.request({
-                system: "guard",
-                state: guard.buildInput({
-                    tool: event.toolName,
-                    subject,
-                    protectedTarget: local.reason === "writes to a protected path",
-                    objective,
-                    recent,
-                    cwd: ctx.cwd,
-                }),
-                questions: guard.questions({ protected: local.reason === "writes to a protected path" }),
-                ctx,
-                root: ctx.cwd,
-                decide: (answers: any) => {
-                    const verdict = guard.decide(answers, { hasUI: ctx.hasUI });
-
-                    return { applied: verdict.action !== "defer", decision: verdict };
-                },
-            });
-            if (!result.ok) {
-                return undefined;
-            }
-
-            verdict = result.decision;
-        } catch {
-            // An advisor must never be the reason a tool call fails. Anything unexpected while
-            // asking hands the call back to the permission system unchanged. The catch ends here, so
-            // that everything the verdict then decides is outside it.
-            return undefined;
-        }
-
-        if (verdict.action === "block") {
-            return refuse(verdict.reason);
-        }
-
-        if (verdict.action === "ask" && ctx.hasUI) {
-            let choice;
-            try {
-                choice = await ctx.ui.select({
-                    title: "Jev guard",
-                    message: `This looks ${verdict.reason}: ${short(subject, 300)}`,
-                    options: [guard.CHOICES.run, guard.CHOICES.block],
-                });
-            } catch {
-                // The one failure in this file that does not fail open, and deliberately. Reaching
-                // here means the verdict already said this call needs a person's approval; a host
-                // that cannot ask has not obtained it, and an unanswerable question resolved as yes
-                // is the failure mode a confirmation dialog exists to rule out.
-                return refuse("this needs your approval and you could not be asked");
-            }
-
-            // `guard.approved` owns the rule; see it for why every non-answer is a refusal.
-            return guard.approved(choice) ? undefined : refuse("not approved by you");
-        }
-
-        return undefined;
-    });
-
     // System 1: condense a spent tool result before it is appended. Doing this after the fact would
     // rewrite a cached prefix; on arrival it never touches one.
     pi.on("tool_result", async (event: any, ctx: ExtensionContext) => {
@@ -379,11 +244,10 @@ export default function jevAdvisor(pi: ExtensionAPI) {
             }
         }
 
-        // Every result, not only the ones retention asked about. This history is what lets the
-        // command guard tell a cleanup step from a first move, and it was written in one place --
-        // inside retention's success path -- so a session running the guard with retention off, or
-        // with retention's budget spent, evaluated the block rule against an empty history for its
-        // whole length while the question set said history was what the intent answer weighed.
+        // Every result, not only the ones retention asked about. It was written in one place --
+        // inside retention's success path -- so a session with retention off, or with retention's
+        // budget spent, handed every other system an empty history for its whole length while
+        // their question sets said history was what they weighed.
         recent.push({ tool: String(event?.toolName ?? ""), outcome: event?.isError === true ? "error" : "ok" });
         if (recent.length > MAX_RECENT) {
             recent.shift();
@@ -868,16 +732,11 @@ export default function jevAdvisor(pi: ExtensionAPI) {
                               }
                           })()
                         : undefined;
-                    // The same disclosure `/jev on` makes, on the path that arms the guard by name.
-                    // Learning from a blocked call that calls can be blocked is the outcome that
-                    // rule exists to prevent, and which command did the arming does not change it.
-                    const armedGuard = action === "enable" && names.includes("guard") && settings.master;
                     ctx.ui.notify(
                         `${action === "enable" ? "Enabled" : "Disabled"}: ${names.join(", ")}.` +
                             `${kept ? " Remembered for new sessions." : " This session only."}` +
                             `${emptied ? " That was the last system, so the layer was switched off; it would otherwise run and do nothing." : ""}` +
-                            `${!emptied && !settings.master ? " The layer is still off; run /jev on." : ""}` +
-                            `${armedGuard ? `\n${guardWarning()}` : ""}`,
+                            `${!emptied && !settings.master ? " The layer is still off; run /jev on." : ""}`,
                         "info",
                     );
 
@@ -916,8 +775,7 @@ export default function jevAdvisor(pi: ExtensionAPI) {
                     const enabled = SYSTEM_NAMES.filter((name) => saved.systems[name]);
                     ctx.ui.notify(
                         saved.startup && saved.master
-                            ? `New Pi sessions will start with the Jev layer on, with ${enabled.length} of ${SYSTEM_NAMES.length} systems: ${enabled.join(", ")}. This session is unchanged; run /jev on to switch it on now.` +
-                                  `${saved.systems.guard ? `\n${guardWarning()}` : ""}`
+                            ? `New Pi sessions will start with the Jev layer on, with ${enabled.length} of ${SYSTEM_NAMES.length} systems: ${enabled.join(", ")}. This session is unchanged; run /jev on to switch it on now.`
                             : "New Pi sessions will start with the Jev layer off. This session is unchanged.",
                         "info",
                     );

package/extensions/jev-advisor/key-source.mjs

@@ -162,7 +162,7 @@ function environmentOnly() {
 
 /**
  * Jev is reached through OpenRouter by default: that is where it is published, it is what
- * the command guard uses, and an OpenRouter key (`sk-or-...`) is rejected by the direct
+ * specpi-jev-guard 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.
  *
  * It lives here rather than in client.mjs because everything below has to bind it. A parameter

package/extensions/jev-advisor/layer.mjs

@@ -18,8 +18,9 @@ import { SYSTEM_NAMES } from "./config.mjs";
  * Decide what a layer switch means, and report it honestly.
  *
  * `state` is `{ settings }` and is never mutated -- the next state comes back in the result. `deps`
- * supplies the outside world, which is now only `keySources`: the command guard used to need a
- * package's global configuration file arbitrated here, and as the eighth system it needs nothing.
+ * supplies the outside world, which is only `keySources`. The command guard is not arbitrated here
+ * and is not arbitrated anywhere in this extension: it is a separate package with its own switch,
+ * and nothing SpecPi does at session time touches it.
  *
  * Scope belongs to `layerScopeLine`, not here, so this takes `{ on }` and nothing else. It used to
  * be handed `sessionOnly` and `interactive` as well and read neither, which reads as a decision
@@ -39,34 +40,16 @@ export function applyLayer({ on }, state, deps) {
     return { settings, lines: onLines(state.settings, settings, active) };
 }
 
-/**
- * What arming the command guard means, in the words every path that arms it has to use.
- *
- * Seven of the eight systems only ever add advice; this one can refuse a tool call. Saying so is a
- * rule rather than a nicety, and it lives here because it was a rule `/jev on` honoured alone while
- * `/jev enable guard` and `/jev startup on` armed the same system in silence.
- */
-export function guardWarning() {
-    return (
-        "guard is the only system that can refuse a tool call: it blocks a call it reads as " +
-        "destructive and not what was asked for, asks you about the uncertain ones, and hands " +
-        "everything else to the permission system unchanged. Turn it off with /jev disable guard."
-    );
-}
-
 /**
  * Enabling the layer enables its systems, because a layer with none on runs and does nothing -- the
- * state people kept arriving at, with the notification cheerfully reporting "0 of 8".
+ * state people kept arriving at, with the notification cheerfully reporting "0 of 7".
  *
  * Only when none are on. Someone deliberately running retention alone has expressed a preference,
- * and `/jev off` then `/jev on` must not hand back the seven they turned off.
+ * and `/jev off` then `/jev on` must not hand back the six they turned off.
  *
- * The command guard is one of the eight, and it is the only system that can refuse a tool call. That
- * is a deliberate answer to a question this file and `config.mjs` resolve differently on purpose:
- * `/jev on` is a person acting now, so it arms everything and `onLines` says in as many words that
- * one of them can refuse a command; `migrateToThree` runs without anyone present, so it arms
- * nothing new. Silence is the difference -- an unattended migration must not change what a session
- * is allowed to run, and an explicit command that reports what it did may.
+ * Every system it arms only ever adds advice, which is what makes arming all of them a reasonable
+ * default and why this switch needs no warning attached. Nothing the layer can turn on is able to
+ * refuse a tool call; the one component that can is a separate package with a separate switch.
  */
 export function enableSystems(settings) {
     const chosen = SYSTEM_NAMES.filter((name) => settings.systems[name]);
@@ -86,12 +69,6 @@ function onLines(before, after, activeSource) {
         lines.push("No system was enabled, so all of them were. Turn any back off with /jev disable <system>.");
     }
 
-    // Said out loud every time, because seven of the eight only ever add advice and this one can
-    // take a command away. Nobody should discover that from a blocked call.
-    if (after.systems.guard) {
-        lines.push(guardWarning());
-    }
-
     lines.push(keyLine(activeSource));
 
     return lines;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpi",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Scope control and a human-selected harness improvement loop for Pi",
   "author": "Tanner Middleton",
   "repository": {
@@ -28,6 +28,7 @@
     "scripts/lib.mjs",
     "scripts/lock.mjs",
     "scripts/packages.mjs",
+        "scripts/jev-guard.mjs",
     "templates",
     "extensions",
     "skills",

package/scripts/jev-guard.mjs

@@ -0,0 +1,154 @@
+// Install-time seam for specpi-jev-guard, the Jev-scored command gate.
+//
+// The guard is pinned in the base set but ships **inert**. Its own `DEFAULT_SETTINGS.enabled` is
+// `true`, so leaving it alone would mean a fresh SpecPi install started gating shell and file calls
+// through a third-party service on day one. SpecPi writes `enabled: false` instead.
+//
+// That is the whole of SpecPi's involvement, and the file lives under `scripts/` to say so. The
+// guard is its own thing: it ships its own `/jev-guard setup | on | off [--global] | check | model
+// | backend`, keeps its own configuration, resolves its own key, and is not part of the Jev layer.
+// The advisor imports nothing from here, `/jev` does not mention it, and no switch in SpecPi turns
+// it on. One command does -- the package's own.
+//
+// Be precise about what this cannot do. The guard is fail-closed by design: with no key, an
+// unreachable endpoint, or an answer it cannot parse, the call does not go through, and in a
+// session with no UI its `uncertain` default blocks the middle band too. There is no setting that
+// hands the decision back to @gotgenes/pi-permission-system instead. So the honest posture is:
+//
+//   - off (what SpecPi installs) -> the guard is not in the tool path at all, and the permission
+//     system decides every call exactly as it did before this package existed;
+//   - on -> the guard decides first, asks a human in the middle band when there is a UI, and
+//     blocks when it cannot reach Jev. An outage stops gated work until it is switched off.
+//
+// That trade is the user's to make, which is why SpecPi only ever writes the off side of it.
+//
+// ONE KEY, and not one SpecPi supplies. Since 0.3.0 the package reads Pi's saved login first and
+// the environment second -- the same order the Jev advisor uses for the same provider entry -- so
+// `/login openrouter` serves both without either knowing about the other.
+//
+// `auditDisplay` is deliberately not asserted below, although SpecPi Chat renders the counter that
+// setting controls. It defaults to `status`, which is what publishes the line, and it is the user's
+// to change: pinning it here would take a display preference away from them to guarantee a readout
+// in one frontend. A session with it set to `off` simply shows no counter, which is what they
+// asked for.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { agentDirectory, regularFile, writeFileAtomic } from "../extensions/jev-advisor/config.mjs";
+
+export const GUARD_PACKAGE = "specpi-jev-guard";
+
+/** Must match the pin in templates/settings.json. */
+export const GUARD_PIN = "npm:specpi-jev-guard@0.4.0";
+
+// The guard reads `<homedir>/.pi/jev-guard.json` globally, and a project copy under `<cwd>/.pi/`
+// when the project is trusted. SpecPi writes only the global file: a project-local override is the
+// user's to make, and writing one would put a security setting inside whatever repository happened
+// to be open at the time.
+const CONFIG_DIR_NAME = ".pi";
+const SETTINGS_FILE = "jev-guard.json";
+
+function guardRoot() {
+    return path.join(agentDirectory(), "npm", "node_modules", GUARD_PACKAGE);
+}
+
+function guardConfigFile() {
+    return path.join(os.homedir(), CONFIG_DIR_NAME, SETTINGS_FILE);
+}
+
+export function installed() {
+    try {
+        const manifest = path.join(guardRoot(), "package.json");
+        if (!fs.existsSync(manifest)) {
+            return { installed: false };
+        }
+
+        const parsed = JSON.parse(fs.readFileSync(manifest, "utf8"));
+        if (parsed?.name !== GUARD_PACKAGE) {
+            return { installed: false };
+        }
+
+        return { installed: true, version: typeof parsed.version === "string" ? parsed.version : "unknown" };
+    } catch {
+        return { installed: false };
+    }
+}
+
+/**
+ * The fields SpecPi owns, in the guard's own schema. Anything absent here keeps the package's
+ * default, so its thresholds, command lists, protected paths and model settings stay its business.
+ *
+ * There is no `enabled: true` form of this, deliberately. SpecPi has no command that arms the
+ * guard, so a function that could produce an armed configuration would have no caller and one
+ * obvious wrong use.
+ */
+export function desiredConfig() {
+    return {
+        // Off means the guard never enters the tool path, so no key is needed and nothing is sent.
+        enabled: false,
+        // Left at the guard's own default, and asserted so the two halves of the Jev story resolve
+        // the same credential: one `/login openrouter` serves the advisor and the guard.
+        backend: "openrouter",
+        // With a UI, a middle-band verdict asks rather than deciding on its own. Without one the
+        // guard fails closed; that is the package's design, disclosed rather than configured away.
+        uncertain: "ask",
+    };
+}
+
+export function readConfig() {
+    try {
+        const file = guardConfigFile();
+        if (!regularFile(file, "Jev guard settings")) {
+            return undefined;
+        }
+
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Write the inert posture, merged into whatever is already there.
+ *
+ * Merged, not replaced: a user's own thresholds, safe-command globs and protected paths survive,
+ * and only the three fields above are asserted. Idempotent, and it reports what it changed so the
+ * installer can say so.
+ *
+ * It runs on install and on update, and it always asserts `enabled: false`. Not only when the file
+ * is absent, which is the version of this that looks safer and is not: an install carrying a stale
+ * `enabled: true` from before this package was last unpinned would arm a fail-closed gate the
+ * moment the package came back, with nobody present to be told. So the rule is the blunt one --
+ * SpecPi never leaves an armed gate behind an installer run -- and `disarmed` is returned so the
+ * run can report the one case where that took something away from someone.
+ *
+ * This is an occasional, human-initiated act, which is what makes the blunt rule affordable. It
+ * deliberately does not run at session start: the package owns its switch between installs, and a
+ * per-session rewrite would mean `/jev-guard on --global` never survived a restart.
+ */
+export function applyInertConfig() {
+    if (!installed().installed) {
+        return { applied: false, reason: "not-installed" };
+    }
+
+    const desired = desiredConfig();
+    const current = readConfig();
+    if (current && Object.entries(desired).every(([key, value]) => current[key] === value)) {
+        return { applied: false, reason: "already-current" };
+    }
+
+    writeFileAtomic(guardConfigFile(), `${JSON.stringify({ ...(current ?? {}), ...desired }, null, 4)}\n`);
+
+    return {
+        applied: true,
+        reason: current ? "updated" : "created",
+        // The one change worth announcing: everything else here is establishing a default, and this
+        // is switching off a gate a human had switched on.
+        disarmed: current?.enabled === true,
+    };
+}
+
+export function configPath() {
+    return guardConfigFile();
+}

package/scripts/packages.mjs

@@ -48,54 +48,6 @@ export function runBrowserQA(agentDir, command) {
     }
 }
 
-/**
- * Packages a past SpecPi version pinned and this one no longer does.
- *
- * Dropping an entry from `templates/settings.json` stops new installs getting it and does nothing at
- * all to a machine that already has it: the entry stays in `settings.json` and Pi keeps loading it.
- * That is tolerable for a package that merely stopped being useful, and not tolerable for
- * `specpi-jev-guard`, which fails closed -- an install left holding it after SpecPi deleted both the
- * code that kept it inert and the `/jev guard off` command that could disarm it would block every
- * shell call the moment its key or its endpoint went away, with nothing left to turn it off.
- *
- * So retirement is explicit, and it removes the entry rather than waiting for the restore path to.
- */
-export const retiredPackages = Object.freeze(["npm:specpi-jev-guard"]);
-
-/**
- * Drop retired entries from a settings object, in place, returning what was removed.
- *
- * Every entry goes, whatever shape it has. That is a deliberate exception to the ownership rule the
- * restore path applies elsewhere -- "a user-modified entry is theirs" -- and the exception is the
- * reason the list is not open to additions. Preserving a modified `specpi-jev-guard` entry preserved
- * a fail-closed gate that this release removed the controls for: the code that rewrote its global
- * configuration to `enabled: false` at every session start is gone, and so is `/jev guard off`, so a
- * preserved entry is a gate that refuses every shell call the moment its key or endpoint goes away,
- * with nothing left to turn it off. Filters are worth less than that.
- *
- * The removed entry is returned verbatim so the caller can print it back, and the write it belongs
- * to is inside the installer's transaction and backed up with everything else. Version is not
- * consulted: the reason for retirement is the package.
- */
-export function removeRetiredPackages(settings) {
-    if (!Array.isArray(settings?.packages)) {
-        return [];
-    }
-
-    const removed = [];
-    settings.packages = settings.packages.filter((entry) => {
-        if (!retiredPackages.includes(packageIdentity(entry))) {
-            return true;
-        }
-
-        removed.push(packageSource(entry));
-
-        return false;
-    });
-
-    return removed;
-}
-
 export function packageChanges(before, after) {
     return basePackages.map((source) => {
         const identity = packageIdentity(source);
@@ -182,14 +134,6 @@ export function installBasePackages(agentDir) {
 
 export function checkBasePackages(agentDir, settings) {
     const errors = [];
-    for (const entry of Array.isArray(settings.packages) ? settings.packages : []) {
-        if (retiredPackages.includes(packageIdentity(entry))) {
-            errors.push(
-                `Retired base package still configured: ${packageSource(entry)}. Run specpi update to unpin it.`,
-            );
-        }
-    }
-
     for (const source of basePackages) {
         const identity = packageIdentity(source);
         const entry =

package/scripts/specpi.mjs

@@ -22,14 +22,8 @@ import {
 import { validateCapabilityRegistry } from "../extensions/tool-wishlist/registry.mjs";
 import { runValidator } from "../extensions/tool-wishlist/validators.mjs";
 import { acquireSpecPiLock } from "./lock.mjs";
-import {
-    basePackages,
-    checkBasePackages,
-    installBasePackages,
-    packageChanges,
-    removeRetiredPackages,
-    runBrowserQA,
-} from "./packages.mjs";
+import { basePackages, checkBasePackages, installBasePackages, packageChanges, runBrowserQA } from "./packages.mjs";
+import { applyInertConfig as applyGuardConfig, configPath as guardConfigPath } from "./jev-guard.mjs";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const VERSION = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version;
@@ -63,8 +57,6 @@ const resourcePaths = [
     "extensions/jev-advisor/client.mjs",
     "extensions/jev-advisor/key-source.mjs",
     "extensions/jev-advisor/layer.mjs",
-    "extensions/jev-advisor/risk.mjs",
-    "extensions/jev-advisor/questions/guard.mjs",
     "extensions/jev-advisor/broker.mjs",
     "extensions/jev-advisor/gate.mjs",
     "extensions/jev-advisor/questions/retention.mjs",
@@ -87,7 +79,7 @@ Usage:
   specpi doctor
   specpi uninstall [--yes]
 
-Installs /scope, the harness improvement loop, and seven pinned packages.
+Installs /scope, the harness improvement loop, and eight pinned packages.
 The base is tested with Pi 0.84.4. Run specpi plan to see package versions.
 --skip-package-install installs only the core, or preserves an existing base on update.
 --skip-browser-install skips Chromium setup, not package acquisition or doctor checks.
@@ -260,32 +252,6 @@ function restoreLegacySettings(manifest, warnings) {
     writeJson(settingsPath, settings, existingMode(settingsPath, 0o600));
 }
 
-/**
- * Unpin a package a past version installed and this one has retired.
- *
- * Deliberately outside the `--skip-packages` guard. Skipping package acquisition means not
- * downloading or re-pinning anything, and it has never meant leaving an entry SpecPi itself wrote
- * pointing at code SpecPi has since removed the controls for -- `specpi-jev-guard` is fail-closed,
- * so the machine that skipped packages is exactly the machine that would keep it armed forever.
- *
- * `settingsPath` is in the transaction's watched set for every non-uninstall operation, so this
- * write is snapshotted, backed up and rolled back with everything else.
- */
-function retireBasePackages(warnings) {
-    const settings = readJson(settingsPath, {});
-    const removed = removeRetiredPackages(settings);
-    if (removed.length === 0) {
-        return;
-    }
-
-    writeJson(settingsPath, settings, existingMode(settingsPath, 0o600));
-    for (const source of removed) {
-        warnings.push(
-            `Unpinned retired package: ${source}. Its downloaded files stay in the agent npm directory, Pi no longer loads it, and any settings of your own on that entry are in this run's backup.`,
-        );
-    }
-}
-
 function removeLegacyShell(manifest) {
     if (manifest?.shellRc && fs.existsSync(manifest.shellRc)) {
         const result = removeManagedBlock(fs.readFileSync(manifest.shellRc, "utf8"), SHELL_START, SHELL_END);
@@ -340,16 +306,7 @@ async function mutate(options, operation) {
             ...files.map(([, target]) => target),
             ...Object.keys(previous?.files || {}),
         ];
-        // Watched whenever anything in this run can write it. `retireBasePackages` runs on every
-        // non-uninstall operation, including under `--skip-package-install`, so the narrower
-        // condition that used to guard this left that write outside the snapshot -- unbacked up, and
-        // not rolled back by a later failure in the same transaction.
-        if (
-            operation !== "uninstall" ||
-            !options.skipPackages ||
-            previous?.settingsChanges?.length ||
-            previous?.packageChanges?.length
-        ) {
+        if (!options.skipPackages || previous?.settingsChanges?.length || previous?.packageChanges?.length) {
             watched.push(settingsPath);
         }
 
@@ -370,10 +327,6 @@ async function mutate(options, operation) {
         const warnings = [];
         const preserveBase = operation !== "uninstall" && options.skipPackages && previous?.basePackages?.length;
         restoreLegacySettings(preserveBase ? { ...previous, packageChanges: [] } : previous, warnings);
-        if (operation !== "uninstall") {
-            retireBasePackages(warnings);
-        }
-
         removeLegacyShell(previous);
         let packageState = preserveBase
             ? {
@@ -402,6 +355,26 @@ async function mutate(options, operation) {
                 runBrowserQA(agentDir, "setup");
             }
 
+            // specpi-jev-guard's own default is enabled:true, so a freshly installed base would
+            // start gating shell and file calls through a third-party service before anyone asked
+            // for it — and with no key it fails closed, which means a first install that refuses to
+            // run commands. This is the only place SpecPi touches that package's configuration:
+            // between installer runs the guard's own /jev-guard commands own it, so the write does
+            // not repeat at session start and a saved `--global` choice survives every restart.
+            try {
+                const guard = applyGuardConfig();
+                if (guard.disarmed) {
+                    // The one case where establishing the default takes something away. An
+                    // installer run that silently switched off a gate the user had switched on is
+                    // exactly the kind of quiet security change this file refuses to make.
+                    warnings.push(
+                        `Switched the Jev command guard off in ${guardConfigPath()}. SpecPi installs it inert and asserts that on every install and update; run /jev-guard on --global in Pi to turn it back on.`,
+                    );
+                }
+            } catch (error) {
+                console.log(`SpecPi: could not write the Jev guard's inert settings: ${error.message}`);
+            }
+
             packageState = {
                 basePackages,
                 packagesKeyBeforeExists: Object.hasOwn(before, "packages"),

package/templates/settings.json

@@ -6,6 +6,7 @@
         "npm:specpi-experiments@0.1.0",
         "npm:pi-goal-x@0.31.2",
         "npm:@sreetej510/pi-usage@0.10.0",
-        "npm:@gotgenes/pi-permission-system@32.0.2"
+        "npm:@gotgenes/pi-permission-system@32.0.2",
+        "npm:specpi-jev-guard@0.4.0"
     ]
 }