things-api 0.19.0 → 0.19.2

package/dist/write/promote-clone.js

@@ -5,10 +5,11 @@ import { byUuid } from "../read/detail.js";
 import { resolveProjectWriteTarget, resolveTaskUuidPrefix } from "../read/queries.js";
 import { runCloneProject, runCloneTodo } from "./clone.js";
 import { promoteProjectViaGui } from "./make-repeating-project.js";
+import { replayIfApplied } from "./opid.js";
 import { fingerprintLabel, runComposite, runMutation, } from "./pipeline.js";
 import { assessOffRuleFirst, daysBetweenIso, deriveFixedAnchor, isIsoDate, } from "./repeat-anchor.js";
 import { assertRepeatRule, ruleToInverseParams, splitAddRepeatingRule } from "./repeat-rule.js";
-import { createDbReader } from "./verify/delta.js";
+import { createDbReader, } from "./verify/delta.js";
 import { H_UI_SESSION_UNREACHABLE } from "./vectors/session-reachability.js";
 const PLACEMENT_NOTE = "the series' current instance lands at its container's default position — its prior slot was " +
     "not automatically restored (best-effort placement is not yet wired for this container); " +
@@ -98,6 +99,29 @@ async function gateUiPreflight(deps, op) {
     }
     if (!deps.config.ui.enabled)
         return null;
+    // 1½. AN OPEN DIALOG, before the seed (MODALX1, issue #620). This is the gap
+    // the field incident fell into twice over: the clone leg rides the URL scheme,
+    // which an open dialog does not touch, so it LANDS — and then the trash leg,
+    // the promote and the cleanup are all AppleScript, all refused with `-1728`,
+    // leaving a copy of the user's to-do in their lists. Measured in-lab: with a
+    // dialog standing, the compound mutates and then fails for a reason it could
+    // have read up front. A census that cannot be read proceeds (the drive's own
+    // precondition is the backstop); only a POSITIVE sighting refuses.
+    const dialogVector = deps.vectors.find((v) => v.probeUiState !== undefined);
+    if (dialogVector?.probeUiState !== undefined) {
+        const state = await dialogVector.probeUiState();
+        if (state !== null && state.inspectable && state.sheetOpen) {
+            return {
+                kind: "blocked",
+                op,
+                reason: "environment",
+                detail: "a dialog is already open in Things, and while one is open the app ignores changes " +
+                    "like this one and stops sending anything to Things Cloud — nothing was created",
+                remediation: "dismiss the dialog in Things (click Cancel, or press Escape with Things in front), " +
+                    "then run the same command again; `things ui-state` shows what is open",
+            };
+        }
+    }
     const ui = deps.vectors.find((v) => v.probeReachability !== undefined);
     if (ui?.probeReachability === undefined)
         return null;
@@ -139,6 +163,126 @@ async function cleanupSeed(deps, kind, createdUuid, promote, options, txnId) {
         ? { detail: `${promote.detail} — ${cleanupNote}` }
         : {};
 }
+/**
+ * Put a restored to-do back where it was (issue #620, field report M1).
+ *
+ * The ONLY scriptable restore-from-Trash is `move <to-do> to list "Inbox"`
+ * (E15) — and it does exactly that: the row lands in the INBOX, DE-SCHEDULED
+ * (`start=0, startDate=NULL`), with its project/heading link severed. That is
+ * the GUI's "Put Back" affordance's poorer scripted cousin, and it is why a
+ * failed promote handed back a to-do sitting unscheduled in the Inbox instead
+ * of where its owner left it. Everything else about the row survives (title,
+ * notes, tags, deadline, reminder byte), so the repair is exactly two writes:
+ * its container, then its schedule.
+ *
+ * Best-effort and fully disclosed: each half reports whether it landed, and a
+ * to-do that lived under a HEADING is returned to the owning project with the
+ * heading placement named as not restored — there is nothing to guess at.
+ * Returns the sentence describing what happened.
+ */
+async function reassertTodoPlacement(deps, src, options, txnId) {
+    const landed = [];
+    const missed = [];
+    const projectUuid = src.project?.uuid ?? src.headingProject?.uuid ?? null;
+    const areaUuid = src.area?.uuid ?? null;
+    const move = projectUuid !== null
+        ? { uuid: src.uuid, project: { uuid: projectUuid } }
+        : areaUuid !== null
+            ? { uuid: src.uuid, area: { uuid: areaUuid } }
+            : null;
+    if (move !== null) {
+        const res = await runMutation(deps, "todo.move", move, legOptions(options, txnId));
+        const where = projectUuid !== null ? "its project" : "its area";
+        (res.kind === "ok" ? landed : missed).push(where);
+    }
+    if (src.heading !== null)
+        missed.push("its position under a heading");
+    // The schedule. `evening` is only expressible for TODAY (the app has no other
+    // evening slot), so a stale evening marker degrades to its date.
+    const todayIso = localToday(deps.now?.() ?? new Date(), deps.zone);
+    const when = src.derived.evening === true && src.startDate === todayIso
+        ? "evening"
+        : src.startDate !== null
+            ? src.startDate
+            : src.derived.start === "someday"
+                ? "someday"
+                : src.derived.start === "active"
+                    ? "anytime"
+                    : null;
+    if (when !== null) {
+        const res = await runMutation(deps, "todo.update", { uuid: src.uuid, when }, legOptions(options, txnId));
+        (res.kind === "ok" ? landed : missed).push(`its "when" (${when})`);
+    }
+    if (landed.length === 0 && missed.length === 0)
+        return "it was already in the Inbox, unscheduled";
+    const ok = landed.length > 0 ? `${landed.join(" and ")} restored` : "";
+    const bad = missed.length > 0
+        ? `${ok === "" ? "" : ", but "}${missed.join(" and ")} could not be restored — set ${missed.length > 1 ? "them" : "it"} yourself`
+        : "";
+    return `a scripted restore returns a to-do to the Inbox with no schedule, so ${ok}${bad}`;
+}
+/**
+ * Undo a failed make-repeating's OWN two mutations (issue #620).
+ *
+ * The compound trashes the original and mints a disposable copy before the
+ * promote runs, so a promote that does not land leaves two artifacts. Both are
+ * ours, so both are cleaned up here rather than described to the caller as
+ * homework: the original is restored AND put back where it was
+ * ({@link reassertTodoPlacement}), and the disposable copy is moved to the
+ * Trash — the same ratified reasoning as the add-repeating seed auto-trash
+ * (2026-08-15, issue #480): our artifact, recreatable verbatim, and the Trash
+ * is recoverable.
+ *
+ * When a step does NOT land, the report names the row and the command that
+ * finishes the job — and names the likeliest reason, because there is exactly
+ * one that matters here: a dialog still open in Things makes the app ignore
+ * scripted changes app-wide (docs/things-app-oddities.md §9cc) and holds Things
+ * Cloud sync with them. That is the mechanism behind the field report's
+ * "AppleScript could not get that to-do ID" on a row the database showed
+ * perfectly present.
+ */
+async function rollBackFailedPromote(deps, kind, ids, options, txnId) {
+    const expectedType = kind === "project" ? "project" : "to-do";
+    const restoreOp = kind === "project" ? "project.restore" : "todo.restore";
+    const restored = await runMutation(deps, restoreOp, { uuid: ids.srcUuid }, legOptions(options, txnId));
+    let originalNote;
+    if (restored.kind === "ok") {
+        // A project restore flips the row in place and keeps its area, schedule and
+        // children exactly as they were (P06) — only the to-do restore relocates.
+        const placement = ids.src.type === "to-do" ? await reassertTodoPlacement(deps, ids.src, options, txnId) : null;
+        originalNote =
+            `the original ${expectedType} (uuid ${ids.srcUuid}) was restored from the Trash` +
+                (placement === null ? "" : ` — ${placement}`);
+    }
+    else {
+        originalNote =
+            `the original ${expectedType} (uuid ${ids.srcUuid}) could NOT be restored from the Trash — ` +
+                `restore it with \`things ${kind} restore ${ids.srcUuid}\`${DISMISS_FIRST}`;
+    }
+    const cloneNote = await trashDisposableCopy(deps, kind, ids.cloneUuid, options, txnId);
+    return `the promote did not land. ${originalNote}; ${cloneNote}`;
+}
+/**
+ * Move the compound's own disposable copy to the Trash and say what happened.
+ * Shared by every failure path that has minted one, so a caller is never left
+ * holding a duplicate of their own to-do with no instruction.
+ */
+async function trashDisposableCopy(deps, kind, cloneUuid, options, txnId) {
+    const trashOp = kind === "project" ? "project.delete" : "todo.delete";
+    const trashed = await runMutation(deps, trashOp, { uuid: cloneUuid }, legOptions(options, txnId));
+    return trashed.kind === "ok"
+        ? `the disposable copy this command made (uuid ${cloneUuid}) was moved to the Trash`
+        : `the disposable copy this command made (uuid ${cloneUuid}) is still in your lists and ` +
+            `could NOT be removed — remove it with \`things ${kind} delete ${cloneUuid}\`${DISMISS_FIRST}`;
+}
+/**
+ * The one remediation a stranded dialog needs, appended wherever a cleanup
+ * mutation fails: while a dialog is open, Things ignores scripted changes
+ * app-wide AND stops sending anything to Things Cloud.
+ */
+const DISMISS_FIRST = ". If a dialog is still open in Things, dismiss it first (click Cancel, or press Escape with " +
+    "Things in front): while one is open the app ignores changes like this and stops sending " +
+    "changes to Things Cloud";
 /**
  * Pick the rule fields (frequency/interval + calendar anchors + deadline offset)
  * as a RepeatRuleParams, plus the requested first-occurrence date to drive into
@@ -258,6 +402,33 @@ function landedFirstStart(deps, templateUuid, instanceUuid, afterCompletion) {
         return firstOccurrenceOf(deps.db, templateUuid);
     return instanceUuid === null ? null : instanceStartDate(deps.db, instanceUuid);
 }
+/**
+ * Was the requested first occurrence honored? (#508's oracle, extended for the
+ * SAME-DAY case — issue #625.)
+ *
+ * A fixed series is normally read off the template's cursor. But when the
+ * requested first occurrence is TODAY, the app materializes that occurrence
+ * immediately on commit and ADVANCES the cursor to the next slot — measured on
+ * 3.23 (FGRD1 §8: `--when <today>` on a weekly rule left the template's cursor
+ * and next-date on the FOLLOWING week with `instanceCreationCount = 1`, while a
+ * live instance sat on today). Reading only the cursor there reports a
+ * `verify-failed:mismatch` on a series that landed exactly as asked — the same
+ * false-negative shape as #508, one case over. So the check accepts EITHER
+ * oracle: the cursor naming the requested date, or a materialized instance
+ * SITTING on it. An instance dated the requested day is proof by construction;
+ * nothing else can put one there.
+ */
+export function firstOccurrenceHonored(deps, args) {
+    const landed = landedFirstStart(deps, args.templateUuid, args.instanceUuid, args.afterCompletion);
+    // An after-completion series with no materialized instance is UNVERIFIABLE
+    // (the create delta already proved the series landed) — never a mismatch.
+    if (args.afterCompletion && landed === null)
+        return { honored: true, landed };
+    if (landed === args.expectedIso)
+        return { honored: true, landed };
+    const instanceIso = args.instanceUuid === null ? null : instanceStartDate(deps.db, args.instanceUuid);
+    return { honored: instanceIso === args.expectedIso, landed };
+}
 /**
  * DBLSPAWN1 (docs/lab/dblspawn1-preserved-instance.md, golden-v3 / Things 3.22.14):
  * a promote whose source is PRESERVED (SRCFATE deadline / terminal-element trigger)
@@ -340,6 +511,36 @@ function discoveryOf(promote) {
     };
 }
 // -------------------------------------------------------------- audit summary
+/**
+ * The promote compound's presence oracle: "a repeating TEMPLATE with this title,
+ * created since this call started, exists". It is the same create-probe the
+ * compound's own dry-run plan states, TIME-BOUNDED to the call — the app mints a
+ * template with a fresh write-time creationDate even when the promoted row was
+ * created earlier (`--preserve-created`), so the bound is safe and it keeps an
+ * older namesake series from reading as this call's work. Recorded on an
+ * AMBIGUOUS summary so a resubmission can settle it (see {@link appendPromoteSummary}).
+ */
+function promotePresenceDelta(title, type, startedAt) {
+    return {
+        mode: "create",
+        probe: { title, type, sinceEpoch: Math.floor(startedAt.getTime() / 1000) },
+        assert: [{ field: "repeating.isTemplate", equals: true }],
+    };
+}
+/**
+ * Append the promote compound's SUMMARY record — the ONE record that stands for
+ * the whole verb (its legs are `leg`-role records, excluded from direct undo),
+ * and the one record the caller's `opId` rides, so a resubmission matches the
+ * whole promote exactly once instead of matching a leg or nothing at all.
+ *
+ * Two shapes, one record either way:
+ *  - the SUCCESS summary (default) — result `ok`, the single undoable unit;
+ *  - an AMBIGUOUS summary (`ambiguous`) — result `verify-failed:timeout` with the
+ *    presence oracle attached, written when a leg dispatched and never confirmed.
+ *    It is not an undo target (undo reads `ok` records only); it exists so a
+ *    resubmission carrying the same key re-reads state and decides instead of
+ *    minting a second series.
+ */
 function appendPromoteSummary(deps, args) {
     const fp = deps.fingerprint();
     const observed = {
@@ -350,7 +551,7 @@ function appendPromoteSummary(deps, args) {
     const record = {
         v: 1,
         ts: args.startedAt.toISOString(),
-        actor: deps.config.actor,
+        actor: args.options?.actor ?? deps.config.actor,
         host: deps.config.host,
         op: args.op,
         uuid: args.templateUuid,
@@ -359,9 +560,11 @@ function appendPromoteSummary(deps, args) {
         invocation: args.invocation,
         requested: args.requested,
         txn: { id: args.txnId, role: "summary" },
+        ...(args.options?.opId !== undefined && { opId: args.options.opId }),
+        ...(args.ambiguous !== undefined && { expected: args.ambiguous }),
         pre: null,
-        observed,
-        result: "ok",
+        observed: args.ambiguous === undefined ? observed : null,
+        result: args.ambiguous === undefined ? "ok" : "verify-failed:timeout",
         ...(args.preModDates !== undefined && { preModDates: args.preModDates }),
         verify: null,
         durationMs: (deps.now?.() ?? new Date()).getTime() - args.startedAt.getTime(),
@@ -373,6 +576,31 @@ function appendPromoteSummary(deps, args) {
     };
     deps.audit.append(record);
 }
+/**
+ * Record the AMBIGUOUS summary when a promote compound's own outcome is a
+ * timeout — the one verdict where the series may or may not exist. Returns the
+ * outcome unchanged, so it wraps a composite body without re-shaping it. Only a
+ * keyed call records one: without an `opId` there is nothing to reconcile
+ * against later, and the leg records already carry the failure.
+ */
+function recordAmbiguousPromote(deps, outcome, args) {
+    if (args.options.opId === undefined)
+        return outcome;
+    if (outcome.kind !== "verify-failed" || outcome.reason !== "timeout")
+        return outcome;
+    appendPromoteSummary(deps, {
+        startedAt: args.startedAt,
+        op: args.op,
+        txnId: args.txnId,
+        templateUuid: null,
+        instanceUuid: null,
+        invocation: args.invocation,
+        requested: args.requested,
+        options: args.options,
+        ambiguous: promotePresenceDelta(args.title, args.type, args.startedAt),
+    });
+    return outcome;
+}
 /** Build the ok result for a promote (make/add-repeating). */
 function promoteOk(args) {
     const repeating = {
@@ -409,6 +637,14 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
     const op = kind === "project" ? "project.make-repeating" : "todo.make-repeating";
     // Validate the rule BEFORE anything (a bad rule must never mint a clone).
     assertRepeatRule(params);
+    // Idempotency FIRST, before the target is even resolved: a successful promote
+    // moves the original to the Trash and hands back a different uuid, so a
+    // resubmission of the same key must be answered from the trail rather than
+    // re-driven against a source that is no longer the item it names. The key
+    // rides the compound's single summary record, so a match is the whole verb.
+    const replay = replayIfApplied(deps, options);
+    if (replay !== null)
+        return replay;
     const now = deps.now?.() ?? new Date();
     const srcUuid = kind === "project"
         ? resolveProjectWriteTarget(deps.db, params.uuid)
@@ -427,6 +663,14 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
                 : "verify the uuid with `things show <uuid>`, or use `things project make-repeating` for a project",
         };
     }
+    // Bound after the existence guard so the composite body (a hoisted function,
+    // where TypeScript cannot carry the narrowing) still sees a plain string.
+    const srcTitle = src.title;
+    // Same reason as srcTitle: the type guard above proved this is the to-do or
+    // project the caller named, but the narrowing does not survive into the
+    // hoisted composite body. The failure rollback reads its placement from here
+    // (captured BEFORE the trash, which is the only moment it is knowable).
+    const srcEntity = src;
     // ANCH2 (issue #476): the app's Repeat dialog HAS a "Next:" first-occurrence
     // field; its default is the today-anchored next match, but it is editable and
     // honored (docs/lab/anch2-next-field.md). Drive it with the requested first
@@ -449,10 +693,14 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
         ? (params.startDaysEarlier ?? 0)
         : 0;
     const driveIso = isIsoDate(whenIso) ? addDaysIso(whenIso, deadlineShift) : undefined;
-    // The dialog is driven with the deadline-adjusted date; the verify below expects
-    // the START to land back on the requested `--when`.
-    const nextIso = driveIso;
-    const expectedStartIso = isIsoDate(whenIso) ? whenIso : undefined;
+    // The ANCHOR is derived from the deadline-adjusted date (the anchor names the
+    // DUE date), but `next` is passed through as the requested START: the promote
+    // leg's own compile applies the "Next:" shift, and it is the ONLY place that
+    // does (NEXTPOP1 — shifting here as well made every downstream consumer that
+    // shifts, `assessOffRuleFirst` among them, shift a second time). The verify
+    // below expects the START to land on the requested `--when` either way.
+    const nextIso = isIsoDate(whenIso) ? whenIso : undefined;
+    const expectedStartIso = nextIso;
     const effParams = { ...params, ...deriveFixedAnchor(params, driveIso) };
     // The promote leg drives the GUI — block before minting a clone if the ack is missing.
     if (options.dangerouslyDriveGui !== true && options.dryRun !== true) {
@@ -484,14 +732,29 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
     const gate = await gateUiPreflight(deps, op);
     if (gate !== null)
         return gate;
+    const startedAt = now;
+    const txnId = newTxnId(startedAt);
     // COMPOSITE LOCK: everything below is ONE verb executed as several mutations
     // (clone → trash → promote → the DBLSPAWN1 clean-up), and they must not
     // interleave with another writer's legs — the promote's row selection is by
     // TITLE, so a concurrent clone of the same item makes it ambiguous. One lock,
     // held to the end; each leg's own acquisition is a reentrant no-op.
     return runComposite(deps, op, async () => {
-        const startedAt = now;
-        const txnId = newTxnId(startedAt);
+        const outcome = await promoteBody();
+        // An unconfirmed outcome gets the compound's AMBIGUOUS summary, so a
+        // resubmission of the same key reconciles instead of minting a second series.
+        return recordAmbiguousPromote(deps, outcome, {
+            startedAt,
+            op,
+            txnId,
+            title: srcTitle,
+            type: expectedType,
+            invocation: `${op}: clone ${srcUuid} → trash ${srcUuid} → promote (unconfirmed)`,
+            requested: effParams,
+            options,
+        });
+    });
+    async function promoteBody() {
         // 1. Clone the source as a disposable, embedded leg (--preserve-created). The
         // clone has captured X's full content by the time it returns.
         const clone = kind === "project"
@@ -507,7 +770,7 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
                     reason: "mismatch",
                     expected: {
                         mode: "create",
-                        probe: { title: src.title, type: expectedType, sinceEpoch: 0 },
+                        probe: { title: srcTitle, type: expectedType, sinceEpoch: 0 },
                         assert: [],
                     },
                     observed: null,
@@ -531,14 +794,16 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
         // ambiguous (H-PROJECT-REPEAT). X survives in the Trash (the recoverable half).
         const trash = await runMutation(deps, `${kind}.delete`, { uuid: srcUuid }, legOptions(options, txnId, undefined, preserveModified ? { preserveModified: true } : undefined));
         if (trash.kind !== "ok") {
+            // The original never moved, so there is nothing to restore — but the
+            // disposable copy exists and is ours to clean up (issue #620).
+            const cloneNote = await trashDisposableCopy(deps, kind, cloneUuid, options, txnId);
             return {
                 ...trash,
                 op,
                 ...("detail" in trash
                     ? {
-                        detail: `${trash.detail} — the disposable clone (uuid ${cloneUuid}) was created but the ` +
-                            `original ${srcUuid} could not be moved to the Trash, so it was NOT promoted; trash ` +
-                            "the clone and retry",
+                        detail: `${trash.detail} — the original ${srcUuid} could not be moved to the Trash, so it ` +
+                            `was NOT promoted and is unchanged; ${cloneNote}`,
                     }
                     : {}),
             };
@@ -549,22 +814,14 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
             ? await promoteProjectViaGui(deps, rule, legOptions(options, txnId, "ui"))
             : await runMutation(deps, "todo.make-repeating", rule, legOptions(options, txnId, "ui"));
         if (promote.kind !== "ok") {
-            // The clone persists but was not promoted; best-effort ROLL BACK the trash so
-            // the original is not stranded in the Trash.
-            const restoreOp = kind === "project" ? "project.restore" : "todo.restore";
-            const rolledBack = await runMutation(deps, restoreOp, { uuid: srcUuid }, legOptions(options, txnId));
-            const rollNote = rolledBack.kind === "ok"
-                ? `the original ${srcUuid} was restored from the Trash`
-                : `the original ${srcUuid} could NOT be restored from the Trash — restore it in the app`;
+            // The clone persists but was not promoted. Undo our own two mutations, in
+            // the order that leaves the least behind (issue #620) — see
+            // {@link rollBackFailedPromote}.
+            const rollNote = await rollBackFailedPromote(deps, kind, { srcUuid, cloneUuid, src: srcEntity }, options, txnId);
             return {
                 ...promote,
                 op,
-                ...("detail" in promote
-                    ? {
-                        detail: `${promote.detail} — the disposable clone (uuid ${cloneUuid}) was created but the ` +
-                            `promote did not land; ${rollNote}. Trash the clone and retry`,
-                    }
-                    : {}),
+                ...("detail" in promote ? { detail: `${promote.detail} — ${rollNote}` } : {}),
             };
         }
         const { templateUuid } = discoveryOf(promote);
@@ -577,10 +834,14 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
         // (#508) — see landedFirstStart; an unverifiable after-completion series skips.
         const afterCompletion = effParams.afterCompletion === true;
         if (expectedStartIso !== undefined) {
-            const landed = landedFirstStart(deps, templateUuid, instanceUuid, afterCompletion);
-            if (!(afterCompletion && landed === null) && landed !== expectedStartIso) {
-                return nextMismatch(op, templateUuid, expectedStartIso, landed);
-            }
+            const first = firstOccurrenceHonored(deps, {
+                templateUuid,
+                instanceUuid,
+                expectedIso: expectedStartIso,
+                afterCompletion,
+            });
+            if (!first.honored)
+                return nextMismatch(op, templateUuid, expectedStartIso, first.landed);
         }
         const warnings = [
             landedRuleEcho(effParams, expectedStartIso ?? firstOccurrenceOf(deps.db, templateUuid)),
@@ -611,6 +872,7 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
             originalUuid: srcUuid,
             invocation: `${op}: clone ${srcUuid} → trash ${srcUuid} → promote ${cloneUuid} → template ${templateUuid}`,
             requested: effParams,
+            options,
             ...(preserveModified && preUmd !== null && { preModDates: { [srcUuid]: preUmd } }),
         });
         return promoteOk({
@@ -618,11 +880,11 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
             templateUuid,
             instanceUuid,
             replacedUuid: cloneUuid,
-            title: src.title,
+            title: srcTitle,
             txnId,
             warnings,
         });
-    });
+    }
 }
 export function runMakeRepeatingTodo(deps, params, options = {}) {
     return makeRepeatingViaClone(deps, "todo", params, options);
@@ -639,6 +901,12 @@ export function runMakeRepeatingProject(deps, params, options = {}) {
 async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options) {
     const op = kind === "project" ? "project.add-repeating" : "todo.add-repeating";
     assertRepeatRule(rule);
+    // Idempotency FIRST: this verb CREATES, so a blind resubmission is a duplicate
+    // series. The key rides the compound's single summary record, so a match is the
+    // whole verb — the add leg and the promote leg together — not one of them.
+    const replay = replayIfApplied(deps, options);
+    if (replay !== null)
+        return replay;
     // ANCH2 (issue #476): drive the Repeat dialog's "Next:" field with --when so the
     // series starts on the requested date (the field's default is today-anchored but
     // it is editable and honored). YANCH1 (issue #493): also DERIVE the calendar
@@ -658,8 +926,11 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
     const whenIso = isIsoDate(addParams["when"]) ? addParams["when"] : null;
     const deadlineShift = rule.deadline === true || (rule.startDaysEarlier ?? 0) > 0 ? (rule.startDaysEarlier ?? 0) : 0;
     const driveIso = whenIso !== null ? addDaysIso(whenIso, deadlineShift) : null;
-    const nextIso = driveIso ?? undefined;
-    const expectedStartIso = whenIso ?? undefined;
+    // The ANCHOR is derived from the deadline-adjusted date; `next` passes through
+    // as the requested START and the promote leg's compile applies the "Next:"
+    // shift — the one place that does (NEXTPOP1; see promoteViaCloneAndMakeRepeating).
+    const nextIso = whenIso ?? undefined;
+    const expectedStartIso = nextIso;
     const effRule = {
         ...rule,
         ...deriveFixedAnchor(rule, driveIso),
@@ -706,12 +977,27 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
     const gate = await gateUiPreflight(deps, op);
     if (gate !== null)
         return gate;
+    const startedAt = deps.now?.() ?? new Date();
+    const txnId = newTxnId(startedAt);
     // COMPOSITE LOCK: add → promote (→ the seed auto-trash / DBLSPAWN1 clean-up)
     // is one verb, several mutations; hold one lock across all of them so a
     // concurrent composite cannot land its own legs between ours.
     return runComposite(deps, op, async () => {
-        const startedAt = deps.now?.() ?? new Date();
-        const txnId = newTxnId(startedAt);
+        const outcome = await addBody();
+        // An unconfirmed outcome gets the compound's AMBIGUOUS summary, so a
+        // resubmission of the same key reconciles instead of creating a second series.
+        return recordAmbiguousPromote(deps, outcome, {
+            startedAt,
+            op,
+            txnId,
+            title,
+            type: expectedType,
+            invocation: `${op}: add "${title}" → promote (unconfirmed)`,
+            requested: { title, ...effRule },
+            options,
+        });
+    });
+    async function addBody() {
         // 1. Create the item (full add vocabulary) as an embedded leg.
         const addOp = kind === "project" ? "project.add" : "todo.add";
         const add = await runMutation(deps, addOp, addParams, legOptions(options, txnId, "url-scheme"));
@@ -762,9 +1048,14 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
         // series verifies against its materialized instance, and skips when it has none.
         const afterCompletion = effRuleWithReminder.afterCompletion === true;
         if (expectedStartIso !== undefined) {
-            const landed = landedFirstStart(deps, templateUuid, instanceUuid, afterCompletion);
-            if (!(afterCompletion && landed === null) && landed !== expectedStartIso)
-                return nextMismatch(op, templateUuid, expectedStartIso, landed);
+            const first = firstOccurrenceHonored(deps, {
+                templateUuid,
+                instanceUuid,
+                expectedIso: expectedStartIso,
+                afterCompletion,
+            });
+            if (!first.honored)
+                return nextMismatch(op, templateUuid, expectedStartIso, first.landed);
         }
         const warnings = [
             landedRuleEcho(ruleParams, expectedStartIso ?? firstOccurrenceOf(deps.db, templateUuid)),
@@ -792,6 +1083,7 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
             instanceUuid,
             invocation: `${op}: add "${title}" ${createdUuid} → template ${templateUuid}`,
             requested: { title, ...effRule },
+            options,
         });
         return promoteOk({
             op,
@@ -802,7 +1094,7 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
             txnId,
             warnings,
         });
-    });
+    }
 }
 /**
  * Fold a concrete item-level `deadline` (and/or an explicit `startDaysEarlier`)