@yagni-app/code 0.2.1 → 0.3.1

package/dist/extension/flywheel.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Session state for the miss-to-record flywheel (org plane, Run 7).
+ *
+ * When `ask_yagni` answers `no_position`, the server attaches a
+ * `recordSuggestion` telling the agent to bank the assumption it proceeds on.
+ * The extension owns two client-side guards the server cannot:
+ *
+ *  - **The per-run cap.** At most {@link FLYWHEEL_RUN_CAP} suggestions are
+ *    surfaced per session; past it the suggestion is suppressed so a busy
+ *    session cannot flood the ledger with asserted rows.
+ *  - **Dedupe attribution.** A `record_decision` call that answers the
+ *    QUESTION a surfaced suggestion asked about is a mid-run agent with no
+ *    human to adjudicate a near-duplicate, so it sends `dedupe: true` (the
+ *    backend then returns the existing row instead of inserting). The
+ *    attribution is correlated to the suggested question — an unrelated
+ *    record_decision (a different judgment the agent banks mid-run, or a
+ *    human `/decide`) never inherits the flag.
+ */
+/** Most flywheel suggestions surfaced per session. */
+export declare const FLYWHEEL_RUN_CAP = 3;
+export interface FlywheelState {
+    /** Suggestions surfaced so far this session. */
+    suggestionsShown: number;
+    /**
+     * The question of the most recent surfaced suggestion, until a matching
+     * record_decision consumes it. Only a record answering THIS question is
+     * flywheel-attributed (sends `dedupe: true`).
+     */
+    pendingQuestion: string | null;
+}
+export declare function makeFlywheelState(): FlywheelState;
+/** May another suggestion be surfaced? */
+export declare function canSurfaceSuggestion(state: FlywheelState): boolean;
+/** Record that a suggestion (asking about `question`) reached the model. */
+export declare function noteSuggestionSurfaced(state: FlywheelState, question: string): void;
+/**
+ * Consume the flywheel attribution for a record_decision call. Returns true
+ * (and clears the pending question) only when the recorded question matches
+ * the surfaced suggestion's; a mismatch leaves the attribution pending — the
+ * agent may record other judgments before circling back, and a fail-safe
+ * mismatch simply means a normal insert (no dedupe), never a swallowed write.
+ */
+export declare function consumeFlywheelAttribution(state: FlywheelState, recordedQuestion: string): boolean;
+//# sourceMappingURL=flywheel.d.ts.map

package/dist/extension/flywheel.js

@@ -0,0 +1,53 @@
+/**
+ * Session state for the miss-to-record flywheel (org plane, Run 7).
+ *
+ * When `ask_yagni` answers `no_position`, the server attaches a
+ * `recordSuggestion` telling the agent to bank the assumption it proceeds on.
+ * The extension owns two client-side guards the server cannot:
+ *
+ *  - **The per-run cap.** At most {@link FLYWHEEL_RUN_CAP} suggestions are
+ *    surfaced per session; past it the suggestion is suppressed so a busy
+ *    session cannot flood the ledger with asserted rows.
+ *  - **Dedupe attribution.** A `record_decision` call that answers the
+ *    QUESTION a surfaced suggestion asked about is a mid-run agent with no
+ *    human to adjudicate a near-duplicate, so it sends `dedupe: true` (the
+ *    backend then returns the existing row instead of inserting). The
+ *    attribution is correlated to the suggested question — an unrelated
+ *    record_decision (a different judgment the agent banks mid-run, or a
+ *    human `/decide`) never inherits the flag.
+ */
+/** Most flywheel suggestions surfaced per session. */
+export const FLYWHEEL_RUN_CAP = 3;
+export function makeFlywheelState() {
+    return { suggestionsShown: 0, pendingQuestion: null };
+}
+/** May another suggestion be surfaced? */
+export function canSurfaceSuggestion(state) {
+    return state.suggestionsShown < FLYWHEEL_RUN_CAP;
+}
+/** Loose textual identity: case- and whitespace-insensitive, terminal punctuation ignored. */
+function normalizeQuestion(question) {
+    return question.toLowerCase().replace(/\s+/g, " ").replace(/[.?!\s]+$/g, "").trim();
+}
+/** Record that a suggestion (asking about `question`) reached the model. */
+export function noteSuggestionSurfaced(state, question) {
+    state.suggestionsShown += 1;
+    state.pendingQuestion = question;
+}
+/**
+ * Consume the flywheel attribution for a record_decision call. Returns true
+ * (and clears the pending question) only when the recorded question matches
+ * the surfaced suggestion's; a mismatch leaves the attribution pending — the
+ * agent may record other judgments before circling back, and a fail-safe
+ * mismatch simply means a normal insert (no dedupe), never a swallowed write.
+ */
+export function consumeFlywheelAttribution(state, recordedQuestion) {
+    if (state.pendingQuestion === null)
+        return false;
+    if (normalizeQuestion(state.pendingQuestion) !== normalizeQuestion(recordedQuestion)) {
+        return false;
+    }
+    state.pendingQuestion = null;
+    return true;
+}
+//# sourceMappingURL=flywheel.js.map

package/dist/extension/footer.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Custom footer for the YAGNI CLI — replaces pi's built-in footer.
+ *
+ * Renders three lines:
+ *   1. folder  ·  [worktree]  ·  branch        (git context; ~-path fallback off-repo)
+ *   2. model  ·  ↑in ↓out $cost  ·  ctx%        (session stats; context % is an integer)
+ *   3. extension statuses                       (branding, todo counter, mode) joined by " · "
+ *
+ * --- How to customize the status bar (for future tickets) ---
+ *
+ * LIFECYCLE: `ctx.ui.setFooter()` is NOT available at extension factory time.
+ * The `pi` (ExtensionAPI) object passed to the factory has no UI methods —
+ * they live on `ctx.ui` (ExtensionUIContext), which is only bound after
+ * `_applyExtensionBindings` runs, immediately before the `session_start`
+ * event. So the footer must be set inside a `pi.on("session_start", ...)`
+ * handler, guarded by `ctx.mode === "tui"` (no footer in RPC/print mode).
+ * See index.ts's session_start handler for the wiring, and pi's
+ * `docs/extensions.md` § "Widgets, Status, and Footer" + the `custom-header.ts`
+ * example for the canonical pattern.
+ *
+ * FACTORY SIGNATURE: `setFooter((tui, theme, footerData) => Component)` where:
+ *   - `tui` — the TUI instance (screen dimensions, focus)
+ *   - `theme` — the current Theme (use `theme.fg("dim", text)` etc.)
+ *   - `footerData` — ReadonlyFooterDataProvider: `getGitBranch()`,
+ *     `getExtensionStatuses()` (statuses set via `ctx.ui.setStatus(key, text)`),
+ *     `getAvailableProviderCount()`
+ * Model info, token stats, and context usage are NOT on `footerData` — they're
+ * on `ctx` (the ExtensionContext passed to the session_start handler):
+ * `ctx.model`, `ctx.sessionManager`, `ctx.getContextUsage()`. Thread them
+ * through a closure if the footer needs them (this module's
+ * `createYagniFooterFactory` does exactly that).
+ *
+ * COMPONENT CONTRACT: the returned object needs `render(width: number): string[]`
+ * (returns the lines to display, one string per row) and `invalidate()` (called
+ * when the component should re-render). Optionally `dispose()` for cleanup.
+ *
+ * REFERENCE: pi's built-in footer lives at
+ * `node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js`
+ * — useful reference for what data to replicate and how to format it.
+ */
+import type { ExtensionContext, ReadonlyFooterDataProvider, Theme } from "@earendil-works/pi-coding-agent";
+import type { ModeHolder, PermissionMode } from "./permission.js";
+export declare const BRANCH_MAX_WIDTH = 60;
+export declare function cyclePermissionMode(current: PermissionMode): PermissionMode;
+export declare function isShiftTab(data: string): boolean;
+export declare const GIT_MUTATING_PATTERN: RegExp;
+/**
+ * Resolve the status bar's left pad from the launcher's `YAGNI_PAD_X` env so it
+ * aligns with the editor input and the chat/output area on one shared column.
+ * The launcher seeds the same value as pi's `editorPaddingX`; this footer can't
+ * read pi settings, so the value crosses over env. Falls back to the output
+ * area's default (1) when unset/invalid. Clamped to pi's 0–3 editor range.
+ */
+export declare function resolveFooterPadX(raw?: string | undefined): number;
+/** Format token counts for compact footer display (mirrors pi's formatTokens). */
+export declare function formatTokens(count: number): string;
+/** Shorten cwd relative to home, like pi's built-in footer. */
+export declare function formatCwd(cwd: string, home: string | undefined): string;
+interface UsageTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}
+/** Accumulate usage from all session entries (mirrors pi's built-in footer). */
+export declare function collectUsage(sessionManager: ExtensionContext["sessionManager"]): UsageTotals;
+export interface GitInfo {
+    /** Repo-root folder basename (the MAIN repo, stable across worktrees), or ~-path off-repo. */
+    folder: string;
+    inRepo: boolean;
+    /** Current branch, null off-repo. "detached" on detached HEAD. */
+    branch: string | null;
+    /** Linked-worktree label for [brackets], or null to hide. */
+    worktree: string | null;
+}
+/** Git probes `resolveWorktreeLabel` needs, injectable so the rules can be unit-tested. */
+export interface WorktreeProbes {
+    isLinkedWorktree(repoRoot: string): boolean;
+    worktrees(repoRoot: string): string[];
+}
+/**
+ * Show [worktree] only on a LINKED worktree (never the main checkout), when the repo has
+ * >1 worktree, AND the dir differs from the branch slug. The main checkout is the default
+ * context and earns no label; a [bracket] only disambiguates a secondary working tree.
+ */
+export declare function resolveWorktreeLabel(repoRoot: string, branch: string | null, probes?: WorktreeProbes): string | null;
+/**
+ * Detect git info for a cwd, gracefully. Never throws: non-git folders, missing git
+ * binary, and corrupt repos all degrade to a safe partial/empty result.
+ */
+export declare function detectGitInfo(cwd: string, home: string | undefined): GitInfo;
+/** Pure line-builder, exported for tests. All data injected; colors via theme. */
+export declare function renderFooterLines(input: {
+    git: GitInfo;
+    model: string;
+    /** Current permission mode; shown on line 2 to the left of the model as "<mode> mode". */
+    mode?: PermissionMode | null;
+    usage: UsageTotals;
+    contextPercent: number | null;
+    statuses: string[];
+}, theme: Pick<Theme, "fg">, width: number, padX?: number): string[];
+/**
+ * Create a footer factory that captures the session `ctx` (for session data)
+ * and returns the component `setFooter` expects. Called from the
+ * `session_start` handler in index.ts.
+ */
+export interface FooterInvalidateHandle {
+    invalidateGit(): void;
+    requestRender(): void;
+}
+export declare function createYagniFooterFactory(ctx: ExtensionContext, modeHolder?: ModeHolder, invalidateHandle?: FooterInvalidateHandle): (_tui: unknown, theme: Theme, footerData: ReadonlyFooterDataProvider) => {
+    render(width: number): string[];
+    invalidate(): void;
+    dispose(): void;
+};
+export {};
+//# sourceMappingURL=footer.d.ts.map

package/dist/extension/footer.js

@@ -0,0 +1,308 @@
+/**
+ * Custom footer for the YAGNI CLI — replaces pi's built-in footer.
+ *
+ * Renders three lines:
+ *   1. folder  ·  [worktree]  ·  branch        (git context; ~-path fallback off-repo)
+ *   2. model  ·  ↑in ↓out $cost  ·  ctx%        (session stats; context % is an integer)
+ *   3. extension statuses                       (branding, todo counter, mode) joined by " · "
+ *
+ * --- How to customize the status bar (for future tickets) ---
+ *
+ * LIFECYCLE: `ctx.ui.setFooter()` is NOT available at extension factory time.
+ * The `pi` (ExtensionAPI) object passed to the factory has no UI methods —
+ * they live on `ctx.ui` (ExtensionUIContext), which is only bound after
+ * `_applyExtensionBindings` runs, immediately before the `session_start`
+ * event. So the footer must be set inside a `pi.on("session_start", ...)`
+ * handler, guarded by `ctx.mode === "tui"` (no footer in RPC/print mode).
+ * See index.ts's session_start handler for the wiring, and pi's
+ * `docs/extensions.md` § "Widgets, Status, and Footer" + the `custom-header.ts`
+ * example for the canonical pattern.
+ *
+ * FACTORY SIGNATURE: `setFooter((tui, theme, footerData) => Component)` where:
+ *   - `tui` — the TUI instance (screen dimensions, focus)
+ *   - `theme` — the current Theme (use `theme.fg("dim", text)` etc.)
+ *   - `footerData` — ReadonlyFooterDataProvider: `getGitBranch()`,
+ *     `getExtensionStatuses()` (statuses set via `ctx.ui.setStatus(key, text)`),
+ *     `getAvailableProviderCount()`
+ * Model info, token stats, and context usage are NOT on `footerData` — they're
+ * on `ctx` (the ExtensionContext passed to the session_start handler):
+ * `ctx.model`, `ctx.sessionManager`, `ctx.getContextUsage()`. Thread them
+ * through a closure if the footer needs them (this module's
+ * `createYagniFooterFactory` does exactly that).
+ *
+ * COMPONENT CONTRACT: the returned object needs `render(width: number): string[]`
+ * (returns the lines to display, one string per row) and `invalidate()` (called
+ * when the component should re-render). Optionally `dispose()` for cleanup.
+ *
+ * REFERENCE: pi's built-in footer lives at
+ * `node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js`
+ * — useful reference for what data to replicate and how to format it.
+ */
+import { spawnSync } from "node:child_process";
+import { statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+export const BRANCH_MAX_WIDTH = 60;
+const WORKTREE_MAX_WIDTH = 30;
+/** Section separator: single space + middle dot + single space. */
+const SEP = " · ";
+const MODE_CYCLE = ["auto", "review", "plan"];
+export function cyclePermissionMode(current) {
+    const idx = MODE_CYCLE.indexOf(current);
+    return MODE_CYCLE[(idx + 1) % MODE_CYCLE.length];
+}
+export function isShiftTab(data) {
+    return matchesKey(data, "shift+tab");
+}
+export const GIT_MUTATING_PATTERN = /\bgit\s+(?:checkout|switch|branch|worktree|reset|restore|rebase|merge|cherry-pick|bisect)\b/;
+/** Default horizontal pad when the launcher didn't forward one (matches outputPad=1). */
+const DEFAULT_PAD_X = 1;
+/**
+ * Resolve the status bar's left pad from the launcher's `YAGNI_PAD_X` env so it
+ * aligns with the editor input and the chat/output area on one shared column.
+ * The launcher seeds the same value as pi's `editorPaddingX`; this footer can't
+ * read pi settings, so the value crosses over env. Falls back to the output
+ * area's default (1) when unset/invalid. Clamped to pi's 0–3 editor range.
+ */
+export function resolveFooterPadX(raw = process.env.YAGNI_PAD_X) {
+    const n = raw === undefined ? NaN : Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n >= 0 && n <= 3 ? n : DEFAULT_PAD_X;
+}
+/** Format token counts for compact footer display (mirrors pi's formatTokens). */
+export function formatTokens(count) {
+    if (count < 1000)
+        return count.toString();
+    if (count < 10000)
+        return `${(count / 1000).toFixed(1)}k`;
+    if (count < 1000000)
+        return `${Math.round(count / 1000)}k`;
+    if (count < 10000000)
+        return `${(count / 1000000).toFixed(1)}M`;
+    return `${Math.round(count / 1000000)}M`;
+}
+/** Shorten cwd relative to home, like pi's built-in footer. */
+export function formatCwd(cwd, home) {
+    if (!home)
+        return cwd;
+    const resolvedCwd = resolve(cwd);
+    const resolvedHome = resolve(home);
+    const rel = relative(resolvedHome, resolvedCwd);
+    const inside = rel === "" ||
+        (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+    return inside ? (rel === "" ? "~" : `~/${rel}`) : cwd;
+}
+/** Accumulate usage from all session entries (mirrors pi's built-in footer). */
+export function collectUsage(sessionManager) {
+    const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+    for (const entry of sessionManager.getEntries()) {
+        let u;
+        if (entry.type === "message" && entry.message.role === "assistant") {
+            u = entry.message.usage;
+        }
+        else if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.usage) {
+            u = entry.message.usage;
+        }
+        else if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
+            u = entry.usage;
+        }
+        if (u) {
+            totals.input += u.input;
+            totals.output += u.output;
+            totals.cacheRead += u.cacheRead;
+            totals.cacheWrite += u.cacheWrite;
+            totals.cost += u.cost.total;
+        }
+    }
+    return totals;
+}
+/** End-cut ellipsis truncation (ANSI-aware) so the branch prefix stays readable. */
+function truncateEnd(text, maxWidth, ellipsis = "…") {
+    if (visibleWidth(text) <= maxWidth)
+        return text;
+    return truncateToWidth(text, maxWidth, ellipsis);
+}
+function runGit(args, cwd) {
+    try {
+        const r = spawnSync("git", ["--no-optional-locks", ...args], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (r.error || r.status !== 0)
+            return null;
+        return r.stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+function gitRepoRoot(cwd) {
+    return runGit(["rev-parse", "--show-toplevel"], cwd) || null;
+}
+function gitBranch(repoRoot) {
+    const out = runGit(["symbolic-ref", "--quiet", "--short", "HEAD"], repoRoot);
+    if (out)
+        return out;
+    // Detached HEAD, or repo with no commits yet.
+    return runGit(["rev-parse", "--verify", "HEAD"], repoRoot) ? "detached" : null;
+}
+function gitWorktrees(repoRoot) {
+    const out = runGit(["worktree", "list", "--porcelain"], repoRoot);
+    if (!out)
+        return [];
+    return out
+        .split("\n")
+        .filter((l) => l.startsWith("worktree "))
+        .map((l) => l.slice("worktree ".length).trim())
+        .filter(Boolean);
+}
+/** The MAIN repository root (stable across worktrees) — used for the folder name. */
+function gitMainRepoRoot(repoRoot) {
+    const common = runGit(["rev-parse", "--git-common-dir"], repoRoot);
+    if (!common)
+        return repoRoot;
+    const abs = isAbsolute(common) ? common : join(repoRoot, common);
+    return basename(abs) === ".git" ? dirname(abs) : repoRoot;
+}
+/** Main checkout: .git is a directory. Linked worktree: .git is a "gitdir:" file. */
+function isLinkedWorktree(repoRoot) {
+    try {
+        return statSync(join(repoRoot, ".git")).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+const liveWorktreeProbes = { isLinkedWorktree, worktrees: gitWorktrees };
+/**
+ * Show [worktree] only on a LINKED worktree (never the main checkout), when the repo has
+ * >1 worktree, AND the dir differs from the branch slug. The main checkout is the default
+ * context and earns no label; a [bracket] only disambiguates a secondary working tree.
+ */
+export function resolveWorktreeLabel(repoRoot, branch, probes = liveWorktreeProbes) {
+    if (!probes.isLinkedWorktree(repoRoot))
+        return null;
+    if (probes.worktrees(repoRoot).length < 2)
+        return null;
+    const currentDir = basename(repoRoot);
+    if (branch && currentDir === branch)
+        return null;
+    return truncateEnd(currentDir, WORKTREE_MAX_WIDTH);
+}
+/**
+ * Detect git info for a cwd, gracefully. Never throws: non-git folders, missing git
+ * binary, and corrupt repos all degrade to a safe partial/empty result.
+ */
+export function detectGitInfo(cwd, home) {
+    const root = gitRepoRoot(cwd);
+    if (!root) {
+        return { folder: formatCwd(cwd, home), inRepo: false, branch: null, worktree: null };
+    }
+    const branch = gitBranch(root);
+    const worktree = resolveWorktreeLabel(root, branch);
+    return { folder: basename(gitMainRepoRoot(root)), inRepo: true, branch, worktree };
+}
+const MODE_DISPLAY = {
+    auto: { text: "⏵⏵ auto mode", color: "accent" },
+    review: { text: "✓ review mode", color: "warning" },
+    plan: { text: "⏸ plan mode", color: "success" },
+};
+function modeDisplay(mode) {
+    return MODE_DISPLAY[mode];
+}
+/** Context color: success below 70, warning 70-90, error above 90. */
+function contextColor(percent) {
+    if (percent === null)
+        return "success";
+    if (percent > 90)
+        return "error";
+    if (percent > 70)
+        return "warning";
+    return "success";
+}
+/** Pure line-builder, exported for tests. All data injected; colors via theme. */
+export function renderFooterLines(input, theme, width, padX = 0) {
+    const dim = (s) => theme.fg("dim", s);
+    const sep = dim(SEP);
+    // Reserve the left pad so the status bar's text starts on the same column as
+    // the (padded) editor input and the chat/output area, instead of hugging the
+    // terminal edge. Truncation runs against the reduced content width.
+    const pad = " ".repeat(Math.max(0, Math.min(3, Math.floor(padX))));
+    const contentWidth = Math.max(1, width - pad.length);
+    // Line 1: folder · [worktree] · branch
+    const line1Parts = [theme.fg("accent", input.git.folder)];
+    if (input.git.inRepo) {
+        if (input.git.worktree)
+            line1Parts.push(theme.fg("warning", `[${input.git.worktree}]`));
+        if (input.git.branch)
+            line1Parts.push(theme.fg("border", truncateEnd(input.git.branch, BRANCH_MAX_WIDTH, dim("…"))));
+    }
+    const line1 = pad + truncateToWidth(line1Parts.join(sep), contentWidth, dim("…"));
+    // Line 2: [mode ·] model · ↑in ↓out $cost · ctx%
+    const statParts = [];
+    if (input.usage.input)
+        statParts.push(`↑${formatTokens(input.usage.input)}`);
+    if (input.usage.output)
+        statParts.push(`↓${formatTokens(input.usage.output)}`);
+    if (input.usage.cost)
+        statParts.push(`$${input.usage.cost.toFixed(3)}`);
+    const stats = statParts.join(" ");
+    const percentText = input.contextPercent === null ? "?" : `${Math.round(input.contextPercent)}%`;
+    const line2Parts = [];
+    if (input.mode) {
+        const modeLabel = modeDisplay(input.mode);
+        line2Parts.push(theme.fg(modeLabel.color, modeLabel.text) + dim(" (shift+tab to change)"));
+    }
+    line2Parts.push(dim(input.model));
+    if (stats)
+        line2Parts.push(dim(stats));
+    line2Parts.push(theme.fg(contextColor(input.contextPercent), percentText));
+    const line2 = pad + truncateToWidth(line2Parts.join(sep), contentWidth, dim("…"));
+    // Line 3: extension statuses (branding, todo counter, mode), joined by " · ".
+    const statuses = input.statuses.map((s) => s.replace(/[\r\n\t]/g, " ").trim()).filter(Boolean);
+    const lines = [line1, line2];
+    if (statuses.length > 0) {
+        lines.push(pad + truncateToWidth(dim(statuses.join(SEP)), contentWidth, dim("…")));
+    }
+    return lines;
+}
+export function createYagniFooterFactory(ctx, modeHolder, invalidateHandle) {
+    return (_tui, theme, footerData) => {
+        let gitCache;
+        const unsubscribeBranch = footerData.onBranchChange?.(() => {
+            gitCache = undefined;
+        });
+        const gitInfo = () => {
+            if (!gitCache) {
+                gitCache = detectGitInfo(ctx.sessionManager.getCwd(), process.env.HOME || process.env.USERPROFILE);
+            }
+            return gitCache;
+        };
+        if (invalidateHandle) {
+            invalidateHandle.invalidateGit = () => { gitCache = undefined; };
+            invalidateHandle.requestRender = () => { _tui?.requestRender?.(); };
+        }
+        return {
+            render(width) {
+                const statuses = [...footerData.getExtensionStatuses().entries()]
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([, text]) => text);
+                return renderFooterLines({
+                    git: gitInfo(),
+                    model: ctx.model?.id ?? "no-model",
+                    mode: modeHolder?.get() ?? null,
+                    usage: collectUsage(ctx.sessionManager),
+                    contextPercent: ctx.getContextUsage()?.percent ?? null,
+                    statuses,
+                }, theme, width, resolveFooterPadX());
+            },
+            invalidate() {
+                gitCache = undefined;
+            },
+            dispose() {
+                unsubscribeBranch?.();
+            },
+        };
+    };
+}
+//# sourceMappingURL=footer.js.map

package/dist/extension/guardian.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The Guardian — LLM auto-review of prompt-band bash commands (YAG-504).
+ *
+ * Pure half: verdict types, state tracking, circuit breaker, JSON parsing.
+ * I/O half: reviewCommand spawns a locked-down child pi (same runStage seam
+ * the advisor uses) on the efficient tier with read-only tools and a risk
+ * policy persona. The child returns a JSON verdict; the gate acts on it.
+ *
+ * Same pure/IO split as advisor.ts (decideConsult pure, askAdvisorTool I/O)
+ * and permission.ts (decideGate pure, registerPermissionGate I/O), for the
+ * same reason: the rules are what need exhaustive tests, and they must not
+ * require a child process to exercise.
+ *
+ * Trigger: the exec policy classifies a bash command as "prompt" (not clearly
+ * safe, not clearly forbidden). The Guardian reviews it instead of interrupting
+ * the user. On allow, the command runs. On ask (YAG-510), the user arbitrates:
+ * the gate shows the Guardian's question-rationale and the user approves or
+ * declines. On deny, the agent sees the rationale and is told to find a safer
+ * alternative or ask the user. On timeout/error, auto mode falls back to an
+ * ask when a UI exists, else fails closed; review mode falls back to the
+ * ordinary user confirm.
+ *
+ * Circuit breaker: 3 consecutive denials within one user prompt → escalation
+ * (ask the user once) or, headless, interruption. Denial streaks reset on
+ * `before_agent_start`, which fires once per USER PROMPT (not per LLM turn).
+ * An `ask` outcome leaves the streak untouched — neither a denial nor an
+ * exoneration — so an ask-preferring model cannot disarm the breaker by
+ * alternating deny/ask.
+ */
+import { runStage as defaultRunStage } from "./pipeline/runner.js";
+import type { PipelineStage } from "./pipeline/types.js";
+export type GuardianOutcome = "allow" | "ask" | "deny";
+export type GuardianRiskLevel = "low" | "medium" | "high" | "critical";
+export interface GuardianVerdict {
+    outcome: GuardianOutcome;
+    riskLevel: GuardianRiskLevel;
+    rationale: string;
+}
+export interface GuardianLimits {
+    /** Cap on Guardian reviews within the sliding window ({@link GUARDIAN_REVIEW_WINDOW_MS}). */
+    maxReviews: number;
+    /** Consecutive denials per turn before the circuit breaker trips. */
+    maxConsecutiveDenials: number;
+    /** Hard timeout for the Guardian consult in ms. */
+    timeoutMs: number;
+}
+export declare const DEFAULT_GUARDIAN_LIMITS: GuardianLimits;
+/**
+ * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
+ * overrides the sliding-window review cap; anything non-numeric or < 1 falls
+ * back to the default (a bad value must never zero out the cap and lock the
+ * session).
+ */
+export declare function resolveGuardianLimits(env?: Record<string, string | undefined>): GuardianLimits;
+/** The model tier the Guardian runs on. Configurable via YAGNI_GUARDIAN_TIER. */
+export declare const GUARDIAN_MODEL_TIER = "efficient";
+/** Read-only tools — the Guardian can read files for context but cannot write or execute. */
+export declare const GUARDIAN_TOOLS: string[];
+/**
+ * The review-cap window. `reviews` counts consults inside a SLIDING window
+ * rather than for the session's lifetime: a 24/7 session (a fleet operator's
+ * always-on terminal) must regain review capacity as old consults age out,
+ * not hard-block forever after the first N. The cap is a cost/runaway bound,
+ * not a safety bound — safety is the verdicts themselves.
+ */
+export declare const GUARDIAN_REVIEW_WINDOW_MS: number;
+export interface GuardianState {
+    /** Guardian consults within the last {@link GUARDIAN_REVIEW_WINDOW_MS}. */
+    reviews: number;
+    consecutiveDenials: number;
+}
+export interface GuardianStateHandle {
+    read(): GuardianState;
+    recordReview(outcome: GuardianOutcome): GuardianState;
+    resetTurn(): void;
+}
+export declare function makeGuardianState(now?: () => number): GuardianStateHandle;
+export interface CircuitBreakerResult {
+    tripped: boolean;
+    reason?: string;
+}
+export declare function checkCircuitBreaker(state: GuardianState, limits: GuardianLimits): CircuitBreakerResult;
+export declare function parseVerdict(raw: string): GuardianVerdict | null;
+export declare function formatGuardianSubtotal(state: GuardianState, limits: GuardianLimits): string;
+export type GuardianError = "timeout" | "malformed" | "network" | "empty" | "aborted";
+export interface ReviewResult {
+    verdict: GuardianVerdict | null;
+    error?: GuardianError;
+    cost: number;
+}
+export interface ReviewCommandDeps {
+    runStage?: typeof defaultRunStage;
+    cwd: string;
+    signal?: AbortSignal;
+    /** Override the model tier (default: efficient). */
+    modelTier?: string;
+    /** Consult timeout in ms (default: DEFAULT_GUARDIAN_LIMITS.timeoutMs). */
+    timeoutMs?: number;
+    /**
+     * The exec policy's justification for routing this command to the Guardian
+     * ("pushes to remote — confirm intent"). Included in the consult prompt so
+     * an `ask` rationale can add information beyond the static rule text.
+     */
+    execJustification?: string;
+}
+/**
+ * The synthetic stage a Guardian consult runs as. Borrows the `plan` StageId
+ * (same pattern as the advisor) so it doesn't ripple into feed/reducers. The
+ * agent name selects the guardian persona from PERSONA_BODIES.
+ */
+export declare function guardianStage(modelTier?: string): PipelineStage;
+/**
+ * Run a Guardian consult: spawn a locked-down child pi with the risk policy
+ * persona and the command as the task. Parse the JSON verdict from the output.
+ * Returns { verdict, cost } on success, { verdict: null, error, cost } on failure.
+ */
+export declare function reviewCommand(command: string, deps: ReviewCommandDeps): Promise<ReviewResult>;
+export interface GuardianDiagnosticEvent {
+    event: "guardian_review";
+    outcome: GuardianOutcome | GuardianError;
+    durationMs?: number;
+    tier?: string;
+    /** Debug-only: command hash for correlation (never the raw command). */
+    commandHash?: string;
+    /** Debug-only: the Guardian's rationale. */
+    rationale?: string;
+}
+/**
+ * Create a sanitized diagnostic event. Never includes the raw command text
+ * (could contain secrets). YAGNI_DEBUG=1 adds rationale and a command hash.
+ */
+export declare function buildDiagnosticEvent(outcome: GuardianOutcome | GuardianError, opts: {
+    durationMs?: number;
+    tier?: string;
+    rationale?: string;
+    commandHash?: string;
+    debug?: boolean;
+}): GuardianDiagnosticEvent;
+//# sourceMappingURL=guardian.d.ts.map