specpi 0.26.0 → 0.28.0

package/extensions/jev-advisor/index.ts

@@ -0,0 +1,999 @@
+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 { 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";
+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.
+    let settings = loadSettings();
+    const broker = createBroker({ loadSettings: () => settings });
+    const recent: { tool: string; outcome: string }[] = [];
+    let objective = "";
+
+    // System 5's local state. Every field here is something the session already knows; it exists so
+    // that "ask local state first" has something to ask. Local state cannot answer whether a session
+    // is stuck, but it answers cheaply whether that question is worth 300ms and a call.
+    const HISTORY_WINDOW = 12;
+    const history = {
+        turn: 0,
+        signatures: [] as string[],
+        tools: [] as string[],
+        errors: [] as string[],
+        consecutiveErrors: 0,
+        turnsSinceChange: 0,
+        filesChanged: 0,
+        changedThisTurn: false,
+        nudged: false,
+        askedAtTurn: undefined as number | undefined,
+    };
+    const resetHistory = () => {
+        history.turn = 0;
+        history.signatures.length = 0;
+        history.tools.length = 0;
+        history.errors.length = 0;
+        history.consecutiveErrors = 0;
+        history.turnsSinceChange = 0;
+        history.filesChanged = 0;
+        history.changedThisTurn = false;
+        history.nudged = false;
+        history.askedAtTurn = undefined;
+    };
+
+    const enabled = (system: string) => settings.master && settings.systems[system] === true;
+
+    // System 6: decide once, before the first provider request, whether this session will need a
+    // withdrawn tool group -- and offer it now rather than at turn 6.
+    //
+    // Phase 7 is why this exists and why it is shaped like this. Flipping Browser QA on mid-session
+    // collapsed cached tokens to 3,200 at the next request in three attempts out of three and cost
+    // 20% of the attempt to re-warm; arming the same group from turn 1 cost 16% against 47%. The
+    // whole value here is moving one decision earlier, so it happens exactly once and only before
+    // the first request.
+    let capabilityAsked = false;
+    const capabilityDeclined = new Set<string>();
+
+    /** Persist the session's switches, or report that it could not be done. */
+    const persistLayer = (result: { settings: any }) => {
+        try {
+            return saveSettings(layerToPersist(result, loadSettings()));
+        } catch {
+            return undefined;
+        }
+    };
+
+    pi.on("session_start", () => {
+        settings = loadSettings();
+        if (!settings.startup) {
+            settings = { ...settings, master: false };
+        }
+
+        broker.reset();
+        recent.length = 0;
+        resetHistory();
+        capabilityAsked = false;
+        capabilityDeclined.clear();
+    });
+
+    pi.on("session_shutdown", () => {
+        // finish, not reset: the counts are published once more as an ended session so anything
+        // reading them from outside -- SpecPi Chat's panel, most of all -- shows what the session
+        // actually spent rather than a zeroed live one.
+        broker.finish();
+        recent.length = 0;
+        resetHistory();
+    });
+
+    pi.on("turn_start", (event: any) => {
+        history.turn = typeof event?.turnIndex === "number" ? event.turnIndex : history.turn + 1;
+        history.changedThisTurn = false;
+    });
+
+    // The task objective is the one piece of context every system wants, and it is already in the
+    // system prompt, so reading it here costs nothing extra.
+    pi.on("before_agent_start", (event: any) => {
+        const match = /\[SPECPI TASK CONTRACT\]\n([^\n]{0,200})/u.exec(event?.systemPrompt ?? "");
+        if (match) {
+            objective = match[1];
+        }
+    });
+
+    // Once per session, whatever the answer: asking later would be the mid-session flip the probe
+    // priced at three times the cost of doing it now.
+    pi.on("before_agent_start", async (event: any, ctx: ExtensionContext) => {
+        if (capabilityAsked || !enabled("capability")) {
+            return;
+        }
+
+        // No interactive human means no proposal at all, exactly as `request_capability` refuses
+        // without one. An unattended run must never be the thing that arms a capability.
+        if (!ctx.hasUI) {
+            return;
+        }
+
+        capabilityAsked = true;
+        try {
+            // Dynamically imported so the advisor never hard-depends on workflow-controls: a
+            // core-only install fails this import and the system degrades to off rather than
+            // taking the whole extension down with it.
+            const table = await import("../workflow-controls/capabilities.mjs");
+            const { syncActiveTools } = await import("../workflow-controls/web-access.mjs");
+            const active = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
+            const registered =
+                typeof pi.getAllTools === "function" ? pi.getAllTools().map((tool: any) => tool.name) : [];
+            // Only groups that are installed and withdrawn. Proposing one that is already on, or
+            // one whose package is absent, is a confirmation dialog that can only waste a person's
+            // attention.
+            const available = table.capabilityNames().filter((id: string) => {
+                const capability = table.findCapability(id);
+
+                return (
+                    capability &&
+                    table.capabilityInstalled(registered, capability) &&
+                    !table.capabilityActive(active, capability)
+                );
+            });
+            if (available.length === 0) {
+                return;
+            }
+
+            let entries: string[] = [];
+            try {
+                entries = fs.readdirSync(ctx.cwd ?? ".").slice(0, 200);
+            } catch {
+                entries = [];
+            }
+
+            const local = capabilities.localSignals({ prompt: event?.prompt, entries });
+            if (!local.ask) {
+                return;
+            }
+
+            const result = await broker.request({
+                system: "capability",
+                state: capabilities.buildInput({
+                    prompt: event?.prompt,
+                    reasons: local.reasons,
+                    available,
+                    cwdEntries: entries,
+                }),
+                questions: capabilities.questions({ available }),
+                ctx,
+                root: ctx.cwd,
+                decide: (answers: any) => {
+                    const advice = capabilities.decide(answers, available);
+
+                    return { applied: advice.propose.length > 0, decision: advice };
+                },
+            });
+            if (!result.ok) {
+                return;
+            }
+
+            const advice = result.decision;
+            if (advice.suggestDelegation) {
+                // A suggestion, never an activation: delegation binds a model and a host and has
+                // its own command, which is why the capability table deliberately omits it.
+                ctx.ui.notify(
+                    "Jev: this looks like a question a delegated read-only session could answer over many files. Run /delegate on if you want it.",
+                    "info",
+                );
+            }
+
+            for (const id of advice.propose) {
+                const capability = table.findCapability(id);
+                if (!capability || capabilityDeclined.has(id)) {
+                    continue;
+                }
+
+                const pending = table.missingTools(pi.getActiveTools(), capability);
+                // The same confirmation `request_capability` shows, pre-filled and moved to turn 0.
+                // Authority is unchanged: the human still decides, and declining is remembered so
+                // nothing asks twice in one session.
+                const accepted = await ctx.ui.confirm(
+                    `Allow ${capability.label} for this session?`,
+                    `Jev expects this request to ${capability.summary}, from the request itself rather than from anything it has done yet.\n\nThis offers ${pending.length} tool${pending.length === 1 ? "" : "s"} for the rest of this session and adds ${capability.schemaCost}. Accepting now is materially cheaper than accepting later: activating it mid-session also discards the cached prompt prefix, which measured about 20% of a mid-length attempt's cost. Withdraw it with ${capability.command} off.`,
+                );
+                if (!accepted) {
+                    capabilityDeclined.add(id);
+                    continue;
+                }
+
+                syncActiveTools(pi, capability.tools, true);
+            }
+        } catch {
+            // Nothing here may prevent a session from starting.
+        }
+    });
+
+    // 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) => {
+        // Bookkeeping first, and unconditionally. Retention's own eligibility gate returns early on
+        // most results, and a history that only recorded the large read-only ones would be blind to
+        // exactly the short repeated failures system 5 exists to notice.
+        if (event?.isError === true) {
+            history.consecutiveErrors += 1;
+            history.errors.push(retention.resultText(event).slice(0, 200));
+            if (history.errors.length > HISTORY_WINDOW) {
+                history.errors.shift();
+            }
+        } else {
+            history.consecutiveErrors = 0;
+            if (progress.MUTATING_TOOLS.has(event?.toolName)) {
+                history.filesChanged += 1;
+                history.changedThisTurn = true;
+            }
+        }
+
+        // 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.
+        recent.push({ tool: String(event?.toolName ?? ""), outcome: event?.isError === true ? "error" : "ok" });
+        if (recent.length > MAX_RECENT) {
+            recent.shift();
+        }
+
+        // Two systems share this hook. Retention wants large read-only results; system 7 wants
+        // externally fetched ones whatever their size, because an injected instruction can be two
+        // hundred bytes. When both want the same result they are one call: questions are evaluated
+        // in parallel against one state, so the second question rides the first's digest for
+        // nothing rather than paying for the same bytes twice at the same hook.
+        const wantRetention = enabled("retention") && retention.eligible(event);
+        const wantUntrusted = enabled("untrusted") && untrusted.applies(event);
+        if (!wantRetention && !wantUntrusted) {
+            return;
+        }
+
+        try {
+            const text = retention.resultText(event);
+            const bytes = retention.resultBytes(event);
+            const result = await broker.request({
+                // Charged to whichever system is driving, which is retention whenever retention is
+                // interested. System 7's own budget therefore only binds when retention is off or
+                // the result was too small for it.
+                system: wantRetention ? "retention" : "untrusted",
+                state: retention.buildInput({ event, objective, recent }),
+                questions: {
+                    ...(wantRetention ? retention.questions() : {}),
+                    ...(wantUntrusted ? untrusted.questions() : {}),
+                },
+                ctx,
+                root: ctx.cwd,
+                // The gate runs inside the call so the ledger line can say what the advice did
+                // rather than only that it was asked. The replacement text is built here too,
+                // because its length is the saving: computing it a second time to measure it would
+                // be the measurement inventing its own number.
+                decide: (answers: any) => {
+                    const verdict = wantRetention
+                        ? retention.decide(answers)
+                        : { elide: false, reason: "retention-off" };
+                    const flagged = wantUntrusted && untrusted.decide(answers).banner;
+                    // Order matters: shorten first, then mark. A banner belongs at the top of
+                    // whatever the model is actually going to read.
+                    const body = verdict.elide ? retention.digest(text, { tool: event.toolName, bytes }) : text;
+                    const replacement = flagged ? untrusted.mark(body) : body;
+
+                    return {
+                        applied: verdict.elide || flagged,
+                        savedBytes: verdict.elide ? bytes - Buffer.byteLength(replacement, "utf8") : 0,
+                        // retention.decide already names why it declined; carrying that into the
+                        // ledger is what makes "asked and did nothing" diagnosable later.
+                        reason: flagged ? `${verdict.reason}+flagged` : verdict.reason,
+                        decision: {
+                            verdict,
+                            flagged,
+                            replacement: verdict.elide || flagged ? replacement : undefined,
+                        },
+                    };
+                },
+            });
+            if (!result.ok) {
+                return;
+            }
+
+            const { verdict, replacement } = result.decision;
+            // Retention knows something the bookkeeping above does not -- whether the result was
+            // spent -- so it refines its own entry rather than appending a second one for the same
+            // call. If anything has been recorded since, the entry is gone and so is the chance.
+            const latest = recent[recent.length - 1];
+            if (wantRetention && latest?.tool === event.toolName) {
+                latest.outcome = verdict.elide ? "spent" : "kept";
+            }
+
+            if (replacement === undefined) {
+                return;
+            }
+
+            // Replace only the text parts. An image part carries no cheap digest and is left whole.
+            const images = (event.content ?? []).filter((part: any) => part?.type !== "text");
+
+            return { content: [{ type: "text" as const, text: replacement }, ...images] };
+        } catch {
+            // An advisor that throws must not fail the tool call that produced the result.
+            return;
+        }
+    });
+
+    // System 1b: steer the summary at the one boundary where the prompt cache is discarded anyway.
+    // Only customInstructions is supplied; the preparation's own cut and budget are left alone.
+    pi.on("session_before_compact", async (event: any, ctx: ExtensionContext) => {
+        if (!enabled("compaction")) {
+            return;
+        }
+
+        try {
+            const result = await broker.request({
+                system: "compaction",
+                state: compaction.buildInput({ preparation: event.preparation, objective }),
+                questions: compaction.questions(),
+                ctx,
+                root: ctx.cwd,
+                signal: event.signal,
+                decide: (answers: any) => {
+                    const built = compaction.decide(answers);
+
+                    // Nothing is shortened here, so savedBytes stays 0 and `applied` is the whole
+                    // record: either a sentence reached the summariser or Pi's own prompt ran.
+                    return { applied: Boolean(built.customInstructions), decision: built };
+                },
+            });
+            if (!result.ok) {
+                return;
+            }
+
+            const advice = result.decision;
+            if (!advice.customInstructions) {
+                return;
+            }
+
+            const existing = typeof event.customInstructions === "string" ? event.customInstructions.trim() : "";
+
+            return {
+                customInstructions: existing
+                    ? `${existing}\n\n${advice.customInstructions}`
+                    : advice.customInstructions,
+            };
+        } catch {
+            return;
+        }
+    });
+
+    // System 1b, second hook. Branch summarisation is the same problem at the same boundary --
+    // something is about to be reduced to a summary and the prefix is being rebuilt regardless --
+    // and it was simply unserved. It shares the compaction switch rather than adding a fifth
+    // system, because a user who has decided the advisor may steer a summary has decided that once.
+    //
+    // `label` is the part worth having. Pi's `/tree` can filter to labelled entries, so a branch
+    // that says what it was is the difference between a navigable tree and a list of timestamps,
+    // and the enum is fixed so no model-written text reaches the session file.
+    pi.on("session_before_tree", async (event: any, ctx: ExtensionContext) => {
+        if (!enabled("compaction")) {
+            return;
+        }
+
+        try {
+            const entries = event?.preparation?.entriesToSummarize ?? [];
+            if (entries.length === 0) {
+                return;
+            }
+
+            const result = await broker.request({
+                system: "compaction",
+                state: compaction.buildBranchInput({ preparation: event.preparation, objective }),
+                questions: compaction.questions({ branch: true }),
+                ctx,
+                root: ctx.cwd,
+                signal: event.signal,
+                decide: (answers: any) => {
+                    const built = compaction.decide(answers);
+                    const branchLabel = compaction.label(answers);
+
+                    return {
+                        applied: Boolean(branchLabel || built.customInstructions),
+                        decision: { ...built, label: branchLabel },
+                    };
+                },
+            });
+            if (!result.ok) {
+                return;
+            }
+
+            const advice = result.decision;
+            const patch: Record<string, unknown> = {};
+            if (advice.label) {
+                patch.label = advice.label;
+            }
+
+            // Only when a summary is actually going to be generated. Instructions for a summariser
+            // that will not run are bytes nobody reads, and `replaceInstructions` is left alone so
+            // Pi's own branch prompt still frames the result.
+            if (advice.customInstructions && event.preparation?.userWantsSummary === true) {
+                const existing =
+                    typeof event.preparation?.customInstructions === "string"
+                        ? event.preparation.customInstructions.trim()
+                        : "";
+                patch.customInstructions = existing
+                    ? `${existing}\n\n${advice.customInstructions}`
+                    : advice.customInstructions;
+            }
+
+            return Object.keys(patch).length > 0 ? patch : undefined;
+        } catch {
+            return;
+        }
+    });
+
+    pi.on("tool_call", async (event: any, ctx: ExtensionContext) => {
+        history.signatures.push(progress.signature(event.toolName, event.input));
+        history.tools.push(event.toolName);
+        if (history.signatures.length > HISTORY_WINDOW) {
+            history.signatures.shift();
+        }
+
+        if (history.tools.length > HISTORY_WINDOW) {
+            history.tools.shift();
+        }
+
+        // System 2: triage a capability gap before tool-wishlist writes it. `event.input` is
+        // documented as mutable, so this patches the report in place rather than duplicating any
+        // of the wishlist's authority logic. Nothing here records a decision.
+        if (event.toolName === "report_capability_gap" && enabled("gap")) {
+            try {
+                const result = await broker.request({
+                    system: "gap",
+                    state: gap.buildInput({ gap: event.input, existing: [] }),
+                    questions: gap.questions({ gap: event.input, existing: [] }),
+                    ctx,
+                    root: ctx.cwd,
+                    decide: (answers: any) => {
+                        const built = gap.decide(answers);
+                        // Exactly the conditions the caller applies below, so the ledger line says
+                        // what happened rather than what was available. A gated answer that
+                        // duplicates a field the model already filled in changed nothing.
+                        const changes =
+                            (built.blockForSanitization ? 1 : 0) +
+                            (built.canonicalKey && typeof event.input?.canonicalKey !== "string" ? 1 : 0) +
+                            (built.suggestedFix && !event.input?.suggestedFix ? 1 : 0) +
+                            (built.independentImpact ? 1 : 0);
+
+                        return { applied: changes > 0, decision: built };
+                    },
+                });
+                if (!result.ok) {
+                    return;
+                }
+
+                const advice = result.decision;
+                if (advice.blockForSanitization) {
+                    return {
+                        block: true,
+                        reason: "This report appears to contain a credential, an absolute path or other machine-specific detail. Rewrite it with the specifics removed and report it again.",
+                    };
+                }
+
+                if (advice.canonicalKey && typeof event.input?.canonicalKey !== "string") {
+                    event.input.canonicalKey = advice.canonicalKey;
+                }
+
+                if (advice.suggestedFix && !event.input?.suggestedFix) {
+                    event.input.suggestedFix = advice.suggestedFix;
+                }
+
+                // Recorded alongside the model's own claim, never over it: a human reading the
+                // wishlist should still see what was originally reported.
+                if (advice.independentImpact) {
+                    event.input.independentImpact = advice.independentImpact;
+                }
+            } catch {
+                return;
+            }
+
+            return;
+        }
+
+        // System 4: order the sources a delegation batch will snapshot. Ordering only — the same
+        // set is frozen either way, but a child pages through `list_sources` in this order.
+        if (event.toolName === "delegate" && enabled("sources") && Array.isArray(event.input?.sources)) {
+            try {
+                const candidates = event.input.sources
+                    .filter((item: unknown) => typeof item === "string")
+                    .map((item: string) => ({ path: item }));
+                if (candidates.length < 2) {
+                    return;
+                }
+
+                const result = await broker.request({
+                    system: "sources",
+                    state: sources.buildInput({ question: event.input?.question ?? objective, candidates }),
+                    questions: sources.questions({ candidates }),
+                    ctx,
+                    root: ctx.cwd,
+                    decide: (answers: any) => {
+                        const built = sources.decide(answers, candidates);
+                        const order = built.ordered.map((item: any) => item.path);
+                        // An ungated run returns the caller's own order, which is not a change and
+                        // must not be recorded as one.
+                        const moved = order.some((item: string, index: number) => item !== candidates[index]?.path);
+
+                        return { applied: moved, decision: { ranked: built, ordered: order } };
+                    },
+                });
+                if (!result.ok) {
+                    return;
+                }
+
+                const { ranked, ordered } = result.decision;
+                const missing = event.input.sources.filter((item: string) => !ordered.includes(item));
+                event.input.sources = [...ordered, ...missing];
+
+                // Two answers the same batch already computed and nothing read. Output is free, so
+                // they were paid for whether or not anyone looked. A confident "this is not a
+                // self-contained evidence question" is worth surfacing before specpi-delegation
+                // freezes up to 200 files and 8 MiB for a child that then cannot answer it.
+                //
+                // Advisory only, and deliberately so: the batch still runs, the ceilings are
+                // unchanged, and with no UI this says nothing rather than blocking.
+                if (ranked.notWorthDelegating && ctx.hasUI) {
+                    ctx.ui.notify(
+                        `Jev rates this a poor fit for delegation${ranked.jobMode ? ` (it reads as ${ranked.jobMode} work)` : ""}. Running anyway; ${ordered.length + missing.length} sources will be frozen for the child.`,
+                        "warning",
+                    );
+                }
+            } catch {
+                return;
+            }
+        }
+    });
+
+    // System 5: notice a session that has stopped making progress, while it can still be helped.
+    //
+    // THE ONE HANDLER THAT IS NOT AWAITED. Everything else in this file mutates what it inspects --
+    // a tool result, a compaction patch, a tool's input -- so the session has to wait for the
+    // answer. This one acts on the next turn, and at roughly 300ms a call, awaiting it on a
+    // thrashing session would add seconds to an attempt to deliver advice that could not have
+    // changed the turn it was asked during.
+    pi.on("turn_end", (event: any, ctx: ExtensionContext) => {
+        // Kept whether or not the system is on, so switching it on mid-session does not start from
+        // a blank history and immediately look healthy.
+        history.turnsSinceChange = history.changedThisTurn ? 0 : history.turnsSinceChange + 1;
+        if (!enabled("progress") || history.nudged) {
+            return;
+        }
+
+        const local = progress.suspicious(history);
+        if (!local.ask) {
+            return;
+        }
+
+        // Recorded before the call rather than after, so a slow answer cannot let the next turn ask
+        // again while this one is still in flight.
+        history.askedAtTurn = history.turn;
+        void (async () => {
+            try {
+                const result = await broker.request({
+                    system: "progress",
+                    state: progress.buildInput({ history, objective, reasons: local.reasons }),
+                    questions: progress.questions(),
+                    ctx,
+                    root: ctx.cwd,
+                    decide: (answers: any) => {
+                        const advice = progress.decide(answers);
+
+                        return {
+                            applied: Boolean(advice.nudge),
+                            reason: advice.nudge ? advice.mode : advice.stuck ? "stuck-but-mode-ungated" : "not-stuck",
+                            decision: advice,
+                        };
+                    },
+                });
+                if (!result.ok || !result.decision?.nudge) {
+                    return;
+                }
+
+                // Write-once, per the standing rule. A second nudge would either repeat a line the
+                // model already has or contradict it, and neither can be withdrawn: it was appended
+                // to a prefix that is cached behind it by the time anyone regrets it.
+                history.nudged = true;
+                if (ctx.hasUI) {
+                    ctx.ui.notify(
+                        result.decision.needsHuman
+                            ? `Jev progress check: this session looks blocked on something only you can answer. ${result.decision.nudge}`
+                            : `Jev progress check: ${result.decision.nudge}`,
+                        "warning",
+                    );
+                }
+
+                // The plan specified `deliverAs: "nextTurn"`, which is documented as "queued for
+                // next user prompt, does not interrupt or trigger anything". An unattended session
+                // has exactly one user prompt, so a nextTurn message would never be delivered -- in
+                // precisely the case the argument for this system rests on, a headless attempt
+                // burning its wall clock. "steer" is delivered after the current tool calls finish
+                // and before the next model request, which is the same append at the same boundary
+                // and is actually read. triggerTurn is left off so this can never add a turn.
+                // Suppressed when the session is blocked on something only a person can answer:
+                // steering a model past a missing credential costs a turn to say nothing.
+                if (
+                    settings.progressNudge === "message" &&
+                    !result.decision.needsHuman &&
+                    typeof pi.sendMessage === "function"
+                ) {
+                    pi.sendMessage(
+                        {
+                            customType: "specpi-jev-progress",
+                            content: result.decision.nudge,
+                            display: true,
+                            details: { mode: result.decision.mode, reasons: local.reasons },
+                        },
+                        { deliverAs: "steer" },
+                    );
+                }
+            } catch {
+                // The turn has already ended. An advisor must not be able to fail it retroactively.
+            }
+        })();
+    });
+
+    pi.registerCommand("jev", {
+        description: "Show or change the Jev advisor: master switch, per-system switches and the transmission ledger",
+        getArgumentCompletions: (prefix: string) =>
+            ["status", "on", "off", "startup", "enable", "disable", "ledger", "forget"]
+                .filter((value) => value.startsWith(prefix.trim().toLowerCase()))
+                .map((value) => ({ value, label: value })),
+        handler: async (args: string, ctx: ExtensionContext) => {
+            const [actionRaw = "status", ...rest] = args.trim().split(/\s+/u).filter(Boolean);
+            const action = actionRaw.toLowerCase();
+            try {
+                if (action === "on" || action === "off") {
+                    const on = action === "on";
+                    // `--session` is the old behaviour, kept for the case it was the right one: a
+                    // one-off try that must not change what the next session does.
+                    const sessionOnly = rest.some((value) => /^--?(session|once)$/u.test(value.toLowerCase()));
+                    const unknown = rest.filter((value) => !/^--?(session|once)$/u.test(value.toLowerCase()));
+                    if (unknown.length > 0) {
+                        throw new Error(`Usage: /jev ${action} [--session]`);
+                    }
+
+                    const result = applyLayer({ on }, { settings }, { keySources: () => keySources() });
+                    settings = result.settings;
+                    // Persisting is the default because a switch that forgets is not a switch. The
+                    // old rule -- that only /jev startup may write -- protected against a session
+                    // toggle silently changing tomorrow's sessions, but the cost of that protection
+                    // was a layer people turned on repeatedly and never actually ran.
+                    const persisted = !sessionOnly && ctx.hasUI ? persistLayer(result) : undefined;
+                    const lines = [
+                        ...result.lines,
+                        layerScopeLine({
+                            sessionOnly,
+                            interactive: ctx.hasUI,
+                            persisted,
+                            stored: loadSettings(),
+                            settingsFile: settingsPath(),
+                        }),
+                    ];
+                    ctx.ui.notify(lines.join("\n"), "info");
+
+                    return;
+                }
+
+                if (action === "enable" || action === "disable") {
+                    const names = rest.map((name) => name.toLowerCase());
+                    const unknown = names.filter((name) => !SYSTEM_NAMES.includes(name));
+                    if (names.length === 0 || unknown.length > 0) {
+                        throw new Error(`Usage: /jev ${action} <${SYSTEM_NAMES.join("|")}>`);
+                    }
+
+                    const changes = Object.fromEntries(names.map((name) => [name, action === "enable"]));
+                    const systems = { ...settings.systems, ...changes };
+                    // Disabling the last system while the layer is on leaves it running and doing
+                    // nothing -- the state `enableSystems`, `startupToPersist`, `couple` and the
+                    // Chat panel's save check all exist to prevent, reachable through the one path
+                    // that did not check it. Switching the layer off is the honest reading of
+                    // "disable everything", and it is announced rather than inferred.
+                    const emptied = settings.master && SYSTEM_NAMES.every((name) => !systems[name]);
+                    settings = { ...settings, systems, master: emptied ? false : settings.master };
+                    // Persisted like every other switch here, and merged into the stored map rather
+                    // than overwriting it: this session's copy may predate systems enabled on disk
+                    // since it started, and writing it whole turned those back off silently.
+                    const kept = ctx.hasUI
+                        ? (() => {
+                              try {
+                                  const current = loadSettings();
+                                  const merged = { ...current.systems, ...changes };
+                                  const dead = current.master && SYSTEM_NAMES.every((name) => !merged[name]);
+
+                                  return saveSettings({
+                                      ...current,
+                                      systems: merged,
+                                      master: dead ? false : current.master,
+                                      startup: dead ? false : current.startup,
+                                  });
+                              } catch {
+                                  return undefined;
+                              }
+                          })()
+                        : 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()}` : ""}`,
+                        "info",
+                    );
+
+                    return;
+                }
+
+                if (action === "startup") {
+                    const [choice] = rest;
+                    if (!choice) {
+                        const current = loadSettings();
+                        ctx.ui.notify(
+                            `Jev starts ${current.startup && current.master ? "on" : "off"} in new sessions. Preference: ${settingsPath()}`,
+                            "info",
+                        );
+
+                        return;
+                    }
+
+                    if (!ctx.hasUI) {
+                        throw new Error("Startup changes require a human interactive command");
+                    }
+
+                    if (!["on", "off"].includes(choice.toLowerCase())) {
+                        throw new Error("Usage: /jev startup [on|off]");
+                    }
+
+                    // Both keys, and the systems with them. Writing `startup` alone was the whole
+                    // two-keys-for-one-intention trap, left in the command named after it: the
+                    // advisor's session_start keeps a stored `master` only when `startup` is true,
+                    // so `startup: true, master: false` starts every future session with the layer
+                    // off while this command cheerfully reported it would start on. And a layer
+                    // that starts on with no system enabled runs and does nothing, so the same rule
+                    // `/jev on` uses applies here: fill them in only when none are chosen.
+                    const wanted = choice.toLowerCase() === "on";
+                    const saved = saveSettings(startupToPersist(wanted, loadSettings()));
+                    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 off. This session is unchanged.",
+                        "info",
+                    );
+
+                    return;
+                }
+
+                if (action === "forget") {
+                    if (!ctx.hasUI) {
+                        throw new Error("Revoking consent requires a human interactive command");
+                    }
+
+                    revokeConsent();
+                    ctx.ui.notify(
+                        "Forgot the Jev transmission consent. The next system that would send anything will ask again.",
+                        "info",
+                    );
+
+                    return;
+                }
+
+                if (action === "ledger") {
+                    const limit = Number.parseInt(rest[0] ?? "10", 10);
+                    const entries = readLedger(Number.isInteger(limit) ? limit : 10);
+                    if (entries.length === 0) {
+                        ctx.ui.notify(`No Jev transmissions recorded. Ledger: ${ledgerPath()}`, "info");
+
+                        return;
+                    }
+
+                    const lines = entries.map(
+                        (entry: any) =>
+                            `${entry.at} ${entry.system} ${entry.stateBytes}B ${entry.ok ? `${entry.latencyMs}ms` : entry.reason} ${String(entry.payloadSha256 ?? "").slice(0, 12)} [${(entry.questionKeys ?? []).join(", ")}]`,
+                    );
+                    ctx.ui.notify(`${lines.join("\n")}\n\nLedger: ${ledgerPath()}`, "info");
+
+                    return;
+                }
+
+                if (action !== "status") {
+                    throw new Error(
+                        "Usage: /jev [status|on [--session]|off [--session]|startup [on|off]|enable <system>|disable <system>|ledger [n]|forget]",
+                    );
+                }
+
+                const state = broker.status();
+                const sources = keySources();
+                const activeSource = sources.find((source: { present: boolean }) => source.present)?.name;
+                const stored = loadSettings();
+                const lines = [
+                    `master: ${settings.master ? "on" : "off"} (new sessions start ${stored.startup && stored.master ? "on" : "off"})`,
+                    ...SYSTEM_NAMES.map((name) => `  ${name}: ${settings.systems[name] ? "on" : "off"}`),
+                    // Every place a key could come from, in the order they are consulted, with the
+                    // one in force marked. A bare "missing" was actively misleading here: it is
+                    // what someone saw who had a perfectly good OpenRouter key stored by /login,
+                    // and it gave them nothing to act on. Names only -- no key is ever printed.
+                    `key: ${activeSource ? `in use from ${activeSource}` : "none found"}`,
+                    ...sources.map(
+                        (source: { name: string; label: string; detail: string; present: boolean }) =>
+                            `  ${source.present ? "found" : "   - "} ${source.label} (${source.detail})`,
+                    ),
+                    `consent: ${granted() ? "granted" : "not granted"}`,
+                    `calls this session: ${state.callsUsed}/${state.budgets.total} total`,
+                    ...SYSTEM_NAMES.map((name) => `  ${name}: ${state.usedBySystem[name] ?? 0}/${state.budgets[name]}`),
+                    `settings: ${settingsPath()}`,
+                    `consent file: ${consentPath()}`,
+                    `ledger: ${ledgerPath()}`,
+                    // Named here because it is the one file another process is meant to read, and
+                    // SpecPi Chat showing a number nobody can find is how a number stops being
+                    // checkable.
+                    `session counts: ${usagePath()}`,
+                ];
+                ctx.ui.notify(lines.join("\n"), "info");
+            } catch (error) {
+                ctx.ui.notify(safeMessage(error), "error");
+            }
+        },
+    });
+}