fun_ci 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ec70009244a286fd23264c7cd99becf5a5a437ee8fb2a636652d1050f2b4d78
-  data.tar.gz: c354caa2011c5d7d8d39d2637f9c3423cae3c7e8a8c6fcce83232aa83d169cd5
+  metadata.gz: e5ea6a4ee9221da8020682980de5e05ad481540f66f9b187620ce121e16ec399
+  data.tar.gz: 27d73d17a2a6089d219f5bceaabe1a39385392c25d6e7ec095862eb84d637135
 SHA512:
-  metadata.gz: aa78fbd513340af9d0cb8cd1c0d071a6eb2c487f4fb2216a7108acdc3b71f1ba19682cb7746f5fdb024a1a0a7ea8f32d15c76f41f64a900f16ab6fc8594beaec
-  data.tar.gz: efb2b61788bd0e2ba361646a2391976c4fd29de3b91f1256d9425a5efc0687b6b731ccc6bbeeca22f52e12a091d705f10035298e2a622be63ef714a8f55f59d9
+  metadata.gz: eebf4b0852e2ecd06abcee7c8a5ce1b72d29705767b55771b349b4882f1f0d0655d5f96eb49ad6b11eee17216b5d5fa7f6f7db35c9f6da69a81d5151987f8d92
+  data.tar.gz: 3a3d674d245e9cd4fae2ecd6afbd39a645e36f06ea305f9454cd4676462da3128903cd559252b500cb187a12d398a8fe6b654d2c90df192680d5ed2ef6788f03

data/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-09-30
+
+### Added
+- Each run checks whether its commit would merge cleanly with the trunk:
+  `trunk:` in `.fun-ci/config`, or else the remote's default branch.
+  `status` and `wait` print where the commit stands, with its age; for a
+  conflict, the files and when and how to integrate. A conflict is not a
+  failure and changes no exit code, unless you ask with `--trunk`, which exits
+  6 for a run that passed but conflicts and waits for the check.
+  `fun-ci why REV trunk` prints each conflicted region. `status --json`,
+  `runs` and `events` carry the check; `fun-ci check` names the trunk.
+- fun-ci fetches the trunk itself, at most every five minutes, into
+  `refs/fun-ci/trunk/`, touching none of your refs, and says so the first time.
+  `trunk_fetch: false` stops it, and `trunk: none` turns the check off.
+- The console says when a branch conflicts with the trunk, `conflicts with
+  main` under it, and plays a knot tying, and later untying, in the header.
+  This needs renderer 2.1.0, which the platform gems bring; with an older
+  renderer, as `cargo install` left it, the console works but shows no
+  conflicts.
+- `fun-ci --help` lists `--raw`, which it left out.
+
+### Changed
+- The console's table is new. Each branch has one row, its newest run's,
+  under its project's name, and reads as one phrase: the branch, a mark each
+  for lint, the build, the fast suite and the slow suite, joined into a track
+  that fills from left to right (`✓─✓─◆┄·`), what happened (`the fast suite
+  failed after 1.4s`, `running the fast and slow suites · 7s`) and when. A
+  legend at the top of the table names each stage and says what it is for,
+  with a line from each name down through every project to its column of
+  marks; when there is no room for it, one line above the keys names the
+  marks. What needs you, a failure, a timeout or a conflict, comes first, with
+  a stripe in the colour of why, and the first of it, or the row under the
+  cursor, sits in one card that breathes: wine when its row needs you, indigo
+  when the cursor only rests there. Passed rows are pale, and fold into one
+  line per project when nothing needs you. The header's night sky carries on
+  below the table, and the keys sit on caps. On a wide terminal the table
+  widens a little and sits in the middle; on a short one it folds and closes
+  up before it leaves anything out, and says how many passed rows it left out.
+  `c cancel` shows only when there is something to cancel.
+- A stage's mark lights up and fades back when something happens to it. A
+  pass glows gold and eases back to the mark's own colour, a timeout pulses
+  amber twice, and a failure flares white on red and cools into the row. They
+  last as long however often the console redraws; they used to run faster
+  when boards arrived quickly.
+- A run that ends washes its row in teal, coral or amber, draining from left
+  to right, and a band of light travels along each running row.
+- The failure and pass banners keep the sky behind them, take their colours
+  from the table's, and name the stage in full (`>>> THE FAST SUITE FAILED
+  <<<`).
+
+### Deprecated
+- `fun-ci trigger --no-validate`, the old name for `--background`, now goes
+  in 3.0 rather than 2.1 as 2.0 said: removing a flag in a minor release
+  would break the scripts and hooks that still pass it. It still works, and
+  says so on stderr.
+
+### Fixed
+- A console row wider than the terminal, from a long branch name or a
+  failure word, wrapped onto the next line and pushed the board up, hiding
+  the newest run under the header. Rows are now cut to fit, the branch first,
+  and never wrap; the footer too.
+- A branch named in Chinese, Japanese or Korean fills two columns a
+  character, but the console counted one, so its marks slid out of line with
+  the other rows' and a long name ran into them. Names are now measured, and
+  cut, by the columns they fill.
+- `.fun-ci/console.log`, where the console notes what went wrong between it
+  and the renderer, was left for `git add` to sweep into a commit. The console
+  now writes a `.fun-ci/.gitignore` naming it, unless the project has one there.
+
 ## [2.0.2] - 2026-09-29
 
 ### Fixed

data/README.md

@@ -59,7 +59,9 @@ Results are kept in SQLite under `$XDG_STATE_HOME/fun-ci/` (`~/.local/state/fun-
 fun-ci console
 ```
 
-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.
+The console shows where each branch stands, one row per branch under its project's name: a mark for each stage (lint, the build, the fast suite and the slow suite, named in a legend at the top of the table), what happened (`the fast suite failed after 1.4s`) and when. What needs you comes first, in one deep block; passed rows stay pale. Above them is a picture that tells you what is happening without reading a word.
+
+![The console's table on a busy board: a legend naming lint, the build, the fast suite and the slow suite over their columns of marks, three projects, a failed branch that conflicts with main in a deep red card, a timeout, a running branch and two pale passed ones](docs/screenshots/table.png)
 
 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.
 
@@ -86,10 +88,12 @@ Five minutes after the latest run finished, the header goes quiet: a starry nigh
 |---|---|
 | ![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) |
 
+A branch that conflicts with the trunk says so on the line under its name, `conflicts with main`, and the header plays two strands braiding into a knot; when a later commit on the branch merges cleanly, the knot unties. A project whose trunk fun-ci last fetched over an hour ago, or couldn't fetch, says so beside its name.
+
 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)
+- `c` cancels the run under the cursor: one waiting to start at once, a running one once you answer `y` (`n` or `Esc` keeps it running); the footer offers it only while a run is running or waits to start
 - `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.
@@ -116,6 +120,7 @@ The section `fun-ci init` writes into `AGENTS.md` tells an agent to run that com
 | 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 |
+| 6 | Passed, but conflicts with the trunk (only with `--trunk`) |
 | 64 | Usage error |
 
 A failed stage comes with its evidence. `status` and `wait` end with a digest and the command that shows the rest:
@@ -161,6 +166,27 @@ The whole output: fun-ci why 2330979 fast --raw
 
 `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.
 
+### Where your commit stands against the trunk
+
+Each run also checks whether its commit would merge cleanly with your trunk: `trunk:` in `.fun-ci/config` if you name one, otherwise your remote's default branch. `status` and `wait` print where it stands, and for a conflict, the files and what to do about it:
+
+```
+$ fun-ci status
+fun-ci: f473fdb "Add shipping to the cart total" on feat/cart
+  lint   passed         0.2s
+  build  passed         0.3s
+  fast   passed         0.1s
+  slow   passed         0.2s (not needed)
+  trunk  conflicts    origin/main 0e15acf, fetched just now, 1 ahead, 1 behind
+    lib/cart.rb
+Conflicts with origin/main in 1 file. When the task is done, integrate: git pull origin main (or git pull --rebase origin main if the branch isn't shared)
+fun-ci why f473fdb trunk
+```
+
+A conflict is not a failure, so that run still exits 0. An agent that should integrate before calling its work done asks with `--trunk`, and gets 6 for a run that passed but conflicts; `fun-ci init` tells agents to. `fun-ci why f473fdb trunk` merges again and prints each conflicted region with the lines around it.
+
+fun-ci fetches the trunk itself, at most every five minutes, into a ref of its own (`refs/fun-ci/trunk/...`), so your `origin/main` and `git status` are left as they were. The first fetch says so. `trunk_fetch: false` in `.fun-ci/config` stops it, `trunk_fetch: 30m` spaces it out, and `trunk: none` turns the check off. A trunk fetched over an hour ago, or whose last fetch failed, is marked STALE wherever it is shown.
+
 ### 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.
@@ -197,9 +223,9 @@ fun-ci install-hooks                            Install post-commit and pre-push
 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 status [commit] [--trunk]                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 why [commit] [stage|trunk]               Everything kept about why a stage failed, or the conflict with the trunk
 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
@@ -215,7 +241,7 @@ fun-ci prune                                    Remove fun-ci's worktrees when n
 - 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`.
+- `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 3.0, as the old name for `--background`.
 - The console needs `fun-ci-renderer`, which the platform gems include (see [Watching: the console](#watching-the-console)).
 
 The whole list is in [CHANGELOG.md](CHANGELOG.md).

data/lib/fun_ci/agent/command_support.rb

@@ -3,6 +3,7 @@
 require_relative "options"
 require_relative "reports"
 require_relative "exit_code"
+require_relative "trunk_verdict"
 
 module FunCi
   module Agent
@@ -16,7 +17,19 @@ module FunCi
         @context.git.resolve(rev) || raise(Options::Invalid, "git can't find the commit '#{rev}'")
       end
 
-      def reports = @reports ||= Reports.new(@context.db, @context.git)
+      # The commit's newest run, judged on the trunk too when the agent asked
+      # (--trunk), checked again first when the trunk has moved since.
+      def report_for(sha, options)
+        report = reports.for(sha, options.need)
+        return report unless options.trunk && report
+
+        report = reports.recheck_trunk(sha).then { reports.for(sha, options.need) } if report.trunk&.moved_to
+        report.with(verdict: TrunkVerdict.of(report.verdict, report.trunk))
+      end
+
+      def output(options) = Output.new(@context.io.stdout, json: options.json, trunk: options.trunk)
+
+      def reports = @reports ||= Reports.new(@context.db, @context.git, @context.clock, @context.trunk)
 
       def usage(message)
         @context.io.stderr.puts "fun-ci #{self.class::NAME}: #{message}"

data/lib/fun_ci/agent/commands.rb

@@ -10,6 +10,7 @@ require_relative "runs_command"
 require_relative "wait_command"
 require_relative "events_command"
 require_relative "why_command"
+require_relative "../trunk/local"
 
 module FunCi
   module Agent

data/lib/fun_ci/agent/context.rb

@@ -4,7 +4,8 @@ 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)
+    # #watch the database for slow suites that died) and the trunk as the
+    # project's git has it now (#now_at(tip), #check(sha, fetches)).
+    Context = Data.define(:db, :git, :io, :clock, :pipeline, :trunk)
   end
 end

data/lib/fun_ci/agent/events.rb

@@ -5,10 +5,16 @@ module FunCi
     # What happened to a project's runs between two looks at them
     # (acceptance-tests.md, AT-9.16), oldest run first: a run started, each
     # stage that finished in the order it finished, a run that passed or
-    # failed, a run a newer commit superseded. The first look is at nothing.
+    # failed, a run a newer commit superseded, a check of its commit against
+    # the trunk recorded or made again. The first look is at nothing.
     module Events
-      # finished: [{ stage:, state:, seconds: }, ...] in the order they finished.
-      RunState = Data.define(:id, :sha, :branch, :status, :finished, :superseded_by)
+      # finished: [{ stage:, state:, seconds: }, ...] in the order they finished;
+      # trunk: the latest check of its commit, as status --json gives it, or nil.
+      RunState = Data.define(:id, :sha, :branch, :status, :finished, :superseded_by, :trunk)
+
+      class RunState
+        def initialize(trunk: nil, **) = super
+      end
       OUTCOMES = { "completed" => "passed", "failed" => "failed" }.freeze
       FAILED_STATES = %w[failed over_budget].freeze
 
@@ -27,7 +33,7 @@ module FunCi
         about = { commit: run.sha, branch: run.branch }
         [*(was ? [] : [{ event: "run_started", **about }]),
          *newly_finished(run, was).map { |stage| { event: "stage_finished", **about, **stage } },
-         *ended(run, was, about)]
+         *checked(run, was, about), *ended(run, was, about)]
       end
 
       def self.newly_finished(run, was)
@@ -35,13 +41,21 @@ module FunCi
         run.finished.reject { |stage| seen.include?(stage[:stage]) }
       end
 
+      # A check is new when its state or its trunk tip is.
+      def self.checked(run, was, about)
+        trunk = run.trunk
+        return [] if trunk.nil? || trunk.values_at(:state, :sha) == was&.trunk&.values_at(:state, :sha)
+
+        [{ event: "trunk_checked", **about, trunk: trunk }]
+      end
+
       def self.ended(run, was, about)
         return [] if was&.status == run.status
         return [{ event: "run_superseded", **about, by_commit: run.superseded_by }] if run.status == "cancelled"
 
         OUTCOMES.key?(run.status) ? [{ event: "run_finished", **about, state: OUTCOMES.fetch(run.status) }] : []
       end
-      private_class_method :of, :newly_finished, :ended
+      private_class_method :of, :newly_finished, :checked, :ended
     end
   end
 end

data/lib/fun_ci/agent/events_command.rb

@@ -55,7 +55,7 @@ module FunCi
         @context.io.stdout.flush
       end
 
-      def snapshots = @snapshots ||= Snapshots.new(@context.db, @context.git)
+      def snapshots = @snapshots ||= Snapshots.new(@context.db, @context.git, @context.clock)
     end
   end
 end

data/lib/fun_ci/agent/exit_code.rb

@@ -4,7 +4,7 @@ module FunCi
   module Agent
     # What `status` and `wait` exit with (acceptance-tests.md, §9).
     module ExitCode
-      FOR = { passed: 0, failed: 1, over_budget: 2, undecided: 3, superseded: 4, unknown: 5 }.freeze
+      FOR = { passed: 0, failed: 1, over_budget: 2, undecided: 3, superseded: 4, unknown: 5, conflicts: 6 }.freeze
       USAGE = 64
     end
   end

data/lib/fun_ci/agent/next_step.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # What to do about a conflict with the trunk, built from the trunk that was
+    # resolved: a pull that fetches first, so the trunk integrated is never
+    # older than the one checked. A rebase of a pushed branch needs a force
+    # push, so off the trunk branch a merge comes first.
+    module NextStep
+      def self.line(tip, files, branch:)
+        count = files.size == 1 ? "1 file" : "#{files.size} files"
+        "Conflicts with #{tip.ref} in #{count}. When the task is done, integrate: #{command(tip, branch)}"
+      end
+
+      def self.command(tip, branch)
+        return "git merge #{tip.branch}" unless tip.remote
+
+        pull = "#{tip.remote} #{tip.branch}"
+        return "git pull --rebase #{pull}" if branch == tip.branch
+
+        "git pull #{pull} (or git pull --rebase #{pull} if the branch isn't shared)"
+      end
+      private_class_method :command
+    end
+  end
+end

data/lib/fun_ci/agent/options.rb

@@ -11,16 +11,18 @@ module FunCi
     module Options
       class Invalid < StandardError; end
 
-      Parsed = Data.define(:rev, :stage, :need, :json, :within, :follow_branch, :limit, :branch, :follow, :only, :raw)
+      Parsed = Data.define(:rev, :stage, :need, :json, :within, :follow_branch, :limit, :branch, :follow, :only, :raw,
+                           :trunk)
       DEFAULTS = { need: "fast", json: false, within: nil, follow_branch: false, limit: 10, branch: nil,
-                   follow: false, only: nil, raw: false }.freeze
+                   follow: false, only: nil, raw: false, trunk: false }.freeze
       SWITCHES = { need: ["--need LEVEL"], json: ["--json"], within: ["--within DURATION"], raw: ["--raw"],
                    follow_branch: ["--follow-branch"], limit: ["-n N", Integer], branch: ["--branch NAME"],
-                   follow: ["--follow"], only: ["--only KIND"] }.freeze
+                   follow: ["--follow"], only: ["--only KIND"], trunk: ["--trunk"] }.freeze
       FILTERS = %w[failures].freeze
       MULTIPLIERS = { "" => 1, "s" => 1, "m" => 60 }.freeze
 
-      STAGES = %w[lint build fast slow].freeze
+      # What `why` explains: a stage, or the run's conflict with the trunk.
+      STAGES = %w[lint build fast slow trunk].freeze
 
       def self.parse(args, takes:)
         values = DEFAULTS.dup

data/lib/fun_ci/agent/output.rb

@@ -7,20 +7,25 @@ require_relative "why_json"
 require_relative "status_json"
 require_relative "runs_text"
 require_relative "exit_code"
+require_relative "evidence_text"
+require_relative "trunk_why_json"
 
 module FunCi
   module Agent
     # Prints what an agent command found, as text or, with --json, as JSON.
     class Output
+      NO_CONFLICT = "No conflict with the trunk to explain."
       NO_STAGE = "No stage it needs failed or ran over budget; name one to see it: fun-ci why REV STAGE"
 
-      def initialize(stdout, json:)
+      # trunk: whether the agent asked about the trunk (--trunk).
+      def initialize(stdout, json:, trunk: false)
         @stdout = stdout
         @json = json
+        @trunk = trunk
       end
 
       def report(report)
-        @json ? print_json(StatusJson.document(report)) : print_lines(StatusText.lines(report))
+        @json ? print_json(StatusJson.document(report)) : print_lines(StatusText.lines(report, trunk: @trunk))
       end
 
       # Everything kept about the stage named, or says no stage decided the verdict.
@@ -32,6 +37,14 @@ module FunCi
         print_lines(WhyText.lines(report, stage))
       end
 
+      # The run's conflict with the trunk; document nil when there is none to explain.
+      def why_trunk(report, document)
+        return print_json(TrunkWhyJson.document(report, document)) if @json
+
+        print_lines([StatusText.header(report), *StatusText.trunk(report, true),
+                     *(document ? EvidenceText.lines(document) : ["", NO_CONFLICT])])
+      end
+
       # Says the commit has no run, and answers the exit code for that.
       def unknown(sha)
         @json ? print_json(StatusJson.unknown(sha)) : print_lines(["fun-ci: no run for #{sha[0, 7]} in this project."])

data/lib/fun_ci/agent/report_stage.rb

@@ -6,7 +6,7 @@ require_relative "../persistence/stage_job"
 
 module FunCi
   module Agent
-    RunReport = Data.define(:sha, :subject, :branch, :need, :stages, :verdict, :deciding, :superseded_by)
+    RunReport = Data.define(:sha, :subject, :branch, :need, :stages, :verdict, :deciding, :superseded_by, :trunk)
 
     # One stage of a run, as an agent is told it.
     class RunReport

data/lib/fun_ci/agent/reports.rb

@@ -1,23 +1,24 @@
 # frozen_string_literal: true
 
 require_relative "../persistence/project_runs"
-require_relative "../persistence/stage_job"
-require_relative "../persistence/raw_outputs"
+require_relative "run_details"
 require_relative "run_report"
 
 module FunCi
   module Agent
     # The runs of the project git names, as an agent is told them.
     class Reports
-      def initialize(db, git)
+      # trunk: where the project's trunk is now (#now_at(tip)), and checks against it (#check(sha, fetches)).
+      def initialize(db, git, clock, trunk)
         @db = db
         @git = git
-        @runs = Persistence::ProjectRuns.new(db, git.toplevel)
-        @raw = Persistence::RawOutputs.beside(db.filename("main"))
+        project = git.toplevel
+        @runs = Persistence::ProjectRuns.new(db, project)
+        @details = RunDetails.new(db, TrunkReading.new(db, project, clock, trunk))
       end
 
       # What the stage kept of its raw output, or nil.
-      def raw_output(stage) = stage.id && @raw.read(stage.id)
+      def raw_output(stage) = @details.raw_output(stage)
 
       # The commit's newest run, or nil.
       def for(sha, need)
@@ -25,6 +26,9 @@ module FunCi
         run && of(run, need)
       end
 
+      # Checks the commit against where the trunk is now, and keeps the check.
+      def recheck_trunk(sha) = @details.recheck_trunk(sha)
+
       # Notes that an agent is waiting on the commit's newest run, as of `at`.
       def mark_waited(sha, at)
         run = @runs.latest_of_commit(sha)
@@ -38,9 +42,9 @@ module FunCi
 
       def of(run, need)
         superseded_by = run[:status] == "cancelled" ? @runs.superseded_by(run) : nil
-        jobs = Persistence::StageJob.for_run(@db, run[:id]).map { |job| job.merge(raw_bytes: @raw.bytes(job[:id])) }
-        RunReport.build(run: run, jobs: jobs, need: need,
-                        commit: { subject: @git.subject(run[:commit_hash]), superseded_by: superseded_by })
+        RunReport.build(run: run, jobs: @details.jobs(run), need: need,
+                        commit: { subject: @git.subject(run[:commit_hash]), superseded_by: superseded_by,
+                                  trunk: @details.trunk(run) })
       end
     end
   end

data/lib/fun_ci/agent/run_details.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../persistence/stage_job"
+require_relative "../persistence/raw_outputs"
+require_relative "trunk_reading"
+
+module FunCi
+  module Agent
+    # What is recorded about one of a project's runs beyond its row: its
+    # stages, the raw output they kept, and its commit's check against the trunk.
+    class RunDetails
+      # trunk: reads the run's trunk (a TrunkReading).
+      def initialize(db, trunk)
+        @db = db
+        @raw = Persistence::RawOutputs.beside(db.filename("main"))
+        @trunk = trunk
+      end
+
+      def jobs(run)
+        Persistence::StageJob.for_run(@db, run[:id]).map { |job| job.merge(raw_bytes: @raw.bytes(job[:id])) }
+      end
+
+      # What the stage kept of its raw output, or nil.
+      def raw_output(stage) = stage.id && @raw.read(stage.id)
+
+      # How the run's commit stands against the trunk, or nil for a run that began no check.
+      def trunk(run) = @trunk.for(run)
+      def recheck_trunk(sha) = @trunk.recheck(sha)
+    end
+  end
+end

data/lib/fun_ci/agent/run_report.rb

@@ -10,10 +10,11 @@ module FunCi
     class RunReport
       STAGES = %w[lint build fast slow].freeze
 
-      # deciding: the stage whose failure or overrun decided the verdict, if one did.
-      def initialize(deciding: nil, **) = super
+      # deciding: the stage whose failure or overrun decided the verdict, if one did;
+      # trunk: how its commit stands against the trunk (a Trunk::Shown), if it was checked.
+      def initialize(deciding: nil, trunk: nil, **) = super
 
-      # commit: the run's subject and the commit that superseded it, if any.
+      # commit: the run's subject, the commit that superseded it, if any, and its trunk check.
       def self.build(run:, jobs:, need:, commit:)
         verdict = Verdict.decide(run_status: run[:status], stages: jobs, need: need)
         new(sha: run[:commit_hash], branch: run[:branch], need: need, stages: stages(jobs), verdict: verdict,

data/lib/fun_ci/agent/runs_text.rb

@@ -5,7 +5,8 @@ require_relative "run_report"
 module FunCi
   module Agent
     # One line per run, the columns lined up: short SHA, branch, age, each
-    # stage's outcome in a word of four letters at most, and the subject.
+    # stage's outcome in a word of four letters at most, a conflict with the
+    # trunk, as of the run's check, and the subject.
     module RunsText
       WORDS = { "passed" => "ok", "failed" => "FAIL", "over_budget" => "OVER", "running" => "...", "waiting" => "-",
                 "cancelled" => "x" }.freeze
@@ -18,10 +19,12 @@ module FunCi
 
       def self.line(report, age, (branch_width, age_width))
         stages = report.stages.map { |stage| "#{stage.name} #{WORDS.fetch(stage.state).ljust(4)}" }.join("  ")
-        "#{report.sha[0,
-                      7]}  #{report.branch.ljust(branch_width)}  #{age.ljust(age_width)}  #{stages}  #{report.subject}"
+        "#{report.sha[0, 7]}  #{report.branch.ljust(branch_width)}  #{age.ljust(age_width)}  #{stages}  " \
+          "#{conflict(report.trunk)}#{report.subject}"
       end
-      private_class_method :line
+
+      def self.conflict(trunk) = trunk&.state == "conflicts" ? "conflicts #{trunk.check.tip.ref}  " : ""
+      private_class_method :line, :conflict
     end
   end
 end

data/lib/fun_ci/agent/snapshots.rb

@@ -4,15 +4,19 @@ require_relative "../persistence/project_runs"
 require_relative "../persistence/stage_job"
 require_relative "run_report"
 require_relative "events"
+require_relative "trunk_reading"
+require_relative "trunk_json"
 
 module FunCi
   module Agent
     # Looks at the newest runs of the project git names, as `events` compares
     # them: { run id => Events::RunState }.
     class Snapshots
-      def initialize(db, git)
+      def initialize(db, git, clock)
+        project = git.toplevel
         @db = db
-        @runs = Persistence::ProjectRuns.new(db, git.toplevel)
+        @runs = Persistence::ProjectRuns.new(db, project)
+        @trunk = TrunkReading.new(db, project, clock, TrunkReading::UNREAD)
       end
 
       def take(limit:)
@@ -24,7 +28,13 @@ module FunCi
       def state_of(run)
         superseded_by = run[:status] == "cancelled" ? @runs.superseded_by(run) : nil
         Events::RunState.new(id: run[:id], sha: run[:commit_hash], branch: run[:branch], status: run[:status],
-                             finished: finished(run), superseded_by: superseded_by)
+                             finished: finished(run), superseded_by: superseded_by, trunk: trunk(run))
+      end
+
+      # The latest check recorded; a check still going has none yet.
+      def trunk(run)
+        shown = @trunk.for(run)
+        shown&.check ? TrunkJson.document(shown) : nil
       end
 
       def finished(run)

data/lib/fun_ci/agent/status_command.rb

@@ -16,9 +16,9 @@ module FunCi
       end
 
       def run(args)
-        options = Options.parse(args, takes: %i[need json])
+        options = Options.parse(args, takes: %i[need json trunk])
         sha = resolve(options.rev)
-        answer(sha, reports.for(sha, options.need), Output.new(@context.io.stdout, json: options.json))
+        answer(sha, report_for(sha, options), output(options))
       rescue Options::Invalid => e
         usage(e.message)
       end

data/lib/fun_ci/agent/status_json.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "run_report"
+require_relative "trunk_json"
 
 module FunCi
   module Agent
@@ -12,7 +13,7 @@ module FunCi
       def self.document(report)
         { schema: SCHEMA, commit: { sha: report.sha, branch: report.branch, subject: report.subject },
           need: report.need, verdict: report.verdict.to_s, stages: report.stages.map { |stage| stage(stage) },
-          superseded_by: report.superseded_by }
+          superseded_by: report.superseded_by, trunk: report.trunk && TrunkJson.document(report.trunk) }
       end
 
       def self.unknown(sha) = { schema: SCHEMA, commit: { sha: sha }, verdict: "unknown" }

data/lib/fun_ci/agent/status_text.rb

@@ -3,6 +3,7 @@
 require_relative "run_report"
 require_relative "verdict"
 require_relative "digest"
+require_relative "trunk_text"
 
 module FunCi
   module Agent
@@ -11,10 +12,19 @@ module FunCi
     module StatusText
       WORDS = { "failed" => "FAILED", "over_budget" => "OVER BUDGET" }.freeze
 
-      def self.lines(report)
+      # trunk: whether the agent asked about the trunk, which says so while its check is going.
+      def self.lines(report, trunk: false)
         needed = Verdict::LEVELS.fetch(report.need)
         [header(report), *report.stages.map { |stage| stage_line(stage, needed) }, *Digest.lines(report.stages, needed),
-         *footer(report)]
+         *trunk(report, trunk), *footer(report)]
+      end
+
+      # The trunk lines; nothing while the check is going, unless asked about
+      # (right after a commit it would say nothing useful).
+      def self.trunk(report, asked)
+        return [] if report.trunk.nil? || (report.trunk.state == "checking" && !asked)
+
+        TrunkText.lines(report.trunk, branch: report.branch, next_step: report.deciding.nil?)
       end
 
       def self.header(report) = %(fun-ci: #{report.sha[0, 7]} "#{report.subject}" on #{report.branch})
@@ -27,6 +37,7 @@ module FunCi
 
       def self.footer(report)
         return ["fun-ci why #{report.sha[0, 7]} #{report.deciding}"] if report.deciding
+        return ["fun-ci why #{report.sha[0, 7]} trunk"] if report.trunk&.state == "conflicts"
         return [] unless report.verdict == :superseded && report.superseded_by
 
         ["Superseded by #{report.superseded_by[0, 7]}."]