@davesheffer/hunch 1.12.0 → 1.12.1

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/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/mcp/server.js

@@ -49,6 +49,13 @@ 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). */
+const publicHomeNote = (home, hasPrivate) => home === "public" && hasPrivate
+    ? "\nℹ Landed in the COMMITTED PUBLIC store (publishes with the repo). For sensitive/strategy content, re-record with private:true — the overlay store."
+    : "";
 // 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 +910,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);
             // 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 +987,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);
             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 +1063,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);
             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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.12.0",
+  "version": "1.12.1",
   "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.1",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.12.0",
+      "version": "1.12.1",
       "runtimeHint": "npx",
       "packageArguments": [
         {