@plot-pm/board 0.16.2 → 0.17.0

package/plot-resolve-artifact.sh

@@ -1,423 +0,0 @@
-#!/usr/bin/env bash
-# Plot helper: repair an ARTIFACT-ONLY merge conflict on one branch.
-# Usage: plot-resolve-artifact.sh [--dry-run] <branch>
-#   --dry-run   print the sequence and the worktree it would use; change nothing
-#   <branch>    the branch to repair — must already exist on origin
-# Output: one `step:` line per stage, then a machine-countable footer:
-#     summary: branch=<name> outcome=pushed|abandoned|refused reason=<word>
-#
-# THE ONLY AUTOMATIC WRITE THIS SYSTEM GRANTS, and it is granted for three
-# verified reasons rather than for convenience:
-#
-#   1. `-merge` KEEPS THE FILE VALID. `.gitattributes` marks every bundle
-#      `-merge`, so git keeps one side whole and writes NO conflict markers.
-#      The artifact stays buildable JavaScript *through* a conflict — which is
-#      why a script may touch it at all. `scripts/check-bundle-attributes.sh`
-#      is the gate that keeps that true of every bundle rather than of one.
-#   2. THE REBUILD IS DETERMINISTIC. Measured: `build.mjs` embeds no timestamp
-#      and no randomness, so the output does not depend on which side was kept.
-#   3. CI PROVES IT. The no-diff gate fails the build if the committed artifact
-#      does not match a fresh rebuild.
-#
-# Together those make this the one repair whose correctness is checkable
-# WITHOUT JUDGEMENT. That is the whole licence. No other failure has these
-# three properties, and none may be added to this path — widening the entry
-# condition removes the argument that grants the permission, even if the code
-# looks correct.
-#
-# THIS IS A SCRIPT AND NOT AN AGENT, deliberately. Every step below is fixed
-# and nothing between them is a decision, which is *precisely* what licenses the
-# automation. Handing the sequence to an agent would introduce judgement exactly
-# where its absence is the permission. (Measured on 2026-08-17: this repo has no
-# `Worker command` configured either, so plot-dispatch.sh would report
-# `worker=unconfigured` and start nothing — but the shape is the reason, not
-# the measurement.)
-#
-# TESTS RUN BEFORE THE PUSH. The CI no-diff gate is what makes the repair
-# checkable, and CI runs only AFTER a push — so a resolver that pushed and
-# waited would manufacture exactly the state this exists to remove: a red PR in
-# the queue. The sequence therefore ends on `pnpm run test:board` green in the
-# branch's own worktree, and CI becomes confirmation rather than discovery.
-#
-# IF THE SUITE FAILS, NOTHING IS PUSHED. The repair stopped being mechanical the
-# moment its own gate said so; the branch is left exactly as it was, and the
-# board reports it as a conflict a human owns.
-#
-# IT MERGES ONLY IN A WORKTREE THAT IS IDLE. A worktree carrying modifications
-# belongs to whoever made them — measured on 2026-08-17, the resolver ran its
-# merge inside one an agent was actively editing. It refuses `worktree-busy`
-# rather than reaching in, which the plan names the honest minimum: a second
-# worktree on the same branch is not available to it anyway, since git refuses a
-# second checkout of one branch.
-#
-# AN EMPTY CONFLICT SET IS NOT A REFUSAL ABOUT FILES. Three cases, named apart,
-# because two of them were once one:
-#
-#   bundles only          → the licensed case                    → repair
-#   other files present   → needs judgement                      → not-artifact-only
-#   empty, no merge ran   → nothing was observed                 → not-observed
-#
-# The last is not a smaller version of the middle. `not-artifact-only` asserts
-# something about the files that conflicted, and a set of zero has none to
-# assert it about — saying it there sends a reader to look for files nobody ever
-# examined.
-#
-# WHICH SIDE IS TAKEN CANNOT MATTER, and the diff is never read. `--theirs` is
-# named here only because `git checkout` needs a word: the rebuild overwrites
-# whichever side was kept. Never phrase it as "take ours" — under `git merge`
-# *ours* is the branch being merged into, under `git rebase` it is the upstream,
-# and this repo rebases routinely.
-set -uo pipefail
-
-script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-. "$script_dir/plot-tmp.sh"
-
-# THE FILES THIS SCRIPT MAY RESOLVE — a SET, and derived rather than listed.
-#
-# It was one hardcoded filename until 2026-09-06, and that cost a repair the
-# same day: PR #727 conflicted in `plot-registryd.mjs` — a `-merge` bundle with
-# a deterministic rebuild, exactly the licensed case — and this script refused
-# `not-artifact-only` against a list naming only `board-server.mjs`. The refusal
-# was correct behaviour against a stale list. Hours later the same branch
-# conflicted in `board-server.mjs` and was repaired automatically: same class of
-# conflict, opposite outcome, one filename apart.
-#
-# DERIVED FROM `build.mjs`'S OWN DECLARATIONS, by the same pipeline
-# `scripts/check-bundle-attributes.sh` uses, because a hand-written list here
-# would be a fourth place to drift — and drift is the defect this replaces. The
-# build declares each output as `const shippedX = path.join(here, '…')`, which
-# is what an author writes when adding a bundle; nothing else has to be
-# remembered. Nine bundles today; `plot-landed.mjs` arrived while the plan that
-# asked for this was still in draft, and the derivation found it.
-#
-# `plot-monitor.mjs` IS DELIBERATELY ABSENT. It is committed and documented, and
-# no `outfile` names it — nothing rebuilds it. Property 2 above is the whole
-# licence, so a file with no deterministic rebuild cannot be on this list. The
-# derivation reads the build, so it cannot ask for it.
-#
-# Still named in the board's contract as well, because the two run in different
-# languages and neither can import the other's constant. The pairing is asserted
-# by a test rather than trusted — and that test now asserts SET EQUALITY, since
-# a set that agrees on one member and differs on another is exactly the drift
-# this replaces.
-#
-# READ FROM THE REPOSITORY BEING REPAIRED, not from this script's own checkout.
-# The script is vendored into the published package, where `packages/` does not
-# exist — and it rebuilds with `pnpm build:board` inside the target repo, so the
-# build that defines the set is the one that will run. Resolved below, once
-# `repo_root` is known.
-bundle_set() { # $1=repo root → one path per line, sorted
-  grep -aoE "shipped[A-Za-z]* = path\.join\([^)]*'[^']*'\)" "$1/packages/board/build.mjs" 2>/dev/null \
-    | sed -E "s|.*'\.\./\.\./([^']*)'.*|\1|" \
-    | sort -u
-}
-
-dry_run=0
-branch=""
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --dry-run) dry_run=1 ;;
-    -*) echo "plot-resolve-artifact: unknown option '$1'" >&2; exit 2 ;;
-    *) branch="$1" ;;
-  esac
-  shift
-done
-
-# The footer travels on EVERY exit path, including the refusals. A run that
-# ends without one is indistinguishable from a crash, and a silent automatic
-# write is the failure mode this whole plan exists to remove.
-finish() { # $1=outcome $2=reason
-  echo "summary: branch=$branch outcome=$1 reason=$2"
-  case "$1" in
-    pushed) exit 0 ;;
-    *) exit 1 ;;
-  esac
-}
-
-[ -n "$branch" ] || { echo "usage: plot-resolve-artifact.sh [--dry-run] <branch>" >&2; exit 2; }
-
-git rev-parse --git-dir >/dev/null 2>&1 || {
-  echo "plot-resolve-artifact: not a git repository" >&2
-  finish refused not-a-repo
-}
-
-MAIN=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')
-[ -n "$MAIN" ] || MAIN="main"
-
-repo_root=$(git rev-parse --show-toplevel)
-
-# THE SET, resolved against the repository this run will rebuild.
-ARTIFACT_PATHS=$(bundle_set "$repo_root")
-
-# AN EMPTY DERIVATION REFUSES, and it must: the guard below asks whether every
-# unmerged path is in this set, and against an empty set that question has no
-# true answer to give — but a guard written the other way round would have said
-# yes to everything. The build changing shape, or a checkout with no
-# `packages/`, is a reason to stop rather than a reason to repair blind.
-if [ -z "$ARTIFACT_PATHS" ]; then
-  echo "step: no bundles derived from packages/board/build.mjs — refusing"
-  finish refused no-bundle-set
-fi
-
-# WHICH WORKTREE HOLDS THIS BRANCH — ASK GIT, do not reconstruct the path from
-# the branch name.
-#
-# MEASURED, and recorded at length in plot-dispatch.sh's held_worktree: a
-# hand-made worktree is named for the branch with its TYPE dropped, so a gate
-# that guessed `plot-wt-<flattened>` missed a worktree with six modified files
-# in it. Desks carry two naming conventions — `plot-wt-*` beside the repo from
-# older dispatches, and unprefixed names under the desk root — so a path guess
-# has two ways to be wrong. So the read asks git, and only the
-# CREATE-a-fresh-one fallback below composes a name (under the desk root, so the
-# fresh worktree lands where dispatch would have put it).
-#
-# `git worktree list --porcelain` emits `worktree <path>` then `branch
-# refs/heads/<name>` per entry; the branch line is matched and the path taken
-# from the preceding one. A branch already dispatched is thus repaired in the
-# worktree it is already checked out in rather than in a second copy of itself —
-# git refuses a second checkout of one branch, and the two would fight over the
-# same index if it did not.
-wt=$(git worktree list --porcelain </dev/null 2>/dev/null | awk -v want="refs/heads/$branch" '
-  /^worktree /  { path = substr($0, 10) }
-  /^branch /    { if (substr($0, 8) == want) { print path; exit } }')
-
-# No existing worktree holds it — compose the path a fresh one will take, under
-# the desk root `plot-dispatch.sh` also asks for, so the fresh worktree lands
-# where dispatch would have put it. The root is the MAIN checkout's, and there
-# is no fallback: an unaskable rule refuses the repair.
-# shellcheck source=plot-desk-root.sh
-. "$script_dir/plot-desk-root.sh"
-if [ -z "$wt" ]; then
-  wt_root=$(plot_desk_root "$(plot_repo_root)") || finish refused no-desk-root
-  wt="$wt_root/$(printf '%s' "$branch" | tr '/' '-')"
-fi
-
-if [ "$dry_run" = 1 ]; then
-  echo "step: would use worktree $wt"
-  echo "step: would merge origin/$MAIN, take a side of each conflicted bundle, rebuild, test"
-  printf 'step: bundle set (%s): %s\n' \
-    "$(printf '%s\n' "$ARTIFACT_PATHS" | grep -c .)" \
-    "$(printf '%s' "$ARTIFACT_PATHS" | tr '\n' ' ')"
-  echo "step: would push only if pnpm run test:board passes"
-  finish refused dry-run
-fi
-
-git fetch -q origin "$MAIN" "$branch" 2>/dev/null || true
-
-# ONE REPAIR AT A TIME, AND NEVER TWO ON ONE BRANCH.
-#
-# A second run while the first is working would fight over the same worktree:
-# the merge, the rebuild and the five-minute suite all write into it, and two of
-# them interleaved produce an artifact belonging to neither run. The lock is a
-# DIRECTORY rather than a file because `mkdir` is atomic on every filesystem
-# this runs on — two processes racing it, one wins, and the loser learns it lost
-# from the exit code rather than from a check-then-write that both pass.
-#
-# The board guards its own in-flight repairs too, in memory. Both are needed and
-# neither is redundant: the board's registry cannot see a repair started by a
-# second board or by a human at a shell, and this lock cannot stop the board
-# from spawning (it learns only after the spawn). The lock is the authority.
-lock="$repo_root/.plot/state/resolve-$(printf '%s' "$branch" | tr '/' '-').lock"
-mkdir -p "$(dirname "$lock")" 2>/dev/null || true
-if ! mkdir "$lock" 2>/dev/null; then
-  echo "step: a repair is already in flight for $branch ($lock)"
-  finish refused already-in-flight
-fi
-# Released on every exit, including a kill. A lock that outlives its process
-# would make one interrupted repair block the branch forever — and the repair is
-# idempotent, so there is nothing to protect after the process is gone. A TERM
-# or INT stops the repair (143 or 130) after the lock is released.
-plot_on_exit 'rmdir "$lock" 2>/dev/null || true'
-
-if [ -d "$wt" ] && git worktree list --porcelain | grep -qx "worktree $wt"; then
-  # A REUSED WORKTREE MAY BELONG TO SOMEONE ELSE, and on 2026-08-17 one did: the
-  # resolver ran `git merge` inside a worktree an agent was actively editing —
-  # zero unmerged paths, three modified files, work in progress. It refused
-  # before writing anything, but that was luck rather than design.
-  #
-  # Reuse is right when the worktree is IDLE; the name alone does not say so. A
-  # worktree with modifications is one whose owner is mid-thought, and merging
-  # into it would either fail on "local changes would be overwritten" or, worse,
-  # succeed and fold a stranger's uncommitted work into a merge commit this
-  # script then pushes.
-  #
-  # The honest minimum is to refuse, and the plan names it acceptable: creating a
-  # scratch worktree is impossible anyway while git holds this branch checked out
-  # here, since git refuses a second checkout of one branch.
-  #
-  # `--porcelain` rather than a parsed `git status`: it is the stable interface,
-  # and an untracked file is deliberately NOT counted — a stray log or an
-  # editor's scratch file is not work in progress, and `merge` does not touch it.
-  echo "step: reusing worktree $wt"
-  busy=$(git -C "$wt" status --porcelain --untracked-files=no 2>/dev/null)
-  if [ -n "$busy" ]; then
-    echo "step: worktree has modifications that are not this repair's — refusing"
-    printf 'step: modified: %s\n' "$(printf '%s' "$busy" | sed 's/^...//' | tr '\n' ' ')"
-    finish refused worktree-busy
-  fi
-else
-  plot_exclude_desk_root "$(plot_repo_root)"
-  if ! git worktree add -q "$wt" "$branch" 2>/dev/null; then
-    if ! git worktree add -q -b "$branch" "$wt" "origin/$branch" 2>/dev/null; then
-      echo "plot-resolve-artifact: cannot create a worktree for $branch at $wt" >&2
-      finish refused no-worktree
-    fi
-  fi
-  echo "step: worktree $wt"
-fi
-
-# THE FIXED SEQUENCE. Five steps, no decision between them.
-
-# 1. Merge. The conflict is EXPECTED — that is why we are here — so a non-zero
-#    exit is not yet a failure. What decides is which paths came back
-#    unmerged, checked next.
-git -C "$wt" merge --no-edit "origin/$MAIN" >/dev/null 2>&1
-merge_status=$?
-
-if [ "$merge_status" -eq 0 ]; then
-  # Nothing conflicted after all — the prediction was made from refs that have
-  # since moved, which is the direction this repo already knows they move in.
-  # The merge stands; there is nothing to repair and nothing to prove, so this
-  # pushes nothing rather than pushing a merge nobody asked for.
-  git -C "$wt" merge --abort >/dev/null 2>&1 || true
-  git -C "$wt" reset -q --hard "HEAD" >/dev/null 2>&1 || true
-  echo "step: no conflict on merge — nothing to repair"
-  finish refused no-conflict
-fi
-
-# 2. VERIFY THE SET, HERE, AGAINST THE REAL MERGE.
-#
-# The board classified from `merge-tree`, which predicts IN MEMORY from the refs
-# this machine holds. This is the merge itself, and it is the only place the set
-# is a fact rather than a forecast — a stale ref makes the prediction wrong in
-# the reassuring direction, so the entry condition is re-checked against reality
-# before anything is written.
-#
-# The set is read once and asked TWO questions, in order: was anything observed
-# at all, and — only then — was it exactly the artifact.
-unmerged=$(git -C "$wt" diff --name-only --diff-filter=U)
-n_unmerged=$(printf '%s\n' "$unmerged" | grep -c . || true)
-
-# AN EMPTY SET IS NOT A SMALL SET — it is the absence of a reading.
-#
-# The merge exited non-zero, so something went wrong; but a conflict is not the
-# only thing that ends a merge non-zero. A merge that never STARTED — refused
-# because the worktree was dirty, because a merge was already in progress, or
-# because the ref could not be resolved — exits non-zero too and leaves no
-# unmerged paths behind. Zero paths therefore answers a different question than
-# one or three do: those say WHICH files conflicted, zero says NOBODY LOOKED.
-#
-# Measured on 2026-08-17, and the defect this branch exists for: the resolver
-# reused a worktree in which no merge was running, read zero paths, compared
-# zero against one, and reported `not-artifact-only` — a name asserting
-# something about files it had never examined. The refusal was right; its reason
-# was wrong, and the wrong reason sent a reader looking for conflicts that did
-# not exist.
-#
-# So the two refusals are named apart. `not-artifact-only` is a claim about an
-# observed set and may only be said when there was one.
-if [ "$n_unmerged" = "0" ]; then
-  git -C "$wt" merge --abort >/dev/null 2>&1 || true
-  echo "step: the merge reported failure but left no unmerged paths — nothing was observed"
-  finish refused not-observed
-fi
-
-# EVERY unmerged path is a bundle: the conflict set is a SUBSET of the bundle
-# set, and nothing else is in it. NOT "a bundle is among the conflicts" — an
-# implementation asking that passes every bundle-only case and silently repairs
-# merges that need judgement as a whole. The claim stayed exact when the list
-# grew from one file to nine; only the thing each path is checked against
-# changed. A merge conflicting in a bundle AND anything else still needs a
-# person, even though one of its files does not.
-#
-# WALKED PER PATH rather than compared as a whole, because the conflict set is
-# an arbitrary subset of nine and there is no single string to compare it to.
-# The direction is what keeps it exact: every element of the observed set must
-# appear in the licensed set, so an unlicensed path can only ever refuse.
-outside=""
-while IFS= read -r conflict; do
-  [ -n "$conflict" ] || continue
-  if ! printf '%s\n' "$ARTIFACT_PATHS" | grep -qxF -- "$conflict"; then
-    outside="${outside}${outside:+ }$conflict"
-  fi
-done <<EOF
-$unmerged
-EOF
-
-if [ -n "$outside" ]; then
-  git -C "$wt" merge --abort >/dev/null 2>&1 || true
-  echo "step: conflict set is not bundles only — refusing"
-  printf 'step: unmerged: %s\n' "$(printf '%s' "$unmerged" | tr '\n' ' ')"
-  printf 'step: outside the bundle set: %s\n' "$outside"
-  finish refused not-artifact-only
-fi
-
-# 3. Take a side of EACH conflicted bundle. WHICH SIDE CANNOT MATTER — the
-#    rebuild overwrites it — and the diff is never read. `--theirs` because the
-#    command needs a word.
-#
-#    Only the paths that actually conflicted, never the whole set: a bundle git
-#    merged cleanly has no side to take, and `checkout --theirs` on an unmerged-
-#    stage-free path errors rather than doing nothing useful.
-while IFS= read -r conflict; do
-  [ -n "$conflict" ] || continue
-  git -C "$wt" checkout --theirs -- "$conflict" 2>/dev/null \
-    || git -C "$wt" checkout --ours -- "$conflict" 2>/dev/null \
-    || true
-  git -C "$wt" add -- "$conflict" 2>/dev/null || true
-  echo "step: took a side of $conflict (either — the rebuild decides)"
-done <<EOF
-$unmerged
-EOF
-
-# 4. Rebuild, in the branch's OWN worktree. This is what makes the kept side
-#    irrelevant, and it is the property CI's no-diff gate then re-checks.
-if ! (cd "$wt" && pnpm build:board >/dev/null 2>&1); then
-  git -C "$wt" merge --abort >/dev/null 2>&1 || true
-  echo "step: rebuild failed — pushing nothing"
-  finish abandoned build-failed
-fi
-# EVERY bundle is staged after the rebuild, not just the ones that conflicted.
-# `pnpm build:board` regenerates all nine, and a rebuild triggered by one
-# conflict can legitimately move another — the merge brought in source changes
-# for the whole package. Staging only the conflicted paths would leave those
-# modifications unstaged, and CI's no-diff gate would then fail the push for a
-# file this run had already rebuilt correctly.
-while IFS= read -r bundle; do
-  [ -n "$bundle" ] || continue
-  git -C "$wt" add -- "$bundle" 2>/dev/null || true
-done <<EOF
-$ARTIFACT_PATHS
-EOF
-printf 'step: rebuilt and staged %s bundle(s)\n' "$(printf '%s\n' "$ARTIFACT_PATHS" | grep -c .)"
-
-# The merge commit exists only once the rebuild has produced the artifact it
-# will carry. Committing before the build would leave a commit holding a stale
-# artifact if the build then failed — exactly what CI's no-diff gate catches,
-# arriving as a push instead of as a refusal.
-if ! git -C "$wt" commit -q --no-edit 2>/dev/null; then
-  echo "step: nothing to commit after the rebuild"
-  finish abandoned nothing-to-commit
-fi
-
-# 5. THE GATE. Green in this worktree BEFORE the push, never CI after it.
-#    A resolver that pushed and let CI decide passes every correctness check
-#    above and manufactures a red PR in the queue — the exact stuck state this
-#    plan exists to remove.
-echo "step: running pnpm run test:board"
-if ! (cd "$wt" && pnpm run test:board >/dev/null 2>&1); then
-  # NOTHING IS PUSHED, and the merge is undone so the branch is left exactly as
-  # it was found. A half-repaired branch would be a third state nobody named.
-  git -C "$wt" reset -q --hard "HEAD~1" 2>/dev/null || true
-  echo "step: test:board failed — pushing nothing, this is a conflict a human owns"
-  finish abandoned tests-failed
-fi
-echo "step: test:board passed"
-
-if ! git -C "$wt" push -q origin "HEAD:$branch" 2>/dev/null; then
-  echo "step: push rejected — the branch moved under us; leaving the repair local"
-  finish abandoned push-failed
-fi
-
-echo "step: pushed $branch"
-finish pushed artifact-conflict-resolved

package/plot-transcript-quiet.sh

@@ -1,170 +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-monitor.sh` and `plot-worker-loop.sh`.
-#
-# 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"
-}