things-api 0.15.0 → 0.17.0

package/dist/cli/commands/writes.js

@@ -1,6 +1,9 @@
 import { readFileSync } from "node:fs";
-import { addRepeatRuleFlags, repeatRuleFlagsFromOpts } from "./repeat-flags.js";
-import { aggregateExitCode, blockedCode, capabilitiesTable, ClockError, describeConfig, errorEnvelope, ExitCode, getConfigKey, mutationWireData, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
+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, installCliTrace, getConfigKey, mutationWireData, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, trace, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
 import { usageError } from "../read-driver.js";
 import { dim } from "../style.js";
 function addWriteFlags(cmd) {
@@ -8,6 +11,12 @@ function addWriteFlags(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("--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")
@@ -88,6 +97,7 @@ function writeOptionsFrom(opts, extra = {}) {
         ...(opts.actor !== undefined && { actor: opts.actor }),
         ...(opts.dangerouslyDriveGui === true && { dangerouslyDriveGui: true }),
         ...(opts.opId !== undefined && { opId: opts.opId }),
+        ...(opts.preserveModified === true && { preserveModified: true }),
         ...extra,
     };
 }
@@ -138,7 +148,12 @@ function headingPlacement(c, projectUuid, opts) {
 /** Add the mandatory GUI-drive acknowledgement to a ui-vector command. */
 function addDriveGuiFlag(cmd) {
     return cmd.option("--dangerously-drive-gui", "required: visibly drives the Things app to make a change it offers nowhere else; " +
-        "also needs `things config set ui-enabled true`");
+        "also needs `things config set ui-enabled true`. Driving the app can take over a " +
+        "minute on a large database, so allow a generous timeout (180s or more) — if your own " +
+        "timeout stops the command first you get empty output, not a result. A timeout or empty " +
+        "output is not a success: the change may still have landed, so re-check with " +
+        "`things show <ref>` before retrying, and never fire an identical retry (it can duplicate " +
+        "the change) — stop and report if the state is wrong or unclear");
 }
 function collect(value, previous) {
     return [...previous, value];
@@ -179,6 +194,16 @@ 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).
+    installCliTrace({
+        argv: process.argv.slice(1),
+        version: CLI_VERSION,
+        isDev: isDevVersion(CLI_VERSION),
+    });
+    armInterrupt(opts.json === true);
     let client = null;
     const meta = (client_) => {
         let dbVersion = null;
@@ -232,7 +257,54 @@ 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();
+    }
+}
+/**
+ * TTY disclosure for `--preserve-modified` on a verified ok result: a dim line
+ * naming how many pre-existing rows' modification date was restored (kept off
+ * the `changes`/watch timeline), plus a stderr warning per row the best-effort
+ * restore could not neutralize. Silent when the flag did no work (the field is
+ * absent — a pure create, or an already-silent op).
+ */
+function emitPreserveNote(result) {
+    if (result.preservedModified === undefined)
+        return;
+    const failed = result.preserveFailures ?? [];
+    const tail = failed.length > 0 ? `; ${failed.length} could not be restored (see warnings)` : "";
+    process.stdout.write(dim(`  preserved modification date on ${result.preservedModified} item(s) — kept off the changes timeline${tail}\n`));
+    for (const f of failed) {
+        process.stderr.write(`warning: preserve-modified: ${f.uuid}: ${f.detail}\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,
+ * so an operator (or an agent reading the human render) sees an emptied container
+ * at a glance. Silent when neither arm applies (the field is absent).
+ */
+function emitContextNote(result) {
+    const context = result.context;
+    if (context === undefined)
+        return;
+    const parts = [];
+    if (context.project !== undefined) {
+        parts.push(`project "${context.project.title}": ${context.project.remainingOpen} open remaining`);
+    }
+    if (context.today !== undefined) {
+        parts.push(`today: ${context.today.remainingOpen} open remaining`);
     }
+    if (parts.length > 0)
+        process.stdout.write(dim(`  ${parts.join("; ")}\n`));
 }
 function emitResult(result, opts, meta) {
     switch (result.kind) {
@@ -265,6 +337,8 @@ 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`);
+                emitPreserveNote(result);
+                emitContextNote(result);
             }
             process.exitCode = ExitCode.Ok;
             return;
@@ -680,6 +754,11 @@ function group(program, name, description) {
     return program.command(name).description(description);
 }
 const containerRef = (value) => value === undefined ? undefined : { uuid: value, title: value };
+/** The clone-specific args (`--title` / `--preserve-created`) for todo/project clone. */
+const cloneArgs = (opts) => ({
+    ...(opts["title"] !== undefined && { title: opts["title"] }),
+    ...(opts["preserveCreated"] === true && { preserveCreated: true }),
+});
 export function registerWriteCommands(program) {
     const todo = group(program, "todo", "To-do–scoped operations");
     addCreateTagsFlag(addWriteFlags(todo
@@ -921,6 +1000,21 @@ export function registerWriteCommands(program) {
         "available for repeating to-dos.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.duplicateTodo(uuid, writeOptionsFrom(opts)));
     });
+    addDriveGuiFlag(addWriteFlags(todo
+        .command("clone <uuid>")
+        .description("Clone a to-do — a faithful content copy (title, notes, tags, when, reminder, deadline, " +
+        "checklist items and their checked state, container, and completed/canceled state with " +
+        "the exact original timestamp). The clone is a new capture: a new uuid, created now, at " +
+        "its container's usual position; the clone's uuid is printed on success. Refuses a " +
+        "trashed source (restore it first). A repeating template is cloned as a NEW repeating " +
+        "series (its content plus the source's rule, minted fresh — no instances copied); this " +
+        "drives the app (requires --dangerously-drive-gui) and refuses a rule the Repeat dialog " +
+        "cannot express. Undo trashes the clone (a template clone trashes the new series).")
+        .option("--title <text>", "give the clone a different title (default: the source's title)")
+        .option("--preserve-created", "copy the source's creation date onto the clone (minute resolution) instead of now"))).action(async (uuid, opts) => {
+        const clone = cloneArgs(opts);
+        await runWrite(opts, (c) => c.write.cloneTodo(uuid, clone, writeOptionsFrom(opts)));
+    });
     addCreateTagsFlag(addWriteFlags(todo
         .command("tags <uuid>")
         .description("Set or extend a to-do's tags. --set REPLACES the full tag set (an empty value " +
@@ -1042,36 +1136,39 @@ export function registerWriteCommands(program) {
     // --- ui vector: GUI-driven transforms (two-key gated) --------------------
     const REPEAT_FREQ_HELP = "daily | weekly | monthly | yearly";
     const REPEAT_INTERVAL_HELP = "every N units (1–99)";
-    for (const [verb, op, desc] of [
-        [
-            "make-repeating",
-            "todo.make-repeating",
-            "Turn a plain to-do into a repeating one. This REPLACES the to-do with a new repeating " +
-                "series — the original disappears and a fresh recurring item takes its place " +
-                "(cannot be undone). Set the rule with the flags below; see `things help repeating`.",
-        ],
-        [
-            "reschedule-repeat",
-            "todo.reschedule-repeat",
-            "Change an existing repeating to-do's rule in place (the item keeps its identity). Set the " +
-                "new rule with the flags below; see `things help repeating`. `things undo` restores the " +
-                "previous rule.",
-        ],
-    ]) {
-        addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(todo
-            .command(`${verb} <uuid>`)
-            .description(desc)
-            .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
-            .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
-            const frequency = opts["frequency"];
-            await runWrite(opts, (c) => c.write.run(op, {
-                uuid,
-                frequency,
-                interval: Number(opts["interval"]),
-                ...repeatRuleFlagsFromOpts(opts, frequency),
-            }, writeOptionsFrom(opts)));
-        });
-    }
+    // make-repeating is promote-via-clone: a disposable copy is promoted and the
+    // ORIGINAL moves to the Trash, so `things undo` reverses it (removes the new
+    // series and restores the original).
+    addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(todo
+        .command("make-repeating <uuid>")
+        .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`.")
+        .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
+        .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
+        const frequency = opts["frequency"];
+        await runWrite(opts, (c) => c.write.makeRepeatingTodo(uuid, {
+            frequency,
+            interval: Number(opts["interval"]),
+            ...repeatRuleFlagsFromOpts(opts, frequency),
+        }, writeOptionsFrom(opts)));
+    });
+    addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(todo
+        .command("reschedule-repeat <uuid>")
+        .description("Change an existing repeating to-do's rule in place (the item keeps its identity). Set " +
+        "the new rule with the flags below; see `things help repeating`. `things undo` " +
+        "restores the previous rule.")
+        .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
+        .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
+        const frequency = opts["frequency"];
+        await runWrite(opts, (c) => c.write.run("todo.reschedule-repeat", {
+            uuid,
+            frequency,
+            interval: Number(opts["interval"]),
+            ...repeatRuleFlagsFromOpts(opts, frequency),
+        }, writeOptionsFrom(opts)));
+    });
     for (const [verb, op, desc] of [
         [
             "pause-repeat",
@@ -1205,7 +1302,7 @@ export function registerWriteCommands(program) {
             return c.write.moveHeading({ uuid: proj.uuid }, headings, placement, writeOptionsFrom(opts));
         });
     });
-    addWriteFlags(project
+    addDriveGuiFlag(addWriteFlags(project
         .command("move-heading-to-project <project> <heading>")
         .requiredOption("--to <project>", "destination project (uuid or unique title)")
         .description("Move a heading — WITH its to-dos — to a DIFFERENT project. This is the cross-project " +
@@ -1215,14 +1312,14 @@ export function registerWriteCommands(program) {
         "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) => {
+        "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"]));
             return c.write.moveHeadingToProject({ uuid: proj.uuid }, sel, { uuid: dest.uuid }, writeOptionsFrom(opts));
         });
     });
-    addWriteFlags(project
+    addDriveGuiFlag(addWriteFlags(project
         .command("dissolve-heading <project> <heading>")
         .description("Dissolve a heading — remove it but KEEP its to-dos, which become direct children of the " +
         "project (in the same order), NOT trashed. This is the opposite of deleting: nothing is " +
@@ -1230,7 +1327,7 @@ export function registerWriteCommands(program) {
         "Shortcuts heading-delete cascade, which TRASH the children. GUI-ONLY (drives the " +
         "heading row's ellipsis Delete): 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. No undo — re-create the heading and move the to-dos back.")).action(async (projectRef, sel, opts) => {
+        "another heading in the project. No undo — re-create the heading and move the to-dos back."))).action(async (projectRef, sel, opts) => {
         await runWrite(opts, (c) => {
             const proj = c.resolve.project(projectRef);
             const h = c.resolve.heading(proj.uuid, sel);
@@ -1272,11 +1369,11 @@ export function registerWriteCommands(program) {
     }
     addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(project
         .command("make-repeating <ref>")
-        .description("Turn a project into a repeating one. This REPLACES the project with a new repeating " +
-        "series — the original disappears and a fresh recurring project takes its place (its " +
-        "area is kept; cannot be undone). 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`.")
+        .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`.")
         .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
         .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
         const frequency = opts["frequency"];
@@ -1288,30 +1385,73 @@ export function registerWriteCommands(program) {
             ...repeatRuleFlagsFromOpts(opts, frequency),
         }, writeOptionsFrom(opts)));
     });
-    addDriveGuiFlag(addWriteFlags(project
+    addDriveGuiFlag(addRepeatCalendarFlags(addWriteFlags(project
         .command("add-repeating <title>")
-        .description("Create a project and turn it into a repeating series in ONE call. Two operations: the " +
-        "project is created first and PERSISTS even if the make-repeating step 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 on success.")
+        .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).")
         .option("--notes <text>", "notes body")
         .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)", collect, [])
         .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
-        .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP))).action(async (title, opts) => {
+        .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"))
             return;
         await runWrite(opts, (c) => c.write.addRepeatingProject({
             title,
             ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
             ...(area !== undefined && { area }),
+            ...(opts["when"] !== undefined && { when: opts["when"] }),
             ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
             ...(todos.length > 0 && { todos }),
-            frequency: opts["frequency"],
-            interval: Number(opts["interval"]),
+            ...addRepeatingRuleFieldsFromOpts(opts, frequency, Number(opts["interval"])),
+        }, writeOptionsFrom(opts)));
+    });
+    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).")
+        .option("--notes <text>", "notes body")
+        .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")
+        .option("--tag <name>", "tag to attach (repeatable)", collect, [])
+        .option("--checklist-item <title>", "checklist item (repeatable)", collect, [])
+        .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)")
+        .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
+        .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (title, opts) => {
+        const tags = opts["tag"];
+        const checklistItems = opts["checklistItem"];
+        const projectRef = containerRef(opts["project"]);
+        const area = containerRef(opts["area"]);
+        const frequency = opts["frequency"];
+        if (opIdCompoundRefused(opts, "todo add-repeating"))
+            return;
+        await runWrite(opts, (c) => c.write.addRepeatingTodo({
+            title,
+            ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
+            ...(opts["when"] !== undefined && { when: opts["when"] }),
+            ...(opts["reminder"] !== undefined && { reminder: opts["reminder"] }),
+            ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
+            ...(tags.length > 0 && { tags }),
+            ...(checklistItems.length > 0 && { checklistItems }),
+            ...(projectRef !== undefined && { project: projectRef }),
+            ...(area !== undefined && { area }),
+            ...(opts["heading"] !== undefined && { heading: opts["heading"] }),
+            ...(opts["createdAt"] !== undefined && { createdAt: opts["createdAt"] }),
+            ...addRepeatingRuleFieldsFromOpts(opts, frequency, Number(opts["interval"])),
         }, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
@@ -1514,6 +1654,23 @@ export function registerWriteCommands(program) {
         "copy's uuid is printed on success. Not available for repeating projects.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.duplicateProject(uuid, writeOptionsFrom(opts)));
     });
+    addDriveGuiFlag(addWriteFlags(project
+        .command("clone <ref>")
+        .description("Clone a project (target by uuid or unique name) — a faithful content copy: area, " +
+        "headings, headed and root children (one import), notes and deadline, plus " +
+        "logged/canceled children and the project's own completed/canceled state with the " +
+        "exact original timestamps. The clone is a new capture (new uuid, created now); its " +
+        "uuid is printed on success. Refuses a trashed source and a project holding a nested " +
+        "repeating template (named in the refusal). A repeating-template project is cloned as " +
+        "a NEW repeating series (its content plus the source's rule, minted fresh — no " +
+        "instances copied); this drives the app (requires --dangerously-drive-gui) and refuses " +
+        "a rule the Repeat dialog cannot express. Undo trashes the clone and every child it " +
+        "minted (a template clone trashes the new series).")
+        .option("--title <text>", "give the clone a different title (default: the source's title)")
+        .option("--preserve-created", "copy the source's creation date onto the clone (minute resolution) instead of now"))).action(async (uuid, opts) => {
+        const clone = cloneArgs(opts);
+        await runWrite(opts, (c) => c.write.cloneProject(uuid, clone, writeOptionsFrom(opts)));
+    });
     addWriteFlags(project
         .command("complete <ref>")
         .description("Complete a project (target by uuid or unique name). Completing also completes its " +
@@ -1701,23 +1858,27 @@ 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. Per-op results stream as JSONL. Per-op " +
+        "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 " +
+        "results stream as JSONL. Per-op " +
         "options carry the confirmation flags (acknowledgeChecklistReset, " +
         "acknowledgeProjectReopen, dangerouslyPermanent, acknowledgeTagSubtree). " +
         "CHAINING: an op that creates something may carry a `tempId` (a handle like " +
         '"proj1"); a LATER op references that new uuid as "$proj1" in any id/container ' +
         'param (dotted "$proj1.instance"/"$proj1.replaced" reach a repeating op\'s spawned ' +
         "instance / replaced source). A tempId is valid only on a creating op (not tag.add — " +
-        "reference a tag by title) and unique per batch; an unresolved/forward $ref fails just " +
-        "that line. IDEMPOTENCY: a line's `opId` makes resubmission safe — a matching earlier " +
-        "success is reported already-applied, not re-created. The trailing summary line adds " +
-        "`tempIdMapping` (handle → uuid) and `undoToken` — undo the WHOLE batch with " +
-        "`things undo --txn <undoToken>`. " +
-        "--dry-run plans everything without executing; --fail-fast skips the rest after " +
-        "the first failure. Exit (worst failure wins): 0 all ok · 3 any verify-failed/invalid " +
-        "· 4 any blocked · 5 any drift-blocked · 6 any unsupported.")
+        "reference a tag by title) and unique per batch. IDEMPOTENCY: a line's `opId` makes " +
+        "resubmission safe — a matching earlier success is reported already-applied, not " +
+        "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>`. " +
+        "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("--fail-fast", "skip remaining ops after the first failure")
+        .option("--continue-on-error", "run past a failed op instead of stopping (default: stop)")
         .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")
@@ -1758,7 +1919,7 @@ export function registerWriteCommands(program) {
             client = openThings(opts.db ? { dbPath: opts.db } : {});
             const batchResult = await client.write.batch(ops, {
                 ...(opts.dryRun !== undefined && { dryRun: opts.dryRun }),
-                ...(opts["failFast"] === true && { failFast: true }),
+                ...(opts["continueOnError"] === true && { continueOnError: true }),
                 ...(opts.actor !== undefined && { actor: opts.actor }),
             }, (r) => {
                 const pre = preInvalid.find((p) => p.index === r.index);
@@ -1777,6 +1938,10 @@ export function registerWriteCommands(program) {
                     // (undo the whole submission with `things undo --txn <token>`).
                     ...(hasMapping && { tempIdMapping: batchResult.tempIdMapping }),
                     ...(batchResult.undoToken !== undefined && { undoToken: batchResult.undoToken }),
+                    // ADDITIVE: resume guidance when a runtime failure stopped the batch
+                    // (Change 2) — how many lines did not run and whether a verbatim
+                    // resubmission is safe.
+                    ...(batchResult.resumption !== undefined && { resumption: batchResult.resumption }),
                 },
             };
             process.stdout.write(`${JSON.stringify(summary)}\n`);
@@ -1797,8 +1962,13 @@ export function registerWriteCommands(program) {
         "author's changes (e.g. `--by mcp` to clean up after an agent), or --txn <token> " +
         "to undo one exact change by the `undoToken` its result returned (immune to any " +
         "changes made in between). Changes made directly in the Things app cannot be " +
-        "undone here. IRREVERSIBLE changes are reported, not guessed: permanent deletes " +
-        "and changes whose prior state is unknown. Partial restores carry notes (e.g. a " +
+        "undone here. --last/--by select the N newest NOT-YET-undone changes: a change already " +
+        "undone is SKIPPED, so repeating `undo --last N` walks progressively deeper into " +
+        "history rather than re-selecting the same changes. An IRREVERSIBLE change is NOT " +
+        "skipped — it still counts toward N and is reported every pass (so you always see it " +
+        "rather than silently reaching past it). IRREVERSIBLE changes are reported, not " +
+        "guessed: permanent deletes and changes whose prior state is unknown. Partial " +
+        "restores carry notes (e.g. a " +
         "delete-undo lands in the Inbox de-scheduled). --dry-run shows every inverse plan " +
         "without executing. Undoing a CREATED area/tag deletes it permanently — requires " +
         "--dangerously-permanent. An undo is refused when the item changed outside things-api " +
@@ -1985,7 +2155,7 @@ export function registerWriteCommands(program) {
         .command("set <key> <value>")
         .description("Persist a config key: profile | maxDisruption | actor | auditEnabled | " +
         "accepted-fingerprint | certified-app-version | allow-experimental | bounce-enabled | " +
-        "bounce-max-items | ui-enabled | scope")
+        "bounce-max-items | auto-launch | ui-enabled | ui-drive-budget-ms | trace | scope")
         .action((key, value, opts) => {
         const map = {
             profile: "profile",
@@ -1997,7 +2167,10 @@ export function registerWriteCommands(program) {
             "allow-experimental": "allowExperimental",
             "bounce-enabled": "bounceEnabled",
             "bounce-max-items": "bounceMaxItems",
+            "auto-launch": "autoLaunch",
             "ui-enabled": "uiEnabled",
+            "ui-drive-budget-ms": "uiDriveBudgetMs",
+            trace: "traceEnabled",
             scope: "scope",
         };
         const target = map[key];
@@ -2006,12 +2179,14 @@ export function registerWriteCommands(program) {
             process.exitCode = ExitCode.Usage;
             return;
         }
-        const parsed = target === "maxDisruption" || target === "bounceMaxItems"
+        const parsed = target === "maxDisruption" || target === "bounceMaxItems" || target === "uiDriveBudgetMs"
             ? Number(value)
             : target === "auditEnabled" ||
                 target === "allowExperimental" ||
                 target === "bounceEnabled" ||
-                target === "uiEnabled"
+                target === "autoLaunch" ||
+                target === "uiEnabled" ||
+                target === "traceEnabled"
                 ? value === "true"
                 : value;
         // Universal `--dry-run` (../dry-run.ts): `config set` writes local config