things-api 0.19.2 → 0.19.4

package/README.md

@@ -4,7 +4,7 @@
 
 A typed TypeScript library + CLI (`things`) for programmatic interaction with [Things 3](https://culturedcode.com/things/) by Cultured Code.
 
-**Status: read + write + MCP layers live and published to npm (v0.19.2 — see [CHANGELOG.md](CHANGELOG.md)).** Reads go straight to the local SQLite database (UI-exact Today ordering, sidebar-grouped Anytime/Someday with container-status cascade, decoded repeat rules, occurrence projections); writes run a verified pipeline over four write vectors — two lab-validated headless surfaces (the URL scheme + AppleScript) and two opt-in surfaces (Apple Shortcuts and an Accessibility-driven GUI vector) — with hazard guards, disruption-tier policy, a JSONL audit trail, batch mode, audit-replay undo (transactional across compound operations), full project lifecycle (complete/cancel/reopen/restore), heading rename/archive/unarchive with children policies, container detach, granular stateful checklists, tag hierarchy management incl. un-nesting, completion/creation backdating, Logbook imports, tiered fuzzy name resolution (uuid prefixes, `things:///show?id=` share links), and kind-neutral in-place reordering within any container or view (one `things reorder <refs…> [--start|--end|--before|--after] --in <target>` verb — Today/Evening, a project, an area, a heading's children, someday, inbox — plus `project move-heading` for the headings themselves and `area reorder` for the sidebar). The Apple Shortcuts surface is wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things project add-heading`) and clearing a reminder from a date-scheduled item (`things todo clear-reminder`). Both run through bundled proxy shortcuts (`things setup`) and are gated on their presence. The fourth vector — the Accessibility-driven GUI vector — is off by default and drives the local Things app to reach transforms that exist on no scriptable surface (repeat-rule editing on existing to-dos and projects, convert-to-project, sidebar area reorder); see [Accessibility GUI vector](#accessibility-gui-vector-optional-off-by-default) below. Single-item permanent delete stays interactive-only (its macOS consent has no always-allow) and is out of the headless pipeline. See [docs/design/](docs/design/) for the architecture and VM-lab design, [docs/lab/](docs/lab/harness.md) for the probe harness and campaign results the write layer is grounded in, and [docs/atlas/](docs/atlas/schema-v26.md) for the database↔UI map.
+**Status: read + write + MCP layers live and published to npm (v0.19.4 — see [CHANGELOG.md](CHANGELOG.md)).** Reads go straight to the local SQLite database (UI-exact Today ordering, sidebar-grouped Anytime/Someday with container-status cascade, decoded repeat rules, occurrence projections); writes run a verified pipeline over four write vectors — two lab-validated headless surfaces (the URL scheme + AppleScript) and two opt-in surfaces (Apple Shortcuts and an Accessibility-driven GUI vector) — with hazard guards, disruption-tier policy, a JSONL audit trail, batch mode, audit-replay undo (transactional across compound operations), full project lifecycle (complete/cancel/reopen/restore), heading rename/archive/unarchive with children policies, container detach, granular stateful checklists, tag hierarchy management incl. un-nesting, completion/creation backdating, Logbook imports, tiered fuzzy name resolution (uuid prefixes, `things:///show?id=` share links), and kind-neutral in-place reordering within any container or view (one `things reorder <refs…> [--start|--end|--before|--after] --in <target>` verb — Today/Evening, a project, an area, a heading's children, someday, inbox — plus `project move-heading` for the headings themselves and `area reorder` for the sidebar). The Apple Shortcuts surface is wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things project add-heading`) and clearing a reminder from a date-scheduled item (`things todo clear-reminder`). Both run through bundled proxy shortcuts (`things setup`) and are gated on their presence. The fourth vector — the Accessibility-driven GUI vector — is off by default and drives the local Things app to reach transforms that exist on no scriptable surface (repeat-rule editing on existing to-dos and projects, convert-to-project, sidebar area reorder); see [Accessibility GUI vector](#accessibility-gui-vector-optional-off-by-default) below. Single-item permanent delete stays interactive-only (its macOS consent has no always-allow) and is out of the headless pipeline. See [docs/design/](docs/design/) for the architecture and VM-lab design, [docs/lab/](docs/lab/harness.md) for the probe harness and campaign results the write layer is grounded in, and [docs/atlas/](docs/atlas/schema-v26.md) for the database↔UI map.
 
 ```sh
 things today --json                # read: your Today list, Evening split, UI order

package/dist/audit/schema.d.ts

@@ -63,6 +63,20 @@ export interface AuditRecord {
      * refusal to guess, never an assumption either way.
      */
     expected?: DeltaSpec;
+    /**
+     * The GUI drive's step play-by-play (ADDITIVE), one compact entry per recipe
+     * step, in order — recorded on the FINAL record of every ui-vector write,
+     * success and failure alike.
+     *
+     * This record is the APPEND-ONLY DEBUG LOG of the diagnostic ladder (#632).
+     * The step list used to ride every successful result and cost a caller context
+     * on writes that went fine; now the default success output omits it, a failure
+     * carries it, `--verbose` opts a success back into it, and it is ALWAYS here —
+     * so `things op-result <op-id>` can hand it back after the fact. Compact
+     * labels only (the recipe's own step names); the per-invocation trace file
+     * remains the deep tier with the raw payloads and timings.
+     */
+    steps?: string[];
     /** Normalized requested delta (params as given, post-normalization). */
     requested: Record<string, unknown>;
     /** Asserted-field subset of the pre-state (null when target didn't exist). */

package/dist/audit/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA+FzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAA0E;IAE1E,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,IAAI,IAAI,EAAE;KAClB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,MAAM,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA6GzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAA0E;IAE1E,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,IAAI,IAAI,EAAE;KAClB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,MAAM,EAAE,CAAC;AACvB,CAAC"}

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

@@ -8,7 +8,9 @@ export function registerOpResult(program) {
         "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).")
+        "outcome UNCERTAIN), or UNKNOWN (no such op-id in history). Also reports the step-by-step " +
+        "account of how a change was driven through the app, for a change that succeeded as well " +
+        "as one that failed. Always exit 0 (a history read).")
         .option("--json", "emit versioned JSON envelope on stdout")
         .action((opId, opts) => {
         const started = Date.now();
@@ -38,6 +40,16 @@ export function registerOpResult(program) {
             if (data.status === "found" && data.observed !== null) {
                 process.stdout.write(`  observed: ${JSON.stringify(data.observed)}\n`);
             }
+            // The step account, read back from the change history (#632). A write
+            // that succeeded no longer prints its steps, so this is where they are
+            // recovered — which is what makes leaving them off the success output
+            // a move rather than a loss.
+            if (data.steps !== null && data.steps.length > 0) {
+                process.stdout.write(`  drove ${data.steps.length} step(s):\n`);
+                for (const [i, step] of data.steps.entries()) {
+                    process.stdout.write(`    ${i + 1}. ${step}\n`);
+                }
+            }
         }
         process.exitCode = 0;
     });

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

@@ -1 +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,UAAU,KAAK,SAAS,EAAE,CAAC;gBAClC,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;gBAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iBAAiB,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,GAAG;oBAC9E,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,cAAc,uBAAuB;oBAC9E,GAAG,CAAC,CAAC,YAAY,IAAI,CACxB,CAAC;YACJ,CAAC;YACD,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"}
+{"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,2FAA2F;QAC3F,0FAA0F;QAC1F,qDAAqD,CACxD;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,UAAU,KAAK,SAAS,EAAE,CAAC;gBAClC,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;gBAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iBAAiB,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,GAAG;oBAC9E,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,cAAc,uBAAuB;oBAC9E,GAAG,CAAC,CAAC,YAAY,IAAI,CACxB,CAAC;YACJ,CAAC;YACD,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;YACD,sEAAsE;YACtE,uEAAuE;YACvE,sEAAsE;YACtE,6BAA6B;YAC7B,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACjD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,IAAI,CAAC,KAAK,CAAC,MAAM,aAAa,CAAC,CAAC;gBAChE,KAAK,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;oBAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;gBAClD,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/commands/writes.js

@@ -25,6 +25,14 @@ const PRESERVE_MODIFIED_HELP = "keep this change off the modification-date timel
     "Safe with Things Cloud: the restored date syncs to your other devices and stays put, so " +
     "the item stays off the timeline everywhere — unless another device edits the same item " +
     "at nearly the same time, which re-dates it.";
+/**
+ * `--verbose` help. The flag is the middle rung of the diagnostic ladder: a
+ * successful change reports what it did and what to consider doing next, and
+ * only says HOW it drove the app when asked. A failure prints the steps without
+ * the flag, and `things op-result <key>` prints them after the fact either way.
+ */
+const VERBOSE_HELP = "add the step-by-step account of how the change was driven through the app; a failed change " +
+    "reports it anyway, and `things op-result` reports it for any change already made";
 function addWriteFlags(cmd, capability = {}) {
     const opId = new Option("--op-id <key>", "idempotency key: a resubmission with the same key is recognized as already applied " +
         "and not re-run (matches [A-Za-z0-9_-], 1-64 chars)");
@@ -40,6 +48,7 @@ function addWriteFlags(cmd, capability = {}) {
         .option("--allow-very-disruptive", "permit changes that visibly drive the Things UI")
         .option("--verify-timeout <ms>", "how long to wait for the change to take effect")
         .option("--actor <name>", "author name recorded for this change (default: from config)")
+        .option("--verbose", VERBOSE_HELP)
         .addOption(opId);
 }
 /**
@@ -126,6 +135,7 @@ function writeOptionsFrom(opts, extra = {}) {
         ...(maxDisruption !== undefined && { maxDisruption }),
         ...(opts.verifyTimeout !== undefined && { verifyTimeoutMs: Number(opts.verifyTimeout) }),
         ...(opts.actor !== undefined && { actor: opts.actor }),
+        ...(opts.verbose === true && { verbose: true }),
         ...(opts.dangerouslyDriveGui === true && { dangerouslyDriveGui: true }),
         ...(opts.opId !== undefined && { opId: opts.opId }),
         ...(opts.preserveModified === true && { preserveModified: true }),
@@ -396,6 +406,30 @@ function emitContextNote(result) {
     if (parts.length > 0)
         process.stdout.write(dim(`  ${parts.join("; ")}\n`));
 }
+/**
+ * The TWO TIERS on the human path (#632), plus the step account when it was
+ * asked for. Warnings are the actionable half and keep the `warning:` prefix on
+ * stderr, where an operator's eye already goes; notes are matter-of-fact and
+ * render DIM and unprefixed on stdout alongside the other disclosure lines, so
+ * "here is what happened" never wears the costume of "you should do something".
+ *
+ * The step account is dimmer still and indented under its own heading — present
+ * only when `--verbose` put `steps` on the result.
+ */
+function emitDisclosures(result) {
+    for (const note of result.notes ?? [])
+        process.stdout.write(dim(`  ${note}\n`));
+    for (const warning of result.warnings ?? []) {
+        process.stderr.write(`warning: ${warning}\n`);
+    }
+    const steps = result.steps ?? [];
+    if (steps.length === 0)
+        return;
+    process.stdout.write(dim(`  drove ${steps.length} step(s):\n`));
+    for (const [i, step] of steps.entries()) {
+        process.stdout.write(dim(`    ${i + 1}. ${step}\n`));
+    }
+}
 function emitResult(result, opts, meta) {
     switch (result.kind) {
         case "bounce-aborted": {
@@ -415,10 +449,11 @@ function emitResult(result, opts, meta) {
             return;
         }
         case "ok": {
-            for (const warning of result.warnings ?? []) {
-                process.stderr.write(`warning: ${warning}\n`);
-            }
             if (opts.json) {
+                // ONE CHANNEL (#632). Under --json the envelope is the WHOLE output:
+                // `warnings` and `notes` are already in it, so echoing them to stderr
+                // made every consumer pay for the same prose twice — once parsed, once
+                // as noise in its log. The human path below keeps the prose.
                 process.stdout.write(`${JSON.stringify(okEnvelope("mutation-result", mutationWireData(result), meta))}\n`);
             }
             else {
@@ -430,6 +465,7 @@ function emitResult(result, opts, meta) {
                 emitOccurrenceNote(result);
                 emitPreserveNote(result);
                 emitContextNote(result);
+                emitDisclosures(result);
             }
             process.exitCode = ExitCode.Ok;
             return;
@@ -459,7 +495,14 @@ function emitResult(result, opts, meta) {
                     message: result.detail,
                     ...(result.likelyCause !== undefined && { likelyCause: result.likelyCause }),
                     ...(result.hint !== undefined && { remediation: result.hint }),
-                    detail: { expected: result.expected, observed: result.observed },
+                    detail: {
+                        expected: result.expected,
+                        observed: result.observed,
+                        // A FAILURE always carries the drive's play-by-play (#632) —
+                        // no flag, no second command. It is what made the field bug
+                        // reports actionable.
+                        ...(result.steps !== undefined && { steps: result.steps }),
+                    },
                 }, meta))}\n`);
             }
             else {
@@ -467,6 +510,9 @@ function emitResult(result, opts, meta) {
                 if (result.likelyCause !== undefined) {
                     process.stderr.write(`  likely cause: ${result.likelyCause}${result.hint !== undefined ? ` — ${result.hint}` : ""}\n`);
                 }
+                for (const [i, step] of (result.steps ?? []).entries()) {
+                    process.stderr.write(`  step ${i + 1}: ${step}\n`);
+                }
             }
             process.exitCode = ExitCode.VerifyFailed;
             return;
@@ -1999,12 +2045,10 @@ export function registerWriteCommands(program) {
             // Human path discloses the count inline; --json carries it on
             // `observed.logged`. Everything else defers to the shared emitter.
             if (result.kind === "ok" && o.json !== true) {
-                for (const warning of result.warnings ?? []) {
-                    process.stderr.write(`warning: ${warning}\n`);
-                }
                 const logged = result.observed?.logged ?? 0;
                 process.stdout.write(`ok log-now (logged ${logged} item${logged === 1 ? "" : "s"}, ` +
                     `vector=${result.vector}, tier=${result.tier}, verified)\n`);
+                emitDisclosures(result);
                 process.exitCode = ExitCode.Ok;
                 return;
             }