@davesheffer/hunch 1.40.0 → 1.41.0

package/dist/cli/index.js

@@ -36,7 +36,7 @@ import { publishedStatus } from "../integrations/registry.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { JsonStore } from "../store/jsonStore.js";
 import { selectEmbedder } from "../store/embedder.js";
-import { assertCompleteRepoScan, indexRepo, mergeScannedEdges, scanRepo } from "../extractors/indexer.js";
+import { assertCompleteRepoScan, assertNoTotalParseFailure, indexRepo, mergeScannedEdges, scanRepo } from "../extractors/indexer.js";
 // Importing this module is free (the addon load is a function call, not a
 // top-level side effect); only `doctor` below actually calls the loader.
 import { isParserLoadError, loadNativeTreeSitter } from "../extractors/nativeTreeSitter.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 ||
@@ -7227,11 +7280,12 @@ program
     // past the isolation guard) is invisible until an index run refuses.
     try {
         loadNativeTreeSitter();
+        assertNoTotalParseFailure(scanRepo(store, root, { churn: false }));
         console.log(`parser:     native tree-sitter addons load`);
     }
     catch (e) {
         console.log(`parser:     ⛔ ${e.message}`);
-        console.log(dim(`            no file can be parsed — \`hunch index\` refuses rather than emptying the graph`));
+        console.log(dim(`            \`hunch index\` refuses rather than replacing the graph after a parser failure`));
         process.exitCode = 1;
     }
     const c = store.reindex().counts;

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

@@ -1,5 +1,8 @@
 import { type LessonHistory, type TaskReport } from "./taskReport.js";
 export declare function writeTaskReportHtml(root: string, taskId: string, publicOnly?: boolean): string;
+/** Delivered lessons are named on the card up to this many; beyond it the
+ * count of the rest is stated, never a silent cut. */
+export declare const CARD_RECALLED_LIMIT = 8;
 /** One short line for the first time a lesson reaches a task; null when every
  * delivered revision was already seen in this task. Never a banner per delivery. */
 export declare function renderRecalledLine(fresh: readonly {

package/dist/core/taskReportRender.js

@@ -21,8 +21,15 @@ export function writeTaskReportHtml(root, taskId, publicOnly = false) {
     writeFileAtomic(file, publicOnly ? renderPublicTaskReportHtml(publicTaskReport(root, taskId)) : renderTaskReportHtml(report, undefined, histories));
     return file;
 }
+/** Card text is copied verbatim into an agent's final response, so every
+ * field is shown whole: a title cut mid-word with an ellipsis reads as a
+ * truncated tool result and the agent refuses to reproduce the card. Every
+ * rendered field is schema-bounded (task title and check label ≤ 200
+ * characters, record titles ≤ 500), so whole never means unbounded. */
 function plain(value) { return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").replace(/\s+/g, " ").trim(); }
-function clip(value, size = 66) { const chars = [...plain(value)]; return chars.length > size ? chars.slice(0, size - 1).join("") + "…" : chars.join(""); }
+/** Delivered lessons are named on the card up to this many; beyond it the
+ * count of the rest is stated, never a silent cut. */
+export const CARD_RECALLED_LIMIT = 8;
 function uniqueRecords(report) {
     return [...new Map(report.deliveries.flatMap(d => d.records).map(r => [`${r.kind}:${r.record_id}:${r.content_hash}`, r])).values()];
 }
@@ -42,44 +49,55 @@ export function renderRecalledLine(fresh) {
     if (!fresh.length)
         return null;
     const rest = fresh.length - 1;
-    return `Hunch recalled: ${clip(fresh[0].title, 90)}${rest ? ` (+${rest} more lesson${rest === 1 ? "" : "s"})` : ""}`;
+    return `Hunch recalled: ${plain(fresh[0].title)}${rest ? ` (+${rest} more lesson${rest === 1 ? "" : "s"})` : ""}`;
 }
 export function renderTaskReport(report) {
     const records = uniqueRecords(report);
-    const lines = [`Hunch · ${clip(report.task.title)}`, `Task ${report.task.task_id} · ${report.task.state}`];
+    const lines = [`Hunch · ${plain(report.task.title)}`, `Task ${report.task.task_id} · ${report.task.state}`];
     if (!report.deliveries.length)
         lines.push("No task-linked delivery observed; connection/use is unverified.");
     else if (!records.length)
         lines.push(report.coverage === "no-relevant-memory" ? "No relevant memory returned for this task." : "Memory delivered; exact record snapshots unavailable.");
     else {
-        lines.push(`Recalled  ${clip(records[0].title, 65)}`);
-        if (records.length > 1)
-            lines.push(`          ${records.length - 1} more lesson(s) in the evidence view`);
+        const named = records.slice(0, CARD_RECALLED_LIMIT);
+        lines.push(`Recalled  ${plain(named[0].title)}`);
+        for (const record of named.slice(1))
+            lines.push(`          ${plain(record.title)}`);
+        if (records.length > named.length)
+            lines.push(`          ${records.length - named.length} more lesson(s) in the evidence view`);
     }
     const standing = ruleStanding(report);
     const violated = standing.find(r => r.outcome === "violated");
     const held = standing.find(r => r.outcome === "satisfied" && r.current);
     if (report.claims.length) {
         const claim = report.claims.find(c => c.supported_by) ?? report.claims[0];
-        lines.push(`Applied   ${clip(claim.action, 42)} · ${claim.supported_by ? "rule-supported" : "agent-reported"}`);
+        lines.push(`Applied   ${plain(claim.action)} · ${claim.supported_by ? "rule-supported" : "agent-reported"}`);
     }
     else if (held)
-        lines.push(`Conformed ${clip(recordTitle(report, held), 34)} · rule held on ${held.files.length} changed file(s)`);
+        lines.push(`Conformed ${plain(recordTitle(report, held))} · rule held on ${held.files.length} changed file(s)`);
     else if (records.length)
         lines.push("Impact    Memory delivered; contribution unverified.");
     if (violated)
-        lines.push(`Violated  ${clip(recordTitle(report, violated), 34)} · rule broken on changed files`);
+        lines.push(`Violated  ${plain(recordTitle(report, violated))} · rule broken on changed files`);
     if (report.saves.length)
-        lines.push(`Saved     ${clip(report.saves[0].record.title, 38)} · ${report.saves[0].durability}`);
+        lines.push(`Saved     ${plain(report.saves[0].record.title)} · ${report.saves[0].durability}`);
     if (report.refusals.length)
-        lines.push(`Guarded   Denial emitted · ${clip(report.refusals[0].record_id, 40)}`);
+        lines.push(`Guarded   Denial emitted · ${plain(report.refusals[0].record_id)}`);
     const check = report.checks.at(-1);
     if (check) {
         const state = check.cancelled ? "cancelled" : check.timed_out ? "timed out" : check.exit_code === 0 ? "passed" : "failed";
-        lines.push(`Checked   ${clip(check.label, 28)} · ${state}${check.current ? " · current source snapshot" : " · current source unverified"}`);
+        lines.push(`Checked   ${plain(check.label)} · ${state}${check.current ? " · current source snapshot" : " · current source unverified"}`);
     }
     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");
 }
@@ -99,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/indexer.d.ts

@@ -46,6 +46,11 @@ export interface IndexRepoOptions {
  * false satisfied receipt. Call this after scanRepo when the consumer cannot
  * represent partial-graph uncertainty directly. */
 export declare function assertCompleteRepoScan(scan: RepoScan): void;
+/** A whole-language failure can be a broken grammar, not a set of bad files.
+ * Refuse the entire publication so cross-language edges and curated components
+ * remain consistent with the previous symbols. Read-only scans retain coverage
+ * and issues for diagnostics; a valid empty scan is still publishable. */
+export declare function assertNoTotalParseFailure(scan: RepoScan): void;
 /** Derive the current repository graph without writing JSON or rebuilding SQLite.
  * Read-only gates use this so checking changed code can never rewrite or publish
  * the durable graph merely by inspecting it. Existing public graph records remain

package/dist/extractors/indexer.js

@@ -35,6 +35,20 @@ export function assertCompleteRepoScan(scan) {
     const more = scan.issues.length > 5 ? ` (+${scan.issues.length - 5} more)` : "";
     throw new Error(`incomplete semantic source scan rejected ${scan.issues.length} file(s): ${sample}${more}`);
 }
+/** A whole-language failure can be a broken grammar, not a set of bad files.
+ * Refuse the entire publication so cross-language edges and curated components
+ * remain consistent with the previous symbols. Read-only scans retain coverage
+ * and issues for diagnostics; a valid empty scan is still publishable. */
+export function assertNoTotalParseFailure(scan) {
+    const failed = scan.result.coverage.filter((item) => item.eligible > 0 && item.reasons.parse_failed === item.eligible);
+    if (!failed.length)
+        return;
+    const details = failed.map((item) => {
+        const first = scan.issues.find((issue) => issue.code === "parse_failed" && languageFor(issue.path)?.id === item.language);
+        return `${item.language}: all ${item.eligible} eligible file(s) failed to parse; ${first?.detail ?? "unknown parse failure"}`;
+    });
+    throw new Error(`index refused — ${details.join("; ")}. Previous graph preserved.`);
+}
 /** Derive the current repository graph without writing JSON or rebuilding SQLite.
  * Read-only gates use this so checking changed code can never rewrite or publish
  * the durable graph merely by inspecting it. Existing public graph records remain
@@ -150,7 +164,7 @@ export function scanRepo(store, root, opts = {}) {
         // one bad/oversized file must never abort the whole index run
         let parsed;
         try {
-            parsed = parseSource(rel, src);
+            parsed = parseSource(rel, src, { throwOnParseError: true });
         }
         catch (error) {
             // …but a dead PARSER is not a bad file. The native addons load on first
@@ -163,7 +177,7 @@ export function scanRepo(store, root, opts = {}) {
             if (isParserLoadError(error))
                 throw error;
             skipped++;
-            issues.push({ path: rel, code: "parse_failed", detail: `${rel} could not be parsed` });
+            issues.push({ path: rel, code: "parse_failed", detail: `${rel} could not be parsed: ${error instanceof Error ? error.message : String(error)}` });
             noteSkip(rel, "parse_failed");
             continue;
         }
@@ -619,6 +633,7 @@ export function indexRepo(store, root, opts = {}) {
         ? { kind: "commit", ref: "HEAD" }
         : opts.source;
     const scan = scanRepo(store, root, { churn: opts.churn, source });
+    assertNoTotalParseFailure(scan);
     if (opts.requireComplete)
         assertCompleteRepoScan(scan);
     store.json.replaceAll("symbols", scan.symbols);

package/dist/extractors/parse.d.ts

@@ -34,7 +34,9 @@ export interface ParsedFile {
 /** Cap on a stored symbol's bodyText — large enough for review context, small
  *  enough that a huge function/file doesn't bloat every JSON symbol record. */
 export declare const MAX_BODY_TEXT_CHARS = 4000;
-export declare function parseSource(file: string, source: string): ParsedFile | null;
+export declare function parseSource(file: string, source: string, opts?: {
+    throwOnParseError?: boolean;
+}): ParsedFile | null;
 /** Map each call site to the innermost symbol whose byte-range contains it.
  *  Keyed by the symbol's position (index) in `parsed.symbols` — NOT its
  *  startByte, which is not a reliable per-symbol identity: a language whose

package/dist/extractors/parse.js

@@ -23,7 +23,7 @@ const STR_QUOTES = /^['"`]|['"`]$/g;
 /** Cap on a stored symbol's bodyText — large enough for review context, small
  *  enough that a huge function/file doesn't bloat every JSON symbol record. */
 export const MAX_BODY_TEXT_CHARS = 4000;
-export function parseSource(file, source) {
+export function parseSource(file, source, opts = {}) {
     const spec = languageFor(file);
     if (!spec)
         return null;
@@ -49,7 +49,11 @@ export function parseSource(file, source) {
     try {
         tree = parser.parse(source, undefined, { bufferSize: Math.max(32 * 1024, source.length * 2 + 1024) });
     }
-    catch {
+    catch (error) {
+        // Index scans need the underlying diagnostic for whole-language failures.
+        // Other callers retain the historical best-effort null result.
+        if (opts.throwOnParseError)
+            throw error;
         return null;
     }
     const symbols = [];

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)}` };