@plot-pm/board 0.14.4 → 0.16.0

package/plot-tmp.sh

@@ -0,0 +1,108 @@
+# plot-tmp.sh — every temp path a Plot script creates, and the process's only
+# EXIT/INT/TERM traps. SOURCED, not run.
+#
+#   . "$SCRIPT_DIR/plot-tmp.sh"
+#   plot_tmpdir  work  fleet-ref     # $work  = $TMPDIR/plot-fleet-ref.XXXXXX (a directory)
+#   plot_tmpfile err   host-err      # $err   = $TMPDIR/plot-host-err.XXXXXX  (a file)
+#   plot_on_exit budget_memo_clear   # a command the exit handler runs
+#
+# THE TEMPLATE IS THE REASON THIS FILE EXISTS. On macOS, `mktemp` with no
+# template and `mktemp -t` both write to `_CS_DARWIN_USER_TEMP_DIR` and ignore
+# `TMPDIR` (`man mktemp`). Only an explicit `"${TMPDIR:-/tmp}/plot-<prefix>.XXXXXX"`
+# lands under `TMPDIR`, and BSD `mktemp` requires the X's to trail. Every path
+# carries the `plot-` prefix, which is the name `plot-reap.sh --sweep-temp`
+# removes after a SIGKILL skipped the traps.
+#
+# ASSIGNMENT BY NAME, NEVER `d=$(plot_tmpdir x)`. The functions assign through
+# `printf -v` and print nothing. `scripts/check-temp-paths.sh` refuses the
+# substitution form.
+#
+# THE REGISTRY IS A FILE KEYED BY `$$`, NOT A SHELL ARRAY. `$$` is the owning
+# script's pid in every subshell, so a registration made inside `$(…)` or
+# `( … ) &` reaches the owner's trap; an array would be a subshell's copy and
+# the path would leak. Measured 2026-09-30: `plot-host.sh` creates two spool
+# files inside a command substitution.
+#
+# THE TRAPS ARE INSTALLED HERE, ONCE, AT SOURCE TIME. A trap installed on the
+# first call would be installed inside that call's substitution and remove the
+# path when the substitution closed. `PLOT_TMP_LOADED` makes a second source in
+# the same process a no-op, because a re-run setup would truncate the live
+# registry. INT and TERM run the cleanup, clear their own trap and re-raise, so
+# the script stops with 130 or 143 rather than running on to exit 0.
+#
+# A script that sources this must not install its own EXIT, INT or TERM trap:
+# the last `trap` wins, and that replacement is the defect this file fixes
+# (`plot-fleet-scan.sh` left one ~955-file cache per run). Use `plot_on_exit`.
+
+if [ "${PLOT_TMP_LOADED:-}" = "$$" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+PLOT_TMP_LOADED=$$
+
+# Fixed at first source: a later `TMPDIR` change in the script does not move it.
+# A file already at this path belongs to a dead process that had the same pid,
+# and its `c:` commands are not this process's, so it is replaced, never read.
+PLOT_TMP_REGISTRY="${TMPDIR:-/tmp}/plot-reg.$$"
+rm -f -- "$PLOT_TMP_REGISTRY" 2>/dev/null
+: > "$PLOT_TMP_REGISTRY" 2>/dev/null || true
+
+# One line per entry, in registration order: `p:<path>` or `c:<command>`.
+_plot_tmp_register() {
+  printf '%s:%s\n' "$1" "$2" >> "$PLOT_TMP_REGISTRY" 2>/dev/null || true
+}
+
+# plot_tmpdir VAR prefix — create a directory, register it, assign it to VAR.
+plot_tmpdir() {
+  local __plot_tmp_new
+  __plot_tmp_new=$(mktemp -d "${TMPDIR:-/tmp}/plot-$2.XXXXXX") || return 1
+  _plot_tmp_register p "$__plot_tmp_new"
+  printf -v "$1" '%s' "$__plot_tmp_new"
+}
+
+# plot_tmpfile VAR prefix — create a file, register it, assign it to VAR.
+plot_tmpfile() {
+  local __plot_tmp_new
+  __plot_tmp_new=$(mktemp "${TMPDIR:-/tmp}/plot-$2.XXXXXX") || return 1
+  _plot_tmp_register p "$__plot_tmp_new"
+  printf -v "$1" '%s' "$__plot_tmp_new"
+}
+
+# plot_on_exit command — run `command` (one line) when the process ends.
+plot_on_exit() {
+  _plot_tmp_register c "$*"
+}
+
+# Runs every registered command and removes every registered path, in
+# registration order, then removes the registry. Runs once: the registry is
+# gone afterwards, so a second call finds nothing.
+_plot_tmp_cleanup() {
+  local __plot_tmp_line
+  [ -f "$PLOT_TMP_REGISTRY" ] || return 0
+  while IFS= read -r __plot_tmp_line; do
+    case $__plot_tmp_line in
+      c:*) eval "${__plot_tmp_line#c:}" ;;
+      p:*) rm -rf -- "${__plot_tmp_line#p:}" 2>/dev/null ;;
+    esac
+  done < "$PLOT_TMP_REGISTRY"
+  rm -f -- "$PLOT_TMP_REGISTRY" 2>/dev/null
+  return 0
+}
+
+_plot_tmp_on_exit() {
+  local __plot_tmp_rc=$?
+  _plot_tmp_cleanup
+  exit "$__plot_tmp_rc"
+}
+
+# $1 is the signal name, $2 its number. `kill` re-raises it with the default
+# disposition; the `exit` is reached only if the shell defers the delivery.
+_plot_tmp_on_signal() {
+  trap - EXIT "$1"
+  _plot_tmp_cleanup
+  kill -"$1" "$$"
+  exit $((128 + $2))
+}
+
+trap _plot_tmp_on_exit EXIT
+trap '_plot_tmp_on_signal INT 2' INT
+trap '_plot_tmp_on_signal TERM 15' TERM

package/plot-transcript-quiet.sh

@@ -1,6 +1,6 @@
 #!/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`.
+# 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
@@ -40,6 +40,14 @@
 # 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 `/`
@@ -121,6 +129,26 @@ plot_transcript_quiet_seconds() { # $1=worktree → seconds | unavailable
   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.

package/plot-worker-monitor.sh

@@ -185,6 +185,11 @@ the environment, exactly as the wrapper's other children do:
   PLOT_MONITOR_FILE  where findings are published (default:
                      $PLOT_WORKTREE/.plot-worker.monitor.worker.jsonl)
   PLOT_MONITOR_INTERVAL  seconds between passes (default 30)
+  PLOT_SESSION_ID    the launch session id; the handle when the manifest
+                     carries no `resumeId`
+  PLOT_MANIFEST_FILE the agent's manifest, whose `resumeId` names the current
+                     conversation. With neither set, `idle` is judged on the
+                     desk alone and one line on stderr says so.
 
   --once   take one sample and exit, rather than looping. A single pass can
            never publish `idle` — that needs two — so this is how a test drives
@@ -255,6 +260,15 @@ plot_transcript_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/plot-transcri
 # shellcheck source=plot-transcript-quiet.sh
 if [ -r "$plot_transcript_lib" ]; then . "$plot_transcript_lib"; fi
 
+# THE CONVERSATION HANDLE — `session_handle`, the one the loop hands the prompt.
+# The manifest's `resumeId`, else `PLOT_SESSION_ID`, both read from the
+# environment the wrapper passes down. Never `plot_manifest_for_worktree`: it
+# resolves `--show-toplevel` to the desk and ignores `Agent registry`, so it
+# names a directory that does not exist (#1086).
+plot_manifest_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/plot-agent-manifest.sh"
+# shellcheck source=plot-agent-manifest.sh
+if [ -r "$plot_manifest_lib" ]; then . "$plot_manifest_lib"; fi
+
 # HOW LONG A TRANSCRIPT MUST BE QUIET BEFORE THE QUESTION IS EVEN ASKED.
 #
 # 900 s, and the number comes from wave 1's measurement rather than from taste.
@@ -318,7 +332,7 @@ publish() { # $1=finding $2=evidence $3=since
 }
 
 # ---------------------------------------------------------------------------
-# THE PORTS — four named seams, so every branch is reachable from a test
+# THE PORTS — seven named seams, so every branch is reachable from a test
 # ---------------------------------------------------------------------------
 #
 # Each of these is one question against the machine, and each is a `monitor_*`
@@ -374,6 +388,29 @@ monitor_transcript_quiet() { # → seconds | unavailable
   plot_transcript_quiet_seconds "$worktree"
 }
 
+# Has THIS worker's conversation written yet?
+#
+# 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 monitor 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 monitor read every quiet worker as unspoken and disable
+# `idle` silently. So the handle is checked here, before the probe.
+monitor_conversation_spoken() { # → 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 "$worktree" "$handle" && return 0
+  return 1
+}
+
 # A cheap stand-in for "the tree as it is right now", compared between passes.
 #
 # IT GOES THROUGH `plot_worker_dirty_filter`, which is not an optimisation — it
@@ -462,7 +499,7 @@ since=''
 # every other question meaningless — you cannot measure the CPU of a subtree
 # that is not there, and `plot_worker_activity` would answer "" for it anyway,
 # which is indistinguishable from a live pid with no children.
-sample_verdict() { # → gone | quiet | busy | unknown
+sample_verdict() { # → gone | quiet | busy | unknown | unspoken
   local alive
   monitor_pid_alive; alive=$?
   [ "$alive" = 1 ] && { printf 'gone'; return; }
@@ -500,6 +537,18 @@ sample_verdict() { # → gone | quiet | busy | unknown
   # needs asking: no CPU sample can overturn a line written seconds ago.
   if [ "$quiet" -lt "$PLOT_MONITOR_QUIET_SECONDS" ]; then printf 'busy'; return; fi
 
+  # PAST THE WINDOW, AND ONLY HERE, ASK WHETHER THIS CONVERSATION HAS WRITTEN.
+  # The number is the desk's; a new conversation with no file yet has produced
+  # none of its silence. `unspoken` is a reading that was made, and it is not
+  # `unknown`, which is no reading. Only `1` answers it: with no handle (`2`)
+  # the verdict is judged on the desk alone, as before this port existed.
+  #
+  # LAZY ON PURPOSE. `session_handle` starts one `node` (about 35 ms), so a
+  # worker inside the window never pays it.
+  local spoken
+  monitor_conversation_spoken; spoken=$?
+  [ "$spoken" = 1 ] && { printf 'unspoken'; return; }
+
   # PAST THE WINDOW, THE SECOND READING DECIDES — and it answers a question the
   # transcript cannot. A transcript is equally quiet whether the agent is
   # waiting on a model or waiting on its own 20-minute test suite. 28 of the 37
@@ -556,9 +605,13 @@ monitor_pass() {
         # failure to observe is not evidence of something to see.
       fi
       ;;
-    # `busy` and `unknown` are not findings. Nothing is published, which is the
-    # design: silence means healthy, and the AgentMonitor's slower loop is what
-    # catches a worker that finished without saying so.
+    # `busy`, `unknown` and `unspoken` are not findings. Nothing is published,
+    # which is the design: silence means healthy, and the AgentMonitor's slower
+    # loop is what catches a worker that finished without saying so. `unspoken`
+    # is recorded as `prev_verdict`, so `idle` needs two `quiet` passes after
+    # the conversation's first line. No grace period bounds it: a prompt that
+    # stays alive and never writes a line ends at `Worker bound`, the cost
+    # `unknown` already carries.
   esac
 
   prev_verdict="$verdict"
@@ -589,6 +642,14 @@ monitor_pass() {
 # line defines, and nothing below it runs when the guard is set.
 [ -n "${PLOT_MONITOR_NO_MAIN:-}" ] && return 0 2>/dev/null
 
+# ONE LINE AT START WHEN THERE IS NO HANDLE. Every wrapper-started monitor has
+# one, because `plot-dispatch.sh` sets `PLOT_SESSION_ID` on every launch; only a
+# monitor started by hand has none. It then behaves as it did before the
+# conversation probe, and says so rather than degrading silently.
+if [ -z "${PLOT_SESSION_ID:-}" ] && [ -z "${PLOT_MANIFEST_FILE:-}" ]; then
+  echo 'plot-worker-monitor: no session handle (PLOT_SESSION_ID and PLOT_MANIFEST_FILE unset) — idle is judged on the desk alone' >&2
+fi
+
 monitor_pass
 [ "$once" = 1 ] && exit 0