@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/mcp/server.js

@@ -14,6 +14,8 @@ import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
 import { canonicalRootPath, resolveActiveRoot } from "./roots.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { StateRefusal, SubscribeResponseSchema, capabilities, partitionOf, readState, recordsState, subscribeState, writeState } from "../store/stateBinding.js";
+import { captureState, captureBatchState } from "../store/stateCapture.js";
+import { CaptureRequestSchema, CaptureBatchRequestSchema, CaptureBatchResultSchema, STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION } from "../core/stateContract.js";
 import { ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION, STATE_RECORDS_VERSION, stateHash } from "../core/stateContract.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId, findingId } from "../core/ids.js";
@@ -38,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";
@@ -49,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";
@@ -768,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",
@@ -1030,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.`);
@@ -1096,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", {
@@ -1144,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)."),
         },
@@ -1165,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"));
     });
@@ -1179,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}`, "");
         }
@@ -1369,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
@@ -1508,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
@@ -1521,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.
@@ -1569,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) => {
@@ -1594,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
@@ -1606,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)";
@@ -1650,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.");
@@ -1682,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;
@@ -1727,7 +1781,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     });
     server.registerTool("nuryel_read", {
         title: "nuryel.state/1 read — the system-of-record answer for a subject",
-        description: "Read organizational state under a delivery receipt. Pass the principal (id, kind, grants) and the scope; optionally a subject (an entity id, a decision topic, an external `object_type:object_key`) to get state_of_record — what is current, in force, done, what it depends on and what invalidates it — plus a task phrase for the ranked delivery envelope. Scopes the principal is not granted are named in denied_scopes, never silently dropped.",
+        description: "Read organizational state under a delivery receipt. Pass the principal (id, kind, grants) and the scope; optionally a subject (an entity id, a decision topic, an external `object_type:object_key`) to get state_of_record — what is current, in force, done, what it depends on and what invalidates it — plus a task phrase for the ranked delivery envelope. Scopes the principal is not granted are named in denied_scopes, never silently dropped. To read observations beyond the default 64, use observed_page:{} with one scope and a subject, then pass state_of_record.observed_page.next_cursor as observed_page.cursor until null. A conflict means the observations changed: restart from the first page. Never claim complete coverage while a next cursor remains.",
         inputSchema: ReadRequestSchema.omit({ schema: true }).shape,
         outputSchema: ReadResponseSchema.shape,
     }, async (input) => {
@@ -1735,7 +1789,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, ...input });
             const sor = response.state_of_record;
             const summary = sor
-                ? `subject ${sor.subject}: current ${sor.current.length} · in force ${sor.in_force.length} · done ${sor.done.length} · depends on ${sor.depends_on.length} · invalidated by ${sor.invalidated_by.length}`
+                ? `subject ${sor.subject}: current ${sor.current.length} · in force ${sor.in_force.length} · done ${sor.done.length} · observed ${sor.observed?.length ?? 0} · depends on ${sor.depends_on.length} · invalidated by ${sor.invalidated_by.length}`
                 : "no subject — delivery envelope only";
             const deniedNote = response.denied_scopes.length ? `\ndenied scopes: ${response.denied_scopes.map((s) => `${s.kind}/${s.id}`).join(", ")}` : "";
             // Render the state of record itself, not only its refs: a consumer answers from this text.
@@ -1774,6 +1828,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             };
             const stateText = sor
                 ? [...sor.current.map((r) => line("current", r)), ...sor.in_force.map((r) => line("in force", r)), ...sor.done.map((r) => line("done", r)),
+                    ...(sor.observed ?? []).map(r => line("observed; verify currentness before relying on it", r)),
+                    ...(sor.observed_page ? [`- Observation page: ${sor.observed_page.total} total; next_cursor: ${JSON.stringify(sor.observed_page.next_cursor)}`]
+                        : sor.observed_truncated ? ['- More observations exist; read this subject with observed_page:{} in one partition, then follow next_cursor.'] : []),
                     ...(sor.invalidated_by.length ? [`- invalidated by: ${sor.invalidated_by.join(", ")}`] : [])].join("\n") || "(nothing on record for this subject)"
                 : "";
             return stateResult(`${response.receipt_id} · ${summary}${deniedNote}${stateText ? `\n\nState of record:\n${stateText}` : ""}\n\n${envelope.text}`, response);
@@ -1784,7 +1841,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     });
     server.registerTool("nuryel_write", {
         title: "nuryel.state/1 write — provenance + idempotency in, durability out",
-        description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay.",
+        description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay. To show an existing captured observation under another subject without copying it, write a relationship type observation_about with from=observation id, to=subject, observation_hash, lifecycle=active, reason and hashed external evidence of the explicit association. Retire the relationship to unlink; reactivation requires expected_version.",
         inputSchema: { ...WriteRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
         outputSchema: WriteResultSchema.shape,
     }, async ({ cwd: _cwd, ...input }) => {
@@ -1800,6 +1857,38 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             return stateRefusal(e);
         }
     });
+    server.registerTool("nuryel_capture", {
+        title: "nuryel.state/1 capture — one relevant assertion with exact source excerpts",
+        description: "Save ONE relevant atomic assertion learned during the task. First split mixed source material into independent assertions; check each one, retaining new relevant details inside otherwise known passages. Exclude chatter, speculation, unsupported conclusions and transient tool output. Supply a concrete future-use reason and exact excerpts from the source text. Whole source text is transient and is never stored. Deduplication is per assertion + subject + source excerpt, independent of agent and read time; never skip a whole document because some of it is known. Records are observations, not verified current summaries or execution receipts. Call after substantive learning without waiting for the user to say remember. Read back the returned record before claiming it was saved.",
+        inputSchema: { ...CaptureRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
+        outputSchema: WriteResultSchema.shape,
+    }, async ({ cwd: _cwd, ...input }) => {
+        try {
+            const result = await withWriteLock(hunchPaths(root).hunch, () => captureState(store, { schema: STATE_CAPTURE_VERSION, ...input }, {
+                flush: (isPrivate, message) => flushCapture(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);
+        }
+        catch (e) {
+            return stateRefusal(e);
+        }
+    });
+    server.registerTool("nuryel_capture_batch", {
+        title: "nuryel.state/1 capture batch — save relevant atomic observations",
+        description: "Preferred capture for multiple facts learned during the task. Split source material into independent relevant assertions, select exact supporting excerpts and give each a concrete future-use reason. Exclude chatter, unsupported inference and transient output. Check every assertion even in a known paragraph: deduplication never discards a whole passage. Send each source once and reference its zero-based index. At most 32 observations and 8 sources; split larger work into batches. One partition lock and index update, no extra model call. Results preserve input indexes; inspect every refusal and stored record. Saved observations have unknown currentness, not verified receipts or current summaries. Use your own initiating agent identity automatically after substantive learning. Optional reviews withdraw specific prior observations: supply record_id, expected_hash, a reason, and exact excerpts from a changed source that observation depends on. Mere hash changes, missing text or uncertain interpretation never suffice; the initiating agent must identify explicit contradiction or withdrawal. Original facts remain in history with the review author and evidence. Review results are separately indexed; inspect every refusal.",
+        inputSchema: { ...CaptureBatchRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
+        outputSchema: CaptureBatchResultSchema.shape,
+    }, async ({ cwd: _cwd, ...input }) => {
+        try {
+            const result = await withWriteLock(hunchPaths(root).hunch, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, ...input }, {
+                flush: (isPrivate, message) => flushCapture(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);
+        }
+        catch (e) {
+            return stateRefusal(e);
+        }
+    });
     server.registerTool("nuryel_subscribe", {
         title: "nuryel.state/1 subscribe — the scope's ordered change stream after a cursor",
         description: "Return the change events for a scope with seq > after_seq, strictly ordered. Unfiltered, the events are contiguous (a gap means resynchronize); with facets/subjects filters the response is a subsequence and head_seq is still your next cursor. Each event names the record, its hash, what changed, what it invalidates, and the cause.",

package/dist/mcp/taskReportTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { HunchStore } from "../store/hunchStore.js";
+export declare function registerTaskReportTools(server: McpServer, getRoot: () => string, getStore: () => HunchStore): void;

package/dist/mcp/taskReportTools.js

@@ -0,0 +1,106 @@
+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);
+}
+/** 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].` }], 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: { ...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. 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: { ...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;
+};

package/dist/serve/app.js

@@ -24,6 +24,8 @@ import { STATE_READ_VERSION, STATE_RECORDS_VERSION, STATE_SUBSCRIBE_VERSION, STA
 import { partitionFor, resolvePrincipal } from "./config.js";
 import { WriteLockTimeout, withWriteLock } from "./writelock.js";
 import { HUNCH_VERSION } from "../core/version.js";
+import { captureState, captureBatchState } from "../store/stateCapture.js";
+import { STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION } from "../core/stateContract.js";
 export const BODY_LIMIT_BYTES = 1024 * 1024;
 export const PROBLEM_TYPE = "https://www.hunchmemory.com/problems/nuryel.state/1/";
 export class HttpProblem extends Error {
@@ -148,6 +150,8 @@ export function createServeApp(config, opts = {}) {
             delete body.schema;
             if (url.pathname === "/nuryel/v1/read") {
                 const scope = requireScope(principal, body);
+                if (body.observed_page !== undefined && body.scopes !== undefined)
+                    throw problem(400, 'malformed', 'observation pages require a single partition without scopes');
                 const { store } = storeFor(scope);
                 if (body.scopes === undefined) {
                     const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, principal, ...body });
@@ -178,6 +182,22 @@ export function createServeApp(config, opts = {}) {
                 }));
                 return send(res, result.outcome === "created" ? 201 : 200, result);
             }
+            if (url.pathname === "/nuryel/v1/capture") {
+                const scope = requireScope(principal, body);
+                const { store } = storeFor(scope);
+                const result = await withWriteLock(hunchPaths(store.publicRoot).hunch, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, {
+                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(store.publicRoot).hunch, isPrivate, message),
+                }));
+                return send(res, result.outcome === "created" ? 201 : 200, result);
+            }
+            if (url.pathname === "/nuryel/v1/capture-batch") {
+                const scope = requireScope(principal, body);
+                const { store, root } = storeFor(scope);
+                const result = await withWriteLock(hunchPaths(root).hunch, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, {
+                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
+                }));
+                return send(res, 200, result);
+            }
             if (url.pathname === "/nuryel/v1/subscribe") {
                 const scope = requireScope(principal, body);
                 const { store } = storeFor(scope);

package/dist/serve/config.d.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { type Principal, type Scope } from "../core/stateContract.js";
+export declare const SERVE_CONFIG_VERSION: "nuryel.serve-config/1";
+export declare const PartitionConfigSchema: z.ZodObject<{
+    scope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    root: z.ZodString;
+}, z.core.$strict>;
+export type PartitionConfig = z.infer<typeof PartitionConfigSchema>;
+export declare const PrincipalConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        service: "service";
+        human: "human";
+        agent: "agent";
+    }>;
+    display: z.ZodOptional<z.ZodString>;
+    token_sha256: z.ZodString;
+    grants: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PrincipalConfig = z.infer<typeof PrincipalConfigSchema>;
+export declare const ServeConfigSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"nuryel.serve-config/1">;
+    port: z.ZodDefault<z.ZodNumber>;
+    partitions: z.ZodArray<z.ZodObject<{
+        scope: z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        root: z.ZodString;
+    }, z.core.$strict>>;
+    principals: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            service: "service";
+            human: "human";
+            agent: "agent";
+        }>;
+        display: z.ZodOptional<z.ZodString>;
+        token_sha256: z.ZodString;
+        grants: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ServeConfig = z.infer<typeof ServeConfigSchema>;
+export declare const PARTITION_GITIGNORE: string;
+export declare function hashToken(token: string): string;
+export declare function mintToken(): string;
+export declare function readServeConfig(file: string): ServeConfig & {
+    file: string;
+};
+export declare function writeServeConfig(file: string, config: ServeConfig): void;
+/** Constant-time token → principal. Undefined for a missing or unknown token. */
+export declare function resolvePrincipal(config: ServeConfig, token: string | undefined): Principal | undefined;
+export declare function partitionFor(config: ServeConfig, scope: Scope): PartitionConfig | undefined;
+/** `serve init`: ensure a partition directory declares its scope, and add a principal
+ *  with a freshly minted token. Idempotent for the partition; a principal id that
+ *  already exists gets a NEW token (rotation), the old one stops working. */
+export declare function initServeConfig(opts: {
+    file: string;
+    scope: Scope;
+    root: string;
+    principal?: {
+        id: string;
+        kind: "human" | "agent" | "service";
+        grants?: Scope[];
+    };
+    port?: number;
+}): {
+    config: ServeConfig;
+    token: string | null;
+    partition: PartitionConfig;
+};