@yagni-app/code 0.1.0 → 0.2.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/credentials.js

@@ -5,6 +5,7 @@
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { DISTRIBUTION } from "./distribution.js";
 /**
  * Test seam: when set, all path resolution roots here instead of
  * `~/.yagni-code`, so tests can exercise profile/credential storage against a
@@ -16,7 +17,7 @@ export function _setYagniCodeHomeForTest(dir) {
     homeOverride = dir;
 }
 export function credentialsDir() {
-    return homeOverride ?? join(homedir(), ".yagni-code");
+    return homeOverride ?? join(homedir(), DISTRIBUTION.stateDirName);
 }
 export function credentialsPath() {
     return join(credentialsDir(), "credentials.json");

package/dist/distribution.d.ts

@@ -0,0 +1,15 @@
+export type DistributionChannel = "production" | "staging";
+export interface CodeDistribution {
+    channel: DistributionChannel;
+    packageName: string;
+    commandName: string;
+    displayName: string;
+    defaultBaseUrl: string;
+    defaultProfile: string;
+    stateDirName: string;
+    updateTag: "latest" | "staging";
+}
+export declare function distributionForPackageName(packageName: string): CodeDistribution;
+export declare function resolveDistribution(env?: NodeJS.ProcessEnv, packageName?: string): CodeDistribution;
+export declare const DISTRIBUTION: CodeDistribution;
+//# sourceMappingURL=distribution.d.ts.map

package/dist/distribution.js

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const PRODUCTION = {
+    channel: "production",
+    packageName: "@yagni-app/code",
+    commandName: "yagni",
+    displayName: "YAGNI Code",
+    defaultBaseUrl: "https://yagni.app",
+    defaultProfile: "prod",
+    stateDirName: ".yagni-code",
+    updateTag: "latest",
+};
+const STAGING = {
+    channel: "staging",
+    packageName: "@yagni-app/code-staging",
+    commandName: "yagni-staging",
+    displayName: "YAGNI Code Staging",
+    defaultBaseUrl: "https://yagni-staging.app",
+    defaultProfile: "staging",
+    stateDirName: ".yagni-code-staging",
+    updateTag: "staging",
+};
+export function distributionForPackageName(packageName) {
+    return packageName === STAGING.packageName ? { ...STAGING } : { ...PRODUCTION };
+}
+function installedPackageName() {
+    try {
+        const path = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed.name ?? PRODUCTION.packageName;
+    }
+    catch {
+        return PRODUCTION.packageName;
+    }
+}
+export function resolveDistribution(env = process.env, packageName = installedPackageName()) {
+    if (env.YAGNI_CODE_DISTRIBUTION === "staging")
+        return { ...STAGING };
+    if (env.YAGNI_CODE_DISTRIBUTION === "production")
+        return { ...PRODUCTION };
+    return distributionForPackageName(packageName);
+}
+export const DISTRIBUTION = resolveDistribution();
+//# sourceMappingURL=distribution.js.map

package/dist/doctor.d.ts

@@ -55,7 +55,18 @@ export declare function checkProfileToken(profile: Pick<Profile, "name" | "token
 export declare function checkTokenExpiry(status: TokenExpiryStatus): CheckResult;
 export declare function checkBackend(probe: BackendProbe): CheckResult;
 export declare function checkStateDir(probe: StateDirProbe): CheckResult;
+export declare function checkCliUpdate(probe: {
+    current: string;
+    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;
@@ -71,10 +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

@@ -15,6 +15,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { delimiter, join } from "node:path";
 import { credentialsDir } from "./credentials.js";
+import { currentCliVersion, fetchLatestVersion, isNewerVersion } from "./upgrade.js";
 import { classifyTokenExpiry } from "./launch.js";
 import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir } from "./paths.js";
 import { readActiveProfile } from "./profiles.js";
@@ -41,12 +42,12 @@ export function checkExtension(probe) {
         return {
             name: "extension",
             status: "fail",
-            detail: "pi-extension-yagni not built (dist/index.js missing)",
-            hint: "reinstall it: npm i -g @yagni-app/code (monorepo: pnpm --filter pi-extension-yagni build)",
+            detail: "YAGNI extension not found (dist/extension/index.js missing)",
+            hint: "reinstall it: npm i -g @yagni-app/code (monorepo: pnpm --filter @yagni-app/code build)",
             required: true,
         };
     }
-    return { name: "extension", status: "ok", detail: "pi-extension-yagni built", required: true };
+    return { name: "extension", status: "ok", detail: "YAGNI extension loaded", required: true };
 }
 export function checkProfileToken(profile) {
     if (!profile.token) {
@@ -160,6 +161,26 @@ export function checkStateDir(probe) {
     }
     return { name: "state dir", status: "ok", detail: `${probe.path} is 0700`, required: false };
 }
+export function checkCliUpdate(probe) {
+    if (probe.latest === null) {
+        return {
+            name: "cli version",
+            status: "ok",
+            detail: `v${probe.current} (update check unavailable)`,
+            required: false,
+        };
+    }
+    if (isNewerVersion(probe.current, probe.latest)) {
+        return {
+            name: "cli version",
+            status: "warn",
+            detail: `v${probe.current} — v${probe.latest} is available`,
+            hint: "run `yagni upgrade`",
+            required: false,
+        };
+    }
+    return { name: "cli version", status: "ok", detail: `v${probe.current} (latest)`, required: false };
+}
 export function checkGh(onPath) {
     if (onPath) {
         return {
@@ -177,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")}`;
 }
@@ -275,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.
@@ -287,9 +352,22 @@ 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(),
+    }));
     const profile = await readProfile();
     checks.push(checkProfileToken(profile));
     if (profile.token) {

package/dist/extension/advisor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The PURE half of the ask_advisor escalation (YAG-380).
+ *
+ * Balanced sessions drive on `advanced` and escalate hard judgment calls to
+ * `peak`. This module owns every decision about whether a consult may happen and
+ * what it cost; `askAdvisorTool.ts` owns the spawn. Same split as `permission.ts`
+ * (`decideGate` pure, wiring separate), for the same reason: the rules are what
+ * need exhaustive tests, and they must not require a child process to exercise.
+ *
+ * Two bounds, both necessarily POST-HOC. pi exposes no pre-emptive turn or token
+ * ceiling (see `pipeline/budget.ts`), so a consult's cost is only knowable once
+ * the child has exited:
+ *
+ *   - `maxConsults` is the real product bound. It makes escalation predictable
+ *     and priceable, which is the point of the cap.
+ *   - `maxSpend` is a RUNAWAY CATCH, not a budget — deliberately generous, in
+ *     the same spirit as `DEFAULT_RUN_BUDGET`. A thorough consult on a large
+ *     repo runs $0.40-$1.00, so a full 5-consult session lands near $2-$5 and
+ *     never approaches this. It exists only so an advisor stuck in a loop has
+ *     something to stop it.
+ *
+ * State is held in a closure via {@link makeAdvisorState}; no module-level
+ * mutable state, so two sessions in one process cannot bleed into each other.
+ */
+/** The session tier that may escalate. Balanced only, by design. */
+export declare const ADVISOR_TIER = "balanced";
+/** The tier a consult itself runs on. */
+export declare const ADVISOR_MODEL_TIER = "peak";
+/** Bounds on escalation within a single session. */
+export interface AdvisorLimits {
+    /** Hard cap on consults per session. */
+    maxConsults: number;
+    /** Runaway-catch ceiling on aggregate advisor spend, in the same unit as StageUsage.cost. */
+    maxSpend: number;
+}
+export declare const DEFAULT_ADVISOR_LIMITS: AdvisorLimits;
+/** Mutable per-session advisor accounting. */
+export interface AdvisorState {
+    consults: number;
+    spend: number;
+}
+/** A live session's advisor accounting, held in a closure. */
+export interface AdvisorStateHandle {
+    read(): AdvisorState;
+    /** Record a completed consult. Returns the state after recording. */
+    record(cost: number): AdvisorState;
+}
+export declare function makeAdvisorState(): AdvisorStateHandle;
+/** The outcome of the pre-consult gate. */
+export interface ConsultDecision {
+    allow: boolean;
+    /** Plain-text explanation when disallowed, surfaced to the model verbatim. */
+    reason?: string;
+}
+export interface ConsultGateInput {
+    /** The LIVE session model id (pi's picker can change this mid-session). */
+    model: string | undefined;
+    state: AdvisorState;
+    limits: AdvisorLimits;
+}
+/**
+ * Decide whether one consult may proceed. PURE.
+ *
+ * The tier check reads the model at CALL time rather than at registration time:
+ * tools register once at activation but pi's picker can switch the session model
+ * afterwards, so a registration-time check would both leave the tool live after
+ * switching away from Balanced and hide it forever from a session that switched
+ * to Balanced.
+ */
+export declare function decideConsult(input: ConsultGateInput): ConsultDecision;
+/**
+ * The line appended to a consult's advice so spend is visible at the moment it
+ * happens. `/cost` cannot see child processes at all (it accumulates off the
+ * parent's `turn_end`), so without this an advisor consult is invisible — see
+ * YAG-383 for the server-authoritative fix.
+ */
+export declare function formatConsultCost(input: {
+    cost: number;
+    consults: number;
+    limits: AdvisorLimits;
+}): string;
+/** The advisor subtotal line `/cost` appends when a session has escalated. */
+export declare function formatAdvisorSubtotal(state: AdvisorState, limits: AdvisorLimits): string;
+//# sourceMappingURL=advisor.d.ts.map