@yagni-app/code-staging 0.1.0-staging.997.1 → 0.2.0-staging.1025.1

package/dist/crashReport.js

@@ -0,0 +1,291 @@
+/**
+ * Crash reporting for the YAGNI Code launcher (and, via deep import, the
+ * desktop driver): a sanitized, fire-and-forget POST to the customer's own
+ * YAGNI backend at /api/yagni-code/crash. Deliberately no third-party
+ * telemetry SDK — crash reports are the ONLY thing this CLI phones home, they
+ * contain no code and no prompts, and `YAGNI_DISABLE_CRASH_REPORTS=1` turns
+ * them off entirely (same switch family as YAGNI_DISABLE_UPDATE_CHECK).
+ *
+ * Everything here is fail-soft: reporting never throws, never retries, never
+ * blocks longer than the short timeout, and never changes how the process
+ * would otherwise crash.
+ *
+ * The sanitizer core (scrub patterns + env-value redaction + path collapse +
+ * caps) is duplicated in `pi-extension-yagni/src/crashReport.ts` (the
+ * extension is bundled standalone and cannot import across packages) and
+ * re-run server-side in `backend/src/yagniCode/crashReports.ts`. Keep the
+ * three in sync. Spec:
+ * docs/superpowers/specs/2026-08-08-crash-reporting-design.md
+ */
+import { credentialsFromProfile, readActiveProfile } from "./profiles.js";
+export const CRASH_REPORT_DISABLE_ENV = "YAGNI_DISABLE_CRASH_REPORTS";
+export const CRASH_REPORT_TIMEOUT_MS = 1_500;
+/** Hard ceiling the process-exit path waits for a report before exiting. */
+export const CRASH_REPORT_EXIT_RACE_MS = 1_600;
+export const MAX_CRASH_MESSAGE = 512;
+export const MAX_CRASH_ERROR_CLASS = 128;
+export const MAX_CRASH_STACK = 8_000;
+export const MAX_CRASH_STACK_FRAMES = 40;
+/** If the serialized payload would exceed this, the stack is dropped. */
+export const MAX_CRASH_PAYLOAD_BYTES = 16_384;
+/** Same truthiness rule as updateChecksDisabled: set and not "" / "0". */
+export function crashReportsDisabled(env = process.env) {
+    const value = env[CRASH_REPORT_DISABLE_ENV];
+    return value !== undefined && value !== "" && value !== "0";
+}
+// Mirrors scrubSecrets (backend yagniCode/scrubSecrets.ts and
+// pi-extension-yagni pipeline/scrubSecrets.ts) — keep in sync.
+const SECRET_PATTERNS = [
+    [/\b([a-z][a-z0-9+.\-]*:\/\/[^\s:@/]+):[^\s:@/]+@/gi, "$1:[REDACTED]@"],
+    [/\b(sk-[A-Za-z0-9]{16,}|sk_(?:live|test)_[A-Za-z0-9]{16,}|rk_(?:live|test)_[A-Za-z0-9]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_\-]{20,})\b/g, "[REDACTED]"],
+    [/\b([A-Za-z0-9_]*(?:secret|password|passwd|api[_-]?key|token|private[_-]?key|access[_-]?key)[A-Za-z0-9_]*)\b(\s*[:=]\s*)("[^"]+"|'[^']+'|`[^`]+`|[^\s"']+)/gi, "$1$2[REDACTED]"],
+    [/\b[A-Za-z0-9+/]{40,}={0,2}\b/g, "[REDACTED]"],
+];
+const HOME_DIR_RE = /(?:\/(?:Users|home)\/|[A-Za-z]:\\Users\\)[^\s/\\]+/g;
+/**
+ * Absolute or ~-rooted path tokens (colon excluded so `file.ts:10:5` keeps its
+ * location). The lookbehind stops a mid-path slash from matching, so an
+ * already-relative path (`src/pipeline/run.ts` after the repo-root strip)
+ * survives intact instead of being re-collapsed at its inner slashes. Spaces
+ * are deliberately ALLOWED inside the token: real directories contain spaces
+ * ("~/Client Confidential Project/src/x.ts"), and a space-stopping class
+ * would leak every segment after the first space verbatim. The cost is that
+ * prose following a path can be folded into the kept basename — over-redacts
+ * rather than under-redacts.
+ */
+const PATH_TOKEN_RE = /(?<![\w.~/\\])(?:~\/|\/|[A-Za-z]:\\)[^\n():'",]+/g;
+/** Values too short to redact safely ("1", "true", "utf-8" would shred text). */
+const MIN_ENV_VALUE_LENGTH = 8;
+function isPathLikeValue(value) {
+    // Filesystem-path values (HOME, PWD, PATH, TMPDIR…) are handled — and more
+    // readably — by the path rules; replacing them here would break ~-collapse.
+    return value.startsWith("/") || value.startsWith("~") || /^[A-Za-z]:\\/.test(value);
+}
+function collapsePathToken(token) {
+    const nm = token.lastIndexOf("node_modules/");
+    if (nm >= 0)
+        return token.slice(nm);
+    const cut = Math.max(token.lastIndexOf("/"), token.lastIndexOf("\\"));
+    const base = cut >= 0 ? token.slice(cut + 1) : token;
+    return base.length > 0 ? base : token;
+}
+/**
+ * Sanitize one piece of crash text. Order matters:
+ *   1. env-value redaction (non-path values, length >= 8) → `[ENV:NAME]`
+ *   2. secret patterns (keys, connection strings, base64 blobs)
+ *   3. home-dir collapse to `~`
+ *   4. repo-root strip (repo files stay readable as relative paths)
+ *   5. every remaining absolute/`~` path → basename (node_modules kept from
+ *      `node_modules/` on, so dependency frames stay diagnosable)
+ * Over-redacts rather than under-redacts; pure; never throws.
+ */
+export function sanitizeCrashText(text, opts = {}) {
+    let out = text;
+    const env = opts.env ?? process.env;
+    const entries = Object.entries(env)
+        .filter((entry) => typeof entry[1] === "string" &&
+        entry[1].length >= MIN_ENV_VALUE_LENGTH &&
+        !isPathLikeValue(entry[1]))
+        // Longest first so a value containing another value cannot leave a tail.
+        .sort((a, b) => b[1].length - a[1].length);
+    for (const [name, value] of entries) {
+        if (out.includes(value))
+            out = out.split(value).join(`[ENV:${name}]`);
+    }
+    for (const [re, repl] of SECRET_PATTERNS)
+        out = out.replace(re, repl);
+    out = out.replace(HOME_DIR_RE, "~");
+    if (opts.repoRoot) {
+        const root = opts.repoRoot.replace(HOME_DIR_RE, "~").replace(/\/+$/, "");
+        if (root.length > 1)
+            out = out.split(`${root}/`).join("");
+    }
+    out = out.replace(PATH_TOKEN_RE, collapsePathToken);
+    return out;
+}
+/**
+ * Reduce an arbitrary thrown value to sanitized error facts. Reads ONLY
+ * `name`, `message`, and `stack` — custom fields (response bodies, request
+ * payloads…) are never touched.
+ */
+export function sanitizeCrashError(err, opts = {}) {
+    let errorClass = "Error";
+    let message;
+    let stack;
+    if (err instanceof Error) {
+        errorClass = err.name || "Error";
+        message = err.message;
+        stack = typeof err.stack === "string" ? err.stack : undefined;
+    }
+    else {
+        try {
+            message = String(err);
+        }
+        catch {
+            message = "unstringifiable thrown value";
+        }
+    }
+    const cappedStack = stack !== undefined
+        ? sanitizeCrashText(stack, opts)
+            .split("\n")
+            .slice(0, MAX_CRASH_STACK_FRAMES)
+            .join("\n")
+            .slice(0, MAX_CRASH_STACK)
+        : undefined;
+    return {
+        errorClass: sanitizeCrashText(errorClass, opts).slice(0, MAX_CRASH_ERROR_CLASS),
+        message: sanitizeCrashText(message, opts).slice(0, MAX_CRASH_MESSAGE),
+        ...(cappedStack !== undefined ? { stack: cappedStack } : {}),
+    };
+}
+/**
+ * Sanitize + POST one crash report from pre-extracted fields. Resolves on
+ * every outcome — timeout, network error, non-2xx, disabled — and never
+ * throws; there is nobody upstream who could act on a failure, and a
+ * reporting bug must never re-crash the process.
+ */
+export async function sendCrashReport(input) {
+    try {
+        const env = input.env ?? process.env;
+        if (crashReportsDisabled(env))
+            return;
+        const opts = { env, repoRoot: input.repoRoot };
+        const stack = input.stack !== undefined
+            ? sanitizeCrashText(input.stack, opts)
+                .split("\n")
+                .slice(0, MAX_CRASH_STACK_FRAMES)
+                .join("\n")
+                .slice(0, MAX_CRASH_STACK)
+            : undefined;
+        const payload = {
+            client: input.client,
+            clientVersion: input.clientVersion,
+            platform: `${process.platform} ${process.arch}`,
+            errorClass: sanitizeCrashText(input.errorClass, opts).slice(0, MAX_CRASH_ERROR_CLASS),
+            message: sanitizeCrashText(input.message, opts).slice(0, MAX_CRASH_MESSAGE),
+            ...(stack !== undefined ? { stack } : {}),
+            ...(input.context !== undefined ? { context: input.context } : {}),
+            timestamp: new Date().toISOString(),
+        };
+        if (JSON.stringify(payload).length > MAX_CRASH_PAYLOAD_BYTES) {
+            delete payload.stack;
+        }
+        const fetchImpl = input.fetchImpl ?? fetch;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), input.timeoutMs ?? CRASH_REPORT_TIMEOUT_MS);
+        timer.unref?.();
+        try {
+            await fetchImpl(`${input.baseUrl.replace(/\/$/, "")}/api/yagni-code/crash`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${input.token}`,
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        // fail-soft by contract
+    }
+}
+/**
+ * Fire one crash report from a live thrown value. Same never-throws contract
+ * as {@link sendCrashReport}, which does the sending.
+ */
+export async function reportCrash(input) {
+    try {
+        const env = input.env ?? process.env;
+        const sanitized = sanitizeCrashError(input.error, { env, repoRoot: input.repoRoot });
+        await sendCrashReport({
+            client: input.client,
+            clientVersion: input.clientVersion,
+            errorClass: sanitized.errorClass,
+            message: sanitized.message,
+            stack: sanitized.stack,
+            context: input.context,
+            baseUrl: input.baseUrl,
+            token: input.token,
+            env,
+            repoRoot: input.repoRoot,
+            fetchImpl: input.fetchImpl,
+            timeoutMs: input.timeoutMs,
+        });
+    }
+    catch {
+        // fail-soft by contract
+    }
+}
+async function resolveProfileTarget() {
+    try {
+        const profile = await readActiveProfile();
+        const creds = credentialsFromProfile(profile);
+        if (!creds?.token)
+            return null;
+        return { baseUrl: creds.baseUrl, token: creds.token };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The handler behind uncaughtException/unhandledRejection: report (bounded by
+ * `raceMs`), then preserve today's crash behavior — print the error to stderr
+ * and exit 1. Exposed for tests; `installProcessCrashHandlers` registers it.
+ */
+export function makeProcessCrashHandler(context, opts) {
+    const exit = opts.exit ?? ((code) => process.exit(code));
+    const writeStderr = opts.writeStderr ?? ((text) => process.stderr.write(text));
+    return (err) => {
+        void (async () => {
+            try {
+                const resolveTarget = opts.resolveTarget ?? resolveProfileTarget;
+                const target = await resolveTarget();
+                if (target) {
+                    // The race timer is deliberately ref'd: it guarantees the exit path
+                    // even if the fetch never settles.
+                    await Promise.race([
+                        reportCrash({
+                            client: opts.client,
+                            clientVersion: opts.clientVersion,
+                            error: err,
+                            context,
+                            baseUrl: target.baseUrl,
+                            token: target.token,
+                            env: opts.env,
+                            repoRoot: opts.repoRoot,
+                            fetchImpl: opts.fetchImpl,
+                        }),
+                        new Promise((resolve) => setTimeout(resolve, opts.raceMs ?? CRASH_REPORT_EXIT_RACE_MS)),
+                    ]);
+                }
+            }
+            catch {
+                // reporting must never re-crash the crash path
+            }
+            try {
+                const text = err instanceof Error ? (err.stack ?? err.message) : String(err);
+                writeStderr(`${text}\n`);
+            }
+            catch {
+                // even stderr can fail (EPIPE); still exit
+            }
+            exit(1);
+        })();
+    };
+}
+/**
+ * Install process-level crash reporting. Call once, before main() runs, from
+ * a process YAGNI owns (the launcher, the desktop driver) — never from inside
+ * pi's process, where adding these listeners would change crash semantics.
+ */
+export function installProcessCrashHandlers(opts) {
+    const proc = opts.proc ?? process;
+    proc.on("uncaughtException", makeProcessCrashHandler("uncaught-exception", opts));
+    proc.on("unhandledRejection", makeProcessCrashHandler("unhandled-rejection", opts));
+}
+//# sourceMappingURL=crashReport.js.map

package/dist/doctor.d.ts

@@ -60,6 +60,13 @@ export declare function checkCliUpdate(probe: {
     latest: string | null;
 }): CheckResult;
 export declare function checkGh(onPath: boolean): CheckResult;
+/** What the Windows bash probe found (pi needs a bash — Git Bash — on win32). */
+export interface BashProbe {
+    found: boolean;
+    /** The resolved bash path, when found. */
+    where?: string;
+}
+export declare function checkBash(probe: BashProbe): CheckResult;
 export interface DoctorReport {
     checks: CheckResult[];
     exitCode: number;
@@ -75,12 +82,26 @@ export interface DoctorDeps {
     probeBackend?: (baseUrl: string, token: string) => Promise<BackendProbe>;
     probeStateDir?: () => StateDirProbe;
     ghOnPath?: () => boolean;
+    /** Platform seam for the win32-only bash check (defaults to process.platform). */
+    platform?: NodeJS.Platform;
+    /** Windows bash probe; only ever called when the platform is win32. */
+    probeBash?: () => BashProbe;
     currentVersion?: string;
     probeLatestVersion?: () => Promise<string | null>;
     log?: (msg: string) => void;
 }
 /** Whether a `gh` executable is resolvable on PATH (no subprocess spawn). */
 export declare function ghOnPathDefault(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Locate the bash pi will actually use on Windows. The order and locations
+ * MIRROR pi 0.83's own shell resolution (dist/utils/shell.js) exactly:
+ * `%ProgramFiles%\Git\bin\bash.exe`, then `%ProgramFiles(x86)%\Git\bin\bash.exe`,
+ * then `bash.exe` on PATH (`where bash.exe`). Deliberately NOTHING wider — a
+ * per-user Git install in `%LOCALAPPDATA%` that is not on PATH is invisible
+ * to pi, and a doctor that reported it green would bless a machine where the
+ * first bash tool call throws. Pure function of env, like the gh probe.
+ */
+export declare function bashOnWindowsDefault(env?: NodeJS.ProcessEnv): BashProbe;
 /**
  * Gather every check result against the (injectable) probes. Pure ordering; each
  * individual check is a pure function of its probe.

package/dist/doctor.js

@@ -198,6 +198,24 @@ export function checkGh(onPath) {
         required: false,
     };
 }
+export function checkBash(probe) {
+    if (!probe.found) {
+        return {
+            name: "bash",
+            status: "fail",
+            detail: "no bash found (pi runs its shell commands through bash)",
+            hint: "Install Git for Windows — pi needs its bash: https://gitforwindows.org "
+                + "(a per-user install must also put bash.exe on PATH)",
+            required: true,
+        };
+    }
+    return {
+        name: "bash",
+        status: "ok",
+        detail: probe.where ? `found (${probe.where})` : "found",
+        required: true,
+    };
+}
 function toOctal(mode) {
     return `0${(mode & 0o777).toString(8).padStart(3, "0")}`;
 }
@@ -296,6 +314,32 @@ export function ghOnPathDefault(env = process.env) {
     }
     return false;
 }
+/**
+ * Locate the bash pi will actually use on Windows. The order and locations
+ * MIRROR pi 0.83's own shell resolution (dist/utils/shell.js) exactly:
+ * `%ProgramFiles%\Git\bin\bash.exe`, then `%ProgramFiles(x86)%\Git\bin\bash.exe`,
+ * then `bash.exe` on PATH (`where bash.exe`). Deliberately NOTHING wider — a
+ * per-user Git install in `%LOCALAPPDATA%` that is not on PATH is invisible
+ * to pi, and a doctor that reported it green would bless a machine where the
+ * first bash tool call throws. Pure function of env, like the gh probe.
+ */
+export function bashOnWindowsDefault(env = process.env) {
+    for (const root of [env.ProgramFiles, env["ProgramFiles(x86)"]]) {
+        if (!root)
+            continue;
+        const candidate = join(root, "Git", "bin", "bash.exe");
+        if (existsSync(candidate))
+            return { found: true, where: candidate };
+    }
+    for (const dir of (env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, "bash.exe");
+        if (existsSync(candidate))
+            return { found: true, where: candidate };
+    }
+    return { found: false };
+}
 /**
  * Gather every check result against the (injectable) probes. Pure ordering; each
  * individual check is a pure function of its probe.
@@ -308,10 +352,18 @@ export async function gatherChecks(deps = {}) {
     const probeBackend = deps.probeBackend ?? defaultProbeBackend;
     const probeStateDir = deps.probeStateDir ?? defaultProbeStateDir;
     const ghOnPath = deps.ghOnPath ?? (() => ghOnPathDefault());
+    const platform = deps.platform ?? process.platform;
+    const probeBash = deps.probeBash ?? (() => bashOnWindowsDefault());
     const probeLatestVersion = deps.probeLatestVersion ?? (() => fetchLatestVersion());
     const checks = [];
     checks.push(checkPiEngine(probePiEngine()));
     checks.push(checkExtension(probeExtension()));
+    // win32 only, and skipped means NOT SHOWN: on macOS/Linux there is nothing
+    // to say. pi shells out through bash, so a Windows machine without Git Bash
+    // cannot launch at all — a required red, like a missing engine.
+    if (platform === "win32") {
+        checks.push(checkBash(probeBash()));
+    }
     checks.push(checkCliUpdate({
         current: deps.currentVersion ?? currentCliVersion(),
         latest: await probeLatestVersion(),

package/dist/extension/askAdvisorTool.js

@@ -113,7 +113,13 @@ export function makeAskAdvisorTool(opts) {
                 content: [{ type: "text", text: "Consulting the advisor…" }],
                 details: { consults: opts.state.read().consults, cost: 0 },
             });
-            const result = await runStage(advisorStage(), { ticket: buildConsultBrief(params) }, { cwd: ctx?.cwd ?? process.cwd(), ...(signal ? { signal } : {}) });
+            const result = await runStage(advisorStage(), { ticket: buildConsultBrief(params) }, {
+                cwd: ctx?.cwd ?? process.cwd(),
+                ...(signal ? { signal } : {}),
+                // YAG-471: attribute the consult's completions to the advisor, not
+                // the "plan" stage id advisorStage() borrows (see its docblock).
+                callerLabel: "advisor",
+            });
             const cost = result.usage?.cost ?? 0;
             const state = opts.state.record(cost);
             if (result.exitCode !== 0 && !result.finalOutput.trim()) {

package/dist/extension/bless.js

@@ -17,6 +17,14 @@
  * one (and vice versa). Everything is pure except the in-memory rule list.
  */
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+/**
+ * Windows-only separator normalization so prefixes compare and display with
+ * `/` on every platform: pi's tools emit forward-slash paths even on Windows,
+ * and a rule keyed `C:\repo\src\api` would silently never match a call for
+ * `C:/repo/src/api/a.ts`. On POSIX this is the identity (a `\` there is a
+ * legal filename character, not a separator).
+ */
+const norm = sep === "\\" ? (p) => p.split("\\").join("/") : (p) => p;
 /** The file path a call targets, or null for path-less tools (bash). */
 export function blessPath(params) {
     const p = params.path;
@@ -25,7 +33,12 @@ export function blessPath(params) {
 /** Build a fresh, empty session bless store rooted at `cwd`. */
 export function makeBlessStore(cwd) {
     const rules = [];
-    const abs = (p) => (isAbsolute(p) ? p : resolve(cwd, p));
+    // Always THROUGH resolve, even for absolute inputs: on Windows a bare
+    // "/repo/…" is drive-relative and resolve() drive-qualifies it, so a rule
+    // minted from a relative path and a call carrying an absolute one land on
+    // the same canonical form. (For an already-absolute POSIX path this is just
+    // normalization.)
+    const abs = (p) => norm(resolve(cwd, p));
     /** Absolute directory prefix a bless of this call would cover, or null. */
     function prefixFor(params) {
         const p = blessPath(params);
@@ -41,7 +54,7 @@ export function makeBlessStore(cwd) {
             const prefix = prefixFor(params);
             if (prefix === null)
                 return null;
-            const rel = relative(cwd, prefix);
+            const rel = norm(relative(cwd, prefix));
             // Inside the tree → the relative dir (or "." for the repo root); outside →
             // the absolute path so the user sees exactly what they are blessing.
             if (rel === "")
@@ -64,7 +77,7 @@ export function makeBlessStore(cwd) {
             if (p === null)
                 return false; // path-less (bash) never auto-approves
             const target = abs(p);
-            return rules.some((r) => r.tool === tool && (target === r.prefix || target.startsWith(r.prefix + sep)));
+            return rules.some((r) => r.tool === tool && (target === r.prefix || target.startsWith(`${r.prefix}/`)));
         },
         rules() {
             return rules.slice();

package/dist/extension/boostCommand.d.ts

@@ -0,0 +1,144 @@
+/**
+ * `/boost` — the sanctioned session-scoped escalation to Peak (spec §7).
+ *
+ * The session default is the `balanced` tier. `/boost` flips the
+ * DRIVER session's live model to `peak` until `/boost off` or the process
+ * exits; `peak` stays directly pickable through pi's own model picker too,
+ * this just adds a one-word lever plus an attribution flag.
+ *
+ * Two halves, same split as `advisor.ts` / `permission.ts`:
+ *
+ *   - `boostOn` / `boostOff` are PURE. They own every transition and the exact
+ *     notice copy; no pi, no I/O, no env. That is what needs exhaustive tests.
+ *   - `registerBoostCommand` is the wiring: it applies the pure result's
+ *     `targetModelId` through pi's real model-switch API, toggles
+ *     `process.env.YAGNI_BOOST`, and paints the notice + a status-bar chip.
+ *
+ * The model-switch API (verified against pi 0.83.0's typings, not guessed):
+ * `ctx.modelRegistry.find(provider, modelId)` resolves a tier id to a
+ * `Model`, and `pi.setModel(model)` (the top-level `ExtensionAPI` method, NOT
+ * `ctx.setModel` — `ExtensionCommandContext` does not expose a setter) applies
+ * it to the live session, resolving `false` when no API key is configured.
+ * The `yagni` provider's catalog entries key `id` on the tier id itself (see
+ * `provider.ts`), so `peak` is the pi model id for the peak tier.
+ *
+ * State lives in the registration closure — module/session-scoped, mirroring
+ * `costHud.ts`'s accumulator — because a session's process exit is the only
+ * "end" there is; nothing needs to persist across it. `registerBoostCommand`
+ * returns a small `{ isBoosted() }` handle onto that same closure so other
+ * registrations (currently just `/cost`, see below) can read the live flag
+ * without a second source of truth.
+ *
+ * Picker-drift guard (spec review item 3): pi's OWN model picker (Ctrl+P,
+ * `/model`) can change the live model independently of `/boost` in either
+ * direction, so `state.active` can go stale relative to `ctx.model.id`. Both
+ * halves read the live model and reconcile rather than trusting `state.active`
+ * blindly:
+ *
+ *   - `boostOn` while already active but the live model has drifted OFF peak
+ *     (the user cycled models mid-boost without `/boost off`): re-applies
+ *     peak instead of a silent "Already boosted." that would leave the
+ *     driver quietly running a cheaper tier under an attribution header that
+ *     claims otherwise. The remembered `priorModelId` is left untouched — the
+ *     tier to restore is still whatever was active before the ORIGINAL boost,
+ *     not the tier the user happened to drift to.
+ *   - `boostOff` while active but the live model is no longer peak (same
+ *     drift, encountered from the other command): the user already left
+ *     boost manually, so forcing a switch back to the remembered prior tier
+ *     would clobber a choice they just made on purpose. Instead this clears
+ *     `/boost`'s own bookkeeping (state, env, chip) without touching the
+ *     model, and names where they actually landed.
+ *
+ * KNOWN asymmetry, documented rather than worked around: `YAGNI_BOOST=1`
+ * while boosted makes every CHILD process spawned during the boost (a /go
+ * run, a subagent, an advisor consult) inherit it, and those children's
+ * completions carry `x-yagni-boost` because their provider is registered
+ * fresh per child. The DRIVER's own completions do not gain that header
+ * retroactively — `buildYagniProvider`'s headers are baked into the
+ * `registerProvider` call once, at session start, from the env snapshot at
+ * that moment (see `provider.ts` / `attributionHeaders`). Re-registering the
+ * provider mid-session to pick up a new header is explicitly NOT the fix
+ * here: it would race the in-flight request the switch itself triggers and
+ * has no test coverage as a live-swap path.
+ *
+ * This is exactly why `/cost` cannot rely on server rows alone: the server's
+ * per-tier "Boosted (tier) spend" subtotal (`formatServerCostLines`, Task 7)
+ * only ever sees rows carrying `x-yagni-boost` — i.e. `/go` children, never
+ * the driver's own turns. A session that only chats while boosted would
+ * otherwise show no boost line at all. `registerCostCommand`'s `isBoosted`
+ * dep (threaded from THIS module's return handle, the same way
+ * `advisorSubtotal` is threaded from `advisor.ts`) closes that gap: `/cost`
+ * appends a fixed "Boost is on. Driver turns bill at the peak tier." line
+ * whenever the live toggle is on, on BOTH the server-authoritative and the
+ * local-fallback branch, independent of what server rows happen to show.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Session-scoped boost state, held in the registration closure. */
+export interface BoostState {
+    active: boolean;
+    /** The tier to restore on `/boost off`. Set only while `active`. */
+    priorModelId?: string;
+}
+/** The pure outcome of a `/boost` transition. */
+export interface BoostResult {
+    state: BoostState;
+    /** Exact notice text to surface to the user. */
+    notice: string;
+    /** The tier id to switch the session to, or undefined for a pure no-op. */
+    targetModelId?: string;
+}
+/**
+ * Turn boost on. PURE.
+ *
+ * - Already active AND the live model is still `peak`: genuine no-op,
+ *   "Already boosted." (no switch — nothing about the prior tier changes).
+ * - Already active but the live model has drifted off `peak` (picker-drift
+ *   guard 3b, see module docblock): re-applies `peak`, keeping the ORIGINAL
+ *   `priorModelId` rather than adopting the drifted-to tier.
+ * - Not active, current model IS already `peak`: activates anyway (so
+ *   attribution and `/boost off` behave correctly) with a distinct notice,
+ *   remembering `peak` itself as the tier to restore.
+ * - Not active, otherwise: remembers the current tier, targets `peak`.
+ */
+export declare function boostOn(state: BoostState, currentModelId: string | undefined): BoostResult;
+/**
+ * Turn boost off. PURE.
+ *
+ * - Not active: no-op, "Boost is not on."
+ * - Active but the live model is no longer `peak` (picker-drift guard 3a,
+ *   see module docblock): the user already left boost manually. Clears
+ *   `/boost`'s own bookkeeping WITHOUT a switch — forcing one back to the
+ *   remembered prior tier would clobber a choice just made on purpose — and
+ *   names the model they actually landed on.
+ * - Active and still on `peak`: restores the remembered prior tier (falling
+ *   back to the session default when none was recorded, which should not
+ *   normally happen). When the prior tier is itself `peak` (the
+ *   already-on-Peak activation path), the resulting switch is a no-op in
+ *   effect — still applied, harmlessly.
+ */
+export declare function boostOff(state: BoostState, currentModelId: string | undefined): BoostResult;
+/** Injectable seams for `registerBoostCommand`. */
+export interface RegisterBoostCommandDeps {
+    /** Environment `YAGNI_BOOST` is toggled on. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/** What `registerBoostCommand` hands back so other registrations (`/cost`) can read the live flag. */
+export interface BoostCommandHandle {
+    /** Whether the session is currently boosted, read fresh off the same closure `/boost` mutates. */
+    isBoosted(): boolean;
+}
+/**
+ * Register the `/boost` command.
+ *
+ * `/boost` (no args) turns boost on; `/boost off` turns it off; any other
+ * argument shows a usage notice and changes nothing. Every transition that
+ * requires a model switch runs it through pi's real API and is guarded end to
+ * end: state and `YAGNI_BOOST` are only ever committed together, AFTER the
+ * switch succeeds (or is deliberately skipped — the picker-drift guards), so
+ * a half-applied boost (env set but model unchanged, or vice versa) can never
+ * happen. A failed ON reports "Boost failed."; a failed OFF reports a
+ * DISTINCT message, because the failure mode is materially worse — the
+ * driver is left still running (and billing) on Peak, not merely unchanged.
+ */
+export declare function registerBoostCommand(pi: ExtensionAPI, deps?: RegisterBoostCommandDeps): BoostCommandHandle;
+//# sourceMappingURL=boostCommand.d.ts.map