things-api 0.17.0 → 0.19.0

package/dist/write/promote-clone.js

@@ -1,12 +1,13 @@
 import { undoToken } from "../audit/schema.js";
-import { addDaysIso, decodePackedDate } from "../model/dates.js";
+import { uiAllowed, uiCapability as uiCapabilityDefault } from "../capability.js";
+import { addDaysIso, decodePackedDate, localToday } from "../model/dates.js";
 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 { fingerprintLabel, runMutation, } from "./pipeline.js";
-import { deriveFixedAnchor, isIsoDate } from "./repeat-anchor.js";
-import { assertRepeatRule, ruleToInverseParams } from "./repeat-rule.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 { 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 " +
@@ -50,22 +51,51 @@ function blockedUiDrive(op) {
         detail: "this operation promotes an item to a repeating series by driving the local Things app " +
             "through the Accessibility API (the Repeat… dialog) — it may briefly interact with the UI",
         remediation: "pass dangerouslyDriveGui (--dangerously-drive-gui) to proceed; the vector also requires " +
-            "`things config set ui-enabled true` and Accessibility granted to this process (see docs/setup.md)",
+            "`things config set ui-enabled true` and `things helpers setup --gui`, which grants " +
+            "GUI-driving to the helper pair — the only identity it is granted to " +
+            "(docs/design/permissions-doctrine.md, Article IV)",
     };
 }
 /**
- * SESSGATE (#480) pre-seed reachability gate. A promote composite is NOT atomic:
- * it SEEDS a row (clone / add) before the GUI promote leg drives the dialog. If
- * the Mac's session is AX-blind (screen locked / full-screen Space), the dialog
- * would open on an unreachable window and the drive would fail — leaving an
- * orphan seed. So probe the live session BEFORE seeding and refuse fast (zero
- * mutation) on the certain-failure LOCKED signature. Only "session" scope refuses
- * here: a window merely on another Space is left for the in-drive relocation (the
- * reveal has not run yet, so refusing before the seed would be a false positive).
- * No ui vector (simulator / bench), ui disabled, or a fail-open probe → proceed
- * (the promote leg's own gate + cleanup remain the backstop).
+ * The pre-seed UI PREFLIGHT (SESSGATE #480 + issue #512). A promote composite is
+ * NOT atomic: it SEEDS a row (clone / add) before the GUI promote leg drives the
+ * dialog. Anything that will certainly stop that drive must be established BEFORE
+ * the seed exists, or the composite mutates, fails, and cleans up after itself for
+ * a reason it could have known up front. Two checks, cheapest and most decisive
+ * first, both prompt-free:
+ *
+ *  1. STANDING (permissions doctrine, Article IV). Driving the window needs
+ *     Accessibility + Automation → System Events, held by the helper pair and
+ *     nothing else. The pipeline already gates this — but only on the PROMOTE leg,
+ *     which runs after the seed, so a machine without the grants used to create
+ *     the row, refuse, and trash it. Same verdict, same copy, one leg earlier;
+ *     nothing is created. Keyed on a vector's `drivesGui` DECLARATION exactly as
+ *     the pipeline's gate is, never on its id, so a fake/simulator substituted
+ *     under "ui" is not gated on the developer's own host state.
+ *  2. REACHABILITY (SESSGATE). If the Mac's session is AX-blind (screen locked /
+ *     full-screen Space), the dialog would open on an unreachable window. Only
+ *     "session" scope refuses here: a window merely on another Space is left for
+ *     the in-drive relocation (the reveal has not run yet, so refusing before the
+ *     seed would be a false positive). A fail-open probe proceeds — the promote
+ *     leg's own gate + the seed cleanup remain the backstop.
+ *
+ * Running the standing check FIRST also keeps the probe itself doctrine-clean: no
+ * System Events call is attempted on a host that has not granted one.
  */
-async function gateSessionReachability(deps, op) {
+async function gateUiPreflight(deps, op) {
+    const gui = deps.vectors.find((v) => v.drivesGui === true && v.simulates !== true);
+    if (gui !== undefined) {
+        const capability = (deps.uiCapability ?? (() => uiCapabilityDefault()))();
+        if (!uiAllowed(capability)) {
+            return {
+                kind: "blocked",
+                op,
+                reason: "environment",
+                detail: `this operation drives the Things window, and ${capability.detail} — nothing was created`,
+                remediation: capability.remediation.join("; "),
+            };
+        }
+    }
     if (!deps.config.ui.enabled)
         return null;
     const ui = deps.vectors.find((v) => v.probeReachability !== undefined);
@@ -117,35 +147,23 @@ async function cleanupSeed(deps, kind, createdUuid, promote, options, txnId) {
  *
  * The `rule` bag is the SUPERSET the make/add legs actually carry: make-repeating
  * passes a full {@link RepeatRuleParams} (rule-level `deadline`/`startDaysEarlier`
- * included), add-repeating an {@link AddRepeatingRuleFields} (which OMITS those —
- * the base add owns the item's own deadline). Every field is copied THROUGH so
- * neither is silently dropped: an earlier version keyed the param type to
- * AddRepeatingRuleFields and stripped `deadline`/`startDaysEarlier` from the
- * make-repeating promote entirely (the same class as the RRX1 reminder drop —
- * a deadlined make-repeating produced a NON-deadlined template, YANCH1 #493).
+ * and the requested `next` included), add-repeating an
+ * {@link AddRepeatingRuleFields} plus whichever of the deadline pair its geometry
+ * folded in. Every field flows through by SPREAD, never by a hand-copied field
+ * list — a list here is how the make-repeating promote once stripped
+ * `deadline`/`startDaysEarlier` (a deadlined make-repeating produced a
+ * NON-deadlined template, YANCH1 #493) and how the project promote later dropped
+ * `next` (#549). The ONE field that is deliberately re-derived rather than copied
+ * is `next`: the drive date is deadline-shifted by the caller, and an
+ * after-completion dialog has no first-occurrence field to drive at all.
  */
 function ruleParamsFor(uuid, rule, nextIso) {
-    return {
-        uuid,
-        frequency: rule.frequency,
-        interval: rule.interval,
-        ...(rule.afterCompletion !== undefined && { afterCompletion: rule.afterCompletion }),
-        ...(rule.weekdays !== undefined && { weekdays: rule.weekdays }),
-        ...(rule.monthly !== undefined && { monthly: rule.monthly }),
-        ...(rule.yearly !== undefined && { yearly: rule.yearly }),
-        ...(rule.ends !== undefined && { ends: rule.ends }),
-        // The repeat reminder picker is drivable (ANCH2). make-repeating carries a
-        // rule-level reminder through; add-repeating threads the base to-do's
-        // --reminder here too (ADR1 #480), since the dialog conversion otherwise drops
-        // the seed's one-off reminder from the series.
-        ...(rule.reminder !== undefined && { reminder: rule.reminder }),
-        // The deadline offset is a rule-level field on make-repeating (the "Add
-        // deadlines" checkbox + "start N days earlier"); it must ride the promote or a
-        // `make-repeating --deadline` lands a non-deadlined series (YANCH1 #493).
-        ...(rule.deadline !== undefined && { deadline: rule.deadline }),
-        ...(rule.startDaysEarlier !== undefined && { startDaysEarlier: rule.startDaysEarlier }),
-        ...(nextIso !== undefined && rule.afterCompletion !== true && { next: nextIso }),
-    };
+    const out = { ...rule, uuid };
+    // Never the caller's raw `next` — see above; the drive date arrives as `nextIso`.
+    delete out.next;
+    if (nextIso !== undefined && rule.afterCompletion !== true)
+        out.next = nextIso;
+    return out;
 }
 const UNIT_SINGULAR = {
     daily: "day",
@@ -182,6 +200,18 @@ function landedRuleEcho(rule, startIso) {
             : "";
     return `landed: the series repeats ${cadence}${first}${deadlineNote}`;
 }
+/**
+ * The DACON1 off-rule-first disclosure line, or null when the request is on-rule.
+ * When an explicit anchor disagrees with `--when` (deadline-shift-aware) the app
+ * lands an OFF-RULE first occurrence (honored for weekly/yearly); this states both
+ * halves of the landed pattern so the caller can eyeball the two-phase series.
+ * The dishonored monthly shape is refused upstream (assertRepeatRule), so only the
+ * honored disclosure ever reaches here.
+ */
+function offRuleFirstNote(params) {
+    const assessment = assessOffRuleFirst(params);
+    return assessment?.kind === "honored" ? assessment.disclosure.message : null;
+}
 /**
  * The template's app-materialized first occurrence (`rt1_instanceCreationStartDate`
  * = the date the current instance is dated at) as an ISO date, for the post-drive
@@ -195,6 +225,95 @@ function firstOccurrenceOf(db, templateUuid) {
         return null;
     return decodePackedDate(row.ic);
 }
+/** A repeating instance's own scheduled start date (`startDate`) as ISO, or null. */
+function instanceStartDate(db, instanceUuid) {
+    const row = db.prepare("SELECT startDate AS s FROM TMTask WHERE uuid = ?").get(instanceUuid);
+    if (row === undefined || row.s === null)
+        return null;
+    return decodePackedDate(row.s);
+}
+/**
+ * The oracle for the post-drive first-occurrence check, picked by rule KIND
+ * (issue #508).
+ *
+ * A FIXED-schedule series is anchored on the calendar: the dialog's "Next:" field
+ * IS driven, and the template's own cursor (`rt1_instanceCreationStartDate`) holds
+ * the resulting first occurrence — the right thing to compare against.
+ *
+ * An AFTER-COMPLETION series has NO calendar anchor, so {@link ruleParamsFor}
+ * deliberately leaves "Next:" alone, and the app mints the template with an EMPTY
+ * cursor (RSIM2 / RSIM-P P4: no next / reference dates exist until a completion
+ * happens). Comparing that empty cursor against `--when` reported a FALSE
+ * `verify-failed:mismatch` on a perfectly correct creation (#508, reproduced 6/6
+ * on the live host). The requested date lives on the materialized INSTANCE's own
+ * `startDate` — the row the promote preserved and relinked — so that is the oracle
+ * for an after-completion series.
+ *
+ * Returns `null` when no oracle is reachable. For an after-completion rule that
+ * means "unverifiable" and the caller SKIPS the check (the create delta already
+ * proved the series landed); for a fixed rule an absent cursor is a genuine miss.
+ */
+function landedFirstStart(deps, templateUuid, instanceUuid, afterCompletion) {
+    if (!afterCompletion)
+        return firstOccurrenceOf(deps.db, templateUuid);
+    return instanceUuid === null ? null : instanceStartDate(deps.db, instanceUuid);
+}
+/**
+ * DBLSPAWN1 (docs/lab/dblspawn1-preserved-instance.md, golden-v3 / Things 3.22.14):
+ * a promote whose source is PRESERVED (SRCFATE deadline / terminal-element trigger)
+ * relinks that source IN PLACE as the current-occurrence instance. When the first
+ * occurrence is FUTURE-dated this double-books: the hidden template's cursor
+ * (`rt1_nextInstanceStartDate`) points at the SAME occurrence with
+ * `rt1_instanceCreationCount = 0` — the cursor does not know the occurrence is already
+ * materialized — so when the date ARRIVES the app spawns a SECOND instance alongside
+ * the preserved one (cell C: two rows dated the same day, icCount 0→1). A genuine
+ * duplicate factory, not cosmetic.
+ *
+ * So a promote composite trashes the redundant preserved FUTURE instance inside the
+ * txn: its content mirrors the template, and the cursor will mint the single real
+ * occurrence when the date arrives (matching a normal future-first series, which holds
+ * no materialized instance until then). A today/past-dated preserved instance is the
+ * LEGITIMATE current occurrence (the cursor has already advanced past it) — left
+ * untouched. Returns the disclosure warning (and the trashed uuid) or null when the
+ * promote did not preserve a future instance. Best-effort: a failed trash is reported
+ * in the warning rather than failing the whole compound (the series is already sound).
+ */
+async function trashRedundantFuturePreservedInstance(deps, kind, promote, options, txnId, now, afterCompletion) {
+    // AFTER-COMPLETION series are exempt: the double-book is a CURSOR phenomenon
+    // (`rt1_nextInstanceStartDate` pointing at an already-materialized occurrence),
+    // and an after-completion template is minted with NO cursor at all — the next
+    // occurrence is unknown until a completion happens (RSIM2 / RSIM-P P4). Its
+    // preserved instance is therefore the series' ONLY occurrence, whatever its
+    // date; trashing it would destroy the series' current occurrence rather than a
+    // duplicate. (Unreachable before #508, whose false verify-failed returned first.)
+    if (afterCompletion)
+        return null;
+    const rep = promote.repeating;
+    // Preserved iff the native promote relinked the source (replacedUuid === null) AND
+    // there is a materialized instance. A DELETE-fate promote reports replacedUuid !==
+    // null and never leaves a future instance to double-book.
+    if (rep === undefined || rep.replacedUuid !== null || rep.instanceUuid === null)
+        return null;
+    const instanceUuid = rep.instanceUuid;
+    const startIso = instanceStartDate(deps.db, instanceUuid);
+    if (startIso === null)
+        return null;
+    const todayIso = localToday(now, deps.zone);
+    if (daysBetweenIso(todayIso, startIso) <= 0)
+        return null; // today or past — legitimate
+    const trashOp = kind === "project" ? "project.delete" : "todo.delete";
+    const trashed = await runMutation(deps, trashOp, { uuid: instanceUuid }, legOptions(options, txnId));
+    const kindWord = kind === "project" ? "project" : "to-do";
+    const warning = trashed.kind === "ok"
+        ? `the source ${kindWord} was kept by the app as a pre-materialized first occurrence dated ` +
+            `${startIso}; because that date is in the future the series would have spawned a DUPLICATE ` +
+            `there, so the redundant occurrence was moved to the Trash — the series mints a single ` +
+            `occurrence when ${startIso} arrives`
+        : `the app kept the source ${kindWord} as a pre-materialized first occurrence dated ${startIso} ` +
+            `(a future date the series would DUPLICATE), and it could NOT be auto-trashed — remove it ` +
+            `with \`things ${kind} delete ${instanceUuid}\``;
+    return { warning, trashedUuid: instanceUuid };
+}
 /**
  * The verify-failed result when the driven "Next:" first occurrence did not land
  * (issue #476, ANCH2). The series exists but on the wrong phase — report it
@@ -358,128 +477,151 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
             },
         };
     }
-    // SESSGATE (#480): refuse a locked / full-screen session BEFORE minting a clone
-    // — otherwise the promote's dialog opens on an unreachable window and the whole
-    // compound fails, stranding a disposable clone. Zero mutation on refusal.
-    const gate = await gateSessionReachability(deps, op);
+    // PRE-SEED UI PREFLIGHT (#480/#512): refuse a host that cannot drive the window,
+    // or a locked / full-screen session, BEFORE minting a clone — otherwise the
+    // promote's dialog never opens and the whole compound fails, stranding a
+    // disposable clone. Zero mutation on refusal.
+    const gate = await gateUiPreflight(deps, op);
     if (gate !== null)
         return gate;
-    const startedAt = now;
-    const txnId = newTxnId(startedAt);
-    // 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"
-        ? await runCloneProject(deps, { uuid: srcUuid, preserveCreated: true }, legOptions(options, txnId))
-        : await runCloneTodo(deps, { uuid: srcUuid, preserveCreated: true }, legOptions(options, txnId));
-    if (clone.kind !== "ok" || clone.uuid === null) {
-        // A clone refusal (nested repeating template, H-CLONE-SOURCE) surfaces
-        // coherently here — re-label it to the make-repeating op for the caller.
-        return clone.kind === "ok"
-            ? {
-                kind: "verify-failed",
+    // 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);
+        // 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"
+            ? await runCloneProject(deps, { uuid: srcUuid, preserveCreated: true }, legOptions(options, txnId))
+            : await runCloneTodo(deps, { uuid: srcUuid, preserveCreated: true }, legOptions(options, txnId));
+        if (clone.kind !== "ok" || clone.uuid === null) {
+            // A clone refusal (nested repeating template, H-CLONE-SOURCE) surfaces
+            // coherently here — re-label it to the make-repeating op for the caller.
+            return clone.kind === "ok"
+                ? {
+                    kind: "verify-failed",
+                    op,
+                    reason: "mismatch",
+                    expected: {
+                        mode: "create",
+                        probe: { title: src.title, type: expectedType, sinceEpoch: 0 },
+                        assert: [],
+                    },
+                    observed: null,
+                    detail: "the disposable clone was created but its uuid was not discovered — nothing was promoted or trashed",
+                }
+                : { ...clone, op };
+        }
+        const cloneUuid = clone.uuid;
+        // --preserve-modified: X is the ONLY pre-existing row the compound touches (the
+        // clone/promote legs mint fresh rows). Capture its pre-write umd BEFORE the
+        // trash bumps it — the trash leg restores it forward, and the value rides the
+        // summary record's preModDates so the symmetric undo restore fires on the
+        // revived X (undo.ts, 2026-08-13 ruling). The clone leg above reads X but never
+        // writes it, so its umd is still pristine here.
+        const preserveModified = options.preserveModified === true;
+        const preUmd = preserveModified
+            ? createDbReader(deps.db, now, deps.zone).modDateOf(srcUuid)
+            : null;
+        // 2. Trash the original BEFORE promoting — the clone already holds X's content,
+        // and a live same-titled X would make the promote's project row-selection
+        // 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") {
+            return {
+                ...trash,
                 op,
-                reason: "mismatch",
-                expected: {
-                    mode: "create",
-                    probe: { title: src.title, type: expectedType, sinceEpoch: 0 },
-                    assert: [],
-                },
-                observed: null,
-                detail: "the disposable clone was created but its uuid was not discovered — nothing was promoted or trashed",
+                ...("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",
+                    }
+                    : {}),
+            };
+        }
+        // 3. Native-promote the clone (with the ANCH2 Next drive + derived weekday).
+        const rule = ruleParamsFor(cloneUuid, effParams, nextIso);
+        const promote = kind === "project"
+            ? 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`;
+            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`,
+                    }
+                    : {}),
+            };
+        }
+        const { templateUuid } = discoveryOf(promote);
+        let { instanceUuid } = discoveryOf(promote);
+        // Post-drive verify (ANCH2 + YANCH1): the instance START must have landed on the
+        // requested `--when` — for a deadlined rule the driven Next is the deadline
+        // (when + startDaysEarlier) and the app back-shifts the start to `--when`, so the
+        // check is against `expectedStartIso`, not the raw drive date. Fail closed on
+        // mismatch rather than report a wrong-phase ok. The ORACLE is rule-kind dependent
+        // (#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);
             }
-            : { ...clone, op };
-    }
-    const cloneUuid = clone.uuid;
-    // --preserve-modified: X is the ONLY pre-existing row the compound touches (the
-    // clone/promote legs mint fresh rows). Capture its pre-write umd BEFORE the
-    // trash bumps it — the trash leg restores it forward, and the value rides the
-    // summary record's preModDates so the symmetric undo restore fires on the
-    // revived X (undo.ts, 2026-08-13 ruling). The clone leg above reads X but never
-    // writes it, so its umd is still pristine here.
-    const preserveModified = options.preserveModified === true;
-    const preUmd = preserveModified
-        ? createDbReader(deps.db, now, deps.zone).modDateOf(srcUuid)
-        : null;
-    // 2. Trash the original BEFORE promoting — the clone already holds X's content,
-    // and a live same-titled X would make the promote's project row-selection
-    // 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") {
-        return {
-            ...trash,
+        }
+        const warnings = [
+            landedRuleEcho(effParams, expectedStartIso ?? firstOccurrenceOf(deps.db, templateUuid)),
+            `the original ${expectedType} (uuid ${srcUuid}) was moved to the Trash; \`things undo\` ` +
+                "removes the new series (trash-both) and restores it",
+            PLACEMENT_NOTE,
+        ];
+        // DBLSPAWN1: if the promote PRESERVED the source (deadline / terminal-element
+        // trigger) as a FUTURE-dated instance, the app would spawn a duplicate on that date
+        // — trash the redundant occurrence and disclose (cursor mints the single real one).
+        const dbl = await trashRedundantFuturePreservedInstance(deps, kind, promote, options, txnId, now, afterCompletion);
+        if (dbl !== null) {
+            warnings.push(dbl.warning);
+            if (instanceUuid === dbl.trashedUuid)
+                instanceUuid = null;
+        }
+        const offRule = offRuleFirstNote(effParams);
+        if (offRule !== null)
+            warnings.push(offRule);
+        if (promote.warnings !== undefined)
+            warnings.push(...promote.warnings);
+        appendPromoteSummary(deps, {
+            startedAt,
             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",
-                }
-                : {}),
-        };
-    }
-    // 3. Native-promote the clone (with the ANCH2 Next drive + derived weekday).
-    const rule = ruleParamsFor(cloneUuid, effParams, nextIso);
-    const promote = kind === "project"
-        ? 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`;
-        return {
-            ...promote,
+            txnId,
+            templateUuid,
+            instanceUuid,
+            originalUuid: srcUuid,
+            invocation: `${op}: clone ${srcUuid} → trash ${srcUuid} → promote ${cloneUuid} → template ${templateUuid}`,
+            requested: effParams,
+            ...(preserveModified && preUmd !== null && { preModDates: { [srcUuid]: preUmd } }),
+        });
+        return promoteOk({
             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`,
-                }
-                : {}),
-        };
-    }
-    const { templateUuid, instanceUuid } = discoveryOf(promote);
-    // Post-drive verify (ANCH2 + YANCH1): the instance START must have landed on the
-    // requested `--when` — for a deadlined rule the driven Next is the deadline
-    // (when + startDaysEarlier) and the app back-shifts the start to `--when`, so the
-    // check is against `expectedStartIso`, not the raw drive date. Fail closed on
-    // mismatch rather than report a wrong-phase ok.
-    if (expectedStartIso !== undefined) {
-        const landed = firstOccurrenceOf(deps.db, templateUuid);
-        if (landed !== expectedStartIso) {
-            return nextMismatch(op, templateUuid, expectedStartIso, landed);
-        }
-    }
-    const warnings = [
-        landedRuleEcho(effParams, expectedStartIso ?? firstOccurrenceOf(deps.db, templateUuid)),
-        `the original ${expectedType} (uuid ${srcUuid}) was moved to the Trash; \`things undo\` ` +
-            "removes the new series (trash-both) and restores it",
-        PLACEMENT_NOTE,
-    ];
-    if (promote.warnings !== undefined)
-        warnings.push(...promote.warnings);
-    appendPromoteSummary(deps, {
-        startedAt,
-        op,
-        txnId,
-        templateUuid,
-        instanceUuid,
-        originalUuid: srcUuid,
-        invocation: `${op}: clone ${srcUuid} → trash ${srcUuid} → promote ${cloneUuid} → template ${templateUuid}`,
-        requested: effParams,
-        ...(preserveModified && preUmd !== null && { preModDates: { [srcUuid]: preUmd } }),
-    });
-    return promoteOk({
-        op,
-        templateUuid,
-        instanceUuid,
-        replacedUuid: cloneUuid,
-        title: src.title,
-        txnId,
-        warnings,
+            templateUuid,
+            instanceUuid,
+            replacedUuid: cloneUuid,
+            title: src.title,
+            txnId,
+            warnings,
+        });
     });
 }
 export function runMakeRepeatingTodo(deps, params, options = {}) {
@@ -504,9 +646,24 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
     // explicit anchor was given, and drive the anchor pop-ups — otherwise the
     // recurring rule keeps the dialog's untouched default (weekly Sunday, monthly
     // 1st, yearly January 1) and only the first occurrence is correct.
-    const anchorIso = isIsoDate(addParams["when"]) ? addParams["when"] : null;
-    const nextIso = anchorIso ?? undefined;
-    const effRule = { ...rule, ...deriveFixedAnchor(rule, anchorIso) };
+    //
+    // DEADLINE-MODE (DBLSPAWN1): a deadlined rule anchors on the DEADLINE, and each
+    // instance's START = deadline − startDaysEarlier (DACON1 DC4). `--when` is the
+    // scheduled START, so the date the dialog's "Next:" field + anchor pop-ups must
+    // carry is when + startDaysEarlier (the deadline); the app back-shifts the start to
+    // `--when`. `runAddRepeatingTodo` maps a concrete item-level `--deadline` into the
+    // rule's deadline/startDaysEarlier here (and strips it from the seed, so the source
+    // is not SRCFATE-preserved as a double-booking future instance). For a non-deadlined
+    // rule the shift is 0 and the drive date equals `--when` (unchanged).
+    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;
+    const effRule = {
+        ...rule,
+        ...deriveFixedAnchor(rule, driveIso),
+    };
     // ADR1 (issue #480, requested behavior #3): carry the base to-do's --reminder
     // onto the SERIES. The create leg sets a one-off reminderTime on the seed, but
     // the Repeat-dialog conversion does NOT preserve it — the dialog OWNS the repeat
@@ -542,137 +699,240 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
             },
         };
     }
-    // SESSGATE (#480): refuse a locked / full-screen session BEFORE seeding the row
-    // (the two legs are not atomic — a doomed promote would strand the seed). Zero
-    // mutation on refusal; a window merely on another Space is relocated in-drive.
-    const gate = await gateSessionReachability(deps, op);
+    // PRE-SEED UI PREFLIGHT (#480/#512): refuse a host that cannot drive the window,
+    // or a locked / full-screen session, BEFORE seeding the row (the two legs are not
+    // atomic — a doomed promote would strand the seed). Zero mutation on refusal; a
+    // window merely on another Space is relocated in-drive.
+    const gate = await gateUiPreflight(deps, op);
     if (gate !== null)
         return gate;
-    const startedAt = deps.now?.() ?? new Date();
-    const txnId = newTxnId(startedAt);
-    // 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"));
-    if (add.kind !== "ok" || add.uuid === null) {
-        return add.kind === "ok"
-            ? {
-                kind: "verify-failed",
-                op,
-                reason: "mismatch",
-                expected: {
-                    mode: "create",
-                    probe: { title, type: expectedType, sinceEpoch: 0 },
-                    assert: [],
-                },
-                observed: null,
-                detail: `the ${expectedType} was created but its uuid was not discovered — it cannot be promoted to repeating`,
-            }
-            : { ...add, op };
+    // 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);
+        // 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"));
+        if (add.kind !== "ok" || add.uuid === null) {
+            return add.kind === "ok"
+                ? {
+                    kind: "verify-failed",
+                    op,
+                    reason: "mismatch",
+                    expected: {
+                        mode: "create",
+                        probe: { title, type: expectedType, sinceEpoch: 0 },
+                        assert: [],
+                    },
+                    observed: null,
+                    detail: `the ${expectedType} was created but its uuid was not discovered — it cannot be promoted to repeating`,
+                }
+                : { ...add, op };
+        }
+        const createdUuid = add.uuid;
+        // 2. Native-promote the fresh row (ANCH2 Next drive + derived weekday + the
+        //    base reminder driven onto the series, ADR1).
+        const ruleParams = ruleParamsFor(createdUuid, effRuleWithReminder, nextIso);
+        const promote = kind === "project"
+            ? await promoteProjectViaGui(deps, ruleParams, legOptions(options, txnId, "ui"))
+            : await runMutation(deps, "todo.make-repeating", ruleParams, legOptions(options, txnId, "ui"));
+        if (promote.kind !== "ok") {
+            // The seed persists (the two legs are not atomic) but the promote did not
+            // land. RATIFIED RULING (2026-08-15, issue #480): auto-trash our OWN seed
+            // inside the txn — it is our artifact, recreatable verbatim from the command
+            // args, and the Trash is recoverable — then disclose it. If the auto-trash
+            // itself fails, the result carries the seed's REAL, resolvable uuid with a
+            // working `delete` remediation, so cleanup is never ambiguous (the #480
+            // second bug: a failed add-repeating left a residue whose reported uuid was
+            // not actionable).
+            const patch = await cleanupSeed(deps, kind, createdUuid, promote, options, txnId);
+            return { ...promote, op, ...patch };
+        }
+        const { templateUuid } = discoveryOf(promote);
+        let { instanceUuid } = discoveryOf(promote);
+        // Post-drive verify (ANCH2 + DBLSPAWN1): the instance START must have landed on the
+        // requested `--when` — for a deadlined rule the driven Next is the deadline (when +
+        // startDaysEarlier) and the app back-shifts the start to `--when`, so the check is
+        // against `expectedStartIso`, not the raw drive date. Fail closed on mismatch rather
+        // than report a wrong-phase ok. The series EXISTS here (promote landed) but on the
+        // wrong phase, so this is a genuine partial success, NOT a seed to trash. The
+        // ORACLE is rule-kind dependent (#508) — see landedFirstStart; an after-completion
+        // 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 warnings = [
+            landedRuleEcho(ruleParams, expectedStartIso ?? firstOccurrenceOf(deps.db, templateUuid)),
+            PLACEMENT_NOTE,
+        ];
+        // DBLSPAWN1 backstop: the deadline-mapping above keeps the seed deadline-free (no
+        // SRCFATE preserve), but any OTHER preserve trigger reaching the seed (defensive)
+        // would double-book a future first occurrence — trash the redundant instance.
+        const dbl = await trashRedundantFuturePreservedInstance(deps, kind, promote, options, txnId, startedAt, afterCompletion);
+        if (dbl !== null) {
+            warnings.push(dbl.warning);
+            if (instanceUuid === dbl.trashedUuid)
+                instanceUuid = null;
+        }
+        const offRule = offRuleFirstNote(ruleParams);
+        if (offRule !== null)
+            warnings.push(offRule);
+        if (promote.warnings !== undefined)
+            warnings.push(...promote.warnings);
+        appendPromoteSummary(deps, {
+            startedAt,
+            op,
+            txnId,
+            templateUuid,
+            instanceUuid,
+            invocation: `${op}: add "${title}" ${createdUuid} → template ${templateUuid}`,
+            requested: { title, ...effRule },
+        });
+        return promoteOk({
+            op,
+            templateUuid,
+            instanceUuid,
+            replacedUuid: createdUuid,
+            title,
+            txnId,
+            warnings,
+        });
+    });
+}
+/**
+ * Fold a concrete item-level `deadline` (and/or an explicit `startDaysEarlier`)
+ * into the RULE, returning the rule to promote with and the deadline the SEED
+ * should keep (none — the rule owns it). Shared by the to-do and project
+ * add-repeating verbs so one geometry, and one set of refusals, serves both.
+ *
+ * DBLSPAWN1 (docs/lab/dblspawn1-preserved-instance.md): each occurrence is due
+ * `deadline − when` days after its start (the "Add deadlines" + "start N days
+ * earlier" dialog fields). This is the deadline the series actually wants, and
+ * mapping it up front is also what keeps the SEED deadline-free — a to-do seed
+ * carrying a deadline is SRCFATE-preserved as a materialized instance, and a
+ * future-dated first occurrence then DOUBLE-BOOKS against the template cursor
+ * and spawns a duplicate on the date (cell C). A project seed is DELETE-fate, so
+ * there the un-mapped deadline was simply LOST rather than duplicated — a
+ * quieter bug with the same cause and the same fix. A deadline needs a concrete
+ * `when` (the per-occurrence offset is measured from the start) on/after it.
+ *
+ * DEADLINE/OFFSET AGREEMENT (ruling 2026-08-18): the same rule-global offset can
+ * be named two ways — a concrete `deadline` (offset = deadline − when) OR an
+ * explicit `startDaysEarlier` N (deadline derived as when + N). The geometry
+ * when/deadline/N is OVER-DETERMINED: the dialog's start-offset is rule-global
+ * and the first occurrence's start is derived as due − N, so there is no
+ * per-first-instance gap to absorb a disagreement (unlike DACON1's off-rule-first
+ * calendar freedom). So when BOTH are given they must AGREE — an exact match is
+ * harmless redundancy, a mismatch is inexpressible and refused fast (zero
+ * mutation). Either input ALONE maps to the rule.
+ */
+function mapDeadlineOntoRule(baseRule, when, deadline, startDaysEarlier) {
+    if (!isIsoDate(when)) {
+        throw new RangeError("a repeating --deadline or --start-days-earlier needs a concrete --when date (the deadline " +
+            "offset is measured from each occurrence's start) — schedule the series on a YYYY-MM-DD " +
+            "--when, or drop --deadline / --start-days-earlier");
     }
-    const createdUuid = add.uuid;
-    // 2. Native-promote the fresh row (ANCH2 Next drive + derived weekday + the
-    //    base reminder driven onto the series, ADR1).
-    const ruleParams = ruleParamsFor(createdUuid, effRuleWithReminder, nextIso);
-    const promote = kind === "project"
-        ? await promoteProjectViaGui(deps, ruleParams, legOptions(options, txnId, "ui"))
-        : await runMutation(deps, "todo.make-repeating", ruleParams, legOptions(options, txnId, "ui"));
-    if (promote.kind !== "ok") {
-        // The seed persists (the two legs are not atomic) but the promote did not
-        // land. RATIFIED RULING (2026-08-15, issue #480): auto-trash our OWN seed
-        // inside the txn — it is our artifact, recreatable verbatim from the command
-        // args, and the Trash is recoverable — then disclose it. If the auto-trash
-        // itself fails, the result carries the seed's REAL, resolvable uuid with a
-        // working `delete` remediation, so cleanup is never ambiguous (the #480
-        // second bug: a failed add-repeating left a residue whose reported uuid was
-        // not actionable).
-        const patch = await cleanupSeed(deps, kind, createdUuid, promote, options, txnId);
-        return { ...promote, op, ...patch };
+    let startEarlier;
+    if (deadline !== undefined) {
+        const derived = daysBetweenIso(when, deadline);
+        if (derived < 0) {
+            throw new RangeError(`--deadline (${deadline}) must be on or after --when (${when}) — a deadline cannot ` +
+                "precede the occurrence's own start");
+        }
+        if (startDaysEarlier !== undefined && startDaysEarlier !== derived) {
+            throw new RangeError(`--deadline (${deadline}) puts each occurrence's due date ${derived} day` +
+                `${derived === 1 ? "" : "s"} after its start (--when ${when}), but ` +
+                `--start-days-earlier says ${startDaysEarlier} — these disagree. Drop one, or make them ` +
+                `agree (--start-days-earlier ${derived}, or --deadline ${addDaysIso(when, startDaysEarlier)}).`);
+        }
+        startEarlier = derived;
     }
-    const { templateUuid, instanceUuid } = discoveryOf(promote);
-    // Post-drive verify (ANCH2): the driven Next must have landed as the first
-    // occurrence — fail closed on mismatch rather than report a wrong-phase ok.
-    // The series EXISTS here (promote landed) but on the wrong phase, so this is a
-    // genuine partial success, NOT a seed to trash — reported for correction.
-    if (nextIso !== undefined) {
-        const landed = firstOccurrenceOf(deps.db, templateUuid);
-        if (landed !== nextIso)
-            return nextMismatch(op, templateUuid, nextIso, landed);
+    else {
+        // `--start-days-earlier N` alone: the deadline is derived as when + N. A bad N
+        // (non-integer / negative) is refused by assertRepeatRule once mapped.
+        startEarlier = startDaysEarlier;
     }
-    const warnings = [
-        landedRuleEcho(ruleParams, nextIso ?? firstOccurrenceOf(deps.db, templateUuid)),
-        PLACEMENT_NOTE,
-    ];
-    if (promote.warnings !== undefined)
-        warnings.push(...promote.warnings);
-    appendPromoteSummary(deps, {
-        startedAt,
-        op,
-        txnId,
-        templateUuid,
-        instanceUuid,
-        invocation: `${op}: add "${title}" ${createdUuid} → template ${templateUuid}`,
-        requested: { title, ...effRule },
-    });
-    return promoteOk({
-        op,
-        templateUuid,
-        instanceUuid,
-        replacedUuid: createdUuid,
-        title,
-        txnId,
-        warnings,
-    });
-}
-export function runAddRepeatingTodo(deps, params, options = {}) {
-    const { frequency, interval, afterCompletion, weekdays, monthly, yearly, ends, ...add } = params;
-    const rule = {
-        frequency,
-        interval,
-        ...(afterCompletion !== undefined && { afterCompletion }),
-        ...(weekdays !== undefined && { weekdays }),
-        ...(monthly !== undefined && { monthly }),
-        ...(yearly !== undefined && { yearly }),
-        ...(ends !== undefined && { ends }),
-    };
-    const addParams = {
-        title: add.title,
-        ...(add.notes !== undefined && { notes: add.notes }),
-        ...(add.when !== undefined && { when: add.when }),
-        ...(add.reminder !== undefined && { reminder: add.reminder }),
-        ...(add.deadline !== undefined && { deadline: add.deadline }),
-        ...(add.tags !== undefined && { tags: add.tags }),
-        ...(add.checklistItems !== undefined && { checklistItems: add.checklistItems }),
-        ...(add.project !== undefined && { project: add.project }),
-        ...(add.area !== undefined && { area: add.area }),
-        ...(add.heading !== undefined && { heading: add.heading }),
-        ...(add.createdAt !== undefined && { createdAt: add.createdAt }),
+    // The RULE owns the deadline; the seed carries none.
+    return {
+        rule: { ...baseRule, deadline: true, startDaysEarlier: startEarlier },
+        seedDeadline: undefined,
     };
+}
+export async function runAddRepeatingTodo(deps, params, options = {}) {
+    // The rule/add split is driven by the exhaustive key map (splitAddRepeatingRule),
+    // not by a hand-written destructure — a field added to either vocabulary lands on
+    // the right leg instead of falling between them (#549 / YANCH1 #493).
+    const { rule: baseRule, add } = splitAddRepeatingRule(params);
+    const { afterCompletion } = params;
+    const startDaysEarlier = add.startDaysEarlier;
+    // A concrete `--deadline` (or `--start-days-earlier`) belongs to the RULE, not
+    // the seed — see mapDeadlineOntoRule for the geometry and the refusals. The
+    // to-do stakes: an un-mapped seed deadline makes the app preserve the seed as a
+    // future-dated instance that double-books the cursor (DBLSPAWN1 cell C).
+    let rule = baseRule;
+    let seedDeadline = add.deadline;
+    if ((add.deadline !== undefined || startDaysEarlier !== undefined) && afterCompletion !== true) {
+        ({ rule, seedDeadline } = mapDeadlineOntoRule(baseRule, add.when, add.deadline, startDaysEarlier));
+    }
+    else if (startDaysEarlier !== undefined) {
+        // afterCompletion === true here: an after-completion repeat has no calendar
+        // start to count a deadline back from — refuse rather than silently drop it.
+        throw new RangeError("--start-days-earlier applies only to a fixed-schedule deadline — an after-completion repeat " +
+            "has no calendar start to count back from; drop --after-completion or --start-days-earlier");
+    }
+    // The seed carries the WHOLE add vocabulary by spread (a field added to
+    // TodoAddRepeatingParams reaches the create leg without a line here), minus the
+    // two the rule took: `startDaysEarlier` is rule-only, and the deadline is
+    // whatever the geometry left for the seed (none, once mapped).
+    const addParams = { ...add };
+    delete addParams["startDaysEarlier"];
+    delete addParams["deadline"];
+    if (seedDeadline !== undefined)
+        addParams["deadline"] = seedDeadline;
     return addRepeatingViaCreate(deps, "todo", addParams, rule, add.title, options);
 }
-export function runAddRepeatingProject(deps, params, options = {}) {
-    const { frequency, interval, afterCompletion, weekdays, monthly, yearly, ends, ...add } = params;
-    const rule = {
-        frequency,
-        interval,
-        ...(afterCompletion !== undefined && { afterCompletion }),
-        ...(weekdays !== undefined && { weekdays }),
-        ...(monthly !== undefined && { monthly }),
-        ...(yearly !== undefined && { yearly }),
-        ...(ends !== undefined && { ends }),
-    };
+export async function runAddRepeatingProject(deps, params, options = {}) {
+    // Same exhaustive rule/add split as the to-do verb (one key map, both verbs).
+    const { rule: baseRule, add } = splitAddRepeatingRule(params);
+    const { afterCompletion } = params;
+    // A concrete `--deadline` maps to the RULE here exactly as it does on the to-do
+    // verb (DBLSPAWN1 residual). The project stakes are quieter than the to-do's but
+    // no more acceptable: a project seed is DELETE-fate, so the app does not preserve
+    // it into a double-booked instance — it simply DROPS the deadline, and the series
+    // came out undeadlined with nothing said. Mapped, every occurrence is due
+    // `deadline − when` days after its start.
+    let rule = baseRule;
+    let seedDeadline = add.deadline;
+    if (add.deadline !== undefined) {
+        if (afterCompletion === true) {
+            // The to-do verb can leave a deadline on an after-completion seed because
+            // that seed SURVIVES as the series' instance. An after-completion project's
+            // seed is deleted and its instance is minted deadline-free (RSIM-P P4), so
+            // the deadline would vanish either way — refuse rather than drop it quietly.
+            throw new RangeError("an after-completion repeating project cannot carry a --deadline: the rule has no calendar " +
+                "start to measure a per-occurrence deadline from, and the created project is replaced by " +
+                "the series' own instance, which is created without one — drop --after-completion to " +
+                "deadline every occurrence, or drop --deadline");
+        }
+        ({ rule, seedDeadline } = mapDeadlineOntoRule(baseRule, add.when, add.deadline, undefined));
+    }
     // Seed a pure-AX taxonomy: an area lands a selectable AREA-view row; otherwise
     // create in Someday (UIC4-f) so the promote skips the anytime-header problem.
     const seedWhen = add.when ?? (add.area === undefined ? "someday" : undefined);
-    const addParams = {
-        title: add.title,
-        ...(add.notes !== undefined && { notes: add.notes }),
-        ...(add.area !== undefined && { area: add.area }),
-        ...(seedWhen !== undefined && { when: seedWhen }),
-        ...(add.deadline !== undefined && { deadline: add.deadline }),
-        ...(add.todos !== undefined && { todos: add.todos }),
-        ...(add.items !== undefined && { items: add.items }),
-        ...(add.createdAt !== undefined && { createdAt: add.createdAt }),
-    };
+    // The whole add vocabulary by spread (see the to-do verb), with the two the
+    // promote owns re-derived: the seed taxonomy `when` and the mapped deadline.
+    const addParams = { ...add };
+    delete addParams["when"];
+    delete addParams["deadline"];
+    if (seedWhen !== undefined)
+        addParams["when"] = seedWhen;
+    if (seedDeadline !== undefined)
+        addParams["deadline"] = seedDeadline;
     return addRepeatingViaCreate(deps, "project", addParams, rule, add.title, options);
 }
 // ====================================================== template-direct clone
@@ -773,95 +1033,103 @@ export async function cloneTemplateViaRepromote(deps, kind, src, srcUuid, params
             },
         };
     }
-    // SESSGATE (#480): refuse a locked / full-screen session BEFORE minting the
-    // plain clone (a doomed promote would strand it). Zero mutation on refusal.
-    const gate = await gateSessionReachability(deps, op);
+    // PRE-SEED UI PREFLIGHT (#480/#512): refuse a host that cannot drive the window,
+    // or a locked / full-screen session, BEFORE minting the plain clone (a doomed
+    // promote would strand it). Zero mutation on refusal.
+    const gate = await gateUiPreflight(deps, op);
     if (gate !== null)
         return gate;
-    const startedAt = deps.now?.() ?? new Date();
-    const txnId = newTxnId(startedAt);
-    // 4. Mint the plain clone as an embedded leg — cloneTemplateAsPlain reaches the
-    //    clone orchestrator's plain-content path (recurrence + schedule stripped);
-    //    --title/--preserve-created ride through the CloneParams.
-    const cloneParams = {
-        uuid: srcUuid,
-        ...(params.title !== undefined && { title: params.title }),
-        ...(params.preserveCreated === true && { preserveCreated: true }),
-    };
-    const cloneOptions = { ...legOptions(options, txnId), cloneTemplateAsPlain: true };
-    const clone = kind === "project"
-        ? await runCloneProject(deps, cloneParams, cloneOptions)
-        : await runCloneTodo(deps, cloneParams, cloneOptions);
-    if (clone.kind !== "ok" || clone.uuid === null) {
-        // A nested-repeater refusal (a template CONTAINING a nested repeater) or any
-        // clone failure surfaces coherently here — re-label it to the compound op.
-        return clone.kind === "ok"
-            ? {
-                kind: "verify-failed",
-                op,
-                reason: "mismatch",
-                expected: {
-                    mode: "create",
-                    probe: { title, type: expectedType, sinceEpoch: 0 },
-                    assert: [],
-                },
-                observed: null,
-                detail: "the plain clone was created but its uuid was not discovered — nothing was promoted",
-            }
-            : { ...clone, op };
-    }
-    const cloneUuid = clone.uuid;
-    // 5. Native-promote the clone with the FULL decoded rule (ruleToInverseParams
-    //    carries deadline/start-earlier + the calendar anchors + ends).
-    const ruleParams = { uuid: cloneUuid, ...inverse };
-    const promote = kind === "project"
-        ? await promoteProjectViaGui(deps, ruleParams, legOptions(options, txnId, "ui"))
-        : await runMutation(deps, "todo.make-repeating", ruleParams, legOptions(options, txnId, "ui"));
-    if (promote.kind !== "ok") {
-        // The plain clone persists but was not promoted — honest report (no original
-        // to roll back; the clone is a fresh row the caller can trash and retry).
-        return {
-            ...promote,
-            op,
-            ...("detail" in promote
+    // COMPOSITE LOCK: clone-as-plain → promote-with-the-source's-rule is one verb;
+    // hold one lock across both legs.
+    return runComposite(deps, op, async () => {
+        const startedAt = deps.now?.() ?? new Date();
+        const txnId = newTxnId(startedAt);
+        // 4. Mint the plain clone as an embedded leg — cloneTemplateAsPlain reaches the
+        //    clone orchestrator's plain-content path (recurrence + schedule stripped);
+        //    --title/--preserve-created ride through the CloneParams.
+        const cloneParams = {
+            uuid: srcUuid,
+            ...(params.title !== undefined && { title: params.title }),
+            ...(params.preserveCreated === true && { preserveCreated: true }),
+        };
+        const cloneOptions = {
+            ...legOptions(options, txnId),
+            cloneTemplateAsPlain: true,
+        };
+        const clone = kind === "project"
+            ? await runCloneProject(deps, cloneParams, cloneOptions)
+            : await runCloneTodo(deps, cloneParams, cloneOptions);
+        if (clone.kind !== "ok" || clone.uuid === null) {
+            // A nested-repeater refusal (a template CONTAINING a nested repeater) or any
+            // clone failure surfaces coherently here — re-label it to the compound op.
+            return clone.kind === "ok"
                 ? {
-                    detail: `${promote.detail} — the plain clone (uuid ${cloneUuid}) was created but the promote ` +
-                        `did not land; trash the clone with \`things ${kind} delete ${cloneUuid}\` and retry`,
+                    kind: "verify-failed",
+                    op,
+                    reason: "mismatch",
+                    expected: {
+                        mode: "create",
+                        probe: { title, type: expectedType, sinceEpoch: 0 },
+                        assert: [],
+                    },
+                    observed: null,
+                    detail: "the plain clone was created but its uuid was not discovered — nothing was promoted",
                 }
-                : {}),
-        };
-    }
-    const { templateUuid, instanceUuid } = discoveryOf(promote);
-    const warnings = [NEW_SERIES_NOTE, PLACEMENT_NOTE];
-    if (params.preserveCreated === true) {
-        warnings.push("--preserve-created is best-effort on a template clone: the promote may replace the clone " +
-            "row with the new template, whose creation date is the conversion time");
-    }
-    if (src.repeating.paused === true) {
-        warnings.push(`the source template was PAUSED; the new series is created UNPAUSED and begins spawning — ` +
-            `pause it with \`things ${kind} pause-repeat\` if you want it suspended`);
-    }
-    if (promote.warnings !== undefined)
-        warnings.push(...promote.warnings);
-    // Summary WITHOUT originalUuid → undo is the add-repeating trash-both (remove
-    // the minted series; there is no original to restore).
-    appendPromoteSummary(deps, {
-        startedAt,
-        op,
-        txnId,
-        templateUuid,
-        instanceUuid,
-        invocation: `${kind}.clone (template) ${srcUuid}: clone → promote ${cloneUuid} → template ${templateUuid}`,
-        requested: { source: srcUuid, title, ...inverse },
-    });
-    return promoteOk({
-        op,
-        templateUuid,
-        instanceUuid,
-        replacedUuid: cloneUuid,
-        title,
-        txnId,
-        warnings,
+                : { ...clone, op };
+        }
+        const cloneUuid = clone.uuid;
+        // 5. Native-promote the clone with the FULL decoded rule (ruleToInverseParams
+        //    carries deadline/start-earlier + the calendar anchors + ends).
+        const ruleParams = { uuid: cloneUuid, ...inverse };
+        const promote = kind === "project"
+            ? await promoteProjectViaGui(deps, ruleParams, legOptions(options, txnId, "ui"))
+            : await runMutation(deps, "todo.make-repeating", ruleParams, legOptions(options, txnId, "ui"));
+        if (promote.kind !== "ok") {
+            // The plain clone persists but was not promoted — honest report (no original
+            // to roll back; the clone is a fresh row the caller can trash and retry).
+            return {
+                ...promote,
+                op,
+                ...("detail" in promote
+                    ? {
+                        detail: `${promote.detail} — the plain clone (uuid ${cloneUuid}) was created but the promote ` +
+                            `did not land; trash the clone with \`things ${kind} delete ${cloneUuid}\` and retry`,
+                    }
+                    : {}),
+            };
+        }
+        const { templateUuid, instanceUuid } = discoveryOf(promote);
+        const warnings = [NEW_SERIES_NOTE, PLACEMENT_NOTE];
+        if (params.preserveCreated === true) {
+            warnings.push("--preserve-created is best-effort on a template clone: the promote may replace the clone " +
+                "row with the new template, whose creation date is the conversion time");
+        }
+        if (src.repeating.paused === true) {
+            warnings.push(`the source template was PAUSED; the new series is created UNPAUSED and begins spawning — ` +
+                `pause it with \`things ${kind} pause-repeat\` if you want it suspended`);
+        }
+        if (promote.warnings !== undefined)
+            warnings.push(...promote.warnings);
+        // Summary WITHOUT originalUuid → undo is the add-repeating trash-both (remove
+        // the minted series; there is no original to restore).
+        appendPromoteSummary(deps, {
+            startedAt,
+            op,
+            txnId,
+            templateUuid,
+            instanceUuid,
+            invocation: `${kind}.clone (template) ${srcUuid}: clone → promote ${cloneUuid} → template ${templateUuid}`,
+            requested: { source: srcUuid, title, ...inverse },
+        });
+        return promoteOk({
+            op,
+            templateUuid,
+            instanceUuid,
+            replacedUuid: cloneUuid,
+            title,
+            txnId,
+            warnings,
+        });
     });
 }
 //# sourceMappingURL=promote-clone.js.map