things-api 0.9.0 → 0.11.0

package/dist/write/undo.js

@@ -22,16 +22,30 @@
  *  - Inverse mutations are audited under an `undo:`-prefixed actor and are
  *    themselves EXCLUDED from later undo target selection (no undo-the-undo).
  *  - PRECONDITION guard: before executing each inverse step, runUndo confirms
- *    the fields the step would OVERWRITE still hold their recorded after-state
- *    (`observed`). A field an out-of-band edit already moved is NOT clobbered —
- *    the step is refused (blocked) and unwinding stops. This is in addition to
- *    the pipeline's own verified read-after-write.
+ *    the state the step would OVERWRITE still holds its recorded after-state
+ *    (`observed`). Two axes are checked, both against the SAME recorded
+ *    `observed` after-values: CONTENT fields (title/notes/deadline/reminder/
+ *    tags, keyed 1:1 to the inverse step's params) and the STRUCTURAL axes each
+ *    step names in its `guardFields` — status, container (project/area/
+ *    heading), schedule (start/startDate/todaySection), and trashed state. A
+ *    field an out-of-band edit already moved is NOT clobbered — the step is
+ *    refused (blocked, naming what moved) and unwinding stops.
+ *    `--acknowledge-out-of-band-changes` (MCP `acknowledge_out_of_band_changes`)
+ *    bypasses this whole class uniformly (content + structural) — a single
+ *    "the world moved, overwrite anyway". Axes with no captured after-state are
+ *    left unguarded (see the NOT-GUARDED note on `checkStepPrecondition`); the
+ *    checklist item-level refusal is a SEPARATE plan-time mechanism (it cannot
+ *    compute a faithful forced inverse), so the flag does not bypass it. This is
+ *    in addition to the pipeline's own verified read-after-write.
  */
 import { readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
+import { undoToken } from "../audit/schema.js";
 import { localToday } from "../model/dates.js";
 import { getField } from "./verify/delta.js";
 import { isRepeatingTemplate, loadTarget } from "./pre-state.js";
+import { isUiDriveOp } from "./operations.js";
+import { ruleToInverseParams } from "./repeat-rule.js";
 import { runMutation } from "./pipeline.js";
 import { runReorder } from "./reorder.js";
 // -------------------------------------------------------------- audit reads
@@ -47,6 +61,7 @@ export function readAuditRecords(dir) {
         return [];
     }
     const records = [];
+    let torn = 0;
     for (const file of files) {
         let raw;
         try {
@@ -64,24 +79,85 @@ export function readAuditRecords(dir) {
                     records.push(parsed);
             }
             catch {
-                // tolerate a torn/corrupt line — audit files are append-only
+                // tolerate a torn/corrupt line — append-only files can hold a partial
+                // trailing write — but make it VISIBLE rather than silently dropping it.
+                torn += 1;
             }
         }
     }
+    // One note per read (M5): silent line-dropping could hide a lost record.
+    if (torn > 0) {
+        process.stderr.write(`things: skipped ${torn} unreadable line(s) in the local change history (${dir}) — ` +
+            "a change record may be incomplete; recent history is otherwise intact\n");
+    }
     return records.toSorted((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
 }
 /**
- * The last N undoable targets, NEWEST FIRST (undo unwinds a stack). Only
- * successful mutations qualify; inverse mutations (actor `undo:…`) never do.
+ * Which audit records are undoable at all: only SUCCESSFUL mutations, never an
+ * inverse mutation (actor `undo:…` — no undo-the-undo), and never a compound
+ * leg (its summary record is the single undoable unit for the whole sequence).
+ *
+ * `result === "ok"` also excludes INTENT records (result `"intent"`, the
+ * pre-execute marker — M3): an intent is not a completed mutation, so it is
+ * never an undo target. This is the single choke point every selector flows
+ * through (selectUndoTargets, its `--txn` and `by` branches), so intent records
+ * are skipped there uniformly. The two OTHER audit readers that scan by result
+ * — runUndo's already-undone check and planUndo's compound-leg lookup — also
+ * filter `result === "ok"`, so they skip intent records too.
  */
-export function selectUndoTargets(records, last) {
-    // Compound operations undo as ONE unit: legs are excluded here; their
-    // summary record replays every inverse (or, for reorders, issues a single
-    // inverse reorder from the recorded pre-ranks).
-    return records
-        .filter((r) => r.result === "ok" && !r.actor.startsWith("undo:") && r.txn?.role !== "leg")
-        .slice(-Math.max(1, last))
-        .toReversed();
+function undoableRecords(records) {
+    return records.filter((r) => r.result === "ok" && !r.actor.startsWith("undo:") && r.txn?.role !== "leg");
+}
+/** Pairing key for an intent and its final record (both derive from startedAt). */
+function intentKey(r) {
+    // uuid is DELIBERATELY excluded: a create discovers its uuid only in the
+    // final record, so the intent (uuid null) and final (uuid set) must still pair.
+    return JSON.stringify([r.ts, r.op, r.actor, r.host]);
+}
+/**
+ * Detect crashed writes: INTENT records left without a matching final record.
+ * A mutation writes an intent immediately before touching the app and a final
+ * record after read-after-write; the two share ts+op+actor+host. An intent
+ * with no non-intent sibling on that key means the process died mid-write — the
+ * app may have applied the change, but no result was recorded, so the change is
+ * invisible to undo. Surfaced by `things doctor` so the user can reconcile.
+ */
+export function scanAuditIntegrity(records) {
+    const finalKeys = new Set();
+    for (const r of records) {
+        if (r.result !== "intent")
+            finalKeys.add(intentKey(r));
+    }
+    let orphanedIntents = 0;
+    let newestOrphanIntent = null;
+    for (const r of records) {
+        if (r.result !== "intent" || finalKeys.has(intentKey(r)))
+            continue;
+        orphanedIntents += 1;
+        if (newestOrphanIntent === null || r.ts > newestOrphanIntent)
+            newestOrphanIntent = r.ts;
+    }
+    return { orphanedIntents, newestOrphanIntent };
+}
+/**
+ * The undoable targets to unwind, NEWEST FIRST (undo unwinds a stack).
+ *
+ *  - `txn` wins when present: the ONE record whose undo token matches (or an
+ *    empty array — the caller distinguishes not-found from already-undone).
+ *  - otherwise the last `last` records, optionally narrowed to actor `by`
+ *    (exact match; "*"/undefined = every actor). `by` NEVER matches an
+ *    `undo:<actor>` record — those are excluded from undoability entirely.
+ */
+export function selectUndoTargets(records, selector = {}) {
+    const undoable = undoableRecords(records);
+    if (selector.txn !== undefined) {
+        const match = undoable.find((r) => undoToken(r) === selector.txn);
+        return match === undefined ? [] : [match];
+    }
+    const byActor = selector.by === undefined || selector.by === "*"
+        ? undoable
+        : undoable.filter((r) => r.actor === selector.by);
+    return byActor.slice(-Math.max(1, selector.last ?? 1)).toReversed();
 }
 // -------------------------------------------------------------- plan builder
 /**
@@ -96,6 +172,22 @@ export const IRREVERSIBLE = {
     "trash.empty": "emptying the Trash hard-deletes every row — nothing to restore (A27)",
     "heading.create": "a created heading can only be removed by deleting it, which has no headless surface " +
         "(heading delete is interactive-only) — archive it in the app instead",
+    "todo.make-repeating": "making a to-do repeat is an identity replacement (UI2-a): the original uuid is destroyed " +
+        "and a new template row is born — there is no un-repeat that restores the original",
+    "todo.convert-to-project": "converting a to-do to a project is an identity replacement (UI2-d): the to-do uuid is " +
+        "destroyed and a new project is born — the app offers no convert-back",
+    "project.make-repeating": "making a project repeat is an identity replacement (UIC4-b): the original project uuid is " +
+        "destroyed and a new template project is born — there is no un-repeat that restores the original",
+    "project.create-repeating": "the composite creates a project then promotes it (identity replacement, UIC4-b): the " +
+        "created uuid is destroyed by the promote and a new repeating template is born — delete the " +
+        "resulting repeating project in the app",
+    "heading.convert-to-project": "converting a heading to a project is an identity replacement (UI2-d): the heading uuid is " +
+        "destroyed and a new project is born — no convert-back",
+    // NB: todo.reschedule-repeat / project.reschedule-repeat are NOT here — with
+    // the full rule vocabulary they are CONDITIONAL (planUndo re-drives reschedule
+    // with the CAPTURED prior rule when it is decodable and expressible; only a
+    // rule the Repeat dialog itself cannot produce falls to the irreversible
+    // branch). See the reschedule cases below and reversibility.ts.
     // NB: todo.clear-dated-reminder is NOT here — it IS reversible. The URL
     // scheme re-SETS a dated reminder (update?id=X&when=<date>@<time>, R17/R18),
     // so its inverse re-attaches the captured reminder to the item's current
@@ -106,6 +198,24 @@ export const IRREVERSIBLE = {
 function preField(record, field) {
     return record.pre === null ? undefined : record.pre[field];
 }
+const RULE_UNITS = new Set(["daily", "weekly", "monthly", "yearly"]);
+/**
+ * The decoded PRIOR recurrence rule captured by a reschedule pre-read
+ * (`repeating.rule`), or null when it was not captured / not a decodable rule.
+ * The value survived JSON in the audit trail, so it is shape-checked rather than
+ * re-decoded.
+ */
+function decodedRuleOf(record) {
+    const raw = preField(record, "repeating.rule");
+    if (raw === null || typeof raw !== "object")
+        return null;
+    const r = raw;
+    if (typeof r["unit"] !== "string" || !RULE_UNITS.has(r["unit"]))
+        return null;
+    if (typeof r["interval"] !== "number" || !Array.isArray(r["offsets"]))
+        return null;
+    return raw;
+}
 /**
  * Reconstruct the scheduling step that restores a to-do's pre-op placement
  * from the captured pre-values (start / startDate / todaySection / reminder).
@@ -334,7 +444,13 @@ function wholesaleChecklistConflict(record, current) {
  * it was cleared from), so it must read the live schedule.
  */
 export function planUndo(record, now, allRecords = [], current) {
-    const target = { ts: record.ts, op: record.op, uuid: record.uuid, actor: record.actor };
+    const target = {
+        ts: record.ts,
+        op: record.op,
+        uuid: record.uuid,
+        actor: record.actor,
+        token: undoToken(record),
+    };
     const todayIso = localToday(now);
     const notes = [];
     const irreversible = (reason) => ({
@@ -412,7 +528,7 @@ export function planUndo(record, now, allRecords = [], current) {
             return {
                 target,
                 kind: "invertible",
-                steps: [{ op: "todo.reopen", params: { uuid } }],
+                steps: [{ op: "todo.reopen", params: { uuid }, options: { guardFields: ["status"] } }],
                 notes,
             };
         }
@@ -426,7 +542,13 @@ export function planUndo(record, now, allRecords = [], current) {
             return {
                 target,
                 kind: "invertible",
-                steps: [{ op: was === "completed" ? "todo.complete" : "todo.cancel", params: { uuid } }],
+                steps: [
+                    {
+                        op: was === "completed" ? "todo.complete" : "todo.cancel",
+                        params: { uuid },
+                        options: { guardFields: ["status"] },
+                    },
+                ],
                 notes,
             };
         }
@@ -438,7 +560,7 @@ export function planUndo(record, now, allRecords = [], current) {
             return {
                 target,
                 kind: "invertible",
-                steps: [{ op: "todo.restore", params: { uuid } }],
+                steps: [{ op: "todo.restore", params: { uuid }, options: { guardFields: ["trashed"] } }],
                 notes,
             };
         }
@@ -448,7 +570,7 @@ export function planUndo(record, now, allRecords = [], current) {
             return {
                 target,
                 kind: "invertible",
-                steps: [{ op: "todo.delete", params: { uuid } }],
+                steps: [{ op: "todo.delete", params: { uuid }, options: { guardFields: ["trashed"] } }],
                 notes,
             };
         }
@@ -459,7 +581,7 @@ export function planUndo(record, now, allRecords = [], current) {
             return {
                 target,
                 kind: "invertible",
-                steps: [{ op: "project.restore", params: { uuid } }],
+                steps: [{ op: "project.restore", params: { uuid }, options: { guardFields: ["trashed"] } }],
                 notes,
             };
         }
@@ -470,7 +592,9 @@ export function planUndo(record, now, allRecords = [], current) {
         case "project.cancel": {
             if (uuid === null)
                 return irreversible("no target uuid recorded");
-            const steps = [{ op: "project.reopen", params: { uuid } }];
+            const steps = [
+                { op: "project.reopen", params: { uuid }, options: { guardFields: ["status"] } },
+            ];
             const pre = record.pre ?? {};
             if (!("status" in pre)) {
                 for (const [childUuid, fields] of Object.entries(pre)) {
@@ -502,8 +626,16 @@ export function planUndo(record, now, allRecords = [], current) {
                 kind: "invertible",
                 steps: [
                     was === "completed"
-                        ? { op: "project.complete", params: { uuid, children: "require-resolved" } }
-                        : { op: "project.cancel", params: { uuid, children: "require-resolved" } },
+                        ? {
+                            op: "project.complete",
+                            params: { uuid, children: "require-resolved" },
+                            options: { guardFields: ["status"] },
+                        }
+                        : {
+                            op: "project.cancel",
+                            params: { uuid, children: "require-resolved" },
+                            options: { guardFields: ["status"] },
+                        },
                 ],
                 notes,
             };
@@ -514,7 +646,7 @@ export function planUndo(record, now, allRecords = [], current) {
             return {
                 target,
                 kind: "invertible",
-                steps: [{ op: "project.delete", params: { uuid } }],
+                steps: [{ op: "project.delete", params: { uuid }, options: { guardFields: ["trashed"] } }],
                 notes,
             };
         }
@@ -533,19 +665,30 @@ export function planUndo(record, now, allRecords = [], current) {
             if (deadline !== undefined)
                 params["deadline"] = deadline;
             const requestedWhen = (record.requested["when"] ?? record.requested["reminder"]) !== undefined;
+            // Schedule axes the restore overwrites — guarded against the recorded
+            // after-state so an out-of-band re-schedule blocks rather than clobbers.
+            const scheduleGuard = ["start", "startDate", "todaySection"];
+            let scheduleMerged = false;
             if (requestedWhen) {
                 const schedule = scheduleSteps(uuid, record, todayIso);
                 notes.push(...schedule.notes);
                 const scheduleStep = schedule.steps[0];
                 if (scheduleStep !== undefined && scheduleStep.op === "todo.update") {
                     Object.assign(params, scheduleStep.params);
+                    scheduleMerged = true;
                 }
                 else if (scheduleStep !== undefined) {
-                    steps.push(scheduleStep); // inbox restore is a separate move op
+                    // inbox restore is a separate move op — carry the schedule guard on it
+                    steps.push({ ...scheduleStep, options: { guardFields: scheduleGuard } });
                 }
             }
-            if (Object.keys(params).length > 1)
-                steps.unshift({ op: "todo.update", params });
+            if (Object.keys(params).length > 1) {
+                steps.unshift({
+                    op: "todo.update",
+                    params,
+                    ...(scheduleMerged && { options: { guardFields: scheduleGuard } }),
+                });
+            }
             if (steps.length === 0) {
                 return irreversible("no pre-values were captured for the changed fields");
             }
@@ -567,12 +710,15 @@ export function planUndo(record, now, allRecords = [], current) {
             // when/reminder restore reuses the schedule reconstructor (emitting a
             // project.update); projects never live in the Inbox so that branch is
             // unreachable here.
+            let projectScheduleMerged = false;
             if ((record.requested["when"] ?? record.requested["reminder"]) !== undefined) {
                 const schedule = scheduleSteps(uuid, record, todayIso, "project.update");
                 notes.push(...schedule.notes);
                 const scheduleStep = schedule.steps[0];
-                if (scheduleStep !== undefined)
+                if (scheduleStep !== undefined) {
                     Object.assign(params, scheduleStep.params);
+                    projectScheduleMerged = true;
+                }
             }
             if (Object.keys(params).length === 1) {
                 return irreversible("no pre-values were captured for the changed fields");
@@ -580,7 +726,15 @@ export function planUndo(record, now, allRecords = [], current) {
             return {
                 target,
                 kind: "invertible",
-                steps: [{ op: "project.update", params }],
+                steps: [
+                    {
+                        op: "project.update",
+                        params,
+                        ...(projectScheduleMerged && {
+                            options: { guardFields: ["start", "startDate", "todaySection"] },
+                        }),
+                    },
+                ],
                 notes,
             };
         }
@@ -613,11 +767,19 @@ export function planUndo(record, now, allRecords = [], current) {
                 if (preField(record, "heading") !== null && preField(record, "heading") !== undefined) {
                     notes.push("heading placement cannot be restored — the to-do returns to the project root");
                 }
+                // The detach removed the container; guard that it is STILL detached
+                // (current project/area both null) so a re-attach out of band blocks.
                 if (typeof oldProj === "string") {
                     return {
                         target,
                         kind: "invertible",
-                        steps: [{ op: "todo.move", params: { uuid, project: { uuid: oldProj } } }],
+                        steps: [
+                            {
+                                op: "todo.move",
+                                params: { uuid, project: { uuid: oldProj } },
+                                options: { guardFields: ["project", "area"] },
+                            },
+                        ],
                         notes,
                     };
                 }
@@ -625,7 +787,13 @@ export function planUndo(record, now, allRecords = [], current) {
                     return {
                         target,
                         kind: "invertible",
-                        steps: [{ op: "todo.move", params: { uuid, area: { uuid: oldArea } } }],
+                        steps: [
+                            {
+                                op: "todo.move",
+                                params: { uuid, area: { uuid: oldArea } },
+                                options: { guardFields: ["project", "area"] },
+                            },
+                        ],
                         notes,
                     };
                 }
@@ -639,6 +807,11 @@ export function planUndo(record, now, allRecords = [], current) {
                 if (schedule.steps.length === 0) {
                     return irreversible("pre-op scheduling state was not captured — cannot leave the Inbox");
                 }
+                // The op left the item in the Inbox (start="inbox"); guard that placement
+                // so an out-of-band re-schedule blocks the leave-Inbox restore.
+                for (const s of schedule.steps) {
+                    s.options = { ...s.options, guardFields: ["start", "startDate"] };
+                }
                 return { target, kind: "invertible", steps: schedule.steps, notes };
             }
             // The audit captured the OLD value of whatever destination-kind fields
@@ -658,7 +831,13 @@ export function planUndo(record, now, allRecords = [], current) {
                 return {
                     target,
                     kind: "invertible",
-                    steps: [{ op: "todo.move", params: { uuid, project: { uuid: oldProject } } }],
+                    steps: [
+                        {
+                            op: "todo.move",
+                            params: { uuid, project: { uuid: oldProject } },
+                            options: { guardFields: ["project.uuid", "heading.uuid"] },
+                        },
+                    ],
                     notes,
                 };
             }
@@ -666,7 +845,13 @@ export function planUndo(record, now, allRecords = [], current) {
                 return {
                     target,
                     kind: "invertible",
-                    steps: [{ op: "todo.move", params: { uuid, area: { uuid: oldArea } } }],
+                    steps: [
+                        {
+                            op: "todo.move",
+                            params: { uuid, area: { uuid: oldArea } },
+                            options: { guardFields: ["area.uuid"] },
+                        },
+                    ],
                     notes,
                 };
             }
@@ -684,10 +869,17 @@ export function planUndo(record, now, allRecords = [], current) {
                     ? areaRef.uuid
                     : undefined;
                 if (typeof oldArea === "string") {
+                    // The op detached (area now null); guard it is still area-less.
                     return {
                         target,
                         kind: "invertible",
-                        steps: [{ op: "project.move", params: { uuid, area: { uuid: oldArea } } }],
+                        steps: [
+                            {
+                                op: "project.move",
+                                params: { uuid, area: { uuid: oldArea } },
+                                options: { guardFields: ["area"] },
+                            },
+                        ],
                         notes,
                     };
                 }
@@ -698,7 +890,13 @@ export function planUndo(record, now, allRecords = [], current) {
                 return {
                     target,
                     kind: "invertible",
-                    steps: [{ op: "project.move", params: { uuid, area: { uuid: areaPre } } }],
+                    steps: [
+                        {
+                            op: "project.move",
+                            params: { uuid, area: { uuid: areaPre } },
+                            options: { guardFields: ["area.uuid"] },
+                        },
+                    ],
                     notes,
                 };
             }
@@ -707,7 +905,13 @@ export function planUndo(record, now, allRecords = [], current) {
                 return {
                     target,
                     kind: "invertible",
-                    steps: [{ op: "project.move", params: { uuid, detach: true } }],
+                    steps: [
+                        {
+                            op: "project.move",
+                            params: { uuid, detach: true },
+                            options: { guardFields: ["area.uuid"] },
+                        },
+                    ],
                     notes,
                 };
             }
@@ -871,6 +1075,35 @@ export function planUndo(record, now, allRecords = [], current) {
                 "their current positions");
             return { target, kind: "invertible", steps: [{ op: "reorder", params }], notes };
         }
+        case "area.reorder": {
+            if (uuid === null)
+                return irreversible("no target area uuid recorded");
+            const pre = record.pre;
+            if (pre === null)
+                return irreversible("the pre-move area order was not captured");
+            const ranked = Object.entries(pre).filter(([, rank]) => typeof rank === "number");
+            if (ranked.length === 0)
+                return irreversible("the pre-move area order was not captured");
+            const ranks = ranked.map(([, r]) => r);
+            if (new Set(ranks).size !== ranks.length) {
+                return irreversible("the area order before this move was not fully determined (areas were still " +
+                    "unranked), so the previous position cannot be reconstructed");
+            }
+            const ordered = ranked.toSorted((a, b) => a[1] - b[1]).map(([id]) => id);
+            const idx = ordered.indexOf(uuid);
+            if (idx < 0)
+                return irreversible("the moved area is not in the captured order");
+            const pred = ordered[idx - 1];
+            const params = pred === undefined ? { target: uuid, position: "first" } : { target: uuid, after: pred };
+            notes.push("the area returns to its previous position by driving the app again " +
+                "(relative order restores; the app may assign fresh rank numbers)");
+            return {
+                target,
+                kind: "invertible",
+                steps: [{ op: "area.reorder", params }],
+                notes,
+            };
+        }
         case "heading.rename": {
             if (uuid === null)
                 return irreversible("no target uuid recorded");
@@ -887,7 +1120,9 @@ export function planUndo(record, now, allRecords = [], current) {
         case "heading.archive": {
             if (uuid === null)
                 return irreversible("no target uuid recorded");
-            const steps = [{ op: "heading.unarchive", params: { uuid } }];
+            const steps = [
+                { op: "heading.unarchive", params: { uuid }, options: { guardFields: ["status"] } },
+            ];
             // Reopen exactly the children the cascade resolved (nested pre map —
             // the project.complete pattern). Reparented children live in leg
             // records; replay their inverses too when this summary heads a txn.
@@ -942,7 +1177,13 @@ export function planUndo(record, now, allRecords = [], current) {
             return {
                 target,
                 kind: "invertible",
-                steps: [{ op: "heading.archive", params: { uuid, children: "complete" } }],
+                steps: [
+                    {
+                        op: "heading.archive",
+                        params: { uuid, children: "complete" },
+                        options: { guardFields: ["status"] },
+                    },
+                ],
                 notes,
             };
         }
@@ -983,6 +1224,78 @@ export function planUndo(record, now, allRecords = [], current) {
                 notes,
             };
         }
+        // The ui-vector reversible pair: pause ↔ resume. Both drive the GUI, so
+        // the inverse carries the drive acknowledgement (added in runUndo).
+        case "todo.pause-repeat": {
+            if (uuid === null)
+                return irreversible("no target uuid recorded");
+            return {
+                target,
+                kind: "invertible",
+                steps: [{ op: "todo.resume-repeat", params: { uuid } }],
+                notes,
+            };
+        }
+        case "todo.resume-repeat": {
+            if (uuid === null)
+                return irreversible("no target uuid recorded");
+            return {
+                target,
+                kind: "invertible",
+                steps: [{ op: "todo.pause-repeat", params: { uuid } }],
+                notes,
+            };
+        }
+        case "project.pause-repeat": {
+            if (uuid === null)
+                return irreversible("no target uuid recorded");
+            return {
+                target,
+                kind: "invertible",
+                steps: [{ op: "project.resume-repeat", params: { uuid } }],
+                notes,
+            };
+        }
+        case "project.resume-repeat": {
+            if (uuid === null)
+                return irreversible("no target uuid recorded");
+            return {
+                target,
+                kind: "invertible",
+                steps: [{ op: "project.pause-repeat", params: { uuid } }],
+                notes,
+            };
+        }
+        // Reschedule: identity preserved (UI2-b / UIC2-a), the rule mutated in
+        // place. The captured-rule inverse re-drives reschedule with the PRIOR rule
+        // (recorded pre-op as the decoded rule + deadline flag). Reversible when the
+        // prior rule was captured, decodable, AND expressible in the Repeat dialog's
+        // vocabulary; irreversible for a rule the dialog itself cannot produce.
+        case "todo.reschedule-repeat":
+        case "project.reschedule-repeat": {
+            if (uuid === null)
+                return irreversible("no target uuid recorded");
+            const priorRule = decodedRuleOf(record);
+            if (priorRule === null) {
+                return irreversible("the prior recurrence rule was not captured (or could not be decoded) — reschedule again by hand");
+            }
+            const inverse = ruleToInverseParams(priorRule, preField(record, "repeating.deadlined") === true);
+            if (inverse === null) {
+                return irreversible("the prior rule is outside the Repeat dialog's vocabulary (a rule with two end bounds, or a " +
+                    "multi-anchor month/year rule) — reschedule again by hand");
+            }
+            if (inverse.reminder === undefined) {
+                // The reminder time is not part of the recurrence rule, so a reminder
+                // the reschedule may have set/changed is not restored by the inverse.
+                notes.push("the recurrence structure is restored; a reminder time on the spawned instances is not part of the captured rule and is not restored");
+            }
+            return {
+                target,
+                kind: "invertible",
+                steps: [{ op: record.op, params: { uuid, ...inverse } }],
+                notes,
+            };
+        }
         default:
             return irreversible(`no inverse is defined for operation "${record.op}"`);
     }
@@ -990,6 +1303,44 @@ export function planUndo(record, now, allRecords = [], current) {
 // ------------------------------------------------------ precondition guard
 /** Content fields an inverse can silently CLOBBER; keyed to observed 1:1. */
 const CLOBBER_FIELDS = ["title", "notes", "deadline", "reminder", "tags"];
+/**
+ * Human labels for the guarded axes, used in the block detail. Both the raw
+ * content fields and the structural getField paths a step may name in
+ * `guardFields` are mapped here; anything unmapped falls back to the raw path.
+ */
+const AXIS_LABEL = {
+    title: "title",
+    notes: "notes",
+    deadline: "deadline",
+    reminder: "reminder",
+    tags: "tags",
+    status: "status",
+    trashed: "trashed state",
+    project: "project",
+    "project.uuid": "project",
+    area: "area",
+    "area.uuid": "area",
+    "heading.uuid": "heading",
+    start: "schedule",
+    startDate: "schedule",
+    todaySection: "schedule",
+};
+/**
+ * NOT GUARDED (no captured after-state to compare against, so left unguarded —
+ * these axes rely on the inverse's own verified read-after-write instead):
+ *  - REPEAT rule / paused state (reschedule-repeat, pause/resume-repeat): the
+ *    repeat axis is out of this guard's scope.
+ *  - todo.backdate timestamps (creation/completion date).
+ *  - reorder / area.reorder RANKS: the inverse is a 3-way restore that already
+ *    leaves non-targeted members in place; a rank precondition is not modeled.
+ *  - area.update / tag.update fields: those steps address by `target`, not
+ *    `uuid`, so this guard returns early for them (entity ops are unguarded, as
+ *    before this change).
+ *  - CASCADE CHILDREN of a project/heading resolve (the extra todo.reopen steps
+ *    carry no guardFields): the recorded `observed` after-values are the PARENT
+ *    target's, not each child's, so a per-child compare cannot be made from
+ *    them; the parent's status axis IS guarded.
+ */
 function fieldsEqual(a, b) {
     if (Array.isArray(a) && Array.isArray(b))
         return JSON.stringify(a) === JSON.stringify(b);
@@ -998,14 +1349,31 @@ function fieldsEqual(a, b) {
 function formatValue(value) {
     return value === null || value === undefined ? "none" : JSON.stringify(value);
 }
+/** The blocked result for an axis an out-of-band change already moved. */
+function clobberBlock(op, field, after, cur) {
+    const label = AXIS_LABEL[field] ?? field;
+    return {
+        kind: "blocked",
+        op,
+        reason: "environment",
+        detail: `${label} changed since the recorded mutation (expected ${formatValue(after)}, found ` +
+            `${formatValue(cur)}) — refusing to overwrite a change made outside things-api`,
+        remediation: "review the item's current state and redo the change by hand if it's still wanted; or " +
+            "re-run undo with --acknowledge-out-of-band-changes to overwrite the change made since",
+    };
+}
 /**
- * Refuse an inverse step that would overwrite a field an out-of-band edit has
- * already moved. For every CLOBBER_FIELD the step writes AND that the audit
- * `observed` (after-state) recorded, the target's CURRENT value must still
- * equal that after-value; a divergence means the world moved underneath us, so
- * we block rather than clobber. Fields absent from `observed` are skipped (we
- * cannot confirm them but must not break ops whose observed legitimately omits
- * them). Returns a blocked result on divergence, else null.
+ * Refuse an inverse step that would overwrite state an out-of-band change has
+ * already moved. Two axes are checked against the SAME recorded `observed`
+ * after-state:
+ *  - CONTENT (CLOBBER_FIELDS): every content field the step WRITES (present in
+ *    its params) whose after-value `observed` recorded.
+ *  - STRUCTURAL (`step.options.guardFields`): the container / status / schedule
+ *    / trashed getField paths the step overwrites, set by planUndo on the
+ *    primary-target step. Paths absent from `observed` are skipped.
+ * For each, the target's CURRENT value must still equal the recorded after-value;
+ * a divergence means the world moved underneath us, so we block rather than
+ * clobber. Returns a blocked result on the first divergence, else null.
  */
 function checkStepPrecondition(deps, step, observed) {
     if (observed === null)
@@ -1020,25 +1388,62 @@ function checkStepPrecondition(deps, step, observed) {
         if (!(field in step.params) || !(field in observed))
             continue;
         const cur = getField(current, field) ?? null;
-        const after = observed[field];
-        if (!fieldsEqual(cur, after)) {
-            return {
-                kind: "blocked",
-                op: step.op,
-                reason: "environment",
-                detail: `${field} changed since the recorded mutation (expected ${formatValue(after)}, found ` +
-                    `${formatValue(cur)}) — refusing to avoid clobbering an out-of-band edit`,
-                remediation: "review the item's current state; redo the change by hand if it's still wanted, or " +
-                    "re-run undo once the field is back to its post-change value",
-            };
-        }
+        if (!fieldsEqual(cur, observed[field]))
+            return clobberBlock(step.op, field, observed[field], cur);
+    }
+    for (const field of step.options?.guardFields ?? []) {
+        if (!(field in observed))
+            continue; // no captured after-state for this axis
+        const cur = getField(current, field) ?? null;
+        if (!fieldsEqual(cur, observed[field]))
+            return clobberBlock(step.op, field, observed[field], cur);
     }
     return null;
 }
+/**
+ * The block that would refuse a step before execution, or null. Two sources:
+ * the plan-time checklist refusal (item-level, never bypassed — there is no
+ * faithful forced inverse) and the runtime precondition guard (content +
+ * structural), which `acknowledgeOutOfBandChanges` suppresses uniformly. Shared
+ * by the executor and the dry-run preview so both report the same outcome.
+ */
+function stepWouldBlock(deps, step, observed, acknowledgeOutOfBandChanges) {
+    const planBlock = step.options?.blocked;
+    if (planBlock !== undefined) {
+        return {
+            kind: "blocked",
+            op: step.op,
+            reason: "environment",
+            detail: planBlock.detail,
+            remediation: planBlock.remediation,
+        };
+    }
+    if (acknowledgeOutOfBandChanges)
+        return null;
+    return checkStepPrecondition(deps, step, observed);
+}
 // ----------------------------------------------------------------- executor
 export async function runUndo(deps, auditDirPath, options = {}, onItem) {
     const records = readAuditRecords(auditDirPath);
-    const targets = selectUndoTargets(records, options.last ?? 1);
+    // Exact-token selection is loud and specific: distinguish a token that was
+    // already undone (an inverse for it is on the trail) from one that never
+    // named an undoable mutation. Both are usage errors (RangeError → exit 2).
+    if (options.txn !== undefined) {
+        const alreadyUndone = records.some((r) => r.undoOf === options.txn && r.result === "ok" && r.actor.startsWith("undo:"));
+        if (alreadyUndone) {
+            throw new RangeError(`mutation "${options.txn}" has already been undone (an inverse for it is in the audit ` +
+                "trail); there is nothing left to undo");
+        }
+        if (selectUndoTargets(records, { txn: options.txn }).length === 0) {
+            throw new RangeError(`no undoable mutation has undo token "${options.txn}" — check the token from the ` +
+                "mutation result, or run `things undo --dry-run` to list recent targets");
+        }
+    }
+    const targets = selectUndoTargets(records, {
+        ...(options.last !== undefined && { last: options.last }),
+        ...(options.by !== undefined && { by: options.by }),
+        ...(options.txn !== undefined && { txn: options.txn }),
+    });
     const now = deps.now?.() ?? new Date();
     const items = [];
     for (const record of targets) {
@@ -1051,30 +1456,29 @@ export async function runUndo(deps, auditDirPath, options = {}, onItem) {
             item = { plan, results: [], outcome: "irreversible" };
         }
         else if (options.dryRun === true) {
-            item = { plan, results: [], outcome: "dry-run" };
+            // Preview the would-block outcome so --dry-run surfaces a refusal (an
+            // out-of-band move/status/schedule change, or the checklist item-level
+            // conflict) before any change is attempted — respecting the ack flag.
+            const preview = [];
+            for (const step of plan.steps) {
+                const block = stepWouldBlock(deps, step, record.observed, options.acknowledgeOutOfBandChanges === true);
+                if (block !== null) {
+                    preview.push(block);
+                    break;
+                }
+            }
+            item = { plan, results: preview, outcome: "dry-run" };
         }
         else {
             const results = [];
             let failed = false;
             for (const step of plan.steps) {
-                // Plan-time precondition (checklist undos): the inverse was resolved
-                // against the current list and found a conflict — refuse, don't clobber.
-                const planBlock = step.options?.blocked;
-                if (planBlock !== undefined) {
-                    results.push({
-                        kind: "blocked",
-                        op: step.op,
-                        reason: "environment",
-                        detail: planBlock.detail,
-                        remediation: planBlock.remediation,
-                    });
-                    failed = true;
-                    break;
-                }
-                // Precondition guard: never clobber a field an out-of-band edit moved.
-                const precondition = checkStepPrecondition(deps, step, record.observed);
-                if (precondition !== null) {
-                    results.push(precondition);
+                // Refuse rather than clobber: the plan-time checklist conflict, or the
+                // runtime precondition guard (content + structural) unless the caller
+                // acknowledged out-of-band changes.
+                const block = stepWouldBlock(deps, step, record.observed, options.acknowledgeOutOfBandChanges === true);
+                if (block !== null) {
+                    results.push(block);
                     failed = true;
                     break;
                 }
@@ -1093,6 +1497,9 @@ export async function runUndo(deps, auditDirPath, options = {}, onItem) {
                 }
                 const writeOptions = {
                     actor: `undo:${options.actor ?? deps.config.actor}`,
+                    // Back-reference the mutation being reversed so a later
+                    // `undo --txn <token>` can report it as already undone.
+                    undoOf: plan.target.token,
                     ...(options.verifyTimeoutMs !== undefined && {
                         verifyTimeoutMs: options.verifyTimeoutMs,
                     }),
@@ -1100,10 +1507,16 @@ export async function runUndo(deps, auditDirPath, options = {}, onItem) {
                         acknowledgeChecklistReset: true,
                     }),
                     ...(needsPermanent && { dangerouslyPermanent: true }),
+                    // A GUI-driven inverse (pause ↔ resume) replays a change the user
+                    // already acknowledged when they made it — carry the drive ack so it
+                    // is not re-gated by H-UI-DRIVE.
+                    ...(isUiDriveOp(step.op) && { dangerouslyDriveGui: true }),
                 };
                 const result = step.op === "reorder"
-                    ? await runReorder(deps, step.params, writeOptions)
-                    : await runMutation(deps, step.op, step.params, writeOptions);
+                    ? // undo steps must be inverted in order: each step's precondition check depends on the DB state left by the prior step
+                        await runReorder(deps, step.params, writeOptions)
+                    : // same sequencing requirement as the reorder branch above
+                        await runMutation(deps, step.op, step.params, writeOptions);
                 results.push(result);
                 if (result.kind !== "ok") {
                     failed = true;