@yagni-app/code-staging 0.3.0-staging.1093.1 → 0.3.0-staging.1098.1

package/dist/extension/askYagniTool.js

@@ -1,8 +1,21 @@
 import { Container, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { canSurfaceSuggestion, noteSuggestionSurfaced } from "./flywheel.js";
 import { collectRepoDocs } from "./repoDocs.js";
 import { friendlyFetchError, METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
 import { markdownOrPlain } from "./subagentRender.js";
+/** One line the TUI shows above the answer, per standing. */
+export const STANDING_LINES = {
+    confirmed: "Grounded in a confirmed decision",
+    asserted: "Grounded in a recorded assumption, not yet verified",
+    inferred: "Inferred from workspace context, not a recorded decision",
+    no_position: "No recorded position in this workspace",
+};
+function standingLine(value) {
+    return typeof value === "string" && value in STANDING_LINES
+        ? STANDING_LINES[value]
+        : undefined;
+}
 const parameters = Type.Object({
     question: Type.String(),
     context: Type.Optional(Type.String()),
@@ -40,6 +53,7 @@ export function makeAskYagniTool(opts) {
             "Call ask_yagni BEFORE guessing about anything organization- or codebase-specific (conventions, policies, architecture, ownership, product decisions).",
             "Pass the user's actual question; add relevant local context (file paths, snippets) in the optional `context` field.",
             "When you use an answer, quote or reference its citations so the user can verify the source.",
+            "Answers carry a standing: treat a confirmed decision as settled; when you lean on an unverified assumption or an inference, say so where the work is reviewed; when there is no recorded position, follow the answer's instruction to record the assumption you proceed on.",
         ],
         parameters,
         renderCall(args, theme) {
@@ -55,8 +69,11 @@ export function makeAskYagniTool(opts) {
             const citations = result.details?.citations ?? [];
             if (isPartial)
                 return new Text(t.fg("muted", answer || "Asking YAGNI…"), 0, 0);
+            const standing = standingLine(result.details?.standing);
             if (expanded) {
                 const container = new Container();
+                if (standing)
+                    container.addChild(new Text(t.fg("muted", standing), 0, 0));
                 container.addChild(markdownOrPlain(answer || "(no answer)", t));
                 if (citations.length > 0) {
                     container.addChild(new Spacer(1));
@@ -69,6 +86,8 @@ export function makeAskYagniTool(opts) {
             const lines = answer.trim().split("\n");
             const out = lines.slice(0, ANSWER_PREVIEW_LINES).map((l) => t.fg("toolOutput", l));
             const meta = [];
+            if (standing)
+                meta.push(standing);
             if (citations.length > 0)
                 meta.push(citationCount(citations.length));
             if (lines.length > ANSWER_PREVIEW_LINES || citations.length > 0)
@@ -95,6 +114,7 @@ export function makeAskYagniTool(opts) {
                     question: params.question,
                     context: params.context,
                     cwd: ctx?.cwd,
+                    ...(opts.getRepo?.() ? { repo: opts.getRepo() } : {}),
                     ...(repoDocs.length > 0 ? { repoDocs } : {}),
                 }),
             }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
@@ -102,9 +122,29 @@ export function makeAskYagniTool(opts) {
                 throw new Error(await friendlyFetchError("ask_yagni", res));
             }
             const data = (await res.json());
+            // Run 7 flywheel: a no-position answer carries the record-the-assumption
+            // instruction. It reaches the model VERBATIM inside the tool result, but
+            // only up to the per-session cap — past it a busy run stops being told
+            // to bank more asserted rows.
+            let text = data.answer;
+            const suggestion = data.recordSuggestion?.instruction;
+            if (suggestion && data.standing === "no_position") {
+                const state = opts.flywheel;
+                if (!state || canSurfaceSuggestion(state)) {
+                    // Attribution correlates to the QUESTION the suggestion asked
+                    // about, so only the record_decision that answers it inherits the
+                    // dedupe flag.
+                    if (state)
+                        noteSuggestionSurfaced(state, data.recordSuggestion?.question ?? params.question);
+                    text = `${text}\n\n${suggestion}`;
+                }
+            }
             return {
-                content: [{ type: "text", text: data.answer }],
-                details: { citations: data.citations ?? [] },
+                content: [{ type: "text", text }],
+                details: {
+                    citations: data.citations ?? [],
+                    ...(data.standing ? { standing: data.standing } : {}),
+                },
             };
         },
     };

package/dist/extension/config.d.ts

@@ -113,6 +113,12 @@ export interface ContextBrief {
         decisions: number;
         corrections: number;
     };
+    /**
+     * Active decisions scoped to the repo named on the request (additive, Run
+     * 7; absent without `?repo=`, on older backends, and on a count failure).
+     * The opt-in mining beat fires ONLY on an explicit 0.
+     */
+    repoDecisionCount?: number;
 }
 /**
  * Attribution headers for the model proxy (YAG-471). On the SERVER side these
@@ -192,6 +198,12 @@ export interface FetchContextBriefOptions {
     fetchImpl?: typeof fetch;
     /** Env seam for the telemetry headers; defaults to process.env. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * The session repo (`owner/name`), when resolvable. Rides as `?repo=` so
+     * the response can carry `repoDecisionCount` for the mining beat — no
+     * second round-trip at boot.
+     */
+    repo?: string;
 }
 /**
  * Fetch the workspace company brief at startup.

package/dist/extension/config.js

@@ -208,7 +208,8 @@ export function sessionTelemetryHeaders(env = process.env) {
  */
 export async function fetchContextBrief(opts) {
     try {
-        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context`, {
+        const query = opts.repo ? `?repo=${encodeURIComponent(opts.repo)}` : "";
+        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context${query}`, {
             method: "GET",
             headers: {
                 authorization: `Bearer ${opts.getToken() ?? ""}`,

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);
         }
     }
@@ -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/index.d.ts

@@ -5,6 +5,7 @@ import { fetchMcpServers as defaultFetchMcpServers } from "./mcpTools.js";
 import { type FlushOutcome, type SpoolClientOpts } from "./spool.js";
 import { type TokenProvider } from "./tokenProvider.js";
 import { type CatalogResult, type ContextBrief } from "./config.js";
+import { maybeOfferMiningBeat as defaultMaybeOfferMiningBeat, type MineBeatMarkers } from "./mineBeat.js";
 /**
  * YAGNI Code extension entry point.
  *
@@ -36,7 +37,21 @@ export interface RegisterYagniDeps {
         baseUrl: string;
         getToken: () => string | undefined;
         fetchImpl?: typeof fetch;
+        repo?: string;
     }) => Promise<ContextBrief | null>;
+    /**
+     * The session repo (`owner/name`), resolved from the origin remote before
+     * the boot brief fetch so `/context` can carry `repoDecisionCount` for the
+     * mining beat. Injectable (no git in tests); undefined outside a repo.
+     */
+    resolveRepoFullName?: (cwd: string) => string | undefined;
+    /**
+     * The opt-in seeding beat itself (Run 7). Injectable so tests assert it
+     * fires only on a startup with an explicitly-zero repo ledger.
+     */
+    offerMiningBeat?: typeof defaultMaybeOfferMiningBeat;
+    /** The beat's once-per-repo marker store. Injectable (no disk in tests). */
+    mineBeatMarkers?: MineBeatMarkers;
     /**
      * Workspace MCP server list seam (YAG-446). The default hits
      * `/api/yagni-code/mcp/servers` and is fail-soft: older backends and

package/dist/extension/index.js

@@ -41,6 +41,8 @@ import { makeAuthedFetch, makeTokenProvider } from "./tokenProvider.js";
 import { attributionHeaders, fetchCatalog as defaultFetchCatalog, fetchContextBrief as defaultFetchContextBrief, getToken, getTokenExpiresAt as defaultGetTokenExpiresAt, getWorkspaceId as defaultGetWorkspaceId, isDriverCaller, resolveBaseUrl, tokenExpiryNotice, } from "./config.js";
 import { buildYagniProvider } from "./provider.js";
 import { registerChipEditor } from "./chipEditor.js";
+import { defaultMineBeatGit, fileMineBeatMarkers, maybeOfferMiningBeat as defaultMaybeOfferMiningBeat, } from "./mineBeat.js";
+import { makeFlywheelState } from "./flywheel.js";
 function isEvalMode(env = process.env) {
     return env.YAGNI_CODE_EVAL_MODE === "1";
 }
@@ -144,7 +146,11 @@ export async function registerYagni(pi, deps = {}) {
     // child, a subagent, or an advisor consult).
     pi.registerProvider("yagni", buildYagniProvider(catalog, baseUrl, attributionHeaders(deps.env)));
     const toolOpts = { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch };
-    pi.registerTool(makeAskYagniTool(toolOpts));
+    // One flywheel state per session, shared by ask_yagni (caps how many
+    // no-position record suggestions reach the model) and record_decision
+    // (flywheel-attributed records send dedupe: true). Run 7.
+    const flywheelState = makeFlywheelState();
+    pi.registerTool(makeAskYagniTool({ ...toolOpts, flywheel: flywheelState, getRepo: () => sessionRepo }));
     // Ticket write-back (spec 2026-08-09): explicit user-intent writes to the
     // workspace tracker, attributed to the developer via per-user credentials.
     if (!evalMode) {
@@ -172,7 +178,7 @@ export async function registerYagni(pi, deps = {}) {
         pi.registerTool(makeRecordEngineeringContextTool(toolOpts));
         // The capture half of the judgment loop: bank a product-intent decision so
         // ask_yagni answers the same question next time instead of interrupting a human.
-        pi.registerTool(makeRecordDecisionTool(toolOpts));
+        pi.registerTool(makeRecordDecisionTool({ ...toolOpts, flywheel: flywheelState }));
     }
     // The visible checklist for multi-step work: the todo_write tool, its
     // above-editor widget, and /todos. Branch-replayed, so forks and resumes
@@ -460,11 +466,27 @@ export async function registerYagni(pi, deps = {}) {
     // must never block the agent), then inject it into the system prompt so the
     // very first turn already knows how this company and codebase work.
     const fetchBrief = deps.fetchContextBrief ?? defaultFetchContextBrief;
+    // Resolved BEFORE the brief fetch so /context can answer repoDecisionCount
+    // in the same round-trip (the mining beat's signal). Best-effort: undefined
+    // outside a git repo or without an origin remote.
+    const resolveRepoFn = deps.resolveRepoFullName ?? ((cwd) => defaultMineBeatGit.repoFullName(cwd));
+    let sessionRepo;
+    try {
+        sessionRepo = evalMode ? undefined : resolveRepoFn(process.cwd());
+    }
+    catch {
+        sessionRepo = undefined;
+    }
     let contextBrief;
     let briefResult = null;
     if (!evalMode) {
         try {
-            briefResult = await fetchBrief({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+            briefResult = await fetchBrief({
+                baseUrl,
+                getToken: getTokenFn,
+                fetchImpl: authedFetch,
+                repo: sessionRepo,
+            });
             contextBrief = briefResult?.brief?.trim() ? briefResult.brief : undefined;
         }
         catch {
@@ -769,6 +791,28 @@ export async function registerYagni(pi, deps = {}) {
                 // The init pass is best-effort; a failure never blocks the session.
             }
         }
+        // Run 7: the opt-in repo seeding beat. Fires only on a genuine startup
+        // when /context reported an explicitly-empty repo-scoped ledger, once per
+        // repo (marker store). Fully fail-soft — a beat failure never blocks the
+        // session.
+        if (event.reason === "startup" && !evalMode) {
+            try {
+                const offerBeat = deps.offerMiningBeat ?? defaultMaybeOfferMiningBeat;
+                const markers = deps.mineBeatMarkers ?? fileMineBeatMarkers(codeStateHome(null, env));
+                await offerBeat(ctx, {
+                    repoFullName: sessionRepo,
+                    repoDecisionCount: briefResult?.repoDecisionCount,
+                    cwd: process.cwd(),
+                    baseUrl,
+                    getToken: getTokenFn,
+                    fetchImpl: authedFetch,
+                    markers,
+                });
+            }
+            catch {
+                // Seeding is best-effort; a failure never blocks the session.
+            }
+        }
     });
 }
 export default async function (pi) {