@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/cutover.js

@@ -0,0 +1,1444 @@
+/**
+ * Cutover state and rollback (kernel plan M4, M4-P26; D-19's second limb at
+ * delivery/plan/kernel-plan-v1.md:394).
+ *
+ * WHAT THIS MODULE IS. The freeze point is not one event. It is FIVE
+ * independently flippable switches, taken from the list the current delivery
+ * process retains at
+ * delivery/decisions/DR-0025-controlled-pre-m4-local-pilot.md:45 and read
+ * against DR-0036's authority condition. Five switches rather than one event
+ * is what makes rollback PARTIAL rather than all-or-nothing, and it is why
+ * `credentials-and-refs`, the one switch with owner latency, is separable
+ * from the four that are not.
+ *
+ * THE SPLIT THAT KEEPS THIS HONEST, and it runs through every function here.
+ * Rollback of the FILES is cheap: everything under the retirement roots is
+ * git-tracked and revertible from history. Rollback of AUTHORITY is the
+ * expensive half: the branch-protection ruleset is owner-configured, the
+ * orchestrator cannot change it, and
+ * delivery/decisions/DR-0036-the-harness-adapter-leads-m4-and-the-kernel-is-the-second-subject.md:15
+ * prices the revert at "whatever phases ran under it". Nothing in this module
+ * flips authority. It PREPARES the request an owner acts on, and it refuses
+ * loudly rather than pretending the preparation is the act.
+ *
+ * WHAT THIS MODULE DELIBERATELY DOES NOT DO. It does not print
+ * `tiphys cutover status`, does not write switches to `kernel`, and does not
+ * ship a state schema. Those are M4-P25's acceptance criteria and M4-P25's
+ * files. This phase was dispatched ahead of its stated dependency because the
+ * conflict pre-pass holds `src/commands/cutover.ts` for exactly one unit at a
+ * time, so the state MODEL is created here and the status SURFACE is left
+ * where the plan put it. The boundary is recorded in
+ * delivery/work-history/m4-p26.md:1 rather than left to be discovered.
+ *
+ * PLAN CONSTRAINTS. C-1: current state comes from `cutover.json` and from
+ * meta.json plus the turn-end file, never from the tail of a log. C-2: no pid,
+ * no signal, no /proc and no process probing appears here; a live worktree is
+ * a DIRECTORY and an open task is a FILE STATE. C-3: nothing is backgrounded.
+ */
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { closeSync, fsyncSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, statSync, writeSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { packageRoot } from "./modes.js";
+import { classifyEntry, readRegularFileIfPresent, turnEndPath, } from "./task.js";
+import { validateToLines } from "./validate.js";
+/* -------------------------------------------------------------------- */
+/* The five switches                                                     */
+/* -------------------------------------------------------------------- */
+/**
+ * The five retained items of DR-0025, in the order section 4.3 of the M4
+ * plan tabulates them. This list is CLOSED. A sixth name is a plan revision,
+ * not a code edit, because every rollback trigger enumerates it.
+ */
+export const CUTOVER_SWITCHES = [
+    "planning-and-scope",
+    "review-and-arbitration",
+    "credentials-and-refs",
+    "salvage-and-recovery",
+    "closeout",
+];
+export const SWITCH_STATES = ["current", "kernel"];
+/**
+ * The switch with owner latency. Named as a constant because three separate
+ * places have to treat it differently and a repeated string literal is how
+ * one of them ends up not doing so.
+ */
+export const OWNER_LATENCY_SWITCH = "credentials-and-refs";
+/**
+ * `cutover.json` sits at the FLEET ROOT and not under `state/`, because
+ * `state/` is gitignored (src/fleet.ts:29) and trigger 2 step 1 identifies a
+ * flip with `git log` over this exact path. A switch history that is not
+ * committed is not a history.
+ */
+export function cutoverStatePath(fleet) {
+    return join(fleet.root, "cutover.json");
+}
+function isSwitchState(value) {
+    return typeof value === "string" && SWITCH_STATES.includes(value);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Validate a parsed document into a CutoverState, returning every reason at
+ * once rather than the first.
+ *
+ * FAIL CLOSED ON `restoreTo`. A record missing it, or carrying it as a word
+ * outside the two-value vocabulary, is REFUSED rather than defaulted to
+ * `current`. Defaulting would make rollback silently guess, and a guess that
+ * happens to be right most of the time is the guard that cannot go red.
+ */
+export function validateCutoverDocument(document) {
+    const reasons = [];
+    if (typeof document !== "object" || document === null || Array.isArray(document)) {
+        return ["cutover state is not a JSON object"];
+    }
+    const switches = document.switches;
+    if (typeof switches !== "object" || switches === null || Array.isArray(switches)) {
+        return ["cutover state has no switches object"];
+    }
+    const table = switches;
+    for (const name of CUTOVER_SWITCHES) {
+        const record = table[name];
+        if (typeof record !== "object" || record === null || Array.isArray(record)) {
+            reasons.push(`switch ${name} is missing`);
+            continue;
+        }
+        const row = record;
+        if (!isSwitchState(row["state"])) {
+            reasons.push(`switch ${name} has no state of current or kernel`);
+        }
+        if (!isSwitchState(row["restoreTo"])) {
+            reasons.push(`switch ${name} has no restoreTo of current or kernel`);
+        }
+        for (const field of ["flippedAt", "flippedBy", "reason"]) {
+            if (!nonEmptyString(row[field])) {
+                reasons.push(`switch ${name} has no ${field}`);
+            }
+        }
+    }
+    const unknown = Object.keys(table).filter((key) => !CUTOVER_SWITCHES.includes(key));
+    for (const key of unknown) {
+        reasons.push(`switch ${key} is not one of the five`);
+    }
+    return reasons;
+}
+/** Read and validate the fleet's cutover state. */
+export function readCutoverState(fleet) {
+    const path = cutoverStatePath(fleet);
+    const read = readRegularFileIfPresent(path);
+    if (read.kind === "absent") {
+        return { kind: "absent" };
+    }
+    if (read.kind === "refused") {
+        return { kind: "refused", reason: read.reason };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.body);
+    }
+    catch (error) {
+        return { kind: "refused", reason: `${path} is not valid JSON: ${String(error)}` };
+    }
+    const reasons = validateCutoverDocument(parsed);
+    if (reasons.length > 0) {
+        return { kind: "refused", reason: `${path}: ${reasons.join("; ")}` };
+    }
+    return {
+        kind: "read",
+        state: parsed,
+        document: parsed,
+    };
+}
+export function renderCutoverState(state) {
+    return `${JSON.stringify(state, null, 2)}\n`;
+}
+/**
+ * Put a new switch table into the document the file actually held, leaving
+ * every other key exactly as it was read.
+ *
+ * WHY THIS EXISTS AS A NAMED FUNCTION. `validateCutoverDocument` refuses an
+ * unknown SWITCH NAME because the five are a closed list, and that made it
+ * look as though the whole document were closed. It is not: M4-P25 owns the
+ * schema and may add top-level keys, so a rollback that serialises only what
+ * this module's interface names would silently delete them. Refusing them
+ * instead would be this phase deciding M4-P25's schema, which is not its to
+ * decide, so the document is CARRIED rather than narrowed or refused.
+ */
+export function withSwitches(document, switches) {
+    return { ...document, switches };
+}
+/**
+ * Publish a whole cutover state ATOMICALLY: serialise everything, write it to
+ * a sibling temporary file, fsync that file, then rename over the
+ * destination. Nothing partial is ever visible at the destination path,
+ * because rename(2) within one directory is atomic.
+ *
+ * THE MECHANISM THIS EXISTS AGAINST is not "a crash". It is WRITING STATE
+ * PER ITEM WHILE ITERATING, which leaves a file that is internally valid and
+ * factually wrong: three switches saying `kernel` and two saying `current`
+ * describes a process that has no owner for three of its five authorities.
+ * Every caller in this module builds the complete next state first and calls
+ * this once.
+ */
+export function publishCutoverState(path, state) {
+    /* M4-P25 criterion 4, AND THE ORDER IS THE PROPERTY. The shipped schema
+       refuses a switch record missing `restoreTo` (or `flippedAt`, `flippedBy`
+       or `reason`) BEFORE the temporary file is opened, so a refused write
+       leaves the destination byte-identical and, where there was none, leaves
+       no file at all. The check lives in the schema rather than here because a
+       check implemented only in a command cannot bind a later writer, and the
+       later writer is exactly who M4-P26's rollback depends on: `targetFor`
+       reads the recorded value rather than reconstructing an intent. */
+    const diagnostics = cutoverSchemaDiagnostics(state);
+    if (diagnostics.length > 0) {
+        throw new Error(`the cutover state was refused by ${CUTOVER_STATE_SCHEMA_FILENAME} and NOTHING was written: ${diagnostics.join("; ")}`);
+    }
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true });
+    /* The suffix is random, never a pid. C-2 forbids a pid as an identity, and
+       a temp-file name is an identity for exactly as long as the rename takes. */
+    const temporary = join(directory, `.cutover.${randomBytes(8).toString("hex")}.tmp`);
+    const body = renderCutoverState(state);
+    let handle;
+    try {
+        handle = openSync(temporary, "wx");
+        writeSync(handle, body);
+        fsyncSync(handle);
+        closeSync(handle);
+        handle = undefined;
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        if (handle !== undefined) {
+            try {
+                closeSync(handle);
+            }
+            catch {
+                /* the write already failed; the close outcome adds nothing */
+            }
+        }
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            /* best effort: a leftover temp file is not the destination */
+        }
+        throw error;
+    }
+}
+export const ROLLBACK_TRIGGERS = [
+    "drain-reversal",
+    "freeze-point-restore",
+    "retirement-unmet",
+];
+/**
+ * The target value a trigger moves a switch to.
+ *
+ * Trigger 1 (drain reversal) hands every authority back to the current
+ * process, so the target is `current` for all five: in-flight work has to be
+ * handled by the process that started it.
+ *
+ * Trigger 2 (freeze-point restore) reads each switch's own `restoreTo`. That
+ * is the difference between the two, and it is why M4-P25 criterion 4 refuses
+ * a write that omits the field.
+ *
+ * ROLLBACK IS MONOTONE AND THE CLAMP BELOW IS WHAT MAKES THE MODULE HEADER
+ * TRUE. `restoreTo` is the value a switch held BEFORE its last flip, and
+ * `planRollback` sets it to the value the switch is leaving. So a switch that
+ * has already been rolled back to `current` carries `restoreTo: "kernel"`, and
+ * returning that value would move the switch FORWARD on the second run of the
+ * same command. The failure arm of trigger 1 step 1 exits nonzero after the
+ * local write has already happened, and the natural response to that is to run
+ * the command again, so the second run is not a hypothetical. A rollback never
+ * hands authority to the kernel: `current` is a floor, and a switch already at
+ * it is a no-op rather than a flip.
+ */
+export function targetFor(trigger, record) {
+    if (trigger === "drain-reversal") {
+        return "current";
+    }
+    if (record.state === "current") {
+        return "current";
+    }
+    return record.restoreTo;
+}
+/**
+ * Assemble the complete next state. Throws rather than returning a partial
+ * plan, and touches no file at all: publishing is a separate call.
+ */
+export function planRollback(state, trigger, options) {
+    const changes = [];
+    const nextSwitches = {};
+    let index = 0;
+    for (const name of CUTOVER_SWITCHES) {
+        const record = state.switches[name];
+        const to = targetFor(trigger, record);
+        const change = { name, from: record.state, to };
+        options.onSwitch?.(change, index);
+        if (change.from === change.to) {
+            /* A SWITCH THIS ROLLBACK DOES NOT MOVE IS NOT REWRITTEN. The record is
+               carried through unchanged, `flippedAt`, `flippedBy`, `reason` and
+               `restoreTo` included. Stamping the current run over an unmoved switch
+               would destroy the one fact freeze-point restore depends on, which is
+               what that switch left, and it would do it while reporting zero
+               changes: a write whose scope is wider than the sentence describing
+               it. */
+            nextSwitches[name] = record;
+        }
+        else {
+            nextSwitches[name] = {
+                /* Spread the record as it was READ. The interface names five fields;
+                   the file may carry more, and a rollback that rebuilds the record
+                   from the interface deletes whatever it did not know about. */
+                ...record,
+                state: to,
+                flippedAt: options.now,
+                flippedBy: options.by,
+                reason: options.reason,
+                /* The rolled-back switch can be flipped forward again, and the value
+                   it would return to is the one it is leaving now. Carrying the OLD
+                   restoreTo forward would make a second rollback restore a state two
+                   flips old. */
+                restoreTo: record.state,
+            };
+            changes.push(change);
+        }
+        index += 1;
+    }
+    return { changes, next: { switches: nextSwitches } };
+}
+/**
+ * Plan and publish in one call: validate the whole input, assemble the whole
+ * next state, then write once.
+ *
+ * ORDER IS THE PROPERTY. Every refusal reachable from a bad input happens
+ * before `publishCutoverState` is called, so a refusal leaves the file
+ * byte-identical. That is asserted directly rather than trusted: see
+ * test/cutover.test.ts.
+ */
+export function applyRollback(fleet, trigger, options) {
+    const read = readCutoverState(fleet);
+    if (read.kind === "absent") {
+        return { ok: false, reason: `${cutoverStatePath(fleet)} is absent` };
+    }
+    if (read.kind === "refused") {
+        return { ok: false, reason: read.reason };
+    }
+    let plan;
+    try {
+        plan = planRollback(read.state, trigger, options);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `rollback assembly failed before any write: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    try {
+        /* Publish the DOCUMENT with the new switch table in it, not the typed
+           view. `read.document` is what the file held; `plan.next.switches` is the
+           only part this rollback decided. Publishing `plan.next` alone would
+           delete every top-level key this module does not name. */
+        publishCutoverState(cutoverStatePath(fleet), withSwitches(read.document, plan.next.switches));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `rollback could not be published: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return { ok: true, changes: plan.changes, next: plan.next };
+}
+/**
+ * WHAT DRAIN COUNTS, and the omission is the decision.
+ *
+ * In-flight work only: live worktrees and open tasks with no turn-end. Pushed
+ * unmerged BRANCHES are deliberately NOT counted (M4-D-15, decided at
+ * delivery/plan/kernel-plan-m4.md:3279). This container cannot delete a remote
+ * ref and the delete dry run exits 0 either way, and the probes generalised
+ * that further: a dry run does not probe push authorization at all
+ * (delivery/verification/m4-prototype-probes.md:165). A drain predicate over
+ * branches therefore blocks cutover on an owner action with no local
+ * pre-check, which is a predicate that can never read clean.
+ *
+ * C-2 is load-bearing here. A live worktree is a DIRECTORY on disk and an
+ * open task is meta.json's status plus the absence of the turn-end file. No
+ * process is probed, no pid is read, and nothing asks whether an agent is
+ * still breathing.
+ */
+export function inFlightItems(fleet) {
+    const items = [];
+    /* ABSENT IS UNDECIDABLE HERE AND NOT EMPTY. `loadFleet` refuses a fleet
+       whose `worktrees/` or `tasks/` is not a directory (src/fleet.ts:65), so a
+       Fleet value that reaches this function had both when it was loaded. One
+       that is gone now was removed since, which says nothing about what was in
+       it, and reading that as a clean drain is the same fall-through as reading
+       an unreadable directory as an empty one. */
+    const worktrees = listDirectory(fleet.worktreesDir);
+    if (worktrees.kind !== "listed") {
+        items.push({
+            kind: "unexaminable",
+            id: fleet.worktreesDir,
+            detail: worktrees.kind === "absent"
+                ? `${fleet.worktreesDir} is gone, and the fleet had it when it was loaded`
+                : worktrees.reason,
+        });
+    }
+    for (const id of worktrees.kind === "listed" ? worktrees.names : []) {
+        const path = join(fleet.worktreesDir, id);
+        const probe = probeDirectory(path);
+        if (probe.kind === "directory") {
+            items.push({ kind: "worktree", id, detail: path });
+        }
+        else if (probe.kind === "unexaminable") {
+            items.push({ kind: "unexaminable", id, detail: probe.reason });
+        }
+    }
+    const tasks = listDirectory(fleet.tasksDir);
+    if (tasks.kind !== "listed") {
+        items.push({
+            kind: "unexaminable",
+            id: fleet.tasksDir,
+            detail: tasks.kind === "absent"
+                ? `${fleet.tasksDir} is gone, and the fleet had it when it was loaded`
+                : tasks.reason,
+        });
+    }
+    for (const id of tasks.kind === "listed" ? tasks.names : []) {
+        /* A TASK IS A DIRECTORY under tasks/, checked by TYPE and never by name,
+           which is the rule src/liveness.ts states for every task reader. This
+           loop was the one reader that skipped it, so `tiphys init`'s own
+           `tasks/.gitkeep` read as one task in flight and a freshly initialised
+           fleet could never report DRAIN clean. Resolved with stat, as the
+           worktree loop above does, so a symlink to a task directory is a task. */
+        const entry = probeDirectory(join(fleet.tasksDir, id));
+        if (entry.kind === "absent" || entry.kind === "other") {
+            continue;
+        }
+        if (entry.kind === "unexaminable") {
+            items.push({ kind: "unexaminable", id, detail: entry.reason });
+            continue;
+        }
+        const metaRead = readRegularFileIfPresent(join(fleet.tasksDir, id, "meta.json"));
+        if (metaRead.kind === "refused") {
+            /* Present and not readable. A meta.json that is a named pipe, a
+               directory, or a path this process may not stat says NOTHING about
+               whether the task finished, and the T-003 hazard shape is exactly a
+               FIFO where a regular file was expected. */
+            items.push({ kind: "task", id, detail: `meta.json could not be examined: ${metaRead.reason}` });
+            continue;
+        }
+        if (metaRead.kind === "absent") {
+            items.push({ kind: "task", id, detail: "meta.json is absent, so the task has no recorded status" });
+            continue;
+        }
+        let status;
+        try {
+            status = JSON.parse(metaRead.body).status;
+        }
+        catch {
+            /* An unparseable meta.json is not evidence that the task finished, so
+               it counts as in flight rather than being skipped. */
+            items.push({ kind: "task", id, detail: "meta.json is unparseable" });
+            continue;
+        }
+        /* `closed` is the ONLY positive evidence that a task is finished. The
+           previous form tested `status !== "open"`, which made every value that is
+           not the word `open` - a missing field, a typo, a number - read as
+           finished. The vocabulary is closed (src/task.ts, TaskStatus), so a value
+           outside it is undecided and undecided counts. */
+        if (status === "closed") {
+            continue;
+        }
+        if (status !== "open") {
+            items.push({
+                kind: "task",
+                id,
+                detail: `meta.json status ${JSON.stringify(status)} is not one of open or closed`,
+            });
+            continue;
+        }
+        const turnEnd = classifyEntry(turnEndPath(fleet, id));
+        /* Symmetrically: a REGULAR turn-end file is the only positive evidence
+           that the turn ended. `irregular` and `unexaminable` are undecided, not
+           finished, and the previous form counted only `absent` and `dangling`,
+           so a turn-end that was a named pipe read as a finished task. */
+        if (turnEnd.kind === "regular") {
+            continue;
+        }
+        items.push({
+            kind: "task",
+            id,
+            detail: turnEnd.kind === "absent" || turnEnd.kind === "dangling"
+                ? "open with no turn-end"
+                : `open and the turn-end could not be examined: ${turnEnd.reason}`,
+        });
+    }
+    return items.sort((a, b) => `${a.kind}/${a.id}`.localeCompare(`${b.kind}/${b.id}`));
+}
+function probeDirectory(path) {
+    let stats;
+    try {
+        stats = statSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { kind: "absent" };
+        }
+        return { kind: "unexaminable", reason: `${path} could not be examined: ${String(error)}` };
+    }
+    return stats.isDirectory() ? { kind: "directory" } : { kind: "other" };
+}
+/**
+ * Enumerate a directory, distinguishing "it is not there" from "it could not
+ * be enumerated". An empty list and a failed listing are the same value to a
+ * caller that returns `[]` for both, and in this module the caller is the
+ * drain predicate: a `tasks/` that cannot be read would have reported a clean
+ * drain over an unknown number of open tasks.
+ */
+function listDirectory(path) {
+    const probe = probeDirectory(path);
+    if (probe.kind === "absent") {
+        return { kind: "absent" };
+    }
+    if (probe.kind === "unexaminable") {
+        return { kind: "unexaminable", reason: probe.reason };
+    }
+    if (probe.kind === "other") {
+        return {
+            kind: "unexaminable",
+            reason: `${path} is not a directory, so its contents could not be enumerated`,
+        };
+    }
+    try {
+        return { kind: "listed", names: readdirSync(path).sort() };
+    }
+    catch (error) {
+        return { kind: "unexaminable", reason: `${path} could not be enumerated: ${String(error)}` };
+    }
+}
+/**
+ * The named list of things no local command can see. It is printed with every
+ * drain report and is NOT abbreviated when the network is unreachable: a
+ * command that silently degrades to a shorter answer is indistinguishable
+ * from one reporting a quiet system, which is the shape standing warning 6
+ * records for watchers.
+ */
+export const CANNOT_SEE = [
+    "open pull requests",
+    "CI conclusions",
+    "post-merge push runs",
+    "whether the pilot's own fleet is drained (DR-0037: the pilot is not this orchestrator's subject)",
+];
+export function runGit(cwd, args) {
+    const result = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        env: {
+            ...process.env,
+            GIT_AUTHOR_NAME: "tiphys",
+            GIT_AUTHOR_EMAIL: "tiphys@localhost",
+            GIT_COMMITTER_NAME: "tiphys",
+            GIT_COMMITTER_EMAIL: "tiphys@localhost",
+            GIT_TERMINAL_PROMPT: "0",
+        },
+    });
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? (result.error === undefined ? "" : String(result.error)),
+    };
+}
+function nonEmptyLines(text) {
+    return text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+export function syncFleetState(fleetRoot, options) {
+    if (options.paths.length === 0) {
+        return {
+            ok: false,
+            reason: "syncFleetState was given no path to stage, and a rollback that stages everything commits work it did not do",
+        };
+    }
+    const remotes = runGit(fleetRoot, ["remote"]);
+    if (remotes.status !== 0) {
+        return { ok: false, reason: `git remote failed in ${fleetRoot}: ${remotes.stderr.trim()}` };
+    }
+    const hasOrigin = remotes.stdout.split("\n").some((line) => line.trim() === "origin");
+    /* An index that already holds something is refused rather than absorbed: a
+       scoped staging does not unstage what somebody else staged, so committing
+       here would carry it under this message. */
+    const preStaged = runGit(fleetRoot, ["diff", "--cached", "--name-only"]);
+    if (preStaged.status !== 0) {
+        return { ok: false, reason: `git diff --cached failed: ${preStaged.stderr.trim()}` };
+    }
+    const already = nonEmptyLines(preStaged.stdout);
+    if (already.length > 0) {
+        return {
+            ok: false,
+            reason: `${fleetRoot} already holds ${String(already.length)} staged path(s) this rollback did not stage, ` +
+                `and nothing was committed: ${already.slice(0, 10).join(", ")}`,
+        };
+    }
+    const add = runGit(fleetRoot, ["add", "--", ...options.paths]);
+    if (add.status !== 0) {
+        return { ok: false, reason: `git add failed in ${fleetRoot}: ${add.stderr.trim()}` };
+    }
+    const staged = runGit(fleetRoot, ["diff", "--cached", "--name-only"]);
+    if (staged.status !== 0) {
+        return { ok: false, reason: `git diff --cached failed: ${staged.stderr.trim()}` };
+    }
+    const stagedPaths = nonEmptyLines(staged.stdout);
+    /* The scope is VERIFIED and not assumed. A named path that turns out to be a
+       directory, or a pathspec the caller did not mean, shows up here. */
+    const stray = stagedPaths.filter((path) => !options.paths.some((want) => path === want || path.startsWith(`${want}/`)));
+    if (stray.length > 0) {
+        return {
+            ok: false,
+            reason: `staging ${options.paths.join(", ")} also staged ${String(stray.length)} path(s) outside it, ` +
+                `and nothing was committed: ${stray.slice(0, 10).join(", ")}`,
+        };
+    }
+    if (stagedPaths.length > 0) {
+        const commit = runGit(fleetRoot, ["commit", "-q", "-m", options.message]);
+        if (commit.status !== 0) {
+            return { ok: false, reason: `git commit failed: ${commit.stderr.trim()}` };
+        }
+    }
+    if (!hasOrigin) {
+        const reason = `${fleetRoot} has no origin remote, so the rollback is committed locally and NOT published`;
+        return options.allowNoRemote === true
+            ? { ok: true, pushed: false, reason, staged: stagedPaths }
+            : { ok: false, reason };
+    }
+    const push = runGit(fleetRoot, ["push", "origin", "HEAD"]);
+    if (push.status !== 0) {
+        return {
+            ok: false,
+            reason: `git push failed: ${(push.stderr + push.stdout).trim().split("\n").join(" ")}`,
+        };
+    }
+    const head = runGit(fleetRoot, ["rev-parse", "HEAD"]);
+    if (head.status !== 0) {
+        return { ok: false, reason: `git rev-parse HEAD failed: ${head.stderr.trim()}` };
+    }
+    return { ok: true, pushed: true, head: head.stdout.trim(), staged: stagedPaths };
+}
+/* -------------------------------------------------------------------- */
+/* Trigger 2 step 2: restoring the FILES                                 */
+/* -------------------------------------------------------------------- */
+/**
+ * Refuse to touch a tree that holds uncommitted work.
+ *
+ * ANY `git checkout --` in such a tree is destructive, INCLUDING when it names
+ * a single path, and especially the path being edited. This repository has
+ * paid for that twice; the rule is standing warning 8 in the agent-rules file.
+ * The guard is a precondition of the restore and not a warning printed beside
+ * it, because a warning is advice and this is the only thing standing between
+ * a rollback and four rounds of somebody's uncommitted work.
+ */
+export function refuseIfTreeDirty(repoRoot) {
+    const status = runGit(repoRoot, ["status", "--porcelain"]);
+    if (status.status !== 0) {
+        return { ok: false, reason: `git status failed in ${repoRoot}: ${status.stderr.trim()}` };
+    }
+    const dirty = status.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (dirty.length > 0) {
+        return {
+            ok: false,
+            reason: `${repoRoot} holds ${dirty.length} uncommitted change(s) and nothing was touched: ` +
+                dirty.slice(0, 10).join(", "),
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Restore the named retirement roots from a pre-freeze sha.
+ *
+ * The dirty check runs FIRST and returns before any version-control
+ * invocation that can write. That order is the whole guarantee, and the test
+ * asserts the dirty file is byte-identical afterwards rather than asserting
+ * the exit code alone.
+ *
+ * "RESTORE" IS A CLAIM ABOUT THE WHOLE ROOT, AND CHECKING A TREE OUT OVER A
+ * PATH IS NOT ONE. `checkout <sha> -- <root>` writes what the sha held and
+ * removes NOTHING, so every file added under the root after the freeze
+ * survives the restore untouched. The result is a hybrid tree that the caller
+ * prints `RESTORED` over: a verdict wider than the operation that produced it.
+ * The post-freeze additions are therefore enumerated and removed, and then the
+ * root is COMPARED with the sha. The comparison is the verdict; without it the
+ * success arm is an assumption, and a success arm that cannot fail is the
+ * guard that cannot go red.
+ */
+export function restoreRetirementRoots(repoRoot, sha, roots) {
+    if (roots.length === 0) {
+        return { ok: false, reason: "no retirement root was named" };
+    }
+    const guard = refuseIfTreeDirty(repoRoot);
+    if (!guard.ok) {
+        return { ok: false, reason: guard.reason };
+    }
+    const resolved = runGit(repoRoot, ["rev-parse", "--verify", `${sha}^{commit}`]);
+    if (resolved.status !== 0) {
+        return { ok: false, reason: `${sha} does not resolve to a commit in ${repoRoot}` };
+    }
+    /* Tracked under a root NOW and absent at the freeze. The tree is clean here,
+       because refuseIfTreeDirty has already returned, so HEAD is the tree. */
+    const added = runGit(repoRoot, [
+        "diff",
+        "--name-only",
+        "--diff-filter=A",
+        /* --no-renames IS LOAD-BEARING AND THE VERIFICATION ARM BELOW IS WHAT
+           FOUND IT. With rename detection on, a file renamed after the freeze is
+           reported as R rather than A, so its NEW name is not enumerated, the
+           removal misses it, and the checkout restores the old name beside it. The
+           first version of this function had the flag missing; the residue
+           comparison turned the hybrid tree into a refusal naming
+           `retired/renamed.md` instead of a green. That is the whole reason the
+           verdict is measured rather than assumed. */
+        "--no-renames",
+        sha,
+        "HEAD",
+        "--",
+        ...roots,
+    ]);
+    if (added.status !== 0) {
+        return {
+            ok: false,
+            reason: `enumerating the post-freeze additions failed: ${added.stderr.trim()}`,
+        };
+    }
+    const postFreeze = nonEmptyLines(added.stdout);
+    const checkout = runGit(repoRoot, ["checkout", sha, "--", ...roots]);
+    if (checkout.status !== 0) {
+        return { ok: false, reason: `git checkout failed: ${checkout.stderr.trim()}` };
+    }
+    if (postFreeze.length > 0) {
+        const removed = runGit(repoRoot, ["rm", "-q", "-f", "--", ...postFreeze]);
+        if (removed.status !== 0) {
+            return {
+                ok: false,
+                reason: `removing the post-freeze additions failed: ${removed.stderr.trim()}`,
+            };
+        }
+    }
+    /* THE VERDICT IS MEASURED. Compare the sha with the working tree over the
+       same roots; anything printed here is a difference the restore did not
+       close, and the caller is told rather than shown a success. */
+    const residue = runGit(repoRoot, ["diff", "--name-only", sha, "--", ...roots]);
+    if (residue.status !== 0) {
+        return {
+            ok: false,
+            reason: `verifying the restore against ${sha} failed: ${residue.stderr.trim()}`,
+        };
+    }
+    const differing = nonEmptyLines(residue.stdout);
+    if (differing.length > 0) {
+        return {
+            ok: false,
+            reason: `${String(differing.length)} path(s) under the retirement roots still differ from ${sha} ` +
+                `after the restore, so nothing is reported as restored: ${differing.slice(0, 10).join(", ")}`,
+        };
+    }
+    return { ok: true, roots, removed: postFreeze };
+}
+/* -------------------------------------------------------------------- */
+/* Trigger 2 step 3: the owner request that cannot be rehearsed          */
+/* -------------------------------------------------------------------- */
+/**
+ * The property that makes trigger 2 step 3 unrehearsable, in one sentence,
+ * exported so the document, the command and the rehearsal script all print
+ * the SAME sentence and cannot drift apart.
+ */
+export const UNREHEARSABLE_REASON = "the branch-protection ruleset is a single live object on one owner-owned " +
+    "repository: there is no second instance to rehearse against, and no dry " +
+    "run distinguishes allowed from refused";
+/**
+ * Flatten the captured ruleset into the fields the owner request must carry.
+ * The shape is fixed here rather than schema-loaded because M4-P25 owns the
+ * schema; what this phase needs is the COMPLETENESS check over whatever that
+ * capture holds.
+ */
+const REQUIRED_TOP_LEVEL = [
+    "capturedAt",
+    "repository",
+    "rulesetName",
+    "rules",
+    "credentialGrants",
+];
+function isEmptyValue(value) {
+    if (value === undefined || value === null) {
+        return true;
+    }
+    if (typeof value === "string") {
+        return value.trim().length === 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+    if (typeof value === "object") {
+        return Object.keys(value).length === 0;
+    }
+    return false;
+}
+/**
+ * Generate the owner request for trigger 2 step 3.
+ *
+ * TWO STRUCTURALLY DIFFERENT REFUSALS, and the second is the one a field
+ * check is green on. An ABSENT key is caught by asking whether the key is
+ * there. A key that is PRESENT and EMPTY passes that question and produces a
+ * request with a blank where a pre-flip value belongs, which the owner would
+ * have to fill in from memory. Both are refused, and the refusal names the
+ * field, because an owner request with a hole in it is worse than no request:
+ * it looks complete.
+ */
+export function generateRestoreRequest(document) {
+    if (typeof document !== "object" || document === null || Array.isArray(document)) {
+        return { ok: false, reasons: ["pre-freeze ruleset is not a JSON object"] };
+    }
+    const capture = document;
+    const reasons = [];
+    for (const key of REQUIRED_TOP_LEVEL) {
+        if (!(key in capture)) {
+            reasons.push(`field ${key} is absent from the captured ruleset`);
+            continue;
+        }
+        if (isEmptyValue(capture[key])) {
+            reasons.push(`field ${key} is present but empty, so it carries no pre-flip value`);
+        }
+    }
+    const fields = [];
+    for (const [listName, idKey] of [
+        ["rules", "id"],
+        ["credentialGrants", "name"],
+    ]) {
+        const list = capture[listName];
+        if (!Array.isArray(list)) {
+            /* PRESENT, NON-EMPTY AND NOT A LIST. The top-level loop above asks only
+               whether the key is there and whether it is empty, and a string such as
+               "see the wiki" passes both. Falling through here would generate an
+               owner request carrying zero fields from that key while reporting
+               success, which is the present-but-useless arm criterion 6 member B
+               exists for, one level up from a single field. Absence is already
+               reported above, so only presence is reported here. */
+            if (listName in capture) {
+                reasons.push(`field ${listName} is present but is not a list, so no pre-flip value could be read from it`);
+            }
+            continue;
+        }
+        list.forEach((row, index) => {
+            if (typeof row !== "object" || row === null || Array.isArray(row)) {
+                reasons.push(`${listName}[${index}] is not an object`);
+                return;
+            }
+            const entry = row;
+            const label = nonEmptyString(entry[idKey]) ? entry[idKey] : `[${index}]`;
+            if (!nonEmptyString(entry[idKey])) {
+                reasons.push(`${listName}[${index}] has no ${idKey}`);
+            }
+            if (!("preFlipValue" in entry)) {
+                reasons.push(`${listName}.${label} has no preFlipValue`);
+                return;
+            }
+            if (isEmptyValue(entry["preFlipValue"])) {
+                reasons.push(`${listName}.${label} has a preFlipValue that is present but empty`);
+                return;
+            }
+            fields.push({ path: `${listName}.${label}`, value: entry["preFlipValue"] });
+        });
+    }
+    if (reasons.length > 0) {
+        return { ok: false, reasons };
+    }
+    const lines = [];
+    lines.push("OWNER ACTION: restore the pre-freeze branch protection and credential grants");
+    lines.push("");
+    lines.push(`repository: ${String(capture["repository"])}`);
+    lines.push(`ruleset: ${String(capture["rulesetName"])}`);
+    lines.push(`captured at: ${String(capture["capturedAt"])}`);
+    lines.push("");
+    lines.push("Restore each field below to its pre-flip value:");
+    for (const field of fields) {
+        lines.push(`  ${field.path} = ${JSON.stringify(field.value)}`);
+    }
+    lines.push("");
+    lines.push("THIS STEP CANNOT BE REHEARSED. " + UNREHEARSABLE_REASON + ".");
+    lines.push("A green rehearsal of this request says the REQUEST is complete. It says " +
+        "nothing about whether the change will be accepted.");
+    lines.push("");
+    lines.push("Request an A-n id from delivery/STATE.md, which is the sole allocator, " +
+        "and record this action there before sending it.");
+    return { ok: true, text: `${lines.join("\n")}\n`, fields: fields.length };
+}
+/**
+ * Decide one PORT row.
+ *
+ * `ported` needs BOTH halves and the second is the one that matters. A verdict
+ * derived only from the destination file existing is the vacuous version: a
+ * file can exist and say nothing. The negative witness was RED under the old
+ * rule, so a witness that exits 0 under the new artifact means the new
+ * artifact does not catch what the old one caught, which is precisely
+ * "WEAKER". Exit 0 from the witness is therefore `unported`, not a pass.
+ *
+ * `ported` IS REACHED FROM A POSITIVE TEST AND NEVER FROM A FALLTHROUGH, and
+ * that is what the first three checks below are. `readRetirementInventory`
+ * casts whatever the fixture's `rows` array holds, so a row may be a string, a
+ * number, or an object whose `disposition` is misspelt; the earlier form asked
+ * only whether the disposition was NOT the word `PORT`, so every one of those
+ * returned `ported`, which is a verdict of "this retirement is complete" over
+ * a row nobody could read. The vocabulary is closed, so a value outside it is
+ * `unported` and names itself.
+ */
+export const DISPOSITIONS = ["PORT", "DELETE", "KEEP"];
+function isDisposition(value) {
+    return typeof value === "string" && DISPOSITIONS.includes(value);
+}
+export function evaluatePortRow(row, repoRoot) {
+    if (typeof row !== "object" || row === null || Array.isArray(row)) {
+        return {
+            id: `(row ${JSON.stringify(row)})`,
+            verdict: "unported",
+            reason: "inventory row is not an object, so its disposition could not be read",
+        };
+    }
+    const id = nonEmptyString(row.id) ? row.id : "(row with no id)";
+    if (!nonEmptyString(row.id)) {
+        return { id, verdict: "unported", reason: "inventory row has no id" };
+    }
+    if (!isDisposition(row.disposition)) {
+        return {
+            id,
+            verdict: "unported",
+            reason: `disposition ${JSON.stringify(row.disposition)} is not one of ${DISPOSITIONS.join(", ")}`,
+        };
+    }
+    if (row.disposition !== "PORT") {
+        return { id, verdict: "ported", reason: `disposition ${row.disposition} needs no port` };
+    }
+    if (!nonEmptyString(row.destination)) {
+        return { id, verdict: "unported", reason: "PORT row names no destination" };
+    }
+    /* A DESTINATION MAY NAME MORE THAN ONE ARTIFACT, and that is the inventory's
+       own declared convention rather than a reading invented here: its checker
+       splits the field on commas at scripts/check-retirement-inventory.mjs:754.
+       Measured 2026-09-18 against the shipped inventory: three rows
+       (`next-script:gittry`, `next-script:gitcount`, `next-script:harderrors`)
+       carry `roles/investigator.md, checklists/clean-room.yaml`, and treating
+       the field as ONE path reported all three as `unported` with a reason about
+       a file that does not exist. That is a false finding about the kernel
+       produced by a disagreement about a separator, so EVERY named path must
+       exist and the first that does not is the one named. Splitting a
+       single-path field yields that one path, so nothing else changes. */
+    const destinations = row.destination.split(/\s*,\s*/).filter((part) => part.length > 0);
+    for (const part of destinations) {
+        if (classifyEntry(join(repoRoot, part)).kind !== "regular") {
+            return {
+                id,
+                verdict: "unported",
+                reason: `destination ${part} does not exist as a file`,
+            };
+        }
+    }
+    /* THE COMMAND'S TYPE IS ESTABLISHED BEFORE IT IS DESTRUCTURED OR SPAWNED,
+       and `destination` one line up is why this line looks the way it does: that
+       field is tested with `nonEmptyString`, this one was tested with `.length`,
+       and `.length` is a property read off a value nobody typed. `42` and `{}`
+       are not iterable, so the destructuring below threw
+       `TypeError: ... is not iterable` out of a function whose interface is a
+       PortResult; `null` threw on `.length` before reaching it; and an ARRAY
+       holding a non-string threw inside spawnSync on the "file" argument. Four
+       throws where a verdict was owed. An inventory row is data supplied by
+       another phase's file, so its fields are unknown in the same way a parsed
+       document's are, and a throw carries no reason for the refusal. */
+    if (!Array.isArray(row.negativeWitness) || row.negativeWitness.length === 0) {
+        return {
+            id,
+            verdict: "unported",
+            reason: "PORT row carries no negative-witness command",
+        };
+    }
+    if (!row.negativeWitness.every((part) => nonEmptyString(part))) {
+        return {
+            id,
+            verdict: "unported",
+            reason: "PORT row's negative-witness command is not a list of non-empty strings, so it could not be run",
+        };
+    }
+    const [program, ...args] = row.negativeWitness;
+    const run = spawnSync(program, args, { cwd: repoRoot, encoding: "utf8" });
+    if (run.error !== undefined) {
+        return {
+            id,
+            verdict: "unported",
+            reason: `negative witness could not be run: ${String(run.error)}`,
+        };
+    }
+    /* A WITNESS THAT DIED IS NOT A WITNESS THAT WAS RED. `status` is null when a
+       child is killed by a signal, and null is not 0, so the nonzero arm at the
+       bottom used to accept it and report the row as ported. A witness killed by
+       the out-of-memory killer or by a harness timeout has demonstrated nothing
+       about the new artifact. */
+    if (run.signal !== null && run.signal !== undefined) {
+        return {
+            id,
+            verdict: "unported",
+            reason: `negative witness was killed by ${run.signal}, which is not evidence that it is red under the new artifact`,
+        };
+    }
+    if (run.status === null) {
+        return {
+            id,
+            verdict: "unported",
+            reason: "negative witness reported no exit status, so it did not demonstrate anything",
+        };
+    }
+    if (run.status === 0) {
+        return {
+            id,
+            verdict: "unported",
+            reason: "negative witness exits 0 under the new artifact, so the destination is WEAKER than the rule it replaced",
+        };
+    }
+    /* A NONZERO EXIT IS NOT THE SAME THING AS A RED WITNESS, and this is the
+       vacuous red one level below the vacuous green above. `grep` exits 1 when
+       it searched and found nothing, which is the answer that makes the row's
+       claim stand, and 2 when it could not search at all: a missing subject
+       file, an unreadable directory, a bad pattern. Accepting any nonzero
+       status reports a row as PORTED on the strength of an error message, which
+       is a guard that fails open when its own tool fails. The row's own
+       `negative-witness.exit` is what it recorded when it was written, so when
+       the row declares one it is REQUIRED to match. Same rule, same reason, as
+       scripts/check-retirement-inventory.mjs:628 applies to its widening grep.
+       Measured 2026-09-18 over the shipped inventory: all 199 PORT rows record
+       exit 1 and all 199 observed exit 1, so this changes no verdict today and
+       is a guard against the day one of them starts erroring instead. */
+    if (row.expectedWitnessExit !== undefined && run.status !== row.expectedWitnessExit) {
+        return {
+            id,
+            verdict: "unported",
+            reason: `negative witness exits ${String(run.status)} under the new artifact but the row recorded ${String(row.expectedWitnessExit)}, so it did not search and find nothing, it failed`,
+        };
+    }
+    return {
+        id,
+        verdict: "ported",
+        reason: `negative witness exits ${String(run.status)} under the new artifact`,
+    };
+}
+/**
+ * Read an M4-P23 retirement inventory. The path is a parameter because that
+ * phase runs concurrently with this one and its file does not exist on this
+ * branch; the rehearsal supplies a fixture.
+ */
+export function readRetirementInventory(path) {
+    const read = readRegularFileIfPresent(path);
+    if (read.kind === "absent") {
+        return { kind: "absent" };
+    }
+    if (read.kind === "refused") {
+        return { kind: "refused", reason: read.reason };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.body);
+    }
+    catch (error) {
+        return { kind: "refused", reason: `${path} is not valid JSON: ${String(error)}` };
+    }
+    /* THE TYPE IS ESTABLISHED BEFORE A PROPERTY IS READ OFF IT, and this line is
+       why. `JSON.parse("null")` succeeds and returns null, so the cast-and-read
+       that used to stand here threw a TypeError out of a function whose whole
+       interface is a three-way refusal. A read function that throws has no
+       refusal REASON, so the caller cannot report what was wrong with the file,
+       and the crash is indistinguishable from a defect in the reader. The
+       sibling readers both test the type first (validateCutoverDocument at
+       src/cutover.ts:154 and generateRestoreRequest at src/cutover.ts:1025);
+       this one did not, and the not-covered statement's claim that a malformed
+       inventory is refused was false for exactly that member. */
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { kind: "refused", reason: `${path} is not a JSON object` };
+    }
+    const rows = parsed.rows;
+    if (!Array.isArray(rows)) {
+        return { kind: "refused", reason: `${path} has no rows array` };
+    }
+    return { kind: "read", rows: rows };
+}
+/* -------------------------------------------------------------------- */
+/* M4-P25: the shipped state schema                                      */
+/* -------------------------------------------------------------------- */
+/** The shipped schema document's basename, in the package's `schemas/`. */
+export const CUTOVER_STATE_SCHEMA_FILENAME = "cutover-state.schema.json";
+/**
+ * Absolute path of the shipped cutover-state schema.
+ *
+ * `packageRoot()` walks UP and TESTS rather than counting `..`, because the
+ * depth differs between running from `src/` and running from `dist/src/`
+ * (src/modes.ts:39 states the same reason for the same walk).
+ */
+export function cutoverStateSchemaPath() {
+    return join(packageRoot(), "schemas", CUTOVER_STATE_SCHEMA_FILENAME);
+}
+let cachedCutoverSchema;
+/** The shipped schema document, read once. */
+export function cutoverStateSchema() {
+    if (cachedCutoverSchema === undefined) {
+        const path = cutoverStateSchemaPath();
+        const read = readRegularFileIfPresent(path);
+        if (read.kind !== "read") {
+            throw new Error(read.kind === "absent"
+                ? `${path} is missing from this installation`
+                : read.reason);
+        }
+        cachedCutoverSchema = JSON.parse(read.body);
+    }
+    return cachedCutoverSchema;
+}
+/**
+ * Validate a whole cutover document against the SHIPPED SCHEMA.
+ *
+ * WHY THIS IS NOT `validateCutoverDocument`, and the two are kept apart on
+ * purpose. That function is this module's READ guard and answers "can this
+ * file be interpreted". This one is the WRITE guard and answers "is this
+ * document one the package is prepared to ship", and criterion 4 says the
+ * required-field rule is validated BY THE SCHEMA rather than by a command.
+ * A check implemented only in a command is one the schema cannot enforce for
+ * a later writer, and a later writer is precisely who rollback depends on:
+ * M4-P26's `targetFor` READS the recorded `restoreTo` (src/cutover.ts:352)
+ * rather than remembering an intent, so a record written without one is a
+ * switch that can never be rolled back.
+ */
+export function cutoverSchemaDiagnostics(document) {
+    return validateToLines(cutoverStateSchema(), document);
+}
+/* -------------------------------------------------------------------- */
+/* M4-P25 criterion 5: the pre-freeze precondition                       */
+/* -------------------------------------------------------------------- */
+/**
+ * The captured pre-freeze state, relative to the REPOSITORY root. It carries
+ * the branch-protection ruleset as it was before the first flip, so the
+ * restore request M4-P26 generates has an input rather than a memory. T-025
+ * is why: the one step that cannot be rehearsed is the one that failed, and
+ * its INPUT can be captured in advance even when its EXECUTION cannot.
+ */
+export const PRE_FREEZE_RULESET_PATH = "delivery/plan/cutover/pre-freeze-ruleset.json";
+/**
+ * THE CAPTURE TIME IS READ FROM THE DOCUMENT, NOT FROM ITS MTIME, and that is
+ * a correction rather than a preference.
+ *
+ * The criterion says the capture must not be OLDER than the most recent switch
+ * write. An mtime does not survive the journey: `git clone` and `git checkout`
+ * set every working-tree mtime to the moment of the checkout, so a capture
+ * taken weeks before a flip reads as newer than the flip on any fresh clone,
+ * and the guard reports satisfied on exactly the machine a reviewer uses.
+ * Measured, and the measurement is in the work history. So the document
+ * records `captured-at` and the comparison is content to content.
+ *
+ * FAIL CLOSED ON AN UNREADABLE CAPTURE. A document with no `captured-at`, or
+ * one that does not parse as an instant, is `unreadable` and refuses. Treating
+ * it as satisfied would make a malformed capture indistinguishable from a good
+ * one, which is the guard that cannot go red.
+ */
+export function preFreezeGuard(repoRoot, state) {
+    const frozen = CUTOVER_SWITCHES.filter((name) => state.switches[name].state === "kernel");
+    if (frozen.length === 0) {
+        return { kind: "not-required" };
+    }
+    const path = join(repoRoot, PRE_FREEZE_RULESET_PATH);
+    const read = readRegularFileIfPresent(path);
+    if (read.kind === "absent") {
+        return {
+            kind: "refused",
+            arm: "absent",
+            reason: `${PRE_FREEZE_RULESET_PATH} is absent, so the pre-freeze branch-protection ruleset was never captured and there is nothing to restore to`,
+        };
+    }
+    if (read.kind === "refused") {
+        return { kind: "refused", arm: "unreadable", reason: read.reason };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.body);
+    }
+    catch (error) {
+        return {
+            kind: "refused",
+            arm: "unreadable",
+            reason: `${PRE_FREEZE_RULESET_PATH} is not valid JSON: ${String(error)}`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            kind: "refused",
+            arm: "unreadable",
+            reason: `${PRE_FREEZE_RULESET_PATH} is not a JSON object`,
+        };
+    }
+    const capturedAt = parsed["captured-at"];
+    if (!nonEmptyString(capturedAt)) {
+        return {
+            kind: "refused",
+            arm: "unreadable",
+            reason: `${PRE_FREEZE_RULESET_PATH} records no captured-at, so it cannot be compared with any switch write`,
+        };
+    }
+    const capturedMs = Date.parse(capturedAt);
+    if (Number.isNaN(capturedMs)) {
+        return {
+            kind: "refused",
+            arm: "unreadable",
+            reason: `${PRE_FREEZE_RULESET_PATH} records captured-at ${JSON.stringify(capturedAt)}, which does not parse as an instant`,
+        };
+    }
+    /* The NEWEST switch write across all five, not only the frozen ones: a
+       switch written back to `current` after the capture is still a write, and
+       the capture has to be at least as new as the whole table. */
+    let newest = Number.NEGATIVE_INFINITY;
+    let newestName = "";
+    for (const name of CUTOVER_SWITCHES) {
+        const at = Date.parse(state.switches[name].flippedAt);
+        if (Number.isNaN(at)) {
+            return {
+                kind: "refused",
+                arm: "unreadable",
+                reason: `switch ${name} records flippedAt ${JSON.stringify(state.switches[name].flippedAt)}, which does not parse as an instant, so the capture could not be compared with it`,
+            };
+        }
+        if (at > newest) {
+            newest = at;
+            newestName = name;
+        }
+    }
+    if (capturedMs < newest) {
+        return {
+            kind: "refused",
+            arm: "stale",
+            reason: `${PRE_FREEZE_RULESET_PATH} was captured at ${capturedAt}, which is older than the most recent switch write (${newestName} at ${state.switches[newestName].flippedAt}), so it does not describe the state before that flip`,
+        };
+    }
+    return { kind: "satisfied", capturedAt };
+}
+/**
+ * Count the PUSHED, UNMERGED branches, and print them nowhere near the drain
+ * verdict.
+ *
+ * THIS NUMBER DOES NOT FEED THE PREDICATE, AND THAT IS THE DECISION (M4-D-15,
+ * delivery/plan/kernel-plan-m4.md:3279). Remote ref deletion is refused in
+ * this container, and `git push --dry-run` does not probe push authorization
+ * at all, in either direction, for any ref namespace
+ * (delivery/verification/m4-prototype-probes.md:165). A drain defined as "no
+ * unmerged branches" therefore waits forever on an owner action that has no
+ * local pre-check, which is a predicate that can never read clean. It is
+ * reported because an operator wants to see it, and it is reported on its own
+ * line so that no reader can mistake it for a reason the cutover is blocked.
+ *
+ * `unexaminable` is a THIRD answer for the same reason it is one in
+ * `inFlightItems`: a repository with no `origin/<default>` cannot be asked
+ * this question, and printing `0` there would be an answer nobody measured.
+ */
+export function unmergedBranchCount(repoRoot, upstream = "origin/main") {
+    const listed = runGit(repoRoot, [
+        "for-each-ref",
+        "--format=%(refname:short)",
+        "--no-merged",
+        upstream,
+        "refs/remotes/origin",
+    ]);
+    if (listed.status !== 0) {
+        return {
+            kind: "unexaminable",
+            reason: `git for-each-ref --no-merged ${upstream} exited ${String(listed.status)}: ${singleLineText(listed.stderr)}`,
+        };
+    }
+    const branches = listed.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && line !== "origin/HEAD");
+    return { kind: "counted", count: branches.length, branches };
+}
+function singleLineText(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/* -------------------------------------------------------------------- */
+/* M4-P25 criterion 6: the retirement verdict over the real inventory    */
+/* -------------------------------------------------------------------- */
+/** The M4-P23 inventory, relative to the REPOSITORY root. */
+export const RETIREMENT_INVENTORY_PATH = "delivery/plan/cutover/retirement-inventory.json";
+/**
+ * The first tokens a retirement row's command may start a segment with.
+ *
+ * MIRRORED FROM `scripts/check-retirement-inventory.mjs`, DELIBERATELY, AND
+ * THE DRIFT IS ASSERTED BY A TEST rather than by this comment. The script is
+ * this project's own predicate and is KEPT rather than shipped (DR-0029), so
+ * the kernel cannot import it; but the two lists screening the same rows must
+ * not diverge, so `test/cutover.test.ts` reads the script's
+ * `ALLOWED_FIRST_TOKENS` and requires this set to be no wider.
+ *
+ * WHAT THE LIST BUYS AND WHAT IT DOES NOT. Every tool on it is one with no
+ * option for writing a file, so a row cannot modify the tree this command is
+ * auditing. It is a TOOL allowlist, not a sandbox: the child still runs with
+ * this process's privileges and can read anything this process can read.
+ */
+export const RETIREMENT_COMMAND_TOKENS = new Set([
+    "grep",
+    "test",
+    "ls",
+    "wc",
+    "comm",
+    "diff",
+    "head",
+    "tail",
+    "cat",
+]);
+const RETIREMENT_COMMAND_FORBIDDEN = [
+    { re: /[<>]/, why: "redirection" },
+    { re: /\$\(/, why: "command substitution" },
+    { re: /`/, why: "backtick substitution" },
+];
+/**
+ * Screen one inventory command. The rows are DATA FROM A FILE, so the command
+ * is screened before anything spawns it, and the check is on the EXECUTABLE
+ * POSITION of every segment rather than on the whole string: a whole-string
+ * denylist refuses `grep -c 'npm ci' gate-registry.yaml`, which runs no npm at
+ * all and merely searches for those characters.
+ */
+export function screenRetirementCommand(command) {
+    if (!nonEmptyString(command)) {
+        return ["negative-witness command is missing or empty"];
+    }
+    const problems = [];
+    for (const forbidden of RETIREMENT_COMMAND_FORBIDDEN) {
+        if (forbidden.re.test(command)) {
+            problems.push(`negative-witness command uses ${forbidden.why}`);
+        }
+    }
+    for (const segment of command.split(/\|\||&&|[|;&\n]/)) {
+        const first = segment.trim().split(/\s+/)[0];
+        if (first === undefined || first === "") {
+            continue;
+        }
+        if (!RETIREMENT_COMMAND_TOKENS.has(first)) {
+            problems.push(`negative-witness command segment starts with ${JSON.stringify(first)}, which is not on the allowlist`);
+        }
+    }
+    return problems;
+}
+/**
+ * Turn one row of the SHIPPED inventory into the shape `evaluatePortRow`
+ * takes.
+ *
+ * THIS ADAPTER EXISTS BECAUSE THE TWO SHAPES REALLY ARE DIFFERENT, and the
+ * difference is silent in the dangerous direction. `RetirementRow` declares
+ * `negativeWitness` as an argv ARRAY (src/cutover.ts:1128), and the M4-P23
+ * inventory writes `negative-witness` as an OBJECT carrying a SHELL STRING
+ * (delivery/plan/cutover/retirement-inventory.json:1). Handing the shipped
+ * document straight to `evaluatePortRow` therefore returns `unported` with
+ * "PORT row carries no negative-witness command" for every row in it: a
+ * verdict that looks like a finding about the kernel and is a finding about a
+ * key spelling. The adapter is named, tested and refuses rather than
+ * defaulting, so the mismatch cannot come back as a silent all-red.
+ */
+export function retirementRowFromDocument(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return {
+            kind: "refused",
+            result: {
+                id: `(row ${JSON.stringify(raw)})`,
+                verdict: "unported",
+                reason: "inventory row is not an object, so its disposition could not be read",
+            },
+        };
+    }
+    const source = raw;
+    const id = nonEmptyString(source["id"]) ? source["id"] : "(row with no id)";
+    const row = {
+        id,
+        disposition: source["disposition"],
+    };
+    if (nonEmptyString(source["destination"])) {
+        row.destination = source["destination"];
+    }
+    const witness = source["negative-witness"];
+    if (source["disposition"] !== "PORT") {
+        return { kind: "row", row };
+    }
+    if (typeof witness !== "object" || witness === null || Array.isArray(witness)) {
+        return {
+            kind: "refused",
+            result: {
+                id,
+                verdict: "unported",
+                reason: "PORT row carries no negative-witness object",
+            },
+        };
+    }
+    const command = witness["command"];
+    const problems = screenRetirementCommand(command);
+    if (problems.length > 0) {
+        return {
+            kind: "refused",
+            result: { id, verdict: "unported", reason: problems.join("; ") },
+        };
+    }
+    /* `sh -c` is how the row's own checker runs it
+       (scripts/check-retirement-inventory.mjs:377), so the command that was
+       screened is the command that runs. */
+    row.negativeWitness = ["sh", "-c", command];
+    const recorded = witness["exit"];
+    if (typeof recorded === "number" && Number.isInteger(recorded)) {
+        row.expectedWitnessExit = recorded;
+    }
+    return { kind: "row", row };
+}
+/**
+ * Evaluate every PORT row of the inventory.
+ *
+ * THE VACUOUS VERDICT IS THE ONE THIS GUARDS AGAINST. `ported` is not "the
+ * named kernel artifact exists"; a file can exist and say nothing. Both halves
+ * are required and the second is the one that matters: the row's negative
+ * witness was RED against a subject that does not carry the rule, so a witness
+ * exiting 0 means the probe discriminates nothing and the row is `unported`.
+ * That derivation is M4-P26's `evaluatePortRow` and is REUSED here rather than
+ * reimplemented; this function supplies the reading, the adaptation and the
+ * screen.
+ */
+export function evaluateRetirementInventory(inventoryPath, repoRoot) {
+    const read = readRetirementInventory(inventoryPath);
+    if (read.kind === "absent") {
+        return {
+            kind: "refused",
+            reason: `${inventoryPath} is absent, so no retirement criterion could be evaluated`,
+        };
+    }
+    if (read.kind === "refused") {
+        return { kind: "refused", reason: read.reason };
+    }
+    const results = [];
+    for (const raw of read.rows) {
+        const source = typeof raw === "object" && raw !== null
+            ? raw
+            : {};
+        /* Only PORT rows are printed (criterion 6). A KEEP or DELETE row is not a
+           retirement that can be incomplete, and an UNREADABLE disposition is not
+           a KEEP: it goes to `evaluatePortRow`, which names it `unported`. */
+        if (source["disposition"] === "KEEP" || source["disposition"] === "DELETE") {
+            continue;
+        }
+        const adapted = retirementRowFromDocument(raw);
+        if (adapted.kind === "refused") {
+            results.push(adapted.result);
+            continue;
+        }
+        results.push(evaluatePortRow(adapted.row, repoRoot));
+    }
+    return {
+        kind: "read",
+        report: { results, unported: results.filter((r) => r.verdict === "unported").length },
+    };
+}