@vzn/vx 0.0.637 → 0.0.639

package/src/cache/run-history.ts

@@ -13,11 +13,11 @@ const INSERT_RUNS = `
         started_at, ended_at,
         run_id, cpu_ms, peak_rss_bytes, wallclock_start_ns, wallclock_end_ns,
         cache_hit, attempts, cached,
-        blocked_by, timed_out, sandbox_violations, not_ready, restored
+        blocked_by, timed_out, sandbox_violations, not_ready, restored, remote_error
       )
       VALUES `
-/** One `runs` row's placeholders: the 22 columns `bindRun` fills. */
-const RUN_TUPLE = `(${Array(22).fill('?').join(', ')})`
+/** One `runs` row's placeholders: the 23 columns `bindRun` fills. */
+const RUN_TUPLE = `(${Array(23).fill('?').join(', ')})`
 
 /** An INSERT of `n` `runs` rows. */
 function insertRunsSql(n: number): string {
@@ -25,7 +25,7 @@ function insertRunsSql(n: number): string {
 }
 
 /**
- * Rows per INSERT: 40 × 22 variables stays under 999, the oldest default
+ * Rows per INSERT: 40 × 23 variables stays under 999, the oldest default
  * ceiling. A statement per row was 8.7 ms of 1,000 rows, 40 at a time 6.4
  * (2026-10-03).
  */
@@ -34,6 +34,31 @@ const RUNS_PER_INSERT = 40
 /** Rows per `task_durations` INSERT: 6 variables each, under 999. */
 const DURATIONS_PER_INSERT = 160
 
+/** Rows per `task_outcomes` INSERT: 6 variables each, under 999. */
+const OUTCOMES_PER_INSERT = 160
+
+/**
+ * Whether a run says anything of its key, so the flaky record may keep it:
+ * keyed, cached, and not run behind a failure (its bytes were not the key's).
+ */
+const keyed = (r: RunRecord): boolean =>
+  r.hash !== undefined && r.hash !== '' && r.cached !== false && r.blockedBy == null
+
+/** A hit, as the orchestrator marks one (`isCacheHit`, run-records.ts). */
+const isHit = (r: RunRecord): boolean => r.cacheHit === true
+
+/**
+ * Of a JSON array of hashes, those the record holds a pass of: one index
+ * probe each (0.6 ms for 1,000; a join reading every row of each key was
+ * 5.7 ms at 20 runs of history). A hit's row is kept only when its key has
+ * none: a hit replays a pass, and the first is what a later failure
+ * relapses from (an entry adopted from its artifact, or older than the
+ * record, has no executed row). By hash alone, as the entry it replays is.
+ */
+const PASSED_HASHES = `
+      SELECT j.value AS hash FROM json_each(?) AS j
+      WHERE EXISTS (SELECT 1 FROM task_outcomes AS o WHERE o.hash = j.value AND o.status <> 'failed')`
+
 /** A local run's `task_durations.source`: its branch, `''` when it had none. */
 export const branchSource = (branch: string | null): string => `branch:${branch ?? ''}`
 
@@ -55,9 +80,9 @@ export class RunHistory {
         up_to_date_count, restored_local_count, restored_remote_count,
         exit_ok,
         commit_sha, branch, dirty, ci, ci_provider,
-        host, os, arch, vx_version, tags
+        host, os, arch, vx_version
       )
-      VALUES (?, ?, ?, ?, ?, ?,  ?, ?, ?,  ?, ?, ?, ?, ?,  ?, ?, ?,  ?,  ?, ?, ?, ?, ?,  ?, ?, ?, ?, ?)
+      VALUES (?, ?, ?, ?, ?, ?,  ?, ?, ?,  ?, ?, ?, ?, ?,  ?, ?, ?,  ?,  ?, ?, ?, ?, ?,  ?, ?, ?, ?)
       ON CONFLICT(run_id) DO NOTHING
     `,
     )
@@ -75,6 +100,7 @@ export class RunHistory {
       .transaction(() => {
         this.insertRuns(runs)
         this.insertDurations(runs, branchSource(null), null)
+        this.insertOutcomes(runs)
       })
       .immediate()
   }
@@ -94,6 +120,45 @@ export class RunHistory {
     }
   }
 
+  /**
+   * The flaky record's rows: every executed outcome, and a key's first hit,
+   * in the order given (a batch may hold one key's history).
+   */
+  private insertOutcomes(runs: readonly RunRecord[]): void {
+    const rows = runs.filter(
+      (r) => keyed(r) && (isHit(r) || r.status === 'success' || r.status === 'failed'),
+    )
+    const hits = rows.filter(isHit)
+    let passed: Set<string> | undefined
+    if (hits.length > 0) {
+      const found = this.db.query(PASSED_HASHES).all(JSON.stringify(hits.map((r) => r.hash))) as {
+        hash: string
+      }[]
+      passed = new Set(found.map((f) => f.hash))
+    }
+    const kept: RunRecord[] = []
+    for (const r of rows) {
+      if (isHit(r)) {
+        if (passed!.has(r.hash!)) continue
+        passed!.add(r.hash!)
+      } else if (r.status === 'success') {
+        passed?.add(r.hash!)
+      }
+      kept.push(r)
+    }
+    for (let i = 0; i < kept.length; i += OUTCOMES_PER_INSERT) {
+      const block = kept.slice(i, i + OUTCOMES_PER_INSERT)
+      const params: SQLQueryBindings[] = []
+      for (const r of block)
+        params.push(r.project, r.task, r.hash!, r.status, r.attempts ?? null, r.startedAt)
+      this.db
+        .query(
+          `INSERT INTO task_outcomes(project, task, hash, status, attempts, recorded_at) VALUES ${Array(block.length).fill('(?, ?, ?, ?, ?, ?)').join(', ')}`,
+        )
+        .run(...params)
+    }
+  }
+
   /** `runs` as few INSERTs; each distinct forward-args list digested once. */
   private insertRuns(runs: readonly RunRecord[]): void {
     const digests = new Map<string, string>()
@@ -134,6 +199,23 @@ export class RunHistory {
           branchSource(bundle.invocation.branch),
           bundle.invocation.commitSha,
         )
+        this.insertOutcomes(bundle.runs)
+      })
+      .immediate()
+  }
+
+  /**
+   * The remote failures a run's uploads met after its rows were written:
+   * the uploads drain once the history is in (run.ts).
+   */
+  recordRemoteErrors(
+    runId: string,
+    errors: readonly (readonly [hash: string, text: string])[],
+  ): void {
+    const update = this.db.prepare('UPDATE runs SET remote_error = ? WHERE run_id = ? AND hash = ?')
+    this.db
+      .transaction(() => {
+        for (const [hash, text] of errors) update.run(text, runId, hash)
       })
       .immediate()
   }
@@ -149,10 +231,12 @@ export class RunHistory {
     this.db.prepare('DELETE FROM runs WHERE started_at < ?').run(cutoff)
     this.db.prepare('DELETE FROM invocations WHERE started_at < ?').run(cutoff)
     this.db.prepare('DELETE FROM task_durations WHERE recorded_at < ?').run(cutoff)
+    this.db.prepare('DELETE FROM task_outcomes WHERE recorded_at < ?').run(cutoff)
+    this.db.prepare('DELETE FROM plugin_blobs WHERE at < ?').run(cutoff)
   }
 }
 
-/** Bind a RunRecord to one `RUN_TUPLE`'s 22 positional parameters. */
+/** Bind a RunRecord to one `RUN_TUPLE`'s 23 positional parameters. */
 function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBindings[] {
   return [
     // The ONE place the no-key sentinel is applied, so the column's
@@ -182,6 +266,7 @@ function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBi
     run.sandboxViolations ?? null,
     run.notReady ?? null,
     run.restored === undefined ? null : run.restored ? 1 : 0,
+    run.remoteError ?? null,
   ]
 }
 
@@ -219,6 +304,5 @@ function bindInvocation(inv: InvocationRecord): SQLQueryBindings[] {
     inv.os,
     inv.arch,
     inv.vxVersion,
-    inv.tags,
   ]
 }

package/src/cache/run-store.ts

@@ -0,0 +1,77 @@
+// What core keeps of a run that writes a remote (owner 2026-10-15): a failed
+// task's log and the files its outputs left, an uncached task's log. Names
+// come from the run id and task (`run/<id>/<task>/log`); each key is derived
+// in a namespace no task key or plugin entry shares. Remote only: locally
+// `vx last --log` and the working tree already hold them. No size cap (M:
+// the cache is free). Plugins read them by name (`ctx.cache.getRun`).
+
+import { xxh3hex } from '../util/index.js'
+import type { ResolvedRemote } from './remote-lane.js'
+import { scopedKey } from './scoped-cache.js'
+import { tarPackInto, tarSize } from './tar-stream.js'
+
+/** The name core stores a task's `part` of run `runId` under. */
+export function runEntryName(runId: string, taskId: string, part: 'log' | 'outputs'): string {
+  return `run/${runId}/${taskId}/${part}`
+}
+
+const runKey = (name: string): string => xxh3hex(`vx-run\0${name}`)
+
+/** The keys `name` is read under: the default, then the scope's, as tasks read. */
+export function runReadKeys(name: string, scope: string | undefined): string[] {
+  const key = runKey(name)
+  return scope === undefined ? [key] : [key, scopedKey(scope, key)]
+}
+
+/** Whether some remote takes this run's writes: only then does core keep run bytes. */
+export function writesRunStore(remotes: readonly ResolvedRemote[]): boolean {
+  return remotes.some((r) => r.write)
+}
+
+/**
+ * Store `bytes` under `name` in every remote the policy writes. An entry is
+ * written once; a remote's failure leaves the others theirs, silently: what
+ * a run keeps here is a record, never its verdict.
+ */
+export async function putRunEntry(
+  remotes: readonly ResolvedRemote[],
+  scope: string | undefined,
+  name: string,
+  bytes: Uint8Array,
+): Promise<boolean> {
+  const key = scope === undefined ? runKey(name) : scopedKey(scope, runKey(name))
+  let kept = false
+  for (const { remote, write } of remotes) {
+    if (!write) continue
+    try {
+      await remote.put(key, new Blob([bytes]), { durationMs: 0 })
+      kept = true
+    } catch {
+      // the other remotes still keep it
+    }
+  }
+  return kept
+}
+
+/**
+ * The files at `paths` (workspace-relative) as a plain ustar archive, names
+ * as given, so any `tar` reads it; null when none is left to read.
+ */
+export async function packRunOutputs(
+  workspaceRoot: string,
+  paths: readonly string[],
+): Promise<Uint8Array | null> {
+  const inputs: { name: string; size: number; body: Uint8Array }[] = []
+  for (const name of paths) {
+    try {
+      const body = await Bun.file(`${workspaceRoot}/${name}`).bytes()
+      inputs.push({ name, size: body.byteLength, body })
+    } catch {
+      // gone since the glob: nothing to keep
+    }
+  }
+  if (inputs.length === 0) return null
+  const out = new Uint8Array(tarSize(inputs))
+  tarPackInto(inputs, out)
+  return out
+}

package/src/cache/schema.ts

@@ -23,7 +23,8 @@ export function lazyStatement(db: Database, sql: string): ReturnType<Database['p
 /**
  * Create every table. `store` names the schema holding the ENTRY tables
  * (`entries`, `entry_stdout`, `output_files`, `entry_inputs`, `store_meta`)
- * and the task timings (`task_durations`):
+ * the task timings (`task_durations`), the flaky record (`task_outcomes`),
+ * the blob sizes (`blob_sizes`) and the plugins' blobs (`plugin_blobs`):
  * `main` when one `cache.db` holds everything (a `cacheDir`), `store` when
  * they live in the shared store attached beside it (v32). The rest is the
  * workspace's own: its history, its memos, and what its disk looked like
@@ -97,7 +98,10 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       not_ready           TEXT,
       -- v31: on a hit, 1 when outputs were restored, 0 when the disk
       -- already matched (up-to-date); NULL on every other status.
-      restored            INTEGER
+      restored            INTEGER,
+      -- v40: each remote read or write of the key that failed, as
+      -- 'upload: <message>', '; '-joined; NULL when none did.
+      remote_error        TEXT
     );
     -- Two whole-table indexes only, and both APPEND: every row of a run carries the
     -- same run_id and a started_at newer than everything before it, so
@@ -114,17 +118,14 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     --   runs_ended (2026-09-09) served only the retention DELETE, which
     --     prunes on started_at now (a row ends after it starts, so the
     --     30-day window moves by at most one task's duration).
+    --   runs_failed (v38) served the flakiness probe, which reads the
+    --     store's task_outcomes now.
     DROP INDEX IF EXISTS main.runs_hash;
     DROP INDEX IF EXISTS main.runs_project;
     DROP INDEX IF EXISTS main.runs_ended;
+    DROP INDEX IF EXISTS main.runs_failed;
     CREATE INDEX IF NOT EXISTS main.runs_started_at ON runs(started_at);
     CREATE INDEX IF NOT EXISTS main.runs_run_id     ON runs(run_id);
-    -- The one keyed index, PARTIAL over failed rows: a green run's
-    -- inserts only evaluate its predicate, so the append-only cost above
-    -- holds, and the flakiness probe after a miss (failure-mode.ts,
-    -- "did this key ever fail?") reads a handful of leaves instead of
-    -- scanning the table (2026-09-10: 10–95 ms at 170k rows without it).
-    CREATE INDEX IF NOT EXISTS main.runs_failed ON runs(hash) WHERE status = 'failed';
     -- Per-file (mtime, size, content_hash) cache. Lets Cache.key()
     -- skip the content-hash on inputs whose stat hasn't changed
     -- since the last run. Pure performance optimization; the stored
@@ -142,8 +143,9 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     -- The size of each index blob the enumeration checked against the
     -- worktree size git recorded (A-60). Fixed for its OID, so a warm
     -- run asks git for none; swept with file_hashes by seen_at, the
-    -- time the row was written.
-    CREATE TABLE IF NOT EXISTS main.blob_sizes (
+    -- time the row was written. v38: in the store, so a worktree reads
+    -- what another learned (owner, 2026-10-14).
+    CREATE TABLE IF NOT EXISTS ${store}.blob_sizes (
       oid     TEXT PRIMARY KEY,
       size    INTEGER NOT NULL,
       seen_at INTEGER NOT NULL
@@ -200,7 +202,7 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     );
     -- v22 (Tier 3): one header row per vx-run invocation. The runs
     -- table is per-task; this is the per-invocation record that
-    -- carries git/CI/host context, the command, tags, and run-level
+    -- carries git/CI/host context, the command, and run-level
     -- counts so the dashboard never reconstructs a header with a
     -- lossy GROUP BY over runs.
     CREATE TABLE IF NOT EXISTS main.invocations (
@@ -231,8 +233,7 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       host              TEXT,
       os                TEXT,
       arch              TEXT,
-      vx_version        TEXT NOT NULL,
-      tags              TEXT NOT NULL DEFAULT '{}'
+      vx_version        TEXT NOT NULL
     );
     CREATE INDEX IF NOT EXISTS main.invocations_started ON invocations(started_at);
     CREATE INDEX IF NOT EXISTS main.invocations_branch  ON invocations(branch);
@@ -275,6 +276,36 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     );
     CREATE INDEX IF NOT EXISTS ${store}.task_durations_task
       ON task_durations(project, task, source, id);
+    -- v37: a 'remote' row is a default-branch commit's timing a plugin
+    -- imported (\`sha\` that commit): one per task, so a repeat import is a
+    -- no-op under INSERT OR IGNORE.
+    CREATE UNIQUE INDEX IF NOT EXISTS ${store}.task_durations_remote
+      ON task_durations(sha, project, task) WHERE source = 'remote';
+    -- v38: the flaky record (orchestrator/failure-mode.ts): each keyed,
+    -- cached, unblocked outcome that observed its key, shared by every
+    -- worktree so a key that passed in one and failed in another is flaky
+    -- in both (owner, 2026-10-14). Every executed success or failure, and
+    -- a key's first hit (run-history.ts): a later hit replays a pass the
+    -- record holds, so a warm run on keys that passed writes no row.
+    -- Append-only, ordered by id, pruned by age with the run history.
+    CREATE TABLE IF NOT EXISTS ${store}.task_outcomes (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      project     TEXT NOT NULL,
+      task        TEXT NOT NULL,
+      hash        TEXT NOT NULL,
+      status      TEXT NOT NULL,
+      attempts    INTEGER,
+      recorded_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS ${store}.task_outcomes_hash ON task_outcomes(hash, status);
+    -- v37: what a plugin keeps through \`ctx.cache\` (plugin-cache.ts), by
+    -- its namespaced key. Written once, never updated; pruned by age with
+    -- the run history.
+    CREATE TABLE IF NOT EXISTS ${store}.plugin_blobs (
+      key   TEXT PRIMARY KEY,
+      bytes BLOB NOT NULL,
+      at    INTEGER NOT NULL
+    );
     ${artifactTables(store)}
   `)
 }

package/src/cache/scoped-cache.ts

@@ -16,7 +16,7 @@ import type {
 } from './layer.js'
 
 /** The key a scope stores `hash` under: task-key shaped, 16 hex, so every wire stores it unchanged. */
-function scopedKey(scope: string, hash: string): string {
+export function scopedKey(scope: string, hash: string): string {
   return xxh3hex(`vx-cache-scope\0${scope}\0${hash}`)
 }
 
@@ -33,7 +33,10 @@ export class ScopedCache implements CacheLayer {
   readonly local?: CacheLayer['local']
   readonly hasRemote?: boolean
   readonly drainUploads?: () => Promise<void>
+  readonly stopUploads?: () => void
   readonly remoteHasMany?: (hashes: readonly string[]) => Promise<Set<string> | null>
+  /** A scoped run saves under the scope's key, so that is the key asked. */
+  readonly probeBeforeUpload?: (hashes: Promise<readonly string[]>) => void
   readonly getMany?: (
     hashes: readonly string[],
     ctx?: (hash: string) => CacheGetContext,
@@ -48,7 +51,11 @@ export class ScopedCache implements CacheLayer {
     if (inner.local !== undefined) this.local = inner.local
     if (inner.hasRemote !== undefined) this.hasRemote = inner.hasRemote
     if (inner.drainUploads !== undefined) this.drainUploads = () => inner.drainUploads!()
+    if (inner.stopUploads !== undefined) this.stopUploads = () => inner.stopUploads!()
     if (inner.remoteHasMany !== undefined) this.remoteHasMany = (h) => this.scopedHasMany(h)
+    if (inner.probeBeforeUpload !== undefined)
+      this.probeBeforeUpload = (h) =>
+        inner.probeBeforeUpload!(h.then((keys) => keys.map((k) => this.own(k))))
     if (inner.getMany !== undefined) this.getMany = (h, ctx) => this.scopedGetMany(h, ctx)
   }
 
@@ -75,6 +82,13 @@ export class ScopedCache implements CacheLayer {
     return out
   }
 
+  /** A task key the store holds under the default key or the scope's. */
+  async localHasMany(hashes: readonly string[]): Promise<Set<string>> {
+    const held = await this.inner.localHasMany?.([...hashes, ...hashes.map((h) => this.own(h))])
+    if (held === undefined) return new Set()
+    return new Set(hashes.filter((h) => held.has(h) || held.has(this.own(h))))
+  }
+
   private async scopedHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
     const scoped = hashes.map((h) => this.own(h))
     const [plain, own] = await Promise.all([
@@ -105,7 +119,13 @@ export class ScopedCache implements CacheLayer {
   }
 
   async get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null> {
-    for (const key of [hash, this.own(hash)]) {
+    // The scope's key first when only it is local: the default key's
+    // remote GET would cost a round-trip for the same inputs.
+    const own = this.own(hash)
+    const keys = (await this.inner.localHasMany?.([hash, own]))?.has(own)
+      ? [own, hash]
+      : [hash, own]
+    for (const key of keys) {
       const entry = await this.inner.get(key, ctx)
       if (entry === null) continue
       this.served.set(hash, key)

package/src/cli/cache.ts

@@ -3,7 +3,15 @@ import { homedir } from 'node:os'
 import path from 'node:path'
 import { Cache, vxCacheEntries } from '../cache/index.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
-import { errorCode, nearest, parseDuration, parseSize, relPosix, treeBytes } from '../util/index.js'
+import {
+  errorCode,
+  nearest,
+  parseDuration,
+  parseSize,
+  relPosix,
+  treeBytes,
+  ui,
+} from '../util/index.js'
 import { acquireRunLock } from '../orchestrator/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import {
@@ -254,15 +262,28 @@ function printPruned(
     )
     return
   }
-  const orphans =
-    result.orphans > 0
-      ? `, ${dry ? 'would reap' : 'reaped'} ${result.orphans} orphaned artifact${result.orphans === 1 ? '' : 's'} (${formatBytes(result.orphanBytes)})`
-      : ''
-  process.stdout.write(
-    `${dry ? 'Would prune' : 'Pruned'} ${result.evicted} entr${result.evicted === 1 ? 'y' : 'ies'} (${formatBytes(result.bytesFreed)}${dry ? '' : ' freed'})${orphans}\n`,
+  const plural = (n: number, one: string, many: string): string => `${n} ${n === 1 ? one : many}`
+  const facts = [
+    ...(result.evicted > 0 ? [plural(result.evicted, 'entry', 'entries')] : []),
+    ...(result.orphans > 0
+      ? [plural(result.orphans, 'orphaned artifact', 'orphaned artifacts')]
+      : []),
+  ]
+  ui.print(
+    'out',
+    freedStatus(dry, result.bytesFreed + result.orphanBytes, facts.length > 0),
+    ...(facts.length > 0 ? [ui.text(facts.join(' · '))] : []),
   )
 }
 
+/** `✓ vx cache clean  freed 1.3 GB`, `› … would free 1.3 GB (dry run)`, or nothing to free. */
+function freedStatus(dry: boolean, bytes: number, any: boolean): ui.Block {
+  if (!any) return ui.status('info', 'vx cache clean', `nothing to free${dry ? ' (dry run)' : ''}`)
+  return dry
+    ? ui.status('info', 'vx cache clean', `would free ${formatBytes(bytes)} (dry run)`)
+    : ui.status('ok', 'vx cache clean', `freed ${formatBytes(bytes)}`)
+}
+
 /** `vx cache clean --format json` with no bound (schemas/cache.json `clear`). */
 export interface ClearResult {
   dryRun: boolean
@@ -341,16 +362,12 @@ async function clear(
   if (parsed.format === 'json') {
     const result: ClearResult = { dryRun: dry, cleared: shown, bytesFreed: bytes }
     process.stdout.write(`${JSON.stringify(result)}\n`)
-  } else if (shown.length === 0) process.stdout.write('Nothing to clear: no cache here\n')
-  else {
-    const scope =
-      parsed.global === true
-        ? "every repository's store and this workspace's run history"
-        : "this repository's store, shared by its checkouts, and this workspace's run history"
-    process.stdout.write(
-      `${dry ? 'Would clear' : 'Cleared'} ${scope} (${formatBytes(bytes)}${dry ? '' : ' freed'}):\n${shown.map((t) => `  ${t}\n`).join('')}`,
+  } else
+    ui.print(
+      'out',
+      freedStatus(dry, bytes, shown.length > 0),
+      ...(shown.length > 0 ? [ui.text(...shown)] : []),
     )
-  }
   return 0
 }
 

package/src/cli/completions.ts

@@ -6,7 +6,7 @@
 // Tab is the wrong price).
 
 import { acceptedFlags, CORE_VERBS, flagHint, seeHelp } from './help.js'
-import { nearest } from '../util/index.js'
+import { nearest, sayNotice } from '../util/index.js'
 
 /** A flag whose value is one of a fixed set; the tests hold each to its parser. */
 export const FLAG_VALUES: Readonly<Record<string, readonly string[]>> = {
@@ -21,8 +21,8 @@ const SHELLS: readonly CompletionShell[] = ['bash', 'zsh', 'fish']
 /**
  * `--help` and every flag the verb accepts. Not every `--flag` its help cut
  * mentions: the cut's prose names other verbs' flags, and `vx watch`
- * completed only `--dry --graph --summarize --profile`, the four its line
- * says it refuses, while `vx show` offered `--run` and `--list`.
+ * completed only the flags its help line says it refuses, while `vx show`
+ * offered `--run` and `--list`.
  */
 export function verbFlags(verb: string): string[] {
   return [...new Set(['--help', ...acceptedFlags(verb)])]
@@ -139,8 +139,10 @@ export async function completionsCmd(
   if (args.length !== 1 || !(SHELLS as readonly string[]).includes(shell ?? '')) {
     const flag = args.find((a) => a.startsWith('-'))
     if (flag !== undefined) {
-      process.stderr.write(
-        `vx completions: unknown flag: ${flag}${flagHint('completions', flag)}${seeHelp('completions')}\n`,
+      sayNotice(
+        'error',
+        'vx completions',
+        `unknown flag: ${flag}${flagHint('completions', flag)}${seeHelp('completions')}`,
       )
       return 1
     }
@@ -148,8 +150,10 @@ export async function completionsCmd(
     // One edit: shell names are three or four letters, so two edits took
     // `tcsh` to `bash`, a different shell.
     const best = one ? nearest(shell, SHELLS, 1) : undefined
-    process.stderr.write(
-      `vx completions: expected one shell — bash, zsh or fish${one ? ` (got ${shell})` : ''}${best === undefined ? '' : `. Did you mean ${best}?`}${seeHelp('completions')}\n`,
+    sayNotice(
+      'error',
+      'vx completions',
+      `expected one shell — bash, zsh or fish${one ? ` (got ${shell})` : ''}${best === undefined ? '' : `. Did you mean ${best}?`}${seeHelp('completions')}`,
     )
     return 1
   }

package/src/cli/foreign-flags.ts

@@ -22,8 +22,7 @@ interface ForeignFlag {
   /**
    * The runner reads `=true` / `=false` on it (Turbo's `--force [FORCE]`,
    * Nx's yargs booleans): `=false` is the flag left out, `=true` the flag
-   * bare. `--skip-nx-cache=false` forced every task, `--summarize=true`
-   * wrote the summary to a file named `true`.
+   * bare: `--skip-nx-cache=false` forced every task.
    */
   bool?: true
   /** For an alias: the vx argv. For a refusal: none. */
@@ -47,8 +46,6 @@ const nxPattern = (p: string): string => {
   return p
 }
 
-const GRAPH_IMAGE = /\.(svg|png|jpe?g|pdf|json|html|mermaid)$/i
-
 export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
   {
     runner: 'turbo',
@@ -98,21 +95,12 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     vx: '`--dry[=text|json]`',
     to: (v) => [v === undefined ? '--dry' : `--dry=${v}`],
   },
-  {
-    runner: 'turbo',
-    names: ['--graph'],
-    value: true,
-    when: (v) => v !== undefined && GRAPH_IMAGE.test(v),
-    shown: '`--graph=<file>.svg|png|json|html|…`',
-    outcome: 'refuse',
-    vx: 'vx writes Graphviz DOT only: `--graph=<file>.dot`, then `dot -Tsvg`',
-  },
   {
     runner: 'turbo',
     names: ['--graph'],
     value: false,
-    outcome: 'same',
-    vx: '`--graph[=<file>.dot]`',
+    outcome: 'refuse',
+    vx: '`--dry=json` prints the planned task graph, each task with its deps',
   },
   {
     runner: 'turbo',
@@ -133,9 +121,8 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'turbo',
     names: ['--summarize'],
     value: false,
-    bool: true,
-    outcome: 'same',
-    vx: '`--summarize[=<path>]`',
+    outcome: 'refuse',
+    vx: "use `vx last --format json` for the run's JSON record",
   },
   {
     runner: 'turbo',
@@ -263,7 +250,8 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'nx',
     names: ['--parallel'],
     value: true,
-    when: (v) => v !== undefined && v !== 'true',
+    // Nx's value is a count or `false`; a word after it is a task name.
+    when: (v) => v === 'false' || (v !== undefined && /^\d+$/.test(v)),
     shown: '`--parallel <n>`',
     outcome: 'alias',
     vx: '`--concurrency <n>` (`--parallel=false` is 1)',
@@ -362,14 +350,14 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['--json'],
     value: false,
     outcome: 'refuse',
-    vx: "use `--format json` for the run's result on stdout, `--dry=json` for the plan",
+    vx: "use `vx last --format json` for the run's result, `--dry=json` for the plan",
   },
   {
     runner: 'turbo',
     names: ['--log-file'],
     value: false,
     outcome: 'refuse',
-    vx: "use `--summarize[=<path>]` for the run's JSON record",
+    vx: "use `vx last --format json` for the run's JSON record",
   },
   {
     runner: 'turbo',
@@ -664,7 +652,7 @@ export const FOREIGN_VERBS: Readonly<Record<string, string>> = {
     '`nx run-many` is `vx run <task> --all` here; -t, -p, --exclude and --parallel work as they are',
   affected:
     '`nx affected` is `vx run <task> --affected` here; -t, --base and --exclude work as they are',
-  graph: '`nx graph` is `vx run <task> --graph[=<file>.dot]` here: the task graph as Graphviz DOT',
+  graph: '`nx graph` is `vx run <task> --dry=json` here: the planned task graph as JSON',
   ls: '`turbo ls` is `vx show` here: every project, its directory and its task count',
   query:
     '`turbo query` has no vx form: `vx run <task> --dry=json` prints the planned graph as JSON',