things-api 0.19.0 → 0.19.1

package/dist/cli/commands/writes.js

@@ -11,7 +11,7 @@ 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, 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, 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";
 /**
@@ -43,11 +43,12 @@ function addWriteFlags(cmd, capability = {}) {
         .addOption(opId);
 }
 /**
- * The write flags for a multi-leg 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
+ * 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.
+ * 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. */
@@ -60,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)
@@ -216,10 +222,15 @@ function splitCsv(value) {
         .filter((s) => s !== "");
 }
 /**
- * Open a CLI write invocation: install the dev-mode step-timeline trace and arm
- * the signal-safe interrupt guard (TRACE1, #487). Returns the teardown for the
- * driver's `finally` — it closes the trace with the final exit code, then
- * disarms the guard so a signal during teardown/reads emits nothing.
+ * 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)
@@ -228,6 +239,15 @@ function splitCsv(value) {
  * 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.
  */
@@ -237,22 +257,28 @@ function beginWriteInvocation(json, startedAt) {
         version: CLI_VERSION,
         isDev: isDevVersion(CLI_VERSION),
     });
-    armInterrupt(json);
-    return () => {
-        trace(() => ({
-            phase: "invocation-end",
-            exitCode: process.exitCode ?? 0,
-            elapsedMs: Date.now() - startedAt,
-        }));
-        disarmInterrupt();
-        closeCliTrace();
+    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 endInvocation = beginWriteInvocation(opts.json === true, started);
+    const { openClient, endInvocation } = beginWriteInvocation(opts.json === true, started);
     let client = null;
     const meta = (client_) => {
         let dbVersion = null;
@@ -267,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));
     }
@@ -497,7 +523,7 @@ async function runMoveCmd(opts, fn) {
         return;
     }
     const started = Date.now();
-    const endInvocation = beginWriteInvocation(opts.json === true, started);
+    const { openClient, endInvocation } = beginWriteInvocation(opts.json === true, started);
     let client = null;
     const meta = () => {
         let dbVersion = null;
@@ -510,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) {
@@ -757,10 +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 endInvocation = beginWriteInvocation(opts.json === true, Date.now());
+    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 }),
@@ -889,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) => {
@@ -1012,7 +1038,7 @@ 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 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 " +
@@ -1059,7 +1085,7 @@ export function registerWriteCommands(program) {
             "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)));
         });
@@ -1269,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"];
@@ -1408,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;
@@ -1436,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"]));
@@ -1492,31 +1525,34 @@ export function registerWriteCommands(program) {
             await runWrite(opts, (c) => c.write.run(op, { uuid }, writeOptionsFrom(opts)));
         });
     }
-    addDriveGuiFlag(addRepeatRuleFlags(addCompoundWriteFlags(project
+    addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(project
         .command("make-repeating <ref>")
         .description("Turn a project 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). 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"]),
             ...repeatRuleFlagsFromOpts(opts, frequency),
         }, writeOptionsFrom(opts)));
     });
-    addDriveGuiFlag(addRepeatCalendarFlags(addCompoundWriteFlags(project
+    addDriveGuiFlag(addRepeatCalendarFlags(addWriteFlags(project
         .command("add-repeating <title>")
         .description("Create a project and turn it into a repeating series in ONE call. Two legs: the project " +
         "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).")
+        "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")
@@ -1529,8 +1565,6 @@ export function registerWriteCommands(program) {
         const todos = opts["todo"];
         const area = containerRef(opts["area"]);
         const frequency = opts["frequency"];
-        if (opIdCompoundRefused(opts, "project add-repeating"))
-            return;
         if (!(await resolveNotesStdin(opts)))
             return;
         await runWrite(opts, (c) => c.write.addRepeatingProject({
@@ -1543,12 +1577,14 @@ export function registerWriteCommands(program) {
             ...addRepeatingRuleFieldsFromOpts(opts, frequency, Number(opts["interval"])),
         }, writeOptionsFrom(opts)));
     });
-    addDriveGuiFlag(addRepeatCalendarFlags(addCompoundWriteFlags(todo
+    addDriveGuiFlag(addRepeatCalendarFlags(addWriteFlags(todo
         .command("add-repeating <title>")
         .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).")
+        "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)")
@@ -1563,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"];
@@ -1571,8 +1607,6 @@ export function registerWriteCommands(program) {
         const projectRef = containerRef(opts["project"]);
         const area = containerRef(opts["area"]);
         const frequency = opts["frequency"];
-        if (opIdCompoundRefused(opts, "todo add-repeating"))
-            return;
         if (!(await resolveNotesStdin(opts)))
             return;
         await runWrite(opts, (c) => c.write.addRepeatingTodo({
@@ -1603,7 +1637,7 @@ export function registerWriteCommands(program) {
         .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"]);
@@ -1636,7 +1670,7 @@ 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) => {
         if (!(await resolveNotesStdin(opts)))
@@ -1704,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 && {
@@ -1723,10 +1757,10 @@ export function registerWriteCommands(program) {
         if (opIdCompoundRefused(opts, "project reopen"))
             return;
         const started = Date.now();
-        const endInvocation = beginWriteInvocation(opts.json === true, started);
+        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 }),
@@ -1798,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 && {
@@ -2048,10 +2082,10 @@ export function registerWriteCommands(program) {
         }
         // batch streams JSONL regardless of --json, so the interrupt guard is
         // armed machine-readable.
-        const endInvocation = beginWriteInvocation(true, Date.now());
+        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 }),
@@ -2139,10 +2173,10 @@ export function registerWriteCommands(program) {
         }
         // undo streams JSONL regardless of --json, so the interrupt guard is armed
         // machine-readable (each inverse is a real write, GUI drives included).
-        const endInvocation = beginWriteInvocation(true, Date.now());
+        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"]) }),
@@ -2211,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 | " +