@vzn/vx 0.0.85 → 0.0.87

package/README.md

@@ -88,7 +88,8 @@ rm -rf packages/*/dist
 npx vx run build --all    # restored from the cache, not rebuilt
 ```
 
-More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
+Or copy [`examples/basic`](examples/basic), a two-package starter CI
+runs on every commit. More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 [Configure](https://vznjs.github.io/vx/guides/configure/) ·
 [CLI](packages/vx/docs/cli.md) · [every config field](packages/vx/docs/schema.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.85",
+  "version": "0.0.87",
   "description": "An open, extensible monorepo task runner.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.85",
-    "@vzn/vx-linux-arm64": "0.0.85",
-    "@vzn/vx-darwin-x64": "0.0.85",
-    "@vzn/vx-darwin-arm64": "0.0.85"
+    "@vzn/vx-linux-x64": "0.0.87",
+    "@vzn/vx-linux-arm64": "0.0.87",
+    "@vzn/vx-darwin-x64": "0.0.87",
+    "@vzn/vx-darwin-arm64": "0.0.87"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/cache.ts

@@ -29,6 +29,7 @@ import { Database, type SQLQueryBindings } from 'bun:sqlite'
 import { accessSync, constants, existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs'
 import { readdir, rm, stat, unlink, writeFile } from 'node:fs/promises'
 import path from 'node:path'
+import { createTables } from './schema.js'
 import {
   UserError,
   asTrees,
@@ -623,212 +624,7 @@ export class Cache implements CacheLayer {
       }
     }
 
-    // Cached config evaluations (workspace/config-cache.ts): the validated
-    // config as JSON, keyed by everything the evaluation could observe. A
-    // separate exec so the artifact schema above stays byte-identical.
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS config_evals (
-        key        TEXT PRIMARY KEY,
-        json       TEXT NOT NULL,
-        created_at INTEGER NOT NULL
-      );
-    `)
-
-    this.db.exec(`
-      -- The queryable index: command, exit_code, duration, size,
-      -- timestamps, and stdout, which the <hash>.tar.zst artifact also
-      -- carries so it survives a remote round trip; a local hit
-      -- replays it from here.
-      CREATE TABLE IF NOT EXISTS entries (
-        hash         TEXT PRIMARY KEY,
-        project      TEXT NOT NULL,
-        task         TEXT NOT NULL,
-        command      TEXT NOT NULL,
-        exit_code    INTEGER NOT NULL,
-        duration_ms  INTEGER NOT NULL,
-        size_bytes   INTEGER NOT NULL,
-        stdout       TEXT NOT NULL DEFAULT '',
-        created_at   INTEGER NOT NULL,
-        accessed_at  INTEGER NOT NULL,
-        -- v26: the producing execution's usage, from the artifact's sidecar.
-        cpu_ms         INTEGER,
-        peak_rss_bytes INTEGER
-      );
-      CREATE TABLE IF NOT EXISTS runs (
-        id                  INTEGER PRIMARY KEY AUTOINCREMENT,
-        -- '' when the outcome derived no cache key (skipped / persistent).
-        -- Every reader that must not mistake it for a key guards hash != ''.
-        hash                TEXT NOT NULL,
-        project             TEXT NOT NULL,
-        task                TEXT NOT NULL,
-        status              TEXT NOT NULL,
-        exit_code           INTEGER NOT NULL,
-        duration_ms         INTEGER NOT NULL,
-        forward_args        TEXT,
-        started_at          INTEGER NOT NULL,
-        ended_at            INTEGER NOT NULL,
-        -- v11 analytics columns. Nullable until the runner / orchestrator
-        -- PRs populate them. Storing them now means we can swap on the
-        -- producer side without touching the schema again.
-        run_id              TEXT,
-        cpu_ms              INTEGER,
-        peak_rss_bytes      INTEGER,
-        wallclock_start_ns  INTEGER,
-        wallclock_end_ns    INTEGER,
-        cache_hit           INTEGER,
-        -- v23: attempts a retried task took (>1); NULL for a once-run task.
-        -- The direct within-run flaky signal.
-        attempts            INTEGER,
-        -- v25: 1 when the task declared a cache block, 0 when it runs every
-        -- time by design; NULL on rows older than the column.
-        cached              INTEGER,
-        -- v27: why a task failed or was skipped, as the run's own footer
-        -- said it (items 267–270): a skip's root blocker (a task id), vx's
-        -- own timeout (1), the sandbox's violation count, and why a
-        -- persistent task never became ready ('timeout' | 'exited' |
-        -- 'spawn'). NULL where the reason does not apply.
-        blocked_by          TEXT,
-        timed_out           INTEGER,
-        sandbox_violations  INTEGER,
-        not_ready           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
-      -- 1,000 inserts touch a handful of leaf pages. The dropped ones did
-      -- not — the DROPs shed them from existing databases (a schema-meta
-      -- bump is for stored shapes, and an index is not one):
-      --   runs_hash (2026-09-03) had no reader; 11.5 → 3.9 ms per 1,000.
-      --   runs_project (project, task) (2026-09-09) scattered every run's
-      --     rows over one leaf per pair: the record stage of a 1,000-hit
-      --     warm run was 57–79 ms with it and 14–19 ms without, at 166k
-      --     rows, and it bought its readers nothing — the history reader
-      --     now scans a rowid slice (history.ts), vx why walks
-      --     started_at newest-first and stops at the first match.
-      --   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).
-      DROP INDEX IF EXISTS runs_hash;
-      DROP INDEX IF EXISTS runs_project;
-      DROP INDEX IF EXISTS runs_ended;
-      CREATE INDEX IF NOT EXISTS runs_started_at ON runs(started_at);
-      CREATE INDEX IF NOT EXISTS 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 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
-      -- hash is the exact same one content-hashing would compute now,
-      -- so the cache key derivation is unchanged.
-      CREATE TABLE IF NOT EXISTS file_hashes (
-        path         TEXT PRIMARY KEY,
-        mtime_ms     INTEGER NOT NULL,
-        size_bytes   INTEGER NOT NULL,
-        ctime_ms     INTEGER NOT NULL,
-        ino          INTEGER NOT NULL,
-        content_hash TEXT NOT NULL,
-        seen_at      INTEGER NOT NULL
-      );
-      -- v16: per-output-file fingerprints, scoped by the cache entry
-      -- that produced them. Lets loadOutputFilesBatch(hashes) answer
-      -- "for entry X, what are its outputs supposed to look like?"
-      -- with one SELECT, so the orchestrator can stat-and-skip the
-      -- whole restore when the tree's already current.
-      --
-      -- ON DELETE CASCADE keeps these rows in sync with entries:
-      -- a cache prune that drops an entry sweeps its output rows
-      -- automatically.
-      CREATE TABLE IF NOT EXISTS output_files (
-        entry_hash  TEXT NOT NULL,
-        path        TEXT NOT NULL,
-        size_bytes  INTEGER NOT NULL,
-        mode        INTEGER NOT NULL,
-        mtime_ms    INTEGER NOT NULL,
-        -- v28: the inode and ctime this machine saw after the save or
-        -- restore that left the file equal to the entry; NULL until then.
-        ino         INTEGER,
-        ctime_ms    INTEGER,
-        PRIMARY KEY (entry_hash, path),
-        FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
-      );
-      -- Each config's ORDERED import closure (the config first), so a warm
-      -- load keys it by stat-hashing the list (the file_hashes memo) instead
-      -- of reading and scanning every file. Machine-local; pruned with
-      -- config_evals (2026-09-03).
-      CREATE TABLE IF NOT EXISTS config_closures (
-        config_path TEXT PRIMARY KEY,
-        files_json  TEXT NOT NULL,
-        created_at  INTEGER NOT NULL
-      );
-      -- Every directory under a whole-subtree output glob, with its mtime
-      -- as of the last save/restore on THIS machine (2026-09-03). On a warm
-      -- hit, unchanged mtimes prove the output SET is unchanged, replacing
-      -- the glob walk that cost 0.36 ms per hit. Machine-local: a remote
-      -- ingest writes none, and the first hit after it walks and records.
-      CREATE TABLE IF NOT EXISTS output_dirs (
-        entry_hash  TEXT NOT NULL,
-        path        TEXT NOT NULL,
-        mtime_ms    INTEGER NOT NULL,
-        PRIMARY KEY (entry_hash, path),
-        FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
-      );
-      -- 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
-      -- counts so the dashboard never reconstructs a header with a
-      -- lossy GROUP BY over runs.
-      CREATE TABLE IF NOT EXISTS invocations (
-        run_id            TEXT PRIMARY KEY,
-        command           TEXT NOT NULL,
-        requested_tasks   TEXT NOT NULL,
-        cache_policy      TEXT NOT NULL,
-        concurrency       INTEGER NOT NULL,
-        flow              TEXT,
-        started_at        INTEGER NOT NULL,
-        ended_at          INTEGER NOT NULL,
-        total_duration_ms INTEGER NOT NULL,
-        task_count        INTEGER NOT NULL,
-        failed_count      INTEGER NOT NULL,
-        hit_count         INTEGER NOT NULL,
-        hit_local_count   INTEGER NOT NULL,
-        hit_remote_count  INTEGER NOT NULL,
-        exit_ok           INTEGER NOT NULL,
-        commit_sha        TEXT,
-        branch            TEXT,
-        dirty             INTEGER,
-        ci                INTEGER NOT NULL,
-        ci_provider       TEXT,
-        host              TEXT,
-        os                TEXT,
-        arch              TEXT,
-        vx_version        TEXT NOT NULL,
-        tags              TEXT NOT NULL DEFAULT '{}'
-      );
-      CREATE INDEX IF NOT EXISTS invocations_started ON invocations(started_at);
-      CREATE INDEX IF NOT EXISTS invocations_branch  ON invocations(branch);
-      CREATE INDEX IF NOT EXISTS invocations_ci      ON invocations(ci);
-      -- v22 (Tier 3): the input-fingerprint moat. One row per cache-key
-      -- component, keyed by the cache-ENTRY hash it belongs to (NOT a
-      -- run id). Written inside the entry-save transaction — only on a
-      -- miss/save, never on a hit — so a warm all-cache-hit run writes
-      -- nothing here (the warm path does zero extra work). The
-      -- why-did-this-re-run diff reads two entry hashes (this run's
-      -- runs.hash and the previous run's) and anti-joins their rows in
-      -- SQL over (kind,name,hash); a JSON blob would force an app-side
-      -- parse + compare on every probe. ON DELETE CASCADE keeps these
-      -- rows in sync with entries (a prune sweeps them automatically).
-      CREATE TABLE IF NOT EXISTS entry_inputs (
-        entry_hash TEXT NOT NULL,
-        kind       TEXT NOT NULL,
-        name       TEXT NOT NULL,
-        hash       TEXT NOT NULL,
-        PRIMARY KEY (entry_hash, kind, name),
-        FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
-      );
-    `)
+    createTables(this.db)
 
     this.insertEntry = this.db.prepare(`
       INSERT INTO entries(hash, project, task, command, exit_code, duration_ms, size_bytes, stdout, created_at, accessed_at, cpu_ms, peak_rss_bytes)

package/src/cache/schema.ts

@@ -0,0 +1,215 @@
+// The index's tables, one concern: what a cache.db holds. `Cache` opens the
+// file, checks `SCHEMA_VERSION` and creates these; every statement against
+// them lives in the store that owns the table (file-hashes, config-evals,
+// output-index, history) or in cache.ts for `entries` and `entry_inputs`.
+
+import type { Database } from 'bun:sqlite'
+
+export function createTables(db: Database): void {
+  // Cached config evaluations (workspace/config-cache.ts): the validated
+  // config as JSON, keyed by everything the evaluation could observe. A
+  // separate exec so the artifact schema stays byte-identical.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS config_evals (
+      key        TEXT PRIMARY KEY,
+      json       TEXT NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+  `)
+
+  db.exec(`
+    -- The queryable index: command, exit_code, duration, size,
+    -- timestamps, and stdout, which the <hash>.tar.zst artifact also
+    -- carries so it survives a remote round trip; a local hit
+    -- replays it from here.
+    CREATE TABLE IF NOT EXISTS entries (
+      hash         TEXT PRIMARY KEY,
+      project      TEXT NOT NULL,
+      task         TEXT NOT NULL,
+      command      TEXT NOT NULL,
+      exit_code    INTEGER NOT NULL,
+      duration_ms  INTEGER NOT NULL,
+      size_bytes   INTEGER NOT NULL,
+      stdout       TEXT NOT NULL DEFAULT '',
+      created_at   INTEGER NOT NULL,
+      accessed_at  INTEGER NOT NULL,
+      -- v26: the producing execution's usage, from the artifact's sidecar.
+      cpu_ms         INTEGER,
+      peak_rss_bytes INTEGER
+    );
+    CREATE TABLE IF NOT EXISTS runs (
+      id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+      -- '' when the outcome derived no cache key (skipped / persistent).
+      -- Every reader that must not mistake it for a key guards hash != ''.
+      hash                TEXT NOT NULL,
+      project             TEXT NOT NULL,
+      task                TEXT NOT NULL,
+      status              TEXT NOT NULL,
+      exit_code           INTEGER NOT NULL,
+      duration_ms         INTEGER NOT NULL,
+      forward_args        TEXT,
+      started_at          INTEGER NOT NULL,
+      ended_at            INTEGER NOT NULL,
+      -- v11 analytics columns. Nullable until the runner / orchestrator
+      -- PRs populate them. Storing them now means we can swap on the
+      -- producer side without touching the schema again.
+      run_id              TEXT,
+      cpu_ms              INTEGER,
+      peak_rss_bytes      INTEGER,
+      wallclock_start_ns  INTEGER,
+      wallclock_end_ns    INTEGER,
+      cache_hit           INTEGER,
+      -- v23: attempts a retried task took (>1); NULL for a once-run task.
+      -- The direct within-run flaky signal.
+      attempts            INTEGER,
+      -- v25: 1 when the task declared a cache block, 0 when it runs every
+      -- time by design; NULL on rows older than the column.
+      cached              INTEGER,
+      -- v27: why a task failed or was skipped, as the run's own footer
+      -- said it (items 267–270): a skip's root blocker (a task id), vx's
+      -- own timeout (1), the sandbox's violation count, and why a
+      -- persistent task never became ready ('timeout' | 'exited' |
+      -- 'spawn'). NULL where the reason does not apply.
+      blocked_by          TEXT,
+      timed_out           INTEGER,
+      sandbox_violations  INTEGER,
+      not_ready           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
+    -- 1,000 inserts touch a handful of leaf pages. The dropped ones did
+    -- not — the DROPs shed them from existing databases (a schema-meta
+    -- bump is for stored shapes, and an index is not one):
+    --   runs_hash (2026-09-03) had no reader; 11.5 → 3.9 ms per 1,000.
+    --   runs_project (project, task) (2026-09-09) scattered every run's
+    --     rows over one leaf per pair: the record stage of a 1,000-hit
+    --     warm run was 57–79 ms with it and 14–19 ms without, at 166k
+    --     rows, and it bought its readers nothing — the history reader
+    --     now scans a rowid slice (history.ts), vx why walks
+    --     started_at newest-first and stops at the first match.
+    --   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).
+    DROP INDEX IF EXISTS runs_hash;
+    DROP INDEX IF EXISTS runs_project;
+    DROP INDEX IF EXISTS runs_ended;
+    CREATE INDEX IF NOT EXISTS runs_started_at ON runs(started_at);
+    CREATE INDEX IF NOT EXISTS 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 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
+    -- hash is the exact same one content-hashing would compute now,
+    -- so the cache key derivation is unchanged.
+    CREATE TABLE IF NOT EXISTS file_hashes (
+      path         TEXT PRIMARY KEY,
+      mtime_ms     INTEGER NOT NULL,
+      size_bytes   INTEGER NOT NULL,
+      ctime_ms     INTEGER NOT NULL,
+      ino          INTEGER NOT NULL,
+      content_hash TEXT NOT NULL,
+      seen_at      INTEGER NOT NULL
+    );
+    -- v16: per-output-file fingerprints, scoped by the cache entry
+    -- that produced them. Lets loadOutputFilesBatch(hashes) answer
+    -- "for entry X, what are its outputs supposed to look like?"
+    -- with one SELECT, so the orchestrator can stat-and-skip the
+    -- whole restore when the tree's already current.
+    --
+    -- ON DELETE CASCADE keeps these rows in sync with entries:
+    -- a cache prune that drops an entry sweeps its output rows
+    -- automatically.
+    CREATE TABLE IF NOT EXISTS output_files (
+      entry_hash  TEXT NOT NULL,
+      path        TEXT NOT NULL,
+      size_bytes  INTEGER NOT NULL,
+      mode        INTEGER NOT NULL,
+      mtime_ms    INTEGER NOT NULL,
+      -- v28: the inode and ctime this machine saw after the save or
+      -- restore that left the file equal to the entry; NULL until then.
+      ino         INTEGER,
+      ctime_ms    INTEGER,
+      PRIMARY KEY (entry_hash, path),
+      FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
+    );
+    -- Each config's ORDERED import closure (the config first), so a warm
+    -- load keys it by stat-hashing the list (the file_hashes memo) instead
+    -- of reading and scanning every file. Machine-local; pruned with
+    -- config_evals (2026-09-03).
+    CREATE TABLE IF NOT EXISTS config_closures (
+      config_path TEXT PRIMARY KEY,
+      files_json  TEXT NOT NULL,
+      created_at  INTEGER NOT NULL
+    );
+    -- Every directory under a whole-subtree output glob, with its mtime
+    -- as of the last save/restore on THIS machine (2026-09-03). On a warm
+    -- hit, unchanged mtimes prove the output SET is unchanged, replacing
+    -- the glob walk that cost 0.36 ms per hit. Machine-local: a remote
+    -- ingest writes none, and the first hit after it walks and records.
+    CREATE TABLE IF NOT EXISTS output_dirs (
+      entry_hash  TEXT NOT NULL,
+      path        TEXT NOT NULL,
+      mtime_ms    INTEGER NOT NULL,
+      PRIMARY KEY (entry_hash, path),
+      FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
+    );
+    -- 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
+    -- counts so the dashboard never reconstructs a header with a
+    -- lossy GROUP BY over runs.
+    CREATE TABLE IF NOT EXISTS invocations (
+      run_id            TEXT PRIMARY KEY,
+      command           TEXT NOT NULL,
+      requested_tasks   TEXT NOT NULL,
+      cache_policy      TEXT NOT NULL,
+      concurrency       INTEGER NOT NULL,
+      flow              TEXT,
+      started_at        INTEGER NOT NULL,
+      ended_at          INTEGER NOT NULL,
+      total_duration_ms INTEGER NOT NULL,
+      task_count        INTEGER NOT NULL,
+      failed_count      INTEGER NOT NULL,
+      hit_count         INTEGER NOT NULL,
+      hit_local_count   INTEGER NOT NULL,
+      hit_remote_count  INTEGER NOT NULL,
+      exit_ok           INTEGER NOT NULL,
+      commit_sha        TEXT,
+      branch            TEXT,
+      dirty             INTEGER,
+      ci                INTEGER NOT NULL,
+      ci_provider       TEXT,
+      host              TEXT,
+      os                TEXT,
+      arch              TEXT,
+      vx_version        TEXT NOT NULL,
+      tags              TEXT NOT NULL DEFAULT '{}'
+    );
+    CREATE INDEX IF NOT EXISTS invocations_started ON invocations(started_at);
+    CREATE INDEX IF NOT EXISTS invocations_branch  ON invocations(branch);
+    CREATE INDEX IF NOT EXISTS invocations_ci      ON invocations(ci);
+    -- v22 (Tier 3): the input-fingerprint moat. One row per cache-key
+    -- component, keyed by the cache-ENTRY hash it belongs to (NOT a
+    -- run id). Written inside the entry-save transaction — only on a
+    -- miss/save, never on a hit — so a warm all-cache-hit run writes
+    -- nothing here (the warm path does zero extra work). The
+    -- why-did-this-re-run diff reads two entry hashes (this run's
+    -- runs.hash and the previous run's) and anti-joins their rows in
+    -- SQL over (kind,name,hash); a JSON blob would force an app-side
+    -- parse + compare on every probe. ON DELETE CASCADE keeps these
+    -- rows in sync with entries (a prune sweeps them automatically).
+    CREATE TABLE IF NOT EXISTS entry_inputs (
+      entry_hash TEXT NOT NULL,
+      kind       TEXT NOT NULL,
+      name       TEXT NOT NULL,
+      hash       TEXT NOT NULL,
+      PRIMARY KEY (entry_hash, kind, name),
+      FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
+    );
+  `)
+}

package/src/cli/run.ts

@@ -585,7 +585,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     const plan = await planRun(opts)
     if (plan.unresolvedTasks !== undefined && plan.unresolvedTasks.length > 0) {
       process.stderr.write(
-        `vx run: no projects declare task(s): ${plan.unresolvedTasks.join(', ')}.\n`,
+        `vx run: no projects declare task(s): ${plan.unresolvedTasks.join(', ')}.${plan.unresolvedHint ?? ''}\n`,
       )
       return 1
     }

package/src/exec/executor.ts

@@ -142,9 +142,11 @@ export interface ExecuteRequest {
   /**
    * Aborted when the run stops (Ctrl-C, SIGTERM, SIGHUP or an embedder's
    * `RunOptions.signal`) or when `timeoutMs` elapses. An executor ends its
-   * work and returns; core waits for `execute`, and a child an executor
-   * spawned is not one core can reach (H-10, H-12). A non-zero exit after
-   * the timeout's abort is recorded `timedOut`.
+   * work and returns: a child an executor spawned is not one core can
+   * reach (H-10, H-12). A non-zero exit after the timeout's abort is
+   * recorded `timedOut`. Core waits the kill grace (`VX_KILL_GRACE_MS`,
+   * 2 s) after the abort, then settles the attempt without `execute` and
+   * abandons it (H-14).
    */
   readonly signal?: AbortSignal
   /** See `RunOptions.liveChildren`: the run's SIGINT/SIGTERM registry. */

package/src/exec/index.ts

@@ -30,7 +30,7 @@ export {
 export { type DeniedCall } from './sandbox-violations.js'
 export { isMountableLiteral, MOUNT_WILDCARDS, toRealPath } from './sandbox-paths.js'
 export { bindableWrites, punchWalls } from './sandbox-binds.js'
-export { localExecutor } from './local-executor.js'
+export { isLocalExecutor, localExecutor } from './local-executor.js'
 export { holdGroups, killTree, untilGroupsGone } from './kill-tree.js'
 export {
   assertExecuteResult,

package/src/exec/local-executor.ts

@@ -8,9 +8,20 @@ import { runCommand } from './runner.js'
 import { runSandboxed } from './sandbox-runtime.js'
 import type { TaskExecutor } from './executor.js'
 
+const locals = new WeakSet<TaskExecutor>()
+
+/**
+ * Whether `executor` is core's own. By identity: a plugin may name its
+ * executor 'local', and core bounds a plugin's `execute` after an abort,
+ * which the local one (it SIGKILLs its own group) never needs.
+ */
+export function isLocalExecutor(executor: TaskExecutor): boolean {
+  return locals.has(executor)
+}
+
 /** The local executor. Accepts every task. */
 export function localExecutor(): TaskExecutor {
-  return {
+  const executor: TaskExecutor = {
     name: 'local',
     async execute(req) {
       const common = {
@@ -38,4 +49,6 @@ export function localExecutor(): TaskExecutor {
       })
     },
   }
+  locals.add(executor)
+  return executor
 }

package/src/exec/sandbox-runtime.ts

@@ -25,7 +25,15 @@
 
 import path from 'node:path'
 import os from 'node:os'
-import { mkdirSync, readlinkSync, realpathSync, rmSync, unlinkSync } from 'node:fs'
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  unlinkSync,
+} from 'node:fs'
 import { mkdir, unlink } from 'node:fs/promises'
 import type { SandboxConfig } from '../config.js'
 import {
@@ -736,6 +744,8 @@ export async function wrapSandboxedCommand(
     Pick<SandboxedRunArgs, 'baseAllowRead' | 'baseDenyRead'> & {
       /** A persistent server: the sandbox outlives a run's reset until `releaseBridges(tag)`. */
       server?: boolean
+      /** Trace the command's `openat` calls to descriptor TRACE_FD (Linux; `wantsStraceDetection`). */
+      trace?: 'plain' | 'seccomp'
     },
 ): Promise<{
   wrapped: string
@@ -746,6 +756,8 @@ export async function wrapSandboxedCommand(
   baselines: CanonicalBaselines
   /** The command reads its polite signals off fd 3: spawn it with one and `signalThrough` it. */
   forwardsSignals: boolean
+  /** The command writes its trace to fd TRACE_FD: spawn it with the log there. */
+  traced: boolean
 }> {
   const { SandboxManager } = await loadSrt()
   const userCommand = withForwardArgs(args.command, args.forwardArgs)
@@ -770,8 +782,8 @@ export async function wrapSandboxedCommand(
   const ports = process.platform === 'linux' ? bridgedPorts(args.config) : []
   const grouped =
     process.platform === 'linux'
-      ? ownGroupCommand(tag, inTmp)
-      : { command: taggedCommand, forwards: false }
+      ? ownGroupCommand(tag, inTmp, args.trace)
+      : { command: taggedCommand, forwards: false, traced: false }
   const inner =
     ports.length > 0 ? `${portBridgeInner(ports, tag)} ${grouped.command}` : grouped.command
   let wrapped = await SandboxManager.wrapWithSandbox(inner, undefined, customConfig)
@@ -783,9 +795,8 @@ export async function wrapSandboxedCommand(
   // `--die-with-parent` is keyed to vx. Behind a shell that waited on it,
   // a `kill -9` of vx left the shell alive, bwrap never heard, and a
   // sandboxed server and all it forked outlived vx (turborepo#9666). Now
-  // the namespace goes with vx, a `setsid` daemon inside included. A
-  // strace-traced spawn keeps strace as bwrap's parent: that residual is
-  // a one-shot task's, and a persistent one is never traced.
+  // the namespace goes with vx, a `setsid` daemon inside included, a
+  // traced one-shot task too: its strace runs inside (B-11).
   if (process.platform === 'linux' && wrapped.startsWith('bwrap ')) wrapped = `exec ${wrapped}`
   if (args.server === true) liveServers.add(tag)
   if (ports.length > 0) spawnHostBridges(ports, tag)
@@ -796,6 +807,7 @@ export async function wrapSandboxedCommand(
     srtCommand: inner,
     baselines,
     forwardsSignals: grouped.forwards,
+    traced: grouped.traced,
   }
 }
 
@@ -823,7 +835,11 @@ export async function wrapSandboxedCommand(
  * Tools resolve on vx's own PATH; without `setsid` the command keeps the
  * shared group, as before, and `forwards` says the channel is not there.
  */
-function ownGroupCommand(tag: string, userCommand: string): { command: string; forwards: boolean } {
+function ownGroupCommand(
+  tag: string,
+  userCommand: string,
+  trace?: 'plain' | 'seccomp',
+): { command: string; forwards: boolean; traced: boolean } {
   // `sh`, as an unsandboxed task runs (`runner.ts`): the command ran under
   // bash here, so `[[ … ]]`, brace expansion and `echo 'a\tb'` read one
   // way sandboxed and another unsandboxed or on a remote executor, where
@@ -832,22 +848,66 @@ function ownGroupCommand(tag: string, userCommand: string): { command: string; f
   try {
     sh = executablePath('sh')
   } catch {
-    return { command: `: 'vx-${tag}'; ${userCommand}`, forwards: false }
+    return { command: `: 'vx-${tag}'; ${userCommand}`, forwards: false, traced: false }
   }
-  let setsid: string
+  const tag0 = `: 'vx-${tag}';`
+  let setsid: string | undefined
   try {
-    setsid = executablePath('setsid')
+    setsid = `${shellQuote(executablePath('setsid'))} `
   } catch {
-    return {
-      command: `: 'vx-${tag}'; exec ${shellQuote(sh)} -c ${shellQuote(userCommand)}`,
-      forwards: false,
-    }
+    setsid = undefined
   }
-  const watch = `{ IFS= read -r s && kill -s "$s" -- "-$$"; } 2>/dev/null <&3 3<&- &`
-  const run = `exec ${shellQuote(setsid)} ${shellQuote(sh)} -c ${shellQuote(userCommand)} 3<&-`
-  return { command: `: 'vx-${tag}'; ${watch} ${run}`, forwards: true }
+  if (trace === undefined) {
+    const run = `exec ${setsid ?? ''}${shellQuote(sh)} -c ${shellQuote(userCommand)}`
+    if (setsid === undefined) return { command: `${tag0} ${run}`, forwards: false, traced: false }
+    const watch = `{ IFS= read -r s && kill -s "$s" -- "-$$"; } 2>/dev/null <&3 3<&- &`
+    return { command: `${tag0} ${watch} ${run} 3<&-`, forwards: true, traced: false }
+  }
+  // Traced, strace runs INSIDE the sandbox, around the command alone:
+  // outside, it followed bwrap building the namespace, a ptrace stop per
+  // `openat` of the setup, 17 of a sandboxed `true`'s 45 ms (B-11). It
+  // writes to the host's log through descriptor TRACE_FD, which the
+  // command's shell closes first, so the task cannot reach the trace.
+  // `-DD`: the command keeps the pid it was forked with and strace forks
+  // off it into a group of its own, so a `sleep 10 &` the command leaves
+  // behind is not a tracee strace waits for: the shell's `wait` ends with
+  // the command, the namespace with the shell, and strace goes with it. A tracee stops at each `openat` until strace
+  // has written its line, so the kill loses none. `-qq`: nothing of
+  // strace's own about the processes it follows.
+  // Forked, never `exec`'d: `-DD`'s process waits for ANY child to hear
+  // the tracer attached, so one it inherited (the watcher, SRT's network
+  // bridges) that exits first sent the command on untraced, and under
+  // `--seccomp-bpf` its `execve` failed ENOSYS. A fresh fork has none.
+  // An async list starts with SIGINT and SIGQUIT ignored, and a shell
+  // cannot trap what it was started ignoring: SRT's bash may put them
+  // back before the `exec` (dash may not), so a task's `trap … INT` hears
+  // vx's cancellation as it does untraced.
+  const tracer = [
+    executablePath('strace'),
+    '-DD',
+    '-f',
+    ...(trace === 'seccomp' ? ['--seccomp-bpf'] : []),
+    '-qq',
+    '-e',
+    'trace=openat',
+    '-o',
+    `/dev/fd/${TRACE_FD}`,
+    '--',
+  ]
+    .map(shellQuote)
+    .join(' ')
+  const body = shellQuote(`exec ${TRACE_FD}>&-; ${userCommand}`)
+  const run = `{ trap - INT QUIT; exec ${setsid ?? ''}${tracer} ${shellQuote(sh)} -c ${body} 3<&-; } & c=$!;`
+  if (setsid === undefined) {
+    return { command: `${tag0} ${run} wait "$c"`, forwards: false, traced: true }
+  }
+  const watch = `{ IFS= read -r s && kill -s "$s" -- "-$c"; } 2>/dev/null <&3 3<&- &`
+  return { command: `${tag0} ${run} ${watch} wait "$c"`, forwards: true, traced: true }
 }
 
+/** The descriptor an in-sandbox strace writes its trace to (`ownGroupCommand`). */
+const TRACE_FD = 5
+
 /** The ports a list grants, deduped; `true` bridges nothing (the host sees no port on Linux). */
 export function bridgedPorts(c: Pick<ResolvedSandboxConfig, 'localBinding'>): number[] {
   return Array.isArray(c.localBinding) ? [...new Set(c.localBinding)] : []
@@ -971,11 +1031,14 @@ const TRACER_RETRY_LINE =
  * `initSandbox()` first.
  *
  * On Linux the task runs under strace, which only REPORTS what the sandbox
- * denied, and a traced task's exit is strace's. strace failing on its own
- * (`ptrace(PTRACE_LISTEN,…): Input/output error`, after a build that had
- * finished) turned green work red on CI five times (STATUS Next 24). Such an
- * attempt, its last word strace's own, is run once more: the sandbox kept
- * its writes to what it declared, so a second run redoes, not doubles, it.
+ * denied. strace failing on its own (`ptrace(PTRACE_LISTEN,…): Input/output
+ * error`, after a build that had finished) turned green work red on CI five
+ * times (STATUS Next 24): its exit was the task's. Since B-11 it is not —
+ * strace runs detached (`-DD`), and a tracer that dies leaves the command
+ * running untraced — but the trace then stops short, and a denial after it
+ * goes unreported. So an attempt whose stderr carries strace's own word is
+ * run once more, whatever its exit: the sandbox kept its writes to what it
+ * declared, so a second run redoes, not doubles, it.
  */
 export async function runSandboxed(args: SandboxedRunArgs): Promise<SandboxedRunResult> {
   const { tracerFailed, ...first } = await runSandboxedOnce(args)
@@ -1029,7 +1092,7 @@ function collectRecords(
   }
 }
 
-/** strace's own message, as the last line a failed traced task printed. */
+/** strace's own message, a line of a traced task's stderr. */
 const STRACE_OWN_ERROR = /^strace: /
 
 /**
@@ -1046,17 +1109,12 @@ async function runSandboxedOnce(
 ): Promise<SandboxedRunResult & { tracerFailed: boolean }> {
   const start = Date.now()
   const { SandboxManager } = await loadSrt()
-  const { wrapped, tag, srtCommand, baselines, forwardsSignals } = await wrapSandboxedCommand(args)
-  const takeRecords = collectRecords(SandboxManager.getSandboxViolationStore(), srtCommand)
-
   // Linux: SRT's store sees only writes (below), so read denials need
-  // the spawn wrapped with strace and the trace parsed for denied syscalls. The trace is per-task (unique
-  // log path keyed by the command tag) so parallel tasks don't share
-  // a stream. Skipped when strace isn't on PATH — bwrap still enforces
-  // structurally; we just lose the structured violation list.
-  const useStrace = await wantsStraceDetection()
-  const straceLog = useStrace ? path.join(os.tmpdir(), `vx-strace-${tag}.log`) : undefined
-  if (straceLog) unlinkOnExit(straceLog)
+  // the command traced and the trace parsed for denied syscalls. The trace
+  // is per-task (a log keyed by the command tag) so parallel tasks don't
+  // share a stream. Skipped when strace isn't on PATH — bwrap still
+  // enforces structurally; we just lose the structured violation list.
+  //
   // We trace only `openat` — it's the actual file-read attempt, the
   // signal the user cares about. `statx` / `newfstatat` / `access`
   // are mostly shell PATH-walking and stat probes that aren't
@@ -1073,56 +1131,37 @@ async function runSandboxedOnce(
   // it taxed every other sandboxed task the same way. With the flag the
   // kernel filter stops only on `openat`. strace ≥ 5.3 (2019); an older
   // one gets the slow form rather than no detection.
+  const useStrace = await wantsStraceDetection()
+  const { wrapped, tag, srtCommand, baselines, forwardsSignals, traced } =
+    await wrapSandboxedCommand({ ...args, ...(useStrace ? { trace: useStrace } : {}) })
+  const takeRecords = collectRecords(SandboxManager.getSandboxViolationStore(), srtCommand)
+  const straceLog = traced ? path.join(os.tmpdir(), `vx-strace-${tag}.log`) : undefined
+  if (straceLog) unlinkOnExit(straceLog)
   let proc: ReturnType<typeof Bun.spawn>
+  let traceFd: number | undefined
   try {
-    // Both tools resolved on vx's own PATH (util/which.ts): strace would
-    // otherwise walk the task's PATH for `sh`, where a project's
-    // node_modules/.bin comes first.
+    // Resolved on vx's own PATH (util/which.ts), not the task's, where a
+    // project's node_modules/.bin comes first.
     const sh = executablePath('sh')
-    const spawnArgv = straceLog
-      ? [
-          executablePath('strace'),
-          '-f',
-          ...(useStrace === 'seccomp' ? ['--seccomp-bpf'] : []),
-          '-e',
-          'trace=openat',
-          '-o',
-          straceLog,
-          '--',
-          sh,
-          '-c',
-          wrapped,
-        ]
-      : [sh, '-c', wrapped]
-    // With the guard, a shell lists the group first and `exec`s the
-    // spawn: strace itself would hold the guard's pipe for its lifetime.
-    const guardAt = forwardsSignals ? 4 : 3
+    if (straceLog) traceFd = openSync(straceLog, 'w')
+    // Descriptors: 3 the signal channel the in-sandbox watcher reads, 4 the
+    // guard's pipe (kill-tree.ts), TRACE_FD the trace log; a gap is 'ignore'.
     proc = spawnGuarded((guard) =>
-      Bun.spawn(
-        guard === undefined
-          ? spawnArgv
-          : [
-              sh,
-              '-c',
-              guardLine(guardAt) +
-                (straceLog ? `exec ${spawnArgv.map(shellQuote).join(' ')}` : wrapped),
-            ],
-        {
-          argv0: straceLog && guard === undefined ? 'strace' : 'sh',
-          cwd: args.cwd,
-          env: args.env as Record<string, string>,
-          // fd 3 is the signal channel the in-sandbox watcher reads.
-          stdio: [
-            'ignore',
-            'pipe',
-            'pipe',
-            ...(forwardsSignals ? ['pipe' as const] : []),
-            ...(guard === undefined ? [] : [guard]),
-          ],
-          // As the unsandboxed spawn: its own process group (kill-tree.ts).
-          detached: true,
-        },
-      ),
+      Bun.spawn([sh, '-c', (guard === undefined ? '' : guardLine(4)) + wrapped], {
+        argv0: 'sh',
+        cwd: args.cwd,
+        env: args.env as Record<string, string>,
+        stdio: [
+          'ignore',
+          'pipe',
+          'pipe',
+          forwardsSignals ? 'pipe' : 'ignore',
+          guard ?? 'ignore',
+          ...(traceFd === undefined ? [] : [traceFd]),
+        ],
+        // As the unsandboxed spawn: its own process group (kill-tree.ts).
+        detached: true,
+      }),
     )
     if (forwardsSignals) signalThrough(proc, proc.stdio[3] as number)
   } catch (err) {
@@ -1138,20 +1177,27 @@ async function runSandboxedOnce(
       violations: [],
       tracerFailed: false,
     }
+  } finally {
+    // The child holds its own copy; ours would keep nothing but a descriptor.
+    if (traceFd !== undefined) closeSync(traceFd)
   }
 
   args.liveChildren?.add(proc)
   const timeout = armTimeout(proc, args.timeoutMs)
   const ac = new AbortController()
-  let stderrTail = ''
+  // The unfinished last line of stderr, and whether a line was strace's.
+  let partial = ''
+  let straceSpoke = false
   const streams = Promise.all([
     streamToString(proc.stdout, args.onStdout, ac.signal, args.capture?.stdout ?? true),
     streamToString(
       proc.stderr,
       (chunk) => {
-        // Kept whatever the capture setting: the last line says whether
-        // strace, not the task, ended the attempt.
-        stderrTail = (stderrTail + chunk).slice(-1024)
+        // Read whatever the capture setting: a line of strace's own says
+        // the trace stopped short.
+        const lines = (partial + chunk).split('\n')
+        partial = (lines.pop() ?? '').slice(0, 64)
+        if (lines.some((l) => STRACE_OWN_ERROR.test(l))) straceSpoke = true
         args.onStderr?.(chunk)
       },
       ac.signal,
@@ -1289,7 +1335,6 @@ async function runSandboxedOnce(
     // ignore; bwrap mount-point cleanup is best-effort
   }
 
-  const lastLine = stderrTail.trimEnd().split('\n').pop() ?? ''
   return {
     exitCode,
     durationMs: Date.now() - start,
@@ -1309,9 +1354,8 @@ async function runSandboxedOnce(
     ...(process.platform === 'linux' ? {} : resourceUsageToCpuRss(proc.resourceUsage())),
     tracerFailed:
       straceLog !== undefined &&
-      exitCode !== 0 &&
       !timeout.timedOut() &&
-      STRACE_OWN_ERROR.test(lastLine),
+      (straceSpoke || STRACE_OWN_ERROR.test(partial)),
   }
 }
 

package/src/orchestrator/execute-task.ts

@@ -22,6 +22,7 @@ import {
   releaseBridges,
   wrapSandboxedCommand,
   signalExitCode,
+  isLocalExecutor,
   type CaptureConfig,
   type ExecuteRequest,
   assertExecuteResult,
@@ -32,7 +33,9 @@ import {
   PersistentReadyError,
 } from '../exec/index.js'
 import { isGroupTask, RestoreDemoted, type TaskNode, type TaskOutcome } from '../graph/index.js'
-import { relPosix, span } from '../util/index.js'
+import { killGraceMs, relPosix, span } from '../util/index.js'
+import { SIGNAL_SHUTDOWN_GRACE_MS } from './signals.js'
+import { executorLabel } from './plugin-host.js'
 import {
   mayWriteFingerprint,
   type Placeholder,
@@ -493,6 +496,49 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     }
     return stop.signal
   }
+  // An executor that ignores `signal` held its task, and so the run, past
+  // the stop and past `exec.timeout` (H-14). Once the signal aborts it has
+  // the kill grace the local executor gives a process group; then core
+  // settles the attempt without it and says so. Its work is abandoned: core
+  // cannot reach what it started.
+  function boundAfterAbort(
+    running: Promise<unknown>,
+    signal: AbortSignal | undefined,
+  ): Promise<unknown> {
+    if (signal === undefined || isLocalExecutor(args.executor)) return running
+    const started = Date.now()
+    let graceTimer: ReturnType<typeof setTimeout> | undefined
+    let onAbort: (() => void) | undefined
+    const abandoned = new Promise<ExecuteResult>((resolve) => {
+      onAbort = (): void => {
+        const graceMs = killGraceMs(SIGNAL_SHUTDOWN_GRACE_MS)
+        graceTimer = setTimeout(() => {
+          const why = timeoutFired ? `timeout (${effectiveTimeout}ms)` : 'stop'
+          log.taskStderr(
+            node,
+            `vx: ${executorLabel(args.executor)} did not return within ${graceMs}ms of the ${why}; abandoned\n`,
+          )
+          const reason: unknown = signal.reason
+          resolve({
+            exitCode: signalExitCode(reason === 'SIGINT' ? 'SIGINT' : 'SIGTERM'),
+            durationMs: Date.now() - started,
+            stdout: '',
+            stderr: '',
+            violations: [],
+            ...(timeoutFired ? { timedOut: true } : {}),
+          })
+        }, graceMs)
+      }
+      if (signal.aborted) onAbort()
+      else signal.addEventListener('abort', onAbort, { once: true })
+    })
+    // The abandoned call may still settle, or reject, later: nobody awaits it.
+    running.catch(() => {})
+    return Promise.race([running, abandoned]).finally(() => {
+      clearTimeout(graceTimer)
+      if (onAbort !== undefined) signal.removeEventListener('abort', onAbort)
+    })
+  }
 
   // When the task started, as a ns offset from run start — captured for
   // EVERY outcome (hits included) so the run-detail timeline reflects when
@@ -722,8 +768,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // no other trace. Rethrown unchanged — the scheduler still classifies it,
     // and still prints it plainly for a UserError.
     const endExec = span('miss: execute')
-    let res = await args.executor
-      .execute(req)
+    let res = await boundAfterAbort(args.executor.execute(req), req.signal)
       .then((r: unknown) => {
         assertExecuteResult(args.executor.name, node.id, r)
         return r

package/src/orchestrator/local-shortcircuit.ts

@@ -199,7 +199,6 @@ function restoreTierExclusions(nodes: Map<string, TaskNode>, workspaceRoot: stri
   if (prefixes.length === 0) return out
   const reaches = (dir: string): boolean =>
     dir === '' ||
-    dir === '.' ||
     prefixes.some((p) => p === dir || p.startsWith(`${dir}/`) || dir.startsWith(`${p}/`))
   const dependants = new Map<string, string[]>()
   for (const node of nodes.values()) {

package/src/orchestrator/metrics.ts

@@ -241,58 +241,24 @@ export function getInvocation(db: Database, runId: string): InvocationDetail | n
 
 export interface ListInvocationsArgs {
   limit?: number
-  branch?: string
-  ci?: boolean
-  tagKey?: string
-  tagValue?: string
 }
 
 /**
- * List `vx run` invocations newest-first from the `invocations` header table
- * with optional branch / ci / tag filters. Reading the dedicated header table
- * (vs the old `GROUP BY run_id` over `runs`) is lossless — git/ci/tag context
- * survives. Accepts a bare `number` for the limit (back-compat with the old
- * `listInvocations(db, 50)` signature).
+ * List `vx run` invocations newest-first from the `invocations` header table.
+ * Reading the dedicated header table (vs the old `GROUP BY run_id` over
+ * `runs`) is lossless — git/ci/tag context survives.
  */
-export function listInvocations(
-  db: Database,
-  args: ListInvocationsArgs | number = {},
-): InvocationDetail[] {
-  const opts: ListInvocationsArgs = typeof args === 'number' ? { limit: args } : args
-  const limit = clampInt(opts.limit ?? 50, 1, 500)
-  const where: string[] = []
-  const params: (string | number)[] = []
-  if (opts.branch !== undefined) {
-    where.push('branch = ?')
-    params.push(opts.branch)
-  }
-  if (opts.ci !== undefined) {
-    where.push('ci = ?')
-    params.push(opts.ci ? 1 : 0)
-  }
-  if (opts.tagKey !== undefined && opts.tagValue !== undefined) {
-    // The tags column is a JSON object {"k":"v"}; a LIKE over the serialized
-    // pair is adequate at this table's scale (see the design doc).
-    where.push('tags LIKE ?')
-    params.push(`%${jsonPairFragment(opts.tagKey, opts.tagValue)}%`)
-  }
-  const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''
+export function listInvocations(db: Database, args: ListInvocationsArgs = {}): InvocationDetail[] {
+  const limit = clampInt(args.limit ?? 50, 1, 500)
   const rows = db
     .query(
-      `SELECT ${INVOCATION_COLUMNS} FROM invocations ${clause}
+      `SELECT ${INVOCATION_COLUMNS} FROM invocations
        ORDER BY rowid DESC LIMIT ?`,
     )
-    .all(...params, limit) as InvocationRawRow[]
+    .all(limit) as InvocationRawRow[]
   return rows.map(mapInvocation)
 }
 
-/** The `"key":"value"` fragment as it appears in `JSON.stringify({k:v})`. */
-function jsonPairFragment(key: string, value: string): string {
-  const k = JSON.stringify(key).slice(1, -1)
-  const v = JSON.stringify(value).slice(1, -1)
-  return `"${k}":"${v}"`
-}
-
 export interface RunDetail {
   runId: string
   startedAt: number

package/src/orchestrator/plan.ts

@@ -77,6 +77,8 @@ export interface RunPlan {
    * equivalent `vx run` would refuse to start.
    */
   unresolvedTasks?: readonly string[]
+  /** What `vx run` appends to that refusal: the nearest declared names, or how to declare one. */
+  unresolvedHint?: string
   /**
    * Producers `--download` WANTED to defer but could not, mapped to why.
    * Without this the gate is invisible: a user asks for `--download=none`,

package/src/orchestrator/plugin-host.ts

@@ -108,10 +108,13 @@ export async function applyConfigHooks(
   plugins: readonly VxPlugin[],
   workspace: WorkspaceConfig,
   ctx: WorkspaceHookContext,
+  /** Runs after EACH plugin's edit, so a refusal can name the plugin that made it. */
+  afterEach?: (plugin: VxPlugin) => void,
 ): Promise<void> {
   for (const plugin of plugins) {
     if (plugin.config === undefined) continue
     await safe(plugin, 'config', () => plugin.config!(workspace, ctx))
+    afterEach?.(plugin)
   }
 }
 

package/src/orchestrator/plugin.ts

@@ -56,6 +56,7 @@ export interface VxPlugin {
   /**
    * The workspace config, before anything is derived from it (concurrency,
    * cacheDir, timeout, …). `plugins` is already fixed by the time this runs.
+   * Core re-validates after each plugin, as it does a user's file.
    */
   config?(workspace: WorkspaceConfig, ctx: WorkspaceHookContext): void | Promise<void>
 

package/src/orchestrator/projects.ts

@@ -26,6 +26,7 @@ import {
   loadWorkspace,
   loadWorkspaceConfig,
   resolveCacheDir,
+  validateWorkspace,
 } from '../workspace/index.js'
 import { parseDependencySpec } from '../graph/index.js'
 import { applyConfigHooks, applyProjectHooks, hasHook } from './plugin-host.js'
@@ -43,7 +44,12 @@ export async function loadWorkspacePlugins(
   const workspaceConfig = await loadWorkspaceConfig(workspaceRoot)
   const plugins = (workspaceConfig?.plugins ?? []) as readonly VxPlugin[]
   if (workspaceConfig !== null && hasHook(plugins, 'config')) {
-    await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn })
+    // Re-validated after each plugin, as the `project` stage is: an edit
+    // the loader would refuse from a user (`concurrency: -3`) hung the run,
+    // and `cacheDir: 42` reached `path.resolve` as a TypeError.
+    await applyConfigHooks(plugins, workspaceConfig, { workspaceRoot, warn }, (plugin) =>
+      validateWorkspace(workspaceConfig, `vx.workspace (after plugin '${plugin.name}')`),
+    )
   }
   return { workspaceConfig, plugins }
 }

package/src/orchestrator/run.ts

@@ -1206,7 +1206,11 @@ export async function planRun(options: RunOptions): Promise<RunPlan> {
   const prepared = await prepareRun(options, log)
   try {
     if (prepared.unresolvedTasks.length > 0) {
-      return { tasks: [], unresolvedTasks: prepared.unresolvedTasks }
+      return {
+        tasks: [],
+        unresolvedTasks: prepared.unresolvedTasks,
+        unresolvedHint: `${didYouMean(prepared.unresolvedTasks, prepared.projects)}${await initHint(prepared)}`,
+      }
     }
     if (prepared.empty !== null) return { tasks: [] }
     // Its own mark: a dry run's plan (every task's hash, the cache lookups,

package/src/workspace/index.ts

@@ -34,7 +34,7 @@ export {
   loadWorkspaceConfig,
   WORKSPACE_CONFIG_FILENAMES,
 } from './project-loader.js'
-export { validateProjectConfig } from './config-schema.js'
+export { validateProjectConfig, validateWorkspace } from './config-schema.js'
 export type { LoadProjectConfigOptions } from './project-loader.js'
 export {
   blobOidOf,