@davesheffer/hunch 1.39.3 → 1.40.1

package/dist/extractors/k8sManifest.d.ts

@@ -37,11 +37,21 @@ interface K8sReferenceCandidate {
      *  value (data-dependent, not statically known). */
     refKind: string;
     name: ManifestNameRef;
+    /** The namespace this reference resolves IN, or null for "unknown" (see
+     *  literalNamespace). Kubernetes name references are same-namespace by
+     *  definition, so this defaults to the referring DOCUMENT's own namespace;
+     *  the one shape that can legitimately point elsewhere (a Gateway API
+     *  `backendRefs[].namespace` sibling) overrides it. */
+    namespace: string | null;
 }
 type ManifestLabelMap = Record<string, string>;
 interface K8sResourceDoc {
     kind: string;
     name: ManifestNameRef;
+    /** `metadata.namespace` when it is a plain literal, else null = UNKNOWN (see
+     *  literalNamespace). Cluster-scoped kinds need no special case: they simply
+     *  never carry the field, so they are unknown and compatible with anything. */
+    namespace: string | null;
     startChar: number;
     endChar: number;
 }
@@ -51,6 +61,9 @@ export interface K8sManifestDocument {
     selector: ManifestLabelMap | null;
     labels: ManifestLabelMap | null;
 }
+/** Namespace compatibility per the product rule: a MISSING (unknown) namespace
+ *  matches anything; two DIFFERENT literal namespaces block the edge. */
+export declare function namespacesCompatible(a: string | null, b: string | null): boolean;
 /** Where a kind's pod spec lives -- factored once so container/volume field
  *  paths below aren't hand-duplicated per kind. */
 export declare const POD_SPEC_PATH_BY_KIND: Record<string, string>;

package/dist/extractors/k8sManifest.js

@@ -390,6 +390,75 @@ function scanFieldPaths(text, baseChar) {
 function findEntry(entries, path) {
     return entries.find((e) => e.path === path);
 }
+/** The RFC 1123 DNS label a real Kubernetes namespace name must be -- the
+ *  positive test literalNamespace applies (see there for why). */
+const DNS_LABEL = /^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$/;
+/** A namespace a reference can be MATCHED on, or null meaning UNKNOWN.
+ *  Deliberately narrower than the ManifestNameRef literal/template split that
+ *  names get: a name is a resolution KEY (a template's raw text matches
+ *  another identical template's raw text, which is real evidence), whereas a
+ *  namespace here is only ever a FILTER, and the product rule is that unknown
+ *  matches anything. So a templated `namespace: {{ .Release.Namespace }}` is
+ *  unknown rather than a `T:`-keyed literal -- two documents whose namespace
+ *  renders identically must not be blocked from linking just because one
+ *  spells it via a template and the other spells it out, and two DIFFERENT
+ *  template expressions are not evidence of different namespaces either.
+ *  Absent (no entry at all) and an explicit empty string are unknown for the
+ *  same reason: neither names a namespace this scanner can compare.
+ *
+ *  The literal-ness test is therefore POSITIVE, not a list of excluded
+ *  spellings: a value counts only when it already looks like the RFC 1123 DNS
+ *  label a real namespace must be. One test then covers every shape the
+ *  scanner cannot resolve, without a special case per spelling -- the scanner
+ *  only tags a value "template" when the template action starts the value, so
+ *  `namespace: app-{{ .Values.env }}` arrives here as a "literal" and would
+ *  otherwise block edges against the very namespace it renders to; likewise
+ *  YAML null spellings (`~`, `Null`), anchors and tags (`&ns prod`,
+ *  `!!str prod`), uppercase, whitespace and empty. Blocking is the damaging
+ *  direction (unknown never blocks an edge), so anything uncomparable is
+ *  unknown.
+ *
+ *  `null` is the one spelling the regex admits but must still be rejected,
+ *  since it is also the bare YAML null word. It is excluded explicitly rather
+ *  than by inspecting quotes: stripQuotes runs in the scanner, so a genuinely
+ *  quoted `namespace: "null"` is indistinguishable here -- and reading it as
+ *  unknown errs in the conservative direction. */
+function literalNamespace(entry) {
+    if (!entry || entry.value.form !== "literal")
+        return null;
+    const value = entry.value.value;
+    if (value === "null" || !DNS_LABEL.test(value))
+        return null;
+    return value;
+}
+/** The namespace named at `path`, reading EVERY entry there rather than the
+ *  first. A Helm `{{- if }} namespace: prod {{- else }} namespace: staging
+ *  {{- end }}` emits both branches as entries on the same path, and taking
+ *  findEntry's first one would read the document as confidently `prod` and
+ *  block every edge to `staging`. Only an unambiguous agreement -- at least
+ *  one entry, all of them the same literal -- is a namespace this scanner can
+ *  compare; disagreement is unknown, like any other unresolved shape. */
+function namespaceAt(entries, path) {
+    let agreed = null;
+    let seen = false;
+    for (const e of entries) {
+        if (e.path !== path)
+            continue;
+        const ns = literalNamespace(e);
+        if (ns === null)
+            return null;
+        if (seen && ns !== agreed)
+            return null;
+        agreed = ns;
+        seen = true;
+    }
+    return agreed;
+}
+/** Namespace compatibility per the product rule: a MISSING (unknown) namespace
+ *  matches anything; two DIFFERENT literal namespaces block the edge. */
+export function namespacesCompatible(a, b) {
+    return a === null || b === null || a === b;
+}
 /** Where a kind's pod spec lives -- factored once so container/volume field
  *  paths below aren't hand-duplicated per kind. */
 export const POD_SPEC_PATH_BY_KIND = {
@@ -448,14 +517,32 @@ function fieldSpecsForKind(kind) {
         specs.push({ path: "spec.rules[].backendRefs[].name", refKind: "Service" });
     return specs;
 }
-function extractFieldReferences(kind, entries) {
+/** The ONE reference shape in fieldSpecsForKind that Kubernetes lets point at
+ *  another namespace: a Gateway API `backendRefs[]` entry carries an optional
+ *  `namespace` SIBLING of its own `name`. Every other shape here
+ *  (configMapRef/secretRef/volumes/imagePullSecrets/Ingress backend/
+ *  ownerReferences) is same-namespace by API definition and has no namespace
+ *  field at all, so none of them needs an override. Read off the concrete
+ *  (non-wildcarded) entry list by exact parentPath -- the same
+ *  pair-siblings-by-index technique extractOwnerReferenceCandidates uses --
+ *  rather than new parsing machinery. */
+const NAMESPACE_SIBLING_PATHS = new Set(["spec.rules[].backendRefs[]"]);
+function extractFieldReferences(kind, entries, docNamespace) {
     const specs = fieldSpecsForKind(kind);
     const out = [];
     for (const e of entries) {
         const wp = wildcardPath(e.path);
         const spec = specs.find((s) => s.path === wp);
-        if (spec)
-            out.push({ refKind: spec.refKind, name: e.value });
+        if (!spec)
+            continue;
+        // A sibling that EXISTS but isn't a comparable literal (templated, empty)
+        // must read as unknown, NOT fall back to the document's namespace: it is
+        // an explicit statement that the target lives somewhere this scanner
+        // cannot name, which is the opposite of "same namespace as me". So the
+        // sibling's existence is checked before its literal-ness.
+        const siblingPath = `${e.parentPath}.namespace`;
+        const hasSibling = NAMESPACE_SIBLING_PATHS.has(wildcardPath(e.parentPath)) && entries.some((c) => c.path === siblingPath);
+        out.push({ refKind: spec.refKind, name: e.value, namespace: hasSibling ? namespaceAt(entries, siblingPath) : docNamespace });
     }
     return out;
 }
@@ -465,7 +552,7 @@ function extractFieldReferences(kind, entries) {
  *  entries never get cross-paired. Not expressible via FieldPathSpec's
  *  single-fixed-refKind model, so it's a dedicated pass over the concrete
  *  (non-wildcarded) entries. */
-function extractOwnerReferenceCandidates(entries) {
+function extractOwnerReferenceCandidates(entries, docNamespace) {
     const byIndex = new Map();
     for (const e of entries) {
         const m = /^metadata\.ownerReferences(\[\d+\])\.(name|kind)$/.exec(e.path);
@@ -479,7 +566,10 @@ function extractOwnerReferenceCandidates(entries) {
     for (const { name, kind } of byIndex.values()) {
         if (!name || !kind || kind.value.form !== "literal")
             continue; // an owner's kind must be a literal to type the reference at all
-        out.push({ refKind: kind.value.value, name: name.value });
+        // An ownerReferences entry has NO namespace field in the API at all -- an
+        // owner is always in the owned object's own namespace (or cluster-scoped),
+        // so the document's namespace is the only correct answer here.
+        out.push({ refKind: kind.value.value, name: name.value, namespace: docNamespace });
     }
     return out;
 }
@@ -550,11 +640,17 @@ function buildDocument(text, docStartChar, entries, unresolvedContainers, valuel
     const kind = kindEntry?.value.form === "literal" ? kindEntry.value.value : null;
     if (!kind || !ALLOWED_KINDS.has(kind))
         return { resource: null, references: [], selector: null, labels: null };
+    // Found with the same entry machinery as metadata.name, so it inherits the
+    // scanner's quote-stripping, comment-stripping and CRLF tolerance for free.
+    // Read OUTSIDE the `resource` branch below: a document with no
+    // metadata.name still emits references, and those references carry this
+    // document's namespace.
+    const namespace = namespaceAt(entries, "metadata.namespace");
     const nameEntry = findEntry(entries, "metadata.name");
     const resource = nameEntry
-        ? { kind, name: nameEntry.value, startChar: docStartChar, endChar: docStartChar + text.length }
+        ? { kind, name: nameEntry.value, namespace, startChar: docStartChar, endChar: docStartChar + text.length }
         : null;
-    const references = [...extractFieldReferences(kind, entries), ...extractOwnerReferenceCandidates(entries)];
+    const references = [...extractFieldReferences(kind, entries, namespace), ...extractOwnerReferenceCandidates(entries, namespace)];
     const selector = kind === "Service" ? extractLiteralLabelMap("spec.selector", entries, unresolvedContainers, valuelessKeyParents) : null;
     const labelsPath = LABELS_PATH_BY_KIND[kind];
     const labels = labelsPath ? extractLiteralLabelMap(labelsPath, entries, unresolvedContainers, valuelessKeyParents) : null;

package/dist/extractors/landscapeDiscovery.js

@@ -6,6 +6,7 @@ import { compareCodeUnits } from "../core/canonicalOrder.js";
 import { resourceId, resourceRelationshipId } from "../core/ids.js";
 import { parseJsonc } from "../core/jsonc.js";
 import { parseSource } from "./parse.js";
+import { isParserLoadError } from "./nativeTreeSitter.js";
 import { EdgeSchema, ResourceSchema, isCredentialFreeText, } from "../core/types.js";
 import { canonicalRemoteRepositoryIdentity, foreignRepoEnv, gitNullDevice, } from "./git.js";
 export const LANDSCAPE_DISCOVERY_SCHEMA_VERSION = "hunch.landscape-discovery/1";
@@ -2026,7 +2027,14 @@ function sloDeclarations(root, tree, issues) {
         try {
             valid = blob.format === "json" ? validJsonOpenSlo(source) : validYamlOpenSlo(blob.path, source);
         }
-        catch {
+        catch (error) {
+            // A malformed declaration is a bad file and stays one issue. A dead
+            // native parser is not: swallowing it made `landscape review` report
+            // every valid SLO as slo_declaration_invalid, drop the resource, and
+            // still exit 0 with a ready-made `landscape adopt --acknowledge-issues`
+            // line — a store write of a false verdict.
+            if (isParserLoadError(error))
+                throw error;
             valid = false;
         }
         if (!valid) {

package/dist/extractors/nativeTreeSitter.d.ts

@@ -8,6 +8,30 @@ export interface NativeTreeSitterRuntime {
     php: unknown;
     yaml: unknown;
 }
+/** The parser runtime itself is unavailable — the addons could not be copied or
+ *  dlopen'd (unwritable/full TMPDIR, a missing or wrong-arch prebuild, npm
+ *  replacing the package mid-session, or the fail-closed "preloaded addon"
+ *  guard). Distinct from a per-file parse error on purpose: now that the load
+ *  happens on first parse rather than at import, every swallow-and-continue
+ *  catch on a parse path would otherwise read this as "this one file is bad"
+ *  and, in a whole-repo scan, mark EVERY file parse_failed and overwrite the
+ *  graph with nothing. Callers rethrow it so the run dies before any write,
+ *  the way the import-time load used to. The original error is kept as `cause`
+ *  and its text is carried in the message so the EACCES/dlopen detail a user
+ *  needs is never lost. */
+export declare class NativeTreeSitterLoadError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The ONE predicate every rethrow site uses — a dead parser is recognised the
+ *  same way everywhere, so no catch can quietly disagree about what counts.
+ *  `instanceof` alone is not enough: a duplicated module instance (two copies of
+ *  this file in one process, e.g. dist/ + src/ under tsx, or a worker that
+ *  re-resolves it) gives a different class identity, and an error rebuilt across
+ *  a worker/IPC boundary keeps only its plain properties. The name check
+ *  survives both. */
+export declare function isParserLoadError(e: unknown): boolean;
 /** Load all native tree-sitter addons (the parser runtime + every grammar) from
  * process-owned temp copies. Windows keeps loaded `.node` files locked for the
  * process lifetime; redirecting the upstream loaders means npm can replace the

package/dist/extractors/nativeTreeSitter.js

@@ -13,6 +13,40 @@ const NATIVE_PACKAGES = [
     "@tree-sitter-grammars/tree-sitter-yaml",
 ];
 let runtime = null;
+/** The parser runtime itself is unavailable — the addons could not be copied or
+ *  dlopen'd (unwritable/full TMPDIR, a missing or wrong-arch prebuild, npm
+ *  replacing the package mid-session, or the fail-closed "preloaded addon"
+ *  guard). Distinct from a per-file parse error on purpose: now that the load
+ *  happens on first parse rather than at import, every swallow-and-continue
+ *  catch on a parse path would otherwise read this as "this one file is bad"
+ *  and, in a whole-repo scan, mark EVERY file parse_failed and overwrite the
+ *  graph with nothing. Callers rethrow it so the run dies before any write,
+ *  the way the import-time load used to. The original error is kept as `cause`
+ *  and its text is carried in the message so the EACCES/dlopen detail a user
+ *  needs is never lost. */
+export class NativeTreeSitterLoadError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "NativeTreeSitterLoadError";
+    }
+}
+/** The ONE predicate every rethrow site uses — a dead parser is recognised the
+ *  same way everywhere, so no catch can quietly disagree about what counts.
+ *  `instanceof` alone is not enough: a duplicated module instance (two copies of
+ *  this file in one process, e.g. dist/ + src/ under tsx, or a worker that
+ *  re-resolves it) gives a different class identity, and an error rebuilt across
+ *  a worker/IPC boundary keeps only its plain properties. The name check
+ *  survives both. */
+export function isParserLoadError(e) {
+    return e instanceof NativeTreeSitterLoadError || e?.name === "NativeTreeSitterLoadError";
+}
+/** Wrap any loader failure once, preserving an already-typed one. */
+function loadFailure(error) {
+    if (error instanceof NativeTreeSitterLoadError)
+        return error;
+    const detail = error instanceof Error ? error.message : String(error);
+    return new NativeTreeSitterLoadError(`native tree-sitter parser unavailable: ${detail}`, { cause: error });
+}
 function processIsAlive(pid) {
     if (pid === process.pid)
         return true;
@@ -71,6 +105,19 @@ function copyNativeBinding(packageName, copyRoot, nodeGypBuild) {
 export function loadNativeTreeSitter() {
     if (runtime)
         return runtime;
+    // Only SUCCESS is memoized (in `runtime`), never the failure: the conditions
+    // that break the load are transient — a full or read-only TMPDIR, an npm
+    // install swapping the package out from under a live process. A long-lived
+    // MCP server must be able to parse again once the condition clears, so every
+    // call retries the load from scratch.
+    try {
+        return loadRuntime();
+    }
+    catch (error) {
+        throw loadFailure(error);
+    }
+}
+function loadRuntime() {
     // Three binding spellings: prebuilds ship as tree-sitter[-typescript|-python].node
     // or, for a scoped package like @tree-sitter-grammars/tree-sitter-yaml, as
     // @scope+name.node; from-source builds are named after the binding.gyp target
@@ -85,9 +132,15 @@ export function loadNativeTreeSitter() {
     }
     removeStaleCopies();
     const copyRoot = mkdtempSync(join(tmpdir(), `${COPY_PREFIX}${process.pid}-`));
-    const nodeGypBuild = runtimeRequire("node-gyp-build");
     const previous = new Map();
     try {
+        // Resolved INSIDE the try: if node-gyp-build cannot be resolved (a partial
+        // install, npm mid-swap) the catch below still removes the copy dir we just
+        // created. Outside it, every retry — and failure is deliberately not
+        // memoized, so a long-lived MCP server retries forever — leaked one empty
+        // hunch-tree-sitter-<pid>-* dir that removeStaleCopies can never prune,
+        // because it only prunes dirs whose pid is dead.
+        const nodeGypBuild = runtimeRequire("node-gyp-build");
         for (const packageName of NATIVE_PACKAGES) {
             const key = environmentKey(packageName);
             previous.set(key, process.env[key]);

package/dist/extractors/parse.d.ts

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

package/dist/extractors/parse.js

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

package/dist/integrations/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/hooks.d.ts

@@ -10,17 +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, but a dead one: the snippet
-     *  REPLACES it rather than being added (non-writing actions only). */
+    /** 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
@@ -125,4 +153,15 @@ export declare function hookInvocationLines(report: HookReport, running: string)
  *  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 {};