approval-md 0.0.1 → 0.2.0

package/dist/src/daemon/advance.js

@@ -0,0 +1,849 @@
+/**
+ * The daemon's log advance, on a cadence and through the gate (APRV-204).
+ *
+ * ## Why the daemon does this at all
+ *
+ * The committed log is this project's truth, and until this module its
+ * freshness depended on somebody remembering to run `approval log advance`. The
+ * daemon is already the committed log's sole writer in the primary checkout, it
+ * is already awake, and since the seq 7413 ceremony `log.advance` resolves
+ * `supervised-live 0.1` — a class that needs no hand on the keyboard for nine
+ * runs in ten. So the bookkeeping moves here, and the human's part shrinks to
+ * the tenth run and the merge.
+ *
+ * ## It borrows every mechanism and owns none
+ *
+ * - The advance itself is `cli/log-advance.ts`'s `logAdvance`, called
+ *   unmodified: the same append lock, the same chain verify, the same staged-set
+ *   refusal, the same commit-on-the-remote-without-a-checkout. A second
+ *   implementation would be a second thing to get wrong about the one file
+ *   nothing may rewind.
+ * - The authorization is `core/gate.ts`'s `register` + `request` and
+ *   `core/execute.ts`'s `startExecution` / `finishExecution`, in that order and
+ *   with no shortcuts. The daemon proposes as `agent:daemon` and the runtime
+ *   decides, exactly as it decides for a session.
+ * - The cadence and the reporting are the only decisions here, and neither
+ *   touches the log.
+ *
+ * ## What happens when the gate says no
+ *
+ * A `supervised-live` draw that SELECTS this advance, a class amended to
+ * `manual`, a policy that will not load: all three end the attempt with nothing
+ * committed and nothing pushed. The outcome is reported on the daemon's event
+ * stream and readable afterwards from the log itself, and the next tick tries
+ * again — after the cadence interval, never immediately, because the
+ * last-attempt clock is set by a refusal exactly as it is by a success. There
+ * is no retry loop and no backoff ladder: the cadence IS the backoff.
+ *
+ * ## The merge: armed here, performed by nobody (APRV-284)
+ *
+ * This file still calls no merge. What it does is ask `logAdvance` to ARM one:
+ * `gh pr merge <branch> --merge --auto` on the day's records pull request, so
+ * the pull request lands when its checks and the repository's branch rules say
+ * it may, and never earlier. Before APRV-284 it sat at CLEAN until a person
+ * clicked, which is the failure mode CLAUDE.md's workflow item 7 is written
+ * against — and clicking was never a review, because a records branch carries
+ * only the log, `QUEUE.md` and `.approval/payloads/`, the three paths CI's
+ * protected-path guard exempts.
+ *
+ * Two things keep that from being a daemon approving its own evidence. The arm
+ * is `vcs.push.main` in this project's taxonomy — the same class as the same
+ * command in a session's hands — and it rides the SAME `log.advance`
+ * authorization this cycle already holds rather than opening a second question
+ * or claiming a second grant: one authorization, one act. And `cli/log-advance.
+ * ts`'s `armAutoMerge` withholds the arm outright when the branch it pushed
+ * carries a path an advance may not carry, so what gets armed is only ever
+ * evidence. `--no-advance-auto-merge` turns the whole thing off.
+ *
+ * ## The self-perpetuation trap, and how the trigger avoids it
+ *
+ * One advance cycle appends three records of its own (`task.registered`,
+ * `execution.started`, `execution.completed`). Two of them land before the
+ * commit and ride it; the third lands after, so every successful advance leaves
+ * the log one record ahead of the records branch. A trigger that counted those
+ * would advance forever on an idle repository. So the TRIGGER counts only
+ * records that are not an advance's own bookkeeping (`PublishedState.substantive`),
+ * while the count REPORTED to an operator is the honest raw one.
+ *
+ * ## Where the pieces live
+ *
+ * The cycle's vocabulary (the actor, the class, the task and key shapes, and
+ * reading the last cycle back out of the log) is `core/advance-cycle.ts`, and
+ * the git-side "what is already published" question is `cli/log-advance.ts`.
+ * Both are shared with `approval doctor`, which reports the same numbers in a
+ * different process — and a CLI module may not import the daemon.
+ */
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { tick } from "../core/clock.js";
+import { ADVANCE_ACTOR, ADVANCE_CLASS, RESOLVE_DANGLING_COMMAND, advanceActionKey, advanceTaskId, danglingAdvances, openAdvanceRequest, proveDanglingAdvances, } from "../core/advance-cycle.js";
+import { childEnvironment } from "../core/child-env.js";
+import { finishExecution, startExecution, } from "../core/execute.js";
+import { register, request } from "../core/gate.js";
+import { attemptsOf, withHeadRetry } from "../core/head-retry.js";
+import { payloadHash } from "../core/payload.js";
+import { loadPolicy } from "../core/policy-load.js";
+import { defaultRecordsBranch, logAdvance, publishedState, } from "../cli/log-advance.js";
+import { repoRoot } from "../cli/git-scope.js";
+/**
+ * How often the daemon advances, absent the record-count trigger: 15 minutes.
+ *
+ * Chosen against what a records pull request costs and what staleness costs. A
+ * shorter interval publishes a pull request whose diff is a handful of lines
+ * and burns a CI run for each; a longer one leaves the guards that read the
+ * committed log (the CI protected-path cross-check especially) looking at a log
+ * that is hours behind the decisions it is supposed to evidence.
+ */
+export const DEFAULT_ADVANCE_INTERVAL_MS = 900_000;
+/**
+ * How many unpublished records force an advance before the interval elapses: 20.
+ *
+ * The busy-hour case. Twenty records is a few minutes of an active session, and
+ * a records branch that far behind is a records branch a person starts doing
+ * arithmetic against.
+ */
+export const DEFAULT_ADVANCE_AFTER_RECORDS = 20;
+/** The default cadence, spelled once. */
+export function defaultCadence() {
+    return {
+        intervalMs: DEFAULT_ADVANCE_INTERVAL_MS,
+        afterRecords: DEFAULT_ADVANCE_AFTER_RECORDS,
+        remote: "origin",
+        base: null,
+        pr: true,
+        autoMerge: true,
+    };
+}
+// ---------------------------------------------------------------------------
+// One gated attempt
+// ---------------------------------------------------------------------------
+/** The argv the payload binds to: the verb this attempt is authorization for. */
+export function advanceArgv(cadence) {
+    return [
+        "approval",
+        "log",
+        "advance",
+        ...(cadence.pr ? ["--pr"] : []),
+        // APRV-284. Present only when the arm is OFF, so the default cadence's argv
+        // is byte-identical to what it was before the arm existed and no payload
+        // hash or idempotency key moves under a running daemon.
+        ...(cadence.pr && !cadence.autoMerge ? ["--no-auto-merge"] : []),
+        "--remote",
+        cadence.remote,
+        ...(cadence.base === null ? [] : ["--base", cadence.base]),
+    ];
+}
+function detail(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/** Build an {@link AdvanceAttempt} with this attempt's fixed fields filled in. */
+function answerFor(ts, recordsPending, recordsBranch) {
+    return (over) => ({
+        ts,
+        recordsPending,
+        recordsBranch,
+        commit: null,
+        prUrl: null,
+        prCreated: false,
+        autoMerge: null,
+        autoMergeNote: null,
+        range: null,
+        code: null,
+        rebuilt: false,
+        rebuiltOn: null,
+        pendingFinish: null,
+        ...over,
+    });
+}
+// ---------------------------------------------------------------------------
+// The bounded head-moved retry on the outcome record (APRV-233)
+// ---------------------------------------------------------------------------
+/**
+ * Append the advance's outcome, re-deriving it against a fresh head on
+ * `head-moved` (APRV-233).
+ *
+ * ## What went wrong without it
+ *
+ * Observed 2026-09-02 on Carter's terminal: the advance pushed
+ * `records-log-2026-09-02`, and then `execution.completed could not be
+ * appended: head moved` — a harness hook's record landed between this module's
+ * read and its append, the compare-and-append refused the stale write exactly
+ * as SPEC.md §11.1 invariant 5 requires, and `daemon-log-advance-1-13984` was
+ * left open. Every other writer on this path has re-derived and re-attempted
+ * since APRV-150; this one did not, and the cost of losing the race was an
+ * execution the log said had never ended.
+ *
+ * ## What an attempt is
+ *
+ * The WHOLE operation, not a re-append: {@link finishExecution} re-reads the
+ * verified log, re-runs its `not-started` / `already-finished` /
+ * `execution-delegated` checks against that read, and appends with the head
+ * THAT read observed. Nothing crosses an attempt except the outcome the caller
+ * observed, which is a fact about the world rather than a conclusion about the
+ * log, so no stale derivation can authorize a write. A verdict that genuinely
+ * changed in the window (another writer closed the execution first) is the
+ * verdict returned, and the bound is returned unchanged once it is spent, so
+ * the caller still fails closed.
+ *
+ * ## One retry, in one place
+ *
+ * The loop and the bound are `core/head-retry.ts`'s (APRV-236 lifted them there
+ * for every gate writer, and APRV-233's first draft of this function was the
+ * local copy that helper replaced). `attemptsOf` clamps a caller's
+ * `retryOnHeadMoved` downward only, so the test harness can pin the unretried
+ * shape at `1` and nothing can raise the ceiling; `withHeadRetry` re-runs the
+ * whole `finishExecution` and adds the attempt count to the message it finally
+ * hands back. What remains here is only which operation is retried.
+ */
+function finishWithHeadMovedRetry(logPath, actionKey, exitCode, options) {
+    return withHeadRetry(attemptsOf(options.retryOnHeadMoved), () => finishExecution(logPath, actionKey, exitCode, ADVANCE_ACTOR, options));
+}
+/**
+ * Close an execution whose outcome an EARLIER tick observed and could not
+ * record (APRV-233).
+ *
+ * The second half of the fix, and the one that matters after a restart of the
+ * loop rather than of the process: the outcome is carried in memory as a
+ * {@link PendingAdvanceFinish} and re-attempted here, on the fresh head,
+ * before the next tick evaluates any trigger. It appends the same record the
+ * failed attempt would have appended, through the same bounded retry.
+ *
+ * `already-finished` is a SUCCESS here: something (a concurrent settle, a
+ * human's `approval execution resolve`) closed the cycle in the meantime, the
+ * log holds an outcome, and there is nothing left to carry.
+ */
+export function settleAdvanceFinish(input, pending) {
+    const result = finishWithHeadMovedRetry(input.logPath, pending.actionKey, pending.exitCode, {
+        policy: input.policy,
+        ...(input.schemaDir === undefined ? {} : { schemaDir: input.schemaDir }),
+        ...(input.clock === undefined ? {} : { clock: input.clock }),
+        ...(input.retryOnHeadMoved === undefined ? {} : { retryOnHeadMoved: input.retryOnHeadMoved }),
+        ...(input.afterFinishRead === undefined ? {} : { afterRead: input.afterFinishRead }),
+        ...(pending.reason === undefined ? {} : { reason: pending.reason }),
+        ...(pending.note === undefined ? {} : { note: pending.note }),
+    });
+    if (result.ok) {
+        return {
+            ok: true,
+            code: null,
+            message: `the outcome of ${pending.actionKey} is recorded (${result.event})`,
+        };
+    }
+    if (result.code === "already-finished") {
+        return {
+            ok: true,
+            code: null,
+            message: `${pending.actionKey} was already closed by another writer; nothing was appended`,
+        };
+    }
+    return {
+        ok: false,
+        code: result.code,
+        message: `the outcome of ${pending.actionKey} still could not be recorded: ${result.message}`,
+    };
+}
+/**
+ * Every open advance cycle, with what this checkout's refs prove (APRV-264).
+ *
+ * One `publishedState` for the whole list rather than one per key: it is the
+ * git read on the tick's hot path, and the answer it gives is the same for
+ * every key — the highest published seq, and the ref that carries it.
+ *
+ * Read from the log rather than from this process's memory, so a daemon that
+ * restarted still sees that an advance HAPPENED. It is the fact the cadence was
+ * missing on 2026-09-02: with no outcome record, nothing but an in-process
+ * clock said the branch had just been pushed.
+ */
+export function proveDanglingAdvancesFor(input, records) {
+    const open = danglingAdvances(records);
+    if (open.length === 0)
+        return [];
+    const root = repoRoot(input.cwd) ?? input.cwd;
+    const today = input.today ?? tick(input.clock === undefined ? {} : { clock: input.clock });
+    const state = publishedState(root, input.logPath, records, input.cadence, today);
+    return proveDanglingAdvances(records, state);
+}
+/** Is this sweep's work done — nothing open, nothing owed to a person? */
+export function sweepIsClear(sweep) {
+    return sweep.settled.length === 0 && sweep.outstanding.length === 0;
+}
+/**
+ * Close EVERY dangling advance cycle whose outcome the git refs still show
+ * (APRV-233, widened by APRV-264).
+ *
+ * ## The loop this breaks
+ *
+ * From Carter's terminal, 2026-09-02, with the APRV-211 build running: tick two
+ * advanced and pushed; its `execution.completed` lost the head race (expected
+ * 14874, found 14875) and `daemon-log-advance-1-14871` was left open. Tick
+ * three's authorization then reached `startExecution` on that same key and was
+ * refused `already-executed: an idempotency key is single-use and nothing here
+ * reconciles or reruns it` — which is the gate saying, correctly, that
+ * somebody has to close the books. Nobody did, so the span moved and the daemon
+ * pushed again, and again, every ninety seconds under a fifteen-minute
+ * interval.
+ *
+ * ## Why it sweeps rather than reconciles one
+ *
+ * APRV-233's version closed the LAST open cycle and returned. On 2026-09-05
+ * that was not enough: `approval status` listed FIVE, left by the 2026-09-02
+ * loop and by the restarts after it, the daemon refused one advance per tick
+ * naming one key each, and Carter closed all five by hand with five
+ * near-identical commands. One key per tick is a repair rate of one every
+ * thirty seconds behind a refusal that stops the cadence entirely, so the sweep
+ * takes every key it can prove in one pass and reports the rest together.
+ *
+ * ## What is and is not a guess here
+ *
+ * {@link settleAdvanceFinish} covers the case this process still holds the
+ * outcome for. This covers the other one — cycles left open by an earlier
+ * process, or by ticks whose memory of them is gone — and it closes each only
+ * on EVIDENCE: the records the cycle was authorized to publish are demonstrably
+ * on a records branch, read from git's own object store through the same
+ * `publishedState` the cadence and the doctor row read. When the evidence is
+ * there the outcome is recorded as the completion it was, with a note saying
+ * which ref proved it and that the RUNTIME observed it. When it is NOT there,
+ * nothing is written: the execution stays open for a person, the daemon warns
+ * once, and no new advance is started over work nobody has accounted for. A
+ * false `execution.failed` for an advance that actually published would be
+ * worse than the dangling record.
+ *
+ * The actor is {@link ADVANCE_ACTOR} and the record carries no
+ * `attested_by_human`: human attestation is for what a person went and looked
+ * at, and this is the runtime reading its own refs. The note says so in as many
+ * words, so no reader has to infer it from the actor field alone.
+ *
+ * This is a deliberate, narrow carve-out to `core/execute.ts`'s rule that
+ * nothing closes a dangling execution automatically. Narrow because it closes
+ * only executions THIS runtime started, for its own `log.advance` cycles, whose
+ * entire effect is a git ref this runtime can look at and did.
+ */
+export function sweepDanglingAdvances(input, records) {
+    const sweep = { settled: [], outstanding: [] };
+    // One git read for the whole sweep. Appending an outcome below cannot change
+    // the answer: `publishedState` counts only a committed copy that is a PREFIX
+    // of the working log, so a record appended after it was read leaves both the
+    // published seq and the ref that carries it exactly where they were.
+    for (const entry of proveDanglingAdvancesFor(input, records)) {
+        if (entry.provenBy === null) {
+            sweep.outstanding.push({
+                actionKey: entry.actionKey,
+                provenBy: null,
+                message: `${entry.actionKey} is an advance execution nobody closed, and no ref in this checkout carries seq ${entry.toSeq === null ? "the span it named" : String(entry.toSeq)}. Nothing is recorded for it: an outcome this runtime cannot observe is a human's to establish.`,
+            });
+            continue;
+        }
+        const finished = finishWithHeadMovedRetry(input.logPath, entry.actionKey, 0, {
+            policy: input.policy,
+            ...(input.schemaDir === undefined ? {} : { schemaDir: input.schemaDir }),
+            ...(input.clock === undefined ? {} : { clock: input.clock }),
+            ...(input.retryOnHeadMoved === undefined ? {} : { retryOnHeadMoved: input.retryOnHeadMoved }),
+            ...(input.afterFinishRead === undefined ? {} : { afterRead: input.afterFinishRead }),
+            note: {
+                code: "advance-reconciled",
+                message: `the outcome record was lost when this cycle ran; ${entry.provenBy} carries seq ${String(entry.toSeq)} in this checkout, so the advance completed. Observed by the runtime (${ADVANCE_ACTOR}) from that ref, not attested by a human`,
+            },
+        });
+        if (finished.ok) {
+            sweep.settled.push({
+                actionKey: entry.actionKey,
+                provenBy: entry.provenBy,
+                message: `${entry.actionKey} was left open by an earlier advance; ${entry.provenBy} carries seq ${String(entry.toSeq)}, so its completion is now recorded`,
+            });
+            continue;
+        }
+        // `already-finished` is somebody else closing the books between the read
+        // and the append, which is the outcome this wanted and not a failure.
+        if (finished.code === "already-finished") {
+            sweep.settled.push({
+                actionKey: entry.actionKey,
+                provenBy: entry.provenBy,
+                message: `${entry.actionKey} was closed by another writer before this sweep reached it; nothing was appended`,
+            });
+            continue;
+        }
+        sweep.outstanding.push({
+            actionKey: entry.actionKey,
+            provenBy: entry.provenBy,
+            message: `${entry.actionKey} could not be closed: ${finished.message}`,
+        });
+    }
+    return sweep;
+}
+/**
+ * The refusal that stands while any advance cycle is open, naming all of them.
+ *
+ * One sentence for every outstanding key rather than one refusal per key per
+ * tick: the operator's next act is the same command whichever key they read
+ * first, so the command is on the line and every key it will close is under it.
+ */
+export function unreconciledRefusal(keys) {
+    return `${String(keys.length)} advance execution(s) were started and their outcomes were never recorded; nothing new is authorized until they are closed (${keys.join(", ")}). \`approval status\` shows them; \`${RESOLVE_DANGLING_COMMAND}\` closes every one this checkout can prove and lists the rest.`;
+}
+/**
+ * Register, request, start. The authorization, and not one byte of side effect.
+ *
+ * The order is the whole point and none of it is optional: nothing is committed
+ * before the gate has answered, and nothing the gate answered for goes
+ * unrecorded. `execution.started` is appended BEFORE the advance runs, so the
+ * commit the advance builds carries the record of its own authorization; the
+ * `execution.completed` that follows lands after the commit and is published by
+ * the next advance, which is why the trigger discounts it.
+ *
+ * ## What APRV-211 changed: the tick asks the log what it already asked
+ *
+ * Observed live on 2026-09-02: three ticks over ONE owed advance put three
+ * questions on Carter's phone, because the idempotency key embedded the log
+ * HEAD and the head moved with each gated attempt's own two records. Two things
+ * fix it and both are here.
+ *
+ * 1. The key and the payload span end at `substantiveSeq` — the last unpublished
+ *    record that is not an advance cycle's own bookkeeping — so a tick that
+ *    appended only its own question computes the SAME key and the SAME hash.
+ * 2. Before it registers anything, the tick reads {@link openAdvanceRequest}.
+ *    A question still open is ADOPTED (nothing is appended, the outcome is
+ *    `gated`, and the human keeps the one question they already have); a grant
+ *    on it is SPENT (straight to `startExecution` on that key, with the hash
+ *    that key declared, so the single-use rule the log already enforces makes
+ *    one decision authorise exactly one advance); a terminal answer on the
+ *    CURRENT owed span is HONOURED (`advance-decided`, and nothing is asked
+ *    again until the span itself changes).
+ */
+export function authorizeAdvance(input, records) {
+    const ts = tick(input.clock === undefined ? {} : { clock: input.clock });
+    const today = input.today ?? ts;
+    const root = repoRoot(input.cwd) ?? input.cwd;
+    const recordsBranch = defaultRecordsBranch(today);
+    const state = publishedState(root, input.logPath, records, input.cadence, today);
+    const answer = answerFor(ts, state.pending, recordsBranch);
+    const no = (over) => ({ authorized: false, attempt: answer(over) });
+    if (state.pending === 0) {
+        return no({
+            outcome: "nothing-owed",
+            message: `every record through seq ${String(state.publishedSeq)} is already on a records branch`,
+        });
+    }
+    // APRV-233. An advance cycle nobody closed the books on. Reaching
+    // `startExecution` from here produced the bare `already-executed` Carter saw
+    // on 2026-09-02 — the gate saying, correctly, that an idempotency key is
+    // single-use and nothing there reconciles or reruns it — after which the span
+    // moved and the branch was pushed all over again. The sweep belongs to
+    // {@link sweepDanglingAdvances}, which the caller runs first; whatever is
+    // still here is still a human's, and nothing is authorized over it.
+    //
+    // APRV-264: EVERY outstanding key, and the one command that clears them. The
+    // refusal used to name the last one only, so an operator holding five of them
+    // learned about the second after they had closed the first.
+    const unreconciled = danglingAdvances(records).map((entry) => entry.actionKey);
+    if (unreconciled.length > 0) {
+        return no({
+            outcome: "refused",
+            code: "advance-unreconciled",
+            message: unreconciledRefusal(unreconciled),
+        });
+    }
+    const gate = { policy: input.policy };
+    if (input.schemaDir !== undefined)
+        gate.schemaDir = input.schemaDir;
+    if (input.clock !== undefined)
+        gate.clock = input.clock;
+    const task = advanceTaskId(state.substantiveSeq);
+    const actionKey = advanceActionKey(state.publishedSeq + 1, state.substantiveSeq);
+    // The bytes this authorization binds to: the command, where it runs, and the
+    // seq span it publishes. The span is IN the hash deliberately (APRV-204). A
+    // payload identical across cycles would give the `supervised-live` draw the
+    // same verdict forever — a selected advance would stay selected on every
+    // later tick and the cadence would stop for good — and a span is not a
+    // re-roll: different records are a different action, which is exactly what
+    // §5.2's no-re-roll property means by "changing the bytes is a different
+    // request".
+    //
+    // It ends at the OWED span's end rather than at the head (APRV-211). The
+    // advance publishes whatever the log holds when it runs, which is this span
+    // plus this cycle's own two or three bookkeeping records; naming the owed
+    // span is what makes one owed advance one question, and the bookkeeping is
+    // not work anybody is being asked to approve.
+    const hash = payloadHash({
+        argv: advanceArgv(input.cadence),
+        cwd: root,
+        seq: { from: state.publishedSeq + 1, to: state.substantiveSeq },
+    });
+    // What this daemon already asked, and what became of it. Read from the
+    // verified records the caller handed in — the enforcement path never reads an
+    // unverified log (SPEC.md §11.1) — and aged against the policy's own TTL, so a
+    // question whose window lapsed stops being adopted whether or not the
+    // `approval.expired` record has been materialised yet.
+    const loaded = loadPolicy({
+        ...(input.policy.file === undefined ? {} : { file: input.policy.file }),
+        ...(input.policy.dir === undefined ? {} : { dir: input.policy.dir }),
+        ...(input.schemaDir === undefined ? {} : { schemaDir: input.schemaDir }),
+    });
+    const open = openAdvanceRequest(records, ts, loaded.ok ? loaded.durations.approvalTtlMs : null);
+    const adopted = open !== null && open.actionKey === actionKey;
+    if (open !== null && open.state === "requested") {
+        // Whatever the span has done since, a question is standing. Asking a second
+        // one would multiply the taps this cadence exists to remove, and answering
+        // the standing one authorises the advance the moment the next tick runs.
+        return no({
+            outcome: "gated",
+            code: "advance-open",
+            message: `an advance question is already open as ${open.actionKey} and nobody has answered it; nothing was asked again and nothing was committed. Answering it authorises the next tick's advance.`,
+        });
+    }
+    if (adopted && open !== null && open.state !== "granted") {
+        return no({
+            outcome: "refused",
+            code: "advance-decided",
+            message: `the advance of seq ${String(state.publishedSeq + 1)}..${String(state.substantiveSeq)} was already answered (${open.state} as ${open.actionKey}); nothing is asked again until the owed span changes.`,
+        });
+    }
+    if (adopted && open !== null && open.state === "granted" && open.spent) {
+        // The grant was consumed — by the advance that failed, or by one whose
+        // `execution.completed` has not been published yet. Either way the
+        // authorisation is gone, and a fresh question about an unchanged span is a
+        // retry loop with a human in it. The reason the last one failed is on the
+        // `execution.failed` and on the doctor row.
+        return no({
+            outcome: "refused",
+            code: "advance-spent",
+            message: `the decision on ${open.actionKey} has already been spent on an execution; this owed span will not be asked again until it changes.`,
+        });
+    }
+    // The grant this tick is riding was earned by an earlier tick's question, so
+    // there is nothing to declare and nothing to ask: the declaration and the
+    // question are in the log already, and re-asking is the defect. Straight to
+    // the execution, bound to the hash THAT request declared.
+    const declaredHash = adopted && open !== null && open.payloadHash !== null ? open.payloadHash : hash;
+    if (!adopted) {
+        const registered = register(input.logPath, {
+            task,
+            envelope: {
+                origin: { app: "approval-daemon", created_by: ADVANCE_ACTOR },
+                state: "proposed",
+                actions: [
+                    {
+                        class: ADVANCE_CLASS,
+                        idempotency_key: actionKey,
+                        summary: `log advance: seq ${String(state.publishedSeq + 1)}..${String(state.substantiveSeq)} onto ${recordsBranch}`,
+                        reversible: true,
+                        est_cost_usd: "0",
+                        payload_hash: hash,
+                    },
+                ],
+            },
+        }, ADVANCE_ACTOR, gate);
+        // A re-attempt at an unchanged span finds its own registration already in
+        // the log. That is the retry working, not a failure: the cycle continues and
+        // the request below adopts the declaration this one already wrote.
+        if (!registered.ok && registered.code !== "task-already-registered") {
+            return no({ outcome: "refused", code: registered.code, message: registered.message });
+        }
+        const asked = request(input.logPath, {
+            task,
+            actionKey,
+            cls: ADVANCE_CLASS,
+            reversible: true,
+            est_cost_usd: "0",
+            summary: `log advance: seq ${String(state.publishedSeq + 1)}..${String(state.substantiveSeq)}`,
+            payload_hash: hash,
+            payload: { value: { argv: advanceArgv(input.cadence), cwd: root, seq: { from: state.publishedSeq + 1, to: state.substantiveSeq } } },
+            // APRV-211. The requester is this process, and it will open the grant
+            // itself through the sealed address this request publishes. No granting
+            // surface is handed a raw token, so no granting surface can print one on
+            // a terminal for an action nobody at that terminal is going to run.
+            delivery: "self",
+        }, ADVANCE_ACTOR, gate);
+        if (!asked.ok) {
+            return no({ outcome: "refused", code: asked.code, message: asked.message });
+        }
+        if (!asked.proceed) {
+            return no({
+                outcome: "gated",
+                code: asked.live?.reason ?? "manual",
+                message: `the gate sent this advance to a human (${asked.live === undefined
+                    ? `class ${ADVANCE_CLASS} resolves ${asked.autonomy}`
+                    : `supervised-live draw: ${asked.live.reason} at rate ${String(asked.live.rate)}`}); nothing was committed. The question is in the queue as ${actionKey}, and the next tick adopts it rather than asking again.`,
+            });
+        }
+    }
+    const started = startExecution(input.logPath, actionKey, {
+        policy: input.policy,
+        presentedPayloadHash: declaredHash,
+        ...(input.schemaDir === undefined ? {} : { schemaDir: input.schemaDir }),
+        ...(input.clock === undefined ? {} : { clock: input.clock }),
+    }, ADVANCE_ACTOR);
+    if (!started.ok) {
+        return no({ outcome: "refused", code: started.code, message: started.message });
+    }
+    return {
+        authorized: true,
+        ts,
+        today,
+        root,
+        recordsBranch,
+        actionKey,
+        recordsPending: state.pending,
+        adopted,
+    };
+}
+/** Run the verb here, on this stack. The shutdown flush's path. */
+function runVerbHere(input, auth) {
+    try {
+        return logAdvance({
+            cwd: auth.root,
+            remote: input.cadence.remote,
+            base: input.cadence.base,
+            pr: input.cadence.pr,
+            autoMerge: input.cadence.autoMerge,
+            branch: auth.recordsBranch,
+            today: auth.today,
+        });
+    }
+    catch (cause) {
+        return { ok: false, code: "log-advance-git-failed", message: `the advance threw: ${detail(cause)}` };
+    }
+}
+/**
+ * Close the execution and report. The gate work, always in this process.
+ *
+ * A finish that is itself refused (an external writer moved the head between
+ * the advance and this append) leaves a dangling execution, which is the honest
+ * state and which nothing here auto-repairs: `approval status` surfaces it and
+ * a human resolves it. It is named in the reported message rather than
+ * swallowed.
+ *
+ * The verb's own refusal code and message travel onto `execution.failed`
+ * (APRV-211). Exit 1 with no reason was the reported half of the 2026-09-02
+ * incident: the daemon knew why the push failed and the log did not.
+ */
+function recordFinish(input, auth, advanced) {
+    const answer = answerFor(auth.ts, auth.recordsPending, auth.recordsBranch);
+    const exitCode = advanced.ok ? 0 : 1;
+    const reason = advanced.ok ? undefined : { code: advanced.code, message: advanced.message };
+    // APRV-234. A rebuilt branch is worth explaining even when the advance
+    // succeeded: an operator reading the doctor row a day later needs to know
+    // that today's records branch was re-parented on the trunk rather than
+    // stacked, and on which commit. A REPORT, never an authorization — nothing in
+    // the gate reads it back.
+    const note = advanced.ok && advanced.report.rebuilt === true
+        ? {
+            code: "advance-rebuilt",
+            message: `the day's records branch was rebuilt on ${advanced.report.rebuiltOn?.ref ?? "the base"} ${(advanced.report.rebuiltOn?.sha ?? "").slice(0, 12)}${advanced.report.recordsBranch === auth.recordsBranch
+                ? ""
+                : ` and opened as ${advanced.report.recordsBranch}`}`,
+        }
+        : undefined;
+    // APRV-233. Bounded, and each attempt a whole operation against a fresh head.
+    const finished = finishWithHeadMovedRetry(input.logPath, auth.actionKey, exitCode, {
+        policy: input.policy,
+        ...(input.schemaDir === undefined ? {} : { schemaDir: input.schemaDir }),
+        ...(input.clock === undefined ? {} : { clock: input.clock }),
+        ...(input.retryOnHeadMoved === undefined ? {} : { retryOnHeadMoved: input.retryOnHeadMoved }),
+        ...(input.afterFinishRead === undefined ? {} : { afterRead: input.afterFinishRead }),
+        ...(reason === undefined ? {} : { reason }),
+        ...(note === undefined ? {} : { note }),
+    });
+    // The bound is spent and the execution is open. The effect HAPPENED and this
+    // process knows how it ended, so the outcome is carried to the next tick
+    // rather than lost; until it is recorded the cadence treats this advance as
+    // still in hand and starts no other.
+    const pendingFinish = finished.ok
+        ? null
+        : {
+            actionKey: auth.actionKey,
+            exitCode,
+            ...(reason === undefined ? {} : { reason }),
+            ...(note === undefined ? {} : { note }),
+        };
+    const dangling = finished.ok
+        ? ""
+        : ` (the execution outcome could not be recorded: ${finished.message}; ${auth.actionKey} is left open and the next tick settles it before it advances anything)`;
+    if (!advanced.ok) {
+        return answer({
+            outcome: "failed",
+            code: advanced.code,
+            message: `${advanced.message}${dangling}`,
+            pendingFinish,
+        });
+    }
+    const report = advanced.report;
+    return answer({
+        outcome: report.commit === null ? "nothing-owed" : "advanced",
+        commit: report.commit,
+        prUrl: report.prUrl,
+        prCreated: report.prCreated ?? false,
+        autoMerge: report.autoMerge ?? null,
+        autoMergeNote: report.autoMergeNote ?? null,
+        range: report.range,
+        recordsBranch: report.recordsBranch,
+        rebuilt: report.rebuilt === true,
+        rebuiltOn: report.rebuiltOn === undefined ? null : report.rebuiltOn.ref,
+        pendingFinish,
+        message: report.commit === null
+            ? "the records branch already carried these bytes; nothing was committed"
+            : `seq ${String(report.range?.from ?? 0)}..${String(report.range?.to ?? 0)} is on ${report.recordsBranch}${report.rebuilt === true
+                ? ` (rebuilt on ${report.rebuiltOn?.ref ?? "the base"} ${(report.rebuiltOn?.sha ?? "").slice(0, 12)})`
+                : ""}${report.prUrl === null ? "" : ` (${report.prUrl})`}${armNote(report)}${dangling}`,
+    });
+}
+/**
+ * What the attempt's message says about the arm (APRV-284).
+ *
+ * Every outcome but `armed` names its reason: a pull request nobody armed is
+ * one a person still has to land, and an operator reading this line is the one
+ * who has to know that from the line rather than from the pull request.
+ */
+function armNote(report) {
+    switch (report.autoMerge ?? null) {
+        case null:
+            return "";
+        case "armed":
+            return ", auto-merge armed";
+        case "off":
+            return ", auto-merge not armed (--no-advance-auto-merge)";
+        case "withheld":
+            return `, auto-merge WITHHELD: ${report.autoMergeNote ?? "the branch carries more than an advance may"}`;
+        default:
+            return `, auto-merge refused by gh: ${report.autoMergeNote ?? "no reason given"}`;
+    }
+}
+/**
+ * The advance, on this stack, start to finish. The shutdown flush's path.
+ *
+ * Kept synchronous deliberately: `finish()` runs inside the daemon's shutdown,
+ * where there is no loop left to return to and an advance that settled after
+ * the process exited would be an advance nobody recorded.
+ */
+export function runAdvanceSync(input, auth) {
+    return recordFinish(input, auth, runVerbHere(input, auth));
+}
+/**
+ * The advance, with the git work in a child, so this loop keeps answering.
+ *
+ * ## Why a child rather than an `await`
+ *
+ * The second half of the 2026-09-02 incident: `answerCallbackQuery: HTTP 400`,
+ * over and over, around the grants. Telegram drops a callback query that is not
+ * answered inside its window, and `approval up` runs the channel listener and
+ * the daemon in ONE process on ONE loop. `logAdvance` is `spawnSync` from end to
+ * end — `git fetch`, a scratch-index commit, `git push`, `gh pr create` — so
+ * every tap that arrived during an advance waited for the push to finish, and
+ * the human got a button that never toasted. A promise would not have helped:
+ * synchronous work does not yield no matter what it is wrapped in. Only another
+ * process does.
+ *
+ * ## What does NOT move
+ *
+ * The gate work. `core/child-env.ts` strips `APPROVAL_*` from a child's
+ * environment (APRV-205), and the `supervised-live` draw's secret is exactly
+ * such a variable, so a child that asked the gate would be a child that could
+ * not draw and would fail closed on every tick. Authorization happens in
+ * {@link authorizeAdvance}, in this process, before the child is spawned;
+ * {@link recordFinish} closes the execution in this process, after it settles.
+ * The child gets one job — the git side effect — and no authority whatsoever.
+ * It never touches the log: it cannot append, and everything it says comes back
+ * as one JSON line on its stdout.
+ */
+export function runAdvanceAsync(input, auth) {
+    return new Promise((resolve) => {
+        const spec = input.runner ?? {
+            command: process.execPath,
+            args: [fileURLToPath(new URL("./advance-child.js", import.meta.url))],
+        };
+        const request_ = JSON.stringify({
+            cwd: auth.root,
+            remote: input.cadence.remote,
+            base: input.cadence.base,
+            pr: input.cadence.pr,
+            autoMerge: input.cadence.autoMerge,
+            branch: auth.recordsBranch,
+            today: auth.today,
+        });
+        let child;
+        try {
+            child = spawn(spec.command, [...spec.args, request_], {
+                cwd: auth.root,
+                env: childEnvironment().env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (cause) {
+            resolve(recordFinish(input, auth, {
+                ok: false,
+                code: "log-advance-child-unspawnable",
+                message: `the advance child could not be started: ${detail(cause)}`,
+            }));
+            return;
+        }
+        let out = "";
+        let err = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => (out += chunk));
+        child.stderr.on("data", (chunk) => (err += chunk));
+        const settle = (run) => {
+            resolve(recordFinish(input, auth, run));
+        };
+        child.on("error", (cause) => {
+            settle({
+                ok: false,
+                code: "log-advance-child-unspawnable",
+                message: `the advance child could not be started: ${detail(cause)}`,
+            });
+        });
+        child.on("close", (code) => {
+            const parsed = parseChildReport(out);
+            if (parsed !== null) {
+                settle(parsed);
+                return;
+            }
+            settle({
+                ok: false,
+                code: "log-advance-child-unreadable",
+                message: `the advance child exited ${String(code)} and said nothing this runtime could read${err.trim() === "" ? "" : `: ${err.trim().slice(0, 400)}`}`,
+            });
+        });
+    });
+}
+/**
+ * The child's one line, or `null` when it is not the shape this expects.
+ *
+ * Validated rather than cast: the child is another process, its stdout is
+ * input, and a report this runtime cannot recognise is a failed advance with a
+ * machine-readable reason — never a success taken on faith.
+ */
+function parseChildReport(text) {
+    const line = text.trim().split("\n").pop();
+    if (line === undefined || line === "")
+        return null;
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null)
+        return null;
+    const shape = value;
+    if (shape["ok"] === true && typeof shape["report"] === "object" && shape["report"] !== null) {
+        return { ok: true, report: shape["report"] };
+    }
+    if (shape["ok"] === false && typeof shape["code"] === "string" && typeof shape["message"] === "string") {
+        return { ok: false, code: shape["code"], message: shape["message"] };
+    }
+    return null;
+}
+/**
+ * Register, request, start, advance, finish. One attempt, on this stack.
+ *
+ * The whole cycle for a caller that has no loop to protect: the shutdown flush,
+ * `--once`, and every test that asserts on what one tick did.
+ */
+export function attemptAdvance(input, records) {
+    const auth = authorizeAdvance(input, records);
+    if (!auth.authorized)
+        return auth.attempt;
+    return runAdvanceSync(input, auth);
+}
+//# sourceMappingURL=advance.js.map