@yagni-app/code 0.3.0 → 0.3.2

package/dist/extension/crashReport.js

@@ -40,6 +40,39 @@ export function crashReportsDisabled(env = process.env) {
     const value = env[CRASH_REPORT_DISABLE_ENV];
     return value !== undefined && value !== "" && value !== "0";
 }
+/**
+ * True when this process is a test run.
+ *
+ * A crash reporter that phones home from a test suite reports FICTIONAL
+ * crashes against real production telemetry. That is not theoretical: the
+ * `/go` terminal catch builds a live reporter whenever its caller doesn't
+ * inject one, so `goCommand.test.ts`'s deliberate `throw new Error("boom")`
+ * POSTed to https://yagni.app on every run — 915 events across Sentry
+ * YAGNI-BACKEND-2P / -2Q, from a team that had never witnessed a crash.
+ *
+ * Injecting a stub at each call site fixes one test; this makes the whole
+ * class impossible, so a future test that forgets cannot re-open the leak.
+ * Detection is deliberately broad — a false positive costs one unreported
+ * crash on a developer machine, a false negative pollutes production.
+ */
+export function runningUnderTest(env = process.env) {
+    if (env.NODE_ENV === "test")
+        return true;
+    // node:test sets this in every spawned test-file process.
+    if (env.NODE_TEST_CONTEXT)
+        return true;
+    if (env.VITEST || env.JEST_WORKER_ID)
+        return true;
+    // npm/pnpm export the script name being run (`pnpm test`, `pnpm test:file`).
+    const script = env.npm_lifecycle_event;
+    if (script === "test" || (script !== undefined && script.startsWith("test:")))
+        return true;
+    return false;
+}
+/** Reporting is off when the user disabled it OR this is a test process. */
+export function crashReportsSuppressed(env = process.env) {
+    return crashReportsDisabled(env) || runningUnderTest(env);
+}
 const HOME_DIR_RE = /(?:\/(?:Users|home)\/|[A-Za-z]:\\Users\\)[^\s/\\]+/g;
 // Spaces deliberately allowed inside the token (real directories contain
 // them); prose after a path may fold into the kept basename — over-redacts
@@ -122,7 +155,7 @@ export function makeCrashReporter(opts) {
     return async (error, context, repoRoot) => {
         try {
             const env = opts.env ?? process.env;
-            if (crashReportsDisabled(env))
+            if (crashReportsSuppressed(env))
                 return;
             const token = opts.getToken();
             const sanitized = sanitizeCrashError(error, { env, repoRoot });
@@ -191,7 +224,7 @@ const DETACHED_SENDER_SRC = [
 export function reportFatalCrash(error, opts, context) {
     try {
         const env = opts.env ?? process.env;
-        if (crashReportsDisabled(env))
+        if (crashReportsSuppressed(env))
             return;
         const token = opts.getToken();
         if (!token)

package/dist/extension/execPolicy.d.ts

@@ -35,7 +35,18 @@
  * bundler), and external dependencies aren't resolvable from the bundled path.
  */
 export type TokenEntry = string | {
-    op: "pipe" | "and" | "or" | "semi" | "redirect" | "substitution";
+    op: "pipe" | "and" | "or" | "semi" | "substitution";
+} | {
+    op: "redirect";
+    direction: "out";
+    fd: "stdout" | "stderr";
+    target: string;
+    append: boolean;
+} | {
+    op: "redirect";
+    direction: "in";
+} | {
+    op: "background";
 };
 /**
  * Parse a shell command string into tokens and control operators.
@@ -48,6 +59,11 @@ export type TokenEntry = string | {
  * - `#` 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

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);
         }
     }
@@ -487,6 +612,16 @@ function classifySegmentTokens(rawTokens, policy, opts) {
     }
     const { tokens: strippedTokens, stripped } = stripLeadingTokens(rawTokens);
     if (strippedTokens.length === 0) {
+        // env standalone: `env` or `env VAR=val` with no following command prints
+        // environment variables — a read-only operation. stripLeadingTokens removes
+        // `env` as a wrapper word, leaving empty tokens. Recognize this case instead
+        // of returning "empty command segment" (YAG-549).
+        if (!opts.forbiddenOnly && rawTokens.length > 0 && basenameToken(rawTokens[0]) === "env") {
+            const onlyEnvAndAssignments = rawTokens.every((t) => basenameToken(t) === "env" || ENV_ASSIGNMENT_RE.test(t));
+            if (onlyEnvAndAssignments) {
+                return { decision: "allow", justification: "print environment variables (read-only)" };
+            }
+        }
         return opts.forbiddenOnly
             ? { decision: "allow", justification: "no forbidden match" }
             : { decision: "prompt", justification: "empty command segment" };
@@ -510,6 +645,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 +865,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,9 +899,64 @@ 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" },
+        // --- allow: CLI tool reads (YAG-549, based on prod Guardian data) ---
+        // linear CLI — read subcommands; write subcommands (create/update/delete/start/pr/attach/comment) stay prompt
+        { pattern: ["linear", "issue", "comment", "list"], decision: "allow", justification: "list Linear issue comments (read-only)" },
+        {
+            pattern: ["linear", "issue"],
+            decision: "allow",
+            justification: "read Linear issue data",
+            unlessTokens: ["start", "create", "update", "delete", "pull-request", "pr", "attach", "comment"],
+        },
+        { pattern: ["linear", ["--help", "-h"]], decision: "allow", justification: "show Linear CLI help" },
+        { pattern: ["linear", ["--version", "-V"]], decision: "allow", justification: "show Linear CLI version" },
+        // gh api — REST GET (no params, no method override) and GraphQL queries (no mutation)
+        // gh api defaults to POST when -f/-F params are present, so params are disqualifying.
+        // GraphQL is always POST, but queries are reads; mutations/subscriptions are disqualifying.
+        {
+            pattern: ["gh", "api", "graphql"],
+            decision: "allow",
+            justification: "GraphQL query (read-only)",
+            unlessTokens: ["query=mutation*", "query=subscription*"],
+        },
+        {
+            pattern: ["gh", "api"],
+            decision: "allow",
+            justification: "GitHub API GET request (read-only)",
+            unlessTokens: ["--method", "-X", "-X*", "graphql", "POST", "PATCH", "DELETE", "PUT", "-f", "-F", "--raw-field", "--field"],
+        },
+        { pattern: ["gh", "release", ["list", "view"]], decision: "allow", justification: "read GitHub release data" },
+        { pattern: ["gh", "label", "list"], decision: "allow", justification: "list GitHub labels" },
+        { pattern: ["gh", "milestone", "list"], decision: "allow", justification: "list GitHub milestones" },
+        { pattern: ["gh", "auth", "status"], decision: "allow", justification: "show GitHub auth status" },
+        // git read-only subcommands
+        { pattern: ["git", "tag"], decision: "allow", justification: "list tags (read-only)" },
+        { pattern: ["git", "reflog"], decision: "allow", justification: "show reference log" },
+        { pattern: ["git", "ls-remote"], decision: "allow", justification: "list remote refs" },
+        { pattern: ["git", "cat-file"], decision: "allow", justification: "inspect git objects (read-only)" },
+        { pattern: ["git", "for-each-ref"], decision: "allow", justification: "enumerate refs (read-only)" },
+        { pattern: ["git", "rev-list"], decision: "allow", justification: "walk commit history (read-only)" },
+        { pattern: ["git", "show-ref"], decision: "allow", justification: "list all refs" },
+        { pattern: ["git", "name-rev"], decision: "allow", justification: "map commit to name (read-only)" },
+        { pattern: ["git", "merge-base"], decision: "allow", justification: "find common ancestor (read-only)" },
+        // package manager test/lint — routine dev-loop operations
+        { pattern: ["pnpm", "test"], decision: "allow", justification: "run tests (routine dev-loop operation)" },
+        { pattern: ["pnpm", "lint"], decision: "allow", justification: "run linter (routine dev-loop operation)" },
+        { pattern: ["npm", "test"], decision: "allow", justification: "run tests (routine dev-loop operation)" },
+        { pattern: ["npm", "run", "lint"], decision: "allow", justification: "run linter (routine dev-loop operation)" },
+        { pattern: ["npx", "tsc", "--noEmit"], decision: "allow", justification: "typecheck only (no file writes)" },
+        { pattern: ["npx", "tsx", "--test"], decision: "allow", justification: "run tests (routine dev-loop operation)" },
+        { pattern: ["npx", "vitest"], decision: "allow", justification: "run vitest tests (routine dev-loop operation)" },
+        { pattern: ["npx", "vitest", "run"], decision: "allow", justification: "run vitest tests (routine dev-loop operation)" },
+        { pattern: ["npx", "jest"], decision: "allow", justification: "run jest tests (routine dev-loop operation)" },
+        // misc read-only commands
+        { pattern: ["printenv"], decision: "allow", justification: "print environment variables (read-only)" },
+        { pattern: ["npm", ["view", "info"]], decision: "allow", justification: "read package metadata from registry" },
         // --- prompt: potentially destructive but context-dependent ---
         { pattern: ["rm"], decision: "prompt", justification: "file deletion — review the target" },
         { pattern: ["git", "commit"], decision: "prompt", justification: "creates a commit — confirm intent" },

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;