@davesheffer/hunch 1.39.2 → 1.40.0

package/dist/cli/index.js

@@ -14,13 +14,13 @@
  *   doctor    environment diagnostics
  */
 import "./preflight.js"; // MUST stay the first import — Node-version gate before node:sqlite loads
-import { chmodSync, existsSync, lstatSync, readFileSync, readdirSync, readlinkSync, writeFileSync, mkdirSync, mkdtempSync, realpathSync, rmSync, rmdirSync, symlinkSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, readFileSync, readdirSync, readlinkSync, writeFileSync, mkdirSync, mkdtempSync, rmSync, rmdirSync, symlinkSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import { join, relative, dirname, basename, resolve, isAbsolute } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget, isDir } from "../core/paths.js";
+import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget, isDir, realpathNorm, repoRelativeTarget } from "../core/paths.js";
 import { writeFileAtomic } from "../core/io.js";
 import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
@@ -36,7 +36,10 @@ 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, scanRepo } from "../extractors/indexer.js";
+import { assertCompleteRepoScan, 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";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, normalizeProviderName, } from "../synthesis/provider.js";
@@ -52,7 +55,7 @@ import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
 import { extractInlineIntent } from "../extractors/comments.js";
 import { renderText, renderMarkdown, renderSarif, renderImpact, reportFailsStrict } from "../core/checkreport.js";
 import { partitionReview, isReviewDraft, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
-import { installPostCommitHook, installPreCommitHook, installPostMergeHook, installPostCheckoutHook, hookStatus, hookReport, formatHookInstall } from "../integrations/hooks.js";
+import { installPostCommitHook, installPreCommitHook, installPostMergeHook, installPostCheckoutHook, hookStatus, hookReport, hookInvocationLines, formatHookInstall, sharedHooksNote } from "../integrations/hooks.js";
 import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
 import { flushCapture, flushMemoryHome, flushMemoryHomes, pinSharedRemote, sharedRemoteFor } from "../integrations/sync.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
@@ -72,7 +75,7 @@ import { rankingStatusLine, resolveTaskRankingMode } from "../core/taskRankingMo
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
-import { buildDeliveryEnvelope, DELIVERY_PROFILES } from "../core/delivery.js";
+import { buildDeliveryEnvelope, deliveryDedupeInput, DELIVERY_PROFILES } from "../core/delivery.js";
 import { deriveChangeIdentity } from "../core/changeIdentity.js";
 import { deriveChangeProof } from "../core/changeProof.js";
 import { discoverProjectDna, evaluateProjectDnaMatch } from "../core/projectDna.js";
@@ -80,7 +83,7 @@ import { diffProjectDna } from "../core/projectDnaDelta.js";
 import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness, workspacesConfig } from "../core/config.js";
 import { loadOrCreateMachine, setMachineLabel, machineFile, labelLeaksIdentity } from "../core/machine.js";
-import { worktreeRows, branchRows } from "../core/workspace.js";
+import { worktreeRows, branchRows, publicWorkspaceRemovalRecipe } from "../core/workspace.js";
 import { workspaceLedgerView, recordWorkspaceSnapshot, renderWorktreeTable, renderBranchTable, workspaceSummaryLine, prunePlanFor, renderPrunePlan, applyPrune, confirmPrune, pruneConfirmQuestion } from "../integrations/workspaceLedger.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { isHumanConfirmed } from "../core/strictgate.js";
@@ -88,7 +91,7 @@ import { appendEvent, readEvents } from "../core/events.js";
 import { computeStats, formatStats } from "../core/stats.js";
 import { injectionMode, resetSessionInjections } from "../core/hookcache.js";
 import { recordServed, servedSummary } from "../core/served.js";
-import { recordTaskDelivery, reportActivity, reportPresentationEnabled, unseenLessons } from "../core/taskReport.js";
+import { recordTaskDelivery, reportActivity, reportHash, reportPresentationEnabled, unseenLessons } from "../core/taskReport.js";
 import { snapshotDeliveredRecords } from "../core/taskReportEvidence.js";
 import { renderRecalledLine } from "../core/taskReportRender.js";
 import { closeHookTask, hookReportTaskId, nativeHookCwd, settleHookSession, startHookReport, stopHookReport, observeHookDenial } from "../core/taskReportHook.js";
@@ -363,7 +366,7 @@ program
             // any mutator. With no commit identity there is no safe public source,
             // so leave no source-derived records behind for a future pump.
             store.json.replaceAll("symbols", []);
-            store.json.replaceAll("edges", []);
+            store.json.replaceAll("edges", mergeScannedEdges(store.json.loadAll("edges"), []));
             store.json.replaceAll("components", []);
             store.reindex();
             console.log("  ⚠ skipped code graph: no committed HEAD — commit code, then run `hunch index`");
@@ -395,15 +398,21 @@ program
             console.log("  ✓ auto-commit OFF (captures stay uncommitted; commit .hunch/ yourself)");
         }
     }
+    // Collected so the linked-worktree note below can say what actually happened
+    // to the SHARED hooks dir (issue #316) rather than assuming.
+    const installs = [];
     if (isGitRepo(root)) {
         const syncToOverlay = !!(opts.privateSync || opts.sharedSync);
         const h = installPostCommitHook(root, inv.shell, { private: syncToOverlay, commit: opts.autoCommit, 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" : ""}`))
             console.log(line);
         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)"))
             console.log(line);
         const pc = installPostCheckoutHook(root, inv.shell);
+        installs.push(pc);
         for (const line of formatHookInstall(root, "post-checkout hook", pc, " (workspace ledger: records this machine's branches + worktrees on checkout)"))
             console.log(line);
         const m = installMergeDriver(root, inv.shell);
@@ -414,6 +423,7 @@ program
         if (opts.enforce !== false || opts.enforceStrict) {
             const strict = !!opts.enforceStrict;
             const p = installPreCommitHook(root, inv.shell, strict);
+            installs.push(p);
             for (const line of formatHookInstall(root, "pre-commit constraint guard", p, ` (${strict ? "strict — fails only on direct, high-confidence, non-stale blocking invariants" : "advisory — flags invariants in scope or blast radius"})`))
                 console.log(line);
         }
@@ -469,9 +479,8 @@ program
     if (ensureSharedOverlayPointer(root, store.privateDir, store.privateAutoCommit, store.mode === "shared" ? "shared" : "private")) {
         console.log(`  ✓ private overlay registered at the git common dir — shared by every worktree of this repo`);
     }
-    if (isLinkedWorktree(root)) {
-        console.log(`  ✓ linked worktree — sharing the repo's hooks + memory (no separate setup needed)`);
-    }
+    for (const line of sharedHooksNote(root, installs))
+        console.log(line);
     store.close();
     console.log("\n" + formatIntegrationHealth(inspectIntegrations(root)));
     console.log("\nTask reporting is configured through Hunch's agent instructions; actual agent activity has not been verified by setup. Reconnect the agent, then work normally. Completed task reports are available with `hunch report`.");
@@ -497,8 +506,10 @@ program
     // the same way; do the same for the hook so an upgrade doesn't require
     // re-running init by hand. Gated on already having post-commit: `index`
     // is not a setup command (it runs in CI, on any git repo), so it must
-    // never be what FIRST hooks a repo that never ran init at all.
-    if (isGitRepo(root) && hookStatus(root).postCommit) {
+    // never be what FIRST hooks a repo that never ran init at all. A STALE
+    // post-commit block counts too (issue #315): it proves init ran, so the
+    // missing post-merge/post-checkout hooks are still this repo's to heal.
+    if (isGitRepo(root) && ["installed", "stale"].includes(hookReport(root).postCommit.state)) {
         const inv = resolveInvocation().shell;
         installPostMergeHook(root, inv);
         installPostCheckoutHook(root, inv); // same upgrade path for the workspace-ledger hook
@@ -1434,6 +1445,20 @@ program
                 indexNote = `\n  ✓ code graph present in the checkout — blast-radius ready`;
             }
         }
+        catch (error) {
+            // The code graph is this command's CONVENIENCE; the worktree + branch
+            // are its promise, and git has already created them. A dead native
+            // parser (loaded on first parse, so it surfaces here rather than at
+            // import) used to abort between the two: no success line, the ledger
+            // step skipped, and a re-run then hitting "path already exists" with no
+            // way forward. Downgrade it to the same note channel the other optional
+            // steps use — the worktree stands, the user is told the index was
+            // skipped and why, and `hunch index` there fixes it once TMPDIR/the
+            // install is sound. Anything else is still a real failure of this step.
+            if (!isParserLoadError(error))
+                throw error;
+            indexNote = `\n  · code graph skipped — ${error.message}\n    (the worktree is ready; run \`hunch index\` there once the parser loads)`;
+        }
         finally {
             wstore.close();
             openStore = null;
@@ -1517,8 +1542,15 @@ workspacesCmd
                 return console.log("  · or set .hunch/config.json {\"workspaces\":{\"publish_public\":true}} to commit it into this repo's .hunch/");
             case "unchanged":
                 return console.log(`✓ unchanged since ${out.previous.observed_at} (${out.record.id}) — nothing written`);
+            case "deferred":
+                return console.log(out.reason === "detached-head"
+                    ? "deferred: HEAD is detached — the next checkout or ledger read records this machine"
+                    : "deferred: a git operation is in progress — the next checkout or ledger read records this machine");
             case "collision":
-                return fail(`not written: ${out.reason}\n  · \`hunch workspaces forget ${out.record.id}\` removes the stale copy (a normal, revertable memory move), then snapshot again`);
+                // The capture is routed to the overlay, so the only home it can collide with is
+                // this repo's committed `.hunch/`. `forget` refuses that record (an additive pump
+                // never stages a deletion), so the recipe here is the manual git removal.
+                return fail(`not written: ${out.reason}\n  the stale copy lives in this repo's .hunch/ — remove it by hand, then snapshot again:\n${publicWorkspaceRemovalRecipe(out.record.id, out.record.machine.label)}`);
             case "written":
                 return console.log(`✓ recorded ${out.record.worktrees.length} worktree(s), ${out.record.branches.length} branch(es) as ${out.record.machine.label} (${out.record.id}, publish=${out.record.publish}) → ${out.home === "private" ? "overlay" : "public .hunch/"}${out.flushed ? `, ${out.flushed}` : ""}`);
         }
@@ -1577,7 +1609,7 @@ workspacesCmd
             console.log(`  ${r.outcome === "deleted" ? "✓" : r.outcome === "skipped" ? "–" : "✗"} ${r.step.branch}: ${r.detail}`);
         const failed = results.filter((r) => r.outcome === "failed").length;
         const skipped = results.filter((r) => r.outcome === "skipped").length;
-        const ledger = recorded === "written" ? " · ledger updated" : recorded === "unchanged" || recorded === "no-home" || recorded === "off" ? "" : ` · ledger not updated (${recorded})`;
+        const ledger = recorded === "written" ? " · ledger updated" : recorded === "unchanged" || recorded === "no-home" || recorded === "off" ? "" : recorded === "deferred" ? " · ledger deferred (git operation in progress or detached HEAD)" : ` · ledger not updated (${recorded})`;
         console.log(`\n${results.length - failed - skipped} deleted, ${skipped ? `${skipped} skipped (nothing changed), ` : ""}${failed} refused by git${ledger}`);
         if (failed || skipped)
             process.exitCode = 1;
@@ -1605,12 +1637,25 @@ workspacesCmd
         const victims = store.recs("workspaces").filter((r) => r.machine.label === machine || r.machine.id === machine || r.id === machine);
         if (!victims.length)
             return fail(`no workspace record for "${machine}" — \`hunch workspaces\` lists the machines in memory`);
-        // Decide each record's home BEFORE deleting it, then flush exactly those homes.
-        const homes = victims.map((v) => store.getPrivateRec("workspaces", v.id) ? "private" : "public");
-        for (const v of victims)
+        // Decide each record's home BEFORE deleting anything, then flush exactly those homes.
+        // A PUBLIC record (workspaces.publish_public) is refused rather than deleted: the
+        // memory pump never stages a tracked deletion, so removing the file here would strand
+        // `D .hunch/workspaces/<id>.json` and wedge every later auto-commit — see
+        // publicWorkspaceRemovalRecipe.
+        const overlay = victims.filter((v) => store.getPrivateRec("workspaces", v.id));
+        const refused = victims.filter((v) => !store.getPrivateRec("workspaces", v.id));
+        for (const v of overlay)
             store.deleteWhereItLives("workspaces", v.id);
-        pumpMemoryHomes(store, root, homes, `hunch: forget workspace ${machine}`);
-        console.log(`✓ forgot ${victims.length} record(s) for ${machine}`);
+        if (overlay.length) {
+            pumpMemoryHome(store, root, "private", `hunch: forget workspace ${machine}`);
+            console.log(`✓ forgot ${overlay.length} record(s) for ${machine}`);
+        }
+        for (const v of refused) {
+            console.log(`refused: ${v.id} (${v.machine.label}) lives in this repo's .hunch/ — Hunch publication is additive and never stages a deletion, so it is removed by hand:\n`
+                + publicWorkspaceRemovalRecipe(v.id, v.machine.label));
+        }
+        if (refused.length && !overlay.length)
+            process.exitCode = 1;
     }
     finally {
         store.close();
@@ -4502,18 +4547,26 @@ program
     .requiredOption("--by <new>", "decision id that supersedes it")
     .action((oldId, opts) => {
     const { store, root } = storeFor();
-    const by = store.json.get("decisions", opts.by);
+    // `old`'s home decides which store the close is written to; `--by` must resolve in
+    // that SAME store, or a private `by` linked against a public `old` would write the
+    // private id straight into the committed public store.
+    const home = decisionMemoryHome(store, oldId);
+    if (!store.decisionInStore(oldId, home === "private")) {
+        store.close();
+        return fail(`decision "${oldId}" not found`);
+    }
+    const by = store.decisionInStore(opts.by, home === "private");
     if (!by) {
         store.close();
-        return fail(`--by decision "${opts.by}" not found`);
+        return fail(`--by decision "${opts.by}" not found in the ${home} store that holds "${oldId}"`);
     }
-    const closed = store.supersede(oldId, by);
+    const closed = home === "private" ? store.supersedePrivate(oldId, by) : store.supersede(oldId, by);
     if (!closed) {
         store.close();
-        return fail(`decision "${oldId}" not found (or same as --by)`);
+        return fail(`decision "${oldId}" cannot supersede itself`);
     }
     store.reindex();
-    pumpMemoryHome(store, root, "public", `hunch: supersede ${oldId} by ${opts.by}`);
+    pumpMemoryHome(store, root, home, `hunch: supersede ${oldId} by ${opts.by}`);
     console.log(`✓ ${oldId} superseded by ${opts.by} — window closed at ${closed.valid_to?.slice(0, 10)}.`);
     store.close();
 });
@@ -4757,10 +4810,12 @@ program
             if (/^(Edit|Write|MultiEdit)$/.test(evt.tool_name ?? "")) {
                 // A Codex apply_patch touches every file it lists (and each Move-to
                 // destination); the Stop gate must see all of them, not only the first.
-                const patchPaths = evt.tool_input?.patch_files?.flatMap((f) => f.moved_to ? [f.path, f.moved_to] : [f.path]);
-                const edited = patchPaths?.length ? patchPaths : evt.tool_input?.file_path ? [evt.tool_input.file_path] : [];
-                for (const p of edited)
-                    st = onEdit(st, toRepoRel(root, p));
+                // Same in-repo filter as the pre-edit path: a scratch file outside the
+                // repository is not a product edit, and recording it would block Stop on
+                // a path no check can ever verify.
+                const edited = editTargets(root, evt.tool_input);
+                for (const e of edited)
+                    st = onEdit(st, e.target);
                 if (edited.length)
                     activity = { kind: "edit" };
             }
@@ -5170,22 +5225,23 @@ program
             docGround;
         if (!hasContent)
             return; // no noise on files Hunch hasn't learned yet
+        const supplements = [
+            ...(retired.length ? [{
+                    id: "retired-code",
+                    kind: "retired-code",
+                    priority: 200,
+                    text: `⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ")}.`,
+                }] : []),
+            ...(docGround ? [{ id: "doc-grounding", kind: "doc-grounding", priority: 100, text: docGround }] : []),
+            ...recentTasks,
+        ];
         const envelope = buildDeliveryEnvelope(ctx, {
             profile: "builder",
             root,
             symbols: store.recs("symbols"),
             components: store.recs("components"),
             decisionCorpus: store.recs("decisions"),
-            supplements: [
-                ...(retired.length ? [{
-                        id: "retired-code",
-                        kind: "retired-code",
-                        priority: 200,
-                        text: `⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ")}.`,
-                    }] : []),
-                ...(docGround ? [{ id: "doc-grounding", kind: "doc-grounding", priority: 100, text: docGround }] : []),
-                ...recentTasks,
-            ],
+            supplements,
         });
         const text = envelope.text.trim();
         // Identical grounding already shown this session → one-line delta instead of
@@ -5218,7 +5274,16 @@ program
         const reportTaskId = hookReportTaskId(root, provider, evt);
         // A new authoritative prompt gets its own full delivery. An earlier
         // prompt's session-level delta cannot establish this task's receipt.
-        if (injectionMode(evt.session_id, `pre:${target}${reportTaskId ? `:${reportTaskId}` : ""}`, text) === "delta") {
+        // A subagent reports to the prompt's task but starts with FRESH context:
+        // it never saw that grounding, so its dedup is scoped by its own agent
+        // identity (hashed — the raw agent_id is never retained in the key).
+        const agentKey = evt.agent_id ? `:${reportHash(evt.agent_id).slice(7, 19)}` : "";
+        // Dedup on the envelope's stable IDENTITY projection, never on the
+        // rendered block: serving the full text writes delivery receipts, and the
+        // next call's task ranking reads them back and moves the wording ("today"
+        // → "delivered today"), so hashing the presentation made this grounding
+        // self-invalidating and re-sent the full block for unchanged records.
+        if (injectionMode(evt.session_id, `pre:${target}${reportTaskId ? `:${reportTaskId}` : ""}${agentKey}`, text, deliveryDedupeInput(envelope, supplements)) === "delta") {
             receipts("refreshed");
             emitContext(provider, "PreToolUse", `Hunch grounding for ${target}: unchanged this session (${envelope.delivered.filter((item) => item.kind === "decisions").length} decision(s), ${envelope.delivered.filter((item) => item.kind === "constraints").length} invariant(s) shown earlier — still current; hunch_why("${target}") to re-expand).`);
             return;
@@ -7080,9 +7145,23 @@ program
         // hook manager's regenerated file — issue #311) is NOT installed.
         const unreachable = [["post-commit", report.postCommit], ["post-merge", report.postMerge], ["pre-commit", report.preCommit], ["post-checkout", report.postCheckout]]
             .filter(([, e]) => e.state === "unreachable");
+        // Present where git runs it, but its command is not a Hunch launcher that
+        // exists (hand-edited, or an absolute path gone after a reinstall) — issue #315.
+        const stale = [["post-commit", report.postCommit], ["post-merge", report.postMerge], ["pre-commit", report.preCommit], ["post-checkout", report.postCheckout]]
+            .filter(([, e]) => e.state === "stale");
+        // A bare `hunch init` regenerates post-commit without --private/--commit
+        // and pre-commit without --strict, so pointing at it without naming the
+        // options that keep them silently DOWNGRADES the install. --commit is left
+        // out: init's auto-commit is ON unless --no-auto-commit is passed, so a
+        // bare re-run keeps it and naming it here would claim a loss that never happens.
+        const carried = [...new Set(stale.flatMap(([, e]) => e.flags ?? []))].filter((f) => f !== "--commit");
+        const keep = carried.map((f) => (f === "--strict" ? "--enforce-strict" : f === "--private" ? "--private-sync (or --shared-sync)" : "")).filter(Boolean);
+        const staleKeep = carried.length
+            ? ` — the stale block carried ${carried.join(", ")}${keep.length ? `: pass ${keep.join(", ")} or they are dropped` : ""}`
+            : "";
         // `hunch index` only ever installs post-merge onto an existing
-        // post-commit install (it never hooks an un-hooked repo — see
-        // isGitRepo(root) && hookStatus(root).postCommit above) and never writes
+        // post-commit install (it never hooks an un-hooked repo — see the
+        // hookReport(root).postCommit.state gate above) and never writes
         // into a manager-owned hook — so the fix hint must not point there when
         // post-commit itself is missing or a hook manager is in play.
         const managedMissing = [report.postCommit, report.postMerge].find((e) => e.state === "missing" && e.manager !== "none");
@@ -7092,6 +7171,7 @@ program
         const problems = [
             missing.length ? `⚠ missing ${missing.join(", ")} — ${fix}` : "",
             unreachable.length ? `⚠ installed but unreachable: ${unreachable.map(([n]) => n).join(", ")} — never runs; run \`hunch init\` to print the snippet for your hook manager` : "",
+            stale.length ? `⚠ stale: ${stale.map(([n]) => n).join(", ")} — the hook's command is not a working Hunch launcher; run \`hunch init\` to regenerate it${staleKeep}` : "",
         ].filter(Boolean);
         console.log(`hooks:      ${problems.length
             ? problems.join("\n            ")
@@ -7099,6 +7179,13 @@ program
         for (const [name, e] of unreachable) {
             console.log(dim(`            ↳ ${name}: ${e.reason ?? "the block sits where git never reaches it"} (${rel(root, e.path)})`));
         }
+        for (const [name, e] of stale) {
+            console.log(dim(`            ↳ ${name}: ${e.reason ?? "the block's command is not a Hunch launcher"} (${rel(root, e.path)})`));
+        }
+        // Where the live hooks point — informational (a hook may legitimately run
+        // another install), but the fastest way to spot a stale/foreign launcher.
+        for (const line of hookInvocationLines(report, resolveInvocation().shell))
+            console.log(dim(`            ↳ ${line}`));
         // Workspace ledger: what this machine is called, whether its record is in memory,
         // and whether the checkout hook that keeps it fresh is installed.
         try {
@@ -7107,7 +7194,7 @@ program
             const others = store.recs("workspaces").filter((r) => r.machine.id !== machine.id).length;
             const leak = labelLeaksIdentity(machine.label);
             console.log(`workspaces: this machine is ${machine.label}${leak ? ` (⚠ label equals the ${leak})` : ""} · record in memory: ${stored ? `yes (${stored.observed_at})` : "no"} · ${others} other machine(s)` +
-                `${hooks.postCheckout ? " · post-checkout hook installed" : report.postCheckout.state === "unreachable" ? " · ⚠ post-checkout hook unreachable" : hooks.postCommit ? " · post-checkout hook not installed (`hunch index` adds it)" : ""}`);
+                `${hooks.postCheckout ? " · post-checkout hook installed" : report.postCheckout.state === "unreachable" ? " · ⚠ post-checkout hook unreachable" : report.postCheckout.state === "stale" ? " · ⚠ post-checkout hook stale" : hooks.postCommit ? " · post-checkout hook not installed (`hunch index` adds it)" : ""}`);
         }
         catch { /* no machine file writable: nothing to report */ }
     }
@@ -7133,6 +7220,20 @@ program
     const ctxWarning = await maybeWarnOllamaContext(provider.name, process.env);
     if (ctxWarning)
         console.log(ctxWarning);
+    // The native addons load on first PARSE, not at import, so no other command
+    // that merely starts up proves the parser works. Doctor is the one place
+    // that should pay the ~1.5s load: without this line a broken parser (an
+    // unwritable TMPDIR, a missing or wrong-arch prebuild, an addon preloaded
+    // past the isolation guard) is invisible until an index run refuses.
+    try {
+        loadNativeTreeSitter();
+        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`));
+        process.exitCode = 1;
+    }
     const c = store.reindex().counts;
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
     try {
@@ -7252,28 +7353,17 @@ function readStdin() {
     });
 }
 /** Absolute edit path → repo-relative, forward-slash (constraint scopes are
- *  forward-slash globs even on Windows). */
-/** realpath a path even if it doesn't exist yet (a new file an agent is about to
- *  Write): resolve the longest existing ancestor, then re-append the missing tail.
- *  Idempotent on already-resolved paths. */
-function realpathNorm(p) {
-    try {
-        return realpathSync.native(p);
-    }
-    catch {
-        const parent = dirname(p);
-        if (parent === p)
-            return p; // hit the root; nothing more to resolve
-        return join(realpathNorm(parent), basename(p));
-    }
-}
-/** Repo-relative POSIX path. BOTH ends are realpath-normalized first: on macOS
- *  `process.cwd()` (hence findRoot) resolves /var→/private/var, but a hook event's
- *  file_path arrives UN-resolved — so a naive relative() yields a bogus "../" path
- *  under any symlinked root (/var, /tmp, symlinked $HOME) and the caller treats the
- *  file as outside the repo, silently dropping all context (dec_e0a36efbf5). */
+ *  forward-slash globs even on Windows), or "" when `abs` isn't (resolvably)
+ *  inside `root`. Thin adapter over the shared `repoRelativeTarget` (core/paths.ts,
+ *  which realpath-normalizes both ends first — see its docstring for why, incl.
+ *  dec_e0a36efbf5): that function passes an unresolvable absolute path through
+ *  UNCHANGED (still absolute) rather than signaling failure directly, since other
+ *  callers want the original target back to fail their own match safely. This
+ *  adapter converts that "still absolute" signal to "" — the sentinel `onEdit`
+ *  and `editTargets` below already treat as "skip, not in this repo". */
 function toRepoRel(root, abs) {
-    return relative(realpathNorm(root), realpathNorm(abs)).split("\\").join("/");
+    const rel = repoRelativeTarget(abs, root);
+    return isAbsolute(rel) || /^[a-zA-Z]:/.test(rel) ? "" : rel;
 }
 /** The in-repo files a pre-edit event would change, each with the lines the edit
  *  ADDS to that file. A Codex apply_patch yields one entry per touched path (a

package/dist/cli/serve.d.ts

@@ -1,2 +1,16 @@
 import type { Command } from "commander";
+/** Compact one served partition's ledger. Compaction is read → slice → write, so it takes the
+ *  partition write lock like every other writer (#286): without it a live server's append between
+ *  the read and the write is overwritten, regressing head_seq and reusing a seq. The ledger lives
+ *  in the store's RESOLVED state home (the overlay in shared mode), never `<root>/.hunch` blindly. */
+export declare function compactPartition(root: string, scope: {
+    kind: "organization" | "team" | "user" | "repository";
+    id: string;
+}, keep: number, lockOptions?: {
+    timeoutMs?: number;
+}): Promise<{
+    dropped: number;
+    floor_seq: number;
+    head_seq: number;
+}>;
 export declare function registerServeCommands(program: Command): void;

package/dist/cli/serve.js

@@ -6,9 +6,9 @@ import { initServeConfig, partitionFor, readServeConfig, writeServeConfig } from
 import { compactLedger } from "../store/changeLedger.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { hunchPaths } from "../core/paths.js";
-import { partitionOf } from "../store/stateBinding.js";
+import { partitionOf, stateHomeFor } from "../store/stateBinding.js";
 import { formatReplayReport, verifyReplay } from "../store/replay.js";
-import { join } from "node:path";
+import { withWriteLock } from "../serve/writelock.js";
 import { ScopeSchema, scopePath } from "../core/stateContract.js";
 import { HUNCH_VERSION } from "../core/version.js";
 function parseScopeArg(value) {
@@ -18,6 +18,20 @@ function parseScopeArg(value) {
         throw new Error(`partition must be kind:id (organization|team|user|repository), got "${value}"`);
     return parsed.data;
 }
+/** Compact one served partition's ledger. Compaction is read → slice → write, so it takes the
+ *  partition write lock like every other writer (#286): without it a live server's append between
+ *  the read and the write is overwritten, regressing head_seq and reusing a seq. The ledger lives
+ *  in the store's RESOLVED state home (the overlay in shared mode), never `<root>/.hunch` blindly. */
+export async function compactPartition(root, scope, keep, lockOptions = {}) {
+    const store = new HunchStore(hunchPaths(root));
+    try {
+        const { hunchDir } = stateHomeFor(store, scope);
+        return await withWriteLock(hunchDir, () => compactLedger(hunchDir, scope, { keep }), lockOptions);
+    }
+    finally {
+        store.close();
+    }
+}
 export function registerServeCommands(program) {
     const DEFAULT_CONFIG = "hunch-serve.json";
     const serve = program.command("serve")
@@ -57,7 +71,7 @@ export function registerServeCommands(program) {
         .requiredOption("--partition <kind:id>", "the partition whose ledger to compact")
         .option("--keep <n>", "events to keep", "1000")
         .option("--json", "machine-readable output")
-        .action((opts) => {
+        .action(async (opts) => {
         const parent = serve.opts();
         const config = readServeConfig(resolve(parent.config ?? DEFAULT_CONFIG));
         const scope = parseScopeArg(opts.partition);
@@ -67,7 +81,7 @@ export function registerServeCommands(program) {
         const keep = Number(opts.keep);
         if (!Number.isInteger(keep) || keep < 0)
             throw new Error("--keep must be a non-negative integer");
-        const result = compactLedger(join(partition.root, ".hunch"), scope, { keep });
+        const result = await compactPartition(partition.root, scope, keep);
         if (opts.json) {
             console.log(JSON.stringify({ partition: scopePath(scope), ...result }));
             return;

package/dist/constitution/g2BehaviorCandidates.js

@@ -25,7 +25,11 @@ const DIRECT_TEST_DELTA_LIMITATIONS = [
     "Direct decision candidates cover newly named node:test test()/it() cases and existing literal-named cases whose body contains an added fixing-commit line.",
     ...LIMITATIONS.slice(1),
 ];
-const { Parser, typescript: tsLanguage, tsx: tsxLanguage } = loadNativeTreeSitter();
+/** Resolved on first parse, not at import: loading the native addons copies six
+ *  `.node` files into a temp dir and dlopens them (~1.5s+ cold), which every CLI
+ *  command and every editor hook would otherwise pay just for importing this
+ *  module. loadNativeTreeSitter() memoizes the runtime itself. */
+const treeSitter = () => loadNativeTreeSitter();
 function safeTestFile(file) {
     return !!file
         && !isAbsolute(file)
@@ -175,6 +179,7 @@ function literalTestName(raw) {
     return name.trim() ? name : null;
 }
 function literalNodeTestCases(file, source) {
+    const { Parser, typescript: tsLanguage, tsx: tsxLanguage } = treeSitter();
     const language = /\.[cm]?[jt]sx$/.test(file) && /x$/.test(file) ? tsxLanguage : tsLanguage;
     const parser = new Parser();
     parser.setLanguage(language);

package/dist/constitution/g2Candidates.js

@@ -5,6 +5,7 @@ import { shortHash } from "../core/ids.js";
 import { hunchPathsForDir } from "../core/paths.js";
 import { commitMeta, fixCommits } from "../extractors/git.js";
 import { indexRepo } from "../extractors/indexer.js";
+import { isParserLoadError } from "../extractors/nativeTreeSitter.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { canonicalHash } from "./canonical.js";
 import { extractStructuralDelta } from "./delta.js";
@@ -62,10 +63,15 @@ function privateGrounding(decisionStore, graphStore, root) {
             });
             byCommit.set(meta.sha, list);
         }
-        catch {
+        catch (error) {
             // A human decision can be real while still lacking a supported structural
             // binding. It contributes no candidate attestation rather than being
             // stretched over a coincidental fact from the same commit.
+            // A dead native parser is not that: it makes EVERY decision look
+            // unbindable, so the review packet would silently downgrade exact human
+            // grounding to unattested coincidence. Fail instead of under-attesting.
+            if (isParserLoadError(error))
+                throw error;
         }
     }
     return byCommit;
@@ -142,6 +148,10 @@ function buildFromIndexedGraph(decisionStore, graphStore, root, opts, resolution
             }
         }
         catch (error) {
+            // A dead native parser would turn every commit into a per-commit failure
+            // entry instead of an honest abort, so it is never recorded as one.
+            if (isParserLoadError(error))
+                throw error;
             failures.push({ commit, error: error.message });
         }
     }

package/dist/constitution/structural.js

@@ -5,6 +5,7 @@ import { pathMatchesGlob } from "../core/glob.js";
 import { shortHash } from "../core/ids.js";
 import { resolveRelativeImport } from "../core/relativeImports.js";
 import { commitMeta } from "../extractors/git.js";
+import { isParserLoadError } from "../extractors/nativeTreeSitter.js";
 import { canonicalHash } from "./canonical.js";
 import { clampCandidateLimit, durationCutoff } from "./bootstrap.js";
 import { compileStructuralPolicy } from "./compiler.js";
@@ -645,6 +646,15 @@ export function bootstrapStructuralPolicies(store, root, repository, opts = {})
             report.compiled.push({ evidence: event, policy });
         }
         catch (e) {
+            // "uncompilable" is a verdict ABOUT the decision, and it is written to
+            // evidence. A dead native parser (extractStructuralDelta parses the
+            // commit's sources) says nothing about the decision — recording it would
+            // stamp every eligible decision uncompilable with a TMPDIR error as the
+            // stated reason, and a later run with a working parser would only
+            // reclassify what `canReclassify` still allows. Fail the bootstrap
+            // instead, the way the import-time load did.
+            if (isParserLoadError(e))
+                throw e;
             report.uncompilable++;
             const reason = e.message;
             if (canReclassify(prior) && (prior?.compiler?.status !== "uncompilable" || prior.compiler.reason !== reason)) {

package/dist/core/correction.js

@@ -8,9 +8,9 @@
  *   - buildCorrectionConstraint(): mint the Constraint record (human-confirmed,
  *     scoped conservatively) that the pre-edit hook + CI guard then enforce.
  */
-import { isAbsolute, relative } from "node:path";
+import { isAbsolute } from "node:path";
 import { constraintId } from "./ids.js";
-import { toPosixTarget } from "./paths.js";
+import { toPosixTarget, repoRelativeTarget } from "./paths.js";
 import { deriveForbids } from "./constraintmatch.js";
 /** Correction cues. Deliberately conservative — anchored to imperative/rebuke
  *  phrasing, not bare "no", so ordinary conversational negation ("no idea",
@@ -57,7 +57,13 @@ export const TESTIMONY_CORRECTION_RATIONALE = "Recorded by the agent as a correc
  *  Returns "" when the hint cannot be made repo-relative (no root, or a path outside the
  *  repo). The caller then falls back to "**", where the existing severity guard
  *  down-ranks a non-explicit blocking rule to a warning — fail-safe and honest, rather
- *  than a blocking rule enforced nowhere. */
+ *  than a blocking rule enforced nowhere.
+ *
+ *  Thin adapter over the shared `repoRelativeTarget` (core/paths.ts): that function
+ *  passes an unresolvable absolute hint through UNCHANGED (still absolute) rather
+ *  than signaling failure directly, since other callers (checkConstraints, why())
+ *  want the original target back to fail their own match safely. This adapter
+ *  converts that "still absolute" signal to "" — the fail-safe this caller needs. */
 function repoRelativeHint(rawHint, root) {
     if (!rawHint)
         return "";
@@ -66,10 +72,9 @@ function repoRelativeHint(rawHint, root) {
         return rawHint;
     if (!root)
         return "";
-    const rel = toPosixTarget(relative(root, rawHint));
-    if (!rel || rel === ".." || rel.startsWith("../") || isAbsolute(rel) || /^[a-zA-Z]:/.test(rel))
-        return "";
-    return rel;
+    const rewritten = repoRelativeTarget(rawHint, root);
+    const stillAbsolute = isAbsolute(rewritten) || /^[a-zA-Z]:/.test(rewritten);
+    return stillAbsolute ? "" : rewritten;
 }
 /**
  * Build the Constraint a correction mints. Pure (caller passes `now`), so the