@plot-pm/board 0.16.2 → 0.17.0

package/plot-reap.sh

@@ -44,12 +44,11 @@
 # written. The scan reports; nothing reaped. Measured 2026-08-25 on this
 # estate: 56 worktrees, 42 of them dispatch trees, of which 29 were finished.
 #
-# WHY A SCRIPT RATHER THAN AN AGENT (Manifesto Principle 3, and the licence
-# `plot-resolve-artifact.sh` states for the one other automatic write): every
-# refusal below is a MEASUREMENT, not a judgement. Is a process alive; is the
-# tree dirty; did the host merge the PR. An agent asked "is this safe to
-# delete?" can talk itself past any of the three. A script cannot, and
-# judgement's absence is exactly what licenses the delete.
+# WHY A SCRIPT RATHER THAN AN AGENT (Manifesto Principle 3): every refusal
+# below is a MEASUREMENT, not a judgement. Is a process alive; is the tree
+# dirty; did the host merge the PR. An agent asked "is this safe to delete?"
+# can talk itself past any of the three. A script cannot, and judgement's
+# absence is exactly what licenses the delete.
 #
 # AND THE DECIDING IS NOT HERE. This script GATHERS the readings, asks
 # `packages/domain/src/rules/reapable.ts`, and ACTS on the answer; it holds no
@@ -433,8 +432,9 @@ LOG_DIR="$WT_ROOT"
 #
 # WHICH LOG THIS IS, since the plan says "the dispatcher log" and the estate
 # holds two shapes of one. `plot-resolve-<branch>` is keyed by BRANCH with its
-# slashes flattened (`repairLogPath`), so it maps one-to-one onto the worktree
-# this loop is removing. `plot-dispatch-<slug>` is keyed by PLAN and opened for
+# slashes flattened (`agentLogPath`'s `resolve` kind), so it maps one-to-one
+# onto the worktree this loop is removing. The artifact repair that wrote it
+# was retired on 2026-10-03; the sweep removes the logs still on disk. `plot-dispatch-<slug>` is keyed by PLAN and opened for
 # APPEND across every dispatch of that plan — `dispatch.ts:150` states it: "a
 # dispatcher log belongs to a plan, a worker log to a branch". Reaping one
 # branch of a five-branch plan must not delete the record the other four are
@@ -656,8 +656,25 @@ while IFS=$'\037' read -r wt br prunable; do
   # not about whether a worktree may go. The filter runs before `head`, so a
   # correction beside a real file names the real file.
   marker=false
-  ls "$wt"/PLOT-BLOCKED* >/dev/null 2>&1 && marker=true
-  dirty=$(desk_dirt "$wt" | head -1)
+  marker_file=$(ls "$wt"/PLOT-BLOCKED* 2>/dev/null | head -1)
+  [ -n "$marker_file" ] && marker=true
+  # The marker's own line is excluded from `dirty`, which otherwise answers
+  # `uncommitted-changes` for a desk this slice reads `refused-empty` instead:
+  # the marker is a question for a person, not unlanded work, and the two
+  # refusals must not both fire for the one line that names it.
+  dirty=$(desk_dirt "$wt" | grep -v 'PLOT-BLOCKED' | head -1)
+
+  # markerRecordsWork — does the desk hold anything besides its marker: a
+  # dirty path that is not the marker itself (`$dirty`, already filtered
+  # above), or a file-changing commit beyond the default branch. Read only
+  # when a marker is present — `firstReapRefusal` does not consult this field
+  # otherwise.
+  marker_records_work=false
+  if [ "$marker" = true ]; then
+    if [ -n "$dirty" ] || [ "$(real_commits "$wt" "origin/$DEFAULT..HEAD")" != 0 ]; then
+      marker_records_work=true
+    fi
+  fi
 
   # The host: whether ANY PR for this branch merged.
   #
@@ -726,6 +743,7 @@ while IFS=$'\037' read -r wt br prunable; do
   verdict=$(PLOT_BRANCH="$short" PLOT_DEFAULT="$DEFAULT" PLOT_PID="$pid" \
             PLOT_DIRTY="$dirty" PLOT_MARKER="$marker" PLOT_MERGE="$merge" \
             PLOT_UNPUSHED="$unpushed" PLOT_RULE="$RULE" \
+            PLOT_MARKER_RECORDS_WORK="$marker_records_work" \
             node --input-type=module - <<'NODE_EOF' 2>/dev/null
 // Imported from an ABSOLUTE path derived from this script, never from the
 // cwd. The reaper runs with its cwd wherever the operator invoked it and the
@@ -746,6 +764,7 @@ const problem = firstReapRefusal({
   workerPid: process.env.PLOT_PID === "" ? null : process.env.PLOT_PID,
   dirtyPath: process.env.PLOT_DIRTY,
   blockedMarker: process.env.PLOT_MARKER === "true",
+  markerRecordsWork: process.env.PLOT_MARKER_RECORDS_WORK === "true",
   merge: process.env.PLOT_MERGE,
   unpushed: process.env.PLOT_UNPUSHED === "unknown"
     ? "unknown"
@@ -792,6 +811,27 @@ NODE_EOF
   # a missing log is the desired state, not an event.
   logs=$(present_logs "$short")
 
+  # THE MARKER MOVES, IT IS NOT DROPPED. A tree that reached `reap` with
+  # `marker=true` passed `firstReapRefusal` only because `markerRecordsWork`
+  # was measured false — `rules/desk-lifecycle.ts`'s `refused-empty`. The
+  # marker's text is evidence of a question somebody asked even though the
+  # desk holding it is otherwise empty, so it is copied to REFUSALS_LOG before
+  # the worktree goes. A FAILED COPY KEEPS THE DESK: the marker is the only
+  # record of the question, and a reap that lost both would make the evidence
+  # exactly as unrecoverable as the desk it lived in.
+  if [ "$DRY" -eq 0 ] && [ "$marker" = true ] && [ -n "$marker_file" ]; then
+    refusals_log="$ROOT/.plot/state/refusals.tsv"
+    if mkdir -p "$(dirname "$refusals_log")" 2>/dev/null \
+       && printf '%s\t%s\t%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$label" \
+            "$(tr '\n\t' '  ' < "$marker_file" 2>/dev/null)" >> "$refusals_log" 2>/dev/null; then
+      why="$why, marker saved to .plot/state/refusals.tsv"
+    else
+      printf '%-8s %-52s %s\n' "keep" "$label" \
+        "could not save PLOT-BLOCKED text to .plot/state/refusals.tsv — desk kept"
+      kept=$((kept+1)); continue
+    fi
+  fi
+
   reap=$((reap+1))
   if [ "$DRY" -eq 1 ]; then
     printf '%-8s %-52s %s\n' "would" "$label" "$why${logs:+, log $logs}"
@@ -1035,25 +1075,18 @@ fi
 case "$ACTIVE_DIR_SWEEP" in /*) ;; *) ACTIVE_DIR_SWEEP="$ROOT/$ACTIVE_DIR_SWEEP" ;; esac
 
 # Does this branch carry ONLY empty claim commits? The scan's definition,
-# applied to a LOCAL ref — this sweep runs over local branches, where the scan
-# reads `origin/`.
+# applied to LOCAL refs — this sweep runs over local branches, where the scan
+# reads `origin/`. ONE `board/plot-empty-claim.mjs` call answers every branch;
+# a branch it does not answer `<branch>\t0` for, a missing bundle included,
+# carries real work and stays.
+EMPTY_CLAIMS=$(git for-each-ref --format='%(refname:short)' refs/heads/ 2>/dev/null |
+  while IFS= read -r br; do
+    git log --boundary --format="${br//%/%%}%x09%m%x09%H%x09%T%x09%P%x09%s" \
+      "origin/$DEFAULT..$br" -- </dev/null 2>/dev/null
+  done | node "$(dirname "${BASH_SOURCE[0]}")/board/plot-empty-claim.mjs" 2>/dev/null) || EMPTY_CLAIMS=""
+
 sweep_is_empty_claim() { # $1=branch
-  local br="$1" ahead c subj real=0
-  ahead=$(git rev-list --count "origin/$DEFAULT..$br" 2>/dev/null || echo 0)
-  [ "${ahead:-0}" -gt 0 ] || return 1   # nothing of its own → merged work, not a claim
-  for c in $(git rev-list "origin/$DEFAULT..$br" </dev/null 2>/dev/null); do
-    subj=$(git log -1 --format=%s "$c" </dev/null 2>/dev/null)
-    case "$subj" in
-      "plot: claim "*)
-        # Titled AND empty. Both, or it counts as real work.
-        if [ "$(git rev-parse "$c^{tree}" </dev/null 2>/dev/null)" \
-             = "$(git rev-parse "$c^^{tree}" </dev/null 2>/dev/null)" ]; then
-          continue
-        fi ;;
-    esac
-    real=$((real+1))
-  done
-  [ "$real" = "0" ]
+  printf '%s\n' "$EMPTY_CLAIMS" | grep -qxF "$1	0"
 }
 
 # How the plan annotation classified this claim — the scan's `claim_disposition`,

package/plot-state-receipt.sh

@@ -165,11 +165,17 @@ _action_receipt_dir() {
 # adapter — a script name in a controller is a boundary crossing no spawn
 # counter can see. So the shared filename is the action word, and mapping a
 # script back to it happens HERE, on the side that reads command lines.
+#
+# `plot-deliver.sh` maps to `deliver` here, same as always — `release` is a
+# SEPARATE action sharing that script, and only `plot-controller-gate.sh` can
+# tell the two calls apart (by whether `--release` rode along), so it passes
+# the action word directly rather than the script name for that one case.
 _action_of() { # $1=script name or action word → the action, or nothing
   case "${1##*/}" in
     plot-dispatch.sh|dispatch) printf 'dispatch\n' ;;
     plot-approve.sh|approve)   printf 'approve\n' ;;
     plot-deliver.sh|deliver)   printf 'deliver\n' ;;
+    release)                   printf 'release\n' ;;
   esac
 }
 
@@ -231,7 +237,7 @@ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
     action_reason="$*"
     if [ -z "$action_script" ] || [ -z "$action_subject" ] || [ -z "$action_reason" ]; then
       echo "plot-state-receipt: --unowned-action needs an action, a subject and a reason." >&2
-      echo "  usage: plot-state-receipt.sh --unowned-action <dispatch|approve|deliver> <slug> <reason>" >&2
+      echo "  usage: plot-state-receipt.sh --unowned-action <dispatch|approve|deliver|release> <slug> <reason>" >&2
       echo "" >&2
       echo "  The reason is required because each use names a routing gap, and a gap" >&2
       echo "  nobody wrote down is one nobody closes. Where the board IS running, the" >&2
@@ -240,13 +246,17 @@ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
     fi
     # The action word, or the script name — an operator reaching for this has
     # just read a refusal naming a script, so both spellings are accepted.
+    # `release` has no script of its own (`plot-deliver.sh --release` shares
+    # `plot-deliver.sh`, which already names `deliver`), so only the bare word
+    # is accepted for it.
     case "$action_script" in
       dispatch|plot-dispatch.sh) action_script="dispatch" ;;
       approve|plot-approve.sh)   action_script="approve" ;;
       deliver|plot-deliver.sh)   action_script="deliver" ;;
+      release)                   action_script="release" ;;
       *)
         echo "plot-state-receipt: '$action_script' is not a controller-owned action." >&2
-        echo "  The three are: dispatch, approve, deliver." >&2
+        echo "  The four are: dispatch, approve, deliver, release." >&2
         exit 2
         ;;
     esac

package/plot-tmp.sh

@@ -59,22 +59,50 @@ _plot_tmp_register() {
 # unlisted. While `__plot_tmp_busy` is set, the signal handler records the
 # signal in `__plot_tmp_pending` and returns; `_plot_tmp_create` handles it once
 # the path is registered.
+#
+# A SUBSHELL HOLDS THE SIGNAL ITSELF. bash resets caught traps in `$(…)` and
+# `( … )`, so there the handler above is not installed and a TERM between
+# `mktemp` and the registration ends the subshell with the path unlisted. The
+# owner's cleanup then runs and cannot remove it. `plot-host.sh`'s
+# `pr_list_call` creates `plot-host-prlist-err.*` this way, inside
+# `_raw="$(pr_list_call …)"`, and CI run 37052327801 left one when the board
+# test teardown sent its process group TERM. Inside a subshell
+# (`BASH_SUBSHELL` > 0; bash 3.2 has no `BASHPID`) the creation installs
+# handlers that only record the signal, and after the registration it restores
+# the defaults and exits with 128 + the signal's number. It does not run the
+# cleanup: the registry belongs to the owner, which received the same group
+# signal and removes the path when the subshell has ended.
 __plot_tmp_busy=''
 __plot_tmp_pending=''
 
 # _plot_tmp_create VAR prefix [-d] — create, register, assign to VAR.
 _plot_tmp_create() {
-  local __plot_tmp_new __plot_tmp_rc
+  local __plot_tmp_new __plot_tmp_rc __plot_tmp_sub=''
   __plot_tmp_busy=1
+  if [ "${BASH_SUBSHELL:-0}" -gt 0 ]; then
+    __plot_tmp_sub=1
+    trap '__plot_tmp_pending="INT 2"' INT
+    trap '__plot_tmp_pending="TERM 15"' TERM
+    trap '__plot_tmp_pending="PIPE 13"' PIPE
+  fi
   if [ "${3:-}" = -d ]; then
     __plot_tmp_new=$(mktemp -d "${TMPDIR:-/tmp}/plot-$2.XXXXXX")
   else
     __plot_tmp_new=$(mktemp "${TMPDIR:-/tmp}/plot-$2.XXXXXX")
   fi
   __plot_tmp_rc=$?
-  [ "$__plot_tmp_rc" -eq 0 ] && _plot_tmp_register p "$__plot_tmp_new"
+  # THE PATH IS REGISTERED WHEN IT EXISTS, whatever the status says. bash 3.2
+  # reports 143 for `$(mktemp …)` when a trap ran during it, although `mktemp`
+  # created the path and printed it; a status-only test leaves that path
+  # unlisted.
+  if [ -n "$__plot_tmp_new" ] && { [ -e "$__plot_tmp_new" ] || [ "$__plot_tmp_rc" -eq 0 ]; }; then
+    _plot_tmp_register p "$__plot_tmp_new"
+  fi
   __plot_tmp_busy=''
-  if [ -n "$__plot_tmp_pending" ]; then
+  if [ -n "$__plot_tmp_sub" ]; then
+    trap - INT TERM PIPE
+    [ -z "$__plot_tmp_pending" ] || exit $((128 + ${__plot_tmp_pending#* }))
+  elif [ -n "$__plot_tmp_pending" ]; then
     # shellcheck disable=SC2086 # "<name> <number>", split on purpose
     _plot_tmp_on_signal $__plot_tmp_pending
   fi