things-api 0.18.0 → 0.19.1

package/dist/cli/commands/writes.js

@@ -1,30 +1,56 @@
+/**
+ * Write commands. Help text is the agent API: every command's --help states
+ * its behavior, side effects, and required confirmation flags in consumer
+ * voice (docs/design/surface-copy.md) — internals stay in docs/ and the
+ * capabilities/dry-run OUTPUT. No interactive prompts: risky semantics
+ * require explicit flags.
+ */
+import { Option } from "commander";
 import { readFileSync } from "node:fs";
 import { armInterrupt, disarmInterrupt } from "../interrupt.js";
 import { isDevVersion } from "../skill.js";
 import { CLI_VERSION } from "../version.js";
 import { addRepeatCalendarFlags, addRepeatingRuleFieldsFromOpts, addRepeatRuleFlags, repeatRuleFlagsFromOpts, } from "./repeat-flags.js";
-import { aggregateExitCode, blockedCode, capabilitiesTable, ClockError, closeCliTrace, describeConfig, errorEnvelope, ExitCode, HELPERS_MODES, installCliTrace, getConfigKey, parseHelpersMode, mutationWireData, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, trace, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
+import { aggregateExitCode, blockedCode, buildUpdatePatch, capabilitiesTable, CLI_UPDATE_LABELS, ClockError, closeCliTrace, describeConfig, errorEnvelope, ExitCode, HELPERS_MODES, installCliTrace, getConfigKey, parseHelpersMode, mutationWireData, NOTES_FORMAT, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ParamSchemaError, ReferenceResolutionError, RESOLUTION_DATE_FORMAT, saveConfigKey, splitWhenSugar, trace, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
 import { usageError } from "../read-driver.js";
 import { dim } from "../style.js";
-function addWriteFlags(cmd) {
+/**
+ * The `--preserve-modified` help text, shared by the universal write flag and
+ * the run-level `batch` flag (which applies it as the default for every line) —
+ * one source so the two surfaces can never drift.
+ */
+const PRESERVE_MODIFIED_HELP = "keep this change off the modification-date timeline: capture each pre-existing edited " +
+    "item's modification date and restore it (to the whole second) after the change, so a " +
+    "changes/watch query keyed on it does not surface the edit. A no-op on a pure create. " +
+    "Safe with Things Cloud: the restored date syncs to your other devices and stays put, so " +
+    "the item stays off the timeline everywhere — unless another device edits the same item " +
+    "at nearly the same time, which re-dates it.";
+function addWriteFlags(cmd, capability = {}) {
+    const opId = new Option("--op-id <key>", "idempotency key: a resubmission with the same key is recognized as already applied " +
+        "and not re-run (matches [A-Za-z0-9_-], 1-64 chars)");
+    if (capability.opId === "unsupported")
+        opId.hideHelp();
     return cmd
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .option("--dry-run", "preview the planned change and its expected effect; nothing executes")
-        .option("--preserve-modified", "keep this change off the modification-date timeline: capture each pre-existing edited " +
-        "item's modification date and restore it (to the whole second) after the change, so a " +
-        "changes/watch query keyed on it does not surface the edit. A no-op on a pure create. " +
-        "Safe with Things Cloud: the restored date syncs to your other devices and stays put, so " +
-        "the item stays off the timeline everywhere — unless another device edits the same item " +
-        "at nearly the same time, which re-dates it.")
+        .option("--preserve-modified", PRESERVE_MODIFIED_HELP)
         .option("--vector <id>", "force how the change is delivered: url-scheme | applescript | shortcuts | ui")
         .option("--allow-disruptive", "permit changes that briefly steal window focus")
         .option("--allow-very-disruptive", "permit changes that visibly drive the Things UI")
         .option("--verify-timeout <ms>", "how long to wait for the change to take effect")
         .option("--actor <name>", "author name recorded for this change (default: from config)")
-        .option("--op-id <key>", "idempotency key: a resubmission with the same key is recognized as already applied " +
-        "and not re-run (matches [A-Za-z0-9_-], 1-64 chars)");
+        .addOption(opId);
 }
+/**
+ * The write flags for a multi-result COMPOUND command: the same set, with
+ * `--op-id` kept out of `--help` because that command's execution refuses it
+ * (see `opIdCompoundRefused` / `runMoveCmd`). Every command wrapped in this MUST
+ * refuse `--op-id` at runtime, and every command that refuses it MUST be wrapped
+ * in this — `test/cli/help-contract.test.ts` holds the two halves together. A
+ * compound that records ONE summary the key rides uses plain `addWriteFlags`.
+ */
+const addCompoundWriteFlags = (cmd) => addWriteFlags(cmd, { opId: "unsupported" });
 /** Validate an `--op-id`; on a malformed value emit the usage error and return false. */
 function opIdOk(opts) {
     if (opts.opId === undefined)
@@ -35,11 +61,16 @@ function opIdOk(opts) {
     return false;
 }
 /**
- * Refuse `--op-id` on a multi-leg COMPOUND command. Single-op idempotency (phase
- * 1) replays exactly ONE recorded ok result; a compound records several (or a
- * summary) and its idempotency is the batch-shaped per-line `op_id`. Refusing is
- * honest — dropping the flag silently would leave a resubmission un-deduped.
- * Returns true when refused (the caller returns).
+ * Refuse `--op-id` on a multi-leg COMPOUND command. The rule is ONE RECORDED
+ * RESULT PER KEY: an idempotency key replays exactly one recorded outcome, so a
+ * command that records SEVERAL — the variadic move/reorder, the granular
+ * checklist edit, clear-reminder, the heading archive pair, project reopen —
+ * cannot honor one, and its idempotency is the batch-shaped per-line `op_id`.
+ * (A compound that records ONE SUMMARY the key rides — the template-target
+ * verbs, the `--completed-at` flip-dance, and the promote verbs — accepts the
+ * flag instead; ruling 2026-08-25.) Refusing is honest — dropping the flag
+ * silently would leave a resubmission un-deduped. Returns true when refused
+ * (the caller returns).
  */
 function opIdCompoundRefused(opts, what) {
     if (opts.opId === undefined)
@@ -190,20 +221,64 @@ function splitCsv(value) {
         .map((s) => s.trim())
         .filter((s) => s !== "");
 }
-async function runWrite(opts, fn, emitFn = emitResult) {
-    if (!opIdOk(opts))
-        return;
-    const started = Date.now();
-    // Dev-mode step-timeline trace + signal-safe interrupt guard (TRACE1, #487).
-    // Scoped to the write driver — the invocations where a per-step timeline earns
-    // its keep, and where a mid-drive kill would otherwise leave empty stdout. The
-    // sink is a no-op unless tracing is on (a `-dev` build, or config/env forced).
+/**
+ * Open a CLI write invocation: install the dev-mode step-timeline trace, and
+ * hand back the two things every write driver needs (TRACE1, #487) —
+ *
+ *   - `openClient(dbPath)`: opens the Things client AND arms the signal-safe
+ *     interrupt guard once that open has returned. This is the ONLY arming seam
+ *     for the CLI; see below for why it sits past the open.
+ *   - `endInvocation()`: the driver's `finally` — closes the trace with the
+ *     final exit code, then disarms the guard so a signal during teardown or a
+ *     trailing read emits nothing.
+ *
+ * EVERY write driver calls this, not just the single-mutation one: the library
+ * half (the in-flight marker, the watchdog, the plain-stderr interrupt line)
+ * works everywhere, but the trace FILE and the `--json` `interrupted` envelope
+ * exist only where the driver installs and arms them. `json` says whether this
+ * invocation's stdout is machine-readable — drivers that emit JSONL regardless
+ * of `--json` (batch, undo) pass true.
+ *
+ * ## Why the arm sits PAST the client open
+ *
+ * `openThings` is the read gate, and its `open(2)` on the Things container is
+ * synchronous and can block indefinitely behind a TCC dialog. A listener armed
+ * across that span cannot dispatch (see src/cli/interrupt.ts's module note), so
+ * arming from the top of the driver made a write stalled there swallow SIGTERM
+ * — measured exit 137. Nothing can be in flight before the client exists, so
+ * the window this gives up is one where the guard had nothing to report anyway.
+ *
+ * The sink is a no-op unless tracing is on (a `-dev` build, or config/env
+ * forced), so this costs a config read on every write and nothing else.
+ */
+function beginWriteInvocation(json, startedAt) {
     installCliTrace({
         argv: process.argv.slice(1),
         version: CLI_VERSION,
         isDev: isDevVersion(CLI_VERSION),
     });
-    armInterrupt(opts.json === true);
+    return {
+        openClient: (dbPath) => {
+            const client = openThings(dbPath ? { dbPath } : {});
+            armInterrupt(json);
+            return client;
+        },
+        endInvocation: () => {
+            trace(() => ({
+                phase: "invocation-end",
+                exitCode: process.exitCode ?? 0,
+                elapsedMs: Date.now() - startedAt,
+            }));
+            disarmInterrupt();
+            closeCliTrace();
+        },
+    };
+}
+async function runWrite(opts, fn, emitFn = emitResult) {
+    if (!opIdOk(opts))
+        return;
+    const started = Date.now();
+    const { openClient, endInvocation } = beginWriteInvocation(opts.json === true, started);
     let client = null;
     const meta = (client_) => {
         let dbVersion = null;
@@ -218,7 +293,7 @@ async function runWrite(opts, fn, emitFn = emitResult) {
         return { dbVersion, fingerprint, elapsedMs: Date.now() - started, ...(clock && { clock }) };
     };
     try {
-        client = openThings(opts.db ? { dbPath: opts.db } : {});
+        client = openClient(opts.db);
         const result = await fn(client);
         emitFn(result, opts, meta(client));
     }
@@ -245,6 +320,14 @@ async function runWrite(opts, fn, emitFn = emitResult) {
             usageError(opts, err.message);
             return;
         }
+        // A structural parameter refusal (#580) is an INPUT-CONTRACT error — the
+        // caller's bag was malformed and nothing was dispatched — not an internal
+        // fault. It exits `usage`, naming the JSON path, the expected shape, and
+        // what was received.
+        if (err instanceof ParamSchemaError) {
+            usageError(opts, err.message);
+            return;
+        }
         const isEnv = err instanceof ThingsDbNotFoundError || err instanceof ThingsDbOpenError;
         const message = err instanceof Error ? err.message : String(err);
         if (opts.json) {
@@ -257,16 +340,7 @@ async function runWrite(opts, fn, emitFn = emitResult) {
     }
     finally {
         client?.close();
-        // Close the trace with a final result line (the exit code the caller sees),
-        // then disarm the interrupt guard so a later signal during teardown/reads
-        // emits nothing.
-        trace(() => ({
-            phase: "invocation-end",
-            exitCode: process.exitCode ?? 0,
-            elapsedMs: Date.now() - started,
-        }));
-        disarmInterrupt();
-        closeCliTrace();
+        endInvocation();
     }
 }
 /**
@@ -286,6 +360,22 @@ function emitPreserveNote(result) {
         process.stderr.write(`warning: preserve-modified: ${f.uuid}: ${f.detail}\n`);
     }
 }
+/**
+ * TTY disclosure for a TEMPLATE-TARGET composite (`complete`/`cancel`/`update
+ * --exception` aimed at a repeating to-do): a dim line naming BOTH uuids — the
+ * occurrence that was written (the result's own uuid) and the series it belongs
+ * to — plus whether that occurrence was created for this call. The human render
+ * would otherwise show one uuid with nothing saying which of the two it is.
+ * Silent for every other op (the field is absent).
+ */
+function emitOccurrenceNote(result) {
+    const o = result.occurrence;
+    if (o === undefined)
+        return;
+    const dated = o.date === null ? "" : ` dated ${o.date}`;
+    const origin = o.minted ? "created for this change" : "already open";
+    process.stdout.write(dim(`  occurrence ${o.occurrenceUuid}${dated} (${origin}) of repeating to-do ${o.templateUuid}\n`));
+}
 /**
  * TTY disclosure for the HINTS1 completion-context on a verified complete/cancel:
  * a dim line naming the OPEN work remaining in the to-do's project and/or Today,
@@ -337,6 +427,7 @@ function emitResult(result, opts, meta) {
                     ? "already applied — matched op-id in the change history, not re-run"
                     : `vector=${result.vector}, tier=${result.tier}, verified`;
                 process.stdout.write(`ok ${result.op}${uuid} (${status})\n`);
+                emitOccurrenceNote(result);
                 emitPreserveNote(result);
                 emitContextNote(result);
             }
@@ -432,6 +523,7 @@ async function runMoveCmd(opts, fn) {
         return;
     }
     const started = Date.now();
+    const { openClient, endInvocation } = beginWriteInvocation(opts.json === true, started);
     let client = null;
     const meta = () => {
         let dbVersion = null;
@@ -444,7 +536,7 @@ async function runMoveCmd(opts, fn) {
         return { dbVersion, fingerprint, elapsedMs: Date.now() - started };
     };
     try {
-        client = openThings(opts.db ? { dbPath: opts.db } : {});
+        client = openClient(opts.db);
         emitMoveResult(await fn(client), opts, meta());
     }
     catch (err) {
@@ -469,6 +561,7 @@ async function runMoveCmd(opts, fn) {
     }
     finally {
         client?.close();
+        endInvocation();
     }
 }
 function emitMoveResult(result, opts, meta) {
@@ -690,9 +783,10 @@ function addResultLine(r) {
  * in creation order, and nothing else. Exit code is the worst leg's failure.
  */
 async function runBulkAdd(opts, ops, idOnly) {
+    const { openClient, endInvocation } = beginWriteInvocation(opts.json === true, Date.now());
     let client = null;
     try {
-        client = openThings(opts.db ? { dbPath: opts.db } : {});
+        client = openClient(opts.db);
         const batchResult = await client.write.batch(ops, {
             ...(opts.dryRun !== undefined && { dryRun: opts.dryRun }),
             ...(opts.actor !== undefined && { actor: opts.actor }),
@@ -735,6 +829,7 @@ async function runBulkAdd(opts, ops, idOnly) {
     }
     finally {
         client?.close();
+        endInvocation();
     }
 }
 /** Read newline-delimited titles from stdin; blank lines (whitespace-only) skipped. */
@@ -748,6 +843,45 @@ async function readStdinTitles() {
         .map((l) => l.replace(/\r$/, ""))
         .filter((l) => l.trim() !== "");
 }
+/**
+ * The CLI-only half of the notes vocabulary (the shared half is NOTES_FORMAT):
+ * how a multi-line body gets in from a shell. `-` reads STDIN, so a heredoc or
+ * a pipe composes; the `$'…'` form covers the inline case.
+ */
+const NOTES_INPUT = "pass - to read the body from stdin, or $'line 1\\nline 2' to give it inline";
+/**
+ * Read the whole of STDIN as one UTF-8 note body. One trailing newline is
+ * dropped (a heredoc and most pipes add one); every other newline is kept.
+ */
+async function readStdinText() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks)
+        .toString("utf8")
+        .replace(/\r?\n$/, "");
+}
+/**
+ * Resolve `--notes -` into the body waiting on STDIN, in place on `opts`. A
+ * terminal STDIN has nothing to read, so it is refused with the two working
+ * spellings rather than hanging on an input nobody is going to type. Returns
+ * false when the invocation was refused (the usage error is already emitted).
+ */
+async function resolveNotesStdin(opts, conflictsWithStdinFlag = false) {
+    if (opts["notes"] !== "-")
+        return true;
+    if (conflictsWithStdinFlag && opts["stdin"] === true) {
+        usageError(opts, "--notes - and --stdin both read stdin; pass at most one of them");
+        return false;
+    }
+    if (process.stdin.isTTY === true) {
+        usageError(opts, "--notes - reads the note body from stdin, and stdin is a terminal: pipe the body in " +
+            "(or redirect a file with < notes.md), or give the text inline with --notes $'line 1\\nline 2'");
+        return false;
+    }
+    opts["notes"] = await readStdinText();
+    return true;
+}
 function group(program, name, description) {
     const existing = program.commands.find((c) => c.name() === name);
     if (existing !== undefined)
@@ -772,7 +906,7 @@ export function registerWriteCommands(program) {
         "--create-tags. Adding into a completed/canceled project reopens that project — " +
         "requires --acknowledge-project-reopen. When several to-dos are created, one undo " +
         "token removes the whole skeleton at once.")
-        .option("--notes <text>", "notes body")
+        .option("--notes <text>", `notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
         .option("--reminder <HH:mm>", "time-of-day reminder (24h); requires --when today|evening|YYYY-MM-DD")
         .option("--deadline <date>", "YYYY-MM-DD")
@@ -781,8 +915,8 @@ export function registerWriteCommands(program) {
         .option("--project <ref>", "destination project (uuid or unique name)")
         .option("--area <ref>", "destination area (uuid or unique name)")
         .option("--heading <name>", "existing heading in the destination project")
-        .option("--created-at <iso>", "born with this creation timestamp (ISO date or datetime; a date is noon in the effective zone)")
-        .option("--completed-at <iso>", "born completed (in the Logbook) with this completion timestamp (ISO date or datetime); drop --when/--reminder")
+        .option("--created-at <iso>", `born with this creation timestamp (${RESOLUTION_DATE_FORMAT})`)
+        .option("--completed-at <iso>", `born completed (in the Logbook) with this completion timestamp (${RESOLUTION_DATE_FORMAT}); drop --when/--reminder`)
         .option("--acknowledge-project-reopen", "allow adding into a completed/canceled project")
         .option("--stdin", "read newline-delimited titles from stdin (blank lines skipped); exclusive with title arguments")
         .option("--id-only", "print only the new uuid(s), one per line in creation order, and nothing else (exclusive with --json)"))).action(async (titles, opts) => {
@@ -792,6 +926,8 @@ export function registerWriteCommands(program) {
             usageError(opts, "--id-only and --json are mutually exclusive");
             return;
         }
+        if (!(await resolveNotesStdin(opts, true)))
+            return;
         if (useStdin && titles.length > 0) {
             usageError(opts, "--stdin is mutually exclusive with title arguments");
             return;
@@ -884,15 +1020,17 @@ export function registerWriteCommands(program) {
     });
     addWriteFlags(todo
         .command("update <uuid>")
-        .description("Update title/notes/when/reminder/deadline. Schedule and deadline changes are not " +
-        "available for repeating to-dos (title/notes are). --reminder needs --when " +
+        .description("Update title/notes/when/reminder/deadline. On a REPEATING to-do a schedule or " +
+        "deadline change needs --exception (change only the next occurrence) or " +
+        "`things todo reschedule-repeat` (change the series); title/notes apply to the " +
+        "series as they always have. --reminder needs --when " +
         "today|evening|YYYY-MM-DD; when re-scheduling WITHOUT --reminder an existing " +
         "reminder is auto-preserved. --clear-reminder works while the to-do is scheduled " +
         "for today|evening — a DATED reminder can only be changed, not cleared " +
         "(re-schedule to today first). --append-notes/--prepend-notes join with a " +
         "newline (exclusive with --notes).")
         .option("--title <text>", "new title")
-        .option("--notes <text>", "replace notes")
+        .option("--notes <text>", `replace the notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--append-notes <text>", "append to existing notes (newline-joined)")
         .option("--prepend-notes <text>", "prepend to existing notes (newline-joined)")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
@@ -900,34 +1038,36 @@ export function registerWriteCommands(program) {
         .option("--clear-reminder", "clear the reminder (works while scheduled today|evening)")
         .option("--deadline <date>", "YYYY-MM-DD")
         .option("--clear-deadline", "remove the deadline")
-        .option("--created-at <iso>", "rewrite the creation timestamp (ISO date or datetime; a date is noon in the effective zone); status-safe")
-        .option("--completed-at <iso>", "rewrite the completion timestamp of an already-resolved to-do (a canceled one stays canceled); open to-dos are refused — use complete/cancel")).action(async (uuid, opts) => {
-        const notesModes = ["notes", "appendNotes", "prependNotes"].filter((k) => opts[k] !== undefined);
-        if (notesModes.length > 1) {
-            usageError(opts, "--notes, --append-notes, --prepend-notes are exclusive");
+        .option("--created-at <iso>", `rewrite the creation timestamp (${RESOLUTION_DATE_FORMAT}); status-safe`)
+        .option("--completed-at <iso>", "rewrite the completion timestamp of an already-resolved to-do (a canceled one stays canceled); open to-dos are refused — use complete/cancel")
+        .option("--exception", "repeating to-dos only: change just the NEXT occurrence and leave the series alone " +
+        "(creates that occurrence if it has not appeared yet); refused when the series already " +
+        "lands on the requested day. The result names both the occurrence and the series. Each " +
+        "re-run takes another occurrence out of the series, so pass --op-id on a retry: a " +
+        "resubmission with the same key replays the first result instead of creating a second " +
+        "occurrence")).action(async (uuid, opts) => {
+        if (!(await resolveNotesStdin(opts)))
             return;
-        }
-        if (opts["reminder"] !== undefined && opts["clearReminder"] === true) {
-            usageError(opts, "pass at most one of --reminder / --clear-reminder");
+        // The patch (and every exclusive-flag pair in it, the @time sugar included)
+        // comes from the ONE update-vocabulary builder both surfaces share.
+        const built = buildUpdatePatch(opts, CLI_UPDATE_LABELS);
+        if (built.kind === "error") {
+            usageError(opts, built.message);
             return;
         }
-        if (!whenSugarOk(opts))
+        if (opts["exception"] === true) {
+            // The occurrence is a to-do of its own once it exists, so the whole update
+            // vocabulary applies to it — except the timestamp rewrites, which are about
+            // a row's history and have no meaning for an occurrence created this second.
+            const stamped = ["createdAt", "completedAt"].filter((k) => opts[k] !== undefined);
+            if (stamped.length > 0) {
+                usageError(opts, "--exception cannot be combined with --created-at/--completed-at");
+                return;
+            }
+            await runWrite(opts, (c) => c.write.updateTodoOccurrence(uuid, built.patch, writeOptionsFrom(opts)));
             return;
-        await runWrite(opts, (c) => c.write.updateTodo(uuid, {
-            ...(opts["title"] !== undefined && { title: opts["title"] }),
-            ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
-            ...(opts["appendNotes"] !== undefined && { appendNotes: opts["appendNotes"] }),
-            ...(opts["prependNotes"] !== undefined && {
-                prependNotes: opts["prependNotes"],
-            }),
-            ...(opts["when"] !== undefined && { when: opts["when"] }),
-            ...(opts["reminder"] !== undefined && { reminder: opts["reminder"] }),
-            ...(opts["clearReminder"] === true && { reminder: null }),
-            ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
-            ...(opts["clearDeadline"] === true && { deadline: null }),
-            ...(opts["createdAt"] !== undefined && { createdAt: opts["createdAt"] }),
-            ...(opts["completedAt"] !== undefined && { completedAt: opts["completedAt"] }),
-        }, writeOptionsFrom(opts)));
+        }
+        await runWrite(opts, (c) => c.write.updateTodo(uuid, built.patch, writeOptionsFrom(opts)));
     });
     for (const verb of ["complete", "cancel"]) {
         const method = verb === "complete" ? "completeTodo" : "cancelTodo";
@@ -936,10 +1076,16 @@ export function registerWriteCommands(program) {
             : "keeping it canceled via the certified flip legs";
         addWriteFlags(todo
             .command(`${verb} <uuid>`)
-            .description(`${verb[0]?.toUpperCase()}${verb.slice(1)} a to-do. Not available for repeating to-dos. ` +
+            .description(`${verb[0]?.toUpperCase()}${verb.slice(1)} a to-do. On a REPEATING to-do this ${verb}s ` +
+            "the series' current occurrence — the unfinished one if there is one, otherwise the " +
+            "next one, created for the purpose — and leaves the series running; the result names " +
+            "both the occurrence and the series, and says which of the two it created. Each " +
+            `re-run is a new ${verb} that takes the FOLLOWING occurrence, so pass --op-id on a ` +
+            "retry: a resubmission with the same key replays the first result instead of " +
+            "creating a second occurrence. " +
             '--completed-at sets the completion timestamp (also the "Completed on" stamp for a canceled ' +
             `item), ${stampNote} — a multi-leg sequence, disclosed in the result and --dry-run.`)
-            .option("--completed-at <iso>", "completion timestamp (ISO date or datetime; a date is noon in the effective zone)")).action(async (uuid, opts) => {
+            .option("--completed-at <iso>", `completion timestamp (${RESOLUTION_DATE_FORMAT})`)).action(async (uuid, opts) => {
             const resolution = opts["completedAt"] !== undefined ? { completedAt: opts["completedAt"] } : {};
             await runWrite(opts, (c) => c.write[method](uuid, resolution, writeOptionsFrom(opts)));
         });
@@ -949,7 +1095,7 @@ export function registerWriteCommands(program) {
         .description("Reopen a to-do. Not available for repeating to-dos.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.reopenTodo(uuid, writeOptionsFrom(opts)));
     });
-    addPositionFlags(addWriteFlags(todo
+    addPositionFlags(addCompoundWriteFlags(todo
         .command("move <refs...>")
         .description("Move one or more to-dos as an ordered block (the argument order is the order they " +
         "land — name them backwards to reverse). MOVE changes WHAT a to-do belongs to; to " +
@@ -1109,8 +1255,12 @@ export function registerWriteCommands(program) {
     });
     addWriteFlags(todo
         .command("delete <uuid>")
-        .description("Move a to-do to the Trash (recover with `things todo restore`). Not available " +
-        "for repeating to-dos.")).action(async (uuid, opts) => {
+        .description("Move a to-do to the Trash (recover with `things todo restore`). Deleting a repeating " +
+        "series' TEMPLATE is allowed and ends the series: it stops generating new occurrences " +
+        "and its existing occurrences are left in place (the result names how many, and the " +
+        "current one). That cannot be undone here — the series comes back only via Put Back " +
+        "in the Things app's Trash — so no undo token is returned. Deleting a single " +
+        "occurrence leaves the series running.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.deleteTodo(uuid, writeOptionsFrom(opts)));
     });
     addWriteFlags(todo
@@ -1123,7 +1273,7 @@ export function registerWriteCommands(program) {
     addWriteFlags(todo
         .command("clear-reminder <uuid>")
         .description("Clear a to-do's time-of-day reminder, keeping its scheduled date. With the proxy " +
-        "shortcuts installed (`things setup shortcuts`) this is in place, and is the only " +
+        "shortcuts installed (`things setup`) this is in place, and is the only " +
         "way for a repeating to-do; otherwise a date-scheduled to-do is cleared by a brief " +
         "re-schedule through Today. Reversible with `things undo`.")).action(async (uuid, opts) => {
         if (opIdCompoundRefused(opts, "clear-reminder"))
@@ -1145,7 +1295,9 @@ export function registerWriteCommands(program) {
         .description("Turn a plain to-do into a repeating one. A disposable copy is promoted and the " +
         "ORIGINAL is moved to the Trash — so `things undo` reverses it (it removes the new " +
         "series and restores the original). The new template's uuid is printed. Set the rule " +
-        "with the flags below; see `things help repeating`.")
+        "with the flags below; see `things help repeating`. Each re-run makes ANOTHER series, " +
+        "so pass --op-id on a retry: a resubmission with the same key replays the first " +
+        "result instead of making a second series.")
         .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
         .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
         const frequency = opts["frequency"];
@@ -1201,11 +1353,11 @@ export function registerWriteCommands(program) {
     // silently re-targets a different heading after any reorder). An empty-string
     // title selects a titleless heading; duplicates fail closed with uuid
     // candidates.
-    addPlacementFlags(addWriteFlags(project
+    addPlacementFlags(addCompoundWriteFlags(project
         .command("add-heading <project> <title>")
         .description("Create a heading inside an existing project; its uuid is printed on success. The " +
         "project must name an existing project (uuid or unique name). Uses the Things proxy " +
-        "shortcuts — run `things setup shortcuts` once first. By default the heading is " +
+        "shortcuts — run `things setup` once first. By default the heading is " +
         "appended; a placement flag positions it among the project's headings (that leg " +
         "needs `things config set allow-experimental true`)."))).action(async (projectRef, title, opts) => {
         if (countPlacementFlags(opts) > 1) {
@@ -1230,7 +1382,7 @@ export function registerWriteCommands(program) {
             return c.write.renameHeading(h.uuid, opts["to"], writeOptionsFrom(opts));
         });
     });
-    addWriteFlags(project
+    addCompoundWriteFlags(project
         .command("archive-heading <project> <heading>")
         .description("Archive a heading — it leaves the active project view (reversible with " +
         "`things project unarchive-heading`). This is the preferred way to retire a heading: " +
@@ -1253,7 +1405,7 @@ export function registerWriteCommands(program) {
             return outcome.heading;
         });
     });
-    addWriteFlags(project
+    addCompoundWriteFlags(project
         .command("unarchive-heading <project> <heading>")
         .description("Un-archive a heading. --restore-children also reopens the children the archive " +
         "cascade resolved with it (identified by matching resolution timestamps; a " +
@@ -1284,14 +1436,18 @@ export function registerWriteCommands(program) {
             return c.write.run("project.promote-heading", { uuid: h.uuid }, writeOptionsFrom(opts));
         });
     });
-    addPlacementFlags(addWriteFlags(project
+    addPlacementFlags(addDriveGuiFlag(addWriteFlags(project
         .command("move-heading <project> <headings...>")
         .description("Reposition one or more of a project's headings as an ordered block — the selection " +
-        "order is the resulting order, and each heading's to-dos follow it. Pass exactly one " +
-        "placement: --first, --last, --before-heading <sel>, or --after-heading <sel>. Each " +
-        `<heading> is a ${HEADING_SEL_HELP}. Reordering headings rides the same experimental ` +
-        "surface as `things reorder` — enable it once with `things config set " +
-        "allow-experimental true`."))).action(async (projectRef, sels, opts) => {
+        "order is the resulting order, and each heading's to-dos follow it. Pass exactly " +
+        "one placement: --first, --last, --before-heading <sel>, or --after-heading <sel>. " +
+        `Each <heading> is a ${HEADING_SEL_HELP}. GUI-ONLY: Things offers heading order as ` +
+        "keyboard shortcuts on a selected heading row and nowhere else, so this drives the " +
+        "app — enable it once with `things config set ui-enabled true` and pass " +
+        "--dangerously-drive-gui. It moves one heading one slot at a time, re-reading the " +
+        "order after each step. Completed and canceled headings are not shown in the " +
+        "project view, so they are skipped over and keep their place in the list; naming " +
+        "one as a heading to move or as an anchor is refused.")))).action(async (projectRef, sels, opts) => {
         if (countPlacementFlags(opts) !== 1) {
             usageError(opts, "pass exactly one of --first / --last / --before-heading / --after-heading");
             return;
@@ -1312,8 +1468,9 @@ export function registerWriteCommands(program) {
         "destination. GUI-ONLY: it drives the heading row's ellipsis Move… menu, so enable it " +
         "once with `things config set ui.enabled true` and pass --dangerously-drive-gui. Fails " +
         "closed when the heading title is shared by another heading in the project, or the " +
-        "destination title by another project (the drive addresses both by title). No undo — " +
-        "move it back to reverse."))).action(async (projectRef, sel, opts) => {
+        "destination title by another project (both are addressed by title), and when the " +
+        "destination project is completed or canceled — reopen it first. No undo — move it " +
+        "back to reverse."))).action(async (projectRef, sel, opts) => {
         await runWrite(opts, (c) => {
             const proj = c.resolve.project(projectRef);
             const dest = c.resolve.project(String(opts["to"]));
@@ -1374,12 +1531,13 @@ export function registerWriteCommands(program) {
         "moved to the Trash — so `things undo` reverses it (it removes the new series and " +
         "restores the original). Refuses a project that holds a nested repeating template. An " +
         "Anytime project with no area is moved to Someday first (a cleanup-free intermediate " +
-        "step, shown in --dry-run). Set the rule with the flags below; see `things help repeating`.")
+        "step, shown in --dry-run). Set the rule with the flags below; see `things help " +
+        "repeating`. Each re-run makes ANOTHER series, so pass --op-id on a retry: a " +
+        "resubmission with the same key replays the first result instead of making a second " +
+        "series.")
         .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
         .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
         const frequency = opts["frequency"];
-        if (opIdCompoundRefused(opts, "project make-repeating"))
-            return;
         await runWrite(opts, (c) => c.write.makeRepeatingProject(uuid, {
             frequency,
             interval: Number(opts["interval"]),
@@ -1392,18 +1550,22 @@ export function registerWriteCommands(program) {
         "is created (notes/area/when/deadline/child to-dos) and PERSISTS even if the promote " +
         "refuses; then it is promoted (which drives the GUI). Give --area to place it, or omit " +
         "it to create in Someday. The new repeating project's uuid is printed; `things undo` " +
-        "removes the created series (trash-both).")
-        .option("--notes <text>", "notes body")
+        "removes the created series (trash-both). Each re-run makes ANOTHER series, so pass " +
+        "--op-id on a retry: a resubmission with the same key replays the first result " +
+        "instead of making a second series.")
+        .option("--notes <text>", `notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--area <ref>", "destination area (uuid or unique name)")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
-        .option("--deadline <date>", "YYYY-MM-DD")
+        .option("--deadline <date>", "YYYY-MM-DD — deadlines EVERY occurrence: each starts (deadline − --when) days " +
+        "before its own deadline (needs a concrete --when, on or before the deadline; " +
+        "not available with --after-completion)")
         .option("--todo <title>", "initial child to-do (repeatable)", collect, [])
         .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
         .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (title, opts) => {
         const todos = opts["todo"];
         const area = containerRef(opts["area"]);
         const frequency = opts["frequency"];
-        if (opIdCompoundRefused(opts, "project add-repeating"))
+        if (!(await resolveNotesStdin(opts)))
             return;
         await runWrite(opts, (c) => c.write.addRepeatingProject({
             title,
@@ -1420,8 +1582,10 @@ export function registerWriteCommands(program) {
         .description("Create a to-do and turn it into a repeating series in ONE call. Two legs: the to-do is " +
         "created (notes/tags/when/deadline/reminder/checklist/--created-at) and PERSISTS even " +
         "if the promote refuses; then it is promoted (which drives the GUI). The new repeating " +
-        "template's uuid is printed; `things undo` removes the created series (trash-both).")
-        .option("--notes <text>", "notes body")
+        "template's uuid is printed; `things undo` removes the created series (trash-both). " +
+        "Each re-run makes ANOTHER series, so pass --op-id on a retry: a resubmission with " +
+        "the same key replays the first result instead of making a second series.")
+        .option("--notes <text>", `notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
         .option("--reminder <time>", "HH:mm reminder (needs a schedulable --when)")
         .option("--deadline <date>", "YYYY-MM-DD — deadlines EVERY occurrence: each starts (deadline − --when) days " +
@@ -1435,7 +1599,7 @@ export function registerWriteCommands(program) {
         .option("--project <ref>", "destination project (uuid or unique name)")
         .option("--area <ref>", "destination area (uuid or unique name)")
         .option("--heading <title>", "existing heading inside the target project")
-        .option("--created-at <iso>", "born with this creation timestamp (ISO date or datetime; a date is noon in the effective zone)")
+        .option("--created-at <iso>", `born with this creation timestamp (${RESOLUTION_DATE_FORMAT})`)
         .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
         .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (title, opts) => {
         const tags = opts["tag"];
@@ -1443,7 +1607,7 @@ export function registerWriteCommands(program) {
         const projectRef = containerRef(opts["project"]);
         const area = containerRef(opts["area"]);
         const frequency = opts["frequency"];
-        if (opIdCompoundRefused(opts, "todo add-repeating"))
+        if (!(await resolveNotesStdin(opts)))
             return;
         await runWrite(opts, (c) => c.write.addRepeatingTodo({
             title,
@@ -1468,15 +1632,17 @@ export function registerWriteCommands(program) {
         .description("Create a project; its uuid is printed on success. Give --todo (repeatable) to " +
         "seed it with child to-dos in the same call — the quick way to stand up a new " +
         "project skeleton.")
-        .option("--notes <text>", "notes body")
+        .option("--notes <text>", `notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--area <ref>", "destination area (uuid or unique name)")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
         .option("--deadline <date>", "YYYY-MM-DD")
         .option("--todo <title>", "initial child to-do, repeatable (seeds the new project)", collect, [])
-        .option("--created-at <iso>", "born with this creation timestamp (ISO date or datetime; a date is noon in the effective zone)")
+        .option("--created-at <iso>", `born with this creation timestamp (${RESOLUTION_DATE_FORMAT})`)
         .option("--completed-at <iso>", "born completed (in the Logbook) with this completion timestamp; cannot seed open child to-dos (§5b)")).action(async (title, opts) => {
         const todos = opts["todo"];
         const area = containerRef(opts["area"]);
+        if (!(await resolveNotesStdin(opts)))
+            return;
         await runWrite(opts, (c) => c.write.addProject({
             title,
             ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
@@ -1496,7 +1662,7 @@ export function registerWriteCommands(program) {
         "--notes). --reminder needs --when today|evening|YYYY-MM-DD; when re-scheduling " +
         "WITHOUT --reminder an existing reminder is auto-preserved."))
         .option("--title <text>", "new title")
-        .option("--notes <text>", "replace notes")
+        .option("--notes <text>", `replace the notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--append-notes <text>", "append to existing notes (newline-joined)")
         .option("--prepend-notes <text>", "prepend to existing notes (newline-joined)")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
@@ -1504,39 +1670,17 @@ export function registerWriteCommands(program) {
         .option("--clear-reminder", "clear the reminder (works while scheduled today|evening)")
         .option("--deadline <date>", "YYYY-MM-DD")
         .option("--clear-deadline", "remove the deadline")
-        .option("--created-at <iso>", "rewrite the creation timestamp (ISO date or datetime; a date is noon in the effective zone); status-safe")
+        .option("--created-at <iso>", `rewrite the creation timestamp (${RESOLUTION_DATE_FORMAT}); status-safe`)
         .option("--completed-at <iso>", "rewrite the completion timestamp of an already-resolved project (a canceled one stays canceled); open projects are refused — use complete/cancel")
         .action(async (uuid, opts) => {
-        const notesModes = ["notes", "appendNotes", "prependNotes"].filter((k) => opts[k] !== undefined);
-        if (notesModes.length > 1) {
-            usageError(opts, "--notes, --append-notes, --prepend-notes are exclusive");
+        if (!(await resolveNotesStdin(opts)))
             return;
-        }
-        if (opts["reminder"] !== undefined && opts["clearReminder"] === true) {
-            usageError(opts, "pass at most one of --reminder / --clear-reminder");
+        const built = buildUpdatePatch(opts, CLI_UPDATE_LABELS);
+        if (built.kind === "error") {
+            usageError(opts, built.message);
             return;
         }
-        if (!whenSugarOk(opts))
-            return;
-        await runWrite(opts, (c) => c.write.updateProject(uuid, {
-            ...(opts["title"] !== undefined && { title: opts["title"] }),
-            ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
-            ...(opts["appendNotes"] !== undefined && {
-                appendNotes: opts["appendNotes"],
-            }),
-            ...(opts["prependNotes"] !== undefined && {
-                prependNotes: opts["prependNotes"],
-            }),
-            ...(opts["when"] !== undefined && { when: opts["when"] }),
-            ...(opts["reminder"] !== undefined && { reminder: opts["reminder"] }),
-            ...(opts["clearReminder"] === true && { reminder: null }),
-            ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
-            ...(opts["clearDeadline"] === true && { deadline: null }),
-            ...(opts["createdAt"] !== undefined && { createdAt: opts["createdAt"] }),
-            ...(opts["completedAt"] !== undefined && {
-                completedAt: opts["completedAt"],
-            }),
-        }, writeOptionsFrom(opts)));
+        await runWrite(opts, (c) => c.write.updateProject(uuid, built.patch, writeOptionsFrom(opts)));
     });
     addCreateTagsFlag(addWriteFlags(project
         .command("tags <ref>")
@@ -1556,7 +1700,7 @@ export function registerWriteCommands(program) {
             ? c.write.setProjectTags(uuid, set, writeOptionsFrom(opts, createTagsExtra(opts)))
             : c.write.addProjectTags(uuid, add ?? [], writeOptionsFrom(opts, createTagsExtra(opts))));
     });
-    addPositionFlags(addWriteFlags(project
+    addPositionFlags(addCompoundWriteFlags(project
         .command("move <refs...>")
         .description("Move one or more projects as an ordered block (argument order = resulting order). " +
         "Pass one destination: --to-area (uuid or unique name) or --no-area (leave the " +
@@ -1594,7 +1738,7 @@ export function registerWriteCommands(program) {
         "canceled via the certified flip legs (multi-leg, disclosed); it is refused while the " +
         "project still has open children.")
         .requiredOption("--children <policy>", "require-resolved (error if open to-dos remain) | auto-cancel (cancel them too)")
-        .option("--completed-at <iso>", "completion timestamp (ISO date or datetime; a date is noon in the effective zone)")).action(async (uuid, opts) => {
+        .option("--completed-at <iso>", `completion timestamp (${RESOLUTION_DATE_FORMAT})`)).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.cancelProject(uuid, {
             children: opts.children,
             ...(opts["completedAt"] !== undefined && {
@@ -1602,7 +1746,7 @@ export function registerWriteCommands(program) {
             }),
         }, writeOptionsFrom(opts)));
     });
-    addWriteFlags(project
+    addCompoundWriteFlags(project
         .command("reopen <ref>")
         .description("Reopen a completed/canceled project (target by uuid or unique name). Its children " +
         "stay completed/canceled unless " +
@@ -1613,9 +1757,10 @@ export function registerWriteCommands(program) {
         if (opIdCompoundRefused(opts, "project reopen"))
             return;
         const started = Date.now();
+        const { openClient, endInvocation } = beginWriteInvocation(opts.json === true, started);
         let client = null;
         try {
-            client = openThings(opts.db ? { dbPath: opts.db } : {});
+            client = openClient(opts.db);
             const outcome = await client.write.reopenProject(uuid, {
                 ...writeOptionsFrom(opts),
                 ...(opts.restoreChildren === true && { restoreChildren: true }),
@@ -1649,6 +1794,7 @@ export function registerWriteCommands(program) {
         }
         finally {
             client?.close();
+            endInvocation();
         }
     });
     addWriteFlags(project
@@ -1686,7 +1832,7 @@ export function registerWriteCommands(program) {
         "open to-dos, so an explicit --children policy is required. --completed-at sets the " +
         "completion timestamp and backdates it (multi-leg, disclosed).")
         .requiredOption("--children <policy>", "require-resolved (error if open to-dos remain) | auto-complete (complete them too)")
-        .option("--completed-at <iso>", "completion timestamp (ISO date or datetime; a date is noon in the effective zone)")).action(async (uuid, opts) => {
+        .option("--completed-at <iso>", `completion timestamp (${RESOLUTION_DATE_FORMAT})`)).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.completeProject(uuid, {
             children: opts.children,
             ...(opts["completedAt"] !== undefined && {
@@ -1697,7 +1843,10 @@ export function registerWriteCommands(program) {
     addWriteFlags(project
         .command("delete <ref>")
         .description("Move a project (target by uuid or unique name) to the Trash; its children go with " +
-        "it (recover with `things project restore`).")).action(async (uuid, opts) => {
+        "it (recover with `things project restore`). Deleting a repeating series' TEMPLATE is " +
+        "allowed and ends the series: it stops generating new occurrences and its existing " +
+        "occurrences are left in place. That cannot be undone here — the series comes back " +
+        "only via Put Back in the Things app's Trash — so no undo token is returned.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.deleteProject(uuid, writeOptionsFrom(opts)));
     });
     const area = group(program, "area", "Area-scoped operations");
@@ -1867,9 +2016,11 @@ export function registerWriteCommands(program) {
         .description("Run MANY mutations from JSONL (file, or stdin when omitted/'-'): one op per line, " +
         '{"op": "<kind>", "params": {...}, "options": {...}} — see `things capabilities` for ' +
         "op kinds and params. Ops run sequentially and independently — NO transactions; a " +
-        "failure does not roll back earlier ops. A statically-invalid line (bad shape, unknown " +
-        "op, a $ref to an undeclared/forward tempId, a duplicate tempId) refuses the WHOLE " +
-        "batch before anything runs, naming every bad line. Otherwise ops run and per-op " +
+        "failure does not roll back earlier ops. A statically-invalid line (unknown op, an " +
+        "unknown or wrongly-typed param, a $ref to an undeclared/forward tempId, a duplicate " +
+        "tempId) refuses the WHOLE batch before anything runs, naming every bad line and the " +
+        'field it names. A container param takes an object — {"project": {"uuid": "…"}} — ' +
+        "never a bare string. Otherwise ops run and per-op " +
         "results stream as JSONL. Per-op " +
         "options carry the confirmation flags (acknowledgeChecklistReset, " +
         "acknowledgeProjectReopen, dangerouslyPermanent, acknowledgeTagSubtree). " +
@@ -1882,12 +2033,18 @@ export function registerWriteCommands(program) {
         "re-created (put an opId on EVERY line so a stopped batch can be resubmitted verbatim " +
         "to resume). The trailing summary line adds `tempIdMapping` (handle → uuid) and " +
         "`undoToken` — undo the WHOLE batch with `things undo --txn <undoToken>`. " +
+        "TIMELINE: --preserve-modified applies to every line (each line may override it with its " +
+        'own `"options": {"preserveModified": true|false}`), so a bulk re-tag stays off the ' +
+        "modification-date timeline under one undo token; each line's result then carries " +
+        "`preservedModified` (and `preserveFailures` for any restore that did not land). " +
         "By DEFAULT a runtime failure STOPS the batch (later lines reported not-run, with resume " +
         "guidance in the summary); --continue-on-error runs past failures. --dry-run plans " +
         "everything without executing. Exit (worst failure wins): 0 all ok · 3 any " +
         "verify-failed/invalid · 4 any blocked · 5 any drift-blocked · 6 any unsupported.")
         .option("--dry-run", "plan every op; execute nothing")
         .option("--continue-on-error", "run past a failed op instead of stopping (default: stop)")
+        .option("--preserve-modified", `${PRESERVE_MODIFIED_HELP} Applies to EVERY line; a line that sets its own ` +
+        '`"options": {"preserveModified": false}` opts back onto the timeline.')
         .option("--json", "JSONL results + summary on stdout (also the default)")
         .option("--db <path>", "explicit database path")
         .option("--actor <name>", "author name recorded for the whole batch")
@@ -1923,12 +2080,18 @@ export function registerWriteCommands(program) {
                 });
             }
         }
+        // batch streams JSONL regardless of --json, so the interrupt guard is
+        // armed machine-readable.
+        const { openClient, endInvocation } = beginWriteInvocation(true, Date.now());
         let client = null;
         try {
-            client = openThings(opts.db ? { dbPath: opts.db } : {});
+            client = openClient(opts.db);
             const batchResult = await client.write.batch(ops, {
                 ...(opts.dryRun !== undefined && { dryRun: opts.dryRun }),
                 ...(opts["continueOnError"] === true && { continueOnError: true }),
+                // Run-level default for every line; a line's own explicit
+                // `options.preserveModified` outranks it (src/write/batch.ts).
+                ...(opts.preserveModified === true && { preserveModified: true }),
                 ...(opts.actor !== undefined && { actor: opts.actor }),
             }, (r) => {
                 const pre = preInvalid.find((p) => p.index === r.index);
@@ -1960,6 +2123,7 @@ export function registerWriteCommands(program) {
         }
         finally {
             client?.close();
+            endInvocation();
         }
     });
     program
@@ -2007,9 +2171,12 @@ export function registerWriteCommands(program) {
             usageError(opts, "--txn cannot be combined with --last or --by");
             return;
         }
+        // undo streams JSONL regardless of --json, so the interrupt guard is armed
+        // machine-readable (each inverse is a real write, GUI drives included).
+        const { openClient, endInvocation } = beginWriteInvocation(true, Date.now());
         let client = null;
         try {
-            client = openThings(opts.db ? { dbPath: opts.db } : {});
+            client = openClient(opts.db);
             const items = await client.write.undo({
                 ...(opts["last"] !== undefined && { last: Number(opts["last"]) }),
                 ...(opts["by"] !== undefined && { by: String(opts["by"]) }),
@@ -2063,9 +2230,10 @@ export function registerWriteCommands(program) {
         }
         finally {
             client?.close();
+            endInvocation();
         }
     });
-    addReorderPositionFlags(addDriveGuiFlag(addWriteFlags(program
+    addReorderPositionFlags(addDriveGuiFlag(addCompoundWriteFlags(program
         .command("reorder <refs...>")
         .description("The ONE reorder verb — rearrange to-dos, projects, headings, OR sidebar areas IN " +
         "PLACE (REARRANGES, never changes membership; to change what an item belongs to use " +
@@ -2077,8 +2245,9 @@ export function registerWriteCommands(program) {
         "EARLIEST one's current slot; --start/--end/--before/--after position the block. A " +
         "Today/Evening member also has an index slot in its container, so a set sharing BOTH " +
         "axes is ambiguous — pass --in to say which. HEADINGS: same-project heading " +
-        "re-ranking runs the native heading-block wire; an archived heading is reorderable " +
-        "but repositioning it brings it back to open (disclosed). AREAS: this drives the " +
+        "re-ranking drives the local Things app (keyboard shortcuts on the heading row) " +
+        "and covers the open headings only — a completed or canceled heading is not shown " +
+        "in the project view, so it is skipped over and cannot be moved. AREAS: this drives the " +
         "local Things app (sidebar drag). `things area reorder` and `things project " +
         "move-heading` remain as kind-specific spellings.")
         .option("--in <target>", "to-dos/projects only — name the axis to reorder on: today | evening | anytime | " +