@plot-pm/board 0.15.0 → 0.16.1

package/plot-plan-meta.sh

@@ -200,6 +200,14 @@
 #                  every wave name is a label; ALWAYS present, so a consumer
 #                  never reads undefined. The plan still parses in full: waves[]
 #                  is unchanged and no name is shortened or dropped.
+#   unread_branch_headings
+#                  slice headings that carry `Branch:` and whose wave holds no
+#                  branch, verbatim, in document order — a report, not a
+#                  refusal. The wave stays in waves[] with branches []; this
+#                  separates a slice the parser could not read from a narrative
+#                  heading, which carries no `Branch:`. Covers both slice
+#                  consumers, so a heading lost to the first-heading latch
+#                  (#1042) is named too. ALWAYS present; [] when none.
 #   issues         tracker issue numbers this plan answers, from the `## Status`
 #                  `Issue:` line or front matter `issue:` (sorted, unique).
 #                  A DEDICATED field, never a scan of the body for `#NNN`: a
@@ -286,7 +294,7 @@ if [ ${#files[@]} -eq 0 ] && [ ${#missing[@]} -eq 0 ]; then
 fi
 
 for f in ${missing[@]+"${missing[@]}"}; do
-  printf '{"file":"%s","format":"none","error":"file not found","phase_raw":"","phase":"NONE","phase_alt_raw":"","phase_alt":"NONE","type":"","title":"","sprint":"","story":"","assignee":"","branches":[],"prs":[],"issues":[],"malformed_prs":[],"changelog":[],"long_wave_names":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
+  printf '{"file":"%s","format":"none","error":"file not found","phase_raw":"","phase":"NONE","phase_alt_raw":"","phase_alt":"NONE","type":"","title":"","sprint":"","story":"","assignee":"","branches":[],"prs":[],"issues":[],"malformed_prs":[],"changelog":[],"long_wave_names":[],"unread_branch_headings":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
     "$(printf '%s' "$f" | sed 's/\\/\\\\/g; s/"/\\"/g')"
 done
 
@@ -433,6 +441,7 @@ function reset_state() {
   delete issues; n_issues = 0
   delete wave_names; delete wave_of; delete wave_seq; delete wave_count
   delete deferred_of; delete deferred_why; delete claimed_of; delete ordered_b; n_waves = 0
+  delete branch_heading
   delete waits_of; delete waits_set
   delete builds_of; delete builds_set
   delete agent_of; delete agent_set
@@ -649,6 +658,20 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
     }
   }
   out = out "]"
+  # unread_branch_headings[]: a slice heading that carries `Branch:` and whose
+  # wave holds no branch, heading text verbatim, in document order. The wave
+  # itself stays in waves[] with branches []; this names WHY it is empty, since
+  # an empty wave with no `Branch:` is narrative and one with it is a slice the
+  # parser could not read. ALWAYS present, [] when every such heading was read.
+  out = out ",\"unread_branch_headings\":["
+  ubh = 0
+  for (w = 1; w <= n_waves; w++) {
+    if ((w in branch_heading) && wave_count[w] == 0) {
+      out = out (ubh > 0 ? "," : "") "\"" jesc(branch_heading[w]) "\""
+      ubh++
+    }
+  }
+  out = out "]"
   out = out ",\"review_raw\":\"" jesc(review) "\",\"review\":\"" norm_review(review) "\""
   out = out ",\"impl_raw\":\"" jesc(impl) "\",\"impl\":\"" norm_impl(impl) "\""
   out = out ",\"design_raw\":\"" jesc(design) "\""
@@ -670,6 +693,16 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
   out = out "}"
   print out
 }
+# Records the current `### ` heading when it carries `Branch:`. Called by BOTH
+# slice consumers, because the list consumer also opens a wave per heading: a
+# section whose FIRST heading is narrative routes every later heading there, and
+# a `(Branch: …)` heading below it then yields nothing (#1042).
+function note_branch_heading(   h) {
+  if (index($0, "Branch:") == 0) return
+  h = trim(substr($0, 4))
+  sub(/[ \t]*<!--.*$/, "", h)
+  branch_heading[n_waves] = h
+}
 # The longest wave name that still reads as a label, not prose. A JUDGEMENT, not
 # a measurement: the longest legitimate name in the estate is `Offered first`
 # (13), and the offender this exists to catch is a 53-character sentence, so the
@@ -911,20 +944,26 @@ section == "changelog" {
   cl_open = 0
   next
 }
-# WHICH SHAPE THIS SECTION HOLDS, decided once from its first `### ` heading and
-# then fixed for the rest of the section.
+# WHICH SHAPE THIS SECTION HOLDS, decided by ANY heading in it that names a
+# branch — not by the first heading alone.
 #
 # `(Branch:` IS THE MARKER, and it is the only reliable one. A heading carrying
 # it is the new shape by construction — that parenthetical is where the new
-# layout puts the branch. A heading without it is the old shape, whose headings
+# layout puts the branch. Headings without it are the old shape, whose headings
 # are bare names (`### Tracer`) and whose branches ride list items below.
 #
-# A SECTION WITH NO `### ` AT ALL is the old shape, and must be: a plan written
-# before subheadings existed is one unnamed wave of list items, which is exactly
-# what the old consumer produces. `slice_shape` therefore stays `""` until a
-# heading is seen, and `""` routes to the old consumer.
+# THE FIRST HEADING IS NOT THE DECIDER, and a latch on it loses work. Measured
+# 2026-09-28 over 357 plans: 56 sections open with a narrative heading, and in 2
+# of them a branched heading sits below it, so the section routed to the list
+# consumer and 5 declared slices were read as none. `slice_shape` therefore
+# stays `""` until a BRANCHED heading appears, wherever it sits.
+#
+# A SECTION WITH NO BRANCHED `### ` AT ALL is the old shape, and must be: a plan
+# written before subheadings existed is one unnamed wave of list items, which is
+# exactly what the old consumer produces — 54 of those 56 plans. `""` routes
+# there, so the absent latch and the old answer are one behaviour.
 section == "slices" && $0 ~ /^###[ \t]/ && slice_shape == "" {
-  slice_shape = (index($0, "(Branch:") > 0) ? "heading" : "list"
+  if (index($0, "(Branch:") > 0) slice_shape = "heading"
 }
 
 section == "slices" && slice_shape != "heading" {
@@ -932,6 +971,7 @@ section == "slices" && slice_shape != "heading" {
   # unnamed wave, so a pre-wave plan parses as exactly one wave.
   if ($0 ~ /^###[ \t]/) {
     wave_names[++n_waves] = trim(substr($0, 4))
+    note_branch_heading()
     next
   }
   # Claim reflection, written by the worker after its ref push succeeds. This is
@@ -1187,6 +1227,7 @@ section == "slices" && slice_shape == "heading" {
   sub(/[ \t]*\(Branch:.*$/, "", wname)
   wname = trim(wname)
   wave_names[++n_waves] = wname
+  note_branch_heading()
 
   # Claim/deferral annotations bind to the line carrying the branch name, which
   # is the heading. Read before any match() below, which clobbers RSTART/RLENGTH.
@@ -1291,10 +1332,17 @@ section == "slices" && slice_shape == "heading" {
   # heading with no readable branch still opened a wave above — so a `## Waves`
   # section is never silently empty, which is the failure this plan refuses: a
   # consumer sees a wave it could not extract a branch from, not an absence.
+  #
+  # THE VALUE MAY BE BACKTICKED. `(Branch: \`bug/foo\`)` is unambiguous, and a
+  # backtick between `Branch:` and the prefix made the anchored match fail, so
+  # the heading opened a wave and yielded nothing. The backticks are optional on
+  # both sides and stripped from the name. Measured 2026-09-28 over 357 plans:
+  # 2 records change, 355 byte-identical.
   hmeta = $0
-  if (match(hmeta, "Branch:[ \t]*(" PREFIXES ")/[^ \t,)]+")) {
+  if (match(hmeta, "Branch:[ \t]*`?(" PREFIXES ")/[^ \t,)`]+`?")) {
     b = substr(hmeta, RSTART, RLENGTH)
     sub(/^Branch:[ \t]*/, "", b)
+    gsub(/`/, "", b)
     branches[++n_branches] = b
     wave_of[n_branches] = n_waves
     wave_seq[n_branches] = ++wave_count[n_waves]

package/plot-reap.sh

@@ -146,12 +146,36 @@
 # words and lives INSIDE the tree, so it goes when the tree does and is not
 # swept here. This is the dispatcher's record of what it started. Two files,
 # two lifetimes, and CLAUDE.md already distinguishes them.
+#
+# `--sweep-temp` IS A SEPARATE MODE, and it runs INSTEAD of the four kinds. A
+# trap does not run on SIGKILL — the board ends a scan at its timeout,
+# `bounded.sh` escalates to SIGKILL, a person kills a hung script — so some temp
+# paths outlive every trap. It removes two populations, each owned by this user
+# and older than `Temp sweep after` hours (default 24), by the entry's own
+# modification time:
+#
+#   - `$TMPDIR/plot-?*` entries directly under `$TMPDIR` — `plot-` and at least
+#     one more character, any separator: `mkdtempSync` appends six characters
+#     with no dot, so `plot-host-pTFuyG` is the common shape. Never `plot`,
+#     `plotter-old` or any `tmp.*`: that is every template-less `mktemp` on the
+#     machine, and neither owner nor age separates Plot's from another
+#     program's. A `plot-reg.<pid>` exit registry is kept while its pid lives,
+#     because a worker loop registers its exit command and runs for days.
+#   - `$PLOT_BUDGET_HOME/memo/<pid>` directories (default `~/.plot/state/memo`)
+#     whose pid is not alive.
+#
+# It lists each candidate with `find` and removes it by the full path it
+# listed; it never passes a glob to `rm`, and it never reads `/tmp` or
+# `/var/folders` when `$TMPDIR` points elsewhere. The age bound is safe because
+# every Plot temp path belongs to one script call, one scan or one board
+# request, and 24 h is about 1,000 times the scan's 90 s timeout.
 set -u
 
-DRY=1; MAX=0
+DRY=1; MAX=0; SWEEP_TEMP=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --yes) DRY=0 ;;
+    --sweep-temp) SWEEP_TEMP=1 ;;
     --dry-run) DRY=1 ;;
     --max) MAX="${2:-0}"; shift ;;
     # The header, however long it has become. A hardcoded last line silently
@@ -163,6 +187,65 @@ while [ $# -gt 0 ]; do
   shift
 done
 
+# Is a pid alive? `ps -p` answers for another user's process too, where
+# `kill -0` reports EPERM, so a reused pid always keeps its entry.
+pid_alive() { ps -p "$1" >/dev/null 2>&1; }
+
+# One entry: report it, and remove it by the exact path unless this is a dry run.
+sweep_one() { # $1=path $2=why
+  temp_swept=$((temp_swept + 1))
+  if [ "$DRY" = 1 ]; then
+    echo "temp: would remove $1 ($2)"
+  elif rm -rf -- "$1" 2>/dev/null; then
+    echo "temp: removed $1 ($2)"
+    temp_removed=$((temp_removed + 1))
+  else
+    echo "temp: could not remove $1 ($2)"
+  fi
+}
+
+sweep_temp() {
+  local hours root me memo entry name
+  hours=$("$(dirname "${BASH_SOURCE[0]}")/plot-config.sh" get "Temp sweep after" 24 2>/dev/null) || hours=24
+  case "$hours" in
+    ''|*[!0-9]*) echo "plot-reap: 'Temp sweep after' must be a whole number of hours, not '$hours'" >&2; return 2 ;;
+  esac
+  root="${TMPDIR:-/tmp}"; root="${root%/}"
+  me=$(id -un)
+  temp_swept=0; temp_removed=0; temp_live=0
+  while IFS= read -r entry; do
+    [ -n "$entry" ] || continue
+    [ "$MAX" -gt 0 ] && [ "$temp_swept" -ge "$MAX" ] && break
+    name=${entry##*/}
+    case "$name" in
+      plot-reg.*)
+        if pid_alive "${name#plot-reg.}"; then temp_live=$((temp_live + 1)); continue; fi ;;
+    esac
+    sweep_one "$entry" "older than ${hours}h"
+  done <<LIST
+$(find "$root" -mindepth 1 -maxdepth 1 -user "$me" -name 'plot-?*' -mmin +$((hours * 60)) -print 2>/dev/null)
+LIST
+  memo="${PLOT_BUDGET_HOME:-${HOME:-}/.plot/state}/memo"
+  if [ -d "$memo" ]; then
+    while IFS= read -r entry; do
+      [ -n "$entry" ] || continue
+      [ "$MAX" -gt 0 ] && [ "$temp_swept" -ge "$MAX" ] && break
+      name=${entry##*/}
+      case "$name" in ''|*[!0-9]*) continue ;; esac
+      if pid_alive "$name"; then temp_live=$((temp_live + 1)); continue; fi
+      sweep_one "$entry" "memo of dead pid $name, older than ${hours}h"
+    done <<LIST
+$(find "$memo" -mindepth 1 -maxdepth 1 -type d -user "$me" -mmin +$((hours * 60)) -print 2>/dev/null)
+LIST
+  fi
+  echo "temp-summary: swept=$temp_swept removed=$temp_removed kept_live=$temp_live bound_hours=$hours root=$root dry_run=$DRY"
+}
+
+if [ "$SWEEP_TEMP" = 1 ]; then
+  sweep_temp
+  exit $?
+fi
+
 command -v git >/dev/null 2>&1 || { echo "plot-reap: git not found" >&2; exit 2; }
 ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
   echo "plot-reap: not a git repository" >&2; exit 2; }
@@ -255,7 +338,7 @@ desk_unpushed() { # $1=worktree $2=branch $3=merge reading → short shas
       # NO MERGED HEAD THIS DESK CONTAINS, and the host still said merged. The
       # subtraction above cannot run, and without it `--not --remotes` reports
       # EVERY commit the branch ever had — so the desk would be held forever
-      # for having done the work that merged.
+      # for having done the work that merged (#1033).
       #
       # Two ways to reach here, both normal. A SQUASH merge rewrites the
       # commits, so the head the host names exists nowhere in this history —
@@ -264,14 +347,27 @@ desk_unpushed() { # $1=worktree $2=branch $3=merge reading → short shas
       # trees against the host's 28. And a host answer that carries no head at
       # all leaves nothing to subtract.
       #
-      # The host's answer decides: it said this branch's work landed, and no
-      # reading taken from refs may overrule it. Answer empty.
+      # THE READING IS PATCH-ID: `git cherry` marks a commit `-` when its
+      # change is already upstream and `+` when it is not. A `+` commit that no
+      # remote holds is work the merge did not take — a commit made after the
+      # merge — and it holds the desk. No clock is consulted: a committer date
+      # holds a rebased merged desk forever, and an author date reaps an old
+      # patch committed today (#1038). The rule stays in shell because the
+      # logic is the prefix test and nothing else; a second conditional here is
+      # the signal to move it into the domain with a corpus entry.
       #
-      # THE GUARD KEEPS ITS WHOLE POPULATION. It protects a desk whose agent
-      # finished and whose work has NOT merged, which is where work is lost.
-      # The merged desk that holds a commit the PR did not carry is still held,
-      # by the subtraction above, whenever the merged head is one this desk has.
+      # It fails toward keeping: an unreadable base or a failing `git cherry`
+      # returns 1, which the rule reads as `unknown` and refuses on.
+      local full cherry
+      full=$(git -C "$wt" rev-list HEAD --not --remotes 2>/dev/null) || return 1
+      cherry=$(git -C "$wt" cherry "origin/$DEFAULT" HEAD 2>/dev/null) || return 1
       list=""
+      for h in $(printf '%s\n' "$cherry" | sed -n 's/^+ //p'); do
+        case $'\n'"$full"$'\n' in
+          *$'\n'"$h"$'\n'*) list+="$(git -C "$wt" rev-parse --short "$h")"$'\n' ;;
+        esac
+      done
+      list=${list%$'\n'}
     fi
   fi
   printf '%s\n' "$list"

package/plot-resolve-artifact.sh

@@ -70,6 +70,7 @@
 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.
 #
@@ -231,8 +232,9 @@ if ! mkdir "$lock" 2>/dev/null; then
 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.
-trap 'rmdir "$lock" 2>/dev/null || true' EXIT INT TERM
+# 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

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