@kolisachint/hoocode-agent 0.5.17 → 0.5.19

package/dist/core/learn/extract.js

@@ -8,81 +8,70 @@
  * whether something is a durable rule or a one-off, and it is the one thing a
  * prompt reading its own context cannot see.
  *
- * The split of labour is deliberate. This module is entirely deterministic: it
- * parses, filters, normalizes, counts and ranks. Judgement — is this a rule, how
- * should it be phrased, which scope owns it — belongs to the model reading the
- * digest, which is why the output carries evidence (counts, sessions, dates)
- * rather than conclusions.
+ * This module is the orchestrator, and the split of labour inside it is
+ * deliberate:
+ *
+ * - **Gathering** is deterministic. Finding session files, resolving which cwd
+ *   they belong to, walking the active branch of a forked session — all exact,
+ *   all cheap, all here.
+ * - **Judgement** is the model's, in `mine.ts` and `coverage.ts`. What counts as
+ *   a directive, what two phrasings have in common, whether a rule already
+ *   covers something — none of that survives contact with a regex, and it used
+ *   to be decided by one.
+ * - **Counting** is deterministic again, in `reduce.ts`. The number is the
+ *   product, and a model asked to count over a long context will be
+ *   approximately right.
+ *
+ * The expensive step is memoized per session file (`cache.ts`), so a session is
+ * read by the model exactly once in its life and the counts are still computed
+ * over every session in the window on every run.
  */
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 import { getUserAgentsDir } from "../../config.js";
 import { getSessionDirPath } from "../session-manager.js";
 import { loadSkills } from "../skills.js";
-import { commandHead, contentWords, extractErrorRegion, isBenignFailure, isRuleShapedDirective, isUninformativeFailure, normalizeCommand, normalizeDirective, normalizeErrorSignature, wordOverlap, } from "./normalize.js";
+import { hashSessionFile, pruneLearnCache, readCachedMining, writeCachedMining } from "./cache.js";
+import { fallbackLabel } from "./cluster.js";
+import { noCoverageJudge } from "./coverage.js";
+import { reduceDirectives, reduceFixes, reduceRequests } from "./reduce.js";
 import { judge } from "./state.js";
-/**
- * Prefix on the message `/learn` injects. The digest is persisted like any user
- * turn, so without this marker the next `/learn` would mine its own output and
- * every proposal would compound its own count.
- */
-export const LEARN_DIGEST_MARKER = "[learn-digest]";
+export { LEARN_DIGEST_MARKER } from "./mine.js";
 /** Sessions considered, newest first. */
 const DEFAULT_MAX_SESSIONS = 20;
 /** Sessions older than this are ignored — a pattern that stopped is not a rule. */
 const DEFAULT_MAX_AGE_DAYS = 30;
 /** Entries parsed per session file, as a guard against pathological transcripts. */
 const MAX_ENTRIES_PER_SESSION = 8000;
-/** Tool calls per session fed to the workflow detector. */
-const MAX_TOOL_CALLS_PER_SESSION = 400;
-/** How far forward the fix extractor looks for the same command succeeding. */
-const FIX_LOOKAHEAD = 40;
-/** Word overlap against an existing rule above which a directive counts as covered. */
-const COVERED_OVERLAP = 0.6;
+/** Occurrences a directive needs before it is proposed. */
+const DEFAULT_MIN_DIRECTIVE_COUNT = 2;
 /**
- * The same bar for skills, set higher on purpose.
+ * Sessions a request needs before it is worth proposing as a slash command.
  *
- * A rule is one line, so overlap against it is a sharp signal. A skill is a name
- * plus a description written to attract matches, which is a far larger haystack
- * — a short directive's words turn up in it by chance much more readily. The
- * higher bar and the truncation below keep "you already have a skill for this"
- * from being said on a coincidence.
+ * Higher than the directive bar. A rule you stated twice is a rule; a job you
+ * asked for twice may just be a job that came up twice. Three separate sessions
+ * is the point at which typing it again is the expensive option.
  */
-const SKILL_COVERED_OVERLAP = 0.75;
-/** Description characters considered. The opening says what a skill does; the rest is trigger bait. */
-const SKILL_DESCRIPTION_CHARS = 300;
-/** Directives must reach this many occurrences to be reported at all. */
-const DEFAULT_MIN_DIRECTIVE_COUNT = 2;
-/** Tool sequence lengths considered as workflow candidates. */
-const WORKFLOW_MIN_LEN = 3;
-const WORKFLOW_MAX_LEN = 5;
-/** Repeats before a tool sequence is worth proposing as a skill. */
-const DEFAULT_MIN_WORKFLOW_COUNT = 3;
+const DEFAULT_MIN_REQUEST_COUNT = 3;
 /** Cap on each list in the digest, so the model's budget goes to the top signals. */
 const DEFAULT_MAX_PER_CATEGORY = 8;
-function textOf(content) {
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    return content
-        .map((block) => block && typeof block === "object" && block.type === "text"
-        ? (block.text ?? "")
-        : "")
-        .join("\n")
-        .trim();
-}
-function isToolCall(block) {
-    return !!block && typeof block === "object" && block.type === "toolCall";
+/** Newest entry timestamp on the branch, falling back to when the session opened. */
+function lastActivityOf(entries, fallback) {
+    let latest = "";
+    for (const entry of entries) {
+        if (typeof entry.timestamp === "string" && entry.timestamp > latest)
+            latest = entry.timestamp;
+    }
+    return latest || fallback;
 }
 /**
  * Reduce a session's raw entries to the branch that was actually taken.
  *
  * Session files are trees — forks and clones append entries that were never
  * part of the same conversation. Walking parent links back from the last entry
- * keeps the extractor from stitching a "fix" out of two turns that never
- * happened in sequence. Sessions written before entry ids existed are flat, and
- * for those file order *is* the branch.
+ * keeps the miner from reading two turns that never happened in sequence as if
+ * they did. Sessions written before entry ids existed are flat, and for those
+ * file order *is* the branch.
  */
 function activeBranch(entries) {
     const withIds = entries.filter((e) => typeof e.id === "string");
@@ -169,11 +158,14 @@ function parseSessionFile(file, cwd, onSkip) {
         onSkip("unreadable");
         return undefined;
     }
+    const branch = activeBranch(entries);
+    const opened = header?.timestamp ?? statSync(file).mtime.toISOString();
     return {
         file,
         id: header?.id ?? file,
-        timestamp: header?.timestamp ?? statSync(file).mtime.toISOString(),
-        entries: activeBranch(entries),
+        timestamp: opened,
+        lastActivity: lastActivityOf(branch, opened),
+        entries: branch,
     };
 }
 /**
@@ -288,8 +280,9 @@ function listSessions(options) {
  * signal off the list.
  */
 function applySuppression(items, state, maxProposals, covered, onDeclined) {
-    if (!state)
-        return { kept: items.slice(0, maxProposals), suppressed: 0 };
+    if (!state) {
+        return { kept: items.slice(0, maxProposals), suppressed: 0, cut: Math.max(0, items.length - maxProposals) };
+    }
     const kept = [];
     let suppressed = 0;
     for (const item of items) {
@@ -302,15 +295,98 @@ function applySuppression(items, state, maxProposals, covered, onDeclined) {
             onDeclined?.(item);
         kept.push(item);
     }
-    return { kept: kept.slice(0, maxProposals), suppressed };
+    // Anything past the cap cleared every bar and lost on rank alone. It is not
+    // suppressed and it is not bookmarked, so it will be back next run — but a
+    // digest that silently shows eight of twenty reads as "twenty is all there
+    // was", and the reader tunes the wrong knob.
+    return { kept: kept.slice(0, maxProposals), suppressed, cut: Math.max(0, kept.length - maxProposals) };
 }
 /**
  * Where this cwd's sessions were found and what was passed over, without
- * ranking anything. `/learn stats` reports on the window without re-mining it.
+ * mining anything. `/learn settings` and `/learn stats` report on the window
+ * without paying for a model call.
  */
 export function scanSessions(options) {
     return listSessions(options).scan;
 }
+/**
+ * What a run would read, without reading it.
+ *
+ * Runs the real selection — the same age, cwd, cap and de-duplication rules
+ * `mineLearnDigest` applies — and then asks the cache about each survivor. It
+ * has to be the same selection: this number is what the confirmation prompt
+ * quotes, and a prompt that says twelve before reading three is worse than no
+ * prompt at all. Hashing the chosen files is cheap next to sending them to a
+ * model.
+ */
+export function planMining(options) {
+    const { sessions } = listSessions(options);
+    let cached = 0;
+    let pending = 0;
+    for (const session of sessions) {
+        const hash = hashSessionFile(session.file);
+        if (hash && readCachedMining(options.agentDir, hash))
+            cached++;
+        else
+            pending++;
+    }
+    return { total: sessions.length, cached, pending };
+}
+/**
+ * Name every candidate in the window in one place.
+ *
+ * The pass runs over the whole window at once rather than per session, which is
+ * the entire point: "is this the same point as that" is unanswerable from
+ * inside one transcript. Labels already on record are offered as vocabulary so
+ * an item you decided on keeps the key it was bookmarked under — without that,
+ * a renamed cluster reads as brand new and suppression quietly stops working.
+ *
+ * A failed call falls back to naming each candidate after its own wording,
+ * which groups identical sentences and nothing else. That is the behaviour the
+ * pipeline had before this stage existed, so a clustering outage costs recall,
+ * not the run.
+ */
+async function labelSessions(raw, clusterer, knownLabels, signal) {
+    const inputs = [];
+    const origin = [];
+    for (const [sessionIndex, session] of raw.entries()) {
+        for (const [candidateIndex, candidate] of session.candidates.entries()) {
+            inputs.push({ id: inputs.length, kind: candidate.kind, text: candidate.text });
+            origin.push({ session: sessionIndex, candidate: candidateIndex });
+        }
+    }
+    let labels = new Map();
+    if (clusterer && inputs.length > 0) {
+        try {
+            labels = await clusterer(inputs, knownLabels, signal);
+        }
+        catch {
+            // Fall through to per-text labels below.
+        }
+    }
+    const labelled = raw.map((session) => ({
+        sessionId: session.sessionId,
+        lastActivity: session.lastActivity,
+        candidates: [],
+    }));
+    for (const [index, input] of inputs.entries()) {
+        const where = origin[index];
+        const candidate = where ? raw[where.session]?.candidates[where.candidate] : undefined;
+        if (!where || !candidate)
+            continue;
+        labelled[where.session]?.candidates.push({
+            ...candidate,
+            label: labels.get(input.id) ?? fallbackLabel(input.text),
+        });
+    }
+    return labelled;
+}
+/** Labels already on record, so the naming pass can reuse rather than reinvent them. */
+function knownLabelsFrom(state) {
+    if (!state)
+        return [];
+    return Object.keys(state.surfaced).map((key) => key.slice(key.indexOf(":") + 1));
+}
 /** Nearest AGENTS.md walking up from cwd, so proposals can be checked against it. */
 function findAgentsFile(cwd) {
     let dir = resolve(cwd);
@@ -326,386 +402,50 @@ function findAgentsFile(cwd) {
         dir = parent;
     }
 }
-/** Pair tool calls with their results along one branch, in call order. */
-function toolEvents(entries) {
-    const byCallId = new Map();
-    const ordered = [];
-    for (const entry of entries) {
-        const message = entry.type === "message" ? entry.message : undefined;
-        if (!message)
-            continue;
-        if (message.role === "assistant") {
-            for (const block of (message.content ?? [])) {
-                if (!isToolCall(block))
-                    continue;
-                const event = { name: block.name, args: block.arguments ?? {} };
-                byCallId.set(block.id, event);
-                ordered.push(event);
-            }
-        }
-        else if (message.role === "toolResult") {
-            const event = byCallId.get(message.toolCallId);
-            if (!event)
-                continue;
-            event.isError = message.isError;
-            event.output = textOf(message.content);
-        }
-    }
-    return ordered;
-}
-/** User turns worth mining, in order, with the digest's own output excluded. */
-function userDirectives(entries) {
-    const out = [];
-    for (const entry of entries) {
-        const message = entry.type === "message" ? entry.message : undefined;
-        if (!message || message.role !== "user")
-            continue;
-        const text = textOf(message.content);
-        if (!text || text.startsWith(LEARN_DIGEST_MARKER))
-            continue;
-        if (!isRuleShapedDirective(text))
-            continue;
-        out.push(text.trim());
-    }
-    return out;
-}
-function clusterDirectives(perSession, coverage, minRepeats) {
-    const acc = new Map();
-    for (const { session, directives } of perSession) {
-        for (const text of directives) {
-            const normalized = normalizeDirective(text);
-            if (!normalized)
-                continue;
-            const existing = acc.get(normalized);
-            if (existing) {
-                existing.count++;
-                existing.sessions.add(session.id);
-                if (session.timestamp > existing.lastSeen)
-                    existing.lastSeen = session.timestamp;
-                if (text.length > existing.text.length)
-                    existing.text = text;
-            }
-            else {
-                acc.set(normalized, {
-                    text,
-                    normalized,
-                    count: 1,
-                    sessions: new Set([session.id]),
-                    lastSeen: session.timestamp,
-                });
-            }
-        }
-    }
-    const clusters = [];
-    for (const entry of acc.values()) {
-        if (entry.count < minRepeats)
-            continue;
-        // Everything reaching here cleared the repeat threshold. Suppression handles
-        // the case that used to make these labels lie — a proposal accepted from a
-        // previous run coming back as "not working" when nothing had happened
-        // since. By the time an item survives that filter, a match genuinely means
-        // you repeated yourself after the rule or skill already existed.
-        const match = matchCoverage(entry.text, coverage);
-        clusters.push({
-            key: `directive:${entry.normalized}`,
-            text: entry.text,
-            normalized: entry.normalized,
-            count: entry.count,
-            sessions: entry.sessions.size,
-            lastSeen: entry.lastSeen,
-            status: match.rule ? "restated" : match.skill ? "has-skill" : "new",
-            existingRule: match.rule,
-            existingSkill: match.skill,
-            previouslyDeclined: false,
-        });
-    }
-    return clusters.sort((a, b) => b.sessions - a.sessions || b.count - a.count || a.text.localeCompare(b.text));
-}
-/** Files a mutating tool touched, for the resolution summary. */
-function editedFile(event) {
-    if (!["edit", "write", "multi_edit", "apply_patch"].includes(event.name))
-        return undefined;
-    const path = event.args?.path ?? event.args?.file_path ?? event.args?.filePath;
-    return typeof path === "string" ? path : undefined;
-}
-function extractFixes(perSession) {
-    const acc = new Map();
-    for (const { session, events } of perSession) {
-        for (let i = 0; i < events.length; i++) {
-            const failure = events[i];
-            if (failure.name !== "bash" || !failure.isError)
-                continue;
-            const command = typeof failure.args?.command === "string" ? failure.args.command : "";
-            if (!command || isBenignFailure(command))
-                continue;
-            const normalized = normalizeCommand(command);
-            const interveningCommands = [];
-            const editedFiles = [];
-            let resolved = false;
-            for (let j = i + 1; j < Math.min(events.length, i + 1 + FIX_LOOKAHEAD); j++) {
-                const next = events[j];
-                const file = editedFile(next);
-                if (file)
-                    editedFiles.push(file);
-                if (next.name !== "bash")
-                    continue;
-                const nextCommand = typeof next.args?.command === "string" ? next.args.command : "";
-                if (!nextCommand)
-                    continue;
-                // The same command later succeeding is the only evidence that the
-                // problem was actually fixed. A *different* command passing says
-                // nothing, and neither does the model moving on.
-                if (normalizeCommand(nextCommand) === normalized && !next.isError) {
-                    resolved = true;
-                    break;
-                }
-                interveningCommands.push(nextCommand.trim());
-            }
-            if (!resolved)
-                continue;
-            const output = failure.output ?? "";
-            // An abort is the user changing their mind, not a problem that was
-            // solved, and empty output carries nothing to sign or show.
-            if (isUninformativeFailure(output))
-                continue;
-            // Sign the error region, not the whole output: build tools lead with an
-            // identical banner, so signing everything makes unrelated failures of
-            // the same command collide on their shared preamble.
-            const errorRegion = extractErrorRegion(output);
-            const signature = normalizeErrorSignature(errorRegion);
-            if (!signature)
-                continue;
-            const key = `${normalized}${signature}`;
-            const existing = acc.get(key);
-            if (existing) {
-                existing.candidate.count++;
-                existing.sessions.add(session.id);
-                if (session.timestamp > existing.candidate.lastSeen)
-                    existing.candidate.lastSeen = session.timestamp;
-            }
-            else {
-                acc.set(key, {
-                    sessions: new Set([session.id]),
-                    candidate: {
-                        key: `fix:${key}`,
-                        command: normalized,
-                        signature,
-                        errorExcerpt: errorRegion.replace(/\s+/g, " ").trim().slice(0, 240),
-                        interveningCommands: [...new Set(interveningCommands)].slice(0, 5),
-                        editedFiles: [...new Set(editedFiles)].slice(0, 5),
-                        count: 1,
-                        sessions: 1,
-                        lastSeen: session.timestamp,
-                    },
-                });
-            }
-        }
-    }
-    const out = [];
-    for (const { candidate, sessions } of acc.values()) {
-        candidate.sessions = sessions.size;
-        out.push(candidate);
-    }
-    return out.sort((a, b) => b.count - a.count || b.sessions - a.sessions || a.signature.localeCompare(b.signature));
-}
-/** A tool call reduced to a comparable step: the tool, plus what a bash call runs. */
-function stepSignature(event) {
-    if (event.name === "bash") {
-        const command = typeof event.args?.command === "string" ? event.args.command : "";
-        const head = commandHead(command);
-        return head ? `bash:${head}` : "bash";
-    }
-    return event.name;
-}
 /**
- * Commands that are how an agent looks around rather than what the user was
- * doing. A sequence built only from these plus file edits describes "coding",
- * not a workflow, and no useful skill has ever come out of one.
- */
-const PLUMBING_COMMANDS = new Set([
-    "cd",
-    "ls",
-    "pwd",
-    "cat",
-    "head",
-    "tail",
-    "wc",
-    "echo",
-    "which",
-    "find",
-    "fd",
-    "grep",
-    "rg",
-    "sed",
-    "awk",
-    "git status",
-    "git diff",
-    "git log",
-    "git show",
-]);
-/**
- * Whether a sequence is a procedure rather than the rhythm of editing code.
+ * Turn one context file into rule lines the coverage judge can reason about.
  *
- * Two distinct doing-commands is the bar, and it was set by looking at real
- * transcripts. One command is not enough: the edit/test loop
- * (`edit → edit → bash:npm run`) satisfies it, and because a sliding window
- * over a long alternating run produces every rotation of that cycle, it alone
- * filled all eight slots with `edit → npm run → edit`, `npm run → edit → edit`
- * and so on — one habit described eight ways.
+ * Headings were dropped and the lines under them sent bare, which asks the
+ * model to decide whether a proposal is in scope using text with the scope
+ * removed — "stage only your own files" reads very differently under "Git Rules
+ * for Parallel Agents" than on its own. So each line carries its heading path,
+ * and the scope it came from, since the corpus spans a repo file and two user
+ * ones and a rule's home decides who it binds.
  *
- * A procedure worth a skill chains *different* actions: test then commit then
- * push, build then tag then publish. Requiring two distinct ones keeps those and
- * drops the rhythm. The cost is real — a genuine one-command routine with setup
- * is missed — and that is the intended trade, since a missed skill costs nothing
- * while a digest full of noise costs the reader's attention every run.
+ * Fenced blocks go: a code sample illustrates a rule, it is not one, and on a
+ * real file it is a large share of the non-bullet text.
  */
-function isProcedure(steps) {
-    const commands = new Set();
-    for (const step of steps) {
-        if (!step.startsWith("bash:"))
+function ruleLinesOf(content, scope) {
+    const lines = [];
+    const headings = [];
+    let inFence = false;
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (line.startsWith("```")) {
+            inFence = !inFence;
             continue;
-        const head = step.slice("bash:".length);
-        if (PLUMBING_COMMANDS.has(head) || PLUMBING_COMMANDS.has(head.split(" ")[0] ?? ""))
-            continue;
-        commands.add(head);
-    }
-    return commands.size >= 2;
-}
-/** True when `needle` appears as a contiguous run inside `haystack`. */
-function containsSequence(haystack, needle) {
-    if (needle.length > haystack.length)
-        return false;
-    for (let i = 0; i + needle.length <= haystack.length; i++) {
-        if (needle.every((step, offset) => haystack[i + offset] === step))
-            return true;
-    }
-    return false;
-}
-function extractWorkflows(perSession, minRepeats) {
-    const acc = new Map();
-    for (const { session, events } of perSession) {
-        const steps = events.slice(0, MAX_TOOL_CALLS_PER_SESSION).map(stepSignature);
-        for (let len = WORKFLOW_MIN_LEN; len <= WORKFLOW_MAX_LEN; len++) {
-            // Collect every position first, then count greedily without overlap.
-            // Counting each sliding position separately treats one long stretch of
-            // edit/read churn as dozens of repeats: an `edit > read > edit` run of
-            // length 12 scores 10 occurrences when it is really one stretch of work.
-            const positions = new Map();
-            for (let i = 0; i + len <= steps.length; i++) {
-                const window = steps.slice(i, i + len);
-                // A run of one repeated tool is a loop, not a workflow.
-                if (new Set(window).size < 2)
-                    continue;
-                if (!isProcedure(window))
-                    continue;
-                const key = window.join(" > ");
-                const list = positions.get(key);
-                if (list)
-                    list.push(i);
-                else
-                    positions.set(key, [i]);
-            }
-            for (const [key, occurrences] of positions) {
-                let count = 0;
-                let nextFree = -1;
-                for (const start of occurrences) {
-                    if (start < nextFree)
-                        continue;
-                    count++;
-                    nextFree = start + len;
-                }
-                const existing = acc.get(key);
-                if (existing) {
-                    existing.count += count;
-                    existing.sessions.add(session.id);
-                    if (session.timestamp > existing.lastSeen)
-                        existing.lastSeen = session.timestamp;
-                }
-                else {
-                    acc.set(key, {
-                        steps: key.split(" > "),
-                        count,
-                        sessions: new Set([session.id]),
-                        lastSeen: session.timestamp,
-                    });
-                }
-            }
         }
-    }
-    const ranked = [...acc.values()]
-        .filter((entry) => entry.count >= minRepeats)
-        .map((entry) => ({
-        key: `workflow:${entry.steps.join(" > ")}`,
-        steps: entry.steps,
-        count: entry.count,
-        sessions: entry.sessions.size,
-        lastSeen: entry.lastSeen,
-    }))
-        // Sessions first, matching directives: a sequence seen in three sessions is
-        // a workflow, while one repeated ten times in a single session is usually
-        // just the shape of that one task.
-        .sort((a, b) => b.sessions - a.sessions ||
-        b.count - a.count ||
-        b.steps.length - a.steps.length ||
-        a.steps.join().localeCompare(b.steps.join()));
-    // Every n-gram overlaps its own extensions and prefixes, so without this the
-    // list is one workflow described five slightly different ways. The test runs
-    // both directions on purpose: a shorter sequence always outranks the longer
-    // one containing it (it occurs at least as often), so checking only
-    // shorter-inside-kept would never fire. Keep the best-ranked member of each
-    // family and drop the rest.
-    const distinct = [];
-    for (const candidate of ranked) {
-        const overlapsKept = distinct.some((kept) => containsSequence(kept.steps, candidate.steps) || containsSequence(candidate.steps, kept.steps));
-        if (overlapsKept)
+        if (inFence || line.length === 0)
+            continue;
+        const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (heading) {
+            const depth = heading[1]?.length ?? 1;
+            headings.length = Math.min(headings.length, depth - 1);
+            headings[depth - 1] = heading[2] ?? "";
             continue;
-        distinct.push(candidate);
-    }
-    return distinct;
-}
-/**
- * Where a piece of text is already written down, if anywhere.
- *
- * A rule wins over a skill when both match: it is the more specific answer, and
- * "rewrite this line" is more actionable than "sharpen a description".
- */
-export function matchCoverage(text, index) {
-    const words = contentWords(text);
-    let bestLine;
-    let bestOverlap = 0;
-    for (const line of index.ruleLines) {
-        const overlap = wordOverlap(words, line);
-        if (overlap > bestOverlap) {
-            bestOverlap = overlap;
-            bestLine = line;
-        }
-    }
-    if (bestOverlap >= COVERED_OVERLAP)
-        return { rule: bestLine };
-    let bestSkill;
-    let bestSkillOverlap = 0;
-    for (const skill of index.skills) {
-        const haystack = `${skill.name} ${skill.description.slice(0, SKILL_DESCRIPTION_CHARS)}`;
-        const overlap = wordOverlap(words, haystack);
-        if (overlap > bestSkillOverlap) {
-            bestSkillOverlap = overlap;
-            bestSkill = skill.name;
         }
+        const path = headings.filter(Boolean).join(" > ");
+        lines.push(path ? `[${scope}] ${path} > ${line}` : `[${scope}] ${line}`);
     }
-    if (bestSkillOverlap >= SKILL_COVERED_OVERLAP)
-        return { skill: bestSkill };
-    return {};
+    return lines;
 }
 /** Assemble the coverage index for a directory. */
 export function buildCoverageIndex(options) {
-    const corpus = coverageCorpus(options.agentDir, findAgentsFile(options.cwd));
-    return {
-        ruleLines: corpus
-            .split("\n")
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0 && !line.startsWith("#")),
-        skills: options.skills ?? loadSkillIndex(options.cwd, options.agentDir),
-    };
+    const ruleLines = [];
+    for (const file of coverageFiles(options.agentDir, findAgentsFile(options.cwd))) {
+        ruleLines.push(...ruleLinesOf(file.content, file.scope));
+    }
+    return { ruleLines, skills: options.skills ?? loadSkillIndex(options.cwd, options.agentDir) };
 }
 /**
  * Text a proposal is checked against to decide whether it is already written
@@ -715,19 +455,24 @@ export function buildCoverageIndex(options) {
  * user scope. Checking only the repo file would report a rule you accepted into
  * `~/.agents/AGENTS.md` as declined.
  */
-function coverageCorpus(agentDir, repoFile) {
-    const parts = [];
-    for (const candidate of [repoFile, join(getUserAgentsDir(), "AGENTS.md"), join(agentDir, "AGENTS.md")]) {
-        if (!candidate || !existsSync(candidate))
+function coverageFiles(agentDir, repoFile) {
+    const files = [];
+    const candidates = [
+        { scope: "repo", path: repoFile },
+        { scope: "user", path: join(getUserAgentsDir(), "AGENTS.md") },
+        { scope: "user", path: join(agentDir, "AGENTS.md") },
+    ];
+    for (const candidate of candidates) {
+        if (!candidate.path || !existsSync(candidate.path))
             continue;
         try {
-            parts.push(readFileSync(candidate, "utf-8"));
+            files.push({ scope: candidate.scope, content: readFileSync(candidate.path, "utf-8") });
         }
         catch {
             // Unreadable context file: treat as absent rather than failing the run.
         }
     }
-    return parts.join("\n");
+    return files;
 }
 /**
  * Skills a proposal could already have become.
@@ -750,8 +495,80 @@ function loadSkillIndex(cwd, agentDir) {
         return [];
     }
 }
+/**
+ * Run the miner over the window, reusing cached results wherever the file has
+ * not changed.
+ *
+ * A session that fails to mine is counted and skipped rather than aborting the
+ * run: one provider hiccup on one transcript should cost that transcript's
+ * signals, not the whole digest. The failure count is reported so the reader
+ * knows the numbers are short.
+ *
+ * Cancellation is different from failure and is reported separately. A run
+ * stopped half way has counted only some of the window, so its numbers are not
+ * merely short — they are wrong in a way that would poison the bookmark if the
+ * digest were treated as a completed run.
+ */
+async function mineSessions(sessions, options) {
+    const mined = [];
+    const report = { cached: 0, mined: 0, failed: 0 };
+    let done = 0;
+    for (const session of sessions) {
+        if (options.signal?.aborted)
+            return { mined, report, aborted: true };
+        const hash = hashSessionFile(session.file);
+        const cached = hash ? readCachedMining(options.agentDir, hash) : undefined;
+        if (cached) {
+            mined.push({ sessionId: session.id, lastActivity: session.lastActivity, candidates: cached.candidates });
+            report.cached++;
+            done++;
+            options.onProgress?.({ done, total: sessions.length, cached: report.cached });
+            continue;
+        }
+        const minable = { id: session.id, timestamp: session.timestamp, entries: session.entries };
+        try {
+            const candidates = await options.miner(minable, options.signal);
+            mined.push({ sessionId: session.id, lastActivity: session.lastActivity, candidates });
+            report.mined++;
+            if (hash) {
+                writeCachedMining(options.agentDir, hash, {
+                    sessionId: session.id,
+                    timestamp: session.timestamp,
+                    candidates,
+                    minedAt: new Date().toISOString(),
+                });
+            }
+        }
+        catch {
+            // A cancelled request surfaces here as a rejection. That is not the
+            // provider failing on this transcript, so it must not be counted as one.
+            if (options.signal?.aborted)
+                return { mined, report, aborted: true };
+            report.failed++;
+        }
+        done++;
+        options.onProgress?.({ done, total: sessions.length, cached: report.cached });
+    }
+    return { mined, report, aborted: false };
+}
+/** Apply the coverage verdicts to the clusters they were asked about. */
+function applyCoverage(directives, verdicts) {
+    for (const cluster of directives) {
+        const verdict = verdicts.get(cluster.label);
+        if (!verdict)
+            continue;
+        if (verdict.rule) {
+            cluster.status = "restated";
+            cluster.existingRule = verdict.rule;
+        }
+        else if (verdict.skill) {
+            cluster.status = "has-skill";
+            cluster.existingSkill = verdict.skill;
+        }
+    }
+}
 /** Mine the recent sessions for this cwd and return the ranked digest. */
-export function extractLearnDigest(options) {
+export async function mineLearnDigest(options) {
     const { sessions, skipped, scan } = listSessions(options);
     const agentsFilePath = findAgentsFile(options.cwd);
     let agentsContent;
@@ -763,39 +580,83 @@ export function extractLearnDigest(options) {
             agentsContent = undefined;
         }
     }
+    const { mined, report, aborted } = await mineSessions(sessions, options);
+    pruneLearnCache(options.agentDir, options.now);
+    const state = options.ignoreState ? undefined : options.state;
+    // Named against the labels already on record — including in `all` mode, where
+    // suppression is off but the bookmark still has to line up next run.
+    const labelled = await labelSessions(mined, options.clusterer, knownLabelsFrom(options.state), options.signal);
+    const minRepeats = options.minRepeats ?? DEFAULT_MIN_DIRECTIVE_COUNT;
+    const maxProposals = options.maxProposals ?? DEFAULT_MAX_PER_CATEGORY;
+    const directives = reduceDirectives(labelled, minRepeats);
+    const fixes = reduceFixes(labelled, minRepeats);
+    const requests = reduceRequests(labelled, options.minRequestRepeats ?? DEFAULT_MIN_REQUEST_COUNT);
+    // Counted with the threshold at 1, which is the same reduce over the same
+    // input — so the difference is exactly what the threshold cost, rather than an
+    // estimate of it.
+    const everyPoint = reduceDirectives(labelled, 1).length + reduceFixes(labelled, 1).length + reduceRequests(labelled, 1).length;
+    const funnel = {
+        candidates: labelled.reduce((sum, session) => sum + session.candidates.length, 0),
+        points: everyPoint,
+        belowThreshold: everyPoint - directives.length - fixes.length - requests.length,
+    };
+    // Coverage is asked only about what survived the repeat threshold. Judging
+    // everything would mean sending the context file alongside a long tail of
+    // one-off observations that are never going to be proposed.
     const coverage = buildCoverageIndex({ cwd: options.cwd, agentDir: options.agentDir, skills: options.skills });
-    const withDirectives = sessions.map((session) => ({ session, directives: userDirectives(session.entries) }));
-    const withEvents = sessions.map((session) => ({ session, events: toolEvents(session.entries) }));
+    const queries = directives.map((d) => ({ label: d.label, text: d.text }));
+    let coverageFailed = false;
+    try {
+        const verdicts = await (options.coverageJudge ?? noCoverageJudge)(queries, coverage, options.signal);
+        applyCoverage(directives, verdicts);
+    }
+    catch {
+        // A failed coverage call leaves everything `new`, which over-proposes
+        // slightly. That is the right way to fail: the reader can reject a
+        // duplicate, but cannot recover a proposal that was wrongly withheld. What
+        // must not happen is writing that guess down as if it were a reading.
+        coverageFailed = true;
+    }
     const timestamps = sessions.map((s) => s.timestamp).sort();
-    const state = options.ignoreState ? undefined : options.state;
     // Directives carry a real coverage signal — is this written down as a rule or
     // a skill right now? — which is what separates an adopted proposal from a
-    // declined one. Fixes and workflows do not: a fix may have become a rule, a
+    // declined one. Fixes and requests do not: a fix may have become a rule, a
     // skill, or a habit, and which one is not recoverable here, so they get
     // suppression only and are never labelled declined.
-    const maxProposals = options.maxProposals ?? DEFAULT_MAX_PER_CATEGORY;
-    const directives = applySuppression(clusterDirectives(withDirectives, coverage, options.minRepeats ?? DEFAULT_MIN_DIRECTIVE_COUNT), state, maxProposals, (item) => item.status !== "new", (item) => {
+    const keptDirectives = applySuppression(directives, state, maxProposals, (item) => item.status !== "new", (item) => {
         item.previouslyDeclined = true;
     });
-    const fixes = applySuppression(extractFixes(withEvents), state, maxProposals, () => false);
-    const workflows = applySuppression(extractWorkflows(withEvents, options.minWorkflowRepeats ?? DEFAULT_MIN_WORKFLOW_COUNT), state, maxProposals, () => false);
+    const keptFixes = applySuppression(fixes, state, maxProposals, () => false);
+    const keptRequests = applySuppression(requests, state, maxProposals, () => false);
     const surfaced = [
-        ...directives.kept.map((d) => ({ key: d.key, lastSeen: d.lastSeen, covered: d.status !== "new" })),
-        ...fixes.kept.map((f) => ({ key: f.key, lastSeen: f.lastSeen, covered: false })),
-        ...workflows.kept.map((w) => ({ key: w.key, lastSeen: w.lastSeen, covered: false })),
+        // Directives carry their wording forward so a later `/learn stats` can ask
+        // about coverage using the sentence rather than the slug that names it.
+        ...keptDirectives.kept.map((d) => ({
+            key: d.key,
+            lastSeen: d.lastSeen,
+            covered: d.status !== "new",
+            text: d.text,
+        })),
+        ...keptFixes.kept.map((f) => ({ key: f.key, lastSeen: f.lastSeen, covered: false })),
+        ...keptRequests.kept.map((r) => ({ key: r.key, lastSeen: r.lastSeen, covered: false })),
     ];
     return {
         scannedSessions: sessions.length,
         skippedSessions: skipped,
         scan,
+        mining: report,
+        aborted,
+        coverageFailed,
         oldestSession: timestamps[0],
         newestSession: timestamps[timestamps.length - 1],
         agentsFilePath,
         agentsFileTokens: agentsContent === undefined ? undefined : Math.round(Buffer.byteLength(agentsContent, "utf-8") / 4),
-        directives: directives.kept,
-        fixes: fixes.kept,
-        workflows: workflows.kept,
-        suppressed: directives.suppressed + fixes.suppressed + workflows.suppressed,
+        directives: keptDirectives.kept,
+        fixes: keptFixes.kept,
+        requests: keptRequests.kept,
+        suppressed: keptDirectives.suppressed + keptFixes.suppressed + keptRequests.suppressed,
+        cut: keptDirectives.cut + keptFixes.cut + keptRequests.cut,
+        funnel,
         surfaced,
     };
 }