@plot-pm/board 0.14.3 → 0.15.0

package/plot-reap.sh

@@ -187,6 +187,96 @@ git fetch origin "$DEFAULT" --quiet 2>/dev/null || true
 # newest — and defines `pr_merged` and nothing else on load.
 . "$(dirname "${BASH_SOURCE[0]}")/plot-pr-merged.sh"
 
+# Which uncommitted paths count as unlanded work. SOURCED, because the reap
+# reading, the dirty sweep below and `plot-reconcile-scan.sh` section 21 must
+# read one tree the same way; the helper names each excused path.
+. "$(dirname "${BASH_SOURCE[0]}")/plot-desk-dirt.sh"
+
+# Is an AGENT still working at a desk? SOURCED from `plot-worker-state.sh`,
+# the ONE classifier `plot-dispatch.sh --stop` also asks. Reading only whether
+# the recorded pid answers `ps` asked about the wrapper shell, which outlives
+# its agent: a desk whose agent had exited read `worker alive` here while
+# `--stop` answered `finished` for the same tree, so it could be neither
+# stopped nor reaped.
+# shellcheck source=plot-worker-state.sh
+. "$(dirname "${BASH_SOURCE[0]}")/plot-worker-state.sh"
+
+# The live worker's pid at a desk, or empty. The FIVE process states map to
+# one reading: `running` is live, and `finished`, `failed`, `ended` and `none`
+# are not.
+#
+# `waiting` and `stalled` are DISCARDED BY NAME. They are desk facts — a marker
+# for a person, work on the floor — which `plot_worker_state` reaches only once
+# no agent runs, and they answer what the agent still OWES. That question is
+# the blocked-marker, uncommitted and unpushed readings' below; only the
+# process fact under the two words (no agent is running) crosses into the
+# liveness reading.
+#
+# A word this mapping does not know keeps the desk: it reports the recorded
+# pid, or `unknown`, rather than guessing the process is gone.
+desk_worker_pid() { # $1=worktree → the live worker's pid, or empty
+  local row state spid
+  row=$(plot_worker_state "$1" "")
+  state=$(printf '%s' "$row" | cut -f1)
+  spid=$(printf '%s' "$row" | cut -f2)
+  case "$state" in
+    running)                   printf '%s' "${spid:-unknown}" ;;
+    finished|failed|ended|none) ;;
+    waiting|stalled)           ;;
+    *)                         printf '%s' "${spid:-unknown}" ;;
+  esac
+}
+
+# The commits on a desk's HEAD that no remote holds, as short shas, one per
+# line. Returns 1 when they cannot be counted, which the rule reads as
+# `unknown` and refuses on.
+#
+# NOT `@{upstream}..HEAD`. The host deletes a branch when its PR merges, and
+# the reaper only removes desks whose PR merged, so after `git fetch --prune`
+# every desk it serves has lost its upstream — and an absent upstream counts as
+# nothing. The reading is `HEAD --not --remotes` instead: what no remote-tracking
+# ref holds. After a squash merge and a pruned ref, the branch's own commits
+# are on no remote ref either, so the head the host MERGED is excluded too
+# (`pr_merged_heads`): a commit beyond it was never pushed.
+desk_unpushed() { # $1=worktree $2=branch $3=merge reading → short shas
+  local wt="$1" br="$2" merge="$3" list heads h
+  local -a excl=()
+  list=$(git -C "$wt" rev-list --abbrev-commit HEAD --not --remotes 2>/dev/null) || return 1
+  [ -n "$list" ] || return 0
+  if [ -n "$br" ] && [ "$merge" = merged ]; then
+    heads=$(pr_merged_heads "$br") || return 1
+    for h in $heads; do
+      git -C "$wt" cat-file -e "$h^{commit}" 2>/dev/null && excl+=("$h")
+    done
+    if [ "${#excl[@]}" -gt 0 ]; then
+      list=$(git -C "$wt" rev-list --abbrev-commit HEAD --not --remotes "${excl[@]}" 2>/dev/null) \
+        || return 1
+    else
+      # 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.
+      #
+      # Two ways to reach here, both normal. A SQUASH merge rewrites the
+      # commits, so the head the host names exists nowhere in this history —
+      # the same property that makes `plot-pr-merged.sh` read `mergedAt` and
+      # never ancestry, measured here as ancestry clearing 1 of 29 finished
+      # 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 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.
+      list=""
+    fi
+  fi
+  printf '%s\n' "$list"
+}
+
 # Where the registry lives, resolved through `plot-config.sh` — the SAME key and
 # default the board's reader uses (`resolveManifestDir` in `registry.ts` shells
 # out to exactly this). Two implementations of "where is the registry" is how
@@ -385,11 +475,19 @@ manifest_for() {
 reap=0; kept=0; removed=0; cleared=0; vanished=0; unplaced=0
 printf '%-8s %-52s %s\n' "verdict" "branch" "why"
 
-while IFS=$'\t' read -r wt br prunable; do
+while IFS=$'\037' read -r wt br prunable; do
   [ -n "$wt" ] || continue
   short=${br#refs/heads/}
   [ "$wt" = "$ROOT" ] && continue
 
+  # WHAT THE REPORT CALLS THIS TREE. `short` is the branch and stays empty for
+  # a detached desk, which is the correct reading and a useless label — an
+  # operator reading a blank column cannot tell which of thirteen it names.
+  # The directory is what identifies such a tree, so the report says so and
+  # every refusal still measures `short`.
+  label=$short
+  [ -z "$label" ] && label="(detached) $(basename "$wt")"
+
   # 4a. GIT'S OWN ANSWER THAT THE DIRECTORY IS GONE, and it is a REPORT rather
   #     than a sixth refusal. The five below each say *do not remove this* and
   #     send an operator to look; this says *there is nothing to remove and the
@@ -414,7 +512,7 @@ while IFS=$'\t' read -r wt br prunable; do
   #     prune stays the operator's decision — the same discipline that makes
   #     every refusal a measurement rather than an act.
   if [ "$prunable" = "yes" ]; then
-    printf '%-8s %-52s %s\n' "vanished" "$short" "directory gone — 'git worktree prune' clears the entry"
+    printf '%-8s %-52s %s\n' "vanished" "$label" "directory gone — 'git worktree prune' clears the entry"
     vanished=$((vanished+1)); continue
   fi
 
@@ -482,7 +580,7 @@ while IFS=$'\t' read -r wt br prunable; do
   # population the rule excludes. It counts, because a refusal that counts is
   # the difference between *nothing to clean* and *nothing was looked at*.
   if [ "$unclassified" = true ]; then
-    printf '%-8s %-52s %s\n' "unknown" "$short" \
+    printf '%-8s %-52s %s\n' "unknown" "$label" \
       "under $(basename "$WT_ROOT")/, no worker pid and no recognised name — needs a person"
     unplaced=$((unplaced+1)); continue
   fi
@@ -493,25 +591,21 @@ while IFS=$'\t' read -r wt br prunable; do
 
   # The process table: the live worker's pid, or empty. Read but not judged —
   # an empty pid file is not a live process, and which of those two it is is
-  # the rule's to say.
-  pid=""
-  if [ -f "$wt/.plot-worker.pid" ]; then
-    p=$(cat "$wt/.plot-worker.pid" 2>/dev/null)
-    if [ -n "$p" ] && ps -p "$p" >/dev/null 2>&1; then pid="$p"; fi
-  fi
+  # the rule's to say. "Live" means an agent runs under the recorded pid, the
+  # answer `--stop` reads; a wrapper whose agent exited is not live.
+  pid=$(desk_worker_pid "$wt")
 
   # The tree: a PLOT-BLOCKED marker, and the first uncommitted path.
   #
-  # The tiny-garden pulse is excused because every board suite rewrites it — a
-  # worker that did nothing but run the tests would otherwise never be
-  # reapable. Any OTHER dirty path is still reported, which keeps this an
-  # exception rather than a hole. It is filtered HERE, in the reading, because
-  # it is a fact about this repository's fixtures and not about whether a
-  # worktree may go.
+  # `desk_dirt` excuses the paths the estate writes itself — the tiny-garden
+  # pulse and a root `PLOT-CORRECTION.md` — and reports every OTHER dirty path,
+  # which keeps this an exception rather than a hole. It is filtered HERE, in
+  # the reading, because those are facts about files this estate writes and
+  # 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=$(git -C "$wt" status --porcelain 2>/dev/null \
-            | grep -v 'tiny-garden/\.plot/state' | head -1)
+  dirty=$(desk_dirt "$wt" | head -1)
 
   # The host: whether ANY PR for this branch merged.
   #
@@ -531,8 +625,33 @@ while IFS=$'\t' read -r wt br prunable; do
     merge=merged; why="merged into $DEFAULT"
   elif [ -n "$short" ] && pr_merged "$short"; then
     merge=merged; why="PR merged (squash)"
+  elif [ -z "$short" ] \
+       && [ "$(git -C "$wt" rev-list --count "origin/$DEFAULT..HEAD" 2>/dev/null || echo 1)" = "0" ]; then
+    # A DETACHED DESK HAS NOTHING TO LAND, and that is a measurement rather
+    # than a weakened refusal. `plot-dispatch.sh --start` cuts a free agent's
+    # desk detached at `origin/<main>` because a free agent holds no slice, so
+    # such a tree never had a branch and can never have a PR. Reading it
+    # through `no-merged-pr` would refuse every one of them forever — the same
+    # silence this slice removes, in the opposite direction.
+    #
+    # THE READING IS `HEAD` AGAINST THE DEFAULT BRANCH, never the desk's name.
+    # Measured 2026-09-22: three `free-*` desks hold a branch and two carry
+    # live workers (pids 27820, 6542), so a prefix-keyed test reaps a running
+    # agent. Detachment is the condition; the name is not.
+    #
+    # A detached desk carrying commits falls through to `not-merged` and is
+    # kept, which is correct: somebody committed there and nothing says the
+    # work landed. The live-pid, marker and dirty refusals are all asked
+    # before this and are unaffected.
+    merge=merged; why="detached, nothing to land"
   fi
 
+  # The desk again: commits only this checkout holds. Taken AFTER the merge
+  # reading, because the head the host merged is what separates a pushed
+  # commit from an unpushed one once the remote ref is gone. Lines, or the
+  # word `unknown` when they could not be counted.
+  if unpushed=$(desk_unpushed "$wt" "$short" "$merge"); then :; else unpushed=unknown; fi
+
   # THE DECISION. One call, and the script holds no `if` about whether a
   # worktree may go — only about what to do with the answer.
   #
@@ -554,7 +673,7 @@ while IFS=$'\t' read -r wt br prunable; do
   # the tree and says why. Silence is never permission, on this path either.
   verdict=$(PLOT_BRANCH="$short" PLOT_DEFAULT="$DEFAULT" PLOT_PID="$pid" \
             PLOT_DIRTY="$dirty" PLOT_MARKER="$marker" PLOT_MERGE="$merge" \
-            PLOT_RULE="$RULE" \
+            PLOT_UNPUSHED="$unpushed" PLOT_RULE="$RULE" \
             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
@@ -576,6 +695,9 @@ const problem = firstReapRefusal({
   dirtyPath: process.env.PLOT_DIRTY,
   blockedMarker: process.env.PLOT_MARKER === "true",
   merge: process.env.PLOT_MERGE,
+  unpushed: process.env.PLOT_UNPUSHED === "unknown"
+    ? "unknown"
+    : process.env.PLOT_UNPUSHED.split("\n").filter((l) => l !== ""),
 });
 
 // `reap` when nothing refused; otherwise the refusal and its reading, which
@@ -595,15 +717,16 @@ NODE_EOF
       live-worker)         reason="worker alive (pid $detail)" ;;
       blocked-marker)      reason="PLOT-BLOCKED marker — needs a person" ;;
       uncommitted-changes) reason="uncommitted: ${detail:0:40}" ;;
+      unpushed-commits)    reason="unpushed commits: ${detail:0:40}" ;;
       on-default-branch)   reason="on $DEFAULT — dispatched branch not checked out" ;;
       no-merged-pr)        reason="unlanded work — no merged PR" ;;
       *)                   reason="rule could not be asked — keeping" ;;
     esac
-    printf '%-8s %-52s %s\n' "keep" "$short" "$reason"; kept=$((kept+1)); continue
+    printf '%-8s %-52s %s\n' "keep" "$label" "$reason"; kept=$((kept+1)); continue
   fi
 
   if [ "$MAX" -gt 0 ] && [ "$reap" -ge "$MAX" ]; then
-    printf '%-8s %-52s %s\n' "keep" "$short" "--max $MAX reached"; kept=$((kept+1)); continue
+    printf '%-8s %-52s %s\n' "keep" "$label" "--max $MAX reached"; kept=$((kept+1)); continue
   fi
 
   # Resolved BEFORE the removal, because `canonical` needs the directory to
@@ -619,7 +742,7 @@ NODE_EOF
 
   reap=$((reap+1))
   if [ "$DRY" -eq 1 ]; then
-    printf '%-8s %-52s %s\n' "would" "$short" "$why${logs:+, log $logs}"
+    printf '%-8s %-52s %s\n' "would" "$label" "$why${logs:+, log $logs}"
   else
     if git worktree remove --force "$wt" 2>/dev/null; then
       # The worktree is gone; NOW the manifest may go. Inside the success arm
@@ -647,16 +770,16 @@ NODE_EOF
         while IFS= read -r f; do rm -f "$f" 2>/dev/null; done < <(branch_log_files "$short")
         why="$why, log removed"
       fi
-      printf '%-8s %-52s %s\n' "reaped" "$short" "$why"; removed=$((removed+1))
+      printf '%-8s %-52s %s\n' "reaped" "$label" "$why"; removed=$((removed+1))
     else
-      printf '%-8s %-52s %s\n' "FAILED" "$short" "git worktree remove refused"; kept=$((kept+1))
+      printf '%-8s %-52s %s\n' "FAILED" "$label" "git worktree remove refused"; kept=$((kept+1))
     fi
   fi
 done < <(git worktree list --porcelain \
-          | awk '/^worktree /{ if (br != "") print p"\t"br"\t"pr; p=$2; br=""; pr="no"; next }
+          | awk -v OFS="\037" '/^worktree /{ if (p != "") print p, br, pr; p=$2; br=""; pr="no"; next }
                  /^branch /  { br=$2; next }
                  /^prunable/ { pr="yes"; next }
-                 END         { if (br != "") print p"\t"br"\t"pr }')
+                 END         { if (p != "") print p, br, pr }')
 
 [ "$DRY" -eq 0 ] && git worktree prune 2>/dev/null
 
@@ -1005,15 +1128,12 @@ while IFS=$'\t' read -r wt br; do
   [ -n "$MAIN_CHECKOUT" ] && [ "$(canonical "$wt")" = "$(canonical "$MAIN_CHECKOUT")" ] && continue
   dshort=${br#refs/heads/}
 
-  dcount=$(git -C "$wt" status --porcelain 2>/dev/null \
-             | grep -v 'tiny-garden/\.plot/state' | wc -l | tr -d ' ')
+  dcount=$(desk_dirt "$wt" | wc -l | tr -d ' ')
   [ "${dcount:-0}" -gt 0 ] || continue
 
-  dpid=""
-  if [ -f "$wt/.plot-worker.pid" ]; then
-    p=$(cat "$wt/.plot-worker.pid" 2>/dev/null)
-    if [ -n "$p" ] && ps -p "$p" >/dev/null 2>&1; then dpid="$p"; fi
-  fi
+  # The same liveness reading the reap loop takes, so a desk the reaper keeps
+  # for a live worker and one the sweep names as owned are the same desks.
+  dpid=$(desk_worker_pid "$wt")
 
   dmanifest=""
   if m=$(manifest_for "$(canonical "$wt")"); then dmanifest=$(basename "$m"); fi