@davesheffer/hunch 1.39.2 → 1.40.0

package/dist/extractors/parse.js

@@ -1,10 +1,15 @@
 import { languageFor } from "./languages.js";
 import { loadNativeTreeSitter } from "./nativeTreeSitter.js";
-const { Parser } = loadNativeTreeSitter();
+/** Resolved on first parse, not at import: loading the native addons copies six
+ *  `.node` files into a temp dir and dlopens them (~1.5s+ cold), which every CLI
+ *  command and every editor hook would otherwise pay just for importing this
+ *  module. loadNativeTreeSitter() memoizes the runtime itself. */
+const parserRuntime = () => loadNativeTreeSitter().Parser;
 const cache = new Map();
 function bundleFor(spec) {
     let b = cache.get(spec.grammarKey);
     if (!b) {
+        const Parser = parserRuntime();
         const parser = new Parser();
         const grammar = spec.loadGrammar();
         parser.setLanguage(grammar);

package/dist/integrations/claudemd.js

@@ -47,7 +47,7 @@ export function renderHunchSection(store, root) {
     lines.push("**Consult Hunch via the `hunch_*` MCP tools — pick by MOMENT, not from memory:**");
     lines.push("");
     lines.push("**Orient (session/task start):**");
-    lines.push("- For a new user task, call `hunch_task(action: \"start\", title: <short task title>)` once and retain its `task_id`. Claude Code's prompt hook supplies a task ID natively — reuse its exact start arguments instead of creating another task (each new prompt has its own ID). Codex supplies one the same way once its `.codex/hooks.json` is trusted (`/hooks`). Hosts without prompt hooks (Windsurf, Cursor) never receive one: start the task yourself. Reuse the ID for follow-up work on the same task; never borrow another task's ID. This is task bookkeeping; `hunch_context` remains the first memory lookup. If reporting fails, continue the work and disclose the gap.");
+    lines.push("- If the host's prompt hook already opened the task and printed a task ID plus a `task verify` command, reuse that exact ID and command — do NOT call `hunch_task(action: \"start\")` for it. Otherwise start the task yourself: call `hunch_task(action: \"start\", title: <short task title>)` once and take `verification_argv` from its result. Each new prompt has its own ID; reuse the ID for follow-up work on the same task and never borrow another task's ID. This is task bookkeeping; `hunch_context` remains the first memory lookup. If reporting fails, continue the work and disclose the gap.");
     lines.push("- When the user asks to **update Hunch**, run `hunch update` from this repository root. It updates to the latest release and repairs all configured harness pins. Use `hunch update --global` to also update a global CLI alongside a repository dependency; reconnect active MCP sessions afterward.");
     lines.push("- `hunch_context(target, task_id)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST** for memory. Include the current task ID on each context call so its contribution is inspectable.");
     lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");
@@ -73,10 +73,10 @@ export function renderHunchSection(store, root) {
     lines.push("- `hunch_pr_impact(base?)` / `hunch_merge_verdict(...)` — a change's memory surface; would it re-open a closed bug?");
     lines.push("");
     lines.push("**Before the final response — make Hunch's contribution visible:**");
-    lines.push("- When running a relevant check, use the exact verification_argv launcher returned by hunch_task start, followed by the check command and its arguments, from this worktree. It runs `hunch task verify <task_id> -- <command> [arguments]` using the same installation as MCP, avoiding stale global binaries. This retains the actual exit result and source snapshot; raw output is not stored. Do not rerun an expensive check solely for reporting; missing evidence stays unverified.");
+    lines.push("- When running a relevant check, use the exact launcher the prompt hook printed — or, on a host without one, the `verification_argv` returned by hunch_task start — followed by the check command and its arguments, from this worktree. It runs `hunch task verify <task_id> -- <command> [arguments]` using the same installation as MCP, avoiding stale global binaries. This retains the actual exit result and source snapshot; raw output is not stored. Do not rerun an expensive check solely for reporting; missing evidence stays unverified.");
     lines.push("- Include the current task_id when calling hunch_record_decision, hunch_record_correction, or hunch_record_finding. The save path records its actual memory home and verifies exact Git revisions when committing or pushing; never infer publication from a successful capture alone.");
     lines.push("- Before claiming an application, call `hunch_report(task_id)` and copy the exact occurrence_id, record_id and content_hash from application_references, adding an action you actually took. Never derive an occurrence ID by replacing a receipt prefix or use the task's scope hash as a record hash. If you did not apply a lesson, omit applications.");
-    lines.push("- Call `hunch_task(action: \"finish\", task_id, applications?)` and include the returned contribution_card in your final response without the user asking. Copy the card verbatim, including its Evidence line (the command that renders the local report on demand) and the agent-reported label; the structured result contains the card even when the host hides text blocks. Do not replace it with a generic claim that Hunch helped. If presentation_enabled is false, omit the card. A delivered lesson or passing command alone does not prove causal impact.");
+    lines.push("- When this task actually used Hunch (a `hunch_*` call carrying the task_id, a verified check, Hunch hook context you acted on, or an application to claim), call `hunch_task(action: \"finish\", task_id, applications?)` and include the returned contribution_card in your final response without the user asking. Skip the finish call only when it used none of those AND the host's own stop hook closes the task and shows the evidence for you (its prompt-hook instruction says so); where no host hook closes the task, and for a task you started yourself with `hunch_task(action: \"start\")`, always finish it yourself. Copy the card verbatim, including its Evidence line (the command that renders the local report on demand) and the agent-reported label; the structured result contains the card even when the host hides text blocks. Do not replace it with a generic claim that Hunch helped. If presentation_enabled is false, omit the card. A delivered lesson or passing command alone does not prove causal impact.");
     lines.push("- If interrupted, finish with `outcome: \"interrupted\"` when possible. `hunch_report(task_id, html: true)` opens the evidence trail by generating a local file; it may contain private memory and is not a public export. If report tools are unavailable after an update, say so and reconnect the host rather than inventing a report.");
     lines.push("");
     lines.push("**Build the Constitution review queue:**");

package/dist/integrations/hookmatch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The single rule for "is this hook command Hunch's own?", shared by every hook
+ * writer (scaffold.ts for Claude Code's .claude/settings.json, providers.ts for
+ * Cursor/Codex/VS Code/Windsurf/Antigravity). One rule, because each writer
+ * deletes what it classifies as ours, and a writer that guesses wide deletes the
+ * user's hooks (con_8460b6770f).
+ */
+/** Does one command string invoke Hunch's own hook?
+ *
+ * Anchored to the shapes hookCommand() / resolveInvocation() write — a Hunch
+ * launcher (the pinned npm package spec, or a …/dist|src/cli/index.js|ts path for
+ * source installs) plus a `hook` tail, tokens quoted or bare. The old unanchored
+ * /index\.(js|ts)/ + /\bhook\b/ pair classified FOREIGN entries like
+ * `node ./hook/index.js` as ours and silently deleted them, violating the
+ * leave-every-foreign-hook-in-place contract (con_8460b6770f, issue #41).
+ *
+ * `requireProvider` distinguishes the two writers. Provider configs always carry
+ * `hook --provider <name>`, so their tail must too; only the LEGACY fully-quoted
+ * form (written before the quoting fix, and by hunch versions that predate
+ * --provider) may omit it, and its quotes keep it unambiguous. Claude Code's own
+ * settings.json never carries --provider, so a bare `hook` tail is all that is
+ * left to match on — and a bare tail alone is far too weak, so there the WHOLE
+ * command must be one of the two shapes `hunch init` has ever written (see
+ * isClaudeCodeHookCommand). */
+export declare function isHunchHookCommand(command: string, requireProvider: boolean): boolean;

package/dist/integrations/hookmatch.js

@@ -0,0 +1,58 @@
+/**
+ * The single rule for "is this hook command Hunch's own?", shared by every hook
+ * writer (scaffold.ts for Claude Code's .claude/settings.json, providers.ts for
+ * Cursor/Codex/VS Code/Windsurf/Antigravity). One rule, because each writer
+ * deletes what it classifies as ours, and a writer that guesses wide deletes the
+ * user's hooks (con_8460b6770f).
+ */
+/** Does one command string invoke Hunch's own hook?
+ *
+ * Anchored to the shapes hookCommand() / resolveInvocation() write — a Hunch
+ * launcher (the pinned npm package spec, or a …/dist|src/cli/index.js|ts path for
+ * source installs) plus a `hook` tail, tokens quoted or bare. The old unanchored
+ * /index\.(js|ts)/ + /\bhook\b/ pair classified FOREIGN entries like
+ * `node ./hook/index.js` as ours and silently deleted them, violating the
+ * leave-every-foreign-hook-in-place contract (con_8460b6770f, issue #41).
+ *
+ * `requireProvider` distinguishes the two writers. Provider configs always carry
+ * `hook --provider <name>`, so their tail must too; only the LEGACY fully-quoted
+ * form (written before the quoting fix, and by hunch versions that predate
+ * --provider) may omit it, and its quotes keep it unambiguous. Claude Code's own
+ * settings.json never carries --provider, so a bare `hook` tail is all that is
+ * left to match on — and a bare tail alone is far too weak, so there the WHOLE
+ * command must be one of the two shapes `hunch init` has ever written (see
+ * isClaudeCodeHookCommand). */
+export function isHunchHookCommand(command, requireProvider) {
+    if (!requireProvider)
+        return isClaudeCodeHookCommand(command);
+    const published = /@davesheffer\/hunch/.test(command);
+    const launcher = published || /(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts)(?=["\s]|$)/.test(command);
+    const legacyTail = /\s"hook"(?:\s+"--provider"\s+"[a-z]+")?\s*$/.test(command);
+    return launcher && (legacyTail || /\s"?hook"?\s+"?--provider"?\s+"?[a-z]+"?\s*$/.test(command));
+}
+const ABSOLUTE = String.raw `(?:\/|[A-Za-z]:[\\/]|\\\\)`;
+const CLI_ENTRY = String.raw `[\\/](?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts)`;
+const SOURCE_HOOK = new RegExp(String.raw `^\s*(?:"?npx(?:\.cmd)?"?\s+"?tsx"?|"[^"]+"|\S+)\s+(?:"${ABSOLUTE}[^"]*${CLI_ENTRY}"|${ABSOLUTE}\S*${CLI_ENTRY})\s+"?hook"?\s*$`);
+/** The bare-`hook` shapes written into .claude/settings.json, matched as a whole
+ *  command so nothing chained before or after one can be swept out with it:
+ *
+ *   - published: `npx -y --package=[hunch-exact@npm:]@davesheffer/hunch[@v] hunch hook`
+ *   - source / `npm link` / dev: `<runtime> <ABSOLUTE …/dist|src/cli/index.js|ts> hook`
+ *
+ *  Quoting is NOT the discriminator. shellInvocation() leaves a safe token bare, so
+ *  since v1.21.1 a POSIX source install writes `/usr/bin/node /abs/dist/cli/index.js
+ *  hook` with no quotes at all (quotes appear only for a space or a Windows
+ *  backslash, and on every token before v1.21.1). Requiring them left our own hook
+ *  in place and appended another on each `hunch init`. What every version shares is
+ *  an absolute entry path — resolveInvocation() derives it from import.meta.url —
+ *  and that is what keeps a tool which merely shares the layout
+ *  (`node tools/lint/dist/cli/index.js hook`) foreign; deleting it was issue #310.
+ *  A foreign tool invoked by ABSOLUTE path with this exact layout and a lone `hook`
+ *  argument is still indistinguishable by string alone. */
+function isClaudeCodeHookCommand(command) {
+    const published = /^\s*"?npx(?:\.cmd)?"?\s+/i.test(command)
+        && /--package=(?:hunch-exact@npm:)?@davesheffer\/hunch(?:@[^"\s]+)?(?=["\s])/.test(command)
+        && /\s"?hunch"?\s+"?hook"?\s*$/.test(command);
+    return published || SOURCE_HOOK.test(command);
+}
+//# sourceMappingURL=hookmatch.js.map

package/dist/integrations/hooks.d.ts

@@ -10,14 +10,45 @@ export interface HookInstall {
     /** The hook file written; for a non-writing result, the file the user should edit. */
     path: string;
     /** created/appended/updated/unchanged: the block is (now) in a file git reaches.
+     *  kept-shared: the shared hook already runs a Hunch that is not inside a
+     *  linked worktree, so it was deliberately left as it is rather than
+     *  re-pointed at one (issue #316); a success, not a failure.
      *  managed-elsewhere: a hook manager owns the hook — nothing was written.
-     *  unreachable: the existing hook ends in exec/exit before our block — nothing was written. */
-    action: "created" | "appended" | "updated" | "unchanged" | "managed-elsewhere" | "unreachable";
+     *  unreachable: the existing hook ends in exec/exit before our block, or the
+     *  block in it has no closing marker and so cannot be replaced in place —
+     *  nothing was written. */
+    action: "created" | "appended" | "updated" | "unchanged" | "kept-shared" | "managed-elsewhere" | "unreachable";
     manager?: HookManagerKind;
     /** Why nothing was written (non-writing actions only). */
     reason?: string;
     /** What to add to `path` by hand (non-writing actions only). */
     snippet?: string;
+    /** The file already carries a Hunch block — a dead one, or one that cannot be
+     *  updated in place: the snippet REPLACES it rather than being added
+     *  (non-writing actions only). */
+    stale?: boolean;
+    /** The block that could not be updated still RUNS as it is (it only lacks its
+     *  closing marker), so the failure is this run's update, not the install. */
+    live?: boolean;
+    /** The block in the file deliberately runs the repo's EXISTING shared
+     *  invocation instead of the caller's worktree-bound one (issue #316). Set on
+     *  kept-shared, and on created/appended/updated when that substitution happened. */
+    sharedInvocation?: string;
+    /** The options the existing SHARED block carries that this run did not ask for
+     *  and that were kept anyway — its own flags (BLOCK_FLAGS), e.g. a strict
+     *  pre-commit guard that a worktree's advisory re-run must not silently
+     *  downgrade, and the post-commit block's local-only provider line (named
+     *  `HUNCH_SYNTH_PROVIDER=deterministic`). Set on kept-shared, and on updated
+     *  when the run also added an option of its own. */
+    keptFlags?: string[];
+    /** The options this run ADDED to the existing shared block (updated only). */
+    addedFlags?: string[];
+    /** Set when a DEAD block was rebuilt from the repo's shared launcher and the
+     *  previous block's own option flags were not requested again. Reported, not
+     *  restored: the flags come from the caller's options, so re-adding one would
+     *  invent a request nobody made — but losing a strict guard in silence is
+     *  exactly the issue-#316 failure mode. */
+    droppedFlags?: string[];
 }
 /** 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
@@ -30,7 +61,23 @@ export declare const PORTABLE_HOOK_INVOCATION: string;
  *  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 declare function terminalExitLine(content: string): string | null;
-type BlockState = "installed" | "unreachable" | "missing";
+type BlockState = "installed" | "unreachable" | "stale" | "missing";
+/** The result of inspecting the command a managed block actually runs (issue #315). */
+export type HookInvocationHealth = {
+    ok: true;
+    invocation: string;
+} | {
+    ok: false;
+    invocation: string;
+    reason: string;
+};
+/** Whether the command in front of a managed block's subcommand is a Hunch
+ *  launcher that could actually run (issue #315): a block whose command was
+ *  hand-edited into something else, or whose absolute node/CLI path no longer
+ *  exists after a reinstall, is present but dead. `command` is the text BEFORE
+ *  the subcommand; env assignments and a leading `(` belong to the block's own
+ *  shape and are stripped. Never spawns anything, never touches the network. */
+export declare function hookInvocationHealth(command: string, root: string): HookInvocationHealth;
 export declare function installPostCommitHook(root: string, invocation: string, opts?: {
     private?: boolean;
     commit?: boolean;
@@ -64,8 +111,13 @@ export interface HookReportEntry {
     manager: HookManagerKind;
     /** The file where the block lives (or should live). */
     path: string;
-    /** Why an `unreachable` block never runs. */
+    /** Why an `unreachable` block never runs, or why a `stale` one could not work. */
     reason?: string;
+    /** Where the hook points: the distinct invocations of its marks' blocks. */
+    invocation?: string;
+    /** Hunch's own option flags the hook's blocks carry (`--private`, `--commit`,
+     *  `--strict`) — what a plain `hunch init` re-run would drop. Omitted when none. */
+    flags?: string[];
 }
 export interface HookReport {
     postCommit: HookReportEntry;
@@ -74,24 +126,42 @@ export interface HookReport {
     postCheckout: HookReportEntry;
 }
 /** 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
+ *  `installed` (present where git will run it, running a Hunch launcher that
+ *  exists), `unreachable` (present, but after an exec/exit or in a
+ *  manager-owned file git never reaches), `stale` (present where git runs it,
+ *  but its command is not a working Hunch launcher — issue #315), 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 declare function hookReport(root: string): HookReport;
 /** 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. */
+ *  managed block is present where git will actually run it AND the command
+ *  inside it is a Hunch launcher that exists. An unreachable block (issue #311)
+ *  and a stale one (issue #315) are both NOT installed. */
 export declare function hookStatus(root: string): {
     postCommit: boolean;
     preCommit: boolean;
     postMerge: boolean;
     postCheckout: boolean;
 };
+/** Doctor lines for where each installed/stale hook points (issue #315): hooks
+ *  sharing one invocation share one line, and a line whose invocation is not the
+ *  Hunch currently running says so. Informational — a hook may legitimately
+ *  point at a different install. Pure; the caller adds indentation and dim(). */
+export declare function hookInvocationLines(report: HookReport, running: string): string[];
 /** 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 declare function formatHookInstall(root: string, label: string, h: HookInstall, detail?: string): string[];
+/** The closing line `hunch init` prints about the SHARED hooks dir (issue #316).
+ *  Setup used to claim "sharing the repo's hooks + memory" unconditionally —
+ *  true of memory, but the hooks dir is genuinely shared, so a block pointing
+ *  inside a linked worktree dies for every checkout when that worktree goes.
+ *
+ *  The verdict is read from what the shared blocks ACTUALLY run, not from this
+ *  run's actions: a second `hunch init` writes nothing yet the hooks are just as
+ *  broken, and the main checkout — which never used to get a note at all — is
+ *  where the user can most easily fix it. `installs` only decides between the
+ *  healthy variants. `[]` when the repo has no linked worktree. Read-only. */
+export declare function sharedHooksNote(root: string, installs: HookInstall[]): string[];
 export {};