@yagni-app/code 0.3.0 → 0.3.1

package/dist/extension/execPolicy.js

@@ -45,6 +45,11 @@
  * - `#` comments (start-of-word to end-of-line, outside quotes)
  * - Shell constructs we flag as unanalyzable: $(), backticks (INCLUDING
  *   inside double quotes — bash executes those), >, <, background &
+ * - Redirect metadata: stdout/stderr redirects carry fd + target so that
+ *   safe redirects (2>/dev/null, 2>&1) can be distinguished from unsafe ones
+ *   (> file.txt). Stdin redirects (<, <<) carry no metadata — they always
+ *   floor. Background & emits a distinct `background` op (not `semi`) so
+ *   hasUnhandledConstructs can always catch it.
  *
  * Does NOT handle: variable expansion, glob patterns, heredocs beyond the
  * redirect flag, nested subshells beyond depth tracking. Commands using
@@ -149,11 +154,13 @@ export function shellParse(command) {
                     i += 2;
                 }
                 else {
-                    // Single & — background operator. A construct (floor: prompt), but
-                    // the command before it must still be rule-matched: `rm -rf / &`
-                    // has to stay forbidden, so emit a separator rather than gluing.
+                    // Single & — background operator. Emits a distinct `background` op
+                    // (not `semi`) so hasUnhandledConstructs can always catch it and
+                    // floor the command. The command before it must still be rule-
+                    // matched: `rm -rf / &` has to stay forbidden, so emit a separator
+                    // rather than gluing.
                     pushCurrent();
-                    tokens.push({ op: "semi" });
+                    tokens.push({ op: "background" });
                     hasConstruct = true;
                     i++;
                 }
@@ -163,18 +170,124 @@ export function shellParse(command) {
                 tokens.push({ op: "semi" });
                 i++;
                 continue;
-            case ">":
-            case "<":
+            case ">": {
                 pushCurrent();
-                tokens.push({ op: "redirect" });
+                // Check for a preceding fd digit: `2>` → stderr, `1>` → stdout.
+                // The digit was emitted as a string token — pop it and use as fd.
+                let fd = "stdout";
+                if (tokens.length > 0 && typeof tokens[tokens.length - 1] === "string") {
+                    const last = tokens[tokens.length - 1];
+                    if (last === "2") {
+                        fd = "stderr";
+                        tokens.pop();
+                    }
+                    else if (last === "1") {
+                        fd = "stdout";
+                        tokens.pop();
+                    }
+                }
+                let append = false;
+                i++;
+                if (command[i] === ">") {
+                    append = true;
+                    i++;
+                }
+                while (command[i] === " " || command[i] === "\t")
+                    i++;
+                // Read the target — handles quoted targets (mirrors the main loop's
+                // quote logic), fd merges (&N), and bare words.
+                let target = "";
+                if (command[i] === "&") {
+                    // fd merge: &1, &2, etc.
+                    i++;
+                    let digits = "";
+                    while (command[i] >= "0" && command[i] <= "9") {
+                        digits += command[i];
+                        i++;
+                    }
+                    target = "&" + digits;
+                }
+                else if (command[i] === "'") {
+                    i++;
+                    while (i < command.length && command[i] !== "'") {
+                        target += command[i];
+                        i++;
+                    }
+                    if (i < command.length)
+                        i++;
+                }
+                else if (command[i] === '"') {
+                    i++;
+                    while (i < command.length && command[i] !== '"') {
+                        if (command[i] === "\\" && i + 1 < command.length) {
+                            target += command[i + 1];
+                            i += 2;
+                        }
+                        else {
+                            target += command[i];
+                            i++;
+                        }
+                    }
+                    if (i < command.length)
+                        i++;
+                }
+                else {
+                    while (i < command.length &&
+                        command[i] !== " " && command[i] !== "\t" &&
+                        command[i] !== "\n" && command[i] !== "\r" &&
+                        command[i] !== "|" && command[i] !== "&" &&
+                        command[i] !== ";" && command[i] !== ">" &&
+                        command[i] !== "<") {
+                        target += command[i];
+                        i++;
+                    }
+                }
+                tokens.push({ op: "redirect", direction: "out", fd, target, append });
                 hasConstruct = true;
-                // Skip the operator char(s) and any following space
+                continue;
+            }
+            case "<": {
+                pushCurrent();
+                // Stdin redirect — always floors (changes program behavior).
                 i++;
-                if (command[i] === ch)
-                    i++; // >> or <<
+                if (command[i] === "<")
+                    i++; // << heredoc — skip delimiter
                 while (command[i] === " " || command[i] === "\t")
                     i++;
+                // Consume the target (filename or heredoc delimiter) so it doesn't
+                // appear as a segment token — mirrors the > case's target reading.
+                if (command[i] === "'") {
+                    i++;
+                    while (i < command.length && command[i] !== "'")
+                        i++;
+                    if (i < command.length)
+                        i++;
+                }
+                else if (command[i] === '"') {
+                    i++;
+                    while (i < command.length && command[i] !== '"') {
+                        if (command[i] === "\\" && i + 1 < command.length)
+                            i += 2;
+                        else
+                            i++;
+                    }
+                    if (i < command.length)
+                        i++;
+                }
+                else {
+                    while (i < command.length &&
+                        command[i] !== " " && command[i] !== "\t" &&
+                        command[i] !== "\n" && command[i] !== "\r" &&
+                        command[i] !== "|" && command[i] !== "&" &&
+                        command[i] !== ";" && command[i] !== ">" &&
+                        command[i] !== "<") {
+                        i++;
+                    }
+                }
+                tokens.push({ op: "redirect", direction: "in" });
+                hasConstruct = true;
                 continue;
+            }
             case "$":
                 if (command[i + 1] === "(") {
                     pushCurrent();
@@ -213,9 +326,10 @@ export function shellParse(command) {
     }
     pushCurrent();
     // If we detected constructs but didn't emit them as operator tokens
-    // (e.g. background & or double-quoted substitution), surface that via a
-    // trailing substitution token so hasUnhandledConstructs sees it.
-    if (hasConstruct && !tokens.some((t) => typeof t === "object" && (t.op === "redirect" || t.op === "substitution"))) {
+    // (e.g. double-quoted substitution), surface that via a trailing
+    // substitution token so hasUnhandledConstructs sees it. Background & now
+    // emits its own distinct op, so it no longer relies on this fallback.
+    if (hasConstruct && !tokens.some((t) => typeof t === "object" && (t.op === "redirect" || t.op === "substitution" || t.op === "background"))) {
         tokens.push({ op: "substitution" });
     }
     return tokens;
@@ -294,47 +408,58 @@ const ENV_ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
 export function tokenize(command) {
     return shellParse(command).filter((t) => typeof t === "string");
 }
-/** Operator tokens we can safely split on (compound command segments). */
-const SPLIT_OPS = new Set(["pipe", "and", "or", "semi"]);
+/** Ops that split compound commands into segments (pipe, &&, ||, ;, background &). */
+const SPLIT_OPS = new Set(["pipe", "and", "or", "semi", "background"]);
+/** Ops that are safe splittable separators — they do NOT trigger the construct floor.
+ * Background & is in SPLIT_OPS (splits segments) but NOT here (always floors). */
+const SAFE_SPLIT_OPS = new Set(["pipe", "and", "or", "semi"]);
+/** A redirect to /dev/null (discard) or &N (fd merge) is safe — no file created. */
+function isSafeRedirect(t) {
+    if (typeof t === "string")
+        return false;
+    if (t.op !== "redirect")
+        return false;
+    if (t.direction === "in")
+        return false; // stdin redirect — always floor
+    if (t.target === "/dev/null")
+        return true; // discard stderr/stdout — safe
+    if (t.target.startsWith("&") && t.target.length > 1)
+        return true; // fd merge (2>&1, 1>&2) — safe; bare "&" (>& with no digit) is NOT safe
+    return false; // > file.txt, >> file.txt — unsafe
+}
 /**
  * Detect whether the command uses shell constructs we can't statically
- * classify (command substitution, redirects, background &) — anything that
- * is NOT a splittable operator. These impose a floor of `prompt`: a command
- * carrying them is never auto-allowed, but forbidden matches still win.
+ * classify (command substitution, unsafe redirects, background &) — anything
+ * that is NOT a safe splittable operator or a safe redirect. These impose a
+ * floor of `prompt`: a command carrying them is never auto-allowed, but
+ * forbidden matches still win.
  */
 function hasUnhandledConstructs(command) {
-    return shellParse(command).some((t) => typeof t === "object" && "op" in t && !SPLIT_OPS.has(t.op));
+    return shellParse(command).some((t) => typeof t === "object" && !SAFE_SPLIT_OPS.has(t.op) && !isSafeRedirect(t));
 }
 /**
  * Split a command into token-array segments at control operators (|, &&, ||,
- * ;, newline). Redirect targets (the token after > or <) are dropped from the
- * segment — they are filenames, not arguments to rule-match. Token arrays are
- * carried through (never re-joined into strings) so quoting survives.
+ * ;, newline, background &). Redirect targets are consumed inside the
+ * tokenizer's > / < cases (stored on the redirect op), so no skipNext logic
+ * is needed. Token arrays are carried through (never re-joined into strings)
+ * so quoting survives.
  */
 function splitSegmentsTokens(command) {
     const parsed = shellParse(command);
     const segments = [];
     let current = [];
-    let skipNext = false;
     for (const t of parsed) {
         if (typeof t === "object") {
             if (SPLIT_OPS.has(t.op)) {
                 if (current.length > 0)
                     segments.push(current);
                 current = [];
-                skipNext = false;
-            }
-            else if (t.op === "redirect") {
-                skipNext = true;
             }
-            // substitution ops are construct markers; the inner text is handled
-            // by dangerScan via extractSubstitutions.
+            // redirect and substitution ops are construct markers; their targets
+            // are consumed inside the tokenizer, and the inner text of $(...) is
+            // handled by dangerScan via extractSubstitutions.
         }
         else {
-            if (skipNext) {
-                skipNext = false;
-                continue;
-            }
             current.push(t);
         }
     }
@@ -510,6 +635,9 @@ function classifySegmentTokens(rawTokens, policy, opts) {
             const tailResult = classifySegmentTokens(tail, policy, { ...opts, depth: opts.depth + 1 });
             if (tailResult.decision === "forbidden")
                 return tailResult;
+            if (tailResult.decision === "allow" && !neverAllow) {
+                return { decision: "allow", justification: "xargs forwards to a read-only command" };
+            }
         }
         if (opts.forbiddenOnly)
             return { decision: "allow", justification: "no forbidden match" };
@@ -727,6 +855,7 @@ export const DEFAULT_EXEC_POLICY = {
         { pattern: ["jq"], decision: "allow", justification: "filter JSON to stdout" },
         { pattern: ["stat"], decision: "allow", justification: "show file metadata" },
         { pattern: ["file"], decision: "allow", justification: "identify file type" },
+        { pattern: ["strings"], decision: "allow", justification: "extract printable strings from binary files (read-only)" },
         { pattern: ["basename"], decision: "allow", justification: "strip directory from path" },
         { pattern: ["dirname"], decision: "allow", justification: "extract directory from path" },
         { pattern: ["realpath"], decision: "allow", justification: "resolve a path" },
@@ -760,7 +889,9 @@ export const DEFAULT_EXEC_POLICY = {
         { pattern: ["node", "--version"], decision: "allow", justification: "check node version" },
         { pattern: ["node", "-v"], decision: "allow", justification: "check node version" },
         { pattern: ["npm", "ls"], decision: "allow", justification: "list installed packages" },
+        { pattern: ["npm", "list"], decision: "allow", justification: "list installed packages" },
         { pattern: ["pnpm", "ls"], decision: "allow", justification: "list installed packages" },
+        { pattern: ["pnpm", "list"], decision: "allow", justification: "list installed packages" },
         { pattern: ["pnpm", "--version"], decision: "allow", justification: "check pnpm version" },
         { pattern: ["tsc", "--version"], decision: "allow", justification: "check typescript version" },
         // --- prompt: potentially destructive but context-dependent ---

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

@@ -41,6 +41,9 @@
 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.
@@ -102,7 +105,11 @@ export declare function renderFooterLines(input: {
  * and returns the component `setFooter` expects. Called from the
  * `session_start` handler in index.ts.
  */
-export declare function createYagniFooterFactory(ctx: ExtensionContext, modeHolder?: ModeHolder): (_tui: unknown, theme: Theme, footerData: ReadonlyFooterDataProvider) => {
+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;

package/dist/extension/footer.js

@@ -41,11 +41,20 @@
 import { spawnSync } from "node:child_process";
 import { statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+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;
 /**
@@ -107,10 +116,10 @@ export function collectUsage(sessionManager) {
     return totals;
 }
 /** End-cut ellipsis truncation (ANSI-aware) so the branch prefix stays readable. */
-function truncateEnd(text, maxWidth) {
+function truncateEnd(text, maxWidth, ellipsis = "…") {
     if (visibleWidth(text) <= maxWidth)
         return text;
-    return truncateToWidth(text, maxWidth, "…");
+    return truncateToWidth(text, maxWidth, ellipsis);
 }
 function runGit(args, cwd) {
     try {
@@ -193,15 +202,23 @@ export function detectGitInfo(cwd, home) {
     const worktree = resolveWorktreeLabel(root, branch);
     return { folder: basename(gitMainRepoRoot(root)), inRepo: true, branch, worktree };
 }
-/** Context color: dim below 70, warning 70-90, error above 90. */
+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 "dim";
+        return "success";
     if (percent > 90)
         return "error";
     if (percent > 70)
         return "warning";
-    return "dim";
+    return "success";
 }
 /** Pure line-builder, exported for tests. All data injected; colors via theme. */
 export function renderFooterLines(input, theme, width, padX = 0) {
@@ -218,7 +235,7 @@ export function renderFooterLines(input, theme, width, padX = 0) {
         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)));
+            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%
@@ -232,8 +249,10 @@ export function renderFooterLines(input, theme, width, padX = 0) {
     const stats = statParts.join(" ");
     const percentText = input.contextPercent === null ? "?" : `${Math.round(input.contextPercent)}%`;
     const line2Parts = [];
-    if (input.mode)
-        line2Parts.push(dim(`${input.mode} mode`));
+    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));
@@ -247,17 +266,8 @@ export function renderFooterLines(input, theme, width, padX = 0) {
     }
     return lines;
 }
-/**
- * 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 function createYagniFooterFactory(ctx, modeHolder) {
+export function createYagniFooterFactory(ctx, modeHolder, invalidateHandle) {
     return (_tui, theme, footerData) => {
-        // Recompute git/worktree info only when the branch actually changes. Optional-
-        // chained: onBranchChange is typed on ReadonlyFooterDataProvider, but the runtime
-        // provider is whatever pi version is installed — guard so a mismatch can't break
-        // footer construction (worst case, git info just doesn't auto-invalidate).
         let gitCache;
         const unsubscribeBranch = footerData.onBranchChange?.(() => {
             gitCache = undefined;
@@ -268,6 +278,10 @@ export function createYagniFooterFactory(ctx, modeHolder) {
             }
             return gitCache;
         };
+        if (invalidateHandle) {
+            invalidateHandle.invalidateGit = () => { gitCache = undefined; };
+            invalidateHandle.requestRender = () => { _tui?.requestRender?.(); };
+        }
         return {
             render(width) {
                 const statuses = [...footerData.getExtensionStatuses().entries()]

package/dist/extension/guardian.d.ts

@@ -37,7 +37,7 @@ export interface GuardianVerdict {
     rationale: string;
 }
 export interface GuardianLimits {
-    /** Session cap on total Guardian reviews. */
+    /** 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;
@@ -47,15 +47,25 @@ export interface GuardianLimits {
 export declare const DEFAULT_GUARDIAN_LIMITS: GuardianLimits;
 /**
  * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
- * overrides the session 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).
+ * 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;
 }
@@ -64,7 +74,7 @@ export interface GuardianStateHandle {
     recordReview(outcome: GuardianOutcome): GuardianState;
     resetTurn(): void;
 }
-export declare function makeGuardianState(): GuardianStateHandle;
+export declare function makeGuardianState(now?: () => number): GuardianStateHandle;
 export interface CircuitBreakerResult {
     tripped: boolean;
     reason?: string;

package/dist/extension/guardian.js

@@ -29,14 +29,15 @@
  */
 import { runStage as defaultRunStage } from "./pipeline/runner.js";
 export const DEFAULT_GUARDIAN_LIMITS = {
-    maxReviews: 30,
+    maxReviews: 120,
     maxConsecutiveDenials: 3,
     timeoutMs: 15_000,
 };
 /**
  * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
- * overrides the session 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).
+ * 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 function resolveGuardianLimits(env = process.env) {
     const raw = env.YAGNI_GUARDIAN_MAX_REVIEWS?.trim();
@@ -48,25 +49,48 @@ export function resolveGuardianLimits(env = process.env) {
 export const GUARDIAN_MODEL_TIER = "efficient";
 /** Read-only tools — the Guardian can read files for context but cannot write or execute. */
 export const GUARDIAN_TOOLS = ["read"];
-export function makeGuardianState() {
-    const state = { reviews: 0, consecutiveDenials: 0 };
+// --- State ---
+/**
+ * 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 const GUARDIAN_REVIEW_WINDOW_MS = 60 * 60_000;
+export function makeGuardianState(now = Date.now) {
+    const reviewTimes = [];
+    let consecutiveDenials = 0;
+    const prune = () => {
+        const cutoff = now() - GUARDIAN_REVIEW_WINDOW_MS;
+        while (reviewTimes.length > 0 && reviewTimes[0] <= cutoff)
+            reviewTimes.shift();
+    };
+    const snapshot = () => ({
+        reviews: reviewTimes.length,
+        consecutiveDenials,
+    });
     return {
-        read: () => ({ ...state }),
+        read: () => {
+            prune();
+            return snapshot();
+        },
         recordReview(outcome) {
-            state.reviews += 1;
+            prune();
+            reviewTimes.push(now());
             if (outcome === "deny") {
-                state.consecutiveDenials += 1;
+                consecutiveDenials += 1;
             }
             else if (outcome === "allow") {
-                state.consecutiveDenials = 0;
+                consecutiveDenials = 0;
             }
             // "ask" leaves the denial streak UNCHANGED: it is neither a denial nor
             // an exoneration. If it reset the streak, deny/ask/deny/ask would never
             // trip the breaker (round-2 review blocker).
-            return { ...state };
+            return snapshot();
         },
         resetTurn() {
-            state.consecutiveDenials = 0;
+            consecutiveDenials = 0;
         },
     };
 }