@plot-pm/board 0.16.3 → 0.18.0

package/plot-host.sh

@@ -219,13 +219,11 @@
 #                                 empty: `jen job list` carries no history and
 #                                 no timestamps, and inventing them would be a
 #                                 collector reaching a verdict.
-#   run-for-sha <branch> <sha>    the run for ONE sha — else the branch's newest
-#                                 run, with `sha` saying which it is — as a
-#                                 single JSON object, or nothing when the branch
-#                                 has no runs at all. Dispatched on the `CI` key
-#                                 like `runs`, and EXITS 4 on jenkins: `jen job
-#                                 list` names no commit, so there is nothing to
-#                                 match a sha against. Output:
+#   run-for-sha <branch> <sha>    the run for ONE sha, and nothing for any
+#                                 other sha — as a single JSON object, or
+#                                 nothing when the branch has no run for this
+#                                 sha. Dispatched on the `CI` key like `runs`.
+#                                 Output:
 #                                   {"sha":"…","status":"queued|in_progress|
 #                                    completed|waiting|requested",
 #                                    "conclusion":"success|failure|…|null",
@@ -235,22 +233,12 @@
 #                                 and sha-blind, and `gh run list --branch X`
 #                                 returns runs for every sha that branch ever
 #                                 had — the newest run is NOT necessarily for
-#                                 the newest commit. A green answer read off the
-#                                 wrong run reports success for code nobody will
-#                                 merge, which is worse than no answer: 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.
-#                                 THE FALLBACK IS WHAT MAKES THAT VISIBLE. Were
-#                                 it to report nothing when the asked-for sha
-#                                 has no run, a run IN FLIGHT for a superseded
-#                                 commit would look exactly like no run at all,
-#                                 and a caller could not tell "CI has not
-#                                 started" from "CI is answering about the
-#                                 past". `sha` names the run's own commit, and
-#                                 comparing it to the one asked about is the
-#                                 CALLER's rule — this decides nothing.
+#                                 the newest commit. A run for any sha but the
+#                                 one asked about is not evidence about it, so
+#                                 reporting it would invite 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.
 #                                 `status` AND `conclusion` ARE BOTH REPORTED,
 #                                 never collapsed. A run that is `completed` has
 #                                 a conclusion; one that is `waiting` or
@@ -474,7 +462,6 @@ die3() { echo "plot-host: $*" >&2; exit 3; }
 # a person at a terminal want three different answers — and a retry inside the
 # adapter would hide the very state this code exists to surface, turning a
 # reportable fact into an unexplained four-minute call.
-die5() { echo "plot-host: $*" >&2; exit 5; }
 
 # Exit 6 — the host refused because too many calls arrived AT ONCE. A secondary
 # limit, and a different ceiling from the one exit 5 reports.
@@ -497,7 +484,6 @@ die5() { echo "plot-host: $*" >&2; exit 5; }
 #
 # NOT A RETRY, for the reason exit 5 states: whether to wait is the caller's
 # decision, and this adapter reports rather than reacts.
-die6() { echo "plot-host: $*" >&2; exit 6; }
 
 # WHICH FAILURE, read off the wording — the same shape `bb_issue_exit_code`
 # uses, and for the same reason: the exit code cannot split these cases. `gh`
@@ -514,7 +500,7 @@ die6() { echo "plot-host: $*" >&2; exit 6; }
 # `throttled` for every match of one regex until 2026-09-02, so *"API rate
 # limit exceeded"* and *"You have exceeded a secondary rate limit"* came back
 # the same word and nothing downstream could tell them apart. `secondary` is
-# now its own answer: `die6` carries it, and the board names which limit was
+# now its own answer: `pr_list_failed` exits 6 for it, and the board names which limit was
 # hit rather than printing one reset over both.
 #
 # THE SECONDARY TEST RUNS FIRST, AND THE ORDER IS THE CLASSIFICATION. GitHub's
@@ -651,7 +637,7 @@ pr_list_failed() { # $1=stderr text
 #
 # EVERY CALL SITE MUST WRITE `|| exit $?`, AND IT IS NOT OPTIONAL. This is
 # invoked as `_raw="$(pr_list_call …)"` — a COMMAND SUBSTITUTION, which is a
-# subshell — so the `exit` inside `die5`/`die3` leaves that subshell only. The
+# subshell — so the `exit` inside `pr_list_failed`/`die3` leaves that subshell only. The
 # outer script would carry on with `_raw` empty and `jq` would emit nothing:
 # the silent empty list this whole helper exists to remove, rebuilt one layer
 # further in and harder to see. The same trap `bb_states_for` documents a few
@@ -3619,7 +3605,8 @@ case "$op" in
         *) die "pr-merged: unknown arg $1" ;;
       esac
     done
-    if [ "$be" = "github" ]; then
+    # NO REMOTE, NO PR: no repository holds one, so nothing merged, whatever gh's auth says.
+    if [ ${#repo_args[@]} -eq 0 ] && [ -z "$(git remote 2>/dev/null)" ]; then echo "not-merged"; elif [ "$be" = "github" ]; then
       # --state all, because a merged PR reports CLOSED and the default `open`
       # would hide every one of them. --limit 100 rather than 1: the newest PR
       # is not the merge, exactly as the state is not the merge.
@@ -4349,7 +4336,7 @@ case "$op" in
     ;;
 
   run-for-sha)
-    # The newest run for ONE sha — the BuildMonitor's only host question.
+    # The run for ONE sha, or nothing — the BuildMonitor's only host question.
     #
     # WHY THIS IS NOT `runs`. `runs` is branch-scoped and reports no sha at all,
     # so a caller cannot tell which commit an answer is about. `gh run list
@@ -4376,9 +4363,9 @@ case "$op" in
     # deliberately NOT an error: a monitor polling a fresh push sees it on every
     # pass until CI wakes up.
     #
-    # Bitbucket reports nothing rather than something invented, exactly as
-    # `runs` does: `bb` has no run listing, and silence here reads as
-    # unavailable, never as "this sha has no build".
+    # A Bitbucket remote exits 4 (`bb` has no run listing), as does a failing
+    # `gh` or Jenkins that cannot be asked: exit 4 reads as unavailable, never
+    # as "this sha has no build".
     branch="${1:?run-for-sha needs a branch}"; shift
     sha="${1:?run-for-sha needs a sha}"; shift
     # Enough runs to find the sha among its neighbours. A branch accumulates
@@ -4467,10 +4454,9 @@ case "$op" in
           echo "plot-host: run-for-sha — Jenkins did not answer for '$_jen_host'" >&2
           exit 4
         fi
-        # THE SAME FALLBACK RULE AS THE GITHUB ARM, and it is inherited rather
-        # than invented: the asked-for sha if a build carries it, else the
-        # newest build, and `sha` says WHICH. A caller that could not tell the
-        # two apart would be back to the branch-scoped guessing this op ends.
+        # THE SAME MATCH RULE AS THE GITHUB ARM: only the asked-for sha, never
+        # another build's. A build for any other commit is not evidence about
+        # this one, so no match means no output.
         #
         # `result` is null while a build runs, which is Jenkins' own word for
         # *in flight* — mapped to the `status`/`conclusion` split the contract
@@ -4482,7 +4468,7 @@ case "$op" in
                 conclusion: (if .building then null else (.result // null) end),
                 url: (.url // ""),
                 startedAt: (if .timestamp then (.timestamp / 1000 | todate) else "" end) } ]
-          | ((map(select(.sha == $sha)) | .[0]) // .[0])
+          | (map(select(.sha == $sha)) | .[0])
           | select(. != null)' 2>/dev/null || true
         # THIS ARM ANSWERS AND THE OP IS OVER. Everything below the `esac` is
         # the GitHub path — the old jenkins arm reached it only because it
@@ -4512,30 +4498,36 @@ case "$op" in
     # newest-first, and a sha can carry several (a rerun, or several
     # workflows). The newest is the live answer; older ones for the same sha
     # are superseded by the same argument that superseded runs for older shas.
-    # THE SHA ASKED ABOUT IF THERE IS ONE, ELSE THE NEWEST RUN ON THE BRANCH —
-    # and `sha` in the output says WHICH, because a caller that could not tell
-    # the two apart would be back to the branch-scoped guessing this op exists
-    # to end.
     #
-    # WHY IT FALLS BACK AT ALL, rather than reporting nothing. Filtering to
-    # the asked-for sha and stopping makes the most important case invisible:
-    # a run IN FLIGHT for a commit the branch has already moved past reports
-    # identically to no run at all, so a caller cannot distinguish *CI has not
-    # started yet* from *CI is busy answering about the past*. The second is
-    # the state that had two merge waiters reporting on superseded runs on
-    # 2026-08-30, and it is exactly what a caller needs to see.
+    # ONLY THE ASKED-FOR SHA, NEVER ANOTHER ONE'S RUN. A run for any other
+    # commit is not evidence about this one — reporting it would read as a
+    # live answer for a commit the branch has already moved past, which is
+    # worse than no answer. No match means no output, read the same as a
+    # branch with no runs at all.
     #
-    # IT STILL DECIDES NOTHING (Principle 3). It reports the run it found and
-    # the sha that run is for; whether that sha being different from the one
-    # asked about means "superseded" is the caller's rule. This collects.
-    gh run list --branch "$branch" --limit "$limit" \
-      --json headSha,conclusion,status,startedAt,url 2>/dev/null \
-      | jq -c --arg sha "$sha" \
-          '(map(select(.headSha == $sha)) | .[0]) // .[0]
-           | select(. != null)
-           | {sha:.headSha, status:.status,
-              conclusion:(if (.conclusion // "") == "" then null else .conclusion end),
-              url:.url, startedAt:.startedAt}' 2>/dev/null || true
+    # A FAILING `gh` IS NOT AN EMPTY HISTORY. An expired token, a rate limit or
+    # a network failure exits 4 here, the way the Jenkins arm does, so the
+    # monitor reads *could not ask* and not *no run yet*.
+    _gh_runs=$(gh run list --branch "$branch" --limit "$limit" \
+      --json headSha,conclusion,status,startedAt,url,databaseId 2>/dev/null) \
+      || { echo "plot-host: run-for-sha — gh run list failed for '$branch'" >&2; exit 4; }
+    _gh_match=$(printf '%s' "$_gh_runs" | jq -c --arg sha "$sha" \
+      '(map(select(.headSha == $sha)) | .[0]) | select(. != null)
+       | {sha:.headSha, status:.status,
+          conclusion:(if (.conclusion // "") == "" then null else .conclusion end),
+          url:.url, startedAt:.startedAt, databaseId:.databaseId}') || exit 4
+    [ -n "$_gh_match" ] || exit 0
+    # ONE MORE CALL, ONLY FOR A CONCLUDED FAILURE (#1295): `gh run view --json
+    # jobs` is the only place a 0-step job (no runner ever picked up the run)
+    # shows up, apart from a real failure. A run still going or that
+    # succeeded costs no extra call.
+    _gh_db_id=$(printf '%s' "$_gh_match" | jq -r 'if (.conclusion == "failure" or .conclusion == "cancelled") then .databaseId else "" end')
+    _gh_match=$(printf '%s' "$_gh_match" | jq -c 'del(.databaseId)') || exit 4
+    [ -z "$_gh_db_id" ] && { printf '%s' "$_gh_match"; exit 0; }
+    # Slurped via stdin, never `--argjson`: that flag caps at 128 KB on Linux.
+    _gh_jobs=$(gh run view "$_gh_db_id" --json jobs 2>/dev/null) || { echo "plot-host: run-for-sha — gh run view failed" >&2; exit 4; }
+    jq -n -c --slurpfile match <(printf '%s' "$_gh_match") --slurpfile run <(printf '%s' "$_gh_jobs") \
+      '$match[0] + {jobs: [$run[0].jobs[] | {conclusion, steps: (.steps | length)}]}' || exit 4
     ;;
 
   issue-list)

package/plot-monitor-subject.sh

@@ -1,14 +1,13 @@
 #!/usr/bin/env bash
 # Plot helper: the ONE answer to "is this monitor's subject still there?"
 #
-# SOURCED, NOT RUN, by `plot-agent-monitor.sh` and `plot-build-monitor.sh`.
-# Both need the same computation and neither renders it the same way, which is
-# the same shape as `plot-worker-state.sh` and `plot-pr-merged.sh` — and the
-# same reason. `plot-worker-state.sh` carried five of its six states in
-# duplicate until 2026-08-18, and the copies had already drifted on the sixth.
-# Two monitors deciding independently when to stop would drift the same way, and
-# the failure would be silent: one monitor left running forever while its twin
-# exits is exactly the leak this file exists to close, half-fixed.
+# SOURCED, NOT RUN, by `plot-agent-monitor.sh`. The same shape as
+# `plot-worker-state.sh` and `plot-pr-merged.sh` — and the same reason.
+# `plot-worker-state.sh` carried five of its six states in duplicate until
+# 2026-08-18, and the copies had already drifted on the sixth. A monitor
+# deciding independently when to stop, with its computation copied rather than
+# shared, would drift the same way, and the failure would be silent: a monitor
+# left running forever is exactly the leak this file exists to close.
 #
 # ═══════════════════════════════════════════════════════════════════════════
 # WHY A MONITOR NEEDS THIS AT ALL

package/plot-worker-state.sh

@@ -499,6 +499,15 @@ plot_worker_blocked_file() { # $1=worktree → prints the marker's basename
 # exact population this state must not name. Excluding them is not widening the
 # rule; it is the `.tmp1` case again, for files Plot itself dropped there.
 #
+# NOR IS AN UNTRACKED ROOT `PLOT-CORRECTION.md`. `plot-worker-loop.sh`'s
+# `write_correction` writes it untracked into the desk for the agent to read,
+# and `reset_desk` removes it when the desk takes the next slice. A desk whose
+# only other content is that file holds no unlanded work, so the loop waits for
+# the checks rather than ending `holding-work`. The match is the whole
+# porcelain line `?? PLOT-CORRECTION.md`, the line `plot-desk-dirt.sh`'s
+# `desk_dirt` drops: a `docs/PLOT-CORRECTION.md`, or a staged, modified or
+# deleted copy, is content and counts.
+#
 # THE EXCLUSION STAYS NARROW OTHERWISE, by suffix and by Plot's own filenames.
 # An uncommitted source file is precisely the case this detection exists for, so
 # anything broader — "untracked files do not count", "only tracked changes
@@ -565,7 +574,7 @@ plot_worker_dirty_filter() { # $1=`git status --porcelain` output $2=worktree (o
   # `--porcelain` is the STABLE format; `git status` prose is localised and
   # reflows. Cut at column 4: the first three bytes are the XY status pair and a
   # space, and a filename can contain spaces of its own.
-  printf '%s' "$status" \
+  printf '%s' "$status" | grep -vxF '?? PLOT-CORRECTION.md' \
     | cut -c4- \
     | grep -vE "(^|/)$PLOT_WORKER_RECORD" \
     | grep -vE "$PLOT_EDITOR_LEFTOVER" \
@@ -829,29 +838,6 @@ plot_worker_limited_reset() { # $1=worktree → epoch seconds | ""
   printf '%s' "$reset"
 }
 
-# Has THIS worker's conversation written yet? → 0 spoken | 1 unspoken | 2 no handle
-#
-# THE DESK-WIDE NUMBER CANNOT SAY. After a hop to a new branch the loop mints a
-# fresh handle, and the new conversation has no transcript file until its first
-# line. Until then the desk's newest file is the PREVIOUS slice's, and its
-# silence is not this worker's. So the watcher asks the loop's own probe with
-# the loop's own handle: one probe, two readers, one answer.
-#
-# THREE ANSWERS, AND THE THIRD IS NOT THE SECOND. `0` the handle's file exists,
-# `1` it does not, `2` there is no handle to ask about. `plot_transcript_exists`
-# reads *no handle* as *no file*, which suits `session_flag`; here it would
-# make a hand-started watcher read every quiet worker as unspoken and disable
-# `idle` silently (#1074). So the handle is checked here, before the probe.
-plot_worker_conversation_spoken() { # $1=worktree → 0 spoken | 1 unspoken | 2 no handle
-  command -v session_handle >/dev/null 2>&1 || return 2
-  command -v plot_transcript_exists >/dev/null 2>&1 || return 2
-  local handle
-  handle=$(session_handle) || return 2
-  [ -n "$handle" ] || return 2
-  plot_transcript_exists "$1" "$handle" && return 0
-  return 1
-}
-
 # Are there commits on this branch yet? → 0 yes | 1 no | 2 unanswerable
 #
 # THE THIRD CONDITION ON `idle`, and the one that separates a stall from an
@@ -887,145 +873,6 @@ plot_worker_has_commits() { # $1=worktree → 0 yes | 1 no | 2 unanswerable
   return 1
 }
 
-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'
-}
-
-# Append one finding line to a desk's findings file, in the WorkerMonitor's own
-# shape — the board's reader keys on this exact field set and this exact
-# monitor name, and changing either would make an unbroken channel look broken.
-#
-# `since` AND `measuredAt` ARE DIFFERENT TIMES. `measuredAt` is when this
-# reading was taken; `since` is when the finding first held. A finding that has
-# held for twenty minutes and one taken twenty minutes ago are not the same
-# fact, and an operator triaging a board needs the first.
-plot_worker_publish_finding() { # $1=file $2=branch $3=worktree $4=finding $5=evidence $6=since
-  local file="$1" branch="$2" worktree="$3" finding="$4" evidence="$5" since="$6" now line
-  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-  line=$(printf '{"monitor":"%s","branch":"%s","worktree":"%s","finding":"%s","since":"%s","evidence":"%s","measuredAt":"%s"}' \
-    'WorkerMonitor' \
-    "$(json_escape "$branch")" \
-    "$(json_escape "$worktree")" \
-    "$(json_escape "$finding")" \
-    "${since:-$now}" \
-    "$(json_escape "$evidence")" \
-    "$now")
-  [ -n "$file" ] && printf '%s\n' "$line" >> "$file" 2>/dev/null
-  printf 'plot-watch %s\n' "$line"
-}
-
-# ONE PASS OF THE LOOP'S OWN WATCHER: take the six readings, ask
-# `plot_worker_idle_now`, publish only on a change.
-#
-# THE PID IS ALWAYS `alive`. The caller is the loop's watcher subshell, started
-# with the loop's own pid (`$_watch_loop_pid`); that pid is alive by
-# construction for as long as the watcher runs, so there is no `monitor_pid_alive`
-# reading here the way the old monitor needed one for a SEPARATE process it was
-# watching.
-#
-# `$5` IS THE RACE THE PLAN DID NOT ANTICIPATE. A prompt started into a
-# conversation whose transcript is already older than the window could read
-# `idle` on its FIRST pass and be ended before the model ever answers — the
-# clamp mirrors the usage-limit clamp's own shape: `silenceSeconds` is capped at
-# the seconds the prompt has actually been running, so a desk cannot be judged
-# quiet for longer than this prompt has existed.
-#
-# THE CHILD IS SAMPLED ON THE PID GIVEN, NEVER ON `$_watch_loop_pid` ITSELF.
-# `plot_worker_activity` sums the pid's whole descendant subtree; the loop's own
-# pid is the root the agent CLI hangs off, so the caller passes it explicitly
-# rather than this function assuming which pid names the subject.
-#
-# PUBLISH AND SIGNAL ARE SEPARATE. This function only ever publishes; it is the
-# caller's job to decide whether the PUBLISHED finding may end the worker — the
-# flag gates that decision, not this one.
-plot_worker_idle_watch_pass() { # $1=worktree $2=branch $3=findings-file $4=window $5=prompt_started_at $6=pid → exit 0 idle | 1 silent (also publishes)
-  local wt="$1" branch="$2" file="$3" window="$4" started_at="$5" pid="$6"
-  local silence spoken_rc spoken tree commits_rc commits activity finding evidence verdict
-
-  silence=$(plot_transcript_quiet_seconds "$wt" 2>/dev/null)
-  case "$silence" in
-    ''|unavailable|*[!0-9]*) silence='' ;;
-  esac
-
-  # THE USAGE-LIMIT CLAMP, AHEAD OF THE WINDOW CHECK. Silence is measured from
-  # the later of the newest transcript line and the reset this desk waits for;
-  # while the reset is ahead of now the difference is negative, which clamps to
-  # 0 and reads as busy — the agent is doing exactly what it should.
-  local limited_until
-  limited_until=$(plot_worker_limited_reset "$wt")
-  if [ -n "$limited_until" ] && [ -n "$silence" ]; then
-    local since_reset
-    since_reset=$(( $(date +%s) - limited_until ))
-    [ "$since_reset" -lt 0 ] && since_reset=0
-    [ "$since_reset" -lt "$silence" ] && silence=$since_reset
-  fi
-
-  # THE RACE CLAMP. A prompt's transcript may be older than the window on the
-  # very first pass, because it is the PREVIOUS slice's silence, not this
-  # prompt's. Silence can never exceed how long this prompt has actually run.
-  case "$started_at" in
-    ''|*[!0-9]*) ;;
-    *)
-      local ran
-      ran=$(( $(date +%s) - started_at ))
-      [ "$ran" -lt 0 ] && ran=0
-      if [ -n "$silence" ] && [ "$ran" -lt "$silence" ]; then silence=$ran; fi
-      ;;
-  esac
-
-  plot_worker_conversation_spoken "$wt"; spoken_rc=$?
-  case "$spoken_rc" in
-    0) spoken=1 ;;
-    *) spoken=0 ;;
-  esac
-
-  activity=$(plot_worker_activity "$pid" 2>/dev/null)
-
-  tree=$(plot_worker_tree_quiet_seconds "$wt" 2>/dev/null)
-
-  plot_worker_has_commits "$wt"; commits_rc=$?
-  case "$commits_rc" in
-    0) commits='yes' ;;
-    1) commits='no' ;;
-    *) commits='unanswerable' ;;
-  esac
-
-  verdict=$(plot_worker_idle_now 'alive' "$spoken" "${silence:-unavailable}" "$activity" "$tree" "$commits" "$window")
-
-  finding=''
-  evidence=''
-  if [ "$verdict" = 'idle' ]; then
-    finding='idle'
-    evidence="the agent's transcript has been silent for over ${window}s with no child process burning CPU behind it, nothing in its tree has moved for ${tree}s, and the branch already carries commits"
-  fi
-
-  # PUBLISH ONLY ON A CHANGE, held in a variable of the CALLER's subshell —
-  # named `PLOT_WATCH_PUBLISHED`/`PLOT_WATCH_SINCE` rather than local, because
-  # this function is called repeatedly from the watcher's own `while` loop and
-  # the state must survive between calls the way `monitor_pass`'s did.
-  if [ "$finding" != "${PLOT_WATCH_PUBLISHED:-}" ]; then
-    local now_iso
-    now_iso=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-    if [ -n "$finding" ]; then
-      PLOT_WATCH_SINCE="$now_iso"
-      plot_worker_publish_finding "$file" "$branch" "$wt" "$finding" "$evidence" "$PLOT_WATCH_SINCE"
-    elif [ -n "${PLOT_WATCH_PUBLISHED:-}" ]; then
-      PLOT_WATCH_SINCE="$now_iso"
-      plot_worker_publish_finding "$file" "$branch" "$wt" 'clear' \
-        "the ${PLOT_WATCH_PUBLISHED} finding no longer holds; the worker is measuring healthy again" "$PLOT_WATCH_SINCE"
-    fi
-    PLOT_WATCH_PUBLISHED="$finding"
-  fi
-
-  # THE VERDICT IS THE EXIT CODE, NOT STDOUT. Stdout is reserved for the
-  # publish line alone (`plot_worker_publish_finding`'s own `plot-watch …`
-  # line), the same convention the old monitor's process stdout carried into
-  # `.plot-worker.log` beside the agent's own output. A caller that needs the
-  # word reads the exit code: 0 for `idle`, 1 for anything else.
-  [ "$finding" = 'idle' ]
-}
-
 # The total CPU time, in centiseconds, of a pid and every process descended from
 # it. Prints the number; prints `0` and returns non-zero when the pid names no
 # live process at all.