@intentius/chant 0.124.13 → 0.124.14

package/dist/op/work-lease-run.js

@@ -0,0 +1,393 @@
+/**
+ * An Op run under a work item's lease (#2748, the Steward's gap 4 in #2731).
+ *
+ * An Op that declares `workLease` (`./types.ts`) runs its steps under the work
+ * lease of one work item (`../lifecycle/work-lease.ts`, ws-055). The local
+ * executor (`./local-executor.ts`) drives the {@link RunWorkLease} here:
+ *
+ * - Claim. Before the first step when the item is a literal or named by the
+ *   run (`chant run <op> --work <id>`); right after the producing step when
+ *   the item is a reference to a step's output. A list of candidates is tried
+ *   in order and the first one nobody holds is taken. When nothing can be
+ *   claimed the run ends `ok` with its remaining steps skipped, and the claim's
+ *   record carries the refusal, which names who holds the item.
+ * - Heartbeat. While the steps run, the lease is renewed every third of its
+ *   time to live, keeping its fencing token. A renewal the lease refuses (it
+ *   ran out and someone else claimed it, or it was released) means the lease
+ *   is lost: the in-flight step's abort signal fires, no further step starts,
+ *   and the run fails with `lease-lost`. A renewal that fails for any other
+ *   reason (the remote didn't answer) is retried at the next beat; if that
+ *   goes on past the expiry, the next renewal is refused and the lease is lost
+ *   then. These are the semantics of chud's dispatcher
+ *   (packages/runtime/src/dispatch.mjs), which this replaces.
+ * - Fence. Before the run's record is written, one last renewal checks that
+ *   the lease is still this run's, with the same token. Refused, the run is
+ *   recorded as failed with `lease-lost`, never as done.
+ * - Release. When the run ends, the lease is given back with the run's
+ *   outcome (`done`, `not_done`, `gated`, `waiting`, or the Op's own
+ *   `outcome`), which lands on `_leases/<id>.jsonl`. Outcomes are a closed
+ *   list (`WORK_LEASE_OUTCOMES`, #3147): an Op's own outcome outside it is
+ *   released `not_done`, with a note naming it. A lost lease is not
+ *   released: it isn't this run's to give back.
+ *
+ * Steps read the lease through {@link workLeaseOutput}: its item, holder,
+ * token and expiry, and for an Op that changes the checkout, the worktree and
+ * branch it works in. An activity that writes somewhere a token can fence
+ * (another ledger, a remote) passes the token along.
+ *
+ * ## Changing the checkout
+ *
+ * An Op with `changesCheckout` (applying a build, `chant workspace upgrade`)
+ * must declare `workLease`, and its leased steps get a git worktree of their
+ * own: `chant/work/<item>` checked out under the repository's git directory,
+ * from the checkout's HEAD, or from the branch as an earlier run left it. The
+ * worktree is removed when the run ends and the branch keeps whatever the
+ * steps committed, for the runner to deliver. The checkout a coding agent is
+ * editing, its index and its uncommitted files, are never touched.
+ *
+ * A run that ends `not_done` keeps its attempt aside (#3147): whatever the
+ * steps committed on the branch since the run started, and anything they
+ * left uncommitted in the worktree, is committed to
+ * `refs/chant/kept/[<member>/]<item>/<token>`, and the branch goes back to
+ * where the run started. The next attempt starts clean, and the earlier one
+ * stays readable by its lease token (`chant workspace work history`).
+ */
+import { existsSync, rmSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { getRuntime } from "../runtime-adapter.js";
+import { claimWorkLease, DEFAULT_WORK_LEASE_TTL_MS, isWorkLeaseOutcome, keptAttemptRef, releaseWorkLease, renewWorkLease, workLeaseRef, isWorkItemId, workItemIdProblem, } from "../lifecycle/work-lease.js";
+import { resolveMemberLedger } from "../lifecycle/member-ledger.js";
+import { currentHolderId } from "../lifecycle/lease.js";
+import { parseDuration } from "./duration.js";
+import { isStepOutputRef, stepOutput } from "./step-output-ref.js";
+import { WORK_LEASE_STEP_ID } from "./types.js";
+export { WORK_LEASE_STEP_ID } from "./types.js";
+export { workLeaseProblems, workLeaseNeedsRunItem } from "./work-lease-decl.js";
+/** Why a run under a work lease failed when the lease was lost: chud's reason, kept. */
+export const LEASE_LOST = "lease-lost";
+/** The branch prefix an Op that changes the checkout works on. */
+export const WORK_BRANCH_PREFIX = "chant/work/";
+/**
+ * A reference to the run's work lease, for a step's args:
+ * `workLeaseOutput("token")`, `workLeaseOutput("worktree")`, or the whole
+ * {@link WorkLeaseOutput} with no path.
+ */
+export function workLeaseOutput(path) {
+    return stepOutput(WORK_LEASE_STEP_ID, path);
+}
+/**
+ * The holder a steward's turn claims work leases as:
+ * `<steward>/<op>@<process>`. `chant workspace status --json` reads it back
+ * to show the lease a steward's current turn holds beside its Ops.
+ */
+export function stewardWorkHolder(steward, op, process = currentHolderId()) {
+    return `${steward}/${op}@${process}`;
+}
+function resolvePath(value, path) {
+    if (!path)
+        return value;
+    return path.split(".").reduce((acc, key) => (acc == null ? acc : acc[key]), value);
+}
+async function git(args, cwd) {
+    const out = await getRuntime().spawn(["git", ...args], { cwd });
+    return { ok: out.exitCode === 0, stdout: out.stdout.trim(), stderr: out.stderr.trim() };
+}
+/** One run's hold on one work item's lease. Created by the executor for an Op with `workLease`. */
+export class RunWorkLease {
+    constructor(config, opts) {
+        this.config = config;
+        this.opts = opts;
+        /** Set once the claim was made or given up on. */
+        this.attempted = false;
+        this.abort = new AbortController();
+        if (!config.workLease)
+            throw new Error(`Op "${config.name}" declares no workLease`);
+        this.spec = config.workLease;
+        this.holder = opts.holder ?? currentHolderId();
+        this.ttlMs = this.spec.ttl ? parseDuration(this.spec.ttl) : DEFAULT_WORK_LEASE_TTL_MS;
+        this.lostSignal = this.abort.signal;
+    }
+    /** The directory whose ledger holds the lease: the kind file's, or the project's. */
+    get ledgerCwd() {
+        const kind = this.spec.kind;
+        if (!kind)
+            return this.opts.cwd;
+        const file = isAbsolute(kind) ? kind : resolve(this.opts.cwd, kind);
+        return resolve(file, "..");
+    }
+    /** Whether the claim is due at a step boundary, given the results so far. */
+    due(resultsById) {
+        if (this.attempted)
+            return false;
+        if (this.opts.item !== undefined)
+            return true;
+        const item = this.spec.item;
+        return !isStepOutputRef(item) || resultsById.has(item.step);
+    }
+    /** The candidate ids, in order. Empty when the reference resolved to nothing. */
+    candidates(resultsById) {
+        if (this.opts.item !== undefined)
+            return [this.opts.item];
+        const item = this.spec.item;
+        const value = isStepOutputRef(item) ? resolvePath(resultsById.get(item.step), item.path) : item;
+        if (value === undefined || value === null || value === "")
+            return [];
+        const list = Array.isArray(value) ? value : [value];
+        return list.filter((v) => v !== undefined && v !== null && v !== "").map((v) => {
+            if (!isWorkItemId(v)) {
+                throw new Error(`Op "${this.config.name}": workLease.item resolved to ${JSON.stringify(v)}, which can't key a work lease${typeof v === "string" ? ` (${workItemIdProblem(v)})` : ""}`);
+            }
+            return v;
+        });
+    }
+    /**
+     * Claim the first candidate nobody holds. On a claim, the heartbeat starts,
+     * and for an Op that changes the checkout its worktree is made. Throws when
+     * the claim could not be made for a reason other than someone holding it
+     * (git failed): the run fails, as for any failing step.
+     */
+    async claim(resultsById) {
+        this.attempted = true;
+        const tried = this.candidates(resultsById);
+        if (tried.length === 0) {
+            this.refusal = "nothing to claim: the work item resolved to no id";
+            return { kind: "unclaimed", refusal: this.refusal, tried };
+        }
+        const refused = [];
+        for (const id of tried) {
+            const result = await claimWorkLease(id, this.holder, { cwd: this.ledgerCwd, ttlMs: this.ttlMs, note: `op ${this.config.name}` });
+            if (!result.ok) {
+                refused.push(`${result.reason}: ${result.message}`);
+                continue;
+            }
+            const { prefix, members } = await resolveMemberLedger(this.ledgerCwd);
+            const lease = {
+                ...pick(result.lease),
+                ref: workLeaseRef(id, prefix),
+                worktree: null,
+                branch: null,
+            };
+            this.lease = lease;
+            if (this.config.changesCheckout) {
+                try {
+                    const made = await this.makeWorktree(id, members);
+                    lease.worktree = made.worktree;
+                    lease.branch = made.branch;
+                }
+                catch (err) {
+                    await releaseWorkLease(id, this.holder, { cwd: this.ledgerCwd, token: lease.token, outcome: "not_done", note: "the worktree could not be made" }).catch(() => undefined);
+                    this.lease = undefined;
+                    throw err;
+                }
+            }
+            this.startHeartbeat();
+            return { kind: "claimed", lease, tried };
+        }
+        this.refusal = refused.join("; ");
+        return { kind: "unclaimed", refusal: this.refusal, tried };
+    }
+    /**
+     * A worktree for `id` on `chant/work/[<member>/]<id>`, under the git
+     * directory so the checkout's own `git status` never lists it. Starts from
+     * the branch when an earlier run left it, from HEAD otherwise.
+     */
+    async makeWorktree(id, members) {
+        const cwd = this.opts.cwd;
+        const common = await git(["rev-parse", "--git-common-dir"], cwd);
+        if (!common.ok)
+            throw new Error(`Op "${this.config.name}" changes the checkout, but ${cwd} is not a git checkout: ${common.stderr}`);
+        const commonDir = isAbsolute(common.stdout) ? common.stdout : resolve(cwd, common.stdout);
+        const scope = members.join("/");
+        const branch = `${WORK_BRANCH_PREFIX}${scope ? `${scope}/` : ""}${id}`;
+        const worktree = join(commonDir, "chant-work", ...members, id);
+        if (existsSync(worktree)) {
+            await git(["worktree", "remove", "--force", worktree], cwd);
+            rmSync(worktree, { recursive: true, force: true });
+        }
+        await git(["worktree", "prune"], cwd);
+        const exists = (await git(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], cwd)).ok;
+        const add = exists
+            ? await git(["worktree", "add", "--quiet", worktree, branch], cwd)
+            : await git(["worktree", "add", "--quiet", "-b", branch, worktree, "HEAD"], cwd);
+        if (!add.ok)
+            throw new Error(`Op "${this.config.name}": could not make the worktree for ${id} on ${branch}: ${add.stderr}`);
+        const base = await git(["rev-parse", "HEAD"], worktree);
+        if (base.ok)
+            this.start = { base: base.stdout, members };
+        return { worktree, branch };
+    }
+    lose(why) {
+        if (this.lost !== undefined)
+            return;
+        this.lost = why;
+        this.stopHeartbeat();
+        this.abort.abort(new Error(`${LEASE_LOST}: ${why}`));
+    }
+    /** One renewal. Refused, the lease is lost; failed otherwise, the next beat retries. */
+    async renew() {
+        const lease = this.lease;
+        if (!lease || this.lost !== undefined)
+            return;
+        try {
+            const result = await renewWorkLease(lease.item, this.holder, { cwd: this.ledgerCwd, ttlMs: this.ttlMs, token: lease.token });
+            if (result.ok) {
+                lease.expiresAt = result.lease.expiresAt;
+                return;
+            }
+            // The remote refusing the push is the lease held elsewhere only when it
+            // says who holds it; unreachable, the next beat tries again.
+            if (result.reason === "lease-push-rejected" && !result.heldBy) {
+                this.opts.onRenewError?.(result.message);
+                return;
+            }
+            if (result.reason === "lease-race") {
+                this.opts.onRenewError?.(result.message);
+                return;
+            }
+            this.lose(result.message);
+        }
+        catch (err) {
+            this.opts.onRenewError?.(err instanceof Error ? err.message : String(err));
+        }
+    }
+    startHeartbeat() {
+        const every = Math.max(1000, Math.floor(this.ttlMs / 3));
+        this.timer = setInterval(() => {
+            if (this.beat)
+                return;
+            this.beat = this.renew().finally(() => {
+                this.beat = undefined;
+            });
+        }, every);
+        this.timer.unref?.();
+    }
+    stopHeartbeat() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /**
+     * The last renewal before the run's record is written, after the heartbeat
+     * stops. Returns whether the lease is still this run's.
+     */
+    async fence() {
+        if (!this.lease)
+            return this.lost === undefined;
+        this.stopHeartbeat();
+        await this.beat;
+        if (this.lost !== undefined)
+            return false;
+        const lease = this.lease;
+        try {
+            const result = await renewWorkLease(lease.item, this.holder, { cwd: this.ledgerCwd, ttlMs: this.ttlMs, token: lease.token });
+            if (result.ok)
+                lease.expiresAt = result.lease.expiresAt;
+            else
+                this.lose(result.message);
+        }
+        catch (err) {
+            this.lose(`the lease could not be renewed before the run was recorded: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return this.lost === undefined;
+    }
+    /**
+     * End the run's hold: stop the heartbeat, remove the worktree (the branch
+     * keeps what was committed), and give the lease back with the outcome
+     * unless it was lost.
+     */
+    async finish(status, resultsById) {
+        this.stopHeartbeat();
+        await this.beat;
+        const lease = this.lease;
+        const base = {
+            item: lease?.item ?? null,
+            holder: this.holder,
+            token: lease?.token ?? null,
+            branch: lease?.branch ?? null,
+            released: false,
+            outcome: null,
+            kept: null,
+            lost: this.lost ?? null,
+            refusal: this.refusal ?? null,
+        };
+        if (!lease)
+            return base;
+        let outcome = status === "ok" ? "done" : status === "gated" || status === "waiting" ? status : "not_done";
+        let note = `op ${this.config.name}`;
+        if (status === "ok" && this.spec.outcome && isStepOutputRef(this.spec.outcome)) {
+            const declared = resolvePath(resultsById.get(this.spec.outcome.step), this.spec.outcome.path);
+            if (typeof declared === "string" && declared.trim() !== "") {
+                const word = declared.trim();
+                if (isWorkLeaseOutcome(word))
+                    outcome = word;
+                else {
+                    outcome = "not_done";
+                    note = `op ${this.config.name}: its outcome ${JSON.stringify(word.slice(0, 80))} is not a work lease outcome`;
+                }
+            }
+        }
+        let kept = null;
+        if (lease.worktree && this.lost === undefined && outcome === "not_done") {
+            kept = await this.keepAttempt(lease).catch(() => null);
+        }
+        if (lease.worktree) {
+            await git(["worktree", "remove", "--force", lease.worktree], this.opts.cwd).catch(() => undefined);
+            rmSync(lease.worktree, { recursive: true, force: true });
+            await git(["worktree", "prune"], this.opts.cwd).catch(() => undefined);
+        }
+        if (this.lost !== undefined)
+            return base;
+        const released = await releaseWorkLease(lease.item, this.holder, {
+            cwd: this.ledgerCwd,
+            token: lease.token,
+            outcome,
+            note,
+        }).catch(() => undefined);
+        // #3172: the box's replicate policy may push the kept attempt and the work branch now. Best effort.
+        // Loaded only here, so an Op run outside a workspace never loads workspace modules (#2526).
+        if (released?.ok)
+            (await import("../workspace/wip.js")).replicateAfter("release", this.opts.cwd);
+        return { ...base, kept, released: released?.ok === true, outcome: released?.ok ? outcome : null };
+    }
+    /**
+     * Keep a `not_done` attempt aside (#3147): commit what the steps left in
+     * the worktree, committed or not, at `refs/chant/kept/.../<item>/<token>`,
+     * and move the branch back to where the run started. Returns the ref, or
+     * null when the attempt changed nothing.
+     */
+    async keepAttempt(lease) {
+        const dir = lease.worktree;
+        const start = this.start;
+        if (!dir || !start)
+            return null;
+        const head = await git(["rev-parse", "HEAD"], dir);
+        if (!head.ok)
+            return null;
+        if (!(await git(["add", "-A"], dir)).ok)
+            return null;
+        const tree = await git(["write-tree"], dir);
+        const headTree = await git(["rev-parse", `${head.stdout}^{tree}`], dir);
+        if (!tree.ok || !headTree.ok)
+            return null;
+        let commit = head.stdout;
+        if (tree.stdout !== headTree.stdout) {
+            // An identity only when git has none, so a configured one is kept.
+            const ident = (await git(["var", "GIT_COMMITTER_IDENT"], dir)).ok && (await git(["var", "GIT_AUTHOR_IDENT"], dir)).ok;
+            const who = ident ? [] : ["-c", "user.name=chant", "-c", "user.email=chant@localhost"];
+            const made = await git([...who, "commit-tree", tree.stdout, "-p", head.stdout, "-m", `${lease.item}: not done, kept (lease ${lease.token})`], dir);
+            if (!made.ok)
+                return null;
+            commit = made.stdout;
+        }
+        if (commit === start.base)
+            return null;
+        const ref = keptAttemptRef(lease.item, lease.token, start.members);
+        if (!(await git(["update-ref", ref, commit], dir)).ok)
+            return null;
+        await git(["reset", "-q", "--hard", start.base], dir);
+        return ref;
+    }
+}
+function pick(lease) {
+    return { item: lease.item, holder: lease.holder, token: lease.token, acquiredAt: lease.acquiredAt, expiresAt: lease.expiresAt };
+}

package/dist/override-gate.js

@@ -0,0 +1,284 @@
+/**
+ * The override gate (#3760, decision #3756): a person's recorded, reasoned
+ * decision to apply one plan a policy denied, spent once a run applies it.
+ *
+ * The policy engines stay in the products (OPA and conftest in terragucci,
+ * config rules in SQL Yodeler). They say a plan is denied and by which rules.
+ * This module records and decides the overrides of those denials, so a
+ * product keeps a thin layer over it:
+ *
+ * - A denial is a pending fact on `_gates/policy-override.jsonl` on
+ *   `chant/lifecycle`, gate the subject (a root, an environment, whatever the
+ *   product applies one plan to), with the rules that denied it
+ *   ({@link overridePending}). Its `planDigest` is the override digest
+ *   ({@link overrideDigest}), which binds the subject, the plan digest and
+ *   the rule ids, so `chant approve` copies it by default.
+ * - An override is an approval of that gate and digest, written with
+ *   `chant approve policy-override <subject> --rule <id> --reason <text>`
+ *   (`--sign` under `sealed`). The reason is its `note`.
+ * - It counts ({@link decideOverride}) when it is newer than the subject's
+ *   newest pending fact, names this digest, was written by a person the
+ *   overriders at base list ({@link overridersAt}), gives a reason, and under
+ *   `sealed` carries a seal that verifies for its approver against the
+ *   signers file at base. A line a job wrote (one that carries `via` or a
+ *   forge `review`) or an agent wrote never counts.
+ * - Before a run applies under an override it appends an applied record
+ *   ({@link appliedOverride}) to `_gates/policy-override/applied.jsonl`. An
+ *   override with an applied record is spent: it counts for nothing again, so
+ *   a plan that is denied again waits for its own override, and a spent
+ *   override of an older plan is not reported as a moved plan.
+ *
+ * Like `./gate-decision.ts` it reads the lines it is handed and writes
+ * nothing; `override-gate-bundle.test.ts` holds its import graph to the
+ * same bundle. chant's own writers are in `./lifecycle/override-ledger.ts`.
+ */
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { OVERRIDE_GATE_OP } from "./op/gate-name.js";
+import { latestPendingGate } from "./lifecycle/gate-ledger-select.js";
+import { samePlanDigest } from "./lifecycle/plan-digest.js";
+import { gateSealRefusal } from "./workspace/trust/gate-seal.js";
+import { DEFAULT_SIGNERS_PATH } from "./workspace/trust/trust-files.js";
+/** The op every override and denial is recorded under. `./lifecycle/gate-audit.ts` reads this op as overrides by default. */
+export const OVERRIDE_OP = OVERRIDE_GATE_OP;
+/** The ledger file on `chant/lifecycle` that holds denials and overrides. */
+export const OVERRIDE_LEDGER = `_gates/${OVERRIDE_OP}.jsonl`;
+/** The file beside it that holds the overrides a run applied under. chant reads only the `.jsonl` files directly under `_gates/` as gate ledgers, so it never reads these lines as gate records. */
+export const OVERRIDE_APPLIED = `_gates/${OVERRIDE_OP}/applied.jsonl`;
+/** Where the overriders are read at base when the caller names no other file: one principal per line, `#` starts a comment. */
+export const OVERRIDERS_PATH = ".chant/overriders";
+// ── the digest ───────────────────────────────────────────────────────────
+/** The rules as an override names them: trimmed, each once, sorted. */
+export function sortedRules(rules) {
+    return [...new Set(rules.map((r) => r.trim()).filter(Boolean))].sort();
+}
+/**
+ * The digest an override binds: the subject, its plan digest and the rules
+ * that denied it, as `sha256:<hex>` over their LF-joined lines after the op
+ * name. A plan that moved, or a different set of rules, gives another digest,
+ * so an override of one denial never lets another through.
+ */
+export function overrideDigest(subject, planDigest, rules) {
+    const text = [OVERRIDE_OP, subject, planDigest, ...sortedRules(rules)].join("\n");
+    return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+/** The command that overrides a denial. */
+export function overrideCommand(subject, rules, sealed = false) {
+    return `chant approve ${OVERRIDE_OP} ${subject} ${sortedRules(rules).map((r) => `--rule ${r}`).join(" ")} --reason "<why>"${sealed ? " --sign" : ""}`;
+}
+/** The pending fact a run records when the policy denies a plan and no override counts for it ({@link decideOverride} returns no `standing` fact). Appending it is the caller's. */
+export function overridePending(input) {
+    const rules = sortedRules(input.rules);
+    return {
+        version: 1,
+        kind: "pending",
+        op: OVERRIDE_OP,
+        gate: input.subject,
+        timestamp: input.timestamp,
+        expiresAt: input.expiresAt,
+        planDigest: overrideDigest(input.subject, input.planDigest, rules),
+        plan: input.planDigest,
+        rules,
+        description: input.description ?? `the policy denied this plan (${rules.join(", ")})`,
+        ...(input.runId ? { runId: input.runId } : {}),
+        ...(input.url ? { url: input.url } : {}),
+    };
+}
+const time = (iso) => new Date(iso).getTime();
+/** The denials on the ledger: each subject's newest pending fact of the override op that names a plan. Sorted by subject. */
+export function recordedDenials(pending) {
+    const newest = new Map();
+    for (const p of pending) {
+        if (p.op !== OVERRIDE_OP || !p.planDigest)
+            continue;
+        const before = newest.get(p.gate);
+        if (!before || time(p.timestamp) >= time(before.timestamp))
+            newest.set(p.gate, p);
+    }
+    return [...newest.values()]
+        .map((p) => {
+        const r = p;
+        return { ...p, plan: typeof r.plan === "string" ? r.plan : "", rules: Array.isArray(r.rules) ? sortedRules(r.rules.filter((x) => typeof x === "string")) : [] };
+    })
+        .sort((a, b) => (a.gate < b.gate ? -1 : a.gate > b.gate ? 1 : 0));
+}
+/** The principals in an overriders file: one per line, blank lines and `#` comments skipped. */
+export function parseOverriders(text) {
+    const out = [];
+    for (const raw of text.split("\n")) {
+        const line = raw.replace(/#.*$/, "").trim();
+        if (line && !out.includes(line))
+            out.push(line);
+    }
+    return out;
+}
+/**
+ * The overriders at `base` (a commit the repository holds, such as
+ * `baseCommit(repo)` from `@intentius/chant/gate-decision`), from `path`
+ * (default {@link OVERRIDERS_PATH}). Read at base, so the change being
+ * applied cannot add the person who overrides its own denial. A product that
+ * keeps its list in its own config at base reads it there and passes the
+ * principals to {@link decideOverride} instead.
+ */
+export function overridersAt(repo, base, path = OVERRIDERS_PATH) {
+    const r = spawnSync("git", ["cat-file", "blob", `${base}:${path}`], { cwd: repo, encoding: "utf-8" });
+    if (r.status !== 0)
+        return { base, path, active: false, principals: [] };
+    return { base, path, active: true, principals: parseOverriders(r.stdout) };
+}
+/** The applied records in the text of an applied file. Malformed lines, and lines of another kind, are skipped. */
+export function parseAppliedOverrides(text) {
+    const out = [];
+    for (const line of text.split("\n").map((l) => l.trim()).filter(Boolean)) {
+        try {
+            const r = JSON.parse(line);
+            if (r.version === 1 && r.kind === "applied" && typeof r.op === "string" && typeof r.gate === "string" && typeof r.planDigest === "string" && typeof r.approvedAt === "string") {
+                out.push(r);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+const norm = (s) => s.normalize("NFKC").trim().toLowerCase();
+/** Why this ledger line does not count as an override, or null when it does. */
+export function overrideRefusal(rule, r) {
+    const line = r;
+    if (line.via !== undefined)
+        return `the override line was written by a job (via ${String(line.via)}), and an override is a person's`;
+    if (r.review !== undefined)
+        return `the override line came from the review of #${r.review.pr}, and an override is a person's own line`;
+    if (r.approver?.kind === "agent")
+        return `the override by ${r.resolvedBy} was recorded by an agent, and an override is a person's`;
+    const where = `${rule.overridersPath ?? OVERRIDERS_PATH} at base`;
+    if (!rule.overriders.map(norm).includes(norm(r.resolvedBy))) {
+        return `${r.resolvedBy} is not listed in ${where}${rule.overriders.length ? ` (${rule.overriders.join(", ")})` : ", which lists nobody"}`;
+    }
+    if (!r.note?.trim())
+        return `the override by ${r.resolvedBy} gives no reason`;
+    if (rule.mode === "sealed") {
+        const signers = rule.signers ?? { base: null, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems: ["no signers were read for this sealed override"] };
+        return gateSealRefusal(signers, r);
+    }
+    return null;
+}
+/**
+ * Decide one denied plan against the override ledger, as `decideGateApproval`
+ * decides a gate: a line counts only when it is an override of this subject
+ * newer than the subject's newest pending fact, names this digest, passes
+ * {@link overrideRefusal}, and is not spent (an applied record of its digest
+ * made at or after it). The newest counting line wins.
+ *
+ * Decide before recording a denial: an override written after an expired
+ * pending fact still counts, and a run that records a fresh fact first would
+ * make it older than the anchor.
+ */
+export function decideOverride(input) {
+    const rules = sortedRules(input.rules);
+    const digest = overrideDigest(input.subject, input.planDigest, rules);
+    const pending = input.ledger.pending.filter((p) => p.op === OVERRIDE_OP);
+    const latest = latestPendingGate(pending, input.subject);
+    const since = latest ? time(latest.timestamp) : 0;
+    const applied = (input.applied ?? []).filter((a) => a.op === OVERRIDE_OP && a.gate === input.subject);
+    const spentBy = (r) => r.planDigest === undefined ? undefined : applied.find((a) => samePlanDigest(a.planDigest, r.planDigest) && time(a.approvedAt) >= time(r.timestamp));
+    const newer = (r, best) => !best || time(r.timestamp) >= time(best.timestamp);
+    let matched;
+    let mismatched;
+    let used;
+    const refusals = [];
+    for (const r of input.ledger.resolutions) {
+        if (r.op !== OVERRIDE_OP || r.gate !== input.subject || time(r.timestamp) < since)
+            continue;
+        const why = overrideRefusal(input, r);
+        const spent = spentBy(r);
+        if (samePlanDigest(r.planDigest, digest)) {
+            if (why !== null)
+                refusals.push(why);
+            else if (spent)
+                refusals.push(`the override by ${r.resolvedBy} at ${r.timestamp} is spent: a run applied under it at ${spent.timestamp}`);
+            else if (newer(r, matched))
+                matched = r;
+        }
+        else if (why !== null) {
+            continue;
+        }
+        else if (spent) {
+            if (newer(r, used))
+                used = r;
+        }
+        else if (newer(r, mismatched)) {
+            mismatched = r;
+        }
+    }
+    if (matched) {
+        return {
+            status: "overridden",
+            digest,
+            override: {
+                subject: input.subject,
+                by: matched.resolvedBy,
+                at: matched.timestamp,
+                reason: matched.note.trim(),
+                rules,
+                planDigest: input.planDigest,
+                digest,
+                sealed: input.mode === "sealed",
+                resolution: matched,
+            },
+        };
+    }
+    const now = input.now ?? new Date().toISOString();
+    const standing = latest && time(latest.expiresAt) > time(now) && samePlanDigest(latest.planDigest, digest)
+        ? recordedDenials([latest])[0]
+        : undefined;
+    if (mismatched)
+        return { status: "moved", digest, by: mismatched.resolvedBy, was: mismatched.planDigest, refusals, ...(standing ? { standing } : {}) };
+    return {
+        status: "none",
+        digest,
+        refusals,
+        ...(standing ? { standing } : {}),
+        ...(used ? { spent: { digest: used.planDigest, by: used.resolvedBy, at: used.timestamp } } : {}),
+    };
+}
+/**
+ * The applied record a run appends before it applies under `override`, which
+ * spends it. Appending it is the caller's. It reads only the subject, the
+ * override digest and the override's time and approver, so a product that
+ * carries those through its own record can pass them without the ledger line
+ * (#3823); a whole {@link StandingOverride} still works.
+ */
+export function appliedOverride(override, at) {
+    return {
+        version: 1,
+        kind: "applied",
+        op: OVERRIDE_OP,
+        gate: override.subject,
+        planDigest: override.digest,
+        approvedAt: override.at,
+        approvedBy: override.by,
+        timestamp: at.timestamp,
+        ...(at.runId ? { runId: at.runId } : {}),
+        ...(at.commit ? { commit: at.commit } : {}),
+    };
+}
+/**
+ * The applied records as applies for the audit reader
+ * (`@intentius/chant/lifecycle/gate-audit`), each citing the override it
+ * spent, so the trail shows an `override-spent` entry for it and a gap when
+ * the ledger holds no such override. A product that records its applies
+ * elsewhere cites the override on its own apply instead.
+ */
+export function overrideAuditApplies(applied, path = OVERRIDE_APPLIED) {
+    return applied.map((a, i) => ({
+        ref: `${path}:${i + 1}`,
+        at: a.timestamp,
+        gate: a.gate,
+        op: a.op,
+        approval: "not-required",
+        overrides: [{ gate: a.gate, digest: a.planDigest }],
+        detail: { approvedBy: a.approvedBy, approvedAt: a.approvedAt, ...(a.runId ? { runId: a.runId } : {}), ...(a.commit ? { commit: a.commit } : {}) },
+    }));
+}