@davesheffer/hunch 1.43.0 → 1.45.0

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/escalations.d.ts

@@ -127,3 +127,23 @@ export interface PolicyLite {
  *  accept/reject) is a human call. Machine conclusions never appear here as
  *  approvals — every entry is a QUESTION with its explicit resolution verb. */
 export declare function policyEscalations(policies: readonly PolicyLite[]): Escalation[];
+/** What one prompt is about, for task-scoped escalation delivery (dec_12ba37db1c). */
+export interface EscalationScope {
+    /** the prompt text as the human wrote it. */
+    prompt: string;
+    /** repo-relative paths the prompt names (taskSelection.promptPaths). */
+    paths: readonly string[];
+    /** record ids the prompt's task selection put on top, when there is one. */
+    selectedIds?: ReadonlySet<string>;
+}
+/** The escalations one prompt's task touches. A prompt hook asks the human only
+ *  about these; every other entry stays exactly as pending — still listed by
+ *  `hunch escalations`, hunch_escalations and hunch_now, never dropped and
+ *  never answered for the human. Deterministic explicit anchors only: a
+ *  prompt that asks about escalations themselves (path tokens aside), an entry
+ *  id or topic the prompt names, an id the task selection chose, or a recorded
+ *  anchor path the prompt names (a directory covers the files under it; a glob
+ *  covers the paths it matches). `relatedFiles` maps an entry id to its anchor
+ *  paths: a decision's related_files, a policy's scope paths/globs. An entry
+ *  with no anchor the prompt names stays CLI/MCP-only. */
+export declare function relevantEscalations(items: readonly Escalation[], scope: EscalationScope, relatedFiles: (id: string) => readonly string[]): Escalation[];

package/dist/core/escalations.js

@@ -1,6 +1,7 @@
 import { topicCollisions } from "./topics.js";
 import { liveRewrites, deadRewrites, commitRepairReviewHash, firstFor } from "./commitrepair.js";
 import { importedAdrReviewHash, importedAdrSourceHash, pendingImportedAdrReviews } from "./importReview.js";
+import { pathMatchesGlob } from "./glob.js";
 /** Escalations gating surfaces (CI exit codes, "needs your call" counts/lists)
  *  should act on: everything except an entry explicitly marked
  *  actionable:false (#61). The full list — including non-actionable
@@ -259,4 +260,50 @@ export function policyEscalations(policies) {
     }
     return out;
 }
+const trimSlash = (x) => x.replace(/\/+$/, "");
+const samePathOrNested = (x, y) => {
+    const a = trimSlash(x), b = trimSlash(y);
+    return !!a && !!b && (a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`));
+};
+/** A recorded related path or scope glob vs a path the prompt names. A plain
+ *  entry relates both ways by directory nesting; a glob entry matches a path it
+ *  covers, or a directory that holds its literal prefix (`src/` ~ `src/store/**`). */
+const relatedPathHit = (entry, promptPath) => {
+    if (!/[*?]/.test(entry))
+        return samePathOrNested(entry, promptPath);
+    if (pathMatchesGlob(promptPath, entry))
+        return true;
+    const literal = trimSlash(entry.split("/").filter((_, i, segs) => !segs.slice(0, i + 1).some((s) => /[*?]/.test(s))).join("/"));
+    const dir = trimSlash(promptPath);
+    return !!literal && !!dir && (literal === dir || literal.startsWith(`${dir}/`));
+};
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** The prompt's prose without path-like tokens (a `/` or a file extension), so a
+ *  file named `escalations.test.ts` is not a question about escalations. */
+const proseOnly = (prompt) => prompt.split(/\s+/).filter((t) => { const w = t.replace(/[)\],.;:!?'"`]+$/, ""); return !w.includes("/") && !/\.[a-z0-9]{1,8}$/i.test(w); }).join(" ");
+/** The escalations one prompt's task touches. A prompt hook asks the human only
+ *  about these; every other entry stays exactly as pending — still listed by
+ *  `hunch escalations`, hunch_escalations and hunch_now, never dropped and
+ *  never answered for the human. Deterministic explicit anchors only: a
+ *  prompt that asks about escalations themselves (path tokens aside), an entry
+ *  id or topic the prompt names, an id the task selection chose, or a recorded
+ *  anchor path the prompt names (a directory covers the files under it; a glob
+ *  covers the paths it matches). `relatedFiles` maps an entry id to its anchor
+ *  paths: a decision's related_files, a policy's scope paths/globs. An entry
+ *  with no anchor the prompt names stays CLI/MCP-only. */
+export function relevantEscalations(items, scope, relatedFiles) {
+    const prompt = scope.prompt ?? "";
+    if (/(?:^|[^a-z0-9-])escalations?(?:$|[^a-z0-9])/i.test(proseOnly(prompt)))
+        return [...items];
+    const lower = prompt.toLowerCase();
+    const named = (term) => {
+        const t = term.trim().toLowerCase();
+        if (t.length < 3)
+            return false;
+        return new RegExp(`(?:^|[^a-z0-9_-])${escapeRegExp(t)}(?:$|[^a-z0-9_-])`).test(lower);
+    };
+    return items.filter((e) => named(e.topic)
+        || e.decisionIds.some((id) => named(id) || scope.selectedIds?.has(id))
+        || e.decisionIds.some((id) => relatedFiles(id).some((file) => scope.paths.some((p) => relatedPathHit(file, p)))));
+}
 //# sourceMappingURL=escalations.js.map

package/dist/core/hookText.js

@@ -4,5 +4,5 @@
 export const HOOK_REMINDER = "Hunch (engineering memory) is available for this repo. Before editing, call " +
     "hunch_check_constraints(scope) for do-not-break invariants and hunch_why(target) " +
     "for the rationale; use hunch_get_dependents for blast radius and hunch_bug_lineage " +
-    "for prior root causes. After a non-trivial choice, record it with hunch_record_decision.";
+    "for prior root causes. Record only what the human decides or corrects.";
 //# sourceMappingURL=hookText.js.map

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 {};

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/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/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

package/dist/extractors/git.js

@@ -1607,6 +1607,12 @@ function pushWithOneRemoteAdvanceRetry(hunchDir, env, protectedRepoRoot, timeout
         return false;
     return tryPush(hunchDir, env, timeoutMs, contract, observe);
 }
+/** 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 function teamPullIsFresh(status) {
+    return status === "updated" || status === "current" || status === "empty";
+}
 export function pullHunchStatus(hunchDir, opts = {}) {
     const env = foreignRepoEnv({
         ...process.env,
@@ -1622,7 +1628,13 @@ export function pullHunchStatus(hunchDir, opts = {}) {
     try {
         const merged = mergeRemote(hunchDir, env, opts.timeoutMs ?? READ_REMOTE_TIMEOUT_MS, opts.remote, opts.allowUnrelatedHistories ?? false);
         if (merged === "failed" || merged === "unconfigured" || !contractReady(opts.remote)) {
-            return merged === "unconfigured" ? merged : "failed";
+            if (merged !== "unconfigured" || !contractReady(opts.remote))
+                return "failed";
+            // The advertised remote has no branch yet AND this clone never committed memory:
+            // both sides are empty, so there is nothing to be stale against (#427). A clone
+            // WITH memory against an empty remote stays "unconfigured" (unpublished, or the
+            // remote lost its history) so strict guards keep failing closed on it.
+            return opts.remote && !before && !headShaWithEnv(hunchDir, env) ? "empty" : merged;
         }
         return headShaWithEnv(hunchDir, env) !== before ? "updated" : "current";
     }
@@ -2612,6 +2624,51 @@ export function commitRepairStatus(commit, ref, cwd) {
         return e.status === 1 ? "orphaned" : "unknown";
     }
 }
+/** 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 function commitRepairStatusAgainst(commit, refs, cwd) {
+    for (const ref of new Set(refs)) {
+        const status = commitRepairStatus(commit, ref, cwd);
+        if (status !== "orphaned")
+            return status;
+    }
+    return "orphaned";
+}
+/** `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 function commitPatchIds(shas, cwd) {
+    const out = new Map();
+    // Only shas that resolve: one unknown sha (a withheld queue entry) would make `git log`
+    // fail outright and drop every patch-id. Fed on stdin, so no argv length limit applies.
+    const exists = commitsExist([...new Set(shas)], cwd);
+    const valid = exists ? [...exists] : [];
+    if (!valid.length)
+        return out;
+    let ids;
+    try {
+        const log = execFileSync("git", ["-C", cwd, "log", "--stdin", "--no-walk=unsorted", "--format=%H", "-p", "--no-merges", "--binary", "--full-index", "--no-renames", "--no-ext-diff", "--no-textconv", "--"], { input: valid.join("\n") + "\n", maxBuffer: 256 * 1024 * 1024, timeout: 30_000, stdio: ["pipe", "pipe", "ignore"] });
+        if (!log.byteLength)
+            return out;
+        ids = execFileSync("git", ["-C", cwd, "patch-id", "--stable"], { input: log, encoding: "utf8", maxBuffer: 16 * 1024 * 1024, timeout: 30_000, stdio: ["pipe", "pipe", "ignore"] });
+    }
+    catch {
+        return out;
+    }
+    for (const line of ids.split("\n")) {
+        const [patchId = "", commit = ""] = line.trim().split(/\s+/);
+        if (!/^[0-9a-f]{40,64}$/.test(patchId))
+            continue;
+        for (const sha of valid)
+            if (commit.startsWith(sha.toLowerCase()))
+                out.set(sha, patchId);
+    }
+    return out;
+}
 /** Machine-generated paths that carry no design "why" — lockfiles, build output,
  *  vendored deps, snapshots, source maps. Excluded from synthesis diffs via git
  *  pathspec BEFORE git assembles/orders the patch: a huge lockfile sorts ahead of
@@ -2713,9 +2770,23 @@ export function firstCommitForFile(file, cwd) {
         return added;
     return gitSafe(["log", "--reverse", "--format=%H", "--", file], cwd).split("\n").find(Boolean) ?? "";
 }
-/** ISO author-date of the most recent commit touching a file ("" if none). */
-export function lastChangeDate(file, cwd) {
-    return gitSafe(["log", "-1", "--format=%aI", "--", file], cwd);
+/** ISO author-date of the most recent commit touching a file ("" if none), as of `rev`
+ *  (default HEAD). */
+export function lastChangeDate(file, cwd, rev) {
+    return gitSafe(["log", "-1", "--format=%aI", ...(rev ? [rev] : []), "--", file], cwd);
+}
+/** 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 function checkFreshnessRevision(source, cwd) {
+    if (source.commit)
+        return `${source.commit}^`;
+    if (source.base)
+        return gitSafe(["merge-base", source.base, "HEAD"], cwd) || source.base;
+    return undefined;
 }
 /**
  * Newest author date for every changed path selected by a bounded set of repository-relative
@@ -2841,11 +2912,17 @@ export function revExists(ref, cwd) {
 export function rangeFiles(base, cwd, head = "HEAD") {
     return nulPaths(gitOutputOrNull(["-c", "core.quotePath=false", "diff", "--no-ext-diff", "--no-textconv", "--name-only", "-z", "--diff-filter=ACMR", `${base}...${head}`], cwd));
 }
-/** 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 function rangeSubjects(base, cwd, head = "HEAD", max = 50) {
-    const out = gitSafe(["log", "--reverse", `-n${max}`, "--format=%s", `${base}..${head}`], cwd);
-    return out ? out.split("\n").filter(Boolean) : [];
+/** 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 function rangeCommits(base, cwd, head = "HEAD", max = 50) {
+    const out = gitSafe(["-c", "core.quotePath=false", "log", "--reverse", `-n${max}`, "--format=%x1e%s", "--name-only", `${base}..${head}`], cwd);
+    if (!out)
+        return [];
+    return out.split("\x1e").filter(Boolean).map((block) => {
+        const [subject = "", ...files] = block.split("\n");
+        return { subject: subject.trim(), files: files.map((f) => f.trim()).filter(Boolean) };
+    });
 }
 /** Complete gating diff of a PR vs `base` (3-dot: the CI Constraint Guard's surface). */
 export function rangeGateDiff(base, cwd, head = "HEAD") {

package/dist/extractors/indexer.js

@@ -13,7 +13,7 @@ import { dirname, join, posix } from "node:path";
 import { parseSource, attributeCalls, attributeRelations, MAX_BODY_TEXT_CHARS } from "./parse.js";
 import { isParserLoadError } from "./nativeTreeSitter.js";
 import { extractHelmDirectives } from "./helm.js";
-import { extractK8sManifest, namespacesCompatible } from "./k8sManifest.js";
+import { extractK8sManifest, extractKustomization, isKustomizationFile, kustomizeNamespaces, namespacesCompatible } from "./k8sManifest.js";
 import { symbolId, componentId, edgeId, sha1 } from "../core/ids.js";
 import { externalImportNodeId, externalPackage } from "../core/externalImports.js";
 import { resolveRelativeImport } from "../core/relativeImports.js";
@@ -143,9 +143,25 @@ export function scanRepo(store, root, opts = {}) {
     }
     const gitMeta = useGit ? fileGitMetrics(root, rels, opts.churn === false ? 0 : 90) : null;
     let skipped = 0;
+    // Kustomize namespace transformers must be known before any manifest is
+    // extracted, so kustomization files are read up front (their reads are
+    // reused by the main loop below, not repeated).
+    const preRead = new Map();
+    const kustomizations = new Map();
     for (const file of files) {
-        const rel = file.path;
+        if (!isKustomizationFile(file.path))
+            continue;
         const read = file.read();
+        preRead.set(file.path, read);
+        if (!read.absent && read.source !== null) {
+            const dir = posix.dirname(file.path);
+            kustomizations.set(dir === "." ? "" : dir, extractKustomization(read.source));
+        }
+    }
+    const kustomizeNamespaceFor = kustomizeNamespaces(kustomizations, new Set(rels));
+    for (const file of files) {
+        const rel = file.path;
+        const read = preRead.get(rel) ?? file.read();
         if (read.absent) {
             sourceFingerprint.push({ path: rel, mode: read.mode, content: "absent" });
             continue;
@@ -227,20 +243,41 @@ export function scanRepo(store, root, opts = {}) {
         // otherwise be indistinguishable by offset alone, and the wrong (Helm)
         // symbol id could get recorded instead of the K8s one.
         const k8sSymbolObjects = new Set();
+        // Identity name a K8s symbol's id is derived from when its kind/name is
+        // NOT unique in this file (issue #382). Absent for the common unique case,
+        // so that id is exactly what it always was; a same-kind/name pair in
+        // different namespaces gets kind/name@namespace for EVERY member, never a
+        // document-order ordinal, so reordering documents can't rename them. The
+        // file path is already in every symbol id, so the same resource repeated
+        // across overlay dirs is distinct by path without any extra disambiguator.
+        const k8sIdNames = new Map();
         if (languageFor(rel)?.id === "yaml") {
-            k8sDocs = extractK8sManifest(src);
-            const k8sSymbols = k8sDocs
-                .filter((d) => d.resource !== null)
+            k8sDocs = kustomizeNamespaceFor.has(rel)
+                ? extractK8sManifest(src, { namespace: kustomizeNamespaceFor.get(rel) })
+                : extractK8sManifest(src);
+            const resourceDocs = k8sDocs
+                .filter((d) => d.resource !== null);
+            const nameCounts = new Map();
+            for (const d of resourceDocs) {
+                const name = `${d.resource.kind}/${displayNameText(d.resource.name)}`;
+                nameCounts.set(name, (nameCounts.get(name) ?? 0) + 1);
+            }
+            const k8sSymbols = resourceDocs
                 // k8sManifest.ts's own offsets are named *Char; mapped here into the
                 // shared startByte/endByte fields, same as the Helm merge above.
-                .map((d) => ({
-                name: `${d.resource.kind}/${displayNameText(d.resource.name)}`,
-                kind: "variable",
-                startByte: d.resource.startChar,
-                endByte: d.resource.endChar,
-                loc: src.slice(d.resource.startChar, d.resource.endChar).split("\n").length,
-                bodyText: src.slice(d.resource.startChar, d.resource.endChar).slice(0, MAX_BODY_TEXT_CHARS),
-            }));
+                .map((d) => {
+                const sym = {
+                    name: `${d.resource.kind}/${displayNameText(d.resource.name)}`,
+                    kind: "variable",
+                    startByte: d.resource.startChar,
+                    endByte: d.resource.endChar,
+                    loc: src.slice(d.resource.startChar, d.resource.endChar).split("\n").length,
+                    bodyText: src.slice(d.resource.startChar, d.resource.endChar).slice(0, MAX_BODY_TEXT_CHARS),
+                };
+                if ((nameCounts.get(sym.name) ?? 0) > 1)
+                    k8sIdNames.set(sym, `${sym.name}@${d.resource.namespace ?? ""}`);
+                return sym;
+            });
             for (const s of k8sSymbols)
                 k8sSymbolObjects.add(s);
             parsed.symbols = [...parsed.symbols, ...k8sSymbols].sort((a, b) => a.startByte - b.startByte);
@@ -253,10 +290,12 @@ export function scanRepo(store, root, opts = {}) {
         const idCounts = new Map(); // disambiguate same (file,name,kind)
         const k8sSymbolIdByStartByte = new Map();
         for (const [index, ps] of parsed.symbols.entries()) {
-            const base = symbolId(rel, ps.name, ps.kind);
+            const base = symbolId(rel, k8sIdNames.get(ps) ?? ps.name, ps.kind);
             const n = idCounts.get(base) ?? 0;
             idCounts.set(base, n + 1);
             // parse() returns symbols sorted by start byte, so the ordinal is stable
+            // (for K8s resources it is only reached by two documents with the SAME
+            // kind, namespace and name in one file -- indistinguishable by identity)
             const id = n === 0 ? base : `${base}_${n}`;
             idsInFile.push(id);
             symbolIndexId.set(index, id);