@davesheffer/hunch 1.39.1 → 1.39.2

package/dist/mcp/server.js

@@ -24,6 +24,7 @@ import { ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultS
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId, findingId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
+import { confirmCommand } from "../core/countersign.js";
 import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
 import { workspaceLedgerView, renderWorktreeTable, renderBranchTable, workspaceSummaryLine, snapshotHasHome, recordWorkspaceSnapshot, branchRows, worktreeRows } from "../integrations/workspaceLedger.js";
@@ -69,7 +70,7 @@ import { readActivePendingRepairs, withheldRewrites } from "../core/repairqueue.
 import { scanRecord, publicationWarning, loadVocabulary } from "../core/publication.js";
 import { premiseEscalations } from "../core/premises.js";
 import { applyImportedAdrReview, pendingImportedAdrReviews } from "../core/importReview.js";
-import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken } from "../core/capturetoken.js";
+import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken, HUMAN_CONFIRMATION_SCHEMA, isHumanConfirmationAnswer } from "../core/capturetoken.js";
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -393,6 +394,23 @@ function deliveredContext(root, target, envelope, sessionId) {
 // thin wrappers bind the process clock and id source at the call site (§5 Stage 1).
 const issueCaptureToken = () => issueToken(randomUUID, Date.now());
 const consumeCaptureToken = (token) => consumeToken(token, Date.now());
+async function askHumanToConfirm(server, message) {
+    if (!server.server.getClientCapabilities()?.elicitation?.form)
+        return "unavailable";
+    try {
+        const answer = await server.server.elicitInput({ mode: "form", message, requestedSchema: HUMAN_CONFIRMATION_SCHEMA });
+        return isHumanConfirmationAnswer(answer) ? "confirmed" : "declined";
+    }
+    catch {
+        return "unavailable";
+    }
+}
+function unconfirmedReason(c) {
+    return c === "declined"
+        ? "the human did not confirm it in the client prompt"
+        : "this client could not ask the human to confirm it (no MCP form elicitation, or the request failed)";
+}
+const clipForPrompt = (s, max = 400) => (s.length > max ? `${s.slice(0, max - 1)}…` : s);
 /** The interrogation protocol returned by hunch_capture_decision. With `deciding`,
  *  the choice is NOT yet made: the verdict loop runs first so the record's
  *  alternatives_rejected are attacks that actually ran — not post-hoc fiction. */
@@ -416,7 +434,7 @@ function grillingProtocol(topic, token, deciding = false) {
         "1. Grill ONE focused question at a time. Push back on hand-wavy answers. Resolve every branch of the decision tree before committing — an unexamined decision poisons the graph.",
         `2. Confirm the TOPIC anchor with the human before committing${topic ? ` (proposed: "${topic}")` : ""}. Exactly one topic per decision; if it spans two, split into two captures.`,
         "3. Capture REJECTED alternatives explicitly — for each, what it was and why not. This is what makes the decision enforceable (Veto/drift check against it).",
-        `4. Commit with hunch_record_decision, passing capture_token:"${token}" and the confirmed topic. The artifact is the graph write, not prose.`,
+        `4. Commit with hunch_record_decision, passing capture_token:"${token}" and the confirmed topic. The artifact is the graph write, not prose. The token is not a human signature: Hunch asks the human to confirm in the client when the client supports it; otherwise the record stays agent testimony until the human runs the \`hunch review --confirm <id>\` command the response prints.`,
         "5. On CONFLICT with an existing live decision for the topic, do NOT auto-supersede — Hunch refuses and presents both; let the human choose to supersede (link), split the topic, or discard.",
         "",
         "Required before commit: topic, title, decision, context (the rationale/why), alternatives_rejected. Missing any → keep grilling.",
@@ -1426,7 +1444,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_capture_decision (decision-grounding: the grilling front door) --
     server.registerTool("hunch_capture_decision", {
         title: "Capture a decision (grilling interview)",
-        description: "Start a decision-capture interview: returns the grilling protocol (interrogate ONE question at a time until the decision tree is resolved) plus a capture-session token. Grill the human, then commit via hunch_record_decision with the token + confirmed topic. Use for '/capture', 'record this decision', 'grill me on this'. The token proves the write is the tail of an interview, not a silent guess. Returns the protocol text and the token; it writes nothing. Not for corrections (hunch_record_correction) or observations (hunch_record_finding).",
+        description: "Start a decision-capture interview: returns the grilling protocol (interrogate ONE question at a time until the decision tree is resolved) plus a capture-session token. Grill the human, then commit via hunch_record_decision with the token + confirmed topic. Use for '/capture', 'record this decision', 'grill me on this'. The token proves the write is the tail of an interview, not a silent guess — it is NOT a human signature: human-confirmed authority needs the human's own confirmation (a client prompt, or `hunch review --confirm <id>`). Returns the protocol text and the token; it writes nothing. Not for corrections (hunch_record_correction) or observations (hunch_record_finding).",
         inputSchema: {
             topic: z.string().optional().describe("proposed topic anchor (confirm with the human before committing)"),
             seed: z.string().optional().describe("what the decision is about, to focus the first question"),
@@ -1510,7 +1528,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 supersedes: z.string().optional().describe("id of a decision this one replaces — closes its valid-time window (invalidate, don't delete)"),
                 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)."),
+            capture_token: z.string().optional().describe("token from hunch_capture_decision — proves this write is the tail of a grilling interview (not a human signature: Hunch asks the human to confirm in the client when supported). 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,
         },
@@ -1546,32 +1564,36 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             // from the commit) stay upgradeable by a different identity. Same-identity
             // re-record remains the countersign/refine path for every tier.
             const curated = ["human_confirmed", "agent_recorded"].some((t) => existing?.provenance.source.split("+").includes(t));
-            // AUTHORSHIP STAMP (memory supply chain): only a consumed capture token — proof a
-            // grilling interview preceded this write — mints human_confirmed. Any agent can
-            // CALL this tool mid-session, possibly steered by untrusted content it read;
-            // "the human probably asked me to" is testimony, not a signature.
+            // AUTHORSHIP STAMP (memory supply chain): human_confirmed needs a HUMAN act. Any
+            // agent can CALL this tool mid-session, possibly steered by untrusted content it
+            // read; "the human probably asked me to" is testimony, not a signature. A consumed
+            // capture token proves only that hunch_capture_decision was called — also inside
+            // the agent's channel — so it licenses ASKING the human (client elicitation, below)
+            // and nothing more.
             //
-            // Resolved HERE, before the overwrite guard, because the guard's answer depends on
-            // it: testimony must yield to a signature. (Consuming before a possible refusal
-            // burns the token, which is the safe direction — a re-run of /capture mints another.)
+            // Consumed HERE, before the overwrite guard, because the guard's answer depends on
+            // it. (Consuming before a possible refusal burns the token, which is the safe
+            // direction — a re-run of /capture mints another.)
             const gated = consumeCaptureToken(capture_token);
             const existingTiers = existing?.provenance.source.split("+") ?? [];
             const existingIsHuman = existingTiers.includes("human_confirmed");
             // A slot held only by AGENT TESTIMONY must not block a later human capture — the
             // stamp's own contract says so ("never lock the id slot against a later human
-            // capture"), but including agent_recorded in `curated` did exactly that. A
-            // human_confirmed slot stays protected as before (issue #23): a signature is never
-            // displaced by a differently-identified record, vouched or not.
-            const conflictsWithHuman = curated && !sameHumanIdentity && !(gated && !existingIsHuman);
-            if (conflictsWithHuman) {
-                return refused(`Decision id ${id} already identifies a different curated decision: ` +
-                    `"${existing.title}"${existing.topic ? ` (topic "${existing.topic}")` : ""}. ` +
-                    `Refusing to overwrite it with "${decision.title}"${decision.topic ? ` (topic "${decision.topic}")` : ""}. ` +
-                    "Record the additional decision without commit, or reuse the incumbent topic/title when refining the same decision.");
-            }
+            // capture"). A human_confirmed slot stays protected as before (issue #23): a
+            // signature is never displaced by a differently-identified record, vouched or not.
+            // Testimony yields only to a HUMAN-CONFIRMED write, so an un-tokened write is
+            // refused now and a tokened one is refused below unless the human confirms.
+            const slotConflict = curated && !sameHumanIdentity;
+            const slotRefusal = () => refused(`Decision id ${id} already identifies a different curated decision: ` +
+                `"${existing.title}"${existing.topic ? ` (topic "${existing.topic}")` : ""}. ` +
+                `Refusing to overwrite it with "${decision.title}"${decision.topic ? ` (topic "${decision.topic}")` : ""}. ` +
+                "Record the additional decision without commit, or reuse the incumbent topic/title when refining the same decision.");
+            if (slotConflict && (existingIsHuman || !gated))
+                return slotRefusal();
             // Un-token'd writes land as agent_recorded: fully functional advisory memory that
             // never carries human authority (strict/veto gates key on human_confirmed) and
-            // surfaces with a testimony marker. Re-record through /capture to countersign.
+            // surfaces with a testimony marker. A human countersigns it (client prompt during
+            // /capture, or `hunch review --confirm <id>`).
             //
             // A signature already on this slot is INHERITED, never erased. The un-token'd path
             // is exactly what the nudge below tells an agent to do ("re-record… supersedes"),
@@ -1580,10 +1602,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             // human had vouched for. That inverts the whole point of the stamp: it exists to
             // stop an agent CLAIMING human authority, not to let one DESTROY it. Downgrading a
             // signature is a human act (`hunch review --reject`, or supersede via /capture).
-            const tier = gated || existingIsHuman ? "human_confirmed" : "agent_recorded";
-            const source = existing && existing.provenance.source.includes("llm_draft")
-                ? `llm_draft+${tier}`
-                : tier;
+            // The tier is resolved after the refusal guards below (it may need the human's
+            // answer), so `rec` carries a placeholder provenance until then.
             const now = new Date().toISOString();
             const rec = {
                 id,
@@ -1612,7 +1632,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 valid_from: existing?.valid_from ?? now,
                 valid_to: existing?.valid_to ?? null,
                 retired: existing?.retired ?? { symbols: [], deps: [] },
-                provenance: { source, confidence: gated ? 0.95 : 0.75, evidence: (decision.related_files ?? existing?.provenance.evidence ?? []).map(toPosixTarget) },
+                provenance: { source: "agent_recorded", confidence: 0.75, evidence: (decision.related_files ?? existing?.provenance.evidence ?? []).map(toPosixTarget) },
                 date: now,
             };
             // Where this write will actually land (see captureHome). Resolved BEFORE the
@@ -1641,6 +1661,31 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                         `re-record with supersedes:<id> to replace it (linked, same store), pick a distinct topic to split, or discard this capture.`);
                 }
             }
+            // Human confirmation: asked only for a tokened write (the /capture tail — never
+            // prompt-spam every agent write), only after every refusal guard has passed (never
+            // ask a human to confirm a write that is then refused), and only through the client
+            // UI, a channel the agent does not control.
+            const confirmation = gated
+                ? await askHumanToConfirm(server, [
+                    "Hunch: an agent is recording this engineering decision on your behalf. Confirm only if YOU made this decision.",
+                    "",
+                    `Title: ${clipForPrompt(rec.title, 200)}`,
+                    ...(rec.topic ? [`Topic: ${rec.topic}`] : []),
+                    `Status: ${rec.status}`,
+                    `Decision: ${clipForPrompt(rec.decision || "(none)")}`,
+                    ...(rec.alternatives_rejected.length ? [`Rejected: ${clipForPrompt(rec.alternatives_rejected.join("; "))}`] : []),
+                    "",
+                    "Confirmed, it carries your authority (human_confirmed). Unconfirmed, it is kept as agent testimony.",
+                ].join("\n"))
+                : null;
+            const humanSigned = confirmation === "confirmed";
+            if (slotConflict && !humanSigned)
+                return slotRefusal();
+            const tier = humanSigned || existingIsHuman ? "human_confirmed" : "agent_recorded";
+            const source = existing && existing.provenance.source.includes("llm_draft")
+                ? `llm_draft+${tier}`
+                : tier;
+            rec.provenance = { ...rec.provenance, source, confidence: humanSigned ? 0.95 : 0.75 };
             // Route the write to its ONE home: an explicit private:true goes to the overlay
             // (putPrivate throws rather than silently falling public); in unified ("shared")
             // mode EVERY capture goes to the overlay; else the public store.
@@ -1668,16 +1713,19 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             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.
-            // A token presented but unknown to THIS process (server restart/expiry) is
-            // not shamed — but it also cannot be VERIFIED, so the record still lands
-            // agent_recorded with a note saying how to countersign.
-            const captureNote = gated
-                ? " [via capture front door]"
-                : capture_token
-                    ? `\n\nℹ The capture token could not be verified (server restart or expiry), so this record is stamped agent_recorded. Re-record through hunch_capture_decision → hunch_record_decision to countersign it as human_confirmed.`
-                    : `\n\n⚠ Recorded WITHOUT a capture interview — the record stands as agent_recorded TESTIMONY (advisory: it never carries human authority; a /capture interview on the same topic/title countersigns it). Harden it NOW in one exchange instead of switching flows: answer the first grilling question directly — "What alternative did you seriously consider and reject for '${rec.title.slice(0, 60)}', and what breaks if a future session re-introduces it?" — then fold the answer into alternatives_rejected via a /capture interview (hunch_capture_decision → hunch_record_decision(supersedes: ${id})), which countersigns the record as human_confirmed. (A future major version will require a capture token here.)`;
+            // above. No token still writes (non-breaking) but lands as agent_recorded with a
+            // nudge toward /capture. A token — verified or not — is never a signature: only
+            // the human's confirmation (client prompt or `hunch review --confirm`) is.
+            const confirmCmd = confirmCommand(id, { private: home === "private" });
+            const captureNote = humanSigned
+                ? " [via capture front door — confirmed by the human in the client]"
+                : existingIsHuman
+                    ? " [the existing human signature on this record is retained]"
+                    : gated
+                        ? `\n\nℹ Interview recorded, but a capture token is not a human signature and ${unconfirmedReason(confirmation)}, so this record stands as agent_recorded TESTIMONY (advisory; it never carries human authority). The human confirms it by running: ${confirmCmd}`
+                        : capture_token
+                            ? `\n\nℹ The capture token could not be verified (server restart or expiry), so this record is stamped agent_recorded. The human confirms it by running: ${confirmCmd}`
+                            : `\n\n⚠ Recorded WITHOUT a capture interview — the record stands as agent_recorded TESTIMONY (advisory: it never carries human authority). Harden it NOW in one exchange instead of switching flows: answer the first grilling question directly — "What alternative did you seriously consider and reject for '${rec.title.slice(0, 60)}', and what breaks if a future session re-introduces it?" — then fold the answer into alternatives_rejected via a /capture interview (hunch_capture_decision → hunch_record_decision(supersedes: ${id})). Human authority needs the human's own confirmation: the client prompt during /capture, or \`${confirmCmd}\`. (A future major version will require a capture token here.)`;
             // Quality nudge only when the untokened deprecation nudge isn't already
             // grilling — one advisory voice per response, never two.
             const quality = gated || capture_token ? qualityNudge(rec) : "";
@@ -1712,7 +1760,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             rationale: z.string().optional().describe("Why it must hold."),
             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'."),
+            capture_token: z.string().optional().describe("token from hunch_capture_decision. The rule is recorded and enforced either way, as agent testimony capped at severity 'warning'. A token never lets it DENY: blocking authority comes only from a human running the printed `hunch review --confirm <id> --severity <s>` command."),
             task_id: TaskIdSchema.optional().describe("Exact task ID for observing this successful save; reporting never changes capture authority."),
             cwd: cwdHintField,
         },
@@ -1724,19 +1772,28 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             // paths (edit-tool payloads and MCP roots are absolute) and every consumer matches
             // repo-relative — without this the rule would be blocking-but-inert and would leak
             // the local filesystem path into the committed graph.
-            // Same authorship tier as hunch_record_decision: a consumed token mints the
-            // signature, an un-token'd write is testimony. Here the stakes are HIGHER — a
-            // blocking constraint DENIES edits, so an un-vouched write is capped at
-            // "warning" rather than being refused. Never Twice still lands immediately.
-            const vouched = consumeCaptureToken(input.capture_token);
-            const rec = buildCorrectionConstraint({ ...input, knownDeps: knownRepoDeps(root), root, vouched }, new Date().toISOString());
+            // AUTHORSHIP TIER. A correction recorded through MCP is ALWAYS agent testimony: a
+            // capture token (callable and consumable by any agent) proves only that the
+            // interview tool was called, and an in-client confirmation is not used here either.
+            // The stakes are higher than for a decision — a blocking constraint DENIES edits
+            // (the edit hook keys on severity alone) and fails strict checks — so blocking
+            // authority comes only from a human running `hunch review --confirm <id> --severity <s>`
+            // outside the agent channel. The write is capped below blocking rather than refused:
+            // Never Twice still lands immediately and is surfaced at edit time and in CI.
+            const gated = consumeCaptureToken(input.capture_token);
+            const now = new Date().toISOString();
+            const knownDeps = knownRepoDeps(root);
+            // What a human confirmation would grant: the severity the caller requested, after
+            // the repo-wide scope guard.
+            const requested = buildCorrectionConstraint({ ...input, knownDeps, root, vouched: true }, now);
             // Private corrections go to the overlay (enforced locally via the merged read,
             // never rendered into the public CI comment, which is public-only by construction).
             const home = store.captureHome(!!input.private);
-            if (home === "public" && rec.source_decision && !store.json.get("decisions", rec.source_decision)) {
-                const location = store.getPrivateRec("decisions", rec.source_decision) ? "exists only in the private overlay" : "does not exist in the public home";
-                return refused(`source decision ${rec.source_decision} ${location}; refusing to record public correction ${rec.id}.`);
+            if (home === "public" && requested.source_decision && !store.json.get("decisions", requested.source_decision)) {
+                const location = store.getPrivateRec("decisions", requested.source_decision) ? "exists only in the private overlay" : "does not exist in the public home";
+                return refused(`source decision ${requested.source_decision} ${location}; refusing to record public correction ${requested.id}.`);
             }
+            const rec = buildCorrectionConstraint({ ...input, knownDeps, root, vouched: false }, now);
             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.
             const stored = store.putCapture("constraints", rec, !!input.private);
@@ -1765,11 +1822,13 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const reviewNote = "\n\nREVIEW PENDING: After the fix is committed, run hunch index; an installed post-commit hook retries this automatically on the fixing commit. Only the supported static ESM import-declaration package projection is eligible, and it remains activation-blocked; the immediate guard is already durable.";
             // Say plainly which tier this landed in. A silent downgrade would be its own
             // dishonesty: the caller asked for "blocking" and must be told it is not.
-            const tierNote = vouched
-                ? ""
-                : `
+            const capped = requested.severity !== rec.severity;
+            const why = gated
+                ? "Recorded after a capture interview, but a capture token is not a human signature"
+                : "Recorded WITHOUT a capture interview or a human confirmation";
+            const tierNote = `
 
-⚠ Recorded WITHOUT a capture interview — this rule is agent_recorded TESTIMONY${input.severity === "blocking" ? ' and was capped from "blocking" to "warning"' : ""}. It IS enforced: the pre-edit hook and CI surface it on every matching edit from now on. What it cannot do is DENY an edit — only a rule a human countersigned may block. Countersign it by re-recording through hunch_capture_decision → hunch_record_correction(capture_token).`;
+⚠ ${why} — this rule is agent_recorded TESTIMONY${capped ? ` and was capped from "${requested.severity}" to "${rec.severity}"` : ""}. It IS enforced: the pre-edit hook and CI surface it on every matching edit from now on. What it cannot do is DENY an edit — only a rule a human confirmed outside the agent channel may block. The human confirms it by running: ${confirmCommand(rec.id, { private: home === "private", severity: requested.severity })}`;
             const dest = destinationNote(resolveDestRoot(home, store, root));
             return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where}${dest} It now ${enforce}.${reviewNote}${tierNote}`);
         }

package/dist/serve/app.d.ts

@@ -34,6 +34,10 @@ export interface ServeOptions {
     version?: string;
     /** Injectable for tests: how a partition's store is opened. */
     openStore?: (root: string) => HunchStore;
+    /** Server-side log line sink for 5xx specifics; defaults to stderr. */
+    log?: (line: string) => void;
+    /** Injectable for tests: how long a write waits for its partition's lock. */
+    writeLockTimeoutMs?: number;
 }
 export declare function createServeApp(config: ServeConfig, opts?: ServeOptions): Server & {
     closeStores: () => void;

package/dist/serve/app.js

@@ -93,6 +93,7 @@ function parseScopeParam(value) {
 }
 export function createServeApp(config, opts = {}) {
     const version = opts.version ?? HUNCH_VERSION;
+    const writeLockTimeoutMs = opts.writeLockTimeoutMs;
     const configFile = config.file;
     const authStateDir = opts.authStateDir ?? (configFile ? resolve(configFile + ".auth") : undefined);
     const stores = new Map();
@@ -125,19 +126,26 @@ export function createServeApp(config, opts = {}) {
     };
     const problemBody = (p) => ({ type: `${PROBLEM_TYPE}${p.code}`, title: p.code, status: p.status, detail: p.message, ...p.extra });
     const sendProblem = (res, p) => { send(res, p.status, problemBody(p), "application/problem+json"); };
-    /** Anything thrown → problem. Shared by REST (problem+json) and MCP (tool error results). */
+    const log = opts.log ?? ((line) => { process.stderr.write(`${line}\n`); });
+    /** Anything thrown → problem. Shared by REST (problem+json) and MCP (tool error results).
+     *  A contract refusal (4xx) explains itself to the caller. A server-side failure (5xx) does
+     *  not: its message can name lock paths, PIDs, host names or store paths, so the caller gets
+     *  a generic detail and the specifics go to the server log only. */
     const problemOf = (error) => {
         if (error instanceof HttpProblem)
             return error;
         if (error instanceof StateRefusal)
             return problem(REFUSAL_STATUS[error.code], error.code, error.message, error.conflict ? { conflict: error.conflict } : {});
-        if (error instanceof WriteLockTimeout)
-            return problem(503, "write-lock-timeout", error.message, { "retry-after": 1 });
+        if (error instanceof WriteLockTimeout) {
+            log(`hunch serve: 503 write-lock-timeout: ${error.message}`);
+            return problem(503, "write-lock-timeout", "the partition is busy with another write; retry shortly", { "retry-after": 1 });
+        }
         if (error && typeof error === "object" && error.name === "ZodError") {
             const issues = (error.issues ?? []).map((i) => `${i.path.join(".") || "request"}: ${i.message}`);
             return problem(400, "malformed", `request is malformed: ${issues.join("; ")}`, { issues });
         }
-        return problem(500, "internal", error.message);
+        log(`hunch serve: 500 internal: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+        return problem(500, "internal", "internal server error");
     };
     /** One authenticated state verb. The REST routes and the MCP tools both call this, so every
      *  rule — grants, the write lock, flushes, refusals — is the same whichever transport carried it. */
@@ -191,20 +199,53 @@ export function createServeApp(config, opts = {}) {
         if (route === "write" || route === "capture" || route === "capture-batch") {
             const { hunchDir } = stateHomeFor(store, scope);
             const opts = { ...accessOptions, flush };
+            const lockOptions = { timeoutMs: writeLockTimeoutMs };
             if (route === "write") {
-                const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, opts));
+                const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, opts), lockOptions);
                 return { status: result.outcome === "created" ? 201 : 200, payload: result };
             }
             if (route === "capture") {
-                const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, opts));
+                const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, opts), lockOptions);
                 return { status: result.outcome === "created" ? 201 : 200, payload: result };
             }
-            return { status: 200, payload: await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, opts)) };
+            return { status: 200, payload: await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, opts), lockOptions) };
         }
         if (route === "subscribe")
             return { status: 200, payload: subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, principal, ...body }, accessOptions) };
         return { status: 200, payload: recordsState(store, { schema: STATE_RECORDS_VERSION, principal, ...body }, accessOptions) };
     };
+    /** The bearer/DPoP credential → the principal. Every authenticated route, and health when a
+     *  credential is presented, goes through this one check. */
+    const authenticate = async (req, res, url, activeConfig) => {
+        const authorization = /^(Bearer|DPoP) ([^\s]+)$/i.exec(req.headers.authorization ?? '');
+        const credential = resolveCredential(activeConfig, authorization?.[2]);
+        if (!credential)
+            throw problem(401, 'unauthorized', 'valid credentials are required');
+        const countHeader = (name) => req.rawHeaders.filter((header, index) => index % 2 === 0 && header.toLowerCase() === name).length;
+        if (countHeader('authorization') !== 1 || countHeader('dpop') > 1)
+            throw problem(401, 'invalid_dpop_proof', 'ambiguous authentication headers');
+        if (credential.proof_key) {
+            if (authorization[1].toLowerCase() !== 'dpop')
+                throw problem(401, 'invalid_dpop_proof', 'this credential requires DPoP proof; bearer fallback is disabled');
+            if (!activeConfig.public_origin || !authStateDir)
+                throw problem(503, 'proof-state-unavailable', 'key-bound authentication requires a public origin and persistent proof state');
+            try {
+                await verifyStateProof({ proof: typeof req.headers.dpop === 'string' ? req.headers.dpop : undefined, key: credential.proof_key, method: req.method ?? '', url: activeConfig.public_origin + url.pathname, token: authorization[2], stateDir: authStateDir });
+            }
+            catch (error) {
+                if (error instanceof StateProofError) {
+                    res.setHeader('WWW-Authenticate', `DPoP error="${error.code}", algs="EdDSA"`);
+                    if (error.nonce)
+                        res.setHeader('DPoP-Nonce', error.nonce);
+                    throw problem(401, error.code, error.message);
+                }
+                throw problem(503, 'proof-state-unavailable', 'proof replay state is unavailable; authentication is refused');
+            }
+        }
+        else if (authorization[1].toLowerCase() !== 'bearer' || req.headers.dpop !== undefined)
+            throw problem(401, 'invalid_dpop_proof', 'credential is not bound to a proof key');
+        return { id: credential.id, kind: credential.kind, grants: credential.grants, ...(credential.display ? { display: credential.display } : {}) };
+    };
     const server = createServer(async (req, res) => {
         try {
             let activeConfig;
@@ -222,36 +263,15 @@ export function createServeApp(config, opts = {}) {
                 return res.end(asset[0]);
             }
             if (url.pathname === "/nuryel/v1/health" && req.method === "GET") {
-                return send(res, 200, { ok: true, version, protocol: "nuryel.state/1", partitions: activeConfig.partitions.map((p) => scopePath(p.scope)) });
-            }
-            const authorization = /^(Bearer|DPoP) ([^\s]+)$/i.exec(req.headers.authorization ?? '');
-            const credential = resolveCredential(activeConfig, authorization?.[2]);
-            if (!credential)
-                throw problem(401, 'unauthorized', 'valid credentials are required');
-            const countHeader = (name) => req.rawHeaders.filter((header, index) => index % 2 === 0 && header.toLowerCase() === name).length;
-            if (countHeader('authorization') !== 1 || countHeader('dpop') > 1)
-                throw problem(401, 'invalid_dpop_proof', 'ambiguous authentication headers');
-            if (credential.proof_key) {
-                if (authorization[1].toLowerCase() !== 'dpop')
-                    throw problem(401, 'invalid_dpop_proof', 'this credential requires DPoP proof; bearer fallback is disabled');
-                if (!activeConfig.public_origin || !authStateDir)
-                    throw problem(503, 'proof-state-unavailable', 'key-bound authentication requires a public origin and persistent proof state');
-                try {
-                    await verifyStateProof({ proof: typeof req.headers.dpop === 'string' ? req.headers.dpop : undefined, key: credential.proof_key, method: req.method ?? '', url: activeConfig.public_origin + url.pathname, token: authorization[2], stateDir: authStateDir });
-                }
-                catch (error) {
-                    if (error instanceof StateProofError) {
-                        res.setHeader('WWW-Authenticate', `DPoP error="${error.code}", algs="EdDSA"`);
-                        if (error.nonce)
-                            res.setHeader('DPoP-Nonce', error.nonce);
-                        throw problem(401, error.code, error.message);
-                    }
-                    throw problem(503, 'proof-state-unavailable', 'proof replay state is unavailable; authentication is refused');
-                }
+                // Liveness is public (a load balancer or proxy probe holds no token). Which
+                // partitions this server hosts is not: their ids name people and organizations.
+                const liveness = { ok: true, version, protocol: "nuryel.state/1" };
+                if (req.headers.authorization === undefined && req.headers.dpop === undefined)
+                    return send(res, 200, liveness);
+                await authenticate(req, res, url, activeConfig);
+                return send(res, 200, { ...liveness, partitions: activeConfig.partitions.map((p) => scopePath(p.scope)) });
             }
-            else if (authorization[1].toLowerCase() !== 'bearer' || req.headers.dpop !== undefined)
-                throw problem(401, 'invalid_dpop_proof', 'credential is not bound to a proof key');
-            const principal = { id: credential.id, kind: credential.kind, grants: credential.grants, ...(credential.display ? { display: credential.display } : {}) };
+            const principal = await authenticate(req, res, url, activeConfig);
             if (url.pathname === "/nuryel/v1/capabilities" && req.method === "GET") {
                 const scope = parseScopeParam(url.searchParams.get("scope"));
                 const { status, payload } = await dispatch("capabilities", principal, scope ? { scope } : {}, activeConfig);

package/dist/store/stateBinding.js

@@ -275,15 +275,18 @@ export function readState(store, input, options = {}) {
             }
         if (facets.has("derived"))
             for (const d of store.recs("derived")) {
+                // Match the subject BEFORE admit, as every other facet does: admit names an ungranted
+                // partition in denied_scopes, and only a record that matches may name its partition.
+                // A linked observation must sit in the request's (granted) partition, so it never names one.
+                const direct = isSubject(d.subject) || d.id === subject;
+                const linked = scopePath(recordScope(d, repo)) === scopePath(request.scope) && linkedObservations.get(d.id)?.has(stateHash(d));
+                if (!direct && !linked)
+                    continue;
                 const scope = admit("derived", d);
                 if (!scope)
                     continue;
                 if (request.observed_page && scopePath(scope) !== scopePath(request.scope))
                     continue;
-                const direct = isSubject(d.subject) || d.id === subject;
-                const linked = scopePath(scope) === scopePath(request.scope) && linkedObservations.get(d.id)?.has(stateHash(d));
-                if (!direct && !linked)
-                    continue;
                 if (!direct) {
                     if (d.state === "unknown" && d.valid_to == null)
                         observations.push(d);
@@ -725,7 +728,17 @@ function writeStateAuthorized(store, input, opts, access) {
     catch (e) {
         throw new StateRefusal(/grants/.test(e.message) ? "outside-grants" : "malformed", e.message);
     }
+    const repo = partitionOf(store);
+    // Legacy kinds carry no partition scope: whatever home they land in, every reader (and the
+    // repository's edit gate) treats them as the store's OWN partition. Written under any other
+    // scope they would silently become that partition's records, so they are refused instead.
+    if (LEGACY_FACETS.has(request.facet) && scopePath(request.scope) !== scopePath(repo)) {
+        throw new StateRefusal("unsupported", `${request.facet} records belong to this store's own partition ${scopePath(repo)}; they cannot be written under ${scopePath(request.scope)} — use a partition-scoped facet (conventions, receipts, commitments, derived, entities, relationships) there`);
+    }
     const { home, hunchDir, isPrivate } = stateHomeFor(store, request.scope);
+    /** Several partitions share one overlay home: a record counts for this write only when it is
+     *  in the write's own partition. */
+    const inScope = (r) => scopePath(recordScope(r, repo)) === scopePath(request.scope);
     const now = (opts.now ?? (() => new Date()))().toISOString();
     const facet = request.facet;
     const getHere = (id) => facet === "derived" || facet === "receipts" || facet === "commitments"
@@ -765,6 +778,10 @@ function writeStateAuthorized(store, input, opts, access) {
     const incumbent = getHere(String(record.id));
     if (incumbent && !access.canWrite(incumbent))
         deny();
+    // An id not derived from its scope (an entity, a relationship) can collide with another
+    // partition's record in a shared home: that record is never rewritten from this partition.
+    if (incumbent && !inScope(incumbent))
+        throw new StateRefusal("conflict", `${id} is on record in ${scopePath(recordScope(incumbent, repo))}, not ${scopePath(request.scope)}: a write never moves or rewrites another partition's record`, { incumbent_id: id, reason: "record id held by another partition" });
     const previousVisibility = incumbent?.visibility;
     const nextVisibility = record.visibility;
     if (nextVisibility && home === 'private')
@@ -774,6 +791,10 @@ function writeStateAuthorized(store, input, opts, access) {
     if (supersededRecord) {
         if (!access.canWrite(supersededRecord))
             deny();
+        // Supersession stays inside one partition: closing another partition's record from here would
+        // land its `superseded` event in THIS ledger, invisible to that partition's subscribers.
+        if (!inScope(supersededRecord))
+            throw new StateRefusal("conflict", `supersedes ${request.supersedes} is on record in ${scopePath(recordScope(supersededRecord, repo))}, not ${scopePath(request.scope)}: a write supersedes only a record in its own partition`, { incumbent_id: String(supersededRecord.id), reason: "supersede target in another partition" });
         if (stateHash(supersededVisibility ?? null) !== stateHash(nextVisibility ?? null)) {
             if (supersededVisibility ? supersededVisibility.owner !== request.principal.id : request.principal.kind !== 'human')
                 deny();
@@ -921,7 +942,7 @@ function writeStateAuthorized(store, input, opts, access) {
             }
         }
     }
-    if (supersedes && !store.recsInHome(facet, home).some((r) => r.id === supersedes)) {
+    if (supersedes && !store.recsInHome(facet, home).some((r) => r.id === supersedes && inScope(r))) {
         throw new StateRefusal("conflict", `supersedes ${supersedes} is not a ${facet} record in this partition`, { incumbent_id: supersedes, reason: "supersede target absent" });
     }
     if (supersedes === id)
@@ -935,7 +956,7 @@ function writeStateAuthorized(store, input, opts, access) {
         if (incumbent && "valid_to" in incumbent && incumbent.valid_to !== null) {
             const subject = subjectOf(facet, incumbent);
             const open = store.recsInHome(facet, home)
-                .filter((r) => subjectOf(facet, r) === subject && r.valid_to === null)
+                .filter((r) => inScope(r) && subjectOf(facet, r) === subject && r.valid_to === null)
                 .map((r) => r.id).sort();
             if (!open.includes(id)) {
                 const current = open.length ? `the current ${facet} record for ${subject ?? "that subject"} is ${open.join(", ")}` : `no ${facet} record for ${subject ?? "that subject"} is open now`;
@@ -954,7 +975,7 @@ function writeStateAuthorized(store, input, opts, access) {
         const d = record;
         const incumbent = store.recsInHome("derived", home).find((r) => {
             const x = r;
-            return x.id !== id && x.id !== supersedes && x.subject === d.subject && x.transform_version === d.transform_version && x.state === "current" && x.valid_to === null;
+            return x.id !== id && x.id !== supersedes && inScope(x) && x.subject === d.subject && x.transform_version === d.transform_version && x.state === "current" && x.valid_to === null;
         });
         if (incumbent) {
             throw new StateRefusal("conflict", `${d.subject} already has a current ${d.transform_version} statement ${incumbent.id}; pass supersedes: "${incumbent.id}" to replace it, or write that identity to update it`, { incumbent_id: incumbent.id, reason: "one-current-derived-per-subject-transform" });

package/dist/wiki/wiki.d.ts

@@ -146,7 +146,14 @@ export interface NowItem {
     date: string;
     /** decision text for recent items; CONTEXT (the why-it's-planned) for roadmap items. */
     note: string;
+    /** Roadmap only: true when the item is agent testimony no human has confirmed yet.
+     *  Omitted (never false) otherwise, so pages rendered before this field stay fresh. */
+    unconfirmed?: true;
 }
+/** Marker for an unconfirmed roadmap item, naming the human countersign command. */
+export declare function unconfirmedRoadmapMarker(item: Pick<NowItem, "id" | "unconfirmed">, opts?: {
+    private?: boolean;
+}): string;
 /** The hot view's inputs: last `recentLimit` decisions by date (any status — a
  *  supersession IS activity), and every live PROPOSED decision (the roadmap:
  *  record intent as a proposed decision; accepting or superseding it removes it