@davesheffer/hunch 1.46.0 → 1.47.1

package/dist/mcp/server.js

@@ -34,7 +34,7 @@ import { refreshExistingGrounding } from "../integrations/providers.js";
 import { workspaceLedgerView, renderWorktreeTable, renderBranchTable, workspaceSummaryLine, snapshotHasHome, recordWorkspaceSnapshot, branchRows, worktreeRows } from "../integrations/workspaceLedger.js";
 import { workspacesConfig } from "../core/config.js";
 import { revParse, asOfDate, revExists, lastChangeDate, checkFreshnessRevision, teamPullIsFresh, rangeFiles, rangeGateDiff, commitFiles, commitGateDiff, stagedFiles, stagedGateDiff, workingFiles, workingGateDiff, pullHunchStatusDetailed, describePullFailure, sameRemoteUrl, currentBranch, worktreePaths, pathKnownToHistory } from "../extractors/git.js";
-import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
+import { flushCapture, flushStateWrite, flushMemoryHome, pinSharedRemote, HELD_ON_DEFAULT_BRANCH } from "../integrations/sync.js";
 import { withWriteLock } from "../serve/writelock.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, isTeamStoreTrusted, overlayMatchesTeamRemote, teamWiringConsented, untrustedTeamStoreMessage, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
 import { formatSearchHit, formatStructure } from "../core/format.js";
@@ -90,34 +90,36 @@ const err = (text) => ({ content: [{ type: "text", text }], isError: true });
  *  Transient states that say "retry" in their own words stay unprefixed. */
 const refused = (text) => err(`Refused: ${text}`);
 const invalid = (text) => err(`Invalid: ${text}`);
-/** 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). */
+/** Shared by every auto-committing write tool. The MCP roots protocol cannot observe an
+ *  agent-driven directory change or worktree entry, so a stdio server's cached root never
+ *  moves by itself; this field is the client-agnostic fallback, resolved fresh on every
+ *  call by the generic tool wrapper. */
 const cwdHintField = z.string().optional().describe("Your current directory, when it differs from where this session started (e.g. a worktree); " +
     "writes then commit there, not to the original root.");
 /** Shared by hunch_record_decision/correction/finding — identical text repeated 3x
  *  otherwise. hunch_context's task_id field differs (delivery vs. save) and keeps its
  *  own description. */
 const saveTaskIdField = TaskIdSchema.optional().describe("Task ID, to attribute this save to it; never affects capture authority.");
-/** 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")
+/** Pulls the cwd hint out of a tool call's already-parsed first argument. The wrapper
+ *  runs for EVERY tool (read and write), so this assumes nothing about any one tool's
+ *  input shape: anything that is not an object with a non-blank string `cwd` yields
+ *  undefined. The original (untrimmed) string is returned. */
+function cwdHintOf(input) {
+    if (typeof input !== "object" || input === null)
         return undefined;
     const cwd = input.cwd;
-    return typeof cwd === "string" && cwd.trim() ? cwd : undefined;
+    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. */
-const flushNote = (flush, home, mode) => flush === "pushed" ? ` (committed + pushed to the ${mode === "shared" ? "shared team store" : "private repo"})`
-    : flush === "committed"
-        ? home === "private"
-            ? " (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)"
-        : "";
+const flushNote = (flush, home, mode) => flush === "held" ? ` (${HELD_ON_DEFAULT_BRANCH})`
+    : flush === "pushed" ? ` (committed + pushed to the ${mode === "shared" ? "shared team store" : "private repo"})`
+        : flush === "committed"
+            ? home === "private"
+                ? " (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
@@ -150,11 +152,9 @@ 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. */
+/** Self-diagnosing destination suffix for every auto-committing write tool. A capture
+ *  silently landing in the wrong repo or branch is only discoverable by auditing git log
+ *  by hand, so the destination is ALWAYS shown, whether or not a cwd hint chose it. */
 const destinationNote = (destRoot) => {
     const branch = currentBranch(destRoot);
     return ` [captured${branch ? ` on branch ${branch}` : ""} in ${destRoot}]`;
@@ -586,12 +586,10 @@ function nuryelWriteSubject(facet, record) {
     const kind = facet.endsWith("s") ? facet.slice(0, -1) : facet;
     return `${kind}${typeof label === "string" ? ` "${label.slice(0, 60)}"` : ""} (nuryel_write)`;
 }
-/** 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;
+/** Where a capture keyed to a storage home actually lands. Centralized so every
+ *  destination-reporting call site agrees: hunch_policy_upgrade_correction once computed
+ *  its own home but reported the public root regardless, misreporting a private-homed proof. */
+const destinationRoot = (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
@@ -993,13 +991,12 @@ function qualityNudge(rec) {
     }
     return "";
 }
-/** Resolve a free-form target (symbol id / name / file path) to symbol records.
- *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
- *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift
- *  apart on the same question. */
+/** Resolve a free-form target (symbol id, name, or file path) to symbol records using
+ *  tiered matching — exact id, then exact name, then exact file, then a path-segment-anchored
+ *  suffix. Shared with HunchStore.why() through matchSymbolsTiered so the two never disagree. */
 export function resolveSymbols(store, target) {
-    // An absolute target (an agent's edit-payload path, verbatim) never matched
-    // the repo-relative stored file paths below (issue #296).
+    // An absolute path (an agent's verbatim edit-payload path) must match the repo-relative
+    // stored file paths (issue #296).
     target = repoRelativeTarget(target, store.publicRoot);
     const syms = store.json.loadAll("symbols");
     const components = store.json.loadAll("components");
@@ -1372,23 +1369,20 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     };
     const registerTool = server.registerTool.bind(server);
     server.registerTool = ((name, config, callback) => hiddenTools.has(name) ? undefined : 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]);
+        // The Claude Code CLI never advertises roots/list_changed for an agent `cd` or worktree
+        // entry, so the cached root never moves and writes land where the process was spawned.
+        // Write tools therefore accept an optional `cwd` (see cwdHintField) as a client-agnostic
+        // fallback, resolved fresh on every call rather than cached, re-homing this stdio
+        // process the way a roots notification would. That is only safe when no other request
+        // is in flight, so that case is refused instead of risked.
+        const cwdHint = cwdHintOf(args[0]);
         // A pinned root is the whole point of `hunch mcp --root`: a served partition must not
         // follow the caller's working directory into some other checkout.
         if (cwdHint !== undefined && !pinned) {
             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.`);
+                if (activeRequests !== 0) {
+                    return err(`Hunch is serving ${root} and cannot safely switch to your working directory (${target}) while another call is in flight. Retry once the other call completes.`);
                 }
                 try {
                     setRoot(cwdHint);
@@ -1923,13 +1917,13 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_now (the hot view: recent activity + roadmap) --------------------
     // PUBLIC store only, per dec_29eff08c69's jurisdiction rule: an assistant may
     // paste this anywhere, so it must be publishable by construction. Union view
-    // stays behind `hunch now --private` on the local terminal. EXCEPTION: a
-    // queued commit-repair's liveness is checked against the full store (see
-    // below), so a private-overlay decision's id and commit shas — never its
-    // title — can surface in the escalation line.
+    // is available only through the local terminal command `hunch now --private`.
+    // Exception: a queued commit-repair's liveness is checked against the full store, so a
+    // private-overlay decision's id and commit shas (never its title) may appear in the
+    // escalation line.
     server.registerTool("hunch_now", {
         title: "Recent activity + the roadmap (the hot view)",
-        description: "What just happened and what's next, straight from the graph: the last N decisions, the ROADMAP, and any inline human question such as an imported ADR awaiting explicit approve/decline. Call at session start to orient, or before planning what to work on. Same data as the wiki's now.md. Public store only, EXCEPT a queued commit-repair's liveness is checked against the full store (so a private-overlay decision's fully-answerable repair doesn't go silently unanswerable); only its id and the commit shas ever surface, never its title.",
+        description: "What just happened and what is next, straight from the graph: the last N decisions, the ROADMAP, and any inline human question such as an imported ADR awaiting explicit approve/decline. Call at session start to orient, or before planning. Same data as the wiki's now.md. Public store only — except that a queued commit-repair's liveness is checked against the full store, so a private-overlay decision's answerable repair does not go silently unanswerable; only its id and commit shas ever surface, never its title.",
         inputSchema: {
             recent_limit: z.number().optional().describe("How many recent decisions to include (default 5)."),
             roadmap_limit: z.number().optional().describe("How many roadmap entries to include (default 2); the rest are counted."),
@@ -1962,18 +1956,15 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             L.push("", ws);
         const escalations = pendingEscalations(store.advisoryRecs("decisions"));
         escalations.push(...premiseEscalations(store.advisoryRecs("decisions"), { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
-        // liveness checked against the full store (repair-provenance reads the
-        // full store too) even though the title stays scoped to advisoryRecs —
-        // an overlay decision's repair is fully answerable, so it must not go
-        // silent here just because its title is private.
-        const hunchNowQueue = readActivePendingRepairs(root);
-        escalations.push(...commitRepairEscalations(hunchNowQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, hunchNowQueue)));
-        // Only ACTIONABLE entries are a question the assistant can put to the human
-        // directly — a duplicate-id commit-repair follower whose own resolution
-        // says "act on a different entry first" isn't one (#61).
-        const actionableNow = actionableEscalations(escalations);
-        if (actionableNow.length) {
-            L.push("", `⚖ ${actionableNow.length} decision(s) need the human's call — ASK inline (never queue): ${actionableNow.map((e) => e.question).join(" · ")}`);
+        // Liveness is checked against the FULL store (the title stays scoped to advisory
+        // records), so an overlay decision's repair does not go silent.
+        const repairQueue = readActivePendingRepairs(root);
+        escalations.push(...commitRepairEscalations(repairQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, repairQueue)));
+        // A duplicate-id commit-repair follower whose own answer is "act on a different
+        // entry first" is not a question to raise (#61).
+        const actionable = actionableEscalations(escalations);
+        if (actionable.length) {
+            L.push("", `⚖ ${actionable.length} decision(s) need the human's call — ASK inline (never queue): ${actionable.map((e) => e.question).join(" · ")}`);
         }
         return ok(L.join("\n"));
     });
@@ -2039,24 +2030,20 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         // Premise decay: a live decision whose recorded reason died. Question-framed
         // like every entry here — authority never changes until the human answers.
         items.push(...premiseEscalations(store.advisoryRecs("decisions"), { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
-        // See the sibling hunch_now handler above for why `live` is the full store.
-        const hunchEscalationsQueue = readActivePendingRepairs(root);
-        items.push(...commitRepairEscalations(hunchEscalationsQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, hunchEscalationsQueue)));
+        // Live set is the full store, for the reason given in the sibling hunch_now handler.
+        const repairQueue = readActivePendingRepairs(root);
+        items.push(...commitRepairEscalations(repairQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, repairQueue)));
         try {
             items.push(...policyEscalations(new ConstitutionService(store, root).list({ publicOnly: true }).map((p) => ({ ...p, last_action: p.audit.at(-1)?.action ?? null }))));
         }
         catch { /* constitution unavailable — memory escalations still surface */ }
         if (!items.length)
             return ok("✓ Nothing needs a human decision — memory is auto-trusted and self-consistent.");
-        // Only ACTIONABLE entries are a question to ask the human directly — a
-        // duplicate-id commit-repair follower whose own resolution says "act on
-        // a different entry first" still surfaces below for transparency, but
-        // isn't itself something to raise as a decision (#61).
+        // Only actionable entries are questions to raise; non-actionable followers still
+        // appear below for transparency (#61).
         const L = [escalationHeadline(items, "mcp"), ""];
         for (const e of items) {
-            // Marked distinctly (never the "⚖ question" glyph) when it isn't
-            // itself something to raise — an entry whose own answer is "act on a
-            // different entry first" reads as informational, not as a question.
+            // Non-actionable entries are marked distinctly so they read as informational, not as a question.
             L.push(`${e.actionable === false ? "·" : "⚖"} ${e.question}`);
             L.push(`   ${e.detail}`);
             L.push(`   → ${e.resolution}`, "");
@@ -2474,7 +2461,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             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;
-            const dest = destinationNote(resolveDestRoot(home, store, root));
+            const dest = destinationNote(destinationRoot(home, store, root));
             // The chain (nuryel.state/1): a `shipped` receipt in an organization drawer rests on
             // this decision by id + the hash ON FILE + this repository's partition. Hand the ref
             // over now so the agent never rests on a pre-store hash or re-derives the scope.
@@ -2585,7 +2572,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const tierNote = `
 
 ⚠ ${why} — this rule is agent_recorded TESTIMONY${capped ? ` and was capped from "${requested.severity}" to "${rec.severity}"` : ""}. 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 confirmed outside the agent channel may block. The human confirms it by running: ${confirmCommand(rec.id, { private: home === "private", severity: requested.severity })}`;
-            const dest = destinationNote(resolveDestRoot(home, store, root));
+            const dest = destinationNote(destinationRoot(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) {
@@ -2666,8 +2653,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 ? `\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.";
-            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}`);
+            const dest = destinationNote(destinationRoot(home, store, root));
+            const grounds = [...rec.affected_files, ...rec.affected_symbols].join(", ") || "(nothing — add affected_files/symbols so it surfaces at edit time)";
+            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: ${grounds}.${danglingCon}${noEvidence}`);
         }
         catch (e) {
             return err(`Failed to record finding: ${e.message}`);
@@ -2780,7 +2768,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 // not race the HTTP server between the ledger read and the record write.
                 const { hunchDir } = stateHomeFor(store, input.scope);
                 const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, ...input }, {
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
+                    flush: (isPrivate, message) => flushStateWrite(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
                 }));
                 return stateResult(`${result.outcome} ${result.record_id} (${result.durability}) ${result.record_hash}`, result);
             }
@@ -2797,7 +2785,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             try {
                 const { hunchDir } = stateHomeFor(store, input.scope);
                 const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, ...input }, {
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
+                    flush: (isPrivate, message) => flushStateWrite(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
                 }));
                 return stateResult(`${result.outcome} observation ${result.record_id} (${result.durability}); this does not assert currentness. ${result.record_hash}`, result);
             }
@@ -2814,7 +2802,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             try {
                 const { hunchDir } = stateHomeFor(store, input.scope);
                 const result = await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, ...input }, {
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
+                    flush: (isPrivate, message) => flushStateWrite(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
                 }));
                 return stateResult(`Capture batch: ${result.results.filter(r => r.status === "saved").length} saved/replayed, ${result.results.filter(r => r.status === "refused").length} refused.${result.reviews ? ` Reviews: ${result.reviews.filter(r => r.status === "saved").length} withdrawn/replayed, ${result.reviews.filter(r => r.status === "refused").length} refused.` : ''} Inspect each indexed result.`, result);
             }
@@ -2950,7 +2938,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             if (artifactHome === "private") {
                 flushMemoryHome(store, hunchPaths(root).hunch, "private", `hunch: prove correction ${constraint_id}`, startupTeamRoute ?? undefined);
             }
-            const destRoot = resolveDestRoot(artifactHome, store, root);
+            const destRoot = destinationRoot(artifactHome, store, root);
             const destination = { root: destRoot, branch: currentBranch(destRoot) };
             if (include_artifacts)
                 return ok(JSON.stringify({ ...upgrade, destination }, null, 2));
@@ -3139,7 +3127,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             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);
-            const destRoot = resolveDestRoot(home, store, root);
+            const destRoot = destinationRoot(home, store, root);
             return ok(JSON.stringify({ ...plan, destination: { root: destRoot, branch: currentBranch(destRoot) } }, null, 2));
         }
         catch (e) {
@@ -3437,7 +3425,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     dependencyTimeoutMs: dependency_timeout_ms ?? 300_000,
                 });
                 flushMemoryHome(store, hunchPaths(root).hunch, "private", "hunch: materialize G2 behavior policies", startupTeamRoute ?? undefined);
-                const destRoot = resolveDestRoot("private", store, root);
+                const destRoot = destinationRoot("private", store, root);
                 return ok(JSON.stringify({ ...materialized, destination: { root: destRoot, branch: currentBranch(destRoot) } }, null, 2));
             }
             catch (e) {

package/dist/mcp/taskReportTools.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { verificationLauncherFor } from "../core/verifyLauncher.js";
 import { TaskIdSchema, ReportClaimSchema, LessonReferenceSchema, finishReportTask, listReportTasks, readTaskReport, readLessonHistory, recordReportClaim, reportPresentationEnabled, startReportTask } from "../core/taskReport.js";
 import { persistTaskRecord } from "../core/taskRecord.js";
-import { reportSourceSnapshot, runReportConformance } from "../core/taskReportEvidence.js";
+import { currentSource, runReportConformance } from "../core/taskReportEvidence.js";
 import { renderTaskReport, writeTaskReportHtml } from "../core/taskReportRender.js";
 function applicationReferences(report) {
     return report.deliveries.flatMap(d => d.records.map(r => ({ occurrence_id: d.occurrence_id, record_id: r.record_id, content_hash: r.content_hash, title: r.title }))).slice(-100);
@@ -85,7 +85,7 @@ export function registerTaskReportTools(server, getRoot, getStore) {
                     // from the model must not fork a second report or fail the start.
                     if (!task_id || !/different title/.test(error.message))
                         throw error;
-                    task = readTaskReport(root, task_id, reportSourceSnapshot(root).hash).task;
+                    task = readTaskReport(root, task_id, currentSource(root)).task;
                 }
                 const launcher = verificationLauncher();
                 // Compact by design (#370): the rules an agent needs to act, and exact
@@ -120,7 +120,7 @@ export function registerTaskReportTools(server, getRoot, getStore) {
             catch (error) {
                 graphNote = `\nGraph     not saved: ${error.message}`;
             }
-            const report = readTaskReport(root, task_id, reportSourceSnapshot(root).hash);
+            const report = readTaskReport(root, task_id, currentSource(root));
             const show = reportPresentationEnabled(root);
             // The HTML evidence view is rendered on demand (hunch_report(html: true),
             // `hunch report <id> --html`, or the VS Code view); finish writes no file.
@@ -165,7 +165,7 @@ export function registerTaskReportTools(server, getRoot, getStore) {
                 const tasks = listReportTasks(root);
                 return { content: [{ type: "text", text: tasks.length ? tasks.map(t => `${t.task_id} · ${t.state} · ${t.title}`).join("\n") : "No task reports yet. Start with hunch_task." }], structuredContent: { tasks } };
             }
-            const report = readTaskReport(root, task_id, reportSourceSnapshot(root).hash);
+            const report = readTaskReport(root, task_id, currentSource(root));
             const file = html ? writeTaskReportHtml(root, task_id) : null;
             return { content: [{ type: "text", text: `${renderTaskReport(report)}${file ? `\nLocal evidence view: ${file}` : ""}` }], structuredContent: { ...boundedTaskReportForHost(report), application_references: applicationReferences(report), contribution_card: renderTaskReport(report), report_path: file } };
         }

package/dist/serve/app.js

@@ -23,7 +23,7 @@ import { STATE_PROOF_CAPABILITY } from '../core/stateProof.js';
 import { createServer } from "node:http";
 import { HunchStore } from "../store/hunchStore.js";
 import { hunchPaths } from "../core/paths.js";
-import { flushCapture } from "../integrations/sync.js";
+import { flushStateWrite } from "../integrations/sync.js";
 import { StateRefusal, capabilities, mergeReadResponses, readState, recordsState, stateHomeFor, subscribeState, writeState } from "../store/stateBinding.js";
 import { STATE_READ_VERSION, STATE_RECORDS_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ReadScopesSchema, ScopeSchema, scopePath } from "../core/stateContract.js";
 import { partitionFor, resolveCredential, readServeConfig } from "./config.js";
@@ -174,7 +174,7 @@ export function createServeApp(config, opts = {}) {
         // Only authenticated grants select stores for cross-partition source visibility.
         const accessOptions = { additionalStores: principal.grants.map(grant => requestStore(grant).store) };
         const { store, root } = requestStore(scope);
-        const flush = (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message);
+        const flush = (isPrivate, message) => flushStateWrite(store, hunchPaths(root).hunch, isPrivate, message);
         if (route === "read") {
             if (body.observed_page !== undefined && body.scopes !== undefined)
                 throw problem(400, 'malformed', 'observation pages require a single partition without scopes');

package/dist/store/hunchStore.js

@@ -1341,8 +1341,8 @@ export class HunchStore {
      *  instant — "what did we believe as of commit X?". Omit `asOf` for the full,
      *  history-inclusive view (backward-compatible default). */
     why(target, opts = {}) {
-        // An absolute target (an agent's edit-payload path, verbatim) never matched
-        // the repo-relative stored file paths below (issue #299).
+        // An agent's verbatim edit-payload path is absolute; stored paths are
+        // repo-relative, so rewrite before any matching (issue #299).
         target = repoRelativeTarget(target, this.paths.root);
         // A record id (every delivered brief line ends in `hunch_why("dec_…")`) resolves
         // to that record directly (issue #474). With `asOf`, a record not in force then
@@ -1364,11 +1364,11 @@ export class HunchStore {
         // so an unanchored suffix pulled unrelated files' records into why()/the
         // pre-edit grounding block (issue #32). Segment-anchored matching only.
         //
-        // A target that IS a path Hunch's index already knows about (README.md,
-        // vscode-extension/index.ts, ...) names exactly one file — suffix-matching
-        // it too pulls in every OTHER file that merely shares a basename (issue
-        // #299: root index.ts delivered vscode-extension/index.ts's rules and vice
-        // versa). "Known to the index" is answered from already-loaded graph data
+        // A target that is a path the index already knows (README.md,
+        // `vscode-extension/index.ts`) names exactly ONE file. Suffix-matching it too
+        // would pull in every other file sharing its basename (issue #299: root
+        // `index.ts` received `vscode-extension/index.ts`'s rules and vice versa). "Known
+        // to the index" is answered from already-loaded graph data, looked up
         // first (a symbol's exact file, or an indexed component's path glob — so a
         // symbol-less indexed file still counts as real), and only then from the
         // working tree, for a real file the index cannot see at all (issue #334).
@@ -1696,9 +1696,8 @@ export class HunchStore {
      *  longer enforced. Pass `{ asOf }` to instead return the invariants in force at
      *  that instant (time-travel: "what must I not have broken as of commit X?"). */
     checkConstraints(scope, opts = {}) {
-        // Constraint scopes are always repo-relative; an absolute target (an
-        // agent's edit-payload path, verbatim) matched nothing even when a
-        // blocking rule plainly applied (issue #296).
+        // Scopes are repo-relative; an absolute target matched nothing even when a
+        // blocking rule applied (issue #296).
         scope = repoRelativeTarget(scope, this.paths.root);
         const all = this.recs("constraints");
         const asOf = opts.asOf;
@@ -1713,11 +1712,8 @@ export class HunchStore {
      *  glob, and the queried scope may be either too. Advisory only — findings never
      *  enter any block path. Sorted worst-first, then id for stable output. */
     liveFindingsFor(scope) {
-        // Same absolute-target and same-basename-leak gaps as why() (issue #299): an
-        // un-rewritten absolute scope never matched the repo-relative `affected_files`
-        // below, and an un-guarded suffix fallback could pull in an unrelated file
-        // that merely shares a basename. Normalize once and reuse the same "is this
-        // path known to the index" guard.
+        // Same absolute-target and same-basename-leak gaps as why() (issue #299):
+        // normalize once and reuse the known-path guard.
         const t = repoRelativeTarget(scope, this.paths.root);
         const indexed = this.isKnownPath(t);
         const live = (f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled";
@@ -2340,9 +2336,7 @@ export class HunchStore {
      *  a task on `target`, ordered by what matters most — invariants first, then the
      *  why, then blast radius and bug history — trimmed to a rough token budget. */
     assembleContext(target, budget = 1500, opts = {}) {
-        // An absolute target (an agent's edit-payload path, verbatim) must be
-        // repo-relative BEFORE it reaches why()/liveFindingsFor() below, or an
-        // absolute path never matches the repo-relative stored data (issue #299).
+        // Normalize before it reaches why()/liveFindingsFor() below (issue #299).
         target = repoRelativeTarget(target, this.paths.root);
         const w = this.why(target, opts);
         const symIds = w.symbols.map((s) => s.id);

package/dist/synthesis/provider.d.ts

@@ -111,8 +111,9 @@ export interface SynthProvider {
 }
 /** Every selectable synthesis mode. `auto` is a preference value rather than a
  * provider: it resolves the invocation's origin without choosing by availability.
- * "openai-compat" is the opt-in local/self-hosted HTTP provider (Ollama, vLLM,
- * LM Studio, ...) — not a subscription, but explicitly selectable like one. */
+ * "openai-compat" is the opt-in local or self-hosted HTTP provider (Ollama, vLLM,
+ * LM Studio and so on). It is not a subscription, but it can be selected
+ * explicitly like one. */
 export declare const SYNTH_PROVIDER_NAMES: readonly ["claude-cli", "codex-cli", "cursor-agent", "kimi-cli", "openai-compat", "deterministic"];
 export declare const SYNTH_PREFERENCES: readonly ["auto", "claude-cli", "codex-cli", "cursor-agent", "kimi-cli", "openai-compat", "deterministic"];
 export type SynthProviderName = (typeof SYNTH_PROVIDER_NAMES)[number];
@@ -172,8 +173,11 @@ export declare function safeModel(v: string | undefined, fallback: undefined): s
  * the explicit skip flag preserves that neutral-cwd isolation without loading a
  * target repo's agent rules or MCP configuration. */
 export declare function codexExecArgs(model?: string): string[];
+/** Sanitize HUNCH_SYNTH_TIMEOUT_MS: a finite number > 0, else `fallback`. */
 export declare function safeTimeout(v: string | undefined, fallback: number): number;
+/** Sanitize HUNCH_SYNTH_MAX_TOKENS: a finite number > 0, else `fallback`. */
 export declare function safeMaxTokens(v: string | undefined, fallback: number): number;
+/** True only when the user explicitly opted in to public (possibly metered) hosts. */
 export declare function meteredHostsAllowed(env?: NodeJS.ProcessEnv): boolean;
 export declare class OpenAICompatProvider extends PromptSynthProvider {
     readonly name = "openai-compat";
@@ -182,9 +186,10 @@ export declare class OpenAICompatProvider extends PromptSynthProvider {
 }
 /** Best-effort: does the configured openai-compat endpoint look like Ollama with
  *  an UNSET num_ctx? Returns
- *  an advisory warning string when so, or null when the endpoint isn't reachable,
- *  doesn't look like Ollama's /api/show shape, or already has num_ctx set — this
- *  is diagnostics only, never thrown, never blocking. Deliberately does NOT try to
+ *  a warning string when the model does not pin num_ctx, or null when the
+ *  endpoint is unreachable, does not look like Ollama's /api/show response shape,
+ *  or already has num_ctx set. Diagnostics only: it never throws and never blocks.
+ *  Deliberately does NOT try to
  *  report the model's effective context length: modern Ollama defaults may come
  *  from server configuration or VRAM tiers, and model_info keys are not a stable
  *  parse target. We therefore report only the observed fact — whether num_ctx is
@@ -203,19 +208,12 @@ export declare class DeterministicProvider implements SynthProvider {
  *  tagged. If nothing parses, hand the raw output to the mapper (→ it finds the JSON
  *  draft or throws → deterministic fallback). Tolerant by design: drift degrades, never crashes. */
 export declare function extractCodexText(out: string): string;
-/** Test-only: clears the availability memoization cache so a test that toggles
- *  env vars mid-process (e.g. HUNCH_SYNTH_BASE_URL) isn't served a stale result
- *  cached by an earlier call in the same process. Never call from production code. */
+/** Test-only: empty the availability cache so a test that changes env vars
+ *  mid-process is not served a stale cached result. */
 export declare function __resetAvailabilityCacheForTests(): void;
-/** "ollama" is accepted as an alias for "openai-compat" — the provider is not
- *  Ollama-specific (it speaks the OpenAI chat-completions format any self-hosted
- *  server can implement), but Ollama is the most common self-hosted target and
- *  users reach for that name first. Applied to the HUNCH_SYNTH_PROVIDER env var in
- *  resolveSynthesisProvider below, and exported so the `hunch provider <name>` CLI
- *  command (index.ts) normalizes it the same way before validating/persisting a
- *  local preference — the two paths must agree, or a user who sets one and reads
- *  the other back gets a confusing "unknown provider" message for a name that
- *  actually works. */
+/** The provider is not Ollama-specific, but Ollama is the name users try first, so
+ *  "ollama" is an alias for "openai-compat". The env var and `hunch provider <name>`
+ *  both normalize through here so the two paths agree. */
 export declare function normalizeProviderName(v: string | undefined): string | undefined;
 /** Read a per-user, gitignored choice. Invalid/missing local state is treated as auto;
  * `writeSynthesisPreference` refuses to overwrite malformed data so this forgiveness
@@ -258,10 +256,10 @@ export declare class EnsembleProvider implements SynthProvider {
 export declare function selectEnsemble(opts?: ProviderSelectionOptions & {
     samples?: number;
 }): Promise<EnsembleProvider | null>;
-/** Pick a provider to run the Critic pass — the same resolved provider normal
- *  synthesis would use (subscription CLI or the opt-in openai-compat endpoint),
- *  honoring the same env/local-preference/auto policy. Returns null when that
- *  resolves to the deterministic fallback — verification then no-ops and the
+/** Pick the provider for the Critic pass: the same resolved provider normal
+ *  synthesis would use (a subscription CLI or the opt-in openai-compat endpoint),
+ *  under the same env / local-preference / auto policy. Returns null when that
+ *  resolves to the deterministic fallback, in which case verification does nothing. The
  *  un-audited draft stands (graceful degradation; dec_18a81c8291). */
 export declare function selectVerifier(opts?: ProviderSelectionOptions): Promise<SynthProvider | null>;
 /** Map model text → RelevanceVerdict, or null when nothing usable parses (→ the