@davesheffer/hunch 1.42.0 → 1.44.0

package/dist/core/procstart.js

@@ -23,19 +23,23 @@
  * puts two writers inside the mutex. Reproduced by simply `utimes`-ing a held
  * lock 30 s into the past. Nothing in this file may read a clock.
  *
- * REMAINING GAP. Only linux exposes a spawn-free, stable process-instance id
- * (`/proc/<pid>/stat` field 22 plus the boot id and the pid/time namespaces). On
- * macOS and Windows a DIFFERENT live process that recycled the owner's pid
- * therefore stays "not proven" and keeps the lock until the age rule applies —
- * today's behaviour, and the safe direction. `ps -o lstart` and PowerShell's
- * `Get-Process ... StartTime` were rejected: both cost a spawn per probe on the
- * contended path, and both return locale/TZ-dependent strings we would have to
- * parse back into a comparable identity. Gating such a probe on age does not
- * rescue them either: the CONTENDER can read the current holder's start time,
- * but a verdict needs something to compare it WITH — either a start time the
- * OWNER recorded when it took the lock (which puts that spawn on every writing
- * process, not just the contended path) or a start-time-vs-mtime comparison,
- * i.e. exactly the cross-clock arithmetic rejected above.
+ * OFF LINUX (issue #287). Only linux exposes a spawn-free, stable process-instance
+ * id (`/proc/<pid>/stat` field 22 plus the boot id and the pid/time namespaces), so
+ * on macOS and Windows a DIFFERENT live process that recycled the owner's pid is
+ * "unproven" here, which this table treats as live. The write lock closes that
+ * forever-deadlock on its own rare path, once a lock already looks stale: it asks
+ * the OS when the process now holding the pid was CREATED (`processStartedAt`, a
+ * spawn) and compares that with the `at` the owner recorded when it took the lock.
+ * A process created after the lock was taken cannot have taken it. Both instants
+ * are the HOST's wall clock, read on this same host, so the filesystem clock never
+ * enters; only a backward clock step of more than the slack between the owner's
+ * start and its acquisition could fake it. macOS and Windows record that creation
+ * instant absolutely; linux does not (`ps lstart` is boot time + uptime, so a
+ * forward clock step after boot moves every live process's "creation" forward and
+ * would fake a reuse), so on linux the probe reports nothing and a tokenless
+ * record keeps main's pid rule — linux writers record a token instead. The earlier objection to such a probe —
+ * that it needs either an owner-recorded start time (a spawn on every write) or a
+ * start-vs-mtime comparison — missed that `at` is already in every record.
  *
  * UNSUPPORTED TOPOLOGIES. A linux-written token carries its boot id and its pid
  * and time namespaces, so a lock written under another boot or another namespace
@@ -51,12 +55,14 @@
  * while our own token is memoized from before the checkpoint — so a restored
  * holder may judge itself against a token that no longer describes it. Tokenless
  * records (a legacy pre-token hunch, any non-linux writer, an unreadable /proc)
- * get main's unchanged pid rule — a live same-host pid keeps its lock, a dead one
- * is stealable — with exactly one exception, the own-pid + foreign-nonce row
+ * get main's unchanged pid rule — a live same-host pid keeps its lock (unless the
+ * write lock's creation-time check above proves the pid reused), a dead one is
+ * stealable — with exactly one exception, the own-pid + foreign-nonce row
  * described in `judgeSameHostOwner`, which gets the AGE rule instead of main's
  * "live forever".
  */
 import { readFileSync, readlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 /** `starttime` in clock ticks since boot, as the exact decimal STRING the kernel
  *  printed — it is an identity component, never a quantity, so it is never
  *  converted to a Number (which would lose precision above 2^53 and invite
@@ -237,8 +243,40 @@ export function judgeSameHostOwner(owner, env) {
     //    that a live writer may still hold.
     if (owner.pid === env.selfPid && owner.nonce !== undefined)
         return "age";
-    // A nonce-less own-pid record stays live: there is nothing to compare, and a
-    // live pid is never stolen on a guess.
-    return "live";
+    // 7. A live pid no token can compare — another process's, or a nonce-less
+    //    record of our own pid. Never stolen on a guess: "unproven" is "live" to a
+    //    caller that has nothing better. The write lock asks the OS for that
+    //    process's creation time, which can prove the pid was reused (issue #287).
+    return "unproven";
+}
+/** 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 function processStartedAt(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        if (process.platform === "win32") {
+            // Epoch milliseconds, not a formatted date: a custom format string follows the
+            // culture's time separator (fi-FI prints `09.04.19`), which Date.parse rejects.
+            const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `([DateTimeOffset](Get-Process -Id ${pid} -ErrorAction Stop).StartTime).ToUnixTimeMilliseconds()`], { encoding: "utf8", timeout: 3_000, windowsHide: true });
+            const ms = r.status === 0 && /^\d+$/.test(r.stdout.trim()) ? Number(r.stdout.trim()) : NaN;
+            return Number.isFinite(ms) ? ms : null;
+        }
+        if (process.platform !== "darwin")
+            return null;
+        const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", timeout: 3_000, env: { ...process.env, LC_ALL: "C", LANG: "C" } });
+        const m = /^\s*\w{3}\s+(\w{3})\s+(\d{1,2})\s+(\d{1,2}):(\d{2}):(\d{2})\s+(\d{4})\s*$/.exec(r.status === 0 ? r.stdout : "");
+        const month = m ? ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"].indexOf(m[1]) : -1;
+        if (!m || month < 0)
+            return null;
+        return new Date(Number(m[6]), month, Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5])).getTime(); // ps prints local time
+    }
+    catch {
+        return null;
+    }
 }
 //# sourceMappingURL=procstart.js.map

package/dist/core/publication.js

@@ -33,9 +33,23 @@ export function isStructural(hit) {
  *  `/Users/me/repo` appears in src/integrations/claudeConfig.ts and its test as an
  *  illustration; flagging those would train everyone to ignore the scanner. */
 const PLACEHOLDER_USER = /^(me|you|user|username|<[^>]+>|\$\{[^}]+\}|example|test|foo|bar)$/i;
+/** A regex quoted in a record (`\/home\/([^/]+)`, `C:\\Users\\([^\\]+)`) names a
+ *  pattern, not a user: its capture starts with a regex metacharacter and, past a
+ *  `(?<name>` label, holds no word. A group that lists names (`(alice|bob)`,
+ *  `{alice,bob}`) still names users. */
+const PATTERN_USER = /^[([*^{|+?]/;
+function isPatternUser(who) {
+    return PATTERN_USER.test(who) && !/[A-Za-z]{3,}/.test(who.replace(/^\(\?<\w+>/, ""));
+}
+/** Home directories in the forms tools print them: a drive path (also as a URI's
+ *  `c%3A`), a POSIX path after any separator (`file:///Users/x`, `cwd=/home/x`,
+ *  `git -C /Users/x`) but not after a drive letter's colon, which the drive rule
+ *  reports, and Git Bash's `/c/Users/x` or WSL's `/mnt/c/Users/x`. A letter right
+ *  before the colon makes it a scheme (`file:/Users/x`), not a drive. */
 const MACHINE_PATH = [
-    /[A-Za-z]:[\\/]Users[\\/]([^\\/"'\s,)\]]+)/g,
-    /(?:^|[\s"'(])\/(?:Users|home)\/([^/"'\s,)\]]+)/g,
+    /(?<![A-Za-z])[A-Z](?::|%3A)[\\/]Users[\\/]([^\\/"'\s,)\]]+)/gi,
+    /(?:^|[^A-Za-z0-9_.~])(?<!(?<![A-Za-z])[A-Za-z]:)\/(?:Users|home)\/([^/"'\s,)\]]+)/g,
+    /(?:^|[^A-Za-z0-9_.~])\/(?:mnt\/)?[A-Za-z]\/Users\/([^/"'\s,)\]]+)/g,
 ];
 /** A path INTO the overlay (dir + file), not a bare mention of the feature. The
  *  gitignore entry and the CLAUDE.md description name `.hunch-private` legitimately;
@@ -151,7 +165,7 @@ export function scanRecord(record, opts = {}) {
         for (const re of MACHINE_PATH) {
             for (const m of text.matchAll(re)) {
                 const who = m[1] ?? "";
-                if (PLACEHOLDER_USER.test(who))
+                if (PLACEHOLDER_USER.test(who) || isPatternUser(who))
                     continue;
                 hits.push({ kind: "machine-path", field, excerpt: clip(m[0]) });
             }

package/dist/core/runbookDraft.d.ts

@@ -0,0 +1,7 @@
+export declare function runbookDraft(commits: readonly {
+    subject: string;
+    files: readonly string[];
+}[], rangeFiles: readonly string[]): {
+    steps: string[];
+    files: string[];
+};

package/dist/core/runbookDraft.js

@@ -0,0 +1,43 @@
+/**
+ * The deterministic runbook draft (`hunch runbook <range> --task`): the commits and files
+ * of a range that describe the work, without Hunch's own bookkeeping (issue #425). With
+ * auto-commit on, a range interleaves capture commits (`hunch: capture …`) whose files are
+ * the store (.hunch/**) and the grounding docs flushCapture regenerates beside it.
+ *
+ * Same notion of "Hunch-owned" as sync (src/synthesis/synthesize.ts) and the task report
+ * (src/core/taskTouched.ts): the store is never the work; a grounding doc is Hunch's when
+ * it changed alongside the store, and the work's when a human edited it on its own.
+ */
+import { HUNCH_COMMIT_SUBJECT, HUNCH_MANAGED_FILES } from "./taskTouched.js";
+/** Grounding docs that are wholly generated (no user text): never the work. */
+const FULLY_MANAGED = new Set([".cursor/rules/hunch.mdc", ".windsurf/rules/hunch.md"]);
+const STORE_SEGMENTS = new Set([".hunch", ".hunch-cache"]);
+const norm = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "");
+/** The store lives at the repository root; a user folder named .hunch further down is theirs. */
+const isStore = (p) => STORE_SEGMENTS.has(norm(p).split("/")[0]);
+export function runbookDraft(commits, rangeFiles) {
+    const steps = [];
+    const workDocs = new Set(); // grounding docs a non-capture commit edited on its own
+    for (const c of commits) {
+        if (HUNCH_COMMIT_SUBJECT.test(c.subject))
+            continue;
+        const files = c.files.map(norm);
+        const touchesStore = files.some(isStore);
+        const work = files.filter((f) => !isStore(f) && !FULLY_MANAGED.has(f) && !(touchesStore && HUNCH_MANAGED_FILES.has(f)));
+        if (files.length && !work.length)
+            continue; // only Hunch's own paths
+        if (c.subject.trim())
+            steps.push(c.subject); // an empty-message commit is no step
+        for (const f of work)
+            if (HUNCH_MANAGED_FILES.has(f))
+                workDocs.add(f);
+    }
+    const files = rangeFiles.filter((raw) => {
+        const f = norm(raw);
+        if (isStore(f) || FULLY_MANAGED.has(f))
+            return false;
+        return !HUNCH_MANAGED_FILES.has(f) || workDocs.has(f);
+    });
+    return { steps, files };
+}
+//# sourceMappingURL=runbookDraft.js.map

package/dist/core/taskReportHook.js

@@ -200,7 +200,7 @@ export function taskInstruction(task, cwdLiteral, provider, launcher = verificat
             const finishRule = HOST_CLOSES_TASK.has(provider) ? "finish only if this task used Hunch" : `finish it yourself with hunch_task(action: "finish", task_id, cwd)`;
             return `Hunch report for this prompt: ${task.task_id} (cwd: ${cwdLiteral}). Use it instead of any earlier ID. Never call hunch_task start. Checks: ${l.shell} task verify ${task.task_id} -- <command> [arguments]${l.note ?? ""}. Same rules as this session's first report; ${finishRule}.`;
         }
-        verify = ` Never call hunch_task start for it. For checks, run: ${l.shell} task verify ${task.task_id} -- <command> [arguments]${l.note ?? ""}. Default budget 15 min; add --timeout <seconds> before -- for longer suites.`;
+        verify = ` Never call hunch_task start for it. For checks, run: ${l.shell} task verify ${task.task_id} -- <command> [arguments]${l.note ?? ""}. Verify with the tests that cover your change (the files you edited and their tests); the full suite is CI's job. The default budget is 15 min; add --timeout <seconds> before -- only if the whole suite is really needed.`;
     }
     catch {
         return `${head} Call hunch_task(action: "start", task_id: "${task.task_id}", title: ${JSON.stringify(task.title)}, cwd: ${cwdLiteral}) to obtain verification_argv, and finish with hunch_task(action: "finish", task_id, cwd) before responding and show its card.`;

package/dist/core/taskSelection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Task-scored memory selection (memory-selection design, point 1-3; Gate A v5).
+ *
+ * The pre-edit hook used to deliver every record anchored to a file, so a hub
+ * file filled the headline cap with memory unrelated to the task. This selector
+ * scores the live store against the prompt ONCE per task; file grounding then
+ * keeps only the decisions, bugs and findings that qualified (constraints are
+ * exempt: they are scoped rules, not relevance guesses).
+ *
+ * PURE on purpose: no fs, no store. Inputs are passed in, so an offline replay
+ * can run it against an old store snapshot. The rule is fixed before
+ * measurement (no vectors in this step): a record qualifies on >= 2 distinct
+ * task terms in its title/rationale, or on a repo path the prompt names that
+ * matches the record's files or scope. Below that, nothing (silence, no filler).
+ * A term common to many live records (document frequency above the cap) names
+ * no task and does not count toward the two.
+ */
+import type { Bug, Constraint, Decision, Finding } from "./types.js";
+export interface TaskSelectionRecords {
+    decisions: readonly Decision[];
+    bugs: readonly Bug[];
+    constraints: readonly Constraint[];
+    findings: readonly Finding[];
+}
+export type TaskSelectionKind = "decision" | "bug" | "constraint" | "finding";
+export interface TaskSelection {
+    /** Every record clearing the threshold (ids only). */
+    qualifying: string[];
+    /** At most k, ordered; blocking constraints are never listed (they arrive at edit time). */
+    top: Array<{
+        id: string;
+        kind: TaskSelectionKind;
+        title: string;
+    }>;
+}
+export declare function isFilterableSelectionId(id: string): boolean;
+export declare function isBareFollowUp(prompt: string): boolean;
+export interface TaskSelectionOptions {
+    /** Prompt-time list size (design: K = 3). */
+    k?: number;
+    /** Optional existence check for a repo-relative path the prompt names. */
+    pathExists?: (path: string) => boolean;
+    /** Repository root, only to strip it from absolute paths in the prompt (string work, no fs). */
+    root?: string;
+}
+/** Document-frequency cap, fixed before the pilot replay: a prompt term counts
+ *  only when at most max(MIN_DF_CAP, ceil(DF_CAP_RATIO × live records)) records
+ *  contain it. */
+export declare const MIN_DF_CAP = 3;
+export declare const DF_CAP_RATIO = 0.05;
+/** The live slice the pre-edit grounding would ever deliver at HEAD: decisions and
+ *  constraints still in force (the store's why() window plus delivery's retired
+ *  test), every bug (why() keeps fixed ones as lessons), and findings whose triage
+ *  liveFindingsFor() keeps. */
+export declare function liveSelectionRecords(all: TaskSelectionRecords): TaskSelectionRecords;
+/** Repo paths the prompt names: a markdown link `[label](target)` reads as its
+ *  target, then a whitespace token containing `/` or ending in a file extension,
+ *  stripped of quoting/punctuation/unmatched brackets, a trailing `:line[:col]`
+ *  or `:start-end` and a possessive `'s`, forward-slashed, repo-relative. A drive-letter root compares
+ *  case-insensitively (Windows paths are case-insensitive on every host). */
+export declare function promptPaths(prompt: string, root?: string): string[];
+/** Score live records against one prompt. Text fields per kind (title + rationale):
+ *  decision title/context/decision; bug title/symptom/root_cause; constraint
+ *  statement/rationale; finding title/observation. Path anchors: decision
+ *  related_files, bug/finding affected_files, constraint scope globs. Priority
+ *  ties break on the builder profile's kind/severity score in delivery.ts. */
+export declare function selectForTask(records: TaskSelectionRecords, promptText: string, opts?: TaskSelectionOptions): TaskSelection;

package/dist/core/taskSelection.js

@@ -0,0 +1,196 @@
+import { lexicalTokens, PROFILE_BASE_SCORE, SEVERITY } from "./delivery.js";
+import { pathMatchesGlob } from "./glob.js";
+/** Id prefixes of the kinds file grounding filters by a selection (ids.ts:
+ *  decisionId/bugId/findingId). Constraints (con_) always pass, so a selection
+ *  holding no id with one of these prefixes filters nothing useful — it would
+ *  only hide every decision, bug and finding — and counts as no selection. */
+const FILTERABLE_ID_PREFIXES = ["dec_", "bug_", "fnd_"];
+export function isFilterableSelectionId(id) {
+    return FILTERABLE_ID_PREFIXES.some((prefix) => id.startsWith(prefix));
+}
+/** Words a bare follow-up is made of ("continue", "go on", "yes do it", "ok,
+ *  next step please"). A prompt of only these names no task of its own and
+ *  inherits the continued task's selection; any other word — a verb and an
+ *  object ("fix sampler"), a path, another language — is a task of its own
+ *  (fail-safe: its own selection, or unfiltered grounding). */
+const CONTINUATION_WORDS = new Set([
+    "continue", "continuing", "go", "on", "ahead", "proceed", "resume", "carry", "keep", "going",
+    "yes", "yep", "yeah", "y", "ok", "okay", "sure", "please", "pls", "do", "it", "that", "this",
+    "next", "step", "again", "lgtm", "sounds", "good", "fine", "and", "the", "with", "now",
+]);
+export function isBareFollowUp(prompt) {
+    const words = (prompt ?? "").toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    return words.length > 0 && words.every((word) => CONTINUATION_WORDS.has(word));
+}
+const BRACKET_PAIRS = { "(": ")", "[": "]", "{": "}" };
+const CLOSING_BRACKETS = { ")": "(", "]": "[", "}": "{" };
+/** Every `close` in text[from, to) follows its `open` (properly nested, none left open). */
+function balanced(text, from, to, open, close) {
+    let depth = 0;
+    for (let i = from; i < to; i++) {
+        if (text[i] === open)
+            depth++;
+        else if (text[i] === close && --depth < 0)
+            return false;
+    }
+    return depth === 0;
+}
+/** Strip quoting, sentence punctuation, unmatched or wrapping brackets and a
+ *  possessive `'s` from a prompt token until stable. A bracket the path itself
+ *  uses (`(auth)/x.ts`, `[id]/page.tsx`, `src/app/(auth)`) is balanced and stays.
+ *  Works on [a, b) indices with bracket counts kept current, so trimming a run of
+ *  n unmatched brackets is linear, not n rescans of the token. */
+const MAX_PATH_TOKEN_CHARS = 1024;
+/** Wrapping pairs unwrapped per token; each unwrap rescans the token, and prose never nests deeper. */
+const MAX_UNWRAPS = 8;
+function trimPathToken(raw) {
+    const counts = { "(": 0, ")": 0, "[": 0, "]": 0, "{": 0, "}": 0 };
+    for (let i = 0; i < raw.length; i++)
+        if (raw[i] in counts)
+            counts[raw[i]]++;
+    const n = (ch) => counts[ch];
+    const dropAt = (i) => { if (raw[i] in counts)
+        counts[raw[i]]--; };
+    let a = 0;
+    let b = raw.length;
+    let unwraps = 0;
+    for (let before = -1; a < b && before !== b - a;) {
+        before = b - a;
+        // A trailing opening bracket can never close, so it goes first (keeps `[id]/x.ts[` from losing its head).
+        const lastOpen = raw[b - 1];
+        if (BRACKET_PAIRS[lastOpen] && n(lastOpen) > n(BRACKET_PAIRS[lastOpen]))
+            dropAt(--b);
+        if (a >= b)
+            break;
+        const head = raw[a];
+        const close = BRACKET_PAIRS[head];
+        const headOpen = CLOSING_BRACKETS[head];
+        if ("`'\"<\u2018\u201c".includes(head))
+            dropAt(a++);
+        else if (close && unwraps < MAX_UNWRAPS && b - a >= 2 && raw[b - 1] === close && n(head) === n(close) && balanced(raw, a + 1, b - 1, head, close)) {
+            unwraps++;
+            dropAt(a++);
+            dropAt(--b);
+        }
+        else if (close && n(head) > n(close))
+            dropAt(a++);
+        else if (headOpen && n(head) > n(headOpen))
+            dropAt(a++);
+        if (a >= b)
+            break;
+        const tail = raw[b - 1];
+        const open = CLOSING_BRACKETS[tail];
+        if ("`'\">,.;:!?\u2019\u201d".includes(tail))
+            dropAt(--b);
+        else if (open && n(open) < n(tail))
+            dropAt(--b);
+        if (b - a >= 2 && "sS".includes(raw[b - 1]) && "'\u2019".includes(raw[b - 2]))
+            b -= 2;
+    }
+    return raw.slice(a, b);
+}
+const MIN_DISTINCT_TERMS = 2;
+/** Document-frequency cap, fixed before the pilot replay: a prompt term counts
+ *  only when at most max(MIN_DF_CAP, ceil(DF_CAP_RATIO × live records)) records
+ *  contain it. */
+export const MIN_DF_CAP = 3;
+export const DF_CAP_RATIO = 0.05;
+const DEFAULT_K = 3;
+const LIVE_FINDING_TRIAGE = new Set(["open", "accepted-risk", "scheduled"]);
+/** The live slice the pre-edit grounding would ever deliver at HEAD: decisions and
+ *  constraints still in force (the store's why() window plus delivery's retired
+ *  test), every bug (why() keeps fixed ones as lessons), and findings whose triage
+ *  liveFindingsFor() keeps. */
+export function liveSelectionRecords(all) {
+    return {
+        decisions: all.decisions.filter((d) => d.status !== "rejected" && d.status !== "superseded" && !d.superseded_by && d.valid_to == null),
+        bugs: [...all.bugs],
+        constraints: all.constraints.filter((c) => c.status !== "retired" && c.valid_to == null),
+        findings: all.findings.filter((f) => LIVE_FINDING_TRIAGE.has(f.triage)),
+    };
+}
+/** Repo paths the prompt names: a markdown link `[label](target)` reads as its
+ *  target, then a whitespace token containing `/` or ending in a file extension,
+ *  stripped of quoting/punctuation/unmatched brackets, a trailing `:line[:col]`
+ *  or `:start-end` and a possessive `'s`, forward-slashed, repo-relative. A drive-letter root compares
+ *  case-insensitively (Windows paths are case-insensitive on every host). */
+export function promptPaths(prompt, root) {
+    const out = new Set();
+    const rootPrefix = root ? `${root.replace(/\\/g, "/").replace(/\/+$/, "")}/` : null;
+    // Label and target may each hold one level of brackets (`[app/[id]/x.ts](app/[id]/x.ts)`,
+    // a linked `src/app/(auth)/page.tsx`); the label never spans a `[`, so a run of `[` fails fast.
+    const links = prompt.replace(/\[(?:[^[\]\n]|\[[^[\]\n]{0,256}\]){0,256}\]\(((?:[^()\s]|\([^()\s]{0,256}\)){1,1024})\)/g, " $1 ");
+    for (const raw of links.split(/\s+/)) {
+        // No repo path is this long; trimming pasted junk one bracket at a time would stall the prompt hook.
+        if (raw.length > MAX_PATH_TOKEN_CHARS)
+            continue;
+        let token = trimPathToken(raw).replace(/\\/g, "/").replace(/:\d+(?:[:-]\d+)?$/, "");
+        if (!token || /^[a-z][a-z0-9+.-]*:\/\//i.test(token))
+            continue;
+        if (!token.includes("/") && !/\.[a-z0-9]{1,8}$/i.test(token))
+            continue;
+        if (rootPrefix) {
+            const foldCase = process.platform === "win32" || /^[a-z]:\//i.test(token);
+            if (foldCase ? token.toLowerCase().startsWith(rootPrefix.toLowerCase()) : token.startsWith(rootPrefix))
+                token = token.slice(rootPrefix.length);
+        }
+        token = token.replace(/^(?:\.\/)+/, "");
+        // Absolute (outside the root) or parent-relative paths name nothing in this repo.
+        if (!token || token.startsWith("/") || /^[a-z]:/i.test(token) || token.split("/").includes(".."))
+            continue;
+        out.add(token);
+    }
+    return [...out];
+}
+/** Score live records against one prompt. Text fields per kind (title + rationale):
+ *  decision title/context/decision; bug title/symptom/root_cause; constraint
+ *  statement/rationale; finding title/observation. Path anchors: decision
+ *  related_files, bug/finding affected_files, constraint scope globs. Priority
+ *  ties break on the builder profile's kind/severity score in delivery.ts. */
+export function selectForTask(records, promptText, opts = {}) {
+    const k = Math.max(0, opts.k ?? DEFAULT_K);
+    const taskTerms = lexicalTokens(promptText ?? "");
+    // Without an existence check (pure/offline) only a slashed token is trusted as a
+    // path: "e.g.", "Node.js" or "v1.2" would otherwise match a broad glob.
+    const paths = promptPaths(promptText ?? "", opts.root).filter((p) => opts.pathExists ? opts.pathExists(p) : p.includes("/"));
+    if (!taskTerms.size && !paths.length)
+        return { qualifying: [], top: [] };
+    const base = PROFILE_BASE_SCORE.builder;
+    // Tokenize every record once: the same tokens feed the document frequency and the score.
+    const candidates = [];
+    const consider = (id, kind, title, text, anchors, priority, listable) => {
+        candidates.push({ id, kind, title, tokens: lexicalTokens(text.join(" ")), anchors, priority, listable });
+    };
+    for (const c of records.constraints) {
+        consider(c.id, "constraint", c.statement, [c.statement, c.rationale], c.scope, base.constraints + SEVERITY[c.severity] * 10 + (c.provenance.confidence ?? 0), c.severity !== "blocking");
+    }
+    for (const d of records.decisions) {
+        consider(d.id, "decision", d.title, [d.title, d.context, d.decision], d.related_files, base.decisions + (d.status === "accepted" ? 20 : 0) + (d.provenance.confidence ?? 0), true);
+    }
+    for (const b of records.bugs) {
+        consider(b.id, "bug", b.title, [b.title, b.symptom, b.root_cause], b.affected_files, base.bugs + SEVERITY[b.severity] * 10 + (b.status === "open" || b.status === "regressed" ? 10 : 0), true);
+    }
+    for (const f of records.findings) {
+        consider(f.id, "finding", f.title, [f.title, f.observation], f.affected_files, base.findings + SEVERITY[f.severity] * 10, true);
+    }
+    const dfCap = Math.max(MIN_DF_CAP, Math.ceil(DF_CAP_RATIO * candidates.length));
+    const rareTerms = [...taskTerms].filter((term) => candidates.filter((c) => c.tokens.has(term)).length <= dfCap);
+    const scored = [];
+    for (const { tokens, anchors, ...rest } of candidates) {
+        let terms = 0;
+        for (const term of rareTerms)
+            if (tokens.has(term))
+                terms++;
+        const pathHits = paths.filter((p) => anchors.some((anchor) => pathMatchesGlob(p, anchor))).length;
+        if (pathHits > 0 || terms >= MIN_DISTINCT_TERMS)
+            scored.push({ ...rest, pathHits, terms });
+    }
+    // A record anchored to more of the files the prompt names outranks one that
+    // shares a single (often hub) file with it; rare terms break the remaining ties.
+    scored.sort((a, b) => b.pathHits - a.pathHits || b.terms - a.terms || b.priority - a.priority || a.id.localeCompare(b.id));
+    return {
+        qualifying: scored.map((s) => s.id),
+        top: scored.filter((s) => s.listable).slice(0, k).map(({ id, kind, title }) => ({ id, kind, title })),
+    };
+}
+//# sourceMappingURL=taskSelection.js.map

package/dist/core/taskTouched.d.ts

@@ -1,6 +1,8 @@
 /** Files Hunch regenerates on every capture (src/integrations/providers.ts,
  * claudemd.ts): a fresh mtime on them is the capture, not the task's work. */
 export declare const HUNCH_MANAGED_FILES: ReadonlySet<string>;
+/** Commit subjects Hunch writes itself. */
+export declare const HUNCH_COMMIT_SUBJECT: RegExp;
 export declare function gitTouchedFiles(root: string, startedAt: string, finishedAt: string | null, options?: {
     limit?: number;
     timeoutMs?: number;

package/dist/core/taskTouched.js

@@ -27,7 +27,7 @@ const EXCLUDED_SEGMENTS = new Set([".hunch", ".hunch-cache", ".git"]);
  * claudemd.ts): a fresh mtime on them is the capture, not the task's work. */
 export const HUNCH_MANAGED_FILES = new Set(["CLAUDE.md", "AGENTS.md", ".cursor/rules/hunch.mdc", ".github/copilot-instructions.md", ".windsurf/rules/hunch.md"]);
 /** Commit subjects Hunch writes itself. */
-const HUNCH_COMMIT_SUBJECT = /^hunch:/i;
+export const HUNCH_COMMIT_SUBJECT = /^hunch:/i;
 function gitDate(ms) {
     // Second resolution, a format every git accepts.
     return `${new Date(ms).toISOString().slice(0, 19).replace("T", " ")} +0000`;

package/dist/extractors/git.d.ts

@@ -125,7 +125,11 @@ export declare function headFileContent(root: string, rel: string): string | nul
  *  machines' memory. Never throws; leaves a clean tree. Serialized with the commit lock so it
  *  can't race a concurrent flush. Returns true only when the checked-out memory HEAD moved,
  *  allowing callers to avoid rebuilding the derived SQLite index after a no-op pull. */
-export type HunchPullStatus = "updated" | "current" | "busy" | "failed" | "unconfigured";
+export type HunchPullStatus = "updated" | "current" | "busy" | "failed" | "unconfigured" | "empty";
+/** A strict guard may pass only on a pull that proved this clone's memory matches the
+ *  advertised remote: it advanced, was already current, or both are provably empty (a
+ *  brand-new shared memory repo before its first capture, #427). */
+export declare function teamPullIsFresh(status: HunchPullStatus): boolean;
 export interface PullHunchOptions {
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
@@ -298,6 +302,17 @@ export type CommitRepairStatus = "orphaned" | "current" | "unresolvable" | "unkn
  *  be treated as repair-eligible; collapsing "false" and "error" into one
  *  boolean is exactly the bug this type exists to prevent. */
 export declare function commitRepairStatus(commit: string, ref: string, cwd: string): CommitRepairStatus;
+/** commitRepairStatus against several tips: "orphaned" only when NO ref
+ *  reaches the commit. A historical `--range old..new` must not make a commit
+ *  that HEAD still reaches look orphaned just because it is newer than `new`
+ *  (#450). The first non-orphaned answer wins, so "unknown" is never upgraded. */
+export declare function commitRepairStatusAgainst(commit: string, refs: readonly string[], cwd: string): CommitRepairStatus;
+/** `git patch-id --stable` of each commit, keyed by the sha exactly as given
+ *  (full or abbreviated). Same diff flags as the workspace ledger's squash
+ *  check. A merge or empty commit, an unknown sha, or any git failure leaves
+ *  no entry: a missing patch-id is never a match. One `git log` + one
+ *  `git patch-id` process for all of them. */
+export declare function commitPatchIds(shas: readonly string[], cwd: string): Map<string, string>;
 /** Byte budget for a diff embedded in a SYNTHESIS prompt. Gates never use it: a
  *  constraint check over a prefix of a change would read every file past the
  *  cutoff as "no added lines" and pass it. */
@@ -328,8 +343,19 @@ export declare function lastCommitForFile(file: string, cwd: string): string;
 /** Full SHA of the commit that introduced a path. Unlike lastCommitForFile this
  * remains stable when lifecycle/proof updates later touch the same policy file. */
 export declare function firstCommitForFile(file: string, cwd: string): string;
-/** ISO author-date of the most recent commit touching a file ("" if none). */
-export declare function lastChangeDate(file: string, cwd: string): string;
+/** ISO author-date of the most recent commit touching a file ("" if none), as of `rev`
+ *  (default HEAD). */
+export declare function lastChangeDate(file: string, cwd: string, rev?: string): string;
+/** The revision a checked change starts from, so freshness is judged WITHOUT the change
+ *  itself: a committed change under review must not make its own guarding record stale
+ *  (#426). `--base` diffs are 3-dot, so the merge-base; `--commit` is its parent;
+ *  staged/working changes are not committed yet, so HEAD (undefined). `--commit` judges
+ *  one commit in isolation, so an earlier commit of the same branch can still age the
+ *  record; `--base` (the CI guard) judges the whole branch and is the authoritative gate. */
+export declare function checkFreshnessRevision(source: {
+    base?: string;
+    commit?: string;
+}, cwd: string): string | undefined;
 /**
  * Newest author date for every changed path selected by a bounded set of repository-relative
  * Hunch scopes. One Git history walk replaces the per-file process loop used by `staleness()`.
@@ -370,9 +396,13 @@ export declare function revExists(ref: string, cwd: string): boolean;
 /** Files a PR/branch changes vs `base` (3-dot: changes on HEAD since the merge-base,
  *  i.e. exactly the PR's own commits — the CI Constraint Guard's surface). */
 export declare function rangeFiles(base: string, cwd: string, head?: string): string[];
-/** Commit subjects on `head` since `base` (2-dot: commits added by the task),
- *  oldest-first, for distilling a runbook's ordered steps (roadmap #5). */
-export declare function rangeSubjects(base: string, cwd: string, head?: string, max?: number): string[];
+/** Commits on `head` since `base` (2-dot: commits added by the task), oldest-first, each
+ *  with its subject and the files it changed, for distilling a runbook's ordered steps
+ *  (roadmap #5); `runbookDraft` uses the files to tell Hunch's own captures from the work. */
+export declare function rangeCommits(base: string, cwd: string, head?: string, max?: number): {
+    subject: string;
+    files: string[];
+}[];
 /** Complete gating diff of a PR vs `base` (3-dot: the CI Constraint Guard's surface). */
 export declare function rangeGateDiff(base: string, cwd: string, head?: string): GateDiff;
 /** The PR's unified diff vs `base` (3-dot), noise-excluded and capped at the