@vzn/vx 0.0.637 → 0.0.639

package/docs/execution.md

@@ -24,7 +24,7 @@ terminal and a task succeeding or failing. Read it alongside
  │       PROCESS — always. (A whole-run `backend` seam existed until
  │       2026-08; it moved the scheduler server-side, which is why it
  │       went. Per-task placement is the `executor` capability.)
- │       --dry / --graph short-circuit into planRun instead.
+ │       --dry short-circuits into planRun instead.
  │
  ├─ Prepare (src/orchestrator/prepare.ts:prepareRun — shared with planRun)
  │    1. findWorkspaceRoot(cwd) — the directory of the nearest
@@ -155,7 +155,7 @@ terminal and a task succeeding or failing. Read it alongside
  │                signal, forward it (SIGHUP as SIGTERM) to everything
  │                in liveChildren + persistentRegistry (and kill any
  │                running cache.inputs.runtime probe, C-65), wait
- │                VX_RUN_KILL_GRACE (2 s) for their groups, SIGKILL
+ │                2 s for their groups, SIGKILL
  │                what is still there, let the run finish its own
  │                end (flush, teardown, cache close), then
  │                die of the signal (SIGINT → 130, SIGTERM → 143,
@@ -303,11 +303,10 @@ terminal and a task succeeding or failing. Read it alongside
     2. Run summary footer (projects / tasks / cache meters + info +
        time + result) — counts only real tasks (with `exec`); group tasks
        don't pollute the totals; failure frames replay just above it.
-    3. Optional --summarize JSON (default <cacheDir>/runs/<run_id>.json)
-       and --profile Chrome-trace JSON (default profile.json).
+    3. Optional --profile Chrome-trace JSON (default profile.json).
     4. recordRunBundle — one transaction writing a `runs` row per real
        task plus the `invocations` header row (command, git/CI/host
-       context, tags, counts). Group + aborted tasks skipped; a run
+       context, counts). Group + aborted tasks skipped; a run
        a signal stopped records nothing.
     5. Telemetry: emit the RunSummaryRecord to every active sink +
        await their flush (crash-isolated; skipped when no sink).
@@ -325,11 +324,7 @@ terminal and a task succeeding or failing. Read it alongside
        alive, Ctrl-C reaps the process group. That first exit ends the
        session: the others are torn down (SIGTERM, grace, SIGKILL) and
        a non-zero exit makes the run exit 1, so a script's `vx run dev`
-       fails when the server it started fell over. That server then reads
-       `failed` with its own exit in the rewritten `--summarize` and in the
-       report `--report-file` writes; one a Ctrl-C stopped does not. The
-       stdout `--report` prints above the footer, so it reads as the
-       footer does, before the wait. Under
+       fails when the server it started fell over. Under
        `holdPersistent` (the watch loop) run() instead returns them on
        `RunSummary.persistent`, still running, for the caller to stop;
        one that dies on its own after that is said, its `stop()` is not.
@@ -543,21 +538,20 @@ Every surface uses one outcome vocabulary: task axis `success` /
 `failed` / `skipped` / `aborted` (+ `running` live), cache axis
 `miss` / `up-to-date` (fresh) / `local` / `remote`. The `--verbosity 1`
 table spells the combinations out as `success` / `restored-local` /
-`restored-remote` / `up-to-date`; `--report` keeps the two axes as its
-Status and Cache columns.
+`restored-remote` / `up-to-date`.
 
 The colors / framing modules:
 
-- `orchestrator/colors.ts` — ANSI truecolor (`ansi-16m`), gated by
+- `util/colors.ts` — ANSI truecolor (`ansi-16m`), gated by
   `NO_COLOR` / `FORCE_COLOR` / `isTTY`. Programmatic-logger callers
   always see plain text.
-- `orchestrator/framed-output.ts` — the `┌─` frames, the glyph grid
+- `report/framed-output.ts` — the `┌─` frames, the glyph grid
   (`formatTaskRow`), one-liners, persistent markers.
-- `orchestrator/status-line.ts` — the serialized writer + the worker
+- `report/status-line.ts` — the serialized writer + the worker
   region.
-- `orchestrator/logger.ts` — composes them; resolves the output view
+- `report/logger.ts` — composes them; resolves the output view
   and applies the per-flow visibility policy.
-- `orchestrator/summary.ts` — the closing footer (wordmark rule,
+- `report/summary.ts` — the closing footer (wordmark rule,
   projects/tasks/cache meters, info and time rows).
 
 ## Concurrency
@@ -617,9 +611,9 @@ snapshot is clean). `--cache-policy=<spec>` gives per-layer control. Full
 semantics: [`cli.md` § Cache control](./cli.md#cache-control---cache-policy---no-cache---force)
 and [`caching.md` § Cache policy](./caching.md#cache-policy-readwrite-axes).
 
-## Planning paths (`--dry`, `--graph`)
+## Planning path (`--dry`)
 
-Both short-circuit execution. The planner (`orchestrator/plan.ts`)
+`--dry` short-circuits execution. The planner (`orchestrator/plan.ts`)
 runs the same setup steps — workspace discovery, config load, package
 graph, task graph — and the same per-task hash derivation, then
 probes the cache. The probe is read-only; against a remote layer it
@@ -628,8 +622,6 @@ deliberate side effect: `cache.inputs.runtime` / `workspaceRuntime`
 probe commands DO run, because predicting a key requires resolving
 them — keep runtime inputs side-effect-free.
 
-The two flags differ only in output format:
-
 - `--dry[=text|json]` → text (default) or JSON list of predicted
   outcomes per task: `hit-local`, `hit-remote`, `miss`, `no-cache`,
   `group`. Formatter: `cli/plan-format.ts:formatPlanText` /
@@ -639,36 +631,19 @@ The two flags differ only in output format:
   executors is a plugin-factory call, the same class the cache capability
   already makes at plan time; a plugin that throws costs the label, never
   the plan.
-- `--graph[=<path>]` → Graphviz DOT, colored by predicted status.
-  Pipe to `dot` for SVG/PNG render. Formatter:
-  `formatGraphDot`.
-
-Mutually exclusive: `--dry` and `--graph` together is a parse error.
-Combining either with `--summarize`, `--profile`, `--report` or
-`--report-file` is a parse error (those need a real run; the last two
-were accepted and wrote nothing until item 992).
+  Combining it with `--profile` is a parse error (the profile needs a
+  real run).
 
 ## Run artifacts
 
-- **`--summarize[=<path>]`** — per-run JSON to
-  `<cacheDir>/runs/<run_id>.json` by default (or the explicit path).
-  Mirrors the `runs` table shape — one task entry per real task, hits
-  included, with status, hash, duration, cpu_ms, peak RSS, hrtime spans
-  (bigint serialized as strings to preserve ns precision).
 - **`--profile[=<path>]`** — Chrome-trace JSON of every task's
   wallclock span. Default path: `profile.json` (cwd-relative). One
   `tid` per project so concurrent tasks render on distinct lanes.
   Open with `chrome://tracing` or https://ui.perfetto.dev.
-- **`--report[=markdown]`** — a markdown table to stdout
-  above the footer (CI step summaries), through `RunOptions.beforeFooter`.
-- **`--report-file <path>`** — the same report APPENDED to `<path>`
-  (`$GITHUB_STEP_SUMMARY`).
-
-Writers live in `orchestrator/run-artifacts.ts:writeRunSummary` /
-`writeRunProfile` and `orchestrator/run-report.ts`. A `--summarize` or
-`--profile` write error is surfaced via `log.status`, a `--report-file`
-one on stderr (`cli/run.ts`); neither changes the run's exit code — the
-run already happened.
+
+The writer is `orchestrator/run-artifacts.ts:writeRunProfile`. A write error is surfaced via `log.status` and does
+not change the run's exit code — the run already happened. A CI job
+summary is `@vzn/vx-ci`'s.
 
 ## Why each rule
 

package/docs/features.md

@@ -26,7 +26,7 @@ config key or an environment variable is missing here.
 - **Task picker** — `vx run` with no task in a terminal lists tasks to pick. [page](https://vznjs.github.io/vx/features/task-picker/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Typo hints** — an unknown task, project or filter suggests the nearest name. [page](https://vznjs.github.io/vx/features/filter-hints/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Turbo and Nx spellings** (`-t`, `-p`, `--exclude`, `--parallel`, `--base`, `--dry-run`, `--skip-nx-cache`) — accepted, or refused naming the vx spelling. [page](https://vznjs.github.io/vx/features/turbo-nx-flags/) · post: [Flags you already know](https://vznjs.github.io/vx/blog/flags-you-already-know/)
-- **Ctrl-C leaves nothing running** (`--kill-grace`, `--teardown-timeout`, `run.killGrace`, `run.teardownTimeout`, `VX_RUN_KILL_GRACE`, `VX_RUN_TEARDOWN_TIMEOUT`) — the whole process tree stops, then teardown runs. [page](https://vznjs.github.io/vx/features/ctrl-c/) · post: [Ctrl-C leaves nothing running](https://vznjs.github.io/vx/blog/ctrl-c/)
+- **Ctrl-C leaves nothing running** — the whole process tree stops, then teardown runs. [page](https://vznjs.github.io/vx/features/ctrl-c/) · post: [Ctrl-C leaves nothing running](https://vznjs.github.io/vx/blog/ctrl-c/)
 - **Longest chain first** — the scheduler starts the critical path first; `@vzn/vx-schedule-history` learns it from past runs. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Bitsets, popcount, and a scheduler tick](https://vznjs.github.io/vx/blog/bitsets-and-the-scheduler/)
 - **Schedule strategy** (`--schedule`, `run.schedule`, `VX_RUN_SCHEDULE`) — pick the order with no timings: most work waiting (default), longest chain, most direct dependents, or ready order; plugins still lead. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Which task runs first?](https://vznjs.github.io/vx/blog/scheduling-strategies/#pick-the-guess)
 - **No daemon** — every run starts cold and still answers in milliseconds. [page](https://vznjs.github.io/vx/features/no-daemon/) · post: [No daemon, on purpose](https://vznjs.github.io/vx/blog/no-daemon/)
@@ -47,23 +47,20 @@ config key or an environment variable is missing here.
 - **Run summary** — one block: projects, tasks, cache, time; nothing prints below it. [page](https://vznjs.github.io/vx/features/run-summary/) · post: [A run you can read](https://vznjs.github.io/vx/blog/a-run-you-can-read/)
 - **Per-task table** (`--verbosity`) — a per-task summary after the run. [page](https://vznjs.github.io/vx/features/per-task-table/) · post: [One failure, and exactly what it takes down](https://vznjs.github.io/vx/blog/when-a-build-fails/)
 - **Failed output kept for agents** — a failure's full log is saved and pointed to. [page](https://vznjs.github.io/vx/features/failed-output-kept/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
-- **Markdown report** (`--report`, `--report-file`) — a run report for a PR or `$GITHUB_STEP_SUMMARY`. [page](https://vznjs.github.io/vx/features/markdown-report/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
-- **Run JSON** (`--summarize`) — per-run JSON for scripts, with the time the cache saved (`savedMs`). [page](https://vznjs.github.io/vx/features/run-json/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
 - **Trace profile** (`--profile`) — Chrome-trace JSON of the run. [page](https://vznjs.github.io/vx/features/profile/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
 - **Run branch** (`--branch`, `VX_RUN_BRANCH`) — name the branch a run records in its history and forecasts from; unset, git's branch, then the CI provider's. no post
-- **Run tags** (`--tag`) — label a run; recorded in history. [page](https://vznjs.github.io/vx/features/run-tags/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
 - **Stage timing** (`VX_DEBUG_TIMING`) — vx's own stage table, for performance work. [page](https://vznjs.github.io/vx/features/stage-timing/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
 - **Output flows** — what is printed follows the run's intent (focused, broad or CI); a truthy `CI` wins. [page](https://vznjs.github.io/vx/features/output-flows/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
 - **Cache-aware glyphs** — each task line's glyph shows ran, fresh, restored locally or remotely, failed, skipped or persistent. [page](https://vznjs.github.io/vx/features/cache-glyphs/) · post: [Output that fits the run](https://vznjs.github.io/vx/blog/output-that-fits-the-run/)
 - **GitHub Actions log groups** — on Actions, each task's block folds in a `::group::` with its outcome and time. [page](https://vznjs.github.io/vx/features/actions-log-groups/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
-- **Colors** (`NO_COLOR`, `FORCE_COLOR`) — truecolor output, forced on or off by env. [page](https://vznjs.github.io/vx/features/colors/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
+- **Colors** (`NO_COLOR`, `FORCE_COLOR`) — truecolor output, forced on or off by env; `TERM=dumb` prints plain, with no live region. [page](https://vznjs.github.io/vx/features/colors/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
 - **Signal-named exits** — a failure reads `exit 137, 128 + SIGKILL`. [page](https://vznjs.github.io/vx/features/signal-exits/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
+- **vx's own steps as rows** — on a terminal, what vx does around the tasks (`vx:uploads`, `<plugin>:teardown`) shows as a running row once it passes 150 ms, then a list row; never counted as a task. no post
 - **Plain output off a TTY** — no live region, and a missing task lists tasks instead of opening the picker. [page](https://vznjs.github.io/vx/features/plain-off-tty/) · post: [The basics, done carefully](https://vznjs.github.io/vx/blog/the-basics/)
 
 ## Plan and explain
 
 - **Dry run** (`--dry`) — the task graph and the predicted hits and misses, text or JSON (with the predicted wall time and its critical path), nothing runs. [page](https://vznjs.github.io/vx/features/dry-run/) · post: [See the plan before you run it](https://vznjs.github.io/vx/blog/dry-run/)
-- **Graph** (`--graph`) — the task graph as Graphviz DOT. [page](https://vznjs.github.io/vx/features/task-graph/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
 - **vx why** (`vx why`, `--run`) — why a task re-ran, down to the file, env var or config that changed, and the task that wrote a moved input. [page](https://vznjs.github.io/vx/features/vx-why/) · post: [Why did this re-run?](https://vznjs.github.io/vx/blog/why-did-this-rerun/)
 - **vx show** (`vx show`) — every project, a project's or a task's resolved config, read from the lock as a run reads it. [page](https://vznjs.github.io/vx/features/vx-show/) · post: [See what a task really is](https://vznjs.github.io/vx/blog/vx-show/)
 - **vx last** (`vx last`, `--list`, `--failed`, `--log`, `--stats`, `--branch`) — replay a recorded run's summary, list recent runs, print one task's output, or per-task history stats (p50 as the live estimate forecasts it on a branch, p99, pass and hit rate, failure mode, peak RSS). [page](https://vznjs.github.io/vx/features/vx-last/) · post: [The last run, on request](https://vznjs.github.io/vx/blog/vx-last/)
@@ -75,7 +72,7 @@ config key or an environment variable is missing here.
 - **Docs for agents** (`llms.txt`, `llms-full.txt`) — the whole site as markdown for coding agents. [page](https://vznjs.github.io/vx/features/llms-txt/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
 - **vx docs** (`vx docs`, `--limit`) — search the CLI, config and cache reference offline; it ships inside vx. [page](https://vznjs.github.io/vx/features/vx-docs/) · post: [The reference, offline](https://vznjs.github.io/vx/blog/vx-docs-offline/)
 - **Affected reasons** (`--affected --dry`) — each kept task says the changed file or the dependency chain that reached it, text or JSON. [page](https://vznjs.github.io/vx/features/affected-reasons/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
-- **Agent skill** (`skills/vx/SKILL.md`, `npx skills add vznjs/vx/packages/vx/skills/vx`) — an installable skill that teaches a coding agent to run, debug and query vx through the CLI's `--format json`; copy it from `node_modules/@vzn/vx/skills/vx/` to match the installed version. [page](https://vznjs.github.io/vx/features/agent-skill/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
+- **Agent skill** (`skills/vx/SKILL.md`, `npx skills add vznjs/vx`) — an installable skill that teaches a coding agent to run, debug and query vx through the CLI's `--format json`; copy it from `node_modules/@vzn/vx/skills/vx/` to match the installed version. [page](https://vznjs.github.io/vx/features/agent-skill/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
 
 ## Cache
 
@@ -83,7 +80,7 @@ config key or an environment variable is missing here.
 - **Inputs** (`cache.inputs.env`, `cache.inputs.runtime`, `cache.inputs.tasks`, `cache.inputs.workspaceFiles`, `cache.inputs.workspaceRuntime`) — env vars, tool versions, upstream tasks and workspace files in the key. [page](https://vznjs.github.io/vx/features/key-inputs/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Outputs** (`cache.outputs.files`, `cache.outputs.workspaceFiles`) — what a hit restores. [page](https://vznjs.github.io/vx/features/cache-outputs/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Input stability** (`cache.inputStability`, workspace `cache.inputStability`, `VX_CACHE_INPUT_STABILITY_STRATEGY`, `VX_CACHE_INPUT_STABILITY_SEVERITY`) — an input written while the command runs withholds the save, on CI too, and the saves of every task that ran over its outputs; `strategy: 'mutable'` accepts a task's identical rewrite of its own input, `'unchecked'` skips the check; `severity: 'error'` fails the run instead of warning. no post
-- **Keep outputs on a miss** (`cache.outputs.clean`, workspace `cache.outputs.clean`, `VX_CACHE_OUTPUTS_CLEAN`) — `false` leaves a task's outputs in place for a tool that reads its last output (tsc's `.tsbuildinfo`); if the run leaves any old file unchanged, nothing is cached. no post
+- **Keep outputs on a miss** (`cache.outputs.clean`, workspace `cache.outputs.clean`) — `false` leaves a task's outputs in place for a tool that reads its last output (tsc's `.tsbuildinfo`) and caches everything the outputs then hold, leftovers included (an opt-out of the clean-tree guarantee). no post
 - **Outputs are exactly the snapshot** (`run.rules.exclusiveOutputs`, `VX_RUN_RULES_EXCLUSIVE_OUTPUTS`) — a hit leaves the tree as the run did; two tasks may not own one output without an edge. [page](https://vznjs.github.io/vx/features/strict-outputs/) · post: [The tree is exactly the snapshot](https://vznjs.github.io/vx/blog/strict-output-ownership/)
 - **Keys from git's index** — tracked clean files hash by their blob id, no read. [page](https://vznjs.github.io/vx/features/keys-from-git/) · post: [Your cache key is already in git's index](https://vznjs.github.io/vx/blog/keys-from-git/)
 - **Config keyed as evaluated** — the key sees the resolved config object. [page](https://vznjs.github.io/vx/features/typescript-config/) · post: [Configs are programs](https://vznjs.github.io/vx/blog/resolved-config-hashing/)
@@ -91,7 +88,7 @@ config key or an environment variable is missing here.
 - **Lockfile-aware keys** (`@vzn/vx-lockfile`: `pnpm()`, `bun()`, `npm()`, `yarn()`) — a bump re-keys only the projects whose closure changed; each also adds every member with a `package.json` as a project named by its `name`, gives vx the project edges the lockfile records (core reads no `package.json`), keys each package's `package.json` as an input and folds its manager's install settings (`.npmrc`, `bunfig.toml`, `pnpm-workspace.yaml`, `.yarnrc.yml`) into every task. Core keys no package file, so without one an install re-keys nothing; `npm()` reads `npm-shrinkwrap.json` first, and `bun()` refuses a lone `bun.lockb`. [page](https://vznjs.github.io/vx/features/lockfile-keys/) · post: [A lockfile bump should re-key two tasks](https://vznjs.github.io/vx/blog/lockfile-aware-keys/)
 - **Upfront keys** (`run.rules.upfrontKeys`, `VX_RUN_RULES_UPFRONT_KEYS`) — refuses an input glob a same-project task's outputs could match, so every key is known before anything runs. [page](https://vznjs.github.io/vx/features/upfront-keys/) · post: [Cascade through dependencies by folding input keys, never outputs](https://vznjs.github.io/vx/blog/cascade-through-inputs/)
 - **Dependency rules** (`run.rules.dependencies`) — `vx lock` refuses a project depending on one a tag or name rule denies or does not allow, every broken edge named (`VX_E_DEPENDENCY_RULE`). [schema](https://vznjs.github.io/vx/schema/) · post: [Say which projects may depend on which](https://vznjs.github.io/vx/blog/dependency-rules/)
-- **Cache controls** (`--no-cache`, `--force`, `--cache-policy`, `--cache-policy`, `VX_CACHE_POLICY`, `cache.policy`) — off, refresh, or per-layer read/write. [page](https://vznjs.github.io/vx/features/cache-controls/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
+- **Cache controls** (`--no-cache`, `--force`, `--cache-policy`, `--cache-policy`, `VX_CACHE_POLICY`, `cache.policy`) — off, re-run past it, or per-layer read/write. [page](https://vznjs.github.io/vx/features/cache-controls/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache location** (`--cache-dir`, `cache.dir`, `VX_CACHE_DIR`) — where the cache lives. [page](https://vznjs.github.io/vx/features/cache-location/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache scope** (`cache.scope`, `VX_CACHE_SCOPE`, `--cache-scope`) — a scope reads the default entries, then its own, and writes only its own. [page](https://vznjs.github.io/vx/features/cache-scope/) · post: [The cache on your terms](https://vznjs.github.io/vx/blog/the-cache-on-your-terms/)
 - **Cache pruning** (`vx cache clean`, `--older-than`, `--max-size`, `--global`, `--dry-run`, `cache.retention`, `maxSize`, `olderThan`, `VX_CACHE_RETENTION_MAX_SIZE`, `VX_CACHE_RETENTION_OLDER_THAN`) — evict by age or size, LRU; with no bound, clear this repo's store (shared by its checkouts) and run history; `--global` clears every repo's store. [page](https://vznjs.github.io/vx/features/cache-prune/) · post: [One command to know your workspace](https://vznjs.github.io/vx/blog/know-your-workspace/)
@@ -101,7 +98,7 @@ config key or an environment variable is missing here.
 - **Hits replay both streams** — stdout and stderr come back in the order the run printed them. [page](https://vznjs.github.io/vx/features/both-streams/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Restore lane** — cache restores run on their own lane, up to twice `--concurrency`. [page](https://vznjs.github.io/vx/features/restore-lane/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Line-ending-correct keys** — files git filters (`eol`, `core.autocrlf`) key on the bytes the build sees. [page](https://vznjs.github.io/vx/features/line-endings/) · post: [Your cache key is already in git's index](https://vznjs.github.io/vx/blog/keys-from-git/)
-- **Background remote uploads** — remote writes drain at the end of the run and never fail the build. [page](https://vznjs.github.io/vx/features/background-uploads/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
+- **Background remote uploads** — remote writes drain at the end of the run and never fail the build; the footer counts them running (`⇡`) and failed (`✗`). [page](https://vznjs.github.io/vx/features/background-uploads/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Bring your own remote cache** (plugin `cache`) — plug any cache server in through one interface. [page](https://vznjs.github.io/vx/features/custom-remote-cache/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)
 
 ## Correctness
@@ -109,7 +106,7 @@ config key or an environment variable is missing here.
 - **Sandboxed tasks** (`exec.sandbox`: `allow`, `deny`, `ignore`, `weakerNetworkIsolation`, `weakerWhenNested`) — a task reads and writes only what it declares; `allow` names `read`, `write`, `network`, `unixSockets`, `localBinding`, `pty`, `systemInfo`, `gitConfig`, `machLookup`. [page](https://vznjs.github.io/vx/features/sandbox/) · post: [The sandbox](https://vznjs.github.io/vx/blog/the-sandbox/)
 - **Env isolation** (`exec.env`: `define`, `passThrough`, `secret`, `VX_DEBUG_DUMPABLE`) — a task sees only the env it names; secrets are masked; vx hides its own env from tasks (Linux and macOS). [page](https://vznjs.github.io/vx/features/env-isolation/) · post: [A task sees only the env it names](https://vznjs.github.io/vx/blog/env-isolation/)
 - **vx lock** (`vx lock`, `--check`, `--format json`, `lock.reviewFiles`, `VX_LOCK_REVIEW_FILES`) — find the projects (every directory holding a `vx.config`), freeze what their configs evaluate to and check the graph rules once; only `vx lock` evaluates configs: runs, `vx show` and `vx info` read the lock and never write it; a pretty `vx.lock.json` beside each config shows reviewers what it resolves to. [page](https://vznjs.github.io/vx/features/vx-lock/) · post: [vx lock: freezing what the key sees](https://vznjs.github.io/vx/blog/lock-and-frozen/)
-- **Flaky detection** — a task that fails then passes is reported flaky. [page](https://vznjs.github.io/vx/features/flaky-detection/) · post: [Flaky is a claim](https://vznjs.github.io/vx/blog/flaky-tasks/)
+- **Flaky detection** — a task whose key fails after it passed is reported flaky, judged on every worktree's record of the repo. [page](https://vznjs.github.io/vx/features/flaky-detection/) · post: [Flaky is a claim](https://vznjs.github.io/vx/blog/flaky-tasks/)
 - **Project boundaries** — globs never cross into another project. [page](https://vznjs.github.io/vx/features/project-boundaries/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Artifact integrity checks** — a CRC-32, a key match and an outputs-only check on every artifact; damage is a miss. [page](https://vznjs.github.io/vx/features/artifact-integrity/) · post: [What goes into a key, and what comes back](https://vznjs.github.io/vx/blog/inside-a-cache-hit/)
 - **Sandbox names what to grant** — a refused write is named beside the failed task with the path to allow. [page](https://vznjs.github.io/vx/features/sandbox-grants/) · post: [Guard rails that tell you the fix](https://vznjs.github.io/vx/blog/guard-rails/)
@@ -118,12 +115,12 @@ config key or an environment variable is missing here.
 
 ## Daily work
 
-- **Watch mode** (`vx watch`, `--poll`, `watch.poll`, `VX_WATCH_POLL`) — re-run what a change affects, on content, not events. [page](https://vznjs.github.io/vx/features/watch/) · post: [Watch: a content gate](https://vznjs.github.io/vx/blog/watch-mode/)
-- **Dev servers in the graph** (`exec.persistent`, `readyWhen`, `--ready-notice`, `run.readyNotice`, `VX_RUN_READY_NOTICE`) — a server is a node; dependents start when it is ready. [page](https://vznjs.github.io/vx/features/dev-servers/) · post: [Dev servers as graph nodes](https://vznjs.github.io/vx/blog/dev-servers-in-the-graph/)
+- **Watch mode** (`vx watch`, `--poll`, `watch.poll`, `VX_WATCH_POLL`, `VX_DEBUG_WATCH`) — re-run what a change affects, on content, not events. [page](https://vznjs.github.io/vx/features/watch/) · post: [Watch: a content gate](https://vznjs.github.io/vx/blog/watch-mode/)
+- **Dev servers in the graph** (`exec.persistent`, `readyWhen`) — a server is a node; dependents start when it is ready. [page](https://vznjs.github.io/vx/features/dev-servers/) · post: [Dev servers as graph nodes](https://vznjs.github.io/vx/blog/dev-servers-in-the-graph/)
 - **Interactive tasks** (`exec.interactive`) — a task that owns the terminal. [page](https://vznjs.github.io/vx/features/interactive-tasks/) · post: [When a task misbehaves](https://vznjs.github.io/vx/blog/tasks-that-misbehave/)
 - **Shell completions** (`vx completions`) — bash, zsh, fish. [page](https://vznjs.github.io/vx/features/completions/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Project-local vx** (`VX_HANDED_OFF`) — a global vx hands every call to the project's own `@vzn/vx`. [page](https://vznjs.github.io/vx/cli/#which-vx-runs)
-- **vx upgrade** (`vx upgrade`) — upgrade vx the way it was installed: a verified binary, or its package manager. [page](https://vznjs.github.io/vx/features/upgrade/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
+- **vx upgrade** (`vx upgrade`) — upgrade vx the way it was installed: a verified binary, or its package manager. Inside a project, the project's vx and the global vx that ran it move together. [page](https://vznjs.github.io/vx/features/upgrade/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
 - **Help and version** (`vx help`, `vx version`) — every verb's reference. [page](https://vznjs.github.io/vx/features/help-and-version/) · post: [An upgrade you can trust](https://vznjs.github.io/vx/blog/upgrade-you-can-trust/)
 - **Did-you-mean** — a mistyped flag or verb gets the nearest valid spelling. [page](https://vznjs.github.io/vx/features/did-you-mean/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
 - **Task typed as a verb** — `vx build app` answers with the exact `vx run` command that does it. [page](https://vznjs.github.io/vx/features/task-as-verb/) · post: [The small things](https://vznjs.github.io/vx/blog/the-small-things/)
@@ -169,7 +166,7 @@ config key or an environment variable is missing here.
 - **Remote cache and execution** (`@vzn/vx-reapi`, `exec.remote`) — Bazel REAPI cache and workers; the scheduler stays here. [page](https://vznjs.github.io/vx/features/remote-execution/) · post: [Remote execution without moving the scheduler](https://vznjs.github.io/vx/blog/remote-execution/)
 - **OpenTelemetry** (`@vzn/vx-otel`) — each run exported to your OpenTelemetry backend, never breaking it. [page](https://vznjs.github.io/vx/features/opentelemetry/) · post: [Observability that cannot break a run](https://vznjs.github.io/vx/blog/telemetry-never-breaks-a-run/)
 - **vx history** (`@vzn/vx-schedule-history`, `vx history`) — what the scheduler learned per task. [page](https://vznjs.github.io/vx/features/vx-history/) · post: [A scheduler that learns from your runs](https://vznjs.github.io/vx/blog/a-scheduler-that-learns/)
-- **Setup and teardown hooks** (`setup`, `teardown`) — plugin code around the run, bounded by a timeout. [page](https://vznjs.github.io/vx/features/setup-teardown/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)
+- **Setup and teardown hooks** (`setup`, `teardown`, `RunReport`, `ctx.cache.getRun`) — plugin code around the run, bounded by a timeout; on a run that writes a remote, vx keeps failed tasks' logs and outputs and uncached tasks' logs there, and `teardown` gets the run, its CI job and every task with the names to read them by, which a plugin verb reads back through its read-only `ctx.cache`. [page](https://vznjs.github.io/vx/features/setup-teardown/) · post: [Extend vx in an afternoon](https://vznjs.github.io/vx/blog/extend-vx/)
 - **REAPI TLS, mTLS and headers** — connect to hosted servers such as BuildBuddy the way Bazel does. [page](https://vznjs.github.io/vx/features/reapi-tls/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
 - **REAPI execution records** — a repeat remote execution skips the worker and replays outputs and stdout. [page](https://vznjs.github.io/vx/features/reapi-action-cache/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
 - **REAPI verified downloads and deadlines** — a corrupt blob or a wedged server degrades to a miss, never a hang. [page](https://vznjs.github.io/vx/features/reapi-safety/) · post: [A remote server you can trust in production](https://vznjs.github.io/vx/blog/reapi-in-production/)
@@ -177,3 +174,4 @@ config key or an environment variable is missing here.
 - **OTel live export** (`otel({ live })`) — spans and metrics stream as tasks end, so a dashboard follows a CI run live. [page](https://vznjs.github.io/vx/features/otel-live/) · post: [Watch a CI run while it runs](https://vznjs.github.io/vx/blog/otel-live/)
 - **Memory-aware admission** (`@vzn/vx-schedule-history`) — tasks are packed by the peak memory learned from past runs. [page](https://vznjs.github.io/vx/features/memory-admission/) · post: [A scheduler that learns from your runs](https://vznjs.github.io/vx/blog/a-scheduler-that-learns/)
 - **CI timings file** (`@vzn/vx-schedule-history`, `file`) — one JSON file of learned task times a CI cache carries between runners, so a fresh runner orders by real times. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Carry the scheduler's memory between CI runners](https://vznjs.github.io/vx/blog/ci-timings-file/)
+- **Shared timings** (`@vzn/vx-schedule-history`, `defaultBranch`) — CI on the default branch writes task timings to the remote cache; a branch with none imports its merge-base's. Plugins keep their own entries there through `ctx.cache`. [page](https://vznjs.github.io/vx/features/critical-path/)

package/docs/patterns.md

@@ -161,19 +161,17 @@ Turbo-aware cache server can transit our blobs unchanged.
 | `--concurrency <n>`                                                                | Turbo          | `src/cli/run.ts`                    |
 | `--no-cache` (all off) / `--force` (reads off, writes on) — distinct, not synonyms | Turbo-adjacent | `src/cli/run.ts`                    |
 | `--dry` / `--dry=json` (plan output)                                               | Turbo          | `src/orchestrator/plan.ts`          |
-| `--graph[=<path>]` (DOT)                                                           | Turbo + Nx     | `src/cli/plan-format.ts`            |
-| `--summarize[=<path>]` (per-run JSON)                                              | Turbo          | `src/orchestrator/run-artifacts.ts` |
 | `--profile[=<path>]` (Chrome-trace)                                                | Turbo          | `src/orchestrator/run-artifacts.ts` |
 | `--affected[=<base>]`                                                              | Turbo + Nx     | `src/workspace/affected.ts`         |
 | `watch <task>` subcommand                                                          | Turbo + Nx     | `src/cli/watch.ts`                  |
 
 ### Output presentation
 
-| Pattern                                              | Source                                           | vx source                                           |
-| ---------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------- |
-| Framed per-task blocks (`┌─ … └─`)                   | Turbo                                            | `src/orchestrator/framed-output.ts`                 |
-| End-of-run summary footer (task/cache meters + time) | Turbo-adjacent (vx renders meters, not a banner) | `src/orchestrator/summary.ts`                       |
-| Per-task output buffered until task finishes         | Turbo                                            | `src/orchestrator/framed-output.ts` ("Turbo-style") |
+| Pattern                                              | Source                                           | vx source                                     |
+| ---------------------------------------------------- | ------------------------------------------------ | --------------------------------------------- |
+| Framed per-task blocks (`┌─ … └─`)                   | Turbo                                            | `src/report/framed-output.ts`                 |
+| End-of-run summary footer (task/cache meters + time) | Turbo-adjacent (vx renders meters, not a banner) | `src/report/summary.ts`                       |
+| Per-task output buffered until task finishes         | Turbo                                            | `src/report/framed-output.ts` ("Turbo-style") |
 
 (There is no `>>> FULL TURBO`-style all-cached banner — a fully-green
 cache meter carries the message.)

package/docs/schema.md

@@ -376,7 +376,7 @@ for it to exit. Instead it considers the task "ready":
   The trailing partial line is tested too, so prompt-style banners
   without a newline (`printf 'Listening on :3000'`) count, and so does
   output read up to 250 ms after the shell exits. A server
-  not ready after 10 s (`run.readyNotice`) is said once, naming
+  not ready after 10 s is said once, naming
   the pattern it waits for, and whether `exec.timeout` bounds the wait.
 
 ```ts
@@ -609,7 +609,7 @@ replays, the command a cache entry stores (what `vx why` prints and a
 remote cache receives), the `$ command` line, telemetry records,
 `vx show`, the hashes `vx why` gives for such a variable in
 `cache.inputs.env` (its value, unsalted: the row names it and its change), an executor's error, a plugin's warning or failure (a remote's reply; the failure masked in the error `run()` rejects with), a failed `cache.inputs` runtime probe's error (its command and output), and the run's own invocation line that `vx last` prints (a
-secret passed after `--`) and its `--tag`s. So are every string of a
+secret passed after `--`). So are every string of a
 task `vx show` prints (a runtime probe, `readyWhen`, the description),
 the description `--dry` and the task picker print, a runtime probe's
 command as the run history stores it and `vx why` names its row (two
@@ -676,8 +676,8 @@ Semantics:
   edge from a `package.json`) and the cross-project `pkg#task` edges.
   With no plugin returning `deps` the workspace has no edge source and
   a `'^name'` is refused (`VX_E_DEPENDS_ON`: "`^build` needs project
-  edges; add pnpm()/bun()/npm()/yarn() or a plugin that returns
-  `deps`"): it would resolve to nothing and fold no upstream into the
+  edges; add pnpm()/bun()/npm()/yarn() and install so its lockfile
+  exists, or a plugin that returns `deps`"): it would resolve to nothing and fold no upstream into the
   key. With one, a project with no deps is a leaf; each path stops at the first dep
   that declares the task and an edge is added to it (Turbo/Nx
   direct-deps parity). The holder's own `dependsOn` is responsible
@@ -881,7 +881,7 @@ lockfile change when a lockfile plugin (`@vzn/vx-lockfile`) is declared.
 Always applied to every glob pass (regardless of what you wrote):
 
 - **gitignore filter** — workspace-root + project `.gitignore`.
-- **Always-ignored** — `.git/**`, `.vx/cache/**`, `*.tsbuildinfo`,
+- **Always-ignored** — `.git/**`, `.vx/cache/**`,
   `.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, and Bun's cross-compile extraction
   directory `.<16 hex>-<8 hex>.tmp/**`, and vx's own restore temp
   `.vx-tmp-*`, at any depth.
@@ -892,8 +892,8 @@ Always applied to every glob pass (regardless of what you wrote):
   itself via its own output. A path an output `!` entry takes back is
   no output, so it stays an input (A-44). Another task's outputs are
   not excluded for you: an input glob that can match them is refused
-  while `rules.upfrontKeys` is on (X-54). Write the exclusion,
-  `['**/*', '!dist/**']`. An input entry the task's OWN outputs take
+  while `rules.upfrontKeys` is on (X-54), unless git ignores them
+  whole. Write the exclusion, `['**/*', '!dist/**']`, or ignore `dist/`. An input entry the task's OWN outputs take
   back whole is always refused (X-55): vx removes outputs before a run,
   so a formatter declaring `src/**` as both would delete its sources. A
   task that rewrites files in place declares no outputs.
@@ -937,7 +937,7 @@ backslash separator (`src\**`, `src\*.ts`) or a drive (`C:\src\**`,
 backslash stays an escape.
 
 Still applied: the always-ignored set (`.git/**`, `.vx/cache/**`,
-`*.tsbuildinfo`, `.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, `.<16 hex>-<8 hex>.tmp/**`, `.vx-tmp-*`),
+`.vx/projects.lock.json`, `vx.lock.json`, `*.bun-build`, `.<16 hex>-<8 hex>.tmp/**`, `.vx-tmp-*`),
 untracked files under `node_modules/`, and the task's own declared
 outputs, `outputs.workspaceFiles` and the `outputs.files` its globs reach
 in its own project (a task never invalidates itself).
@@ -1186,10 +1186,10 @@ run is a no-op too.
 
 **`clean: false`** keeps the outputs on a miss instead of wiping them
 first, for a tool that reads its own last output (tsc's
-`.tsbuildinfo`). An entry still holds only what a clean run would
-leave: if the run leaves any old file unchanged, nothing is cached, and
-the next run executes again. A retry still starts clean, and a hit
-still restores bit-identically. Omitted → the workspace's
+`.tsbuildinfo`). It opts out of the clean-tree guarantee: the save
+stores every file the outputs match after the run, so a file an older
+build left behind is cached and restored on every machine. A retry
+still starts clean, and a hit still restores bit-identically. Omitted → the workspace's
 `cache.outputs.clean`, else `true`.
 
 A **`!` entry takes a path back** from what the positive globs select
@@ -1259,7 +1259,11 @@ and so are `dist//**` and `dist/./app.js` (item 441) — and a literal
 entry is read as the file OR its whole tree, the same rule the resolver
 uses, so `dist` collides with `dist/app.js` (item 442). A whole subtree
 collides with any glob whose literal head lies inside it: `dist/**` with
-`dist/extra/**` or `dist/*.js` (item 941). Globs that only _might_
+`dist/extra/**` or `dist/*.js` (item 941). Two globs a path built from
+either one matches are one too: `**/*` and `**/dist/**` both match
+`x/dist/x`. A pair is no overlap where one task's `!` output entry
+takes the other's glob back whole: `['**/dist', '!types/**']` beside
+`types/**` (a `!` entry is never cleaned or captured). Globs that only _might_
 overlap (`dist/*` and `dist/sub/**`) are let through; there, last
 restore wins. A workspace output is also compared with every other
 project's `files` outputs, read from the root: `packages/b/dist/a.txt`
@@ -1642,9 +1646,6 @@ export default defineWorkspace({
     affectedBase: 'origin/main',
     schedule: 'most-work',
     continue: 'deps-ok',
-    killGrace: '2s',
-    teardownTimeout: '3s',
-    readyNotice: '10s',
     rules: {
       exclusiveOutputs: true,
       upfrontKeys: true,
@@ -1676,7 +1677,7 @@ task's value over all of them; the input-stability variables are the one
 exception, overriding every task for the run. A duration carries its
 unit (`'500ms'`, `'30s'`, `'10m'`, `'2h'`, `'30d'`), and a bare number is
 refused naming the forms with units; a size carries one too (`'10GB'`).
-`debug.timing`, `debug.dumpable`, `config.workerTimeout` and `run.outputLogs` are read
+`debug.timing`, `debug.watch`, `debug.dumpable`, `config.workerTimeout` and `run.outputLogs` are read
 before the workspace loads, so they have a variable (and a flag) only.
 None is folded into a cache key. `vx info` lists every setting not at its
 default and where it came from.
@@ -1685,35 +1686,33 @@ default and where it came from.
 
 <!-- settings table: generated by tests/settings.test.ts -->
 
-| Setting                                        | Variable                            | Flag                 | Value                                                                   | Default                                    | What it does                                                                                                                                        |
-| ---------------------------------------------- | ----------------------------------- | -------------------- | ----------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `run.concurrency`                              | `VX_RUN_CONCURRENCY`                | `--concurrency`      | a positive integer, or a share of the cores like '50%'                  | the cores this process may use             | Tasks at once: a positive integer, or a share of the cores (`'50%'`).                                                                               |
-| `run.schedule`                                 | `VX_RUN_SCHEDULE`                   | `--schedule`         | one of 'most-work', 'critical-path', 'direct-dependents', 'ready-order' | most-work                                  | Which ready task starts first when there are more than workers.                                                                                     |
-| `run.affectedBase`                             | `VX_RUN_AFFECTED_BASE`              | —                    | a non-blank string                                                      | origin/HEAD, then the trunk, else HEAD~1   | The git ref a bare `--affected` compares with.                                                                                                      |
-| `run.branch` (variable or flag only)           | `VX_RUN_BRANCH`                     | `--branch`           | a non-blank string                                                      | git's branch, then the CI provider's       | The branch a run records in its history and forecasts from. Flag and env only: a committed branch would be wrong on every other branch.             |
-| `run.timeout`                                  | `VX_RUN_TIMEOUT`                    | `--timeout`          | a duration like '500ms', '30s' or '5m', at most 24 days                 | none                                       | A task's time limit, for tasks without their own `exec.timeout` (`'30m'`). A task's own `exec.timeout` beats it.                                    |
-| `run.retries`                                  | `VX_RUN_RETRIES`                    | `--retries`          | a non-negative integer                                                  | 0                                          | Re-runs of a failed task, for tasks without their own `exec.retries`. A task's own `exec.retries` beats it.                                         |
-| `run.continue`                                 | `VX_RUN_CONTINUE`                   | `--continue`         | one of 'never', 'deps-ok', 'always'                                     | deps-ok                                    | What a failed task takes down: `never` stops the run, `deps-ok` skips its dependents, `always` runs them too.                                       |
-| `run.outputLogs` (variable or flag only)       | `VX_RUN_OUTPUT_LOGS`                | `--output-logs`      | one of 'full', 'errors-only', 'hash-only', 'none'                       | `full` on CI, else by what the run selects | Which task output the run prints. Chosen before the workspace loads, so flag and env only.                                                          |
-| `run.killGrace`                                | `VX_RUN_KILL_GRACE`                 | `--kill-grace`       | a duration like '500ms', '30s' or '5m', at most 24 days                 | 2s                                         | How long a task that ignores SIGTERM gets before SIGKILL.                                                                                           |
-| `run.teardownTimeout`                          | `VX_RUN_TEARDOWN_TIMEOUT`           | `--teardown-timeout` | a duration like '500ms', '30s' or '5m', at most 24 days                 | 3s                                         | The bound on each plugin's end-of-run flush and teardown.                                                                                           |
-| `run.readyNotice`                              | `VX_RUN_READY_NOTICE`               | `--ready-notice`     | a duration like '500ms', '30s' or '5m', at most 24 days                 | 10s                                        | How long a persistent task may take to match `readyWhen` before vx says it waits.                                                                   |
-| `run.rules.exclusiveOutputs`                   | `VX_RUN_RULES_EXCLUSIVE_OUTPUTS`    | —                    | true or false                                                           | true                                       | Refuse two tasks whose outputs overlap even when an edge orders them.                                                                               |
-| `run.rules.upfrontKeys`                        | `VX_RUN_RULES_UPFRONT_KEYS`         | —                    | true or false                                                           | true                                       | Refuse a task whose inputs can match another task's outputs.                                                                                        |
-| `cache.dir`                                    | `VX_CACHE_DIR`                      | `--cache-dir`        | a non-blank string                                                      | .vx/cache, entries in ~/.vx/<repo>/cache   | Where the cache lives, relative to the workspace root; named, it holds the whole cache.                                                             |
-| `cache.retention.maxSize`                      | `VX_CACHE_RETENTION_MAX_SIZE`       | —                    | a size like '500MB' or '10GB'                                           | none                                       | Evict least-recently-used entries at each run's end until the cache is under this (`'10GB'`).                                                       |
-| `cache.retention.olderThan`                    | `VX_CACHE_RETENTION_OLDER_THAN`     | —                    | a duration like '45s', '12h' or '30d'                                   | none                                       | Evict entries unused for this long at each run's end (`'30d'`).                                                                                     |
-| `cache.policy`                                 | `VX_CACHE_POLICY`                   | `--cache-policy`     | a non-blank string                                                      | every layer reads and writes               | Which layers a run reads and writes (`'local:rw,remote:r'`); `--no-cache` and `--force` apply on top.                                               |
-| `cache.scope`                                  | `VX_CACHE_SCOPE`                    | `--cache-scope`      | a non-blank string                                                      | none (the default keys)                    | Where cache writes land (`'pr-123'`): reads try the default key, then the scope's.                                                                  |
-| `cache.download`                               | `VX_CACHE_DOWNLOAD`                 | `--cache-download`   | one of 'all', 'toplevel', 'none'                                        | all                                        | Which remote hits land on disk: every one, only the requested tasks, or none.                                                                       |
-| `cache.inputStability.strategy`                | `VX_CACHE_INPUT_STABILITY_STRATEGY` | —                    | one of 'immutable', 'mutable', 'unchecked'                              | immutable                                  | What a write to an input during the command means for the save, for tasks without their own. A task's own `cache.inputStability.strategy` beats it. |
-| `cache.inputStability.severity`                | `VX_CACHE_INPUT_STABILITY_SEVERITY` | —                    | one of 'warn', 'error'                                                  | warn                                       | Whether a skipped save warns or fails the task, for tasks without their own. A task's own `cache.inputStability.severity` beats it.                 |
-| `cache.outputs.clean`                          | `VX_CACHE_OUTPUTS_CLEAN`            | —                    | true or false                                                           | true                                       | Remove a task's declared outputs before it runs on a miss, for tasks without their own. A task's own `cache.outputs.clean` beats it.                |
-| `lock.reviewFiles`                             | `VX_LOCK_REVIEW_FILES`              | —                    | true or false                                                           | true                                       | `vx lock` writes each project's resolved config, pretty, to `vx.lock.json` beside its `vx.config`, for review; vx never reads it.                   |
-| `watch.poll`                                   | `VX_WATCH_POLL`                     | `vx watch --poll`    | true or false                                                           | false                                      | Poll for changes from the start instead of the OS watcher.                                                                                          |
-| `config.workerTimeout` (variable or flag only) | `VX_CONFIG_WORKER_TIMEOUT`          | —                    | a duration like '500ms', '30s' or '5m', at most 24 days                 | 30s                                        | How long one config evaluation may take.                                                                                                            |
-| `debug.timing` (variable or flag only)         | `VX_DEBUG_TIMING`                   | —                    | true or false                                                           | false                                      | Print the run's stage timings to stderr.                                                                                                            |
-| `debug.dumpable` (variable or flag only)       | `VX_DEBUG_DUMPABLE`                 | —                    | true or false                                                           | false                                      | Linux: keep vx dumpable, so strace or a debugger can read its memory and `/proc/<pid>/fd`, and an unsandboxed task its env.                         |
+| Setting                                        | Variable                            | Flag               | Value                                                                   | Default                                    | What it does                                                                                                                                        |
+| ---------------------------------------------- | ----------------------------------- | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run.concurrency`                              | `VX_RUN_CONCURRENCY`                | `--concurrency`    | a positive integer, or a share of the cores like '50%'                  | the cores this process may use             | Tasks at once: a positive integer, or a share of the cores (`'50%'`).                                                                               |
+| `run.schedule`                                 | `VX_RUN_SCHEDULE`                   | `--schedule`       | one of 'most-work', 'critical-path', 'direct-dependents', 'ready-order' | most-work                                  | Which ready task starts first when there are more than workers.                                                                                     |
+| `run.affectedBase`                             | `VX_RUN_AFFECTED_BASE`              | —                  | a non-blank string                                                      | origin/HEAD, then the trunk, else HEAD~1   | The git ref a bare `--affected` compares with.                                                                                                      |
+| `run.branch` (variable or flag only)           | `VX_RUN_BRANCH`                     | `--branch`         | a non-blank string                                                      | git's branch, then the CI provider's       | The branch a run records in its history and forecasts from. Flag and env only: a committed branch would be wrong on every other branch.             |
+| `run.timeout`                                  | `VX_RUN_TIMEOUT`                    | `--timeout`        | a duration like '500ms', '30s' or '5m', at most 24 days                 | none                                       | A task's time limit, for tasks without their own `exec.timeout` (`'30m'`). A task's own `exec.timeout` beats it.                                    |
+| `run.retries`                                  | `VX_RUN_RETRIES`                    | `--retries`        | a non-negative integer                                                  | 0                                          | Re-runs of a failed task, for tasks without their own `exec.retries`. A task's own `exec.retries` beats it.                                         |
+| `run.continue`                                 | `VX_RUN_CONTINUE`                   | `--continue`       | one of 'never', 'deps-ok', 'always'                                     | deps-ok                                    | What a failed task takes down: `never` stops the run, `deps-ok` skips its dependents, `always` runs them too.                                       |
+| `run.outputLogs` (variable or flag only)       | `VX_RUN_OUTPUT_LOGS`                | `--output-logs`    | one of 'full', 'errors-only', 'hash-only', 'none'                       | `full` on CI, else by what the run selects | Which task output the run prints. Chosen before the workspace loads, so flag and env only.                                                          |
+| `run.rules.exclusiveOutputs`                   | `VX_RUN_RULES_EXCLUSIVE_OUTPUTS`    | —                  | true or false                                                           | true                                       | Refuse two tasks whose outputs overlap even when an edge orders them.                                                                               |
+| `run.rules.upfrontKeys`                        | `VX_RUN_RULES_UPFRONT_KEYS`         | —                  | true or false                                                           | true                                       | Refuse a task whose inputs can match another task's outputs.                                                                                        |
+| `cache.dir`                                    | `VX_CACHE_DIR`                      | `--cache-dir`      | a non-blank string                                                      | .vx/cache, entries in ~/.vx/<repo>/cache   | Where the cache lives, relative to the workspace root; named, it holds the whole cache.                                                             |
+| `cache.retention.maxSize`                      | `VX_CACHE_RETENTION_MAX_SIZE`       | —                  | a size like '500MB' or '10GB'                                           | none                                       | Evict least-recently-used entries at each run's end until the cache is under this (`'10GB'`).                                                       |
+| `cache.retention.olderThan`                    | `VX_CACHE_RETENTION_OLDER_THAN`     | —                  | a duration like '45s', '12h' or '30d'                                   | none                                       | Evict entries unused for this long at each run's end (`'30d'`).                                                                                     |
+| `cache.policy`                                 | `VX_CACHE_POLICY`                   | `--cache-policy`   | a non-blank string                                                      | every layer reads and writes               | Which layers a run reads and writes (`'local:rw,remote:r'`); `--no-cache` and `--force` apply on top.                                               |
+| `cache.scope`                                  | `VX_CACHE_SCOPE`                    | `--cache-scope`    | a non-blank string                                                      | none (the default keys)                    | Where cache writes land (`'pr-123'`): reads try the default key, then the scope's.                                                                  |
+| `cache.download`                               | `VX_CACHE_DOWNLOAD`                 | `--cache-download` | one of 'all', 'toplevel', 'none'                                        | all                                        | Which remote hits land on disk: every one, only the requested tasks, or none.                                                                       |
+| `cache.inputStability.strategy`                | `VX_CACHE_INPUT_STABILITY_STRATEGY` | —                  | one of 'immutable', 'mutable', 'unchecked'                              | immutable                                  | What a write to an input during the command means for the save, for tasks without their own. A task's own `cache.inputStability.strategy` beats it. |
+| `cache.inputStability.severity`                | `VX_CACHE_INPUT_STABILITY_SEVERITY` | —                  | one of 'warn', 'error'                                                  | warn                                       | Whether a skipped save warns or fails the task, for tasks without their own. A task's own `cache.inputStability.severity` beats it.                 |
+| `cache.outputs.clean`                          | —                                   | —                  | true or false                                                           | true                                       | Remove a task's declared outputs before it runs on a miss, for tasks without their own. A task's own `cache.outputs.clean` beats it.                |
+| `lock.reviewFiles`                             | `VX_LOCK_REVIEW_FILES`              | —                  | true or false                                                           | true                                       | `vx lock` writes each project's resolved config, pretty, to `vx.lock.json` beside its `vx.config`, for review; vx never reads it.                   |
+| `watch.poll`                                   | `VX_WATCH_POLL`                     | `vx watch --poll`  | true or false                                                           | false                                      | Poll for changes from the start instead of the OS watcher.                                                                                          |
+| `config.workerTimeout` (variable or flag only) | `VX_CONFIG_WORKER_TIMEOUT`          | —                  | a duration like '500ms', '30s' or '5m', at most 24 days                 | 30s                                        | How long one config evaluation may take.                                                                                                            |
+| `debug.timing` (variable or flag only)         | `VX_DEBUG_TIMING`                   | —                  | true or false                                                           | false                                      | Print the run's stage timings to stderr.                                                                                                            |
+| `debug.watch` (variable or flag only)          | `VX_DEBUG_WATCH`                    | —                  | true or false                                                           | false                                      | `vx watch`: say on stderr each time the loop arms, with the projects it watches.                                                                    |
+| `debug.dumpable` (variable or flag only)       | `VX_DEBUG_DUMPABLE`                 | —                  | true or false                                                           | false                                      | Linux: keep vx dumpable, so strace or a debugger can read its memory and `/proc/<pid>/fd`, and an unsandboxed task its env.                         |
 
 <!-- /settings table -->
 
@@ -1734,9 +1733,6 @@ interface RunSettings {
   timeout?: Duration
   retries?: number
   continue?: 'never' | 'deps-ok' | 'always'
-  killGrace?: Duration
-  teardownTimeout?: Duration
-  readyNotice?: Duration
   /** Graph rules `vx lock` checks, never a run; each on unless set to false. */
   rules?: { exclusiveOutputs?: boolean; upfrontKeys?: boolean; dependencies?: DependencyRule[] }
 }
@@ -1774,11 +1770,6 @@ interface CacheSettings {
 - **`run.continue`** — what a failed task takes down: `never` stops
   dispatch, `deps-ok` (the default) skips its dependents, `always` runs
   them (`docs/cli.md` § Failure propagation).
-- **`run.killGrace`**, **`run.teardownTimeout`**, **`run.readyNotice`**
-  — the SIGTERM → SIGKILL grace (2 s), the bound on each plugin's
-  end-of-run flush and teardown (3 s; there is no "no limit"), and how
-  long a persistent task may wait for `readyWhen` before vx says what it
-  waits for (10 s).
 - **`run.rules`** — checked by `vx lock` and `vx lock --check` only;
   no run checks them.
 - **`cache.dir`** — unset, the workspace keeps its index and history in
@@ -1904,7 +1895,17 @@ false in .vx/workspace.ts to let it wait for its producer.` Such a key
     the schedule (`caching.md` § Local restore tier). The upstream's key
     already reaches the reader through `dependsOn`. A `!` entry that
     takes the whole output back clears it, and an output the reader's
-    `!` entries take back no longer holds its key back either. A task's
+    `!` entries take back no longer holds its key back either. Nor does
+    an output git ignores whole: a key reads only what git lists, so
+    `**/*` beside a gitignored `**/dist/**` passes and keys up front. Git
+    is asked, never a `.gitignore` read: `git check-ignore` on the
+    output's directory (for `**/dist/**`, `dist/` and a fresh
+    `__vx_probe__/dist/`), and no tracked or listed file may match it,
+    so a tracked output is still refused. A glob no few paths stand for
+    (`*.js`) is refused as before. `vx lock` asks once for every
+    overlapped output; a run asks once beside its git walk for the
+    stability gate, so a rule changed after the lock keys the reader
+    late until the next `vx lock` refuses it. A task's
     own outputs, a task with no `cache`, and a group are exempt. Off,
     the key waits for its producer, as before.
   - **`dependencies`** — which workspace projects a project may depend
@@ -2263,16 +2264,22 @@ opens it on click), and the lines up to it with a caret under the field
 (`util/config-frame.ts`):
 
 ```
-vx: packages/b/vx.config.ts:4:15: tasks.build.exec has unknown field "comand" (allowed: …) — did you mean command?
+✗ vx lock  lock not written
 
-  2 |   tasks: {
-  3 |     build: {
-> 4 |       exec: { comand: 'mkdir -p dist' },
-    |               ^
+  packages/b/vx.config.ts:4:15
+  tasks.build.exec has unknown field "comand"
+  allowed: …
+
+    2 |   tasks: {
+    3 |     build: {
+  > 4 |       exec: { comand: 'mkdir -p dist' },
+      |               ^
+
+  fix  use command
 ```
 
 A field the file does not hold (a required one missing, or one a plugin
-set) prints the one line as before. The table below lists the messages
+set) prints without the frame. The table below lists the messages
 a user meets most:
 
 | Symptom                                                                                                                               | Cause                                                                                                                                                                                                                          |