@kolisachint/hoocode-agent 0.5.17 → 0.5.19

package/dist/core/learn/audit.js

@@ -0,0 +1,316 @@
+/**
+ * The subtractive half of `/learn`: which lines in a context file describe
+ * things that no longer exist?
+ *
+ * The mining pipeline can only ever propose additions. Nothing in it moves the
+ * always-loaded token surface down, so a context file accumulates: a rule
+ * naming a deleted workflow, a command that was removed, a file that moved two
+ * refactors ago. Those lines cost tokens on every request forever and are worse
+ * than useless, because the agent believes them.
+ *
+ * This is deliberately deterministic — no model call, no cache, no state. It
+ * reads the context files already in force, pulls out the referents they name
+ * in backticks, and asks the filesystem. That makes it instant and free, which
+ * is what lets it be the half you run most often.
+ *
+ * Precision is bought with exclusions rather than cleverness, because a noisy
+ * audit is one nobody reads. Three rules do most of the work:
+ *
+ * - **Only path-like referents with a separator.** A bare `auth.json` could be
+ *   anywhere or nowhere; `docs/providers.md` is a claim about this repo.
+ * - **Resolve against every package root, not just the repo root.** A monorepo
+ *   names `src/cli/args.ts` relative to the package being discussed, and
+ *   checking only the repo root reports the entire contributing guide as stale.
+ * - **Skip lines that assert absence.** "these are all gone", "e.g.
+ *   `bedrock-utils.ts`", "create `foo.ts`" legitimately name files that do not
+ *   exist. Deciding this in general is a judgement call; a short vocabulary of
+ *   assertive forms catches the cases that occur in practice.
+ *
+ * What is left is a short list where a wrong entry costs one glance and a right
+ * one costs a line of always-loaded context. That asymmetry is the reason the
+ * remaining false positives are acceptable and silent misses are not.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+/** Directories never descended into when discovering package roots. */
+const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", "out", ".next", ".turbo"]);
+/** How deep to look for package roots. Deep enough for a monorepo, shallow enough to stay instant. */
+const MAX_ROOT_DEPTH = 3;
+/** Extensions that make a token a file reference even without an obvious path shape. */
+const FILE_EXTENSIONS = /\.(md|markdown|ts|tsx|js|jsx|mjs|cjs|json|jsonc|ya?ml|toml|sh|bash|zsh|py|rs|go|lock|txt|css|html)$/i;
+/**
+ * Forms that legitimately name something absent.
+ *
+ * Every one of these was a false positive on a real context file before it was
+ * excluded. `removed`/`gone` describe a deletion; `e.g.`/`for example` name a
+ * pattern rather than a file; `create`/`scaffold` describe an artifact the
+ * reader is being told to write.
+ *
+ * The list is deliberately short. Broad prohibitions ("never edit X", "do not
+ * run Y") name things that exist and are exactly the claims worth checking, so
+ * matching on those words would trade the audit's whole purpose for a little
+ * precision.
+ */
+const ABSENCE_MARKERS = [
+    "removed",
+    "deleted",
+    " gone",
+    "no longer",
+    "used to",
+    "if present",
+    "if it exists",
+    "optional",
+    "e.g.",
+    "for example",
+    "create ",
+    "scaffold",
+];
+/** Referents that look like a git ref rather than a path. */
+const GIT_REF_PREFIXES = ["origin/", "upstream/", "refs/", "HEAD"];
+/** Rough token estimate, matching the convention used elsewhere for context files. */
+function estimateTokens(text) {
+    return Math.round(Buffer.byteLength(text, "utf-8") / 4);
+}
+/**
+ * Directories a relative referent may be resolved against.
+ *
+ * The repo root alone is not enough: a monorepo's contributing notes name
+ * `src/cli/args.ts` meaning "inside the package under discussion", and resolving
+ * that only from the root reports every such line as stale. Every directory
+ * holding a `package.json` is therefore a root, nearest-shallowest first.
+ */
+export function resolutionRoots(base) {
+    const roots = [resolve(base)];
+    const walk = (dir, depth) => {
+        if (depth > MAX_ROOT_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || IGNORED_DIRS.has(entry.name))
+                continue;
+            const child = join(dir, entry.name);
+            if (existsSync(join(child, "package.json")))
+                roots.push(child);
+            walk(child, depth + 1);
+        }
+    };
+    walk(resolve(base), 1);
+    return roots;
+}
+/** Every backticked span in a line, in order. */
+function backtickedSpans(line) {
+    const out = [];
+    const pattern = /`([^`\n]+)`/g;
+    let match = pattern.exec(line);
+    while (match) {
+        if (match[1])
+            out.push(match[1]);
+        match = pattern.exec(line);
+    }
+    return out;
+}
+/** True when the line reads as a statement about something absent, optional, or yet to be written. */
+function assertsAbsence(line) {
+    const lower = line.toLowerCase();
+    return ABSENCE_MARKERS.some((marker) => lower.includes(marker));
+}
+/** The script name a `bun run x` / `npm run x` reference names, if it is one. */
+function scriptReference(token) {
+    const match = /^(?:bun|npm|pnpm|yarn)\s+run\s+([A-Za-z0-9:_-]+)$/.exec(token.trim());
+    return match?.[1];
+}
+/**
+ * Decide whether a backticked token is a checkable claim about this repo.
+ *
+ * Ordering matters: the skip reasons are reported as counts, and a token that
+ * matches several should be attributed to the most specific one, so a
+ * placeholder is a placeholder rather than "ambiguous".
+ */
+export function classifyReferent(token) {
+    const value = token.trim();
+    const script = scriptReference(value);
+    if (script)
+        return { kind: "script", script };
+    if (/[<>*{}$|]/.test(value))
+        return { kind: "skip", reason: "placeholder" };
+    if (/^https?:\/\//i.test(value))
+        return { kind: "skip", reason: "external" };
+    if (GIT_REF_PREFIXES.some((prefix) => value.startsWith(prefix)))
+        return { kind: "skip", reason: "external" };
+    // A shell command, a prose fragment, or a flag list — not a path.
+    if (/\s/.test(value))
+        return { kind: "skip", reason: "ambiguous" };
+    if (value.startsWith("~") || value.startsWith(sep) || /^[A-Za-z]:[\\/]/.test(value)) {
+        return { kind: "skip", reason: "runtime" };
+    }
+    if (value === "." || value === "..")
+        return { kind: "skip", reason: "ambiguous" };
+    // The load-bearing precision rule: without a separator the token names a
+    // filename that could be anywhere, and "anywhere" is not a claim worth
+    // contradicting. A bare `stream.test.ts` in a monorepo is not stale, it is
+    // under-specified.
+    if (!value.includes("/"))
+        return { kind: "skip", reason: "ambiguous" };
+    // Past the separator rule, something that is neither a known file type nor an
+    // obvious directory is more likely prose than a path.
+    if (!FILE_EXTENSIONS.test(value) && !value.endsWith("/"))
+        return { kind: "skip", reason: "ambiguous" };
+    return { kind: "path" };
+}
+/** True when the referent resolves against any root. Directories count. */
+function pathResolves(referent, roots) {
+    const relative = referent.replace(/\/+$/, "");
+    if (!relative)
+        return false;
+    return roots.some((root) => existsSync(join(root, relative)));
+}
+/** Script names declared by any `package.json` at any resolution root. */
+function declaredScripts(roots) {
+    const names = new Set();
+    for (const root of roots) {
+        const manifest = join(root, "package.json");
+        if (!existsSync(manifest))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(manifest, "utf-8"));
+            for (const name of Object.keys(parsed.scripts ?? {}))
+                names.add(name);
+        }
+        catch {
+            // A malformed manifest is not this command's problem; treat it as
+            // declaring nothing rather than failing the audit.
+        }
+    }
+    return names;
+}
+/**
+ * The project a referent is resolved against: the nearest ancestor holding a
+ * `.git`, or `cwd` when there is none.
+ *
+ * Not `cwd` itself. Context files are collected by walking up from `cwd`, so in
+ * a monorepo the repo's `AGENTS.md` sits *above* the package you are working
+ * in — and running from a package root is the normal case, not the exception.
+ * Anchoring on `cwd` meant the file with all the claims in it was declared "not
+ * in this working tree" and skipped, so the audit passed by checking nothing.
+ */
+export function findProjectRoot(cwd) {
+    let dir = resolve(cwd);
+    while (true) {
+        if (existsSync(join(dir, ".git")))
+            return dir;
+        const parent = resolve(dir, "..");
+        if (parent === dir)
+            return resolve(cwd);
+        dir = parent;
+    }
+}
+/** True when the path is inside the project, so its claims are about this repo. */
+function insideTree(path, root) {
+    const base = resolve(root);
+    const target = resolve(path);
+    return target === base || target.startsWith(base + sep);
+}
+/**
+ * Check every referent named by the repo-scope context files.
+ *
+ * Files outside the project are listed but not audited: a rule in
+ * `~/.agents/AGENTS.md` naming `src/index.ts` is a claim about whichever repo
+ * it was written for, and resolving it here would report another project's
+ * rules as broken.
+ *
+ * File contents are re-read from disk rather than taken from the loader, which
+ * truncates oversized files for the prompt — auditing the truncation would
+ * silently stop checking exactly the files most likely to have gone stale.
+ */
+export function auditContextFiles(options) {
+    // Rooted at the project, not at `cwd`: a path in the repo's context file is
+    // written relative to the repo, and is being read from wherever you happen to
+    // be working.
+    const projectRoot = findProjectRoot(options.cwd);
+    const roots = resolutionRoots(projectRoot);
+    const scripts = declaredScripts(roots);
+    const report = {
+        files: [],
+        skippedFiles: [],
+        checked: 0,
+        skipped: { placeholder: 0, runtime: 0, external: 0, ambiguous: 0, assertsAbsence: 0 },
+        stale: [],
+        roots,
+    };
+    for (const file of options.files) {
+        if (!insideTree(file.path, projectRoot)) {
+            report.skippedFiles.push(file.path);
+            continue;
+        }
+        let content;
+        try {
+            content = readFileSync(file.path, "utf-8");
+        }
+        catch {
+            report.skippedFiles.push(file.path);
+            continue;
+        }
+        report.files.push({ path: file.path, tokens: file.tokens ?? estimateTokens(content) });
+        const lines = content.split("\n");
+        let inFence = false;
+        for (const [index, raw] of lines.entries()) {
+            // A fenced block is example code, not a claim about the repo. Its
+            // contents are also where most of a context file's plausible-looking
+            // paths live, so auditing it is almost pure noise.
+            if (raw.trimStart().startsWith("```")) {
+                inFence = !inFence;
+                continue;
+            }
+            if (inFence)
+                continue;
+            const spans = backtickedSpans(raw);
+            if (spans.length === 0)
+                continue;
+            const absence = assertsAbsence(raw);
+            for (const span of spans) {
+                const classification = classifyReferent(span);
+                if (classification.kind === "skip") {
+                    report.skipped[classification.reason]++;
+                    continue;
+                }
+                if (absence) {
+                    report.skipped.assertsAbsence++;
+                    continue;
+                }
+                report.checked++;
+                const resolved = classification.kind === "script" ? scripts.has(classification.script) : pathResolves(span, roots);
+                if (resolved)
+                    continue;
+                report.stale.push({
+                    file: file.path,
+                    line: index + 1,
+                    lineText: raw.trim(),
+                    referent: span,
+                    kind: classification.kind,
+                    tokens: estimateTokens(raw),
+                });
+            }
+        }
+    }
+    return report;
+}
+/** Total recurring cost of the lines the audit flagged. */
+export function staleTokens(report) {
+    const seen = new Set();
+    let total = 0;
+    for (const item of report.stale) {
+        const key = `${item.file}:${item.line}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        total += item.tokens;
+    }
+    return total;
+}
+//# sourceMappingURL=audit.js.map

package/dist/core/learn/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/core/learn/audit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The subtractive half of `/learn`: which lines in a context file describe\n * things that no longer exist?\n *\n * The mining pipeline can only ever propose additions. Nothing in it moves the\n * always-loaded token surface down, so a context file accumulates: a rule\n * naming a deleted workflow, a command that was removed, a file that moved two\n * refactors ago. Those lines cost tokens on every request forever and are worse\n * than useless, because the agent believes them.\n *\n * This is deliberately deterministic — no model call, no cache, no state. It\n * reads the context files already in force, pulls out the referents they name\n * in backticks, and asks the filesystem. That makes it instant and free, which\n * is what lets it be the half you run most often.\n *\n * Precision is bought with exclusions rather than cleverness, because a noisy\n * audit is one nobody reads. Three rules do most of the work:\n *\n * - **Only path-like referents with a separator.** A bare `auth.json` could be\n *   anywhere or nowhere; `docs/providers.md` is a claim about this repo.\n * - **Resolve against every package root, not just the repo root.** A monorepo\n *   names `src/cli/args.ts` relative to the package being discussed, and\n *   checking only the repo root reports the entire contributing guide as stale.\n * - **Skip lines that assert absence.** \"these are all gone\", \"e.g.\n *   `bedrock-utils.ts`\", \"create `foo.ts`\" legitimately name files that do not\n *   exist. Deciding this in general is a judgement call; a short vocabulary of\n *   assertive forms catches the cases that occur in practice.\n *\n * What is left is a short list where a wrong entry costs one glance and a right\n * one costs a line of always-loaded context. That asymmetry is the reason the\n * remaining false positives are acceptable and silent misses are not.\n */\n\nimport { type Dirent, existsSync, readdirSync, readFileSync } from \"node:fs\";\nimport { join, resolve, sep } from \"node:path\";\n\n/** One referent that did not resolve, with the line that claimed it. */\nexport interface StaleReference {\n\t/** Context file the claim lives in. */\n\tfile: string;\n\t/** 1-based line number. */\n\tline: number;\n\t/** The line, trimmed — what the reader would delete or fix. */\n\tlineText: string;\n\t/** The referent that could not be found. */\n\treferent: string;\n\tkind: \"path\" | \"script\";\n\t/** Rough token cost of the line, so the value of deleting it is visible. */\n\ttokens: number;\n}\n\n/** Why a referent was not checked. Reported as counts so the audit's reach is visible. */\nexport interface AuditSkips {\n\t/** Contains a placeholder or a glob, e.g. an angle-bracket stand-in or a star. */\n\tplaceholder: number;\n\t/** Home-relative or absolute: a runtime location, not a repo artifact. */\n\truntime: number;\n\t/** A URL, or a git ref like `origin/main`. */\n\texternal: number;\n\t/** No path separator, so the claim is not about a specific location. */\n\tambiguous: number;\n\t/** The line asserts the referent is absent, optional, or to be created. */\n\tassertsAbsence: number;\n}\n\nexport interface AuditReport {\n\t/** Context files audited, with their recurring cost. */\n\tfiles: Array<{ path: string; tokens: number }>;\n\t/** Context files skipped because they live outside the working tree. */\n\tskippedFiles: string[];\n\t/** Referents actually resolved against the filesystem. */\n\tchecked: number;\n\tskipped: AuditSkips;\n\tstale: StaleReference[];\n\t/** Directories referents were resolved against, nearest first. */\n\troots: string[];\n}\n\n/** Directories never descended into when discovering package roots. */\nconst IGNORED_DIRS = new Set([\"node_modules\", \".git\", \"dist\", \"build\", \"coverage\", \"out\", \".next\", \".turbo\"]);\n\n/** How deep to look for package roots. Deep enough for a monorepo, shallow enough to stay instant. */\nconst MAX_ROOT_DEPTH = 3;\n\n/** Extensions that make a token a file reference even without an obvious path shape. */\nconst FILE_EXTENSIONS =\n\t/\\.(md|markdown|ts|tsx|js|jsx|mjs|cjs|json|jsonc|ya?ml|toml|sh|bash|zsh|py|rs|go|lock|txt|css|html)$/i;\n\n/**\n * Forms that legitimately name something absent.\n *\n * Every one of these was a false positive on a real context file before it was\n * excluded. `removed`/`gone` describe a deletion; `e.g.`/`for example` name a\n * pattern rather than a file; `create`/`scaffold` describe an artifact the\n * reader is being told to write.\n *\n * The list is deliberately short. Broad prohibitions (\"never edit X\", \"do not\n * run Y\") name things that exist and are exactly the claims worth checking, so\n * matching on those words would trade the audit's whole purpose for a little\n * precision.\n */\nconst ABSENCE_MARKERS = [\n\t\"removed\",\n\t\"deleted\",\n\t\" gone\",\n\t\"no longer\",\n\t\"used to\",\n\t\"if present\",\n\t\"if it exists\",\n\t\"optional\",\n\t\"e.g.\",\n\t\"for example\",\n\t\"create \",\n\t\"scaffold\",\n];\n\n/** Referents that look like a git ref rather than a path. */\nconst GIT_REF_PREFIXES = [\"origin/\", \"upstream/\", \"refs/\", \"HEAD\"];\n\n/** Rough token estimate, matching the convention used elsewhere for context files. */\nfunction estimateTokens(text: string): number {\n\treturn Math.round(Buffer.byteLength(text, \"utf-8\") / 4);\n}\n\n/**\n * Directories a relative referent may be resolved against.\n *\n * The repo root alone is not enough: a monorepo's contributing notes name\n * `src/cli/args.ts` meaning \"inside the package under discussion\", and resolving\n * that only from the root reports every such line as stale. Every directory\n * holding a `package.json` is therefore a root, nearest-shallowest first.\n */\nexport function resolutionRoots(base: string): string[] {\n\tconst roots: string[] = [resolve(base)];\n\n\tconst walk = (dir: string, depth: number): void => {\n\t\tif (depth > MAX_ROOT_DEPTH) return;\n\t\tlet entries: Dirent[];\n\t\ttry {\n\t\t\tentries = readdirSync(dir, { withFileTypes: true });\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t\tfor (const entry of entries) {\n\t\t\tif (!entry.isDirectory() || IGNORED_DIRS.has(entry.name)) continue;\n\t\t\tconst child = join(dir, entry.name);\n\t\t\tif (existsSync(join(child, \"package.json\"))) roots.push(child);\n\t\t\twalk(child, depth + 1);\n\t\t}\n\t};\n\twalk(resolve(base), 1);\n\n\treturn roots;\n}\n\n/** Every backticked span in a line, in order. */\nfunction backtickedSpans(line: string): string[] {\n\tconst out: string[] = [];\n\tconst pattern = /`([^`\\n]+)`/g;\n\tlet match = pattern.exec(line);\n\twhile (match) {\n\t\tif (match[1]) out.push(match[1]);\n\t\tmatch = pattern.exec(line);\n\t}\n\treturn out;\n}\n\n/** True when the line reads as a statement about something absent, optional, or yet to be written. */\nfunction assertsAbsence(line: string): boolean {\n\tconst lower = line.toLowerCase();\n\treturn ABSENCE_MARKERS.some((marker) => lower.includes(marker));\n}\n\n/** The script name a `bun run x` / `npm run x` reference names, if it is one. */\nfunction scriptReference(token: string): string | undefined {\n\tconst match = /^(?:bun|npm|pnpm|yarn)\\s+run\\s+([A-Za-z0-9:_-]+)$/.exec(token.trim());\n\treturn match?.[1];\n}\n\ntype Classification =\n\t| { kind: \"path\" }\n\t| { kind: \"script\"; script: string }\n\t| { kind: \"skip\"; reason: keyof AuditSkips };\n\n/**\n * Decide whether a backticked token is a checkable claim about this repo.\n *\n * Ordering matters: the skip reasons are reported as counts, and a token that\n * matches several should be attributed to the most specific one, so a\n * placeholder is a placeholder rather than \"ambiguous\".\n */\nexport function classifyReferent(token: string): Classification {\n\tconst value = token.trim();\n\tconst script = scriptReference(value);\n\tif (script) return { kind: \"script\", script };\n\n\tif (/[<>*{}$|]/.test(value)) return { kind: \"skip\", reason: \"placeholder\" };\n\tif (/^https?:\\/\\//i.test(value)) return { kind: \"skip\", reason: \"external\" };\n\tif (GIT_REF_PREFIXES.some((prefix) => value.startsWith(prefix))) return { kind: \"skip\", reason: \"external\" };\n\t// A shell command, a prose fragment, or a flag list — not a path.\n\tif (/\\s/.test(value)) return { kind: \"skip\", reason: \"ambiguous\" };\n\tif (value.startsWith(\"~\") || value.startsWith(sep) || /^[A-Za-z]:[\\\\/]/.test(value)) {\n\t\treturn { kind: \"skip\", reason: \"runtime\" };\n\t}\n\tif (value === \".\" || value === \"..\") return { kind: \"skip\", reason: \"ambiguous\" };\n\t// The load-bearing precision rule: without a separator the token names a\n\t// filename that could be anywhere, and \"anywhere\" is not a claim worth\n\t// contradicting. A bare `stream.test.ts` in a monorepo is not stale, it is\n\t// under-specified.\n\tif (!value.includes(\"/\")) return { kind: \"skip\", reason: \"ambiguous\" };\n\t// Past the separator rule, something that is neither a known file type nor an\n\t// obvious directory is more likely prose than a path.\n\tif (!FILE_EXTENSIONS.test(value) && !value.endsWith(\"/\")) return { kind: \"skip\", reason: \"ambiguous\" };\n\n\treturn { kind: \"path\" };\n}\n\n/** True when the referent resolves against any root. Directories count. */\nfunction pathResolves(referent: string, roots: string[]): boolean {\n\tconst relative = referent.replace(/\\/+$/, \"\");\n\tif (!relative) return false;\n\treturn roots.some((root) => existsSync(join(root, relative)));\n}\n\n/** Script names declared by any `package.json` at any resolution root. */\nfunction declaredScripts(roots: string[]): Set<string> {\n\tconst names = new Set<string>();\n\tfor (const root of roots) {\n\t\tconst manifest = join(root, \"package.json\");\n\t\tif (!existsSync(manifest)) continue;\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(readFileSync(manifest, \"utf-8\")) as { scripts?: Record<string, unknown> };\n\t\t\tfor (const name of Object.keys(parsed.scripts ?? {})) names.add(name);\n\t\t} catch {\n\t\t\t// A malformed manifest is not this command's problem; treat it as\n\t\t\t// declaring nothing rather than failing the audit.\n\t\t}\n\t}\n\treturn names;\n}\n\n/**\n * The project a referent is resolved against: the nearest ancestor holding a\n * `.git`, or `cwd` when there is none.\n *\n * Not `cwd` itself. Context files are collected by walking up from `cwd`, so in\n * a monorepo the repo's `AGENTS.md` sits *above* the package you are working\n * in — and running from a package root is the normal case, not the exception.\n * Anchoring on `cwd` meant the file with all the claims in it was declared \"not\n * in this working tree\" and skipped, so the audit passed by checking nothing.\n */\nexport function findProjectRoot(cwd: string): string {\n\tlet dir = resolve(cwd);\n\twhile (true) {\n\t\tif (existsSync(join(dir, \".git\"))) return dir;\n\t\tconst parent = resolve(dir, \"..\");\n\t\tif (parent === dir) return resolve(cwd);\n\t\tdir = parent;\n\t}\n}\n\n/** True when the path is inside the project, so its claims are about this repo. */\nfunction insideTree(path: string, root: string): boolean {\n\tconst base = resolve(root);\n\tconst target = resolve(path);\n\treturn target === base || target.startsWith(base + sep);\n}\n\nexport interface AuditOptions {\n\tcwd: string;\n\t/** Context files in force, as loaded for the system prompt. */\n\tfiles: Array<{ path: string; tokens?: number }>;\n}\n\n/**\n * Check every referent named by the repo-scope context files.\n *\n * Files outside the project are listed but not audited: a rule in\n * `~/.agents/AGENTS.md` naming `src/index.ts` is a claim about whichever repo\n * it was written for, and resolving it here would report another project's\n * rules as broken.\n *\n * File contents are re-read from disk rather than taken from the loader, which\n * truncates oversized files for the prompt — auditing the truncation would\n * silently stop checking exactly the files most likely to have gone stale.\n */\nexport function auditContextFiles(options: AuditOptions): AuditReport {\n\t// Rooted at the project, not at `cwd`: a path in the repo's context file is\n\t// written relative to the repo, and is being read from wherever you happen to\n\t// be working.\n\tconst projectRoot = findProjectRoot(options.cwd);\n\tconst roots = resolutionRoots(projectRoot);\n\tconst scripts = declaredScripts(roots);\n\n\tconst report: AuditReport = {\n\t\tfiles: [],\n\t\tskippedFiles: [],\n\t\tchecked: 0,\n\t\tskipped: { placeholder: 0, runtime: 0, external: 0, ambiguous: 0, assertsAbsence: 0 },\n\t\tstale: [],\n\t\troots,\n\t};\n\n\tfor (const file of options.files) {\n\t\tif (!insideTree(file.path, projectRoot)) {\n\t\t\treport.skippedFiles.push(file.path);\n\t\t\tcontinue;\n\t\t}\n\n\t\tlet content: string;\n\t\ttry {\n\t\t\tcontent = readFileSync(file.path, \"utf-8\");\n\t\t} catch {\n\t\t\treport.skippedFiles.push(file.path);\n\t\t\tcontinue;\n\t\t}\n\t\treport.files.push({ path: file.path, tokens: file.tokens ?? estimateTokens(content) });\n\n\t\tconst lines = content.split(\"\\n\");\n\t\tlet inFence = false;\n\t\tfor (const [index, raw] of lines.entries()) {\n\t\t\t// A fenced block is example code, not a claim about the repo. Its\n\t\t\t// contents are also where most of a context file's plausible-looking\n\t\t\t// paths live, so auditing it is almost pure noise.\n\t\t\tif (raw.trimStart().startsWith(\"```\")) {\n\t\t\t\tinFence = !inFence;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (inFence) continue;\n\n\t\t\tconst spans = backtickedSpans(raw);\n\t\t\tif (spans.length === 0) continue;\n\n\t\t\tconst absence = assertsAbsence(raw);\n\t\t\tfor (const span of spans) {\n\t\t\t\tconst classification = classifyReferent(span);\n\t\t\t\tif (classification.kind === \"skip\") {\n\t\t\t\t\treport.skipped[classification.reason]++;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (absence) {\n\t\t\t\t\treport.skipped.assertsAbsence++;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\n\t\t\t\treport.checked++;\n\t\t\t\tconst resolved =\n\t\t\t\t\tclassification.kind === \"script\" ? scripts.has(classification.script) : pathResolves(span, roots);\n\t\t\t\tif (resolved) continue;\n\n\t\t\t\treport.stale.push({\n\t\t\t\t\tfile: file.path,\n\t\t\t\t\tline: index + 1,\n\t\t\t\t\tlineText: raw.trim(),\n\t\t\t\t\treferent: span,\n\t\t\t\t\tkind: classification.kind,\n\t\t\t\t\ttokens: estimateTokens(raw),\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n\n\treturn report;\n}\n\n/** Total recurring cost of the lines the audit flagged. */\nexport function staleTokens(report: AuditReport): number {\n\tconst seen = new Set<string>();\n\tlet total = 0;\n\tfor (const item of report.stale) {\n\t\tconst key = `${item.file}:${item.line}`;\n\t\tif (seen.has(key)) continue;\n\t\tseen.add(key);\n\t\ttotal += item.tokens;\n\t}\n\treturn total;\n}\n"]}

package/dist/core/learn/cache.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Per-session memo of the miner's output, keyed on file content.
+ *
+ * This is what makes an LLM-read-everything pipeline affordable. A closed
+ * session transcript never changes again, so the model needs to read it exactly
+ * once in its life. Hash the bytes, keep the candidates, and a routine `/learn`
+ * pays for the one or two sessions written since the last run while the other
+ * eighteen come back for free.
+ *
+ * It also happens to be the right answer to "incremental vs. full history",
+ * which an earlier design tried to solve with an mtime cursor. A cursor breaks
+ * the counting: if a run only *reads* sessions newer than the cursor, a
+ * directive said once today has a count of one, because the four earlier
+ * occurrences were never in the scan. Caching moves the skipping to the
+ * expensive step only — the reduce step still runs over every cached session
+ * every time, so the cross-session counts stay exact no matter how little was
+ * mined this run.
+ *
+ * The cache is disposable. Deleting it costs one re-mine and nothing else, so
+ * every failure path here degrades to "mine it again" rather than to an error.
+ */
+import type { MinedCandidate } from "./mine.js";
+export interface CachedMining {
+    /** Session identity, carried so a cache hit does not need the transcript reparsed. */
+    sessionId: string;
+    /** Session start time, ISO. */
+    timestamp: string;
+    candidates: MinedCandidate[];
+    /** When this entry was written, ISO. */
+    minedAt: string;
+}
+export declare function getLearnCacheDir(agentDir: string): string;
+/**
+ * Content hash of a session file.
+ *
+ * Content, not mtime: a resumed session gets a fresh mtime with identical
+ * bytes, and a file copied between machines gets a new mtime too. Both would
+ * force a needless re-mine. Content also makes the reverse mistake impossible —
+ * a file whose bytes changed always misses the cache, which matters because the
+ * live session is appended to between runs.
+ */
+export declare function hashSessionFile(file: string): string | undefined;
+/** Look up a previously mined session. Any unreadable entry reads as a miss. */
+export declare function readCachedMining(agentDir: string, hash: string): CachedMining | undefined;
+/** Store a mined session. Failing to cache is never worth failing the run over. */
+export declare function writeCachedMining(agentDir: string, hash: string, entry: CachedMining): void;
+/**
+ * Drop entries nothing has referenced in a long time, so a machine that has
+ * been running this for a year does not keep every session it ever saw.
+ */
+export declare function pruneLearnCache(agentDir: string, now?: Date): void;
+/**
+ * Counting what a run still owes the model lives in `extract.ts:planMining`,
+ * not here: the answer depends on which sessions the window actually selects,
+ * and duplicating that selection is how the confirmation prompt ends up
+ * quoting a number the run does not honour.
+ */
+//# sourceMappingURL=cache.d.ts.map

package/dist/core/learn/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/core/learn/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AA0BhD,MAAM,WAAW,YAAY;IAC5B,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMhE;AAMD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAezF;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAO3F;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,IAAI,CAgB9E;AAED;;;;;GAKG","sourcesContent":["/**\n * Per-session memo of the miner's output, keyed on file content.\n *\n * This is what makes an LLM-read-everything pipeline affordable. A closed\n * session transcript never changes again, so the model needs to read it exactly\n * once in its life. Hash the bytes, keep the candidates, and a routine `/learn`\n * pays for the one or two sessions written since the last run while the other\n * eighteen come back for free.\n *\n * It also happens to be the right answer to \"incremental vs. full history\",\n * which an earlier design tried to solve with an mtime cursor. A cursor breaks\n * the counting: if a run only *reads* sessions newer than the cursor, a\n * directive said once today has a count of one, because the four earlier\n * occurrences were never in the scan. Caching moves the skipping to the\n * expensive step only — the reduce step still runs over every cached session\n * every time, so the cross-session counts stay exact no matter how little was\n * mined this run.\n *\n * The cache is disposable. Deleting it costs one re-mine and nothing else, so\n * every failure path here degrades to \"mine it again\" rather than to an error.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { writeFileAtomicSync } from \"../../utils/atomic-file.js\";\nimport type { MinedCandidate } from \"./mine.js\";\n\n/**\n * Bump when the miner prompt, the candidate shape, or what the miner is shown\n * changes.\n *\n * The version is part of the cache key, not a field inside the entry, so a bump\n * invalidates every entry at once without a migration or a sweep — old files\n * simply stop being looked up, and the pruner reclaims them on age.\n *\n * v2: transcripts no longer carry successful tool output or replayed\n * slash-command bodies, and candidates are dropped when their quote cannot be\n * found in what the user said. Entries mined before that were read from a\n * different transcript than the one the pipeline now produces, so keeping them\n * would mean counting evidence the current rules would have rejected.\n *\n * v3: candidates no longer carry a label. Naming moved to a global pass that\n * sees the whole window, which is also what makes this file model-independent:\n * a cached label was frozen at mining time, so changing the `fast` tier forked\n * the vocabulary permanently and split every count across the seam.\n */\nconst CACHE_VERSION = 3;\n\n/** Entries untouched for this long are reclaimed. */\nconst CACHE_RETENTION_DAYS = 180;\n\nexport interface CachedMining {\n\t/** Session identity, carried so a cache hit does not need the transcript reparsed. */\n\tsessionId: string;\n\t/** Session start time, ISO. */\n\ttimestamp: string;\n\tcandidates: MinedCandidate[];\n\t/** When this entry was written, ISO. */\n\tminedAt: string;\n}\n\nexport function getLearnCacheDir(agentDir: string): string {\n\treturn join(agentDir, \"learn\", \"cache\");\n}\n\n/**\n * Content hash of a session file.\n *\n * Content, not mtime: a resumed session gets a fresh mtime with identical\n * bytes, and a file copied between machines gets a new mtime too. Both would\n * force a needless re-mine. Content also makes the reverse mistake impossible —\n * a file whose bytes changed always misses the cache, which matters because the\n * live session is appended to between runs.\n */\nexport function hashSessionFile(file: string): string | undefined {\n\ttry {\n\t\treturn createHash(\"sha256\").update(readFileSync(file)).digest(\"hex\").slice(0, 32);\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction entryPath(agentDir: string, hash: string): string {\n\treturn join(getLearnCacheDir(agentDir), `v${CACHE_VERSION}-${hash}.json`);\n}\n\n/** Look up a previously mined session. Any unreadable entry reads as a miss. */\nexport function readCachedMining(agentDir: string, hash: string): CachedMining | undefined {\n\tconst path = entryPath(agentDir, hash);\n\ttry {\n\t\tif (!existsSync(path)) return undefined;\n\t\tconst parsed = JSON.parse(readFileSync(path, \"utf-8\")) as Partial<CachedMining>;\n\t\tif (!Array.isArray(parsed.candidates) || typeof parsed.sessionId !== \"string\") return undefined;\n\t\treturn {\n\t\t\tsessionId: parsed.sessionId,\n\t\t\ttimestamp: typeof parsed.timestamp === \"string\" ? parsed.timestamp : new Date(0).toISOString(),\n\t\t\tcandidates: parsed.candidates as MinedCandidate[],\n\t\t\tminedAt: typeof parsed.minedAt === \"string\" ? parsed.minedAt : new Date(0).toISOString(),\n\t\t};\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** Store a mined session. Failing to cache is never worth failing the run over. */\nexport function writeCachedMining(agentDir: string, hash: string, entry: CachedMining): void {\n\ttry {\n\t\tmkdirSync(getLearnCacheDir(agentDir), { recursive: true });\n\t\twriteFileAtomicSync(entryPath(agentDir, hash), `${JSON.stringify(entry, null, 2)}\\n`);\n\t} catch {\n\t\t// The cost is re-mining this session next run.\n\t}\n}\n\n/**\n * Drop entries nothing has referenced in a long time, so a machine that has\n * been running this for a year does not keep every session it ever saw.\n */\nexport function pruneLearnCache(agentDir: string, now: Date = new Date()): void {\n\tconst dir = getLearnCacheDir(agentDir);\n\tif (!existsSync(dir)) return;\n\tconst cutoff = now.getTime() - CACHE_RETENTION_DAYS * 24 * 60 * 60 * 1000;\n\ttry {\n\t\tfor (const name of readdirSync(dir)) {\n\t\t\tconst path = join(dir, name);\n\t\t\ttry {\n\t\t\t\tif (statSync(path).mtime.getTime() < cutoff) rmSync(path, { force: true });\n\t\t\t} catch {\n\t\t\t\t// Concurrent run reclaimed it first.\n\t\t\t}\n\t\t}\n\t} catch {\n\t\t// An unreadable cache directory is not an error worth surfacing.\n\t}\n}\n\n/**\n * Counting what a run still owes the model lives in `extract.ts:planMining`,\n * not here: the answer depends on which sessions the window actually selects,\n * and duplicating that selection is how the confirmation prompt ends up\n * quoting a number the run does not honour.\n */\n"]}

package/dist/core/learn/cache.js

@@ -0,0 +1,132 @@
+/**
+ * Per-session memo of the miner's output, keyed on file content.
+ *
+ * This is what makes an LLM-read-everything pipeline affordable. A closed
+ * session transcript never changes again, so the model needs to read it exactly
+ * once in its life. Hash the bytes, keep the candidates, and a routine `/learn`
+ * pays for the one or two sessions written since the last run while the other
+ * eighteen come back for free.
+ *
+ * It also happens to be the right answer to "incremental vs. full history",
+ * which an earlier design tried to solve with an mtime cursor. A cursor breaks
+ * the counting: if a run only *reads* sessions newer than the cursor, a
+ * directive said once today has a count of one, because the four earlier
+ * occurrences were never in the scan. Caching moves the skipping to the
+ * expensive step only — the reduce step still runs over every cached session
+ * every time, so the cross-session counts stay exact no matter how little was
+ * mined this run.
+ *
+ * The cache is disposable. Deleting it costs one re-mine and nothing else, so
+ * every failure path here degrades to "mine it again" rather than to an error.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomicSync } from "../../utils/atomic-file.js";
+/**
+ * Bump when the miner prompt, the candidate shape, or what the miner is shown
+ * changes.
+ *
+ * The version is part of the cache key, not a field inside the entry, so a bump
+ * invalidates every entry at once without a migration or a sweep — old files
+ * simply stop being looked up, and the pruner reclaims them on age.
+ *
+ * v2: transcripts no longer carry successful tool output or replayed
+ * slash-command bodies, and candidates are dropped when their quote cannot be
+ * found in what the user said. Entries mined before that were read from a
+ * different transcript than the one the pipeline now produces, so keeping them
+ * would mean counting evidence the current rules would have rejected.
+ *
+ * v3: candidates no longer carry a label. Naming moved to a global pass that
+ * sees the whole window, which is also what makes this file model-independent:
+ * a cached label was frozen at mining time, so changing the `fast` tier forked
+ * the vocabulary permanently and split every count across the seam.
+ */
+const CACHE_VERSION = 3;
+/** Entries untouched for this long are reclaimed. */
+const CACHE_RETENTION_DAYS = 180;
+export function getLearnCacheDir(agentDir) {
+    return join(agentDir, "learn", "cache");
+}
+/**
+ * Content hash of a session file.
+ *
+ * Content, not mtime: a resumed session gets a fresh mtime with identical
+ * bytes, and a file copied between machines gets a new mtime too. Both would
+ * force a needless re-mine. Content also makes the reverse mistake impossible —
+ * a file whose bytes changed always misses the cache, which matters because the
+ * live session is appended to between runs.
+ */
+export function hashSessionFile(file) {
+    try {
+        return createHash("sha256").update(readFileSync(file)).digest("hex").slice(0, 32);
+    }
+    catch {
+        return undefined;
+    }
+}
+function entryPath(agentDir, hash) {
+    return join(getLearnCacheDir(agentDir), `v${CACHE_VERSION}-${hash}.json`);
+}
+/** Look up a previously mined session. Any unreadable entry reads as a miss. */
+export function readCachedMining(agentDir, hash) {
+    const path = entryPath(agentDir, hash);
+    try {
+        if (!existsSync(path))
+            return undefined;
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (!Array.isArray(parsed.candidates) || typeof parsed.sessionId !== "string")
+            return undefined;
+        return {
+            sessionId: parsed.sessionId,
+            timestamp: typeof parsed.timestamp === "string" ? parsed.timestamp : new Date(0).toISOString(),
+            candidates: parsed.candidates,
+            minedAt: typeof parsed.minedAt === "string" ? parsed.minedAt : new Date(0).toISOString(),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Store a mined session. Failing to cache is never worth failing the run over. */
+export function writeCachedMining(agentDir, hash, entry) {
+    try {
+        mkdirSync(getLearnCacheDir(agentDir), { recursive: true });
+        writeFileAtomicSync(entryPath(agentDir, hash), `${JSON.stringify(entry, null, 2)}\n`);
+    }
+    catch {
+        // The cost is re-mining this session next run.
+    }
+}
+/**
+ * Drop entries nothing has referenced in a long time, so a machine that has
+ * been running this for a year does not keep every session it ever saw.
+ */
+export function pruneLearnCache(agentDir, now = new Date()) {
+    const dir = getLearnCacheDir(agentDir);
+    if (!existsSync(dir))
+        return;
+    const cutoff = now.getTime() - CACHE_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+    try {
+        for (const name of readdirSync(dir)) {
+            const path = join(dir, name);
+            try {
+                if (statSync(path).mtime.getTime() < cutoff)
+                    rmSync(path, { force: true });
+            }
+            catch {
+                // Concurrent run reclaimed it first.
+            }
+        }
+    }
+    catch {
+        // An unreadable cache directory is not an error worth surfacing.
+    }
+}
+/**
+ * Counting what a run still owes the model lives in `extract.ts:planMining`,
+ * not here: the answer depends on which sessions the window actually selects,
+ * and duplicating that selection is how the confirmation prompt ends up
+ * quoting a number the run does not honour.
+ */
+//# sourceMappingURL=cache.js.map

package/dist/core/learn/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/core/learn/cache.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Per-session memo of the miner's output, keyed on file content.\n *\n * This is what makes an LLM-read-everything pipeline affordable. A closed\n * session transcript never changes again, so the model needs to read it exactly\n * once in its life. Hash the bytes, keep the candidates, and a routine `/learn`\n * pays for the one or two sessions written since the last run while the other\n * eighteen come back for free.\n *\n * It also happens to be the right answer to \"incremental vs. full history\",\n * which an earlier design tried to solve with an mtime cursor. A cursor breaks\n * the counting: if a run only *reads* sessions newer than the cursor, a\n * directive said once today has a count of one, because the four earlier\n * occurrences were never in the scan. Caching moves the skipping to the\n * expensive step only — the reduce step still runs over every cached session\n * every time, so the cross-session counts stay exact no matter how little was\n * mined this run.\n *\n * The cache is disposable. Deleting it costs one re-mine and nothing else, so\n * every failure path here degrades to \"mine it again\" rather than to an error.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { writeFileAtomicSync } from \"../../utils/atomic-file.js\";\nimport type { MinedCandidate } from \"./mine.js\";\n\n/**\n * Bump when the miner prompt, the candidate shape, or what the miner is shown\n * changes.\n *\n * The version is part of the cache key, not a field inside the entry, so a bump\n * invalidates every entry at once without a migration or a sweep — old files\n * simply stop being looked up, and the pruner reclaims them on age.\n *\n * v2: transcripts no longer carry successful tool output or replayed\n * slash-command bodies, and candidates are dropped when their quote cannot be\n * found in what the user said. Entries mined before that were read from a\n * different transcript than the one the pipeline now produces, so keeping them\n * would mean counting evidence the current rules would have rejected.\n *\n * v3: candidates no longer carry a label. Naming moved to a global pass that\n * sees the whole window, which is also what makes this file model-independent:\n * a cached label was frozen at mining time, so changing the `fast` tier forked\n * the vocabulary permanently and split every count across the seam.\n */\nconst CACHE_VERSION = 3;\n\n/** Entries untouched for this long are reclaimed. */\nconst CACHE_RETENTION_DAYS = 180;\n\nexport interface CachedMining {\n\t/** Session identity, carried so a cache hit does not need the transcript reparsed. */\n\tsessionId: string;\n\t/** Session start time, ISO. */\n\ttimestamp: string;\n\tcandidates: MinedCandidate[];\n\t/** When this entry was written, ISO. */\n\tminedAt: string;\n}\n\nexport function getLearnCacheDir(agentDir: string): string {\n\treturn join(agentDir, \"learn\", \"cache\");\n}\n\n/**\n * Content hash of a session file.\n *\n * Content, not mtime: a resumed session gets a fresh mtime with identical\n * bytes, and a file copied between machines gets a new mtime too. Both would\n * force a needless re-mine. Content also makes the reverse mistake impossible —\n * a file whose bytes changed always misses the cache, which matters because the\n * live session is appended to between runs.\n */\nexport function hashSessionFile(file: string): string | undefined {\n\ttry {\n\t\treturn createHash(\"sha256\").update(readFileSync(file)).digest(\"hex\").slice(0, 32);\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction entryPath(agentDir: string, hash: string): string {\n\treturn join(getLearnCacheDir(agentDir), `v${CACHE_VERSION}-${hash}.json`);\n}\n\n/** Look up a previously mined session. Any unreadable entry reads as a miss. */\nexport function readCachedMining(agentDir: string, hash: string): CachedMining | undefined {\n\tconst path = entryPath(agentDir, hash);\n\ttry {\n\t\tif (!existsSync(path)) return undefined;\n\t\tconst parsed = JSON.parse(readFileSync(path, \"utf-8\")) as Partial<CachedMining>;\n\t\tif (!Array.isArray(parsed.candidates) || typeof parsed.sessionId !== \"string\") return undefined;\n\t\treturn {\n\t\t\tsessionId: parsed.sessionId,\n\t\t\ttimestamp: typeof parsed.timestamp === \"string\" ? parsed.timestamp : new Date(0).toISOString(),\n\t\t\tcandidates: parsed.candidates as MinedCandidate[],\n\t\t\tminedAt: typeof parsed.minedAt === \"string\" ? parsed.minedAt : new Date(0).toISOString(),\n\t\t};\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** Store a mined session. Failing to cache is never worth failing the run over. */\nexport function writeCachedMining(agentDir: string, hash: string, entry: CachedMining): void {\n\ttry {\n\t\tmkdirSync(getLearnCacheDir(agentDir), { recursive: true });\n\t\twriteFileAtomicSync(entryPath(agentDir, hash), `${JSON.stringify(entry, null, 2)}\\n`);\n\t} catch {\n\t\t// The cost is re-mining this session next run.\n\t}\n}\n\n/**\n * Drop entries nothing has referenced in a long time, so a machine that has\n * been running this for a year does not keep every session it ever saw.\n */\nexport function pruneLearnCache(agentDir: string, now: Date = new Date()): void {\n\tconst dir = getLearnCacheDir(agentDir);\n\tif (!existsSync(dir)) return;\n\tconst cutoff = now.getTime() - CACHE_RETENTION_DAYS * 24 * 60 * 60 * 1000;\n\ttry {\n\t\tfor (const name of readdirSync(dir)) {\n\t\t\tconst path = join(dir, name);\n\t\t\ttry {\n\t\t\t\tif (statSync(path).mtime.getTime() < cutoff) rmSync(path, { force: true });\n\t\t\t} catch {\n\t\t\t\t// Concurrent run reclaimed it first.\n\t\t\t}\n\t\t}\n\t} catch {\n\t\t// An unreadable cache directory is not an error worth surfacing.\n\t}\n}\n\n/**\n * Counting what a run still owes the model lives in `extract.ts:planMining`,\n * not here: the answer depends on which sessions the window actually selects,\n * and duplicating that selection is how the confirmation prompt ends up\n * quoting a number the run does not honour.\n */\n"]}