things-api 0.15.0 → 0.17.0

package/dist/write/pipeline.d.ts

@@ -9,6 +9,8 @@ import { type EnvironmentTracker } from "./environment.ts";
 import { type LikelyCause } from "./failure-hints.ts";
 import { type HazardId } from "./guards.ts";
 import { type Acknowledgements, type OperationKind, type OperationParamsMap } from "./operations.ts";
+import { type CompletionContext } from "./completion-context.ts";
+import { type PreserveModifiedFailure } from "./preserve-modified.ts";
 import type { VectorId, WriteVector } from "./vectors/types.ts";
 import { type DeltaSpec, type RepeatingDiscovery } from "./verify/delta.ts";
 import { type PollerDeps } from "./verify/poller.ts";
@@ -20,6 +22,18 @@ export interface WriteOptions extends Acknowledgements {
     verifyTimeoutMs?: number;
     /** Return the plan without executing (nothing is audited). */
     dryRun?: boolean;
+    /**
+     * Keep this change off the `userModificationDate` (`umd`) timeline. When set,
+     * the pipeline captures every pre-existing TARGET row's `umd` before the write
+     * and — after the change verifies — restores it through the AppleScript `set
+     * modification date` leg (preserve-modified.ts), so a `changes`/watch query
+     * keyed on `umd` does not surface the edit. Rows the op CREATES are untouched
+     * (their `umd` is legitimately new); a create-only op (add) is a silent no-op.
+     * BEST-EFFORT: a failed restore never fails the (already-verified) mutation —
+     * it is disclosed per row on the result. Restore lands on `floor(umd0)` (the
+     * AppleScript 1-second floor) and is proven only on an UNSYNCED store (SYNC2).
+     */
+    preserveModified?: boolean;
     /**
      * Skip the post-execute state VERIFY poll for this write, treating a clean
      * transport (exit 0) as ok. Fail-loud on the transport itself is preserved (a
@@ -73,6 +87,17 @@ export interface WriteOptions extends Acknowledgements {
      * stay on the host clock.
      */
     normalizeWhen?: boolean;
+    /**
+     * TEMPLATE-DIRECT clone (template-clone via re-promote): tells the clone
+     * orchestrator to copy a repeating TEMPLATE source's content as a PLAIN item
+     * (recurrence stripped — no rule, no schedule/reminder), instead of refusing it
+     * (H-CLONE-SOURCE). NEVER set by a consumer entry point (the CLI/MCP/batch/client
+     * do not thread it) — only `cloneTemplateViaRepromote` sets it on the embedded
+     * clone leg, which it then native-promotes with the source's decoded rule. A bare
+     * `todo/project clone` of a template still routes through the compound (which sets
+     * this flag internally). See promote-clone.ts cloneTemplateViaRepromote.
+     */
+    cloneTemplateAsPlain?: boolean;
 }
 export interface MutationPlan {
     op: OperationKind;
@@ -130,6 +155,34 @@ export type MutationResult = {
      * the ORIGINAL mutation's identity. Absent on a normal (executed) result.
      */
     alreadyApplied?: true;
+    /**
+     * `--preserve-modified` disclosure (ADDITIVE, presence-keyed): the count of
+     * pre-existing target rows whose `userModificationDate` was restored to its
+     * pre-write value (to the floored second) so the change stays off the
+     * `changes`/watch timeline. Present only when the flag did real work —
+     * absent on a create-only or already-silent op, where restore is a no-op.
+     */
+    preservedModified?: number;
+    /**
+     * `--preserve-modified` per-row failures (ADDITIVE): rows the restore leg
+     * could not neutralize. Best-effort — the mutation itself stands; these are
+     * disclosed, never fatal. Absent when every restore leg succeeded.
+     */
+    preserveFailures?: PreserveModifiedFailure[];
+    /**
+     * HINTS1 completion-context (ADDITIVE, presence-keyed): on a successful
+     * `todo.complete` / `todo.cancel` only, the remaining OPEN work in the
+     * to-do's container(s), computed from a cheap post-verify re-read so an
+     * agent can notice an emptied project/Today without a second read.
+     * `project` is present when the to-do was in a project (directly or under a
+     * heading) and carries its `uuid`, `title`, and the OPEN, untrashed,
+     * non-template to-dos remaining in it (heading children included; `0` = the
+     * project's open work is now empty). `today` is present when the to-do was
+     * a Today member at mutation time and carries the OPEN Today members
+     * remaining. The hint INFORMS, never auto-acts; absent when neither applies
+     * (and on every other op). See {@link CompletionContext}.
+     */
+    context?: CompletionContext;
 } | {
     kind: "verify-failed";
     op: OperationKind;
@@ -140,6 +193,16 @@ export type MutationResult = {
     /** Advisory attribution when the failure signals point somewhere. */
     likelyCause?: LikelyCause;
     hint?: string;
+    /**
+     * The outcome is genuinely UNCERTAIN, not confirmed-failed (TRACE1, #487):
+     * a UI drive was aborted by the watchdog (or the process was interrupted)
+     * while the app might have been mid-commit, so the caller must re-check
+     * with `things show <uuid>` rather than assume nothing changed. Present
+     * only on the ui-drive watchdog timeout.
+     */
+    uncertain?: true;
+    /** The local trace file reconstructing this drive's timeline (TRACE1). */
+    tracePath?: string;
 } | {
     kind: "blocked";
     op: OperationKind;
@@ -170,6 +233,20 @@ export interface WriteDeps {
     /** Injectable for tests/lab: returns true when Things is up (launching if needed). */
     ensureRunning?: (alreadyRunning: boolean) => Promise<boolean>;
     isAppRunning?: () => boolean;
+    /**
+     * Seam for the default launch: the consent-free launch-readiness probe polled
+     * after a background launch, before dispatch (past the startup URL-drop
+     * window, #486). Only consulted by the default {@link ensureRunning}; ignored
+     * when a test injects its own `ensureRunning`.
+     */
+    appReady?: () => boolean;
+    /**
+     * The resolved on-disk database path (client-wired from the located DB). The
+     * default launch uses `${dbPath}-wal` as its consent-free readiness signal
+     * (the app has written since we launched it, #486). Absent = fall back to the
+     * LaunchServices launch-completion label.
+     */
+    dbPath?: string;
     /** Canary seam: does the installed sdef still declare the private command? */
     sdefProbe?: () => boolean;
     /** Consent-churn tripwire: tuple recorded per verified mutation (client wires the default). */

package/dist/write/pipeline.js

@@ -7,12 +7,14 @@
  * after verify.
  */
 import { execFile, execFileSync } from "node:child_process";
+import { statSync } from "node:fs";
 import { undoToken } from "../audit/schema.js";
 import { blockedCode, verifyFailedCode } from "../contracts.js";
 import { localToday } from "../model/dates.js";
-import { resolveProjectWriteTarget, resolveTaskUuidPrefix } from "../read/queries.js";
+import { liveSeriesInstances, resolveProjectWriteTarget, resolveTaskUuidPrefix, } from "../read/queries.js";
 import { namedProjectClause, taskMembershipClause } from "../read/scope.js";
 import { evaluateScope } from "./scope-guard.js";
+import { isThingsRunning } from "./automation-probe.js";
 import { readShortcutProxies, readUrlSchemeEnabled } from "./availability.js";
 import { COMMANDS } from "./commands.js";
 import { describeEnvironmentChanges, diffEnvironment, } from "./environment.js";
@@ -21,11 +23,15 @@ import { classifyTransportFailure, classifyVerifyFailure, } from "./failure-hint
 import { evaluateGuards } from "./guards.js";
 import { acquireMutationLock, MutationLockError } from "./lock.js";
 import { isHeadingTargetOp, } from "./operations.js";
+import { computeCompletionContext } from "./completion-context.js";
 import { planVector } from "./planner.js";
+import { isRepeatingTemplate } from "./pre-state.js";
+import { restoreModDates, } from "./preserve-modified.js";
 import { REVERSIBILITY } from "./reversibility.js";
 import { certificationOf } from "./vectors/ui-certification.js";
 import { createDbReader, evaluateDelta, getField, } from "./verify/delta.js";
 import { pollUntilVerified } from "./verify/poller.js";
+import { setInflight, trace } from "../trace/tracer.js";
 /**
  * Bounded backoff for the post-transport-failure re-verify (0½ defect (a)): a
  * GUI drive can abort part-way yet still have LANDED the change, so a nonzero
@@ -41,33 +47,108 @@ export function readAuthToken(db) {
         return null;
     }
 }
-function defaultIsAppRunning() {
+/**
+ * The ONE process-presence signal (shared with `doctor`/sync-health via
+ * automation-probe.ts) — a single stable `pgrep -x Things3` shape so macOS
+ * never sees a second command form.
+ */
+const defaultIsAppRunning = isThingsRunning;
+/** Poll interval for the launch waits. */
+const LAUNCH_POLL_INTERVAL_MS = 200;
+/** Cap on how long we wait for the launched PROCESS to appear. */
+const LAUNCH_PROCESS_TIMEOUT_MS = 20_000;
+/**
+ * Cap on how long we wait — after the process appears — for the app to become
+ * READY to land a write. A freshly launched Things registers its URL handler
+ * before it can actually apply a command: a command dispatched into that
+ * startup window is accepted and silently dropped (issue #486). We poll a cheap
+ * consent-free readiness signal past that window before dispatching.
+ */
+const LAUNCH_READY_TIMEOUT_MS = 12_000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** The write-ahead-log's mtime in ms, or null when it cannot be read. */
+function walMtimeMs(walPath) {
     try {
-        execFileSync("pgrep", ["-x", "Things3"], { stdio: "ignore" });
+        return statSync(walPath).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Consent-free launch-completion signal via LaunchServices — the fallback used
+ * only when the database path is unknown. NOT an Apple Event, so it never drags
+ * Automation consent onto the consent-free URL path. `lsappinfo` reports a
+ * process still coming up as `"Not Finished Launching"`; anything else is
+ * treated as launched. False on any error (treated as "not ready yet").
+ */
+function lsappinfoLaunched() {
+    try {
+        const out = execFileSync("lsappinfo", ["info", "-only", "StatusLabel", "-app", "com.culturedcode.ThingsMac"], { encoding: "utf8", timeout: 3000 });
+        if (out.trim() === "" || /Not Finished Launching/i.test(out))
+            return false;
         return true;
     }
     catch {
         return false;
     }
 }
-/** Background-launch Things and wait for the process (tier 1, by policy). */
-async function defaultEnsureRunning(alreadyRunning) {
+/**
+ * Consent-free launch-readiness signal — a DB-write-capability probe. A freshly
+ * launched Things recomputes its Today/repeat state and writes to its database
+ * shortly after launch; a URL command applied BEFORE the app is truly up is at
+ * risk of being dropped in the startup window (issue #486). Reading a file mtime
+ * needs no Apple Event, so this never triggers a consent prompt. "Ready" = the
+ * write-ahead log has advanced past the pre-launch baseline (the app has written
+ * since we launched it). APPRUN1 (golden-v3, Things 3.22.14): the WAL advanced
+ * ~0.9s after `open -g` — a real post-launch signal — while the process appeared
+ * at ~0.03s; the drop window itself did not reproduce in a clean airgapped clone
+ * (first URL landed immediately), so this wait is a defensive floor, and any
+ * residual drop is caught by verify and attributed `app-not-running`. Falls back
+ * to the LaunchServices label when the DB path is unknown. See
+ * docs/lab/apprun1-launch-readiness.md.
+ */
+function walAdvancedSince(walPath, baseline) {
+    if (walPath === undefined)
+        return lsappinfoLaunched();
+    const m = walMtimeMs(walPath);
+    return m !== null && (baseline === null || m > baseline);
+}
+/**
+ * Background-launch Things (tier 1, by policy — `open -g` keeps it off the
+ * foreground) and wait CLOSED-LOOP for it to become ready to land a write:
+ * first for the process to appear, then for the readiness signal to trip (past
+ * the startup URL-drop window, #486). Returns false only if the process never
+ * appears within {@link LAUNCH_PROCESS_TIMEOUT_MS}; once it is up we proceed
+ * after readiness trips OR the readiness cap elapses (best-effort — a residual
+ * drop is then caught by verify + attributed "app was not running").
+ */
+async function defaultEnsureRunning(alreadyRunning, opts = {}) {
     if (alreadyRunning)
         return true;
+    // Capture the readiness baseline BEFORE launching, so "the app has written
+    // since we launched it" is judged against the pre-launch WAL state.
+    const walPath = opts.dbPath !== undefined ? `${opts.dbPath}-wal` : undefined;
+    const walBaseline = walPath !== undefined ? walMtimeMs(walPath) : null;
+    const appReady = opts.appReady ?? (() => walAdvancedSince(walPath, walBaseline));
     await new Promise((resolve) => {
         execFile("open", ["-g", "-a", "Things3"], () => resolve());
     });
-    const deadline = Date.now() + 20_000;
-    while (Date.now() < deadline) {
-        if (defaultIsAppRunning()) {
-            // the post-launch settle wait must happen once, right after the process is first detected, before returning
-            await new Promise((r) => setTimeout(r, 2000)); // post-launch settle
-            return true;
-        }
-        // launch-detection retries are inherently sequential polling of the same process state
-        await new Promise((r) => setTimeout(r, 250));
+    // Phase 1: wait for the process to exist.
+    const processDeadline = Date.now() + LAUNCH_PROCESS_TIMEOUT_MS;
+    while (!defaultIsAppRunning()) {
+        if (Date.now() >= processDeadline)
+            return false;
+        await sleep(LAUNCH_POLL_INTERVAL_MS);
+    }
+    // Phase 2: wait for launch-readiness (past the URL-drop window).
+    const readyDeadline = Date.now() + LAUNCH_READY_TIMEOUT_MS;
+    while (!appReady()) {
+        if (Date.now() >= readyDeadline)
+            break; // best-effort: proceed and let verify judge
+        await sleep(LAUNCH_POLL_INTERVAL_MS);
     }
-    return false;
+    return true;
 }
 /** Capture pre-values of asserted fields + movement tripwires for the spec. */
 function capturePre(spec, deps, pre) {
@@ -514,14 +595,35 @@ export async function runMutation(deps, op, params, options = {}) {
         // plain opens and AppleEvents to a closed Things steal focus (A40/A41).
         // A simulating vector applies SQL to a fixture DB and never touches the
         // real app, so it neither needs nor may trigger the background launch.
-        if (vector.simulates !== true) {
-            const running = await (deps.ensureRunning ?? defaultEnsureRunning)(appRunning);
+        // A write can only land through a real transport when Things is up (a
+        // command dispatched into a closed app is silently dropped, #486), so a
+        // closed app is either launched-and-readied here or — when auto-launch is
+        // disabled — refused BEFORE dispatch with a plain environment error.
+        if (vector.simulates !== true && !appRunning) {
+            if (!config.autoLaunch) {
+                audit({ result: blockedCode({ reason: "environment" }) });
+                return {
+                    kind: "blocked",
+                    op,
+                    reason: "environment",
+                    likelyCause: "app-not-running",
+                    detail: "Things is not running, and auto-launch is turned off",
+                    remediation: "open Things (or run `things config set auto-launch true` to let writes launch it), " +
+                        "then retry",
+                };
+            }
+            const running = await (deps.ensureRunning ??
+                ((ar) => defaultEnsureRunning(ar, {
+                    ...(deps.dbPath !== undefined && { dbPath: deps.dbPath }),
+                    ...(deps.appReady !== undefined && { appReady: deps.appReady }),
+                })))(appRunning);
             if (!running) {
                 audit({ result: blockedCode({ reason: "environment" }) });
                 return {
                     kind: "blocked",
                     op,
                     reason: "environment",
+                    likelyCause: "app-not-running",
                     detail: "Things did not become available after a background launch attempt",
                     remediation: "launch Things manually and retry",
                 };
@@ -554,7 +656,54 @@ export async function runMutation(deps, op, params, options = {}) {
             pre: flattenPreFields(preCapture.fields),
             uuid: intentUuid,
         });
-        const executeResult = await vector.execute(invocation);
+        // Mark the write as touching the app (read by the CLI's signal handler so a
+        // SIGTERM/SIGINT can name the exact op — and last UI step — it interrupted,
+        // TRACE1 #487) and open the execute stage in the trace. Cleared the moment
+        // execute returns, whatever the outcome.
+        setInflight({
+            op,
+            uuid: intentUuid,
+            vector: vector.id,
+            uiDrive: vector.id === "ui",
+            startedAt: (deps.now?.() ?? new Date()).getTime(),
+        });
+        trace(() => ({
+            phase: "stage",
+            stage: "execute-start",
+            op,
+            vector: vector.id,
+            tier: effectiveTier,
+        }));
+        let executeResult;
+        try {
+            executeResult = await vector.execute(invocation);
+        }
+        finally {
+            setInflight(null);
+        }
+        trace(() => ({
+            phase: "stage",
+            stage: "execute-done",
+            op,
+            exitCode: executeResult.exitCode,
+            timedOut: executeResult.timedOut === true,
+            ...(executeResult.watchdog !== undefined && { watchdog: executeResult.watchdog }),
+        }));
+        // A vector that REFUSED at runtime before touching the app (the ui vector's
+        // session-reachability gate: a locked / full-screen session leaves no
+        // AX-reachable Things window for the dialog, SESSGATE #480). Nothing was
+        // mutated → a `blocked` outcome (exit 4), never a transport failure.
+        if (executeResult.blocked !== undefined) {
+            const { hazard, detail, remediation } = executeResult.blocked;
+            audit({
+                result: blockedCode({ hazard, reason: "hazard" }),
+                vector: vector.id,
+                disruption: effectiveTier,
+                invocation: invocation.redactedPayload,
+                pre: flattenPreFields(preCapture.fields),
+            });
+            return { kind: "blocked", op, reason: "hazard", hazard, detail, remediation };
+        }
         // Verify under the injected clock (deps.now/deps.zone), never the wall
         // clock: an `evening`/`today` write dated pinned-today must read back IN
         // Today at verify time, or its today/evening marker assertion fails under a
@@ -576,6 +725,46 @@ export async function runMutation(deps, op, params, options = {}) {
             // with bounded backoff and treat a landed target state as SUCCESS.
             const recovery = await pollUntilVerified(() => evaluateDelta(delta, reader, preCapture), RECOVERY_VERIFY_TIMEOUT_MS, deps.poller ?? {});
             if (recovery.kind !== "ok") {
+                // The ui-drive WATCHDOG timeout is its own honest outcome (TRACE1 #487):
+                // the CLI gave up first and cleared the dialog, but a drive aborted while
+                // the OK was possibly mid-commit cannot promise the app is untouched — so
+                // it is reported UNCERTAIN with the trace path and a "re-check first"
+                // remediation, distinct from a plain transport failure with no landed change.
+                const wd = executeResult.watchdog;
+                if (wd !== undefined) {
+                    audit({
+                        result: verifyFailedCode({ reason: "timeout" }),
+                        vector: vector.id,
+                        disruption: effectiveTier,
+                        invocation: invocation.redactedPayload,
+                        pre: flattenPreFields(preCapture.fields),
+                        observed: recovery.observed,
+                    });
+                    const budgetS = Math.round(wd.budgetMs / 1000);
+                    const elapsedS = Math.round(wd.elapsedMs / 1000);
+                    const cleared = wd.clear === "dismissed"
+                        ? "the open dialog was dismissed"
+                        : wd.clear === "cleared-blind"
+                            ? "the Things window was closed and reopened to clear the open dialog"
+                            : "a dialog may still be open in Things";
+                    const traceNote = wd.tracePath != null && wd.tracePath !== ""
+                        ? ` The step timeline is at ${wd.tracePath}.`
+                        : "";
+                    return {
+                        kind: "verify-failed",
+                        op,
+                        reason: "timeout",
+                        expected: delta,
+                        observed: recovery.observed,
+                        detail: `the GUI drive ran past its ${budgetS}s budget at step "${wd.lastStep}" (after ` +
+                            `~${elapsedS}s) and the CLI stopped it before the change could be confirmed; ` +
+                            `${cleared}. The outcome is UNCERTAIN — a rule committed at the last moment could ` +
+                            `still appear — so re-check with \`things show ${intentUuid ?? "<uuid>"}\` before ` +
+                            `retrying (retrying could create a duplicate series).${traceNote}`,
+                        uncertain: true,
+                        ...(wd.tracePath != null && wd.tracePath !== "" && { tracePath: wd.tracePath }),
+                    };
+                }
                 audit({
                     result: verifyFailedCode({ reason: "silent-noop" }),
                     vector: vector.id,
@@ -612,6 +801,15 @@ export async function runMutation(deps, op, params, options = {}) {
         else {
             outcome = await pollUntilVerified(() => evaluateDelta(delta, reader, preCapture), timeoutMs, deps.poller ?? {});
         }
+        trace(() => ({
+            phase: "stage",
+            stage: "verify",
+            op,
+            kind: outcome.kind,
+            attempts: outcome.attempts,
+            elapsedMs: outcome.elapsedMs,
+            recovered: transportRecovered,
+        }));
         const auditCommon = {
             vector: vector.id,
             disruption: effectiveTier,
@@ -627,15 +825,53 @@ export async function runMutation(deps, op, params, options = {}) {
                     : delta.mode === "ordering"
                         ? (delta.subject ?? null)
                         : null);
-            audit({ ...auditCommon, result: "ok", uuid });
+            // --preserve-modified: after the change verifies, restore the pre-write
+            // `userModificationDate` of every pre-existing TARGET row the op BUMPED, so
+            // the edit stays off the umd-keyed `changes`/watch timeline (TAGMOD T5).
+            // The pre-read already captured each asserted/cascade row's umd
+            // (preCapture.modDates); a null capture is a row the op CREATED (skip it),
+            // and a row whose umd did not rise needs no restore (a silent op — no-op).
+            // Best-effort: a failed restore is disclosed per row, never fatal (the
+            // mutation already stands). The captured pre-values ride the audit record
+            // when the flag is active (enables a future symmetric undo).
+            let preserve = null;
+            let preModDatesAudit;
+            if (options.preserveModified === true) {
+                const postReader = createDbReader(deps.db, deps.now?.() ?? new Date(), deps.zone);
+                const captured = {};
+                const targets = [];
+                for (const [tUuid, preUmd] of Object.entries(preCapture.modDates)) {
+                    captured[tUuid] = preUmd;
+                    if (preUmd === null)
+                        continue; // a row the op created — legitimately new umd
+                    const post = postReader.modDateOf(tUuid);
+                    if (post !== null && post > preUmd)
+                        targets.push({ uuid: tUuid, preUmd });
+                }
+                if (Object.keys(captured).length > 0)
+                    preModDatesAudit = captured;
+                preserve = await restoreModDates(deps.db, deps.vectors, targets);
+            }
+            audit({
+                ...auditCommon,
+                result: "ok",
+                uuid,
+                ...(preModDatesAudit !== undefined && { preModDates: preModDatesAudit }),
+            });
             if (deps.environment !== undefined) {
                 deps.environment.record(deps.environment.capture());
             }
+            // Deleting a repeating TEMPLATE is allowed (byte-identical to the GUI's own
+            // Edit ▸ Delete, SERDEL S1) but is IRREVERSIBLE headlessly — the app forbids
+            // restoring a template out to a list (AS 301), so its only revival is Trash ▸
+            // Put Back. Treat it like an irreversible op (no undo token) and disclose the
+            // consequences below. Trashing an INSTANCE (no rule of its own) is unaffected.
+            const templateDelete = (op === "todo.delete" || op === "project.delete") && isRepeatingTemplate(pre.target);
             // The undo token identifies THIS record on the trail (see undoToken); a
             // leg's token would be its shared txn id, but legs are never undone
             // directly, so we only surface it for non-leg writes. Irreversible ops get
             // NO token: `undo --txn` can only refuse it, so emitting one is misleading.
-            const resultToken = options.txn?.role === "leg" || REVERSIBILITY[op].class === "irreversible"
+            const resultToken = options.txn?.role === "leg" || REVERSIBILITY[op].class === "irreversible" || templateDelete
                 ? undefined
                 : undoToken({
                     ts: startedAt.toISOString(),
@@ -646,6 +882,28 @@ export async function runMutation(deps, op, params, options = {}) {
                     ...(options.txn !== undefined && { txn: options.txn }),
                 });
             const warnings = [];
+            // Auto-launch disclosure (#486): the app was not running when this write
+            // started, so it was background-launched for the write. Never silent — a
+            // side effect the caller should see (a simulating vector never launches).
+            if (!appRunning && vector.simulates !== true) {
+                warnings.push("Things was not running, so it was launched in the background for this write");
+            }
+            // Template-delete disclosure (public deletes only — internal trash-both legs
+            // run under a txn and aggregate their own result). The series stops, its live
+            // instances are left in place (count + name the current occurrence), and the
+            // only revival is the app's Trash ▸ Put Back.
+            if (templateDelete && options.txn?.role !== "leg" && pre.target !== null) {
+                const kindNoun = op === "project.delete" ? "project" : "to-do";
+                const series = liveSeriesInstances(deps.db, pre.target.uuid);
+                warnings.push("this repeating series will no longer generate new occurrences");
+                if (series.count > 0) {
+                    warnings.push(`its ${series.count} existing occurrence${series.count === 1 ? " was" : "s were"} ` +
+                        "left in place (not moved to the Trash)" +
+                        (series.currentUuid !== null ? ` — the current one is ${series.currentUuid}` : ""));
+                }
+                warnings.push(`this cannot be undone here — to bring the series back, use the Things app's Trash ` +
+                    `(Put Back on the ${kindNoun})`);
+            }
             if (transportRecovered) {
                 warnings.push("the GUI drive reported a transport error, but a follow-up re-read confirmed the " +
                     "requested change DID land — no retry is needed (retrying could overwrite it)");
@@ -678,6 +936,15 @@ export async function runMutation(deps, op, params, options = {}) {
                     `${describeEnvironmentChanges(envChanges)} — the first use of another ` +
                     `capability may show a macOS consent prompt`);
             }
+            // HINTS1 completion-context: on a verified complete/cancel of a to-do,
+            // attach the remaining OPEN work in its project and/or Today. Applicability
+            // is read off the captured pre-state, so a to-do in neither costs no extra
+            // reads; the counts are a cheap post-verify re-read via the library's own
+            // read paths.
+            const completionContext = op === "todo.complete" || op === "todo.cancel"
+                ? computeCompletionContext(deps.db, pre.target, deps.now?.() ?? new Date(), deps.zone)
+                : undefined;
+            trace(() => ({ phase: "result", op, kind: "ok", uuid, vector: vector.id }));
             return {
                 kind: "ok",
                 op,
@@ -692,6 +959,16 @@ export async function runMutation(deps, op, params, options = {}) {
                 tier: effectiveTier,
                 ...(resultToken !== undefined && { undoToken: resultToken }),
                 ...(outcome.repeating !== undefined && { repeating: outcome.repeating }),
+                // Disclose --preserve-modified only when it did real work (restored a
+                // bump or hit a restore failure) — a create-only / already-silent op
+                // stays clean (no `preservedModified: 0` noise).
+                ...(preserve !== null &&
+                    (preserve.restored > 0 || preserve.failures.length > 0) && {
+                    preservedModified: preserve.restored,
+                }),
+                ...(preserve !== null &&
+                    preserve.failures.length > 0 && { preserveFailures: preserve.failures }),
+                ...(completionContext !== undefined && { context: completionContext }),
                 ...(warnings.length > 0 && { warnings }),
             };
         }
@@ -712,6 +989,7 @@ export async function runMutation(deps, op, params, options = {}) {
             reason: outcome.kind,
             vector: vector.id,
             urlSchemeEnabled: (deps.urlSchemeEnabled ?? (() => readUrlSchemeEnabled().enabled))(),
+            appWasRunning: appRunning,
             environmentChanges: envChanges,
         }));
     }