@ultimat3/cli 7.0.0 → 8.0.0

package/src/drift.ts

@@ -11,7 +11,9 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { describeEntities } from '@ultimat3/entity';
 import { countDeclaredEntities } from './app-entities';
+import { loadApp } from './app-load';
 // One declaration of where migrations live, and it belongs to the module that reads them —
 // `x db migrate` and this sidecar must never disagree about the directory they share.
 import { hashFileName, MIGRATIONS_DIR } from './migrations';
@@ -20,7 +22,48 @@ import type { Finding } from './output';
 export const DB_PACKAGE = join('packages', 'db');
 const SCHEMA_GLOB = 'packages/db/src/**/*.ts';
 
-/** Content hash of the whole schema, order-independent per file path. */
+/**
+ * Canonical JSON: object keys sorted, arrays in their own order. The registry's description is a
+ * BUILD INPUT committed to disk as a hash, so a field reordered inside `describe()` upstream would
+ * otherwise move every app's hash and report drift over a framework upgrade nobody made.
+ */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
+      a < b ? -1 : a > b ? 1 : 0,
+    );
+    return `{${entries.map(([key, held]) => `${JSON.stringify(key)}:${canonicalJson(held)}`).join(',')}}`;
+  }
+  // `undefined` has no JSON form and an optional field left unset must hash as absent, not throw.
+  return JSON.stringify(value) ?? 'null';
+}
+
+/**
+ * What the app's entities declare, as the registry describes them — the half `SCHEMA_GLOB` cannot
+ * see. `x new` puts an entity at `apps/web/app/<feature>/entity.ts` and `packages/db/src/schema.ts`
+ * merely re-exports it, so a column added there moved NO byte the glob reads: three generated
+ * entities and one migration reported clean, with every `.hash` sidecar identical. The registry is
+ * the same fact `x db gen` diffs (`describeEntities()`), so the check and the generator now read
+ * one schema instead of two.
+ *
+ * `loadApp` is what fills that registry, and it is called on every path rather than only where the
+ * caller happens to have loaded already: a hash computed against an EMPTY registry would differ
+ * from the one `x db gen` recorded with the app loaded, and every app would read as drifted.
+ * A module that will not import leaves the registry SHORT rather than raising — the stance
+ * `countDeclaredEntities` already documents — so `x doctor` still answers on the app it diagnoses.
+ */
+async function declaredSchemaJson(root: string): Promise<string> {
+  await loadApp(root);
+  return canonicalJson(describeEntities());
+}
+
+/**
+ * Content hash of the whole schema: the entity registry first, then every non-test file under
+ * `packages/db/src`, order-independent per file path. Both halves, because they answer different
+ * questions — the registry is what reaches the database, and the glob is what catches a seed or a
+ * helper moving under it (which is what `reconcileSchemaHash` exists to re-record).
+ */
 export async function schemaHash(root: string): Promise<string> {
   const glob = new Bun.Glob(SCHEMA_GLOB);
   const paths: string[] = [];
@@ -29,6 +72,7 @@ export async function schemaHash(root: string): Promise<string> {
   }
   paths.sort();
   const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(await declaredSchemaJson(root));
   for (const path of paths) {
     hasher.update(path);
     hasher.update(await Bun.file(join(root, path)).text());
@@ -77,9 +121,10 @@ export interface HashReconciliation {
 }
 
 /**
- * Re-record the sidecar for a migration that is already the right one. `SCHEMA_GLOB` covers every
- * non-test file under `packages/db/src`, not only the ones that imply DDL, so editing a seed or a
- * helper moves the hash with no diff behind it — and `X_DB_DRIFT`'s `fix:` has to have somewhere to
+ * Re-record the sidecar for a migration that is already the right one. Neither half of the hash is
+ * DDL-only — `SCHEMA_GLOB` covers every non-test file under `packages/db/src`, and the registry
+ * carries invariants and tags a diff can leave empty — so an edit can move the hash with no
+ * statement behind it, and `X_DB_DRIFT`'s `fix:` has to have somewhere to
  * land or the instruction is unfollowable. The caller owes the proof that the DDL genuinely did not
  * move (`db-generate.ts` reaches this only on an empty diff off a fully loaded registry); this
  * function decides only whether a write is needed.
@@ -107,9 +152,9 @@ export type DeclaredEntityCount = () => Promise<number>;
  * Empty result = no drift. A missing db package is not drift (an app may have no database yet);
  * a schema with no migration at all is — *provided* the app declares an entity for one to record.
  *
- * The entity count is read lazily and ONLY in that first branch, so an app past its first migration
- * pays nothing for it: every other path answers from file hashes alone, with no app load and no
- * database, which is what lets the gate run this in a CI with neither.
+ * The entity count is read lazily and ONLY in that first branch; the hash itself loads the app on
+ * every path, because the registry is half of what it covers. Still no database anywhere here,
+ * which is what lets the gate run this in a CI with nothing listening.
  */
 export async function checkSourceDrift(
   root: string,

package/src/error-codes.ts

@@ -56,6 +56,10 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_ROLE_UNKNOWN',
   'X_PORT_INVALID',
   'X_DEV_ALREADY_RUNNING',
+  // The OTHER thing the preflight can find, and it was reported as the one above: an unreadable
+  // lock this process could not remove made `DevAlreadyRunningError` name THIS pid as the holder,
+  // so the remedy printed was `kill <self>` — unrunnable, and a cause that was simply untrue.
+  'X_DEV_LOCK_UNREADABLE',
   // The boot's own consistency check. `startServices` captures the drivers it built, and
   // `loadApp` runs AFTER it — so an app module calling `setJobDriver(theirs)` moved the ambient
   // slot and left the captured object alone: every `handle.enqueue()` went to their queue while
@@ -177,6 +181,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ROLE_UNKNOWN: 'ROLE names something that is not a role',
   X_PORT_INVALID: 'PORT is not a TCP port number',
   X_DEV_ALREADY_RUNNING: 'another x dev already owns this checkout',
+  X_DEV_LOCK_UNREADABLE: 'the dev lock file cannot be read or removed',
   X_RUNTIME_DRIVER_SPLIT: 'the ambient driver is not the one this process serves',
   X_GENERATE_CONFLICT: 'a generator would overwrite a file',
   X_PORT_IN_USE: 'the dev port is taken',

package/src/framework-scope.ts

@@ -4,9 +4,10 @@
 // directory or they describe different builds.
 
 // `node:fs`/`node:path` because Bun ships neither: `dirname` walks a resolved module up to the
-// directory that owns it, and `existsSync` is what says which directory that is.
+// directory that owns it, `basename` names the two segments the store layout is recognised by,
+// and `existsSync` is what says which directory is really there.
 import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 
 /**
  * Deep enough for `src/index.ts` and for any entry an `exports` map could point at, shallow enough
@@ -14,6 +15,45 @@ import { dirname, join } from 'node:path';
  */
 const MAX_DEPTH = 6;
 
+/** The two segments Bun's isolated layout is recognised by: `node_modules/.bun/<pkg>@<version>/`. */
+const STORE_DIR = '.bun';
+const NODE_MODULES = 'node_modules';
+
+/**
+ * `node_modules/.bun/@ultimat3+core@7.0.0/node_modules/@ultimat3` → `node_modules/@ultimat3`.
+ *
+ * Bun's **isolated** layout gives every package its own store entry, and a store entry's scope
+ * directory holds exactly the one package it was created for. `Bun.resolveSync` follows the
+ * install's symlink into that store, so walking up from the resolved entry lands there rather
+ * than in the tree an app actually installed: measured on a fixture install, `x docs` saw
+ * **1** of 6 packages, and `x errors explain` answered *"nothing in the installed framework raises
+ * X_…"* — with `ok: true` — for 400 of 405 codes. A confident wrong answer, from a walk that had
+ * never looked at the app's own `node_modules`.
+ *
+ * The store is recognised by its own shape and never by an app root handed in from outside: the
+ * two callers here are a module-scope memo (`error-fixes.ts`) and a command that may run under
+ * `--cwd`, so a cwd-derived root would be wrong for one of them and absent for the other.
+ *
+ * `undefined` — leaving the caller on the resolved answer — whenever this is not a store path or
+ * the sibling scope directory is not there. A hoisted install already resolves to
+ * `node_modules/@ultimat3/core` and a workspace checkout to `packages/core`, and neither has a
+ * `.bun` above it.
+ */
+function installedScopeFor(storeScope: string): string | undefined {
+  const scopeName = basename(storeScope);
+  let dir = storeScope;
+  for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    if (basename(dir) === STORE_DIR && basename(parent) === NODE_MODULES) {
+      const candidate = join(parent, scopeName);
+      return existsSync(candidate) ? candidate : undefined;
+    }
+    dir = parent;
+  }
+  return undefined;
+}
+
 /**
  * Resolved from the CLI's own dependency on `@ultimat3/core` rather than from the user's cwd:
  * these are the packages this `x` would actually run. Resolution follows the symlink, so a
@@ -29,18 +69,30 @@ const MAX_DEPTH = 6;
  * framework raises the code. Walking up from the entry to the directory that owns its
  * `package.json` depends on nothing but the entry that is already imported.
  *
+ * Following the symlink is also what makes the last step necessary rather than optional: under
+ * Bun's isolated layout the entry resolves *into the store*, whose scope directory holds one
+ * package. `installedScopeFor` is the correction, and it is a shape test on the path — never a
+ * `readdir` of the resolved package's parent, which is the read that reported one package as the
+ * whole framework.
+ *
+ * `resolveFrom` exists so a test can point this at a fixture install; nothing passes it in
+ * production, where the only defensible base is this module's own directory.
+ *
  * `undefined` means the CLI cannot see its own dependency, which is a broken install and not
  * merely an undocumented one; every caller reports that rather than answering emptily.
  */
-export function frameworkScopeDir(): string | undefined {
+export function frameworkScopeDir(resolveFrom: string = import.meta.dir): string | undefined {
   let dir: string;
   try {
-    dir = dirname(Bun.resolveSync('@ultimat3/core', import.meta.dir));
+    dir = dirname(Bun.resolveSync('@ultimat3/core', resolveFrom));
   } catch {
     return undefined;
   }
   for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
-    if (existsSync(join(dir, 'package.json'))) return dirname(dir);
+    if (existsSync(join(dir, 'package.json'))) {
+      const scope = dirname(dir);
+      return installedScopeFor(scope) ?? scope;
+    }
     const parent = dirname(dir);
     if (parent === dir) return undefined;
     dir = parent;

package/src/generate-kinds.ts

@@ -2,6 +2,7 @@
 // because "what a generator emits" and "which spelling reaches it" are two jobs — and the file
 // that held both had reached the 500-line ceiling, one generator short of failing its own gate.
 
+import { nearestName } from '@ultimat3/core';
 import { BadFlagError, MissingPositionalError, UnknownCommandError } from './errors';
 import type { Surface } from './templates';
 
@@ -42,13 +43,30 @@ export function assertSurfaceSupported(kind: Generator, surface: Surface, name:
   });
 }
 
+/**
+ * The generator a spelling reaches, or a refusal that leads with the one it is nearest.
+ *
+ * The lead used to be the literal `g resource`, whatever was typed: `x g rout x` — one edit from
+ * `route` — answered `fix: x g resource`, the WRONG PRIMITIVE, and one that refuses in turn
+ * because it carries no `<name>`. `nearestName` is what `parse.ts` already does with a mistyped
+ * command, over this file's own list.
+ *
+ * Two rules hold the fix line to a command that runs. A near miss is completed with that
+ * generator's own `EXAMPLE_NAME`, because `x g route <name>` pasted into a shell is a redirect.
+ * A word near NOTHING gets `x help g` rather than an invented lead — the same rule `parse.test.ts`
+ * pins for a command that resembles nothing, and the reason `nearestName` is never asked about an
+ * ABSENT kind: the empty string is within the cutoff of `job`, so `x g` would "suggest" a
+ * generator nobody typed.
+ */
 export function readKind(raw: string | undefined): Generator {
   const kinds: readonly string[] = GENERATORS;
   if (raw !== undefined && kinds.includes(raw)) return raw as Generator;
+  const near = raw === undefined ? undefined : nearestName(raw, kinds);
+  const suggestion = GENERATORS.find((kind) => kind === near);
   throw new UnknownCommandError({
     path: `g ${raw ?? ''}`.trim(),
     known: GENERATORS,
-    suggestion: 'g resource',
+    suggestion: suggestion === undefined ? 'help g' : `g ${suggestion} ${EXAMPLE_NAME[suggestion]}`,
   });
 }
 

package/src/i18n-registration.ts

@@ -12,6 +12,7 @@ import {
   catalogRegistrationGaps,
   catalogsNeverRegistered,
   catalogUnregistered,
+  pluralVariantsOf,
   registeredLocales,
 } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
@@ -105,9 +106,68 @@ export async function checkRegistration(input: RegistrationInput): Promise<Regis
 }
 
 /**
- * The file half: a key source uses that a locale's catalog does not define. Built here rather than
- * in `cmd-i18n.ts` because `x verify`'s `i18n` step reports the same finding, and a second
- * construction of it is two renderers of one fact waiting to drift.
+ * `⟦key⟧` — `@ultimat3/i18n`'s own loud miss, spelled ONCE for the whole CLI. `x i18n sync <default>`
+ * writes it and the two checks below refuse it, so a second spelling would be a placeholder one
+ * half of this package writes and the other half cannot see.
+ */
+const MISS_OPEN = '\u27E6';
+const MISS_CLOSE = '\u27E7';
+
+/** What `x i18n sync` seeds a key with when there is no catalog above it to copy a value from. */
+export const loudMiss = (key: string): string => `${MISS_OPEN}${key}${MISS_CLOSE}`;
+
+/**
+ * A value that is a placeholder rather than a translation. Any `⟦…⟧`, not just `⟦<this key>⟧`:
+ * an author who renames a key and leaves the old marker behind still ships a placeholder.
+ */
+export const isLoudMiss = (value: string | undefined): boolean =>
+  value?.startsWith(MISS_OPEN) === true && value.endsWith(MISS_CLOSE);
+
+/**
+ * Whether `locale` answers `key` with a placeholder. Every spelling `definesKey` accepts is
+ * checked — `pluralVariantsOf` is `@ultimat3/i18n`'s own list, the same one `auditCatalogs` uses,
+ * so "defined" and "defined with a real string" can never disagree about which entries count.
+ * `some`, not `every`: a plural family with one untranslated category renders `⟦items_many⟧` on
+ * exactly the rows that hit it.
+ */
+const answersWithPlaceholder = (catalog: Catalog, key: string): boolean =>
+  [key, ...pluralVariantsOf(key)].some(
+    (candidate) => Object.hasOwn(catalog, candidate) && isLoudMiss(catalog[candidate]),
+  );
+
+/**
+ * The audit, with every placeholder counted as the missing key it stands in for.
+ *
+ * `auditCatalogs` asks `Object.hasOwn` and nothing else, so a key present with ANY value is not
+ * missing — including `⟦key⟧`, which is the value `x i18n sync <defaultLocale>` writes for every
+ * gap it closes. Without this, following `X_CATALOG_MISSING_KEYS`'s own `fix:` turns the `i18n`
+ * gate step green over strings no human has ever read: issue #249's ending, reached by running the
+ * command the error recommends. The hole predates the seeding — a hand-written `"TODO"` bought the
+ * same green — but one command now writes sixteen of them, so it is a hole with a shortcut to it.
+ *
+ * Applied HERE and not in `auditCatalogs`: `⟦…⟧` is what the CLI writes, and `@ultimat3/i18n`'s
+ * audit answering "is this key defined" is a different question from "is this app shippable".
+ */
+export function withPlaceholdersMissing(
+  report: ExtractReport,
+  catalogs: Readonly<Record<Locale, Catalog>>,
+): ExtractReport {
+  const locales = report.locales.map((audit) => {
+    const catalog = catalogs[audit.locale] ?? {};
+    const known = new Set(audit.missing);
+    const placeheld = report.used.filter(
+      (key) => !known.has(key) && answersWithPlaceholder(catalog, key),
+    );
+    if (placeheld.length === 0) return audit;
+    return { ...audit, missing: [...audit.missing, ...placeheld].sort() };
+  });
+  return { ...report, locales, ok: locales.every((audit) => audit.missing.length === 0) };
+}
+
+/**
+ * The file half: a key source uses that a locale's catalog does not define, or defines with a
+ * placeholder. Built here rather than in `cmd-i18n.ts` because `x verify`'s `i18n` step reports
+ * the same finding, and a second construction of it is two renderers of one fact waiting to drift.
  */
 export function missingKeyFindings(report: ExtractReport): readonly Finding[] {
   return report.locales
@@ -126,5 +186,8 @@ export function missingKeyFindings(report: ExtractReport): readonly Finding[] {
 export async function catalogFindings(root: string): Promise<readonly Finding[]> {
   const { report, catalogs, extraction, ignoreUnused } = await auditApp(root);
   const registration = await checkRegistration({ root, catalogs, extraction, ignoreUnused });
-  return [...missingKeyFindings(report), ...registration.findings];
+  return [
+    ...missingKeyFindings(withPlaceholdersMissing(report, catalogs)),
+    ...registration.findings,
+  ];
 }

package/src/index.ts

@@ -323,4 +323,4 @@ export type { WorkspaceNode, WorkspaceScan } from './workspace-graph';
 // nothing to read. `checkWorkspaceDependencies` stays internal — it is reached through
 // `x verify`, which is the one way a rule is enforced here.
 export { readWorkspaceGraph, scanWorkspaces } from './workspace-graph';
-export { writeLine } from './write-line';
+export { writeErrorLine, writeLine } from './write-line';

package/src/jobs-report.ts

@@ -18,23 +18,20 @@ import {
   inspectJob,
   inspectJobList,
   inspectQueues,
+  isJobState,
+  JOB_STATES,
   retryFromStep,
 } from '@ultimat3/jobs';
 import { BadFlagError, JobUnknownError } from './errors';
 
-/** Mirrors `JobState` from `@ultimat3/jobs`, which exports the type but no runtime list. */
-export const JOB_STATES: readonly JobState[] = [
-  'ready',
-  'delayed',
-  'running',
-  'suspended',
-  'done',
-  'failed',
-  'dead',
-];
-
-const isJobState = (value: string): value is JobState =>
-  (JOB_STATES as readonly string[]).includes(value);
+/**
+ * The queue's own vocabulary, re-exported rather than restated — this file carried a copy of it,
+ * and the copy was one member short. `cancelled` shipped in `@ultimat3/jobs` and never here, so
+ * `x jobs cancel` created a state `x jobs ls --state cancelled` then refused to filter on: two
+ * commands of one CLI disagreeing about what a job can be. Kept on this module's surface because
+ * `index.ts` exports it from here.
+ */
+export { JOB_STATES } from '@ultimat3/jobs';
 
 export function parseStateFlag(value: string | undefined): JobState | undefined {
   if (value === undefined) return undefined;

package/src/mcp-errors.ts

@@ -102,6 +102,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_PORT_IN_USE: 'x dev --port 3001 --json',
   X_DEV_ALREADY_RUNNING:
     'x dev --json   # after stopping the x dev that already owns this checkout',
+  // The path, not `x dev`: the boot has already refused and rerunning it refuses again. The
+  // error's own `fix:` carries the resolved `.x/dev.lock`; this table cannot know the state dir.
+  X_DEV_LOCK_UNREADABLE: 'rm .x/dev.lock   # then: x dev --json',
   // Not `x db status`: there is no such subcommand (`x db` is gen, migrate, reset, studio, branch),
   // so the fix answered a failed step with X_CLI_UNKNOWN_COMMAND. `x doctor` is what reports
   // reachability and drift, and is already this table's answer for X_DB_STUDIO_FAILED.

package/src/messages.ts

@@ -139,6 +139,11 @@ const CATALOG = {
   // the app has a schema no migration records and `x verify`'s drift step says so until it runs.
   'cli.new.done':
     'created {name} — next: cd {name} && bun install && x db gen "initial" && x db migrate && x dev',
+  // The two prose lines of `x new`'s report. The `run: cd … && git init …` line beneath the second
+  // one stays inline in `cmd-new.ts`: it is an instruction to paste verbatim, and a translated
+  // command is a broken one — the same split `Finding.fix` already makes.
+  'cli.new.wrote': '  {count} files in {dir}',
+  'cli.new.noRepository': '  no repository — {problem}',
   'cli.policy.count':
     '{permissions} permission(s), {roles} role(s), {enforced} enforced by a declaration',
   // One row per (declaration, actor) pair, never per role: a permission two declarations enforce
@@ -178,6 +183,9 @@ const CATALOG = {
   'cli.shot.canvasUnreadable': '  canvas   unreadable — {bytes} byte(s), not a decodable image',
   'cli.shot.islands': '  islands  {booted} of {declared} mounted ({strategies})',
   'cli.shot.islandsUnknown': '  islands  not counted — the page answered no probe',
+  // The failure a picture cannot show and a console count cannot see: a rejected mount promise
+  // calls no console method, so the FIRST one is named here rather than left to verdict.json.
+  'cli.shot.islandFailed': '{route}: {failed} island(s) failed to mount — {island}: {message}',
   'cli.shot.network': '  network  {requests} request(s), {refused} refused, {dropped} dropped',
   'cli.shot.console': '  console  {level}: {text}',
   'cli.shot.threw': '{route}: {thrown} uncaught exception(s) — {first}',
@@ -228,6 +236,10 @@ const CATALOG = {
   'cli.test.sampled': 'sampled {kept} of {total} {type} file(s)',
   'cli.test.type.fail': '{type} — {failed} of {workers} shard(s) failed',
   'cli.test.type.pass': '{type} — {files} test file(s) on {workers} worker(s) passed in {ms}ms',
+  // The banner a `--only` run carries, in front of whichever summary above it renders. Rendered
+  // output, so it lives here — `data.notAGateRun` is the machine marker, and a reader testing for
+  // one narrowed run reads that boolean rather than substring-matching this line.
+  'cli.verify.notAGateRun': 'NOT A GATE RUN — {summary}',
   'cli.verify.pass': 'all {count} steps passed in {ms}ms',
   'cli.verify.fail': '{failed} of {count} steps failed',
   // A skipped step is not a passed one, so the two counts never share a sentence — and the skipped

package/src/output.ts

@@ -52,6 +52,17 @@ export interface CommandResult {
    * could show is how the two drift.
    */
   readonly hold?: () => Promise<void>;
+  /**
+   * Which fd this result is written to. `stdout` for every command, absent included — and
+   * `stderr` for the one case where fd 1 is not the command's to write on: `x mcp serve
+   * --transport stdio`, whose stdout carries JSON-RPC frames, and where the `✓ mcp stdio serving
+   * 13 tools` line printed after the loop exits is a malformed frame to whatever is reading.
+   *
+   * Behaviour, not a fact, exactly like `hold` above — so NEITHER renderer carries it. It says
+   * where a rendered line goes, and a payload that also claimed it would be a second answer to a
+   * question `dispatch` has already answered by choosing the sink.
+   */
+  readonly stream?: 'stdout' | 'stderr';
 }
 
 export interface UltimateErrorShape {
@@ -158,13 +169,22 @@ export function renderHuman(result: CommandResult, verbose = false): string {
   for (const step of result.steps ?? []) {
     out.push(`  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms${width(step)}`);
     for (const finding of step.findings) out.push(renderFinding(finding, '      '));
+    // NOT escaped, and that is the one exception: `output` is this process's own captured
+    // subprocess stdout — `bun test`'s colour is the reason a human reads it at all, and it is
+    // already split on its real newlines rather than carrying them inside one entry.
     if (step.output !== undefined && step.output.length > 0 && (verbose || !step.ok)) {
       for (const line of step.output.trimEnd().split('\n')) out.push(`      | ${line}`);
     }
   }
-  for (const line of result.lines ?? []) out.push(line);
+  // Every free-text line through the SAME `singleLine` the 3-line format runs, because this is
+  // where text the CLI did not write reaches fd 1: a GitHub review body (`x pr`), a CI log tail
+  // (`x ci`), a page's own console (`x shot`). It was emitted verbatim, so an ESC byte in a PR
+  // comment retitled the window and cleared the screen, and a newline in one entry printed a
+  // second line a reader — or the agent this command exists for — takes for the renderer's own.
+  for (const line of result.lines ?? []) out.push(singleLine(line));
   for (const finding of result.findings ?? []) out.push(renderFinding(finding, '  '));
-  out.push(`${result.ok ? '✓' : '✗'} ${result.summary}`);
+  // The summary is foreign too: `cli.shot.threw` interpolates a page's own error message.
+  out.push(`${result.ok ? '✓' : '✗'} ${singleLine(result.summary)}`);
   return out.join('\n');
 }