fun_ci 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8de275f366537fcf143b9dccdd10002a9cbff42632ab7e2549b695b4a3ba6240
-  data.tar.gz: 8723aee6ea508e2f9bf44c59cb717a83a08dc60381f389550f714b0b0f0de722
+  metadata.gz: 8c32c8feba3da028e17991565e2221423f97cab25535eb940667306b8f21205b
+  data.tar.gz: 83ec5dc09376e04feb8d08e7d863c6a574c2814754e9e57f3745d8719d4fb01e
 SHA512:
-  metadata.gz: f4122b18c73b6434eedbe7124fa19b79c64b03fce502a34fdc978aa0d97006091477495d6d9ccfe1cb3ca8eba8be0fa9d53341d328a3bd20ecff43e00c482ddc
-  data.tar.gz: fde4e5346d6bb6038ad35137456a6b1188a61c16f75973e9a55e44b73bc751afed551e1ea063a6a58a38adfbde4eefc1919297d870810ec8ddadfabd6106ce38
+  metadata.gz: 352c02313f711498642a148a7639e559ab4c1dbbd92c12f3c83f6a1cefd78263545c617428c0293ab5c2da4e6f2b70984f6bbe8db402538c84bb3d243cce6314
+  data.tar.gz: 6d873b080a2d5417b046aab0516cb116a92ae705b72207ab634b14196d8d18856540411f864bd424c1eb995d34018b89a07e7059eef47f1eeacdf4a5851b2088

data/CHANGELOG.md

@@ -5,6 +5,247 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [2.0.0] - 2026-09-29
+
+fun-ci 2.0 has two ways in. People watch a new console, drawn by a Rust
+renderer in 24-bit colour, with a scene for each milestone a run passes. Coding
+agents and scripts ask with new commands (`status`, `wait`, `why`, `runs`,
+`events`) that answer with exit codes and keep enough of each failure to say
+why it failed without running the suite again. Pipelines now run in git
+worktrees at the commit they test, started after the commit rather than
+before it. See "Upgrading to 2.0" in the README.
+
+### Changed
+- The hook that runs a pipeline in the background is now `post-commit`, so it
+  tests the commit you just made; the `pre-commit` hook tested the commit
+  before it. `fun-ci install-hooks` writes `post-commit` and `pre-push`, and
+  removes the `pre-commit` hook fun-ci 1.x wrote. A `pre-commit` hook of your
+  own is left alone, and if it still calls fun-ci, `fun-ci check` warns you
+  to take that out. Run `fun-ci install-hooks` again to update your hooks;
+  until you do, `fun-ci check` warns that each run tests the commit before
+  yours.
+- The pre-push hook waits for the fast verdict of each commit the push sends
+  (`fun-ci wait SHA --need fast`) instead of running the pipeline again, so a
+  push after a finished post-commit run goes through at once. It reads the
+  commits from what git passes it, so pushing a branch other than the one
+  checked out tests the right commits.
+- Every pipeline runs in a git worktree of its own, checked out at the commit
+  it tests, under `.git/fun-ci/worktrees/`. Before, the stages ran in your
+  checkout while you kept editing it. Ignored files such as `vendor/bundle`
+  stay in a worktree from one run to the next. The stage scripts come from
+  the commit too, unless it has no `.fun-ci/`, in which case the checkout's
+  are used. Two pipelines run at once by default; set `worktree_slots: 3` (or
+  any number above 0) in `.fun-ci/config` for more.
+- fun-ci keeps its database in `$XDG_STATE_HOME/fun-ci/`, or
+  `~/.local/state/fun-ci/` without it, instead of under `$TMPDIR`, so every
+  process of a user finds the same database, including an agent in a sandbox
+  with a `TMPDIR` of its own. Runs recorded by 1.x are not carried over. The
+  state directory is readable by its user alone (0700).
+- A newer commit cancels an older unfinished run on its branch only in its own
+  project, never a run an agent is waiting on, and never a run of the same
+  commit.
+- `fun-ci console` is drawn by a separate program, `fun-ci-renderer`, written
+  in Rust. The gems for Linux (x86_64, aarch64, musl) and macOS (arm64,
+  x86_64) include it. Elsewhere, install it with `cargo install
+  fun-ci-renderer` or point `FUN_CI_RENDERER` at a copy you built; without
+  it, `console` says so and every other command works as before. What goes
+  wrong between the two ends up in `.fun-ci/console.log`, since the renderer
+  owns the terminal.
+- The console's header is a picture rather than ASCII art: soft light,
+  gradients and particles in 24-bit colour across the whole width, or the
+  nearest of 256 colours when `COLORTERM` doesn't say `truecolor` or `24bit`.
+  Only the parts that change are sent to the terminal.
+- The header plays a scene for each milestone a run passes, each milestone
+  with scenes of its own, so you can tell which it was without reading: a teal
+  sweep, ripple or spirit level for lint; amber blocks, gears or a ringing
+  anvil for the build; a lightning strike, YAY or a jump to warp speed for the
+  fast suite; fireworks, a trophy, dancing leprechauns or a sunrise for the
+  whole run; an explosion or shattering glass for a failure. Scenes queue and
+  each plays to its end, so a failure no longer cuts a celebration short, and
+  a run gets one failure scene however many of its stages fail.
+- When the scenes are done, the header rests on how the latest run went: a
+  calm dusk with a tick after a pass, a pulsing hazard sign after a failure.
+  Five minutes after the latest run finished it goes quiet: a starry night,
+  an aurora, fireflies, a fire in a medieval stone hearth with a storm at the
+  window, a moonlit island with a palm, or snowfall over pines, a different
+  one every five minutes while nothing runs, with a small lamp in the corner
+  that stays green after a pass and flickers red after a failure. The streak
+  ("7 in a row!", or "streak broken") sits in the top right.
+- The console's board fits the terminal's height and scrolls to keep the
+  cursor on screen.
+- The console's cancel prompt names the run it would cancel, as in
+  `Cancel feat/search (d4e5f67)? y / n`.
+- With no runs yet, the console suggests `fun-ci init --everything`. It used to
+  suggest `fun-ci trigger HEAD`, which fails without a branch, and
+  `fun-ci install-hook pre-push`, which does not exist.
+- When a stage fails, `fun-ci trigger` says what to do next, such as "Fix the
+  failing tests above, then try again."
+- A project's colour in the console stays the same from one start to the next.
+
+### Added
+- `fun-ci status [REV]` says where a commit's run stands, stage by stage, and
+  exits with a verdict an agent can branch on: 0 passed, 1 failed, 2 over
+  budget, 3 undecided, 4 superseded, 5 no run, 64 usage error. `--need
+  build|fast|all` says which stages must pass (fast by default), and `--json`
+  prints one JSON document.
+- `fun-ci wait [REV]` waits for that verdict and exits with it: as soon as the
+  stages `--need` names have passed, or at the first of them to fail or
+  overrun. `--within 30s` gives up undecided (exit 3). A commit with no run
+  after 5 seconds gets one started. `wait` on a superseded run exits 4 naming
+  the newer commit, and `--follow-branch` moves on to that commit's run.
+- `fun-ci runs` lists the project's recent runs, one line each; `-n N`,
+  `--branch NAME` and `--json`.
+- `fun-ci events` prints the project's runs' events as JSON lines (run
+  started, stage finished, run finished, run superseded); `--follow` keeps
+  printing them as they happen, and `--only failures` keeps to failed or
+  over-budget stages and superseded runs.
+- After each commit, the hook's output ends with the `fun-ci wait` command
+  that gets its verdict, and `fun-ci init` adds a short section to the
+  project's `AGENTS.md` (or `CLAUDE.md` when that is the only one) telling
+  agents to run it in the background.
+- `fun-ci why [REV] [STAGE]` prints everything fun-ci kept about a failed
+  stage: how it exited, how long it took against its budget, each reported
+  failure with its whole message and its own output, what the extractors
+  picked out, and the last lines of its output. `status` and `wait` end with
+  a digest of it and the `why` command. `why --raw` prints the stage's whole
+  output, kept for a project's 10 newest runs as its first 1 MB and last
+  7 MB, compressed. The end of a failed stage's output (200 lines, at most
+  64 KB) is kept for the 50 newest.
+- A `junit-files` entry under `evidence:` keeps each failure in the JUnit XML
+  a stage wrote (`build/test-results/**/*.xml`, `target/surefire-reports/*.xml`),
+  with the output each failure printed, and leaves alone reports an earlier
+  run left behind. `status --json` gives them to a program. fun-ci now depends
+  on `rexml` to read them.
+- Every stage script finds its stage's name in `FUN_CI_STAGE`.
+- Secrets are masked before fun-ci keeps anything a stage printed: the value
+  of any variable in the stage's environment whose name holds TOKEN, SECRET,
+  PASSWORD, PASSWD, API_KEY, PRIVATE_KEY or CREDENTIAL (8 characters or more)
+  shows as `[masked:NAME]`, and GitHub, AWS and Slack tokens, private keys and
+  `Authorization:` headers as `[masked]`. `mask:` under `evidence:` adds
+  patterns.
+- Presets pick out a tool's failures from a stage's output, for 34 tools,
+  each checked against the recorded output of a real failing run: rspec,
+  Minitest, Gradle, Maven, pytest, unittest, Jest, Vitest, Mocha, Node's test
+  runner, Bun, Deno, go test, cargo test, dotnet test, PHPUnit, ExUnit, swift
+  test, dart test, GoogleTest, tsc, ESLint, RuboCop, Ruff, mypy, go build,
+  rustc, gcc, ShellCheck, Perl's prove, and JSON logs from
+  logstash-logback-encoder, Elastic's ECS encoders, pino and structlog. With
+  no configuration fun-ci runs those whose marker files the project has
+  (`Gemfile`, `pom.xml`, ...) and whose tool's output the failure shows;
+  `fun-ci why` says why each was chosen and `fun-ci check` lists them.
+- `fun-ci init` writes stage scripts for every stack a preset reads, not only
+  Ruby and the JVM: rspec projects, Rust, Go, Elixir, Dart, Swift, PHP, .NET,
+  Python (uv, Poetry, pip), Deno, Bun, Node (pnpm, Yarn, npm), Perl, CMake and
+  make.
+- A project says what else to keep when a stage fails under `evidence:` in
+  `.fun-ci/config`, within a budget of 2 seconds: `grep`, `section` (with a
+  `preset:`), `log-file` (what the stage wrote to a log file, and only that),
+  `json-log` (records at or above a level, with the fields of a named preset or
+  your own), `junit-files` (JUnit XML a build tool writes in its own place),
+  and `run:`, your own extractor in any language, which gets the context as
+  JSON on stdin and prints text or JSON. `detect: false` and `skip: [name]`
+  turn presets off. The documents a `run:` extractor reads and prints are
+  pinned in `contract/evidence/`.
+- A stage that runs over budget says what it was doing: before the kill,
+  fun-ci lists its processes and the deepest one still running, and `status`
+  and `wait` lead with it (`fast ran over budget: running java ...
+  GradleWorkerMain (9.8s)`). A `run:` entry with `on: overrun` runs then, with
+  the stage's process group in `FUN_CI_PGID`, for a thread dump.
+- When another stage shared the worktree while a stage ran (lint beside
+  build, the slow suite beside the fast one), `fun-ci why` says so
+  (`alongside: slow`), since a log file may hold both stages' lines.
+- `fun-ci extract STAGE --output FILE` runs a stage's extractors against a
+  saved output and prints what `why` would, so an extractor can be tried
+  without making a commit.
+- `fun-ci check` reports a mistake under `evidence:` or a `run:` script that
+  is missing or can't be run. A mistake never stops a pipeline: the entry is
+  left out and `fun-ci why` names it as a problem.
+- `fun-ci prune` deletes the worktrees fun-ci keeps and has git forget them.
+  It refuses, and deletes nothing, while a pipeline is running.
+- `.fun-ci/console.log` notes when the console starts and stops and why it
+  stopped, what it sent every ten minutes, and when the renderer stops
+  reading or a frame takes a second or more to reach the terminal.
+- `fun-ci-renderer --colours 24bit|256` chooses the colours to draw in.
+
+### Deprecated
+- `fun-ci trigger --no-validate` is the old name for `--background`. It works
+  until 2.1 and says so on stderr.
+
+### Removed
+- The `fun-ci-trigger` and `fun-ci-tui` executables. Use `fun-ci trigger` and
+  `fun-ci console`, which have done the same job since 1.0.
+
+### Fixed
+- In a pipeline started in the background, as the post-commit hook starts
+  them (and 1.x's pre-commit hook did), the fast suite waited for the slow
+  suite to finish before it began. It now runs beside it, so the verdict a
+  push waits for comes when the fast suite is done, not the slow one.
+- A commit on a branch cancelled every unfinished run on a branch of that
+  name in every project, because all projects share one database. It now
+  cancels only its own project's runs.
+- Cancelling a stale pipeline left its stage scripts running and could let
+  the old run record itself as failed after it was cancelled. fun-ci now
+  records every process a run starts and stops all of them, and cancels runs
+  still waiting for a worktree as well. A run that had already died is only
+  marked cancelled, since the process ids it left behind may belong to
+  something else by now.
+- Cancelling a run from the console (`c`, then `y`) only marked it
+  cancelled; its stages kept running. It now stops the run.
+- A run whose fast suite failed could end up PASSED when its slow suite passed
+  afterwards, and a run showed PASSED for a moment when the slow suite
+  finished before the fast suite. A run's status now follows from all four
+  stages, whichever finishes first.
+- A slow suite whose process died without finishing left its run RUNNING for
+  ever. The console now records it failed on its next poll.
+- A database that stays busy, or can't be written because the disk is full,
+  no longer stops `fun-ci trigger`: the stages still run, the exit code is
+  theirs, and fun-ci says once that the run wasn't recorded.
+- Two fun-ci processes starting at once against a database that didn't exist
+  yet (the first commit and push on a machine, say) could die with `database
+  is locked` or `duplicate column name: project_path`. They now take turns.
+- The git hooks blocked a push when fun-ci wasn't installed, failing with
+  "fun-ci: command not found". Now they say fun-ci is missing, how to install
+  it, and let the push go ahead.
+- Git runs hooks with variables such as `GIT_INDEX_FILE` pointing at the
+  checkout. fun-ci passed them on to the git commands it runs and to your
+  stage scripts, which then read the checkout's index instead of the
+  commit's. They are cleared now.
+- `fun-ci install-hooks` wrote into `.git/hooks` even when `core.hooksPath`
+  sends git elsewhere (as husky sets it), so git never ran the hooks; and in
+  a linked worktree, whose `.git` is a file, it said the project wasn't a git
+  repository. It now asks git where the hooks go.
+- Every stage failed in a project whose path held a space, with "cannot
+  execute: No such file or directory". The stage script's path is quoted now.
+- A stage that printed without end grew fun-ci's memory without end, since
+  its output was held in memory. It is written to disk as it runs now.
+- The phase 1 line printed lint and build in whichever order they finished.
+  Lint always comes first now.
+
+## [1.2.1] - 2026-09-20
+
+### Bug Fixes
+- `StageRunner` raised `NameError: uninitialized constant FunCi::NullRecorder`
+  when built without an explicit recorder. The module reorganisation in 1.2.0
+  moved `NullRecorder` under `Persistence` and the default argument was left
+  pointing at the old name. The file also never required the recorder it names,
+  so the constant was only ever resolvable by luck of load order.
+
+### Changed
+- The gemspec reads the version from a new `lib/fun_ci/version.rb` instead of
+  loading the whole library. Loading the library pulls in sqlite3, and Bundler
+  reads the gemspec before it installs anything, so `bundle install` failed on
+  any machine that did not already happen to have sqlite3.
+- `required_ruby_version` is now `>= 3.2`. The stated floor of 3.0 was never
+  reachable: the TUI uses `Data.define`, which arrived in Ruby 3.2.
+
+### Internal
+- The cucumber suite had been broken since the 1.2.0 reorganisation, which moved
+  the files and constants it loads. It runs again, `rake` runs it, and it runs
+  with `--strict` so an undefined step fails instead of passing quietly.
+- `StageRunner` has tests. It had none, which is how the broken default survived.
+
 ## [1.2.0] - 2026-02-23
 
 ### Bug Fixes

data/README.md

@@ -1,20 +1,17 @@
 # Fun-CI
 
-Opinionated local CI that checks your code before it leaves your machine. Runs a four-stage pipeline on every commit with strict time budgets, so your feedback loop stays fast.
+Opinionated local CI that checks your code before it leaves your machine. Every commit runs lint, build, a fast suite and a slow suite on your own computer, each held to a strict time budget, so the feedback stays fast.
 
-## How It Works
+![The fun-ci console following a run: a rocket while it runs, then a scene as lint, the build, the fast suite and the whole run pass](docs/screenshots/console.png)
 
-Fun-CI hooks into git and runs your pipeline locally:
+Fun-CI has two goals. It should be extremely easy to tell whether all is well, and it should be fun. The design behind both is in [docs/design.md](docs/design.md).
 
-1. **Lint + Build** (parallel, 30s budget each) -- static analysis and compilation
-2. **Slow suite** (spawned in background, 5min budget) -- integration/end-to-end tests
-3. **Fast suite** (synchronous, 10s budget) -- unit tests
+There are two ways to use it, and both read the same results:
 
-On **pre-commit**, the entire pipeline forks to the background so your commit is not blocked. On **pre-push**, lint, build, and fast suite must pass before the push proceeds. The slow suite always runs in the background.
+- **You watch.** `fun-ci console` sits on a second screen. Colour and motion tell you from the corner of your eye that lint passed, the build passed, the fast suite passed, or that something failed and you should look closer. A pass gets a celebration, a failure gets an explosion.
+- **Your agent asks.** A coding agent can't glance at a screen, so it runs commands. `fun-ci wait` blocks until a commit's verdict is in and exits with it, and `fun-ci why` prints everything fun-ci kept about a failure, so the agent never has to rerun a suite to find out what broke.
 
-Results are stored in a local SQLite database. A terminal dashboard lets you monitor pipeline status across branches.
-
-## Getting Started
+## Getting started
 
 ```bash
 gem install fun_ci
@@ -22,87 +19,211 @@ cd your-project
 fun-ci init --everything
 ```
 
-This does three things:
-1. Detects your project type and creates `.fun-ci/` with template scripts
-2. Installs pre-commit and pre-push git hooks
-3. Verifies the setup is valid
+This detects your project type, writes four stage scripts into `.fun-ci/`, installs a `post-commit` and a `pre-push` git hook, and checks the setup. It also adds a short section to your `AGENTS.md` (or `CLAUDE.md`, if that is the only one) telling coding agents what to do after a commit.
+
+`fun-ci init` has templates for Ruby, Gradle, Maven, Rust, Go, Elixir, Dart, Swift, PHP, .NET, Python, Deno, Bun, Node, Perl, and C or C++ built with CMake or make. [docs/stacks.md](docs/stacks.md) shows how it recognises each one and the commands it writes. Fun-CI works with any project: the stages are shell scripts, so edit them to run whatever your project uses.
+
+- `lint.sh`: linter and static analysis
+- `build.sh`: compile or build
+- `fast.sh`: the fast suite (unit tests)
+- `slow.sh`: the slow suite (integration tests)
+
+Each script gets the commit hash as its first argument, its stage's name in `FUN_CI_STAGE`, and exits 0 to pass.
+
+Upgrading from 1.x? Read [Upgrading to 2.0](#upgrading-to-20) first.
+
+## How a run works
 
-`fun-ci init` has built-in templates for Ruby (Bundler), JVM (Gradle Kotlin, Gradle Groovy, Maven), but Fun-CI works with any project -- just write your own shell scripts.
+| Stage | Budget | Runs | Blocks |
+|-------|--------|------|--------|
+| Lint  | 30 s   | in parallel with build | the push |
+| Build | 30 s   | in parallel with lint | the push |
+| Fast  | 10 s   | after lint and build pass | the push |
+| Slow  | 5 min  | in the background, beside the fast suite | nothing |
 
-### Manual Setup
+A stage that overruns its budget is killed and reported as over budget, in yellow rather than red: a fast suite that takes 12 seconds has grown too heavy, which is a different problem from a failing test.
 
-If you prefer to set things up step by step:
+After each commit, the `post-commit` hook starts the pipeline in the background and returns at once, so a commit is never held up. The `pre-push` hook waits for the verdict of each commit you push and stops the push if lint, build or the fast suite failed. A commit whose run has already finished goes straight through. If fun-ci isn't installed, both hooks say so and let git carry on.
+
+Each run happens in a git worktree of its own under `.git/fun-ci/worktrees/`, checked out at the commit it tests, so you can keep editing while it runs. Ignored files such as `vendor/bundle` or `node_modules` stay in a worktree from one run to the next, which keeps builds quick. Two runs can go at once; set `worktree_slots: 3` in `.fun-ci/config` for more, and `fun-ci prune` removes the worktrees when you want the space back. A newer commit on a branch cancels the older run that is still going, unless an agent is waiting on it.
+
+Results are kept in SQLite under `$XDG_STATE_HOME/fun-ci/` (`~/.local/state/fun-ci/` by default), shared by every project on the machine.
+
+## Watching: the console
 
 ```bash
-fun-ci init              # Create .fun-ci/ with template scripts
-fun-ci install-hooks     # Install git hooks
-fun-ci check             # Verify everything is configured
+fun-ci console
 ```
 
-Then edit the generated scripts in `.fun-ci/` to match your project:
-- `lint.sh` -- linter/static analysis
-- `build.sh` -- build/compile step
-- `fast.sh` -- fast test suite (unit tests)
-- `slow.sh` -- slow test suite (integration tests)
+The console lists your runs across branches, newest first, one row each: the commit, the branch, each stage with its time, and the outcome. Above them is a picture that tells you what is happening without reading a word.
 
-Each script receives the commit hash as its first argument.
+While a run runs, a rocket flies. Each milestone a run passes has its own set of scenes, so you can tell which one it was from across the room, and a failure has its own.
 
-## Commands
+| | |
+|---|---|
+| Lint passed: a teal sweep, a ripple or a spirit level | The build passed: amber blocks, gears or a ringing anvil |
+| ![A teal line sweeping across the header](docs/screenshots/lint-sweep.png) | ![Two amber gears turning](docs/screenshots/build-gears.png) |
+| The fast suite passed: a lightning strike, a very happy YAY or a jump to warp speed | The whole run passed: fireworks, a trophy, dancing leprechauns or a sunrise |
+| ![YAY in rainbow letters with balloons](docs/screenshots/fast-yay.png) | ![The sun rising over hills](docs/screenshots/run-sunrise.png) |
+
+Scenes queue and each plays to its end, so a failure never cuts a celebration short, and a run gets one explosion however many of its stages fail.
+
+![The console after a run's fast suite failed: an explosion reading BOOM over the runs](docs/screenshots/failure.png)
+
+When the scenes are done, the header rests on how the latest run went, so a glance a minute later still tells you: a calm tick after a pass, a pulsing hazard sign after a failure. The top right keeps count of the passes in a row.
+
+| | |
+|---|---|
+| ![A tick over a calm teal horizon](docs/screenshots/rest-passed.png) | ![A pulsing hazard triangle](docs/screenshots/rest-failed.png) |
+
+Five minutes after the latest run finished, the header goes quiet: a starry night, an aurora, fireflies, a fire in a medieval stone hearth while a storm rages at the window, a moonlit island with a lone palm, or snow falling on a pine forest, changing every five minutes while nothing runs. A small lamp in the corner stays green after a pass and flickers red after a failure.
+
+| | |
+|---|---|
+| ![A fire in a stone hearth, with a green lamp in the corner](docs/screenshots/quiet-fireplace.png) | ![A moonlit island with a palm, with a red lamp in the corner](docs/screenshots/quiet-island.png) |
+
+Keys:
+
+- `j` and `k`, or the arrow keys, move the cursor down and up
+- `c` cancels the run under the cursor: a scheduled one at once, a running one once you answer `y` (`n` or `Esc` keeps it running)
+- `q` quits
+
+The console is drawn in 24-bit colour when `COLORTERM` says the terminal has it (`truecolor` or `24bit`), and in 256 colours otherwise. The pictures above come from the renderer's headless mode, drawn with its own bitmap font; in your terminal the text is in your terminal's font.
+
+The drawing is done by a separate program, `fun-ci-renderer`, written in Rust. The gem for Linux (x86_64, aarch64, musl) and macOS (arm64, x86_64) includes it. On other Unix-like systems you get the plain gem, where every command except `console` works; install the renderer with `cargo install fun-ci-renderer` (Rust 1.88 or newer), or point `FUN_CI_RENDERER` at a copy you built. Windows is not supported, because fun-ci forks its background pipeline, but WSL runs the Linux gem. When something goes wrong between the two, the details are in `.fun-ci/console.log`.
+
+## Asking: commands for agents and scripts
+
+Every commit's output ends with the command that gets its verdict:
 
 ```
-fun-ci trigger <commit> <branch>               Run the full pipeline
-fun-ci trigger --no-validate <commit> <branch>  Fork pipeline to background (used by pre-commit)
-fun-ci console                                 Launch the TUI dashboard
-fun-ci init                                     Scaffold .fun-ci/ for detected project type
-fun-ci init --everything                        init + install-hooks + check in one step
-fun-ci install-hooks                            Install pre-commit and pre-push hooks
-fun-ci install-hooks pre-commit                 Install a single hook type
-fun-ci check                                    Verify .fun-ci/ setup
+fun-ci: testing 3f9c2ab. Verdict: fun-ci wait 3f9c2ab --need all
 ```
 
-## Git Hooks
+The section `fun-ci init` writes into `AGENTS.md` tells an agent to run that command in the background after each commit. Agent harnesses wake the agent when a background command exits, so it hears about a failure without having to remember to ask.
+
+`status` says where a commit's run stands and `wait` blocks until it is decided. Both exit with the verdict for the stages you need: `--need build` (lint and build), `fast` (the default) or `all` (the slow suite too).
 
-After `fun-ci install-hooks`, two hooks are active:
+| Exit code | Meaning |
+|---|---|
+| 0 | Passed |
+| 1 | A needed stage failed |
+| 2 | A needed stage ran over budget |
+| 3 | Still undecided (`wait --within 30s` gives up at your deadline) |
+| 4 | Superseded by a newer commit on the branch (`wait --follow-branch` moves on to it) |
+| 5 | No run for the commit |
+| 64 | Usage error |
 
-**pre-commit** -- Runs `fun-ci trigger --no-validate <commit> <branch>`. This forks the pipeline into a background process and returns immediately, so commits are never blocked.
+A failed stage comes with its evidence. `status` and `wait` end with a digest and the command that shows the rest:
 
-**pre-push** -- Runs `fun-ci trigger <commit> <branch>`. This validates the project config, runs lint + build + fast suite synchronously, and blocks the push if any stage fails. The slow suite runs in the background.
+```
+$ fun-ci status
+fun-ci: 2330979 "Add shipping to the cart total" on main
+  lint   passed         0.6s
+  build  passed         0.3s
+  fast   FAILED         0.3s
+  slow   passed         0.5s (not needed)
+fast failed:
+    1) Failure:
+  CartTest#test_total_includes_shipping [test/cart_test.rb:16]:
+  Expected: 104.95
+    Actual: 99.95
+fun-ci why 2330979 fast
+```
 
-## Admin Dashboard
+`why` prints how the stage ended, each failure with its whole message and its own output, what the extractors picked out of the output and the log files, and anything that went wrong collecting it. `why --raw` prints the whole output. Every command takes `--json`.
 
-```bash
-fun-ci console
+```
+$ fun-ci why 2330979 fast
+fun-ci: 2330979 "Add shipping to the cart total" on main
+fast failed (exit 1) after 0.2s, budget 10s
+
+Minitest's failures and errors (output:9-12), from section:minitest:
+    1) Failure:
+  CartTest#test_total_includes_shipping [test/cart_test.rb:16]:
+  Expected: 104.95
+    Actual: 99.95
+
+The output's last lines, from output-tail:
+  Run options: --seed 20502
+  ...
+  3 runs, 3 assertions, 1 failures, 0 errors, 0 skips
+  rake aborted!
+  Command failed with status (1)
+  ...
+
+The whole output: fun-ci why 2330979 fast --raw
 ```
 
-Opens a terminal UI showing pipeline status across all branches. The header area displays animated ASCII art: a gentle starfield when idle, a rocket while pipelines run, and celebration/explosion animations on success or failure.
+`fun-ci runs` lists recent runs one line each, and `fun-ci events --follow` prints each run's events as JSON lines as they happen, for a supervising agent or a status bar.
+
+### What fun-ci keeps when a stage fails
+
+With no configuration, fun-ci runs the presets for the tools your project has when a failure shows them. There are presets for the test runners, compilers, linters and type checkers of every stack `fun-ci init` knows, and for JSON logs from logstash-logback-encoder, ECS, pino and structlog; [docs/stacks.md](docs/stacks.md#presets) lists each one with what it picks out and when it runs. Each preset is checked against the recorded output of a real failing run of its tool. `fun-ci check` lists the ones that apply to your project.
+
+To keep more, add entries under `evidence:` in `.fun-ci/config`:
+
+```yaml
+evidence:
+  stages:
+    fast:
+      - use: junit-files         # each failure in the JUnit XML the stage wrote,
+        paths: [build/test-results/test/*.xml]   # as file, line, test and message
+      - use: log-file            # what the stage wrote to it, and only that
+        path: log/test.log
+        grep: ["ERROR"]
+        context: 5
+    slow:
+      - run: .fun-ci/evidence/problems   # your own extractor, in any language:
+        format: json                     # the context on stdin, JSON on stdout
+      - run: pkill -QUIT -g "$FUN_CI_PGID" java   # a thread dump before an overrun is killed
+        on: overrun
+```
+
+`fun-ci extract fast --output saved.log` runs a stage's extractors against a saved output (`fun-ci why --raw > saved.log`), so you can try an entry without making a commit. A mistake under `evidence:` never stops a pipeline: `fun-ci check` reports it and `fun-ci why` names it.
+
+Secrets in the stage's environment are masked before anything is kept: the value of any variable whose name holds TOKEN, SECRET, PASSWORD, PASSWD, API_KEY, PRIVATE_KEY or CREDENTIAL, and GitHub, AWS and Slack tokens, private keys and `Authorization:` headers wherever they appear. The state directory is readable by your user alone.
+
+## Commands
 
-Navigation:
+```
+fun-ci init                                     Scaffold .fun-ci/ for the detected project type
+fun-ci init --everything                        init + install-hooks + check in one step
+fun-ci install-hooks                            Install post-commit and pre-push hooks
+fun-ci install-hooks post-commit                Install a single hook type
+fun-ci check                                    Verify .fun-ci/ setup
+fun-ci console                                  Watch the runs
+fun-ci status [commit]                          Where a commit's run stands; the verdict is the exit code
+fun-ci wait [commit]                            Wait until that verdict is decided, then exit with it
+fun-ci why [commit] [stage]                     Everything kept about why a stage failed
+fun-ci runs                                     This project's recent runs, newest first
+fun-ci events [--follow]                        The runs' events as JSON lines
+fun-ci extract <stage> --output <file>          Try a stage's extractors on a saved output
+fun-ci trigger <commit> <branch>                Run the whole pipeline in the foreground
+fun-ci trigger --background <commit> <branch>   Start the pipeline in the background (what post-commit runs)
+fun-ci prune                                    Remove fun-ci's worktrees when no pipeline is running
+```
 
-- `j` / `k` -- scroll up/down
-- `c` -- cancel a running pipeline
-- `q` -- quit
+`fun-ci --help` lists every option.
 
-## Time Budgets
+## Upgrading to 2.0
 
-| Stage | Budget | Blocks |
-|-------|--------|--------|
-| Lint  | 30s    | push   |
-| Build | 30s    | push   |
-| Fast  | 10s    | push   |
-| Slow  | 5min   | nothing (background) |
+- Run `fun-ci install-hooks` again. The background pipeline now runs after the commit (`post-commit`), so it tests the commit you just made; the `pre-commit` hook tested the one before it. Until you do, each run tests the commit before yours, and `fun-ci check` warns you. Installing removes the `pre-commit` hook fun-ci 1.x wrote and leaves a hook of your own alone (`fun-ci check` warns if yours still calls fun-ci). The new `pre-push` hook waits for the verdict instead of running the pipeline again.
+- The stages run in a worktree at the commit, not in your checkout. A script that relied on uncommitted files in your checkout won't see them any more.
+- The database moved from `$TMPDIR` to `$XDG_STATE_HOME/fun-ci/`. Runs recorded by 1.x are not carried over.
+- `fun-ci-trigger` and `fun-ci-tui` are gone; use `fun-ci trigger` and `fun-ci console`. `fun-ci trigger --no-validate` still works until 2.1, as the old name for `--background`.
+- The console needs `fun-ci-renderer`, which the platform gems include (see [Watching: the console](#watching-the-console)).
 
-If a stage exceeds its budget, it is killed and reported as timed out.
+The whole list is in [CHANGELOG.md](CHANGELOG.md).
 
 ## Development
 
 ```bash
 bundle install
-rake test
+bundle exec rake   # the gate: tests, the renderer's tests, the binary contract, rubocop, clippy
 ```
 
-## Changelog
-
-See [CHANGELOG.md](CHANGELOG.md) for release history.
+How it is built is in [docs/architecture.md](docs/architecture.md), and the requirements are in [docs/acceptance-tests.md](docs/acceptance-tests.md). The renderer is written in Rust; install Rust with [rustup](https://rustup.rs), which picks up the version the repository pins in `rust-toolchain.toml`. `ruby script/readme_screenshots.rb` draws the pictures in this README again.
 
 ## License
 

data/lib/fun_ci/agent/age.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # How long ago something happened, in the largest whole unit.
+    module Age
+      UNITS = [[86_400, "d"], [3600, "h"], [60, "m"]].freeze
+
+      def self.words(seconds)
+        size, unit = UNITS.find { |unit_seconds, _| seconds >= unit_seconds }
+        size ? "#{(seconds / size).floor}#{unit} ago" : "just now"
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/command_support.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "options"
+require_relative "reports"
+require_relative "exit_code"
+
+module FunCi
+  module Agent
+    # What the agent commands share: the commit a revision names, the reports
+    # of its runs, and refusing arguments they can't use. Expects @context and
+    # a NAME constant.
+    module CommandSupport
+      private
+
+      def resolve(rev)
+        @context.git.resolve(rev) || raise(Options::Invalid, "git can't find the commit '#{rev}'")
+      end
+
+      def reports = @reports ||= Reports.new(@context.db, @context.git)
+
+      def usage(message)
+        @context.io.stderr.puts "fun-ci #{self.class::NAME}: #{message}"
+        ExitCode::USAGE
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/commands.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../pipeline/trigger_params"
+require_relative "context"
+require_relative "git"
+require_relative "system_clock"
+require_relative "live_pipeline"
+require_relative "status_command"
+require_relative "runs_command"
+require_relative "wait_command"
+require_relative "events_command"
+require_relative "why_command"
+
+module FunCi
+  module Agent
+    # The commands an agent runs in a project, each answered from the
+    # database and the project's git.
+    module Commands
+      ALL = { "status" => StatusCommand, "runs" => RunsCommand, "wait" => WaitCommand,
+              "events" => EventsCommand, "why" => WhyCommand }.freeze
+
+      def self.run(name, args, context)
+        ALL.fetch(name).new(context).run(args)
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/context.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # What every agent command answers from: the database, the project's git,
+    # where to print, the time (#now, #pause) and the pipeline (#start a run,
+    # #watch the database for slow suites that died).
+    Context = Data.define(:db, :git, :io, :clock, :pipeline)
+  end
+end