approval-md 0.2.0 → 0.4.0

package/dist/src/cli/amend.js

@@ -59,12 +59,14 @@ import { createHash } from "node:crypto";
 import { accessSync, constants, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve as resolvePathSegments, sep } from "node:path";
-import { HUMAN_ACTOR_ENV, appendAttestation, checkAttestation, policyFileHash, resolveHumanActor, } from "../core/attest.js";
+import { HUMAN_ACTOR_ENV, appendAttestation, attestedPolicyPayloadHash, checkAttestation, policyBytesHash, resolveHumanActor, } from "../core/attest.js";
 import { compareChains } from "../core/log-reconcile.js";
 import { diffPolicies, renderDiff, SPEC_NAMESPACES } from "../core/policy-diff.js";
 import { checkPolicyExpectations, describeFailure, describePinChange, diffPinSources, expectationsFor, DOGFOOD_SUITE_BUILT, DOGFOOD_SUITE_SOURCE, EXPECTATIONS_MODULE, } from "../core/policy-expectations.js";
 import { loadPolicy, parseDuration, POLICY_FILENAMES, } from "../core/policy-load.js";
-import { proposalState, proposeAttestation, } from "../core/policy-proposal.js";
+import { payloadHash } from "../core/payload.js";
+import { payloadPath, payloadStoreDirFor } from "../core/payload-store.js";
+import { proposalPayloadValue, proposalState, proposeAttestation, } from "../core/policy-proposal.js";
 import { readVerifiedRecords } from "../core/state.js";
 import { boolFlag, parseFlags, stringFlag } from "./args.js";
 import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_TORN_TAIL, EXIT_USAGE, } from "./exit-codes.js";
@@ -83,6 +85,9 @@ const FLAGS = {
     "--require-load": "boolean",
     "--dry-run": "boolean",
     "--commit": "boolean",
+    // APRV-341: the whole ceremony in one word. Implies `--commit` and forces the
+    // branch flow, so the amendment reaches a protected trunk the only way it can.
+    "--pr": "boolean",
     "--no-publish": "boolean",
     "--branch": "string",
     "--direct": "boolean",
@@ -946,7 +951,11 @@ export function commandPolicyAmend(argv, streams, cwd) {
     }
     const dryRun = boolFlag(parsed.flags, "--dry-run");
     const requireLoad = boolFlag(parsed.flags, "--require-load");
-    const wantCommit = boolFlag(parsed.flags, "--commit");
+    // APRV-341. `--pr` is `--commit` plus "and finish the job": the branch flow,
+    // whatever the protection probe thinks, because the operator has said which
+    // ceremony they want. `--commit` alone keeps letting the probe decide.
+    const wantPr = boolFlag(parsed.flags, "--pr");
+    const wantCommit = boolFlag(parsed.flags, "--commit") || wantPr;
     // APRV-130: the ceremony publishes by default (push, and on a protected main
     // branch + push + PR). `--no-publish` is the operator who wants it to stop at
     // the commit, which is what `--commit` did before the publishing half existed.
@@ -960,6 +969,12 @@ export function commandPolicyAmend(argv, streams, cwd) {
     if (branchFlag !== null && branchFlag.trim().length === 0) {
         return usageError(streams, json, "--branch expects a branch name");
     }
+    if (wantPr && forceDirect) {
+        return usageError(streams, json, "--pr and --direct ask for opposite ceremonies: --pr publishes through a branch and a pull request, --direct commits on the branch you are standing on. Pass one of them");
+    }
+    if (wantPr && noPublish) {
+        return usageError(streams, json, "--pr and --no-publish ask for opposite ceremonies: --pr opens the pull request, --no-publish stops at the commit. Pass one of them");
+    }
     // Identity first, before a byte is read. Asking a human to read a diff and
     // only then telling them their sign-off cannot be attributed wastes the one
     // resource this system spends.
@@ -1006,13 +1021,54 @@ export function commandPolicyAmend(argv, streams, cwd) {
         return refuse(streams, json, "io", policy.message, EXIT_IO);
     const policyPath = policy.path;
     let liveSha256;
+    /**
+     * The live bytes as text, for the payload file this ceremony will commit
+     * (APRV-356).
+     *
+     * One read for both, on the rule `core/attest.ts` states for the same pair:
+     * two reads of a file an operator may still be editing can disagree, and the
+     * digest reported in the report has to be the digest of the bytes whose store
+     * file the `git add` names.
+     */
+    let liveText;
     try {
-        liveSha256 = policyFileHash(policyPath);
+        const liveBytes = readFileSync(policyPath);
+        liveSha256 = policyBytesHash(liveBytes);
+        liveText = liveBytes.toString("utf8");
     }
     catch (cause) {
         return refuse(streams, json, "io", `policy ${policyPath} could not be read: ${detail(cause)}`, EXIT_IO);
     }
     const logPath = resolvePath(stringFlag(parsed.flags, "--log"), DEFAULT_LOG_PATH, cwd);
+    /**
+     * The store file holding the attested policy text, absolute (APRV-356).
+     *
+     * The ceremony commit carries it beside the policy and the log, because a
+     * committed log carrying a binding whose payload file was never committed is
+     * a chain whose in-force bytes are unrecoverable to every reader of the
+     * committed copy, which is the state this task exists to end. The CI
+     * protected-path guard resolves payloads out of committed trees, so that copy
+     * is the one it reads.
+     *
+     * Which file it is depends on which door the attestation comes through, and
+     * both are addressable from the bytes on disk before anything is appended:
+     *
+     * - The HUMAN path appends the attestation here, and since APRV-356 that
+     *   record binds `{ text }` (`core/attest.ts`).
+     * - The AGENT path proposes and waits for a tap. The phone's attestation
+     *   stores nothing, which APRV-356 left unchanged; what carries the text on
+     *   that chain is the `policy.proposed` this ceremony appends, binding
+     *   `{ policy_path, text }` (`core/policy-proposal.ts`).
+     *
+     * Addressed from `liveText` rather than read back from the appended record,
+     * so it is a ceremony file from the start: `--dry-run` names it in the `git
+     * add` it would run, and `--commit` counts it as its own rather than as a
+     * stray in the index. An edit landing between here and the append moves the
+     * hash, and the append refuses on the digest before this path is used.
+     */
+    const payloadFile = payloadPath(payloadStoreDirFor(logPath), agentActor === null
+        ? attestedPolicyPayloadHash(liveText)
+        : payloadHash(proposalPayloadValue(policyPath, liveText)));
     // (a-pre) The thirty-three seconds of silence, ended (APRV-167).
     //
     // Everything from here to the `Policy` block below is work the operator could
@@ -1044,6 +1100,14 @@ export function commandPolicyAmend(argv, streams, cwd) {
                 : EXIT_IO;
         return refuse(streams, json, read.code, read.message, exitCode);
     }
+    /**
+     * The amendment branch's name, `--branch` or the seq-derived default.
+     *
+     * Declared HERE rather than beside the flow selection below (APRV-420): the
+     * no-op path needs it too, because a re-run's whole job is to find the branch
+     * a previous run left standing.
+     */
+    const branchName = (seq) => branchFlag ?? `policy-amend-${seq}`;
     const status = checkAttestation(read.records, policyPath);
     const attested = status.status === "attested"
         ? { sha256: status.sha256, seq: status.seq }
@@ -1053,7 +1117,27 @@ export function commandPolicyAmend(argv, streams, cwd) {
     // (a) Nothing to amend. A no-op ceremony is a SUCCESS, not an error: an
     // operator (or a script) that runs `amend` on an already-attested policy has
     // established exactly what they wanted to establish.
+    //
+    // APRV-420, one exception: an amendment branch already standing on origin.
+    // The live policy does match its attestation, and saying only that leaves the
+    // pull request carrying it open, unmergeable and unarmed, which is the state a
+    // records advance landing first puts it in. So the re-run repairs it, or names
+    // exactly what to run — never "nothing to amend" over a dirty amendment.
     if (status.status === "attested") {
+        const noopRoot = repoRoot(dirname(policyPath));
+        const repair = wantCommit && noopRoot !== null && hasOrigin(noopRoot)
+            ? repairAmendBranch({
+                root: noopRoot,
+                policyPath,
+                logPath,
+                payloadFile,
+                seq: status.seq,
+                branch: branchName(String(status.seq)),
+                // `--dry-run` and `--no-publish` mean the same thing here as
+                // everywhere else in this verb: compute it, print it, run nothing.
+                act: !dryRun && !noPublish,
+            })
+            : null;
         if (json) {
             emitReport(streams, {
                 policyPath,
@@ -1067,12 +1151,24 @@ export function commandPolicyAmend(argv, streams, cwd) {
                 noop: true,
                 dryRun,
                 aborted: false,
+                repair,
             });
         }
-        else {
+        else if (repair === null) {
             streams.out(`nothing to amend: ${relPath(policyPath, cwd)} already matches its attestation at seq ${status.seq} (sha256 ${shortHash(liveSha256)})\n`);
         }
-        return EXIT_OK;
+        else {
+            const headline = repair.state === "failed" ? st.glyph("fail") : st.glyph(repair.state === "owed" ? "point" : "ok");
+            streams.out(`${headline} ${repair.branch}: ${repair.message}\n`);
+            for (const step of repair.commands) {
+                streams.err(`  ${step.ok === null ? st.glyph("point") : step.ok ? st.glyph("ok") : st.glyph("fail")} ${step.command}\n`);
+            }
+        }
+        // A repair that BROKE keeps the I/O exit, which is the split the rest of
+        // this verb uses: the exit code speaks to scripts, the text to people.
+        // `owed` is not a failure — it is `--dry-run` or `--no-publish` answering
+        // the question they were asked — and `landed` and `repaired` are successes.
+        return repair !== null && repair.state === "failed" ? EXIT_IO : EXIT_OK;
     }
     // (b) The baseline, and only a verifiable one. See the module header.
     progress.phase("recovering the attested baseline and diffing it against the live policy");
@@ -1108,8 +1204,11 @@ export function commandPolicyAmend(argv, streams, cwd) {
     const onProtectedDefault = probe.protection === "protected" &&
         probe.currentBranch !== null &&
         probe.currentBranch === probe.defaultBranch;
-    const useBranch = branchFlag !== null || (!forceDirect && onProtectedDefault);
-    const branchName = (seq) => branchFlag ?? `policy-amend-${seq}`;
+    // APRV-341: `--pr` is a third way into the branch flow, and it is the
+    // operator's own instruction rather than an inference from a probe. A probe
+    // that cannot reach GitHub answers `unknown`, which used to mean "commit in
+    // place"; an operator who typed `--pr` has said what they want either way.
+    const useBranch = branchFlag !== null || wantPr || (!forceDirect && onProtectedDefault);
     // The direct flow's push is about to hit a protected branch. Say so before
     // the human types it, rather than after GitHub says it.
     const pushWarning = !useBranch && onProtectedDefault
@@ -1133,9 +1232,9 @@ export function commandPolicyAmend(argv, streams, cwd) {
      */
     let pinsChange = null;
     if (wantCommit && !dryRun) {
-        const plan = planCommit(policyPath, logPath, useBranch ? { branch: branchFlag } : null);
+        const plan = planCommit(policyPath, logPath, payloadFile, useBranch ? { branch: branchFlag } : null);
         if (!plan.ok) {
-            return refuse(streams, json, "commit-preconditions", plan.message, EXIT_USAGE);
+            return refuse(streams, json, plan.code, plan.message, EXIT_USAGE);
         }
         commitPlan = plan.plan;
         const prepared = prepareBase({ root: commitPlan.root, policyArg: commitPlan.policyArg, logPath, progress }, probe, attested?.sha256 ?? null);
@@ -1211,7 +1310,7 @@ export function commandPolicyAmend(argv, streams, cwd) {
         pinsChange = pinsChangeIn(amendRoot, policyPath, "HEAD");
     }
     /**
-     * The same command, with the two long absolute paths written the way the
+     * The same command, with the long absolute paths written the way the
      * operator would type them.
      *
      * This is a HUMAN transform and nothing else: `--json`'s `git.commands` keeps
@@ -1224,7 +1323,9 @@ export function commandPolicyAmend(argv, streams, cwd) {
             .split(policyPath)
             .join(relPath(policyPath, cwd))
             .split(logPath)
-            .join(relPath(logPath, cwd));
+            .join(relPath(logPath, cwd))
+            .split(payloadFile)
+            .join(relPath(payloadFile, cwd));
         return pinsChange === null
             ? shortened
             : shortened.split(pinsChange.path).join(relPath(pinsChange.path, cwd));
@@ -1242,8 +1343,13 @@ export function commandPolicyAmend(argv, streams, cwd) {
     };
     const summary = summarize(policyPath, diff, pinsChange);
     // APRV-274: the pins file is a member of the `git add` exactly when it moved,
-    // so a copied command lands the same three (or two) files the verb would.
-    const ceremonyFiles = [policyPath, logPath, ...(pinsChange === null ? [] : [pinsChange.path])];
+    // so a copied command lands the same three (or four) files the verb would.
+    const ceremonyFiles = [
+        policyPath,
+        logPath,
+        ...(pinsChange === null ? [] : [pinsChange.path]),
+        payloadFile,
+    ];
     const commitCommands = (seq) => [
         `git add ${ceremonyFiles.join(" ")}`,
         `git commit -m ${JSON.stringify(`Policy: ${summary} (attested seq ${seq})`)}`,
@@ -1251,15 +1357,31 @@ export function commandPolicyAmend(argv, streams, cwd) {
     const gitCommands = (seq) => {
         // APRV-203: `--commit` runs none of these; it assembles the commit on the
         // remote's tip without a checkout. These are the HAND procedure, and they
-        // start where `--commit` starts: at the remote, so the branch is not built
-        // on a local trunk that has fallen behind.
+        // start where `--commit` starts: with the checkout brought current, so the
+        // branch is not built on a local trunk that has fallen behind.
+        //
+        // APRV-360: and they never switch branches. The form printed before this
+        // opened with `git checkout -b policy-amend-<seq> origin/main`, which is
+        // the shape that forked the log on 2026-09-16 and that refused outright on
+        // 2026-09-18, when the primary's main was fourteen commits behind and the
+        // switch would have overwritten QUEUE.md, the working log and six
+        // payloads. A branch switch in the primary is never the right answer: the
+        // daemon is appending to the working log while the operator reads this.
+        //
+        // What replaces it is what the 2026-09-18 recovery actually did. `approval
+        // log sync` brings the checkout current (and refuses `log-diverged` rather
+        // than fast-forwarding over a fork), the commit is made where the operator
+        // is standing, and the branch is created on the REMOTE by refspec, so it
+        // exists without any local ref ever being checked out.
         if (useBranch) {
+            const branch = branchName(seq);
+            const base = probe.defaultBranch === null ? "" : ` --base ${probe.defaultBranch}`;
             return [
-                "git fetch origin",
-                `git checkout -b ${branchName(seq)} origin/${probe.defaultBranch ?? "main"}`,
+                "approval log sync",
                 ...commitCommands(seq),
-                `git push -u origin ${branchName(seq)}`,
-                `gh pr create --title ${JSON.stringify(prTitle(summary, seq))} --body ${JSON.stringify(prBody(seq))}`,
+                `git push origin HEAD:refs/heads/${branch}`,
+                `gh pr create --title ${JSON.stringify(prTitle(summary, seq))} --body ${JSON.stringify(prBody(seq))} --head ${branch}${base}`,
+                `gh pr merge ${branch} --auto --merge`,
             ];
         }
         return amendRoot === null
@@ -1506,6 +1628,7 @@ export function commandPolicyAmend(argv, streams, cwd) {
         branch: null,
         pushed: false,
         prUrl: null,
+        prUpdated: false,
         autoMerge: "not-attempted",
         steps: [],
         stoppedAt: null,
@@ -1596,6 +1719,14 @@ export function commandPolicyAmend(argv, streams, cwd) {
         const why = commandOutputLines(merge.stderr, merge.stdout)[0];
         note(`${prLabel(publishing.prUrl)} is open — merge it with a MERGE COMMIT when CI is green. auto-merge was not armed${why === undefined ? "" : `: ${why}`}`);
     };
+    /**
+     * Who publishes the log for this amendment (APRV-420).
+     *
+     * Settled at commit-assembly time against the base the commit is parented
+     * on, and reported, so the pull request's file list is never a surprise. The
+     * default is the behaviour that predates the task: this commit carries it.
+     */
+    let carriage = { carry: true, reason: null, publisher: null };
     if (commitPlan !== null && commitBase !== null) {
         // APRV-203. The commit is ASSEMBLED, never checked out: a scratch index is
         // filled from the remote's tree, the two ceremony files are laid over it
@@ -1605,6 +1736,10 @@ export function commandPolicyAmend(argv, streams, cwd) {
         const message = `Policy: ${summary} (attested seq ${seq})`;
         /** `origin/main abc123`, or `HEAD abc123` where there is no remote. */
         const baseLabel = `${commitBase.remote === null ? "HEAD" : `${commitBase.remote}/${commitBase.branch}`} ${commitBase.sha.slice(0, 12)}`;
+        // APRV-420: who publishes the log. Decided here, from the base this commit
+        // is about to be parented on, so the answer is about the tree the commit
+        // will actually sit against.
+        carriage = decideLogCarriage(commitPlan.root, commitBase, logPath);
         progress.phase(`building the amendment commit on ${baseLabel} (nothing is checked out)`);
         const built = commitOnBase(commitPlan.root, {
             base: commitBase.sha,
@@ -1613,12 +1748,23 @@ export function commandPolicyAmend(argv, streams, cwd) {
             // keeps this ceremony from reverting a pins edit somebody else landed.
             paths: [
                 commitPlan.policyArg,
-                commitPlan.logArg,
+                // APRV-420: the log joins the commit only when this amendment is the
+                // thing publishing it. When a records advance is, two commits carrying
+                // the same appended records is a conflict on `events.jsonl` whichever
+                // lands first, and the repair is a hand merge of the log.
+                ...(carriage.carry ? [commitPlan.logArg] : []),
                 ...(pinsChange === null ? [] : [pinsChange.arg]),
+                // APRV-356: the attested policy text, so the commit carrying the
+                // binding carries the bytes it binds. Without it the in-force policy is
+                // unrecoverable for every reader of the committed copy, the CI guard
+                // included.
+                commitPlan.payloadArg,
             ],
             message,
         });
         progress.done();
+        if (carriage.reason !== null)
+            note(`${st.glyph("ok")} ${carriage.reason}`);
         if (!built.ok) {
             return gitFailed(built.step, built.quote.join(" | "), `the attestation was appended at seq ${seq}, but ${built.message}; the checkout is untouched, so run the printed commands by hand`, commands);
         }
@@ -1669,6 +1815,47 @@ export function commandPolicyAmend(argv, streams, cwd) {
             : `${commitSha.slice(0, 12)} on ${baseLabel} (held at ${anchor}; your checkout was not moved)`;
         /** `gh pr create …` as the operator would type it, for both flows. */
         const prCreateCommand = (head) => `gh pr create --title ${JSON.stringify(prTitle(summary, String(seq)))} --body ${JSON.stringify(prBody(String(seq)))} --head ${head}${probe.defaultBranch === null ? "" : ` --base ${probe.defaultBranch}`}`;
+        /**
+         * The open pull request for `head`, or `null` when there is none (APRV-341).
+         *
+         * Asked before `gh pr create`, because a second run of the ceremony onto a
+         * branch that already carries one is the ordinary shape of "the ceremony
+         * stopped half-way and I ran it again": `gh pr create` answers that with a
+         * failure, and a failure there used to end the verb holding an attestation
+         * it had already appended. A `gh` that cannot answer is `null`, which falls
+         * through to `create` — the path that was there before this existed.
+         */
+        const openPrFor = (head) => {
+            const listed = gh(["pr", "list", "--head", head, "--state", "open", "--json", "url"], commitPlan.root);
+            if (!listed.ok)
+                return null;
+            const text = listed.stdout.trim();
+            if (text.length === 0)
+                return null;
+            let rows;
+            try {
+                rows = JSON.parse(text);
+            }
+            catch {
+                return null;
+            }
+            if (!Array.isArray(rows))
+                return null;
+            const first = rows[0];
+            if (typeof first !== "object" || first === null)
+                return null;
+            const url = first.url;
+            return typeof url === "string" && url.length > 0 ? url : null;
+        };
+        const prEditArgs = (head) => [
+            "pr",
+            "edit",
+            head,
+            "--title",
+            prTitle(summary, String(seq)),
+            "--body",
+            prBody(String(seq)),
+        ];
         const prCreateArgs = (head) => [
             "pr",
             "create",
@@ -1714,11 +1901,22 @@ export function commandPolicyAmend(argv, streams, cwd) {
             publishing.pushed = true;
             output = `${output}\n${`${push.stdout}${push.stderr}`.trim()}`.trim();
             if (ghAvailable(commitPlan.root)) {
-                const pr = gh(prCreateArgs(branch), commitPlan.root);
-                publishing.steps.push({ command: prCreateCommand(branch), ok: pr.ok });
+                // APRV-341: open, or update the one that is already open for this
+                // branch. A ceremony re-run onto a branch a pull request already stands
+                // on is not an error to report, it is the state to bring up to date.
+                const standing = openPrFor(branch);
+                const pr = standing === null
+                    ? gh(prCreateArgs(branch), commitPlan.root)
+                    : gh(prEditArgs(branch), commitPlan.root);
+                publishing.steps.push({
+                    command: standing === null ? prCreateCommand(branch) : `gh pr edit ${branch} --title … --body …`,
+                    ok: pr.ok,
+                });
                 if (!pr.ok) {
                     const ghFailure = pr.stderr.trim() || pr.stdout.trim() || "gh did not run";
-                    return stalled("pr-failed", "`gh pr create` failed; the branch is already on origin", pr, `the attestation was appended at seq ${seq}, committed on ${branch} and pushed, but \`gh pr create\` failed: ${ghFailure}; open the pull request by hand and merge it with a merge commit`, [
+                    return stalled("pr-failed", standing === null
+                        ? "`gh pr create` failed; the branch is already on origin"
+                        : "`gh pr edit` failed; the branch and its pull request are already on origin", pr, `the attestation was appended at seq ${seq}, committed on ${branch} and pushed, but \`gh pr create\` failed: ${ghFailure}; open the pull request by hand and merge it with a merge commit`, [
                         `attestation appended at seq ${seq}: it is in the log, on disk`,
                         `committed on ${branch} and PUSHED: origin has the branch`,
                         "no pull request: origin's default branch still carries the previous policy",
@@ -1727,8 +1925,12 @@ export function commandPolicyAmend(argv, streams, cwd) {
                         { command: `gh pr merge ${branch} --merge`, note: "or merge it in the web UI" },
                     ], 0, [MERGE_COMMIT_LINE]);
                 }
-                prUrl = lastUrl(pr.stdout);
+                // `gh pr edit` prints the pull request's URL too, but the one this
+                // ceremony already knows is the one it asked for; `create` has nothing
+                // but its own output. Either way `null` is an honest answer.
+                prUrl = standing ?? lastUrl(pr.stdout);
                 publishing.prUrl = prUrl;
+                publishing.prUpdated = standing !== null;
                 publishing.complete = true;
                 // APRV-130: the ceremony offers to finish the last step too.
                 armAutoMerge(commitPlan.root, branch);
@@ -1865,7 +2067,10 @@ export function commandPolicyAmend(argv, streams, cwd) {
             // APRV-274: the headline names what the commit actually carries. A reader
             // who is told "the policy and the log" and finds a third file in the diff
             // has been told something false about the one commit that must not lie.
-            const carried = pinsChange === null ? "the policy and the log" : "the policy, the log and the pins";
+            // APRV-356 added the fourth: the store file holding the attested bytes.
+            const carried = pinsChange === null
+                ? "the policy, the log and the attested policy text"
+                : "the policy, the log, the pins and the attested policy text";
             const done = [
                 branch === null
                     ? `${st.glyph("ok")} committed ${carried} together:`
@@ -1958,6 +2163,8 @@ export function commandPolicyAmend(argv, streams, cwd) {
  * across two commits and a hand-run cherry-pick.
  */
 function planCommit(policyPath, logPath, 
+/** The store file holding the attested policy text, absolute (APRV-356). */
+payloadFile, 
 /**
  * The branch flow's preconditions, checked here for the same reason: an
  * `origin` that does not exist, or a branch name already taken, would fail
@@ -1971,11 +2178,16 @@ branchFlow) {
     if (root === null) {
         return {
             ok: false,
+            code: "commit-preconditions",
             message: `--commit needs a git repository and ${policyPath} is not inside one; nothing was attested`,
         };
     }
     const policyArg = repoPath(root, policyPath);
     const logArg = repoPath(root, logPath);
+    // APRV-356. The payload store is a sibling of the log directory, so a log
+    // inside the repository puts this inside it too; the check below covers both
+    // with one sentence rather than naming a path no operator chose.
+    const payloadArg = repoPath(root, payloadFile);
     // APRV-274. `null` where these pins do not govern this policy, and where the
     // repository simply has no pins module: in both cases the ceremony's file set
     // is the two it always was.
@@ -1985,32 +2197,59 @@ branchFlow) {
     if (policyArg.startsWith("../") || logArg.startsWith("../")) {
         return {
             ok: false,
+            code: "commit-preconditions",
             message: `--commit needs the policy (${policyPath}) and the log (${logPath}) inside the same repository (${root}); nothing was attested`,
         };
     }
     const status = git(["status", "--porcelain"], root);
     if (!status.ok) {
-        return { ok: false, message: `--commit could not read git status: ${status.stderr.trim()}` };
+        return {
+            ok: false,
+            code: "commit-preconditions",
+            message: `--commit could not read git status: ${status.stderr.trim()}`,
+        };
     }
+    const ceremonyFiles = [policyArg, logArg, payloadArg, ...(pinsArg === null ? [] : [pinsArg])];
+    const carried = pinsArg === null
+        ? "the policy, the log and the attested policy text"
+        : `the policy, the log, the attested policy text and ${pinsArg}`;
     const strays = [];
+    /** Ceremony files staged in one state and left in another (APRV-341). */
+    const split = [];
     for (const line of status.stdout.split("\n")) {
         if (line.trim().length === 0)
             continue;
         const index = line[0] ?? " ";
-        // Only the INDEX column matters: an unstaged or untracked file elsewhere is
-        // not going into this commit, and refusing over it would make the verb
-        // unusable in any working repository.
+        const worktree = line[1] ?? " ";
+        const path = line.slice(3).trim();
+        const ceremony = ceremonyFiles.includes(path);
+        // A ceremony file the operator staged and then edited again. The commit is
+        // assembled from the working tree, so the bytes it would carry are not the
+        // bytes `git diff --cached` shows, and an amendment is the one commit that
+        // may not be a surprise to the person who signed it.
+        if (ceremony && index !== " " && index !== "?" && worktree === "M")
+            split.push(path);
+        // Only the INDEX column matters for everything else: an unstaged or
+        // untracked file elsewhere is not going into this commit (the scratch index
+        // lays exactly the ceremony paths over the remote's tree), and refusing
+        // over one would make the verb unusable in any working repository.
         if (index === " " || index === "?")
             continue;
-        const path = line.slice(3).trim();
-        if (path === policyArg || path === logArg || path === pinsArg)
+        if (ceremony)
             continue;
         strays.push(path);
     }
+    if (split.length > 0) {
+        return {
+            ok: false,
+            code: "dirty-tree",
+            message: `--commit refuses: ${split.join(", ")} ${split.length === 1 ? "is" : "are"} staged in one state and modified again in the working tree. The amendment commit is assembled from the WORKING TREE, so it would carry bytes your \`git diff --cached\` does not show, and the one commit that may not surprise the person who signed it is this one. Stage the file as it stands (\`git add ${split.join(" ")}\`) or unstage it, then run this again. Nothing was attested`,
+        };
+    }
     if (strays.length > 0) {
-        const carried = pinsArg === null ? "the policy and the log" : `the policy, the log and ${pinsArg}`;
         return {
             ok: false,
+            code: "staged-unrelated",
             message: `--commit refuses: the index carries ${strays.length} staged change(s) beyond ${carried} (${strays.join(", ")}). The amendment commit carries EXACTLY those files, so that "this commit is the amendment" stays true. Unstage them, or drop --commit and run the printed commands yourself. Nothing was attested`,
         };
     }
@@ -2019,6 +2258,7 @@ branchFlow) {
         if (!remote.ok) {
             return {
                 ok: false,
+                code: "commit-preconditions",
                 message: `--commit on a branch needs an "origin" remote to push to, and ${root} has none (${remote.stderr.trim()}); pass --direct to commit in place, or add the remote. Nothing was attested`,
             };
         }
@@ -2027,12 +2267,13 @@ branchFlow) {
             if (exists.ok) {
                 return {
                     ok: false,
+                    code: "commit-preconditions",
                     message: `--branch ${branchFlow.branch} already exists in ${root}; the amendment branch is created fresh so it carries exactly one commit. Pick another name. Nothing was attested`,
                 };
             }
         }
     }
-    return { ok: true, plan: { root, policyArg, logArg, pinsArg } };
+    return { ok: true, plan: { root, policyArg, logArg, pinsArg, payloadArg } };
 }
 /**
  * Fetch the remote and establish that this ceremony may be based on it (APRV-203).
@@ -2137,6 +2378,292 @@ function readLogText(path) {
         return "";
     }
 }
+/**
+ * The open records-advance branch on `origin`, or `null`.
+ *
+ * `git ls-remote` rather than `gh`, deliberately: this is a question about refs
+ * and it must answer the same way on a box with no GitHub CLI, no token and no
+ * network beyond the remote itself. `approval log advance` names its branch
+ * `records-log-<YYYY-MM-DD>` and falls back to `records-log-<date>-<n>`
+ * (`cli/log-advance.ts`), and merged branches are deleted by the reconcile
+ * script, so a branch matching that pattern on origin is a live advance.
+ */
+function recordsPublisher(root) {
+    const listed = git(["ls-remote", "--heads", "origin", "records-log-*"], root);
+    if (!listed.ok)
+        return null;
+    for (const line of listed.stdout.split("\n")) {
+        const [sha, ref] = line.trim().split(/\s+/u);
+        if (ref === undefined || sha === undefined)
+            continue;
+        const name = ref.replace(/^refs\/heads\//u, "");
+        if (name.startsWith("records-log-"))
+            return { name, sha };
+    }
+    return null;
+}
+/**
+ * Whether the records branch at `sha` already carries every record of the
+ * working log, this attestation included.
+ *
+ * A branch pushed BEFORE the attestation was appended does not, and that is
+ * the ordinary order (the cadence advance ran, then the human signed), so
+ * saying "this attestation included" of it would be a claim the committed
+ * log contradicts. What publishes the attestation then is the NEXT advance,
+ * and the pull request's protected-path guard holds the policy change until
+ * a records branch or main carries the record. `null` when the branch's log
+ * could not be fetched or read, which the caller reports as unknown rather
+ * than as either answer.
+ */
+function publisherCarriesLog(root, sha, logArg, logPath) {
+    const fetched = git(["fetch", "--quiet", "origin", sha], root);
+    if (!fetched.ok)
+        return null;
+    const branchLog = showBlob(root, sha, logArg);
+    if (branchLog === null)
+        return null;
+    const compared = compareChains({ label: "the working log", text: readLogText(logPath) }, { label: `records branch ${sha.slice(0, 12)}:${logArg}`, text: branchLog.toString("utf8") });
+    if (!compared.ok)
+        return null;
+    return compared.drift.relation === "equal" || compared.drift.relation === "behind";
+}
+/**
+ * Decide who publishes the log for this amendment. See the block above.
+ *
+ * Fails toward CARRYING it: every answer this function cannot establish (a log
+ * that does not verify, a blob it could not read, a remote it could not list)
+ * leaves the amendment holding the log, which is the behaviour that predates
+ * this task. A dirty pull request is a nuisance; an attestation that reaches
+ * `main` in nobody's commit is a policy in force that the committed log does
+ * not record, and between those two there is no contest.
+ */
+function decideLogCarriage(root, base, logPath) {
+    const logArg = repoPath(root, logPath);
+    const baseLabel = base.remote === null ? base.branch : `${base.remote}/${base.branch}`;
+    const baseLog = showBlob(root, base.sha, logArg);
+    const compared = compareChains({ label: "the working log", text: readLogText(logPath) }, { label: `${baseLabel}:${logArg}`, text: baseLog === null ? "" : baseLog.toString("utf8") });
+    if (compared.ok && (compared.drift.relation === "equal" || compared.drift.relation === "behind")) {
+        return {
+            carry: false,
+            reason: `${baseLabel} already carries every record this attestation added, so this amendment does not touch the log`,
+            publisher: null,
+        };
+    }
+    const publisher = recordsPublisher(root);
+    if (publisher !== null) {
+        const carries = publisherCarriesLog(root, publisher.sha, logArg, logPath);
+        return {
+            carry: false,
+            reason: carries === true
+                ? `the records advance on ${publisher.name} publishes the whole log, this attestation included, so this amendment carries only the policy and cannot conflict with it`
+                : `a records advance is live on ${publisher.name}${carries === null ? " (its log could not be read from here)" : ", pushed before this attestation was appended"}, so this amendment carries only the policy and cannot conflict with it; the attestation record lands with the next advance, and the pull request's protected-path check holds the policy change until a records branch or main carries it`,
+            publisher: publisher.name,
+        };
+    }
+    return { carry: true, reason: null, publisher: null };
+}
+/**
+ * Repair the amendment pull request a previous run left standing (APRV-420).
+ *
+ * The second run of a ceremony that already attested reaches "nothing to
+ * amend", which is true and useless: the live policy does match its
+ * attestation, and the pull request carrying that attestation to the trunk is
+ * open, unmergeable and unarmed. On 2026-09-21 the repair was a hand merge of
+ * `events.jsonl` in a throwaway worktree, which is the work every idiom here
+ * exists to remove.
+ *
+ * So the re-run rebuilds. The trunk's log is a superset of the amendment's by
+ * construction — every record the amendment appended reaches the trunk through
+ * a records advance as well — so a commit built fresh on the current trunk,
+ * carrying only what the trunk still LACKS, is the merge without a merge.
+ *
+ * Two things this does not do. It does not check anything out: the rebuild is
+ * `commitOnBase`'s scratch index, exactly as the first run's was, so a live
+ * appender never has the log moved underneath it. And it does not touch a
+ * branch it cannot account for: the remote tip must be a single commit on top
+ * of an ancestor of the base, which is the shape this ceremony creates and
+ * nothing else. Anything else is reported with its commands rather than
+ * force-pushed over.
+ *
+ * Returns `null` when there is nothing standing, which leaves the caller's
+ * "nothing to amend" exactly as it was.
+ */
+function repairAmendBranch(input) {
+    const { root, policyPath, logPath, payloadFile, seq, branch, act } = input;
+    const listed = git(["ls-remote", "--heads", "origin", branch], root);
+    const tipLine = listed.ok
+        ? listed.stdout.split("\n").find((line) => line.trim().length > 0)
+        : undefined;
+    if (tipLine === undefined)
+        return null;
+    const commands = [];
+    const stop = (state, message, extra = []) => {
+        for (const command of extra)
+            commands.push({ command, ok: null });
+        return {
+            branch,
+            state,
+            base: null,
+            carried: [],
+            commit: null,
+            pushed: false,
+            autoMerge: "not-attempted",
+            commands,
+            message,
+        };
+    };
+    const probe = probeProtection(root);
+    const baseBranch = probe.defaultBranch ?? probe.currentBranch;
+    if (baseBranch === null) {
+        return stop("failed", `${branch} is on origin and no branch could be resolved to rebuild it on (${probe.reason})`);
+    }
+    commands.push({ command: `git fetch origin ${baseBranch}`, ok: null });
+    const fetched = fetchBase(root, "origin", baseBranch);
+    if (!fetched.ok) {
+        commands[commands.length - 1] = { command: `git fetch origin ${baseBranch}`, ok: false };
+        return stop("failed", `${branch} is on origin and ${fetched.message}`);
+    }
+    commands[commands.length - 1] = { command: `git fetch origin ${baseBranch}`, ok: true };
+    const base = { remote: "origin", branch: baseBranch, sha: fetched.sha };
+    const baseLabel = `origin/${baseBranch}`;
+    // Fetched rather than read off `ls-remote`, because the count below needs the
+    // tip to be an OBJECT in this repository: a commit somebody else pushed to
+    // the branch has never been near this checkout, and `rev-list` over a sha it
+    // does not have answers nothing at all.
+    commands.push({ command: `git fetch origin ${branch}`, ok: null });
+    const fetchedTip = fetchBase(root, "origin", branch);
+    if (!fetchedTip.ok) {
+        commands[commands.length - 1] = { command: `git fetch origin ${branch}`, ok: false };
+        return stop("failed", `${branch} is on origin and ${fetchedTip.message}`);
+    }
+    commands[commands.length - 1] = { command: `git fetch origin ${branch}`, ok: true };
+    const tipSha = fetchedTip.sha;
+    // What the base still lacks. Each answer is read from the base's own tree,
+    // so a record or a payload a records advance already landed is not carried
+    // twice, which is the whole cause of the conflict this repairs.
+    const policyArg = repoPath(root, policyPath);
+    const payloadArg = repoPath(root, payloadFile);
+    const carried = [];
+    const reasons = [];
+    const basePolicy = showBlob(root, base.sha, policyArg);
+    const livePolicy = ((() => {
+        try {
+            return readFileSync(policyPath);
+        }
+        catch {
+            return null;
+        }
+    })());
+    if (livePolicy === null) {
+        return stop("failed", `${policyPath} could not be read, so the rebuild has no policy bytes to carry`);
+    }
+    if (basePolicy === null || !basePolicy.equals(livePolicy)) {
+        carried.push(policyArg);
+        reasons.push(`the policy bytes (${baseLabel} does not carry them)`);
+    }
+    if (showBlob(root, base.sha, payloadArg) === null) {
+        carried.push(payloadArg);
+        reasons.push("the attested policy text");
+    }
+    const carriage = decideLogCarriage(root, base, logPath);
+    if (carriage.carry) {
+        carried.push(repoPath(root, logPath));
+        reasons.push("the log, which nothing else is publishing");
+    }
+    else {
+        reasons.push(`NOT the log: ${carriage.reason ?? "it is published elsewhere"}`);
+    }
+    const pins = pinsChangeIn(root, policyPath, base.sha);
+    if (pins !== null) {
+        carried.push(pins.arg);
+        reasons.push(pins.arg);
+    }
+    if (carried.length === 0) {
+        return stop("landed", `the amendment at seq ${seq} is already on ${baseLabel} in full: the policy, its attested text and its records are all there, so ${branch} has nothing left to carry. Close the pull request`, [`gh pr close ${branch} --delete-branch`]);
+    }
+    // Only now that a rebuild is actually owed does the branch's SHAPE matter,
+    // and it has to be the one shape this ceremony makes: one commit, on a parent
+    // the base already contains. `rev-list --count base..tip` counts the commits
+    // the tip has that the base does not, so anything above one is work this verb
+    // did not put there and a force-push would lose it. Zero is not checked here,
+    // because a branch the base already contains has nothing left to carry and
+    // left through the `landed` exit above.
+    const countRun = git(["rev-list", "--count", `${base.sha}..${tipSha}`], root);
+    const count = countRun.ok ? Number(countRun.stdout.trim()) : Number.NaN;
+    if (!Number.isInteger(count) || count > 1) {
+        return stop("failed", `${branch} on origin carries ${Number.isInteger(count) ? String(count) : "an unknown number of"} commits that ${baseLabel} does not. The amendment ceremony builds exactly one, so this branch holds work this verb did not put there and it will not be rebuilt over. Rebase or merge it by hand`, [`git log --oneline ${base.sha.slice(0, 12)}..${tipSha.slice(0, 12)}`]);
+    }
+    const subject = git(["log", "-1", "--format=%s", tipSha], root);
+    const message = subject.ok && subject.stdout.trim().length > 0
+        ? subject.stdout.trim()
+        : `Policy: amend ${policyArg} (attested seq ${seq})`;
+    const rebuild = `git push origin +<rebuilt>:refs/heads/${branch}`;
+    const built = commitOnBase(root, { base: base.sha, paths: carried, message });
+    if (!built.ok) {
+        commands.push({ command: rebuild, ok: null });
+        return stop("failed", `${branch} could not be rebuilt on ${baseLabel}: ${built.message}`);
+    }
+    if (built.unchanged) {
+        return stop("landed", `the amendment at seq ${seq} is already on ${baseLabel}: a commit carrying ${carried.join(", ")} over ${baseLabel} is the same tree. Close the pull request`, [`gh pr close ${branch} --delete-branch`]);
+    }
+    const commitSha = built.sha;
+    const carriedNote = `rebuilt ${commitSha.slice(0, 12)} on ${baseLabel} ${base.sha.slice(0, 12)} carrying ${reasons.join(", ")}`;
+    const push = `git push origin +${commitSha.slice(0, 12)}:refs/heads/${branch}`;
+    if (!act) {
+        commands.push({ command: push, ok: null });
+        commands.push({ command: `gh pr merge ${branch} --merge --auto`, ok: null });
+        return {
+            branch,
+            state: "owed",
+            base: base.sha,
+            carried,
+            commit: commitSha,
+            pushed: false,
+            autoMerge: "not-attempted",
+            commands,
+            message: `${carriedNote}; nothing was pushed, so the pull request is unchanged. Run the commands above to finish it`,
+        };
+    }
+    // Force, and only here: the branch carries exactly the one commit this
+    // ceremony put on it (checked above), and the whole repair is replacing that
+    // commit with the same amendment parented on a base that has moved.
+    const pushed = git(["push", "origin", `+${commitSha}:refs/heads/${branch}`], root);
+    commands.push({ command: push, ok: pushed.ok });
+    if (!pushed.ok) {
+        commands.push({ command: `gh pr merge ${branch} --merge --auto`, ok: null });
+        return {
+            branch,
+            state: "failed",
+            base: base.sha,
+            carried,
+            commit: commitSha,
+            pushed: false,
+            autoMerge: "not-attempted",
+            commands,
+            message: `${carriedNote}, and \`${push}\` was REJECTED: ${pushFailureText(pushed)}. The commit exists locally; push it and re-arm the merge`,
+        };
+    }
+    let autoMerge = "not-attempted";
+    if (ghAvailable(root)) {
+        const armed = gh(["pr", "merge", branch, "--merge", "--auto"], root);
+        commands.push({ command: `gh pr merge ${branch} --merge --auto`, ok: armed.ok });
+        autoMerge = armed.ok ? "armed" : "refused";
+    }
+    else {
+        commands.push({ command: `gh pr merge ${branch} --merge --auto`, ok: null });
+    }
+    return {
+        branch,
+        state: "repaired",
+        base: base.sha,
+        carried,
+        commit: commitSha,
+        pushed: true,
+        autoMerge,
+        commands,
+        message: `${carriedNote}, and force-updated ${branch} on origin, so the pull request is mergeable again${autoMerge === "armed" ? " and armed" : ""}`,
+    };
+}
 function loadSummary(load) {
     return load.ok
         ? { ok: true, code: null, message: null }
@@ -2166,6 +2693,9 @@ function emitReport(streams, report) {
         // APRV-109, additive and always present: `null` says the attestation was
         // performed at this terminal, an object says it was collected as a tap.
         proposal: report.proposal ?? null,
+        // APRV-420, additive and always present: `null` says this run had an
+        // amendment to make, or found no standing branch to repair.
+        repair: report.repair ?? null,
     })}\n`);
 }
 //# sourceMappingURL=amend.js.map