@davesheffer/hunch 1.39.0 → 1.39.2

package/dist/integrations/workspaceLedger.js

@@ -9,14 +9,14 @@
  * funnel as every other record: the overlay when one is configured, the public .hunch/
  * only when `workspaces.publish_public` opts in, nothing otherwise.
  */
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { foreignRepoEnv, mainWorktreeRoot } from "../extractors/git.js";
 import { hunchPaths } from "../core/paths.js";
 import { readConfig, workspacesConfig } from "../core/config.js";
 import { loadOrCreateMachine } from "../core/machine.js";
-import { ago, branchRows, isSafeBranchName, latestPerMachine, isUnverified, planPrune, sameWorkspaceContent, withPublishMode, worktreeRows, } from "../core/workspace.js";
-import { snapshotWorkspace } from "../extractors/workspaces.js";
+import { CONTROL_CHARS, ago, branchRows, isSafeBranchName, latestPerMachine, isUnverified, planPrune, sameWorkspaceContent, withPublishMode, worktreeRows, } from "../core/workspace.js";
+import { ignoredPaths, snapshotWorkspace } from "../extractors/workspaces.js";
 import { flushCapture } from "./sync.js";
 export function workspaceLedgerView(store, root, opts = {}) {
     const machine = loadOrCreateMachine();
@@ -95,7 +95,7 @@ export function renderBranchTable(view, rows) {
         r.machines.join(","),
         r.worktree_on.length ? r.worktree_on.join(",") + (r.dirty_on.length ? " (dirty)" : "") : "-",
         describeUpstream(r),
-        r.merged.status === "merged" ? `yes (${r.merged.method}${r.merged.pr ? `, PR #${r.merged.pr}` : ""})` : r.merged.status === "unmerged" ? "no" : "unknown",
+        r.merged.status === "merged" ? `yes (${r.merged.method}${r.merged.pr ? `, PR #${r.merged.pr}` : ""})` : r.merged.status === "unmerged" ? "no" : r.merged.status === "no-commits" ? "no commits" : "unknown",
         r.action,
     ]));
     const deletable = rows.filter((r) => r.action.startsWith("delete local")).length;
@@ -123,15 +123,97 @@ export { branchRows, worktreeRows };
 // record), with `git worktree remove` (no --force) and `git branch -d` (no -D), so git itself
 // re-checks "clean" and "merged" as a second line of defense. Nothing here touches a remote
 // or another machine; their commands are printed for a human to run there.
-export function prunePlanFor(view) {
-    return planPrune(view.live, view.records);
+/** This machine's plan: the pure plan from the live record, then two live checks per step.
+ *  A step `git branch -d` would refuse is moved to `skipped` BEFORE anything runs (removing
+ *  the worktree and then failing the branch delete would half-apply the step), and a
+ *  worktree's ignored files — which `git worktree remove` deletes without asking — are
+ *  attached so the plan and the confirmation name them. */
+export function prunePlanFor(view, root) {
+    const plan = planPrune(view.live, view.records);
+    const local = [];
+    for (const step of plan.local) {
+        const refusal = branchDeleteRefusal(root, step);
+        if (refusal) {
+            plan.skipped.push({ branch: step.branch, reason: refusal });
+            continue;
+        }
+        if (step.worktree?.path) {
+            const ignored = ignoredPaths(step.worktree.path);
+            if (ignored === null) {
+                plan.skipped.push({ branch: step.branch, reason: "the worktree's ignored files could not be listed" });
+                continue;
+            }
+            if (ignored.total)
+                step.ignored = ignored;
+        }
+        local.push(step);
+    }
+    plan.local = local;
+    return plan;
+}
+function gitEnv() {
+    return { ...foreignRepoEnv(process.env), GIT_OPTIONAL_LOCKS: "0" };
+}
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+/** Why `git branch -d -- <branch>` would refuse right now, or null when it would delete.
+ *  Mirrors git's own rule (builtin/branch.c `branch_merged`): the branch head must be an
+ *  ancestor of its upstream when one is configured AND resolves, otherwise of HEAD of the
+ *  worktree the command runs in (the main worktree). Squash and rebase merges never pass it
+ *  once the upstream is gone or unset, so such a step is reported, not half-applied. The
+ *  branch name is matched in JS; only refs git printed and SHAs reach git as arguments. */
+export function branchDeleteRefusal(root, step) {
+    const main = mainWorktreeRoot(root);
+    const env = gitEnv();
+    const read = (args) => {
+        try {
+            return execFileSync("git", args, { cwd: main, env, encoding: "utf8", timeout: 30_000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    const unchecked = "git branch -d precondition could not be checked; nothing was changed";
+    const refs = read(["for-each-ref", "--format=%(refname)%00%(objectname)%00%(upstream)", "refs/heads/"]);
+    if (refs === null)
+        return unchecked;
+    const entry = refs.split("\n").map((line) => line.split("\0")).find(([ref]) => ref === `refs/heads/${step.branch}`);
+    if (!entry)
+        return "branch no longer exists";
+    const [, head = "", upstream = ""] = entry;
+    if (head !== step.head)
+        return `branch moved since the snapshot (now ${head.slice(0, 12)})`;
+    let reference = null;
+    let referenceName = "HEAD";
+    if (upstream.startsWith("refs/")) {
+        const resolved = read(["rev-parse", "--verify", "-q", "--end-of-options", `${upstream}^{commit}`]);
+        if (resolved && SHA.test(resolved)) {
+            reference = resolved;
+            referenceName = upstream.replace(/^refs\/(?:remotes|heads)\//, "");
+        }
+    }
+    if (!reference) {
+        const resolved = read(["rev-parse", "--verify", "-q", "--end-of-options", "HEAD^{commit}"]);
+        if (!resolved || !SHA.test(resolved))
+            return "git branch -d would refuse: the main worktree's HEAD does not resolve; delete manually after checking";
+        reference = resolved;
+    }
+    const r = spawnSync("git", ["merge-base", "--is-ancestor", step.head, reference], { cwd: main, env, timeout: 30_000, stdio: "ignore" });
+    if (r.error || r.status === null || (r.status !== 0 && r.status !== 1))
+        return unchecked;
+    if (r.status === 0)
+        return null;
+    return step.method === "squash" || step.method === "rebase"
+        ? `${step.method}-merged: git branch -d would refuse (not merged into ${referenceName}); delete manually after checking`
+        : `git branch -d would refuse: not merged into ${referenceName}; update it, or delete manually after checking`;
 }
 /** Execute the local steps of a plan. Each command is a fixed argv; the branch name was
  *  validated by the record schema and is passed after `--`; the worktree path comes from
- *  `git worktree list` on this machine. A failure stops that step, never the others. */
+ *  `git worktree list` on this machine. `git branch -d`'s own precondition is re-checked
+ *  BEFORE the worktree is removed, so a step either runs whole or not at all. A failure
+ *  stops that step, never the others. */
 export function applyPrune(root, steps) {
     const main = mainWorktreeRoot(root);
-    const env = foreignRepoEnv(process.env);
+    const env = gitEnv();
     const git = (args) => execFileSync("git", args, { cwd: main, env, encoding: "utf8", timeout: 60_000, stdio: ["ignore", "pipe", "pipe"] }).trim();
     const results = [];
     for (const step of steps) {
@@ -139,6 +221,11 @@ export function applyPrune(root, steps) {
             results.push({ step, outcome: "failed", detail: "refused: unsafe branch name" });
             continue;
         }
+        const refusal = branchDeleteRefusal(root, step);
+        if (refusal) {
+            results.push({ step, outcome: "skipped", detail: `skipped (worktree and branch kept): ${refusal}` });
+            continue;
+        }
         try {
             const detail = [];
             if (step.worktree?.path) {
@@ -160,6 +247,23 @@ export function applyPrune(root, steps) {
     }
     return results;
 }
+/** A file name is repository content a terminal would interpret: control characters are
+ *  shown escaped, never emitted. */
+function printable(text) {
+    return text.replace(new RegExp(CONTROL_CHARS.source, "g"), (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`);
+}
+export function describeIgnored(ignored) {
+    const more = ignored.total - ignored.shown.length;
+    return `${ignored.total} ignored path(s) in the worktree: ${ignored.shown.map(printable).join(", ")}${more > 0 ? `, … and ${more} more` : ""}`;
+}
+/** The confirmation question for `prune --apply`: counts, and — because `git worktree
+ *  remove` deletes ignored files (.env, build output) without asking — every worktree's
+ *  ignored paths by name. */
+export function pruneConfirmQuestion(view, plan) {
+    const worktrees = plan.local.filter((s) => s.worktree).length;
+    const details = plan.local.filter((s) => s.ignored).map((s) => `  ${s.branch}: removing its worktree also deletes ${describeIgnored(s.ignored)}`);
+    return [...details, `Delete ${plan.local.length} branch(es)${worktrees ? ` and remove ${worktrees} worktree(s)` : ""} on ${view.machine.label}?`].join("\n");
+}
 /** Interactive yes/no; false when stdin is not a terminal (the caller then needs --yes). */
 export async function confirmPrune(question) {
     if (!process.stdin.isTTY)
@@ -182,6 +286,8 @@ export function renderPrunePlan(view, plan) {
         L.push(`  ${step.branch}  — ${step.why}`);
         for (const c of step.commands)
             L.push(`    ${c}`);
+        if (step.ignored)
+            L.push(`    ⚠ also deletes ${describeIgnored(step.ignored)}`);
     }
     if (plan.skipped.length) {
         L.push("", "Merged but left alone on this machine:");

package/dist/mcp/server.js

@@ -24,11 +24,12 @@ 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";
 import { workspacesConfig } from "../core/config.js";
-import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, workingFiles, workingDiff, pullHunchStatus, sameRemoteUrl, currentBranch } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeGateDiff, commitFiles, commitGateDiff, stagedFiles, stagedGateDiff, workingFiles, workingGateDiff, pullHunchStatus, sameRemoteUrl, currentBranch } from "../extractors/git.js";
 import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
 import { withWriteLock } from "../serve/writelock.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, overlayMatchesTeamRemote, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.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}`);
         }
@@ -2138,8 +2197,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : working ? "working changes" : "staged changes";
             if (!files.length)
                 return ok(`VERDICT: ✅ PASS — no changed files in ${scope}.`);
-            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : working ? workingDiff(root) : stagedDiff(root);
-            const report = store.buildCheckReport(files, diff, { strict: true, lastChange: (f) => lastChangeDate(f, root) });
+            const gate = commit ? commitGateDiff(commit, root) : base ? rangeGateDiff(base, root) : working ? workingGateDiff(root) : stagedGateDiff(root);
+            const report = store.buildCheckReport(files, gate.diff, { strict: true, lastChange: (f) => lastChangeDate(f, root), diffStatus: gate });
             const v = verdict(report);
             const head = v === "block"
                 ? "VERDICT: ⛔ BLOCK — a recorded guard requires review; inspect the cited scope and evidence below before merge."
@@ -2181,8 +2240,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : working ? "working changes" : "staged changes";
             if (!files.length)
                 return ok(`No changed files in ${scope}.`);
-            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : working ? workingDiff(root) : stagedDiff(root);
-            return ok(renderImpact(store.prImpact(files, diff), scope));
+            const gate = commit ? commitGateDiff(commit, root) : base ? rangeGateDiff(base, root) : working ? workingGateDiff(root) : stagedGateDiff(root);
+            return ok(renderImpact(store.prImpact(files, gate.diff, gate), scope));
         }
         catch (e) {
             return err(`Failed to compute impact: ${e.message}`);

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;