@davesheffer/hunch 1.40.1 → 1.41.1

package/dist/cli/index.js

@@ -395,7 +395,7 @@ program
         }
         else {
             writeFileAtomic(localFile, JSON.stringify({ ...existing, autoCommit: false }, null, 2) + "\n");
-            console.log("  ✓ auto-commit OFF (captures stay uncommitted; commit .hunch/ yourself)");
+            console.log("  ✓ local auto-commit preference OFF (an explicit hook --commit flag still takes precedence)");
         }
     }
     // Collected so the linked-worktree note below can say what actually happened
@@ -403,10 +403,21 @@ program
     const installs = [];
     if (isGitRepo(root)) {
         const syncToOverlay = !!(opts.privateSync || opts.sharedSync);
-        const h = installPostCommitHook(root, inv.shell, { private: syncToOverlay, commit: opts.autoCommit, localOnly: syncToOverlay });
+        // A default is not an explicit request to change the repo-wide hook.
+        // Linked init keeps an installed shared block's existing commit choice.
+        let hookCommit = opts.autoCommit;
+        if (hookCommit && isLinkedWorktree(root)) {
+            const existingHook = hookReport(root).postCommit;
+            if (existingHook.state === "installed")
+                hookCommit = existingHook.flags?.includes("--commit") ?? false;
+        }
+        const h = installPostCommitHook(root, inv.shell, { private: syncToOverlay, commit: hookCommit, localOnly: syncToOverlay });
         installs.push(h);
-        for (const line of formatHookInstall(root, "post-commit hook", h, ` (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${opts.autoCommit ? " — auto-commit on" : ""}`))
+        for (const line of formatHookInstall(root, "post-commit hook", h, ` (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${hookCommit ? " — auto-commit on" : ""}`))
             console.log(line);
+        if (opts.autoCommit === false && hookReport(root).postCommit.flags?.includes("--commit")) {
+            console.log("  ⚠ the shared post-commit hook still auto-commits. To change it, re-run `hunch init --no-auto-commit` using a global install or the main checkout's Hunch.");
+        }
         const pm = installPostMergeHook(root, inv.shell);
         installs.push(pm);
         for (const line of formatHookInstall(root, "post-merge hook", pm, " (squash-merge provenance repair + re-syncs grounding docs after a merge that brought memory in)"))
@@ -4570,6 +4581,48 @@ program
     console.log(`✓ ${oldId} superseded by ${opts.by} — window closed at ${closed.valid_to?.slice(0, 10)}.`);
     store.close();
 });
+// ---- retire-constraint -----------------------------------------------------
+program
+    .command("retire-constraint")
+    .description("Retire an active constraint: close its valid-time window (invalidate, don't delete) so `hunch check` and the strict hook stop enforcing it.")
+    .argument("<id>", "constraint id (con_*)")
+    .option("--reason <text>", "why it's being retired — recorded in the commit body, never the subject")
+    .action((id, opts) => {
+    const { store, root } = storeFor();
+    const existing = store.getRec("constraints", id);
+    if (!existing) {
+        store.close();
+        return fail(`constraint "${id}" not found`);
+    }
+    if (existing.status === "retired") {
+        store.close();
+        return fail(`constraint "${id}" is already retired — window closed at ${existing.valid_to?.slice(0, 10) ?? "unknown"}.`);
+    }
+    // Which store already holds the record decides where the close is written —
+    // same rule supersede applies to a decision's home (decisionMemoryHome).
+    const home = store.getPrivateRec("constraints", id) ? "private" : "public";
+    const retired = store.retireConstraint(existing);
+    store.reindex();
+    // Public grounding docs (CLAUDE.md's Top invariants list) are a publishable
+    // artifact: flushMemoryHome regenerates them on the SAME commit when auto-commit
+    // is on, but no commit happens to carry that refresh when it's off, so do it here
+    // too — otherwise a retired constraint keeps showing as enforced on disk (the same
+    // gap record-constraint and `conform --add` close for their own capture path).
+    if (home === "public" && !store.autoCommit)
+        refreshExistingGrounding(root, store);
+    // `--reason` goes in the commit BODY, never the subject: `hunch log`'s move
+    // classifier (src/core/memorylog.ts) regexes the commit SUBJECT for keywords
+    // like "supersed"/"repair"/"adopt"/"capture", so free-form reason text landing
+    // in the subject could accidentally match one and misclassify the move.
+    const willCommit = home === "private" ? store.privateAutoCommit : store.autoCommit;
+    const message = `hunch: retire constraint ${id}${opts.reason ? `\n\n${opts.reason}` : ""}`;
+    pumpMemoryHome(store, root, home, message);
+    console.log(`✓ ${retired.id} retired — window closed at ${retired.valid_to?.slice(0, 10)}.`);
+    if (opts.reason && !willCommit) {
+        console.log("  ⚠ --reason is not recorded anywhere: auto-commit is off, so no commit message captured it.");
+    }
+    store.close();
+});
 // ---- firmness (agent-hook enforcement level) ------------------------------
 program
     .command("firmness")
@@ -5212,7 +5265,7 @@ program
         // from this file. No diff exists yet, so this is context — "don't re-add X" —
         // not a block; the commit-time `hunch check` does the actual gating.
         const retired = store.retiredForFile(target).filter((r) => r.symbols.length || r.deps.length);
-        const recentTasks = taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, hookReportTaskId(root, provider, evt), target)), target);
+        const recentTasks = taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, hookReportTaskId(root, provider, evt), target, { excludeTargetDeliveries: true })), target);
         const hasContent = ctx.constraints.length ||
             ctx.decisions.length ||
             ctx.bugs.length ||

package/dist/core/paths.d.ts

@@ -5,7 +5,15 @@ export declare const HUNCH_DIR = ".hunch";
  *  `src\auth\session.ts` never matches the stored `src/auth/session.ts`). Safe on
  *  symbol names too: they contain no backslashes. This does NOT make a path
  *  repo-relative — an absolute path passes through with its separators flipped,
- *  unchanged otherwise; use `repoRelativeTarget` for that. */
+ *  unchanged otherwise; use `repoRelativeTarget` for that.
+ *
+ *  Inherently ambiguous for a string like `docs/notes\notes.md`: it could be a
+ *  Windows-style path with a literal separator, or a POSIX path whose filename
+ *  legitimately contains a backslash BYTE (illegal on Windows, legal on
+ *  POSIX/git) — the string alone can't say which, and this function always
+ *  assumes the former. A caller that can check the filesystem/git history and
+ *  needs the correct answer for a real file should decide from that evidence
+ *  instead of trusting this blindly. */
 export declare function toPosixTarget(target: string): string;
 /** realpath a path even if it doesn't exist yet (e.g. a new file an agent is about
  *  to Write, or a glob whose concrete segments aren't literal): resolve the longest

package/dist/core/paths.js

@@ -9,7 +9,15 @@ export const HUNCH_DIR = ".hunch";
  *  `src\auth\session.ts` never matches the stored `src/auth/session.ts`). Safe on
  *  symbol names too: they contain no backslashes. This does NOT make a path
  *  repo-relative — an absolute path passes through with its separators flipped,
- *  unchanged otherwise; use `repoRelativeTarget` for that. */
+ *  unchanged otherwise; use `repoRelativeTarget` for that.
+ *
+ *  Inherently ambiguous for a string like `docs/notes\notes.md`: it could be a
+ *  Windows-style path with a literal separator, or a POSIX path whose filename
+ *  legitimately contains a backslash BYTE (illegal on Windows, legal on
+ *  POSIX/git) — the string alone can't say which, and this function always
+ *  assumes the former. A caller that can check the filesystem/git history and
+ *  needs the correct answer for a real file should decide from that evidence
+ *  instead of trusting this blindly. */
 export function toPosixTarget(target) {
     return target.replace(/\\/g, "/").replace(/^\.\//, "");
 }

package/dist/core/taskQuery.d.ts

@@ -2,6 +2,8 @@ import { type RankingQuery } from "./taskRanking.js";
 export interface TaskQueryOptions {
     /** A phrase the caller has (hunch_context's target when it is not a path). */
     phrase?: string | null;
+    /** Automatic hooks must not feed their own target delivery back into ranking. */
+    excludeTargetDeliveries?: boolean;
     now?: number;
 }
 export declare function buildTaskRankingQuery(root: string, taskId: string | null | undefined, target: string, options?: TaskQueryOptions): RankingQuery;

package/dist/core/taskQuery.js

@@ -22,6 +22,8 @@ export function buildTaskRankingQuery(root, taskId, target, options = {}) {
         try {
             const report = readTaskReport(root, taskId);
             for (const d of report.deliveries) {
+                if (options.excludeTargetDeliveries && d.target && normalizePath(d.target) === normalizePath(target))
+                    continue;
                 if (d.target && targetLooksLikePath(d.target))
                     files.add(normalizePath(d.target));
                 for (const r of d.records)

package/dist/core/taskReportEvidence.js

@@ -257,7 +257,9 @@ export async function runReportCheck(root, taskId, command, label, timeoutMs = D
                 clearTimeout(drainTimer);
             child.stdout.destroy();
             child.stderr.destroy();
-            resolveResult({ code, timedOut, cancelled, hash: reportHash({ stdout: stdout.digest("hex"), stderr: stderr.digest("hex") }) });
+            // Windows taskkill produces exit code 1. That is the runner terminating
+            // the process, not an independently observed command result.
+            resolveResult({ code: timedOut || cancelled ? null : code, timedOut, cancelled, hash: reportHash({ stdout: stdout.digest("hex"), stderr: stderr.digest("hex") }) });
         };
         const stopTree = () => {
             if (settled || cleanupTimer)

package/dist/core/taskReportRender.js

@@ -90,6 +90,14 @@ export function renderTaskReport(report) {
     }
     else
         lines.push("Checked   No independent command result recorded.");
+    // Only a later run of the same argv supersedes a check. A different check
+    // passing (or an edit to source) cannot clear an earlier failure.
+    const latestChecks = new Map(report.checks.map(c => [JSON.stringify(c.command), c]));
+    const failures = [...latestChecks.values()].filter(c => c.cancelled || c.timed_out || c.exit_code !== 0);
+    if (failures.length) {
+        const names = failures.slice(0, 3).map(c => plain(c.label)).join("; ");
+        lines.push(`Failures  ${failures.length} unresolved check(s): ${names}${failures.length > 3 ? "; more in the evidence view" : ""}`);
+    }
     lines.push(`Evidence  hunch report ${report.task.task_id} --html`);
     return lines.join("\n");
 }
@@ -109,7 +117,7 @@ export function renderTaskReportHtml(report, generatedAt = new Date().toISOStrin
     const refusals = report.refusals.map(r => `<article><span class="badge">DENIAL EMITTED</span><h3>${esc(r.record_id)}</h3><p>Hunch emitted a ${esc(r.kind)} denial for ${esc(r.target)}.</p><p>This does not establish that the host honored the denial or that a bug was prevented.</p><details><summary>Inspect gate evidence</summary><dl><dt>Observed</dt><dd>${esc(r.at)}</dd><dt>Event</dt><dd>${esc(r.event_id)}</dd><dt>Exact response reason digest</dt><dd>${esc(r.reason_hash)}</dd></dl></details></article>`).join("");
     const history = histories === null ? empty("Lesson history is unavailable. The task evidence above is retained.") : histories.map(h => `<article><h3>${esc(h.entries[0]?.record.title ?? h.reference.record_id)}</h3><p>Save and delivery observations show where a lesson appeared; they do not prove use or additional impact.</p>${h.entries.map(e => `<details><summary>${esc(e.task.title)} · ${esc(e.task.state)}</summary><p>${e.event === "save" ? "Saved" : "Delivered"} ${esc(e.at)}</p><p class="lesson">${esc(e.record.lesson)}</p><dl><dt>Exact revision</dt><dd>${esc(e.record.content_hash)}</dd><dt>Evidence reference</dt><dd>${esc(e.receipt_id ?? e.event_id)}</dd></dl><p>Inspect this task: <code>hunch report ${esc(e.task.task_id)} --html</code></p></details>`).join("")}${!h.index_complete ? empty("History indexing is incomplete. Refresh for additional retained evidence.") : ""}${h.truncated ? empty("Additional deliveries are available through the lesson history command.") : ""}</article>`).join("");
     return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'"><title>Hunch · ${esc(report.task.title)}</title><style>
-:root{color-scheme:light dark;--bg:#f4f7f4;--paper:#fff;--ink:#162e24;--muted:#53685b;--line:#d5e1d8;--accent:#276540}*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.65 system-ui,sans-serif}main{max-width:920px;margin:auto;padding:48px 24px 80px}header{border-top:5px solid var(--accent);padding-top:24px;margin-bottom:40px}.eyebrow{font-size:12px;letter-spacing:.09em;color:var(--muted);font-weight:650}h1{font-size:clamp(28px,5vw,46px);line-height:1.15;letter-spacing:-.035em;margin:16px 0}h2{font-size:22px;margin:32px 0 12px}h3{font-size:18px;margin:12px 0 6px}p{margin:8px 0}article{background:var(--paper);border:1px solid var(--line);border-radius:12px;padding:22px;margin:12px 0}.muted,dt{color:var(--muted)}.badge{font-size:11px;letter-spacing:.06em;border:1px solid var(--line);border-radius:30px;padding:5px 10px}.lesson{white-space:pre-wrap}a{color:var(--accent);text-underline-offset:3px}a:focus-visible,summary:focus-visible{outline:3px solid var(--accent);outline-offset:5px}summary{cursor:pointer;font-weight:600;padding:8px 0}details{margin-top:16px}pre,code,dd{overflow-wrap:anywhere;word-break:break-word}pre{white-space:pre-wrap;font:13px/1.6 ui-monospace,monospace;padding:14px;background:var(--bg);border-radius:8px}dd{margin:0 0 12px}footer{border-top:1px solid var(--line);margin-top:36px;padding-top:20px;font-size:12px;color:var(--muted)}@media(prefers-color-scheme:dark){:root{--bg:#101b16;--paper:#17271e;--ink:#e3eee6;--muted:#a7b9ac;--line:#365041;--accent:#9cdbb0}}@media print{details>*{display:block}body{background:white;color:black}article{break-inside:avoid}}
+:root{color-scheme:light dark;--bg:#f4f7f4;--paper:#fff;--ink:#162e24;--muted:#53685b;--line:#d5e1d8;--accent:#276540}*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.65 system-ui,sans-serif}main{max-width:920px;margin:auto;padding:48px 24px 80px}header{border-top:5px solid var(--accent);padding-top:24px;margin-bottom:40px}.eyebrow{font-size:12px;letter-spacing:.09em;color:var(--muted);font-weight:650}h1{font-size:clamp(28px,5vw,46px);line-height:1.15;letter-spacing:-.035em;margin:16px 0}h2{font-size:22px;margin:32px 0 12px}h3{font-size:18px;margin:12px 0 6px}p{margin:8px 0}article{background:var(--paper);border:1px solid var(--line);border-radius:12px;padding:22px;margin:12px 0}.muted,dt{color:var(--muted)}.badge{font-size:11px;letter-spacing:.06em;border:1px solid var(--line);border-radius:30px;padding:5px 10px}.lesson{white-space:pre-wrap}a{color:var(--accent);text-underline-offset:3px}a:focus-visible,summary:focus-visible{outline:3px solid var(--accent);outline-offset:5px}summary{cursor:pointer;font-weight:600;padding:8px 0}details{margin-top:16px}pre,code,dd,footer{overflow-wrap:anywhere;word-break:break-word}pre{white-space:pre-wrap;font:13px/1.6 ui-monospace,monospace;padding:14px;background:var(--bg);border-radius:8px}dd{margin:0 0 12px}footer{border-top:1px solid var(--line);margin-top:36px;padding-top:20px;font-size:12px;color:var(--muted)}@media(prefers-color-scheme:dark){:root{--bg:#101b16;--paper:#17271e;--ink:#e3eee6;--muted:#a7b9ac;--line:#365041;--accent:#9cdbb0}}@media print{details>*{display:block}body{background:white;color:black}article{break-inside:avoid}}
 </style></head><body><main><header><div class="eyebrow">HUNCH · TASK EVIDENCE · LOCAL REPORT</div><h1>${esc(report.task.title)}</h1><p>${records.length ? "Project experience carried into this task." : "What Hunch could observe in this task."}</p><p class="muted">${esc(report.task.state)} · ${esc(report.task.started_at)} · ${esc(report.task.task_id)}</p></header>${section("1. What the project remembered", lessons || empty("No lesson snapshot is available for this task."))}${section("2. What reached the agent", deliveries || empty("No task-linked delivery was observed. This does not prove the agent was disconnected."))}${section("3. How the agent says it applied", claims || empty("Contribution is unverified. A context delivery alone does not establish use."))}${section("4. What was checked", checks || empty("No independent command result was recorded."))}${section("5. How the change conforms to delivered rules", rules || empty("No delivered rule was evaluated. Finishing a task, or hunch task conform, evaluates each delivered lesson's declared rule against the changed files."))}${saves ? section("What was saved for future tasks", saves) : ""}${refusals ? section("When Hunch intervened", refusals) : ""}${section("Where this lesson appeared", (history || empty("No lesson history is included in this view.")) + (histories && historyRecords(report).length > histories.length ? empty(`History shown for ${histories.length} of ${historyRecords(report).length} lesson revisions. Inspect another revision with hunch report --lesson <record-id> --kind <kind> --revision <content-hash>.`) : ""))}${section("What remains unknown", report.unknowns.length ? `<ul>${report.unknowns.map(x => `<li>${esc(x)}</li>`).join("")}</ul>` : empty("The report makes no additional causal claim."))}<footer>Generated ${esc(generatedAt)}. This is a saved snapshot, not a live source check.<br>After editing source, refresh with <code>hunch report ${esc(report.task.task_id)} --html</code>.<br>Observed evidence, not a score or an estimate of bugs prevented.<br>Report ${esc(report.content_hash)}<br>Local report may contain private project memory. Keep it within the project's authorized audience.</footer></main></body></html>`;
 }
 //# sourceMappingURL=taskReportRender.js.map

package/dist/extractors/git.d.ts

@@ -159,6 +159,43 @@ export declare function gitCommonDir(cwd: string): string;
 /** True when `cwd` is inside a LINKED worktree (not the main checkout): its own git
  *  dir differs from the shared common dir. Used by `hunch doctor` and setup messaging. */
 export declare function isLinkedWorktree(cwd: string): boolean;
+/** Every worktree of this repo (the main checkout AND every linked one), as absolute
+ *  paths — parsed from `git worktree list --porcelain`. Named for what it returns, not
+ *  `linkedWorktreePaths`: unlike `isLinkedWorktree`, this deliberately includes the main
+ *  checkout, since callers need it for self-exclusion. Lets a write tool guess where an
+ *  auto-commit actually belongs when its own evidence (e.g. a decision's related_files)
+ *  doesn't exist at the resolved root but does exist in a sibling worktree — a caller
+ *  working in a linked worktree that forgot to pass a cwd hint. Empty on any error /
+ *  non-repo. */
+export declare function worktreePaths(root: string): string[];
+/** True when `root`'s OWN history has ever tracked `file` — EXACTLY `file`, not
+ *  merely something under it — at HEAD. Distinguishes an ordinary delete/rename
+ *  recorded correctly at the resolved root (the file is gone here because THIS
+ *  checkout removed it, and a sibling worktree that branched earlier simply
+ *  predates the change) from a genuine misroute: without this check, deleting or
+ *  renaming a tracked file at the correct root reads as evidence the write
+ *  belonged in whichever sibling still has the old path, refusing a correct write
+ *  and pointing the caller at the wrong worktree. `git log --name-only` alone
+ *  treats `file` as an ordinary PATHSPEC: a directory name or a glob matches
+ *  anything under/matching it, so "src" or "*.ts" would read as "known to
+ *  history" whenever ANYTHING under that directory was ever tracked, anywhere in
+ *  the repo. `:(literal)` disables glob/magic interpretation, and checking the
+ *  commit's OWN changed-file list for an exact string match (not just "the
+ *  pathspec matched something") confirms `file` was itself a tracked PATH.
+ *
+ *  `--diff-merges=first-parent` makes a merge commit report its own changes like
+ *  an ordinary commit instead of being skipped by diff simplification (the
+ *  `--name-only` default prints nothing at all for a merge). `-z` (NUL-separated,
+ *  read via the untrimmed `gitRawSafe`) sidesteps git's path-quoting rules
+ *  entirely, so a name containing a quote, backslash, control character, or a
+ *  leading/trailing space compares exactly rather than being C-quoted or trimmed
+ *  away.
+ *
+ *  `file` must be non-empty: `-z` NUL-terminates every entry rather than
+ *  separating them, so splitting on "\0" always yields a trailing "" element —
+ *  and an empty pathspec matches everything, so an empty `file` would otherwise
+ *  read as "known to history" for any repo with history at all. */
+export declare function pathKnownToHistory(root: string, file: string): boolean;
 /** Current branch name (e.g. "main", "feat/x"), or "" in detached HEAD / non-repo.
  *  Stamped onto auto-captured decisions so branch-scoped work stays filterable. */
 export declare function currentBranch(cwd: string): string;

package/dist/extractors/git.js

@@ -3,7 +3,7 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { devNull, tmpdir } from "node:os";
-import { isAbsolute, resolve, join, basename, dirname, relative, sep } from "node:path";
+import { isAbsolute, resolve, join, basename, dirname, relative, sep, posix } from "node:path";
 import { mkdtempSync, openSync, closeSync, readSync, mkdirSync, rmSync, statSync, lstatSync, realpathSync, readFileSync, renameSync, readdirSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { MEMLOG_FORMAT } from "../core/memorylog.js";
@@ -1927,6 +1927,61 @@ export function isLinkedWorktree(cwd) {
     // macOS, or long vs 8.3/case variants on Windows. Compare physical identity.
     return !sameFilesystemEntry(own, common);
 }
+/** Every worktree of this repo (the main checkout AND every linked one), as absolute
+ *  paths — parsed from `git worktree list --porcelain`. Named for what it returns, not
+ *  `linkedWorktreePaths`: unlike `isLinkedWorktree`, this deliberately includes the main
+ *  checkout, since callers need it for self-exclusion. Lets a write tool guess where an
+ *  auto-commit actually belongs when its own evidence (e.g. a decision's related_files)
+ *  doesn't exist at the resolved root but does exist in a sibling worktree — a caller
+ *  working in a linked worktree that forgot to pass a cwd hint. Empty on any error /
+ *  non-repo. */
+export function worktreePaths(root) {
+    const out = gitSafe(["worktree", "list", "--porcelain"], root);
+    if (!out)
+        return [];
+    const paths = [];
+    for (const line of out.split("\n")) {
+        if (line.startsWith("worktree "))
+            paths.push(line.slice("worktree ".length).trim());
+    }
+    return paths;
+}
+/** True when `root`'s OWN history has ever tracked `file` — EXACTLY `file`, not
+ *  merely something under it — at HEAD. Distinguishes an ordinary delete/rename
+ *  recorded correctly at the resolved root (the file is gone here because THIS
+ *  checkout removed it, and a sibling worktree that branched earlier simply
+ *  predates the change) from a genuine misroute: without this check, deleting or
+ *  renaming a tracked file at the correct root reads as evidence the write
+ *  belonged in whichever sibling still has the old path, refusing a correct write
+ *  and pointing the caller at the wrong worktree. `git log --name-only` alone
+ *  treats `file` as an ordinary PATHSPEC: a directory name or a glob matches
+ *  anything under/matching it, so "src" or "*.ts" would read as "known to
+ *  history" whenever ANYTHING under that directory was ever tracked, anywhere in
+ *  the repo. `:(literal)` disables glob/magic interpretation, and checking the
+ *  commit's OWN changed-file list for an exact string match (not just "the
+ *  pathspec matched something") confirms `file` was itself a tracked PATH.
+ *
+ *  `--diff-merges=first-parent` makes a merge commit report its own changes like
+ *  an ordinary commit instead of being skipped by diff simplification (the
+ *  `--name-only` default prints nothing at all for a merge). `-z` (NUL-separated,
+ *  read via the untrimmed `gitRawSafe`) sidesteps git's path-quoting rules
+ *  entirely, so a name containing a quote, backslash, control character, or a
+ *  leading/trailing space compares exactly rather than being C-quoted or trimmed
+ *  away.
+ *
+ *  `file` must be non-empty: `-z` NUL-terminates every entry rather than
+ *  separating them, so splitting on "\0" always yields a trailing "" element —
+ *  and an empty pathspec matches everything, so an empty `file` would otherwise
+ *  read as "known to history" for any repo with history at all. */
+export function pathKnownToHistory(root, file) {
+    if (!file)
+        return false;
+    const out = gitRawSafe(["log", "-n", "1", "--format=", "--name-only", "-z", "--diff-merges=first-parent", "HEAD", "--", `:(literal)${file}`], root);
+    // Git reports repository-relative paths without dot segments. Normalize only
+    // slash segments for comparison, retaining literal backslashes and whitespace.
+    const comparable = posix.normalize(file);
+    return !!out && out.split("\0").some((entry) => entry === comparable);
+}
 /** Current branch name (e.g. "main", "feat/x"), or "" in detached HEAD / non-repo.
  *  Stamped onto auto-captured decisions so branch-scoped work stays filterable. */
 export function currentBranch(cwd) {

package/dist/extractors/languages.d.ts

@@ -42,12 +42,19 @@ export interface LanguageSpec {
     /** Ancestor shapes in which an ERROR node is a known limitation of THIS grammar
      *  rather than a real syntax error. parse.ts forgives an error only when some
      *  ancestor has type `node` AND that ancestor's own parent has type `parentIs` —
-     *  the pair is what keeps the tolerance narrow. Omit for a language with no known
-     *  grammar false positives; that spec then stays strictly fail-closed. */
+     *  the pair is what keeps the tolerance narrow. `textPattern`, when present,
+     *  must also match that ancestor's text. Omit for a language with no
+     *  known grammar false positives; that spec then stays strictly fail-closed. */
     toleratedErrorScopes?: ReadonlyArray<{
         readonly node: string;
         readonly parentIs: string;
+        readonly textPattern?: RegExp;
     }>;
+    /** Optional same-length recovery used only when the original syntax tree is
+     *  not parseable. A recovered tree may classify structure, but parse.ts reads
+     *  every captured value from the original source at the tree's unchanged
+     *  offsets. Keep replacements syntax-equivalent outside the grammar defect. */
+    parseErrorRecovery?: (source: string) => string;
     /** Patterns whose presence anywhere in the source mean "this isn't actually
      *  {id} text yet — it's a template that renders to {id} later" (Go/Jinja/Helm
      *  delimiters in a .yaml file, e.g.). parse.ts still runs the real parse — a

package/dist/extractors/languages.js

@@ -81,6 +81,19 @@ const TSX = {
     extensions: [".tsx", ".jsx"],
     grammarKey: "tsx",
     loadGrammar: () => loadNativeTreeSitter().tsx,
+    // tree-sitter-javascript rejects a bare ampersand in JSX text even though JSX
+    // accepts it (tree-sitter-javascript#366). The ERROR is a direct jsx_element
+    // child and its text begins at the ampersand. Require both facts plus text that
+    // cannot cross into a tag or expression; real JSX errors beside it remain fail-closed.
+    toleratedErrorScopes: [
+        ...TS_SHARED.toleratedErrorScopes,
+        { node: "ERROR", parentIs: "jsx_element", textPattern: /^&[^<>{}]*$/u },
+    ],
+    // More than one bare ampersand can make the grammar collapse the entire TSX
+    // tree instead of emitting the narrow ERROR above. `|` is accepted as JSX
+    // text and has the same length; in JS/TS syntax it preserves ampersand
+    // operators' arity, so malformed expressions remain malformed on the retry.
+    parseErrorRecovery: (source) => source.replaceAll("&", "|"),
 };
 const PY_QUERY = `
   (class_definition

package/dist/extractors/parse.js

@@ -56,11 +56,35 @@ export function parseSource(file, source, opts = {}) {
             throw error;
         return null;
     }
+    let parseable = isParseable(tree.rootNode, spec);
+    let usingRecoveredTree = false;
+    if (!parseable && spec.parseErrorRecovery) {
+        const recoveredSource = spec.parseErrorRecovery(source);
+        // Offsets from the recovery tree are used against the original source below.
+        // Refuse a misconfigured recovery rather than corrupt captured names/text.
+        if (recoveredSource.length === source.length) {
+            try {
+                const recoveredTree = parser.parse(recoveredSource, undefined, { bufferSize: Math.max(32 * 1024, recoveredSource.length * 2 + 1024) });
+                if (isParseable(recoveredTree.rootNode, spec)) {
+                    tree = recoveredTree;
+                    parseable = true;
+                    usingRecoveredTree = true;
+                }
+            }
+            catch (error) {
+                if (opts.throwOnParseError)
+                    throw error;
+            }
+        }
+    }
     const symbols = [];
     const imports = [];
     const calls = [];
     const relations = [];
     let namespace = null;
+    const originalText = (node) => usingRecoveredTree
+        ? source.slice(node.startIndex, node.endIndex)
+        : node.text;
     // group captures by their enclosing @*.def via a quick pass: we record names
     // keyed by the def node, then emit a symbol per def.
     const pendingDefs = new Map();
@@ -82,30 +106,32 @@ export function parseSource(file, source, opts = {}) {
             if (defNode) {
                 const existing = pendingDefs.get(defNode.id);
                 if (existing)
-                    existing.name = node.text;
+                    existing.name = originalText(node);
                 else
-                    pendingDefs.set(defNode.id, { kind: spec.defKindOf[spec.nameToDef[cname]], def: defNode, name: node.text });
+                    pendingDefs.set(defNode.id, { kind: spec.defKindOf[spec.nameToDef[cname]], def: defNode, name: originalText(node) });
             }
             if (cname === "namespace.name")
-                namespace = node.text;
+                namespace = originalText(node);
         }
         else if (cname === "import.src") {
-            imports.push(node.text.replace(STR_QUOTES, ""));
+            imports.push(originalText(node).replace(STR_QUOTES, ""));
         }
         else if (cname === "call.id") {
-            if (!spec.builtinFunctions?.has(node.text)) {
-                calls.push({ callee: node.text, atByte: node.startIndex, endByte: node.endIndex, member: false });
+            const text = originalText(node);
+            if (!spec.builtinFunctions?.has(text)) {
+                calls.push({ callee: text, atByte: node.startIndex, endByte: node.endIndex, member: false });
             }
         }
         else if (cname === "call.member") {
             // skip builtin method names to avoid false edges to similarly-named symbols
-            if (!spec.builtinMethods.has(node.text))
-                calls.push({ callee: node.text, atByte: node.startIndex, endByte: node.endIndex, member: true });
+            const text = originalText(node);
+            if (!spec.builtinMethods.has(text))
+                calls.push({ callee: text, atByte: node.startIndex, endByte: node.endIndex, member: true });
         }
         else if (spec.relationKindOf?.[cname]) {
             const relation = spec.relationKindOf[cname];
             relations.push({
-                target: node.text,
+                target: originalText(node),
                 atByte: node.startIndex,
                 endByte: node.endIndex,
                 edgeType: relation.edgeType,
@@ -121,7 +147,7 @@ export function parseSource(file, source, opts = {}) {
         symbols.push({
             name: resolvedName, kind,
             startByte: def.startIndex, endByte: def.endIndex, loc,
-            bodyText: def.text.slice(0, MAX_BODY_TEXT_CHARS),
+            bodyText: originalText(def).slice(0, MAX_BODY_TEXT_CHARS),
         });
     }
     // Every other successfully-parsed YAML file gets at least a file-root symbol
@@ -141,7 +167,7 @@ export function parseSource(file, source, opts = {}) {
         });
     }
     symbols.sort((a, b) => a.startByte - b.startByte);
-    return { symbols, imports, calls, relations, namespace, parseable: templated || isParseable(tree.rootNode, spec) };
+    return { symbols, imports, calls, relations, namespace, parseable: templated || parseable };
 }
 /** True when every ERROR/MISSING node in the tree sits in an ancestor shape this
  *  language declares as a known grammar limitation (LanguageSpec.toleratedErrorScopes).
@@ -177,9 +203,11 @@ function isParseable(root, spec) {
     return ok;
 }
 function inToleratedScope(node, scopes) {
-    for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+    for (let ancestor = node; ancestor; ancestor = ancestor.parent) {
         for (const scope of scopes) {
-            if (ancestor.type === scope.node && ancestor.parent?.type === scope.parentIs)
+            if (ancestor.type === scope.node
+                && ancestor.parent?.type === scope.parentIs
+                && (!scope.textPattern || ancestor.text.search(scope.textPattern) !== -1))
                 return true;
         }
     }

package/dist/integrations/hooks.js

@@ -17,13 +17,13 @@ import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync, realpath
 import { spawnSync } from "node:child_process";
 import { join, isAbsolute, dirname, basename, relative, resolve } from "node:path";
 import { homedir } from "node:os";
-import { hooksDir, gitCommonDir, isLinkedWorktree } from "../extractors/git.js";
+import { hooksDir, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
 import { initiatorChildEnv } from "../synthesis/initiator.js";
-import { HUNCH_NPX_PACKAGE_SPEC } from "../core/version.js";
+import { HUNCH_NPX_PACKAGE_SPEC, HUNCH_PACKAGE_NAME } from "../core/version.js";
 const MARK = "# >>> hunch post-commit >>>";
 const ENDMARK = "# <<< hunch post-commit <<<";
-const GIT_CONTEXT = { checkoutType: "$3" };
-const PRE_COMMIT_CONTEXT = { checkoutType: "$PRE_COMMIT_CHECKOUT_TYPE" };
+const GIT_CONTEXT = { checkoutType: "$3", portable: false };
+const PRE_COMMIT_CONTEXT = { checkoutType: "$PRE_COMMIT_CHECKOUT_TYPE", portable: true };
 const LOCAL_ONLY_LINE = "  export HUNCH_SYNTH_PROVIDER=deterministic";
 // Tolerates hand-added quotes: missing the line would let a re-run delete it.
 const LOCAL_ONLY_RE = /^\s*export HUNCH_SYNTH_PROVIDER=["']?deterministic["']?\s*$/m;
@@ -497,7 +497,7 @@ function snippetFor(t, mark, build, localInvocation) {
         // Untracked local hook: this machine's invocation is fine; placement is the fix.
         return `# insert ABOVE the final exec/exit in ${t.hookName}\n${build(localInvocation, GIT_CONTEXT)}`;
     }
-    return build(PORTABLE_HOOK_INVOCATION, GIT_CONTEXT);
+    return build(PORTABLE_HOOK_INVOCATION, { ...GIT_CONTEXT, portable: true });
 }
 /** The repo's worktree tops as `git worktree list --porcelain` reports them:
  *  `linked` is every entry AFTER the first (the first is always the main
@@ -711,8 +711,58 @@ function installManagedBlock(root, hookName, mark, end, build, invocation) {
     chmodSync(hookPath, 0o755);
     return { path: hookPath, action: "appended", ...sharedNote };
 }
+/** True when `root` is a checkout of Hunch's OWN source tree (its own
+ *  package.json declares this exact package name), not merely a project that
+ *  depends on Hunch — the same detection `hunch update` already uses to
+ *  refuse running inside this repo (src/cli/update.ts). */
+function isHunchRepoRoot(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return pkg.name === HUNCH_PACKAGE_NAME;
+    }
+    catch {
+        return false;
+    }
+}
+/** For a doc-regenerating hook (post-commit's `sync`, post-merge's grounding
+ *  refresh) installed inside Hunch's own checkout, force the invocation to
+ *  that checkout's own in-tree build; every other project keeps the passed
+ *  invocation unchanged. Without this, the hook bakes in whatever build the
+ *  INSTALLING process happened to be running (a stale/newer global install,
+ *  npx, another checkout) — which then regenerates CLAUDE.md/AGENTS.md/etc.
+ *  from a DIFFERENT generator than this checkout's own, silently drifting the
+ *  committed docs out of sync (caught only by a doc-freshness test).
+ *
+ *  Anchored to the MAIN worktree, not `root` itself: the hook FILE this
+ *  produces is the one `hooksDir` resolves to, shared across every linked
+ *  worktree of the repo, but `root` is merely whichever worktree happened to
+ *  run the install — often an ephemeral one under an agent-worktree workflow.
+ *  Baking in a linked worktree's own path would silently break every OTHER
+ *  worktree's shared hook the moment that one is `git worktree remove`d.
+ *
+ *  Existence-checked rather than assumed: a Hunch-named checkout that ships
+ *  no `src/` (a sparse checkout, or one built from the published tarball —
+ *  `dist/**` only) would otherwise get a hook block that silently no-ops
+ *  forever (it's wrapped `|| true`) — the exact invisible-staleness failure
+ *  this override exists to close, just moved one step. */
+function selfBuildInvocation(root, invocation) {
+    const main = mainWorktreeRoot(root);
+    if (!isHunchRepoRoot(main))
+        return invocation;
+    const entry = join(main, "src", "cli", "index.ts");
+    const tsx = join(main, "node_modules", "tsx", "dist", "cli.mjs");
+    if (!existsSync(entry) || !existsSync(tsx))
+        return invocation;
+    // process.execPath against tsx's own cli.mjs, not a bare `npx tsx`: a GUI git
+    // client or non-interactive shell commonly lacks nvm's npx/tsx on PATH — the
+    // same reason resolveInvocation's installed/dist branches avoid a bare `node`
+    // (src/cli/invocation.ts).
+    return `${JSON.stringify(process.execPath)} ${JSON.stringify(tsx)} ${JSON.stringify(entry)}`;
+}
 export function installPostCommitHook(root, invocation, opts = {}) {
-    return installManagedBlock(root, "post-commit", MARK, ENDMARK, (inv, _ctx, keep) => block(inv, opts, keep), invocation);
+    // Resolve shared invocation/flags before selecting the in-tree generator.
+    // Rewriting the caller first hides that it came from a linked worktree.
+    return installManagedBlock(root, "post-commit", MARK, ENDMARK, (inv, ctx, keep) => block(ctx.portable ? inv : selfBuildInvocation(root, inv), opts, keep), invocation);
 }
 const PRE_MARK = "# >>> hunch pre-commit (constraint guard) >>>";
 const PRE_END = "# <<< hunch pre-commit <<<";
@@ -787,7 +837,10 @@ const writes = (h) => h.action !== "managed-elsewhere" && h.action !== "unreacha
  *  a repo carrying only one half (an older install, or a hand-edited hook)
  *  gets the other appended rather than clobbered. */
 export function installPostMergeHook(root, invocation) {
-    const grounding = installManagedBlock(root, "post-merge", GROUNDING_MERGE_MARK, GROUNDING_MERGE_END, groundingMergeBlock, invocation);
+    // Only the grounding half regenerates committed docs; repair-provenance writes
+    // no docs (it only queues a match for a human to confirm), so it keeps the
+    // passed invocation unchanged — see selfBuildInvocation.
+    const grounding = installManagedBlock(root, "post-merge", GROUNDING_MERGE_MARK, GROUNDING_MERGE_END, (inv, ctx) => groundingMergeBlock(ctx.portable ? inv : selfBuildInvocation(root, inv)), invocation);
     const repair = installManagedBlock(root, "post-merge", REPAIR_MERGE_MARK, REPAIR_MERGE_END, repairProvenanceMergeBlock, invocation);
     if (!writes(grounding) && !writes(repair)) {
         return { ...grounding, snippet: `${grounding.snippet}\n${stripComment(repair.snippet ?? "", grounding.manager)}` };

package/dist/integrations/team.js

@@ -19,15 +19,25 @@ import { installMergeDriver } from "./mergeDriver.js";
 import { ensureGitignore } from "./gitignore.js";
 import { resolveInvocation } from "../cli/invocation.js";
 export const DEFAULT_TEAM_REF = "refs/heads/main";
+// check-ref-format without --branch checks syntax only, independent of the
+// repository, ref existence, or remote state. Retain just its last successful
+// input: one shared sync can otherwise spawn Git dozens of times for the same
+// name. Route/remote validation still runs afresh, and failed invocations retry.
+let lastValidTeamRef;
 export function safeTeamRef(value) {
     const ref = value.trim();
     if (!ref.startsWith("refs/heads/") || ref === "refs/heads/")
         return null;
+    if (ref === lastValidTeamRef)
+        return ref;
     const checked = spawnSync("git", ["check-ref-format", ref], {
         stdio: "ignore",
         env: { ...process.env, GIT_CONFIG_NOSYSTEM: "1" },
     });
-    return checked.status === 0 ? ref : null;
+    if (checked.status !== 0)
+        return null;
+    lastValidTeamRef = ref;
+    return ref;
 }
 export function teamSharedRef(team) {
     return team.shared_ref ?? DEFAULT_TEAM_REF;