things-api 0.16.0 → 0.18.0

package/dist/cli/commands/helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `things helpers` — lifecycle for the optional helper pair (one installed
+ * bundle housing both):
+ *
+ *   things-deputy — app automation (mutations), unsandboxed.
+ *   things-reader — database/file reads, sandboxed to a user-granted folder.
+ *
+ * Running them means macOS permission prompts and grants attach to two stable
+ * identities instead of every terminal or agent runtime that invokes
+ * `things`, so grants stop re-prompting when those runtimes update. Routing is
+ * tri-state (`helpers-enabled`: auto | true | false, default auto —
+ * installation is the intent signal), overridable per invocation with
+ * THINGS_API_HELPERS or the global `--helpers`/`--no-helpers` flags; the CLI
+ * always falls back to direct execution when a helper is unavailable.
+ */
+import type { Command } from "commander";
+export declare function registerHelpers(program: Command): void;

package/dist/cli/commands/helpers.js

@@ -0,0 +1,148 @@
+import { helpersStatus, ExitCode, grantReader, installHelpers, loadConfig, okEnvelope, restartHelpers, uninstallHelpers, } from "../../index.js";
+function envelopeMeta(started) {
+    return { dbVersion: null, fingerprint: "unknown", elapsedMs: Date.now() - started };
+}
+/** One line describing what the configured mode means for this machine. */
+function routingLine(status) {
+    switch (status.mode) {
+        case "true":
+            return "enabled — every process routes through the helpers, and reports when it cannot";
+        case "false":
+            return "disabled (things config set helpers-enabled auto)";
+        case "auto":
+            return status.bundleInstalled
+                ? "auto — the installed helpers are used while healthy; a failure is reported, never silent"
+                : "auto — nothing installed, so everything runs direct (things helpers install to change that)";
+    }
+}
+function renderStatus(status) {
+    const deputy = status.deputy;
+    const lines = [`deputy: ${deputy.running ? "running" : "does not appear to be running"}`];
+    // The plain no-socket case needs no elaboration; a socket that exists but
+    // misbehaves (not answering, handshake refused) is worth its own line.
+    if (!deputy.running && !deputy.detail.startsWith("not running")) {
+        lines.push(`  detail: ${deputy.detail}`);
+    }
+    if (deputy.hungSocket) {
+        lines.push("  next: `things helpers restart` — the socket is present but no handshake answers");
+    }
+    lines.push(`  routing: ${routingLine(status)}`, `  launchd: ${deputy.plistInstalled ? (deputy.loaded ? "installed + loaded" : "installed, NOT loaded") : "not installed (things helpers install)"}`, `  bundle: ${status.bundleInstalled
+        ? `installed${status.installedVersion !== null ? ` (v${status.installedVersion})` : ""}`
+        : "not installed"}`, `  socket: ${deputy.socketPath}`);
+    if (deputy.hello !== null) {
+        lines.push(`  version: ${deputy.hello.deputyVersion} (protocol ${deputy.hello.protocol}, pid ${deputy.hello.pid})`);
+    }
+    if (deputy.signing !== null) {
+        lines.push(`  signing: ${deputy.signing.state}${deputy.signing.authority !== null ? ` (${deputy.signing.authority})` : ""}`);
+        if (deputy.signing.state !== "signed") {
+            lines.push("  warning: an unsigned/ad-hoc helper loses its macOS grants on every rebuild — run scripts/deputy-cert-setup.sh once, rebuild, reinstall");
+        }
+    }
+    const reader = status.reader;
+    lines.push(`reader: ${reader.running ? (reader.granted ? "running, granted" : "running, NOT granted") : reader.installed ? reader.detail : "not installed"}`);
+    if (reader.running && !reader.granted) {
+        lines.push("  next: run `things helpers grant` and accept the panel (one time; the grant survives restarts, reboots, and rebuilds)");
+    }
+    if (reader.hungSocket) {
+        lines.push("  next: `things helpers restart` — the socket is present but no handshake answers");
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function registerHelpers(program) {
+    const helpers = program
+        .command("helpers")
+        .description("Manage the optional helper pair that performs database reads and app automation " +
+        "on the CLI's behalf, so macOS permission grants attach to stable helpers instead " +
+        "of every terminal or agent runtime that runs `things`. Subcommands: status, " +
+        "install, grant, restart, uninstall.");
+    helpers
+        .command("status")
+        .description("Report both helpers' state: running or not, launchd installation, installed version, " +
+        "code-signing identity, the reader's grant, and the routing mode on this machine. " +
+        "Read-only.")
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .action((opts) => {
+        const started = Date.now();
+        const status = helpersStatus(loadConfig().helpersMode);
+        if (opts.json === true) {
+            process.stdout.write(`${JSON.stringify(okEnvelope("helpers-status", status, envelopeMeta(started)))}\n`);
+        }
+        else {
+            process.stdout.write(renderStatus(status));
+        }
+        process.exitCode = ExitCode.Ok;
+    });
+    helpers
+        .command("install")
+        .description("Install the helper bundle: copy it to its stable location, register both helpers " +
+        "with launchd (starts now and on every login), and report signing + grant state. " +
+        "Under the default helpers-enabled auto, an installed and healthy helper is used from " +
+        "the next command on. Rerun after every rebuild.")
+        .option("--bundle <path>", "path to a built Things API Helper.app (default: deputy/build/Things API Helper.app in this package)")
+        .action((opts) => {
+        try {
+            const result = installHelpers(opts.bundle !== undefined ? { bundlePath: opts.bundle } : {});
+            process.stdout.write(`installed ${result.bundlePath}\nlaunchd agent: ${result.plistPath}\n`);
+            if (result.readerInstalled) {
+                process.stdout.write(result.readerGranted === true
+                    ? "reader: granted — file reads ride the scoped reader\n"
+                    : result.readerGranted === false
+                        ? "reader: installed — run `things helpers grant` once to give it durable read access\n"
+                        : "reader: installed, not answering yet — check `things helpers status`\n");
+            }
+            for (const warning of result.warnings) {
+                process.stderr.write(`warning: ${warning}\n`);
+            }
+            process.exitCode = ExitCode.Ok;
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = ExitCode.Environment;
+        }
+    });
+    helpers
+        .command("grant")
+        .description("One-time ceremony: opens a folder panel presented by the sandboxed reader helper, " +
+        "already showing the Things data folder. Accepting gives the reader durable read " +
+        "access to exactly that folder — it survives restarts, reboots, and updates, and " +
+        "macOS enforces that the reader can reach nothing else. Interactive: run this at " +
+        "the machine, not from an unattended session.")
+        .action(() => {
+        const result = grantReader();
+        if (result.granted) {
+            process.stdout.write("granted — file reads now ride the scoped reader\n");
+            process.exitCode = ExitCode.Ok;
+        }
+        else {
+            process.stderr.write(`not granted: ${result.detail}\n`);
+            process.exitCode = ExitCode.Environment;
+        }
+    });
+    helpers
+        .command("restart")
+        .description("Restart the launchd-managed helpers (picks up a rebuilt installed bundle).")
+        .action(() => {
+        try {
+            restartHelpers();
+            process.stdout.write("helpers restarted\n");
+            process.exitCode = ExitCode.Ok;
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = ExitCode.Environment;
+        }
+    });
+    helpers
+        .command("uninstall")
+        .description("Stop both helpers and remove their launchd registrations and the installed bundle. " +
+        "Local state (access token, logs, the reader's grant) is kept; routing config is " +
+        "untouched (commands fall back to direct execution).")
+        .action(() => {
+        const result = uninstallHelpers();
+        process.stdout.write(result.removed.length > 0
+            ? `removed:\n${result.removed.map((p) => `  ${p}`).join("\n")}\n`
+            : "nothing installed\n");
+        process.exitCode = ExitCode.Ok;
+    });
+}
+//# sourceMappingURL=helpers.js.map

package/dist/cli/commands/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/cli/commands/helpers.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/op-result.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `things op-result <op-id>` — a read-only CALLER-RECOVERY lookup over the local
+ * change history (RSPA1 deliverable 3). Thin surface over the library's opResult().
+ *
+ * When your environment kills long commands (a wall-time cap) before a write's
+ * result is printed — a `--dangerously-drive-gui` drive can run its full verify
+ * budget — dispatch the op with `--op-id <key>`, let it die, then run this in a
+ * fresh process to learn what ACTUALLY happened from the record the killed process
+ * already durably wrote. NEVER blind-retry a GUI drive.
+ *
+ * Always exit 0: this is a successful HISTORY READ regardless of the underlying
+ * op's outcome (which lives in `data.status` / `data.result`).
+ */
+import type { Command } from "commander";
+export declare function registerOpResult(program: Command): void;

package/dist/cli/commands/op-result.js

@@ -0,0 +1,39 @@
+import { okEnvelope, opResult } from "../../index.js";
+export function registerOpResult(program) {
+    program
+        .command("op-result")
+        .argument("<op-id>", "the --op-id / op_id the original write carried")
+        .description("Look up what happened to a write you dispatched with --op-id, from the local change " +
+        "history alone (opens no database, drives nothing). Use it to recover the outcome when " +
+        "your environment killed the command before it printed its result: let the command die, " +
+        "then run this. Reports FOUND (the final result + target + observation), INTENT-ONLY (the " +
+        "op started but no outcome was written — still running or the process died mid-flight, " +
+        "outcome UNCERTAIN), or UNKNOWN (no such op-id in history). Always exit 0 (a history read).")
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .action((opId, opts) => {
+        const started = Date.now();
+        const data = opResult(opId);
+        const meta = {
+            dbVersion: null,
+            fingerprint: "unknown",
+            elapsedMs: Date.now() - started,
+        };
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(okEnvelope("op-result", data, meta))}\n`);
+        }
+        else {
+            const head = data.status === "found"
+                ? `${data.result} — ${data.op}${data.uuid !== null ? ` (${data.uuid})` : ""}`
+                : data.status === "intent-only"
+                    ? `intent-only — ${data.op} (no final outcome recorded)`
+                    : "unknown op-id";
+            process.stdout.write(`op-result ${opId}: ${head}\n`);
+            process.stdout.write(`  ${data.note}\n`);
+            if (data.status === "found" && data.observed !== null) {
+                process.stdout.write(`  observed: ${JSON.stringify(data.observed)}\n`);
+            }
+        }
+        process.exitCode = 0;
+    });
+}
+//# sourceMappingURL=op-result.js.map

package/dist/cli/commands/op-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-result.js","sourceRoot":"","sources":["../../../src/cli/commands/op-result.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAqB,MAAM,gBAAgB,CAAC;AAEzE,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,OAAO;SACJ,OAAO,CAAC,WAAW,CAAC;SACpB,QAAQ,CAAC,SAAS,EAAE,gDAAgD,CAAC;SACrE,WAAW,CACV,sFAAsF;QACpF,wFAAwF;QACxF,yFAAyF;QACzF,2FAA2F;QAC3F,wFAAwF;QACxF,4FAA4F,CAC/F;SACA,MAAM,CAAC,QAAQ,EAAE,wCAAwC,CAAC;SAC1D,MAAM,CAAC,CAAC,IAAY,EAAE,IAAwB,EAAE,EAAE;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAiB;YACzB,SAAS,EAAE,IAAI;YACf,WAAW,EAAE,SAAS;YACtB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;SAChC,CAAC;QACF,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QACnF,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GACR,IAAI,CAAC,MAAM,KAAK,OAAO;gBACrB,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC7E,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,aAAa;oBAC7B,CAAC,CAAC,iBAAiB,IAAI,CAAC,EAAE,8BAA8B;oBACxD,CAAC,CAAC,eAAe,CAAC;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC;YACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;YACzC,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/commands/repeat-flags.d.ts

@@ -23,8 +23,8 @@ export declare function addRepeatCalendarFlags(cmd: Command): Command;
 export declare function addRepeatingRuleFieldsFromOpts(opts: Record<string, unknown>, frequency: RepeatFrequency, interval: number): AddRepeatingRuleFields;
 /**
  * Build the extended rule fields from CLI options (present keys only —
- * exactOptionalPropertyTypes). Combination validity is enforced downstream
- * (the same refusals the library raises), so a wrong-frequency flag surfaces a
- * clear error rather than being silently applied.
+ * exactOptionalPropertyTypes). A wrong-frequency anchor flag is REFUSED here
+ * (UIC6-l), never silently dropped; other combination validity (e.g. weekdays on
+ * a non-weekly rule) is enforced downstream by assertRepeatRule.
  */
 export declare function repeatRuleFlagsFromOpts(opts: Record<string, unknown>, frequency: RepeatFrequency): RepeatRuleFlagFields;

package/dist/cli/commands/repeat-flags.js

@@ -9,6 +9,8 @@ export function addRepeatRuleFlags(cmd) {
         .option("--yearly-month <n>", "yearly only: the month (1–12)")
         .option("--ends-after <n>", "stop after N occurrences (1–999)")
         .option("--ends-on <date>", "YYYY-MM-DD — stop after this date")
+        .option("--when <date>", "YYYY-MM-DD — the first occurrence (drives the Repeat dialog's Next field); " +
+        "make-repeating defaults to the item's scheduled date")
         .option("--reminder <time>", "HH:mm — a reminder time on each occurrence")
         .option("--deadline", "give each occurrence a deadline")
         .option("--start-days-earlier <n>", "with --deadline: start each occurrence N days before its deadline");
@@ -55,45 +57,100 @@ function dayAnchor(opts) {
     return undefined;
 }
 /**
- * Build the extended rule fields from CLI options (present keys only —
- * exactOptionalPropertyTypes). Combination validity is enforced downstream
- * (the same refusals the library raises), so a wrong-frequency flag surfaces a
- * clear error rather than being silently applied.
+ * The CALENDAR-ANCHOR flags that apply only to a SUBSET of frequencies, and the
+ * frequencies that consume each. A present anchor flag on any other frequency is
+ * a hard error — never a silent drop (UIC6-l). Exhaustive over the anchor flag
+ * set; a new anchor flag must earn a row here (and the mapper below consumes it).
+ * `weekdays` is intentionally ABSENT: it is mapped unconditionally and refused
+ * downstream by assertRepeatRule ("weekdays apply only to a weekly rule"), the
+ * mapped-contradiction path — this table is only for the SILENTLY-dropped anchors.
  */
-export function repeatRuleFlagsFromOpts(opts, frequency) {
-    const fields = {};
-    if (opts["afterCompletion"] === true)
-        fields.afterCompletion = true;
-    if (typeof opts["weekdays"] === "string") {
-        fields.weekdays = opts["weekdays"]
+const ANCHOR_FLAG_FREQUENCIES = {
+    onDay: ["monthly", "yearly"],
+    onWeekday: ["monthly", "yearly"],
+    onOrdinal: ["monthly", "yearly"],
+    yearlyMonth: ["yearly"],
+};
+/** The user-facing flag spelling for a camelCase option key (error messages). */
+const ANCHOR_FLAG_SPELLING = {
+    onDay: "--on-day",
+    onWeekday: "--on-weekday",
+    onOrdinal: "--on-ordinal",
+    yearlyMonth: "--yearly-month",
+};
+/**
+ * Refuse a calendar-anchor flag supplied on a frequency that does not consume it
+ * (UIC6-l): `--frequency weekly --on-day 15` errors instead of silently running a
+ * plain weekly rule. Behavioral message — names the flag + the frequency it
+ * belongs to, never a mechanism.
+ */
+function assertAnchorFlagsMatchFrequency(opts, frequency) {
+    for (const [key, allowed] of Object.entries(ANCHOR_FLAG_FREQUENCIES)) {
+        if (opts[key] === undefined)
+            continue;
+        if (!allowed.includes(frequency)) {
+            const flag = ANCHOR_FLAG_SPELLING[key] ?? key;
+            throw new RangeError(`${flag} applies only to a ${allowed.join(" or ")} rule — this rule is ${frequency}`);
+        }
+    }
+}
+/**
+ * EXHAUSTIVE over every field of {@link RepeatRuleFlagFields}: each rule param is
+ * derived from the CLI options by exactly one entry, so a new param added to
+ * RepeatRuleParams breaks compilation here until it earns a flag mapping. This is
+ * what makes an accepted-but-dropped flag impossible for this vocabulary (the
+ * UIC6-l class) — the wrong-frequency guard above catches the inverse (a flag
+ * with no consuming frequency). Each entry returns the mapped value or
+ * `undefined` (absent — exactOptionalPropertyTypes).
+ */
+const FLAG_MAP = {
+    afterCompletion: (opts) => (opts["afterCompletion"] === true ? true : undefined),
+    weekdays: (opts) => typeof opts["weekdays"] === "string"
+        ? opts["weekdays"]
             .split(",")
             .map((d) => d.trim().toLowerCase())
-            .filter((d) => d.length > 0);
-    }
-    const anchor = dayAnchor(opts);
-    if (frequency === "monthly" && anchor !== undefined) {
-        fields.monthly = anchor;
-    }
-    if (frequency === "yearly") {
+            .filter((d) => d.length > 0)
+        : undefined,
+    monthly: (_opts, frequency, anchor) => frequency === "monthly" && anchor !== undefined ? anchor : undefined,
+    yearly: (opts, frequency, anchor) => {
+        if (frequency !== "yearly")
+            return undefined;
         const month = opts["yearlyMonth"];
-        if (month !== undefined || anchor !== undefined) {
-            const base = { month: Number(month) };
-            fields.yearly = (anchor === undefined ? base : { ...base, ...anchor });
+        if (month === undefined && anchor === undefined)
+            return undefined;
+        const base = { month: Number(month) };
+        return (anchor === undefined ? base : { ...base, ...anchor });
+    },
+    ends: (opts) => {
+        if (opts["endsAfter"] !== undefined)
+            return { kind: "after", count: Number(opts["endsAfter"]) };
+        if (typeof opts["endsOn"] === "string")
+            return { kind: "on-date", date: opts["endsOn"] };
+        return undefined;
+    },
+    reminder: (opts) => (typeof opts["reminder"] === "string" ? opts["reminder"] : undefined),
+    next: (opts) => (typeof opts["when"] === "string" ? opts["when"] : undefined),
+    deadline: (opts) => (opts["deadline"] === true ? true : undefined),
+    startDaysEarlier: (opts) => opts["startDaysEarlier"] !== undefined ? Number(opts["startDaysEarlier"]) : undefined,
+};
+/**
+ * Build the extended rule fields from CLI options (present keys only —
+ * exactOptionalPropertyTypes). A wrong-frequency anchor flag is REFUSED here
+ * (UIC6-l), never silently dropped; other combination validity (e.g. weekdays on
+ * a non-weekly rule) is enforced downstream by assertRepeatRule.
+ */
+export function repeatRuleFlagsFromOpts(opts, frequency) {
+    assertAnchorFlagsMatchFrequency(opts, frequency);
+    const anchor = dayAnchor(opts);
+    const fields = {};
+    for (const key of Object.keys(FLAG_MAP)) {
+        const value = FLAG_MAP[key](opts, frequency, anchor);
+        if (value !== undefined) {
+            // The map's per-key return type is exactly RepeatRuleFlagFields[K]; the
+            // index write is safe but TS cannot narrow K across the loop.
+            fields[key] = value;
         }
     }
-    if (opts["endsAfter"] !== undefined) {
-        fields.ends = { kind: "after", count: Number(opts["endsAfter"]) };
-    }
-    else if (typeof opts["endsOn"] === "string") {
-        fields.ends = { kind: "on-date", date: opts["endsOn"] };
-    }
-    if (typeof opts["reminder"] === "string")
-        fields.reminder = opts["reminder"];
-    if (opts["deadline"] === true)
-        fields.deadline = true;
-    if (opts["startDaysEarlier"] !== undefined) {
-        fields.startDaysEarlier = Number(opts["startDaysEarlier"]);
-    }
     return fields;
 }
 //# sourceMappingURL=repeat-flags.js.map

package/dist/cli/commands/repeat-flags.js.map

@@ -1 +1 @@
-{"version":3,"file":"repeat-flags.js","sourceRoot":"","sources":["../../../src/cli/commands/repeat-flags.ts"],"names":[],"mappings":"AAsBA,8DAA8D;AAC9D,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,OAAO,GAAG;SACP,MAAM,CACL,oBAAoB,EACpB,6EAA6E,CAC9E;SACA,MAAM,CACL,mBAAmB,EACnB,qEAAqE,CACtE;SACA,MAAM,CAAC,gBAAgB,EAAE,2DAA2D,CAAC;SACrF,MAAM,CACL,wBAAwB,EACxB,4EAA4E,CAC7E;SACA,MAAM,CACL,kBAAkB,EAClB,uEAAuE,CACxE;SACA,MAAM,CAAC,oBAAoB,EAAE,+BAA+B,CAAC;SAC7D,MAAM,CAAC,kBAAkB,EAAE,kCAAkC,CAAC;SAC9D,MAAM,CAAC,kBAAkB,EAAE,mCAAmC,CAAC;SAC/D,MAAM,CAAC,mBAAmB,EAAE,4CAA4C,CAAC;SACzE,MAAM,CAAC,YAAY,EAAE,iCAAiC,CAAC;SACvD,MAAM,CACL,0BAA0B,EAC1B,mEAAmE,CACpE,CAAC;AACN,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,OAAO,GAAG;SACP,MAAM,CACL,oBAAoB,EACpB,6EAA6E,CAC9E;SACA,MAAM,CACL,mBAAmB,EACnB,qEAAqE,CACtE;SACA,MAAM,CAAC,gBAAgB,EAAE,2DAA2D,CAAC;SACrF,MAAM,CACL,wBAAwB,EACxB,4EAA4E,CAC7E;SACA,MAAM,CACL,kBAAkB,EAClB,uEAAuE,CACxE;SACA,MAAM,CAAC,oBAAoB,EAAE,+BAA+B,CAAC;SAC7D,MAAM,CAAC,kBAAkB,EAAE,kCAAkC,CAAC;SAC9D,MAAM,CAAC,kBAAkB,EAAE,mCAAmC,CAAC,CAAC;AACrE,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,8BAA8B,CAC5C,IAA6B,EAC7B,SAA0B,EAC1B,QAAgB;IAEhB,MAAM,EACJ,QAAQ,EAAE,EAAE,EACZ,QAAQ,EAAE,EAAE,EACZ,gBAAgB,EAAE,EAAE,EACpB,GAAG,IAAI,EACR,GAAG,uBAAuB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC7C,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED,iFAAiF;AACjF,6EAA6E;AAC7E,gEAAgE;AAChE,SAAS,SAAS,CAAC,IAA6B;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAuB,CAAC;IAClD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAuB,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAuB,CAAC;IAC1D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,GAAG,EAAE,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC5D,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACvD,OAAO;YACL,OAAO,EAAE,SAAoB;YAC7B,OAAO,EAAE,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAmB;SAC/E,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAA6B,EAC7B,SAA0B;IAE1B,MAAM,MAAM,GAAyB,EAAE,CAAC;IAExC,IAAI,IAAI,CAAC,iBAAiB,CAAC,KAAK,IAAI;QAAE,MAAM,CAAC,eAAe,GAAG,IAAI,CAAC;IAEpE,IAAI,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;aAC/B,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;aAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAc,CAAC;IAC9C,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,SAAS,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACpD,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC;IAC1B,CAAC;IACD,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;QAClC,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAChD,MAAM,IAAI,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACtC,MAAM,CAAC,MAAM,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,EAAE,CAAiB,CAAC;QACzF,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,CAAC,IAAI,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;IACpE,CAAC;SAAM,IAAI,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,CAAC,IAAI,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC1D,CAAC;IAED,IAAI,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,QAAQ;QAAE,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7E,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI;QAAE,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC;IACtD,IAAI,IAAI,CAAC,kBAAkB,CAAC,KAAK,SAAS,EAAE,CAAC;QAC3C,MAAM,CAAC,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"repeat-flags.js","sourceRoot":"","sources":["../../../src/cli/commands/repeat-flags.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/writes.js

@@ -1,6 +1,9 @@
 import { readFileSync } from "node:fs";
+import { armInterrupt, disarmInterrupt } from "../interrupt.js";
+import { isDevVersion } from "../skill.js";
+import { CLI_VERSION } from "../version.js";
 import { addRepeatCalendarFlags, addRepeatingRuleFieldsFromOpts, addRepeatRuleFlags, repeatRuleFlagsFromOpts, } from "./repeat-flags.js";
-import { aggregateExitCode, blockedCode, capabilitiesTable, ClockError, describeConfig, errorEnvelope, ExitCode, getConfigKey, mutationWireData, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
+import { aggregateExitCode, blockedCode, capabilitiesTable, ClockError, closeCliTrace, describeConfig, errorEnvelope, ExitCode, HELPERS_MODES, installCliTrace, getConfigKey, parseHelpersMode, mutationWireData, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, trace, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
 import { usageError } from "../read-driver.js";
 import { dim } from "../style.js";
 function addWriteFlags(cmd) {
@@ -145,7 +148,12 @@ function headingPlacement(c, projectUuid, opts) {
 /** Add the mandatory GUI-drive acknowledgement to a ui-vector command. */
 function addDriveGuiFlag(cmd) {
     return cmd.option("--dangerously-drive-gui", "required: visibly drives the Things app to make a change it offers nowhere else; " +
-        "also needs `things config set ui-enabled true`");
+        "also needs `things config set ui-enabled true`. Driving the app can take over a " +
+        "minute on a large database, so allow a generous timeout (180s or more) — if your own " +
+        "timeout stops the command first you get empty output, not a result. A timeout or empty " +
+        "output is not a success: the change may still have landed, so re-check with " +
+        "`things show <ref>` before retrying, and never fire an identical retry (it can duplicate " +
+        "the change) — stop and report if the state is wrong or unclear");
 }
 function collect(value, previous) {
     return [...previous, value];
@@ -186,6 +194,16 @@ async function runWrite(opts, fn, emitFn = emitResult) {
     if (!opIdOk(opts))
         return;
     const started = Date.now();
+    // Dev-mode step-timeline trace + signal-safe interrupt guard (TRACE1, #487).
+    // Scoped to the write driver — the invocations where a per-step timeline earns
+    // its keep, and where a mid-drive kill would otherwise leave empty stdout. The
+    // sink is a no-op unless tracing is on (a `-dev` build, or config/env forced).
+    installCliTrace({
+        argv: process.argv.slice(1),
+        version: CLI_VERSION,
+        isDev: isDevVersion(CLI_VERSION),
+    });
+    armInterrupt(opts.json === true);
     let client = null;
     const meta = (client_) => {
         let dbVersion = null;
@@ -239,6 +257,16 @@ async function runWrite(opts, fn, emitFn = emitResult) {
     }
     finally {
         client?.close();
+        // Close the trace with a final result line (the exit code the caller sees),
+        // then disarm the interrupt guard so a later signal during teardown/reads
+        // emits nothing.
+        trace(() => ({
+            phase: "invocation-end",
+            exitCode: process.exitCode ?? 0,
+            elapsedMs: Date.now() - started,
+        }));
+        disarmInterrupt();
+        closeCliTrace();
     }
 }
 /**
@@ -258,6 +286,26 @@ function emitPreserveNote(result) {
         process.stderr.write(`warning: preserve-modified: ${f.uuid}: ${f.detail}\n`);
     }
 }
+/**
+ * TTY disclosure for the HINTS1 completion-context on a verified complete/cancel:
+ * a dim line naming the OPEN work remaining in the to-do's project and/or Today,
+ * so an operator (or an agent reading the human render) sees an emptied container
+ * at a glance. Silent when neither arm applies (the field is absent).
+ */
+function emitContextNote(result) {
+    const context = result.context;
+    if (context === undefined)
+        return;
+    const parts = [];
+    if (context.project !== undefined) {
+        parts.push(`project "${context.project.title}": ${context.project.remainingOpen} open remaining`);
+    }
+    if (context.today !== undefined) {
+        parts.push(`today: ${context.today.remainingOpen} open remaining`);
+    }
+    if (parts.length > 0)
+        process.stdout.write(dim(`  ${parts.join("; ")}\n`));
+}
 function emitResult(result, opts, meta) {
     switch (result.kind) {
         case "bounce-aborted": {
@@ -290,6 +338,7 @@ function emitResult(result, opts, meta) {
                     : `vector=${result.vector}, tier=${result.tier}, verified`;
                 process.stdout.write(`ok ${result.op}${uuid} (${status})\n`);
                 emitPreserveNote(result);
+                emitContextNote(result);
             }
             process.exitCode = ExitCode.Ok;
             return;
@@ -305,6 +354,7 @@ function emitResult(result, opts, meta) {
                     `  invocation: ${result.plan.invocation}`,
                     `  hazards checked: ${result.plan.hazardsChecked.join(", ") || "none"}`,
                     `  expected delta: ${JSON.stringify(result.plan.expectedDelta)}`,
+                    ...(result.plan.notes ?? []).map((n) => `  note: ${n}`),
                     "",
                 ].join("\n"));
             }
@@ -1374,7 +1424,12 @@ export function registerWriteCommands(program) {
         .option("--notes <text>", "notes body")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
         .option("--reminder <time>", "HH:mm reminder (needs a schedulable --when)")
-        .option("--deadline <date>", "YYYY-MM-DD")
+        .option("--deadline <date>", "YYYY-MM-DD — deadlines EVERY occurrence: each starts (deadline − --when) days " +
+        "before its own deadline (needs a concrete --when, on or before the deadline; " +
+        "alternative spelling of --start-days-earlier — give one or the other, both must agree)")
+        .option("--start-days-earlier <n>", "deadlines EVERY occurrence, naming the lead directly: each starts N days before " +
+        "its own deadline (needs a concrete --when; alternative spelling of --deadline <date> — " +
+        "give one or the other, both must agree)")
         .option("--tag <name>", "tag to attach (repeatable)", collect, [])
         .option("--checklist-item <title>", "checklist item (repeatable)", collect, [])
         .option("--project <ref>", "destination project (uuid or unique name)")
@@ -1396,6 +1451,9 @@ export function registerWriteCommands(program) {
             ...(opts["when"] !== undefined && { when: opts["when"] }),
             ...(opts["reminder"] !== undefined && { reminder: opts["reminder"] }),
             ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
+            ...(opts["startDaysEarlier"] !== undefined && {
+                startDaysEarlier: Number(opts["startDaysEarlier"]),
+            }),
             ...(tags.length > 0 && { tags }),
             ...(checklistItems.length > 0 && { checklistItems }),
             ...(projectRef !== undefined && { project: projectRef }),
@@ -2106,7 +2164,8 @@ export function registerWriteCommands(program) {
         .command("set <key> <value>")
         .description("Persist a config key: profile | maxDisruption | actor | auditEnabled | " +
         "accepted-fingerprint | certified-app-version | allow-experimental | bounce-enabled | " +
-        "bounce-max-items | ui-enabled | scope")
+        "bounce-max-items | auto-launch | helpers-enabled (auto | true | false) | ui-enabled | " +
+        "ui-drive-budget-ms | trace | scope")
         .action((key, value, opts) => {
         const map = {
             profile: "profile",
@@ -2118,7 +2177,11 @@ export function registerWriteCommands(program) {
             "allow-experimental": "allowExperimental",
             "bounce-enabled": "bounceEnabled",
             "bounce-max-items": "bounceMaxItems",
+            "auto-launch": "autoLaunch",
+            "helpers-enabled": "helpersMode",
             "ui-enabled": "uiEnabled",
+            "ui-drive-budget-ms": "uiDriveBudgetMs",
+            trace: "traceEnabled",
             scope: "scope",
         };
         const target = map[key];
@@ -2127,12 +2190,22 @@ export function registerWriteCommands(program) {
             process.exitCode = ExitCode.Usage;
             return;
         }
-        const parsed = target === "maxDisruption" || target === "bounceMaxItems"
+        // `helpers-enabled` is TRI-state (auto | true | false): anything else is
+        // refused rather than silently coerced to a boolean, so a typo can never
+        // read as "off" on a machine that meant "auto".
+        if (target === "helpersMode" && parseHelpersMode(value) === undefined) {
+            process.stderr.write(`error: helpers-enabled accepts ${HELPERS_MODES.join(" | ")} (got "${value}")\n`);
+            process.exitCode = ExitCode.Usage;
+            return;
+        }
+        const parsed = target === "maxDisruption" || target === "bounceMaxItems" || target === "uiDriveBudgetMs"
             ? Number(value)
             : target === "auditEnabled" ||
                 target === "allowExperimental" ||
                 target === "bounceEnabled" ||
-                target === "uiEnabled"
+                target === "autoLaunch" ||
+                target === "uiEnabled" ||
+                target === "traceEnabled"
                 ? value === "true"
                 : value;
         // Universal `--dry-run` (../dry-run.ts): `config set` writes local config