@davesheffer/hunch 1.39.3 → 1.40.0

package/dist/cli/index.js

@@ -37,6 +37,9 @@ import { HunchStore } from "../store/hunchStore.js";
 import { JsonStore } from "../store/jsonStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { assertCompleteRepoScan, indexRepo, mergeScannedEdges, scanRepo } from "../extractors/indexer.js";
+// Importing this module is free (the addon load is a function call, not a
+// top-level side effect); only `doctor` below actually calls the loader.
+import { isParserLoadError, loadNativeTreeSitter } from "../extractors/nativeTreeSitter.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, normalizeProviderName, } from "../synthesis/provider.js";
@@ -52,7 +55,7 @@ import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
 import { extractInlineIntent } from "../extractors/comments.js";
 import { renderText, renderMarkdown, renderSarif, renderImpact, reportFailsStrict } from "../core/checkreport.js";
 import { partitionReview, isReviewDraft, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
-import { installPostCommitHook, installPreCommitHook, installPostMergeHook, installPostCheckoutHook, hookStatus, hookReport, hookInvocationLines, formatHookInstall } from "../integrations/hooks.js";
+import { installPostCommitHook, installPreCommitHook, installPostMergeHook, installPostCheckoutHook, hookStatus, hookReport, hookInvocationLines, formatHookInstall, sharedHooksNote } from "../integrations/hooks.js";
 import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
 import { flushCapture, flushMemoryHome, flushMemoryHomes, pinSharedRemote, sharedRemoteFor } from "../integrations/sync.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
@@ -72,7 +75,7 @@ import { rankingStatusLine, resolveTaskRankingMode } from "../core/taskRankingMo
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
-import { buildDeliveryEnvelope, DELIVERY_PROFILES } from "../core/delivery.js";
+import { buildDeliveryEnvelope, deliveryDedupeInput, DELIVERY_PROFILES } from "../core/delivery.js";
 import { deriveChangeIdentity } from "../core/changeIdentity.js";
 import { deriveChangeProof } from "../core/changeProof.js";
 import { discoverProjectDna, evaluateProjectDnaMatch } from "../core/projectDna.js";
@@ -395,15 +398,21 @@ program
             console.log("  ✓ auto-commit OFF (captures stay uncommitted; commit .hunch/ yourself)");
         }
     }
+    // Collected so the linked-worktree note below can say what actually happened
+    // to the SHARED hooks dir (issue #316) rather than assuming.
+    const installs = [];
     if (isGitRepo(root)) {
         const syncToOverlay = !!(opts.privateSync || opts.sharedSync);
         const h = installPostCommitHook(root, inv.shell, { private: syncToOverlay, commit: opts.autoCommit, localOnly: syncToOverlay });
+        installs.push(h);
         for (const line of formatHookInstall(root, "post-commit hook", h, ` (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${opts.autoCommit ? " — auto-commit on" : ""}`))
             console.log(line);
         const pm = installPostMergeHook(root, inv.shell);
+        installs.push(pm);
         for (const line of formatHookInstall(root, "post-merge hook", pm, " (squash-merge provenance repair + re-syncs grounding docs after a merge that brought memory in)"))
             console.log(line);
         const pc = installPostCheckoutHook(root, inv.shell);
+        installs.push(pc);
         for (const line of formatHookInstall(root, "post-checkout hook", pc, " (workspace ledger: records this machine's branches + worktrees on checkout)"))
             console.log(line);
         const m = installMergeDriver(root, inv.shell);
@@ -414,6 +423,7 @@ program
         if (opts.enforce !== false || opts.enforceStrict) {
             const strict = !!opts.enforceStrict;
             const p = installPreCommitHook(root, inv.shell, strict);
+            installs.push(p);
             for (const line of formatHookInstall(root, "pre-commit constraint guard", p, ` (${strict ? "strict — fails only on direct, high-confidence, non-stale blocking invariants" : "advisory — flags invariants in scope or blast radius"})`))
                 console.log(line);
         }
@@ -469,9 +479,8 @@ program
     if (ensureSharedOverlayPointer(root, store.privateDir, store.privateAutoCommit, store.mode === "shared" ? "shared" : "private")) {
         console.log(`  ✓ private overlay registered at the git common dir — shared by every worktree of this repo`);
     }
-    if (isLinkedWorktree(root)) {
-        console.log(`  ✓ linked worktree — sharing the repo's hooks + memory (no separate setup needed)`);
-    }
+    for (const line of sharedHooksNote(root, installs))
+        console.log(line);
     store.close();
     console.log("\n" + formatIntegrationHealth(inspectIntegrations(root)));
     console.log("\nTask reporting is configured through Hunch's agent instructions; actual agent activity has not been verified by setup. Reconnect the agent, then work normally. Completed task reports are available with `hunch report`.");
@@ -1436,6 +1445,20 @@ program
                 indexNote = `\n  ✓ code graph present in the checkout — blast-radius ready`;
             }
         }
+        catch (error) {
+            // The code graph is this command's CONVENIENCE; the worktree + branch
+            // are its promise, and git has already created them. A dead native
+            // parser (loaded on first parse, so it surfaces here rather than at
+            // import) used to abort between the two: no success line, the ledger
+            // step skipped, and a re-run then hitting "path already exists" with no
+            // way forward. Downgrade it to the same note channel the other optional
+            // steps use — the worktree stands, the user is told the index was
+            // skipped and why, and `hunch index` there fixes it once TMPDIR/the
+            // install is sound. Anything else is still a real failure of this step.
+            if (!isParserLoadError(error))
+                throw error;
+            indexNote = `\n  · code graph skipped — ${error.message}\n    (the worktree is ready; run \`hunch index\` there once the parser loads)`;
+        }
         finally {
             wstore.close();
             openStore = null;
@@ -5202,22 +5225,23 @@ program
             docGround;
         if (!hasContent)
             return; // no noise on files Hunch hasn't learned yet
+        const supplements = [
+            ...(retired.length ? [{
+                    id: "retired-code",
+                    kind: "retired-code",
+                    priority: 200,
+                    text: `⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ")}.`,
+                }] : []),
+            ...(docGround ? [{ id: "doc-grounding", kind: "doc-grounding", priority: 100, text: docGround }] : []),
+            ...recentTasks,
+        ];
         const envelope = buildDeliveryEnvelope(ctx, {
             profile: "builder",
             root,
             symbols: store.recs("symbols"),
             components: store.recs("components"),
             decisionCorpus: store.recs("decisions"),
-            supplements: [
-                ...(retired.length ? [{
-                        id: "retired-code",
-                        kind: "retired-code",
-                        priority: 200,
-                        text: `⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ")}.`,
-                    }] : []),
-                ...(docGround ? [{ id: "doc-grounding", kind: "doc-grounding", priority: 100, text: docGround }] : []),
-                ...recentTasks,
-            ],
+            supplements,
         });
         const text = envelope.text.trim();
         // Identical grounding already shown this session → one-line delta instead of
@@ -5254,7 +5278,12 @@ program
         // it never saw that grounding, so its dedup is scoped by its own agent
         // identity (hashed — the raw agent_id is never retained in the key).
         const agentKey = evt.agent_id ? `:${reportHash(evt.agent_id).slice(7, 19)}` : "";
-        if (injectionMode(evt.session_id, `pre:${target}${reportTaskId ? `:${reportTaskId}` : ""}${agentKey}`, text) === "delta") {
+        // Dedup on the envelope's stable IDENTITY projection, never on the
+        // rendered block: serving the full text writes delivery receipts, and the
+        // next call's task ranking reads them back and moves the wording ("today"
+        // → "delivered today"), so hashing the presentation made this grounding
+        // self-invalidating and re-sent the full block for unchanged records.
+        if (injectionMode(evt.session_id, `pre:${target}${reportTaskId ? `:${reportTaskId}` : ""}${agentKey}`, text, deliveryDedupeInput(envelope, supplements)) === "delta") {
             receipts("refreshed");
             emitContext(provider, "PreToolUse", `Hunch grounding for ${target}: unchanged this session (${envelope.delivered.filter((item) => item.kind === "decisions").length} decision(s), ${envelope.delivered.filter((item) => item.kind === "constraints").length} invariant(s) shown earlier — still current; hunch_why("${target}") to re-expand).`);
             return;
@@ -7191,6 +7220,20 @@ program
     const ctxWarning = await maybeWarnOllamaContext(provider.name, process.env);
     if (ctxWarning)
         console.log(ctxWarning);
+    // The native addons load on first PARSE, not at import, so no other command
+    // that merely starts up proves the parser works. Doctor is the one place
+    // that should pay the ~1.5s load: without this line a broken parser (an
+    // unwritable TMPDIR, a missing or wrong-arch prebuild, an addon preloaded
+    // past the isolation guard) is invisible until an index run refuses.
+    try {
+        loadNativeTreeSitter();
+        console.log(`parser:     native tree-sitter addons load`);
+    }
+    catch (e) {
+        console.log(`parser:     ⛔ ${e.message}`);
+        console.log(dim(`            no file can be parsed — \`hunch index\` refuses rather than emptying the graph`));
+        process.exitCode = 1;
+    }
     const c = store.reindex().counts;
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
     try {

package/dist/constitution/g2BehaviorCandidates.js

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

package/dist/constitution/g2Candidates.js

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

package/dist/constitution/structural.js

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

package/dist/core/delivery.d.ts

@@ -28,6 +28,14 @@ export interface DeliverySupplement {
     text: string;
     /** Higher values are attempted first after ranked memory. */
     priority?: number;
+    /** Stable IDENTITY of the records behind `text`, for callers that dedup
+     *  injections by hash (the pre-edit hook). Some supplements are
+     *  self-invalidating: serving them writes delivery receipts, and the next
+     *  render's wording, scores or slot order move with no record change. Set this
+     *  to what is a property of the record — never of delivery state or the clock —
+     *  and `deliveryDedupeInput` swaps it in for `text` when hashing. Omitted →
+     *  `text` is its own identity. Never shown to the agent. */
+    hash_text?: string;
 }
 export interface DeliveredSupplement {
     id: string;
@@ -106,5 +114,31 @@ export interface DeliveryOptions {
 }
 /** Validate the public receipt without trusting a caller-supplied identity. */
 export declare function assertDeliveryEnvelope(envelope: DeliveryEnvelope): void;
+/** The string a hash-based injection dedup (`injectionMode`'s `hashInput`) must
+ *  key on instead of the rendered block: a STABLE IDENTITY PROJECTION of this
+ *  envelope.
+ *
+ *  THE RULE, for every caller and every provider: nothing that depends on
+ *  delivery receipts, ranking warmth or scores, slot labels, line ORDER, or
+ *  `now` may enter the dedupe hash; a record entering, leaving, or changing
+ *  content MUST. Grounding that violates it is self-invalidating — serving the
+ *  block writes delivery receipts, the next call's ranking reads them back, the
+ *  wording moves ("today" → "delivered today"), the hash changes, and the full
+ *  block is re-sent for records the agent already has.
+ *
+ *  The projection, done line-wise over the one text the assembler produced:
+ *  - a supplement that declared `hash_text` contributes that identity (kind +
+ *    record id + the record's own content hash) instead of its rendered line —
+ *    that is where reason text, slot labels and age words live;
+ *  - every other line contributes verbatim, because it is already a property of
+ *    the records (id, statement, scope, provenance tier, validation state);
+ *  - each contiguous run of `- ` list lines is SORTED, so a pure re-ordering of
+ *    the same records is not a change while a record entering or leaving the run
+ *    still is.
+ *
+ *  Nothing is removed from what the agent SEES — this string is never emitted.
+ *  Never throws: on any surprise the caller gets `envelope.text` back, i.e. the
+ *  original hash-the-presentation behaviour (a full block, never a wrong delta). */
+export declare function deliveryDedupeInput(envelope: DeliveryEnvelope, supplements?: readonly DeliverySupplement[]): string;
 /** Build the one envelope used by CLI, MCP, and the edit hook. */
 export declare function buildDeliveryEnvelope(ctx: AssembledContext, options?: DeliveryOptions): DeliveryEnvelope;

package/dist/core/delivery.js

@@ -21,6 +21,9 @@ const MIN_ADVISORY_CONFIDENCE = 0.5;
 const MIN_UNCONDITIONED_CONFIDENCE = 0.7;
 const MAX_ACTIONABLE_HYPOTHESES = 2;
 const MAX_PROFILE_HEADLINES = 8;
+/** How far a supplement's text is clipped in the rendered line. Shared so
+ *  `deliveryDedupeInput` can reconstruct that exact line to project over it. */
+const SUPPLEMENT_HEADLINE_CHARS = 700;
 const PROFILE_BASE_SCORE = {
     builder: {
         constraints: 900,
@@ -457,6 +460,62 @@ export function assertDeliveryEnvelope(envelope) {
         throw new Error("delivery envelope receipt does not match its content");
     }
 }
+/** The string a hash-based injection dedup (`injectionMode`'s `hashInput`) must
+ *  key on instead of the rendered block: a STABLE IDENTITY PROJECTION of this
+ *  envelope.
+ *
+ *  THE RULE, for every caller and every provider: nothing that depends on
+ *  delivery receipts, ranking warmth or scores, slot labels, line ORDER, or
+ *  `now` may enter the dedupe hash; a record entering, leaving, or changing
+ *  content MUST. Grounding that violates it is self-invalidating — serving the
+ *  block writes delivery receipts, the next call's ranking reads them back, the
+ *  wording moves ("today" → "delivered today"), the hash changes, and the full
+ *  block is re-sent for records the agent already has.
+ *
+ *  The projection, done line-wise over the one text the assembler produced:
+ *  - a supplement that declared `hash_text` contributes that identity (kind +
+ *    record id + the record's own content hash) instead of its rendered line —
+ *    that is where reason text, slot labels and age words live;
+ *  - every other line contributes verbatim, because it is already a property of
+ *    the records (id, statement, scope, provenance tier, validation state);
+ *  - each contiguous run of `- ` list lines is SORTED, so a pure re-ordering of
+ *    the same records is not a change while a record entering or leaving the run
+ *    still is.
+ *
+ *  Nothing is removed from what the agent SEES — this string is never emitted.
+ *  Never throws: on any surprise the caller gets `envelope.text` back, i.e. the
+ *  original hash-the-presentation behaviour (a full block, never a wrong delta). */
+export function deliveryDedupeInput(envelope, supplements = []) {
+    try {
+        const identity = new Map();
+        for (const s of supplements) {
+            if (s.hash_text === undefined)
+                continue;
+            // Key on the line exactly as the assembler rendered it, so the swap is a
+            // substitution and never a guess about the text's shape.
+            identity.set(`- supplemental/${s.kind} | ${clipHeadline(s.text, SUPPLEMENT_HEADLINE_CHARS)}`, `- supplemental/${s.kind} | identity\u0000${s.hash_text}`);
+        }
+        const projected = [];
+        let run = [];
+        const flush = () => { if (run.length) {
+            projected.push(...run.sort());
+            run = [];
+        } };
+        for (const line of envelope.text.split("\n")) {
+            if (!line.startsWith("- ")) {
+                flush();
+                projected.push(line);
+                continue;
+            }
+            run.push(identity.get(line) ?? line);
+        }
+        flush();
+        return projected.join("\n");
+    }
+    catch {
+        return envelope.text; // the projection is an optimization, never a correctness dependency
+    }
+}
 /** Build the one envelope used by CLI, MCP, and the edit hook. */
 export function buildDeliveryEnvelope(ctx, options = {}) {
     const profile = options.profile ?? "builder";
@@ -742,7 +801,7 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         ...(options.supplements ?? []),
     ].sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0) || left.id.localeCompare(right.id));
     for (const [index, supplement] of supplementalCandidates.entries()) {
-        const content = clipHeadline(supplement.text, 700);
+        const content = clipHeadline(supplement.text, SUPPLEMENT_HEADLINE_CHARS);
         if (!content) {
             supplements.push({ id: supplement.id, kind: supplement.kind, delivered: false, reason: "empty", rank: index + 1, token_cost: 0 });
             continue;

package/dist/core/docanchors.js

@@ -1,29 +1,199 @@
 import { currentForTopic, rejectedForTopic } from "./topics.js";
 const MARKER = /<!--\s*hunch:topic\s+([A-Za-z0-9._/-]+)(?:\s+(dec_[A-Za-z0-9]+))?\s*-->/g;
+/** Expand the leading whitespace of a line to columns. A tab advances to the
+ *  NEXT 4-column tab stop (CommonMark), not a flat 4 columns: after two
+ *  spaces a tab is worth 2, so `  \t``` ` sits at column 4 like `\t``` `.
+ *  Matching-only — offsets always come from the original line. */
+function expandTabs(line) {
+    const ws = /^[ \t]*/.exec(line)[0];
+    if (!ws.includes("\t"))
+        return line;
+    let col = 0;
+    for (const c of ws)
+        col += c === "\t" ? 4 - (col % 4) : 1;
+    return " ".repeat(col) + line.slice(ws.length);
+}
+/** For every index i of `probe`, whether probe.slice(i) is a thematic break
+ *  (`---`, `* * *`, `___`: ≤3 leading spaces, then ≥3 of one char separated by
+ *  spaces only). Computed right-to-left in ONE pass so the list-marker walk
+ *  below can ask the question at each nesting level without re-scanning the
+ *  rest of the line each time — the difference between O(L) and O(L²) on a
+ *  line that is nothing but list markers (`- - - …`, an adversarial doc). */
+function thematicBreakSuffixes(probe) {
+    const L = probe.length;
+    // runFrom[i] = the break-so-far state of probe.slice(i) when it consists only
+    // of spaces and one repeated break char: its char, and how many were seen.
+    const ok = new Array(L + 1).fill(false);
+    let ch = "";
+    let count = 0;
+    let onlySpaceSoFar = true;
+    for (let i = L - 1; i >= 0; i--) {
+        const c = probe[i];
+        if (c === " " || c === "\t") {
+            // A space never breaks the run; it is allowed anywhere, including the
+            // ≤3 leading columns handled by the indent check at the call site.
+            ok[i] = ok[i + 1];
+            continue;
+        }
+        if (c === "-" || c === "*" || c === "_") {
+            if (onlySpaceSoFar) {
+                ch = c;
+                count = 1;
+                onlySpaceSoFar = false;
+            }
+            else if (c === ch)
+                count++;
+            // Two different break chars: every suffix starting at or before i now
+            // mixes them (`- - - * -` is five nested items, not a break), so stop.
+            else
+                return ok;
+        }
+        else {
+            // Any other char means no suffix starting at or before i is a break;
+            // ok is already false there, so stop.
+            return ok;
+        }
+        ok[i] = count >= 3;
+    }
+    return ok;
+}
 /** Character ranges covered by fenced code blocks (``` or ~~~), so a
  *  documentation EXAMPLE of a marker never registers as a live anchor.
  *  CommonMark-lite: a fence of N chars (≤3 leading spaces) closes only on a
  *  line of ≥N of the same char and nothing else; an unclosed fence runs to
  *  EOF; a backtick fence's info string may not itself contain a backtick.
- *  Expects LF-normalized text — see parseDocAnchors's normalization; a
- *  caller that skips it re-opens the CRLF fence-detection bug. */
+ *  The "≤3 leading spaces" is measured relative to the enclosing LIST ITEM's
+ *  content offset, so a fence indented under `1. step` (issue #331) is still a
+ *  fence and not an indented code block.
+ *
+ *  A fence hosted in a list item ends where the ITEM ends: at the first
+ *  non-blank line dedented below the item's content base. That is what the
+ *  rendered document shows — the closing ``` of a sloppily indented example
+ *  sits outside the item, so it terminates the item's fence and opens a new
+ *  top-level one — and this scanner's job is to agree with the rendering a
+ *  reader sees, not with the author's intent. In sloppy docs that differs from
+ *  a flat fence scan; the rendering is the tiebreaker.
+ *
+ *  Tabs expand to the next 4-column tab stop (not a flat 4), so `\t``` ` sits
+ *  at column 4 exactly as a renderer places it. Offsets always come from the
+ *  ORIGINAL line, never from the expanded probe.
+ *
+ *  Deliberate limits: no lazy continuations and no blockquote containers — a
+ *  `>` prefix is still read as ordinary text. With no list open the item stack
+ *  is empty, the base is 0 and behaviour is the plain CommonMark-lite one.
+ *  Expects LF-normalized text — see parseDocAnchors's normalization; a caller
+ *  that skips it re-opens the CRLF fence-detection bug. */
 function fencedRanges(text) {
+    const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
     const ranges = [];
     let open = null;
+    // Content offsets (columns) of the currently open list items, outermost first.
+    const items = [];
     let offset = 0;
+    // Whether the previous line was a paragraph-continuation line: non-blank,
+    // and not itself a container/leaf opener. Only a bullet or a `1.`/`1)` with
+    // non-empty content may interrupt such a paragraph (CommonMark), so prose
+    // like "see item\n2. the second point" stays one paragraph.
+    let inParagraph = false;
     for (const line of text.split("\n")) {
-        const m = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
-        if (m) {
-            const ch = m[1][0];
-            if (!open) {
-                if (!(ch === "`" && m[2].includes("`")))
-                    open = { ch, len: m[1].length, start: offset };
-            }
-            else if (ch === open.ch && m[1].length >= open.len && m[2].trim() === "") {
-                ranges.push([open.start, offset + line.length]);
+        // Matching-only copy: tabs advance to the next 4-column tab stop.
+        const probe = expandTabs(line);
+        const indent = probe.length - probe.replace(/^ +/, "").length;
+        const blank = probe.trim() === "";
+        if (open) {
+            if (!blank && indent < open.base) {
+                // The list item holding the fence ended, which ends the fence too.
+                ranges.push([open.start, offset - 1]);
                 open = null;
             }
+            else {
+                const m = FENCE.exec(probe.slice(Math.min(open.base, indent)));
+                if (m && m[1][0] === open.ch && m[1].length >= open.len && m[2].trim() === "") {
+                    ranges.push([open.start, offset + line.length]);
+                    open = null;
+                }
+                offset += line.length + 1;
+                continue; // the item stack is frozen while a fence is open
+            }
+        }
+        if (blank) {
+            offset += line.length + 1;
+            inParagraph = false;
+            continue; // a blank line neither opens nor closes an item here
+        }
+        // A dedent that closes an item also closes the paragraph inside it, so the
+        // line is a fresh block start: `1. one\n2. two` is two sibling items, not
+        // item one's paragraph being "interrupted" by a `2.`.
+        let popped = false;
+        while (items.length && items.at(-1) > indent) {
+            items.pop();
+            popped = true;
+        }
+        const isBreak = thematicBreakSuffixes(probe);
+        // Walk the line with an INDEX, peeling one list marker per step. Each step
+        // is O(marker) and the cheap checks are O(1), so a line costs O(length)
+        // however many markers it carries.
+        let base = items.at(-1) ?? 0;
+        let opened = false;
+        let thematic = false;
+        for (;;) {
+            // Leading spaces of this nesting level: ≤3, else it is indented content
+            // (and `    ---` is paragraph text or code, never a thematic break).
+            let i = base;
+            while (i < probe.length && probe[i] === " " && i - base < 4)
+                i++;
+            const lead = i - base;
+            if (lead > 3)
+                break;
+            if (isBreak[i]) {
+                thematic = true;
+                break;
+            } // thematic break, not a list marker
+            const c = probe[i];
+            let markerLen = 0;
+            if (c === "-" || c === "*" || c === "+")
+                markerLen = 1;
+            else if (c !== undefined && c >= "0" && c <= "9") {
+                let d = i;
+                while (d < probe.length && probe[d] >= "0" && probe[d] <= "9" && d - i < 9)
+                    d++;
+                if (probe[d] === "." || probe[d] === ")")
+                    markerLen = d - i + 1;
+            }
+            if (!markerLen)
+                break;
+            // Spaces between the marker and the item's content.
+            let s = i + markerLen;
+            while (s < probe.length && probe[s] === " ")
+                s++;
+            const gap = s - (i + markerLen);
+            const emptyItem = s >= probe.length;
+            if (!emptyItem && gap === 0)
+                break; // `-foo` / `1.foo` is not a marker
+            if (!opened && !popped && inParagraph && items.length === 0) {
+                // Interrupting a paragraph: only a bullet, or `1.`/`1)`, and never with
+                // empty content. `2. the second point` mid-prose stays paragraph text.
+                const ordinal = markerLen > 1 ? probe.slice(i, i + markerLen - 1) : "";
+                if (emptyItem || (ordinal !== "" && ordinal !== "1"))
+                    break;
+            }
+            // ≥5 spaces after the marker starts an indented code block, so the
+            // item's content begins one column after the marker instead.
+            const w = gap >= 1 && gap <= 4 ? gap : 1;
+            base = base + lead + markerLen + w;
+            items.push(base);
+            opened = true;
+            continue; // `- 1. x` nests, and "- ```js" opens a fence on the marker line
+        }
+        const m = FENCE.exec(probe.slice(base));
+        if (m) {
+            const ch = m[1][0];
+            if (!(ch === "`" && m[2].includes("`")))
+                open = { ch, len: m[1].length, start: offset, base };
         }
+        // A fence line or a thematic break ends the paragraph it follows; ordinary
+        // text (including an item's own content) continues or starts one.
+        inParagraph = !m && !thematic;
         offset += line.length + 1;
     }
     if (open)

package/dist/core/format.js

@@ -16,8 +16,13 @@ export function formatSearchHit(hit, record) {
 /** Render a StructureView as a compact orientation brief (hunch_structure). */
 export function formatStructure(v) {
     const NL = "\n";
-    if (v.kind === "none")
+    if (v.kind === "none") {
+        // A real working-tree file with zero indexed symbols is a different answer from
+        // an unknown path — never tell the user a file we just stat'd doesn't exist.
+        if (v.realFile)
+            return `"${v.target}" is a real file, but the index holds no symbols for it — nothing to outline. Run hunch index if the repo changed, or hunch_why for its recorded decisions and invariants.`;
         return `Nothing indexed matches "${v.target}" — not a known file, directory, or symbol. Run hunch index if the repo changed, or hunch_query for fuzzy search.`;
+    }
     if (v.kind === "repo") {
         const out = [`# Repo structure (from the graph — no grep needed)`];
         if (v.components.length) {

package/dist/core/glob.d.ts

@@ -13,14 +13,20 @@ export declare function pathsRelated(left: string, right: string): boolean;
  *  Dockerfile, ...) that has zero tree-sitter symbols but is still a real,
  *  known file. Derived entirely from already-loaded graph data — never the
  *  filesystem — so the answer doesn't depend on untracked working-tree state
- *  (a deleted-but-still-indexed path stays "real"; issue #299). */
+ *  (a deleted-but-still-indexed path stays "real"; issue #299). It is therefore
+ *  only HALF the "is this a real path" question: a real file with no symbols and
+ *  no covering component is invisible here, so callers OR in `isRepoFile` as a
+ *  last resort (issue #334) — `HunchStore.isKnownPath` is that composition. */
 export declare function isIndexedPath(target: string, symbolFiles: Iterable<string>, componentPaths: Iterable<readonly string[]>): boolean;
 /** Resolve symbols matching `target`, tiered: exact id > exact name > exact file >
- *  (only when `target` is NOT a path already known to the index) segment-anchored
- *  suffix. A real indexed file with zero symbols must return [] rather than fall
- *  through to the suffix tier, which would leak an unrelated same-basename file's
- *  records (issue #299) — callers compute `indexed` via `isIndexedPath` first so
- *  the "is this a real path" question is answered identically everywhere. */
+ *  (only when `target` is NOT a path already known to be real) segment-anchored
+ *  suffix. A real file with zero symbols must return [] rather than fall through
+ *  to the suffix tier, which would leak an unrelated same-basename file's records
+ *  (issues #299/#334). Callers decide what counts as "real": one that ATTRIBUTES
+ *  records silently (why(), the pre-edit hook) passes `HunchStore.isKnownPath`, the
+ *  wider graph-or-working-tree answer that also covers a file about to be created;
+ *  one that NAMES the file it resolved to (resolveNodeIds, structure()) passes the
+ *  narrower `isRepoFile`, since glob coverage alone is not existence. */
 export declare function matchSymbolsTiered<S extends {
     id: string;
     file: string;