@plot-pm/board 0.16.3 → 0.18.0

package/plot-build-monitor.sh

@@ -1,480 +0,0 @@
-#!/usr/bin/env bash
-# Plot helper: the BuildMonitor — watches the RUN, and what it concluded about a sha.
-#
-# RUN, NOT SOURCED, and started by `start_worker()` in `plot-dispatch.sh` as a
-# child of the wrapper, beside the WorkerMonitor and the AgentMonitor.
-#
-# ═══════════════════════════════════════════════════════════════════════════
-# THREE MONITORS, BECAUSE THERE ARE THREE SUBJECTS
-# ═══════════════════════════════════════════════════════════════════════════
-#
-# Two monitors became three, and the reason is the one that split the first two:
-# a different subject on a different cadence.
-#
-# | monitor           | subject     | samples                      | asks                       |
-# |-------------------|-------------|------------------------------|----------------------------|
-# | **WorkerMonitor** | the process | ~30 s                        | is it doing anything?      |
-# | **AgentMonitor**  | the desk    | ~5 min                       | what does this agent owe?  |
-# | **BuildMonitor**  | the run     | ~30 s **while a run is live**| did the build change?      |
-#
-# A Build is already an entity in the spec, with its own identity and its own
-# state: DESIGN-build.md — *"is the thing that RUNS … one RESULT of one run"*,
-# identified by its URL, holding a state, a start time and a duration. **A
-# monitor per entity is the pattern, not an exception to it.**
-#
-# ═══════════════════════════════════════════════════════════════════════════
-# FOUR FINDINGS, AND `head moved` IS THE ONE THAT EARNS THIS MONITOR
-# ═══════════════════════════════════════════════════════════════════════════
-#
-# | finding                  | measurement                                        |
-# |--------------------------|----------------------------------------------------|
-# | **build failed**         | a run for this branch's head reached a failing conclusion |
-# | **build passed**         | it reached success                                 |
-# | **build needs approval** | it is `action_required`                            |
-# | **head moved**           | a newer sha exists, so the run in flight answers about the past |
-#
-# **`head moved` is why this cannot live in the AgentMonitor.** A build's
-# subject is a SHA, not a branch. A green result for code nobody will merge is
-# worse than no result — it invites a merge of the wrong thing. Measured
-# 2026-08-30: two merge waiters reported on superseded runs and had to be
-# stopped and re-armed.
-#
-# **`action_required` is a real state here, not an edge case.** Bot branches hit
-# it — the release PR's runs need manual approval before they start. A monitor
-# that folded it into "not passed yet" would report a build as pending forever
-# while it waits for a click nobody knows is needed.
-#
-# ═══════════════════════════════════════════════════════════════════════════
-# IT POLLS NOTHING WHEN NO RUN IS LIVE
-# ═══════════════════════════════════════════════════════════════════════════
-#
-# That is what makes a 30-second cadence against a host affordable, and it is
-# the property that separates this monitor's budget from the AgentMonitor's.
-# The AgentMonitor's five-minute budget exists because it asks ON EVERY PASS;
-# this one asks only while there is something to ask about.
-#
-# STRUCTURALLY, NOT INCIDENTALLY: `monitor_head_sha` is a LOCAL git read and it
-# gates the host call. `sample_finding` returns before `monitor_run_for_sha` is
-# ever reached whenever there is no head to ask about, and once a sha has
-# reached a terminal conclusion it is never asked about again. A monitor that
-# kept questioning an idle host is the rate problem this whole design avoids,
-# so the silence is asserted by the tests rather than assumed.
-#
-# ═══════════════════════════════════════════════════════════════════════════
-# THE FINDINGS ARE TRANSITIONS, NOT CONDITIONS
-# ═══════════════════════════════════════════════════════════════════════════
-#
-# The other monitors report states that PERSIST — `owes a review` holds until a
-# PR exists, and republishing it would be repeating one fact. A build's answer
-# CHANGES ONCE AND STAYS: a run that failed has failed, and it will still have
-# failed in thirty seconds.
-#
-# So the state this monitor carries is keyed by SHA as well as by finding.
-# Publishing `build passed` for one sha does not suppress `build passed` for the
-# next one — that would silence the answer an operator is actually waiting for,
-# on the very push they pushed to get it. And once a sha's build is terminal,
-# the sha is not asked about again: the answer cannot change, so continuing to
-# poll would be spending a host round trip to re-learn a fact already published.
-#
-# ═══════════════════════════════════════════════════════════════════════════
-# IT OBSERVES; IT DOES NOT ACT
-# ═══════════════════════════════════════════════════════════════════════════
-#
-# It does not rerun a workflow, approve a run that is `action_required`, merge a
-# PR that went green, or push a fix for one that went red. Every one of those is
-# a judgement with a blast radius. Approving a run in particular is a human's
-# call by construction — `action_required` EXISTS because a person is meant to
-# look — and a monitor that clicked it would defeat the gate it is reporting.
-#
-# PUBLISHING IS ITS ONLY OUTPUT, as next door: no state file, no cache, nothing
-# written into the repository it watches, not even a record of what it last
-# published. The variables that make "publish on change" work live in memory and
-# die with the process, so a restarted monitor re-derives them one interval late
-# rather than reading a stale one.
-set -uo pipefail
-
-usage() {
-  cat >&2 <<'EOF'
-Usage: plot-build-monitor.sh [--once]
-
-Started by plot-dispatch.sh inside the worker's wrapper. Reads its subject from
-the environment, exactly as the wrapper's other children do:
-
-  PLOT_BRANCH        the branch whose builds this monitor will report
-  PLOT_WORKTREE      the desk it STARTS on; it follows the manifest's
-                     `worktree` from then on (PLOT_MANIFEST_FILE below)
-  PLOT_MANIFEST_FILE the manifest this agent is named in, re-read each pass;
-                     absent or unreadable keeps watching PLOT_WORKTREE
-  PLOT_MONITOR_FILE  where findings are published (default:
-                     $PLOT_WORKTREE/.plot-worker.monitor.build.jsonl). Set
-                     explicitly, it WINS and does not follow a hop.
-  PLOT_MONITOR_INTERVAL  seconds between passes (default 30)
-
-  --once   take one sample and exit, rather than looping. A test
-           affordance: nothing dispatches this mode.
-EOF
-}
-
-once=0
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --once) once=1 ;;
-    -h|--help) usage; exit 0 ;;
-    *) echo "plot-build-monitor: unknown argument '$1'" >&2; usage; exit 2 ;;
-  esac
-  shift
-done
-
-monitor='BuildMonitor'
-
-branch="${PLOT_BRANCH:-}"
-# The branch at start, kept for a detached or unreadable desk; `monitor_branch`
-# re-reads the desk on every pass.
-start_branch="$branch"
-# THE DESK THIS MONITOR WAS LAUNCHED ON, FIXED FOR ITS WHOLE LIFE. `worktree`
-# itself is no longer fixed: `monitor_pass` reassigns it every pass by asking
-# `plot_watched_desk`, which follows a hop to the manifest's new `worktree`
-# field. This is the launch desk `plot_watched_desk` falls back to when the
-# manifest carries no override — never read directly after startup.
-launched_worktree="${PLOT_WORKTREE:-}"
-worktree="$launched_worktree"
-manifest_file="${PLOT_MANIFEST_FILE:-}"
-# THIRTY SECONDS IS AFFORDABLE ONLY BECAUSE OF THE SILENCE RULE. This cadence
-# matches the WorkerMonitor's rather than the AgentMonitor's, and it asks a HOST
-# — which would be the rate problem the AgentMonitor's 300 s exists to avoid,
-# were it asking on every pass. It is not: no live run, no question. The budget
-# is bounded by how long a build takes, not by how long a worker lives.
-interval="${PLOT_MONITOR_INTERVAL:-30}"
-
-# IF `PLOT_MONITOR_FILE` IS SET IT WINS AND DOES NOT FOLLOW THE DESK — the
-# existing contract this usage text already states. Otherwise `findings`
-# follows `worktree`, reassigned alongside it at the top of `monitor_pass`.
-monitor_file_override="${PLOT_MONITOR_FILE:-}"
-findings="${monitor_file_override:-${worktree:+$worktree/.plot-worker.monitor.build.jsonl}}"
-
-# THE SUBJECT, read the same way the other two monitors read it.
-pid_file="${PLOT_PID_FILE:-${worktree:+$worktree/.plot-worker.pid}}"
-
-# ONE ANSWER TO "IS MY SUBJECT STILL THERE?", shared with both siblings, for the
-# reason `plot-monitor-subject.sh` documents: three monitors deciding
-# independently when to stop would drift, and the failure would be silent.
-# shellcheck source=./plot-monitor-subject.sh
-. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/plot-monitor-subject.sh"
-
-# THE HOST ADAPTER, sourced for its path rather than its functions: the one
-# operation this monitor asks is `plot-host.sh run-for-sha`, and `plot-host.sh`
-# is the ONE place that talks to the host CLI. A monitor calling `gh` directly
-# would be a second adapter, and the backend split (github/bitbucket) would have
-# to be decided twice.
-host_script="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/plot-host.sh"
-
-json_escape() { # $1 = raw → prints a JSON-safe string body
-  printf '%s' "$1" | python3 -c 'import json,sys; sys.stdout.write(json.dumps(sys.stdin.read())[1:-1])' 2>/dev/null \
-    || printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
-}
-
-# A FINDING CARRIES THE SAME FOUR FIELDS the other two monitors publish —
-# `finding`, `since`, `evidence`, `measuredAt` — for the same reason: one
-# subscriber will read all three files and must not need a third parser to do
-# it.
-#
-# `since` HERE IS WHEN THE BUILD REACHED THIS ANSWER, as far as this monitor
-# can tell — the pass that first saw it. On a 30 s cadence the gap to
-# `measuredAt` is small by construction, which is the opposite of the
-# AgentMonitor's case and follows from the same field meaning the same thing.
-publish() { # $1=finding $2=evidence $3=since
-  local now
-  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-  local line
-  line=$(printf '{"monitor":"%s","branch":"%s","worktree":"%s","finding":"%s","since":"%s","evidence":"%s","measuredAt":"%s"}' \
-    "$monitor" \
-    "$(json_escape "$branch")" \
-    "$(json_escape "$worktree")" \
-    "$(json_escape "$1")" \
-    "${3:-$now}" \
-    "$(json_escape "$2")" \
-    "$now")
-  # Both destinations, for the reason the siblings give: the file is what a
-  # subscriber reads, and stdout lands in `.plot-worker.log` beside the agent's
-  # own output where an operator tailing a worker sees it.
-  [ -n "$findings" ] && printf '%s\n' "$line" >> "$findings" 2>/dev/null
-  printf 'plot-monitor %s\n' "$line"
-}
-
-# ---------------------------------------------------------------------------
-# THE PORTS — two named seams, so every branch is reachable from a test
-# ---------------------------------------------------------------------------
-#
-# Same convention as the four next door and the five beyond it: a test sources
-# this file with `PLOT_MONITOR_NO_MAIN=1` and REDEFINES them. Here there are
-# only two, and one of them is the host round trip — which is exactly the seam a
-# test can least afford to drive for real. You cannot ask GitHub for a run that
-# is `action_required` on demand, you cannot make a run vanish to order, and you
-# certainly cannot arrange two runs for two shas at the instant a test needs
-# them. Every one of those is a branch this monitor must get right.
-
-# What sha is this branch's head, right now?
-#
-# → prints the sha, or nothing when it cannot be read
-#
-# LOCAL, AND IT GATES THE HOST CALL. This is the cheap reading that makes the
-# silence rule structural: no head, no question. It reads the WORKTREE's HEAD
-# rather than a remote ref, because the head a build should be about is the one
-# the agent has actually produced — and because a fetch per pass would be a
-# second network call on a 30-second loop.
-monitor_head_sha() { # → prints a sha, or nothing
-  [ -n "$worktree" ] && [ -d "$worktree" ] || return 0
-  git -C "$worktree" rev-parse --verify --quiet HEAD 2>/dev/null || true
-}
-
-# Which branch does the desk hold, right now?
-#
-# → prints the branch, or the branch the monitor started with when the desk is
-#   detached or unreadable
-#
-# READ ON EVERY PASS, NOT ONCE. A free agent starts with an empty `PLOT_BRANCH`
-# and is handed its slices later, in the same desk; a dispatched agent hops to
-# its next slice in the same desk too. A branch fixed at start made this monitor
-# unaskable for every free agent (`monitor_run_for_sha` returns 2 on an empty
-# branch) and wrong after every hop, so the correction path in
-# `plot-worker-loop.sh` received no finding for most slices.
-monitor_branch() { # → prints a branch, or nothing
-  local current=''
-  if [ -n "$worktree" ] && [ -d "$worktree" ]; then
-    current=$(git -C "$worktree" branch --show-current 2>/dev/null || true)
-  fi
-  printf '%s' "${current:-$start_branch}"
-}
-
-# What does the host say about the run for ONE sha?
-#
-# → prints the run JSON, or nothing when there is no run for it
-# → returns 2 when the host could not be asked at all
-#
-# THE DISTINCTION BETWEEN "NO RUN" AND "COULD NOT ASK" IS THE POINT, and it is
-# the same discipline `monitor_pr_state` keeps next door. An unreachable host is
-# NOT evidence that a build is absent. A monitor that read a `gh` failure as "no
-# run" would go silent about every build on the estate the moment a token
-# expired — and silence is this monitor's healthy signal, so the failure would
-# be invisible by construction.
-#
-# An EMPTY result with a reachable host is a real and common answer: the run has
-# not been created yet. A monitor polling a fresh push sees exactly this until
-# CI wakes up, and it is not a finding.
-monitor_run_for_sha() { # $1 = sha → prints run JSON | rc 2 = unaskable
-  [ -n "$branch" ] || return 2
-  [ -x "$host_script" ] || return 2
-  local out
-  out=$("$host_script" run-for-sha "$branch" "$1" 2>/dev/null) || return 2
-  printf '%s' "$out"
-  return 0
-}
-
-# ---------------------------------------------------------------------------
-# READING ONE FIELD OUT OF THE RUN
-# ---------------------------------------------------------------------------
-#
-# `jq` where it exists and `sed` where it does not, the same fallback shape
-# `json_escape` uses above. A monitor that died because `jq` was missing would
-# be a monitor that reported nothing on exactly the machines least likely to
-# have anyone watching.
-run_field() { # $1 = json, $2 = key → prints the value, or nothing for null
-  local v
-  if command -v jq >/dev/null 2>&1; then
-    v=$(printf '%s' "$1" | jq -r --arg k "$2" '.[$k] // empty' 2>/dev/null)
-  else
-    v=$(printf '%s' "$1" | sed -n 's/.*"'"$2"'":"\([^"]*\)".*/\1/p')
-  fi
-  printf '%s' "$v"
-}
-
-# ---------------------------------------------------------------------------
-# THE SAMPLER — one pass, using only the ports above
-# ---------------------------------------------------------------------------
-#
-# THE STATE IS TWO VARIABLES AND IT IS DERIVED, as next door — but `published`
-# is keyed by SHA here, because the findings are transitions rather than
-# conditions. `published_sha` records which commit the standing answer is about,
-# so the same word about a different commit is still news.
-published=''
-published_sha=''
-since=''
-# The shas whose builds have reached a terminal answer. Once a run has failed,
-# passed, or been superseded, asking again spends a host round trip to re-learn
-# a fact already published — so it is not asked. THIS is the second half of "it
-# polls nothing when no run is live": the first half is having no head at all,
-# and this is having no OPEN question about the head there is.
-settled_shas=''
-
-sha_is_settled() { # $1 = sha → 0 settled | 1 not
-  case " $settled_shas " in *" $1 "*) return 0 ;; esac
-  return 1
-}
-
-# ---------------------------------------------------------------------------
-# ONE FINDING PER PASS, AND `head moved` COMES FIRST
-# ---------------------------------------------------------------------------
-#
-# Unlike the AgentMonitor's four, these are near-exclusive by construction — a
-# run has one status. The one genuine overlap is the one that matters: a run
-# that concluded `success` for a sha the branch has since moved past is BOTH
-# "passed" and "superseded", and reporting it as passed is precisely the failure
-# this monitor exists to prevent.
-#
-# So `head moved` is decided FIRST and about the run's own sha, not about the
-# branch: if the answer in hand describes a commit that is no longer the head,
-# the answer is about the past whatever it says.
-sample_finding() { # → prints "finding\tevidence", or nothing
-  local head
-  head=$(monitor_head_sha)
-
-  # NO HEAD, NO QUESTION. The cheap local reading refuses before anything
-  # reaches the host — the structural form of "it polls nothing when no run is
-  # live". A worktree that is gone, or a branch with no commit yet, asks
-  # nothing at all.
-  [ -n "$head" ] || return 0
-
-  # ALREADY ANSWERED. The head's build reached a terminal conclusion on an
-  # earlier pass and a build's answer does not change back. Asking again would
-  # be the idle polling this design refuses.
-  sha_is_settled "$head" && return 0
-
-  local run rc
-  run=$(monitor_run_for_sha "$head"); rc=$?
-
-  # UNASKABLE — no finding. The host could not be asked, so nothing about the
-  # build is known. Reporting anything here would be inventing an answer out of
-  # a failure to observe.
-  [ "$rc" = 2 ] && return 0
-
-  # NO RUN YET — no finding, and not an error. The commit exists and CI has not
-  # created a run for it. This is the ordinary state of a freshly pushed sha,
-  # and it is what the monitor sees on every pass until the run appears.
-  [ -n "$run" ] || return 0
-
-  local run_sha status conclusion url
-  run_sha=$(run_field "$run" sha)
-  status=$(run_field "$run" status)
-  conclusion=$(run_field "$run" conclusion)
-  url=$(run_field "$run" url)
-
-  # 1. HEAD MOVED — the run in hand is about a commit that is no longer the
-  # head. Decided BEFORE the conclusion is read, because a green run for
-  # superseded code is the specific wrong answer this monitor was built to
-  # avoid: it invites a merge of the wrong thing. Measured 2026-08-30 — two
-  # merge waiters reported on superseded runs and had to be stopped and
-  # re-armed.
-  #
-  # This fires when the host answered about a DIFFERENT sha than the one asked
-  # about, which is the shape a race actually takes: the head moved between the
-  # local read and the host's reply.
-  if [ -n "$run_sha" ] && [ "$run_sha" != "$head" ]; then
-    printf 'head moved\tthe run at %s is for %s, but the branch head is now %s; its answer is about the past\n' \
-      "${url:-an unknown url}" "$run_sha" "$head"
-    return 0
-  fi
-
-  # 2. BUILD NEEDS APPROVAL — a real state, not an edge case. Bot branches hit
-  # it: the release PR's runs need a manual click before they start. GitHub
-  # reports it as a `status` of `waiting`/`action_required` and as a
-  # `conclusion` of `action_required`, depending on where the run is, so both
-  # are read. Folding it into "not passed yet" would report the build pending
-  # forever while it waits for a click nobody knows is needed.
-  case "$status:$conclusion" in
-    *action_required*|waiting:*)
-      printf 'build needs approval\tthe run at %s for %s is waiting for a manual approval before it can start\n' \
-        "${url:-an unknown url}" "$head"
-      return 0
-      ;;
-  esac
-
-  # 3 & 4. THE TERMINAL CONCLUSIONS. An empty conclusion means the run is still
-  # going — queued or in progress — and a monitor whose subject is a transition
-  # says nothing about a state that has not changed yet.
-  [ -n "$conclusion" ] || return 0
-
-  case "$conclusion" in
-    success)
-      printf 'build passed\tthe run at %s for %s concluded success\n' "${url:-an unknown url}" "$head"
-      return 0
-      ;;
-    # EVERY OTHER TERMINAL CONCLUSION IS A FAILURE TO A READER WAITING ON GREEN.
-    # `failure`, `timed_out`, `cancelled` and `startup_failure` differ in cause
-    # and not in consequence: none of them is a build somebody may merge on. The
-    # cause is not thrown away — it rides in the evidence, where a reader
-    # deciding whether to rerun can see it.
-    *)
-      printf 'build failed\tthe run at %s for %s concluded %s\n' "${url:-an unknown url}" "$head" "$conclusion"
-      return 0
-      ;;
-  esac
-}
-
-# One full pass: sample, publish only on a change of ANSWER-ABOUT-A-COMMIT.
-monitor_pass() {
-  local row finding evidence head
-  # REASSIGNED ONCE, HERE, RATHER THAN THREADED THROUGH EACH READER. `worktree`
-  # feeds `monitor_head_sha`, `monitor_branch` and `publish()`'s own field, so a
-  # hop is picked up in one place rather than three. `PLOT_MONITOR_FILE`, when
-  # set, WINS and does not follow the desk — the existing contract the usage
-  # text states.
-  worktree=$(plot_watched_desk "$manifest_file" "$launched_worktree")
-  findings="${monitor_file_override:-${worktree:+$worktree/.plot-worker.monitor.build.jsonl}}"
-  branch=$(monitor_branch)
-  head=$(monitor_head_sha)
-  row=$(sample_finding)
-  finding="${row%%	*}"
-  evidence=''
-  case "$row" in *"	"*) evidence="${row#*	}" ;; esac
-  [ -z "$row" ] && finding=''
-
-  # PUBLISH ON A CHANGE OF EITHER THE FINDING OR THE COMMIT IT IS ABOUT. The
-  # second half is what makes these transitions rather than conditions: `build
-  # passed` for a new sha is news even though the word is the same as last
-  # time, and suppressing it would silence exactly the answer an operator
-  # pushed in order to get.
-  if [ "$finding" != "$published" ] || { [ -n "$finding" ] && [ "$head" != "$published_sha" ]; }; then
-    if [ -n "$finding" ]; then
-      since=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-      publish "$finding" "$evidence" "$since"
-      # SETTLED, so it is never asked about again. Every finding this monitor
-      # publishes is terminal for its sha: a failure stays failed, a pass stays
-      # passed, and a superseded run does not become current. Recording it here
-      # rather than in `sample_finding` keeps the decision beside the publish it
-      # follows from.
-      [ -n "$head" ] && settled_shas="$settled_shas $head"
-    fi
-    # NO CLEARING PUBLISH, and that is the difference from the AgentMonitor. A
-    # debt is cleared when it is paid — that is news. A build's answer is never
-    # withdrawn: `build failed` does not stop being true about that sha, and the
-    # next answer is a new finding about a new commit, which the sha key already
-    # carries. Publishing `clear` here would tell a subscriber a failure had
-    # been resolved when all that happened is the branch moved on.
-    published="$finding"
-    published_sha="$head"
-  fi
-}
-
-# SOURCEABLE FOR TESTS, the same guard the siblings carry. A test that wants to
-# drive `monitor_pass` against redefined ports needs the functions without the
-# loop; everything above this line defines, and nothing below it runs when the
-# guard is set.
-[ -n "${PLOT_MONITOR_NO_MAIN:-}" ] && return 0 2>/dev/null
-
-monitor_pass
-[ "$once" = 1 ] && exit 0
-
-# IT ENDS WITH ITS AGENT, by the mechanism `plot-monitor-subject.sh` documents
-# and for the reason `docs/research/2026-08-30-what-ends-a-monitor.md` measured.
-#
-# PUBLISH FIRST, THEN LEAVE. The final pass runs with the agent already gone,
-# and it matters here for a reason of its own: an agent that pushes and exits
-# leaves a run still going, and the answer arrives after there is nobody left to
-# see it. The last pass is the one chance to catch a build that concluded during
-# the shutdown.
-while plot_monitor_wait "$interval" "$pid_file"; do
-  monitor_pass
-done
-
-monitor_pass
-exit 0

package/plot-transcript-quiet.sh

@@ -1,172 +0,0 @@
-#!/usr/bin/env bash
-# The ONE answer to "how long has this worktree's agent been quiet?" — sourced,
-# not run, by `plot-worker-loop.sh` for its own watcher (`plot-worker-state.sh`'s
-# `plot_worker_idle_watch_pass`) and for its own ending message. Sourced by the
-# now-deleted `plot-worker-monitor.sh` until `bug/the-loop-reports-idle`.
-#
-# It reads the AGENT rather than the machine. A `claude -p` session appends a
-# timestamped line to its transcript for every model turn, tool call and tool
-# result; the seconds since the newest of those lines is how long the agent has
-# produced nothing. A CPU sample answers *is this process on a core right now?*,
-# which is a different question and is zero for most of a working agent's life.
-#
-# ═══════════════════════════════════════════════════════════════════════════
-# THREE ANSWERS, AND THE THIRD IS NOT A FAILURE
-# ═══════════════════════════════════════════════════════════════════════════
-#
-#   <seconds>     the newest transcript line is that many seconds old
-#   unavailable   no transcript can be read for this worktree, INCLUDING the
-#                 case where the arguments name no worktree at all
-#
-# `unavailable` is a first-class answer, settled by
-# `the-registry-supervises-its-agents`: a capability the adopting project does
-# not provide is UNAVAILABLE, never failed and never zero. A caller that read
-# it as "quiet for 0 seconds" would report every unreadable agent healthy; one
-# that read it as an error would refuse to run where Plot's own contract says
-# it should degrade. So it is a word, and callers match on it.
-#
-# ═══════════════════════════════════════════════════════════════════════════
-# THE TRANSCRIPT IS FOUND BY PATH, NOT BY SESSION ID — AND THAT IS A CHOICE
-# ═══════════════════════════════════════════════════════════════════════════
-#
-# `.plot/worker-prompt.sh:29` DOES pass `--session-id` now (2026-09-04), so an
-# exact join is available here and this deliberately does not take it. The
-# reason is the question, not the capability: this asks *is anything happening
-# at this desk*, and an operator's own session at the same worktree is a true
-# answer to it. Joining on the worker's id alone would report a desk quiet
-# while somebody is visibly working at it.
-#
-# THE OPPOSITE JOIN IS RIGHT FOR THE OPPOSITE QUESTION. *What has THIS agent
-# spent* is per session and never per worktree — one project directory measured
-# 2026-09-03 held 45 session files, 30 of them subagents, and a sum across them
-# belongs to no one. `rules/spend.ts` states that side; the two read the same
-# files and must not be made to share a join.
-#
-# A THIRD QUESTION USES BOTH KEYS: *has this worker's conversation written?* It
-# is per worktree AND per conversation handle, and it is asked as a file's
-# existence, never as a time: `plot_transcript_exists` below. The loop asks it
-# to choose `--session-id` or `--resume`; the worker monitor asks it before it
-# calls a quiet desk idle, because until the new conversation writes its first
-# line the desk's newest file belongs to the previous one. It does not change
-# the quiet number, which stays about the desk.
-#
-# So the join here is the one `plot-quiet-stretch.mjs` already made and proved
-# on 23 real sessions: the runtime stores a session under
-# `$HOME/.claude/projects/<slug>` where the slug is the WORKTREE PATH with `/`
-# and `.` replaced by `-`. A dispatched worker has its own worktree, so the
-# path identifies the DESK without any id being passed anywhere.
-#
-# `agent-` PREFIXED FILES ARE SKIPPED, for wave 1's reason: a subagent's
-# transcript is a true statement about the wrong process. A worker whose
-# subagent is chatting while the worker itself has stopped must read as quiet.
-#
-# ═══════════════════════════════════════════════════════════════════════════
-# THE NEWEST LINE ACROSS ALL OF A WORKTREE'S SESSIONS
-# ═══════════════════════════════════════════════════════════════════════════
-#
-# A worktree can hold several sessions: a worker that hopped waves, or an
-# operator who opened a session at the same desk. Any of them producing output
-# means SOMEBODY is working there, and the monitor's question is about the desk.
-# Taking the maximum timestamp is the answer that never ends a live session
-# because a stale sibling exists beside it.
-
-# The runtime's project-slug derivation. Duplicated from `plot-quiet-stretch.mjs`
-# — which duplicates it from the board's `projectSlug` — because a monitor on a
-# 30s loop must not depend on a build step. One line, pinned by a test on each
-# side.
-plot_transcript_slug() { # $1=worktree path → slug
-  printf '%s' "$1" | tr '/.' '--'
-}
-
-# Where the runtime keeps this worktree's transcripts, or "" if nowhere.
-plot_transcript_dir() { # $1=worktree → directory path (may not exist)
-  local wt="$1" home="${PLOT_TRANSCRIPT_HOME:-${HOME:-}}"
-  [ -n "$wt" ] && [ -n "$home" ] || return 0
-  printf '%s/.claude/projects/%s' "$home" "$(plot_transcript_slug "$wt")"
-}
-
-# Seconds since this worktree's agent last wrote anything.
-#
-# THE MTIME IS THE READING, not the file's contents. The runtime appends as it
-# works, so the file's modification time IS the timestamp of its newest line —
-# and reading it costs one `stat` rather than parsing a transcript that reaches
-# tens of megabytes on a long session. Wave 1 parsed timestamps because it was
-# measuring a DISTRIBUTION of past gaps; this needs only the newest, on a 30s
-# loop, for as many workers as the machine holds.
-#
-# A CLOCK IS THE RIGHT INSTRUMENT HERE, and that is worth stating because Plot
-# usually refuses one. `plot-estate-changed.sh` hashes content rather than
-# reading mtime, because its question is *did this change?* and a checkout moves
-# mtime without changing anything. This question is *how long since output?* —
-# which is a question about elapsed time, and mtime is the measurement of it.
-plot_transcript_quiet_seconds() { # $1=worktree → seconds | unavailable
-  local wt="$1" dir newest now mtime
-  dir=$(plot_transcript_dir "$wt")
-  [ -n "$dir" ] && [ -d "$dir" ] || { printf 'unavailable'; return 0; }
-
-  # The newest mtime across every non-`agent-` session file in the directory.
-  # `find -print0` and a while-read keep paths with spaces intact; `stat` is
-  # asked once per file, and a worktree holds one to eight.
-  newest=''
-  while IFS= read -r -d '' f; do
-    case "$(basename "$f")" in agent-*) continue ;; esac
-    mtime=$(plot_transcript_mtime "$f") || continue
-    [ -n "$mtime" ] || continue
-    if [ -z "$newest" ] || [ "$mtime" -gt "$newest" ] 2>/dev/null; then newest="$mtime"; fi
-  done < <(find "$dir" -maxdepth 1 -type f -name '*.jsonl' -print0 2>/dev/null)
-
-  # A directory that exists but holds no session file is still UNAVAILABLE. The
-  # runtime creates the directory when the project is first opened, so an empty
-  # one means no session has written here — which is exactly "no transcript can
-  # be read", not "quiet for a very long time".
-  [ -n "$newest" ] || { printf 'unavailable'; return 0; }
-
-  now=$(date +%s)
-  local quiet=$(( now - newest ))
-  # A transcript written in the future — a clock skew across a mounted volume —
-  # reads as zero rather than negative. An end condition comparing a negative
-  # against a threshold would behave correctly by accident here and not
-  # elsewhere; clamping says what is meant.
-  [ "$quiet" -lt 0 ] && quiet=0
-  printf '%s' "$quiet"
-}
-
-# Does the conversation `id` have a transcript at this worktree?
-#
-# EXISTENCE, NOT A TIMESTAMP. The runtime creates `<id>.jsonl` with its first
-# line and appends to it after, under both `--session-id` and `--resume`. So the
-# file's presence says the conversation has written, and no comparison of
-# clocks is made, so a file created in the same second as a manifest write
-# reads as present.
-#
-# NO HANDLE AND NO FILE ARE ONE ANSWER HERE, and a caller that must tell them
-# apart checks the handle first. `session_flag` reads both as *create*; the
-# monitor's port does not, because a monitor with no handle must not read every
-# quiet worker as unspoken.
-plot_transcript_exists() { # $1=worktree $2=id → 0 found | 1 not
-  local wt="$1" id="$2" dir
-  [ -n "$wt" ] && [ -n "$id" ] || return 1
-  dir=$(plot_transcript_dir "$wt" 2>/dev/null) || return 1
-  [ -n "$dir" ] || return 1
-  [ -f "$dir/$id.jsonl" ]
-}
-
-# A file's modification time as a unix epoch. BSD and GNU `stat` disagree on the
-# flag, and a monitor that works on the author's laptop and not in CI is a
-# monitor nobody trusts.
-#
-# THE `||` IS NOT ENOUGH, AND CI MEASURED WHY. On Linux `stat -f` is not an
-# unknown flag — it means FILESYSTEM info, and it SUCCEEDS. So the BSD form
-# never falls through: it printed `Namelen: 255  Type: ext2/ext3` and the
-# caller subtracted that from a clock. Two of this branch's own tests failed on
-# it, 2026-09-02, having passed on macOS.
-#
-# So the answer is validated rather than trusted. Each form must yield digits;
-# anything else is treated as that form not being available here.
-plot_transcript_mtime() { # $1=file → epoch seconds
-  local m
-  m=$(stat -c '%Y' "$1" 2>/dev/null)
-  case "$m" in ''|*[!0-9]*) m=$(stat -f '%m' "$1" 2>/dev/null) ;; esac
-  case "$m" in ''|*[!0-9]*) return 1 ;; esac
-  printf '%s' "$m"
-}