@davesheffer/hunch 1.42.0 → 1.44.0

package/dist/core/docanchors.d.ts

@@ -22,9 +22,18 @@ export interface DocAnchor {
     line: number;
 }
 /** Parse every hunch:topic marker out of a markdown document. Markers inside
- *  fenced code blocks or inline code spans are examples, not declarations,
- *  and are skipped. */
+ *  code blocks or inline code spans are examples, not declarations, and are
+ *  skipped. */
 export declare function parseDocAnchors(text: string): DocAnchor[];
+/** parseDocAnchors plus what drift reports about the document: a fence that
+ *  never closes hides every marker below it, almost always by mistake (#381). */
+export declare function scanDocAnchors(text: string): {
+    anchors: DocAnchor[];
+    unclosedFence: {
+        line: number;
+        hidden: number;
+    } | null;
+};
 /** Pre-edit grounding for a markdown document that carries topic anchors: the
  *  CURRENT decision per declared topic (graph over prose), what it rejected,
  *  and a stale-pin warning the editor can heal inline. Empty when no anchor

package/dist/core/docanchors.js

@@ -58,14 +58,18 @@ function thematicBreakSuffixes(probe) {
     }
     return ok;
 }
-/** Character ranges covered by fenced code blocks (``` or ~~~), so a
- *  documentation EXAMPLE of a marker never registers as a live anchor.
- *  CommonMark-lite: a fence of N chars (≤3 leading spaces) closes only on a
- *  line of ≥N of the same char and nothing else; an unclosed fence runs to
- *  EOF; a backtick fence's info string may not itself contain a backtick.
- *  The "≤3 leading spaces" is measured relative to the enclosing LIST ITEM's
- *  content offset, so a fence indented under `1. step` (issue #331) is still a
- *  fence and not an indented code block.
+/** Character ranges covered by code blocks — fenced (``` or ~~~) and indented —
+ *  so a documentation EXAMPLE of a marker never registers as a live anchor.
+ *  A hand scanner, not a markdown parser: it answers only "is this offset inside
+ *  code as a renderer shows it?", line by line and linear in each line's length.
+ *
+ *  Fences, CommonMark-lite: a fence of N chars (≤3 leading spaces) closes only on
+ *  a line of ≥N of the same char and nothing else; an unclosed fence runs to EOF
+ *  (reported as `unclosed`, which drift surfaces — issue #381); a backtick
+ *  fence's info string may not itself contain a backtick. The "≤3 leading
+ *  spaces" is measured relative to the enclosing LIST ITEM's content offset, so a
+ *  fence indented under `1. step` (issue #331) is still a fence and not an
+ *  indented code block.
  *
  *  A fence hosted in a list item ends where the ITEM ends: at the first
  *  non-blank line dedented below the item's content base. That is what the
@@ -75,134 +79,286 @@ function thematicBreakSuffixes(probe) {
  *  reader sees, not with the author's intent. In sloppy docs that differs from
  *  a flat fence scan; the rendering is the tiebreaker.
  *
+ *  Also as a renderer reads them (issue #381):
+ *  - indented code: ≥4 columns past the container's content, not continuing a
+ *    paragraph, runs until a line dedents below that (blank lines inside it);
+ *  - blockquotes: `>` prefixes are peeled first, so `> ```` opens a fence inside
+ *    the quote, and a line that leaves the quote ends it;
+ *  - HTML blocks (CommonMark types 1–6: script/pre/style/textarea, comments,
+ *    `<?`, `<!X`, CDATA, block-level tags): their lines are raw HTML, so a ``` or
+ *    an indented line inside one opens no code block. A marker inside an HTML
+ *    block stays LIVE: it is an HTML comment there too, not shown as an example;
+ *  - lazy continuation: a paragraph line dedented out of its list item or quote
+ *    that starts no block of its own keeps that item/quote open.
+ *
  *  Tabs expand to the next 4-column tab stop (not a flat 4), so `\t``` ` sits
  *  at column 4 exactly as a renderer places it. Offsets always come from the
  *  ORIGINAL line, never from the expanded probe.
  *
- *  Deliberate limits: no lazy continuations and no blockquote containers — a
- *  `>` prefix is still read as ordinary text. With no list open the item stack
- *  is empty, the base is 0 and behaviour is the plain CommonMark-lite one.
- *  Expects LF-normalized text — see parseDocAnchors's normalization; a caller
- *  that skips it re-opens the CRLF fence-detection bug. */
-function fencedRanges(text) {
-    const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+ *  Deliberate limits, each a case where it can still disagree with a renderer:
+ *  HTML block type 7 (a lone arbitrary tag line) reads as text; a blockquote
+ *  nested INSIDE a list item is read as a top-level quote; after a tab right
+ *  after a `>`, later tabs on that line expand from the quote's content, not
+ *  the line. With no container
+ *  open the base is 0 and behaviour is the plain CommonMark-lite one.
+ *  Expects LF-normalized, BOM-free text — see parseDocAnchors's normalization;
+ *  a caller that skips it re-opens the CRLF fence-detection bug. */
+function codeRanges(text) {
     const ranges = [];
     let open = null;
-    // Content offsets (columns) of the currently open list items, outermost first.
+    // Open list items, outermost first: the quote depth each lives in and its content column.
     const items = [];
+    let curQ = 0; // quote depth of the current block
     let offset = 0;
+    let lineNo = 0;
     // Whether the previous line was a paragraph-continuation line: non-blank,
     // and not itself a container/leaf opener. Only a bullet or a `1.`/`1)` with
     // non-empty content may interrupt such a paragraph (CommonMark), so prose
     // like "see item\n2. the second point" stays one paragraph.
     let inParagraph = false;
+    const closeOpen = (lineStart) => {
+        if (open?.kind === "fence")
+            ranges.push([open.start, lineStart - 1]);
+        else if (open?.kind === "indent")
+            ranges.push([open.start, open.end]);
+        open = null;
+    };
     for (const line of text.split("\n")) {
+        lineNo++;
+        const lineStart = offset;
+        offset += line.length + 1;
         // Matching-only copy: tabs advance to the next 4-column tab stop.
         const probe = expandTabs(line);
-        const indent = probe.length - probe.replace(/^ +/, "").length;
-        const blank = probe.trim() === "";
         if (open) {
-            if (!blank && indent < open.base) {
-                // The list item holding the fence ended, which ends the fence too.
-                ranges.push([open.start, offset - 1]);
-                open = null;
+            const held = peelQuotes(probe, open.q);
+            if (held.q < open.q) {
+                closeOpen(lineStart); // the quote holding the block ended, which ends the block too
             }
             else {
-                const m = FENCE.exec(probe.slice(Math.min(open.base, indent)));
-                if (m && m[1][0] === open.ch && m[1].length >= open.len && m[2].trim() === "") {
-                    ranges.push([open.start, offset + line.length]);
-                    open = null;
+                const rest = held.rest;
+                const indent = leadingSpaces(rest);
+                const blank = rest.trim() === "";
+                if (open.kind === "fence") {
+                    if (!blank && indent < open.base) {
+                        closeOpen(lineStart); // the list item holding the fence ended, which ends the fence too
+                    }
+                    else {
+                        const m = FENCE.exec(rest.slice(Math.min(open.base, indent)));
+                        if (m && m[1][0] === open.ch && m[1].length >= open.len && m[2].trim() === "") {
+                            ranges.push([open.start, lineStart + line.length]);
+                            open = null;
+                        }
+                        continue; // the container stacks are frozen while a fence is open
+                    }
+                }
+                else if (open.kind === "indent") {
+                    if (blank)
+                        continue;
+                    if (indent >= open.base + 4) {
+                        open.end = lineStart + line.length;
+                        continue;
+                    }
+                    closeOpen(lineStart);
+                }
+                else {
+                    if (open.end === "blank" ? blank : open.end.test(rest)) {
+                        open = null;
+                        inParagraph = false;
+                    }
+                    continue;
                 }
-                offset += line.length + 1;
-                continue; // the item stack is frozen while a fence is open
             }
         }
-        if (blank) {
-            offset += line.length + 1;
+        const { q, rest } = peelQuotes(probe, Infinity);
+        const indent = leadingSpaces(rest);
+        if (rest.trim() === "") {
+            while (items.length && items.at(-1).q > q)
+                items.pop();
+            curQ = q;
             inParagraph = false;
             continue; // a blank line neither opens nor closes an item here
         }
+        const isBreak = thematicBreakSuffixes(rest);
+        // Lazy continuation: a paragraph line that falls out of its item or quote but
+        // starts no block of its own still belongs to that paragraph, so every
+        // container stays open (`- foo\nbar` — bar is item text).
+        const top = items.at(-1);
+        const leaves = q < curQ || (top !== undefined && top.q === q && top.base > indent);
+        if (inParagraph && leaves && !startsBlock(rest, indent, isBreak))
+            continue;
         // A dedent that closes an item also closes the paragraph inside it, so the
         // line is a fresh block start: `1. one\n2. two` is two sibling items, not
         // item one's paragraph being "interrupted" by a `2.`.
-        let popped = false;
-        while (items.length && items.at(-1) > indent) {
+        let popped = q !== curQ;
+        while (items.length && (items.at(-1).q !== q || items.at(-1).base > indent)) {
             items.pop();
             popped = true;
         }
-        const isBreak = thematicBreakSuffixes(probe);
+        curQ = q;
         // Walk the line with an INDEX, peeling one list marker per step. Each step
         // is O(marker) and the cheap checks are O(1), so a line costs O(length)
         // however many markers it carries.
-        let base = items.at(-1) ?? 0;
+        let base = items.at(-1)?.base ?? 0;
         let opened = false;
         let thematic = false;
+        let indented = false;
+        let at = base;
         for (;;) {
             // Leading spaces of this nesting level: ≤3, else it is indented content
             // (and `    ---` is paragraph text or code, never a thematic break).
             let i = base;
-            while (i < probe.length && probe[i] === " " && i - base < 4)
+            while (i < rest.length && rest[i] === " " && i - base < 4)
                 i++;
-            const lead = i - base;
-            if (lead > 3)
+            at = i;
+            if (i - base > 3) {
+                indented = true;
                 break;
+            }
             if (isBreak[i]) {
                 thematic = true;
                 break;
             } // thematic break, not a list marker
-            const c = probe[i];
+            const c = rest[i];
             let markerLen = 0;
             if (c === "-" || c === "*" || c === "+")
                 markerLen = 1;
             else if (c !== undefined && c >= "0" && c <= "9") {
                 let d = i;
-                while (d < probe.length && probe[d] >= "0" && probe[d] <= "9" && d - i < 9)
+                while (d < rest.length && rest[d] >= "0" && rest[d] <= "9" && d - i < 9)
                     d++;
-                if (probe[d] === "." || probe[d] === ")")
+                if (rest[d] === "." || rest[d] === ")")
                     markerLen = d - i + 1;
             }
             if (!markerLen)
                 break;
             // Spaces between the marker and the item's content.
             let s = i + markerLen;
-            while (s < probe.length && probe[s] === " ")
+            while (s < rest.length && rest[s] === " ")
                 s++;
             const gap = s - (i + markerLen);
-            const emptyItem = s >= probe.length;
+            const emptyItem = s >= rest.length;
             if (!emptyItem && gap === 0)
                 break; // `-foo` / `1.foo` is not a marker
             if (!opened && !popped && inParagraph && items.length === 0) {
                 // Interrupting a paragraph: only a bullet, or `1.`/`1)`, and never with
                 // empty content. `2. the second point` mid-prose stays paragraph text.
-                const ordinal = markerLen > 1 ? probe.slice(i, i + markerLen - 1) : "";
+                const ordinal = markerLen > 1 ? rest.slice(i, i + markerLen - 1) : "";
                 if (emptyItem || (ordinal !== "" && ordinal !== "1"))
                     break;
             }
             // ≥5 spaces after the marker starts an indented code block, so the
             // item's content begins one column after the marker instead.
             const w = gap >= 1 && gap <= 4 ? gap : 1;
-            base = base + lead + markerLen + w;
-            items.push(base);
+            base = i + markerLen + w;
+            items.push({ q, base });
             opened = true;
             continue; // `- 1. x` nests, and "- ```js" opens a fence on the marker line
         }
-        const m = FENCE.exec(probe.slice(base));
+        if (indented) {
+            // An indented code block cannot interrupt a paragraph: there it is text.
+            if (!inParagraph || opened) {
+                open = { kind: "indent", start: lineStart, end: lineStart + line.length, base, q };
+                inParagraph = false;
+            }
+            continue;
+        }
+        const content = rest.slice(at);
+        const html = htmlBlockEnd(content);
+        if (html) {
+            if (html === "blank" || !html.test(content))
+                open = { kind: "html", end: html, q };
+            inParagraph = false;
+            continue;
+        }
+        const m = FENCE.exec(rest.slice(base));
         if (m) {
             const ch = m[1][0];
             if (!(ch === "`" && m[2].includes("`")))
-                open = { ch, len: m[1].length, start: offset, base };
+                open = { kind: "fence", ch, len: m[1].length, start: lineStart, base, q, line: lineNo };
         }
-        // A fence line or a thematic break ends the paragraph it follows; ordinary
+        // A fence line, a thematic break or a heading (ATX, or a `===` setext
+        // underline beneath a paragraph) ends the paragraph it follows; ordinary
         // text (including an item's own content) continues or starts one.
-        inParagraph = !m && !thematic;
-        offset += line.length + 1;
+        const setext = inParagraph && /^=+[ \t]*$/.test(content);
+        inParagraph = !m && !thematic && !setext && content.trim() !== "" && !/^#{1,6}(?:[ \t]|$)/.test(content);
     }
-    if (open)
-        ranges.push([open.start, text.length]);
-    return ranges;
+    let unclosed = null;
+    const last = open;
+    if (last?.kind === "fence") {
+        ranges.push([last.start, text.length]);
+        unclosed = { start: last.start, line: last.line };
+    }
+    else if (last?.kind === "indent")
+        ranges.push([last.start, last.end]);
+    return { ranges, unclosed };
+}
+const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const leadingSpaces = (s) => s.length - s.replace(/^ +/, "").length;
+/** Peel up to `max` blockquote markers (`>`, ≤3 spaces before it, one optional
+ *  space after) off a tab-expanded line: the quote depth and what follows. */
+function peelQuotes(probe, max) {
+    let q = 0;
+    let i = 0;
+    let col = 0;
+    let pad = 0;
+    while (q < max) {
+        let j = i;
+        while (j < probe.length && probe[j] === " " && j - i < 3)
+            j++;
+        if (probe[j] !== ">")
+            break;
+        col += j - i + 1;
+        i = j + 1;
+        pad = 0;
+        if (probe[i] === " ") {
+            i++;
+            col++;
+        }
+        else if (probe[i] === "\t") {
+            // The tab's first column is the quote's optional space; the rest of it is
+            // content indentation (CommonMark 5.1). `>\t<!-- … -->` is a paragraph, not code.
+            const width = 4 - (col % 4);
+            i++;
+            col += width;
+            pad = width - 1;
+        }
+        q++;
+    }
+    return q ? { q, rest: " ".repeat(pad) + expandTabs(probe.slice(i)) } : { q, rest: probe };
+}
+/** Whether a line (≤3 columns in) opens a block of its own, which a lazy
+ *  continuation line by definition does not. */
+function startsBlock(rest, indent, isBreak) {
+    if (indent > 3)
+        return false;
+    const s = rest.slice(indent);
+    return isBreak[indent] === true || FENCE.test(rest) || /^#{1,6}(?:[ \t]|$)/.test(s) || s[0] === ">"
+        || htmlBlockEnd(s) !== null || /^(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)/.test(s);
+}
+const HTML_BLOCK_TAGS = new Set(("address article aside base basefont blockquote body caption center col colgroup dd details dialog dir div dl dt "
+    + "fieldset figcaption figure footer form frame frameset h1 h2 h3 h4 h5 h6 head header hr html iframe legend li link main menu menuitem "
+    + "nav noframes ol optgroup option p param search section summary table tbody td tfoot th thead title tr track ul").split(" "));
+/** The end condition of the HTML block (CommonMark types 1–6) a line opens:
+ *  a pattern that closes it on a later (or the same) line, "blank" for a block
+ *  that runs to the next blank line, or null when the line opens none. */
+function htmlBlockEnd(s) {
+    if (s[0] !== "<")
+        return null;
+    if (/^<(?:script|pre|style|textarea)(?:[\s>]|$)/i.test(s))
+        return /<\/(?:script|pre|style|textarea)>/i;
+    if (s.startsWith("<!--"))
+        return /-->/;
+    if (s.startsWith("<?"))
+        return /\?>/;
+    if (s.startsWith("<![CDATA["))
+        return /\]\]>/;
+    if (/^<![A-Za-z]/.test(s))
+        return />/;
+    const tag = /^<\/?([A-Za-z][A-Za-z0-9-]*)(?:[\s>]|\/>|$)/.exec(s);
+    return tag && HTML_BLOCK_TAGS.has(tag[1].toLowerCase()) ? "blank" : null;
 }
 /** Character ranges covered by inline code spans (`…`), same rationale as
- *  fencedRanges: prose quoting a marker in backticks is showing an example.
+ *  codeRanges: prose quoting a marker in backticks is showing an example.
  *  CommonMark-lite: an opener run pairs with the next run of the SAME length
  *  on the same line; unpaired runs never open a span.
  *  Expects LF-normalized text — see parseDocAnchors's normalization.
@@ -229,28 +385,39 @@ function inlineSpanRanges(text) {
     return ranges;
 }
 /** Parse every hunch:topic marker out of a markdown document. Markers inside
- *  fenced code blocks or inline code spans are examples, not declarations,
- *  and are skipped. */
+ *  code blocks or inline code spans are examples, not declarations, and are
+ *  skipped. */
 export function parseDocAnchors(text) {
-    // fencedRanges is CRLF-sensitive (its fence-line regex's `.` excludes \r, so
+    return scanDocAnchors(text).anchors;
+}
+/** parseDocAnchors plus what drift reports about the document: a fence that
+ *  never closes hides every marker below it, almost always by mistake (#381). */
+export function scanDocAnchors(text) {
+    // codeRanges is CRLF-sensitive (its fence-line regex's `.` excludes \r, so
     // "```\r" never matched at all on a CRLF checkout); inlineSpanRanges is
     // lone-CR-sensitive (split("\n") doesn't split a bare CR — see its
     // docblock). Either way an example marker inside a fence/span registered as
     // a live, pinned anchor. Normalizing both CRLF and lone CR once here keeps
-    // fencedRanges/inlineSpanRanges/MARKER offsets consistent with each other
-    // and with the line numbers reported below.
-    text = normalizeEol(text);
-    const out = [];
-    const skip = [...fencedRanges(text), ...inlineSpanRanges(text)];
+    // codeRanges/inlineSpanRanges/MARKER offsets consistent with each other
+    // and with the line numbers reported below. A leading BOM is dropped too, so
+    // line 1 starts at column 0 (#381); it is one char on line 1, so line numbers hold.
+    text = normalizeEol(text).replace(/^\uFEFF/, "");
+    const anchors = [];
+    const code = codeRanges(text);
+    const skip = [...code.ranges, ...inlineSpanRanges(text)];
+    let hidden = 0;
     MARKER.lastIndex = 0;
     let m;
     while ((m = MARKER.exec(text))) {
         const at = m.index;
-        if (skip.some(([s, e]) => at >= s && at <= e))
+        if (skip.some(([s, e]) => at >= s && at <= e)) {
+            if (code.unclosed && at > code.unclosed.start)
+                hidden++;
             continue;
-        out.push({ topic: m[1], pin: m[2] ?? null, line: text.slice(0, at).split("\n").length });
+        }
+        anchors.push({ topic: m[1], pin: m[2] ?? null, line: text.slice(0, at).split("\n").length });
     }
-    return out;
+    return { anchors, unclosedFence: code.unclosed && hidden ? { line: code.unclosed.line, hidden } : null };
 }
 const clip = (s, n = 220) => (s.length > n ? s.slice(0, n - 1).trimEnd() + "…" : s);
 /** Pre-edit grounding for a markdown document that carries topic anchors: the

package/dist/core/drift.d.ts

@@ -1,5 +1,5 @@
 import type { HunchStore } from "../store/hunchStore.js";
-export declare const DRIFT_KINDS: readonly ["dead-ref", "supersede", "doc-stale", "anchor-stale", "doc-anchor-stale", "doc-anchor-dangling", "wiki-stale", "finding-stale", "premise-stale", "commit-unresolvable", "madr-stale", "madr-edited", "madr-orphan"];
+export declare const DRIFT_KINDS: readonly ["dead-ref", "supersede", "doc-stale", "anchor-stale", "doc-anchor-stale", "doc-anchor-dangling", "doc-fence-unclosed", "wiki-stale", "finding-stale", "premise-stale", "commit-unresolvable", "madr-stale", "madr-edited", "madr-orphan"];
 export type DriftKind = typeof DRIFT_KINDS[number];
 export interface DriftFinding {
     kind: DriftKind;

package/dist/core/drift.js

@@ -22,12 +22,12 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { toPosixTarget } from "./paths.js";
 import { currentForTopic, isLive } from "./topics.js";
 import { evaluatePremises } from "./premises.js";
-import { parseDocAnchors } from "./docanchors.js";
+import { scanDocAnchors } from "./docanchors.js";
 import { markdownDocs, STALE_MARKER, SRC_REF } from "./docscan.js";
 import { computeWikiDrift } from "../wiki/wiki.js";
 import { computeMadrDrift } from "../integrations/madrManifest.js";
 import { commitsExist, isGitRepo } from "../extractors/git.js";
-export const DRIFT_KINDS = ["dead-ref", "supersede", "doc-stale", "anchor-stale", "doc-anchor-stale", "doc-anchor-dangling", "wiki-stale", "finding-stale", "premise-stale", "commit-unresolvable", "madr-stale", "madr-edited", "madr-orphan"];
+export const DRIFT_KINDS = ["dead-ref", "supersede", "doc-stale", "anchor-stale", "doc-anchor-stale", "doc-anchor-dangling", "doc-fence-unclosed", "wiki-stale", "finding-stale", "premise-stale", "commit-unresolvable", "madr-stale", "madr-edited", "madr-orphan"];
 export function computeDrift(store, root, deps = {}) {
     const findings = [];
     const decisions = store.recs("decisions");
@@ -157,7 +157,14 @@ export function computeDrift(store, root, deps = {}) {
         //    been superseded (doc-anchor-stale, the CI-gateable one) or that doesn't
         //    exist (doc-anchor-dangling). Unpinned markers only ground the pre-edit
         //    hook — an explicit pin is the ONLY thing that can fire drift here.
-        for (const a of parseDocAnchors(text)) {
+        //    A fence that never closes hides every marker below it (doc-fence-unclosed,
+        //    advisory): almost always an authoring mistake that disables real anchors.
+        const scan = scanDocAnchors(text);
+        if (scan.unclosedFence) {
+            const { line, hidden } = scan.unclosedFence;
+            findings.push({ kind: "doc-fence-unclosed", id: doc.rel, detail: `fence opened at line ${line} never closes; ${hidden} marker(s) below it are hidden` });
+        }
+        for (const a of scan.anchors) {
             if (!a.pin)
                 continue;
             const pinned = byId.get(a.pin);

package/dist/core/eol.d.ts

@@ -2,6 +2,8 @@
 export declare function normalizeEol(text: string): string;
 /** Remove the CR retained by split("\n") without changing source offsets. */
 export declare function lineContent(line: string): string;
+/** Length of the line break (CRLF, CR, or LF) starting at `at`, or 0. */
+export declare function eolLengthAt(text: string, at: number): number;
 /** Read logical lines while keeping offsets in the original UTF-16 source. */
 export declare function sourceLines(text: string): Generator<{
     content: string;

package/dist/core/eol.js

@@ -6,6 +6,12 @@ export function normalizeEol(text) {
 export function lineContent(line) {
     return line.endsWith("\r") ? line.slice(0, -1) : line;
 }
+/** Length of the line break (CRLF, CR, or LF) starting at `at`, or 0. */
+export function eolLengthAt(text, at) {
+    if (text[at] === "\r")
+        return text[at + 1] === "\n" ? 2 : 1;
+    return text[at] === "\n" ? 1 : 0;
+}
 /** Read logical lines while keeping offsets in the original UTF-16 source. */
 export function* sourceLines(text) {
     let start = 0;

package/dist/core/hookcache.d.ts

@@ -15,3 +15,25 @@ export declare function injectionMode(sessionId: string | undefined, key: string
  *  reset, or post-compact edits get delta one-liners against grounding the
  *  agent no longer has. Never throws (same posture as injectionMode). */
 export declare function resetSessionInjections(sessionId: string | undefined): void;
+/** The machine-local directory every hook cache lives in (OS tmpdir). */
+export declare function hookCacheDir(): string;
+/** A task's prompt-time memory selection (taskSelection.ts): record ids only —
+ *  never the prompt text it was scored from. Kill switch: HUNCH_TASK_SELECTION=0
+ *  (no selection is written or read, so file grounding stays unfiltered). */
+export interface TaskSelectionFile {
+    task_id: string;
+    qualifying: string[];
+    top: string[];
+}
+export declare function taskSelectionPath(taskId: string): string;
+/** Persist a task's selection (atomic temp+rename). Throws; callers fail open. */
+export declare function saveTaskSelection(selection: TaskSelectionFile): void;
+export declare function taskSelectionEnabled(): boolean;
+/** Remove a task's selection file (an empty selection is no selection). Never throws. */
+export declare function clearTaskSelection(taskId: string): void;
+/** The task's selection, or null when none was written (a host without a prompt
+ *  hook, a legacy session), it holds no decision/bug/finding id (constraints
+ *  are never filtered, so a constraint-only selection would only hide memory),
+ *  it is unreadable, or selection is switched off — callers then keep today's
+ *  unfiltered grounding. Never throws. */
+export declare function loadTaskSelection(taskId: string | null | undefined): TaskSelectionFile | null;

package/dist/core/hookcache.js

@@ -18,7 +18,9 @@
 import { createHash } from "node:crypto";
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { isFilterableSelectionId } from "./taskSelection.js";
 import { tmpdir } from "node:os";
+import { writeFileAtomic } from "./io.js";
 const MAX_KEYS = 300;
 const SWEEP_AGE_MS = 48 * 3600 * 1000;
 /** Decide whether this injection should be the FULL grounding block or a delta
@@ -35,7 +37,7 @@ export function injectionMode(sessionId, key, content, hashInput = content) {
     try {
         if (!sessionId || process.env.HUNCH_HOOK_DEDUP === "0")
             return "full";
-        const dir = join(tmpdir(), "hunch-hookcache");
+        const dir = hookCacheDir();
         mkdirSync(dir, { recursive: true });
         sweep(dir);
         const file = join(dir, `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
@@ -71,13 +73,62 @@ export function resetSessionInjections(sessionId) {
     try {
         if (!sessionId)
             return;
-        const file = join(tmpdir(), "hunch-hookcache", `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
+        const file = join(hookCacheDir(), `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
         rmSync(file, { force: true });
     }
     catch {
         /* unwritable tmpdir — next injectionMode call falls back to "full" anyway */
     }
 }
+/** The machine-local directory every hook cache lives in (OS tmpdir). */
+export function hookCacheDir() {
+    return join(tmpdir(), "hunch-hookcache");
+}
+export function taskSelectionPath(taskId) {
+    return join(hookCacheDir(), `task-${taskId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
+}
+/** Persist a task's selection (atomic temp+rename). Throws; callers fail open. */
+export function saveTaskSelection(selection) {
+    const dir = hookCacheDir();
+    mkdirSync(dir, { recursive: true });
+    sweep(dir);
+    writeFileAtomic(taskSelectionPath(selection.task_id), JSON.stringify({
+        task_id: selection.task_id, qualifying: [...selection.qualifying], top: [...selection.top],
+    }));
+}
+export function taskSelectionEnabled() {
+    return process.env.HUNCH_TASK_SELECTION !== "0";
+}
+/** Remove a task's selection file (an empty selection is no selection). Never throws. */
+export function clearTaskSelection(taskId) {
+    try {
+        rmSync(taskSelectionPath(taskId), { force: true });
+    }
+    catch {
+        /* fail open: a stale file is read back as whatever it holds */
+    }
+}
+/** The task's selection, or null when none was written (a host without a prompt
+ *  hook, a legacy session), it holds no decision/bug/finding id (constraints
+ *  are never filtered, so a constraint-only selection would only hide memory),
+ *  it is unreadable, or selection is switched off — callers then keep today's
+ *  unfiltered grounding. Never throws. */
+export function loadTaskSelection(taskId) {
+    try {
+        if (!taskId || !taskSelectionEnabled())
+            return null;
+        const raw = JSON.parse(readFileSync(taskSelectionPath(taskId), "utf8"));
+        if (!raw || raw.task_id !== taskId || !Array.isArray(raw.qualifying) || !Array.isArray(raw.top))
+            return null;
+        const qualifying = raw.qualifying.filter((id) => typeof id === "string");
+        if (!qualifying.some(isFilterableSelectionId))
+            return null;
+        return { task_id: taskId, qualifying, top: raw.top.filter((id) => typeof id === "string") };
+    }
+    catch {
+        return null;
+    }
+}
 /** Drop session caches from long-gone sessions (best effort, bounded dir). */
 function sweep(dir) {
     try {

package/dist/core/procstart.d.ts

@@ -66,10 +66,14 @@ export declare function ownerInstance(ownerStart: string | undefined, pid: numbe
  *  held nonce and could age-steal its live lock. */
 export declare const heldLockNonces: Set<string>;
 /** What a contender should do about a SAME-HOST lock owner.
- *  - `stale` — provably not the owner's process any more: take it over.
- *  - `live`  — authoritative, however old the file looks: never steal it.
- *  - `age`   — nothing is proven; fall back to the caller's own age rule. */
-export type SameHostVerdict = "stale" | "live" | "age";
+ *  - `stale`    — provably not the owner's process any more: take it over.
+ *  - `live`     — authoritative, however old the file looks: never steal it.
+ *  - `unproven` — a live pid whose process instance no token can compare (macOS,
+ *                 Windows, a legacy record). Treated as live; a caller with a
+ *                 better probe may still disprove it (src/serve/writelock.ts
+ *                 asks the OS when that process was created, issue #287).
+ *  - `age`      — nothing is proven; fall back to the caller's own age rule. */
+export type SameHostVerdict = "stale" | "live" | "unproven" | "age";
 /** The parts of a lock record this decision reads. Both lock formats supply it. */
 export interface SameHostOwner {
     pid: number;
@@ -91,4 +95,11 @@ export interface SameHostEnv {
  * process state beyond what `env` hands it.
  */
 export declare function judgeSameHostOwner(owner: SameHostOwner, env: SameHostEnv): SameHostVerdict;
+/** Wall-clock ms at which the process now holding `pid` was created, from the
+ *  OS, or null when it cannot be read. SPAWNS (PowerShell on Windows, `ps` on
+ *  macOS), so it is for rare paths only — a lock that already looks stale —
+ *  never for every acquisition. Precision is a second on `ps`. Null on every
+ *  other platform: linux derives `lstart` from boot time, which a forward clock
+ *  step shifts for live processes too (see the header). */
+export declare function processStartedAt(pid: number): number | null;
 export {};