@davesheffer/hunch 1.38.1 → 1.39.1

package/dist/client/readOrCompute.d.ts

@@ -0,0 +1,77 @@
+/**
+ * readOrCompute — the reuse rule every derived-state writer otherwise re-derives by hand, and
+ * gets wrong first. No dependencies beyond the platform: canonical JSON and WebCrypto SHA-256.
+ *
+ * Rules applied, in order (docs/nuryel-state-contract.md, "Read or compute"):
+ *  1. Read the subject. A current statement under the same transform whose dependency SET equals
+ *     the given one is reused and nothing is computed. The set, not the order: the server derives
+ *     a statement's identity from its dependency hashes sorted, so order never makes it new.
+ *  2. Otherwise run `compute` once and write the result as the subject's current statement.
+ *  3. The idempotency key names the REQUEST: subject, transform and dependencies, the content
+ *     hash, and computed_at. A key without the content hash is reused when the same evidence
+ *     yields new wording, and the contract refuses a reused key with another payload for good
+ *     (the pilot's stuck outbox).
+ *  4. `supersedes` names the current statement it replaces under the same transform; the server
+ *     keeps one current statement per subject and transform and refuses a second.
+ *  5. The audience carries forward: without an explicit `visibility` the new statement keeps the
+ *     one it supersedes (audiences are preserved across supersession). An explicit change sends
+ *     the predecessor's record hash as `expected_version`, which the server requires.
+ *  6. No retries. A refusal or a transport failure surfaces to the caller. Calling again re-reads
+ *     first, so a write that did land is reused instead of written twice.
+ */
+import type { DependencyRef, DerivedState, ReadResponse, RecordsResponse, Scope, WriteResult } from "../core/stateContract.js";
+/** What the helper needs from a client; `createStateClient` satisfies it. */
+export interface ReadOrComputeClient {
+    read(request: {
+        scope: Scope;
+        subject: string;
+        facets: ["derived"];
+    }): Promise<ReadResponse>;
+    records(request: {
+        scope: Scope;
+        ids: string[];
+    }): Promise<RecordsResponse>;
+    write(request: {
+        scope: Scope;
+        facet: "derived";
+        record: Record<string, unknown>;
+        idempotency_key: string;
+        supersedes?: string;
+        expected_version?: string;
+    }): Promise<WriteResult>;
+}
+export interface ComputedContent {
+    content: string;
+    field_provenance?: DerivedState["field_provenance"];
+}
+export interface ReadOrComputeRequest {
+    scope: Scope;
+    subject: string;
+    transform_version: string;
+    /** What the statement rests on; at least one. Equal sets reuse, whatever their order. */
+    dependencies: DependencyRef[];
+    provenance: DerivedState["provenance"];
+    /** Record audience. Omitted: the superseded statement's audience is kept. */
+    visibility?: DerivedState["visibility"];
+    /** Runs only when no current statement rests on exactly these dependencies. */
+    compute: () => string | ComputedContent | Promise<string | ComputedContent>;
+    /** ISO timestamp for computed_at; defaults to the clock. */
+    now?: () => string;
+}
+export type ReadOrComputeResult = {
+    reused: true;
+    record: DerivedState;
+    read_receipt: string;
+} | {
+    reused: false;
+    record: DerivedState;
+    write: WriteResult;
+    superseded: string | null;
+    read_receipt: string;
+};
+/** The server's canonical form (src/core/stateCanonical.ts): keys in code-unit order, undefined
+ *  dropped, non-finite numbers and `__proto__` refused. Kept in step by test. */
+export declare function canonicalJson(value: unknown): string;
+/** `sha256:<hex>` over the canonical form — the server's stateHash. */
+export declare function stateHash(value: unknown): Promise<string>;
+export declare function readOrCompute(client: ReadOrComputeClient, request: ReadOrComputeRequest): Promise<ReadOrComputeResult>;

package/dist/client/readOrCompute.js

@@ -0,0 +1,85 @@
+const DERIVED_SCHEMA = "nuryel.derived/1";
+/** The server's canonical form (src/core/stateCanonical.ts): keys in code-unit order, undefined
+ *  dropped, non-finite numbers and `__proto__` refused. Kept in step by test. */
+export function canonicalJson(value) {
+    return JSON.stringify(canonical(value));
+}
+function canonical(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("canonical form rejects non-finite numbers");
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            if (key === "__proto__")
+                throw new Error("canonical form rejects reserved key __proto__");
+            const v = value[key];
+            if (v !== undefined)
+                out[key] = canonical(v);
+        }
+        return out;
+    }
+    throw new Error(`canonical form rejects ${typeof value}`);
+}
+/** `sha256:<hex>` over the canonical form — the server's stateHash. */
+export async function stateHash(value) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalJson(value)));
+    return `sha256:${Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+function dependencySet(dependencies) {
+    return dependencies.map(canonicalJson).sort().join("\n");
+}
+function sameScope(a, b) {
+    return !!a && a.kind === b.kind && a.id === b.id;
+}
+export async function readOrCompute(client, request) {
+    const { scope, subject, transform_version, dependencies, provenance } = request;
+    if (!Array.isArray(dependencies) || dependencies.length === 0)
+        throw new Error("readOrCompute: derived state needs at least one dependency (a statement nothing can invalidate is not state)");
+    const read = await client.read({ scope, subject, facets: ["derived"] });
+    const refs = (read.state_of_record?.current ?? []).filter((ref) => ref.facet === "derived" && sameScope(ref.scope, scope));
+    const recordHash = new Map(refs.map((ref) => [ref.id, ref.record_hash]));
+    let records = read.records ?? {};
+    const unseen = refs.map((ref) => ref.id).filter((id) => !records[id]);
+    // Hosts that predate `records` on the read answer by id instead.
+    if (unseen.length)
+        records = { ...records, ...(await client.records({ scope, ids: unseen })).records };
+    const current = refs
+        .map((ref) => records[ref.id])
+        .filter((r) => !!r && r.schema === DERIVED_SCHEMA && r.subject === subject && r.transform_version === transform_version && r.state === "current" && r.valid_to == null);
+    const wanted = dependencySet(dependencies);
+    const reusable = current.find((r) => dependencySet(r.dependencies) === wanted);
+    if (reusable)
+        return { reused: true, record: reusable, read_receipt: read.receipt_id };
+    const computed = await request.compute();
+    const { content, field_provenance } = typeof computed === "string" ? { content: computed, field_provenance: undefined } : computed;
+    if (typeof content !== "string" || content.length === 0)
+        throw new Error("readOrCompute: compute must return non-empty content");
+    const content_hash = await stateHash(content);
+    const computed_at = (request.now ?? (() => new Date().toISOString()))();
+    const incumbent = current.find((r) => dependencySet(r.dependencies) !== wanted) ?? null;
+    const statement = await stateHash({ scope, subject, transform_version, dependencies: dependencies.map(canonicalJson).sort() });
+    const idempotency_key = `derived:${statement.slice(7, 23)}:${content_hash.slice(7, 23)}:${computed_at}`;
+    const visibility = request.visibility !== undefined ? request.visibility : incumbent?.visibility;
+    const audienceChanges = !!incumbent && canonicalJson(incumbent.visibility ?? null) !== canonicalJson(visibility ?? null);
+    const record = {
+        ...(visibility ? { visibility } : {}),
+        schema: DERIVED_SCHEMA, scope, subject, content, content_hash, dependencies,
+        ...(field_provenance ? { field_provenance } : {}),
+        transform_version, computed_at, valid_to: null, state: "current", provenance,
+    };
+    const write = await client.write({
+        scope, facet: "derived", record, idempotency_key,
+        ...(incumbent ? { supersedes: incumbent.id } : {}),
+        ...(audienceChanges ? { expected_version: recordHash.get(incumbent.id) } : {}),
+    });
+    const stored = (write.record ?? { ...record, id: write.record_id });
+    return { reused: false, record: stored, write, superseded: incumbent?.id ?? null, read_receipt: read.receipt_id };
+}
+//# sourceMappingURL=readOrCompute.js.map

package/dist/client/state.d.ts

@@ -314,3 +314,4 @@ export declare function createStateClient(opts: StateClientOptions): {
     }>;
 };
 export type StateClient = ReturnType<typeof createStateClient>;
+export { readOrCompute, type ReadOrComputeClient, type ReadOrComputeRequest, type ReadOrComputeResult, type ComputedContent } from "./readOrCompute.js";

package/dist/client/state.js

@@ -62,4 +62,5 @@ export function createStateClient(opts) {
         health: () => call("GET", "/nuryel/v1/health"),
     };
 }
+export { readOrCompute } from "./readOrCompute.js";
 //# sourceMappingURL=state.js.map

package/dist/constitution/g2.d.ts

@@ -131,6 +131,7 @@ export interface G2ShadowSweepReport {
         policy_id: string;
         error: string;
     }>;
+    retired: string[];
     skipped_reason: string | null;
     authority: "none";
     effects: "shadow_only";

package/dist/constitution/service.js

@@ -677,6 +677,7 @@ export class ConstitutionService {
         const recorded = [];
         const existing = [];
         const failures = [];
+        const retired = [];
         if (manifest) {
             const before = new Set(this.repository.listShadowEvaluations({ privateOnly: true }).map((record) => record.id));
             for (const policyId of manifest.policy_ids) {
@@ -686,6 +687,12 @@ export class ConstitutionService {
                     if (!policy || publicDuplicate || this.repository.homeOfPolicy(policyId) !== "private" || policy.data_class === "public") {
                         throw new Error("selected policy is not in one exact private-only home");
                     }
+                    // A retired policy has closed its valid-time window: observing it again is
+                    // not evidence, only growth. Its recorded history stays untouched.
+                    if (policy.state === "retired") {
+                        retired.push(policyId);
+                        continue;
+                    }
                     const record = this.recordShadow(policyId, { now: opts.now });
                     if (before.has(record.id))
                         existing.push(record.id);
@@ -705,6 +712,7 @@ export class ConstitutionService {
             recorded: recorded.sort(),
             existing: existing.sort(),
             failures: failures.sort((left, right) => left.policy_id.localeCompare(right.policy_id)),
+            retired: retired.sort(),
             skipped_reason: manifest ? null : "No current private G2 plan; shadow sweep wrote nothing.",
             authority: "none",
             effects: "shadow_only",

package/dist/constitution/sourceMutation.js

@@ -93,16 +93,21 @@ function parsedSymbolFor(graphSymbol, parsed) {
     const base = symbolId(graphSymbol.file, graphSymbol.name, graphSymbol.kind);
     return matches.find((_symbol, index) => (index === 0 ? base : `${base}_${index}`) === graphSymbol.id) ?? null;
 }
-function spliceBytes(source, replacements) {
-    let bytes = Buffer.from(source, "utf8");
+/** `start`/`end` are JS string (UTF-16 code unit) indices. Despite their
+ *  names, parse.ts's startByte/endByte/atByte carry the same units — native
+ *  tree-sitter indexes the JS string it was handed, not its UTF-8 encoding —
+ *  so every scan and splice against them must be string-based, never Buffer-
+ *  based. */
+function spliceChars(source, replacements) {
+    let result = source;
     for (const replacement of [...replacements].sort((a, b) => b.start - a.start)) {
-        bytes = Buffer.concat([
-            bytes.subarray(0, replacement.start),
-            Buffer.from(replacement.text, "utf8"),
-            bytes.subarray(replacement.end),
-        ]);
+        result = result.slice(0, replacement.start) + replacement.text + result.slice(replacement.end);
     }
-    return bytes.toString("utf8");
+    return result;
+}
+/** Where a new top-level statement (an import) can be inserted without splitting a shebang line. */
+function insertionPoint(source) {
+    return source.startsWith("#!") ? Math.max(0, source.indexOf("\n") + 1) : 0;
 }
 function mutateSource(policy, base, sourceFile, source) {
     const assertion = policy.assertion;
@@ -145,10 +150,10 @@ function mutateSource(policy, base, sourceFile, source) {
         const specifier = relativeSpecifier(sourceFile, targetFile);
         if (parsed.imports.some((candidate) => candidate === specifier))
             return { error: "mutation-component-import-already-present" };
-        const insertion = source.startsWith("#!") ? Math.max(0, source.indexOf("\n") + 1) : 0;
+        const insertion = insertionPoint(source);
         return {
             file: sourceFile,
-            source: spliceBytes(source, [{ start: insertion, end: insertion, text: `import ${JSON.stringify(specifier)}; // hunch deterministic component mutation\n` }]),
+            source: spliceChars(source, [{ start: insertion, end: insertion, text: `import ${JSON.stringify(specifier)}; // hunch deterministic component mutation\n` }]),
         };
     }
     const subject = symbolForSelector(base, assertion.subject);
@@ -161,7 +166,7 @@ function mutateSource(policy, base, sourceFile, source) {
     if (!definition)
         return { error: "mutation-subject-definition-unresolved" };
     if (assertion.kind === "exists") {
-        return { file: subject.file, source: spliceBytes(source, [{ start: definition.startByte, end: definition.endByte, text: "" }]) };
+        return { file: subject.file, source: spliceChars(source, [{ start: definition.startByte, end: definition.endByte, text: "" }]) };
     }
     if (assertion.kind === "not-reaches"
         && assertion.relation.edges.length === 1
@@ -173,10 +178,10 @@ function mutateSource(policy, base, sourceFile, source) {
         if (parsed.imports.some((specifier) => externalPackage(specifier) === dependency)) {
             return { error: "mutation-forbidden-import-already-present" };
         }
-        const insertion = source.startsWith("#!") ? Math.max(0, source.indexOf("\n") + 1) : 0;
+        const insertion = insertionPoint(source);
         return {
             file: subject.file,
-            source: spliceBytes(source, [{ start: insertion, end: insertion, text: `import ${JSON.stringify(dependency)}; // hunch deterministic source mutation\n` }]),
+            source: spliceChars(source, [{ start: insertion, end: insertion, text: `import ${JSON.stringify(dependency)}; // hunch deterministic source mutation\n` }]),
         };
     }
     const object = symbolForSelector(base, assertion.object);
@@ -193,19 +198,19 @@ function mutateSource(policy, base, sourceFile, source) {
             .map((call) => ({ start: call.atByte, end: call.endByte, text: "hunchMutationRemovedCall" }));
         if (!replacements.length)
             return { error: "mutation-required-call-unresolved" };
-        return { file: subject.file, source: spliceBytes(source, replacements) };
+        return { file: subject.file, source: spliceChars(source, replacements) };
     }
     if (!assertion.relation.edges.includes("calls"))
         return { error: "mutation-call-edge-not-supported" };
-    const bytes = Buffer.from(source, "utf8");
-    const open = bytes.indexOf("{".charCodeAt(0), definition.startByte);
+    // String search, matching definition.startByte/endByte's actual units -- see spliceChars' doc comment.
+    const open = source.indexOf("{", definition.startByte);
     if (open < 0 || open >= definition.endByte)
         return { error: "mutation-subject-body-unsupported" };
     const replacements = [{ start: open + 1, end: open + 1, text: `\n  ${object.name}(); // hunch deterministic source mutation\n` }];
     if (object.file !== subject.file) {
         const specifier = relativeSpecifier(subject.file, object.file);
         if (!parsed.imports.includes(specifier)) {
-            const insertion = source.startsWith("#!") ? Math.max(0, source.indexOf("\n") + 1) : 0;
+            const insertion = insertionPoint(source);
             replacements.push({
                 start: insertion,
                 end: insertion,
@@ -215,7 +220,7 @@ function mutateSource(policy, base, sourceFile, source) {
     }
     return {
         file: subject.file,
-        source: spliceBytes(source, replacements),
+        source: spliceChars(source, replacements),
     };
 }
 function removeWorktree(root, hooks, env, checkout) {

package/dist/core/agenthook.d.ts

@@ -8,6 +8,16 @@
 export declare const HOOK_PROVIDERS: readonly ["claude", "codex", "vscode", "windsurf", "antigravity", "cursor"];
 export type HookProvider = (typeof HOOK_PROVIDERS)[number];
 export type HunchHookEvent = "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "UserPromptSubmit" | "SessionStart" | "SubagentStart" | "PreCompact" | "Stop";
+/** One file section of a Codex `apply_patch` payload. */
+export interface HunchPatchFile {
+    /** The path as written in the patch (may be absolute). */
+    path: string;
+    action: "update" | "add" | "delete";
+    /** `*** Move to:` destination, when the section renames the file. */
+    moved_to?: string;
+    /** Only the lines this section adds (`+` prefix stripped). */
+    added_lines: string[];
+}
 export interface HunchToolInput {
     file_path?: string;
     new_string?: string;
@@ -17,6 +27,9 @@ export interface HunchToolInput {
     }>;
     command?: string;
     skill?: string;
+    /** Codex `apply_patch` only: every file the patch touches. `file_path` is the
+     * first entry's path and `content` the raw patch, for single-file consumers. */
+    patch_files?: HunchPatchFile[];
 }
 /** A provider-neutral observation of the tool result. Output is ephemeral: the
  * pipeline compares it with bounded expectations but never persists it. */
@@ -41,6 +54,7 @@ export interface HunchHookInput {
     /** SubagentStart: the delegated agent's type (e.g. "Explore", "Plan"). */
     agent_type?: string;
 }
+export declare function parseApplyPatch(patch: string): HunchPatchFile[];
 /** Parse a provider name supplied by a hook config. Unknown values intentionally
  * return null so a bad config cannot make an edit fail. */
 export declare function hookProvider(value: unknown): HookProvider | null;

package/dist/core/agenthook.js

@@ -49,16 +49,59 @@ function edits(value) {
         .map((item) => ({ new_string: stringAt(item, "new_string", "newString", "ReplacementContent", "replacementContent") }));
     return normalized.length ? normalized : undefined;
 }
+/** Parse Codex `apply_patch` text into one entry per touched file. Only `+` lines
+ * inside a file section count as added: removed (`-`) and context (` `) lines are
+ * text the edit takes away or leaves alone, so a content-matched gate must not read
+ * them as proposed content. Paths are returned exactly as written in the patch;
+ * the CLI normalizes them against the repository root. */
+const PATCH_HEADER = /^\*\*\* (Update|Add|Delete) File: (.+?)\s*$/;
+const PATCH_MOVE = /^\*\*\* Move to: (.+?)\s*$/;
+export function parseApplyPatch(patch) {
+    const files = [];
+    let current;
+    for (const line of patch.split(/\r?\n/)) {
+        const header = PATCH_HEADER.exec(line);
+        if (header) {
+            current = { path: header[2], action: header[1].toLowerCase(), added_lines: [] };
+            files.push(current);
+            continue;
+        }
+        if (!current)
+            continue;
+        const move = PATCH_MOVE.exec(line);
+        if (move) {
+            current.moved_to = move[1];
+            continue;
+        }
+        // `*** End Patch` / `*** End of File` close sections; they carry no content.
+        if (line.startsWith("*** "))
+            continue;
+        // A unified-diff style file header is not content; apply_patch has none, but
+        // a model can still emit one.
+        if (/^\+\+\+ (?:[ab]\/|\/dev\/null)/.test(line))
+            continue;
+        if (line.startsWith("+"))
+            current.added_lines.push(line.slice(1));
+    }
+    return files;
+}
 /** Codex edits files through `apply_patch`, whose input is the patch text itself
- * (`*** Update File: path`). The first touched path becomes the edit target so the
- * per-file pre-edit gate applies; the whole patch stands in for the new content. */
-const PATCH_FILE = /^\*\*\* (?:Update|Add|Delete) File: (.+?)\s*$/m;
+ * (`*** Update File: path`). Every touched file is listed in `patch_files` so the
+ * pre-edit gate runs per file; the first path stays `file_path` and the whole patch
+ * stays `content` for consumers that read the single-file shape.
+ *
+ * TODO(codex-exec-patch): a Codex code-mode `exec` tool call that embeds an
+ * apply_patch does NOT reach this parser: `.codex/hooks.json` (integrations/
+ * providers.ts) matches PreToolUse on `apply_patch` only, and `normalizeHookEvent`
+ * enables patch parsing only for tool names `apply_patch`/`patch`. No captured
+ * payload of such a call exists in the repo, so its shape is not guessed here;
+ * capture a real hook payload before extending the matcher or this parser. */
 function applyPatchInput(raw) {
     const patch = [raw.input, raw.patch, raw.content].find((v) => typeof v === "string" && /\*\*\* Begin Patch/.test(v));
     if (!patch)
         return undefined;
-    const file = PATCH_FILE.exec(patch)?.[1];
-    return file ? { file_path: file, content: patch } : undefined;
+    const files = parseApplyPatch(patch);
+    return files.length ? { file_path: files[0].path, content: patch, patch_files: files } : undefined;
 }
 function normalizeToolInput(value, allowPatch = false) {
     const raw = obj(value);

package/dist/core/changeProof.js

@@ -94,7 +94,8 @@ function exactChangedPaths(root, baseRevision, resultRevision) {
 }
 function exactDiff(root, baseRevision, resultRevision) {
     const raw = gitBytes(root, [
-        "diff", "--no-ext-diff", "--no-textconv", "--no-color", "--no-renames", "--unified=2",
+        "-c", "core.quotePath=false",
+        "diff", "--no-ext-diff", "--no-textconv", "--no-color", "--no-renames", "--unified=2", "--src-prefix=a/", "--dst-prefix=b/",
         baseRevision, resultRevision, "--",
     ]);
     if (raw.byteLength <= MAX_DIFF_BYTES)
@@ -309,6 +310,9 @@ export function deriveChangeProof(root, store, baseRef, resultRef = "HEAD", opti
     const guardReport = store.buildCheckReport(changed.paths, diff.diff, {
         strict: true,
         publicOnly,
+        // A diff cut at MAX_DIFF_BYTES is a prefix: content-matched blocking rules over the
+        // files it omits fail closed rather than read as compliant (dec_20db57c576).
+        diffStatus: diff.gaps.length ? { incomplete: `the guard diff exceeded ${MAX_DIFF_BYTES} bytes and was cut`, truncated: true } : undefined,
         lastChange: (path) => lastChangeAt(root, change.head_revision, path),
     });
     const allStrictBlockerIds = sortedUnique([

package/dist/core/checkreport.d.ts

@@ -29,6 +29,13 @@ export interface CheckDirect {
     strictBlocks: boolean;
     /** If a blocking invariant is downgraded to advisory under strict, why. */
     downgrade?: "stale" | "low-confidence";
+    /** Set when a content-matched blocking invariant could NOT be evaluated because the
+     *  added lines of some scoped files are missing from the diff (truncated diff, git
+     *  failure, unreadable file). Reported as a hit, never as compliance: it fails closed. */
+    unevaluable?: {
+        reason: string;
+        files: string[];
+    };
     /** The causal citation (the "why this guard exists") — present when the graph links it. */
     why?: CausalWhy;
 }

package/dist/core/checkreport.js

@@ -44,6 +44,16 @@ export function renderImpact(im, scope) {
     }
     return out.join("\n");
 }
+/** Strict-failure reason fragments for direct invariants: proven hits and the
+ *  content-matched invariants that could not be evaluated are named separately. */
+function strictBlockerReasons(r) {
+    const unevaluable = r.direct.filter((d) => d.strictBlocks && d.unevaluable).length;
+    const proven = r.strictBlockers - unevaluable;
+    return [
+        proven > 0 ? `${proven} high-confidence blocking invariant(s) directly in scope` : "",
+        unevaluable > 0 ? `${unevaluable} blocking invariant(s) that could not be evaluated against the complete diff` : "",
+    ];
+}
 /** True when --strict should FAIL the commit/PR. */
 export function reportFailsStrict(r) {
     return r.strict && (r.strictBlockers > 0 || r.regBlocking > 0 || r.vetoBlocking > 0);
@@ -93,7 +103,10 @@ export function renderText(r) {
             const note = r.strict && c.severity === "blocking" && !c.strictBlocks
                 ? c.downgrade === "stale" ? "  (advisory: stale)" : "  (advisory: low confidence)"
                 : "";
-            out.push(`  ${mark(c.severity)} [${c.severity}] ${c.statement}${note}\n      ${c.id} · in: ${c.files.join(", ")}\n      rationale: ${c.rationale || "—"}${whyText(c.why)}`);
+            const unevaluable = c.unevaluable
+                ? `\n      ‼ NOT EVALUATED — ${c.unevaluable.reason}; added lines unavailable for: ${c.unevaluable.files.join(", ")} (fails closed)`
+                : "";
+            out.push(`  ${mark(c.severity)} [${c.severity}] ${c.statement}${note}\n      ${c.id} · in: ${c.files.join(", ")}\n      rationale: ${c.rationale || "—"}${unevaluable}${whyText(c.why)}`);
         }
     }
     if (r.near.length) {
@@ -122,7 +135,7 @@ export function renderText(r) {
     }
     if (reportFailsStrict(r)) {
         const reasons = [
-            r.strictBlockers ? `${r.strictBlockers} high-confidence blocking invariant(s) directly in scope` : "",
+            ...strictBlockerReasons(r),
             r.regBlocking ? `${r.regBlocking} blocking-linked regression(s)` : "",
             r.vetoBlocking ? `${r.vetoBlocking} reversed-decision veto(es)` : "",
         ].filter(Boolean).join(" + ");
@@ -153,6 +166,8 @@ export function renderMarkdown(r) {
                 : "";
             out.push(`- **[${c.severity}] ${c.statement}** — \`${c.id}\`${note}`);
             out.push(`  - in: ${c.files.map((f) => `\`${f}\``).join(", ")}`);
+            if (c.unevaluable)
+                out.push(`  - ‼ **Not evaluated** — ${c.unevaluable.reason}; added lines unavailable for ${c.unevaluable.files.map((f) => `\`${f}\``).join(", ")} _(fails closed)_`);
             if (c.rationale)
                 out.push(`  - _${c.rationale}_`);
             for (const line of whyMd(c.why))
@@ -196,7 +211,7 @@ export function renderMarkdown(r) {
     out.push("---");
     if (reportFailsStrict(r)) {
         const reasons = [
-            r.strictBlockers ? `${r.strictBlockers} high-confidence blocking invariant(s) directly in scope` : "",
+            ...strictBlockerReasons(r),
             r.regBlocking ? `${r.regBlocking} blocking-linked regression(s)` : "",
             r.vetoBlocking ? `${r.vetoBlocking} reversed-decision veto(es)` : "",
         ].filter(Boolean).join(" + ");
@@ -233,6 +248,8 @@ export function renderSarif(r, version, extras = {}) {
             text += ` — ${c.rationale}`;
         if (c.downgrade)
             text += ` (advisory under strict: ${c.downgrade})`;
+        if (c.unevaluable)
+            text += `\nNOT EVALUATED (fails closed): ${c.unevaluable.reason}; added lines unavailable for ${c.unevaluable.files.join(", ")}`;
         if (c.why?.decision)
             text += `\nwhy: “${c.why.decision.title}” (${c.why.decision.id})`;
         if (c.why?.bug)

package/dist/core/compare.js

@@ -1,5 +1,5 @@
 import { verdict } from "./checkreport.js";
-import { revExists, rangeFiles, rangeDiff } from "../extractors/git.js";
+import { revExists, rangeFiles, rangeGateDiff } from "../extractors/git.js";
 /** A lower fit score is better. Verdict dominates (pass < warn < block), then the
  *  blocking count, then total advisory hits. Errored candidates sort last. */
 function fitKey(c) {
@@ -14,7 +14,8 @@ export function compareCandidates(store, root, base, candidates) {
         const files = rangeFiles(base, root, ref);
         if (!files.length)
             return { ...zero, verdict: "pass", error: `no changes vs ${base}` };
-        const r = store.buildCheckReport(files, rangeDiff(base, root, ref), { strict: true });
+        const gate = rangeGateDiff(base, root, ref);
+        const r = store.buildCheckReport(files, gate.diff, { strict: true, diffStatus: gate });
         return {
             ref,
             verdict: verdict(r),

package/dist/core/config.d.ts

@@ -9,12 +9,28 @@ import type { HunchPaths } from "./paths.js";
 export type Firmness = "off" | "advisory" | "firm" | "strict";
 export declare const FIRMNESS_LEVELS: readonly Firmness[];
 export declare const DEFAULT_FIRMNESS: Firmness;
+/** Workspace-ledger knobs (docs/workspace-ledger.md). `publish` decides what a snapshot
+ *  carries: `branches` (default — label, branches, verdicts, dirty/locked flags, no paths),
+ *  `full` (worktree paths too), `off` (no record). `publish_public` lets a repo WITHOUT an
+ *  overlay commit the record into its tracked .hunch/ — off by default: per-machine facts
+ *  churning the code repo is rarely wanted. */
+export type WorkspacePublish = "full" | "branches" | "off";
+export declare const WORKSPACE_PUBLISH_MODES: readonly WorkspacePublish[];
+export declare const DEFAULT_WORKSPACE_PUBLISH: WorkspacePublish;
+export interface WorkspacesConfig {
+    publish: WorkspacePublish;
+    stale_after_days: number;
+    publish_public: boolean;
+}
 export interface HunchConfig {
     firmness: Firmness;
     /** MCP tool groups beyond the everyday set: `all`, `core`, or `core,nuryel`
      *  (see src/mcp/toolset.ts). Undefined = decide from the root's contents. */
     mcp_tools?: string;
+    workspaces?: Partial<WorkspacesConfig>;
 }
+/** The effective workspace config: every field present, unknown values ignored. */
+export declare function workspacesConfig(config: HunchConfig): WorkspacesConfig;
 export declare function isFirmness(v: unknown): v is Firmness;
 /** Read `.hunch/config.json`. A missing/unparseable file, or an unknown firmness
  *  value, falls back to defaults — the hook must NEVER crash an edit over config. */

package/dist/core/config.js

@@ -6,6 +6,18 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 export const FIRMNESS_LEVELS = ["off", "advisory", "firm", "strict"];
 export const DEFAULT_FIRMNESS = "advisory";
+export const WORKSPACE_PUBLISH_MODES = ["full", "branches", "off"];
+export const DEFAULT_WORKSPACE_PUBLISH = "branches";
+/** The effective workspace config: every field present, unknown values ignored. */
+export function workspacesConfig(config) {
+    const raw = config.workspaces ?? {};
+    const days = Number(raw.stale_after_days);
+    return {
+        publish: WORKSPACE_PUBLISH_MODES.includes(raw.publish) ? raw.publish : DEFAULT_WORKSPACE_PUBLISH,
+        stale_after_days: Number.isInteger(days) && days >= 1 && days <= 3650 ? days : 7,
+        publish_public: raw.publish_public === true,
+    };
+}
 function defaults() {
     return { firmness: DEFAULT_FIRMNESS };
 }
@@ -22,6 +34,7 @@ export function readConfig(paths) {
         return {
             firmness: isFirmness(raw.firmness) ? raw.firmness : DEFAULT_FIRMNESS,
             ...(typeof raw.mcp_tools === "string" && raw.mcp_tools.trim() ? { mcp_tools: raw.mcp_tools.trim() } : {}),
+            ...(raw.workspaces && typeof raw.workspaces === "object" && !Array.isArray(raw.workspaces) ? { workspaces: raw.workspaces } : {}),
         };
     }
     catch {

package/dist/core/machine.d.ts

@@ -0,0 +1,20 @@
+export interface MachineIdentity {
+    id: string;
+    label: string;
+    created_at: string;
+}
+export interface MachinePathOptions {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    platform?: NodeJS.Platform;
+}
+export declare function machineFile(opts?: MachinePathOptions): string;
+export declare function defaultMachineLabel(id: string): string;
+/** The machine's identity, minted on first use. An unreadable or invalid file is
+ *  replaced (a machine that lost its id simply becomes a new machine; the old record
+ *  ages out as unverified and `hunch workspaces forget` removes it). */
+export declare function loadOrCreateMachine(opts?: MachinePathOptions): MachineIdentity;
+export declare function setMachineLabel(label: string, opts?: MachinePathOptions): MachineIdentity;
+/** A label that equals the hostname or the OS username publishes personal data into a
+ *  shared store; `doctor` and `label` warn, they do not refuse — the user chose it. */
+export declare function labelLeaksIdentity(label: string): string | null;