things-api 0.16.0 → 0.18.0

package/dist/write/promote-clone.js

@@ -1,11 +1,14 @@
 import { undoToken } from "../audit/schema.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 { assessOffRuleFirst, daysBetweenIso, deriveFixedAnchor, isIsoDate, } from "./repeat-anchor.js";
 import { assertRepeatRule, ruleToInverseParams } 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 " +
     "not automatically restored (best-effort placement is not yet wired for this container); " +
     "reposition it with `things reorder` if the order matters";
@@ -50,8 +53,78 @@ function blockedUiDrive(op) {
             "`things config set ui-enabled true` and Accessibility granted to this process (see docs/setup.md)",
     };
 }
-/** Pick the rule fields (frequency/interval + calendar anchors) as a RepeatRuleParams. */
-function ruleParamsFor(uuid, rule) {
+/**
+ * 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).
+ */
+async function gateSessionReachability(deps, op) {
+    if (!deps.config.ui.enabled)
+        return null;
+    const ui = deps.vectors.find((v) => v.probeReachability !== undefined);
+    if (ui?.probeReachability === undefined)
+        return null;
+    const verdict = await ui.probeReachability();
+    if (verdict.reachable || verdict.scope !== "session")
+        return null;
+    return {
+        kind: "blocked",
+        op,
+        reason: "hazard",
+        hazard: H_UI_SESSION_UNREACHABLE,
+        detail: verdict.detail,
+        remediation: verdict.remediation,
+    };
+}
+/**
+ * Auto-trash a promote composite's own seeded item after its promote leg failed
+ * (RATIFIED RULING 2026-08-15, issue #480). The add/add-repeating legs are NOT
+ * atomic: the seed persists even when the promote no-ops. The seed is OUR
+ * artifact — recreatable verbatim from the command args — and the Trash is
+ * recoverable, so we trash it inside the same txn and disclose it. The
+ * distinction the failure MUST make honest: an auto-trash that SUCCEEDS points
+ * the caller at `restore` (the row is in the Trash); one that FAILS points at
+ * `delete` with the seed's REAL, resolvable uuid (never a buried, non-actionable
+ * uuid — the #480 second bug). Returns a `detail` patch appended to the promote
+ * result's own message (best-effort: a non-`detail` result shape is left as-is).
+ */
+async function cleanupSeed(deps, kind, createdUuid, promote, options, txnId) {
+    const expectedType = kind === "project" ? "project" : "to-do";
+    const trashOp = kind === "project" ? "project.delete" : "todo.delete";
+    const trashed = await runMutation(deps, trashOp, { uuid: createdUuid }, legOptions(options, txnId));
+    const cleanupNote = trashed.kind === "ok"
+        ? `the seeded ${expectedType} (uuid ${createdUuid}) was created but the promote did not land, ` +
+            `so it was moved to the Trash — recreate it from the command args, or restore it with ` +
+            `\`things ${kind} restore ${createdUuid}\``
+        : `the seeded ${expectedType} (uuid ${createdUuid}) was created but the promote did not land, ` +
+            `and it could NOT be auto-trashed — remove it with \`things ${kind} delete ${createdUuid}\``;
+    return "detail" in promote
+        ? { detail: `${promote.detail} — ${cleanupNote}` }
+        : {};
+}
+/**
+ * Pick the rule fields (frequency/interval + calendar anchors + deadline offset)
+ * as a RepeatRuleParams, plus the requested first-occurrence date to drive into
+ * the dialog's "Next:" field (ANCH2, issue #476). `nextIso` is the item's
+ * scheduled date; omitted (or after-completion) leaves Next at the app default.
+ *
+ * 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).
+ */
+function ruleParamsFor(uuid, rule, nextIso) {
     return {
         uuid,
         frequency: rule.frequency,
@@ -61,6 +134,148 @@ function ruleParamsFor(uuid, rule) {
         ...(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 UNIT_SINGULAR = {
+    daily: "day",
+    weekly: "week",
+    monthly: "month",
+    yearly: "year",
+};
+const UNIT_PLURAL = {
+    daily: "days",
+    weekly: "weeks",
+    monthly: "months",
+    yearly: "years",
+};
+/**
+ * A one-line echo of the LANDED series so a caller can eyeball what actually
+ * committed — the cadence, the verified first-occurrence START, and the deadline
+ * offset (YANCH1 #493 item 5). It rides the verified data (the anchor is asserted
+ * == requested by the post-drive verify), so it describes the START date rather
+ * than the internal deadline anchor, which for a deadlined rule is N days later.
+ */
+function landedRuleEcho(rule, startIso) {
+    const cadence = rule.interval === 1
+        ? `every ${UNIT_SINGULAR[rule.frequency]}`
+        : `every ${rule.interval} ${UNIT_PLURAL[rule.frequency]}`;
+    if (rule.afterCompletion === true) {
+        return `landed: the series repeats ${cadence} after each occurrence is completed`;
+    }
+    const first = startIso !== null ? `; the first occurrence is ${startIso}` : "";
+    const offset = rule.startDaysEarlier ?? 0;
+    const deadlineNote = offset > 0
+        ? `, with a deadline ${offset} day${offset === 1 ? "" : "s"} later`
+        : rule.deadline === true
+            ? ", with a deadline on each occurrence"
+            : "";
+    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
+ * Next-honored check. `null` when the row/date is absent.
+ */
+function firstOccurrenceOf(db, templateUuid) {
+    const row = db
+        .prepare("SELECT rt1_instanceCreationStartDate AS ic FROM TMTask WHERE uuid = ?")
+        .get(templateUuid);
+    if (row === undefined || row.ic === null)
+        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);
+}
+/**
+ * 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) {
+    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
+ * fail-closed rather than as a silent ok.
+ */
+function nextMismatch(op, templateUuid, requestedIso, landedIso) {
+    return {
+        kind: "verify-failed",
+        op,
+        reason: "mismatch",
+        expected: { mode: "update", uuid: templateUuid, assert: [] },
+        observed: null,
+        detail: `the repeating series was created but its first occurrence landed on ` +
+            `${landedIso ?? "an undetermined date"}, not the requested ${requestedIso} — the Next-field ` +
+            "drive did not take; the series exists and can be corrected with `things reschedule-repeat`",
     };
 }
 /** The discovered template/instance from a promote leg's result. */
@@ -159,6 +374,33 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
                 : "verify the uuid with `things show <uuid>`, or use `things project make-repeating` for a project",
         };
     }
+    // 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
+    // occurrence — an explicit `--when` if given, else the item's own scheduled
+    // date. YANCH1 (issue #493): also DERIVE the calendar anchor (weekly weekday /
+    // monthly day / yearly month+day) from that date when no 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 (the #493 anchor-drop).
+    //
+    // DEADLINE-MODE ANCHORING (YANCH1 #493, in-lab golden-v3): a deadlined rule
+    // anchors on the DEADLINE, and each instance's START = anchor − startDaysEarlier
+    // (probe: anchor+Next driven to Oct-16 with start-14 → of=[Oct-16], instance
+    // start = Oct-02). `--when` is the scheduled START, so the date the dialog's
+    // anchor pop-ups + "Next:" field must carry is when + startDaysEarlier (the
+    // deadline); the app then back-shifts the start to `when`. For a non-deadlined
+    // rule the shift is 0 and the drive date equals `--when` (unchanged).
+    const whenIso = isIsoDate(params.next) ? params.next : src.startDate;
+    const deadlineShift = params.deadline === true || (params.startDaysEarlier ?? 0) > 0
+        ? (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;
+    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) {
         return blockedUiDrive(op);
@@ -172,7 +414,7 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
                 vector: "ui",
                 tier: 3,
                 invocation: `clone ${srcUuid} (--preserve-created) → make-repeating the clone (Repeat… → ` +
-                    `frequency=${params.frequency}, interval=${params.interval}) → trash the original ${srcUuid}`,
+                    `frequency=${effParams.frequency}, interval=${effParams.interval}) → trash the original ${srcUuid}`,
                 expectedDelta: {
                     mode: "create",
                     probe: { title: src.title, type: expectedType, sinceEpoch: 0 },
@@ -182,6 +424,12 @@ 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);
+    if (gate !== null)
+        return gate;
     const startedAt = now;
     const txnId = newTxnId(startedAt);
     // 1. Clone the source as a disposable, embedded leg (--preserve-created). The
@@ -235,8 +483,8 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
                 : {}),
         };
     }
-    // 3. Native-promote the clone.
-    const rule = ruleParamsFor(cloneUuid, params);
+    // 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"));
@@ -259,12 +507,37 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
                 : {}),
         };
     }
-    const { templateUuid, instanceUuid } = discoveryOf(promote);
+    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.
+    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,
     ];
+    // 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);
+    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, {
@@ -275,7 +548,7 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
         instanceUuid,
         originalUuid: srcUuid,
         invocation: `${op}: clone ${srcUuid} → trash ${srcUuid} → promote ${cloneUuid} → template ${templateUuid}`,
-        requested: params,
+        requested: effParams,
         ...(preserveModified && preUmd !== null && { preModDates: { [srcUuid]: preUmd } }),
     });
     return promoteOk({
@@ -303,6 +576,42 @@ 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);
+    // 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
+    // anchor (weekly weekday / monthly day / yearly month+day) from --when when no
+    // 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.
+    //
+    // 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
+    // reminder via its "Add reminders" control — so a base reminder was silently
+    // dropped from the template (verified empty on golden-v2,
+    // docs/lab/adr1-add-repeating-reveal.md). Drive the dialog's reminder with the
+    // base time so every spawned occurrence carries it (ANCH2: the reminder picker
+    // commits reminderTime deterministically). Projects have no reminder vocabulary,
+    // so addParams never carries one there.
+    const baseReminder = typeof addParams["reminder"] === "string" ? addParams["reminder"] : undefined;
+    const effRuleWithReminder = baseReminder !== undefined ? { ...effRule, reminder: baseReminder } : effRule;
     // The promote leg drives the GUI — block before creating anything if the ack is missing.
     if (options.dangerouslyDriveGui !== true && options.dryRun !== true) {
         return blockedUiDrive(op);
@@ -327,6 +636,12 @@ 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);
+    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.
@@ -349,17 +664,53 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
             : { ...add, op };
     }
     const createdUuid = add.uuid;
-    // 2. Native-promote the fresh row.
-    const ruleParams = ruleParamsFor(createdUuid, rule);
+    // 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") {
-        // Honest: the item was created (and persists) but the promote did not land.
-        return { ...promote, op };
+        // 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, instanceUuid } = discoveryOf(promote);
-    const warnings = [PLACEMENT_NOTE];
+    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.
+    if (expectedStartIso !== undefined) {
+        const landed = firstOccurrenceOf(deps.db, templateUuid);
+        if (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);
+    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, {
@@ -369,7 +720,7 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
         templateUuid,
         instanceUuid,
         invocation: `${op}: add "${title}" ${createdUuid} → template ${templateUuid}`,
-        requested: { title, ...rule },
+        requested: { title, ...effRule },
     });
     return promoteOk({
         op,
@@ -381,9 +732,9 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
         warnings,
     });
 }
-export function runAddRepeatingTodo(deps, params, options = {}) {
-    const { frequency, interval, afterCompletion, weekdays, monthly, yearly, ends, ...add } = params;
-    const rule = {
+export async function runAddRepeatingTodo(deps, params, options = {}) {
+    const { frequency, interval, afterCompletion, weekdays, monthly, yearly, ends, startDaysEarlier, ...add } = params;
+    const baseRule = {
         frequency,
         interval,
         ...(afterCompletion !== undefined && { afterCompletion }),
@@ -392,12 +743,71 @@ export function runAddRepeatingTodo(deps, params, options = {}) {
         ...(yearly !== undefined && { yearly }),
         ...(ends !== undefined && { ends }),
     };
+    // DBLSPAWN1 (docs/lab/dblspawn1-preserved-instance.md): a concrete item-level
+    // `--deadline <date>` on add-repeating maps to the RULE's deadline — 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 it
+    // keeps the SEED deadline-free: a seed carrying a deadline is SRCFATE-preserved as a
+    // materialized instance, and when that first occurrence is future-dated the app
+    // DOUBLE-BOOKS it against the template cursor and spawns a duplicate on the date
+    // (cell C). The seed owning the deadline was the two-step dance the live agent hit
+    // (add-repeating dropped the rule deadline, forcing a follow-up reschedule-repeat);
+    // mapping it up front makes that unnecessary. A deadline needs a concrete `--when`
+    // (the per-occurrence offset is deadline − start) and must be on/after it.
+    //
+    // DEADLINE/OFFSET AGREEMENT (ruling 2026-08-18): the same rule-global offset can be
+    // named two ways — a concrete `--deadline <date>` (offset = deadline − when) OR an
+    // explicit `--start-days-earlier N` (offset = 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 (`deadline − when == N`)
+    // — an exact match is harmless redundancy, a mismatch is inexpressible and refused
+    // fast (zero mutation). Either input ALONE maps to the rule and keeps the seed
+    // deadline-free.
+    let rule = baseRule;
+    let seedDeadline = add.deadline;
+    if ((add.deadline !== undefined || startDaysEarlier !== undefined) && afterCompletion !== true) {
+        if (!isIsoDate(add.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");
+        }
+        let startEarlier;
+        if (add.deadline !== undefined) {
+            const derived = daysBetweenIso(add.when, add.deadline);
+            if (derived < 0) {
+                throw new RangeError(`--deadline (${add.deadline}) must be on or after --when (${add.when}) — a deadline cannot ` +
+                    "precede the occurrence's own start");
+            }
+            if (startDaysEarlier !== undefined && startDaysEarlier !== derived) {
+                throw new RangeError(`--deadline (${add.deadline}) puts each occurrence's due date ${derived} day` +
+                    `${derived === 1 ? "" : "s"} after its start (--when ${add.when}), but ` +
+                    `--start-days-earlier says ${startDaysEarlier} — these disagree. Drop one, or make them ` +
+                    `agree (--start-days-earlier ${derived}, or --deadline ${addDaysIso(add.when, startDaysEarlier)}).`);
+            }
+            startEarlier = derived;
+        }
+        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;
+        }
+        rule = { ...baseRule, deadline: true, startDaysEarlier: startEarlier };
+        seedDeadline = undefined; // the RULE owns the deadline; the seed carries none
+    }
+    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");
+    }
     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 }),
+        ...(seedDeadline !== undefined && { deadline: seedDeadline }),
         ...(add.tags !== undefined && { tags: add.tags }),
         ...(add.checklistItems !== undefined && { checklistItems: add.checklistItems }),
         ...(add.project !== undefined && { project: add.project }),
@@ -453,7 +863,7 @@ function blockedCloneSource(op, detail, remediation) {
  * produce: two simultaneous end bounds, and a multi-anchor month/year rule.
  */
 function inexpressibleReason(rule) {
-    if (rule.endDate !== null && rule.remainingCount !== null) {
+    if (rule.endDate !== null && rule.occurrenceCount !== null) {
         return ("the source rule ends on BOTH a date and an occurrence count, which the repeat vocabulary " +
             "cannot express (its Ends bound is a single choice)");
     }
@@ -531,6 +941,11 @@ 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);
+    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