@davesheffer/hunch 1.39.0 → 1.39.2

package/dist/integrations/hooks.js

@@ -3,12 +3,26 @@
  * learning loop after every commit. Loop-guarded via the HUNCH_SYNC env var, and
  * backgrounded so it never slows a commit down. Existing hooks are preserved —
  * we append a guarded block rather than clobbering.
+ *
+ * Hook managers (issue #311): an appended block is only worth writing when git
+ * will actually reach it and the file is this machine's own. The pre-commit
+ * framework's generated hook ends in `exec`, husky v9 routes every hook through
+ * `.husky/_/h` (which ends in `exit $c` and is regenerated on `npm install`), and
+ * husky ≤8 / any committed `core.hooksPath` would put this machine's absolute
+ * CLI path into tracked files. In those cases nothing is written: the installer
+ * returns a portable snippet for the manager's own configuration instead, and
+ * `hookReport` tells a present-but-dead block apart from a working one.
  */
-import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync } from "node:fs";
-import { join, isAbsolute } from "node:path";
-import { hooksDir } from "../extractors/git.js";
+import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync, realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, isAbsolute, dirname, basename, relative, resolve } from "node:path";
+import { hooksDir, gitCommonDir } from "../extractors/git.js";
+import { initiatorChildEnv } from "../synthesis/initiator.js";
+import { HUNCH_NPX_PACKAGE_SPEC } 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" };
 function block(invocation, opts = {}) {
     // --private routes the auto-synthesized decision into the HUNCH_PRIVATE_DIR overlay
     // instead of the public repo. --commit (opt-in) also commits & pushes the repo the
@@ -38,21 +52,243 @@ function block(invocation, opts = {}) {
 function escapeRe(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-/** Shared idempotent create/append/update-in-place logic for every hunch git
- *  hook: write a fresh hook file, replace our own managed block in place if the
- *  invocation changed, or append after any pre-existing (non-hunch) hook body
- *  without clobbering it. Used by all three hook installers below — the three
- *  copies had already drifted (installPreCommitHook was missing the chmodSync
- *  on its "updated" path) before this was unified. */
-function installManagedBlock(root, hookName, mark, end, blk) {
+/** Portable invocation for text that lands in a TRACKED file (a husky script, a
+ *  committed hooks dir, .pre-commit-config.yaml): the same exact-version npx
+ *  package reference the committed MCP/provider configs use — never this
+ *  machine's absolute node/CLI path. */
+export const PORTABLE_HOOK_INVOCATION = `npx -y --package=${HUNCH_NPX_PACKAGE_SPEC} hunch`;
+const EXIT_LINE = /^(?:exec|exit)(?:\s|;|$)/;
+const INDENTED_EXIT_LINE = /^\s*(?:exec|exit)(?:\s|;|$)/;
+const BLOCK_OPEN = /^(?:if|case|for|while|until|select)\b|\{\s*$/;
+const BLOCK_CLOSE = /^(?:fi|esac|done)\b|^\}|[;\s](?:fi|esac|done|\})\s*;?\s*$/;
+/** The line that ends the script unconditionally before anything appended after
+ *  it could run, or null. Deliberately conservative (a heuristic, not a shell
+ *  parser): an `exec`/`exit` statement outside any if/case/loop/function block,
+ *  or a trailing top-level `if … else … fi` whose every branch ends in
+ *  `exec`/`exit` — the shape of the pre-commit framework's generated hook. */
+export function terminalExitLine(content) {
+    const lines = content.replace(/\r/g, "").split("\n");
+    let depth = 0;
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        if (depth === 0 && EXIT_LINE.test(line))
+            return line;
+        depth = Math.max(0, depth + (BLOCK_OPEN.test(line) ? 1 : 0) - (BLOCK_CLOSE.test(line) ? 1 : 0));
+    }
+    const meaningful = lines.filter((l) => l.trim() !== "" && !/^\s*#/.test(l));
+    const last = meaningful.at(-1);
+    if (last === undefined || !/^fi\s*(?:;|$)/.test(last))
+        return null;
+    const start = meaningful.slice(0, -1).findLastIndex((l) => /^if\s/.test(l));
+    if (start < 0)
+        return null;
+    const branches = [];
+    let current = [];
+    let hasElse = false;
+    for (const line of meaningful.slice(start + 1, -1)) {
+        if (/^elif\s/.test(line) || /^else\s*(?:;|$)/.test(line)) {
+            if (/^else/.test(line))
+                hasElse = true;
+            branches.push(current);
+            current = [];
+            continue;
+        }
+        current.push(line);
+    }
+    branches.push(current);
+    if (!hasElse)
+        return null;
+    const allExit = branches.every((b) => {
+        const tail = b.filter((l) => !/^\s*then\s*$/.test(l)).at(-1);
+        return tail !== undefined && INDENTED_EXIT_LINE.test(tail);
+    });
+    return allExit ? last.trim() : null;
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `mark` is present in `file`, and if so whether git would reach it. */
+function markerState(file, mark) {
+    const text = readText(file);
+    if (text === null)
+        return "absent";
+    const at = text.indexOf(mark);
+    if (at < 0)
+        return "absent";
+    return terminalExitLine(text.slice(0, at)) ? "unreachable" : "reachable";
+}
+function realish(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+function isInside(parent, child) {
+    const norm = (p) => (process.platform === "win32" ? realish(p).toLowerCase() : realish(p));
+    const rel = relative(norm(parent), norm(child));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function gitRun(args, cwd) {
+    const p = spawnSync("git", args, { cwd, encoding: "utf8", env: initiatorChildEnv(), stdio: ["ignore", "pipe", "ignore"] });
+    return { status: p.status, stdout: (p.stdout ?? "").trim() };
+}
+function isPreCommitFrameworkHook(text) {
+    return /File generated by pre-commit/i.test(text) || /-m\s*pre_commit\b/.test(text) || /^\s*exec\s+pre-commit\b/m.test(text);
+}
+/** Work out who owns `hookName` in `root` and whether an appended block would run.
+ *  `mark` is our block's marker: when an existing block sits BEFORE a trailing
+ *  exec/exit it is reachable, so only the text above it is inspected. Read-only. */
+function resolveHookTarget(root, hookName, mark) {
     const dir = hooksDir(root);
     // `git rev-parse --git-path hooks` returns a path relative to the repo in a
     // normal checkout, but an ABSOLUTE one inside a linked worktree (the shared
     // hooks dir). isAbsolute() handles both POSIX (/…) and Windows (C:\… / C:/…);
     // a bare startsWith("/") misfired on Windows worktrees → a doubled junk path.
     const abs = isAbsolute(dir) ? dir : join(root, dir);
-    mkdirSync(abs, { recursive: true });
     const hookPath = join(abs, hookName);
+    const slashed = abs.replace(/\\/g, "/").replace(/\/+$/, "");
+    const huskyH = readText(join(abs, "h"));
+    if (slashed.endsWith(".husky/_") || (huskyH !== null && /husky/.test(huskyH))) {
+        return {
+            hookName, hookPath, manager: "husky", ownerFile: join(dirname(abs), hookName),
+            reason: "husky v9 runs every hook through .husky/_/h, which exits before any appended line (and regenerates .husky/_ on install)",
+        };
+    }
+    const common = gitCommonDir(root);
+    const insideGitDir = common !== "" && isInside(common, abs);
+    if (!insideGitDir) {
+        const top = gitRun(["rev-parse", "--show-toplevel"], root).stdout;
+        if (top && isInside(top, abs)) {
+            const rel = relative(realish(top), realish(abs)).replace(/\\/g, "/") || ".";
+            const tracked = gitRun(["ls-files", "--", rel], top).stdout !== "";
+            // Not yet committed but not ignored either: the next `git add -A` would commit it.
+            const committable = tracked || gitRun(["check-ignore", "-q", "--", `${rel}/${hookName}`], top).status === 1;
+            if (committable) {
+                const legacy = basename(abs) === ".husky";
+                return {
+                    hookName, hookPath, ownerFile: hookPath,
+                    manager: legacy ? "husky-legacy" : "tracked-hooks-path",
+                    reason: `${rel}/ is ${tracked ? "tracked by git" : "inside the work tree and not ignored"}${legacy ? " (husky ≤8)" : ""} — Hunch will not write this machine's CLI path into a committed hook`,
+                };
+            }
+        }
+    }
+    const text = readText(hookPath);
+    if (text !== null && isPreCommitFrameworkHook(text)) {
+        const config = /--config=(\S+?)["')\s]/.exec(text)?.[1] ?? ".pre-commit-config.yaml";
+        const top = gitRun(["rev-parse", "--show-toplevel"], root).stdout || root;
+        return {
+            hookName, hookPath, manager: "pre-commit", ownerFile: isAbsolute(config) ? config : join(top, config),
+            reason: `the pre-commit framework generated ${hookName}; it ends in exec, so an appended block never runs (and \`pre-commit install\` rewrites the file)`,
+        };
+    }
+    if (text !== null) {
+        const at = text.indexOf(mark);
+        const terminal = terminalExitLine(at >= 0 ? text.slice(0, at) : text);
+        if (terminal) {
+            return {
+                hookName, hookPath, manager: "exec-exit", ownerFile: hookPath,
+                reason: `${hookName} ends in \`${terminal}\`, so a block after it never runs`,
+            };
+        }
+    }
+    return { hookName, hookPath, manager: "none", ownerFile: hookPath };
+}
+/** Stable pre-commit framework hook id per managed block (detection + snippet). */
+function preCommitId(mark) {
+    return {
+        [MARK]: "hunch-post-commit",
+        [PRE_MARK]: "hunch-pre-commit",
+        [GROUNDING_MERGE_MARK]: "hunch-post-merge-grounding",
+        [REPAIR_MERGE_MARK]: "hunch-post-merge-repair-provenance",
+        [CHECKOUT_MARK]: "hunch-post-checkout",
+    }[mark] ?? "hunch";
+}
+/** Whether our block for `mark` is present where git will actually run it. */
+function blockState(t, mark) {
+    const inHook = markerState(t.hookPath, mark);
+    switch (t.manager) {
+        case "none":
+            return inHook === "reachable" ? "installed" : inHook === "unreachable" ? "unreachable" : "missing";
+        case "husky":
+            if (markerState(t.ownerFile, mark) === "reachable")
+                return "installed";
+            if (markerState(t.ownerFile, mark) === "unreachable" || inHook !== "absent")
+                return "unreachable";
+            return "missing";
+        case "pre-commit": {
+            const config = readText(t.ownerFile);
+            if (config !== null && new RegExp(`\\bid:\\s*["']?${escapeRe(preCommitId(mark))}["']?\\s*$`, "m").test(config))
+                return "installed";
+            // Migration mode: `pre-commit install` moved the previous hook to <hook>.legacy and runs it first.
+            if (markerState(`${t.hookPath}.legacy`, mark) === "reachable")
+                return "installed";
+            return inHook !== "absent" ? "unreachable" : "missing";
+        }
+        default: // husky-legacy, tracked-hooks-path, exec-exit: the hook file itself
+            return inHook === "reachable" ? "installed" : inHook === "unreachable" ? "unreachable" : "missing";
+    }
+}
+function stripMarkers(blk) {
+    return blk.split("\n").filter((l) => !/^# (?:>>>|<<<) hunch /.test(l)).join("\n");
+}
+/** The hand-applied equivalent of our block, in the manager's own format. */
+function snippetFor(t, mark, build, localInvocation) {
+    if (t.manager === "pre-commit") {
+        const script = stripMarkers(build(PORTABLE_HOOK_INVOCATION, PRE_COMMIT_CONTEXT));
+        return [
+            `# under \`repos:\` in ${basename(t.ownerFile)} (and run \`pre-commit install --hook-type ${t.hookName}\`)`,
+            "- repo: local",
+            "  hooks:",
+            `    - id: ${preCommitId(mark)}`,
+            `      name: hunch ${t.hookName}`,
+            "      entry: sh",
+            `      args: ["-c", ${JSON.stringify(script)}]`,
+            "      language: system",
+            `      stages: [${t.hookName}]`,
+            "      always_run: true",
+            "      pass_filenames: false",
+        ].join("\n");
+    }
+    if (t.manager === "exec-exit") {
+        // 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);
+}
+/** Shared idempotent create/append/update-in-place logic for every hunch git
+ *  hook: write a fresh hook file, replace our own managed block in place if the
+ *  invocation changed, or append after any pre-existing (non-hunch) hook body
+ *  without clobbering it. Used by all hook installers below — the copies had
+ *  already drifted (installPreCommitHook was missing the chmodSync on its
+ *  "updated" path) before this was unified. When a hook manager owns the file,
+ *  or the block would sit after an exec/exit, nothing is written and the result
+ *  carries the snippet to add by hand (issue #311). */
+function installManagedBlock(root, hookName, mark, end, build, invocation) {
+    const t = resolveHookTarget(root, hookName, mark);
+    if (t.manager !== "none") {
+        if (blockState(t, mark) === "installed")
+            return { path: t.ownerFile, action: "unchanged", manager: t.manager };
+        return {
+            path: t.ownerFile,
+            action: t.manager === "exec-exit" ? "unreachable" : "managed-elsewhere",
+            manager: t.manager,
+            reason: t.reason,
+            snippet: snippetFor(t, mark, build, invocation),
+        };
+    }
+    const blk = build(invocation, GIT_CONTEXT);
+    const hookPath = t.hookPath;
+    mkdirSync(dirname(hookPath), { recursive: true });
     if (!existsSync(hookPath)) {
         writeFileSync(hookPath, `#!/bin/sh\n${blk}\n`);
         chmodSync(hookPath, 0o755);
@@ -73,7 +309,7 @@ function installManagedBlock(root, hookName, mark, end, blk) {
     return { path: hookPath, action: "appended" };
 }
 export function installPostCommitHook(root, invocation, opts = {}) {
-    return installManagedBlock(root, "post-commit", MARK, ENDMARK, block(invocation, opts));
+    return installManagedBlock(root, "post-commit", MARK, ENDMARK, (inv) => block(inv, opts), invocation);
 }
 const PRE_MARK = "# >>> hunch pre-commit (constraint guard) >>>";
 const PRE_END = "# <<< hunch pre-commit <<<";
@@ -83,9 +319,11 @@ const PRE_END = "# <<< hunch pre-commit <<<";
  *  blocking invariant (see strictgate.ts), so it's safe on a shared repo.
  *  Preserves any existing pre-commit hook. */
 export function installPreCommitHook(root, invocation, strict = false) {
-    const cmd = `${invocation} check --staged${strict ? " --strict" : ""}`;
-    const blk = [PRE_MARK, strict ? cmd : `${cmd} || true`, PRE_END].join("\n");
-    return installManagedBlock(root, "pre-commit", PRE_MARK, PRE_END, blk);
+    const build = (inv) => {
+        const cmd = `${inv} check --staged${strict ? " --strict" : ""}`;
+        return [PRE_MARK, strict ? cmd : `${cmd} || true`, PRE_END].join("\n");
+    };
+    return installManagedBlock(root, "pre-commit", PRE_MARK, PRE_END, build, invocation);
 }
 // Original marker, kept byte-for-byte for backward compat: an existing install's
 // grounding-refresh block must still be found and updated in place by its own
@@ -126,8 +364,10 @@ function repairProvenanceMergeBlock(invocation) {
 /** How significant a combined install result is, for picking one HookInstall
  *  action out of two independent sub-installs into the same file — "created"
  *  (the file itself is new) outranks "appended"/"updated" (an existing file
- *  changed), which outrank "unchanged". */
-const ACTION_RANK = { created: 3, appended: 2, updated: 2, unchanged: 1 };
+ *  changed), which outrank "unchanged". Non-writing results are handled before
+ *  ranking (they must never be masked by a sibling's success). */
+const ACTION_RANK = { created: 3, appended: 2, updated: 2, unchanged: 1, "managed-elsewhere": 0, unreachable: 0 };
+const writes = (h) => h.action !== "managed-elsewhere" && h.action !== "unreachable";
 /** Install a post-merge hook carrying TWO independently-managed blocks:
  *  re-sync the committed grounding docs when a merge brought memory in behind
  *  them (fnd_c402046ac7, HUNCH_SYNC-guarded, foreground — it rewrites five
@@ -143,50 +383,97 @@ const ACTION_RANK = { created: 3, appended: 2, updated: 2, unchanged: 1 };
  *  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));
-    const repair = installManagedBlock(root, "post-merge", REPAIR_MERGE_MARK, REPAIR_MERGE_END, repairProvenanceMergeBlock(invocation));
+    const grounding = installManagedBlock(root, "post-merge", GROUNDING_MERGE_MARK, GROUNDING_MERGE_END, groundingMergeBlock, 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)}` };
+    }
+    if (!writes(grounding))
+        return grounding;
+    if (!writes(repair))
+        return repair;
     return ACTION_RANK[repair.action] >= ACTION_RANK[grounding.action] ? repair : grounding;
 }
+/** When two snippets for the same file are joined, drop the second's leading
+ *  instruction comment (the first already says where it goes). */
+function stripComment(snippet, manager) {
+    if (manager !== "pre-commit" && manager !== "exec-exit")
+        return snippet;
+    return snippet.split("\n").filter((l, i) => !(i === 0 && l.startsWith("# "))).join("\n");
+}
 const CHECKOUT_MARK = "# >>> hunch post-checkout (workspace ledger) >>>";
 const CHECKOUT_END = "# <<< hunch post-checkout (workspace ledger) <<<";
 /** post-checkout is where branches and worktrees actually change (`git checkout`,
  *  `git switch`, `git worktree add`). git passes `$3 = 1` for a branch checkout and `0`
  *  for a file checkout; only the former can change the ledger. Constant argv (nothing
  *  from repository content), HUNCH_SYNC-guarded, backgrounded, offline. */
-function checkoutBlock(invocation) {
+function checkoutBlock(invocation, ctx = GIT_CONTEXT) {
     return [
         CHECKOUT_MARK,
-        'if [ -z "$HUNCH_SYNC" ] && [ "$3" = "1" ]; then',
+        `if [ -z "$HUNCH_SYNC" ] && [ "${ctx.checkoutType}" = "1" ]; then`,
         `  ( HUNCH_SYNC=1 ${invocation} workspaces snapshot --quiet >/dev/null 2>&1 || true ) &`,
         "fi",
         CHECKOUT_END,
     ].join("\n");
 }
 export function installPostCheckoutHook(root, invocation) {
-    return installManagedBlock(root, "post-checkout", CHECKOUT_MARK, CHECKOUT_END, checkoutBlock(invocation));
-}
-/** Read-only diagnostic (used by `hunch doctor`): which of the three managed
- *  hooks are currently present. Never writes anything — a hook counts as
- *  installed if its managed marker is present, regardless of whether the
- *  invocation inside it happens to be stale. postMerge requires BOTH halves
- *  (grounding-refresh and repair-provenance) present — a repo carrying only
- *  one is a partial install, same as `installPostMergeHook` self-healing it. */
-export function hookStatus(root) {
-    const dir = hooksDir(root);
-    const abs = isAbsolute(dir) ? dir : join(root, dir);
-    const has = (name, mark) => {
-        try {
-            return readFileSync(join(abs, name), "utf8").includes(mark);
-        }
-        catch {
-            return false;
-        }
+    return installManagedBlock(root, "post-checkout", CHECKOUT_MARK, CHECKOUT_END, checkoutBlock, invocation);
+}
+function reportEntry(root, hookName, marks) {
+    const states = marks.map((mark) => {
+        const t = resolveHookTarget(root, hookName, mark);
+        return { t, state: blockState(t, mark) };
+    });
+    const unreachable = states.find((s) => s.state === "unreachable");
+    const pick = unreachable ?? states.find((s) => s.state === "missing") ?? states[0];
+    if (!pick)
+        throw new Error("reportEntry needs at least one marker");
+    const state = unreachable ? "unreachable" : states.every((s) => s.state === "installed") ? "installed" : "missing";
+    return {
+        state,
+        manager: pick.t.manager,
+        path: state === "unreachable" && pick.t.manager !== "husky" ? pick.t.hookPath : pick.t.ownerFile,
+        ...(state === "unreachable" ? { reason: pick.t.reason } : {}),
     };
+}
+/** Read-only diagnostic (used by `hunch doctor`): each managed hook's state —
+ *  `installed` (present where git will run it), `unreachable` (present, but
+ *  after an exec/exit or in a manager-owned file git never reaches), or
+ *  `missing`. postMerge requires BOTH halves (grounding-refresh and
+ *  repair-provenance) — a repo carrying only one is a partial install, same as
+ *  `installPostMergeHook` self-healing it. Never writes anything. */
+export function hookReport(root) {
     return {
-        postCommit: has("post-commit", MARK),
-        preCommit: has("pre-commit", PRE_MARK),
-        postMerge: has("post-merge", GROUNDING_MERGE_MARK) && has("post-merge", REPAIR_MERGE_MARK),
-        postCheckout: has("post-checkout", CHECKOUT_MARK),
+        postCommit: reportEntry(root, "post-commit", [MARK]),
+        preCommit: reportEntry(root, "pre-commit", [PRE_MARK]),
+        postMerge: reportEntry(root, "post-merge", [GROUNDING_MERGE_MARK, REPAIR_MERGE_MARK]),
+        postCheckout: reportEntry(root, "post-checkout", [CHECKOUT_MARK]),
     };
 }
+/** Boolean view of `hookReport`: a hook counts as installed only when its
+ *  managed block is present where git will actually run it, regardless of
+ *  whether the invocation inside it happens to be stale. An unreachable block
+ *  (issue #311) is NOT installed. */
+export function hookStatus(root) {
+    const r = hookReport(root);
+    return {
+        postCommit: r.postCommit.state === "installed",
+        preCommit: r.preCommit.state === "installed",
+        postMerge: r.postMerge.state === "installed",
+        postCheckout: r.postCheckout.state === "installed",
+    };
+}
+/** CLI lines for one install result: the usual ✓ line when the block is in a
+ *  file git runs, otherwise a warning with the reason and the snippet to add to
+ *  the manager's own file. */
+export function formatHookInstall(root, label, h, detail = "") {
+    if (writes(h))
+        return [`  ✓ ${label} ${h.action}${detail}`];
+    const shown = isInside(root, h.path) ? relative(realish(root), realish(h.path)).replace(/\\/g, "/") : h.path;
+    return [
+        `  ⚠ ${label} NOT installed — ${h.reason ?? "a hook manager owns this hook"}`,
+        `    add this to ${shown} yourself:`,
+        ...(h.snippet ?? "").split("\n").map((l) => `      ${l}`),
+    ];
+}
 //# sourceMappingURL=hooks.js.map

package/dist/integrations/scaffold.js

@@ -80,7 +80,7 @@ Capture the decision for **$ARGUMENTS** into Hunch's graph.
 2. Run the GRILLING LOOP: one focused question at a time. Push back on hand-wavy answers. Resolve every branch before committing — an unexamined decision poisons the graph.
 3. Confirm the TOPIC anchor with me before committing. One topic per decision; if it spans two, split into two captures.
 4. Capture REJECTED alternatives explicitly (what, and why not) — this is what makes the decision enforceable (Veto/drift check against it).
-5. Commit with \`hunch_record_decision\`, passing \`capture_token\` (from step 1) and the confirmed \`topic\`. The artifact is the graph write, not prose.
+5. Commit with \`hunch_record_decision\`, passing \`capture_token\` (from step 1) and the confirmed \`topic\`. The artifact is the graph write, not prose. The token is not my signature: confirm the record in the client prompt if one appears; otherwise it stays agent testimony until I run the \`hunch review --confirm <id>\` command the response prints.
 6. On CONFLICT for the topic, do NOT auto-supersede — Hunch refuses and presents both; let me choose supersede (link) / split the topic / discard.
 `;
 const WORKTREES_CMD = `---

package/dist/integrations/workspaceLedger.d.ts

@@ -58,16 +58,36 @@ export declare function renderBranchTable(view: LedgerView, rows: BranchRow[]):
  *  view stays fast); null when memory holds no workspace record. */
 export declare function workspaceSummaryLine(records: readonly Workspace[], config: WorkspacesConfig, now?: Date): string | null;
 export { branchRows, worktreeRows };
-export declare function prunePlanFor(view: LedgerView): PrunePlan;
+/** This machine's plan: the pure plan from the live record, then two live checks per step.
+ *  A step `git branch -d` would refuse is moved to `skipped` BEFORE anything runs (removing
+ *  the worktree and then failing the branch delete would half-apply the step), and a
+ *  worktree's ignored files — which `git worktree remove` deletes without asking — are
+ *  attached so the plan and the confirmation name them. */
+export declare function prunePlanFor(view: LedgerView, root: string): PrunePlan;
+/** Why `git branch -d -- <branch>` would refuse right now, or null when it would delete.
+ *  Mirrors git's own rule (builtin/branch.c `branch_merged`): the branch head must be an
+ *  ancestor of its upstream when one is configured AND resolves, otherwise of HEAD of the
+ *  worktree the command runs in (the main worktree). Squash and rebase merges never pass it
+ *  once the upstream is gone or unset, so such a step is reported, not half-applied. The
+ *  branch name is matched in JS; only refs git printed and SHAs reach git as arguments. */
+export declare function branchDeleteRefusal(root: string, step: Pick<PruneStep, "branch" | "head" | "method">): string | null;
 export interface PruneResult {
     step: PruneStep;
-    outcome: "deleted" | "failed";
+    /** `skipped`: a live precondition failed before anything ran — the step is untouched. */
+    outcome: "deleted" | "skipped" | "failed";
     detail: string;
 }
 /** Execute the local steps of a plan. Each command is a fixed argv; the branch name was
  *  validated by the record schema and is passed after `--`; the worktree path comes from
- *  `git worktree list` on this machine. A failure stops that step, never the others. */
+ *  `git worktree list` on this machine. `git branch -d`'s own precondition is re-checked
+ *  BEFORE the worktree is removed, so a step either runs whole or not at all. A failure
+ *  stops that step, never the others. */
 export declare function applyPrune(root: string, steps: readonly PruneStep[]): PruneResult[];
+export declare function describeIgnored(ignored: NonNullable<PruneStep["ignored"]>): string;
+/** The confirmation question for `prune --apply`: counts, and — because `git worktree
+ *  remove` deletes ignored files (.env, build output) without asking — every worktree's
+ *  ignored paths by name. */
+export declare function pruneConfirmQuestion(view: LedgerView, plan: PrunePlan): string;
 /** Interactive yes/no; false when stdin is not a terminal (the caller then needs --yes). */
 export declare function confirmPrune(question: string): Promise<boolean>;
 export declare function renderPrunePlan(view: LedgerView, plan: PrunePlan): string;