@davesheffer/hunch 1.12.0 → 1.12.2

package/dist/cli/index.js

@@ -58,6 +58,7 @@ import { isHumanConfirmed } from "../core/strictgate.js";
 import { appendEvent, readEvents } from "../core/events.js";
 import { computeStats, formatStats } from "../core/stats.js";
 import { injectionMode, resetSessionInjections } from "../core/hookcache.js";
+import { recordServed, servedSummary } from "../core/served.js";
 import { contextHookOutput, denyHookOutput, hookProvider, normalizeHookEvent, stopHookOutput } from "../core/agenthook.js";
 import { PIPELINE_LOOP, UNVERIFIED_NAG, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, savePipelineState, stopVerdict, } from "../core/pipeline.js";
 import { draftDuplicateOf, isAcceptedDuplicateAnchor } from "../core/dupdetect.js";
@@ -3718,6 +3719,47 @@ program
         store.close();
     }
 });
+program
+    .command("served")
+    .description("Delivery receipts: which memory records actually reached an agent, how often, and which never have")
+    .option("--json", "emit the raw ledger summary")
+    .action((opts) => {
+    const { store, root } = storeFor();
+    try {
+        const summary = servedSummary(root);
+        if (opts.json) {
+            console.log(JSON.stringify(summary, null, 2));
+            return;
+        }
+        if (!summary.total) {
+            console.log("No delivery receipts yet — they accrue as the pre-edit hook and subagent grounding fire on this machine.");
+            return;
+        }
+        console.log(`\nHunch — delivery receipts (this machine)\n`);
+        console.log(`  ${summary.total} deliveries · ${summary.distinct_records} distinct record(s) · ${summary.distinct_sessions} session(s) · ${summary.first_at?.slice(0, 10)} → ${summary.last_at?.slice(0, 10)}\n`);
+        const titleOf = (row) => {
+            if (row.kind === "decisions")
+                return store.recs("decisions").find((r) => r.id === row.record_id)?.title ?? row.record_id;
+            if (row.kind === "constraints")
+                return store.recs("constraints").find((r) => r.id === row.record_id)?.statement.slice(0, 70) ?? row.record_id;
+            return row.record_id;
+        };
+        console.log("  Most delivered:");
+        for (const row of summary.rows.slice(0, 10)) {
+            console.log(`    ${String(row.serves).padStart(4)}× (+${row.refreshes} still-current) ${row.record_id} — ${titleOf(row)}`);
+        }
+        const servedIds = new Set(summary.rows.map((r) => r.record_id));
+        const neverServed = [
+            ...store.recs("constraints").filter((c) => c.status === "active" && !servedIds.has(c.id)).map((c) => c.id),
+            ...store.recs("decisions").filter((d) => d.status === "accepted" && !d.superseded_by && !servedIds.has(d.id)).map((d) => d.id),
+        ];
+        console.log(`\n  Never delivered on this machine: ${neverServed.length} in-force record(s)${neverServed.length ? ` — compact candidates start here (${neverServed.slice(0, 5).join(", ")}${neverServed.length > 5 ? ", …" : ""})` : ""}`);
+        console.log(`  Prevented violations live in \`hunch stats\` (events ledger); receipts here are the delivery half.\n`);
+    }
+    finally {
+        store.close();
+    }
+});
 program
     .command("hook")
     .description("Agent-agnostic hook handler: normalizes Claude, VS Code, Cursor, Windsurf, and Antigravity events into Hunch context and strict policy checks. Reads hook JSON on stdin.")
@@ -3809,28 +3851,67 @@ program
             // A delegated agent starts with NONE of the parent session's grounding:
             // session orientation never fired inside it and only per-edit PreToolUse
             // follows it in — so read-only agents (Explore/Plan) could work fully
-            // blind. Give it the invariants that must survive delegation. Public
-            // store only; once per agent type per session.
+            // blind. Slice by what the agent TYPE is about to do (dec_a788cc039b):
+            // explorers get the indexed shape, planners get live decisions + what
+            // was already rejected, everyone else gets the invariant digest. Public
+            // store only; cheap reads.
             const s = new HunchStore(paths);
             try {
-                const sevRank = { blocking: 0, warning: 1, advisory: 2 };
-                const constraints = s.advisoryRecs("constraints")
-                    .filter((c) => c.status === "active")
-                    .sort((a, b) => sevRank[a.severity] - sevRank[b.severity]);
-                if (!constraints.length)
-                    return;
-                const L = [`🧠 Hunch — delegated agent grounding: ${constraints.length} invariant(s) in force in this repo.`];
-                for (const c of constraints.slice(0, 8)) {
-                    const flat = c.statement.replace(/\s+/g, " ").trim();
-                    const claim = flat.length > 140 ? `${flat.slice(0, 139).trimEnd()}…` : flat;
-                    L.push(`- [${c.severity}] ${claim}${c.scope.length ? ` (scope: ${c.scope.slice(0, 3).join(", ")})` : ""}`);
+                const clip1 = (text, max) => {
+                    const flat = text.replace(/\s+/g, " ").trim();
+                    return flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
+                };
+                const type = (evt.agent_type ?? "").toLowerCase();
+                const L = [];
+                const served = [];
+                if (/explore|search|investigat/.test(type)) {
+                    // Orient from the graph, not grep rounds: the component map IS the shape.
+                    const components = s.advisoryRecs("components").filter((c) => c.status === "active");
+                    if (!components.length)
+                        return;
+                    L.push(`🧠 Hunch — repo shape for a delegated explorer: ${components.length} component(s).`);
+                    for (const c of components.slice(0, 12)) {
+                        L.push(`- ${c.name}${c.paths.length ? ` (${c.paths.slice(0, 2).join(", ")})` : ""}${c.responsibility ? ` — ${clip1(c.responsibility, 90)}` : ""}`);
+                        served.push({ kind: "components", record_id: c.id });
+                    }
+                    if (components.length > 12)
+                        L.push(`…and ${components.length - 12} more — hunch_structure() for the full map.`);
+                    L.push("Orient: hunch_structure(target) · hunch_why(target) · hunch_context(task).");
+                }
+                else if (/plan|architect|design/.test(type)) {
+                    // A plan drafted blind re-proposes what the graph already rejected.
+                    const decisions = s.advisoryRecs("decisions")
+                        .filter((d) => d.status === "accepted")
+                        .sort((a, b) => (a.date < b.date ? 1 : -1));
+                    if (!decisions.length)
+                        return;
+                    L.push(`🧠 Hunch — live decisions for a delegated planner (${decisions.length} in force; plans must not re-propose the rejected).`);
+                    for (const d of decisions.slice(0, 6)) {
+                        L.push(`- ${d.title} (${d.id})${d.alternatives_rejected.length ? ` — rejected: ${clip1(d.alternatives_rejected[0], 80)}` : ""}`);
+                        served.push({ kind: "decisions", record_id: d.id });
+                    }
+                    L.push("Before finalizing a plan: hunch_why(target) · hunch_current_decision(topic) · hunch_check_constraints(scope).");
+                }
+                else {
+                    const sevRank = { blocking: 0, warning: 1, advisory: 2 };
+                    const constraints = s.advisoryRecs("constraints")
+                        .filter((c) => c.status === "active")
+                        .sort((a, b) => sevRank[a.severity] - sevRank[b.severity]);
+                    if (!constraints.length)
+                        return;
+                    L.push(`🧠 Hunch — delegated agent grounding: ${constraints.length} invariant(s) in force in this repo.`);
+                    for (const c of constraints.slice(0, 8)) {
+                        L.push(`- [${c.severity}] ${clip1(c.statement, 140)}${c.scope.length ? ` (scope: ${c.scope.slice(0, 3).join(", ")})` : ""}`);
+                        served.push({ kind: "constraints", record_id: c.id });
+                    }
+                    if (constraints.length > 8)
+                        L.push(`…and ${constraints.length - 8} more — hunch_check_constraints(scope) for your files.`);
+                    L.push("Before editing: hunch_check_constraints(scope) · hunch_why(target). Orient: hunch_context(task).");
                 }
-                if (constraints.length > 8)
-                    L.push(`…and ${constraints.length - 8} more — hunch_check_constraints(scope) for your files.`);
-                L.push("Before editing: hunch_check_constraints(scope) · hunch_why(target). Orient: hunch_context(task).");
                 // No dedup here: the hook event carries the PARENT session id, but each
                 // spawned agent is a fresh empty context — deduping would ground the
                 // first Explore and silently starve every later one.
+                recordServed(root, served.map((r) => ({ ...r, event: "served", target: `(subagent:${evt.agent_type ?? "any"})`, session_id: evt.session_id })));
                 emitContext(provider, "SubagentStart", L.join("\n"));
             }
             finally {
@@ -3999,10 +4080,21 @@ program
         // Identical grounding already shown this session → one-line delta instead of
         // the full 10-16KB block. Any record change re-sends the full text; the
         // strict-gate deny path above never routes through this (dec_244397d920).
+        // Delivery receipts (dec_925f4bcaad): the ledger of what actually reached
+        // an agent. A full injection is a serve; a delta one-liner attests the
+        // earlier serve is still standing. Never throws, never blocks.
+        const receipts = (event) => recordServed(root, [
+            ...ctx.constraints.map((c) => ({ event, kind: "constraints", record_id: c.id, target, session_id: evt.session_id })),
+            ...ctx.decisions.map((d) => ({ event, kind: "decisions", record_id: d.id, target, session_id: evt.session_id })),
+            ...ctx.bugs.map((b) => ({ event, kind: "bugs", record_id: b.id, target, session_id: evt.session_id })),
+            ...ctx.findings.map((f) => ({ event, kind: "findings", record_id: f.id, target, session_id: evt.session_id })),
+        ]);
         if (injectionMode(evt.session_id, `pre:${target}`, text) === "delta") {
+            receipts("refreshed");
             emitContext(provider, "PreToolUse", `Hunch grounding for ${target}: unchanged this session (${ctx.decisions.length} decision(s), ${ctx.constraints.length} invariant(s) shown earlier — still current; hunch_why("${target}") to re-expand).`);
             return;
         }
+        receipts("served");
         emitContext(provider, "PreToolUse", text);
     }
     catch {

package/dist/core/docanchors.js

@@ -28,16 +28,40 @@ function fencedRanges(text) {
         ranges.push([open.start, text.length]);
     return ranges;
 }
+/** Character ranges covered by inline code spans (`…`), same rationale as
+ *  fencedRanges: prose quoting a marker in backticks is showing an example.
+ *  CommonMark-lite: an opener run pairs with the next run of the SAME length
+ *  on the same line; unpaired runs never open a span. */
+function inlineSpanRanges(text) {
+    const ranges = [];
+    let offset = 0;
+    for (const line of text.split("\n")) {
+        let pending = null;
+        const runs = /`+/g;
+        let m;
+        while ((m = runs.exec(line))) {
+            if (!pending)
+                pending = { len: m[0].length, start: m.index };
+            else if (m[0].length === pending.len) {
+                ranges.push([offset + pending.start, offset + m.index + m[0].length - 1]);
+                pending = null;
+            }
+        }
+        offset += line.length + 1;
+    }
+    return ranges;
+}
 /** Parse every hunch:topic marker out of a markdown document. Markers inside
- *  fenced code blocks are examples, not declarations, and are skipped. */
+ *  fenced code blocks or inline code spans are examples, not declarations,
+ *  and are skipped. */
 export function parseDocAnchors(text) {
     const out = [];
-    const fences = fencedRanges(text);
+    const skip = [...fencedRanges(text), ...inlineSpanRanges(text)];
     MARKER.lastIndex = 0;
     let m;
     while ((m = MARKER.exec(text))) {
         const at = m.index;
-        if (fences.some(([s, e]) => at >= s && at <= e))
+        if (skip.some(([s, e]) => at >= s && at <= e))
             continue;
         out.push({ topic: m[1], pin: m[2] ?? null, line: text.slice(0, at).split("\n").length });
     }

package/dist/core/docscan.js

@@ -20,7 +20,11 @@ import { join, extname } from "node:path";
 import { parseDocAnchors } from "./docanchors.js";
 import { currentForTopic } from "./topics.js";
 import { compareCodeUnits } from "./canonicalOrder.js";
-export const STALE_MARKER = /\b(proposed|not yet implemented|no code yet)\b/i;
+// Self-referential status declarations only. A bare "proposed" is too loose:
+// the auto-generated grounding block in AGENTS.md legitimately DESCRIBES the
+// proposed decision status ("candidate/proposed rules") and was graded stale
+// for it — a false alarm in the machinery that polices false alarms.
+export const STALE_MARKER = /\b(?:status|state)\s*[:\-—]\s*(?:proposed|draft)\b|\bnot yet implemented\b|\bno code yet\b/i;
 export const SRC_REF = /\bsrc\/[A-Za-z0-9_\-/]+\.ts\b/g;
 const SKIP_DIRS = new Set(["node_modules", ".git", ".hunch", ".hunch-private", "dist", "vscode-extension", "site"]);
 /** Bounded walk for repo markdown (root + docs/, depth-limited; heavy/irrelevant trees skipped). */

package/dist/core/drift.js

@@ -29,6 +29,16 @@ export function computeDrift(store, root) {
     // anchor-stale. Keeps the doc≠graph gate's false-positive rate ~zero: a routine
     // narrowing supersession (successor lists fewer files) never flags files still governed.
     const liveFiles = new Set(decisions.filter(isLive).flatMap((d) => (d.related_files ?? []).map(toPosixTarget)));
+    // A related_files entry may name a DIRECTORY ("vscode-extension/"), which governs every
+    // file beneath it. Exact Set.has cannot see that, so a live directory-scoped decision
+    // failed to suppress anchor-stale for files it plainly covers — a false positive that
+    // only appeared on a public-only store, because an overlay decision happened to claim
+    // the same file by exact path and masked it locally.
+    const liveDirs = [...liveFiles].filter((f) => f.endsWith("/"));
+    const governedByLiveDecision = (file) => {
+        const p = toPosixTarget(file);
+        return liveFiles.has(p) || liveDirs.some((dir) => p.startsWith(dir));
+    };
     const premiseEnv = { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) };
     for (const d of decisions) {
         // 1. DEAD-REFERENCE — only for in-force decisions; a superseded one referencing
@@ -66,7 +76,7 @@ export function computeDrift(store, root) {
             const current = currentForTopic(decisions, d.topic);
             if (current && current.id !== d.id) {
                 for (const f of d.related_files ?? []) {
-                    if (!f || f.includes("*") || liveFiles.has(toPosixTarget(f)))
+                    if (!f || f.includes("*") || governedByLiveDecision(f))
                         continue;
                     if (!referenceExists(store, root, d.id, f))
                         continue; // missing file is history → dead-ref's job

package/dist/core/publication.js

@@ -0,0 +1,196 @@
+/** Publication safety — what a record would EXPOSE if it lands in the committed store.
+ *
+ *  Context (2026-08-09, 2026-08-11): a capture defaults to the PUBLIC store, and for a
+ *  default `hunch init` user `.hunch/*.json` is git-tracked, so an unflagged
+ *  `hunch_record_*` publishes on the next push. Two leaks reached the public tree that
+ *  way. Nothing inspected what the records SAID.
+ *
+ *  Two tiers, deliberately unequal:
+ *
+ *  - STRUCTURAL hits (machine paths, overlay paths, secret material) are
+ *    domain-independent — a Windows home directory is a leak in any repository, in any
+ *    industry. These are safe to enforce in a package other people install.
+ *  - VOCABULARY hits are corpus-tuned and ship EMPTY. A term list built from one
+ *    project's strategy prose fires on another project's ordinary engineering writing
+ *    ("revenue" is a domain noun in a billing system). A repo opts in through
+ *    `.hunch/publication.json`; the package never presumes.
+ *
+ *  Nothing here throws or blocks. `con_03a0b94b2e` holds the lifecycle hook to
+ *  fail-open, and a privacy heuristic is a smoke detector, not a proof — it earns a
+ *  visible line, not a veto. */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Structural kinds are the only ones a package may enforce for a stranger's repo. */
+const STRUCTURAL = new Set([
+    "machine-path",
+    "private-overlay-path",
+    "secret-material",
+]);
+export function isStructural(hit) {
+    return STRUCTURAL.has(hit.kind);
+}
+/** Placeholder home directories that documentation and tests use on purpose.
+ *  `/Users/me/repo` appears in src/integrations/claudeConfig.ts and its test as an
+ *  illustration; flagging those would train everyone to ignore the scanner. */
+const PLACEHOLDER_USER = /^(me|you|user|username|<[^>]+>|\$\{[^}]+\}|example|test|foo|bar)$/i;
+const MACHINE_PATH = [
+    /[A-Za-z]:[\\/]Users[\\/]([^\\/"'\s,)\]]+)/g,
+    /(?:^|[\s"'(])\/(?:Users|home)\/([^/"'\s,)\]]+)/g,
+];
+/** A path INTO the overlay (dir + file), not a bare mention of the feature. The
+ *  gitignore entry and the CLAUDE.md description name `.hunch-private` legitimately;
+ *  `.hunch-private/exp03-bank/cases-hunch-draft.json` names private CONTENT. */
+const OVERLAY_PATH = /\.hunch-private[\\/][A-Za-z0-9._-]+[\\/][A-Za-z0-9._-]+/g;
+/** Live credential shapes only. A bare `VSCE_PAT` / `AUTH_TOKEN` identifier is a
+ *  variable name, not a secret, and flagging it produced a false positive on
+ *  dec_cd37bf2d9a during tuning. */
+const SECRET_MATERIAL = /\b(?:gh[pousr]_[A-Za-z0-9]{16,}|sk-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})\b/g;
+const clip = (s, max = 120) => {
+    const flat = s.replace(/\s+/g, " ").trim();
+    return flat.length > max ? flat.slice(0, max) + "…" : flat;
+};
+/** Fields that hold human prose. Vocabulary is scanned here only — scanning raw JSON
+ *  would match ids, file paths and evidence lines and drown the signal. */
+const PROSE_KEYS = new Set([
+    "title", "context", "decision", "rationale", "statement", "rule", "observation",
+    "summary", "description", "symptom", "root_cause", "resolution", "notes",
+    "consequences", "alternatives_rejected", "steps", "why",
+]);
+function proseOf(record) {
+    const out = [];
+    if (!record || typeof record !== "object")
+        return out;
+    for (const [k, v] of Object.entries(record)) {
+        if (!PROSE_KEYS.has(k))
+            continue;
+        if (typeof v === "string")
+            out.push({ field: k, text: v });
+        else if (Array.isArray(v)) {
+            v.forEach((item, i) => {
+                if (typeof item === "string")
+                    out.push({ field: `${k}[${i}]`, text: item });
+            });
+        }
+    }
+    return out;
+}
+function readPatterns(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const raw = parsed?.vocabulary;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const pattern of raw) {
+        if (typeof pattern !== "string")
+            continue;
+        try {
+            out.push(new RegExp(pattern, "gi"));
+        }
+        catch {
+            // One bad pattern must not disable the rest of a user's list.
+        }
+    }
+    return out;
+}
+/** Read a repo's opt-in term list, merged from two layers:
+ *      .hunch/publication.json        committed, shareable patterns
+ *      .hunch/publication.local.json  gitignored, per-machine patterns
+ *
+ *  The local layer exists because the list itself can be sensitive. A rule that
+ *  catches a competitor teardown has to NAME competitors, and committing that
+ *  publishes a watchlist — the exact class of content the scanner is meant to keep
+ *  out of a public repo. Patterns that would embarrass you if read belong in the
+ *  local layer; generic ones can ship.
+ *
+ *  Absent file, malformed JSON, or an invalid pattern all degrade to "no vocabulary".
+ *  A privacy heuristic that crashes a capture is worse than one that stays quiet, and
+ *  the structural tier — the part that works for everyone — never depends on this. */
+export function loadVocabulary(hunchDir) {
+    return [
+        ...readPatterns(join(hunchDir, "publication.json")),
+        ...readPatterns(join(hunchDir, "publication.local.json")),
+    ];
+}
+/** Every string VALUE in the record, with the field path that carried it.
+ *  Deliberately not `JSON.stringify` + one regex pass: the JSON encoding doubles
+ *  backslashes, so `C:\Users\x` becomes `C:\\Users\\x` and a path rule written for
+ *  real text silently stops matching on Windows — which is exactly how the first
+ *  version of this scanner passed its macOS cases and failed its Windows ones. */
+function stringValues(node, path, seen, out) {
+    if (typeof node === "string") {
+        out.push({ field: path, text: node });
+        return;
+    }
+    if (!node || typeof node !== "object")
+        return;
+    if (seen.has(node))
+        return; // cycles are input we tolerate, never throw on
+    seen.add(node);
+    if (Array.isArray(node)) {
+        node.forEach((v, i) => stringValues(v, `${path}[${i}]`, seen, out));
+        return;
+    }
+    for (const [k, v] of Object.entries(node)) {
+        stringValues(v, path === "$" ? k : `${path}.${k}`, seen, out);
+    }
+}
+/** Pure. No IO, no throw. Returns every sensitivity signal in one record. */
+export function scanRecord(record, opts = {}) {
+    const hits = [];
+    if (!record || typeof record !== "object")
+        return hits;
+    const values = [];
+    stringValues(record, "$", new WeakSet(), values);
+    for (const { field, text } of values) {
+        for (const re of MACHINE_PATH) {
+            for (const m of text.matchAll(re)) {
+                const who = m[1] ?? "";
+                if (PLACEHOLDER_USER.test(who))
+                    continue;
+                hits.push({ kind: "machine-path", field, excerpt: clip(m[0]) });
+            }
+        }
+        for (const m of text.matchAll(OVERLAY_PATH)) {
+            hits.push({ kind: "private-overlay-path", field, excerpt: clip(m[0]) });
+        }
+        for (const m of text.matchAll(SECRET_MATERIAL)) {
+            // Never echo a live credential back into a log or a tool result.
+            hits.push({ kind: "secret-material", field, excerpt: `${m[0].slice(0, 6)}… (redacted)` });
+        }
+    }
+    const vocab = opts.vocabulary ?? [];
+    if (vocab.length) {
+        for (const { field, text } of proseOf(record)) {
+            for (const re of vocab) {
+                const probe = new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g");
+                for (const m of text.matchAll(probe)) {
+                    const at = m.index ?? 0;
+                    hits.push({
+                        kind: "market-vocabulary",
+                        field,
+                        excerpt: clip(text.slice(Math.max(0, at - 40), at + m[0].length + 40)),
+                    });
+                }
+            }
+        }
+    }
+    return hits;
+}
+/** One line naming what was matched and the exact remedy. The predecessor of this
+ *  message was a generic "for sensitive content use private:true" nudge, which was
+ *  present and ignored during both leaks — a warning that does not quote the offending
+ *  text reads as boilerplate. */
+export function publicationWarning(hits) {
+    if (!hits.length)
+        return "";
+    const shown = hits.slice(0, 3).map((h) => `${h.kind}${h.field === "$" ? "" : ` in ${h.field}`}: "${h.excerpt}"`);
+    const more = hits.length > shown.length ? ` (+${hits.length - shown.length} more)` : "";
+    return `\n⚠ PUBLICATION RISK — this record would publish with the repo:\n  ${shown.join("\n  ")}${more}\n  Re-record with private:true to route it to the overlay instead.`;
+}
+//# sourceMappingURL=publication.js.map

package/dist/core/served.js

@@ -0,0 +1,105 @@
+/**
+ * Delivery receipts (roadmap dec_925f4bcaad): a machine-local ledger of which
+ * memory records were actually DELIVERED to an agent, when, and into what.
+ *
+ * This is observed telemetry, not derived state: it cannot be reconstructed
+ * from the JSON store, so it must NOT live in the reindex-rebuilt SQLite index
+ * (con_a87360128b's derived layer is dropped and rebuilt at will). It gets its
+ * own database under .hunch-cache/ — gitignored, per-machine, append-only —
+ * the same family as hookcache's session state, not the store's.
+ *
+ * Failure posture inherits the hook's: recording a receipt must never cost a
+ * delivery. Every entry point swallows every error; a lost receipt is noise,
+ * a blocked edit is a broken product.
+ */
+import { createRequire } from "node:module";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+/** Load node:sqlite while swallowing ONLY its ExperimentalWarning — the same
+ *  discipline as src/store/db.ts: this module rides the hook into every CLI
+ *  invocation, and Hunch's stderr reaches humans, hooks, and MCP clients. A
+ *  bare top-level import printed the warning on every command and failed the
+ *  release gate's clean-stderr contract. */
+function loadSqlite() {
+    const require = createRequire(import.meta.url);
+    const realEmit = process.emitWarning.bind(process);
+    process.emitWarning = ((warning, ...rest) => {
+        if (String(warning).includes("SQLite is an experimental feature"))
+            return;
+        realEmit(warning, ...rest);
+    });
+    try {
+        return require("node:sqlite");
+    }
+    finally {
+        process.emitWarning = realEmit;
+    }
+}
+let sqlite = null;
+function openServedDb(root) {
+    sqlite ??= loadSqlite();
+    const dir = join(root, ".hunch-cache");
+    mkdirSync(dir, { recursive: true });
+    const db = new sqlite.DatabaseSync(join(dir, "served.db"));
+    db.exec(`CREATE TABLE IF NOT EXISTS served (
+    at TEXT NOT NULL,
+    session TEXT,
+    event TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    record_id TEXT NOT NULL,
+    target TEXT NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS served_record ON served (record_id);`);
+    return db;
+}
+/** Append delivery receipts. Never throws — a receipt must never cost a delivery. */
+export function recordServed(root, entries) {
+    if (!entries.length)
+        return;
+    try {
+        const db = openServedDb(root);
+        try {
+            const at = new Date().toISOString();
+            const insert = db.prepare("INSERT INTO served (at, session, event, kind, record_id, target) VALUES (?, ?, ?, ?, ?, ?)");
+            for (const entry of entries) {
+                insert.run(at, entry.session_id ?? null, entry.event, entry.kind, entry.record_id, entry.target);
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        /* unwritable cache dir / locked db — the delivery already happened; drop the receipt */
+    }
+}
+/** The ledger, aggregated per record. Never throws; an unreadable ledger reads as empty. */
+export function servedSummary(root) {
+    const empty = { total: 0, distinct_records: 0, distinct_sessions: 0, first_at: null, last_at: null, rows: [] };
+    try {
+        const db = openServedDb(root);
+        try {
+            const totals = db.prepare("SELECT COUNT(*) AS total, COUNT(DISTINCT record_id) AS records, COUNT(DISTINCT session) AS sessions, MIN(at) AS first_at, MAX(at) AS last_at FROM served").get();
+            const rows = db.prepare(`SELECT record_id, kind,
+           SUM(CASE WHEN event = 'served' THEN 1 ELSE 0 END) AS serves,
+           SUM(CASE WHEN event = 'refreshed' THEN 1 ELSE 0 END) AS refreshes,
+           MAX(at) AS last_at
+         FROM served GROUP BY record_id, kind ORDER BY serves DESC, refreshes DESC`).all();
+            return {
+                total: totals?.total ?? 0,
+                distinct_records: totals?.records ?? 0,
+                distinct_sessions: totals?.sessions ?? 0,
+                first_at: totals?.first_at ?? null,
+                last_at: totals?.last_at ?? null,
+                rows,
+            };
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return empty;
+    }
+}
+//# sourceMappingURL=served.js.map

package/dist/extractors/languages.js

@@ -6,25 +6,25 @@
  * four files.
  */
 import { loadNativeTreeSitter } from "./nativeTreeSitter.js";
-const TS_QUERY = `
-  (function_declaration name: (identifier) @fn.name) @fn.def
-  (generator_function_declaration name: (identifier) @fn.name) @fn.def
-  (method_definition name: (property_identifier) @method.name) @method.def
-  (class_declaration name: (type_identifier) @class.name) @class.def
-  (interface_declaration name: (type_identifier) @iface.name) @iface.def
-  (type_alias_declaration name: (type_identifier) @type.name) @type.def
-  (variable_declarator
-     name: (identifier) @arrow.name
-     value: [(arrow_function) (function_expression)]) @arrow.def
-  (import_statement source: (string) @import.src)
-  (call_expression function: (identifier) @call.id)
-  (call_expression function: (member_expression property: (property_identifier) @call.member))
-  ;; Construction IS a call. Without these, \`new Foo()\` produced no edge at all, so
-  ;; every class in a TS/JS repo had fan_in 0: blast radius before a constructor
-  ;; change came back empty, and a \`not-calls\` conformance predicate over a class
-  ;; could never see its own counterexample.
-  (new_expression constructor: (identifier) @call.id)
-  (new_expression constructor: (member_expression property: (property_identifier) @call.member))
+const TS_QUERY = `
+  (function_declaration name: (identifier) @fn.name) @fn.def
+  (generator_function_declaration name: (identifier) @fn.name) @fn.def
+  (method_definition name: (property_identifier) @method.name) @method.def
+  (class_declaration name: (type_identifier) @class.name) @class.def
+  (interface_declaration name: (type_identifier) @iface.name) @iface.def
+  (type_alias_declaration name: (type_identifier) @type.name) @type.def
+  (variable_declarator
+     name: (identifier) @arrow.name
+     value: [(arrow_function) (function_expression)]) @arrow.def
+  (import_statement source: (string) @import.src)
+  (call_expression function: (identifier) @call.id)
+  (call_expression function: (member_expression property: (property_identifier) @call.member))
+  ;; Construction IS a call. Without these, \`new Foo()\` produced no edge at all, so
+  ;; every class in a TS/JS repo had fan_in 0: blast radius before a constructor
+  ;; change came back empty, and a \`not-calls\` conformance predicate over a class
+  ;; could never see its own counterexample.
+  (new_expression constructor: (identifier) @call.id)
+  (new_expression constructor: (member_expression property: (property_identifier) @call.member))
 `;
 const TS_BUILTIN_METHODS = new Set([
     "map", "filter", "forEach", "reduce", "find", "findIndex", "some", "every", "includes",
@@ -54,6 +54,16 @@ const TS_SHARED = {
         "iface.name": "iface.def", "type.name": "type.def", "arrow.name": "arrow.def",
     },
     builtinMethods: TS_BUILTIN_METHODS,
+    // ES2018 relaxed template literals: an INVALID escape (`\x` with no hex, `\u`
+    // short, `\u{` unterminated) is legal inside a TAGGED template — the cooked
+    // value is undefined and the raw text survives, which is the entire point of
+    // String.raw`C:\Users\x`. tree-sitter-javascript never implemented that
+    // relaxation and is identical through 0.25.0, so it emits an ERROR node inside
+    // the template_string. In an UNTAGGED template the same escape IS a syntax
+    // error, and the grammar models the two differently — a tagged template's
+    // template_string hangs off a call_expression, an untagged one off whatever
+    // consumes the value — so requiring that pair keeps genuine errors failing.
+    toleratedErrorScopes: [{ node: "template_string", parentIs: "call_expression" }],
 };
 const TYPESCRIPT = {
     ...TS_SHARED,
@@ -71,28 +81,28 @@ const TSX = {
     grammarKey: "tsx",
     loadGrammar: () => loadNativeTreeSitter().tsx,
 };
-const PY_QUERY = `
-  (class_definition
-    name: (identifier) @class.name
-    body: (block
-      [
-        (function_definition name: (identifier) @method.name) @method.def
-        (decorated_definition definition: (function_definition name: (identifier) @method.name) @method.def)
-      ])) @class.def
-  ;; Every class, including one with no directly-nested def: dataclasses, Exception
-  ;; subclasses, Enums, TypedDicts and pydantic models are method-less by design and
-  ;; were invisible to the entire graph (no symbol, no component, no edges), so
-  ;; \`hunch why\` and blast radius came back empty for exactly the classes a refactor
-  ;; breaks. parse.ts keys pendingDefs by node id and keeps the first classification,
-  ;; so a class that ALSO matches the method-bearing pattern above is not duplicated.
-  (class_definition name: (identifier) @class.name) @class.def
-  (function_definition name: (identifier) @fn.name) @fn.def
-  (import_statement name: (dotted_name) @import.src)
-  (import_statement name: (aliased_import name: (dotted_name) @import.src))
-  (import_from_statement module_name: (dotted_name) @import.src)
-  (import_from_statement module_name: (relative_import) @import.src)
-  (call function: (identifier) @call.id)
-  (call function: (attribute attribute: (identifier) @call.member))
+const PY_QUERY = `
+  (class_definition
+    name: (identifier) @class.name
+    body: (block
+      [
+        (function_definition name: (identifier) @method.name) @method.def
+        (decorated_definition definition: (function_definition name: (identifier) @method.name) @method.def)
+      ])) @class.def
+  ;; Every class, including one with no directly-nested def: dataclasses, Exception
+  ;; subclasses, Enums, TypedDicts and pydantic models are method-less by design and
+  ;; were invisible to the entire graph (no symbol, no component, no edges), so
+  ;; \`hunch why\` and blast radius came back empty for exactly the classes a refactor
+  ;; breaks. parse.ts keys pendingDefs by node id and keeps the first classification,
+  ;; so a class that ALSO matches the method-bearing pattern above is not duplicated.
+  (class_definition name: (identifier) @class.name) @class.def
+  (function_definition name: (identifier) @fn.name) @fn.def
+  (import_statement name: (dotted_name) @import.src)
+  (import_statement name: (aliased_import name: (dotted_name) @import.src))
+  (import_from_statement module_name: (dotted_name) @import.src)
+  (import_from_statement module_name: (relative_import) @import.src)
+  (call function: (identifier) @call.id)
+  (call function: (attribute attribute: (identifier) @call.member))
 `;
 const PY_BUILTIN_METHODS = new Set([
     "get", "set", "keys", "values", "items", "pop", "popitem", "update", "setdefault", "copy", "clear",

package/dist/extractors/parse.js

@@ -82,7 +82,49 @@ export function parseSource(file, source) {
         });
     }
     symbols.sort((a, b) => a.startByte - b.startByte);
-    return { symbols, imports, calls, parseable: !tree.rootNode.hasError };
+    return { symbols, imports, calls, parseable: isParseable(tree.rootNode, spec) };
+}
+/** True when every ERROR/MISSING node in the tree sits in an ancestor shape this
+ *  language declares as a known grammar limitation (LanguageSpec.toleratedErrorScopes).
+ *
+ *  This matters because `conform` is fail-CLOSED on scan completeness: one file
+ *  reporting parseable:false rejects the WHOLE architectural-conformance scan, so a
+ *  grammar false positive takes down the gate for the entire repo. Scoping the
+ *  tolerance to a declared ancestor pair — rather than downgrading unparseable files
+ *  to a warning — keeps the completeness guarantee intact for real syntax errors.
+ *
+ *  A tolerated ERROR's children are not visited: tree-sitter reports the same span
+ *  again as a nested ERROR child, and the raw text inside a template literal cannot
+ *  contain an independent error to hide. */
+function isParseable(root, spec) {
+    if (!root.hasError)
+        return true; // covers ERROR and MISSING; no walk needed
+    const scopes = spec.toleratedErrorScopes ?? [];
+    if (scopes.length === 0)
+        return false;
+    let ok = true;
+    const visit = (node) => {
+        if (!ok)
+            return;
+        if (node.type === "ERROR" || node.isMissing) {
+            if (!inToleratedScope(node, scopes))
+                ok = false;
+            return;
+        }
+        for (let i = 0; i < node.childCount; i++)
+            visit(node.child(i));
+    };
+    visit(root);
+    return ok;
+}
+function inToleratedScope(node, scopes) {
+    for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+        for (const scope of scopes) {
+            if (ancestor.type === scope.node && ancestor.parent?.type === scope.parentIs)
+                return true;
+        }
+    }
+    return false;
 }
 /** Walk up to the nearest node whose type is a definition this language recognizes. */
 function ascendToDef(node, defNodeTypes) {

package/dist/integrations/providers.js

@@ -141,24 +141,44 @@ function writeJson(file, obj) {
     writeFileAtomic(file, JSON.stringify(obj, null, 2) + "\n");
     return file;
 }
+/** Quote one argv token only when it needs quoting. These commands are run by
+ * whatever shell the host assistant uses, which on Windows is PowerShell — and
+ * PowerShell parses a QUOTED first token as a string expression, not a command,
+ * so the old quote-everything form died before the hook ever ran:
+ *
+ *   "npx" "-y" "--package=…" "hunch" "hook" "--provider" "vscode"
+ *   → Unexpected token '"-y"' in expression or statement.
+ *
+ * A token of safe characters is a command/word in PowerShell, cmd AND POSIX sh,
+ * so quote-only-when-needed is the one shape all three accept. Backslash is not
+ * safe bare (sh eats it as an escape), so Windows paths still get quoted — those
+ * appear only in per-machine source-checkout installs, never in the published
+ * npx invocation that `hunch init` writes into tracked config. */
+function shellToken(part) {
+    return /^[A-Za-z0-9_@:=+.,/-]+$/.test(part) ? part : JSON.stringify(part);
+}
 /** Provider hook commands live in tracked config files, so use the structured
  * invocation (the same portable npx package reference as MCP) rather than a
- * machine-local CLI path. JSON quoting is accepted by POSIX shells and keeps
- * paths with spaces intact for source/dev installs. */
+ * machine-local CLI path. */
 function hookCommand(inv, provider) {
-    return [...[inv.command], ...inv.args, "hook", "--provider", provider].map((part) => JSON.stringify(part)).join(" ");
+    return [inv.command, ...inv.args, "hook", "--provider", provider].map(shellToken).join(" ");
 }
 function isHunchProviderHook(entry) {
     const e = entry && typeof entry === "object" ? entry : null;
     const command = typeof e?.command === "string" ? e.command : "";
-    // Anchored to the exact shape hookCommand() writes — JSON-quoted parts ending
-    // in "hook" "--provider" "<name>" — plus a Hunch launcher (the pinned npm
-    // package spec, or a quoted …/index.js|ts path for source installs). The old
-    // unanchored /index\.(js|ts)/ + /\bhook\b/ pair classified FOREIGN entries
-    // like `node ./hook/index.js` as ours and silently deleted them, violating
-    // the leave-every-foreign-hook-in-place contract (con_8460b6770f, issue #41).
-    return /(?:@davesheffer\/hunch|[\\/]index\.(?:js|ts)")/.test(command)
-        && /\s"hook"(?:\s+"--provider"\s+"[a-z]+")?\s*$/.test(command);
+    // Anchored to the shapes hookCommand() writes — a Hunch launcher (the pinned
+    // npm package spec, or a …/index.js|ts path for source installs) plus a tail
+    // of `hook --provider <name>`, tokens quoted or bare. The old unanchored
+    // /index\.(js|ts)/ + /\bhook\b/ pair classified FOREIGN entries like
+    // `node ./hook/index.js` as ours and silently deleted them, violating the
+    // leave-every-foreign-hook-in-place contract (con_8460b6770f, issue #41), so
+    // the bare tail must still carry --provider to match; only the LEGACY
+    // fully-quoted form (written before this quoting fix, and by hunch versions
+    // that predate --provider) may omit it, and its quotes keep it unambiguous.
+    const launcher = /@davesheffer\/hunch|[\\/]index\.(?:js|ts)(?=["\s]|$)/.test(command);
+    const legacyTail = /\s"hook"(?:\s+"--provider"\s+"[a-z]+")?\s*$/.test(command);
+    const tail = /\s"?hook"?\s+"?--provider"?\s+"?[a-z]+"?\s*$/.test(command);
+    return launcher && (legacyTail || tail);
 }
 /** Merge our command entries into a standard `{ hooks: { Event: [] } }` file.
  * We replace only old Hunch commands and leave every foreign hook in place. */

package/dist/mcp/server.js

@@ -33,6 +33,7 @@ import { HUNCH_VERSION } from "../core/version.js";
 import { assertCompleteRepoScan, indexRepo, scanRepo } from "../extractors/indexer.js";
 import { liveForTopic, historyForTopic, rejectedForTopic, captureConflicts } from "../core/topics.js";
 import { pendingEscalations, policyEscalations } from "../core/escalations.js";
+import { scanRecord, publicationWarning, loadVocabulary } from "../core/publication.js";
 import { premiseEscalations } from "../core/premises.js";
 import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken } from "../core/capturetoken.js";
 import { randomUUID } from "node:crypto";
@@ -49,6 +50,27 @@ const flushNote = (flush, home, mode) => flush === "pushed" ? ` (committed + pus
             ? " (committed to the overlay repo — push deferred: offline, no upstream, or merge conflict; the next capture or `hunch private --sync` retries)"
             : " (auto-committed to .hunch/ — rides your next push)"
         : "";
+/** When an overlay exists, a PUBLIC write deserves one visible line: a record that
+ *  lands in the committed store publishes on the next push, and an agent writing
+ *  strategy/competitive content there is a leak nobody notices until it ships
+ *  (2026-08-09: 15 roadmap records caught pre-push only by a release sweep). */
+/** Repo-local term list, read once per server process. The package ships none;
+ *  `.hunch/publication.json` is how a repo opts in (see src/core/publication.ts). */
+let vocabularyCache = null;
+const publicationVocabulary = (hunchDir) => (vocabularyCache ??= loadVocabulary(hunchDir));
+const publicHomeNote = (home, hasPrivate, record, hunchDir) => {
+    if (home !== "public")
+        return "";
+    // The generic nudge below was already present during BOTH leaks and was ignored,
+    // because a warning that cannot quote the offending text reads as boilerplate.
+    // scanRecord adds the specific line: what matched, in which field.
+    const risk = record === undefined
+        ? ""
+        : publicationWarning(scanRecord(record, { vocabulary: hunchDir ? publicationVocabulary(hunchDir) : [] }));
+    if (!hasPrivate)
+        return risk;
+    return "\nℹ Landed in the COMMITTED PUBLIC store (publishes with the repo). For sensitive/strategy content, re-record with private:true — the overlay store." + risk;
+};
 // Read-side token budgets: every tool result is injected into a Claude Code
 // session, so an uncapped list pollutes the context window. Cap each list to its
 // highest-signal head (records are pre-sorted by severity/confidence) and tell the
@@ -903,7 +925,7 @@ export function buildServerWithRootControl(initialRoot) {
             // record commits+pushes its overlay repo; a public one commits .hunch/ in THIS repo
             // (commit only — it rides the user's next push, never auto-pushing their code branch).
             const flush = flushCapture(store, hunchPaths(root).hunch, !!decision.private, `hunch: capture ${id}`, startupTeamRoute ?? undefined);
-            const flushed = flushNote(flush, home, store.mode);
+            const flushed = flushNote(flush, home, store.mode) + publicHomeNote(home, store.hasPrivate, rec, hunchPaths(root).hunch);
             // Capture-session gate (staged deprecation, §9.3): the token was consumed
             // above (it also decides the provenance tier). No token still writes
             // (non-breaking) but lands as agent_recorded with a nudge toward /capture.
@@ -980,7 +1002,7 @@ export function buildServerWithRootControl(initialRoot) {
             if (home === "public" && !store.autoCommit)
                 refreshExistingGrounding(root, store); // overlay rules never render into committed grounding
             const flush = flushCapture(store, hunchPaths(root).hunch, !!input.private, `hunch: capture ${rec.id}`, startupTeamRoute ?? undefined);
-            const flushed = flushNote(flush, home, store.mode);
+            const flushed = flushNote(flush, home, store.mode) + publicHomeNote(home, store.hasPrivate, rec, hunchPaths(root).hunch);
             const enforce = rec.severity === "blocking"
                 ? "blocks a DIRECT edit to its scope at strict firmness, and fails a PR whose diff touches that scope (CI guard); blast-radius hits and lower firmness stay advisory"
                 : "flags violating edits and PRs (advisory)";
@@ -1056,7 +1078,7 @@ export function buildServerWithRootControl(initialRoot) {
             store.putCapture("findings", rec, !!finding.private);
             store.reindex();
             const flush = flushCapture(store, hunchPaths(root).hunch, !!finding.private, `hunch: capture ${id}`, startupTeamRoute ?? undefined);
-            const flushed = flushNote(flush, home, store.mode);
+            const flushed = flushNote(flush, home, store.mode) + publicHomeNote(home, store.hasPrivate, rec, hunchPaths(root).hunch);
             const where = finding.private
                 ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
                 : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;

package/dist/synthesis/synthesize.js

@@ -201,8 +201,16 @@ export async function syncCommit(store, root, sha, opts = {}) {
         },
         date: meta.date, // the commit date
     };
-    // Route to the record's ONE home: the overlay when asked (--private) or in unified
-    // ("shared") mode; else the public store. Same contract as every other capture path.
+    // Route to the resolved home: the overlay when asked (--private / opts.home) or in
+    // unified ("shared") mode; else the public store.
+    //
+    // DELIBERATELY home-scoped, NOT putCapture. Synthesis keeps the public and private
+    // spines separate: a public failure must never reach through and rewrite a same-id
+    // private record, which putCapture's cross-home collision guard would either throw on
+    // or (via putWhereItLives) silently redirect. test/private-capture.test.ts pins that
+    // behaviour — "public post-promotion rewrite cannot overwrite the private collision".
+    // An earlier comment here claimed the "same contract as every other capture path",
+    // which read as an accidental bypass and invited exactly that wrong fix.
     if (home === "private")
         store.putPrivate("decisions", decision);
     else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.12.0",
+  "version": "1.12.2",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -52,6 +52,8 @@
     "node": ">=22.13.0"
   },
   "scripts": {
+    "version": "node tooling/sync-version-pins.mjs && git add plugin/.mcp.json server.json",
+    "sync-version-pins": "node tooling/sync-version-pins.mjs",
     "clean": "node --input-type=commonjs -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.json",
     "dev": "tsx src/cli/index.ts",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://hunch-pi.vercel.app",
-  "version": "1.12.0",
+  "version": "1.12.2",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.12.0",
+      "version": "1.12.2",
       "runtimeHint": "npx",
       "packageArguments": [
         {