fun_ci 2.1.1-x86_64-linux → 2.3.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f37bc30d8cfa394baf3701449769df4652a65598a209c7c1ed870d9dc70e0221
-  data.tar.gz: c66dd824f11d8c2b870e101271c6679dd36a15a8663a96dc9b2aa9b967ebd134
+  metadata.gz: 312bfad226919d4599a0bc5cacecef1c26f08dda6d522f2a181b0b8c0c39ef81
+  data.tar.gz: 1183694930f2aa2b655238523c2068e9278e51ecad3cf14be1c8065ad285d271
 SHA512:
-  metadata.gz: 3f6030e8a6c675cca3112dd7f3c4da909c5d162090a40fefca9b85c3cf5d914a5b209516ec02fc5086cc6dffc744c092e13f3b8345af5826bee18341926e0e68
-  data.tar.gz: 8c19530b1164151eda907bbeaf19abd44274ccdf3f7c3ce1d9eb222cc5bf227a2501df38b8cc360b5241598dfccf53aa5f3da9c70745787f497687f819a59a26
+  metadata.gz: 291d5610ff766c5c09903a53d0aac5eb7b7e376d4c36e39ac11cd7024a2081d763d8bcbe25312008c520bf250c124b12d0fce022904e86cced70671714fe14b4
+  data.tar.gz: 7b6524c10cbef0919c017e3ba0f784313c009c3c0bf6a0b19655f2f017ddcc148daaa1b402210e4ee579e528d7594b095aa7fd32ed56eaad455383e804ccbaa6

data/CHANGELOG.md

@@ -7,6 +7,101 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-10-02
+
+### Added
+- A commit's due daily and weekly jobs take turns instead of starting
+  together, spread evenly over the day: with four jobs, the first at once
+  and each next one six hours later, and none sooner than that after a job
+  still running or waiting. `job_spacing:` in `.fun-ci/config` sets the gap
+  instead (`30m`, `1h`; `0` starts them together). A job waiting its turn
+  says when it starts: `starts in 6h` in the console and in `fun-ci jobs`,
+  `starts_at` in its JSON, `scheduled, starts in 6h` in `status`,
+  `job_scheduled` in `events`. `c` in the console cancels it at
+  once, as does `fun-ci cancel --job`. `fun-ci check` names a spacing it
+  can't read. The console needs renderer 2.3.0 to show a waiting job; an
+  older one says it is in a state it doesn't know.
+- `fun-ci cancel --job NAME` stops a daily or weekly job's run, as `c` on its
+  row does in the console, so an agent can too. The job runs again on the
+  next commit.
+- `fun-ci-renderer --version` and `--help`, for anyone who installed the
+  renderer with cargo. Before, each said it "needs a value".
+- `fun-ci check` warns when the post-commit or pre-push hook doesn't run
+  fun-ci, instead of saying all is well while no commit is tested.
+
+### Changed
+- In a worktree fun-ci has just made, as for the first runs after install or
+  `fun-ci prune`, lint and build get the slow suite's budget, since their
+  caches are empty: a cold build over 30 seconds no longer blocks the first
+  push. A run in the foreground says so, `fun-ci status` says `(new
+  worktree, budget 300s)` on their lines, and one that still runs over shows
+  the longer budget in `fun-ci why`. `status --json` gives each stage's
+  `budget`.
+- Daily and weekly jobs run at a lower priority than the stages: on macOS
+  under `taskpolicy -c utility`, elsewhere at `nice -n 19`. Before, four due
+  jobs could leave a build a fraction of the cores and push it over its
+  budget. The slow suite runs at `nice -n 10` beside the fast suite, except
+  on macOS, where nice has no measurable effect.
+- `fun-ci init` brings the fun-ci section of `AGENTS.md` (or `CLAUDE.md`) up
+  to date, so agents in a project set up with an older fun-ci learn about
+  jobs and the trunk. It replaces the section from its `## fun-ci` heading to
+  the next heading; before, it left any section it found as it was.
+
+### Fixed
+- `fun-ci trigger` given a short SHA, or a revision such as `HEAD`, kept the
+  run under what it was given, so `fun-ci status`, `wait` and `why`, which
+  look runs up by the full SHA, never found it. Runs are kept under the full
+  SHA, and the daily and weekly jobs a run starts test that commit too.
+- An agent that waited on each commit, as `fun-ci init` tells it to, kept
+  every run it made from being cancelled by the next, so their slow suites
+  ran side by side. `wait --follow-branch` no longer keeps its run going, and
+  the command a commit prints, which agents are told to run, follows the
+  branch. Run `fun-ci init` again to bring the section it wrote into
+  AGENTS.md up to date; the old one tells agents to act on `4 superseded`.
+- `fun-ci status` said `trunk unknown, the check never finished` for a run
+  whose lint, build or fast suite took longer than 25 seconds, while the
+  check was only waiting for them to end before it was recorded.
+- In a Git LFS repository, `fun-ci install-hooks` installed nothing, since
+  git-lfs had written post-commit and pre-push already, and no commit was
+  tested. It now writes hooks that run fun-ci's and then git-lfs's, giving
+  git-lfs the push's ref list as git sent it. In such a repository, run
+  `fun-ci install-hooks` again. `git lfs install` then says the hooks exist
+  and exits 2; they already run git-lfs's.
+- A mistake `fun-ci check` names in `.fun-ci/config` (a wrong
+  `worktree_slots` or `job_spacing`, or YAML it can't read) no longer stops a
+  commit's run, which let the push through untested: the trigger names it,
+  the setting takes its default, and the run goes ahead. `fun-ci check` still
+  fails on it.
+- YAML anchors and aliases in `.fun-ci/config` are read, so stages can share
+  one list of evidence entries. Before, an alias made `fun-ci check` and
+  `fun-ci trigger` die with a stack trace, and the evidence settings were
+  quietly dropped. YAML that holds a value settings can't (a date, say) is
+  named as the file's mistake instead of raised.
+
+## [2.2.0] - 2026-10-01
+
+### Added
+- Daily and weekly jobs, for checks too long for a stage's budget. A script
+  in `.fun-ci/daily/` or `.fun-ci/weekly/` runs at most once a day or once a
+  week, started by your commits, in a worktree of its own, with 24 hours to
+  finish. The console shows them in a section of their own under the table,
+  and `c` cancels a running one; on a screen too short for both, the jobs
+  give way to the branches. `fun-ci check` lists them.
+- The console's job section needs renderer 2.2.0, which the platform gems
+  bring. With an older renderer, as `cargo install` left it, the console
+  works but shows no jobs.
+- `fun-ci prune` removes the jobs' worktrees too.
+- Agents ask about jobs: `fun-ci jobs` lists them, `fun-ci why --job NAME`
+  prints what was kept about one's last run, `fun-ci status` names the jobs
+  that tested the commit and any failing on another, and `fun-ci events`
+  says when a job starts and finishes. The instructions `fun-ci init` writes
+  for agents mention them.
+
+### Fixed
+- On a short screen, a project whose branches had all passed and were left
+  out (counted beside the keys) kept its label, with nothing under it. The
+  label now goes with them.
+
 ## [2.1.1] - 2026-09-30
 
 ### Fixed

data/README.md

@@ -21,7 +21,7 @@ cd your-project
 fun-ci init --everything
 ```
 
-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.
+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; run again after an upgrade, it brings that section up to date.
 
 `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.
 
@@ -49,10 +49,31 @@ A stage that overruns its budget is killed and reported as over budget, in yello
 
 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.
+`install-hooks` leaves a hook another tool wrote alone, and `fun-ci check` warns that no commit is tested until that hook calls fun-ci. Git LFS's own hooks are the exception: fun-ci writes its hooks in their place, and they run git-lfs's after fun-ci's, so LFS objects still reach the remote. After that, `git lfs install` says the hooks exist and exits 2, since it accepts no hook but its own; there is nothing for it to do. `git lfs update --force` would put git-lfs's back, leaving fun-ci out, until you run `fun-ci install-hooks` again.
+
+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. A worktree fun-ci has just made has none of them yet, so in its first run lint and build get the slow suite's five minutes rather than 30 seconds, and `fun-ci status` says so on their lines. 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 without `--follow-branch`.
 
 Results are kept in SQLite under `$XDG_STATE_HOME/fun-ci/` (`~/.local/state/fun-ci/` by default), shared by every project on the machine.
 
+## Daily and weekly jobs
+
+Some checks take longer than the time between two commits: a mutation run, a soak test, a full audit of your dependencies. Put each in a script of its own under `.fun-ci/daily/` or `.fun-ci/weekly/`:
+
+```
+.fun-ci/daily/mutation.sh
+.fun-ci/weekly/soak.sh
+```
+
+The script's name is the job's name. Like a stage, it gets the commit's hash as its first argument and passes when it exits 0, and `FUN_CI_JOB` tells it which job it is. There is nothing else to configure.
+
+Commits start jobs. When the `post-commit` hook runs a pipeline, it also starts the project's due jobs on the commit just made: a job is due when it has never run, when its last run was cancelled, or a day (daily) or a week (weekly) after its last run started, so a project nobody commits to runs none. The jobs take turns, spread evenly over the day: with four jobs, the first starts at once and each next one six hours later. `job_spacing: 30m` in `.fun-ci/config` sets the gap instead, and `0` starts them together. A job waiting its turn says when it starts.
+
+Each job runs once at a time, in a worktree of its own under `.git/fun-ci/jobs/`, at a lower priority than the stages, so it takes only the cores they leave idle and never holds up a commit's run. It has 24 hours. A newer commit never cancels a job, and a job's result changes no run, no streak and no exit code. The [design](docs/design.md#daily-and-weekly-jobs) has the rest of the rules.
+
+A failed job keeps its evidence as a failed stage does; add entries under `evidence: jobs: <name>:` in `.fun-ci/config` to keep more. `fun-ci check` lists the jobs it found, and says which scripts it can't run.
+
+`fun-ci jobs` lists the jobs, each with how its last run went, on which commit, and when it is due again. `fun-ci why --job soak` prints everything kept about the job's last run (`--raw` for its whole output, `--json` for a document), and exits as `why` does for a stage. `fun-ci status` names the jobs whose last run tested the commit you ask about, and any job failing on another commit, and `fun-ci events` says when a job is scheduled, starts and finishes. `fun-ci cancel --job soak` stops the job's run, as `c` does in the console, so it runs again on the next commit. None of them changes a commit's verdict. A job's name is letters, digits, `.`, `_` and `-`, so those commands can be pasted as they are printed.
+
 ## Watching: the console
 
 ```bash
@@ -88,12 +109,16 @@ 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) |
 
+The daily and weekly jobs have a section of their own under the last project: each job's name, how often it runs, its mark, what its last run did on which branch and commit, and when it is due again (`passed on main 3a1f9c2 · due in 14h`), or that it runs on your next commit. When none of them failed or runs, the section folds into one pale line.
+
+![The daily and weekly jobs under the table: soak failed a day ago on wip/foo, with a red stripe, mutation running for over an hour, with a blue one, deps-audit passed and due again in 14 hours, and lint-deep due on the next commit](docs/screenshots/jobs.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: 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
+- `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. The cursor moves on past the last branch into the jobs, and `c` cancels a job too: one waiting its turn at once, a running one the same way; a cancelled job runs again on your next commit
 - `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 are the renderer's output replayed in a terminal emulator, set in Menlo; in your terminal the text is in your terminal's font.
@@ -105,10 +130,10 @@ The drawing is done by a separate program, `fun-ci-renderer`, written in Rust. T
 Every commit's output ends with the command that gets its verdict:
 
 ```
-fun-ci: testing 3f9c2ab. Verdict: fun-ci wait 3f9c2ab --need all
+fun-ci: testing 3f9c2ab. Verdict: fun-ci wait 3f9c2ab --need all --follow-branch
 ```
 
-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.
+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. With `--follow-branch`, a newer commit on the branch cancels the older run, and the wait moves on to the newer run's verdict.
 
 `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).
 
@@ -210,6 +235,8 @@ evidence:
         on: overrun
 ```
 
+Beside the entries, `evidence:` takes a few settings: `budget: 5` gives the extractors five seconds rather than two, `detect: false` stops fun-ci choosing presets from what the output shows, `skip: [rspec]` leaves out the presets named, `mask:` adds patterns of your own to mask, and `masking: false` turns masking off.
+
 `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.
@@ -224,9 +251,12 @@ 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] [--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 wait [commit] [--follow-branch]          Wait until that verdict is decided, then exit with it
 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 jobs                                     This project's daily and weekly jobs and how each stands
+fun-ci why --job <name>                         Everything kept about a job's latest run
+fun-ci cancel --job <name>                      Stop a job's run; it runs again on the next commit
 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

data/lib/fun_ci/agent/cancel_command.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "command_support"
+require_relative "../jobs/folders"
+require_relative "../persistence/active_jobs"
+
+module FunCi
+  module Agent
+    # `fun-ci cancel --job NAME` (acceptance-tests.md, AT-13.26): stops a
+    # daily or weekly job's running run, as `c` on its row in the console
+    # does, and records it cancelled, so it is due again on the next commit.
+    class CancelCommand
+      include CommandSupport
+
+      NAME = "cancel"
+
+      def initialize(context)
+        @context = context
+      end
+
+      def run(args)
+        name = Options.parse(args, takes: %i[job]).job || raise(Options::Invalid, "name the job: --job NAME")
+        raise Options::Invalid, no_job(name) unless names.include?(name)
+
+        cancel(name, Persistence::ActiveJobs.running_of(@context.db, project, name))
+      rescue Options::Invalid => e
+        usage(e.message)
+      end
+
+      private
+
+      def cancel(name, running)
+        return say("job #{name} is not running, so there is nothing to cancel.") if running.empty?
+
+        running.each { |id| @context.pipeline.cancel_job(@context.db, id) }
+        say("cancelled job #{name}; it runs again on the next commit.")
+      end
+
+      def say(message)
+        @context.io.stdout.puts "fun-ci: #{message}"
+        0
+      end
+
+      def project = @context.git.toplevel
+      def names = Jobs::Folders.new(project).jobs.map(&:name)
+
+      def no_job(name)
+        names.empty? ? JobWhy::NO_JOBS : "no job '#{name}' in this project: its jobs are #{names.join(", ")}"
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/command_support.rb

@@ -4,6 +4,7 @@ require_relative "options"
 require_relative "reports"
 require_relative "exit_code"
 require_relative "trunk_verdict"
+require_relative "job_report"
 
 module FunCi
   module Agent
@@ -31,6 +32,12 @@ module FunCi
 
       def reports = @reports ||= Reports.new(@context.db, @context.git, @context.clock, @context.trunk)
 
+      # After recording failed the jobs whose process died, which would otherwise read as running.
+      def job_reports
+        @context.pipeline.watch(@context.db)
+        JobReports.new(@context.db, @context.git.toplevel, @context.clock)
+      end
+
       def usage(message)
         @context.io.stderr.puts "fun-ci #{self.class::NAME}: #{message}"
         ExitCode::USAGE

data/lib/fun_ci/agent/commands.rb

@@ -10,6 +10,8 @@ require_relative "runs_command"
 require_relative "wait_command"
 require_relative "events_command"
 require_relative "why_command"
+require_relative "jobs_command"
+require_relative "cancel_command"
 require_relative "../trunk/local"
 
 module FunCi
@@ -18,7 +20,8 @@ module FunCi
     # database and the project's git.
     module Commands
       ALL = { "status" => StatusCommand, "runs" => RunsCommand, "wait" => WaitCommand,
-              "events" => EventsCommand, "why" => WhyCommand }.freeze
+              "events" => EventsCommand, "why" => WhyCommand, "jobs" => JobsCommand,
+              "cancel" => CancelCommand }.freeze
 
       def self.run(name, args, context)
         ALL.fetch(name).new(context).run(args)

data/lib/fun_ci/agent/due_in.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # How long until something, rounded up, since it is still to come, in the
+    # largest unit it reaches once rounded: `45m`, `22h`, `7d`; as the console says it.
+    module DueIn
+      def self.words(seconds)
+        minutes = up(seconds, 60).clamp(1..)
+        hours = up(seconds, 3600)
+        return "#{minutes}m" if minutes < 60
+        return "#{hours}h" if hours < 24
+
+        "#{up(seconds, 86_400)}d"
+      end
+
+      def self.up(seconds, unit) = (seconds.to_r / unit).ceil
+      private_class_method :up
+    end
+  end
+end

data/lib/fun_ci/agent/events_command.rb

@@ -4,19 +4,23 @@ require "json"
 require_relative "command_support"
 require_relative "snapshots"
 require_relative "events"
+require_relative "job_events"
 require_relative "waiting"
 
 module FunCi
   module Agent
     # `fun-ci events [--follow] [--only failures]` (acceptance-tests.md,
-    # AT-9.16): one JSON line per event of the project's recent runs, then,
-    # with --follow, each new one as it happens, until interrupted.
+    # AT-9.16, AT-13.23): one JSON line per event of the project's recent runs
+    # and job runs, then, with --follow, each new one as it happens, until
+    # interrupted.
     class EventsCommand
       include CommandSupport
 
       NAME = "events"
       SCHEMA = 1
       RECENT_RUNS = 10
+      # The first look: no runs, no job runs.
+      NOTHING_SEEN = [{}, {}].freeze
 
       def initialize(context)
         @context = context
@@ -24,7 +28,7 @@ module FunCi
 
       def run(args)
         options = Options.parse(args, takes: %i[follow only json])
-        seen = emit({}, options.only)
+        seen = emit(NOTHING_SEEN, options.only)
         follow(seen, options.only) if options.follow
         0
       rescue Options::Invalid => e
@@ -43,13 +47,16 @@ module FunCi
         # Following ends when whoever follows stops it.
       end
 
-      # Prints what happened since `before`, and answers the look it took.
-      def emit(before, only)
-        after = snapshots.take(limit: RECENT_RUNS)
-        Events.between(before, after).select { |event| !only || Events.failure?(event) }.each { |event| print(event) }
+      # Prints what happened since `before` ([runs, job runs]), and answers the look it took.
+      def emit((runs, jobs), only)
+        after = [snapshots.take(limit: RECENT_RUNS), snapshots.jobs(limit: RECENT_RUNS)]
+        events = Events.between(runs, after.first) + JobEvents.between(jobs, after.last)
+        events.select { |event| !only || failure?(event) }.each { |event| print(event) }
         after
       end
 
+      def failure?(event) = Events.failure?(event) || JobEvents.failure?(event)
+
       def print(event)
         @context.io.stdout.puts JSON.generate({ schema: SCHEMA, **event })
         @context.io.stdout.flush

data/lib/fun_ci/agent/job_events.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../jobs/state"
+
+module FunCi
+  module Agent
+    # What happened to a project's daily and weekly job runs between two
+    # looks at them (acceptance-tests.md, AT-13.23, AT-13.28), oldest first: a
+    # job run was scheduled to start later (Jobs::Schedule), started, and
+    # ended with its state and seconds. The first look is at nothing.
+    module JobEvents
+      # state: as Jobs::State says it; seconds: how long it ran, once it ended;
+      # starts_at: when a run waiting its turn starts, nil for any other.
+      JobState = Data.define(:id, :job, :cadence, :sha, :branch, :state, :seconds, :starts_at)
+
+      # The states of a run that has not ended.
+      GOING = %w[running due scheduled].freeze
+
+      # before, after: { job run id => JobState }.
+      def self.between(before, after)
+        after.values.sort_by(&:id).flat_map { |run| of(run, before[run.id]) }
+      end
+
+      def self.failure?(event) = event[:event] == "job_finished" && Jobs::State.needs_you?(event[:state])
+
+      def self.of(run, was)
+        about = { job: run.job, cadence: run.cadence, commit: run.sha, branch: run.branch }
+        [*begun(run, was, about), *ended(run, was, about)]
+      end
+
+      # A run first seen waiting was scheduled; one that started since the
+      # last look started.
+      def self.begun(run, was, about)
+        return [{ event: "job_scheduled", **about, starts_at: run.starts_at }] if run.state == "scheduled" && !was
+
+        started?(run, was) ? [{ event: "job_started", **about }] : []
+      end
+
+      # First seen past waiting, or past it now after it waited; one
+      # cancelled while it waited never started.
+      def self.started?(run, was)
+        return false if run.state == "scheduled"
+        return true unless was
+
+        was.state == "scheduled" && run.state != "cancelled"
+      end
+
+      def self.ended(run, was, about)
+        return [] if was&.state == run.state || GOING.include?(run.state)
+
+        [{ event: "job_finished", **about, state: run.state, seconds: run.seconds }]
+      end
+      private_class_method :of, :begun, :started?, :ended
+    end
+  end
+end

data/lib/fun_ci/agent/job_json.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # One job as `jobs --json` and `status --json` give it. Fields once
+    # published keep their names.
+    module JobJson
+      def self.document(report)
+        stage = report.stage
+        { name: report.name, cadence: report.cadence, state: report.state,
+          commit: stage && { sha: report.sha, branch: report.branch }, seconds: stage&.seconds,
+          **times(report), due: report.due? }
+      end
+
+      # When its latest run started, or, while it waits its turn, is to start
+      # (Jobs::Schedule), and when it is due again.
+      def self.times(report)
+        { started_at: iso(report.started_at), starts_at: iso(report.starts_at), due_at: iso(report.due_at) }
+      end
+
+      def self.iso(time) = time&.utc&.iso8601
+      private_class_method :times, :iso
+    end
+  end
+end

data/lib/fun_ci/agent/job_report.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "report_stage"
+require_relative "verdict"
+require_relative "../jobs/standings"
+require_relative "../persistence/raw_outputs"
+
+module FunCi
+  module Agent
+    # A daily or weekly job as an agent is told it: where it stands
+    # (Jobs::Standing), and its latest run as a RunReport::Stage named after
+    # the job, nil while it never ran, and the seconds until a run waiting its
+    # turn starts (Jobs::Schedule), nil for any other.
+    JobReport = Data.define(:standing, :stage, :starts_in)
+
+    # The jobs `status` names for a commit: those whose latest run tested it,
+    # and those failing on another commit, which an agent would not hear of otherwise.
+    CommitJobs = Data.define(:on_commit, :failing)
+
+    class CommitJobs
+      NONE = new(on_commit: [], failing: [])
+    end
+
+    class JobReport
+      VERDICTS = { "passed" => :passed, "failed" => :failed, "lost" => :failed, "over_budget" => :over_budget,
+                   "running" => :undecided, "scheduled" => :undecided }.freeze
+
+      def name = standing.name
+      def cadence = standing.cadence
+      def state = standing.state
+      def needs_you? = standing.needs_you?
+      def due_at = standing.due_at
+
+      # Whether the next commit starts it.
+      def due? = standing.due_now?
+
+      # The commit and branch its latest run tested, and when that started,
+      # or, while it waits its turn, when it is to.
+      def sha = standing.run&.dig(:commit_hash)
+      def branch = standing.run&.dig(:branch)
+      def started_at = standing.run && !starts_at ? Time.parse(standing.run[:started_at]) : nil
+      def starts_at = standing.starts_at
+
+      # As `status` would exit for a stage in this state; a job that never ran, or was cancelled, has none.
+      def verdict = VERDICTS.fetch(state, :unknown)
+    end
+
+    # The daily and weekly jobs of a project, as JobReports.
+    class JobReports
+      def initialize(db, project, clock)
+        @db = db
+        @project = project
+        @clock = clock
+      end
+
+      # By name.
+      def all = Jobs::Standings.new(@db, @project, now: @clock.now).all.map { |standing| report(standing) }
+
+      # The job named, or nil when the project has no such job.
+      def named(name) = all.find { |report| report.name == name }
+
+      # The jobs whose latest run tested `sha`, and those failing on another commit.
+      def of_commit(sha)
+        reports = all
+        CommitJobs.new(on_commit: reports.select { |report| report.sha == sha },
+                       failing: reports.select { |report| report.needs_you? && report.sha != sha })
+      end
+
+      # What the job's latest run kept of its raw output, or nil.
+      def raw_output(report) = report.stage && raw.read(report.stage.id)
+
+      private
+
+      def raw = Persistence::RawOutputs.for_jobs(@db.filename("main"))
+
+      def report(standing)
+        run = standing.run
+        JobReport.new(standing: standing, stage: run && stage(standing.name, run),
+                      starts_in: standing.starts_at && (standing.starts_at - @clock.now))
+      end
+
+      def stage(name, run)
+        RunReport::Stage.from_row(name,
+                                  run.merge(budget: run[:budget] || Jobs::Job::BUDGET, raw_bytes: raw.bytes(run[:id])))
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/job_why.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "job_report"
+require_relative "job_why_text"
+require_relative "job_why_json"
+require_relative "exit_code"
+require_relative "options"
+
+module FunCi
+  module Agent
+    # `fun-ci why --job NAME [--json] [--raw]` (acceptance-tests.md, AT-13.21):
+    # everything kept about the job's latest run, exiting as `why` does for a
+    # stage in the same state; a job that never ran has no verdict.
+    class JobWhy
+      NO_JOBS = "this project has no daily or weekly jobs; put their scripts in .fun-ci/daily/ or .fun-ci/weekly/"
+
+      def initialize(context, jobs)
+        @context = context
+        @jobs = jobs
+      end
+
+      # Raises Options::Invalid for a name that is no job of the project.
+      def answer(options)
+        report = @jobs.named(options.job) || raise(Options::Invalid, no_job(options.job))
+        return never_ran(report, options.json) unless report.stage
+
+        options.raw ? raw(report) : say(report, options.json)
+        ExitCode::FOR.fetch(report.verdict)
+      end
+
+      private
+
+      def say(report, json) = json ? print_json(report) : print_lines(JobWhyText.lines(report))
+
+      def never_ran(report, json)
+        json ? print_json(report) : print_lines([JobWhyText.never_ran(report)])
+        ExitCode::FOR.fetch(:unknown)
+      end
+
+      def raw(report)
+        text = @jobs.raw_output(report)
+        return @context.io.stdout.write(text) if text
+
+        @context.io.stderr.puts "fun-ci why: no raw output is kept for job #{report.name}"
+      end
+
+      def no_job(name)
+        names = @jobs.all.map(&:name)
+        return NO_JOBS if names.empty?
+
+        "no job '#{name}' in this project: its jobs are #{names.join(", ")}"
+      end
+
+      def print_json(report) = @context.io.stdout.puts(JSON.generate(JobWhyJson.document(report)))
+      def print_lines(lines) = lines.each { |line| @context.io.stdout.puts line }
+    end
+  end
+end

data/lib/fun_ci/agent/job_why_json.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # `fun-ci why --job NAME --json` (acceptance-tests.md, AT-13.21): the job,
+    # how its latest run ended, its evidence, or else why there is none, as
+    # `why --json` gives them for a stage. Fields once published keep their
+    # names; a change bumps SCHEMA.
+    module JobWhyJson
+      SCHEMA = 1
+
+      def self.document(report)
+        stage = report.stage
+        { schema: SCHEMA, name: report.name, cadence: report.cadence, state: report.state,
+          commit: stage && { sha: report.sha, branch: report.branch }, **ending(stage), **evidence(report),
+          raw_output: { kept: !stage&.raw_bytes.nil?, bytes: stage&.raw_bytes || 0 } }
+      end
+
+      # The evidence of a run that failed or ran over budget, or else why there is none.
+      def self.evidence(report)
+        failed = report.needs_you?
+        { evidence: failed ? report.stage.evidence.to_h : nil, no_evidence: failed ? nil : report.state }
+      end
+
+      def self.ending(stage)
+        { exit_status: stage&.exit_status, signal: stage&.signal, seconds: stage&.seconds, budget: stage&.budget }
+      end
+      private_class_method :ending, :evidence
+    end
+  end
+end