@davesheffer/hunch 1.38.1 → 1.39.1

package/dist/core/workspace.js

@@ -0,0 +1,359 @@
+/**
+ * Workspace ledger — one record per MACHINE per repository describing that machine's
+ * git worktrees and local branches, with deterministic merged verdicts
+ * (docs/workspace-ledger.md). A LEAF module (zod + ids + provenance only) so types.ts
+ * can register the kind without a cycle, like stateRecords.ts.
+ *
+ * Security posture, in code: the schema is `.strict()` with bounded lengths, every
+ * branch name must be a git-valid ref component, every free-text field passes the
+ * credential filter, and NOTHING here reads a record back as authority — the
+ * aggregation below produces DISPLAY rows and a recommended action; `prune --apply`
+ * (Phase 3) re-snapshots live git and never acts on a stored record.
+ */
+import { z } from "zod";
+import { shortHash } from "./ids.js";
+import { ProvenanceSchema, isCredentialFreeValue } from "./provenance.js";
+export const WORKSPACE_SCHEMA_VERSION = "hunch.workspace/1";
+/** Record bounds. The extractor keeps the most recently committed entries and says so in
+ *  provenance, so a huge repository degrades to a truncated record, never to a crash. */
+export const MAX_WORKTREES = 512;
+export const MAX_BRANCHES = 4096;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/;
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+export const MACHINE_ID = /^mac_[0-9a-f]{32}$/;
+export const MACHINE_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A branch name git would accept (`git check-ref-format --branch`), fail-closed: no
+ *  leading `-` (flag smuggling), no control/whitespace characters, no `..`, `@{`,
+ *  `.lock` suffix, leading/trailing `.` or `/`, and bounded length. Every real branch
+ *  from `for-each-ref` passes; a crafted record cannot smuggle an argument. */
+export function isSafeBranchName(name) {
+    if (!name || name.length > 256)
+        return false;
+    if (name.startsWith("-") || name.startsWith("/") || name.endsWith("/") || name.startsWith(".") || name.endsWith("."))
+        return false;
+    if (name.includes("..") || name.includes("@{") || name.includes("//") || name.endsWith(".lock") || name === "@")
+        return false;
+    if (/[\s~^:?*[\\\x00-\x1f\x7f]/.test(name))
+        return false;
+    return !name.split("/").some((part) => part.startsWith(".") || part.endsWith(".lock"));
+}
+const BranchName = z.string().refine(isSafeBranchName, { message: "branch name must be a git-valid, flag-free ref" });
+/** `origin/feature` — a remote-tracking short ref: remote name plus a safe branch name. */
+const UpstreamName = z.string().max(320).refine((v) => {
+    const slash = v.indexOf("/");
+    return slash > 0 && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(v.slice(0, slash)) && isSafeBranchName(v.slice(slash + 1));
+}, { message: "upstream must be <remote>/<branch>" });
+/** C0/C1 control characters, including newline and ESC: a stored string carrying one could
+ *  forge extra lines or terminal escapes in output a human reads (a printed command). */
+export const CONTROL_CHARS = /[\x00-\x1f\x7f-\x9f]/;
+const credentialFree = (label, max) => z.string().min(1).max(max)
+    .refine((v) => !CONTROL_CHARS.test(v), { message: `${label} must not contain control characters or newlines` })
+    .refine(isCredentialFreeValue, { message: `${label} must not carry credential material` });
+export const WorkspaceWorktreeSchema = z.object({
+    /** Stable, path-free handle (hash of the path) so branches can point at a worktree in
+     *  `branches` publish mode, where the path itself is omitted. */
+    id: z.string().regex(/^wt_[0-9a-f]{8}$/),
+    path: credentialFree("worktree path", 1024).nullable(),
+    branch: BranchName.nullable(),
+    head: z.string().regex(SHA),
+    is_main: z.boolean(),
+    /** null = could not be determined (the path no longer exists). */
+    dirty: z.boolean().nullable(),
+    locked: z.boolean(),
+    prunable: z.boolean(),
+    last_commit_at: z.string().regex(ISO).nullable(),
+}).strict();
+/** `no-commits`: the branch head lies on the default branch's first-parent history, so the
+ *  branch holds no commits of its own (freshly created, or fast-forwarded into the default
+ *  branch). Ancestry alone would call it merged; it is never offered for deletion. */
+export const MERGED_STATUSES = ["merged", "unmerged", "no-commits", "unknown"];
+export const MERGED_METHODS = ["ancestry", "squash", "rebase"];
+export const MergedVerdictSchema = z.object({
+    status: z.enum(MERGED_STATUSES),
+    method: z.enum(MERGED_METHODS).nullable(),
+    evidence: z.array(z.string().max(256)
+        .refine((v) => !CONTROL_CHARS.test(v), { message: "verdict evidence must not contain control characters or newlines" })
+        .refine(isCredentialFreeValue, { message: "verdict evidence must not carry credential material" })).max(8),
+    /** The pull request that landed a merged branch, read from the LOCAL merge / squash commit
+     *  subject ("Merge pull request #N from …", "… (#N)") — never fetched from a forge. */
+    pr: z.number().int().min(1).max(100_000_000).optional(),
+}).strict().superRefine((v, ctx) => {
+    if ((v.status === "merged") !== (v.method !== null)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a merged verdict names its method; any other verdict has none" });
+    }
+    if (v.pr !== undefined && v.status !== "merged") {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["pr"], message: "only a merged verdict can name a pull request" });
+    }
+});
+export const WorkspaceBranchSchema = z.object({
+    name: BranchName,
+    head: z.string().regex(SHA),
+    is_default: z.boolean(),
+    upstream: UpstreamName.nullable(),
+    upstream_gone: z.boolean(),
+    ahead: z.number().int().min(0).max(1_000_000).nullable(),
+    behind: z.number().int().min(0).max(1_000_000).nullable(),
+    last_commit_at: z.string().regex(ISO).nullable(),
+    /** The worktree (by id) checked out on this branch, if any. */
+    worktree: z.string().regex(/^wt_[0-9a-f]{8}$/).nullable(),
+    merged: MergedVerdictSchema,
+}).strict();
+export const WorkspaceSchema = z.object({
+    schema: z.literal(WORKSPACE_SCHEMA_VERSION),
+    id: z.string().regex(/^ws_[0-9a-f]{12}$/),
+    machine: z.object({
+        id: z.string().regex(MACHINE_ID),
+        label: z.string().regex(MACHINE_LABEL),
+        platform: z.string().regex(/^[a-z0-9]{1,16}$/),
+    }).strict(),
+    /** The existing privacy-safe repository label (`stableRepositoryName`): a digest of the
+     *  canonical fetch remote, never a URL or a path. */
+    repository: credentialFree("repository label", 256),
+    publish: z.enum(["full", "branches"]),
+    observed_at: z.string().regex(ISO),
+    fetched_at: z.string().regex(ISO).nullable(),
+    default_branch: z.object({ name: BranchName, ref: UpstreamName.or(BranchName), head: z.string().regex(SHA) }).strict().nullable(),
+    worktrees: z.array(WorkspaceWorktreeSchema).max(MAX_WORKTREES),
+    branches: z.array(WorkspaceBranchSchema).max(MAX_BRANCHES),
+    provenance: ProvenanceSchema,
+}).strict().superRefine((record, ctx) => {
+    if (record.id !== workspaceId(record.machine.id)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["id"], message: "workspace id must derive from the machine id" });
+    }
+    if (record.publish === "branches" && record.worktrees.some((w) => w.path !== null)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["worktrees"], message: "branches publish mode carries no worktree paths" });
+    }
+    const worktreeIds = new Set(record.worktrees.map((w) => w.id));
+    if (worktreeIds.size !== record.worktrees.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["worktrees"], message: "worktree ids must be unique" });
+    }
+    const names = new Set();
+    for (const [index, branch] of record.branches.entries()) {
+        if (names.has(branch.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["branches", index], message: "branch names must be unique" });
+        names.add(branch.name);
+        if (branch.worktree !== null && !worktreeIds.has(branch.worktree)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["branches", index, "worktree"], message: "branch points at a worktree this record does not carry" });
+        }
+    }
+    if (record.provenance.evidence.length > 64 || record.provenance.evidence.some((e) => e.length > 512 || !isCredentialFreeValue(e))) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance"], message: "workspace provenance must remain bounded and credential-free" });
+    }
+});
+/** One record per machine: the id derives from the machine id, so a re-snapshot
+ *  UPDATES the machine's record and two machines can never collide on a file. */
+export function workspaceId(machineId) {
+    return "ws_" + machineId.replace(/^mac_/, "").slice(0, 12);
+}
+/** Path-free worktree handle. */
+export function worktreeId(path) {
+    return "wt_" + shortHash(path, 8);
+}
+/** The same observation, published under `publish`: `branches` drops every worktree path
+ *  (the default), `full` keeps them. Pure, so a caller that already took a live snapshot
+ *  (paths included, for its own display) can publish it without re-running git. */
+export function withPublishMode(record, publish) {
+    if (record.publish === publish)
+        return record;
+    return WorkspaceSchema.parse({
+        ...record,
+        publish,
+        worktrees: record.worktrees.map((w) => ({ ...w, path: publish === "full" ? w.path : null })),
+    });
+}
+/** True when two snapshots of the same machine describe the same workspace, ignoring the
+ *  observation stamps — so an idle machine's hook does not commit a new record per
+ *  checkout. Provenance is constant per build and is compared too. */
+export function sameWorkspaceContent(a, b) {
+    const strip = (w) => JSON.stringify({ ...w, observed_at: null, fetched_at: null });
+    return strip(a) === strip(b);
+}
+export const DEFAULT_STALE_AFTER_DAYS = 7;
+export function isUnverified(record, opts = {}) {
+    const now = (opts.now ?? new Date()).getTime();
+    const days = opts.staleAfterDays ?? DEFAULT_STALE_AFTER_DAYS;
+    const observed = Date.parse(record.observed_at);
+    return !Number.isFinite(observed) || now - observed > days * 86_400_000;
+}
+/** Same machine id → the newest observation wins; a stale duplicate never shadows a fresh one. */
+export function latestPerMachine(records) {
+    const byMachine = new Map();
+    for (const r of records) {
+        const prev = byMachine.get(r.machine.id);
+        if (!prev || Date.parse(r.observed_at) > Date.parse(prev.observed_at))
+            byMachine.set(r.machine.id, r);
+    }
+    return [...byMachine.values()].sort((a, b) => a.machine.label.localeCompare(b.machine.label));
+}
+export function worktreeRows(records, opts = {}) {
+    const rows = [];
+    for (const r of latestPerMachine(records)) {
+        const unverified = isUnverified(r, opts);
+        for (const w of r.worktrees) {
+            rows.push({
+                machine: r.machine.label, worktree_id: w.id, path: w.path, branch: w.branch, head: w.head,
+                dirty: w.dirty, locked: w.locked, prunable: w.prunable, last_commit_at: w.last_commit_at,
+                seen_at: r.observed_at, unverified,
+            });
+        }
+    }
+    return rows;
+}
+function daysIdle(iso, now) {
+    if (!iso)
+        return null;
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? Math.floor((now.getTime() - t) / 86_400_000) : null;
+}
+/** The recommendation rules from docs/workspace-ledger.md — deterministic text an agent
+ *  or a human reads; nothing executes it. */
+export function recommendAction(row, opts = {}) {
+    const now = opts.now ?? new Date();
+    const staleDays = opts.staleAfterDays ?? DEFAULT_STALE_AFTER_DAYS;
+    const suffix = row.unverified_on.length ? ` (unverified: ${row.unverified_on.join(", ")})` : "";
+    if (row.is_default)
+        return "keep: default branch";
+    if (row.heads.length > 1)
+        return `review: local heads differ across ${row.machines.join(", ")}${suffix}`;
+    if (row.merged.status === "merged") {
+        if (row.dirty_on.length)
+            return `keep: dirty worktree on ${row.dirty_on.join(", ")}${suffix}`;
+        const parts = [`delete local on ${row.machines.join(", ")}`];
+        if (row.worktree_on.length)
+            parts.push(`prune worktree on ${row.worktree_on.join(", ")}`);
+        return parts.join("; ") + suffix;
+    }
+    // Unmerged: a dirty worktree is not a reason to keep (the branch is kept anyway) but
+    // it is what the reader needs to know before touching the branch on that machine.
+    const dirty = row.dirty_on.length ? `; dirty worktree on ${row.dirty_on.join(", ")}` : "";
+    if (row.merged.status === "unknown")
+        return `review: merge state unknown${dirty}${suffix}`;
+    if (row.merged.status === "no-commits")
+        return `keep: no commits of its own${dirty}${suffix}`;
+    if (row.upstream === null || row.upstream_gone) {
+        const idle = daysIdle(row.last_commit_at, now);
+        const why = row.upstream_gone ? "upstream deleted, unmerged work" : "unpushed";
+        if (idle !== null && idle > staleDays)
+            return `review: ${why}, ${idle}d idle${dirty}${suffix}`;
+        return `keep: ${why}${dirty}${suffix}`;
+    }
+    return `keep${dirty}${suffix}`;
+}
+/** Merge verdicts across machines for one branch at one head: any machine that PROVED a
+ *  merge (with evidence) wins over machines that could not tell; `unknown` never
+ *  outranks `unmerged`, so an offline machine cannot mask real unmerged work. */
+function bestVerdict(verdicts) {
+    return verdicts.find((v) => v.status === "merged")
+        ?? verdicts.find((v) => v.status === "unmerged")
+        ?? verdicts.find((v) => v.status === "no-commits")
+        ?? verdicts[0]
+        ?? { status: "unknown", method: null, evidence: [] };
+}
+export function branchRows(records, opts = {}) {
+    const latest = latestPerMachine(records);
+    const byName = new Map();
+    for (const record of latest) {
+        const unverified = isUnverified(record, opts);
+        for (const branch of record.branches) {
+            const list = byName.get(branch.name) ?? [];
+            list.push({ record, branch, unverified });
+            byName.set(branch.name, list);
+        }
+    }
+    const rows = [];
+    for (const [name, entries] of [...byName.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const worktreeOf = (e) => e.branch.worktree ? e.record.worktrees.find((w) => w.id === e.branch.worktree) : undefined;
+        const withUpstream = entries.find((e) => e.branch.upstream !== null) ?? entries[0];
+        const partial = {
+            name,
+            machines: entries.map((e) => e.record.machine.label),
+            worktree_on: entries.filter((e) => worktreeOf(e)).map((e) => e.record.machine.label),
+            dirty_on: entries.filter((e) => worktreeOf(e)?.dirty === true).map((e) => e.record.machine.label),
+            heads: [...new Set(entries.map((e) => e.branch.head))],
+            is_default: entries.some((e) => e.branch.is_default),
+            upstream: withUpstream.branch.upstream,
+            upstream_gone: entries.some((e) => e.branch.upstream_gone),
+            ahead: withUpstream.branch.ahead,
+            behind: withUpstream.branch.behind,
+            last_commit_at: entries.map((e) => e.branch.last_commit_at).filter((d) => !!d).sort().at(-1) ?? null,
+            merged: bestVerdict(entries.map((e) => e.branch.merged)),
+            unverified_on: entries.filter((e) => e.unverified).map((e) => e.record.machine.label),
+        };
+        rows.push({ ...partial, action: recommendAction(partial, opts) });
+    }
+    return rows;
+}
+/** "2h ago" / "9d ago" for the SEEN column. */
+export function ago(iso, now = new Date()) {
+    const ms = now.getTime() - Date.parse(iso);
+    if (!Number.isFinite(ms) || ms < 0)
+        return "just now";
+    const m = Math.floor(ms / 60_000);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 48)
+        return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+/** POSIX shell quoting for one token of a PRINTED command (never executed through a shell
+ *  here: execution uses argv arrays). Tokens made only of characters no shell treats
+ *  specially stay bare; anything else is single-quoted with `'` escaped as `'\''`, which is
+ *  also valid in Git Bash for Windows paths. */
+export function shellQuote(token) {
+    if (/^[A-Za-z0-9_\-./:@+,]+$/.test(token))
+        return token;
+    return `'${token.replace(/'/g, `'\\''`)}'`;
+}
+function pruneStepsFor(record, opts) {
+    const steps = [];
+    const skipped = [];
+    for (const b of record.branches) {
+        const wt = b.worktree ? record.worktrees.find((w) => w.id === b.worktree) : undefined;
+        const reason = opts.skip(b, wt);
+        if (reason) {
+            if (b.merged.status === "merged" && !b.is_default)
+                skipped.push({ branch: b.name, reason });
+            continue;
+        }
+        const commands = [];
+        if (wt)
+            commands.push(`git worktree remove -- ${wt.path === null ? "<its worktree>" : shellQuote(wt.path)}`);
+        commands.push(`git branch -d -- ${shellQuote(b.name)}`);
+        steps.push({
+            branch: b.name, head: b.head, worktree: wt ? { id: wt.id, path: wt.path } : null, commands,
+            why: `${b.merged.method}${b.merged.pr ? ` (PR #${b.merged.pr})` : ""}: ${b.merged.evidence[0] ?? ""}`,
+            method: b.merged.method,
+        });
+    }
+    return { steps, skipped };
+}
+/** Why a branch must not be pruned, or null when it may. The rules are the documented ones:
+ *  proven merged, not the default branch, worktree (if any) clean, unlocked and present. */
+export function pruneRefusal(b, wt) {
+    if (b.is_default)
+        return "default branch";
+    if (b.merged.status !== "merged") {
+        return b.merged.status === "unknown" ? "merge state unknown" : b.merged.status === "no-commits" ? "no commits of its own" : "not merged";
+    }
+    if (wt?.is_main)
+        return "checked out in the main worktree (switch away first)";
+    if (wt?.locked)
+        return "worktree is locked";
+    if (wt?.prunable)
+        return "worktree path is missing (git worktree prune first)";
+    if (wt && wt.dirty !== false)
+        return wt.dirty === null ? "worktree state could not be read" : "worktree has uncommitted or untracked changes";
+    return null;
+}
+export function planPrune(live, others) {
+    const mine = pruneStepsFor(live, { skip: pruneRefusal });
+    const plan = { local: mine.steps, others: {}, skipped: mine.skipped };
+    for (const record of latestPerMachine(others.filter((r) => r.machine.id !== live.machine.id))) {
+        const theirs = pruneStepsFor(record, { skip: pruneRefusal });
+        if (theirs.steps.length)
+            plan.others[record.machine.label] = theirs.steps;
+    }
+    return plan;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/extractors/diff.d.ts

@@ -35,6 +35,40 @@ export interface DiffAnalysis {
      *  the same (new-path) key as perFile. */
     addedLinesByFile: Map<string, string[]>;
 }
+/** Undo git's C-style path quoting. Even with core.quotePath=false, git quotes a
+ *  path holding `"`, `\`, or a control character (`"src/a\"b.ts"`); with the
+ *  default quotePath it also octal-escapes every byte above 0x7F. Octal escapes
+ *  are raw bytes, so the unescaped byte string is decoded as UTF-8. An unquoted
+ *  or malformed value is returned unchanged. */
+export declare function unquoteGitPath(p: string): string;
+/** The final line a budget-capped diff ends with (see SYNTHESIS_DIFF_BUDGET in git.ts). */
+export declare const DIFF_TRUNCATED_LINE = "\u2026(diff truncated)\u2026";
+/** Does this diff end with the truncation marker (i.e. is it a prefix of the change)? */
+export declare function isTruncatedDiff(diff: string): boolean;
+/** The (new-side) path of every file block in a unified diff, in order — including
+ *  blocks with no hunks (binary, mode-only). Paths use the same keys as
+ *  DiffAnalysis.addedLinesByFile. */
+export declare function diffBlockFiles(diff: string): string[];
+/** How complete a gate's diff is (git.ts GateDiff satisfies this shape). */
+export interface DiffStatus {
+    /** Why the diff as a whole cannot be trusted as complete. */
+    incomplete?: string;
+    /** The diff is a byte prefix of the change, so its last block may be cut. */
+    truncated?: boolean;
+    /** Files whose content could not be read into the diff. */
+    unreadFiles?: string[];
+}
+export interface DiffContentGaps {
+    /** True when this file's added lines may be missing from the diff. */
+    missing(file: string): boolean;
+    /** A human-readable reason for the given missing files. */
+    reason(files: string[]): string;
+}
+/** Which files a content check cannot trust "no added lines" for. Null when the
+ *  diff is complete, so callers keep the exact small-diff behavior. A truncated
+ *  diff (ends with DIFF_TRUNCATED_LINE) covers only the blocks before its last,
+ *  possibly cut, block; an `incomplete` status covers only the blocks present. */
+export declare function diffContentGaps(diff: string, status?: DiffStatus): DiffContentGaps | null;
 export declare function analyzeDiff(diff: string): DiffAnalysis;
 /** A compact human-readable summary of a DiffAnalysis (used in decision text). */
 export declare function summarizeDiff(a: DiffAnalysis): string;

package/dist/extractors/diff.js

@@ -59,6 +59,148 @@ function importOf(line) {
 function stripAB(p) {
     return p.replace(/^[ab]\//, "");
 }
+const C_ESCAPES = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '"': 34, "\\": 92 };
+/** Undo git's C-style path quoting. Even with core.quotePath=false, git quotes a
+ *  path holding `"`, `\`, or a control character (`"src/a\"b.ts"`); with the
+ *  default quotePath it also octal-escapes every byte above 0x7F. Octal escapes
+ *  are raw bytes, so the unescaped byte string is decoded as UTF-8. An unquoted
+ *  or malformed value is returned unchanged. */
+export function unquoteGitPath(p) {
+    if (p.length < 2 || !p.startsWith('"') || !p.endsWith('"'))
+        return p;
+    const body = p.slice(1, -1);
+    const bytes = [];
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (ch !== "\\") {
+            for (const b of Buffer.from(ch, "utf8"))
+                bytes.push(b);
+            continue;
+        }
+        const next = body[i + 1];
+        if (next === undefined)
+            return p;
+        if (/[0-7]/.test(next)) {
+            const oct = /^[0-7]{1,3}/.exec(body.slice(i + 1))[0];
+            bytes.push(parseInt(oct, 8) & 0xff);
+            i += oct.length;
+            continue;
+        }
+        const code = C_ESCAPES[next];
+        if (code === undefined)
+            return p;
+        bytes.push(code);
+        i += 1;
+    }
+    return Buffer.from(bytes).toString("utf8");
+}
+/** A `---`/`+++` header path: strip git's trailing tab (added after names with
+ *  spaces), unquote, then drop the a/ b/ prefix. */
+function headerPath(raw) {
+    const value = raw.replace(/\r$/, "").replace(/\t$/, "").trim();
+    return value.startsWith('"') ? unquoteGitPath(value) : value;
+}
+/** The final line a budget-capped diff ends with (see SYNTHESIS_DIFF_BUDGET in git.ts). */
+export const DIFF_TRUNCATED_LINE = "…(diff truncated)…";
+/** Does this diff end with the truncation marker (i.e. is it a prefix of the change)? */
+export function isTruncatedDiff(diff) {
+    return diff === DIFF_TRUNCATED_LINE || diff.endsWith(`\n${DIFF_TRUNCATED_LINE}`);
+}
+/** The (new-side) path of every file block in a unified diff, in order — including
+ *  blocks with no hunks (binary, mode-only). Paths use the same keys as
+ *  DiffAnalysis.addedLinesByFile. */
+export function diffBlockFiles(diff) {
+    const out = [];
+    let cur = null;
+    const flush = () => { if (cur?.path)
+        out.push(cur.path); };
+    for (const raw of diff.split("\n")) {
+        if (raw.startsWith("diff --git ")) {
+            flush();
+            cur = { path: gitHeaderNewPath(raw.slice("diff --git ".length)), inHunk: false };
+            continue;
+        }
+        if (!cur)
+            continue;
+        if (raw.startsWith("@@")) {
+            cur.inHunk = true;
+            continue;
+        }
+        if (cur.inHunk)
+            continue;
+        if (raw.startsWith("rename to ") || raw.startsWith("copy to ")) {
+            cur.path = headerPath(raw.slice(raw.indexOf(" to ") + 4));
+        }
+        else if (raw.startsWith("+++ ")) {
+            const p = headerPath(raw.slice(4));
+            if (p !== "/dev/null")
+                cur.path = stripAB(p);
+        }
+        else if (raw.startsWith("--- ")) {
+            const p = headerPath(raw.slice(4));
+            if (p !== "/dev/null")
+                cur.path = stripAB(p);
+        }
+    }
+    flush();
+    return out;
+}
+/** Which files a content check cannot trust "no added lines" for. Null when the
+ *  diff is complete, so callers keep the exact small-diff behavior. A truncated
+ *  diff (ends with DIFF_TRUNCATED_LINE) covers only the blocks before its last,
+ *  possibly cut, block; an `incomplete` status covers only the blocks present. */
+export function diffContentGaps(diff, status) {
+    const truncated = !!status?.truncated || isTruncatedDiff(diff);
+    const unread = new Set(status?.unreadFiles ?? []);
+    const wholeReason = status?.incomplete ?? (truncated ? "the diff was truncated before this file's changes" : undefined);
+    if (!wholeReason && !unread.size)
+        return null;
+    let covered = null;
+    if (wholeReason) {
+        const blocks = diffBlockFiles(diff);
+        if (truncated)
+            blocks.pop();
+        covered = new Set(blocks);
+    }
+    const outsideDiff = (f) => covered !== null && !covered.has(f);
+    return {
+        missing: (f) => unread.has(f) || outsideDiff(f),
+        reason: (files) => {
+            const parts = [];
+            if (files.some(outsideDiff))
+                parts.push(wholeReason);
+            if (files.some((f) => unread.has(f)))
+                parts.push("file content could not be read");
+            return parts.join("; ");
+        },
+    };
+}
+/** Best-effort new path from a `diff --git <a> <b>` line, used only when a block
+ *  has no ---/+++ header (binary or mode-only). Unambiguous when both sides are
+ *  the same path, which is the case for every non-rename block. */
+function gitHeaderNewPath(rest) {
+    const line = rest.replace(/\r$/, "");
+    if (line.startsWith('"')) {
+        const close = /^"(?:[^"\\]|\\.)*"/.exec(line);
+        if (!close)
+            return "";
+        const second = line.slice(close[0].length + 1);
+        return stripAB(unquoteGitPath(second.startsWith('"') ? second : second.trim()));
+    }
+    if (line.endsWith('"')) {
+        const open = line.lastIndexOf(' "');
+        return open >= 0 ? stripAB(unquoteGitPath(line.slice(open + 1))) : "";
+    }
+    // "a/P b/P": both halves have equal length when old and new path agree.
+    if ((line.length - 1) % 2 === 0) {
+        const half = (line.length - 1) / 2;
+        const a = line.slice(0, half), b = line.slice(half + 1);
+        if (stripAB(a) === stripAB(b))
+            return stripAB(b);
+    }
+    const lastB = line.lastIndexOf(" b/");
+    return lastB >= 0 ? line.slice(lastB + 3) : "";
+}
 export function analyzeDiff(diff) {
     const filesAdded = new Set();
     const filesDeleted = new Set();
@@ -106,24 +248,24 @@ export function analyzeDiff(diff) {
                 curDeleted = true;
             }
             else if (raw.startsWith("rename from ")) {
-                renameFrom = raw.slice("rename from ".length).trim();
+                renameFrom = headerPath(raw.slice("rename from ".length));
             }
             else if (raw.startsWith("copy from ")) {
-                renameFrom = raw.slice("copy from ".length).trim();
+                renameFrom = headerPath(raw.slice("copy from ".length));
             }
             else if (raw.startsWith("rename to ") || raw.startsWith("copy to ")) {
-                const to = raw.slice(raw.indexOf(" to ") + 4).trim();
+                const to = headerPath(raw.slice(raw.indexOf(" to ") + 4));
                 curFile = to;
                 if (isSubstantive(to))
                     filesRenamed.push({ from: renameFrom, to });
             }
             else if (raw.startsWith("--- ")) {
-                const p = raw.slice(4).trim();
+                const p = headerPath(raw.slice(4));
                 if (p !== "/dev/null")
                     curFile = stripAB(p); // old path (may be replaced by +++)
             }
             else if (raw.startsWith("+++ ")) {
-                const p = raw.slice(4).trim();
+                const p = headerPath(raw.slice(4));
                 if (p !== "/dev/null")
                     curFile = stripAB(p); // new path preferred
                 if (isSubstantive(curFile)) {

package/dist/extractors/git.d.ts

@@ -143,6 +143,9 @@ export declare function isolatedHeadSha(cwd: string): string;
  *  without deleting it locally. `--ignore-unmatch` makes an already-untracked path a
  *  no-op rather than an error; best-effort (a non-repo dir just no-ops). */
 export declare function gitUntrackCached(cwd: string, paths: string[]): void;
+/** Tracked files under the given pathspecs (repo-relative, POSIX). Best-effort:
+ *  `[]` when not a repository or nothing is tracked there. */
+export declare function gitTrackedPaths(cwd: string, paths: string[]): string[];
 /** Resolve any commit-ish (short sha / HEAD / branch) to a canonical full sha.
  *  Returns the input unchanged if it can't be resolved (e.g. not a git repo). */
 export declare function revParse(ref: string, cwd: string): string;
@@ -222,9 +225,28 @@ export type CommitRepairStatus = "orphaned" | "current" | "unresolvable" | "unkn
  *  be treated as repair-eligible; collapsing "false" and "error" into one
  *  boolean is exactly the bug this type exists to prevent. */
 export declare function commitRepairStatus(commit: string, ref: string, cwd: string): CommitRepairStatus;
-/** The unified diff for a commit, truncated to keep synthesis prompts bounded.
+/** Byte budget for a diff embedded in a SYNTHESIS prompt. Gates never use it: a
+ *  constraint check over a prefix of a change would read every file past the
+ *  cutoff as "no added lines" and pass it. */
+export declare const SYNTHESIS_DIFF_BUDGET = 60000;
+/** The diff a GATE evaluates (`hunch check`, the CI Constraint Guard, merge verdict,
+ *  veto, PR impact). Complete — no byte budget and no noise exclusion — or explicitly
+ *  marked incomplete, so content-matched constraints fail closed instead of reading a
+ *  missing hunk as "nothing added". */
+export interface GateDiff {
+    diff: string;
+    /** Why the diff cannot be trusted as complete (git failed, or its output exceeded
+     *  the capture ceiling). Every file without a diff block is then unevaluable. */
+    incomplete?: string;
+    /** Files whose content could not be read into the diff; unevaluable individually. */
+    unreadFiles?: string[];
+}
+/** Complete gating diff of one commit (see GateDiff). */
+export declare function commitGateDiff(sha: string, cwd: string): GateDiff;
+/** The unified diff for a commit, truncated to keep SYNTHESIS prompts bounded.
  *  Machine-generated noise (see DIFF_NOISE) is excluded so the model spends its
- *  budget on code that encodes intent, not on regenerated lockfiles/build output. */
+ *  budget on code that encodes intent, not on regenerated lockfiles/build output.
+ *  Not for gating: use commitGateDiff. */
 export declare function commitDiff(sha: string, cwd: string, maxBytes?: number): string;
 /** Number of commits touching a file in the last `days` (churn). */
 export declare function fileChurn(file: string, cwd: string, days?: number): number;
@@ -278,18 +300,25 @@ export declare function rangeFiles(base: string, cwd: string, head?: string): st
 /** Commit subjects on `head` since `base` (2-dot: commits added by the task),
  *  oldest-first, for distilling a runbook's ordered steps (roadmap #5). */
 export declare function rangeSubjects(base: string, cwd: string, head?: string, max?: number): string[];
-/** The PR's unified diff vs `base` (3-dot), for the Regression Guard's structural
- *  analysis. Same noise-exclusion + truncation budget as commit/staged diffs. */
+/** Complete gating diff of a PR vs `base` (3-dot: the CI Constraint Guard's surface). */
+export declare function rangeGateDiff(base: string, cwd: string, head?: string): GateDiff;
+/** The PR's unified diff vs `base` (3-dot), noise-excluded and capped at the
+ *  synthesis budget. Bounded-prompt use only; gates use rangeGateDiff. */
 export declare function rangeDiff(base: string, cwd: string, head?: string, maxBytes?: number): string;
-/** Unified diff of the staged changes (for the Regression Guard's structural
- *  analysis). Excludes machine-generated noise and truncates at the SAME budget as
- *  commitDiff, so the staged and `--commit` guard paths can't diverge on big diffs. */
+/** Complete gating diff of the staged changes (pre-commit `hunch check`). */
+export declare function stagedGateDiff(cwd: string): GateDiff;
+/** Unified diff of the staged changes, noise-excluded and capped at the synthesis
+ *  budget. Bounded-prompt use only; gates use stagedGateDiff. */
 export declare function stagedDiff(cwd: string, maxBytes?: number): string;
-/** Unified diff of the complete local working tree vs HEAD. Git's normal diff
+/** Complete gating diff of the local working tree vs HEAD. Git's normal diff
  * includes both staged and unstaged tracked edits; untracked text files are
- * appended as synthetic additions so guards can also see their added symbols.
- * Binary/unreadable files remain in workingFiles (scope checks still apply) but
- * intentionally contribute no synthetic content to regression analysis. */
+ * appended as synthetic additions so guards can also see their added lines.
+ * Binary files and non-regular paths (symlinks) contribute no content, as in a
+ * git diff; an untracked regular file that cannot be read is listed in
+ * `unreadFiles`, so content checks over it fail closed. */
+export declare function workingGateDiff(cwd: string): GateDiff;
+/** Working-tree diff vs HEAD capped at the synthesis budget. Bounded-prompt use
+ *  only; gates and rule verification use workingGateDiff. */
 export declare function workingDiff(cwd: string, maxBytes?: number): string;
 /** Resolve a time-travel ref (commit / tag / branch / HEAD~n) to the ISO author-
  *  date of that commit — the instant valid-time windows are filtered against.