@ultimat3/cli 22.15.0 → 24.0.0

package/src/cmd-secrets.ts

@@ -25,25 +25,68 @@ import {
   SecretsPlaintextInvalidError,
   secretsFileExists,
   serializeSecretValues,
+  UltimateError,
   writeMasterKeyFile,
   writeSecretsFile,
 } from '@ultimat3/core';
 import { ENV_SCHEMA_EXPORT, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
+import { appSecrets, dropRetired, retire, retiredKeyIds } from './cmd-secrets-ring';
 import { secretsSpec } from './cmd-secrets-spec';
 import type { CliCommand, CommandContext } from './command';
-import {
-  MissingPositionalError,
-  SecretsEditFailedError,
-  SecretsEditorMissingError,
-  SecretsExistsError,
-} from './errors';
+import { MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
+import { flagString } from './parse';
 import { recoverRotation, rotateMasterKey } from './secrets-rotation';
 import { shredOnSignal } from './signal-shred';
 import { renderTable } from './table';
 
+/**
+ * `x secrets edit` decrypts into a buffer and hands it to `$EDITOR`. There is no fallback editor:
+ * guessing one and opening a decrypted file in it is the last place a surprise belongs.
+ */
+export class SecretsEditorMissingError extends UltimateError {
+  constructor(input: { vars: readonly string[] }) {
+    super({
+      code: 'X_SECRETS_EDITOR_MISSING',
+      cause: `x secrets edit opens the decrypted secrets in an editor and none of ${input.vars.join(', ')} is set`,
+      fix: 'EDITOR=nano x secrets edit',
+    });
+  }
+}
+
+/**
+ * The editor exited non-zero — a crash, or a deliberate abort. The buffer is discarded either way
+ * and the committed file is left exactly as it was: resealing a buffer whose editor failed would
+ * commit whatever half-written state the crash left behind.
+ */
+export class SecretsEditFailedError extends UltimateError {
+  constructor(input: { editor: string; code: number }) {
+    super({
+      code: 'X_SECRETS_EDIT_FAILED',
+      cause: `"${input.editor}" exited ${input.code}, so the decrypted buffer was discarded and the committed secrets file was not rewritten`,
+      fix: 'x secrets edit',
+    });
+  }
+}
+
+/**
+ * `x secrets init` would overwrite a file that already exists. `X_GENERATE_CONFLICT` is this
+ * package's own code for exactly that, and a second name for "a generator would clobber something"
+ * is the duplication the code registry exists to prevent. Losing a master key is unrecoverable —
+ * the committed file it opens is then ciphertext nobody can read again.
+ */
+export class SecretsExistsError extends UltimateError {
+  constructor(input: { path: string; fix: string }) {
+    super({
+      code: 'X_GENERATE_CONFLICT',
+      cause: `${input.path} already exists, and x secrets init would replace it`,
+      fix: input.fix,
+    });
+  }
+}
+
 export { SECRETS_SUBCOMMANDS } from './cmd-secrets-spec';
 
 /** In order of precedence. `VISUAL` outranks `EDITOR` by POSIX convention on an interactive tty. */
@@ -244,36 +287,65 @@ async function set(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
   };
 }
 
+/**
+ * The closing half of a rotation: one retired key leaves the ring, by id, once nothing sealed
+ * under it is left. No new key is generated and the key file is not touched — the committed file
+ * is resealed under the key already in force.
+ */
+async function drop(session: Session, keyId: string): Promise<CommandResult> {
+  const { root, key } = session;
+  const after = await dropRetired(await readSecretsFile(root, key), keyId);
+  await writeSecretsFile(root, after, key);
+  const retired = await retiredKeyIds(after);
+  return {
+    ok: true,
+    command: 'secrets',
+    summary: msg('cli.secrets.dropped', { path: SECRETS_FILE, kid: keyId, count: retired.length }),
+    data: {
+      path: SECRETS_FILE,
+      keyId: await masterKeyIdOf(key),
+      dropped: keyId,
+      retiredKeyIds: [...retired],
+    },
+  };
+}
+
 /**
  * A new master key over the same values: staged beside the old one, the file sealed with it, then
  * made live (`rotateMasterKey`). Sealed first with the key file written last, a crash between the
  * two left a committed file no key on disk could open.
+ *
+ * The key being replaced joins the ring INSIDE the sealed file (`cmd-secrets-ring.ts`), so a value
+ * `seal()` wrote under it still opens and a deploy is still handed exactly one key.
  */
 async function rotate(ctx: CommandContext): Promise<CommandResult> {
-  const { root, key } = await open(ctx, 'rotate');
-  const values = await readSecretsFile(root, key);
+  const session = await open(ctx, 'rotate');
+  const dropping = flagString(ctx.args, 'drop');
+  if (dropping !== undefined) return drop(session, dropping);
+  const { root, key } = session;
+  const values = retire(await readSecretsFile(root, key), key.hex);
   const previous = await masterKeyIdOf(key);
   // Ignored BEFORE any key file is written, staged one included; the order inside is
   // `secrets-rotation.ts`'s: stage the key, seal, then rename it live.
   await ensureIgnored(root);
   const next = await rotateMasterKey(root, values);
   const keyId = await masterKeyIdOf(next);
+  const count = Object.keys(appSecrets(values)).length;
   return {
     ok: true,
     command: 'secrets',
-    summary: msg('cli.secrets.rotated', {
-      path: SECRETS_FILE,
-      from: previous,
-      to: keyId,
-      count: Object.keys(values).length,
-    }),
-    lines: [msg('cli.secrets.redeploy', { env: SECRETS_KEY_ENV, keyPath: SECRETS_KEY_FILE })],
+    summary: msg('cli.secrets.rotated', { path: SECRETS_FILE, from: previous, to: keyId, count }),
+    lines: [
+      msg('cli.secrets.redeploy', { env: SECRETS_KEY_ENV, keyPath: SECRETS_KEY_FILE }),
+      msg('cli.secrets.retired', { kid: previous }),
+    ],
     data: {
       path: SECRETS_FILE,
       keyPath: SECRETS_KEY_FILE,
       previousKeyId: previous,
       keyId,
-      count: Object.keys(values).length,
+      count,
+      retiredKeyIds: [...(await retiredKeyIds(values))],
     },
   };
 }
@@ -285,9 +357,12 @@ async function rotate(ctx: CommandContext): Promise<CommandResult> {
  */
 async function show(ctx: CommandContext): Promise<CommandResult> {
   const { root, key } = await open(ctx, 'show');
-  const values = await readSecretsFile(root, key);
+  const sealed = await readSecretsFile(root, key);
+  // The ring is the framework's own entry: reported by key id below, never as an app secret that
+  // `envSchema` forgot to declare.
+  const retired = await retiredKeyIds(sealed);
   const schema = await loadEnvSchema(root);
-  const summaries = describeSecrets(values);
+  const summaries = describeSecrets(appSecrets(sealed));
   const keyId = await masterKeyIdOf(key);
   const declared = (name: string): boolean | undefined =>
     schema === undefined ? undefined : schema[name] !== undefined;
@@ -309,6 +384,7 @@ async function show(ctx: CommandContext): Promise<CommandResult> {
       : [
           msg('cli.secrets.undeclared', { count: undeclared.length, names: undeclared.join(', ') }),
         ]),
+    ...(retired.length === 0 ? [] : [msg('cli.secrets.ring', { kids: retired.join(', ') })]),
   ];
   return {
     ok: true,
@@ -322,6 +398,7 @@ async function show(ctx: CommandContext): Promise<CommandResult> {
       path: SECRETS_FILE,
       keySource: key.source,
       keyId,
+      retiredKeyIds: [...retired],
       count: summaries.length,
       secrets: summaries.map((entry) => ({
         name: entry.name,

package/src/cmd-shot-matrix.ts

@@ -5,6 +5,7 @@
 
 // why: no Bun native joins a path.
 import { join, relative } from 'node:path';
+import { escapeHtml } from '@ultimat3/core';
 import { routeEntries } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import type { ShotRun } from './cmd-shot';
@@ -94,9 +95,6 @@ export interface MatrixShot {
   readonly image: string;
 }
 
-const escapeHtml = (text: string): string =>
-  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-
 /**
  * The contact sheet. System colours only (`Canvas`, `CanvasText`, `Mark`): a generated review page
  * has no design tokens to read, and a literal colour would be the one this repo refuses.

package/src/cmd-shot.ts

@@ -339,6 +339,14 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
   }
 }
 
+/**
+ * Where the artifacts land. A relative `--out` is a path the caller typed from where they stand,
+ * so it resolves against the cwd — `x build --out`'s rule. Against the app root it landed
+ * somewhere else whenever `x shot` ran from `apps/web`.
+ */
+export const shotOutDir = (cwd: string, out: string | undefined, fallback: string): string =>
+  out === undefined ? fallback : resolve(cwd, out);
+
 export const shotResult = (artifacts: ShotArtifacts): CommandResult => ({
   ok: artifacts.verdict.ok,
   command: 'shot',
@@ -426,7 +434,8 @@ export const shotCommand: CliCommand = {
     const boot = (): Promise<ShotServer> => devServerFor(root, ctx.env, port);
     const shared = {
       root,
-      ...(out === undefined ? {} : { out }),
+      // Absolute here, so the island sweep's own `resolve(root, out)` keeps the caller's path.
+      ...(out === undefined ? {} : { out: shotOutDir(ctx.cwd, out, root) }),
       settleMs,
       timeoutMs,
       ...(executablePath === undefined ? {} : { executablePath }),
@@ -465,7 +474,7 @@ export const shotCommand: CliCommand = {
         defaultLocale: app.defaultLocale,
         ...(theme === undefined ? {} : { themes: [theme] }),
       });
-      const outDir = out === undefined ? join(root, MATRIX_DIR) : resolve(root, out);
+      const outDir = shotOutDir(ctx.cwd, out, join(root, MATRIX_DIR));
       return runShotMatrix({ cells, outDir, boot, shoot: runShot, base });
     }
     const shown = locale ?? app.defaultLocale;
@@ -474,7 +483,7 @@ export const shotCommand: CliCommand = {
       await runShot({
         ...base,
         route: path,
-        outDir: out === undefined ? join(root, SHOT_DIR, shotSlug(path)) : resolve(root, out),
+        outDir: shotOutDir(ctx.cwd, out, join(root, SHOT_DIR, shotSlug(path))),
         boot,
         // Pinned whether or not `--locale` was given: the default locale, never the box's own.
         acceptLanguage: shown,

package/src/cmd-tasks.ts

@@ -1,16 +1,19 @@
 // `x tasks [list|show <name>]` — introspect scheduled cron tasks: cadence, timezone, the jobs
-// each enqueues, and real next-occurrence instants from `@ultimat3/time`'s cron math instead of
-// an agent reading `0 3 * * *` and guessing. CLI wiring only; the pure computation lives in
-// `tasks-facts.ts` — the same split `cmd-jobs.ts` makes against `jobs-report.ts`.
+// each enqueues, the occurrence the scheduler LAST dispatched (off the queue's own record) and
+// real next-occurrence instants from `@ultimat3/time`'s cron math instead of an agent reading
+// `0 3 * * *` and guessing. CLI wiring only; the pure computation lives in `tasks-facts.ts` — the
+// same split `cmd-jobs.ts` makes against `jobs-report.ts`.
 
 import { nearestName, systemClock } from '@ultimat3/core';
-import type { TaskHandle } from '@ultimat3/jobs';
+import type { JobDriver, TaskFire, TaskHandle } from '@ultimat3/jobs';
 import type { CronPhrases } from '@ultimat3/time';
+import { fromEpochMs, isoInZone } from '@ultimat3/time';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import { tasksSpec } from './cmd-tasks-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, DeclarationUnknownError } from './errors';
+import { withJobDriver } from './jobs-driver';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { flagString } from './parse';
@@ -24,7 +27,41 @@ import {
   taskShowFacts,
 } from './tasks-facts';
 
-const HEADER = ['name', 'cron', 'tz', 'catchUp', 'jobs', 'next'] as const;
+const HEADER = ['name', 'cron', 'tz', 'catchUp', 'jobs', 'last', 'next'] as const;
+
+/**
+ * When a task last fired, flat beside `nextMs` / `next`. All three are `null` for a task the
+ * scheduler has never dispatched — a key that is sometimes absent is a question asked two ways.
+ */
+interface LastFire {
+  /** Epoch ms of the occurrence it was scheduled FOR — the instant `last` renders. */
+  readonly lastMs: number | null;
+  readonly last: string | null;
+  /** Epoch ms the scheduler dispatched it, on the queue's clock. Later than `lastMs` by its lag. */
+  readonly lastFiredAtMs: number | null;
+}
+
+const NEVER_FIRED: LastFire = { lastMs: null, last: null, lastFiredAtMs: null };
+
+/**
+ * The last occurrence each task DISPATCHED, by task name — `JobIntrospection.taskFires()`, never
+ * the scheduler's watermark, which arming and skipping move too. A driver with no introspection
+ * answers none, and every task then reads as never fired.
+ */
+async function lastFires(driver: JobDriver): Promise<ReadonlyMap<string, TaskFire>> {
+  const fires = (await driver.introspect?.taskFires()) ?? [];
+  return new Map(fires.map((fire) => [fire.task, fire]));
+}
+
+const lastFireOf = (fires: ReadonlyMap<string, TaskFire>, name: string, tz: string): LastFire => {
+  const fire = fires.get(name);
+  if (fire === undefined) return NEVER_FIRED;
+  return {
+    lastMs: fire.occurrenceMs,
+    last: isoInZone(fromEpochMs(fire.occurrenceMs), tz),
+    lastFiredAtMs: fire.firedAt,
+  };
+};
 
 /**
  * The vocabulary `describeCron` interpolates. The cron *math* stays in `tasks-facts.ts` — it is
@@ -57,17 +94,25 @@ const detailLines = (payload: Readonly<Record<string, JsonValue>>): readonly str
 
 const jobsCell = (jobs: readonly string[]): string => (jobs.length === 0 ? '-' : jobs.join(','));
 
-const row = (fact: TaskFact): readonly string[] => [
+const row = (fact: TaskFact & LastFire): readonly string[] => [
   fact.name,
   fact.cron,
   fact.tz,
   fact.catchUp,
   jobsCell(fact.jobs),
+  fact.last ?? '-',
   fact.next,
 ];
 
-function runList(nowMs: number, findings: readonly Finding[]): CommandResult {
-  const facts = listTaskFacts(nowMs);
+function runList(
+  nowMs: number,
+  fires: ReadonlyMap<string, TaskFire>,
+  findings: readonly Finding[],
+): CommandResult {
+  const facts = listTaskFacts(nowMs).map((fact) => ({
+    ...fact,
+    ...lastFireOf(fires, fact.name, fact.tz),
+  }));
   return {
     ok: findings.length === 0,
     command: 'tasks',
@@ -101,13 +146,23 @@ function requireHandle(ctx: CommandContext): TaskHandle {
   );
 }
 
-function runShow(ctx: CommandContext, nowMs: number, findings: readonly Finding[]): CommandResult {
-  const handle = requireHandle(ctx);
-  const count = parseCountFlag(flagString(ctx.args, 'count'));
-  const { descriptor, describe, upcoming } = taskShowFacts(handle, nowMs, count, cronPhrases());
+function runShow(
+  shown: { readonly handle: TaskHandle; readonly count: number },
+  nowMs: number,
+  fires: ReadonlyMap<string, TaskFire>,
+  findings: readonly Finding[],
+): CommandResult {
+  const { descriptor, describe, upcoming } = taskShowFacts(
+    shown.handle,
+    nowMs,
+    shown.count,
+    cronPhrases(),
+  );
   const first = upcoming[0];
+  const fired = lastFireOf(fires, descriptor.name, descriptor.tz);
   const lines = [
     ...detailLines(asJson(descriptor)),
+    `  last: ${fired.last ?? '-'}`,
     `  ${describe}`,
     ...upcoming.map((occurrence) => `    ${occurrence.at}`),
   ];
@@ -124,6 +179,7 @@ function runShow(ctx: CommandContext, nowMs: number, findings: readonly Finding[
     findings,
     data: {
       ...asJson(descriptor),
+      ...fired,
       describe,
       upcoming: upcoming.map((occurrence) => asJson(occurrence)),
     },
@@ -136,8 +192,21 @@ export const tasksCommand: CliCommand = {
     const root = requireAppRoot('tasks', ctx.cwd).dir;
     const { findings } = await loadApp(root);
     const nowMs = systemClock.now().getTime();
-    return ctx.args.subcommand === 'show'
-      ? runShow(ctx, nowMs, findings)
-      : runList(nowMs, findings);
+    // Everything argv can get wrong is refused BEFORE the queue is opened: a typo in a task name
+    // must not cost a database boot to be told about.
+    const shown =
+      ctx.args.subcommand === 'show'
+        ? { handle: requireHandle(ctx), count: parseCountFlag(flagString(ctx.args, 'count')) }
+        : undefined;
+    // Nothing to join a fire to: an app that declares no task never pays for a queue.
+    if (shown === undefined && knownTaskNames().length === 0) {
+      return runList(nowMs, new Map(), findings);
+    }
+    return withJobDriver(root, ctx, async (driver) => {
+      const fires = await lastFires(driver);
+      return shown === undefined
+        ? runList(nowMs, fires, findings)
+        : runShow(shown, nowMs, fires, findings);
+    });
   },
 };

package/src/cmd-test-spec.ts

@@ -10,7 +10,7 @@ export const testSpec: CommandSpec = {
   name: 'test',
   summary:
     'run one test type — or the whole suite — across N workers, one isolated database per worker',
-  usage: `x test [${TEST_TYPES.join('|')}] [--filter path[,path…]] [--allow-empty] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--isolate] [--json] [-- <bun test flags>]`,
+  usage: `x test [${TEST_TYPES.join('|')}] [--filter path[,path…]] [--allow-empty] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--isolate] [--json] [-- <bun test flags>]`,
   positionalChoices: TEST_TYPES,
   // The one command that hands a tail to another tool — `bun test` — and the reason
   // `CommandSpec.passthrough` exists: `x test unit -- --coverage --bail` parsed both flags and
@@ -28,12 +28,6 @@ export const testSpec: CommandSpec = {
       summary:
         'a fresh global per test file (bun test --isolate) — off by default since 22.7; x.verify.json "isolate": true makes it the repo default',
     },
-    {
-      name: 'worker',
-      type: 'string',
-      summary:
-        'run only shard I of an N-way split of the selection, serially — one CI job\u2019s share',
-    },
     {
       name: 'filter',
       type: 'string',

package/src/cmd-test.ts

@@ -40,22 +40,20 @@ import type { TestType } from './verify-tests';
 import { TEST_TYPES } from './verify-tests';
 
 /**
- * `--workers` and `--shard`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while
- * `cmd-verify.ts`'s own comment claimed `x test --workers` refused the same values `x verify`
- * does — so the two commands disagreed about the same flag. One reader now answers for both.
+ * `--workers`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while `cmd-verify.ts`'s
+ * own comment claimed `x test --workers` refused the same values `x verify` does — so the two
+ * commands disagreed about the same flag. One reader now answers for both.
  */
-const readIndex = (args: ParsedArgs, name: string, min: number): number | undefined =>
+const readWorkers = (args: ParsedArgs): number | undefined =>
   readIntFlag(args, {
-    name,
+    name: 'workers',
     command: 'test',
-    min,
+    min: 1,
     // The ceiling the summary already claimed and the reader never enforced: `--workers 5000` was
     // accepted and the run clamps only to the file count, which is one Bun worker per test FILE,
-    // each with the framework module graph and a cloned database. `--worker` is an index into an
-    // N-way split, so the same bound holds it (the exact upper index is `workers - 1`, refused a
-    // line below by the check that knows the real width).
+    // each with the framework module graph and a cloned database.
     max: WORKER_CEILING,
-    example: `x test --${name} ${Math.max(min, 1)}`,
+    example: 'x test --workers 1',
   });
 
 /**
@@ -168,29 +166,17 @@ export const testCommand: CliCommand = {
       });
     }
     const files = sample === undefined ? selected : sampleFiles(selected, sample);
-    const explicit = readIndex(ctx.args, 'workers', 1);
+    const explicit = readWorkers(ctx.args);
     const plan =
       explicit === undefined ? workerPlan(availableCpus(), totalMemory(), ctx.env) : undefined;
     const requested = explicit ?? (plan as WorkerPlan).workers;
     const floor = await readVerifyFloor(ctx.cwd);
     const isolate = flagBool(ctx.args, 'isolate') || floor?.isolate === true;
-    // The width a `--worker` index is judged against, and nothing else: which files really run one
-    // at a time is `test-passes.ts`, off the FILES rather than off the positional. This line read
-    // the positional alone until 2026-09 and the comment here claimed it made a serial type serial
-    // — true for `x test live`, false for the bare `x test --workers 8` that selects every type,
-    // which ran the same `live` and `e2e` files eight at a time. It stays because a `--worker` run
-    // is one process per CI JOB: sharding a serial type across N of them is the cluster-wide race
-    // in a second disguise, and refusing the index is where that is caught.
+    // A serial type is one worker whatever `--workers` says. `test-passes.ts` makes the same call
+    // off the FILES, which is what decides which files really run one at a time; this keeps the
+    // width the run reports and reproduces with the one it ran at.
     const ceiling = type !== undefined && SERIAL_TYPES.includes(type) ? 1 : files.length;
     const workers = Math.max(1, Math.min(requested, ceiling));
-    const only = readIndex(ctx.args, 'worker', 0);
-    if (only !== undefined && only >= workers) {
-      throw new BadFlagError({
-        flag: 'worker',
-        command: 'test',
-        reason: `shard ${only} does not exist in a ${workers}-worker split (0..${workers - 1})`,
-      });
-    }
     const result = await runShards({
       root: ctx.cwd,
       runner: ctx.runner,
@@ -201,11 +187,9 @@ export const testCommand: CliCommand = {
       // A default-width run leases its workers from the machine pool, so a second `x test` or
       // gate on the same box runs narrower instead of doubling its memory.
       ...(plan === undefined ? {} : withLease(machineLease(plan.workers, ctx.env))),
-      ...(only === undefined ? {} : { only }),
       ...(filter === undefined ? {} : { filter }),
       ...(type === undefined ? {} : { type }),
-      // `kept` is the corpus the split saw; a `--worker` rerun must name it, not its own shard.
-      // `selected`, not `discovered`: with `--affected` the sample was taken from the narrowed
+      // `kept` is the corpus the run saw. `selected`, not `discovered`: with `--affected` the sample was taken from the narrowed
       // set, and reporting the whole tree as its total would name a corpus no run ever had.
       ...(sample === undefined ? {} : { sample: { kept: files.length, total: selected.length } }),
       // The fourth input to the split. Without it a failing shard's `fix:` re-splits the whole

package/src/cmd-verify.ts

@@ -20,15 +20,16 @@ import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
 import { WORKER_CEILING, WORKER_FLOOR } from './test-workers';
 import { VERIFY_STEPS } from './verify-checks';
-import { VerifyMergeInputError, VerifyShardInvalidError } from './verify-errors';
 import { readVerifyFloor } from './verify-floor';
 import type { VerifyPart } from './verify-merge';
-import { mergeParts, parsePart } from './verify-merge';
+import { coverageRiders, mergeParts, parsePart, VerifyMergeInputError } from './verify-merge';
+import { stepStream } from './verify-progress';
 import { runVerify } from './verify-run';
 import type { ShardSpec, Timings } from './verify-shard';
-import { assertShardable, parseShard, readTimings } from './verify-shard';
+import { assertShardable, parseShard, readTimings, VerifyShardInvalidError } from './verify-shard';
 import type { VerifyStepName } from './verify-step';
 import { VERIFY_STEP_NAMES } from './verify-step';
+import { writeErrorLine } from './write-line';
 
 // One import path for the gate, unchanged by the split: `index.ts`, `x build` and the MCP host all
 // reach the list and the runner through this module, and a second path to either would be the
@@ -55,6 +56,9 @@ export const verifyCommand: CliCommand = {
       ...(only === undefined ? {} : { only }),
       ...(shard === undefined ? {} : { shard }),
       ...(isolate === undefined ? {} : { isolate }),
+      // `--json` prints one document when the run ends; a line per finished step on stderr is
+      // what a cancelled CI job's log ends on (#589). stdout stays the single document.
+      ...stepStream(ctx.args.json, writeErrorLine),
     });
     return shard === undefined ? result : withShardData(result, shard);
   },
@@ -119,7 +123,10 @@ async function mergeCommand(
     }
     parts.push(parsePart(file, await handle.text()));
   }
-  return mergeParts(parts, await readVerifyFloor(root));
+  const floor = await readVerifyFloor(root);
+  return mergeParts(parts, floor, VERIFY_STEP_NAMES, {
+    riders: await coverageRiders(parts, root, floor),
+  });
 }
 
 /**
@@ -142,8 +149,9 @@ export const readOnlySteps = (args: ParsedArgs): readonly VerifyStepName[] | und
   if (unknown.length === 0) {
     return VERIFY_STEP_NAMES.filter((name) => items.includes(name));
   }
+  // An empty item corrects to nothing — never to whichever step is nearest to ''.
   const corrected = items.map((item) =>
-    isStepName(item) ? item : nearestName(item, VERIFY_STEP_NAMES),
+    isStepName(item) ? item : item === '' ? undefined : nearestName(item, VERIFY_STEP_NAMES),
   );
   const fix = corrected.every((item) => item !== undefined)
     ? `x verify --only ${renderFixShellArg([...new Set(corrected)].join(','), '<step,step>')} --json`

package/src/comment-safe.ts

@@ -0,0 +1,16 @@
+// A path read off the repository being scanned, made safe to ride in the `#` comment of a `fix:`
+// line. One definition: every finding that names a scanned file in its fix writes it through this.
+
+/**
+ * Control characters, `\u00xx`-escaped. The path is a value read off the repository being scanned,
+ * and it rides in a `#` comment: a directory holding a NEWLINE ends that comment, so everything
+ * after it is a second command in a line whose whole purpose is to be pasted into a shell.
+ * Escaped rather than deleted, because the comment still has to name the file the reader owns.
+ */
+export const commentSafe = (path: string): string =>
+  [...path]
+    .map((char) => {
+      const code = char.codePointAt(0) ?? 0;
+      return code < 0x20 || code === 0x7f ? `\\u${code.toString(16).padStart(4, '0')}` : char;
+    })
+    .join('');