@davesheffer/hunch 1.39.1 → 1.39.3

package/dist/mcp/server.js

@@ -12,7 +12,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
+import { hunchPaths, findRoot, toPosixTarget, repoRelativeTarget } from "../core/paths.js";
+import { isIndexedPath, matchSymbolsTiered } from "../core/glob.js";
 import { resolveMcpToolset } from "./toolset.js";
 import { readConfig } from "../core/config.js";
 import { canonicalRootPath, resolveActiveRoot } from "./roots.js";
@@ -24,6 +25,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 +71,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 +395,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 +435,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.",
@@ -436,23 +455,30 @@ function qualityNudge(rec) {
     }
     return "";
 }
-/** Resolve a free-form target (symbol id / name / file path) to symbol records. */
-function resolveSymbols(store, target) {
-    target = toPosixTarget(target);
+/** Resolve a free-form target (symbol id / name / file path) to symbol records.
+ *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
+ *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift
+ *  apart on the same question. */
+export function resolveSymbols(store, target) {
+    // An absolute target (an agent's edit-payload path, verbatim) never matched
+    // the repo-relative stored file paths below (issue #296).
+    target = repoRelativeTarget(target, store.publicRoot);
     const syms = store.json.loadAll("symbols");
-    const byId = syms.find((s) => s.id === target);
-    if (byId)
-        return [byId];
-    const byName = syms.filter((s) => s.name === target);
-    if (byName.length)
-        return byName;
-    return syms.filter((s) => s.file === target || s.file.endsWith(target));
+    const components = store.json.loadAll("components");
+    // A target that IS a real indexed path (has a symbol, or is covered by an
+    // indexed component even with zero symbols — README.md, package.json, ...)
+    // never falls through to the suffix tier: bare `endsWith` matched unrelated
+    // files that merely end in the same characters — "db.ts" matched "mongodb.ts"
+    // (issue #300), and a same-basename file in another directory leaked its
+    // rules onto a real indexed target with no symbols of its own (issue #299).
+    const indexed = isIndexedPath(target, syms.map((s) => s.file), components.map((c) => c.paths));
+    return matchSymbolsTiered(target, syms, indexed);
 }
 /** Resolve a target to canonical indexed file path(s) (for file-granular blast
  *  radius). Falls back to the literal target so direct-scope checks still run. */
-function resolveFiles(store, target) {
+export function resolveFiles(store, target) {
     const files = new Set(resolveSymbols(store, target).map((s) => s.file));
-    return files.size ? [...files] : [toPosixTarget(target)];
+    return files.size ? [...files] : [repoRelativeTarget(target, store.publicRoot)];
 }
 function pullBackoff(status, finishedAt, failures) {
     if (status === "updated" || status === "current") {
@@ -1426,7 +1452,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 +1536,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 +1572,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 +1610,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 +1640,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 +1669,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 +1721,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 +1768,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 +1780,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 +1830,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/serve/writelock.d.ts

@@ -3,11 +3,25 @@
 export declare const STALE_AFTER_MS = 60000;
 /** Longest a writer waits before giving up and telling the caller. */
 export declare const ACQUIRE_TIMEOUT_MS = 10000;
+/** Longest a takeover claim may sit before another contender may clear it. The
+ *  claimed section is a few syscalls, so anything this old means its claimer
+ *  crashed inside it. */
+export declare const CLAIM_STALE_MS = 10000;
 export interface LockOwner {
     pid: number;
     host: string;
     nonce: string;
     at: string;
+    start?: string;
+}
+/** Token seam: the caller's own process-instance token and a probe for another
+ *  pid's, plus the platform the decision table should reason about (the own-pid
+ *  fallback differs on linux, where pid namespaces exist). Injected by tests so
+ *  the identity paths are exercised off linux. */
+export interface StartTokenProbe {
+    self: string | null;
+    of: (pid: number) => string | null;
+    platform?: NodeJS.Platform;
 }
 export declare class WriteLockTimeout extends Error {
     readonly path: string;
@@ -16,7 +30,13 @@ export declare class WriteLockTimeout extends Error {
     constructor(path: string, heldBy: LockOwner | undefined, waitedMs: number);
 }
 export declare function writeLockPath(hunchDir: string): string;
-/** Hold the partition's lock across `fn` (sync or async); released even if it throws. */
+/** Hold the partition's lock across `fn` (sync or async); released even if it throws.
+ *
+ *  `opts.startToken` is an INTERNAL TEST SEAM, not API: it lets the test suite
+ *  drive the process-identity rows of the decision table on a platform that has
+ *  no such identity. Callers outside this repo must leave it unset — the real
+ *  probe (`selfStartToken`/`startTokenOf`) is the only sound one. */
 export declare function withWriteLock<T>(hunchDir: string, fn: () => T | Promise<T>, opts?: {
     timeoutMs?: number;
+    startToken?: StartTokenProbe;
 }): Promise<T>;