@davesheffer/hunch 1.31.1 → 1.32.1

package/dist/mcp/server.js

@@ -40,6 +40,10 @@ import { PROJECT_DNA_DELTA_SCHEMA_VERSION, diffProjectDna } from "../core/projec
 import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
 import { armExecutionObligations, loadPipelineState, savePipelineState } from "../core/pipeline.js";
 import { recordServed } from "../core/served.js";
+import { TaskIdSchema, recordTaskDelivery } from "../core/taskReport.js";
+import { observeReportCapture } from "../core/taskReportCapture.js";
+import { snapshotDeliveredRecords } from "../core/taskReportEvidence.js";
+import { registerTaskReportTools } from "./taskReportTools.js";
 import { EdgeSchema, ResourceSchema } from "../core/types.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
@@ -51,7 +55,8 @@ import { nowData, wikiStatus, publicHome, readWikiManifestAt } from "../wiki/wik
 import { HUNCH_VERSION } from "../core/version.js";
 import { assertCompleteRepoScan, indexRepo, scanRepo } from "../extractors/indexer.js";
 import { liveForTopic, historyForTopic, rejectedForTopic, captureConflicts } from "../core/topics.js";
-import { pendingEscalations, policyEscalations } from "../core/escalations.js";
+import { pendingEscalations, policyEscalations, commitRepairEscalations, actionableEscalations, escalationHeadline } from "../core/escalations.js";
+import { readActivePendingRepairs, withheldRewrites } from "../core/repairqueue.js";
 import { scanRecord, publicationWarning, loadVocabulary } from "../core/publication.js";
 import { premiseEscalations } from "../core/premises.js";
 import { applyImportedAdrReview, pendingImportedAdrReviews } from "../core/importReview.js";
@@ -770,6 +775,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         });
         return ok(`Top matches for "${query}":\n\n${lines.join("\n")}`);
     });
+    registerTaskReportTools(server, () => root, () => store);
     // -- hunch_runbook --------------------------------------------------------
     server.registerTool("hunch_runbook", {
         title: "Find a runbook for a task",
@@ -1032,9 +1038,26 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             budget_tokens: z.number().optional().describe("Rough token budget for the brief (default 1500)."),
             profile: z.enum(DELIVERY_PROFILES).optional().describe("Delivery role: builder (default), reviewer, or architect. Changes non-blocking order only."),
             as_of: z.string().optional().describe("Time-travel ref (commit/tag/branch): assemble the slice as it stood then."),
+            task_id: TaskIdSchema.optional().describe("Exact task ID from hunch_task; records this delivery for the task's contribution report."),
+            cwd: cwdHintField,
         },
         outputSchema: DELIVERY_OUTPUT_SCHEMA,
-    }, async ({ target, budget_tokens, profile, as_of }, extra) => {
+    }, async ({ target, budget_tokens, profile, as_of, task_id }, extra) => {
+        const deliver = (envelope) => {
+            const result = deliveredContext(root, as_of ? `${target} (as_of:${as_of})` : target, envelope, extra.sessionId);
+            if (task_id) {
+                try {
+                    // Historical contexts must not borrow today's record text/revision.
+                    const records = as_of ? [] : snapshotDeliveredRecords(store, envelope);
+                    const occurrence = recordTaskDelivery(root, task_id, envelope, records);
+                    result.content.push({ type: "text", text: `Task evidence: ${task_id} · occurrence ${occurrence}.\n${records.slice(0, 20).map(r => `${r.record_id} @ ${r.content_hash}`).join("\n")}${records.length > 20 ? "\nMore record identities: hunch_report(task_id)." : ""}` });
+                }
+                catch {
+                    result.content.push({ type: "text", text: `Task evidence could not be recorded for ${task_id}. Context remains available; this delivery's report attribution is unverified. Check the task ID, working directory, and local ledger.` });
+                }
+            }
+            return result;
+        };
         const asOf = as_of ? asOfDate(as_of, root) : undefined;
         if (as_of && !asOf)
             return invalid(`Could not resolve as_of "${as_of}" to a commit.`);
@@ -1098,11 +1121,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                         })),
                     ],
                 });
-                return deliveredContext(root, target, envelope, extra.sessionId);
+                return deliver(envelope);
             }
         }
         const envelope = buildDeliveryEnvelope(ctx, options);
-        return deliveredContext(root, as_of ? `${target} (as_of:${as_of})` : target, envelope, extra.sessionId);
+        return deliver(envelope);
     });
     // -- hunch_shortlist (bounded correction-stage diagnostic) ----------------
     server.registerTool("hunch_shortlist", {
@@ -1146,10 +1169,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.
+    // 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.
     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.",
+        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.",
         inputSchema: {
             recent_limit: z.number().optional().describe("How many recent decisions to include (default 10)."),
         },
@@ -1167,8 +1193,18 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             L.push("", `${pendingReview} legacy un-vouched draft(s) — \`hunch adopt-drafts\` auto-trusts them as advisory (new captures land trusted automatically).`);
         const escalations = pendingEscalations(store.advisoryRecs("decisions"));
         escalations.push(...premiseEscalations(store.advisoryRecs("decisions"), { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
-        if (escalations.length) {
-            L.push("", `⚖ ${escalations.length} decision(s) need the human's call — ASK inline (never queue): ${escalations.map((e) => e.question).join(" · ")}`);
+        // 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(" · ")}`);
         }
         return ok(L.join("\n"));
     });
@@ -1181,22 +1217,32 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // (con_e04226bd05): no Claude-specific behavior.
     server.registerTool("hunch_escalations", {
         title: "Decisions the human must make now (ask inline, not a queue)",
-        description: "The rare decisions the graph cannot resolve on its own — surfaced so you ASK THE USER in the prompt at the moment, then act. This includes one exact imported ADR at a time awaiting approve/decline, topic conflicts, premise-stale decisions, and Constitution human moments. Normally empty. Raise each question with the user; do NOT decide it for them — an entry is a question, silence is never approval. Reads the public store, or the unified overlay when the repo is in shared mode (where the overlay IS the store) — never private-mode overlay records.",
+        description: "The rare decisions the graph cannot resolve on its own — surfaced so you ASK THE USER in the prompt at the moment, then act. Auto-captured memory is trusted automatically and never appears here; this returns topic conflicts (>1 live decision for one topic), premise-stale decisions (a live decision whose recorded REASON no longer holds — its authority is unchanged until the human re-attests, supersedes, or retires), one exact imported ADR at a time awaiting approve/decline, a queued commit-provenance repair (the post-merge hook detected a decision's commit was squash-merged away but never applies the fix unattended — apply with `hunch repair-provenance --apply` or leave it queued), and Constitution human moments (candidate policies awaiting review, proposed policies awaiting an activation decision). Normally empty. Raise each question with the user; do NOT decide it for them — an entry is a question, silence is never approval. Reads the public store, or the unified overlay when the repo is in shared mode — never private-mode overlay records, EXCEPT a queued commit-repair, whose liveness is checked against the full store; only its id and commit shas ever surface, never its title.",
         inputSchema: {},
     }, async () => {
         const items = pendingEscalations(store.advisoryRecs("decisions"));
         // 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)));
         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.");
-        const L = [`${items.length} decision(s) need the human's call — ask each inline, don't decide it for them:`, ""];
+        // 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).
+        const L = [escalationHeadline(items, "mcp"), ""];
         for (const e of items) {
-            L.push(`⚖ ${e.question}`);
+            // 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.
+            L.push(`${e.actionable === false ? "·" : "⚖"} ${e.question}`);
             L.push(`   ${e.detail}`);
             L.push(`   → ${e.resolution}`, "");
         }
@@ -1371,9 +1417,10 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 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)."),
+            task_id: TaskIdSchema.optional().describe("Exact task ID for observing this successful save; reporting never changes capture authority."),
             cwd: cwdHintField,
         },
-    }, async ({ decision, capture_token }) => {
+    }, async ({ decision, capture_token, task_id }) => {
         try {
             // Commit-keyed on the CANONICAL full sha (resolved via git rev-parse), so a
             // human passing the short sha they see in `commit` produces the SAME id as
@@ -1510,7 +1557,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             // closes the other, leaving two live decisions on one topic and grounding
             // silently injecting nothing for it. The guard throws; the surrounding catch
             // turns that into a clean tool error instead of a silent twin.
-            store.putCapture("decisions", rec, !!decision.private);
+            const stored = store.putCapture("decisions", rec, !!decision.private);
+            const observed = observeReportCapture(root, task_id, "decisions", stored, home, !!existing, home === "private" ? store.privateDir ?? undefined : hunchPaths(root).hunch);
             // Invalidate, don't delete: closing the superseded decision's valid-time window
             // (+ a supersedes edge) preserves the why-it-changed trail. Route the close to the
             // same store the new record landed in — a private decision supersedes within the
@@ -1523,8 +1571,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             // Auto-flush the store the record landed in (on by default in every mode): a private
             // 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) + publicHomeNote(home, store.hasPrivate, rec, hunchPaths(root).hunch);
+            const flush = flushCapture(store, hunchPaths(root).hunch, !!decision.private, `hunch: capture ${id}`, startupTeamRoute ?? undefined, observed.observe);
+            const flushed = flushNote(flush, home, store.mode) + publicHomeNote(home, store.hasPrivate, rec, hunchPaths(root).hunch) + observed.note;
             // 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.
@@ -1571,6 +1619,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             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'."),
+            task_id: TaskIdSchema.optional().describe("Exact task ID for observing this successful save; reporting never changes capture authority."),
             cwd: cwdHintField,
         },
     }, async (input) => {
@@ -1596,7 +1645,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             }
             const existing = home === "private" ? store.getPrivateRec("constraints", rec.id) : store.json.get("constraints", rec.id);
             // Same cross-home twin guard as the decision path above.
-            store.putCapture("constraints", rec, !!input.private);
+            const stored = store.putCapture("constraints", rec, !!input.private);
+            const observed = observeReportCapture(root, input.task_id, "constraints", stored, home, !!existing, home === "private" ? store.privateDir ?? undefined : hunchPaths(root).hunch);
             store.reindex();
             // Propagate the new rule to EVERY assistant's ambient grounding (Cursor/Copilot/
             // Windsurf/AGENTS.md/CLAUDE.md), so a correction captured in one assistant is held
@@ -1608,8 +1658,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             // dirty AGENTS/assistant docs. Manual mode still refreshes in place.
             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) + publicHomeNote(home, store.hasPrivate, rec, hunchPaths(root).hunch);
+            const flush = flushCapture(store, hunchPaths(root).hunch, !!input.private, `hunch: capture ${rec.id}`, startupTeamRoute ?? undefined, observed.observe);
+            const flushed = flushNote(flush, home, store.mode) + publicHomeNote(home, store.hasPrivate, rec, hunchPaths(root).hunch) + observed.note;
             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)";
@@ -1652,9 +1702,10 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 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."),
             }),
+            task_id: TaskIdSchema.optional().describe("Exact task ID for observing this successful save; reporting never changes capture authority."),
             cwd: cwdHintField,
         },
-    }, async ({ finding }) => {
+    }, async ({ finding, task_id }) => {
         try {
             if (!finding.title.trim())
                 return invalid("title is required.");
@@ -1684,10 +1735,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 resolved_commit: finding.resolved_commit ?? existing?.resolved_commit ?? null,
                 provenance: { source: "human_confirmed", confidence: 0.95, evidence: finding.evidence ?? existing?.provenance.evidence ?? [], last_verified: now },
             };
-            store.putCapture("findings", rec, !!finding.private);
+            const stored = store.putCapture("findings", rec, !!finding.private);
+            const observed = observeReportCapture(root, task_id, "findings", stored, home, !!existing, home === "private" ? store.privateDir ?? undefined : hunchPaths(root).hunch);
             store.reindex();
-            const flush = flushCapture(store, hunchPaths(root).hunch, !!finding.private, `hunch: capture ${id}`, startupTeamRoute ?? undefined);
-            const flushed = flushNote(flush, home, store.mode) + publicHomeNote(home, store.hasPrivate, rec, hunchPaths(root).hunch);
+            const flush = flushCapture(store, hunchPaths(root).hunch, !!finding.private, `hunch: capture ${id}`, startupTeamRoute ?? undefined, observed.observe);
+            const flushed = flushNote(flush, home, store.mode) + publicHomeNote(home, store.hasPrivate, rec, hunchPaths(root).hunch) + observed.note;
             const where = finding.private
                 ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
                 : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;

package/dist/mcp/taskReportTools.d.ts

@@ -0,0 +1,188 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { readTaskReport } from "../core/taskReport.js";
+import type { HunchStore } from "../store/hunchStore.js";
+/** A tool result must fit the host's round-trip. The full report (every
+ * envelope's context text, every lesson) belongs to `hunch report --json` and
+ * the HTML view; MCP returns exact identities, verdicts and the card. Bounded
+ * by caps first, then by byte size (fnd_53991b877b: an 18-delivery task
+ * produced a 101 KB result the host refused). */
+export declare const MCP_REPORT_BYTE_BUDGET = 48000;
+export declare function boundedTaskReport(report: ReturnType<typeof readTaskReport>, deliveries?: number, recordsPerDelivery?: number): {
+    schema: "hunch.task-report-summary/1";
+    task: {
+        task_id: string;
+        scope: string;
+        title: string;
+        started_at: string;
+        finished_at: string | null;
+        state: "open" | "completed" | "interrupted";
+    };
+    coverage: "delivered" | "no-delivery-observed" | "no-relevant-memory";
+    content_hash: string;
+    unknowns: string[];
+    deliveries: {
+        occurrence_id: string;
+        receipt_id: string;
+        at: string;
+        envelope_hash: string;
+        delivered: number;
+        abstention: boolean;
+        records: {
+            record_id: string;
+            kind: string;
+            content_hash: string;
+            title: string;
+        }[];
+        more_records: number;
+    }[];
+    claims: {
+        action: string;
+        occurrence_id: string;
+        record_id: string;
+        content_hash: string;
+        at: string;
+        attribution: "agent-reported";
+        supported_by: string | null;
+    }[];
+    checks: {
+        check_id: string | undefined;
+        label: string;
+        command: string[];
+        exit_code: number | null;
+        timed_out: boolean;
+        cancelled: boolean;
+        current: boolean;
+        at: string;
+    }[];
+    conformance: {
+        record_id: string;
+        kind: "decisions" | "constraints";
+        content_hash: string;
+        rule: "constraint-forbids" | "decision-conformance";
+        outcome: "satisfied" | "violated" | "not-exercised" | "unavailable";
+        current: boolean;
+        files: string[];
+        detail: string;
+    }[];
+    saves: {
+        event_id: string;
+        at: string;
+        record_id: string;
+        kind: string;
+        content_hash: string;
+        title: string;
+        home: "public" | "private";
+        operation: "updated" | "created";
+        durability: "committed" | "pushed" | "local";
+    }[];
+    refusals: ({
+        source: "native-edit-gate";
+        outcome: "denial-emitted";
+        kind: "constraint" | "veto";
+        record_id: string;
+        target: string;
+        reason_hash: string;
+    } & {
+        event_id: string;
+        at: string;
+    })[];
+    omitted: {
+        deliveries: number;
+        claims: number;
+        checks: number;
+        conformance: number;
+        saves: number;
+        refusals: number;
+    };
+    full_report: string;
+};
+export declare function boundedTaskReportForHost(report: ReturnType<typeof readTaskReport>): {
+    schema: "hunch.task-report-summary/1";
+    task: {
+        task_id: string;
+        scope: string;
+        title: string;
+        started_at: string;
+        finished_at: string | null;
+        state: "open" | "completed" | "interrupted";
+    };
+    coverage: "delivered" | "no-delivery-observed" | "no-relevant-memory";
+    content_hash: string;
+    unknowns: string[];
+    deliveries: {
+        occurrence_id: string;
+        receipt_id: string;
+        at: string;
+        envelope_hash: string;
+        delivered: number;
+        abstention: boolean;
+        records: {
+            record_id: string;
+            kind: string;
+            content_hash: string;
+            title: string;
+        }[];
+        more_records: number;
+    }[];
+    claims: {
+        action: string;
+        occurrence_id: string;
+        record_id: string;
+        content_hash: string;
+        at: string;
+        attribution: "agent-reported";
+        supported_by: string | null;
+    }[];
+    checks: {
+        check_id: string | undefined;
+        label: string;
+        command: string[];
+        exit_code: number | null;
+        timed_out: boolean;
+        cancelled: boolean;
+        current: boolean;
+        at: string;
+    }[];
+    conformance: {
+        record_id: string;
+        kind: "decisions" | "constraints";
+        content_hash: string;
+        rule: "constraint-forbids" | "decision-conformance";
+        outcome: "satisfied" | "violated" | "not-exercised" | "unavailable";
+        current: boolean;
+        files: string[];
+        detail: string;
+    }[];
+    saves: {
+        event_id: string;
+        at: string;
+        record_id: string;
+        kind: string;
+        content_hash: string;
+        title: string;
+        home: "public" | "private";
+        operation: "updated" | "created";
+        durability: "committed" | "pushed" | "local";
+    }[];
+    refusals: ({
+        source: "native-edit-gate";
+        outcome: "denial-emitted";
+        kind: "constraint" | "veto";
+        record_id: string;
+        target: string;
+        reason_hash: string;
+    } & {
+        event_id: string;
+        at: string;
+    })[];
+    omitted: {
+        deliveries: number;
+        claims: number;
+        checks: number;
+        conformance: number;
+        saves: number;
+        refusals: number;
+    };
+    full_report: string;
+};
+export declare function registerTaskReportTools(server: McpServer, getRoot: () => string, getStore: () => HunchStore): void;

package/dist/mcp/taskReportTools.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { fileURLToPath } from "node:url";
+import { TaskIdSchema, ReportClaimSchema, LessonReferenceSchema, finishReportTask, listReportTasks, readTaskReport, readLessonHistory, recordReportClaim, reportPresentationEnabled, startReportTask } from "../core/taskReport.js";
+import { reportSourceSnapshot, 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);
+}
+/** A tool result must fit the host's round-trip. The full report (every
+ * envelope's context text, every lesson) belongs to `hunch report --json` and
+ * the HTML view; MCP returns exact identities, verdicts and the card. Bounded
+ * by caps first, then by byte size (fnd_53991b877b: an 18-delivery task
+ * produced a 101 KB result the host refused). */
+export const MCP_REPORT_BYTE_BUDGET = 48_000;
+export function boundedTaskReport(report, deliveries = 30, recordsPerDelivery = 25) {
+    const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+    const tail = (items, n) => items.slice(Math.max(0, items.length - n));
+    return {
+        schema: "hunch.task-report-summary/1",
+        task: report.task, coverage: report.coverage, content_hash: report.content_hash, unknowns: report.unknowns,
+        deliveries: tail(report.deliveries, deliveries).map(d => ({
+            occurrence_id: d.occurrence_id, receipt_id: d.receipt_id, at: d.at, envelope_hash: d.envelope_hash,
+            delivered: d.envelope.delivered.length, abstention: d.envelope.abstention.active,
+            records: d.records.slice(0, recordsPerDelivery).map(r => ({ record_id: r.record_id, kind: r.kind, content_hash: r.content_hash, title: clip(r.title, 160) })),
+            more_records: Math.max(0, d.records.length - recordsPerDelivery),
+        })),
+        claims: tail(report.claims, 20).map(c => ({ ...c, action: clip(c.action, 300) })),
+        checks: tail(report.checks, 30).map(c => ({ check_id: c.check_id, label: c.label, command: c.command.map(x => clip(x, 120)), exit_code: c.exit_code, timed_out: c.timed_out, cancelled: c.cancelled ?? false, current: c.current, at: c.at })),
+        conformance: tail(report.conformance, 50).map(r => ({ record_id: r.record_id, kind: r.kind, content_hash: r.content_hash, rule: r.rule, outcome: r.outcome, current: r.current, files: r.files.slice(0, 8), detail: clip(r.detail, 240) })),
+        saves: tail(report.saves, 30).map(s => ({ event_id: s.event_id, at: s.at, record_id: s.record.record_id, kind: s.record.kind, content_hash: s.record.content_hash, title: clip(s.record.title, 160), home: s.home, operation: s.operation, durability: s.durability })),
+        refusals: tail(report.refusals, 30),
+        omitted: {
+            deliveries: Math.max(0, report.deliveries.length - deliveries), claims: Math.max(0, report.claims.length - 20), checks: Math.max(0, report.checks.length - 30),
+            conformance: Math.max(0, report.conformance.length - 50), saves: Math.max(0, report.saves.length - 30), refusals: Math.max(0, report.refusals.length - 30),
+        },
+        full_report: `hunch report ${report.task.task_id} --json`,
+    };
+}
+export function boundedTaskReportForHost(report) {
+    // Shrink deterministically until the summary fits; identities are never dropped
+    // from what remains, and `omitted` says exactly how much fell off.
+    for (const [deliveries, records] of [[30, 25], [10, 10], [5, 5], [1, 5], [1, 1]]) {
+        const summary = boundedTaskReport(report, deliveries, records);
+        if (JSON.stringify(summary).length <= MCP_REPORT_BYTE_BUDGET)
+            return summary;
+    }
+    const minimal = boundedTaskReport(report, 1, 1);
+    return { ...minimal, deliveries: [], omitted: { ...minimal.omitted, deliveries: report.deliveries.length } };
+}
+/** Reuse the MCP server's installation, not a potentially stale global binary.
+ * Structured argv is authoritative; the shell hint uses literal quoting. */
+function verificationLauncher() {
+    const dev = import.meta.url.endsWith(".ts");
+    const entry = fileURLToPath(new URL(`../cli/index.${dev ? "ts" : "js"}`, import.meta.url));
+    const argv = [process.execPath, ...(dev ? ["--import", fileURLToPath(import.meta.resolve("tsx"))] : []), entry];
+    const quote = (s) => process.platform === "win32" ? `'${s.replace(/'/g, "''")}'` : `'${s.replace(/'/g, "'\\''")}'`;
+    return { argv, shell: `${process.platform === "win32" ? "& " : ""}${argv.map(quote).join(" ")}` };
+}
+export function registerTaskReportTools(server, getRoot, getStore) {
+    server.registerTool("hunch_task", {
+        title: "Start or finish a task's contribution report",
+        description: "Start once per user task; pass the returned task_id to hunch_context. Finish before your final response and include the returned concise contribution card, without asking the user. Applications are explicitly agent-reported and must name an exact delivered occurrence and record hash. Completion never implies successful verification. Not for storing decisions or claiming tests passed; use the CLI task verify wrapper for observed command results.",
+        inputSchema: {
+            action: z.enum(["start", "finish"]), task_id: TaskIdSchema.optional(),
+            title: z.string().min(1).max(200).optional(),
+            outcome: z.enum(["completed", "interrupted"]).optional(),
+            applications: z.array(ReportClaimSchema).max(20).optional(),
+            cwd: z.string().optional().describe("Actual repository/worktree directory for this task."),
+        },
+    }, async ({ action, task_id, title, outcome, applications }) => {
+        try {
+            const root = getRoot();
+            if (action === "start") {
+                if (!title || applications?.length || outcome)
+                    throw new Error("start requires a short task title and no completion evidence");
+                const task = startReportTask(root, title, task_id);
+                const launcher = verificationLauncher();
+                return { content: [{ type: "text", text: `Task ${task.task_id} · ${task.state}. Pass task_id to every hunch_context and decision/correction/finding capture call. Before the final response, finish with hunch_task and include its contribution card. For checks use this exact installation (the global hunch binary may be stale): ${launcher.shell} task verify ${task.task_id} -- <command> [arguments]. The default budget is 2 minutes; add --timeout <seconds> before -- for a long suite.` }], structuredContent: { task, verification_argv: [...launcher.argv, "task", "verify", task.task_id, "--"] } };
+            }
+            if (!task_id)
+                throw new Error("finish requires the exact task_id");
+            for (const claim of applications ?? [])
+                recordReportClaim(root, task_id, claim);
+            // Hunch's own rule evaluation of the delivered lessons; the agent submits
+            // no verdict. Failure is disclosed by the report and never blocks finish.
+            if ((outcome ?? "completed") === "completed") {
+                try {
+                    runReportConformance(root, getStore(), task_id);
+                }
+                catch { /* unknowns disclose it */ }
+            }
+            finishReportTask(root, task_id, outcome ?? "completed");
+            const report = readTaskReport(root, task_id, reportSourceSnapshot(root).hash);
+            const show = reportPresentationEnabled(root);
+            let file = null;
+            try {
+                file = writeTaskReportHtml(root, task_id);
+            }
+            catch { /* retained report remains inspectable through MCP */ }
+            const card = file ? renderTaskReport(report).replace(/^Evidence .*$/m, `Evidence  [Open local report](<${file}>)`) : renderTaskReport(report);
+            return { content: [{ type: "text", text: show ? card : "Task report retained. Automatic presentation is disabled; omit the contribution card from the final response." }], structuredContent: { ...boundedTaskReportForHost(report), presentation_enabled: show, contribution_card: show ? card : null, report_path: file } };
+        }
+        catch (error) {
+            const message = `Task report unavailable: ${error.message}`;
+            // Some hosts show structuredContent instead of text blocks. Return exact
+            // recovery references there as well; never ask an agent to invent a hash.
+            let references = [];
+            if (task_id) {
+                try {
+                    references = applicationReferences(readTaskReport(getRoot(), task_id));
+                }
+                catch { }
+            }
+            return { isError: true, content: [{ type: "text", text: message }], structuredContent: { error: message, application_references: references, recovery: "For a real application, copy an exact reference and add the action you took. Do not replace receipt prefixes or substitute a scope hash. For full evidence call hunch_report with the exact task ID." } };
+        }
+    });
+    server.registerTool("hunch_report", {
+        title: "Inspect the evidence for Hunch's contribution to a task",
+        description: "Read task reports: exact delivered memory, agent-reported applications, observed command results and explicit unknowns, as a bounded summary (identities and verdicts, not envelope text; the full report is `hunch report <id> --json`). Supply lesson for exact revision history across tasks. With neither task_id nor lesson, lists recent tasks without guessing which is yours. html writes a local private evidence view. Not a causal impact score, public export, or authority to execute verification commands.",
+        inputSchema: { task_id: TaskIdSchema.optional(), lesson: LessonReferenceSchema.optional().describe("Exact kind and record_id, optionally content_hash, to inspect retained appearances across tasks. Partial indexing requires refreshing before pagination."), before: z.number().int().positive().optional(), html: z.boolean().optional(), cwd: z.string().optional() },
+    }, async ({ task_id, lesson, before, html }) => {
+        try {
+            const root = getRoot();
+            if (lesson) {
+                if (task_id || html)
+                    throw new Error("choose lesson history or a task report, not both");
+                const history = readLessonHistory(root, lesson, { before });
+                return { content: [{ type: "text", text: JSON.stringify(history) }], structuredContent: history };
+            }
+            if (before !== undefined)
+                throw new Error("before requires a lesson reference");
+            if (!task_id) {
+                if (html)
+                    throw new Error("html requires an exact task_id");
+                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 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 } };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: `Invalid: ${error.message}` }] };
+        }
+    });
+}
+//# sourceMappingURL=taskReportTools.js.map

package/dist/serve/app.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `hunch serve` — the HTTP binding of nuryel.state/1, and the served product's partition host.
+ *
+ * Folded in from Hunch Memory: bind 127.0.0.1 (the caller's job; never expose a port), a
+ * bearer token that resolves the PRINCIPAL (the body never names one — grants come from the
+ * config, never from the caller), problem+json errors, a body limit, and a cross-process
+ * write lock per partition so a stdio MCP process on the same store cannot race a write.
+ *
+ * Every rule lives in src/store/stateBinding.ts; this file only maps HTTP to it:
+ *   GET  /nuryel/v1/capabilities      → capabilities of the partition named by ?scope=kind:id (default: first granted)
+ *   POST /nuryel/v1/read              → readState; with `scopes` a UNION read: readState per granted
+ *                                       served partition, merged by mergeReadResponses (primary's envelope)
+ *   POST /nuryel/v1/write             → writeState (under the partition's write lock)
+ *   POST /nuryel/v1/subscribe         → subscribeState
+ *   POST /nuryel/v1/records           → recordsState (by id, grants first)
+ * Request bodies are the contract's request schemas minus `schema` and `principal`.
+ */
+import { type Server } from "node:http";
+import { HunchStore } from "../store/hunchStore.js";
+import { type ServeConfig } from "./config.js";
+export declare const BODY_LIMIT_BYTES: number;
+export declare const PROBLEM_TYPE = "https://www.hunchmemory.com/problems/nuryel.state/1/";
+export declare class HttpProblem extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly extra: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, extra?: Record<string, unknown>);
+}
+export interface ServeOptions {
+    version?: string;
+    /** Injectable for tests: how a partition's store is opened. */
+    openStore?: (root: string) => HunchStore;
+}
+export declare function createServeApp(config: ServeConfig, opts?: ServeOptions): Server & {
+    closeStores: () => void;
+};