approval-md 0.1.0 → 0.3.0

package/dist/src/cli/preflight.js

@@ -15,33 +15,73 @@
  *
  * ## What it is allowed to do
  *
- * Read git, and at most two writes: a `--ff-only` merge, and `npm run build`.
+ * Read git, and at most four writes: a `--ff-only` merge, `npm run build`,
+ * when the merge refused over an untracked file under `backlog/tasks/`
+ * that main already contains, clearing that file out of the way (APRV-300, and
+ * the rules it obeys are in {@link reconcileUntrackedTaskFiles}), and the one
+ * `approval log sync` performs on its behalf (APRV-346, below).
  *
  * It never resets, never stashes, never checks anything out, and never touches
- * the working log. That list is not conservatism for its own sake — it is fork 2
- * of 2026-08-20 (APRV-104's notes, and the reason `approval log sync` exists at
- * all): a working `events.jsonl` rewound through git underneath a live appender
- * is two chains where there was one. `--ff-only` cannot rewind a file that
- * upstream did not change, and when upstream DID change it while the working
- * copy is dirty, this module refuses and names `approval log sync`, which is the
- * verb that knows how to do it safely.
+ * the working log ITSELF. That list is not conservatism for its own sake — it is
+ * fork 2 of 2026-08-20 (APRV-104's notes, and the reason `approval log sync`
+ * exists at all): a working `events.jsonl` rewound through git underneath a live
+ * appender is two chains where there was one. `--ff-only` cannot rewind a file
+ * that upstream did not change, and when upstream DID change it while the
+ * working copy is dirty, the file is moved by `cli/log-sync.ts` and by nothing
+ * here.
+ *
+ * ## The routine collision, and the one that is not (APRV-346)
+ *
+ * Every records advance moves `origin/main`'s `.approval/log/events.jsonl`
+ * while the hook keeps appending locally, so "upstream changed the log and so
+ * did this working copy" is the NORMAL state of the primary checkout after a
+ * merge rather than an edge case. Refusing it sent the operator to `approval log
+ * sync` and then back to `approval up` every single time, which is a two-step
+ * ritual for a state the preflight can already tell apart from a fork.
+ *
+ * So the collision is now a question rather than a verdict: is the working log a
+ * byte-for-byte EXTENSION of the committed one (main's records 1..N unchanged,
+ * local N+1.. following) or are they two chains that share a prefix and then
+ * differ? {@link planLogSync} asks `core/log-reconcile.ts` — the same comparison
+ * `log sync` and doctor's `log-drift` ask — and answers a plan or `null`:
+ *
+ * - a plan, and {@link runPreflight} calls `logSync` itself. Not a
+ *   reimplementation of it: the APRV-215 ceremony (one hold of the append lock,
+ *   snapshot, baseline, fast-forward, reconcile, rebuild the projections,
+ *   post-verify) stays the single implementation, and this module supplies a
+ *   caller rather than a copy;
+ * - `null`, and the old `up-preflight-log-diverged` refusal stands unchanged.
+ *   A fork, a log that does not verify, a log at some path other than the
+ *   repository's own, or any OTHER upstream-touched path locally modified all
+ *   answer `null`. Every one of those is a judgment, and this module makes none.
  *
  * ## Refusals, not repairs
  *
- * Three codes, evaluated in this order, each firing for exactly one condition:
+ * Four codes, each firing for exactly one condition. The first three are
+ * evaluated in this order, before anything is written:
  *
  * - `up-preflight-behind-ahead` — `origin/<branch>..HEAD` is non-empty. Local
  *   commits exist that the remote does not have. A fast-forward is not the
  *   operation for that state, and guessing which side to keep is a decision.
  * - `up-preflight-log-diverged` — the upstream range changes the working log or
- *   the queue projection, and the working copy has uncommitted changes to them.
- *   This is the case the human could not judge by eye, and it is `approval log
- *   sync`'s whole subject.
+ *   the queue projection, the working copy has uncommitted changes to them, AND
+ *   the two chains are not in a prefix relationship (or cannot be compared at
+ *   all). This is the case the human could not judge by eye, and it is `approval
+ *   log sync`'s whole subject. The routine case — a working log that merely
+ *   extends the committed one — is reconciled rather than refused (APRV-346).
  * - `up-preflight-dirty-protected` — some OTHER path the upstream range changes
  *   is locally modified, so `git merge --ff-only` would refuse to overwrite it.
  *   Named separately because the repair is different: look at the edit and
  *   decide, or start on the current build with `--no-preflight`.
  *
+ * The fourth is answered after the merge has already refused, and only for the
+ * one path shape where two checkouts routinely author one file (APRV-300):
+ *
+ * - `up-preflight-task-file-conflict` — an untracked file under
+ *   `backlog/tasks/` stopped the fast-forward, and it holds lines the incoming
+ *   copy does not. See {@link reconcileUntrackedTaskFiles} for what happens
+ *   when it holds none, and why that is a claim rather than an assumption.
+ *
  * `git reset --hard` appears in none of them, and never will: it is the command
  * that turns "your checkout is confusing" into "your work is gone".
  *
@@ -67,12 +107,18 @@
  * operator did not ask for, and says out loud that its answer is only as fresh
  * as the last fetch.
  */
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
-import { dirname, join, resolve as resolvePathSegments } from "node:path";
+import { basename, dirname, join, resolve as resolvePathSegments } from "node:path";
 import { fileURLToPath } from "node:url";
+import { checkAttestation, policyBytesHash } from "../core/attest.js";
+import { compareChains } from "../core/log-reconcile.js";
+import { POLICY_FILENAMES } from "../core/policy-load.js";
+import { verifyWithRecords } from "../core/verify.js";
 import { EXIT_IO, EXIT_OK } from "./exit-codes.js";
-import { currentBranch, failureText, fetchBase, git, repoPath, repoRoot, } from "./git-scope.js";
+import { currentBranch, failureText, fetchBase, git, repoPath, repoRoot, showBlob, } from "./git-scope.js";
+import { logSync } from "./log-sync.js";
+import { DEFAULT_LOG_PATH } from "./paths.js";
 import { runbook, style } from "./style.js";
 // ---------------------------------------------------------------------------
 // Build freshness (moved here from cli/doctor.ts, APRV-215)
@@ -269,6 +315,7 @@ export const PREFLIGHT_REFUSAL_CODES = [
     "up-preflight-behind-ahead",
     "up-preflight-log-diverged",
     "up-preflight-dirty-protected",
+    "up-preflight-task-file-conflict",
 ];
 const ZERO = {
     behind_by: 0,
@@ -276,6 +323,7 @@ const ZERO = {
     log_touched: false,
     dist_stale: false,
     reexec: false,
+    log_synced: false,
 };
 /** `git status --porcelain -uno` as a set of repo-relative paths. */
 function dirtyPaths(root) {
@@ -323,7 +371,68 @@ function counts(root, base) {
     return { behind, ahead };
 }
 function skipped(detail, root) {
-    return { ok: true, facts: { ...ZERO, action: "skipped" }, detail, warning: null, target: null, root };
+    return {
+        ok: true,
+        facts: { ...ZERO, action: "skipped" },
+        detail,
+        warning: null,
+        target: null,
+        root,
+        sync: null,
+    };
+}
+/**
+ * Is this protected-path collision the routine one, and what would clearing it
+ * keep? `null` means "not a question this module answers", and the caller
+ * refuses (APRV-346).
+ *
+ * Four conditions, and every one of them is a reason to refuse rather than a
+ * degree of confidence:
+ *
+ * 1. **The log is the repository's own.** `approval log sync` reconciles the log
+ *    at `.approval/log/events.jsonl` in the checkout it runs in, so a preflight
+ *    pointed at some other file with `--log` must not hand it a reconcile of a
+ *    file it was never asked about. That is a mismatch a test fixture can have
+ *    and the primary checkout cannot, which is exactly when a guard is cheap.
+ * 2. **Nothing else is in the merge's way.** `logSync` ends in `git merge
+ *    --ff-only`, which refuses over any dirty tracked path. A dirty unrelated
+ *    file is the `up-preflight-dirty-protected` conversation and is not made
+ *    better by starting a ceremony that will stop half-way.
+ * 3. **Both chains can be read.** `compareChains` verifies each side before it
+ *    compares a single seq, and a side that does not verify is a refusal rather
+ *    than an answer (SPEC §11.1: enforcement paths read only verified records).
+ * 4. **They are in a prefix relationship.** `ahead`, `behind` and `equal` all
+ *    mean the longer chain contains the other whole, so adopting it extends and
+ *    rewinds nothing. `diverged` means two appenders built different records on
+ *    one predecessor, hash chains do not merge, and no verb here will pick.
+ *
+ * Read-only throughout, so doctor can ask the same question without doctor ever
+ * having done anything.
+ */
+function planLogSync(root, logPath, target, upstream, dirty, protectedPaths) {
+    const logRelative = repoPath(root, logPath);
+    if (logRelative !== DEFAULT_LOG_PATH)
+        return null;
+    const others = [...upstream].filter((path) => dirty.has(path) && !protectedPaths.has(path));
+    if (others.length > 0)
+        return null;
+    let working;
+    try {
+        const bytes = readIfPresent(logPath);
+        working = bytes === null ? "" : bytes.toString("utf8");
+    }
+    catch {
+        return null;
+    }
+    const committed = showBlob(root, target, logRelative);
+    if (committed === null)
+        return null;
+    const compared = compareChains({ label: `the working log ${logPath}`, text: working }, { label: `the committed log at ${target.slice(0, 12)}`, text: committed.toString("utf8") });
+    if (!compared.ok)
+        return null;
+    if (compared.drift.relation === "diverged")
+        return null;
+    return { relation: compared.drift.relation, kept: compared.drift.ahead };
 }
 /**
  * The whole judgment, and not one byte of action.
@@ -360,6 +469,7 @@ export function inspectPreflight(input) {
                 warning: fetched.message,
                 target: null,
                 root,
+                sync: null,
             };
         }
         base = fetched.sha;
@@ -391,6 +501,7 @@ export function inspectPreflight(input) {
         dist_stale: stale,
         action,
         reexec: false,
+        log_synced: false,
     });
     // 1. Ahead. Nothing else is worth judging: whatever the upstream range holds,
     //    a fast-forward is not the operation for a checkout carrying commits the
@@ -436,6 +547,7 @@ export function inspectPreflight(input) {
             root,
             target: base,
             warning,
+            sync: null,
             facts: facts(stale ? "rebuild" : "none"),
             detail: stale
                 ? `up to date with ${remote}/${branch}, and the build is older than the sources`
@@ -449,38 +561,29 @@ export function inspectPreflight(input) {
     //    does this — snapshot, baseline, fast-forward, reconcile, rebuild the
     //    projections — and this module deliberately does not reimplement it.
     const collidingProtected = [...protectedPaths].filter((path) => upstream.has(path) && dirty.has(path));
-    if (collidingProtected.length > 0) {
+    // ...unless the collision is the routine one, which is the state the primary
+    // checkout is in after every records advance (APRV-346). `planLogSync` asks
+    // the chains themselves; a plan is a reconcile `runPreflight` will delegate to
+    // `approval log sync`, and `null` is the refusal below, unchanged.
+    const plan = collidingProtected.length === 0
+        ? null
+        : planLogSync(root, input.logPath, base, upstream, dirty, protectedPaths);
+    if (collidingProtected.length > 0 && plan === null) {
         return {
             ok: false,
             root,
             facts: facts("refused"),
-            refusal: {
-                code: "up-preflight-log-diverged",
-                headline: `${remote}/${branch} changed ${collidingProtected.join(" and ")} and so did this working copy`,
-                state: [
-                    `${plural(counted.behind, "commit")} behind ${remote}/${branch}`,
-                    `changed on both sides: ${collidingProtected.join(", ")}`,
-                    "the working log was not read, moved, or rewound",
-                ],
-                steps: [
-                    {
-                        command: "approval log sync",
-                        note: "snapshots the working log, fast-forwards, reconciles the chain",
-                    },
-                    { command: "approval up", note: "again, once sync reports clean" },
-                ],
-                footer: [
-                    "a fast-forward over a log another process is appending to is how one chain becomes two",
-                    "the ritual and what it refuses: docs/cli-reference.md#log-sync",
-                ],
-                next: "approval log sync",
-            },
+            refusal: divergedRefusal(remote, branch, counted.behind, collidingProtected),
         };
     }
     // 3. Any other local modification in the fast-forward's way. `--ff-only` would
     //    refuse rather than clobber it, so the refusal is reported here, where it
-    //    can say which file and what the two ways out are.
-    const colliding = [...upstream].filter((path) => dirty.has(path)).sort();
+    //    can say which file and what the two ways out are. The protected pair is
+    //    exempt when there is a plan: `log sync` is the writer that moves those
+    //    two, and it has already been asked whether it can.
+    const colliding = [...upstream]
+        .filter((path) => dirty.has(path) && !(plan !== null && protectedPaths.has(path)))
+        .sort();
     if (colliding.length > 0) {
         return {
             ok: false,
@@ -514,8 +617,46 @@ export function inspectPreflight(input) {
         root,
         target: base,
         warning,
+        sync: plan,
         facts: facts(stale ? "fast-forward+rebuild" : "fast-forward"),
-        detail: `${plural(counted.behind, "commit")} behind ${remote}/${branch}, and the upstream range is safe to fast-forward${stale ? "; the build is older than the sources" : ""}`,
+        detail: `${plural(counted.behind, "commit")} behind ${remote}/${branch}, and the upstream range is safe to fast-forward${plan === null ? "" : `, once \`approval log sync\`'s reconcile has kept the ${plural(plan.kept, "local record")}`}${stale ? "; the build is older than the sources" : ""}`,
+    };
+}
+/**
+ * The `up-preflight-log-diverged` refusal, in one place.
+ *
+ * Two callers now: the judgment that decides the chains cannot be reconciled
+ * without a human, and the one case where `logSync` — asked to reconcile a pair
+ * this module had already found reconcilable — refuses anyway. The second is a
+ * race (an appender that beat the lock, a fork that landed between the read and
+ * the ceremony) or a machine problem, and it says so in `extra` rather than in a
+ * code of its own: the repair is the same repair, and a code whose repair is
+ * another code's is not a distinct refusal, it is a synonym.
+ */
+function divergedRefusal(remote, branch, behind, collidingProtected, extra = []) {
+    return {
+        code: "up-preflight-log-diverged",
+        headline: `${remote}/${branch} changed ${collidingProtected.join(" and ")} and so did this working copy`,
+        state: [
+            `${plural(behind, "commit")} behind ${remote}/${branch}`,
+            `changed on both sides: ${collidingProtected.join(", ")}`,
+            ...extra,
+            extra.length === 0
+                ? "the working log was not read, moved, or rewound"
+                : "the reconcile restored the working log exactly as it found it, and nothing was started",
+        ],
+        steps: [
+            {
+                command: "approval log sync",
+                note: "snapshots the working log, fast-forwards, reconciles the chain",
+            },
+            { command: "approval up", note: "again, once sync reports clean" },
+        ],
+        footer: [
+            "a fast-forward over a log another process is appending to is how one chain becomes two",
+            "the ritual and what it refuses: docs/cli-reference.md#log-sync",
+        ],
+        next: "approval log sync",
     };
 }
 function plural(count, noun) {
@@ -538,8 +679,65 @@ export function runPreflight(input, spawnBuild = npmBuild) {
     if (facts.action === "skipped" || facts.action === "fetch-failed") {
         return { ok: true, facts, detail: report.detail, warning: report.warning };
     }
+    // What the task-file reconciliation below cleared, or `null` when it had
+    // nothing to do. It rides out on the warning line so the aside directory is
+    // printed where the operator is already looking.
+    let cleared = null;
+    // The routine protected-path collision, reconciled rather than refused
+    // (APRV-346). This runs BEFORE the fast-forward below and does that
+    // fast-forward itself: `logSync` holds the append lock for its whole ceremony
+    // — snapshot, baseline, `git merge --ff-only`, reconcile, rebuild the
+    // projections, post-verify — and this module supplies a caller for it rather
+    // than a second copy of any of that. The merge below then finds the checkout
+    // already at the target and says so.
+    let synced = null;
+    if (report.sync !== null && report.root !== null) {
+        const remote = input.remote ?? "origin";
+        const branch = input.branch ?? currentBranch(report.root) ?? "main";
+        const result = logSync({ cwd: report.root, remote, branch });
+        if (!result.ok) {
+            // Asked for a reconcile this module had already found reconcilable, and
+            // refused: an appender that took the lock first, a fork that landed in
+            // between, or git itself. Either way nothing starts, and the sync's own
+            // code and sentence go into the refusal so the operator is not sent to
+            // read a second one.
+            return {
+                ok: false,
+                facts: { ...facts, action: "refused" },
+                refusal: divergedRefusal(remote, branch, facts.behind_by, [repoPath(report.root, input.logPath)], [`approval log sync refused at its ${result.step} step (${result.code}): ${result.message}`]),
+            };
+        }
+        synced = {
+            commit: result.report.commitAfter,
+            kept: report.sync.kept,
+            relation: report.sync.relation,
+            remote,
+            branch,
+        };
+    }
     if (facts.behind_by > 0 && report.root !== null && report.target !== null) {
-        const merged = git(["merge", "--ff-only", report.target], report.root);
+        const root = report.root;
+        const target = report.target;
+        let merged = git(["merge", "--ff-only", target], root);
+        if (!merged.ok) {
+            const reconciled = reconcileUntrackedTaskFiles(root, target, failureText(merged));
+            if (reconciled.kind === "refused") {
+                return { ok: false, facts: { ...facts, action: "refused" }, refusal: reconciled.refusal };
+            }
+            if (reconciled.kind === "failed") {
+                return {
+                    ok: false,
+                    facts: { ...facts, action: "refused" },
+                    failed: { step: reconciled.step, message: reconciled.message },
+                };
+            }
+            if (reconciled.kind === "cleared") {
+                cleared = reconciled.note;
+                // Once. A second failure is a different failure — the merge was asked
+                // again only because the thing that stopped it is provably gone.
+                merged = git(["merge", "--ff-only", target], root);
+            }
+        }
         if (!merged.ok) {
             return {
                 ok: false,
@@ -605,12 +803,262 @@ export function runPreflight(input, spawnBuild = npmBuild) {
     const plan = stale && build ? reexecPlan(input.root) : null;
     return {
         ok: true,
-        facts: { ...settled, reexec: plan !== null },
+        facts: { ...settled, reexec: plan !== null, log_synced: synced !== null },
         detail: report.detail,
-        warning,
+        warning: [warning, cleared].filter((part) => part !== null).join("; ") || null,
         ...(plan === null ? {} : { reexec: plan }),
+        ...(synced === null ? {} : { synced }),
     };
 }
+// ---------------------------------------------------------------------------
+// Untracked task files in the fast-forward's way (APRV-300)
+// ---------------------------------------------------------------------------
+/**
+ * The one directory this reconciliation is allowed to touch.
+ *
+ * Backlog.md task files are the only path in this repository where the same
+ * file is routinely authored in two checkouts at once: a lane files a task on
+ * its branch and the primary files it again with `backlog task create`, so the
+ * primary holds untracked bytes at a path the incoming commit carries. Nothing
+ * else has that shape, and widening the prefix would turn a narrow, provable
+ * case into a general licence to move an operator's files.
+ */
+const TASK_FILE_PREFIX = "backlog/tasks/";
+/** Git's own sentence when a fast-forward would clobber an untracked file. */
+const UNTRACKED_HEADLINE = "untracked working tree files would be overwritten";
+/**
+ * The paths out of that message, or `null` when this was some other failure.
+ *
+ * {@link failureText} has already joined git's lines with ` | `, so the shape
+ * parsed here is `error: The following untracked working tree files would be
+ * overwritten by merge: | <path> | <path> | Please move or remove them…`. A
+ * path git chose to quote (`core.quotePath`, a name with a control byte or a
+ * non-ASCII byte) is answered as `null` rather than unquoted by hand: guessing
+ * the spelling of a file about to be moved is the one mistake this whole
+ * function exists to avoid, and the existing refusal is a fine answer.
+ */
+function untrackedCollisions(message) {
+    const parts = message.split(" | ").map((part) => part.trim());
+    const start = parts.findIndex((part) => part.includes(UNTRACKED_HEADLINE));
+    if (start < 0)
+        return null;
+    const paths = [];
+    for (const part of parts.slice(start + 1)) {
+        if (part.length === 0)
+            continue;
+        if (part.startsWith("Please ") || part === "Aborting")
+            break;
+        if (part.startsWith('"'))
+            return null;
+        paths.push(part);
+    }
+    return paths.length === 0 ? null : paths;
+}
+/**
+ * Clear untracked task files out of a fast-forward's way, or refuse saying why.
+ *
+ * The incident (2026-09-07): a lane filed `backlog/tasks/aprv-299` on its
+ * branch and its pull request merged, while the primary checkout held the same
+ * path untracked from its own `backlog task create`. `git merge --ff-only`
+ * refuses to write over an untracked file, so `approval up` refused, and its
+ * next-steps text pointed at `git status`, which cannot say whether the local
+ * copy holds anything the incoming one does not. That is the question, and it
+ * is answerable, so it is answered here.
+ *
+ * Three verdicts, in this order, each with a different claim behind it:
+ *
+ * - **identical bytes** — the local file says nothing the incoming file does
+ *   not say. Removing it loses nothing, so it is removed;
+ * - **every line also in the incoming copy** — the primary's copy is a subset
+ *   of what main now carries (the ordinary shape: a stub filed by hand, then
+ *   the lane's copy with a plan and criteria added). Nothing is lost by
+ *   letting the incoming copy land, but "nothing is lost" is a judgment about
+ *   an operator's file, so the bytes are moved aside rather than deleted and
+ *   the destination is printed;
+ * - **anything else** — the local copy has lines main lacks. That is a
+ *   question about which version is wanted, and no verb here will pick.
+ *
+ * Two passes, and the order is the safety property, exactly as APRV-225's
+ * payload reconciliation in `cli/log-sync.ts`: every file is judged before any
+ * file is touched, so a refusal over the last one cannot have already removed
+ * the first.
+ */
+function reconcileUntrackedTaskFiles(root, target, message) {
+    const collisions = untrackedCollisions(message);
+    if (collisions === null)
+        return { kind: "declined" };
+    // One path outside `backlog/tasks/` and the whole set is declined. A
+    // reconciliation that cleared what it understood and then refused anyway
+    // would have moved an operator's files for a merge that was never going to
+    // run (AC3).
+    if (!collisions.every((path) => path.startsWith(TASK_FILE_PREFIX)))
+        return { kind: "declined" };
+    const verdicts = [];
+    for (const relative of collisions) {
+        let local;
+        try {
+            local = readIfPresent(join(root, relative));
+        }
+        catch (cause) {
+            return {
+                kind: "failed",
+                step: "reading an untracked task file",
+                message: `${relative} stopped the fast-forward and could not be read to judge it: ${detailOf(cause)}. Nothing was moved.`,
+            };
+        }
+        // Gone between the merge's complaint and this read: nothing to clear, and
+        // nothing to weigh either. The retry will find out.
+        if (local === null)
+            continue;
+        const incoming = showBlob(root, target, relative);
+        if (incoming === null) {
+            return {
+                kind: "failed",
+                step: `git show ${target}:${relative}`,
+                message: `the fast-forward stopped on the untracked ${relative} and git could not read the incoming copy to compare it against. Nothing was moved.`,
+            };
+        }
+        if (incoming.equals(local)) {
+            verdicts.push({ kind: "remove", relative });
+            continue;
+        }
+        const only = linesOnlyIn(local, incoming);
+        verdicts.push(only === 0 ? { kind: "aside", relative } : { kind: "diverged", relative, only });
+    }
+    const diverged = verdicts.find((verdict) => verdict.kind === "diverged");
+    if (diverged !== undefined) {
+        const local = join(root, diverged.relative);
+        return {
+            kind: "refused",
+            refusal: {
+                code: "up-preflight-task-file-conflict",
+                headline: `the untracked ${diverged.relative} has ${plural(diverged.only, "line")} the incoming copy does not`,
+                state: [
+                    `yours: ${local}`,
+                    `incoming: ${target.slice(0, 12)}:${diverged.relative}`,
+                    `${plural(diverged.only, "line")} only yours has`,
+                    "nothing was merged, nothing was moved, and nothing was rebuilt",
+                ],
+                steps: [
+                    {
+                        command: `git show ${target.slice(0, 12)}:${diverged.relative} | diff - ${JSON.stringify(local)}`,
+                        note: "the two copies, side by side",
+                    },
+                    {
+                        command: `mv ${JSON.stringify(local)} ${JSON.stringify(`${local}.mine`)}`,
+                        note: "keep yours out of the way, then run approval up again",
+                    },
+                ],
+                footer: [
+                    "an identical copy is removed and a copy main already contains is moved aside; this one is neither",
+                    "what the preflight will and will not do: docs/cli-reference.md#up",
+                ],
+                next: `git show ${target.slice(0, 12)}:${diverged.relative}`,
+            },
+        };
+    }
+    const removals = verdicts.filter((verdict) => verdict.kind === "remove");
+    const asides = verdicts.filter((verdict) => verdict.kind === "aside");
+    if (removals.length === 0 && asides.length === 0)
+        return { kind: "declined" };
+    // The moves go first and the removals second, so a failure part-way has
+    // preserved every byte it had a reason to preserve. Either way the message
+    // names what already moved: a half-finished clearing an operator cannot see
+    // is worse than the collision it was clearing.
+    const asideRoot = asidePath(root);
+    const moved = [];
+    const sofar = () => moved.length === 0 ? "" : ` Already moved aside: ${moved.join(", ")}.`;
+    for (const verdict of asides) {
+        const from = join(root, verdict.relative);
+        const to = join(asideRoot, verdict.relative);
+        try {
+            mkdirSync(dirname(to), { recursive: true });
+            moveFile(from, to);
+        }
+        catch (cause) {
+            return {
+                kind: "failed",
+                step: "moving an untracked task file aside",
+                message: `${verdict.relative} could not be moved to ${to}: ${detailOf(cause)}. Nothing was merged.${sofar()}`,
+            };
+        }
+        moved.push(to);
+    }
+    for (const verdict of removals) {
+        try {
+            rmSync(join(root, verdict.relative), { force: true });
+        }
+        catch (cause) {
+            return {
+                kind: "failed",
+                step: "removing an untracked task file",
+                message: `${verdict.relative} is byte-identical to the incoming copy and could not be removed: ${detailOf(cause)}. Nothing was merged.${sofar()}`,
+            };
+        }
+    }
+    const said = [];
+    if (removals.length > 0) {
+        said.push(`${plural(removals.length, "untracked task file")} byte-identical to the incoming copy ${removals.length === 1 ? "was" : "were"} removed`);
+    }
+    if (moved.length > 0) {
+        said.push(`${plural(moved.length, "untracked task file")} whose every line the incoming copy already carries ${moved.length === 1 ? "was" : "were"} moved to ${moved.join(", ")}`);
+    }
+    return { kind: "cleared", note: `${said.join("; ")}, and the fast-forward was retried` };
+}
+/**
+ * How many lines of `local` do not appear anywhere in `incoming`.
+ *
+ * A set of the incoming lines rather than a diff, and deliberately: the
+ * question is not whether the two files line up, it is whether the local copy
+ * holds any *content* main has not got. A task file reordered by the Backlog.md
+ * CLI, or one whose sections were rewritten in place, is the same information
+ * in a different arrangement, and zero here is exactly the claim that moving
+ * the local copy aside loses nothing.
+ */
+function linesOnlyIn(local, incoming) {
+    const carried = new Set(incoming.toString("utf8").split("\n"));
+    return local
+        .toString("utf8")
+        .split("\n")
+        .filter((line) => !carried.has(line)).length;
+}
+/**
+ * Where a moved-aside file goes: a sibling of the checkout, dated.
+ *
+ * Outside the repository on purpose. Inside it, the file would still be
+ * untracked, `git status` would still show it, and the next fast-forward could
+ * collide with it all over again — which is to say the move would have solved
+ * nothing. A sibling directory is somewhere `ls ..` finds, the date makes two
+ * runs on two days two directories, and nothing here ever removes one: it is
+ * the operator's copy, kept until they say otherwise.
+ */
+function asidePath(root) {
+    const day = new Date().toISOString().slice(0, 10);
+    return join(dirname(root), `${basename(root)}-preflight-aside-${day}`);
+}
+/** `rename`, falling back to copy-and-unlink when the two sit on two devices. */
+function moveFile(from, to) {
+    try {
+        renameSync(from, to);
+    }
+    catch (cause) {
+        if (cause.code !== "EXDEV")
+            throw cause;
+        copyFileSync(from, to);
+        rmSync(from, { force: true });
+    }
+}
+/** The bytes at `path`, or `null` when there is no file there. */
+function readIfPresent(path) {
+    try {
+        return readFileSync(path);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return null;
+        throw new ScanError(`${path} could not be read: ${detailOf(cause)}`);
+    }
+}
 /**
  * The plan to re-exec, or `null` when there is nothing to re-exec into.
  *
@@ -683,6 +1131,18 @@ export function describePreflightEvent(event) {
     if (event.event === "preflight_warning") {
         return { text: `approval: preflight — ${event.message}`, stderr: true };
     }
+    if (event.event === "preflight_policy") {
+        return {
+            text: `up: preflight — ${event.detail}${event.fix === null ? "" : `; ${event.fix}`}`,
+            stderr: true,
+        };
+    }
+    if (event.event === "preflight_sync") {
+        return {
+            text: `up: preflight — synced: fast-forwarded to ${event.remote}/${event.branch} ${event.commit.slice(0, 12)}, kept ${String(event.kept)} local records`,
+            stderr: false,
+        };
+    }
     const commits = `${String(event.behind_by)} commit${event.behind_by === 1 ? "" : "s"}`;
     const did = {
         none: "already at the remote tip, on a build no older than the sources",
@@ -702,6 +1162,27 @@ export function describePreflightEvent(event) {
     const handover = event.reexec ? ", in a fresh process on the new build" : "";
     return { text: `up: preflight — ${did[event.action]}${running}${handover}`, stderr: false };
 }
+/**
+ * The policy file `--policy` names, or the one `--dir` (else `cwd`) holds.
+ *
+ * Discovery, not a load: this answers WHICH FILE, so the preflight can compare
+ * its attested hash against the remote's copy (APRV-342) before either caller
+ * has loaded a policy. The order is `core/policy-load.ts`'s own, so the file
+ * named here is the file the runtime will go on to enforce. `null` when there is
+ * no such file, which is not a finding — `approval doctor`'s `policy` rows are
+ * where an absent policy is somebody's problem.
+ */
+export function preflightPolicyPath(policyFlag, dirFlag, cwd) {
+    if (policyFlag !== null)
+        return resolvePathSegments(cwd, policyFlag);
+    const dir = dirFlag === null ? cwd : resolvePathSegments(cwd, dirFlag);
+    for (const filename of POLICY_FILENAMES) {
+        const candidate = join(dir, filename);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
 /**
  * Run the preflight, print what it did, and answer whether the caller may start.
  *
@@ -733,6 +1214,11 @@ export function startupPreflight(input) {
     if (outcome.warning !== null) {
         input.emit({ event: "preflight_warning", message: outcome.warning });
     }
+    // Before the `preflight` line, because it happened before what that line
+    // reports: the reconcile is what made the fast-forward possible.
+    if (outcome.synced !== undefined) {
+        input.emit({ event: "preflight_sync", ...outcome.synced });
+    }
     // Emitted BEFORE the re-exec, and by the parent, because this is the only
     // place the whole story is known: the child runs with `--no-preflight` and
     // has nothing to say about a fast-forward it did not perform. The commit is
@@ -743,8 +1229,75 @@ export function startupPreflight(input) {
         detail: outcome.detail,
         ...outcome.facts,
     });
+    // APRV-342, and AFTER the fast-forward: a merge that just landed the
+    // amendment is exactly the case where the answer changes, and reporting the
+    // pre-merge one would name an interregnum this process had already left.
+    const interregnum = attestedPolicyLine(input);
+    if (interregnum !== null)
+        input.emit(interregnum);
     return { ok: true, reexec: outcome.reexec ?? null };
 }
+/**
+ * The `attested-policy-on-main` line, or `null` when there is nothing to say.
+ *
+ * `null` for a pass, a skip, and for every state the check cannot read: the
+ * preflight's lines report what happened and what an operator has to act on,
+ * and "your policy is where it should be" is neither. It NEVER refuses — see
+ * {@link checkAttestedPolicyOnMain} for why a pending amendment is a normal
+ * state of a repository rather than a fault.
+ *
+ * The log is re-verified here rather than passed in, because the preflight runs
+ * before either caller has opened it. That is one whole-log read at startup, in
+ * a process that is about to read the log on every tick.
+ */
+function attestedPolicyLine(input) {
+    const policyPath = input.policyPath ?? null;
+    if (policyPath === null)
+        return null;
+    const root = repoRoot(dirname(input.logPath));
+    if (root === null)
+        return null;
+    // The cheap half first, and it answers the common case without opening the
+    // log at all: when the remote's copy of the policy is byte-identical to the
+    // one on disk, "is the attested policy on the remote" has the same answer as
+    // "is the policy on disk attested" — which is doctor's `attestation` row, and
+    // which `up` has no business duplicating on its startup line. The expensive
+    // half below is a whole-log verify, so skipping it whenever the answer is
+    // already settled is the difference between a read per start and a read per
+    // start on a repository mid-amendment.
+    const relative = repoPath(root, policyPath);
+    if (relative.startsWith(".."))
+        return null;
+    const remote = input.remote ?? "origin";
+    const branch = input.branch ?? currentBranch(root) ?? "main";
+    const resolved = git(["rev-parse", "--verify", "--quiet", `refs/remotes/${remote}/${branch}^{commit}`], root);
+    const tip = resolved.stdout.trim();
+    if (!resolved.ok || tip.length === 0)
+        return null;
+    const blob = showBlob(root, tip, relative);
+    let onDisk;
+    try {
+        onDisk = readIfPresent(policyPath);
+    }
+    catch {
+        return null;
+    }
+    if (blob !== null && onDisk !== null && blob.equals(onDisk))
+        return null;
+    const verified = verifyWithRecords(input.logPath);
+    if (verified.result.status !== "clean")
+        return null;
+    const row = checkAttestedPolicyOnMain({
+        policyPath,
+        records: verified.records,
+        root,
+        ...(input.remote === null ? {} : { remote: input.remote }),
+        ...(input.branch === null ? {} : { branch: input.branch }),
+    });
+    if (row.status !== "fail")
+        return null;
+    return { event: "preflight_policy", detail: row.detail, fix: row.fix ?? null };
+}
 /** The short sha this checkout is on, or `null` when git will not say. */
 function headCommit(logPath) {
     const root = repoRoot(dirname(logPath));
@@ -859,6 +1412,90 @@ function npmBuild(root) {
  * never `git`. That constraint predates this row and is the right one — a repair
  * line telling an operator to reset a branch would be doctor making a decision.
  */
+/**
+ * `attested-policy-on-main`, doctor's row for the interregnum (APRV-342).
+ *
+ * Between a policy amendment and its pull request merging there is a window
+ * where the attestation is in the log and the amended `APPROVAL.md` is in the
+ * working tree, and `origin/main` carries neither. A fresh checkout of main in
+ * that window has the OLD policy with no attestation covering it, and every
+ * gate operation there refuses `policy-not-attested`.
+ *
+ * Nothing said so. On 2026-09-16 `approval up` ran its preflight in exactly that
+ * state and reported "already at the remote tip"; doctor's `attestation` row
+ * passed, because the LOCAL file is attested and that row asks a different
+ * question. This row asks the missing one: is the policy the log vouches for the
+ * policy `origin/<branch>` carries?
+ *
+ * Read-only, and networkless. The remote tip is read from the last fetch, like
+ * every other answer doctor gives about a remote, and the `policy-amend-<seq>`
+ * branch is looked for among the remote-tracking refs rather than asked of
+ * GitHub: a report that reached the network to be more accurate would be doing
+ * something on its own account.
+ */
+export function checkAttestedPolicyOnMain(input) {
+    const check = "attested-policy-on-main";
+    const root = input.root;
+    if (root === null) {
+        return {
+            check,
+            status: "skip",
+            detail: `${input.policyPath} is not inside a git repository, so there is no remote copy of it to compare the attestation against`,
+        };
+    }
+    const status = checkAttestation([...input.records], input.policyPath);
+    // Not applicable rather than a pass: with no attestation there is no hash to
+    // compare, and `attestation` is the row that has something to say about that.
+    const attested = status.status === "attested"
+        ? { sha256: status.sha256, seq: status.seq }
+        : status.status === "hash-mismatch"
+            ? { sha256: status.attestedSha256, seq: status.seq }
+            : null;
+    if (attested === null) {
+        return {
+            check,
+            status: "skip",
+            detail: `${input.policyPath} carries no attestation, so there is no attested hash to look for on the remote`,
+        };
+    }
+    const remote = input.remote ?? "origin";
+    const branch = input.branch ?? currentBranch(root) ?? "main";
+    const ref = `refs/remotes/${remote}/${branch}`;
+    const resolved = git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], root);
+    const tip = resolved.stdout.trim();
+    if (!resolved.ok || tip.length === 0) {
+        return {
+            check,
+            status: "skip",
+            detail: `this checkout has no ${remote}/${branch} remote-tracking ref, so there is no remote copy of ${input.policyPath} to compare the attestation against`,
+        };
+    }
+    const relative = repoPath(root, input.policyPath);
+    const blob = relative.startsWith("..") ? null : showBlob(root, tip, relative);
+    const remoteSha256 = blob === null ? null : policyBytesHash(blob);
+    if (remoteSha256 === attested.sha256) {
+        return {
+            check,
+            status: "pass",
+            detail: `${remote}/${branch} carries the policy attested at seq ${String(attested.seq)} (sha256 ${attested.sha256.slice(0, 12)}…)`,
+        };
+    }
+    // The branch the amendment would ride, when this checkout has already seen it
+    // on the remote. Named in the detail rather than in the fix: `approval policy
+    // amend --pr` is the command either way, because it updates an open pull
+    // request rather than opening a second one (APRV-341).
+    const amendBranch = `policy-amend-${String(attested.seq)}`;
+    const pushed = git(["rev-parse", "--verify", "--quiet", `refs/remotes/${remote}/${amendBranch}^{commit}`], root);
+    const carried = pushed.ok && pushed.stdout.trim().length > 0;
+    return {
+        check,
+        status: "fail",
+        detail: `attested at seq ${String(attested.seq)}, not yet on main: ${remote}/${branch} carries ${remoteSha256 === null ? `no ${relative} at all` : `${relative} hashing ${remoteSha256.slice(0, 12)}…`} while the attestation covers ${attested.sha256.slice(0, 12)}…${carried
+            ? `; ${remote} already carries ${amendBranch}, so its pull request is what lands it`
+            : ""}. A fresh checkout of ${branch} refuses every gate operation with policy-not-attested until it merges`,
+        fix: `approval policy amend --pr — commits the policy and its attestation on ${amendBranch}, opens or updates its pull request, and arms the merge`,
+    };
+}
 export function checkMainBehindOrigin(logPath, queuePath, root) {
     const report = inspectPreflight({ logPath, queuePath, root, fetch: false });
     if (!report.ok) {
@@ -878,10 +1515,17 @@ export function checkMainBehindOrigin(logPath, queuePath, root) {
     if (report.facts.behind_by === 0 && !report.facts.dist_stale) {
         return { check: "main-behind-origin", status: "pass", detail: `${report.detail}${suffix}` };
     }
+    // A plan is worth naming even though it is a pass: the row is where an
+    // operator looks to find out whether starting will be one command or two, and
+    // "your working log extends the committed one" is the answer that used to
+    // arrive as a refusal (APRV-346).
+    const plan = report.sync === null
+        ? ""
+        : `; the working log is a clean extension (${report.sync.relation}, ${plural(report.sync.kept, "local record")}), so up reconciles it rather than refusing`;
     return {
         check: "main-behind-origin",
         status: "pass",
-        detail: `${report.detail}; upstream ${report.facts.log_touched ? "DOES" : "does not"} touch the working log or queue${suffix}`,
+        detail: `${report.detail}; upstream ${report.facts.log_touched ? "DOES" : "does not"} touch the working log or queue${plan}${suffix}`,
         fix: "approval up — fast-forwards and rebuilds when it is safe, and refuses with the next command when it is not",
     };
 }