@davesheffer/hunch 1.40.1 → 1.41.0

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

package/dist/mcp/server.d.ts

@@ -8,8 +8,133 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { HunchStore } from "../store/hunchStore.js";
+import { type StateFacet } from "../core/stateContract.js";
 import type { Symbol } from "../core/types.js";
 export declare const publicationVocabulary: (hunchDir: string) => RegExp[];
+/** The cwd-hint fallback (see `cwdHintField` above) only helps when the CALLER
+ *  remembers to pass it — a subagent spawned straight into its own linked
+ *  worktree has no reason to think of the session's "starting directory" as
+ *  different from its own, so the hint is silently omitted and an auto-committing
+ *  write lands wherever `root` last was (often the primary checkout, on its
+ *  default branch). This is a backstop, NOT a complete fix: it only catches a
+ *  related file that's new/untracked at the resolved root but already exists in
+ *  a sibling worktree — the common "edited an existing tracked file" case is
+ *  invisible to a pure existence check (the file exists at every worktree, just
+ *  with different content).
+ *
+ *  Used by `misrouteGuard` below to cover every auto-committing write tool that
+ *  names files: hunch_record_decision's related_files, hunch_record_correction's
+ *  scope_hint_file, hunch_record_finding's affected_files, and nuryel_write's
+ *  decisions/findings/bugs/constraints facets via `fileEvidenceFor`. Every
+ *  matching sibling is named as a candidate `cwd` and the write is refused
+ *  rather than risked; it returns every match rather than the first, since
+ *  confidently naming just one would let a caller that blindly retries as
+ *  instructed land in the WRONG worktree — the same failure mode one level
+ *  removed.
+ *
+ *  Two false-positive guards, both required, not optional hardening:
+ *  - Empty related_files, or no sibling worktree doing any better, is silent — a
+ *    decision that legitimately precedes its code (no files yet) is unaffected.
+ *  - A related_files entry ABSENT at the root is not automatically suspicious: an
+ *    ordinary delete/rename recorded correctly at the resolved root produces the
+ *    exact same shape (file gone here, still present in whichever sibling
+ *    worktree branched before the change) as a genuine misroute.
+ *    `pathKnownToHistory` distinguishes them — a path this checkout's own HEAD
+ *    has ever tracked explains its absence without invoking a worktree guess.
+ *
+ *  Coverage boundary: only checks the file evidence passed in THIS call (related_files
+ *  / scope_hint_file / affected_files), not values inherited from an existing record
+ *  on re-record/supersede — a call that omits its file field to rely on inheritance
+ *  won't trip this guard even if it's happening in the wrong worktree. That's a
+ *  deliberate tradeoff against false positives on stale evidence, not full coverage
+ *  of every misrouted write.
+ *
+ *  Absolute paths: agents naturally send them (edit-tool payloads and MCP roots
+ *  are absolute), and a NAIVE `join(dir, "/abs/path")` produces a nonsense
+ *  concatenated path that exists nowhere — the guard would find nothing to
+ *  compare against ANY directory and stay silent, reproducing the exact bug the
+ *  guard exists to catch. `existsUnder` checks an absolute entry AS ITSELF,
+ *  scoped to whichever directory is under test (root, or each candidate worktree
+ *  in turn) via `deepestContainer`, not `join()` — so an absolute path naming a
+ *  file that exists only under a worktree's own tree is direct positive evidence
+ *  for that worktree specifically, no existence heuristic required. Relativizing
+ *  it against `root` alone can't represent a SIBLING worktree's absolute path at
+ *  all: it's never under root's tree, so it relativizes to "../…" and gets
+ *  dropped — silently reintroducing the bypass one level removed. A NESTED
+ *  worktree (`root/.worktrees/x`) is the opposite trap: it IS lexically under
+ *  root's own tree, so a plain "is this path under root" check wrongly
+ *  attributes it to root — `deepestContainer` picks the MOST SPECIFIC
+ *  (longest-path) containing worktree, not just any containing ancestor, so root
+ *  never swallows a worktree nested inside it. An absolute path outside every
+ *  known worktree matches none and correctly contributes nothing: not "absent
+ *  here, check the siblings", just nothing to compare. Canonicalized
+ *  (`canonicalRootPath`, the same symlink/case resolution `resolveActiveRoot`
+ *  uses above) on both sides before comparing, so a worktree reached through a
+ *  symlink or a case-different spelling isn't silently missed, and compared by
+ *  exact path SEGMENT, not string prefix, so a real sibling `foo-other` doesn't
+ *  false-match `foo` and a file genuinely named `..odd.ts` isn't mistaken for a
+ *  `..` traversal. A DIRECTORY entry (or the empty-string/"." an agent might
+ *  send meaning "the repo itself") contributes nothing either: `existsUnder`
+ *  checks `isFile`, never mere existence, since a directory match would silently
+ *  disable the guard for every OTHER entry in the same call — and
+ *  `pathKnownToHistory` (below) confirms a git pathspec matched the EXACT entry,
+ *  not merely something under/matching it, for the identical reason.
+ *
+ *  A RELATIVE entry containing a ".." segment that escapes root's own tree when
+ *  resolved against root is the same misroute as a worktree-rooted absolute
+ *  path, merely spelled relatively — resolved against ROOT specifically (the
+ *  only base the server actually has; never re-resolved per candidate in the
+ *  loop below, which would answer a different, meaningless question) and then
+ *  run through the identical absolute-path containment logic. A relative entry
+ *  that does NOT escape root's tree keeps the original, intentional
+ *  multi-location check instead: the SAME relative suffix tried against every
+ *  candidate directory in turn — that's how a plain "this file's name" evidence
+ *  has always found a sibling worktree holding a file by that name, and it must
+ *  keep doing so for a NESTED worktree reached by a non-escaping relative path,
+ *  whose containing worktree this does not (yet) distinguish from root itself —
+ *  that residual gap fails OPEN (silently uncaught), never toward a false
+ *  positive.
+ *
+ *  Exported for direct unit testing — the candidate logic is otherwise reachable
+ *  only through a full MCP client/server integration test. */
+export declare const misroutedWorktreeCandidates: (root: string, relatedFiles: readonly string[]) => string[];
+/** Normalizes file evidence for the misroute guard specifically. A literal
+ *  backslash byte is a legal POSIX filename character, not a path separator,
+ *  so blindly running every entry through `toPosixTarget` before
+ *  `misroutedWorktreeCandidates` sees it can rewrite a real file's name into a
+ *  fake extra path segment. The string alone can't disambiguate "Windows
+ *  separator" from "literal POSIX byte", so this asks the filesystem AND git
+ *  history instead (`namesRealEvidence`): when the RAW, un-normalized entry
+ *  already names a real file, or is a relative path git knows was tracked at
+ *  `root` (possibly since deleted/renamed), that settles it — the byte was
+ *  literal — and the raw string is kept as-is, bypassing `toPosixTarget`
+ *  entirely. Otherwise it normalizes through `toPosixTarget` exactly as
+ *  before, preserving the legitimate Windows-separator case (a Windows-style
+ *  path can never collide with a real or once-tracked POSIX file, since `\`
+ *  cannot appear in a Windows filename to begin with). Scoped to the
+ *  misroute-guard call sites only — the stored related_files/affected_files
+ *  fields are still normalized separately, unaffected by this.
+ *
+ *  Known accepted gap: a contrived collision — a file legitimately deleted
+ *  from `root`'s history AND a genuine Windows-style path meaning something
+ *  else present in a sibling worktree — resolves in favor of history and
+ *  fails OPEN (no misroute reported), the same fail-open tradeoff
+ *  `misroutedWorktreeCandidates` itself already documents elsewhere. */
+export declare function guardEvidence(root: string, files: readonly string[]): string[];
+/** The file-evidence field, if any, each nuryel_write facet carries: related_files
+ *  for decisions, affected_files for findings/bugs, and scope (the glob list a
+ *  constraint applies to — the same role hunch_record_correction's
+ *  scope_hint_file plays) for constraints. A TOTAL map over StateFacet, not an
+ *  open-ended ternary chain: adding a facet to STATE_FACETS without adding it
+ *  here is a compile error, not a silent gap. null means the facet carries no
+ *  comparable field and is left unguarded rather than inventing one. Exported so
+ *  tests can assert the mapping directly instead of only probing it through live
+ *  misroute behavior. */
+export declare const FILE_EVIDENCE_FIELD: Record<StateFacet, string | null>;
+/** `record` is caller-supplied z.record(string, unknown) — defensive by
+ *  construction, so anything other than an array of strings reads as no
+ *  evidence instead of throwing. */
+export declare function fileEvidenceFor(facet: StateFacet, record: Record<string, unknown>): string[];
 /** Resolve a free-form target (symbol id / name / file path) to symbol records.
  *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
  *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift

package/dist/mcp/server.js

@@ -30,7 +30,7 @@ import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
 import { workspaceLedgerView, renderWorktreeTable, renderBranchTable, workspaceSummaryLine, snapshotHasHome, recordWorkspaceSnapshot, branchRows, worktreeRows } from "../integrations/workspaceLedger.js";
 import { workspacesConfig } from "../core/config.js";
-import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeGateDiff, commitFiles, commitGateDiff, stagedFiles, stagedGateDiff, workingFiles, workingGateDiff, pullHunchStatus, sameRemoteUrl, currentBranch } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeGateDiff, commitFiles, commitGateDiff, stagedFiles, stagedGateDiff, workingFiles, workingGateDiff, pullHunchStatus, sameRemoteUrl, currentBranch, worktreePaths, pathKnownToHistory } from "../extractors/git.js";
 import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
 import { withWriteLock } from "../serve/writelock.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, overlayMatchesTeamRemote, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
@@ -73,8 +73,8 @@ import { premiseEscalations } from "../core/premises.js";
 import { applyImportedAdrReview, pendingImportedAdrReviews } from "../core/importReview.js";
 import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken, HUMAN_CONFIRMATION_SCHEMA, isHumanConfirmationAnswer } from "../core/capturetoken.js";
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, statSync, lstatSync } from "node:fs";
+import { join, isAbsolute, resolve, relative, sep, parse, dirname } from "node:path";
 import { initiatorFromClient, withInitiator } from "../synthesis/initiator.js";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const err = (text) => ({ content: [{ type: "text", text }], isError: true });
@@ -153,6 +153,433 @@ const destinationNote = (destRoot) => {
     const branch = currentBranch(destRoot);
     return ` [captured${branch ? ` on branch ${branch}` : ""} in ${destRoot}]`;
 };
+/** The cwd-hint fallback (see `cwdHintField` above) only helps when the CALLER
+ *  remembers to pass it — a subagent spawned straight into its own linked
+ *  worktree has no reason to think of the session's "starting directory" as
+ *  different from its own, so the hint is silently omitted and an auto-committing
+ *  write lands wherever `root` last was (often the primary checkout, on its
+ *  default branch). This is a backstop, NOT a complete fix: it only catches a
+ *  related file that's new/untracked at the resolved root but already exists in
+ *  a sibling worktree — the common "edited an existing tracked file" case is
+ *  invisible to a pure existence check (the file exists at every worktree, just
+ *  with different content).
+ *
+ *  Used by `misrouteGuard` below to cover every auto-committing write tool that
+ *  names files: hunch_record_decision's related_files, hunch_record_correction's
+ *  scope_hint_file, hunch_record_finding's affected_files, and nuryel_write's
+ *  decisions/findings/bugs/constraints facets via `fileEvidenceFor`. Every
+ *  matching sibling is named as a candidate `cwd` and the write is refused
+ *  rather than risked; it returns every match rather than the first, since
+ *  confidently naming just one would let a caller that blindly retries as
+ *  instructed land in the WRONG worktree — the same failure mode one level
+ *  removed.
+ *
+ *  Two false-positive guards, both required, not optional hardening:
+ *  - Empty related_files, or no sibling worktree doing any better, is silent — a
+ *    decision that legitimately precedes its code (no files yet) is unaffected.
+ *  - A related_files entry ABSENT at the root is not automatically suspicious: an
+ *    ordinary delete/rename recorded correctly at the resolved root produces the
+ *    exact same shape (file gone here, still present in whichever sibling
+ *    worktree branched before the change) as a genuine misroute.
+ *    `pathKnownToHistory` distinguishes them — a path this checkout's own HEAD
+ *    has ever tracked explains its absence without invoking a worktree guess.
+ *
+ *  Coverage boundary: only checks the file evidence passed in THIS call (related_files
+ *  / scope_hint_file / affected_files), not values inherited from an existing record
+ *  on re-record/supersede — a call that omits its file field to rely on inheritance
+ *  won't trip this guard even if it's happening in the wrong worktree. That's a
+ *  deliberate tradeoff against false positives on stale evidence, not full coverage
+ *  of every misrouted write.
+ *
+ *  Absolute paths: agents naturally send them (edit-tool payloads and MCP roots
+ *  are absolute), and a NAIVE `join(dir, "/abs/path")` produces a nonsense
+ *  concatenated path that exists nowhere — the guard would find nothing to
+ *  compare against ANY directory and stay silent, reproducing the exact bug the
+ *  guard exists to catch. `existsUnder` checks an absolute entry AS ITSELF,
+ *  scoped to whichever directory is under test (root, or each candidate worktree
+ *  in turn) via `deepestContainer`, not `join()` — so an absolute path naming a
+ *  file that exists only under a worktree's own tree is direct positive evidence
+ *  for that worktree specifically, no existence heuristic required. Relativizing
+ *  it against `root` alone can't represent a SIBLING worktree's absolute path at
+ *  all: it's never under root's tree, so it relativizes to "../…" and gets
+ *  dropped — silently reintroducing the bypass one level removed. A NESTED
+ *  worktree (`root/.worktrees/x`) is the opposite trap: it IS lexically under
+ *  root's own tree, so a plain "is this path under root" check wrongly
+ *  attributes it to root — `deepestContainer` picks the MOST SPECIFIC
+ *  (longest-path) containing worktree, not just any containing ancestor, so root
+ *  never swallows a worktree nested inside it. An absolute path outside every
+ *  known worktree matches none and correctly contributes nothing: not "absent
+ *  here, check the siblings", just nothing to compare. Canonicalized
+ *  (`canonicalRootPath`, the same symlink/case resolution `resolveActiveRoot`
+ *  uses above) on both sides before comparing, so a worktree reached through a
+ *  symlink or a case-different spelling isn't silently missed, and compared by
+ *  exact path SEGMENT, not string prefix, so a real sibling `foo-other` doesn't
+ *  false-match `foo` and a file genuinely named `..odd.ts` isn't mistaken for a
+ *  `..` traversal. A DIRECTORY entry (or the empty-string/"." an agent might
+ *  send meaning "the repo itself") contributes nothing either: `existsUnder`
+ *  checks `isFile`, never mere existence, since a directory match would silently
+ *  disable the guard for every OTHER entry in the same call — and
+ *  `pathKnownToHistory` (below) confirms a git pathspec matched the EXACT entry,
+ *  not merely something under/matching it, for the identical reason.
+ *
+ *  A RELATIVE entry containing a ".." segment that escapes root's own tree when
+ *  resolved against root is the same misroute as a worktree-rooted absolute
+ *  path, merely spelled relatively — resolved against ROOT specifically (the
+ *  only base the server actually has; never re-resolved per candidate in the
+ *  loop below, which would answer a different, meaningless question) and then
+ *  run through the identical absolute-path containment logic. A relative entry
+ *  that does NOT escape root's tree keeps the original, intentional
+ *  multi-location check instead: the SAME relative suffix tried against every
+ *  candidate directory in turn — that's how a plain "this file's name" evidence
+ *  has always found a sibling worktree holding a file by that name, and it must
+ *  keep doing so for a NESTED worktree reached by a non-escaping relative path,
+ *  whose containing worktree this does not (yet) distinguish from root itself —
+ *  that residual gap fails OPEN (silently uncaught), never toward a false
+ *  positive.
+ *
+ *  Exported for direct unit testing — the candidate logic is otherwise reachable
+ *  only through a full MCP client/server integration test. */
+export const misroutedWorktreeCandidates = (root, relatedFiles) => {
+    if (!relatedFiles.length)
+        return [];
+    const worktrees = worktreePaths(root);
+    const canonRoot = canonicalRootPath(root);
+    // Resolve against the CANONICAL root, not the raw `root` string. `f` almost
+    // always does NOT exist yet (that's the whole point of checking it) --
+    // canonicalRootPath's realpath then throws and falls back to the raw,
+    // un-resolved path. Resolving against raw `root` first and canonicalizing
+    // second means that fallback returns a path still spelled however `root` was
+    // spelled -- if `root` itself reaches the repo through a symlink (reachable
+    // via `hunch mcp --root <path through a symlink>`, which pins the root and
+    // skips the client-root canonicalization path entirely), an ORDINARY relative
+    // filename that never escapes root's own tree gets compared against the
+    // CANONICAL root and reads as escaping, silently disabling the guard for the
+    // exact shape it exists to catch. Resolving against the already-canonical
+    // root first means the common non-existent-file case is correctly rooted even
+    // when realpath's later canonicalization attempt on the (still nonexistent)
+    // resolved path has nothing to resolve and simply returns it unchanged.
+    //
+    // The escape check below is deliberately LEXICAL (plain resolve(), never
+    // canonicalRootPath) on the resolved path: whether a relative entry escapes
+    // root is a question about ".." SEGMENTS, answered by pure string math, not
+    // about where a SYMLINK at that location happens to point. Canonicalizing
+    // (following symlinks) here is the wrong move: a symlink that physically
+    // lives inside root but targets a sibling worktree (e.g. a shared cache file)
+    // would resolve to a target outside canonRoot, misclassifying an entry that
+    // legitimately exists at root as "escaping", and promoting it to an absolute
+    // path that deepestContainer then wrongly attributes to the sibling -- a
+    // false positive, refusing a write that was already correctly homed.
+    // Symlink-following still happens, and is still needed, one step later in
+    // deepestContainer/existsUnder, whose job (does this path's CONTENT belong to
+    // this specific worktree) is a genuinely different question from whether a
+    // relative STRING escapes root.
+    const evidence = relatedFiles.filter(Boolean).map((f) => {
+        if (isAbsolute(f))
+            return f;
+        const resolved = resolve(canonRoot, f);
+        return isWithin(canonRoot, resolved) ? f : resolved;
+    });
+    if (!evidence.length)
+        return [];
+    if (evidence.some((f) => existsUnder(root, f, worktrees)))
+        return [];
+    if (relatedFiles.some((f) => f && !isAbsolute(f) && pathKnownToHistory(root, f)))
+        return [];
+    const here = canonRoot;
+    const candidates = [];
+    for (const candidate of worktrees) {
+        if (canonicalRootPath(candidate) === here)
+            continue;
+        if (evidence.some((f) => existsUnder(candidate, f, worktrees)))
+            candidates.push(candidate);
+    }
+    return candidates;
+};
+/** True when path segment `child` (canonical) lies inside directory `parent`
+ *  (canonical) — an exact segment boundary, not a string prefix, so a sibling
+ *  `foo-other` never false-matches `foo` and `parent` itself counts as inside. */
+function isWithin(parent, child) {
+    const rel = relative(parent, child);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+/** The worktree (from `worktrees`, which always includes root itself — see
+ *  `worktreePaths`) whose OWN directory tree most SPECIFICALLY contains ABSOLUTE
+ *  path `f` — the deepest/longest match, not merely any containing ancestor. Null
+ *  when `f` is under none of the known worktrees. `canonicalRootPath` resolves the
+ *  WHOLE path including `f`'s own final component, so a symlink reached from
+ *  OUTSIDE a worktree that happens to point INSIDE one is still found (a symlink
+ *  ALIAS to a whole worktree). This is the CANONICAL (symlink-resolved) ownership
+ *  lens; `existsUnder` also checks a LEXICAL lens via `lexicalDeepestContainer`
+ *  below, for the opposite symlink shape this lens alone cannot see. */
+function deepestContainer(f, worktrees) {
+    const canonF = canonicalRootPath(f);
+    let best = null;
+    let bestLen = -1;
+    for (const wt of worktrees) {
+        const canonWt = canonicalRootPath(wt);
+        if (!isWithin(canonWt, canonF))
+            continue;
+        if (canonWt.length > bestLen) {
+            best = wt;
+            bestLen = canonWt.length;
+        }
+    }
+    return best;
+}
+/** Walks ABSOLUTE path `f` component by component to find its PHYSICAL
+ *  location: a plain component is appended lexically and never resolved; a
+ *  ".." only consults the kernel (fully resolving whatever symlink chain led
+ *  there, via `canonicalRootPath`) when the component it's popping is ITSELF
+ *  a symlink -- the one case where the kernel's ".."-cancellation point (the
+ *  symlink's TARGET's parent) differs from the lexical parent. A ".." popping
+ *  a plain directory stays a lexical `dirname()`, since lexical and kernel
+ *  resolution already agree there. `usedKernel` tells the caller whether any
+ *  kernel call actually happened, so it knows whether `path` is canonical (and
+ *  therefore whether a worktree path must be canonicalized too before
+ *  comparing) or still purely lexical. Splits on `\` as well as `/` ONLY when
+ *  the platform separator is itself `\` (win32) -- on POSIX, `\` is an
+ *  ordinary, legal filename byte, not a separator; unconditionally treating it
+ *  as one chops a single real directory entry into two synthetic components,
+ *  which can misattribute a file whose name happens to contain a literal
+ *  backslash to whichever worktree the FIRST synthetic component's name
+ *  matches. A win32 path may legitimately use either separator, so both are
+ *  split there. */
+function walkPhysicalLocation(f) {
+    const root = parse(f).root;
+    const splitter = sep === "\\" ? /[\\/]/ : "/";
+    const segments = f.slice(root.length).split(splitter).filter(Boolean);
+    let phys = root || sep;
+    let usedKernel = false;
+    for (const seg of segments) {
+        if (seg === ".")
+            continue;
+        if (seg !== "..") {
+            phys = join(phys, seg);
+            continue;
+        }
+        let base = phys;
+        try {
+            if (lstatSync(phys).isSymbolicLink()) {
+                base = canonicalRootPath(phys);
+                usedKernel = true;
+            }
+        }
+        catch {
+            // unreadable or nonexistent -- fall through to a plain lexical pop
+        }
+        phys = dirname(base);
+    }
+    return { path: phys, usedKernel };
+}
+/** The worktree whose own directory tree most specifically contains ABSOLUTE path
+ *  `f` AS PHYSICALLY PLACED — its own final path component is never resolved
+ *  through a symlink, unlike `deepestContainer`. A symlink physically sitting
+ *  INSIDE a worktree, whose target lives elsewhere (e.g. a shared cache file), is
+ *  still legitimately "at" that worktree: `deepestContainer` alone resolves such
+ *  an `f` to whichever worktree the symlink's TARGET lives in, misattributing a
+ *  file that genuinely exists where it's spelled and refusing an
+ *  already-correctly-homed write. Ranked by the SAME "deepest/longest match" rule
+ *  as the canonical lens, so a NESTED worktree still correctly out-ranks its own
+ *  physically-containing parent root here too — this lens does not, on its own,
+ *  relax that boundary.
+ *
+ *  Delegates to `walkPhysicalLocation` (above), which decides PER PATH COMPONENT
+ *  whether the kernel needs consulting at all: a ".." only triggers a kernel call
+ *  when the specific component it pops is itself a symlink, never merely because
+ *  `f` happens to contain a ".." somewhere. A purely lexical comparison (plain
+ *  `resolve()`/`relative()`, no realpath anywhere) disagrees with the kernel on
+ *  any `f` containing symlink-then-"..": direct kernel-level testing (a real
+ *  `open()`/`readFile()` on a constructed symlink+".." path, comparing file
+ *  identity, not just `resolve()`/`realpath()` string output) shows the kernel
+ *  cancels ".." against the parent of the CURRENT LOOKUP DIRECTORY, which after
+ *  traversing a symlink component is the symlink's TARGET's parent — exactly
+ *  what `path_resolution(7)` documents. A purely lexical comparison disagrees
+ *  with the kernel both as a false positive (a symlinked dir physically inside a
+ *  sibling worktree, entry `<worktree>/cache/../stray.ts` really resolving
+ *  OUTSIDE every worktree, wrongly attributed to `<worktree>`) and a false
+ *  negative (an alias symlink at root pointing into a sibling worktree, entry
+ *  `<root>/alias/../only-in-wt.ts` really resolving INSIDE the sibling, wrongly
+ *  attributed to nothing). Resolving `dirname(f)` through the kernel
+ *  UNCONDITIONALLY (regardless of whether "..") is stronger than the problem
+ *  requires: it follows every symlink in the directory chain even with no ".."
+ *  present at all, resolving straight through the plain symlinked-DIRECTORY
+ *  shape this function exists to serve. Gating the kernel resolution on whether
+ *  `f` contains ANY ".." segment, then resolving the WHOLE directory chain once
+ *  triggered, is also too coarse: a harmless ".." with no symlink anywhere near
+ *  it (e.g. `<worktree>/subdir/../shared-src/helper.ts`, where `subdir` is a
+ *  plain directory and `shared-src` is a symlink) would still route the WHOLE
+ *  path through the kernel, following `shared-src` and misattributing it. This
+ *  function decides PER COMPONENT instead: walking `f` left to right, a plain
+ *  component is appended lexically (never resolved); a ".." only consults the
+ *  kernel when the component it's popping is ITSELF a symlink — the one case
+ *  where the kernel's cancellation point differs from the lexical parent. Any
+ *  symlink NOT immediately followed by a ".." is never resolved (preserving the
+ *  physical-location contract), and every ".." that actually needs the kernel
+ *  gets it, regardless of how many harmless ".."s or plain directories surround
+ *  it. */
+function lexicalDeepestContainer(f, worktrees) {
+    const { path: spelled, usedKernel } = walkPhysicalLocation(f);
+    let best = null;
+    let bestLen = -1;
+    for (const wt of worktrees) {
+        // `wt` must be canonicalized too, but ONLY to match a canonical `spelled`
+        // -- comparing a canonical spelled path against a raw wt string would
+        // spuriously fail to match even a worktree with no symlinks in its own
+        // path, on any platform where the canonical form differs cosmetically
+        // (e.g. a case-preserving vs case-folding mount). `git worktree list`
+        // already returns realpaths in every fixture this suite has produced, so
+        // this branch is defence-in-depth against a `worktrees` source that one
+        // day doesn't.
+        const compareWt = usedKernel ? canonicalRootPath(wt) : wt;
+        if (!isWithin(compareWt, spelled))
+            continue;
+        if (compareWt.length > bestLen) {
+            best = wt;
+            bestLen = compareWt.length;
+        }
+    }
+    return best;
+}
+/** True when `p` names an existing FILE — never a directory. `existsSync` alone
+ *  would be true for a directory too; since a match here short-circuits the whole
+ *  misroute check (`misroutedWorktreeCandidates`'s early `.some()`), a single
+ *  DIRECTORY entry among a call's file evidence would silently disable the guard
+ *  for every other entry in the same call — including the natural "." / "" an
+ *  agent might send meaning "the repo" (`existsSync(join(dir, ""))` is
+ *  `existsSync(dir)`, always true). */
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function existsUnder(dir, f, worktrees) {
+    if (!f)
+        return false; // "" / "./" normalize to "" — nothing to compare, never `dir` itself
+    if (isAbsolute(f)) {
+        if (!isFile(f))
+            return false;
+        // `dir` owns `f` if EITHER lens says so, checked independently -- not a single
+        // merged ranking across both, which would let a longer-named sibling
+        // out-rank root's own genuine lexical claim by string length alone. Each
+        // lens resolves nested-vs-parent ambiguity within itself (see each
+        // function's own doc comment), so this OR never lets root reclaim a file
+        // that legitimately belongs to a worktree nested inside it.
+        const canonicalOwner = deepestContainer(f, worktrees);
+        if (canonicalOwner && canonicalRootPath(canonicalOwner) === canonicalRootPath(dir))
+            return true;
+        const lexicalOwner = lexicalDeepestContainer(f, worktrees);
+        return !!lexicalOwner && canonicalRootPath(lexicalOwner) === canonicalRootPath(dir);
+    }
+    return isFile(join(dir, f));
+}
+/** True when `f` names evidence the disambiguation in `guardEvidence` can trust
+ *  as real: an existing file on disk (absolute, or relative under `root`), or —
+ *  for a relative entry only — one git already knows was tracked at `root`
+ *  (covers a since-deleted/renamed file, which has nothing left on disk to
+ *  check). */
+function namesRealEvidence(root, f) {
+    return isFile(isAbsolute(f) ? f : join(root, f)) || (!isAbsolute(f) && pathKnownToHistory(root, f));
+}
+/** Normalizes file evidence for the misroute guard specifically. A literal
+ *  backslash byte is a legal POSIX filename character, not a path separator,
+ *  so blindly running every entry through `toPosixTarget` before
+ *  `misroutedWorktreeCandidates` sees it can rewrite a real file's name into a
+ *  fake extra path segment. The string alone can't disambiguate "Windows
+ *  separator" from "literal POSIX byte", so this asks the filesystem AND git
+ *  history instead (`namesRealEvidence`): when the RAW, un-normalized entry
+ *  already names a real file, or is a relative path git knows was tracked at
+ *  `root` (possibly since deleted/renamed), that settles it — the byte was
+ *  literal — and the raw string is kept as-is, bypassing `toPosixTarget`
+ *  entirely. Otherwise it normalizes through `toPosixTarget` exactly as
+ *  before, preserving the legitimate Windows-separator case (a Windows-style
+ *  path can never collide with a real or once-tracked POSIX file, since `\`
+ *  cannot appear in a Windows filename to begin with). Scoped to the
+ *  misroute-guard call sites only — the stored related_files/affected_files
+ *  fields are still normalized separately, unaffected by this.
+ *
+ *  Known accepted gap: a contrived collision — a file legitimately deleted
+ *  from `root`'s history AND a genuine Windows-style path meaning something
+ *  else present in a sibling worktree — resolves in favor of history and
+ *  fails OPEN (no misroute reported), the same fail-open tradeoff
+ *  `misroutedWorktreeCandidates` itself already documents elsewhere. */
+export function guardEvidence(root, files) {
+    return files.map((f) => {
+        const normalized = toPosixTarget(f);
+        return f && normalized !== f && namesRealEvidence(root, f) ? f : normalized;
+    });
+}
+/** Shared misroute-guard refusal for the auto-committing write tools that name
+ *  files (hunch_record_decision, hunch_record_correction, hunch_record_finding,
+ *  and nuryel_write's decisions/findings/bugs/constraints facets via
+ *  `fileEvidenceFor`) — one message so every call site stays in lockstep instead
+ *  of drifting. Returns the refusal ToolResult when `misroutedWorktreeCandidates`
+ *  finds a better home, else null (proceed as normal). `subject` names what's
+ *  being recorded, e.g. `"Foo"` or `finding "Foo"`, for the refusal text. `extra`,
+ *  when given, is appended as a further sentence — for a caller (nuryel_write)
+ *  whose retry needs more than just `cwd` moved. Callers pass file evidence
+ *  through `guardEvidence` — `misroutedWorktreeCandidates` itself understands
+ *  both relative and absolute entries, so no pre-relativization step is needed or
+ *  correct here (see its doc comment on why relativizing against `root` alone
+ *  would drop the exact sibling-worktree case this guard exists to catch). */
+function misrouteGuard(root, subject, relatedFiles, extra) {
+    const misroutes = misroutedWorktreeCandidates(root, relatedFiles);
+    if (!misroutes.length)
+        return null;
+    const branch = currentBranch(root);
+    const plural = misroutes.length > 1;
+    const where = plural
+        ? `they do in these linked worktrees: ${misroutes.join(", ")}`
+        : `they do in the linked worktree ${misroutes[0]}`;
+    const retry = plural
+        ? `retry with cwd pointing at whichever of those is actually correct`
+        : `retry with cwd:"${misroutes[0]}"`;
+    return err(`Refusing to record ${subject} in ${root}${branch ? ` (branch ${branch})` : ""}: ` +
+        `none of the files it names exist there, but ${where}. This call is very likely missing the cwd ` +
+        `argument — ${retry}, or wherever this work actually happened.${extra ? ` ${extra}` : ""}`);
+}
+/** The file-evidence field, if any, each nuryel_write facet carries: related_files
+ *  for decisions, affected_files for findings/bugs, and scope (the glob list a
+ *  constraint applies to — the same role hunch_record_correction's
+ *  scope_hint_file plays) for constraints. A TOTAL map over StateFacet, not an
+ *  open-ended ternary chain: adding a facet to STATE_FACETS without adding it
+ *  here is a compile error, not a silent gap. null means the facet carries no
+ *  comparable field and is left unguarded rather than inventing one. Exported so
+ *  tests can assert the mapping directly instead of only probing it through live
+ *  misroute behavior. */
+export const FILE_EVIDENCE_FIELD = {
+    decisions: "related_files",
+    findings: "affected_files",
+    bugs: "affected_files",
+    constraints: "scope",
+    receipts: null,
+    commitments: null,
+    derived: null,
+    entities: null,
+    relationships: null,
+    conventions: null,
+};
+/** `record` is caller-supplied z.record(string, unknown) — defensive by
+ *  construction, so anything other than an array of strings reads as no
+ *  evidence instead of throwing. */
+export function fileEvidenceFor(facet, record) {
+    const field = FILE_EVIDENCE_FIELD[facet];
+    if (!field)
+        return [];
+    const value = record[field];
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+/** The misrouteGuard `subject` for a nuryel_write call, matching the
+ *  "<kind> \"<label>\"" style hunch_record_decision/_correction/_finding use for
+ *  the same refusal text. Constraints have no title, only a statement. */
+function nuryelWriteSubject(facet, record) {
+    const labelField = facet === "decisions" || facet === "findings" || facet === "bugs" ? "title" : facet === "constraints" ? "statement" : null;
+    const label = labelField ? record[labelField] : undefined;
+    const kind = facet.endsWith("s") ? facet.slice(0, -1) : facet;
+    return `${kind}${typeof label === "string" ? ` "${label.slice(0, 60)}"` : ""} (nuryel_write)`;
+}
 /** Where a capture keyed to `home` actually lands: the private overlay directory when
  *  one is configured, else the public repo root. Centralizes the branch used at every
  *  destination-reporting call site below — `hunch_policy_upgrade_correction` once
@@ -1550,6 +1977,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         },
     }, async ({ decision, capture_token, task_id }) => {
         try {
+            const misroute = misrouteGuard(root, `"${decision.title.slice(0, 60)}"`, guardEvidence(root, decision.related_files ?? []));
+            if (misroute)
+                return misroute;
             // Commit-keyed on the CANONICAL full sha (resolved via git rev-parse), so a
             // human passing the short sha they see in `commit` produces the SAME id as
             // the auto-sync path (which keys on the full sha) — UPGRADING the auto-draft
@@ -1784,6 +2214,16 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         try {
             if (!input.rule || !input.rule.trim())
                 return invalid("rule is required — state the invariant in plain words.");
+            // Same misroute guard as hunch_record_decision: a scope_hint_file that exists in a
+            // sibling linked worktree but not here is very likely a subagent that forgot cwd,
+            // about to silently scope-and-commit a constraint against the wrong checkout.
+            // Passed through guardEvidence — misroutedWorktreeCandidates understands absolute
+            // paths itself (see its doc comment). The constraint's own scope glob below is a
+            // DIFFERENT job, still relativized against root by buildCorrectionConstraint
+            // internally — a sibling worktree's file evidence never reaches that path.
+            const correctionMisroute = misrouteGuard(root, `correction "${input.rule.slice(0, 60)}"`, input.scope_hint_file ? guardEvidence(root, [input.scope_hint_file]) : []);
+            if (correctionMisroute)
+                return correctionMisroute;
             // root: relativizes an ABSOLUTE scope_hint_file. Agents naturally send absolute
             // paths (edit-tool payloads and MCP roots are absolute) and every consumer matches
             // repo-relative — without this the rule would be blocking-but-inert and would leak
@@ -1880,6 +2320,10 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 return invalid("title is required.");
             if (!finding.observation.trim())
                 return invalid("observation is required — state what you saw.");
+            // Same misroute guard as hunch_record_decision.
+            const findingMisroute = misrouteGuard(root, `finding "${finding.title.slice(0, 60)}"`, guardEvidence(root, finding.affected_files ?? []));
+            if (findingMisroute)
+                return findingMisroute;
             const id = findingId(finding.title);
             const home = store.captureHome(!!finding.private);
             const existing = home === "private" ? store.getPrivateRec("findings", id) : store.json.get("findings", id);
@@ -2024,6 +2468,14 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             outputSchema: WriteResultSchema.shape,
         }, async ({ cwd: _cwd, ...input }) => {
             try {
+                // Same misroute guard as hunch_record_decision/_correction/_finding. Unlike those
+                // three, nuryel_write's `scope`/`principal.grants` are a repository partition tied
+                // to the CURRENT root: retrying with only `cwd` moved re-homes the store but leaves
+                // the request scoped to the old root's partition, which fails loudly (not silently)
+                // on the retry — misrouteGuard's `extra` spells out the additional step.
+                const misroute = misrouteGuard(root, nuryelWriteSubject(input.facet, input.record), guardEvidence(root, fileEvidenceFor(input.facet, input.record)), "Also move `scope` (and `principal.grants`) to the repository partition for that worktree — nuryel_write's scope does not follow `cwd` automatically.");
+                if (misroute)
+                    return misroute;
                 // Same cross-process lock `hunch serve` takes: a second agent writing over stdio must
                 // not race the HTTP server between the ledger read and the record write.
                 const { hunchDir } = stateHomeFor(store, input.scope);

package/dist/store/hunchStore.d.ts

@@ -505,6 +505,14 @@ export declare class HunchStore {
      *  newest-first, with its valid-time window and supersession links. Answers
      *  "what did we believe, and when/why did it change?" (hunch_timeline). */
     timeline(target: string): Decision[];
+    /** Invalidate, don't delete: close an active constraint's valid-time window
+     *  (status → "retired", valid_to → now) so `hunch check` and the strict hook
+     *  stop enforcing it while its full history stays on record. The caller has
+     *  already resolved `existing` (id lookup + already-retired refusal are the
+     *  CLI's job, not this method's), so there is no internal re-lookup and no
+     *  nullable return. Writes to whichever store already holds the record
+     *  (`putWhereItLives`), so a public/private twin can never be forked. */
+    retireConstraint(existing: Constraint): Constraint;
     /** Invalidate, don't delete (Zep edge-invalidation): close `oldId`'s valid-time
      *  window at the superseding decision's `valid_from`, mark it superseded + linked,
      *  and write a `supersedes` edge. Returns the updated old decision, or null if it

package/dist/store/hunchStore.js

@@ -148,7 +148,10 @@ export class HunchStore {
             const distinctNestedRoot = nestedBoundary ? gitWorktreeRoot(publicationProbe) : null;
             if (canonical(candidate) === canonical(this.paths.hunch) ||
                 (nestedBoundary && (!distinctNestedRoot || sameGitPublication(distinctNestedRoot, this.paths.root))) ||
-                sameGitPublication(publicationProbe, this.paths.root)) {
+                // If these paths are identical, the nested-boundary clause just ran
+                // this exact proof. Different probe paths still need their own check;
+                // no result is retained across store opens or publication operations.
+                (distinctNestedRoot !== publicationProbe && sameGitPublication(publicationProbe, this.paths.root))) {
                 throw new Error(`Unsafe private overlay "${candidate}" shares the public code repository's local or remote publication boundary. ` +
                     "Run `hunch private` or `hunch shared --repo <url>` to create a standalone overlay repository.");
             }
@@ -1846,6 +1849,16 @@ export class HunchStore {
     timeline(target) {
         return this.why(target).decisions.sort((a, b) => (b.valid_from ?? b.date).localeCompare(a.valid_from ?? a.date));
     }
+    /** Invalidate, don't delete: close an active constraint's valid-time window
+     *  (status → "retired", valid_to → now) so `hunch check` and the strict hook
+     *  stop enforcing it while its full history stays on record. The caller has
+     *  already resolved `existing` (id lookup + already-retired refusal are the
+     *  CLI's job, not this method's), so there is no internal re-lookup and no
+     *  nullable return. Writes to whichever store already holds the record
+     *  (`putWhereItLives`), so a public/private twin can never be forked. */
+    retireConstraint(existing) {
+        return this.putWhereItLives("constraints", { ...existing, status: "retired", valid_to: new Date().toISOString() });
+    }
     /** Invalidate, don't delete (Zep edge-invalidation): close `oldId`'s valid-time
      *  window at the superseding decision's `valid_from`, mark it superseded + linked,
      *  and write a `supersedes` edge. Returns the updated old decision, or null if it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.40.1",
+  "version": "1.41.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.40.1",
+  "version": "1.41.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.40.1",
+      "version": "1.41.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {