@davesheffer/hunch 1.39.3 → 1.40.1

package/dist/core/glob.js

@@ -72,7 +72,10 @@ export function pathsRelated(left, right) {
  *  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 function isIndexedPath(target, symbolFiles, componentPaths) {
     for (const f of symbolFiles)
         if (f === target)
@@ -84,11 +87,14 @@ export function isIndexedPath(target, symbolFiles, componentPaths) {
     return false;
 }
 /** 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 function matchSymbolsTiered(target, symbols, indexed) {
     const byId = symbols.find((s) => s.id === target);
     if (byId)

package/dist/core/hookcache.d.ts

@@ -1,7 +1,14 @@
 /** Decide whether this injection should be the FULL grounding block or a delta
  *  one-liner. Records the content hash as a side effect (so the next identical
- *  call dedups). Never throws. */
-export declare function injectionMode(sessionId: string | undefined, key: string, content: string): "full" | "delta";
+ *  call dedups). Never throws.
+ *
+ *  `hashInput` lets a caller dedup on a STABLE PROJECTION of the block instead
+ *  of its presentation: some grounding is self-invalidating —
+ *  serving it writes delivery receipts, and the next call's wording moves
+ *  ("today" → "delivered today") with no record change, so hashing the rendered
+ *  text re-sends the full block forever. Callers pass the identity of the
+ *  underlying records; omitting it hashes `content`, the original contract. */
+export declare function injectionMode(sessionId: string | undefined, key: string, content: string, hashInput?: string): "full" | "delta";
 /** Forget everything injected into a session. Compaction summarizes injected
  *  grounding out of the agent's context while the dedup map still says
  *  "delivered" — so on PreCompact / SessionStart[source=compact] the map must

package/dist/core/hookcache.js

@@ -23,8 +23,15 @@ const MAX_KEYS = 300;
 const SWEEP_AGE_MS = 48 * 3600 * 1000;
 /** Decide whether this injection should be the FULL grounding block or a delta
  *  one-liner. Records the content hash as a side effect (so the next identical
- *  call dedups). Never throws. */
-export function injectionMode(sessionId, key, content) {
+ *  call dedups). Never throws.
+ *
+ *  `hashInput` lets a caller dedup on a STABLE PROJECTION of the block instead
+ *  of its presentation: some grounding is self-invalidating —
+ *  serving it writes delivery receipts, and the next call's wording moves
+ *  ("today" → "delivered today") with no record change, so hashing the rendered
+ *  text re-sends the full block forever. Callers pass the identity of the
+ *  underlying records; omitting it hashes `content`, the original contract. */
+export function injectionMode(sessionId, key, content, hashInput = content) {
     try {
         if (!sessionId || process.env.HUNCH_HOOK_DEDUP === "0")
             return "full";
@@ -32,7 +39,7 @@ export function injectionMode(sessionId, key, content) {
         mkdirSync(dir, { recursive: true });
         sweep(dir);
         const file = join(dir, `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
-        const hash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+        const hash = createHash("sha256").update(hashInput).digest("hex").slice(0, 16);
         let map;
         try {
             const raw = JSON.parse(readFileSync(file, "utf8"));

package/dist/core/paths.d.ts

@@ -27,6 +27,27 @@ export declare function realpathNorm(p: string): string;
  *  caller treats the file as outside the repo, silently dropping all context
  *  (dec_e0a36efbf5). */
 export declare function repoRelativeTarget(target: string, root: string): string;
+/** True when `target` (already repo-relative POSIX form) names a regular FILE
+ *  that really exists inside `root`. The LAST-RESORT half of the "is this a real
+ *  path" question: `isIndexedPath` answers it from graph data alone, but a real
+ *  working-tree file with zero tree-sitter symbols and no covering component
+ *  glob is invisible to it, so it fell through to the suffix tier and leaked an
+ *  unrelated same-basename file's records (issue #334). Callers consult the
+ *  index FIRST and only fall back here, so a deleted-but-still-indexed path and
+ *  a time-travel (`asOf`) query keep answering exactly as before.
+ *
+ *  Deliberately narrow: an absolute path (or a Windows drive letter) and any
+ *  target escaping `root` via ".." are rejected rather than resolved — the
+ *  caller has already run `repoRelativeTarget`, so anything still absolute is
+ *  outside the repo. A DIRECTORY is false: directory targets must keep flowing
+ *  to `structure()`'s dir tier. Any fs error (missing, EACCES, ...) → false.
+ *
+ *  Containment is checked twice: lexically, then again on the REALPATHS. `statSync`
+ *  follows symlinks, so an in-repo `link -> /outside` would otherwise make
+ *  `isRepoFile(root, "link/secret.ts")` true and turn this into a one-bit existence
+ *  oracle for paths outside the repo. A symlinked file pointing at another file
+ *  INSIDE the repo stays true. */
+export declare function isRepoFile(root: string, target: string): boolean;
 export interface HunchPaths {
     /** Repo root (where .hunch/ lives). */
     root: string;

package/dist/core/paths.js

@@ -1,7 +1,7 @@
 /** Filesystem layout for the Hunch (DESIGN.md §6 folder structure). */
 import { join } from "node:path";
 import { existsSync, realpathSync, statSync } from "node:fs";
-import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 export const HUNCH_DIR = ".hunch";
 /** Canonicalize a free-form path/target to forward-slash form (Hunch stores every
  *  path with "/" — git emits it on all OSes — so any user- or agent-supplied
@@ -56,6 +56,44 @@ export function repoRelativeTarget(target, root) {
         return t;
     return rel;
 }
+/** True when `target` (already repo-relative POSIX form) names a regular FILE
+ *  that really exists inside `root`. The LAST-RESORT half of the "is this a real
+ *  path" question: `isIndexedPath` answers it from graph data alone, but a real
+ *  working-tree file with zero tree-sitter symbols and no covering component
+ *  glob is invisible to it, so it fell through to the suffix tier and leaked an
+ *  unrelated same-basename file's records (issue #334). Callers consult the
+ *  index FIRST and only fall back here, so a deleted-but-still-indexed path and
+ *  a time-travel (`asOf`) query keep answering exactly as before.
+ *
+ *  Deliberately narrow: an absolute path (or a Windows drive letter) and any
+ *  target escaping `root` via ".." are rejected rather than resolved — the
+ *  caller has already run `repoRelativeTarget`, so anything still absolute is
+ *  outside the repo. A DIRECTORY is false: directory targets must keep flowing
+ *  to `structure()`'s dir tier. Any fs error (missing, EACCES, ...) → false.
+ *
+ *  Containment is checked twice: lexically, then again on the REALPATHS. `statSync`
+ *  follows symlinks, so an in-repo `link -> /outside` would otherwise make
+ *  `isRepoFile(root, "link/secret.ts")` true and turn this into a one-bit existence
+ *  oracle for paths outside the repo. A symlinked file pointing at another file
+ *  INSIDE the repo stays true. */
+export function isRepoFile(root, target) {
+    const t = toPosixTarget(target);
+    if (!t || isAbsolute(t) || /^[a-zA-Z]:/.test(t))
+        return false;
+    const abs = resolve(root, t);
+    const rel = relative(resolve(root), abs);
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return false;
+    try {
+        if (!statSync(abs).isFile())
+            return false;
+        const realRel = relative(realpathNorm(resolve(root)), realpathSync.native(abs));
+        return !!realRel && realRel !== ".." && !realRel.startsWith(`..${sep}`) && !isAbsolute(realRel);
+    }
+    catch {
+        return false;
+    }
+}
 export function hunchPaths(root) {
     const hunch = join(root, HUNCH_DIR);
     return {

package/dist/core/taskDelivery.js

@@ -39,15 +39,41 @@ export function taskSelectionSupplements(selection, target) {
     const parts = selection.mode === "latest"
         ? `latest ${counts.latest} (ranking off: it lost its evaluation; hunch task rank-eval)`
         : [counts.latest ? "latest" : null, counts.violation ? "problem" : null, counts.relevant ? `relevant ${counts.relevant}` : null].filter(Boolean).join(" · ");
+    // `hash_text`: the IDENTITY of the records this selection picked, for the
+    // pre-edit hook's injection dedup. Every presentation field here is volatile
+    // between two back-to-back calls with no record change — the slot label and
+    // counts move with ranking warmth, and the reason text flips ("today" →
+    // "delivered today", or to a different top reason) because serving the block
+    // writes delivery receipts the next call's ranking reads back. Hashing the
+    // rendered line therefore made the block self-invalidating and re-sent the
+    // full 3-4KB grounding.
+    //
+    // What the identity KEEPS, because each is a property of the records, the
+    // repo or the evaluation state and never of a receipt:
+    //  - header: the target, the picked set of record ids (sorted, so order is
+    //    not a change), `selection.mode` (ranker vs the "latest" fallback the
+    //    kill rule imposes — resolved from .hunch/local.json or the rank-eval
+    //    report), and `selection.more` (gated candidates minus picks; the gates
+    //    read superseded ids, anchor liveness and file/rule structure — scores
+    //    only order them, so the count does not move with warmth);
+    //  - per task: its id, its own content hash, and whether its file anchors
+    //    are still all alive (`anchorsAlive < 1` — the fact behind the "files
+    //    since changed" reason), so a picked task whose anchors die mid-session
+    //    re-sends the full block instead of leaving a silently stale line.
     return [
         {
             id: "recent-tasks", kind: "recent-tasks", priority: 415,
             text: `RECENT TASKS on ${target} — ${parts} — earlier agent work here, from graph memory (advisory history, not rules): build on what was verified instead of redoing it blind.${selection.more > 0 ? ` ${selection.more} more: hunch task list ${target}.` : ""}`,
+            hash_text: `recent-tasks ${target} ${[...selection.picks.map((p) => p.ranked.record.id)].sort().join(",")} mode=${selection.mode ?? "ranked"} more=${selection.more}`,
         },
         ...selection.picks.map((p, i) => {
             const t = p.ranked.record;
             const reasons = p.ranked.reasons.slice(0, 2).join(" · ");
-            return { id: t.id, kind: "recent-task", priority: 414 - i, text: `${SLOT_LABEL[p.slot]} ${t.id} · ${t.finished_at.slice(0, 10)} · "${clip(t.title, 80)}" — ${reasons} · ${summarizeRecord(t)}` };
+            return {
+                id: t.id, kind: "recent-task", priority: 414 - i,
+                text: `${SLOT_LABEL[p.slot]} ${t.id} · ${t.finished_at.slice(0, 10)} · "${clip(t.title, 80)}" — ${reasons} · ${summarizeRecord(t)}`,
+                hash_text: `${t.id}@${t.report_hash}${p.ranked.anchorsAlive < 1 ? "!stale" : ""}`,
+            };
         }),
     ];
 }

package/dist/core/taskReportHook.d.ts

@@ -21,6 +21,25 @@ export declare function hookReportTaskId(root: string, provider: HookProvider, e
  * No raw prompt, host session identifier, or transcript is retained; a repository
  * that opts in (`taskTitles: "prompt"`) keeps only a bounded first-line title. */
 export declare function startHookReport(root: string, provider: HookProvider, event: HunchHookInput): string | null;
+/** The hook already opened the task, so the model needs no start call: the only
+ * thing start used to supply was verification_argv, and the launcher is printed
+ * inline here. Identical in substance for EVERY hook provider that reaches this
+ * function; the one variation is capability-driven, never host-named — where the
+ * host is not PROVEN to close the task it opened (HOST_CLOSES_TASK) nobody but the
+ * next prompt's settle would close it, so finish stays mandatory there. Elsewhere
+ * finish is CONDITIONAL: ~87 start/finish round trips a day mostly returned "No
+ * task-linked delivery observed", and the host's Stop hook closes the task and
+ * shows the evidence either way. FAILS OPEN (con_03a0b94b2e): if the launcher
+ * cannot be computed, fall back to asking for the start call — that path is then
+ * the only source of both the launcher and the finish instruction, so it carries
+ * its own finish sentence. */
+export declare function taskInstruction(task: {
+    task_id: string;
+    title: string;
+}, cwdLiteral: string, provider: HookProvider, launcher?: () => {
+    shell: string;
+    note?: string;
+}): string;
 /** A prompt the host generated to report a background command's completion,
  * not something the user typed. */
 export declare function isNotificationPrompt(prompt: string | undefined): boolean;

package/dist/core/taskReportHook.js

@@ -8,6 +8,7 @@ import { isCredentialFreeText } from "./types.js";
 import { aliasReportTask, continuationLinks, finishReportTask, isEmptyTaskReport, latestSessionTask, readTaskReport, recordReportRefusal, reportHash, reportPresentationEnabled, reportTaskExists, resolveReportTask, settleSessionTasks, startReportTask } from "./taskReport.js";
 import { reportSourceSnapshot } from "./taskReportEvidence.js";
 import { renderTaskReport } from "./taskReportRender.js";
+import { verificationLauncher } from "./verifyLauncher.js";
 /** The exact task identity a native host prompt maps to. */
 export function promptTaskId(root, sessionId, promptId, agentId = null, provider = "claude") {
     return `htask_${reportHash([canonicalReportRoot(root), provider, sessionId, promptId, agentId]).slice(7, 31)}`;
@@ -15,6 +16,16 @@ export function promptTaskId(root, sessionId, promptId, agentId = null, provider
 /** Hosts whose hooks deliver a native per-prompt identity (Claude Code's
  * prompt_id, Codex's turn_id). Others get no task from a hook. */
 const NATIVE_PROMPT_HOSTS = new Set(["claude", "codex"]);
+/** Hosts PROVEN to close a task they opened, so its evidence is shown without
+ * the agent's cooperation and the finish call may be made conditional. A host
+ * belongs here only when BOTH hold: (1) `hunch init` wires its stop event, and
+ * (2) its stop payload carries the same native prompt identity the task was
+ * opened under, so `closeHookTask` actually resolves that task and closes it.
+ * (2) is what excludes a host with a stop hook but no native identity: outside
+ * NATIVE_PROMPT_HOSTS `nativeHookCwd` returns null on Stop, so nothing is
+ * closed and a skipped finish would leak an open task. Everywhere else finish
+ * stays mandatory. Adding a host requires proving both, never its name. */
+const HOST_CLOSES_TASK = new Set(["claude", "codex"]);
 const NATIVE_TASK_TITLE = "Assistant task";
 const GENERIC_TASK_TITLES = new Set(["Assistant task", "Claude task"]);
 const TASK_TITLE_MAX = 72;
@@ -133,7 +144,7 @@ export function startHookReport(root, provider, event) {
             // this prompt's Stop and hook observations report to that task.
             if (previous && previous.task_id !== id && isNotificationPrompt(event.prompt) && previous.closed_by !== "agent") {
                 aliasReportTask(root, id, previous.task_id);
-                return taskInstruction(previous, cwdLiteral);
+                return taskInstruction(previous, cwdLiteral, provider);
             }
             const continued = previous && previous.task_id !== id ? continuationLinks(previous) : null;
             if (continued)
@@ -154,10 +165,35 @@ export function startHookReport(root, provider, event) {
             throw error;
         task = existing;
     }
-    return taskInstruction(task, cwdLiteral);
+    return taskInstruction(task, cwdLiteral, provider);
 }
-function taskInstruction(task, cwdLiteral) {
-    return `Hunch has opened this prompt's report: ${task.task_id}. Reuse this exact ID for this prompt. Call hunch_task(action: "start", task_id: "${task.task_id}", title: ${JSON.stringify(task.title)}, cwd: ${cwdLiteral}) to obtain verification_argv; do not create another report. Pass this task_id and cwd: ${cwdLiteral} to hunch_context and decision/correction/finding captures, and pass the same cwd when finishing with hunch_task before responding. A host Stop notice will show the evidence even if no task-linked memory was observed.`;
+/** The hook already opened the task, so the model needs no start call: the only
+ * thing start used to supply was verification_argv, and the launcher is printed
+ * inline here. Identical in substance for EVERY hook provider that reaches this
+ * function; the one variation is capability-driven, never host-named — where the
+ * host is not PROVEN to close the task it opened (HOST_CLOSES_TASK) nobody but the
+ * next prompt's settle would close it, so finish stays mandatory there. Elsewhere
+ * finish is CONDITIONAL: ~87 start/finish round trips a day mostly returned "No
+ * task-linked delivery observed", and the host's Stop hook closes the task and
+ * shows the evidence either way. FAILS OPEN (con_03a0b94b2e): if the launcher
+ * cannot be computed, fall back to asking for the start call — that path is then
+ * the only source of both the launcher and the finish instruction, so it carries
+ * its own finish sentence. */
+export function taskInstruction(task, cwdLiteral, provider, launcher = verificationLauncher) {
+    const head = `Hunch has already opened this prompt's report: ${task.task_id}. Reuse this exact ID; never open another report. Pass this task_id and cwd: ${cwdLiteral} to hunch_context and decision/correction/finding captures.`;
+    let verify;
+    try {
+        const l = launcher();
+        verify = ` Never call hunch_task start for it. For checks, run: ${l.shell} task verify ${task.task_id} -- <command> [arguments]${l.note ?? ""}. Default budget 15 min; add --timeout <seconds> before -- for longer suites.`;
+    }
+    catch {
+        return `${head} Call hunch_task(action: "start", task_id: "${task.task_id}", title: ${JSON.stringify(task.title)}, cwd: ${cwdLiteral}) to obtain verification_argv, and finish with hunch_task(action: "finish", task_id, cwd) before responding and show its card.`;
+    }
+    const used = `this task used Hunch (a hunch_* call on this ID, a task verify check, Hunch hook context you acted on, or an application to claim)`;
+    const finish = HOST_CLOSES_TASK.has(provider)
+        ? ` ONLY if ${used}, call hunch_task(action: "finish", task_id, cwd) before responding and show its card; otherwise skip it — this host's stop hook closes the task and shows the evidence.`
+        : ` No stop hook closes this task, so finish it yourself whether or not ${used}: call hunch_task(action: "finish", task_id, cwd) before responding and show its card.`;
+    return `${head}${verify}${finish}`;
 }
 /** The session key a hook event maps to: a hash of (root, provider, session,
  * agent), never the identifier itself. Null without a host session. */

package/dist/core/taskReportRender.d.ts

@@ -1,5 +1,8 @@
 import { type LessonHistory, type TaskReport } from "./taskReport.js";
 export declare function writeTaskReportHtml(root: string, taskId: string, publicOnly?: boolean): string;
+/** Delivered lessons are named on the card up to this many; beyond it the
+ * count of the rest is stated, never a silent cut. */
+export declare const CARD_RECALLED_LIMIT = 8;
 /** One short line for the first time a lesson reaches a task; null when every
  * delivered revision was already seen in this task. Never a banner per delivery. */
 export declare function renderRecalledLine(fresh: readonly {

package/dist/core/taskReportRender.js

@@ -21,8 +21,15 @@ export function writeTaskReportHtml(root, taskId, publicOnly = false) {
     writeFileAtomic(file, publicOnly ? renderPublicTaskReportHtml(publicTaskReport(root, taskId)) : renderTaskReportHtml(report, undefined, histories));
     return file;
 }
+/** Card text is copied verbatim into an agent's final response, so every
+ * field is shown whole: a title cut mid-word with an ellipsis reads as a
+ * truncated tool result and the agent refuses to reproduce the card. Every
+ * rendered field is schema-bounded (task title and check label ≤ 200
+ * characters, record titles ≤ 500), so whole never means unbounded. */
 function plain(value) { return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").replace(/\s+/g, " ").trim(); }
-function clip(value, size = 66) { const chars = [...plain(value)]; return chars.length > size ? chars.slice(0, size - 1).join("") + "…" : chars.join(""); }
+/** Delivered lessons are named on the card up to this many; beyond it the
+ * count of the rest is stated, never a silent cut. */
+export const CARD_RECALLED_LIMIT = 8;
 function uniqueRecords(report) {
     return [...new Map(report.deliveries.flatMap(d => d.records).map(r => [`${r.kind}:${r.record_id}:${r.content_hash}`, r])).values()];
 }
@@ -42,41 +49,44 @@ export function renderRecalledLine(fresh) {
     if (!fresh.length)
         return null;
     const rest = fresh.length - 1;
-    return `Hunch recalled: ${clip(fresh[0].title, 90)}${rest ? ` (+${rest} more lesson${rest === 1 ? "" : "s"})` : ""}`;
+    return `Hunch recalled: ${plain(fresh[0].title)}${rest ? ` (+${rest} more lesson${rest === 1 ? "" : "s"})` : ""}`;
 }
 export function renderTaskReport(report) {
     const records = uniqueRecords(report);
-    const lines = [`Hunch · ${clip(report.task.title)}`, `Task ${report.task.task_id} · ${report.task.state}`];
+    const lines = [`Hunch · ${plain(report.task.title)}`, `Task ${report.task.task_id} · ${report.task.state}`];
     if (!report.deliveries.length)
         lines.push("No task-linked delivery observed; connection/use is unverified.");
     else if (!records.length)
         lines.push(report.coverage === "no-relevant-memory" ? "No relevant memory returned for this task." : "Memory delivered; exact record snapshots unavailable.");
     else {
-        lines.push(`Recalled  ${clip(records[0].title, 65)}`);
-        if (records.length > 1)
-            lines.push(`          ${records.length - 1} more lesson(s) in the evidence view`);
+        const named = records.slice(0, CARD_RECALLED_LIMIT);
+        lines.push(`Recalled  ${plain(named[0].title)}`);
+        for (const record of named.slice(1))
+            lines.push(`          ${plain(record.title)}`);
+        if (records.length > named.length)
+            lines.push(`          ${records.length - named.length} more lesson(s) in the evidence view`);
     }
     const standing = ruleStanding(report);
     const violated = standing.find(r => r.outcome === "violated");
     const held = standing.find(r => r.outcome === "satisfied" && r.current);
     if (report.claims.length) {
         const claim = report.claims.find(c => c.supported_by) ?? report.claims[0];
-        lines.push(`Applied   ${clip(claim.action, 42)} · ${claim.supported_by ? "rule-supported" : "agent-reported"}`);
+        lines.push(`Applied   ${plain(claim.action)} · ${claim.supported_by ? "rule-supported" : "agent-reported"}`);
     }
     else if (held)
-        lines.push(`Conformed ${clip(recordTitle(report, held), 34)} · rule held on ${held.files.length} changed file(s)`);
+        lines.push(`Conformed ${plain(recordTitle(report, held))} · rule held on ${held.files.length} changed file(s)`);
     else if (records.length)
         lines.push("Impact    Memory delivered; contribution unverified.");
     if (violated)
-        lines.push(`Violated  ${clip(recordTitle(report, violated), 34)} · rule broken on changed files`);
+        lines.push(`Violated  ${plain(recordTitle(report, violated))} · rule broken on changed files`);
     if (report.saves.length)
-        lines.push(`Saved     ${clip(report.saves[0].record.title, 38)} · ${report.saves[0].durability}`);
+        lines.push(`Saved     ${plain(report.saves[0].record.title)} · ${report.saves[0].durability}`);
     if (report.refusals.length)
-        lines.push(`Guarded   Denial emitted · ${clip(report.refusals[0].record_id, 40)}`);
+        lines.push(`Guarded   Denial emitted · ${plain(report.refusals[0].record_id)}`);
     const check = report.checks.at(-1);
     if (check) {
         const state = check.cancelled ? "cancelled" : check.timed_out ? "timed out" : check.exit_code === 0 ? "passed" : "failed";
-        lines.push(`Checked   ${clip(check.label, 28)} · ${state}${check.current ? " · current source snapshot" : " · current source unverified"}`);
+        lines.push(`Checked   ${plain(check.label)} · ${state}${check.current ? " · current source snapshot" : " · current source unverified"}`);
     }
     else
         lines.push("Checked   No independent command result recorded.");

package/dist/core/verifyLauncher.d.ts

@@ -0,0 +1,21 @@
+/** Structured argv is authoritative; the shell hint uses literal quoting, and
+ * `note` disambiguates it where one platform has two incompatible shells. */
+export declare function verificationLauncher(): {
+    argv: string[];
+    shell: string;
+    note: string;
+};
+/** `metaUrl` is the module running (a `.ts` source checkout needs the tsx
+ * loader; a published `.js` build needs nothing) and `resolve` is that
+ * module's `import.meta.resolve`. Callers in sibling directories (src/core,
+ * src/mcp) resolve the same `../cli/index.{ts|js}`, but each must pass ITS OWN
+ * import.meta so the dev/published discrimination stays honest. The loader is
+ * resolved ONLY on the source path: `import.meta.resolve` throws for a package
+ * that is not installed, and `tsx` is a devDependency absent from every
+ * published install (#261). `platform` defaults to the running one and exists so
+ * the Windows quoting branch is testable from any machine. */
+export declare function verificationLauncherFor(metaUrl: string, resolve: (specifier: string) => string, platform?: NodeJS.Platform): {
+    argv: string[];
+    shell: string;
+    note: string;
+};

package/dist/core/verifyLauncher.js

@@ -0,0 +1,37 @@
+/** The launcher that runs `hunch task verify` from THIS installation, not a
+ * potentially stale global binary. Core, not mcp: the prompt hook prints the
+ * command inline (so the model needs no hunch_task start call just to learn it)
+ * and a hook must never pull in the MCP SDK. */
+import { fileURLToPath, pathToFileURL } from "node:url";
+/** Structured argv is authoritative; the shell hint uses literal quoting, and
+ * `note` disambiguates it where one platform has two incompatible shells. */
+export function verificationLauncher() {
+    return verificationLauncherFor(import.meta.url, (specifier) => import.meta.resolve(specifier));
+}
+/** `metaUrl` is the module running (a `.ts` source checkout needs the tsx
+ * loader; a published `.js` build needs nothing) and `resolve` is that
+ * module's `import.meta.resolve`. Callers in sibling directories (src/core,
+ * src/mcp) resolve the same `../cli/index.{ts|js}`, but each must pass ITS OWN
+ * import.meta so the dev/published discrimination stays honest. The loader is
+ * resolved ONLY on the source path: `import.meta.resolve` throws for a package
+ * that is not installed, and `tsx` is a devDependency absent from every
+ * published install (#261). `platform` defaults to the running one and exists so
+ * the Windows quoting branch is testable from any machine. */
+export function verificationLauncherFor(metaUrl, resolve, platform = process.platform) {
+    const dev = metaUrl.endsWith(".ts");
+    const entry = fileURLToPath(new URL(`../cli/index.${dev ? "ts" : "js"}`, metaUrl));
+    // `--import` takes a URL. Converting the resolved loader to a path made Node on
+    // Windows reject it ("Received protocol 'c:'"), so every verification launched
+    // from a source checkout there failed before running and cards showed no check.
+    const loader = dev ? resolve("tsx") : null;
+    const argv = [process.execPath, ...(loader ? ["--import", loader.startsWith("file:") ? loader : pathToFileURL(loader).href] : []), entry];
+    const win = platform === "win32";
+    const quote = (s) => win ? `'${s.replace(/'/g, "''")}'` : `'${s.replace(/'/g, "'\\''")}'`;
+    // Windows hosts run either PowerShell or a POSIX shell (Git Bash), and the
+    // call operator that PowerShell needs is a syntax error in the other. The hint
+    // is quoted for PowerShell and says how to use it in the other; the structured
+    // argv stays the unambiguous form.
+    const note = win ? ` (PowerShell form; in a POSIX shell such as Git Bash drop the leading "& ")` : "";
+    return { argv, shell: `${win ? "& " : ""}${argv.map(quote).join(" ")}`, note };
+}
+//# sourceMappingURL=verifyLauncher.js.map

package/dist/extractors/indexer.d.ts

@@ -46,6 +46,11 @@ export interface IndexRepoOptions {
  * false satisfied receipt. Call this after scanRepo when the consumer cannot
  * represent partial-graph uncertainty directly. */
 export declare function assertCompleteRepoScan(scan: RepoScan): void;
+/** A whole-language failure can be a broken grammar, not a set of bad files.
+ * Refuse the entire publication so cross-language edges and curated components
+ * remain consistent with the previous symbols. Read-only scans retain coverage
+ * and issues for diagnostics; a valid empty scan is still publishable. */
+export declare function assertNoTotalParseFailure(scan: RepoScan): void;
 /** Derive the current repository graph without writing JSON or rebuilding SQLite.
  * Read-only gates use this so checking changed code can never rewrite or publish
  * the durable graph merely by inspecting it. Existing public graph records remain

package/dist/extractors/indexer.js

@@ -11,8 +11,9 @@
 import { readFileSync } from "node:fs";
 import { dirname, join, posix } from "node:path";
 import { parseSource, attributeCalls, attributeRelations, MAX_BODY_TEXT_CHARS } from "./parse.js";
+import { isParserLoadError } from "./nativeTreeSitter.js";
 import { extractHelmDirectives } from "./helm.js";
-import { extractK8sManifest } from "./k8sManifest.js";
+import { extractK8sManifest, namespacesCompatible } from "./k8sManifest.js";
 import { symbolId, componentId, edgeId, sha1 } from "../core/ids.js";
 import { externalImportNodeId, externalPackage } from "../core/externalImports.js";
 import { resolveRelativeImport } from "../core/relativeImports.js";
@@ -34,6 +35,20 @@ export function assertCompleteRepoScan(scan) {
     const more = scan.issues.length > 5 ? ` (+${scan.issues.length - 5} more)` : "";
     throw new Error(`incomplete semantic source scan rejected ${scan.issues.length} file(s): ${sample}${more}`);
 }
+/** A whole-language failure can be a broken grammar, not a set of bad files.
+ * Refuse the entire publication so cross-language edges and curated components
+ * remain consistent with the previous symbols. Read-only scans retain coverage
+ * and issues for diagnostics; a valid empty scan is still publishable. */
+export function assertNoTotalParseFailure(scan) {
+    const failed = scan.result.coverage.filter((item) => item.eligible > 0 && item.reasons.parse_failed === item.eligible);
+    if (!failed.length)
+        return;
+    const details = failed.map((item) => {
+        const first = scan.issues.find((issue) => issue.code === "parse_failed" && languageFor(issue.path)?.id === item.language);
+        return `${item.language}: all ${item.eligible} eligible file(s) failed to parse; ${first?.detail ?? "unknown parse failure"}`;
+    });
+    throw new Error(`index refused — ${details.join("; ")}. Previous graph preserved.`);
+}
 /** Derive the current repository graph without writing JSON or rebuilding SQLite.
  * Read-only gates use this so checking changed code can never rewrite or publish
  * the durable graph merely by inspecting it. Existing public graph records remain
@@ -101,6 +116,12 @@ export function scanRepo(store, root, opts = {}) {
     const perFileCalls = [];
     const perFileImports = [];
     const perFileRelations = [];
+    // `namespace` on all four: a Kubernetes reference only resolves WITHIN a
+    // namespace, so a same-named resource in a different one is a different
+    // resource (issue #297). null means UNKNOWN (absent/templated/empty), which
+    // matches anything -- see namespacesCompatible. All four are in-memory
+    // resolution scratch, never persisted: the edges they produce keep their
+    // existing shape.
     const k8sResourceIndex = [];
     const k8sReferenceCandidates = [];
     const k8sSelectors = [];
@@ -143,11 +164,20 @@ export function scanRepo(store, root, opts = {}) {
         // one bad/oversized file must never abort the whole index run
         let parsed;
         try {
-            parsed = parseSource(rel, src);
+            parsed = parseSource(rel, src, { throwOnParseError: true });
         }
-        catch {
+        catch (error) {
+            // …but a dead PARSER is not a bad file. The native addons load on first
+            // parse, so a broken load (unwritable TMPDIR, missing prebuild, an addon
+            // preloaded past the isolation guard) surfaces here and would mark every
+            // file parse_failed, after which indexRepo replaces symbols/edges/
+            // components with empty arrays and exits 0 — the whole graph silently
+            // wiped. Rethrow so the scan dies before its first store write, the way
+            // the import-time load did.
+            if (isParserLoadError(error))
+                throw error;
             skipped++;
-            issues.push({ path: rel, code: "parse_failed", detail: `${rel} could not be parsed` });
+            issues.push({ path: rel, code: "parse_failed", detail: `${rel} could not be parsed: ${error instanceof Error ? error.message : String(error)}` });
             noteSkip(rel, "parse_failed");
             continue;
         }
@@ -248,17 +278,18 @@ export function scanRepo(store, root, opts = {}) {
             if (!fromId)
                 continue;
             const scope = chartRoot ?? rel;
-            k8sResourceIndex.push({ symbolId: fromId, scope, kind: doc.resource.kind, nameKey: nameKeyText(doc.resource.name) });
+            const namespace = doc.resource.namespace;
+            k8sResourceIndex.push({ symbolId: fromId, scope, kind: doc.resource.kind, nameKey: nameKeyText(doc.resource.name), namespace });
             for (const ref of doc.references) {
                 k8sReferenceCandidates.push({
-                    fromSymbolId: fromId, scope, refKind: ref.refKind, nameKey: nameKeyText(ref.name),
+                    fromSymbolId: fromId, scope, refKind: ref.refKind, nameKey: nameKeyText(ref.name), namespace: ref.namespace,
                     reason: `${doc.resource.kind}/${displayNameText(doc.resource.name)} references ${ref.refKind}/${displayNameText(ref.name)}`,
                 });
             }
             if (doc.selector)
-                k8sSelectors.push({ symbolId: fromId, scope, selector: doc.selector });
+                k8sSelectors.push({ symbolId: fromId, scope, namespace, selector: doc.selector });
             if (doc.labels)
-                k8sWorkloadLabels.push({ symbolId: fromId, scope, labels: doc.labels });
+                k8sWorkloadLabels.push({ symbolId: fromId, scope, namespace, labels: doc.labels });
         }
         fileSymbols.set(rel, idsInFile);
         fileSymbolIndexId.set(rel, symbolIndexId);
@@ -359,16 +390,24 @@ export function scanRepo(store, root, opts = {}) {
     // only, with no concept of Kubernetes kind -- a ConfigMap and a Secret that
     // happen to share a name would incorrectly conflate. Same ambiguity contract
     // as resolveName() though: 0 matches or 2+ matches -> no edge, never guess.
+    //
+    // Namespace is a FILTER applied to the candidate list, not part of the key
+    // (issue #297): an unknown namespace on either side must still match, which
+    // a key can't express. Filtering before the uniqueness check -- rather than
+    // after picking a single candidate -- is what makes "ref in a, candidates in
+    // a and b" resolve to a instead of declining as ambiguous, while "ref in a,
+    // candidates in a and unknown" correctly stays ambiguous.
     const kindNameIndex = new Map();
     for (const r of k8sResourceIndex) {
         const key = `${r.scope}:${r.kind}:${r.nameKey}`;
-        pushInto(kindNameIndex, key, r.symbolId);
+        pushInto(kindNameIndex, key, r);
     }
     for (const ref of k8sReferenceCandidates) {
-        const candidates = kindNameIndex.get(`${ref.scope}:${ref.refKind}:${ref.nameKey}`) ?? [];
+        const byName = kindNameIndex.get(`${ref.scope}:${ref.refKind}:${ref.nameKey}`) ?? [];
+        const candidates = byName.filter((c) => namespacesCompatible(ref.namespace, c.namespace));
         if (candidates.length !== 1)
             continue; // 0 or 2+ -> ambiguous or absent, don't guess
-        const toId = candidates[0];
+        const toId = candidates[0].symbolId;
         if (toId === ref.fromSymbolId)
             continue;
         addEdge({
@@ -410,6 +449,11 @@ export function scanRepo(store, root, opts = {}) {
                 // ids can never collide today.
                 if (svc.symbolId === wl.symbolId)
                     continue;
+                // A Service only ever selects pods in its OWN namespace -- a
+                // label-identical workload next door is a different workload (issue
+                // #297). Unknown on either side still matches, same rule as Phase 1.
+                if (!namespacesCompatible(svc.namespace, wl.namespace))
+                    continue;
                 const isSubset = Object.entries(svc.selector).every(([k, v]) => wl.labels[k] === v);
                 if (!isSubset)
                     continue;
@@ -589,6 +633,7 @@ export function indexRepo(store, root, opts = {}) {
         ? { kind: "commit", ref: "HEAD" }
         : opts.source;
     const scan = scanRepo(store, root, { churn: opts.churn, source });
+    assertNoTotalParseFailure(scan);
     if (opts.requireComplete)
         assertCompleteRepoScan(scan);
     store.json.replaceAll("symbols", scan.symbols);