@ultimat3/cli 27.13.2 → 27.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.13.2",
+  "version": "27.14.1",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.13.2",
-    "@ultimat3/admin": "27.13.2",
-    "@ultimat3/ai": "27.13.2",
-    "@ultimat3/auth": "27.13.2",
-    "@ultimat3/cache": "27.13.2",
-    "@ultimat3/core": "27.13.2",
-    "@ultimat3/db": "27.13.2",
-    "@ultimat3/entity": "27.13.2",
-    "@ultimat3/flags": "27.13.2",
-    "@ultimat3/http": "27.13.2",
-    "@ultimat3/i18n": "27.13.2",
-    "@ultimat3/jobs": "27.13.2",
-    "@ultimat3/mail": "27.13.2",
-    "@ultimat3/manifest": "27.13.2",
-    "@ultimat3/mcp": "27.13.2",
-    "@ultimat3/money": "27.13.2",
-    "@ultimat3/notify": "27.13.2",
-    "@ultimat3/policy": "27.13.2",
-    "@ultimat3/pwa": "27.13.2",
-    "@ultimat3/query": "27.13.2",
-    "@ultimat3/realtime": "27.13.2",
-    "@ultimat3/render": "27.13.2",
-    "@ultimat3/schema": "27.13.2",
-    "@ultimat3/seo": "27.13.2",
-    "@ultimat3/storage": "27.13.2",
-    "@ultimat3/testing": "27.13.2",
-    "@ultimat3/time": "27.13.2",
+    "@ultimat3/action": "27.14.1",
+    "@ultimat3/admin": "27.14.1",
+    "@ultimat3/ai": "27.14.1",
+    "@ultimat3/auth": "27.14.1",
+    "@ultimat3/cache": "27.14.1",
+    "@ultimat3/core": "27.14.1",
+    "@ultimat3/db": "27.14.1",
+    "@ultimat3/entity": "27.14.1",
+    "@ultimat3/flags": "27.14.1",
+    "@ultimat3/http": "27.14.1",
+    "@ultimat3/i18n": "27.14.1",
+    "@ultimat3/jobs": "27.14.1",
+    "@ultimat3/mail": "27.14.1",
+    "@ultimat3/manifest": "27.14.1",
+    "@ultimat3/mcp": "27.14.1",
+    "@ultimat3/money": "27.14.1",
+    "@ultimat3/notify": "27.14.1",
+    "@ultimat3/policy": "27.14.1",
+    "@ultimat3/pwa": "27.14.1",
+    "@ultimat3/query": "27.14.1",
+    "@ultimat3/realtime": "27.14.1",
+    "@ultimat3/render": "27.14.1",
+    "@ultimat3/schema": "27.14.1",
+    "@ultimat3/seo": "27.14.1",
+    "@ultimat3/storage": "27.14.1",
+    "@ultimat3/testing": "27.14.1",
+    "@ultimat3/time": "27.14.1",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/budgets-unmeasured.ts

@@ -39,13 +39,26 @@ const ACTOR_REFUSALS: ReadonlySet<string> = new Set([
   'X_TENANCY_ACTOR_ORG_REQUIRED',
 ]);
 
-function ownCodeFinding(url: string, entry: UnmeasuredRoute): Finding {
+/**
+ * The locator every finding here carries: `at` is the FILE an agent opens, never the route URL —
+ * `output.ts`'s `Finding.at`, and `verify-checks.ts` reads it as the path to open. The URL is a
+ * fact of its own and rides beside it in `meta.route`, so `--json` loses nothing by the move.
+ *
+ * OMITTED, not filled with something, when no file declares the route: a URL is not a path anyone
+ * can open, and `at` that names nothing opens nothing. The cause and the fix both name the URL.
+ */
+const locatorOf = (file: string | undefined, url: string): Pick<Finding, 'at' | 'meta'> => ({
+  ...(file === undefined ? {} : { at: file }),
+  meta: { route: url },
+});
+
+function ownCodeFinding(url: string, file: string | undefined, entry: UnmeasuredRoute): Finding {
   return {
     code: entry.code ?? 'X_BUDGET_UNMEASURED',
     cause: entry.cause ?? entry.reason,
     fix: entry.fix ?? `x build --target static --json   # its "unmeasured" list has ${url}`,
     docs: ERROR_DOCS_URL,
-    at: url,
+    ...locatorOf(file, url),
   };
 }
 
@@ -57,15 +70,20 @@ const refusalOf = (entry: UnmeasuredRoute): string =>
  * A build ran and has no row for `url`. `entry` is the report's account of why, when it has one:
  * an instruction under its own code, an actor edit, or — for a failure that is a fact about the
  * build's environment — the report, with the refusal already in the cause.
+ *
+ * `file` is the file that declares `url`, resolved by the caller (`budgets.ts` asks the loaded
+ * route table); `undefined` when no route file claims it, and the finding then carries no locator
+ * rather than a URL that opens nothing.
  */
 export function builtUnmeasuredFinding(
   url: string,
   declared: string,
   statsFile: string,
   entry: UnmeasuredRoute | undefined,
+  file: string | undefined,
 ): Finding {
   if (entry?.code !== undefined && REPORTED_BY_OWN_CODE.has(entry.code)) {
-    return ownCodeFinding(url, entry);
+    return ownCodeFinding(url, file, entry);
   }
   const base = `${url} declares a ${declared} budget and ${statsFile} has no row for it, so the build ran and could not weigh it`;
   if (entry?.code !== undefined && ACTOR_REFUSALS.has(entry.code)) {
@@ -76,7 +94,7 @@ export function builtUnmeasuredFinding(
       // The paste: one declaration in the one file every build imports.
       fix: "defineMeasurementActor(() => userActor({ id: 'measure', orgId: '<an org your dev seed creates>', roles: ['<the role this page requires>'] }))   # in app.config.ts",
       docs: ERROR_DOCS_URL,
-      at: url,
+      ...locatorOf(file, url),
     };
   }
   return {
@@ -86,6 +104,6 @@ export function builtUnmeasuredFinding(
     // route it could not weigh, and why.
     fix: `x build --target static --json   # its "unmeasured" list says why ${url} could not be weighed`,
     docs: ERROR_DOCS_URL,
-    at: url,
+    ...locatorOf(file, url),
   };
 }

package/src/budgets.ts

@@ -117,27 +117,34 @@ function exceededJsFix(url: string, file: string | undefined, bytes: number): st
  * run and could not weigh this one, which is `PrerenderReport.unmeasured`'s question and not a
  * second build's. Reporting the first as the second is what sends a reader to re-run a build that
  * already did everything it was going to do.
+ *
+ * `fileOf` names the file an agent opens to fix this route, exactly as it does for
+ * `X_BUDGET_EXCEEDED`: `Finding.at` is a PATH, never a URL (`output.ts`, `verify-checks.ts`),
+ * so the route rides beside it in `meta.route` and every cause below still spells the URL.
  */
 function unmeasuredFinding(
   url: string,
   declared: string,
   stats: BuildStats | undefined,
   unmeasured: readonly UnmeasuredRoute[],
+  fileOf: RouteFileOf,
 ): Finding {
+  const file = fileOf(url);
   if (stats?.stale === true) {
     return {
       code: 'X_BUDGET_UNMEASURED',
       cause: `${url} declares a ${declared} budget and ${BUILD_STATS_FILE} was written by an earlier measurement rule than this gate's (v${String(BUILD_STATS_RULES)}), so its numbers are not this gate's to read`,
       fix: 'x build --target static --json && x verify --json',
       docs: ERROR_DOCS_URL,
-      at: url,
+      ...(file === undefined ? {} : { at: file }),
+      meta: { route: url },
     };
   }
   // A build ran: the report's account of this route decides the instruction
   // (`budgets-unmeasured.ts`) — its own code, an actor edit, or the report.
   if (stats !== undefined) {
     const entry = unmeasured.find((one) => one.path === url);
-    return builtUnmeasuredFinding(url, declared, BUILD_STATS_FILE, entry);
+    return builtUnmeasuredFinding(url, declared, BUILD_STATS_FILE, entry, file);
   }
   return {
     code: 'X_BUDGET_UNMEASURED',
@@ -147,7 +154,8 @@ function unmeasuredFinding(
     // the one caller of `writeBuildStats`.
     fix: 'x build --target static --json && x verify --json',
     docs: ERROR_DOCS_URL,
-    at: url,
+    ...(file === undefined ? {} : { at: file }),
+    meta: { route: url },
   };
 }
 
@@ -161,8 +169,9 @@ function unmeasuredFinding(
  * and can be absent for the same reason; with it, a route whose measurement failed on a code in
  * `REPORTED_BY_OWN_CODE` (`budgets-unmeasured.ts`) is reported under that code, with the build's own cause and fix.
  *
- * `fileOf` names the file an `X_BUDGET_EXCEEDED` fix edits: the step runs after the app loaded,
- * so render's route table already holds it. A test hands its own.
+ * `fileOf` names the file an agent opens for a route's finding — the locator `Finding.at` carries
+ * and the file `X_BUDGET_EXCEEDED`'s fix edits: the step runs after the app loaded, so render's
+ * route table already holds it. A test hands its own.
  */
 export function checkBudgets(
   manifest: Manifest,
@@ -183,19 +192,24 @@ export function checkBudgets(
     const js = jsBudgetOf(route);
     if (measured === undefined) {
       if (js !== null) {
-        findings.push(unmeasuredFinding(route.url, 'JS', stats, unmeasured));
+        findings.push(unmeasuredFinding(route.url, 'JS', stats, unmeasured, fileOf));
       }
       continue;
     }
     if (js !== null && measured.jsBytes > js) {
-      const meta = chargedMeta(measured.jsBytes, measured.charged, measured.inlineJsBytes);
+      // `at` is the file an agent opens — the SAME resolution `exceededJsFix` edits, so the
+      // locator and the instruction name one place. The route URL it belongs to is in `cause`
+      // (`budgets-charged.test.ts` holds the per-file breakdown in `meta` only when a row carries
+      // one — adding a `route` key would conflict with that contract).
+      const file = fileOf(route.url);
+      const charged = chargedMeta(measured.jsBytes, measured.charged, measured.inlineJsBytes);
       findings.push({
         code: 'X_BUDGET_EXCEEDED',
         cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS (minified, uncompressed) over a ${formatBytes(js)} budget via ${chainOf(measured)}${chargedClause(measured.charged, measured.inlineJsBytes)}`,
-        fix: exceededJsFix(route.url, fileOf(route.url), measured.jsBytes),
+        fix: exceededJsFix(route.url, file, measured.jsBytes),
         docs: ERROR_DOCS_URL,
-        at: route.url,
-        ...(meta === undefined ? {} : { meta }),
+        ...(file === undefined ? {} : { at: file }),
+        ...(charged === undefined ? {} : { meta: charged }),
       });
     }
   }

package/src/ci-log.ts

@@ -4,7 +4,7 @@
 // this file undoes the transport and reconstructs the `Finding`, rather than printing a wall of
 // text and asking the reader to spot the code in it.
 
-import type { Finding } from './output';
+import type { Finding, JsonValue } from './output';
 
 /** One log line, with the two columns Actions prefixes every line with taken off. */
 export interface CiLogLine {
@@ -67,11 +67,52 @@ export function jobsInLog(lines: readonly CiLogLine[]): readonly string[] {
 }
 
 const CODE = /^(X_[A-Z][A-Z0-9_]*)/;
-const LOCATOR = /\(([^()]+)\)$/;
+// The ONE way a `Finding.at` — a path an agent can open — returns from a log. The renderer
+// prints it as the parenthesised expression in the head (`renderFinding`, `output.ts`).
+//
+// Anchored to the head minus a trailing `[step=…]`, NOT to the end of the line:
+// `X_VERIFY_STEP_TIMEOUT` sets both `at` and `meta.step`, so that head reads
+// `CODE (path) [step=unit]` — an end-anchor matches only what follows the brackets, the match
+// fails, and the path is dropped. With no step the optional group is absent and the
+// parenthesised group is still the last thing on the line.
+const LOCATOR = /\(([^()]+)\)(?=\s*(?:\[step=[^[\]]+\]\s*)?$)/;
+// The second, non-path locator the renderer prints on the head — `meta.step` in the same
+// brackets-keyed form (`[step=lint]`) `renderFinding` writes — so a merge gap's gate step name
+// or any future non-path identifier survives the round-trip too. Its own brackets are what
+// `LOCATOR`'s lookahead stands aside for, so the two cannot collide in one head.
+const STEP_LOCATOR = /\[step=([^[\]]+)\]\s*$/;
 
 const after = (text: string, label: string): string | undefined =>
   text.trim().startsWith(label) ? text.trim().slice(label.length).trim() : undefined;
 
+// The `meta.step` locator the renderer prints in the head (`output.ts:185-189`): a gate step name
+// the finding carries on `meta`, never on `at`. Total on every shape `Finding.meta` may take —
+// the field is optional, and a malformed `meta` (a non-object value, an array) is read as "no
+// step", the same answer an absent `meta` gets.
+const stepOf = (finding: Finding): string => {
+  if (typeof finding.meta === 'object' && finding.meta !== null && !Array.isArray(finding.meta)) {
+    const value = (finding.meta as { readonly [key: string]: JsonValue })['step'];
+    return typeof value === 'string' ? value : '';
+  }
+  return '';
+};
+
+/**
+ * The dedupe key a finding is told apart by. Two findings are the same only if every locator
+ * the renderer prints agrees on them — `code`, `cause`, `at`, and `meta.step`. Ci-log's per-log
+ * dedupe (`findingsFrom` below) and `x ci`'s cross-log dedupe (`cmd-ci.ts`) both build the key
+ * off this formula, so a finding that survives one cannot be silently merged by the other.
+ *
+ * A re-run appends a second copy of the same block; two identical findings would read as two
+ * problems where the job has one. A `X_COVERAGE_BELOW` routed to two different packages is the
+ * opposite — two findings, where a key of code and cause alone folds the second into a duplicate.
+ * `fix` is deliberately not in it: the same block reprints its fix line, and `x ci` fences it
+ * differently per job, so keying on it would report a re-run twice.
+ */
+export function findingKey(finding: Finding): string {
+  return `${finding.code}\0${finding.cause}\0${finding.at ?? ''}\0${stepOf(finding)}`;
+}
+
 /**
  * `renderFinding`'s output, read backwards. A code line ALONE is not a finding — prose naming a
  * code, a summary counting them and a `fix:` quoting one all start with `X_`, and reconstructing
@@ -93,19 +134,26 @@ export function findingsFrom(lines: readonly CiLogLine[]): readonly Finding[] {
     if (cause === undefined || fix === undefined) continue;
     const code = head[1] ?? '';
     const at = LOCATOR.exec(texts[index] ?? '')?.[1];
+    const step = STEP_LOCATOR.exec(texts[index] ?? '')?.[1];
     const docs = after(texts[index + 3] ?? '', 'docs:');
-    const key = `${code}\0${cause}`;
-    // A re-run appends a second copy of the same block; two identical findings would read as two
-    // problems where the job has one.
-    if (!seen.has(key)) {
-      seen.add(key);
-      out.push({
-        code,
-        cause,
-        fix,
-        ...(at === undefined ? {} : { at }),
-        ...(docs === undefined ? {} : { docs }),
-      });
+    // Step name and any other reconstructed structured fact ride on `meta`, so the
+    // reconstructed finding has a place to put a non-path locator `at` cannot carry.
+    const meta = step === undefined ? undefined : { step };
+    // Built once, then keyed: `findingKey` reads `code`, `cause`, `at` and `meta.step` off it,
+    // so the per-log dedupe here and the across-log dedupe in `cmd-ci.ts` agree on what one
+    // finding is. `X_VERIFY_MERGE_INCOMPLETE` arrives here once per missing step, and only the
+    // step name tells them apart.
+    const finding: Finding = {
+      code,
+      cause,
+      fix,
+      ...(at === undefined ? {} : { at }),
+      ...(meta === undefined ? {} : { meta }),
+      ...(docs === undefined ? {} : { docs }),
+    };
+    if (!seen.has(findingKey(finding))) {
+      seen.add(findingKey(finding));
+      out.push(finding);
     }
     index += 2;
   }

package/src/ci-runs.ts

@@ -9,13 +9,14 @@ import type { GhRepo } from './gh-target';
 
 /** The fields both `gh run list` and `gh run view` accept, named once so the two agree. */
 export const RUN_FIELDS =
-  'databaseId,status,conclusion,headBranch,displayTitle,workflowName,url,createdAt';
+  'databaseId,status,conclusion,headBranch,displayTitle,workflowName,url,createdAt,headSha';
 
 const RUN_ROW = t.object({
   databaseId: t.number,
   status: t.string,
   conclusion: t.nullable(t.string),
   headBranch: t.string,
+  headSha: t.string,
   displayTitle: t.string,
   workflowName: t.string,
   url: t.string,
@@ -58,6 +59,7 @@ export interface CiRun {
   readonly workflow: string;
   readonly url: string;
   readonly createdAt: string;
+  readonly headSha: string;
 }
 
 /**
@@ -85,6 +87,7 @@ interface RunRow {
   readonly status: string;
   readonly conclusion: string | null;
   readonly headBranch: string;
+  readonly headSha: string;
   readonly displayTitle: string;
   readonly workflowName: string;
   readonly url: string;
@@ -96,6 +99,7 @@ const runOf = (row: RunRow): CiRun => ({
   status: row.status,
   conclusion: row.conclusion,
   branch: row.headBranch,
+  headSha: row.headSha,
   title: row.displayTitle,
   workflow: row.workflowName,
   url: row.url,
@@ -117,11 +121,17 @@ export function latestPerWorkflow(runs: readonly CiRun[]): readonly CiRun[] {
   return [...newest.values()];
 }
 
+/**
+ * The branch's runs, newest first. `filters` narrows the ask to one workflow or one event; with
+ * neither given, the argv is byte-for-byte the one `x ci` has always sent — cmd-ci.test.ts pins
+ * it, so a filter may only ever insert its pair between `--branch` and `--limit`.
+ */
 export async function listRuns(
   host: GhHost,
   repo: GhRepo,
   branch: string,
   limit: number,
+  filters?: { readonly workflow?: string | undefined; readonly event?: string | undefined },
 ): Promise<readonly CiRun[]> {
   const rows = await ghJson(
     host,
@@ -132,6 +142,8 @@ export async function listRuns(
       repo.slug,
       '--branch',
       branch,
+      ...(filters?.workflow === undefined ? [] : ['--workflow', filters.workflow]),
+      ...(filters?.event === undefined ? [] : ['--event', filters.event]),
       '--limit',
       String(limit),
       '--json',

package/src/cmd-ci-spec.ts

@@ -6,10 +6,17 @@ import type { CommandSpec } from './parse';
 /** Log lines kept per failed job. Enough to hold a findings block, short enough to read. */
 export const TAIL_LINES = 40;
 
+/**
+ * The events `--event` accepts, closed: `cmd-ci.ts` refuses every other value against this same
+ * constant, so the summary, the refusal and the `gh` filter can never name different sets.
+ */
+export const CI_EVENTS = ['push', 'pull_request', 'workflow_dispatch'] as const;
+
 export const ciSpec: CommandSpec = {
   name: 'ci',
   summary: 'the workflow runs for this branch, and the findings inside the failed steps log',
-  usage: 'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--json]',
+  usage:
+    'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--workflow <name>] [--event <push|pull_request|workflow_dispatch>] [--json]',
   flags: [
     { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
     { name: 'branch', type: 'string', summary: 'branch to read runs for; this one by default' },
@@ -20,5 +27,15 @@ export const ciSpec: CommandSpec = {
       summary: `log lines kept per failed job (default ${TAIL_LINES})`,
     },
     { name: 'full', type: 'boolean', summary: 'the whole failed-step log, not the tail' },
+    {
+      name: 'workflow',
+      type: 'string',
+      summary: 'only this workflow name or filename (e.g. ci.yml)',
+    },
+    {
+      name: 'event',
+      type: 'string',
+      summary: 'only runs of this event (push, pull_request, workflow_dispatch)',
+    },
   ],
 };

package/src/cmd-ci.ts

@@ -6,11 +6,12 @@
 
 import { UltimateError } from '@ultimat3/core';
 import type { CiLogLine } from './ci-log';
-import { findingsFrom, jobsInLog, parseLogLines, tailOf } from './ci-log';
+import { findingKey, findingsFrom, jobsInLog, parseLogLines, tailOf } from './ci-log';
 import type { CiJob, CiRun } from './ci-runs';
 import { failedLog, isFailed, isRunning, latestPerWorkflow, listRuns, viewRun } from './ci-runs';
-import { ciSpec, TAIL_LINES } from './cmd-ci-spec';
+import { CI_EVENTS, ciSpec, TAIL_LINES } from './cmd-ci-spec';
 import type { CliCommand, CommandContext } from './command';
+import { BadFlagError } from './errors';
 import { parseIntFlag } from './flag-number';
 import { commentBlock } from './foreign-text';
 import type { GhRepo } from './gh-target';
@@ -18,6 +19,7 @@ import { currentBranch, resolveRepo } from './gh-target';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { flagBool, flagString } from './parse';
+import { quoteArg } from './shell-quote';
 
 export { TAIL_LINES } from './cmd-ci-spec';
 
@@ -43,10 +45,22 @@ export const RUN_LOOKBACK = 20;
 
 /** No run to triage. The remedy is a branch that has one, or the id of the run in question. */
 export class CiRunNotFoundError extends UltimateError {
-  constructor(input: { branch: string; repo: string }) {
+  constructor(input: {
+    branch: string;
+    repo: string;
+    workflow?: string | undefined;
+    event?: string | undefined;
+  }) {
+    // A filter beside --branch makes an empty list two different situations — a branch never
+    // pushed, or a filter that matched nothing. Naming what was asked keeps the diagnosis right.
+    const given = [
+      input.workflow !== undefined ? `--workflow ${input.workflow}` : undefined,
+      input.event !== undefined ? `--event ${input.event}` : undefined,
+    ].filter((clause) => clause !== undefined);
+    const matching = given.length > 0 ? ` matching ${given.join(' ')}` : '';
     super({
       code: 'X_CI_RUN_NOT_FOUND',
-      cause: `no workflow run on ${input.repo} for branch "${input.branch}"`,
+      cause: `no workflow run on ${input.repo} for branch "${input.branch}"${matching}`,
       fix: `x ci --branch main --repo ${input.repo} --json`,
     });
   }
@@ -55,11 +69,39 @@ export class CiRunNotFoundError extends UltimateError {
 const RUN_FLAG = { name: 'run', command: 'ci', min: 1, example: 'x ci --run 32484583944 --json' };
 const TAIL_FLAG = { name: 'tail', command: 'ci', min: 1, example: 'x ci --tail 80 --json' };
 
+/**
+ * `--event`, read against the spec's own closed set: a typo is a refusal naming the events that
+ * exist, never an empty run list a reader would take for a red branch.
+ */
+function readEvent(raw: string | undefined): (typeof CI_EVENTS)[number] | undefined {
+  if (raw === undefined) return undefined;
+  const known: readonly string[] = CI_EVENTS;
+  if (known.includes(raw)) return raw as (typeof CI_EVENTS)[number];
+  throw new BadFlagError({
+    flag: 'event',
+    command: 'ci',
+    reason: `${quoteArg(raw)} is not a workflow event — one of ${CI_EVENTS.join(', ')}`,
+    fix: 'x ci --event push --json',
+  });
+}
+
 export const ciCommand: CliCommand = {
   spec: ciSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
-    const repo = await resolveRepo(ctx, 'ci', flagString(ctx.args, 'repo'));
+    // Filters are validated, and crossed with --run, before any subprocess runs: a refusal must
+    // not cost a gh round trip, and a filter beside --run would otherwise be silently ignored.
     const rawRun = flagString(ctx.args, 'run');
+    const workflow = flagString(ctx.args, 'workflow');
+    const event = readEvent(flagString(ctx.args, 'event'));
+    if (rawRun !== undefined && (workflow !== undefined || event !== undefined)) {
+      throw new BadFlagError({
+        flag: workflow !== undefined ? 'workflow' : 'event',
+        command: 'ci',
+        reason: 'filters the run list, and --run names one run already',
+        fix: 'x ci --run <id> --json',
+      });
+    }
+    const repo = await resolveRepo(ctx, 'ci', flagString(ctx.args, 'repo'));
     const rawTail = flagString(ctx.args, 'tail');
     const limit = flagBool(ctx.args, 'full')
       ? Number.POSITIVE_INFINITY
@@ -71,8 +113,11 @@ export const ciCommand: CliCommand = {
       return report(repo, viewed.run.branch, [await inspect(ctx, repo, viewed, limit)]);
     }
     const branch = flagString(ctx.args, 'branch') ?? (await currentBranch(ctx));
-    const runs = latestPerWorkflow(await listRuns(ctx, repo, branch, RUN_LOOKBACK));
-    if (runs.length === 0) throw new CiRunNotFoundError({ branch, repo: repo.slug });
+    const runs = latestPerWorkflow(
+      await listRuns(ctx, repo, branch, RUN_LOOKBACK, { workflow, event }),
+    );
+    if (runs.length === 0)
+      throw new CiRunNotFoundError({ branch, repo: repo.slug, workflow, event });
     const inspected: RunReport[] = [];
     for (const run of runs) {
       // Only a failed run is opened. A green run's jobs are 35 rows saying `success`, and fetching
@@ -128,9 +173,11 @@ async function inspect(
     const pool: readonly CiLogLine[] = own.length > 0 ? own : lines;
     const job = failed.find((candidate) => candidate.name === name);
     for (const finding of findingsFrom(pool)) {
+      // Keep whatever the log carried: a path-style `at` or a non-path step (now on `meta.step`).
+      // Inventing a locator from the CI JOB name would put a non-path in `at` — exactly the seam
+      // this repair closes — so when the log had nothing, the finding reads nothing.
       findings.push({
         ...finding,
-        at: finding.at ?? name,
         // Fenced and tagged: the log is foreign text, and a `fix:` reconstructed from it is the
         // log author's instruction, not this CLI's. `commentBlock` is `x pr review`'s fence.
         fix: commentBlock(`ci-log ${name}`, [finding.fix]).join('\n'),
@@ -152,12 +199,17 @@ async function inspect(
 
 /**
  * The same block can be reached twice — once per job when the log attributes nothing, once per
- * attempt when a run was re-run — and two copies of one finding read as two problems.
+ * attempt when a run was re-run — and two copies of one finding read as two problems. The
+ * inverse is a finding with the same code and cause but a different `at` or `meta.step` (a
+ * `X_COVERAGE_BELOW` routed to two packages, the same gate step failing twice for different
+ * tests): they are NOT the same finding, and the key has to take every locator the gate printed
+ * to tell them apart. `findingKey` is the same formula `ci-log`'s per-log dedupe uses, so a
+ * finding that survives one cannot be silently merged by the other.
  */
 function dedupe(findings: readonly Finding[]): readonly Finding[] {
   const seen = new Set<string>();
   return findings.filter((finding) => {
-    const key = `${finding.code} ${finding.cause}`;
+    const key = findingKey(finding);
     if (seen.has(key)) return false;
     seen.add(key);
     return true;
@@ -241,6 +293,7 @@ function runJson(entry: RunReport): JsonValue {
     title: entry.run.title,
     url: entry.run.url,
     createdAt: entry.run.createdAt,
+    headSha: entry.run.headSha,
     // Absent rather than empty on a run that was never opened: `jobs: []` on a green run would
     // claim the run has no jobs, which is a different statement from "nobody asked".
     ...(entry.jobs === undefined

package/src/output.ts

@@ -21,7 +21,12 @@ export interface Finding {
   readonly cause: string;
   readonly fix: string;
   readonly docs?: string;
-  /** Optional locator: a file, route, or table the finding is about. */
+  /**
+   * Optional locator: a path an agent can OPEN — a source file (its path from the repo root) or
+   * a table. A gate step name, a route URL, or any other identifier that is not a file is NOT
+   * here: it belongs on `meta` (e.g. `meta.step`), and the renderer prints it in the head where
+   * `ci-log` can recover it. Set iff the finding is about a file the author can edit.
+   */
   readonly at?: string;
   /**
    * Where the finding's TEXT came from, when not from this process. `'ci-log'` is `x ci` reading
@@ -172,7 +177,18 @@ export function renderFinding(finding: Finding, indent = ''): string {
   // Every field through `singleLine`: this is the format's only renderer for the terminal and CI
   // logs, and a `cause` carrying a newline would print a line a reader takes for a real finding.
   const code = singleLine(finding.code);
-  const head = finding.at === undefined ? code : `${code} (${singleLine(finding.at)})`;
+  // The path-style locator (`at`) keeps its parenthesised form: `CODE (path)`. A non-path locator
+  // — today only `meta.step`, the gate step name — is printed AFTER, bracketed and keyed
+  // (`[step=lint]`), so `ci-log`'s existing `LOCATOR = /\(([^()]+)\)$/` still means `at` and a
+  // matching step regex can recover it without colliding. Either side may be absent; when BOTH
+  // are absent the head is the bare `CODE` it always was.
+  const stepValue =
+    typeof finding.meta === 'object' && finding.meta !== null && !Array.isArray(finding.meta)
+      ? (finding.meta as { readonly [key: string]: JsonValue })['step']
+      : undefined;
+  const stepLabel = typeof stepValue === 'string' ? ` [step=${singleLine(stepValue)}]` : '';
+  const pathLabel = finding.at === undefined ? '' : ` (${singleLine(finding.at)})`;
+  const head = `${code}${pathLabel}${stepLabel}`;
   const lines = [
     `${indent}${head}`,
     `${indent}  cause: ${singleLine(finding.cause)}`,

package/src/serve-retire.ts

@@ -37,8 +37,10 @@ const NOTHING: WorkerRetire = Object.freeze({ adopt: () => undefined, disarm: ()
 
 /**
  * Listen for `RETIRE_SIGNAL` NOW, before the boot: Bun's default for an unhandled SIGUSR2 ends the
- * process, so a `preStop` that lands while the pod still boots must meet this listener, which waits
- * for the worker and then retires it. One retire per process; a second signal joins it.
+ * process — except as PID 1 (a container's ENTRYPOINT), where the kernel DROPS a signal with no
+ * listener, so a `preStop` that lands before this line runs is lost. The chart's preStop therefore
+ * re-sends it every 5 s until PID 1 is gone; this listener waits for the worker and then retires it.
+ * One retire per process; a second signal joins it.
  *
  * Exits rather than holds, decided 2026-10-07: the `preStop` has no channel back but PID 1 itself,
  * so "retired" has to be observable as "PID 1 is gone" — and a pod that has stopped claiming serves

package/src/static-report.ts

@@ -57,7 +57,11 @@ export type SkippedRoute = RouteFacts & {
  * re-exports the name for its own callers.
  */
 export type UnmeasuredRoute = {
-  /** The DECLARED path, as `X_BUDGET_UNMEASURED`'s `at:` spells it, so the two rows join. */
+  /**
+   * The DECLARED path, the way the finding about it spells the route: `X_BUDGET_UNMEASURED`'s
+   * `meta.route` and its `cause`, so the report row and the gate's finding join. NOT its `at:` —
+   * `Finding.at` is the file an agent opens, and the declaring page is what that holds.
+   */
   readonly path: string;
   readonly reason: string;
   /**

package/src/templates/scaffold-helm-templates.ts

@@ -172,7 +172,9 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
   The worker's retire, opt-in: roles.worker.retireSeconds > 0. The preStop sends PID 1 SIGUSR2 —
   the framework's retire: stop claiming, finish every held job however long it takes, abort
   nothing, then drain and exit 0 — and waits until PID 1 is gone, so the SIGTERM that follows finds
-  nothing left to cut off. bun -e, never kill/sleep: bun is the image's ENTRYPOINT (exec form, so it
+  nothing left to cut off. It re-sends the signal every 5 s while it waits: PID 1 has no default
+  signal action, so a preStop that lands before the boot arms the listener is dropped by the kernel
+  (the pod then idles to its grace); a repeat joins the retire in flight. bun -e, never kill/sleep: bun is the image's ENTRYPOINT (exec form, so it
   IS PID 1). The kubelet counts the preStop against the grace period, so retireSeconds is added to
   it and is the longest a retire may take.
   */}}
@@ -183,7 +185,7 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
         command:
           - bun
           - -e
-          - "process.kill(1, 'SIGUSR2'); for (;;) { try { process.kill(1, 0); } catch { break; } await Bun.sleep(1000); }"
+          - "process.kill(1, 'SIGUSR2'); for (let n = 1; ; n++) { try { process.kill(1, n % 5 === 0 ? 'SIGUSR2' : 0); } catch { break; } await Bun.sleep(1000); }"
   {{- end }}
   {{- end }}
   resources: {{- toYaml $cfg.resources | nindent 4 }}

package/src/verify-merge.ts

@@ -128,8 +128,13 @@ export function parsePart(file: string, text: string, command: string = GATE_COM
   };
 }
 
-/** A gap finding, with a fix spelled for the entry that raised it. */
-type Gap = (cause: string, at?: string) => Finding;
+/**
+ * A gap finding, with a fix spelled for the entry that raised it. The second positional is the
+ * gate `step` name the merge is naming — matching `X_VERIFY_STEP_TIMEOUT`'s precedent at
+ * `verify-stalled.ts:180-197`, where a timeout finding carries the step name in `meta.step`,
+ * never in `at` (which is, repo-wide, a path an agent can open — `output.ts:24-25`).
+ */
+type Gap = (cause: string, step: string, at?: string) => Finding;
 
 /**
  * The gap kinds a merge can find. `present` is a document that arrived and disagrees with the
@@ -149,13 +154,17 @@ const NEVER_ARRIVED =
 const gapsFor = (command: string): Gaps => {
   const finding =
     (fix: string): Gap =>
-    (cause, at) => ({
-      code: 'X_VERIFY_MERGE_INCOMPLETE',
-      cause,
-      fix,
-      docs: ERROR_DOCS_URL,
-      ...(at === undefined ? {} : { at }),
-    });
+    (cause, step, at) => {
+      const meta: { readonly step: string } = { step };
+      return {
+        code: 'X_VERIFY_MERGE_INCOMPLETE',
+        cause,
+        fix,
+        docs: ERROR_DOCS_URL,
+        ...(at === undefined ? {} : { at }),
+        meta,
+      };
+    };
   return {
     present: finding(
       `${command} merge parts/*.json --json   # after every CI job uploaded its part`,
@@ -354,7 +363,12 @@ export function mergeParts(
     part.steps
       .filter((step) => !declared.includes(step.name))
       .map((step) =>
-        kinds.present(`${part.file} reports "${step.name}", which x verify does not run`),
+        // The unknown step's own NAME rides on `meta.step` — it is the only locator here,
+        // never a path. `part.file` is already in the cause.
+        kinds.present(
+          `${part.file} reports "${step.name}", which x verify does not run`,
+          step.name,
+        ),
       ),
   );
   const steps = declared.map((name) =>