in2-agent-server 0.20260821.185429

package/dist/direct/rollbackRun.js

@@ -0,0 +1,1360 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { runProjection, ScopeTooLargeError } from "../projection/project.js";
+import { diffMetadata } from "../projection/diff.js";
+import { walkSourceTree } from "./sourceTree.js";
+import { runDirectApply } from "./applyLoop.js";
+import { SETUP_AUDIT_TRAIL_SOQL, TOOLING_CUSTOM_FIELD_SOQL, classifyRollback, isUnverifiedLapse, recheckUndeleteWindow, tableEnumOrId } from "./rollback.js";
+// `direct_rollback`'s ENGINE (plan 2026-08-02-002 U10; origin R17, R19–R21; AE4, AE5).
+//
+// U9 classifies and touches nothing. This module is the other half: it supplies the live-org reads
+// the classifier declares as a seam, decides what the tool may DO with each class, writes the cards
+// an operator reads, and — for the components that survive all of that — executes through
+// `runDirectApply` so a rollback is an ordinary wave with its own bundle, verdicts, diff and
+// revert-marked commit (R21).
+//
+// ---------------------------------------------------------------------------------------------
+// PARTIAL BY DEFAULT IS THE WHOLE POSTURE (R17, R20)
+//
+// A rollback selection is a list of independent decisions, not a transaction. An irreversible
+// component is refused and the rest of the selection still executes; a lossy one waits for its own
+// named ack while its clean neighbours go; an undelete-window one leaves through Setup and cannot
+// block anything. The one place this is NOT true is Salesforce's own destructive package, which
+// rolls back whole — so a rollback whose deletes are refused by the org takes its own deletes down
+// with them, and nothing here can change that. What this module guarantees is that a refusal HERE
+// never becomes a refusal THERE.
+//
+// ---------------------------------------------------------------------------------------------
+// THE ADDRESS IS (sessionId, wave), NEVER A SHA (R17)
+//
+// The mirror is a rebuildable cache and every rebuild rewrites its SHAs by design (the materializer
+// version is a commit trailer). `direct_history` says so on every line it prints, and this tool is
+// the reason it has to: a rollback addressed by a SHA an operator wrote down last week is a
+// rollback aimed at whatever that SHA means today, which is nothing. The bundle directory
+// `<session>/direct/<wave>` is the stable identity, so that is the address.
+//
+// ---------------------------------------------------------------------------------------------
+// A CHECK THAT WAS ATTEMPTED IS NOT A CHECK THAT ANSWERED
+//
+// The doctrine everything above rests on is that a check which did not run is not a check that
+// found nothing — it is why NOT_COMPARABLE is an ack, why presence withholds instead of defaulting
+// to absent, and why the not-read branch of the plan header spells out that no divergence is
+// reported because none was looked for. The SUMMARY LINES are where that discipline is easiest to
+// lose, because a summary is a boolean's natural home and these two facts do not fit in one:
+//
+//   ATTEMPTED   a reader was built, a probe object exists, the call went out
+//   ANSWERED    the org came back with something to compare against
+//
+// An org token that expires mid-session separates them completely — the reader CONSTRUCTS, because
+// a refresh token is only spent on the first request, and then every query behind it fails.
+// `LiveStateReport` here and `ProbeOutcome` in the classifier each carry BOTH halves in one status,
+// plus what the gap leaves UNVERIFIED, and `liveStateLines` / `probeLines` render the partial cases
+// as partial. No summary line in this module may resolve off the attempted half alone — and neither
+// type carries a separate `attempted` boolean, because a boolean holding half of what the status
+// holds all of is the exact shape that caused this.
+// ---------------------------------------------------------------------------------------------
+// the live-org probe — the implementation of U9's seam
+// ---------------------------------------------------------------------------------------------
+/** SOQL literals here are org-derived names; anything outside this shape is refused, never quoted. */
+const SOQL_SAFE = /^[A-Za-z0-9_]{1,80}$/;
+/**
+ * The object as the Tooling API addresses it — and this is NOT the API name for a custom object.
+ *
+ * MEASURED, T-Pinto 00Dfn00000BFjbBEAT, 2026-08-03 (read-only):
+ *
+ *   TableEnumOrId = 'PV_Asset__c'      -> 0 rows
+ *   TableEnumOrId = '01Ifn000003E4hx'  -> 8 rows   (the object's EntityDefinition DurableId)
+ *   TableEnumOrId = 'Account'          -> 361 rows (a standard object IS its own DurableId)
+ *
+ * 2026-08-02-005 probed a standard object only, so its `TableEnumOrId='Account'` recipe reads as
+ * general and is not. Getting this wrong is SILENT in the dangerous direction: zero Tooling rows
+ * means an empty deleted set, which the classifier reads as "Salesforce has purged it" and cards as
+ * permanent data loss over a field still sitting in Setup's Deleted Fields list. Hence one
+ * `EntityDefinition` read per object before anything else, cached for the run.
+ *
+ * The labels come along because the audit trail needs them (`scopeAuditRows`), and both are one
+ * query.
+ */
+async function resolveObject(reader, objectName) {
+    if (!SOQL_SAFE.test(objectName)) {
+        throw new Error(`refusing to query for object name ${JSON.stringify(objectName)} — not a plain API name.`);
+    }
+    const result = await reader.toolingQuery(`SELECT DurableId, QualifiedApiName, Label, PluralLabel FROM EntityDefinition WHERE QualifiedApiName = '${objectName}'`);
+    const row = result.records[0];
+    // NO FALLBACK TO THE API NAME. Falling back used to look harmless — a standard object IS its own
+    // DurableId — but it is the same zero-rows trap from the other side: for a CUSTOM object the API
+    // name returns 0 Tooling rows, which is an empty deleted set, which classifies as LOSSY_RECREATE
+    // and tells an operator the data is permanently gone about a field still sitting in Setup. An
+    // unresolvable object is a probe that COULD NOT RUN, and `probeObject` turns that into presence
+    // UNVERIFIED — the safe direction, and the one this module states everywhere else.
+    if (typeof row?.DurableId !== "string" || row.DurableId.length === 0) {
+        throw new Error(`EntityDefinition has no DurableId for ${objectName}, so CustomField.TableEnumOrId cannot be addressed for it. ` +
+            `Querying by API name instead would return zero rows for a custom object, which reads downstream as "Salesforce ` +
+            `purged this field and its data" — so presence is left UNVERIFIED rather than guessed at.`);
+    }
+    const durableId = tableEnumOrId(row.DurableId);
+    return {
+        durableId,
+        // A standard object's DurableId IS its API name; a custom one's is an `01I…` key. Derived from
+        // the org's own answer rather than sniffed off a `__c` suffix, which would also have to know
+        // about `__mdt`, `__e`, `__b` and `__x`.
+        custom: durableId !== objectName,
+        labels: [row?.Label, row?.PluralLabel]
+            .filter((label) => typeof label === "string" && label.length > 0)
+            .map((label) => label.toLowerCase())
+    };
+}
+/**
+ * The audit rows that plausibly concern THIS object, from a query that cannot be scoped to it.
+ *
+ * `Display` is unfilterable server-side (probe §4 trap 1) and the object appears in two different
+ * places depending on the object's kind, both measured:
+ *
+ *   standard (`deletedCF`)       Section = "Customize Accounts"  — the PLURAL label
+ *   custom   (`deletedCFCustom`) Section = "Custom Objects"      — no object at all; the object is
+ *                                the Display tail, "… from PV Assets" — again the PLURAL label
+ *
+ * (The second row is new here: 2026-08-02-005 §4 measured the standard shape and inferred the
+ * custom one from its rendering. Confirmed against T-Pinto's two `PV_Asset__c` deletions on
+ * 2026-08-03.)
+ *
+ * NARROWING ONLY, NEVER EMPTYING. If the filter matches nothing while the unscoped set is
+ * non-empty, the unscoped set is returned: this is corroboration for a timestamp the bundle usually
+ * already has, and every fact it contributes is reported INFERRED, so an over-broad set costs
+ * precision (`auditRowsMatched > 1`, which the classifier surfaces) while an empty one silently
+ * removes the only cross-check there is.
+ */
+export function scopeAuditRows(rows, identity, sections) {
+    if (identity.labels.length === 0)
+        return rows;
+    const matches = rows.filter((row, index) => {
+        if (identity.custom) {
+            const display = row.display.toLowerCase();
+            const sep = display.lastIndexOf(" from ");
+            return sep >= 0 && identity.labels.includes(display.slice(sep + " from ".length).trim());
+        }
+        const section = (sections?.[index] ?? "").toLowerCase();
+        return identity.labels.some((label) => section === `customize ${label}`);
+    });
+    return matches.length > 0 ? matches : rows;
+}
+/**
+ * The three read-only surfaces U9's `RollbackOrgProbe` declares, over the live org.
+ *
+ * READ-ONLY BY CONSTRUCTION: two Tooling queries and one SOQL query, no metadata call, no deploy,
+ * nothing that could undelete. The classifier cannot reach an org at all; this is the only place
+ * that can, which is what keeps U9 testable against transcribed fixtures.
+ */
+export function liveRollbackProbe(reader) {
+    const identities = new Map();
+    const identity = (objectName) => {
+        let pending = identities.get(objectName);
+        if (!pending) {
+            pending = resolveObject(reader, objectName);
+            identities.set(objectName, pending);
+        }
+        return pending;
+    };
+    return {
+        async toolingCustomFields(objectName) {
+            const object = await identity(objectName);
+            const result = await reader.toolingQuery(TOOLING_CUSTOM_FIELD_SOQL(object.durableId));
+            return result.records
+                .filter((row) => typeof row.DeveloperName === "string")
+                .map((row) => ({ developerName: row.DeveloperName, namespacePrefix: row.NamespacePrefix ?? null }));
+        },
+        /**
+         * The LIVE custom-field set, from `FieldDefinition` rather than `listMetadata`.
+         *
+         * 2026-08-02-005 §3 established `Tooling ∖ listMetadata` as the detector and warned off
+         * `describe` as the live baseline (FLS hides 133 live fields on this org, which would read as
+         * deletions). `FieldDefinition` is the third candidate and the probe dismissed it in one line
+         * for showing "nothing" for deleted fields — which is exactly the property the live side needs.
+         * Measured as a set, T-Pinto, 2026-08-03:
+         *
+         *   Account:      Tooling 361, FieldDefinition 327, difference 34, all `_del`, reverse empty
+         *   PV_Asset__c:  Tooling 8,   FieldDefinition 6,   difference 2,  both `_del`, reverse empty
+         *
+         * The Account numbers are the addendum's `listMetadata` numbers exactly (361/327/34/0), so this
+         * reproduces the sanctioned detector rather than substituting a weaker one — and it is scoped
+         * to ONE OBJECT over the Tooling connection the reader already holds, where `listMetadata`
+         * returns the whole org (~10.8 MB measured) and needs a Metadata API call this reader does not
+         * expose. `EntityDefinition.QualifiedApiName` filters both object kinds with no durable-id
+         * indirection, and `QualifiedApiName` carries the namespace the way `listMetadata` does
+         * (`SBQQ__Foo__c`), which is the refinement the whole detector turns on.
+         */
+        async listCustomFields(objectName) {
+            if (!SOQL_SAFE.test(objectName))
+                return [];
+            const result = await reader.toolingQuery(`SELECT QualifiedApiName FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = '${objectName}'`);
+            return result.records
+                .map((row) => row.QualifiedApiName)
+                .filter((name) => typeof name === "string" && name.endsWith("__c"))
+                .map((name) => `${objectName}.${name}`)
+                .sort();
+        },
+        async fieldDeleteAudit(objectName) {
+            // Optional on the reader interface, and its absence is not a failure: the audit trail is
+            // corroboration for a timestamp the bundle's own mutation window usually supplies, so losing
+            // it costs an INFERRED term and never a class.
+            if (!reader.soqlQuery)
+                return [];
+            const object = await identity(objectName);
+            const result = await reader.soqlQuery(SETUP_AUDIT_TRAIL_SOQL(!object.custom));
+            const rows = [];
+            const sections = [];
+            for (const row of result.records) {
+                if (typeof row.CreatedDate !== "string" || typeof row.Display !== "string")
+                    continue;
+                rows.push({ createdDate: row.CreatedDate, display: row.Display });
+                sections.push(typeof row.Section === "string" ? row.Section : "");
+            }
+            return scopeAuditRows(rows, object, sections);
+        }
+    };
+}
+const componentKey = (c) => `${c.typeName}:${c.fullName}`;
+/**
+ * A component read as `found: false` — but is that ABSENCE or a read that failed?
+ *
+ * The projection records both as `found: false` with an `errors` array, and the difference is the
+ * whole preflight: absence compared against a recorded post-image produces "this component is gone,
+ * something changed it outside this history", which is a confident accusation to make out of a
+ * network error. `runProjection`'s catch-all writes `read failed: …`; a genuine miss writes only
+ * the reader's `<Type>:<name> not found`. Anything that is not recognisably the latter is treated
+ * as UNKNOWN and the key is omitted, which the classifier reads as "no live state supplied".
+ */
+function isVerifiedAbsence(errors) {
+    if (!errors || errors.length === 0)
+        return true;
+    return errors.every((error) => /\bnot found$/i.test(error.trim()));
+}
+/**
+ * Read live state for the components a rollback would touch (origin R16).
+ *
+ * Through `runProjection`, deliberately, rather than by calling the snapshot readers directly: the
+ * recorded side of every comparison was written by that same function, and a preflight whose two
+ * sides come from two readers is the NOT_COMPARABLE finding this plan already had to invent once
+ * (PV Arm B). Same producer, same shape, and the projection lands in the rollback's own bundle as
+ * evidence of what was checked.
+ */
+export async function readLiveState(args) {
+    const scope = args.components.length;
+    if (scope === 0)
+        return { live: new Map(), unknown: [], unreadable: [], scope };
+    try {
+        const result = await runProjection(args.reader, {
+            scope: { components: args.components },
+            outDir: args.outDir,
+            orgAlias: args.orgAlias,
+            apiVersion: args.apiVersion,
+            label: "rollback-preflight"
+        });
+        const live = new Map();
+        const unknown = [];
+        const wanted = new Set(args.components.map(componentKey));
+        for (const entry of result.manifest.components) {
+            const key = componentKey(entry);
+            // Precedent samples ride along on every projection and are NOT this caller's scope. They
+            // would only ever add keys nobody asked about, but the mirror already learned once what
+            // happens when a sampled component is read as work somebody did.
+            if (entry.precedent || !wanted.has(key))
+                continue;
+            if (entry.found) {
+                live.set(key, result.byFile.get(entry.file) ?? null);
+                continue;
+            }
+            if (isVerifiedAbsence(entry.errors))
+                live.set(key, null);
+            else
+                unknown.push(`${key} (${entry.errors?.join("; ") ?? "read failed"})`);
+        }
+        const unreadable = args.components.map(componentKey).filter((key) => !live.has(key));
+        return { live, unknown, unreadable, scope, dir: args.outDir };
+    }
+    catch (error) {
+        // FAIL-OPEN, LOUDLY. A preflight that cannot run must not stop a rollback the operator has
+        // decided on — but it must never be mistaken for a preflight that ran and found nothing, which
+        // is why the caller prints this error on the card.
+        const message = error instanceof ScopeTooLargeError
+            ? `${error.message} — narrow the selection with \`components\``
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        return { live: new Map(), unknown: [], unreadable: [], scope, error: message };
+    }
+}
+/**
+ * A NOT_COMPARABLE divergence is an ACK here, though U9 leaves the gate at PROCEEDS.
+ *
+ * The classifier is right not to move it: not-comparable is the statement that the recorded and
+ * observed snapshots were produced by different readers, so their difference is not evidence about
+ * the org IN EITHER DIRECTION. It is not drift, and calling it drift is the false accusation PV Arm
+ * B produced (an entire Layout "changed" on reader shape alone, org state byte-identical).
+ *
+ * But the tool's question is different from the classifier's. What PROCEEDS would mean here is
+ * "overwrite live state without having been able to look at it", and the R16 preflight exists
+ * precisely so an overwrite is never issued blind. The conservative reading costs one ack; the
+ * permissive one silently spends the operator's only chance to notice that the check did not run.
+ * So: ack, worded as a gap rather than as a change.
+ */
+const notComparableAck = (component) => `${component.key}: the R16 preflight could not compare live state to what this wave recorded — ${component.divergence?.detail ?? "the two snapshots are not comparable"} ` +
+    `Rolling back overwrites whatever is live now, and nothing here can tell you whether that is what the wave left. This is a CHECK THAT DID NOT RUN, not a change that was found.`;
+/**
+ * Same doctrine as `notComparableAck`, for its sibling gap: the preflight ASKED about this
+ * component and got no answer, so no drift comparison ran. PROCEEDS here would mean overwriting
+ * live state nobody could look at. Worded as a gap, never as a change that was found.
+ */
+const unreadableAck = (component) => `${component.key}: the R16 preflight tried to read this component's live state and could not — the read failed or returned nothing. ` +
+    `Rolling back overwrites whatever is live now, and this plan cannot tell you whether that matches what the wave left. ` +
+    `This is a CHECK THAT DID NOT RUN, not a change that was found.`;
+/** Which components execute, which wait for a named ack, and which only ever get reported. */
+export function gateRollback(plan, ackComponents, unreadable = new Set()) {
+    const acked = new Set(ackComponents);
+    return plan.components.map((component) => {
+        const notComparable = component.divergence?.kind === "NOT_COMPARABLE";
+        const unanswered = unreadable.has(component.key);
+        const ackReasons = [
+            ...component.ackReasons,
+            ...(notComparable ? [notComparableAck(component)] : []),
+            ...(unanswered ? [unreadableAck(component)] : [])
+        ];
+        // AE4, ASKED OF THE CLASS AND ASKED FIRST — layer 1 of three.
+        //
+        // Everything below this line dispatches on the GATE, which is the right question for every other
+        // class: the gate is where "this needs an ack" lives, and an ack is a real answer to drift, to an
+        // incomplete image, to a sharing-model recalculation. It is NOT a real answer to an in-window
+        // deleted field, because the thing an ack would release is the deploy, and the deploy is the
+        // harm: a re-create restores the definition, reports success, and throws away every value every
+        // record held while Setup still has the field AND ITS DATA.
+        //
+        // So the class decides here, and no gate can overrule it. This is not belt-and-braces around a
+        // hypothetical: `UNDELETE_WINDOW` + `ACK_REQUIRED` was REACHABLE, and by an ordinary route — the
+        // delete frees the original API name, something takes it, the R16 preflight finds the
+        // disagreement, and U9's divergence handling rewrote OPERATOR_ACTION into an ackable gate. That
+        // hole is closed in `rollback.ts` too, but AE4 is U10's invariant and U10 does not own that file.
+        //
+        // AND THE SAME LAYER COVERS THE LAPSE NOTHING VERIFIED, asked of `rollback.ts`'s own predicate
+        // rather than re-derived — a guard that re-derives is a guard that can come to disagree with the
+        // rule it guards. Today every producer of that state already sets `OPERATOR_ACTION`, so this
+        // changes no disposition; what it removes is the dependence on that. `rollbackWork` throws over
+        // one of these, which stops the harm but stops it as a CRASH at the end of a run, after the plan
+        // has already printed a release token for a component no acknowledgement may release. The gate is
+        // where that belongs, and it is exactly the rewrite `UNDELETE_WINDOW` above already survived.
+        if (component.class === "UNDELETE_WINDOW" || isUnverifiedLapse(component)) {
+            return { component, disposition: "OPERATOR_ACTION", ackReasons };
+        }
+        switch (component.gate) {
+            case "OPERATOR_ACTION":
+                return { component, disposition: "OPERATOR_ACTION", ackReasons };
+            case "REFUSED":
+            case "NO_ACTION":
+            case "BLOCKED_NO_IMAGE":
+                return { component, disposition: "REPORTED", ackReasons };
+            case "ACK_REQUIRED":
+                return acked.has(component.key)
+                    ? { component, disposition: "EXECUTE", ackKey: component.key, ackReasons }
+                    : { component, disposition: "HELD_FOR_ACK", ackKey: component.key, ackReasons };
+            case "PROCEEDS":
+                if (!notComparable && !unanswered)
+                    return { component, disposition: "EXECUTE", ackReasons };
+                return acked.has(component.key)
+                    ? { component, disposition: "EXECUTE", ackKey: component.key, ackReasons }
+                    : { component, disposition: "HELD_FOR_ACK", ackKey: component.key, ackReasons };
+        }
+    });
+}
+/**
+ * THE POST-UNDELETE CHECKLIST (origin R19), written here because it existed nowhere.
+ *
+ * R19 names five things — strip the `_del` suffix, re-check required/unique, field dependencies,
+ * master-detail conversion, layout membership — and the plan carries no text for any of them. What
+ * follows is that list turned into instructions, and the load-bearing editorial decision is the
+ * `basis` field: ONE of the five is measured and four are not, and a checklist that presented all
+ * five in the same confident voice would be inventing four Salesforce behaviours to sound complete.
+ *
+ * The frame that makes the unmeasured four honest AND useful: while a field sits deleted it is
+ * unreachable — `FieldDefinition`, `EntityParticle`, `describe` and `readMetadata` are all blind to
+ * it and its data is not SOQL-queryable (2026-08-02-005 §2, §5). So nothing could have checked any
+ * of these in the window, by anyone, and "verify it" is not hedging — it is the only available
+ * answer. The verification wave (`mode: "verify"`) then does the mechanical half against the wave's
+ * own pre-image, which is the comparison AE4 asks for.
+ */
+export const POST_UNDELETE_CHECKLIST = [
+    {
+        title: "STRIP THE `_del` SUFFIX FROM THE API NAME",
+        basis: "MEASURED",
+        detail: "Salesforce renamed the field when it was deleted — `Region__c` became `Region_del__c` — and it comes back under that name, " +
+            "so every formula, flow, validation rule, layout, report and integration that names the original is still broken after a successful undelete. " +
+            "Two traps, both measured: the LABEL was never renamed and does not track the API name, so the field looks right in Setup while the API name is wrong; " +
+            "and the original API name was FREED by the delete, so if anything has taken it since, the rename is refused until that is resolved. " +
+            "A second deleted generation takes a numeric suffix (`_del1`), and both generations can sit in the Deleted Fields list at once holding different data."
+    },
+    {
+        title: "RE-CHECK `required` AND `unique`",
+        basis: "VERIFY",
+        detail: "Compare the restored field against the pre-image this rollback holds. Nothing in the deleted window could have told you whether these survive — " +
+            "a deleted field is invisible to describe and FieldDefinition and its data is not queryable — so this is a look, not a formality. " +
+            "`required` in particular changes data entry for every user of the object, in both directions."
+    },
+    {
+        title: "RE-CHECK FIELD DEPENDENCIES",
+        basis: "VERIFY",
+        detail: "A controlling/dependent picklist pair is stored on the DEPENDENT field. If the undeleted field was either half of one, confirm the dependency is back " +
+            "and that the value mapping is the one the pre-image records — a dependency that came back empty enforces nothing and reports no error."
+    },
+    {
+        title: "RE-CHECK A MASTER-DETAIL RELATIONSHIP",
+        basis: "VERIFY",
+        detail: "A master-detail and a lookup are not interchangeable: roll-up summaries, record ownership, sharing and cascade delete all ride on master-detail. " +
+            "If the field was a relationship, confirm it came back as the SAME kind, and that any roll-up summary fields on the parent are recalculating."
+    },
+    {
+        title: "RE-ADD IT TO PAGE LAYOUTS AND COMPACT LAYOUTS",
+        basis: "VERIFY",
+        detail: "Deleting a field removes it from every layout that carried it, and layout membership is a property of the LAYOUT, not of the field — " +
+            "so restoring the field cannot restore it. Until this is done the data is back and nobody can see it. " +
+            "The wave's pre-image for the affected layouts is on this machine and is what to compare against."
+    }
+];
+/**
+ * The card for one deleted field the operator has to handle in Setup: path, window, and checklist.
+ *
+ * NEVER A DEPLOY, and the card says so first. The failure this exists to prevent is a rollback that
+ * "succeeds" by re-creating the field from its pre-image: the definition returns, the deploy reports
+ * green, and every value every record held is gone — a second incident caused by the recovery.
+ *
+ * TWO CARDS IN ONE, because two states reach `OPERATOR_ACTION` and they ask for different things.
+ * The in-window field is KNOWN to be sitting in Setup's Deleted Fields list, and the instruction is
+ * to undelete it. A field whose window is out on a clock NOTHING CHECKED (`isUnverifiedLapse`) is a
+ * question, and the instruction is to go and settle it — because either answer is possible and the
+ * two have opposite consequences. Printing the plain undelete card over that state would promise
+ * recoverable data nobody verified, which is this module's own defect wearing the other hat; and
+ * this card is the ONLY per-component detail an `OPERATOR_ACTION` entry gets, since `renderPlan`
+ * prints the disposition line for every other kind.
+ *
+ * AND IT CARRIES THE DIVERGENCE, which is not decoration. `renderPlan` prints per-component detail
+ * for every disposition EXCEPT `OPERATOR_ACTION`, whose whole detail is this card — so a divergence
+ * that reached only the disposition list would be dropped silently for exactly the components where
+ * it matters most. For an in-window delete the finding has one meaning and it is checklist item 1's
+ * measured trap: the wave's recorded post-image is ABSENCE, so a divergence at all means something
+ * now holds the API name, and the rename back off `_del` is refused until that is resolved. That is
+ * the fact that decides whether the operator's undelete actually finishes.
+ */
+export function renderUndeleteCard(component, target) {
+    const objectName = component.fullName.split(".")[0] ?? "";
+    const window = component.window;
+    const candidates = window?.candidates ?? [];
+    const divergence = component.divergence;
+    const setupPath = `Object Manager → ${objectName} → Fields & Relationships → Deleted Fields → Undelete`;
+    // The clock said the window ran out and nothing checked the org against it. Asked of the SAME
+    // predicate the classifier gated on, so the card cannot describe a state the gate did not produce.
+    const unverifiedLapse = isUnverifiedLapse(component);
+    const anchor = window?.basis === "BUNDLE_WINDOW" ? "measured from this wave's own mutation window" : "INFERRED from SetupAuditTrail, joined by field label";
+    // `daysRemaining` IS A FLOOR, AND A FLOOR IS NOT AN ELAPSED DAY. `-1` covers everything from one
+    // minute past the derived date to a full day past it, so `-(daysRemaining)` printed "1 day(s) ago"
+    // over a lapse an hour and a half old — overstating, in the one card whose entire subject is that
+    // nothing verified the lapse at all. What the floor DOES establish is a lower bound, so that is
+    // what this says: `-1` means less than a day, and `-n` means more than `n - 1` whole days.
+    const lapsedAgo = window?.daysRemaining !== null && window?.daysRemaining !== undefined && window.daysRemaining < -1
+        ? `more than ${-window.daysRemaining - 1} day(s) ago`
+        : "less than a day ago";
+    const windowLine = window === undefined || window.basis === "UNVERIFIED"
+        ? "Window: NOT ESTABLISHED from this bundle — Setup's own Deleted Fields list is what shows whether it is still there and for how long."
+        : unverifiedLapse
+            ? `Window: the derived window CLOSED ${window.lapsesAt} (${anchor}) — ${lapsedAgo} BY THE CLOCK, which is the only thing that said so.`
+            : `Window: ${window.daysRemaining} day(s) left, closes ${window.lapsesAt} (${anchor}).`;
+    const lines = [
+        // TITLED FOR WHAT IT ASKS FOR, not for the outcome it cannot promise. The legend and the
+        // checklist both stopped stating the undelete as a given ("settled in Setup", "IF YOU FIND IT AND
+        // UNDELETE") on the grounds that either answer is possible here; a headline that still announced
+        // the conclusion is the same overclaim in the largest type on the card.
+        unverifiedLapse ? `SETTLE IN SETUP — ${component.key}` : `UNDELETE — ${component.key}`,
+        "",
+        "  DO NOT RE-CREATE THIS FIELD AS METADATA. The undelete restores the field AND ITS DATA; a",
+        "  re-create from the pre-image restores the definition only, reports success, and throws every",
+        "  value every record held away. That is why this component is not part of the deploy below.",
+        ...(unverifiedLapse
+            ? [
+                "",
+                "  [!] THE WINDOW LOOKS CLOSED, AND NOTHING VERIFIED IT. No live probe answered whether",
+                "      Salesforce still lists this field as deleted-and-recoverable, so the line below is a",
+                "      derivation from recorded timestamps, not a reading of the org. This tool will not",
+                "      re-create the field on that: no acknowledgement releases it, because if the field IS",
+                "      still listed the re-create destroys exactly the data an undelete would have restored.",
+                "",
+                "      SETTLE IT — open the Setup path below and look:",
+                "        • If the field IS listed, UNDELETE IT. The data is intact and this window was wrong.",
+                "        • If it is NOT listed, the field and its data are gone. Re-run this rollback with the",
+                "          org reachable so the probe can measure that, and the re-create is then offered for",
+                "          your acknowledgement:",
+                `            direct_rollback {sessionId: "${target.sessionId}", wave: "${target.wave}", mode: "plan"}`
+            ]
+            : []),
+        "",
+        `  Setup path:  ${setupPath}`,
+        // THE DELETED NAME IS DATED WHEN NOTHING RE-READ IT — and never dropped.
+        //
+        // `window.candidates` is only ever written by a probe that ANSWERED (`matchDeletedField` over a
+        // live Tooling read), so on an unverified lapse it can only have arrived one way: this plan's
+        // earlier pass measured it, and `recheckUndeleteWindow` carried it forward because it had nothing
+        // fresher (see its `candidates: presenceVerified ? candidates : component.window.candidates`).
+        // Printed unattributed it read as a present-tense reading of the org, three lines under "nothing
+        // verified it" — the card contradicting itself in the operator's hands.
+        //
+        // ATTRIBUTED RATHER THAN REMOVED, because it is the one string that FINDS the field: Salesforce
+        // renames a field on the way out, so an operator sent to Deleted Fields without the `_del` name
+        // is searching for something Setup does not show under the name they were given.
+        ...(candidates[0]
+            ? unverifiedLapse
+                ? [
+                    `  This plan's EARLIER reading — taken before the probe stopped answering — listed it under`,
+                    `  its DELETED name: ${candidates[0]}. SEARCH FOR THAT in Setup; nothing has re-read it since.`
+                ]
+                : [`  Salesforce lists it under its DELETED name: ${candidates[0]}`]
+            : []),
+        `  ${windowLine}`,
+        ...(window?.presenceVerified === false
+            ? ["  Presence in the Deleted Fields list is UNVERIFIED — no live probe answered. Not the same as absent."]
+            : []),
+        ...(candidates.length > 1
+            ? [
+                // THE TWIN OF THE LINE ABOVE, off the same array and dated the same way. "N generations
+                // coexist" is a reading of Setup's Deleted Fields list, and on an unverified lapse nothing
+                // in this pass read it — the sentence sat four lines under "no live probe answered". The
+                // NAMES stay either way: the choice between two generations is the operator's to make in
+                // Setup, and they cannot compare deletion dates without knowing which rows to compare.
+                unverifiedLapse
+                    ? `  [!] that EARLIER reading listed ${candidates.length} deleted generations of this API name: ${candidates.join(", ")}.`
+                    : `  [!] ${candidates.length} deleted generations of this API name coexist: ${candidates.join(", ")}.`,
+                "      Salesforce suffixes a re-delete (`_del`, `_del1`, …) and both hold DIFFERENT data. Which one",
+                "      this wave deleted cannot be decided from the API — compare the deletion dates Setup shows",
+                "      against this wave's own window before you restore one."
+            ]
+            : []),
+        ...(divergence
+            ? [
+                "",
+                `  [!] THE API NAME ${component.fullName} IS OCCUPIED. The R16 preflight compared live state`,
+                `      against what wave ${target.wave} recorded — a DELETE, so the record is ABSENCE — and found something`,
+                "      there. What it found:",
+                ...wrap(divergence.detail, 90).map((sentence) => `        ${sentence}`),
+                ...(divergence.laterWaves?.length
+                    ? [`      This org's own later delivery accounts for it: ${divergence.laterWaves.join(", ")}.`]
+                    : []),
+                "      THIS IS WHAT BLOCKS CHECKLIST ITEM 1 BELOW. The delete FREED the original name (measured), so",
+                "      renaming the restored field back off its `_del` suffix is refused while anything else holds it.",
+                "      Decide what happens to the occupant BEFORE you undelete — and note that the occupant is a",
+                "      DIFFERENT field: it holds none of the data the deleted generation is still holding for you.",
+                "      Nothing in this tool will deploy over it; that is the operator's decision to make in Setup."
+            ]
+            : []),
+        "",
+        // The checklist applies the moment the field comes back, which is exactly as certain as the
+        // undelete is. "AFTER YOU UNDELETE" over a field nobody has found yet states the undelete as a
+        // given — the same overclaim the block above exists to refuse, restated in a heading.
+        unverifiedLapse
+            ? "  IF YOU FIND IT AND UNDELETE — five checks, none of which the undelete performs for you:"
+            : "  AFTER YOU UNDELETE — five checks, none of which the undelete performs for you:"
+    ];
+    POST_UNDELETE_CHECKLIST.forEach((check, index) => {
+        lines.push(`   ${index + 1}. ${check.title}  [${check.basis === "MEASURED" ? "measured" : "verify — not measured"}]`);
+        for (const sentence of wrap(check.detail, 96))
+            lines.push(`      ${sentence}`);
+        if (index === 0 && candidates[0]) {
+            lines.push(`      For this field: rename ${candidates[0]} back to ${component.fullName}.`);
+        }
+        if (index === 0 && divergence) {
+            lines.push(`      BLOCKED AS THINGS STAND — ${component.fullName} is occupied; see the finding above.`);
+        }
+    });
+    lines.push("", `  Then run the verification wave, which compares the restored field against wave ${target.wave}'s own`, "  pre-image and reports what the undelete did not restore:", `    direct_rollback {sessionId: "${target.sessionId}", wave: "${target.wave}", mode: "verify"}`);
+    return {
+        key: component.key,
+        objectName,
+        ...(candidates[0] ? { deletedName: candidates[0] } : {}),
+        candidates,
+        setupPath,
+        window: windowLine,
+        ...(divergence ? { divergence: divergence.detail } : {}),
+        text: lines.join("\n")
+    };
+}
+function wrap(text, width) {
+    const out = [];
+    let line = "";
+    for (const word of text.split(/\s+/)) {
+        if (line.length > 0 && line.length + word.length + 1 > width) {
+            out.push(line);
+            line = word;
+        }
+        else {
+            line = line.length > 0 ? `${line} ${word}` : word;
+        }
+    }
+    if (line.length > 0)
+        out.push(line);
+    return out;
+}
+export const UNDELETE_SCHEDULE_FILE = "undelete-verification.json";
+/**
+ * Turn the executable half of a plan into a wave.
+ *
+ * The bytes come from the target bundle's `pre/source/` tree — the deployable image a retrieve
+ * landed before the wave ran — walked with the SAME walker `direct_apply` uses on an authored tree,
+ * so a rollback deploys through the identical path as any other wave. Filtered to the selection
+ * rather than deployed wholesale: `pre/source/` holds an image for every component the wave
+ * touched, and a partial rollback that quietly redeployed all of them would undo work the operator
+ * did not select.
+ */
+export async function rollbackWork(bundleDir, selected) {
+    // AE4 AT THE CHOKEPOINT — layer 2 of three, and the last one.
+    //
+    // This function is the ONLY producer of the edits and deletes `runDirectApply` sends, and
+    // `runDirectApply` is called exactly once in this module. So this is the single line every
+    // component must cross to reach a deploy, and it is the right place to state the invariant as a
+    // fact about the system rather than as a property of whoever called it.
+    //
+    // THROWS RATHER THAN FILTERS, deliberately. Silently dropping the component would let a rollback
+    // report a clean partial success while an operator who believed they had released it went looking
+    // for a field that never came back — and it would hide a gating bug, which is exactly the failure
+    // this guard exists to catch. Nothing downstream of a correct `gateRollback` can trip this; if it
+    // ever fires, the gating is wrong and the loud stop is the point.
+    const inWindow = selected.filter((component) => component.class === "UNDELETE_WINDOW");
+    if (inWindow.length > 0) {
+        throw new Error(`AE4 VIOLATION — refusing to build a deploy containing ${inWindow.length} component(s) still inside Salesforce's ` +
+            `undelete window: ${inWindow.map((component) => component.key).join(", ")}. An UNDELETE_WINDOW component is ` +
+            `recoverable WITH ITS DATA through Setup (Object Manager → Fields & Relationships → Deleted Fields → Undelete) ` +
+            `and may NEVER join a deploy: re-creating it from the pre-image restores the definition only, reports success, ` +
+            `and destroys every value every record held while the recoverable generation is still sitting in Setup. ` +
+            `No acknowledgement releases this — the ack vocabulary cannot buy a re-create, because the re-create is the harm. ` +
+            `Reaching this line means the gating that should have carded these components as OPERATOR_ACTION did not; that is ` +
+            `a defect in this tool, not something to work around.`);
+    }
+    // THE SAME INVARIANT WITH THE CLOCK AS ITS ONLY WITNESS — and it asks `rollback.ts`'s own predicate
+    // rather than re-deriving the question, because a guard that re-derives is a guard that can come to
+    // disagree with the rule it guards. (That is not hypothetical here: U9's divergence handling
+    // rewrote a gate the AE4 check above was reading, and the fix was to ask the CLASS instead.)
+    //
+    // A `LOSSY_RECREATE` reached by a probe that answered is a component Salesforce told us is past
+    // recovery, and R20's per-component ack is the right release for it. One reached by a probe that
+    // did NOT answer is a component nobody looked at, and the class alone cannot tell the two apart.
+    const unverified = selected.filter(isUnverifiedLapse);
+    if (unverified.length > 0) {
+        throw new Error(`AE4 VIOLATION — refusing to build a deploy containing ${unverified.length} component(s) whose undelete window ` +
+            `is UNVERIFIED: ${unverified.map((component) => component.key).join(", ")}. Nothing read Salesforce's Deleted ` +
+            `Fields list for ${plural(unverified.length, "this component", "these components")}, so "the window has closed" ` +
+            `is a clock's inference and not the org's answer — and if the field is still listed, re-creating it from the ` +
+            `pre-image destroys the data an undelete would have restored, while the deploy reports success. These must be ` +
+            `carded as OPERATOR_ACTION so the operator settles it in Setup, or re-classified against a reachable org. ` +
+            `Reaching this line means the gating did not; that is a defect in this tool, not something to work around.`);
+    }
+    const deletes = [];
+    const needsImage = [];
+    for (const component of selected) {
+        // Undoing a CREATE is a delete; everything else executable is a redeploy of the pre-image.
+        if (component.class === "CLEAN_DELETE")
+            deletes.push({ typeName: component.typeName, fullName: component.fullName });
+        else
+            needsImage.push(component);
+    }
+    const edits = [];
+    const missingImage = [];
+    if (needsImage.length > 0) {
+        const walked = await walkSourceTree(path.join(bundleDir, "pre", "source")).catch(() => ({ components: [], skipped: [] }));
+        const byKey = new Map(walked.components.map((edit) => [componentKey(edit), edit]));
+        for (const component of needsImage) {
+            const edit = byKey.get(component.key);
+            if (edit)
+                edits.push(edit);
+            else
+                missingImage.push(component.key);
+        }
+    }
+    return { edits, deletes, missingImage };
+}
+/**
+ * `attempt.json` exists but this machine could not learn a trustworthy attempt number from it —
+ * truncated JSON, or an `"attempt"` field that is not a positive integer (`{"attempt":"3"}` and
+ * `{"attempt":0}` included: both are shapes `nextWaveAttempt` never writes, and coercing or
+ * defaulting either would trust exactly what cannot be trusted).
+ *
+ * REFUSES rather than falling back to `attempt = 1` (single-attempt, `preRoot = bundleDir`), because
+ * that fallback is exactly the failure `resolveRollbackBaseline` exists to prevent: a marker this
+ * corrupt could belong to a bundle retried five times, and defaulting it to "never retried" would
+ * silently redeploy the mid-wave `pre/` image the whole function exists to keep out of a rollback.
+ * A missing marker (`ENOENT`) is different and NOT this case — it is handled by the caller before
+ * this is ever reached, because a bundle from before attempt tracking existed is, by construction,
+ * single-attempt.
+ */
+function unreadableMarkerRefusal(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+        ok: false,
+        code: "ROLLBACK_PREIMAGE_AMBIGUOUS",
+        message: `this bundle's attempt.json exists but is unreadable (${detail}) — the attempt marker is unreadable, so the bundle's retry ` +
+            `history cannot be trusted: this machine cannot tell a single-attempt bundle from a retried one, or find attempt 1's ` +
+            `archived baseline if it was retried. Deploying its pre/ on the assumption that it was never retried could redeploy the ` +
+            `org mid-wave and report a clean rollback. Use direct_history to see what this wave actually delivered.`
+    };
+}
+/**
+ * Which directory the rollback's pre-image reads come from.
+ *
+ * The bundle dir is keyed by wave label; attempts share it. Since archivePriorAttempt (tools/
+ * direct.ts), attempts/<n> holds each prior attempt's evidence, and the EARLIEST archived attempt
+ * that captured a pre-image holds the baseline from before the wave first touched the org — the
+ * only state a rollback of the wave can honestly restore, because a later attempt's "before" is an
+ * earlier attempt's "after". An archived attempt whose manifest proves it wrote nothing is a no-op
+ * that never reached the org and is skipped, not fatal. A multi-attempt bundle with no completed
+ * archive predates that fix (or the copy died): its pre/ records the org DURING the wave, and
+ * deploying it would report a clean rollback while leaving earlier attempts' changes in place — so
+ * that case refuses rather than guesses. The SAME refusal covers a marker this
+ * machine cannot read at all: an unparseable or mis-shaped `attempt.json` on a genuinely retried
+ * bundle is indistinguishable from corruption, and defaulting it to "single attempt" would redeploy
+ * the mid-wave image exactly as confidently as no check at all (see `unreadableMarkerRefusal`).
+ */
+export async function resolveRollbackBaseline(bundleDir) {
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(bundleDir, "attempt.json"), "utf8");
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            // No marker at all — a bundle from before attempt tracking is necessarily single-attempt.
+            return { ok: true, preRoot: bundleDir };
+        }
+        // Present in some form (a directory, permission-denied, …) but not readable as a file — the
+        // same untrusted-history case as a malformed marker, so the same refusal.
+        return unreadableMarkerRefusal(error);
+    }
+    let attempt;
+    try {
+        const parsed = JSON.parse(raw);
+        // Positive integers only — nextWaveAttempt never writes anything else, so a zero, negative or
+        // fractional attempt is corruption wearing a number, and must refuse like any other shape it
+        // cannot trust rather than sliding through a `<= 1` comparison as "single attempt".
+        if (typeof parsed.attempt !== "number" || !Number.isInteger(parsed.attempt) || parsed.attempt < 1) {
+            throw new Error(`"attempt" is ${JSON.stringify(parsed.attempt)}, not a positive integer`);
+        }
+        attempt = parsed.attempt;
+    }
+    catch (error) {
+        return unreadableMarkerRefusal(error);
+    }
+    if (attempt === 1)
+        return { ok: true, preRoot: bundleDir };
+    // Retried. The bundle's own pre/ belongs to the LAST attempt; the honest baseline is the
+    // EARLIEST attempt that captured one. Walk the archives in order:
+    //   - a completed archive (archive.json is archivePriorAttempt's completion receipt) that holds
+    //     a pre-image → that archive is the baseline; nothing earlier can have touched the org.
+    //   - a completed archive that recorded NO pre-image → a proven no-op: pre/ is written before
+    //     any deploy, so an attempt that never wrote it died before it could reach the org. Skip it
+    //     and keep walking.
+    //   - no archive.json → either the bundle predates per-attempt archiving or the copy never
+    //     finished; both are the untrusted-history case, and both refuse.
+    const noOps = [];
+    for (let n = 1; n < attempt; n++) {
+        const archived = path.join(bundleDir, "attempts", String(n));
+        const manifest = await readJson(path.join(archived, "archive.json"));
+        if (!manifest?.archived) {
+            return {
+                ok: false,
+                code: "ROLLBACK_PREIMAGE_AMBIGUOUS",
+                message: `this wave was applied ${attempt} times under one label, and attempt ${n} left no completed archive — either the bundle predates per-attempt archiving, or the archive never finished. The bundle's pre/ was recaptured by the last attempt, so it records the org DURING the wave, not before it. ` +
+                    `Deploying it would report a clean rollback while leaving earlier attempts' changes in place. ` +
+                    `Use direct_history to see what each attempt delivered; the mirror commit before attempt 1 holds the true baseline, and restoring from it is a new wave, not this rollback.`
+            };
+        }
+        if (manifest.archived["pre"]) {
+            try {
+                await fs.access(path.join(archived, "pre", "projection.json"));
+            }
+            catch {
+                return {
+                    ok: false,
+                    code: "ROLLBACK_PREIMAGE_AMBIGUOUS",
+                    message: `this wave was applied ${attempt} times under one label, and attempt ${n}'s archive manifest records a pre-image its directory does not hold — a truncated archive cannot testify to a baseline. ` +
+                        `Use direct_history to see what each attempt delivered; the mirror commit before attempt 1 holds the true baseline, and restoring from it is a new wave, not this rollback.`
+                };
+            }
+            return {
+                ok: true,
+                preRoot: archived,
+                note: `this wave was applied ${attempt} times under one label; the rollback restores the baseline attempt ${n} captured, from before the wave first changed the org.` +
+                    (noOps.length > 0 ? ` (Attempt${noOps.length > 1 ? "s" : ""} ${noOps.join(", ")} left no pre-image and never reached the org.)` : "")
+            };
+        }
+        noOps.push(n);
+    }
+    // Every earlier attempt is a PROVEN no-op: none wrote a pre-image, so none reached the deploy
+    // that follows the pre-write — the org went untouched until the attempt that wrote this bundle's
+    // own pre/, which is therefore the wave's honest baseline. Refusing here would permanently lock
+    // rollback out of the ordinary "first attempt errored out, fix it, re-run the label" flow.
+    return {
+        ok: true,
+        preRoot: bundleDir,
+        note: `this wave was applied ${attempt} times under one label, but attempt${noOps.length > 1 ? "s" : ""} ${noOps.join(", ")} left no pre-image and never reached the org — the last attempt's own pre/ is the wave's baseline.`
+    };
+}
+function liveStateReport(state, readerError) {
+    if (!state) {
+        return { status: "NOT_ATTEMPTED", scope: 0, count: 0, error: readerError ?? "no live org reader", unknown: [] };
+    }
+    const count = state.live.size;
+    const status = state.error !== undefined
+        ? "FAILED"
+        : state.scope === 0
+            ? "NOTHING_IN_SCOPE"
+            : count === 0
+                ? "NONE_READABLE"
+                : count < state.scope
+                    ? "PARTIAL"
+                    : "READ";
+    return { status, scope: state.scope, count, ...(state.error ? { error: state.error } : {}), unknown: state.unknown };
+}
+/**
+ * Classify, gate, card — and, in `execute`, deploy.
+ *
+ * TWO CLASSIFICATION PASSES, and the first one touches nothing. The classifier needs the live map
+ * and the probe up front, and which components to read live is decided by the wave's own candidate
+ * list, which only the classifier knows. So the first pass runs against the bundle alone (pure
+ * disk, no org contact) to learn the candidates, and the second — with live state and the probe —
+ * is the plan. Both are handed the same `asOf`, so the window arithmetic cannot move between them.
+ */
+export async function runRollback(input) {
+    const asOf = input.now ?? new Date().toISOString();
+    const notes = [];
+    if (input.mode === "verify")
+        return verifyUndelete(input, asOf);
+    // Pass 1 — the candidate list, from the bundle only.
+    const candidates = await classifyRollback({
+        bundleDir: input.bundleDir,
+        orgId: input.orgId,
+        asOf,
+        ...(input.components ? { components: input.components } : {}),
+        ...(input.preImageRoot ? { preImageRoot: input.preImageRoot } : {})
+    });
+    // Live state, for the R16 preflight and for nothing else. It is opt-in in the classifier and
+    // SILENT when omitted, so the one thing this must never do is skip it quietly.
+    // UNDEFINED when there was no reader, rather than a hand-built result carrying an `error` — a read
+    // that never happened is not a read that failed, and shaping the two identically is what forced
+    // the distinction to travel beside the value as a boolean the caller had to keep in sync.
+    let liveState;
+    if (input.reader) {
+        liveState = await readLiveState({
+            reader: input.reader,
+            orgAlias: input.orgAlias,
+            apiVersion: input.apiVersion,
+            outDir: path.join(input.rollbackBundleDir, "preflight"),
+            components: candidates.components.map((c) => ({ typeName: c.typeName, fullName: c.fullName }))
+        });
+    }
+    const probe = input.reader ? liveRollbackProbe(input.reader) : undefined;
+    // Pass 2 — the plan.
+    let plan = await classifyRollback({
+        bundleDir: input.bundleDir,
+        orgId: input.orgId,
+        asOf,
+        ...(input.components ? { components: input.components } : {}),
+        ...(probe ? { probe } : {}),
+        ...(liveState && liveState.live.size > 0 ? { live: liveState.live } : {}),
+        ...(input.preImageRoot ? { preImageRoot: input.preImageRoot } : {})
+    });
+    // THE WINDOW IS RE-ASKED AT EXECUTION TIME, per component. A plan that said "11 days left,
+    // undelete in Setup" is a statement about the instant it was made; an operator who takes it to a
+    // change board and comes back on day 16 is holding a promise Salesforce has already broken.
+    let reclassified = [];
+    if (input.mode === "execute") {
+        const rechecked = await recheckUndeleteWindow({ plan, asOf, ...(probe ? { probe } : {}) });
+        plan = rechecked.plan;
+        reclassified = rechecked.reclassified;
+    }
+    // AN ACK THAT MATCHED NOTHING IS REPORTED, never dropped. `classifyRollback` already does this for
+    // an unmatched `components` entry, and the asymmetry was the bug: a mistyped `ackComponents` key
+    // silently releases nothing, so the operator reads "HELD — needs a named ack" against a component
+    // they believe they just released, and the natural next move is to look for what else is wrong
+    // rather than at the key. Named here in the same voice, and it does not block anything: the keys
+    // that DID match still release their components.
+    const knownKeys = new Set(plan.components.map((component) => component.key));
+    const unmatchedAcks = [...new Set(input.ackComponents ?? [])].filter((key) => !knownKeys.has(key)).sort();
+    if (unmatchedAcks.length > 0) {
+        notes.push(`acknowledged but not classified in this plan, so ${unmatchedAcks.length > 1 ? "these acks released" : "this ack released"} nothing: ${unmatchedAcks.join(", ")}. ` +
+            `An ack key is the component's own \`Type:FullName\`, exactly as printed above` +
+            `${input.components ? " — and note this call narrowed the plan with `components`, so a real key outside that selection is not in it either" : ""}.`);
+    }
+    // A component the preflight could not answer for gates like NOT_COMPARABLE: held behind its own
+    // key. A WHOLE-preflight failure holds every component the same way: `liveState.error` set means
+    // the projection itself threw — expired token, scope too large — and exactly none of the plan's
+    // components were compared against live state. The old reading made that the ONE case with an
+    // empty hold-set, so a dead token at execute time released every PROCEEDS component to overwrite
+    // live state nobody looked at, while a single unreadable component would have been held (gap G2,
+    // confirmed 2026-08-18). The header still prints the failure; the hold is what makes it binding.
+    // `liveState` UNDEFINED stays distinct: no reader was supplied at all, which plan mode reports as
+    // `readerError` — a read that never happened is not a read that failed, and the per-component ack
+    // text would claim an attempt that was never made.
+    const unreadableKeys = liveState === undefined
+        ? new Set()
+        : liveState.error === undefined
+            ? new Set(liveState.unreadable)
+            : new Set(plan.components.map((component) => component.key));
+    const gated = gateRollback(plan, input.ackComponents ?? [], unreadableKeys);
+    // THE SAME RULE ONE STEP IN: an ack that matched a component NO ACKNOWLEDGEMENT CAN RELEASE.
+    //
+    // An `OPERATOR_ACTION` component is settled in Setup, and the ack vocabulary deliberately cannot
+    // buy its deploy — the deploy is the harm. But the key still MATCHES a real component, so the note
+    // above never fires for it, and the operator spends their acknowledgement, reads a card that never
+    // mentions it, and goes hunting for the mistake somewhere else. That is precisely the silence the
+    // unmatched-ack note exists to end; the fact that this one is inert BY DESIGN is a reason to say
+    // so, not a reason to say nothing. Reported only: nothing about the run changes.
+    const ackedKeys = new Set(input.ackComponents ?? []);
+    const inertAcks = gated
+        .filter((entry) => entry.disposition === "OPERATOR_ACTION" && ackedKeys.has(entry.component.key))
+        .map((entry) => entry.component.key)
+        .sort();
+    if (inertAcks.length > 0) {
+        notes.push(`acknowledged but settled in Setup rather than by a deploy, so ${inertAcks.length > 1 ? "these acks released" : "this ack released"} nothing: ${inertAcks.join(", ")}. ` +
+            `No acknowledgement releases ${plural(inertAcks.length, "this component", "these components")} — what an ack would release is a metadata re-create, ` +
+            `and the re-create is the harm this card exists to prevent. Follow the card above instead; it is the whole instruction.`);
+    }
+    const cards = gated
+        .filter((entry) => entry.disposition === "OPERATOR_ACTION")
+        .map((entry) => renderUndeleteCard(entry.component, { sessionId: input.sessionId, wave: input.wave }));
+    // The verification wave is SCHEDULED when the card is issued, not when the operator remembers.
+    // It is written on a plan as well as an execute, because the ordinary undelete flow never calls
+    // execute at all: card → the operator undeletes in Setup → verify.
+    let schedule;
+    if (cards.length > 0) {
+        schedule = await writeUndeleteSchedule(input, gated, asOf);
+    }
+    const result = {
+        mode: input.mode,
+        sessionId: input.sessionId,
+        wave: input.wave,
+        orgId: input.orgId,
+        asOf,
+        plan,
+        reclassified,
+        dispositions: gated.map((entry) => ({
+            key: entry.component.key,
+            class: entry.component.class,
+            gate: entry.component.gate,
+            disposition: entry.disposition,
+            ...(entry.ackKey ? { ackKey: entry.ackKey } : {}),
+            ackReasons: entry.ackReasons
+        })),
+        cards,
+        ...(schedule ? { schedule } : {}),
+        liveState: liveStateReport(liveState, input.readerError),
+        notes,
+        text: ""
+    };
+    if (input.mode === "plan") {
+        result.text = renderPlan(input, result, gated);
+        return result;
+    }
+    // EXECUTE. Partial by default: whatever is held, refused or carded simply does not travel.
+    const executing = gated.filter((entry) => entry.disposition === "EXECUTE").map((entry) => entry.component);
+    const work = await rollbackWork(input.preImageRoot ?? input.bundleDir, executing);
+    for (const key of work.missingImage) {
+        notes.push(`${key} classified as executable but no file for it survives in ${input.wave}'s pre/source tree — nothing was deployed for it. The retrieve that produces that tree is fail-open, so an image can be absent without the wave having failed.`);
+    }
+    if (work.edits.length === 0 && work.deletes.length === 0) {
+        notes.push("nothing executed: no selected component reached an executable state. Every reason is named above — this is the partial-selection posture working, not a failure.");
+        result.text = renderPlan(input, result, gated);
+        return result;
+    }
+    if (!input.reader) {
+        throw new Error(`cannot execute a rollback without a live org reader (${input.readerError ?? "unavailable"}). Classification above is complete and nothing was changed.`);
+    }
+    result.applied = await runDirectApply({
+        reader: input.reader,
+        targetOrg: input.orgAlias,
+        apiVersion: input.apiVersion,
+        edits: work.edits,
+        deletes: work.deletes,
+        facetUpdates: [],
+        acks: input.ackLints ?? [],
+        // R3/R21 — the commit is marked as a revert of the wave it undoes, by (session, wave), which is
+        // the same rebuild-stable address this tool was called with. A SHA here would not survive the
+        // next materializer change.
+        revertOf: { sessionId: input.sessionId, wave: input.wave },
+        ...(input.batchId ? { batchId: input.batchId } : {}),
+        ...(input.requirementIds?.length ? { requirementIds: input.requirementIds } : {}),
+        ...(input.operator ? { operator: input.operator } : {}),
+        dryRunOnly: input.dryRunOnly ?? false,
+        bundleDir: input.rollbackBundleDir
+    });
+    result.text = renderPlan(input, result, gated);
+    return result;
+}
+async function writeUndeleteSchedule(input, gated, asOf) {
+    const manifest = await readJson(path.join(input.preImageRoot ?? input.bundleDir, "pre", "projection.json"));
+    const fileFor = new Map((manifest?.components ?? [])
+        .filter((entry) => typeof entry?.typeName === "string" && typeof entry?.fullName === "string" && typeof entry?.file === "string")
+        .map((entry) => [`${entry.typeName}:${entry.fullName}`, entry.file]));
+    const schedule = {
+        target: { sessionId: input.sessionId, wave: input.wave },
+        orgId: input.orgId,
+        scheduledAt: asOf,
+        components: gated
+            .filter((entry) => entry.disposition === "OPERATOR_ACTION")
+            .map((entry) => {
+            const preImageFile = fileFor.get(entry.component.key);
+            return {
+                key: entry.component.key,
+                typeName: entry.component.typeName,
+                fullName: entry.component.fullName,
+                deletedNames: entry.component.window?.candidates ?? [],
+                ...(preImageFile ? { preImageFile } : {}),
+                ...(entry.component.window?.lapsesAt ? { lapsesAt: entry.component.window.lapsesAt } : {})
+            };
+        })
+    };
+    try {
+        await fs.mkdir(input.rollbackBundleDir, { recursive: true });
+        await fs.writeFile(path.join(input.rollbackBundleDir, UNDELETE_SCHEDULE_FILE), `${JSON.stringify(schedule, null, 1)}\n`, "utf8");
+    }
+    catch {
+        // The schedule is a convenience for the verification wave, not the card. A rollback plan that
+        // could not write a file still cards the operator correctly, and `mode: "verify"` says plainly
+        // when it has nothing to read.
+        return schedule;
+    }
+    return schedule;
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * AE4's second half: after the operator undeletes, compare the field against its pre-image.
+ *
+ * READS BOTH NAMES, which is the whole reason this cannot be a normal projection. An undelete
+ * restores the field UNDER ITS DELETED NAME (`Region_del__c`) — measured, 2026-08-02-005 §1 — so a
+ * verification that read only the original API name would report a successful restore as "still
+ * absent" and send the operator to re-create it, which is the exact data-loss path R19 exists to
+ * close. Finding it under the deleted name is a PASS with an outstanding rename, and is reported
+ * that way.
+ */
+async function verifyUndelete(input, asOf) {
+    const base = {
+        mode: "verify",
+        sessionId: input.sessionId,
+        wave: input.wave,
+        orgId: input.orgId,
+        asOf,
+        notes: [],
+        text: ""
+    };
+    const schedule = await readJson(path.join(input.rollbackBundleDir, UNDELETE_SCHEDULE_FILE));
+    if (!schedule || schedule.components.length === 0) {
+        base.text =
+            `no verification wave is scheduled for wave ${input.wave}. One is written when a rollback cards an in-window ` +
+                `deleted field for undelete — run \`direct_rollback {sessionId, wave}\` first, undelete in Setup, then come back.`;
+        return base;
+    }
+    if (!input.reader) {
+        base.liveState = liveStateReport(undefined, input.readerError);
+        base.text = `cannot verify: no live org reader (${input.readerError ?? "unavailable"}). Nothing was read and nothing is claimed.`;
+        return base;
+    }
+    // Both names for every carded component — see the doc comment.
+    const wanted = [];
+    for (const entry of schedule.components) {
+        wanted.push({ typeName: entry.typeName, fullName: entry.fullName });
+        for (const deleted of entry.deletedNames)
+            wanted.push({ typeName: entry.typeName, fullName: deleted });
+    }
+    const live = await readLiveState({
+        reader: input.reader,
+        orgAlias: input.orgAlias,
+        apiVersion: input.apiVersion,
+        outDir: path.join(input.rollbackBundleDir, "verify"),
+        components: wanted
+    });
+    // Reported in the same shape a plan reports it, so a structured consumer has ONE place to ask what
+    // a live read answered rather than re-counting findings for this mode.
+    base.liveState = liveStateReport(live, input.readerError);
+    if (live.error) {
+        base.text = `cannot verify: the live read failed (${live.error}). Nothing was read and nothing is claimed.`;
+        return base;
+    }
+    const findings = [];
+    for (const entry of schedule.components) {
+        const preImage = entry.preImageFile
+            ? await readJson(path.join(input.preImageRoot ?? input.bundleDir, "pre", entry.preImageFile))
+            : null;
+        const before = (preImage?.state?.metadata ?? null);
+        const original = live.live.get(entry.key);
+        const deletedKey = entry.deletedNames.map((name) => `${entry.typeName}:${name}`).find((key) => live.live.get(key));
+        const observed = original ?? (deletedKey ? live.live.get(deletedKey) : undefined);
+        const after = (observed?.state?.metadata ?? null);
+        if (!live.live.has(entry.key) && !deletedKey) {
+            findings.push({
+                key: entry.key,
+                state: "UNREADABLE",
+                differences: [],
+                detail: `${entry.key}: the org could not be read for this component under either name, so nothing is claimed about it.`
+            });
+            continue;
+        }
+        if (after === null) {
+            findings.push({
+                key: entry.key,
+                state: "ABSENT",
+                differences: [],
+                detail: `${entry.key} is not in the org under its own name${entry.deletedNames.length ? ` or as ${entry.deletedNames.join(", ")}` : ""}. The undelete has not happened yet, or it restored a different generation. DO NOT re-create it as metadata while the window is open — that trades the data for a definition.`
+            });
+            continue;
+        }
+        // NEVER compare across the rename: `fullName` differs by construction while the field is still
+        // `_del`-suffixed, and reporting that as a restored-wrong facet would bury the real ones. The
+        // rename is checklist item 1 and is reported as its own state, not as a facet difference.
+        const differences = diffMetadata(before === null ? null : withoutFullName(before), withoutFullName(after));
+        const restoredUnderDeletedName = original === undefined || original === null;
+        findings.push({
+            key: entry.key,
+            state: restoredUnderDeletedName ? "RESTORED_UNDER_DELETED_NAME" : "RESTORED",
+            ...(restoredUnderDeletedName && deletedKey ? { liveAs: deletedKey.slice(deletedKey.indexOf(":") + 1) } : {}),
+            differences,
+            detail: restoredUnderDeletedName
+                ? `${entry.key} is BACK, still under its deleted name — checklist item 1 is outstanding: rename it to ${entry.fullName} before anything that references it works again.`
+                : before === null
+                    ? `${entry.key} is live under its own name. This bundle holds no pre-image snapshot for it, so what it looked like before the delete cannot be compared here.`
+                    : differences.length === 0
+                        ? `${entry.key} is live under its own name and matches wave ${input.wave}'s pre-image on every facet the read covers.`
+                        : `${entry.key} is live under its own name and differs from wave ${input.wave}'s pre-image on ${differences.length} facet(s) — these are what the undelete did not restore.`
+        });
+    }
+    base.verification = { target: { sessionId: input.sessionId, wave: input.wave }, checkedAt: asOf, findings };
+    base.text = renderVerification(base.verification, input.wave);
+    return base;
+}
+const withoutFullName = (metadata) => {
+    const { fullName: _fullName, ...rest } = metadata;
+    return rest;
+};
+function renderVerification(report, wave) {
+    // SAME RULE AS THE PLAN HEADER. `readLiveState` returns without an error when the projection
+    // itself ran and every component inside it failed, so "checked against that wave's own pre-image"
+    // is a heading that survives a verification which read nothing. Each finding says UNREADABLE on
+    // its own line; the summary has to say it too, because the summary is what gets skimmed.
+    const unreadable = report.findings.filter((finding) => finding.state === "UNREADABLE").length;
+    const total = report.findings.length;
+    const lines = [
+        `VERIFICATION WAVE — the undelete of wave ${wave}, checked against that wave's own pre-image (${report.checkedAt})`,
+        unreadable === 0
+            ? `all ${total} carded component(s) were read and compared.`
+            : unreadable === total
+                ? `NOTHING WAS COMPARED — the org could not be read for any of the ${total} carded component(s), under either name. Nothing below is a claim about whether the undelete happened.`
+                : `${total - unreadable} of ${total} carded component(s) were read and compared; ${unreadable} could not be read and carry no claim either way.`,
+        ""
+    ];
+    for (const finding of report.findings) {
+        lines.push(`${finding.state}  ${finding.key}`);
+        for (const sentence of wrap(finding.detail, 100))
+            lines.push(`  ${sentence}`);
+        for (const change of finding.differences) {
+            lines.push(`  - ${change.path}: pre-image ${change.before} → now ${change.after}${change.orderOnly ? " (order only)" : ""}`);
+        }
+        lines.push("");
+    }
+    lines.push("This compares METADATA SHAPE against the pre-image. It does not and cannot prove the records' values came", "back — the field was unreadable while deleted, so nothing recorded what they were. Open a record and look.");
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------------------------
+// rendering
+// ---------------------------------------------------------------------------------------------
+const HEADINGS = {
+    EXECUTE: "WILL EXECUTE",
+    HELD_FOR_ACK: "HELD — needs a named ack",
+    // "Settled in Setup" rather than "undelete in Setup": the same disposition also carries the field
+    // whose window is out on a clock nothing checked, and there the operator's job is to find out
+    // WHICH it is. Promising an undelete to someone who may find nothing to undelete is the same
+    // overclaim as the header this module's last defect produced, one line further down.
+    OPERATOR_ACTION: "OPERATOR ACTION — settled in Setup, never a deploy",
+    REPORTED: "REPORTED — nothing for this tool to execute"
+};
+/** `n component(s)`, or `it`/`them` where the count is already on the line. */
+const plural = (n, singular, many) => (n === 1 ? singular : many);
+/**
+ * The R16 preflight's summary — what it COMPARED, never what it was asked to compare.
+ *
+ * The count-zero case gets its own branch and its own verb. A read that answered for nothing did
+ * not preflight anything, and it borrows the not-read branch's sentence verbatim, because that is
+ * exactly what it is: no divergence below because none was looked for.
+ */
+function liveStateLines(live) {
+    const noneLookedFor = "No divergence is reported below because none was looked for; that is not the same as live state agreeing with what this wave recorded.";
+    const notRead = (error) => [
+        `live state: NOT READ (${error ?? "unavailable"}) — the R16 preflight DID NOT RUN. ${noneLookedFor}`
+    ];
+    if (!live)
+        return notRead(undefined);
+    const unreadable = live.scope - live.count;
+    // `unknown` can be shorter than the count — a component the projection never mentioned is
+    // unreadable with no reason to give — so the count comes from the scope and the list is detail.
+    const detail = live.unknown.length > 0
+        ? `  the org could not be read for ${unreadable}: ${live.unknown.join("; ")}. Those carry NO live claim either way.`
+        : `  ${unreadable} component(s) in scope came back with no answer at all. Those carry NO live claim either way.`;
+    switch (live.status) {
+        case "NOT_ATTEMPTED":
+        case "FAILED":
+            return notRead(live.error);
+        case "READ":
+            return [
+                `live state: READ — all ${live.count} component(s) in scope were read from the org, and the R16 preflight compared every one of them.`
+            ];
+        case "PARTIAL":
+            return [
+                `live state: PARTIAL — ${live.count} of ${live.scope} component(s) in scope were read and compared; ${unreadable} could not be read, so the R16 preflight did not run against ${plural(unreadable, "it", "them")}.`,
+                detail
+            ];
+        case "NONE_READABLE":
+            return [
+                `live state: NOT COMPARED — the read was issued and answered for 0 of ${live.scope} component(s), so the R16 preflight compared NOTHING. ${noneLookedFor}`,
+                detail
+            ];
+        case "NOTHING_IN_SCOPE":
+            return [
+                "live state: NOTHING IN SCOPE — no component was selected for the R16 preflight to read, so it compared nothing."
+            ];
+    }
+    // A status this renderer has not been taught falls to the CONSERVATIVE line. Every switch above is
+    // exhaustive today, so this is unreachable — and it is here because the alternative default (the
+    // last case listed) would render an unknown status as "nothing to read", the single most
+    // reassuring sentence in the set, in a module whose thesis is that a summary may not overclaim.
+    return notRead(live.error);
+}
+/**
+ * The deleted-field probe's summary — what ANSWERED, and what an unanswered probe costs.
+ *
+ * Every branch that is not MEASURED names the consequence in the same sentence as the status, in
+ * the words `classifyDeletedField` uses per component: presence UNVERIFIED, not absent, and the
+ * window is the clock's answer alone.
+ */
+function probeLines(probe) {
+    const notRun = [
+        "deleted-field probe: NOT RUN — presence in Salesforce's Deleted Fields list is UNVERIFIED, which is not the same as absent."
+    ];
+    if (!probe)
+        return notRun;
+    // EACH COMPONENT CARRIES ITS OWN REASON. `failures` is keyed by object and `unverified` by
+    // component; printing the object errors as one parenthetical and the component keys as another
+    // would invite the reader to pair them up, and they do not always pair.
+    const reasons = probe.unverified.map((entry) => `  ${entry.key} — ${entry.reason}`);
+    switch (probe.status) {
+        case "NOT_ATTEMPTED":
+            return notRun;
+        case "MEASURED":
+            return [
+                `deleted-field probe: MEASURED for ${probe.verified.length} component(s) — presence in Salesforce's Deleted Fields list was read from the org, not derived from the clock.`
+            ];
+        case "PARTIAL":
+            return [
+                `deleted-field probe: PARTIAL — measured for ${probe.verified.length} component(s), and ${probe.unverified.length} went unanswered. ` +
+                    `Presence in Salesforce's Deleted Fields list is UNVERIFIED — not absent — for ${plural(probe.unverified.length, "that component, whose window is", "those components, whose windows are")} the clock's answer alone:`,
+                ...reasons
+            ];
+        case "FAILED":
+            return [
+                `deleted-field probe: ATTEMPTED, FAILED — nothing answered. ` +
+                    `Presence in Salesforce's Deleted Fields list is UNVERIFIED — not absent — for all ${probe.unverified.length} component(s) it was asked about, and every window below is the clock's answer alone:`,
+                ...reasons
+            ];
+        case "NOT_NEEDED":
+            return [
+                "deleted-field probe: NOT NEEDED — no component in this plan is a deleted field, so there is no Deleted Fields list to read and none was."
+            ];
+    }
+    return notRun; // Unknown status → the conservative line. See `liveStateLines`.
+}
+function renderPlan(input, result, gated) {
+    const executed = result.applied !== undefined;
+    const lines = [
+        `${executed ? "ROLLBACK EXECUTED" : "ROLLBACK PLAN"} — wave ${input.wave} of session ${input.sessionId} (org ${input.orgId}), classified ${result.asOf}`,
+        `${gated.length} component(s) classified${input.components ? " from the selection given" : " — the whole wave"}.`
+    ];
+    // R16 IS OPT-IN AND SILENT WHEN OMITTED, so its absence is stated rather than left to be inferred
+    // from a card with no divergence on it. Absence of a divergence is not absence of divergence.
+    //
+    // AND NEITHER OF THESE TWO LINES MAY RESOLVE OFF "WAS ATTEMPTED". They are the first thing an
+    // operator reads and everything below them is per-component; a summary that says MEASURED over
+    // evidence that says UNVERIFIED is not a wording problem, it is the header contradicting the
+    // finding. See `LiveStateReport` for the live case that caught this. Both statuses distinguish
+    // not-attempted from attempted-and-failed from partial, and every branch states the consequence
+    // in the same breath as the status.
+    lines.push(...liveStateLines(result.liveState), ...probeLines(result.plan?.probe));
+    if (input.writeBlocked)
+        lines.push(`writes: ${input.writeBlocked}`);
+    if (result.reclassified?.length) {
+        lines.push("", "RECLASSIFIED AT EXECUTION TIME — the plan you read is no longer the plan:");
+        for (const entry of result.reclassified) {
+            lines.push(`  ${entry.key}: ${entry.from} → ${entry.to}`);
+            for (const sentence of wrap(entry.reason, 100))
+                lines.push(`    ${sentence}`);
+        }
+    }
+    for (const disposition of ["EXECUTE", "HELD_FOR_ACK", "OPERATOR_ACTION", "REPORTED"]) {
+        const entries = gated.filter((entry) => entry.disposition === disposition);
+        if (entries.length === 0)
+            continue;
+        lines.push("", `${HEADINGS[disposition]} (${entries.length})`);
+        for (const entry of entries) {
+            // An OPERATOR_ACTION entry's detail is its CARD, printed in full below — repeating the action
+            // line here would say less in more space. Everything that would be lost by skipping it has to
+            // reach the card instead, which is why `renderUndeleteCard` carries the R16 divergence: this
+            // `continue` used to drop that finding on the floor for the one class that cannot afford it.
+            if (disposition === "OPERATOR_ACTION")
+                continue;
+            lines.push(`  ${entry.component.key} — ${entry.component.class}`);
+            for (const sentence of wrap(entry.component.action, 100))
+                lines.push(`    ${sentence}`);
+            if (entry.component.limitation) {
+                for (const sentence of wrap(`REFUSED: ${entry.component.limitation}`, 100))
+                    lines.push(`    ${sentence}`);
+            }
+            // THE REASONS COME BEFORE THE RELEASE TOKEN, and the token says how many it covers. One key
+            // releases every reason on the component (see `GatedComponent.ackKey`), so an operator who
+            // read one reason and typed the key would be answering for all of them without being told.
+            for (const reason of entry.ackReasons) {
+                for (const sentence of wrap(`• ${reason}`, 100))
+                    lines.push(`    ${sentence}`);
+            }
+            if (entry.ackKey && disposition === "HELD_FOR_ACK") {
+                lines.push(entry.ackReasons.length > 1
+                    ? `    release it with:  ackComponents: ["${entry.ackKey}"]   <- this ONE key accepts ALL ${entry.ackReasons.length} reasons above`
+                    : `    release it with:  ackComponents: ["${entry.ackKey}"]`);
+            }
+        }
+    }
+    for (const card of result.cards ?? [])
+        lines.push("", card.text);
+    if (result.schedule) {
+        lines.push("", `A verification wave is scheduled in ${path.join(input.rollbackBundleDir, UNDELETE_SCHEDULE_FILE)}.`);
+    }
+    if (result.applied) {
+        const applied = result.applied;
+        lines.push("", `deploy verdict: ${applied.verdict}`, `bundle: ${applied.bundleDir}`, ...(applied.mirror
+            ? [
+                applied.mirror.error
+                    ? `history: NOT RECORDED (${applied.mirror.error})`
+                    : applied.mirror.committed
+                        ? `history: recorded as ${applied.mirror.sha?.slice(0, 12)}, marked a revert of ${input.sessionId}/${input.wave} (the sha is a display alias, never store it)`
+                        : "history: nothing to record — this rollback left the org exactly as it was"
+            ]
+            : []), ...(applied.operatorSummary ? [`operator summary: ${applied.operatorSummary}`] : []), ...applied.notes);
+    }
+    else if (input.mode === "plan") {
+        const held = gated.filter((entry) => entry.disposition === "HELD_FOR_ACK").map((entry) => entry.component.key);
+        lines.push("", "NOTHING HAS BEEN CHANGED. This call classified and carded only.", `  execute it with:  direct_rollback {sessionId: "${input.sessionId}", wave: "${input.wave}", mode: "execute"${held.length ? `, ackComponents: [${held.map((key) => `"${key}"`).join(", ")}]` : ""}}`);
+    }
+    for (const note of [...result.notes, ...(result.plan?.notes ?? [])])
+        lines.push(`note: ${note}`);
+    return lines.join("\n");
+}