@plot-pm/board 0.8.1 → 0.9.1

package/plot-plan-meta.sh

@@ -57,6 +57,11 @@
 # the old shape invited (a second path-shaped token on a line read as a phantom
 # branch) is structurally impossible.
 #
+# The old shape is now closed against the same defect from the other side: a
+# claim must be a LIST ITEM that starts with the backticked name, so a branch
+# cited in prose, a blockquote or an HTML comment under `## Branches` is read as
+# the citation it is. See the anchor at `branch_claim_re` below.
+#
 # Phase values are normalized by scanning whitespace-separated tokens for the
 # first known phase word — so decorated real-world values like
 # "Delivered (2026-06-29) — split done" normalize to "delivered". A non-empty
@@ -88,9 +93,14 @@
 #   assignee       github handle from the `## Approval` `Assignee:` line or
 #                  front matter `assignee:`; "" if absent
 #   branches       branch names, sorted and unique, read from EITHER spelling:
-#                  the old `## Branches` section (backtick-quoted in the list
-#                  line, matching the known prefixes) OR the new `## Waves`
-#                  section (`Branch:` in a `### ` heading — see below). Both
+#                  the old `## Branches` section (a LIST ITEM whose first token
+#                  is the backtick-quoted name, matching the known prefixes) OR
+#                  the new `## Waves` section (`Branch:` in a `### ` heading —
+#                  see below). A backticked branch name anywhere else under
+#                  `## Branches` — mid-sentence, in a blockquote, in a comment,
+#                  on a wrapped continuation line — is a CITATION and claims
+#                  nothing: plans name each other branches to declare
+#                  dependencies, and doing so must not claim them. Both
 #                  spellings emit the same array; a plan carries one or the
 #                  other, and the parser reads both so a migration that moves
 #                  files one at a time never makes a plan silently empty.
@@ -201,11 +211,18 @@
 set -uo pipefail
 
 prefixes='idea|feature|bug|docs|infra'
+tracker_override=''      # set by --tracker; overrides the config read below
+tracker_override_set=0
 files=()
 missing=()
 while [ $# -gt 0 ]; do
   case "$1" in
     --prefixes) prefixes="${2:?--prefixes needs a value}"; shift 2 ;;
+    # --tracker names the tracker directly, bypassing plot-config.sh. It exists
+    # for the contract tests (which parse fixtures outside any repo whose Plot
+    # Config could name a tracker) and for a caller that has already resolved
+    # the value once. An empty value means "GitHub", the same as no config.
+    --tracker) tracker_override="${2-}"; tracker_override_set=1; shift 2 ;;
     -*) echo "plot-plan-meta: unknown flag: $1" >&2; shift ;;
     *)
       if [ -f "$1" ]; then files+=("$1"); else missing+=("$1"); fi
@@ -225,7 +242,33 @@ done
 
 [ ${#files[@]} -gt 0 ] || exit 0
 
-awk -v PREFIXES="$prefixes" '
+# Read the tracker config to determine whether tracker-key issue references
+# (`PROJ-123`) are parsed in addition to GitHub's `#N`.
+#
+# THIS IS THE FIRST CONFIGURATION DEPENDENCY THIS SCRIPT HAS — keep it narrow:
+# read ONE key, an unreadable or missing config means GitHub (today's
+# behaviour), and NEVER fail a parse for want of configuration. plot-config.sh
+# exits 0 for all cases and prints an empty string when the key is absent, so a
+# repo with no `## Plot Config` at all still parses exactly as it does today.
+if [ "$tracker_override_set" -eq 1 ]; then
+  tracker="$tracker_override"
+else
+  script_dir="$(dirname "${BASH_SOURCE[0]}")"
+  tracker=$("$script_dir/plot-config.sh" get Tracker 2>/dev/null || true)
+fi
+# The value may carry a URL after the scheme (`jira https://…`), so match the
+# FIRST token, lowercased. Only a tracker whose keys are `LETTERS-digits` —
+# jira, linear — enables the key form; github, github-issues, plot, and absent
+# all keep `#N`-only, unchanged. An unrecognized token stays GitHub too: a
+# guess here would let `WONT-FIX` masquerade as an issue reference and hide a
+# real ticket, which the plan interrogation explicitly rejected.
+tracker_scheme=$(printf '%s' "$tracker" | tr '[:upper:]' '[:lower:]' | awk '{print $1}')
+case "$tracker_scheme" in
+  jira|linear) parse_key_issues=1 ;;
+  *) parse_key_issues=0 ;;
+esac
+
+awk -v PREFIXES="$prefixes" -v PARSE_KEY_ISSUES="$parse_key_issues" '
 function jesc(s) {
   gsub(/\\/, "\\\\", s); gsub(/"/, "\\\"", s); gsub(/\t/, "\\t", s)
   return s
@@ -316,7 +359,7 @@ function reset_state() {
   fm_changelog = ""
   delete changelog; n_changelog = 0; changelog_seen = 0; cl_open = 0
 }
-function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assignee, review, impl, design, approved, delivered, issue, i, j, out, sorted_b, sorted_p, sorted_i, nb, np, ni) {
+function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assignee, review, impl, design, approved, delivered, issue, issue2, i, j, v, is_dup, out, sorted_b, sorted_p, sorted_i, nb, np, ni, num_issues, str_issues, n_num_i, n_str_i, issue_is_str) {
   if (fm_status != "" || fm_phase != "") {
     fmt = "frontmatter"
     praw = (fm_status != "") ? fm_status : fm_phase
@@ -350,10 +393,27 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
   # A LIST, because one plan can answer several signals; the plan that
   # introduced this field subsumes three.
   issue = strip_placeholder((fm_issue != "") ? fm_issue : canon_issue)
+  # GitHub-style `#N` is parsed everywhere, regardless of tracker.
   while (match(issue, /#[0-9]+/)) {
     issues[++n_issues] = substr(issue, RSTART + 1, RLENGTH - 1)
     issue = substr(issue, RSTART + RLENGTH)
   }
+  # Jira-style `PROJ-123` is parsed ONLY when Tracker: names a non-GitHub
+  # tracker (jira, linear). PARSE_KEY_ISSUES is set by the shell before the awk
+  # invocation, based on plot-config.sh reading the Tracker key. Missing config
+  # defaults to 0 (GitHub behaviour), so this never fires in a repo with no
+  # config — the test in this branch proves that (Done-when item 6).
+  #
+  # THE PATTERN is `[A-Z]+-[0-9]+` anchored to word boundaries by iterating
+  # through the string. A greedy match of the whole field would capture only
+  # one; the loop mirrors the `#N` extraction above.
+  if (PARSE_KEY_ISSUES == 1) {
+    issue2 = strip_placeholder((fm_issue != "") ? fm_issue : canon_issue)
+    while (match(issue2, /[A-Z][A-Z0-9]*-[0-9]+/)) {
+      issues[++n_issues] = substr(issue2, RSTART, RLENGTH)
+      issue2 = substr(issue2, RSTART + RLENGTH)
+    }
+  }
   # Insertion sort + dedupe (portable: no gawk asort).
   nb = 0
   for (i = 1; i <= n_branches; i++) {
@@ -369,13 +429,36 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
     for (j = np; j >= 1 && sorted_p[j] > prs[i]+0; j--) sorted_p[j+1] = sorted_p[j]
     sorted_p[j+1] = prs[i]+0; np++
   }
-  ni = 0
+  # Issues: sort numeric (GitHub) issues first, then string (Jira) keys.
+  # Separate into two arrays, sort each, then concatenate.
+  n_num_i = 0; n_str_i = 0
   for (i = 1; i <= n_issues; i++) {
-    for (j = 1; j <= ni && sorted_i[j] != issues[i]+0; j++) ;
-    if (j <= ni) continue
-    for (j = ni; j >= 1 && sorted_i[j] > issues[i]+0; j--) sorted_i[j+1] = sorted_i[j]
-    sorted_i[j+1] = issues[i]+0; ni++
+    v = issues[i]
+    if (v ~ /^[0-9]+$/) {
+      # Numeric: check for duplicate, then insert sorted.
+      is_dup = 0
+      for (j = 1; j <= n_num_i; j++) if (num_issues[j] == v + 0) { is_dup = 1; break }
+      if (!is_dup) {
+        for (j = n_num_i; j >= 1 && num_issues[j] > v + 0; j--) num_issues[j+1] = num_issues[j]
+        num_issues[j+1] = v + 0; n_num_i++
+      }
+    } else {
+      # String (Jira key): check for duplicate, then insert sorted.
+      is_dup = 0
+      for (j = 1; j <= n_str_i; j++) if (str_issues[j] == v) { is_dup = 1; break }
+      if (!is_dup) {
+        for (j = n_str_i; j >= 1 && str_issues[j] > v; j--) str_issues[j+1] = str_issues[j]
+        str_issues[j+1] = v; n_str_i++
+      }
+    }
   }
+  # Concatenate: numeric first, then string (matches the field ordering the
+  # board expects — GitHub issues before Jira keys when both are present).
+  ni = 0
+  for (i = 1; i <= n_num_i; i++) sorted_i[++ni] = num_issues[i]
+  for (i = 1; i <= n_str_i; i++) sorted_i[++ni] = str_issues[i]
+  delete issue_is_str
+  for (i = 1; i <= n_str_i; i++) issue_is_str[str_issues[i]] = 1
   out = "{\"file\":\"" jesc(cur_file) "\",\"format\":\"" fmt "\""
   out = out ",\"phase_raw\":\"" jesc(praw) "\",\"phase\":\"" norm_phase(praw) "\""
   out = out ",\"phase_alt_raw\":\"" jesc(palt_raw) "\",\"phase_alt\":\"" norm_phase(palt_raw) "\""
@@ -387,7 +470,13 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
   out = out "],\"prs\":["
   for (i = 1; i <= np; i++) out = out (i > 1 ? "," : "") sorted_p[i]
   out = out "],\"issues\":["
-  for (i = 1; i <= ni; i++) out = out (i > 1 ? "," : "") sorted_i[i]
+  for (i = 1; i <= ni; i++) {
+    # Numeric issues output as JSON numbers; string issues (Jira keys) as quoted.
+    if (sorted_i[i] in issue_is_str)
+      out = out (i > 1 ? "," : "") "\"" jesc(sorted_i[i]) "\""
+    else
+      out = out (i > 1 ? "," : "") sorted_i[i]
+  }
   out = out "],\"malformed_prs\":["
   for (i = 1; i <= n_malformed_prs; i++) out = out (i > 1 ? "," : "") "\"" jesc(malformed_prs[i]) "\""
   out = out "]"
@@ -463,7 +552,26 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
 # (13), and the offender this exists to catch is a 53-character sentence, so the
 # line sits well clear of both. Reported, never enforced — a name past it makes
 # `long_wave_names`, and nothing refuses the plan.
-BEGIN { branch_re = "`(" PREFIXES ")/[^`]+`"; LONG_WAVE_NAME_MAX = 40 }
+# A CLAIM IS A LIST ITEM, and the anchor is what says so.
+#
+# This matched a backticked branch name ANYWHERE on a line, so a plan that
+# merely CITED another plan branch under `## Branches` claimed it. Measured on
+# the board 2026-08-23: two branches rendered twice, in two sections, wearing
+# `claimed twice` — and /plot-dispatch would have fanned out a branch the plan
+# does not own. Both second claims were dependency citations, written exactly as
+# a `## Branches` section should write them.
+#
+# Rewording the citations was the old repair. That is a rule an author must
+# remember in the one section where writing branch names is the entire point,
+# and it had already been forgotten twice. Gates over rules: anchoring makes the
+# parser UNABLE to read a citation as a claim.
+#
+# Licensed by a MEASUREMENT, not a preference. Swept across docs/plans/ on
+# 2026-08-27: 259 lines under `## Branches` carry a backticked branch name and
+# all 259 are anchored list items, so the stricter rule drops no real claim. The
+# contract test re-runs that sweep differentially rather than pinning a total —
+# the estate moves weekly, and an absolute number would fail a correct parser.
+BEGIN { branch_claim_re = "^[ \t]*-[ \t]+`(" PREFIXES ")/[^`]+`"; LONG_WAVE_NAME_MAX = 40 }
 FNR == 1 {
   if (NR > 1) emit_record()
   reset_state()
@@ -667,9 +775,19 @@ section == "branches" {
     sub(/[ \t]*-->.*$/, "", _d)
     defer_note = trim(_d)
   }
-  line = $0
-  while (match(line, branch_re)) {
-    b = substr(line, RSTART + 1, RLENGTH - 2)
+  # ONE LIST ITEM, AT MOST ONE CLAIM — an `if`, not the `while` this was.
+  #
+  # The old loop walked the line taking every backticked name on it, which is
+  # exactly how a citation became a second claim. Anchoring makes a second match
+  # impossible by construction, so the loop is gone rather than left as dead
+  # scaffolding that reads like several claims per item are still expected.
+  #
+  # The match now spans `- ` and the backticks, so the name is cut from the
+  # first backtick rather than from RSTART: RSTART lands on the indent.
+  if (match($0, branch_claim_re)) {
+    claim = substr($0, RSTART, RLENGTH)
+    b = substr(claim, index(claim, "`") + 1)
+    sub(/`$/, "", b)
     branches[++n_branches] = b
     if (n_waves == 0) { wave_names[++n_waves] = "" }
     wave_of[n_branches] = n_waves
@@ -691,7 +809,6 @@ section == "branches" {
     # is a reflection, not the claim: git refs remain authoritative.
     claimed_of[n_branches] = claim_note
     ordered_b[n_branches] = b
-    line = substr(line, RSTART + RLENGTH)
   }
   line = $0
   # `→ #N` and `→ owner/repo#N` are both annotations: /plot-deliver instructs

package/plot-reap.sh

@@ -0,0 +1,286 @@
+#!/usr/bin/env bash
+# Remove worktrees whose work has landed, their dead worker files, and the
+# registry manifests that named them.
+#
+# The gap this fills was named by a comment before it existed:
+# `plot-reconcile-scan.sh:323` says "with a deferred: annotation the reaper
+# would offer to DELETE real work" — describing a reaper that was never
+# 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.
+#
+# DEFAULT IS --dry-run. Removal happens only under --yes.
+#
+#   plot-reap.sh                # report what WOULD be reaped
+#   plot-reap.sh --yes          # actually remove them
+#   plot-reap.sh --yes --max 5  # bound it
+#
+# What is NEVER reaped, in the order the tests run:
+#   1. a worktree with a LIVE worker process        (a desk someone is at)
+#   2. a worktree with uncommitted changes           (work that exists nowhere else)
+#   3. a worktree carrying a PLOT-BLOCKED* marker    (a worker waiting on a person)
+#   4. a branch NO PR of which merged                (the host is the authority)
+#   5. the main checkout, and any non-dispatch tree  (not ours to remove)
+#
+# THE MANIFEST GOES WITH THE WORKTREE. `readAgentRegistry` renders one row per
+# manifest, so a reap that removes only the checkout converts a finished agent
+# into an `unknown` row naming a directory that no longer exists — measured
+# 2026-08-26, twelve worktrees removed and seven such rows appearing at once.
+# Nothing further needs deciding to remove it: an entry whose worktree the five
+# tests above just cleared is covered by exactly those measurements.
+#
+# ORDER: worktree FIRST, manifest second. The reverse leaves a live worktree
+# with no registration, which `readAgentRegistry` answers by SYNTHESIZING an
+# `unknown` entry — the same bad row, earned a different way. A failure between
+# the two steps this way round leaves an orphaned manifest, which the sweep
+# below clears on the next run.
+set -u
+
+DRY=1; MAX=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --yes) DRY=0 ;;
+    --dry-run) DRY=1 ;;
+    --max) MAX="${2:-0}"; shift ;;
+    -h|--help) sed -n '2,42p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "plot-reap: unknown argument: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+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; }
+
+# The default branch, via the host adapter when it can answer and `main`
+# otherwise. A wrong answer here would only ever make the ancestry test MORE
+# conservative, never less.
+HOST="$(dirname "${BASH_SOURCE[0]}")/plot-host.sh"
+DEFAULT=main
+if [ -x "$HOST" ]; then
+  d=$("$HOST" default-branch 2>/dev/null) && [ -n "$d" ] && DEFAULT="$d"
+fi
+git fetch origin "$DEFAULT" --quiet 2>/dev/null || true
+
+# Does the host say ANY PR for this branch merged?
+#
+# SOURCED from `plot-pr-merged.sh` rather than defined here, since 2026-08-28.
+# It lived in this file until `plot-release-refs.sh` needed the SAME gate: both
+# scripts ask "has this branch's work landed", and a second implementation that
+# drifted toward permissive would delete a ref that cannot be restored. The
+# helper carries the reasoning — `mergedAt` never `state`, ANY PR never the
+# newest — and defines `pr_merged` and nothing else on load.
+. "$(dirname "${BASH_SOURCE[0]}")/plot-pr-merged.sh"
+
+# 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
+# they drift, so this asks the config rather than hard-coding `.plot/agents`: a
+# project whose board is served from another checkout points the key elsewhere,
+# and a reaper writing to the wrong directory would report success over a
+# manifest the board still renders.
+# Tested with -r, not -x: the helper is invoked through `bash "$CONFIG"`, which
+# needs the file READABLE and not executable. `-x` would silently fall back to
+# the default on a checkout whose exec bits did not survive — and a reaper
+# reading the wrong directory reports success over a manifest the board still
+# renders, which is exactly the failure #420 fixed on the board's own side.
+CONFIG="$(dirname "${BASH_SOURCE[0]}")/plot-config.sh"
+MANIFEST_DIR=".plot/agents"
+if [ -r "$CONFIG" ]; then
+  d=$(bash "$CONFIG" get "Agent registry" ".plot/agents" 2>/dev/null) && [ -n "$d" ] && MANIFEST_DIR="$d"
+fi
+case "$MANIFEST_DIR" in /*) ;; *) MANIFEST_DIR="$ROOT/$MANIFEST_DIR" ;; esac
+
+# The manifest naming a given worktree, or nothing.
+#
+# Manifests are keyed by SESSION id, not by branch, so the file cannot be
+# derived from the worktree path — it is found by reading the `worktree` field
+# out of each one. The match is on the exact recorded path: a prefix match would
+# let `plot-wt-foo` claim `plot-wt-foo-bar`'s manifest.
+#
+# Parsed with `sed`, not a JSON reader, deliberately — this script must run
+# where node does not, and the field it needs is one flat string written by the
+# dispatcher. A manifest whose `worktree` cannot be read simply does not match,
+# which keeps an unparseable file OUT of the removal set rather than in it.
+# A path with its symlinks resolved, or the path unchanged when it does not
+# exist (nothing to resolve, and the caller still needs a string to compare).
+#
+# NOT cosmetic. `git worktree list` reports RESOLVED paths, while a manifest
+# records whatever the dispatcher was handed — and on macOS `/tmp`, `/var` and
+# `/etc` are symlinks into `/private`, so the same directory arrives as two
+# different strings. Measured while writing this: a worktree git called
+# `/private/var/.../repo` against a manifest saying `/var/.../repo`, matching
+# nothing and stranding the manifest the reap was supposed to take.
+canonical() {
+  local p="$1"
+  [ -n "$p" ] || return 0
+  # Resolve through the filesystem while the directory is still there — the
+  # authoritative answer, and the only one that handles an arbitrary symlink.
+  if [ -d "$p" ]; then
+    p=$( (cd "$p" 2>/dev/null && pwd -P) || printf '%s' "$p" )
+  fi
+  # Then normalise the macOS `/private` prefix TEXTUALLY, because the manifest
+  # side is compared AFTER its directory has been removed and there is no
+  # longer anything to resolve. `/tmp`, `/var` and `/etc` are symlinks into
+  # `/private`, so git's `/private/var/...` and a manifest's `/var/...` name
+  # one directory; stripping the prefix from both makes them one string
+  # whether or not either still exists.
+  case "$p" in
+    /private/tmp/*|/private/var/*|/private/etc/*) p=${p#/private} ;;
+  esac
+  printf '%s\n' "$p"
+}
+
+manifest_for() {
+  local target="$1" f wt
+  [ -d "$MANIFEST_DIR" ] || return 1
+  target=$(canonical "$target")
+  for f in "$MANIFEST_DIR"/*.json; do
+    [ -f "$f" ] || continue
+    wt=$(sed -n 's/.*"worktree"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$f" | head -1)
+    [ -n "$wt" ] || continue
+    [ "$(canonical "$wt")" = "$target" ] && { printf '%s\n' "$f"; return 0; }
+  done
+  return 1
+}
+
+reap=0; kept=0; removed=0; cleared=0
+printf '%-8s %-52s %s\n' "verdict" "branch" "why"
+
+while IFS=$'\t' read -r wt br; do
+  [ -n "$wt" ] || continue
+  short=${br#refs/heads/}
+
+  # 5. Only dispatch trees. A hand-made worktree and the main checkout are not
+  #    this script's to remove, whatever state they are in.
+  case "$wt" in *"/plot-wt-"*) ;; *) continue ;; esac
+  [ "$wt" = "$ROOT" ] && continue
+
+  # 1. A live worker outranks every other signal. Checked FIRST because it is
+  #    the only one describing a person or process acting right now.
+  if [ -f "$wt/.plot-worker.pid" ]; then
+    pid=$(cat "$wt/.plot-worker.pid" 2>/dev/null)
+    if [ -n "$pid" ] && ps -p "$pid" >/dev/null 2>&1; then
+      printf '%-8s %-52s %s\n' "keep" "$short" "worker alive (pid $pid)"; kept=$((kept+1)); continue
+    fi
+  fi
+
+  # 3. A marker means a worker stopped to ask a person something. Reaping it
+  #    discards the question along with the tree.
+  if ls "$wt"/PLOT-BLOCKED* >/dev/null 2>&1; then
+    printf '%-8s %-52s %s\n' "keep" "$short" "PLOT-BLOCKED marker — needs a person"; kept=$((kept+1)); continue
+  fi
+
+  # 2. Uncommitted work exists in exactly one place. 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 still keeps the tree, which is what keeps this an exception
+  #    rather than a hole.
+  dirty=$(git -C "$wt" status --porcelain 2>/dev/null \
+            | grep -v 'tiny-garden/\.plot/state' | head -1)
+  if [ -n "$dirty" ]; then
+    printf '%-8s %-52s %s\n' "keep" "$short" "uncommitted: ${dirty:0:40}"; kept=$((kept+1)); continue
+  fi
+
+  # 4a. A tree sitting ON the default branch answers the ancestry test
+  #     trivially — `origin/main..main` is empty — and would be reaped with the
+  #     reason "merged into main", which says nothing about the work it was
+  #     dispatched for. Measured here 2026-08-25: one dispatch tree had been
+  #     left on `main` by its worker, and the first draft of this script
+  #     offered to reap it for a reason that was true and irrelevant.
+  #
+  #     It is KEPT and named. Deleting a tree whose dispatched branch is no
+  #     longer checked out means deleting something whose state was never
+  #     measured — and "probably fine" is the judgement this script exists to
+  #     not make.
+  if [ "$short" = "$DEFAULT" ]; then
+    printf '%-8s %-52s %s\n' "keep" "$short" "on $DEFAULT — dispatched branch not checked out"
+    kept=$((kept+1)); continue
+  fi
+
+  # 4b. Landed, by either route: ancestry for a merge commit, the host for a
+  #     squash. Ancestry is tried first because it needs no network.
+  why=""
+  if [ -n "$short" ] && [ "$(git -C "$wt" rev-list --count "origin/$DEFAULT..$short" 2>/dev/null || echo 1)" = "0" ]; then
+    why="merged into $DEFAULT"
+  elif [ -n "$short" ] && pr_merged "$short"; then
+    why="PR merged (squash)"
+  else
+    printf '%-8s %-52s %s\n' "keep" "$short" "unlanded work — no merged PR"; 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
+  fi
+
+  # Resolved BEFORE the removal, because `canonical` needs the directory to
+  # still exist to resolve it. After `git worktree remove` there is nothing to
+  # follow, and the manifest's spelling would never converge with git's.
+  wt_real=$(canonical "$wt")
+
+  reap=$((reap+1))
+  if [ "$DRY" -eq 1 ]; then
+    printf '%-8s %-52s %s\n' "would" "$short" "$why"
+  else
+    if git worktree remove --force "$wt" 2>/dev/null; then
+      # The worktree is gone; NOW the manifest may go. Inside the success arm
+      # and nowhere else — a manifest removed before a removal that then
+      # refuses leaves a live worktree unregistered, which the registry answers
+      # by synthesizing an `unknown` row. Failing this way round strands a
+      # manifest instead, which the sweep below clears.
+      if m=$(manifest_for "$wt_real"); then
+        rm -f "$m" && why="$why, manifest cleared"
+      fi
+      printf '%-8s %-52s %s\n' "reaped" "$short" "$why"; removed=$((removed+1))
+    else
+      printf '%-8s %-52s %s\n' "FAILED" "$short" "git worktree remove refused"; kept=$((kept+1))
+    fi
+  fi
+done < <(git worktree list --porcelain \
+          | awk '/^worktree /{p=$2} /^branch /{print p"\t"$2}')
+
+[ "$DRY" -eq 0 ] && git worktree prune 2>/dev/null
+
+# The manifests whose worktree is ALREADY gone.
+#
+# Every reap before this script learned about the registry left one, and the
+# board renders each as an `unknown` row naming a directory that does not
+# exist. They are the population this plan was written from — seven of them,
+# measured 2026-08-26 — and a fix that only stops NEW ones leaves those on the
+# board forever.
+#
+# The predicate is the same one the loop above satisfies by construction: the
+# recorded worktree is not there. It needs no PR check and no liveness check —
+# nothing runs in a directory that does not exist, which is the strongest
+# evidence of "dead" available, not the weakest.
+#
+# A manifest recording NO worktree path is left alone: it names an agent
+# between checkouts, and absence of a path is not absence of an agent.
+if [ -d "$MANIFEST_DIR" ]; then
+  for m in "$MANIFEST_DIR"/*.json; do
+    [ -f "$m" ] || continue
+    mwt=$(sed -n 's/.*"worktree"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$m" | head -1)
+    [ -n "$mwt" ] || continue
+    [ -d "$mwt" ] && continue
+    cleared=$((cleared+1))
+    if [ "$DRY" -eq 1 ]; then
+      printf '%-8s %-52s %s\n' "would" "$(basename "${mwt}")" "orphaned manifest — worktree absent"
+    else
+      rm -f "$m"
+      printf '%-8s %-52s %s\n' "cleared" "$(basename "${mwt}")" "orphaned manifest — worktree absent"
+    fi
+  done
+fi
+
+# The branches and refs are untouched, deliberately: this removes CHECKOUTS and
+# the registrations that named them. A reaped tree is re-creatable with
+# `git worktree add`, so the destructive act is bounded to disk space and to a
+# record of an agent that has already finished — never to history.
+echo "summary: reapable=$reap removed=$removed kept=$kept cleared=$cleared dry_run=$DRY"
+exit 0