fun_ci 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 363808a79c7bf82b45f577fdc241e10ab866a11d2966fdc6b52ad583e1a35ce7
-  data.tar.gz: 9932aa6e0b9b1c2cf506032bca183046e02b71ea583f4cd66affd1dbe2311df9
+  metadata.gz: b55c9059ad2ffd38aa87dd4dd9958631a14390bcae0e0e7577e78bd83d4c530f
+  data.tar.gz: 6c40537e0a4eb9425dc9eab279e22dec5fdfe0142bab07b49c47f290cdaceeb3
 SHA512:
-  metadata.gz: a0b58e24f2d166894afa311971af5b42992535a9befbbbbdcdcd4a9afe6e6c3f7ff396d5c63bc9e31262c5e4b8a0fed95572bbca63b6f32749fcaba75beeee80
-  data.tar.gz: 16be19fcf7a864a7d573f6b64bfbbad7024dd0bbfd371c0b515ca304202135d6f37046f7e09ad64b27606565e7ac71345a828dd761e195cbc61c1303107ee976
+  metadata.gz: 82576ff9731c282102710ad24d83b2ff3430a71bab671b33d6823dd507a47ec3855ccf912afbff706b9514d2f045313bd69461aa3076dbf85673b17e2db32920
+  data.tar.gz: 28c718c40751cf17bdc74bba6db5f8b07d4d9ecf889409b7861563302c22c10590f54f82680facbaf5d0000552d5ed8344831eff856fb9927acaf6f113383242

data/CHANGELOG.md

@@ -7,6 +7,77 @@ 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

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,7 +49,9 @@ 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.
 
@@ -64,11 +66,13 @@ Some checks take longer than the time between two commits: a mutation run, a soa
 
 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 each of the project's jobs that is due, beside the pipeline, 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. A project nobody commits to runs no jobs. Each job runs once at a time, in a worktree of its own under `.git/fun-ci/jobs/`, so it never holds up a commit's run, and has 24 hours before it is stopped. A newer commit never cancels a job. A job's result changes no run, no streak and no exit code.
+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 starts and finishes. 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.
+`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
 
@@ -114,7 +118,7 @@ A branch that conflicts with the trunk says so on the line under its name, `conf
 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. The cursor moves on past the last branch into the jobs, and `c` cancels a running job the same way; a cancelled job runs again on your next commit
+- `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.
@@ -126,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).
 
@@ -231,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.
@@ -245,11 +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/commands.rb

@@ -11,6 +11,7 @@ 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
@@ -19,7 +20,8 @@ module FunCi
     # database and the project's git.
     module Commands
       ALL = { "status" => StatusCommand, "runs" => RunsCommand, "wait" => WaitCommand,
-              "events" => EventsCommand, "why" => WhyCommand, "jobs" => JobsCommand }.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/job_events.rb

@@ -5,14 +5,16 @@ 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), oldest first: a job run
-    # started, and ended with its state and seconds. The first look is at nothing.
+    # 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.
-      JobState = Data.define(:id, :job, :cadence, :sha, :branch, :state, :seconds)
+      # 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].freeze
+      GOING = %w[running due scheduled].freeze
 
       # before, after: { job run id => JobState }.
       def self.between(before, after)
@@ -23,7 +25,24 @@ module FunCi
 
       def self.of(run, was)
         about = { job: run.job, cadence: run.cadence, commit: run.sha, branch: run.branch }
-        [*(was ? [] : [{ event: "job_started", **about }]), *ended(run, was, about)]
+        [*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)
@@ -31,7 +50,7 @@ module FunCi
 
         [{ event: "job_finished", **about, state: run.state, seconds: run.seconds }]
       end
-      private_class_method :of, :ended
+      private_class_method :of, :begun, :started?, :ended
     end
   end
 end

data/lib/fun_ci/agent/job_json.rb

@@ -9,8 +9,17 @@ module FunCi
         stage = report.stage
         { name: report.name, cadence: report.cadence, state: report.state,
           commit: stage && { sha: report.sha, branch: report.branch }, seconds: stage&.seconds,
-          started_at: report.started_at&.utc&.iso8601, due_at: report.due_at&.utc&.iso8601, due: report.due? }
+          **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

@@ -10,8 +10,9 @@ 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.
-    JobReport = Data.define(:standing, :stage)
+    # 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.
@@ -23,7 +24,7 @@ module FunCi
 
     class JobReport
       VERDICTS = { "passed" => :passed, "failed" => :failed, "lost" => :failed, "over_budget" => :over_budget,
-                   "running" => :undecided }.freeze
+                   "running" => :undecided, "scheduled" => :undecided }.freeze
 
       def name = standing.name
       def cadence = standing.cadence
@@ -34,10 +35,12 @@ module FunCi
       # Whether the next commit starts it.
       def due? = standing.due_now?
 
-      # The commit and branch its latest run tested, and when that started.
+      # 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 && Time.parse(standing.run[:started_at])
+      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)
@@ -73,7 +76,8 @@ module FunCi
 
       def report(standing)
         run = standing.run
-        JobReport.new(standing: standing, stage: run && stage(standing.name, 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)

data/lib/fun_ci/agent/job_why_text.rb

@@ -3,6 +3,7 @@
 require_relative "stage_summary"
 require_relative "evidence_text"
 require_relative "span"
+require_relative "starts_in"
 
 module FunCi
   module Agent
@@ -16,7 +17,7 @@ module FunCi
 
       def self.lines(report)
         summary = StageSummary.line(report.stage, seconds: Span.method(:words))
-        [header(report), summary, *body(report.stage), *raw(report), *only_tail(report)]
+        [header(report), summary, *body(report), *raw(report), *only_tail(report)]
       end
 
       def self.header(report) = "fun-ci: job #{report.name} (#{report.cadence}) on #{report.branch} #{report.sha[0, 7]}"
@@ -25,7 +26,9 @@ module FunCi
         "fun-ci: job #{report.name} (#{report.cadence}) has not run yet; it runs on the next commit."
       end
 
-      def self.body(stage)
+      def self.body(report)
+        stage = report.stage
+        return [waiting(report)] if report.starts_in
         return [PASSED] if stage.state == "passed"
         return [RUNNING] if stage.state == "running"
         return [CANCELLED] if stage.state == "cancelled"
@@ -33,6 +36,11 @@ module FunCi
         EvidenceText.lines(stage.evidence)
       end
 
+      def self.waiting(report)
+        "It waits its turn, and #{StartsIn.words(report.starts_in)}; " \
+          "fun-ci cancel --job #{report.name} cancels it."
+      end
+
       def self.raw(report)
         report.stage.raw_bytes ? ["", "The whole output: fun-ci why --job #{report.name} --raw"] : []
       end
@@ -45,7 +53,7 @@ module FunCi
         ["", "Only the output's last lines were kept; extractors under `evidence: jobs: #{report.name}:` " \
              "in .fun-ci/config keep more."]
       end
-      private_class_method :body, :raw, :only_tail
+      private_class_method :body, :waiting, :raw, :only_tail
     end
   end
 end

data/lib/fun_ci/agent/jobs_text.rb

@@ -2,6 +2,7 @@
 
 require_relative "age"
 require_relative "due_in"
+require_relative "starts_in"
 require_relative "span"
 
 module FunCi
@@ -14,7 +15,7 @@ module FunCi
     # command of each job that failed or ran over budget.
     module JobsText
       WORDS = { "passed" => "ok", "failed" => "FAIL", "lost" => "LOST", "over_budget" => "OVER", "running" => "...",
-                "due" => "due", "cancelled" => "x" }.freeze
+                "due" => "due", "cancelled" => "x", "scheduled" => "wait" }.freeze
 
       # now: the time the ages and due times count from.
       def self.lines(reports, now)
@@ -34,13 +35,17 @@ module FunCi
         "#{head}  #{seconds(report.stage)}  #{tested(report, now)}  #{due(report, now)}"
       end
 
-      # `wip/foo 9e0b1d4  1h ago`
-      def self.tested(report, now) = "#{report.branch} #{report.sha[0, 7]}  #{Age.words(now - report.started_at)}"
+      # `wip/foo 9e0b1d4  1h ago`; a run waiting its turn has not started.
+      def self.tested(report, now)
+        commit = "#{report.branch} #{report.sha[0, 7]}"
+        report.started_at ? "#{commit}  #{Age.words(now - report.started_at)}" : commit
+      end
 
       def self.seconds(stage) = (stage.seconds ? Span.words(stage.seconds) : "").rjust(6)
 
       def self.due(report, now)
         return "running" if report.state == "running"
+        return StartsIn.words(report.starts_in) if report.starts_in
 
         report.due_at ? "due in #{DueIn.words(report.due_at - now)}" : "runs on the next commit"
       end

data/lib/fun_ci/agent/live_pipeline.rb

@@ -6,10 +6,10 @@ require_relative "../setup/project_config"
 
 module FunCi
   module Agent
-    # The project's pipeline, as `wait` starts and watches it: a run starts
-    # the way the post-commit hook starts one, with `fun-ci trigger
-    # --background` in a process of its own, rather than as a fork of the
-    # waiting process and its open database connection.
+    # The project's pipeline, as `wait` starts and watches it and `cancel`
+    # stops a job of it: a run starts the way the post-commit hook starts one,
+    # with `fun-ci trigger --background` in a process of its own, rather than
+    # as a fork of the waiting process and its open database connection.
     class LivePipeline
       FUN_CI = File.expand_path("../../../exe/fun-ci", __dir__)
 
@@ -35,6 +35,9 @@ module FunCi
         canceller.record_dead(db)
         canceller.record_dead_jobs(db)
       end
+
+      # Stops a daily or weekly job's run and records it cancelled, as the console does.
+      def cancel_job(db, id) = Pipeline::RunCanceller.new.cancel_job(db, id)
     end
   end
 end

data/lib/fun_ci/agent/snapshots.rb

@@ -37,9 +37,13 @@ module FunCi
       def job_state(run)
         JobEvents::JobState.new(id: run[:id], job: run[:job], cadence: run[:cadence], sha: run[:commit_hash],
                                 branch: run[:branch], state: Jobs::State.of(run),
-                                seconds: Persistence::StageJob.elapsed_duration(run)&.round(1))
+                                seconds: Persistence::StageJob.elapsed_duration(run)&.round(1),
+                                starts_at: starts_at(run))
       end
 
+      # When a run waiting its turn starts, as an ISO time; nil for any other.
+      def starts_at(run) = run[:status] == "scheduled" ? Time.parse(run[:started_at]).utc.iso8601 : nil
+
       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],

data/lib/fun_ci/agent/starts_in.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "due_in"
+
+module FunCi
+  module Agent
+    # When a job waiting its turn (Jobs::Schedule) starts, as agents are
+    # told it: `starts in 6h`, or `starts now` once its time has come and its
+    # process has yet to start it.
+    module StartsIn
+      def self.words(seconds) = seconds.positive? ? "starts in #{DueIn.words(seconds)}" : "starts now"
+    end
+  end
+end

data/lib/fun_ci/agent/status_json.rb

@@ -19,7 +19,7 @@ module FunCi
       def self.unknown(sha) = { schema: SCHEMA, commit: { sha: sha }, verdict: "unknown" }
 
       def self.stage(stage)
-        facts = { name: stage.name, state: stage.state, seconds: stage.seconds }
+        facts = { name: stage.name, state: stage.state, seconds: stage.seconds, budget: stage.budget }
         stage.failures.any? ? facts.merge(failures: stage.failures) : facts
       end
       private_class_method :stage

data/lib/fun_ci/agent/status_text.rb

@@ -5,6 +5,8 @@ require_relative "verdict"
 require_relative "digest"
 require_relative "trunk_text"
 require_relative "job_report"
+require_relative "starts_in"
+require_relative "../pipeline/budgets"
 
 module FunCi
   module Agent
@@ -29,10 +31,13 @@ module FunCi
       # `  soak (weekly job) FAILED  fun-ci why --job soak`; `where` names the
       # commit it tested when that is another.
       def self.job_line(job, where = "")
-        said = "  #{job.name} (#{job.cadence} job) #{WORDS.fetch(job.state, job.state)}#{where}"
+        said = "  #{job.name} (#{job.cadence} job) #{WORDS.fetch(job.state, job.state)}#{starts(job)}#{where}"
         job.needs_you? ? "#{said}  fun-ci why --job #{job.name}" : said
       end
 
+      # `, starts in 8m` for a job waiting its turn.
+      def self.starts(job) = job.starts_in ? ", #{StartsIn.words(job.starts_in)}" : ""
+
       # 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)
@@ -45,10 +50,17 @@ module FunCi
 
       def self.stage_line(stage, needed)
         seconds = stage.seconds ? format("%6.1fs", stage.seconds) : " " * 7
-        note = needed.include?(stage.name) ? "" : " (not needed)"
+        note = (needed.include?(stage.name) ? "" : " (not needed)") + longer(stage)
         "  #{stage.name.ljust(6)} #{WORDS.fetch(stage.state, stage.state).ljust(12)}#{seconds}#{note}".rstrip
       end
 
+      # Only a worktree just made gives a stage more than its usual budget
+      # (AT-1.14), which a run in the background says nowhere else.
+      def self.longer(stage)
+        usual = Pipeline::DEFAULT_BUDGETS[stage.name]
+        stage.budget && usual && stage.budget > usual ? "  (new worktree, budget #{stage.budget}s)" : ""
+      end
+
       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"
@@ -56,7 +68,7 @@ module FunCi
 
         ["Superseded by #{report.superseded_by[0, 7]}."]
       end
-      private_class_method :stage_line, :footer, :job_lines, :job_line
+      private_class_method :stage_line, :longer, :footer, :job_lines, :job_line, :starts
     end
   end
 end

data/lib/fun_ci/agent/trunk_reading.rb

@@ -28,7 +28,8 @@ module FunCi
         return shown(check) if check
 
         started = run[:trunk_started_at]
-        started && Trunk::Shown.unchecked(started: Time.parse(started), now: @clock.now)
+        started && Trunk::Shown.unchecked(started: Time.parse(started), now: @clock.now,
+                                          stages_running: !run[:trigger_pid].nil?)
       end
 
       # Checks the commit against where the trunk is now, without fetching, and keeps the check,

data/lib/fun_ci/agent/wait_command.rb

@@ -52,9 +52,10 @@ module FunCi
         ExitCode::FOR.fetch(report.verdict)
       end
 
+      # A waiter keeps its run from being superseded, unless it follows the branch to the newer commit.
       def poll(sha, options)
         @context.pipeline.watch(@context.db)
-        reports.mark_waited(sha, @context.clock.now)
+        reports.mark_waited(sha, @context.clock.now) unless options.follow_branch
         report_for(sha, options) || start_after_grace(sha)
       end
 

data/lib/fun_ci/cli.rb

@@ -17,7 +17,7 @@ module FunCi
       "prune" => :run_prune,
       "extract" => :run_extract
     }.freeze
-    AGENT_COMMANDS = %w[status runs wait events why jobs].freeze
+    AGENT_COMMANDS = %w[status runs wait events why jobs cancel].freeze
 
     def self.default_db_dir = Persistence::StateDir.path(ENV)
 

data/lib/fun_ci/cli_help.rb

@@ -32,6 +32,7 @@ module FunCi
         events         Print this project's runs' events as JSON lines
         why            Print everything kept about why a commit's stage failed, or its conflict with the trunk
         jobs           List this project's daily and weekly jobs and how each stands
+        cancel         Cancel a daily or weekly job's run: cancel --job NAME
         extract        Try a stage's evidence extractors on a saved output
 
       Options:
@@ -47,7 +48,7 @@ module FunCi
         --follow-branch  (wait) Move on to the newer commit that superseded the run
         --trunk        (status, wait) Exit 6 when the run passed but conflicts with the trunk
         --raw          (why) Print the stage's whole output as it was kept
-        --job NAME     (why) Explain the daily or weekly job's latest run instead of a commit's stage
+        --job NAME     (why, cancel) The daily or weekly job to explain or cancel, instead of a commit
         -n N           (runs) How many runs to list (default 10)
         --branch NAME  (runs) Only runs on this branch
         --follow       (events) Keep printing events as they happen, until stopped