@davesheffer/hunch 1.13.0 → 1.14.0

package/README.md

@@ -16,8 +16,8 @@ strict enforcement.
 **Memory is the input. The product boundary is the receipt:** relevant evidence before an edit,
 then a deterministic check of the change against the rules your team has explicitly trusted.
 
-> **New in v1.13.0:** CLI, MCP, and edit hooks now share one provenance-checked, hard-budgeted
-> delivery envelope, and local receipts record exactly what reached the agent and why.
+> **New in v1.13.1:** `hunch_context` exposes that provenance-checked, hard-budgeted delivery
+> envelope as MCP structured output and records exactly which returned items reached the client.
 
 See the public [roadmap](ROADMAP.md) for what is next and what is deliberately out of scope.
 
@@ -82,7 +82,7 @@ Git repo that every teammate can access, install the Matrix release on team mach
 have one maintainer run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.13.0
+npm i -g @davesheffer/hunch@1.13.1
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -97,7 +97,7 @@ printed by Hunch. Omit `--migrate` for a new setup.
 After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
 
 ```bash
-npm i -g @davesheffer/hunch@1.13.0
+npm i -g @davesheffer/hunch@1.13.1
 git pull
 hunch init
 hunch doctor

package/dist/cli/index.js

@@ -64,7 +64,7 @@ import { contextHookOutput, denyHookOutput, hookProvider, normalizeHookEvent, st
 import { PIPELINE_LOOP, UNVERIFIED_NAG, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, savePipelineState, stopVerdict, } from "../core/pipeline.js";
 import { draftDuplicateOf, isAcceptedDuplicateAnchor } from "../core/dupdetect.js";
 import { planAutoReview, planMutations } from "../core/autoreview.js";
-import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
+import { loadGoldenSet, evaluateRetrieval, evaluateTraversalLift } from "../eval/harness.js";
 import { loadGuardCases, evalGuards, generateGuardCases } from "../eval/guards.js";
 import { computeDrift } from "../core/drift.js";
 import { renderCompilerScorecard, scoreCompilerCaseBank } from "../constitution/scorecard.js";
@@ -1349,16 +1349,20 @@ program
     // Default is deterministic (FTS + graph, no model). --semantic only adds the
     // semantic leg when embeddings actually exist; otherwise it's still FTS + graph.
     const embedder = opts.semantic ? await selectEmbedder() : undefined;
-    const lift = await evaluateGraphLift(store, cases, { k, embedder, kind: opts.kind });
+    const evalOpts = { k, embedder, kind: opts.kind };
+    const off = await evaluateRetrieval(store, cases, { ...evalOpts, graphWeight: 0 });
+    const traversal = await evaluateTraversalLift(store, cases, evalOpts);
     const pct = (x) => `${(x * 100).toFixed(1)}%`;
     const dpt = (x) => `${x >= 0 ? "+" : ""}${(x * 100).toFixed(1)}pt`;
     const dnum = (x) => `${x >= 0 ? "+" : ""}${x.toFixed(3)}`;
     console.log(`Eval over ${cases.length} case(s), k=${k}${opts.semantic ? " (semantic + graph + FTS)" : " (FTS + graph)"}\n`);
     console.log(`                Recall@${k}    MRR      hit-rate`);
-    console.log(`  graph OFF     ${pct(lift.off.recallAtK).padStart(7)}    ${lift.off.mrr.toFixed(3)}    ${pct(lift.off.hitRate)}`);
-    console.log(`  graph ON      ${pct(lift.on.recallAtK).padStart(7)}    ${lift.on.mrr.toFixed(3)}    ${pct(lift.on.hitRate)}`);
-    console.log(`  graph LIFT    ${dpt(lift.recallDelta).padStart(7)}    ${dnum(lift.mrrDelta)}`);
-    const misses = lift.on.perCase.filter((c) => c.found === 0);
+    console.log(`  graph OFF     ${pct(off.recallAtK).padStart(7)}    ${off.mrr.toFixed(3)}    ${pct(off.hitRate)}`);
+    console.log(`  graph 1-HOP   ${pct(traversal.oneHop.recallAtK).padStart(7)}    ${traversal.oneHop.mrr.toFixed(3)}    ${pct(traversal.oneHop.hitRate)}`);
+    console.log(`  graph BOUNDED ${pct(traversal.bounded.recallAtK).padStart(7)}    ${traversal.bounded.mrr.toFixed(3)}    ${pct(traversal.bounded.hitRate)}`);
+    console.log(`  graph LIFT    ${dpt(traversal.bounded.recallAtK - off.recallAtK).padStart(7)}    ${dnum(traversal.bounded.mrr - off.mrr)}`);
+    console.log(`  depth LIFT    ${dpt(traversal.recallDelta).padStart(7)}    ${dnum(traversal.mrrDelta)}`);
+    const misses = traversal.bounded.perCase.filter((c) => c.found === 0);
     if (misses.length) {
         console.log(`\n  ${misses.length} case(s) with no expected hit — curate or tune:`);
         for (const m of misses.slice(0, 10))

package/dist/eval/harness.js

@@ -8,7 +8,13 @@ export async function evaluateRetrieval(store, cases, opts = {}) {
         // buries terse records before any filter.
         const hits = opts.kind
             ? await store.searchScoped(c.query, opts.kind, k, { embedder: opts.embedder })
-            : await store.hybridSearch(c.query, k, { embedder: opts.embedder, graphWeight: opts.graphWeight });
+            : await store.hybridSearch(c.query, k, {
+                embedder: opts.embedder,
+                graphWeight: opts.graphWeight,
+                graphDepth: opts.graphDepth,
+                graphNodeCap: opts.graphNodeCap,
+                graphTokenCap: opts.graphTokenCap,
+            });
         const top = hits.slice(0, k).map((h) => h.ref);
         const expected = new Set(c.expected);
         let found = 0;
@@ -46,6 +52,17 @@ export async function evaluateGraphLift(store, cases, opts = {}) {
     const on = await evaluateRetrieval(store, cases, opts);
     return { off, on, recallDelta: on.recallAtK - off.recallAtK, mrrDelta: on.mrr - off.mrr };
 }
+/** Compare the historical 1-hop graph with the shipped bounded traversal. */
+export async function evaluateTraversalLift(store, cases, opts = {}) {
+    const oneHop = await evaluateRetrieval(store, cases, { ...opts, graphDepth: 1 });
+    const bounded = await evaluateRetrieval(store, cases, opts);
+    return {
+        oneHop,
+        bounded,
+        recallDelta: bounded.recallAtK - oneHop.recallAtK,
+        mrrDelta: bounded.mrr - oneHop.mrr,
+    };
+}
 /** Parse + validate a golden-set JSON string (array of {query, expected[]}). */
 export function loadGoldenSet(raw) {
     const data = JSON.parse(raw);

package/dist/integrations/claudemd.js

@@ -24,6 +24,7 @@ export function stripManagedSection(text) {
 export function renderHunchSection(store, root) {
     const constraints = store.json
         .loadAll("constraints")
+        .filter((c) => c.status === "active" && !c.valid_to)
         .sort((a, b) => sev(b.severity) - sev(a.severity))
         .slice(0, 8);
     const counts = {

package/dist/mcp/server.js

@@ -18,10 +18,12 @@ import { decisionId, findingId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
 import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
-import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, workingFiles, workingDiff, pullHunchStatus, sameRemoteUrl } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, workingFiles, workingDiff, pullHunchStatus, sameRemoteUrl, currentBranch } from "../extractors/git.js";
 import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, overlayMatchesTeamRemote, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
-import { formatContext, formatStructure } from "../core/format.js";
+import { formatStructure } from "../core/format.js";
+import { buildDeliveryEnvelope } from "../core/delivery.js";
+import { recordServed } from "../core/served.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
 import { ConstitutionService, policyEvaluationEnvelope } from "../constitution/service.js";
@@ -41,6 +43,23 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const err = (text) => ({ content: [{ type: "text", text }], isError: true });
+/** Shared by every auto-committing write tool (issue #20): the MCP `roots` protocol
+ *  cannot see an agent-driven `cd`/EnterWorktree, so a stdio server's cached root
+ *  never moves on its own — this is the client-agnostic fallback, resolved fresh on
+ *  every call by the generic tool wrapper below (see extractCwdHint). */
+const cwdHintField = z.string().optional().describe("Your ACTUAL current working directory for THIS call. Pass it whenever it differs from where this MCP " +
+    "session started — most commonly after entering a git worktree (EnterWorktree) or `cd`-ing to a different " +
+    "checkout — so the write commits to that repo/branch instead of silently landing on the server's original " +
+    "root. Omit only when you are still in the session's starting directory.");
+/** Pull `cwd` out of a tool call's already-parsed input without assuming any one
+ *  tool's exact input shape — every write tool spreads the same cwdHintField in,
+ *  but the wrapper below runs for every tool, read or write. */
+function extractCwdHint(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const cwd = input.cwd;
+    return typeof cwd === "string" && cwd.trim() ? cwd : undefined;
+}
 /** Honest auto-commit suffix: reports only what flushCapture ACTUALLY did. A skipped
  *  commit (backstop/lock/nothing staged) says nothing — the record is on disk and the
  *  next flush sweeps it up; claiming "auto-committed" there would be a lie. */
@@ -71,6 +90,21 @@ const publicHomeNote = (home, hasPrivate, record, hunchDir) => {
         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;
 };
+/** Self-diagnosing destination report (issue #17/#20): the exact failure mode this
+ *  guards against is silent — a capture landing in the wrong repo/branch with no
+ *  sign of it short of a manual `git log` audit. Every auto-committing write tool
+ *  appends this so the destination is always visible in the response, whether or
+ *  not a cwd hint was involved in choosing it. */
+const destinationNote = (destRoot) => {
+    const branch = currentBranch(destRoot);
+    return ` [captured${branch ? ` on branch ${branch}` : ""} in ${destRoot}]`;
+};
+/** Where a capture keyed to `home` actually lands: the private overlay directory when
+ *  one is configured, else the public repo root. Centralizes the branch used at every
+ *  destination-reporting call site below — `hunch_policy_upgrade_correction` once
+ *  diverged from this (computing its own `artifactHome` but reporting the public root
+ *  regardless), silently misreporting the destination for a private-homed proof. */
+const resolveDestRoot = (home, store, root) => home === "private" && store.privateDir ? store.privateDir : root;
 // 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
@@ -82,6 +116,61 @@ const FINDINGS_CAP = 12; // hunch_findings listing
 const SEV_CONSTRAINT = { blocking: 3, warning: 2, advisory: 1 };
 const SEV_BUG = { critical: 4, high: 3, medium: 2, low: 1 };
 const more = (total, cap, hint = "") => total > cap ? `\n  …(+${total - cap} more${hint ? ` — ${hint}` : ""})` : "";
+/** Public MCP shape for the canonical delivery envelope. Keeping the schema on
+ *  the tool means orchestrators can consume receipt facts without scraping the
+ *  backward-compatible text block. */
+const DELIVERY_OUTPUT_SCHEMA = z.object({
+    text: z.string(),
+    delivered: z.array(z.object({
+        kind: z.enum(["constraints", "decisions", "bugs", "findings"]),
+        record_id: z.string(),
+        rank: z.number().int().positive(),
+        delivery_reason: z.enum(["ranked", "blocking-reserved"]),
+        provenance_status: z.enum(["current", "unverified", "stale"]),
+        token_cost: z.number().int().nonnegative(),
+    })),
+    supplements: z.array(z.object({
+        id: z.string(),
+        kind: z.string(),
+        delivered: z.boolean(),
+        reason: z.enum(["supplemental", "budget", "empty"]),
+        rank: z.number().int().positive(),
+        token_cost: z.number().int().nonnegative(),
+    })),
+    omitted: z.array(z.object({
+        kind: z.enum(["constraints", "decisions", "bugs", "findings"]),
+        record_id: z.string(),
+        reason: z.enum(["budget", "stale-provenance", "retired"]),
+        detail: z.string(),
+    })),
+    budget_tokens: z.number().int().nonnegative(),
+    used_chars: z.number().int().nonnegative(),
+    blocking_overflow: z.boolean(),
+});
+/** Return the same human-readable brief older clients consume plus the exact
+ *  machine-readable envelope. Receipt recording is deliberately best-effort:
+ *  recordServed never throws, so telemetry can never cost a delivery. */
+function deliveredContext(root, target, envelope, sessionId) {
+    // Validate before recording: if a future envelope change drifts from the
+    // advertised MCP contract, the SDK will reject the call and the local ledger
+    // must not claim that response was served.
+    const structuredContent = DELIVERY_OUTPUT_SCHEMA.parse(envelope);
+    recordServed(root, structuredContent.delivered.map((item) => ({
+        event: "served",
+        kind: item.kind,
+        record_id: item.record_id,
+        target,
+        session_id: sessionId,
+        rank: item.rank,
+        delivery_reason: item.delivery_reason,
+        provenance_status: item.provenance_status,
+        token_cost: item.token_cost,
+    })));
+    return {
+        content: [{ type: "text", text: structuredContent.text }],
+        structuredContent,
+    };
+}
 // Capture-session tokens live in src/core/capturetoken.ts (pure + testable). These
 // thin wrappers bind the process clock and id source at the call site (§5 Stage 1).
 const issueCaptureToken = () => issueToken(randomUUID, Date.now());
@@ -378,6 +467,30 @@ export function buildServerWithRootControl(initialRoot) {
     };
     const registerTool = server.registerTool.bind(server);
     server.registerTool = ((name, config, callback) => registerTool(name, config, async (...args) => {
+        // Claude Code CLI never advertises `roots`/`roots/list_changed` for an agent-driven
+        // `cd` or EnterWorktree (issue #20) — the cached `root` above just never moves, so a
+        // write silently lands wherever the process was spawned. Write tools accept an
+        // optional `cwd` argument (see cwdHintField) as a client-agnostic fallback: resolved
+        // fresh on EVERY call instead of trusted from a cache, and re-homing this stdio
+        // process the same way a `roots` notification would. Only safe when this is the
+        // sole in-flight request — re-homing under a concurrent request would tear its
+        // root/store out from under it, so that case is refused rather than risked.
+        const cwdHint = extractCwdHint(args[0]);
+        if (cwdHint !== undefined) {
+            const target = canonicalRootPath(findRoot(cwdHint));
+            if (target !== canonicalRootPath(root)) {
+                if (activeRequests) {
+                    return err(`Hunch is mid-request against ${root} and cannot safely switch to the working directory you passed ` +
+                        `(resolves to ${target}) while another call is in flight. Retry this call once the other one completes.`);
+                }
+                try {
+                    setRoot(cwdHint);
+                }
+                catch (error) {
+                    return err(`Failed to switch Hunch to your working directory (${cwdHint}): ${error.message}`);
+                }
+            }
+        }
         activeRequests++;
         try {
             // Routing is live state, not a startup constant. A branch switch or
@@ -589,11 +702,19 @@ export function buildServerWithRootControl(initialRoot) {
             budget_tokens: z.number().optional().describe("Rough token budget for the brief (default 1500)."),
             as_of: z.string().optional().describe("Time-travel ref (commit/tag/branch): assemble the slice as it stood then."),
         },
-    }, async ({ target, budget_tokens, as_of }) => {
+        outputSchema: DELIVERY_OUTPUT_SCHEMA,
+    }, async ({ target, budget_tokens, as_of }, extra) => {
         const asOf = as_of ? asOfDate(as_of, root) : undefined;
         if (as_of && !asOf)
             return err(`Could not resolve as_of "${as_of}" to a commit.`);
         const ctx = store.assembleContext(target, budget_tokens ?? 1500, { asOf });
+        const options = {
+            root,
+            symbols: store.recs("symbols"),
+            components: store.recs("components"),
+            decisionCorpus: store.recs("decisions"),
+            historical: !!asOf,
+        };
         // Task-phrase input ("improve retrieval ranking") resolves no file/symbol and
         // used to return an empty brief while the graph held the answer — fall back to
         // FTS so the assistant always leaves with the closest matches, not a shrug.
@@ -601,17 +722,30 @@ export function buildServerWithRootControl(initialRoot) {
         if (empty && !asOf) {
             const hits = store.search(target, 8);
             if (hits.length) {
-                const lines = hits.map((h) => `• ${h.ref} — ${h.title}\n    ${h.snippet}`);
-                return ok(`No file/symbol resolves for "${target}" — closest graph matches instead:\n\n${lines.join("\n")}\n\n(For a file/symbol brief pass a concrete target; free-text goes through the same search as hunch_query.)`);
+                const resolved = hits.map((hit) => ({ hit, record: store.resolve(hit.ref)?.record }));
+                const fallback = {
+                    ...ctx,
+                    constraints: resolved.filter(({ hit, record }) => hit.kind === "constraints" && !!record).map(({ record }) => record),
+                    decisions: resolved.filter(({ hit, record }) => hit.kind === "decisions" && !!record).map(({ record }) => record),
+                    bugs: resolved.filter(({ hit, record }) => hit.kind === "bugs" && !!record).map(({ record }) => record),
+                    findings: resolved.filter(({ hit, record }) => hit.kind === "findings" && !!record).map(({ record }) => record),
+                };
+                const envelope = buildDeliveryEnvelope(fallback, {
+                    ...options,
+                    supplements: hits
+                        .filter((hit) => !["constraints", "decisions", "bugs", "findings"].includes(hit.kind))
+                        .map((hit, index) => ({
+                        id: hit.ref,
+                        kind: `search-${hit.kind}`,
+                        text: `${hit.ref} — ${hit.title}: ${hit.snippet}`,
+                        priority: 100 - index,
+                    })),
+                });
+                return deliveredContext(root, target, envelope, extra.sessionId);
             }
         }
-        return ok(formatContext(ctx, {
-            root,
-            symbols: store.recs("symbols"),
-            components: store.recs("components"),
-            decisionCorpus: store.recs("decisions"),
-            historical: !!asOf,
-        }));
+        const envelope = buildDeliveryEnvelope(ctx, options);
+        return deliveredContext(root, as_of ? `${target} (as_of:${as_of})` : target, envelope, extra.sessionId);
     });
     // -- hunch_now (the hot view: recent activity + roadmap) --------------------
     // PUBLIC store only, per dec_29eff08c69's jurisdiction rule: an assistant may
@@ -779,6 +913,7 @@ export function buildServerWithRootControl(initialRoot) {
                 private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — for sensitive decisions kept out of a public repo. Errors if no private store is configured."),
             }),
             capture_token: z.string().optional().describe("token from hunch_capture_decision — proves this write is the tail of a grilling interview. Omit only for a quick manual record (a deprecation nudge is returned)."),
+            cwd: cwdHintField,
         },
     }, async ({ decision, capture_token }) => {
         try {
@@ -951,7 +1086,8 @@ export function buildServerWithRootControl(initialRoot) {
             const where = decision.private
                 ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
                 : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
-            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${supNote}${note}${captureNote}${quality}`);
+            const dest = destinationNote(resolveDestRoot(home, store, root));
+            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${dest}${supNote}${note}${captureNote}${quality}`);
         }
         catch (e) {
             return err(`Failed to record decision: ${e.message}`);
@@ -971,6 +1107,7 @@ export function buildServerWithRootControl(initialRoot) {
             source_decision: z.string().optional().describe("id of a decision this correction derives from."),
             private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — a sensitive rule enforced locally (pre-edit hook + local check) but never exposed in a public PR comment. Errors if no private store is configured."),
             capture_token: z.string().optional().describe("token from hunch_capture_decision. The rule is recorded and enforced either way — the token only decides whether it may DENY: without one it lands as advisory testimony capped at severity 'warning'."),
+            cwd: cwdHintField,
         },
     }, async (input) => {
         try {
@@ -1025,7 +1162,8 @@ export function buildServerWithRootControl(initialRoot) {
                 : `
 
 ⚠ Recorded WITHOUT a capture interview — this rule is agent_recorded TESTIMONY${input.severity === "blocking" ? ' and was capped from "blocking" to "warning"' : ""}. It IS enforced: the pre-edit hook and CI surface it on every matching edit from now on. What it cannot do is DENY an edit — only a rule a human countersigned may block. Countersign it by re-recording through hunch_capture_decision → hunch_record_correction(capture_token).`;
-            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where} It now ${enforce}.${reviewNote}${tierNote}`);
+            const dest = destinationNote(resolveDestRoot(home, store, root));
+            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where}${dest} It now ${enforce}.${reviewNote}${tierNote}`);
         }
         catch (e) {
             return err(`Failed to record correction: ${e.message}`);
@@ -1050,6 +1188,7 @@ export function buildServerWithRootControl(initialRoot) {
                 resolved_commit: z.string().optional().describe("the commit that fixed it (with triage:'resolved')"),
                 private: z.boolean().optional().describe("write into the PRIVATE overlay store instead of the committed repo. Errors if no private store is configured."),
             }),
+            cwd: cwdHintField,
         },
     }, async ({ finding }) => {
         try {
@@ -1094,7 +1233,8 @@ export function buildServerWithRootControl(initialRoot) {
                 ? `\n\n△ violates_constraint ${rec.violates_constraint} resolves to no known constraint — if the rule isn't recorded yet, hunch_record_correction it and re-record this finding with the real id.`
                 : "";
             const noEvidence = rec.evidence.length ? "" : "\n\n△ No evidence attached — a finding without the query/output that produced it is an opinion. Re-record with evidence when you have it.";
-            return ok(`${existing ? "Updated" : "Recorded"} finding ${id}: "${rec.title}" (${rec.triage}/${rec.severity}, observed ${rec.observed_at.slice(0, 10)}).${where} It now grounds edits to: ${[...rec.affected_files, ...rec.affected_symbols].join(", ") || "(nothing — add affected_files/symbols so it surfaces at edit time)"}.${danglingCon}${noEvidence}`);
+            const dest = destinationNote(resolveDestRoot(home, store, root));
+            return ok(`${existing ? "Updated" : "Recorded"} finding ${id}: "${rec.title}" (${rec.triage}/${rec.severity}, observed ${rec.observed_at.slice(0, 10)}).${where}${dest} It now grounds edits to: ${[...rec.affected_files, ...rec.affected_symbols].join(", ") || "(nothing — add affected_files/symbols so it surfaces at edit time)"}.${danglingCon}${noEvidence}`);
         }
         catch (e) {
             return err(`Failed to record finding: ${e.message}`);
@@ -1129,6 +1269,7 @@ export function buildServerWithRootControl(initialRoot) {
             public_only: z.boolean().optional().describe("Read and write only the public correction home."),
             private_only: z.boolean().optional().describe("Keep correction-derived evidence/policy/proof artifacts in the configured private overlay; the public source-code graph is refreshed before proof."),
             include_artifacts: z.boolean().optional().describe("Include the complete Policy IR, proof plan, proof receipts, and evidence object. Default output is a concise review envelope."),
+            cwd: cwdHintField,
         },
     }, async ({ constraint_id, public_only, private_only, include_artifacts }) => {
         try {
@@ -1166,8 +1307,10 @@ export function buildServerWithRootControl(initialRoot) {
             if (artifactHome === "private") {
                 flushMemoryHome(store, hunchPaths(root).hunch, "private", `hunch: prove correction ${constraint_id}`, startupTeamRoute ?? undefined);
             }
+            const destRoot = resolveDestRoot(artifactHome, store, root);
+            const destination = { root: destRoot, branch: currentBranch(destRoot) };
             if (include_artifacts)
-                return ok(JSON.stringify(upgrade, null, 2));
+                return ok(JSON.stringify({ ...upgrade, destination }, null, 2));
             return ok(JSON.stringify({
                 status: upgrade.status,
                 correction_id: upgrade.correction_id,
@@ -1180,6 +1323,7 @@ export function buildServerWithRootControl(initialRoot) {
                 authority: upgrade.authority,
                 effects: upgrade.effects,
                 activation: upgrade.activation,
+                destination,
             }, null, 2));
         }
         catch (e) {
@@ -1338,6 +1482,7 @@ export function buildServerWithRootControl(initialRoot) {
         inputSchema: {
             policy_id: z.string().describe("Policy id (pol_*)."),
             public_only: z.boolean().optional().describe("Exclude private-overlay policy and evidence records."),
+            cwd: cwdHintField,
         },
     }, async ({ policy_id, public_only }) => {
         try {
@@ -1347,7 +1492,8 @@ export function buildServerWithRootControl(initialRoot) {
             if (!home)
                 throw new Error(`policy ${policy_id} has no exact storage home`);
             flushMemoryHome(store, hunchPaths(root).hunch, home, `hunch: plan policy ${policy_id}`, startupTeamRoute ?? undefined);
-            return ok(JSON.stringify(plan, null, 2));
+            const destRoot = resolveDestRoot(home, store, root);
+            return ok(JSON.stringify({ ...plan, destination: { root: destRoot, branch: currentBranch(destRoot) } }, null, 2));
         }
         catch (e) {
             return err(`Failed to generate policy proof plan: ${e.message}`);
@@ -1614,6 +1760,7 @@ export function buildServerWithRootControl(initialRoot) {
             limit: z.number().int().min(1).max(100).optional().describe("Item limit used by the exact review packet (default 30)."),
             allow_install_scripts: z.array(z.string().min(1).max(214)).max(20).optional().describe("Exact dependency package names allowed to run lifecycle scripts while provisioning snapshots."),
             dependency_timeout_ms: z.number().int().min(1).max(900000).optional().describe("Timeout for each exact dependency snapshot operation (default 300000ms)."),
+            cwd: cwdHintField,
         },
     }, async ({ decision_id, since, max_commits, limit, allow_install_scripts, dependency_timeout_ms }) => {
         try {
@@ -1626,7 +1773,8 @@ export function buildServerWithRootControl(initialRoot) {
                 dependencyTimeoutMs: dependency_timeout_ms ?? 300_000,
             });
             flushMemoryHome(store, hunchPaths(root).hunch, "private", "hunch: materialize G2 behavior policies", startupTeamRoute ?? undefined);
-            return ok(JSON.stringify(materialized, null, 2));
+            const destRoot = resolveDestRoot("private", store, root);
+            return ok(JSON.stringify({ ...materialized, destination: { root: destRoot, branch: currentBranch(destRoot) } }, null, 2));
         }
         catch (e) {
             return err(`Failed to materialize G2 behavior policies: ${e.message}`);

package/dist/store/hunchStore.js

@@ -662,7 +662,11 @@ export class HunchStore {
         // The graph stream is model-free, so it contributes even on a lean (no-embeddings)
         // install. With neither semantic nor graph signal, return pure FTS so the
         // zero-fusion-overhead fast path is preserved.
-        const graph = this.graphExpand([...fts, ...sem], 50, gw);
+        const graph = this.graphExpand([...fts, ...sem], {
+            maxDepth: boundedWhole(opts.graphDepth, GRAPH_MAX_DEPTH, GRAPH_DEPTH_HARD_MAX),
+            nodeCap: boundedWhole(opts.graphNodeCap, GRAPH_NODE_CAP, GRAPH_NODE_HARD_MAX),
+            tokenCap: boundedWhole(opts.graphTokenCap, GRAPH_TOKEN_CAP, GRAPH_TOKEN_HARD_MAX),
+        }, gw);
         if (!sem.length && !graph.length)
             return this.rerankByPriors(fts, limit, query);
         // Fuse with headroom so the prior rerank can promote from below the cut line.
@@ -764,47 +768,91 @@ export class HunchStore {
         add(graph, graphWeight);
         return [...acc.values()].sort((a, b) => b.score - a.score).slice(0, limit).map((e) => ({ ...e.hit, score: e.score }));
     }
-    /** Graph retrieval stream (roadmap #1): 1-hop expansion over the dependency graph
-     *  from the lexical/semantic seed hits. For each seed SYMBOL, surface its direct
-     *  neighbors (callers/callees, importers/imported, container) — the cross-file
-     *  evidence a "why" question needs but that neither bm25 nor cosine reaches. Each
-     *  neighbor accrues GAMMA-decayed support per linking seed (one pulled in by several
-     *  top seeds ranks higher); seeds themselves are excluded, so this only ADDS context.
-     *  Deterministic, model-free (runs on a lean install too), one indexed query per seed. */
-    graphExpand(seeds, n, weight = RRF_W_GRAPH) {
-        if (weight <= 0)
+    /** Bounded relevance traversal over the dependency graph. Lexical/semantic symbol
+     *  and component hits seed a small number of depth layers; support decays per hop
+     *  and adds across multiple useful paths. Each frontier and the returned context
+     *  obey a hard node cap, while hydration obeys a separate token cap. Only records
+     *  present in the indexed symbol/component tables can enter the frontier, so
+     *  shared external-package hubs never become context or bridge unrelated symbols. */
+    graphExpand(seeds, opts, weight = RRF_W_GRAPH) {
+        if (weight <= 0 || GRAPH_GAMMA <= 0 || opts.maxDepth <= 0 || opts.nodeCap <= 0 || opts.tokenCap <= 0)
             return [];
-        const symSeeds = seeds.filter((h) => h.ref.startsWith("sym_"));
-        if (!symSeeds.length)
+        const seedRefs = new Set(seeds.map((h) => h.ref)); // never re-surface a seed
+        let frontier = new Map();
+        seeds.forEach((hit, rank) => {
+            if (!isGraphContextRef(hit.ref))
+                return;
+            frontier.set(hit.ref, (frontier.get(hit.ref) ?? 0) + 1 / (RRF_K + rank + 1));
+        });
+        if (!frontier.size)
             return [];
-        const seen = new Set(seeds.map((h) => h.ref)); // never re-surface a seed
         const nbStmt = this.db.prepare(
         /* sql */ `
-      SELECT e."to"   AS nb FROM edges e WHERE e."from" = ? AND e.type IN ('calls','depends_on','imports','contains')
+      SELECT e."to" AS nb
+        FROM edges e
+       WHERE e."from" = ? AND e.type IN ('calls','depends_on','imports','contains')
+         AND (EXISTS (SELECT 1 FROM symbols s WHERE s.id = e."to")
+           OR EXISTS (SELECT 1 FROM components c WHERE c.id = e."to"))
       UNION
-      SELECT e."from" AS nb FROM edges e WHERE e."to"   = ? AND e.type IN ('calls','depends_on','imports','contains')`);
+      SELECT e."from" AS nb
+        FROM edges e
+       WHERE e."to" = ? AND e.type IN ('calls','depends_on','imports','contains')
+         AND (EXISTS (SELECT 1 FROM symbols s WHERE s.id = e."from")
+           OR EXISTS (SELECT 1 FROM components c WHERE c.id = e."from"))
+       ORDER BY nb`);
+        const expanded = new Set();
         const score = new Map();
-        symSeeds.forEach((h, i) => {
-            const contrib = GRAPH_GAMMA / (RRF_K + i + 1);
-            for (const r of nbStmt.all(h.ref, h.ref)) {
-                if (seen.has(r.nb))
-                    continue;
-                score.set(r.nb, (score.get(r.nb) ?? 0) + contrib);
+        for (let depth = 1; depth <= opts.maxDepth && frontier.size; depth++) {
+            const layer = new Map();
+            const rankedFrontier = [...frontier.entries()]
+                .sort((a, b) => b[1] - a[1] || compareRefs(a[0], b[0]))
+                .slice(0, opts.nodeCap)
+                .filter(([ref]) => !expanded.has(ref));
+            // Mark the whole frontier visited before walking it. Otherwise an edge
+            // between peers in this layer credits whichever peer sorts second as if
+            // it were deeper context, making scores depend on ref ordering.
+            for (const [ref] of rankedFrontier)
+                expanded.add(ref);
+            for (const [ref, support] of rankedFrontier) {
+                const contribution = support * GRAPH_GAMMA;
+                for (const row of nbStmt.all(ref, ref)) {
+                    if (seedRefs.has(row.nb) || expanded.has(row.nb))
+                        continue;
+                    layer.set(row.nb, (layer.get(row.nb) ?? 0) + contribution);
+                }
             }
-        });
+            const rankedLayer = [...layer.entries()]
+                .sort((a, b) => b[1] - a[1] || compareRefs(a[0], b[0]))
+                .slice(0, opts.nodeCap);
+            for (const [ref, support] of rankedLayer)
+                score.set(ref, (score.get(ref) ?? 0) + support);
+            frontier = new Map(rankedLayer);
+        }
         if (!score.size)
             return [];
-        const top = [...score.entries()].sort((a, b) => b[1] - a[1]).slice(0, n);
+        const top = [...score.entries()]
+            .sort((a, b) => b[1] - a[1] || compareRefs(a[0], b[0]))
+            .slice(0, opts.nodeCap);
         // Hydrate title/snippet from the FTS table in ONE query (mirrors cosineRank).
         const placeholders = top.map(() => "?").join(",");
         const meta = new Map();
-        for (const row of this.db.prepare(`SELECT ref, title, body FROM search WHERE ref IN (${placeholders})`).all(...top.map(([ref]) => ref))) {
-            meta.set(row.ref, { title: row.title, body: row.body });
+        for (const row of this.db.prepare(`SELECT ref, kind, title, body FROM search WHERE ref IN (${placeholders})`).all(...top.map(([ref]) => ref))) {
+            meta.set(row.ref, { kind: row.kind, title: row.title, body: row.body });
         }
-        return top.map(([ref, s]) => {
+        const hits = [];
+        let usedTokens = 0;
+        for (const [ref, s] of top) {
             const m = meta.get(ref);
-            return { ref, kind: ref.startsWith("cmp_") ? "component" : "symbol", title: m?.title ?? ref, snippet: (m?.body ?? "").slice(0, 120), score: s };
-        });
+            if (!m)
+                continue;
+            const hit = { ref, kind: m.kind, title: m.title, snippet: m.body.slice(0, 120), score: s };
+            const tokenCost = estimatedSearchHitTokens(hit);
+            if (usedTokens + tokenCost > opts.tokenCap)
+                continue;
+            hits.push(hit);
+            usedTokens += tokenCost;
+        }
+        return hits;
     }
     /** All decisions/bugs/constraints/symbols/components touching a file path or
      *  symbol name (hunch_why). Pass `{ asOf }` (an ISO instant) to TIME-TRAVEL:
@@ -1581,7 +1629,13 @@ const RRF_K = numEnv("HUNCH_RRF_K", 60);
 const RRF_W_FTS = numEnv("HUNCH_RRF_W_FTS", 1);
 const RRF_W_SEM = numEnv("HUNCH_RRF_W_SEM", 0.7);
 const RRF_W_GRAPH = numEnv("HUNCH_RRF_W_GRAPH", 0.5);
-const GRAPH_GAMMA = numEnv("HUNCH_GRAPH_GAMMA", 0.25);
+const GRAPH_GAMMA = Math.min(1, numEnv("HUNCH_GRAPH_GAMMA", 0.25));
+const GRAPH_DEPTH_HARD_MAX = 8;
+const GRAPH_NODE_HARD_MAX = 500;
+const GRAPH_TOKEN_HARD_MAX = 100_000;
+const GRAPH_MAX_DEPTH = boundedWhole(numEnv("HUNCH_GRAPH_MAX_DEPTH", 2), 2, GRAPH_DEPTH_HARD_MAX);
+const GRAPH_NODE_CAP = boundedWhole(numEnv("HUNCH_GRAPH_NODE_CAP", 50), 50, GRAPH_NODE_HARD_MAX);
+const GRAPH_TOKEN_CAP = boundedWhole(numEnv("HUNCH_GRAPH_TOKEN_CAP", 2_000), 2_000, GRAPH_TOKEN_HARD_MAX);
 /** Prior tuning: how far a trust weight may move a hit from its FUSED position.
  *  SCALE maps the weight's realistic span onto positions (this repo's own decisions
  *  span w 0.48…1.0, so ×12 reaches the clamp at the low end); MAX_PRIOR_SHIFT is the
@@ -1595,6 +1649,20 @@ function numEnv(name, dflt) {
     // a stream); rejecting it silently re-enabled the default weight (issue #33).
     return Number.isFinite(v) && v >= 0 ? v : dflt;
 }
+function boundedWhole(value, dflt, hardMax) {
+    if (value === undefined || !Number.isFinite(value) || value < 0)
+        return dflt;
+    return Math.min(Math.floor(value), hardMax);
+}
+function isGraphContextRef(ref) {
+    return ref.startsWith("sym_") || ref.startsWith("cmp_");
+}
+function compareRefs(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function estimatedSearchHitTokens(hit) {
+    return Math.max(1, Math.ceil([...`${hit.kind} ${hit.ref}\n${hit.title}\n${hit.snippet}`].length / 4));
+}
 /** Pack a vector's exact bytes for SQLite. Explicit offset+length so a SUBARRAY
  *  view (byteOffset != 0) writes only its slice, not the whole backing buffer.
  *  node:sqlite copies on bind, so the returned view never aliases the row. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

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