@plot-pm/board 0.14.4 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
   "files": [
     "dist/board-server.mjs",
     "plot-agent-monitor.sh",
+    "plot-agent-manifest.sh",
     "plot-build-monitor.sh",
     "plot-monitor-subject.sh",
     "plot-approve.sh",

package/plot-agent-manifest.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Plot helper: the ONE writer that clears an agent manifest's `branch` field.
+#
+# SOURCED, NOT RUN — the shape `plot-worker-state.sh` and `plot-pr-merged.sh`
+# already take. Two scripts clear an assignment and must clear it one way:
+#
+#   - `plot-worker-loop.sh` clears its own manifest when a slice finishes, so
+#     the window before the next hand-over is observable as `branch: ""`;
+#   - `plot-dispatch.sh --release <branch>` clears every manifest naming an
+#     abandoned slice, beside deleting the claim ref.
+#
+# The function lived inside `plot-worker-loop.sh` until the second caller
+# arrived. The loop is a script, not a library, so sourcing it would run it; the
+# body moved here unchanged and the loop sources this file instead.
+#
+# Defines one function and does nothing else on load.
+
+# Clear `branch` when a slice finishes, so the window before the next one is
+# observable.
+#
+# WHY THIS EXISTS. `free = process alive AND manifest names no branch`, and the
+# second half was unreachable. `seal_declaration` runs the moment a branch is
+# done; `update_manifest_on_hop` runs after `--next` answers and a worktree is
+# built. Between those two points the agent genuinely holds no slice and the
+# manifest still named the last one, so `isFree`'s empty-branch arm — written,
+# exported and unit-tested since `a-dispatch-asks-for-a-free-agent` — had no
+# production caller that could ever satisfy it. Measured 2026-09-02: 2
+# manifests on this estate, neither ever carrying `branch: ""`.
+#
+# `branch` AND ONLY `branch`. `worktree` still names the desk the agent is
+# sitting at — it has not moved, and clearing it would take the transcript join
+# and the liveness check with it, since both are keyed on the worktree path.
+# `wavesCount` counts hops and no hop has happened yet. The node one-liner
+# round-trips the whole object, so every other field survives verbatim, the same
+# property `update_manifest_on_hop` records.
+#
+# ADDED, NOT SUBSTITUTED. The hop still rewrites `branch` and `worktree`
+# together; this writes the empty value that sits between two slices. A worker
+# that finishes its last branch exits with the manifest cleared and the exit
+# trap removes the file, so the empty value is never a leftover.
+#
+# ABSENT IS NOT A FAILURE. No manifest — a hand-started loop, an older
+# dispatcher — means there is nothing to clear and nothing to report, so this
+# returns 0 like `update_manifest_on_hop` does.
+clear_manifest_branch() { # $1=manifest
+  local manifest="$1"
+  [ -f "$manifest" ] || return 0
+
+  local tmp="$manifest.plot-free-tmp"
+  node -e '
+    const fs = require("fs");
+    const manifest = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+    manifest.branch = "";
+    fs.writeFileSync(process.argv[2], JSON.stringify(manifest, null, 2) + "\n");
+  ' "$manifest" "$tmp" 2>/dev/null || { rm -f "$tmp"; return 1; }
+
+  mv -f "$tmp" "$manifest" 2>/dev/null || { rm -f "$tmp"; return 1; }
+}

package/plot-approve.sh

@@ -227,7 +227,25 @@ else
   pr_branch="idea/$slug"
 fi
 
-pr_json=$(bash "$script_dir/plot-host.sh" pr-state "$pr_branch" 2>/dev/null) || pr_json=""
+# THE EXIT CODE IS THE READING, not the emptiness of stdout. `pr-state` exits 0
+# with `state: NONE` when the host answered that the branch has no PR, and
+# non-zero when the host could not be asked: 3 for a refused or failed call
+# (a rate limit included), 4 for a backend with no answer at all. Only the
+# first is an absence. The other two stop here with the host's own words and
+# name no repair to the branch, because nothing about the branch was read.
+pr_err_file=$(mktemp "${TMPDIR:-/tmp}/plot-approve-pr.XXXXXX")
+pr_rc=0
+pr_json=$(bash "$script_dir/plot-host.sh" pr-state "$pr_branch" 2>"$pr_err_file") || pr_rc=$?
+pr_err=$(cat "$pr_err_file" 2>/dev/null); rm -f "$pr_err_file"
+if [ "$pr_rc" = 4 ]; then
+  die "the host backend has no answer for the PR state of '$pr_branch' (plot-host.sh pr-state exited 4).
+  ${pr_err:-The host adapter gave no reason.}
+  This backend cannot report a PR's state, so the approval cannot read its gate. The plan was not approved and its phase is unchanged."
+elif [ "$pr_rc" != 0 ]; then
+  die "the host could not be asked for the PR of '$pr_branch' (plot-host.sh pr-state exited $pr_rc).
+  ${pr_err:-The host adapter gave no reason.}
+  The plan was not approved and its phase is unchanged. Wait for the host to answer again, then re-run the approval."
+fi
 [ -n "$pr_json" ] || pr_json='{"number":0,"state":"NONE","draft":false,"url":""}'
 pr_number=$(printf '%s' "$pr_json" | jq -r '.number // 0' 2>/dev/null)
 pr_state=$(printf '%s' "$pr_json" | jq -r '.state // "NONE"' 2>/dev/null)
@@ -420,6 +438,10 @@ append_approved_line() { # $1=in $2=out $3=record
       insert = start
       for (i = start + 1; i <= n; i++) {
         if (lines[i] ~ /^##[ \t]/) break
+        # An HTML comment ends the writable region. Checked BEFORE the
+        # placeholder arms so a commented-out `- **Approved:**` template line
+        # is never mistaken for the slot to fill.
+        if (lines[i] ~ /<!--/) break
         if (lines[i] ~ /^[ \t]*[-*][ \t]*\*\*Approved:\*\*[ \t]*$/) { slot = i; break }
         if (lines[i] ~ /^[ \t]*[-*][ \t]/) insert = i
       }

package/plot-config.sh

@@ -80,6 +80,13 @@
 #                       here can invoke a skill. Absent (or `none`) = the button
 #                       refuses and names this key as the fix, rather than
 #                       accepting the click and doing nothing.
+#   Interrogate command how the board runs `/plot-panel <plan path>` on a Draft
+#                       plan (the card's `Interrogate` button); the prompt is
+#                       appended as one argument and names a FILE the board
+#                       wrote. REQUIRED for the same reason as `Idea command`:
+#                       a panel fans out N agents reading a plan, and no script
+#                       can do that. Absent (or `none`) = the button renders
+#                       disabled and names this key as the fix.
 #   Brief command       how /plot-dispatch runs an agent headless to WRITE a
 #                       missing hand-off brief. The prompt is appended as one
 #                       argument and asks for `/plot-implement <slug>`, whose
@@ -95,6 +102,16 @@
 #   Hosts plans         yes | no                      (no = refuse plan files)
 #   Tracker             plot | jira | github-issues | linear  (+ URL)
 #                       (plot = plans in this repo ARE the tracker; absent = same)
+#   Tracker delivered status
+#                       the status word a plan's issues are set to when the plan
+#                       reaches Delivered, in the tracker's own vocabulary
+#                       (`In Review`, `Done`). Read by plot-issue-status.sh.
+#                       Absent or empty = Delivered writes nothing — never an
+#                       empty status, and never the released word instead.
+#   Tracker released status
+#                       the same for Released. A team whose *Done* means
+#                       *shipped* sets only this one; a team watching progress
+#                       sets both.
 #   Ticket prefixes     the tracker project keys this repository's work lives
 #                       in, comma-separated (`PROJ-A, PROJ-B`). NOT
 #                       `Branch prefixes`, which sits next to it and holds
@@ -142,7 +159,23 @@ if [ "$cmd" != "get" ]; then
   exit 1
 fi
 
-root=$(git rev-parse --show-toplevel 2>/dev/null) || root="."
+# THE CALLER'S ROOT IS TAKEN WHERE IT OFFERS ONE. `git rev-parse` is ~5 ms and
+# this script runs once per config key, so a caller reading several keys pays
+# for the same constant repeatedly. Measured on CI 2026-09-25: one board build
+# spawned `git rev-parse --show-toplevel` 21 times out of 42 git processes
+# total, which `plan-read-shape.test.mjs` caught as the spawn count crossing
+# its bound. The board already exports `PLOT_REPO_ROOT` (`index.ts:65`) and
+# `plot-deliver.sh` and `plot-issue-status.sh` already read it.
+#
+# IT MUST BE A DIRECTORY, and a wrong one falls back rather than failing: an
+# exported stale path would otherwise make every config read answer from a
+# repository that is not this one, silently. Asking git is the safe answer and
+# stays the default for every caller that offers nothing.
+if [ -n "${PLOT_REPO_ROOT:-}" ] && [ -d "$PLOT_REPO_ROOT" ]; then
+  root="$PLOT_REPO_ROOT"
+else
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || root="."
+fi
 
 # Find the first repo-root file that contains a ## Plot Config section.
 # CLAUDE.md wins for backwards compatibility; AGENTS.md is the modern fallback.

package/plot-deliver.sh

@@ -5,7 +5,10 @@
 #   --who       the name recorded in the `Delivered:` line (default: git user.name)
 #   <slug>      the plan to deliver
 # Output: one `step:` line per step, then a machine-countable summary:
-#             summary: phase=flipped record=written index=moved sprint=updated push=clean
+#             summary: phase=flipped record=written index=moved sprint=updated push=clean tracker=none
+#         `tracker=` is plot-issue-status.sh's outcome (none|written|no-target|
+#         unaskable|failed), or `skipped` when the push was rejected. It never
+#         changes the exit code: a failed status write is reported, not raised.
 #         Exit 0 when the plan is Delivered on the default branch (whether this
 #         run did the work or found it already done); 1 on a refusal or a
 #         failure, with the reason on stderr.
@@ -654,6 +657,12 @@ git -C "$tmpwt" add -- "${ACTIVE_DIR#/}" >/dev/null 2>&1 || true
 git -C "$tmpwt" add -- "${DELIVERED_DIR#/}" >/dev/null 2>&1 || true
 [ "$sprint_report" = "updated" ] && git -C "$tmpwt" add -- "${SPRINT_DIR#/}" >/dev/null 2>&1
 
+# THE BOOKED PLAN, KEPT FOR THE TRACKER. The booking worktree is removed on
+# every exit below, and the working tree may still read `Approved`; the issue
+# status is decided from the file that reached the default branch.
+booked_plan=$(mktemp "${TMPDIR:-/tmp}/plot-deliver-plan.XXXXXX")
+cp "$tmpwt/$rel" "$booked_plan" 2>/dev/null || : > "$booked_plan"
+
 if git -C "$tmpwt" diff --cached --quiet 2>/dev/null; then
   # THE IDEMPOTENT EXIT. Everything this run would have written was already
   # on the default branch, so there is nothing to push and nothing wrong.
@@ -694,13 +703,25 @@ else
       echo "plot-deliver: the delivery is committed on '$bookbr' but could not reach $MAIN." >&2
       echo "  Land '$bookbr' by hand, or re-run this command once the push works." >&2
       git worktree remove --force "$tmpwt" >/dev/null 2>&1 || true
-      echo "summary: phase=$phase_report record=$record_report index=$index_report sprint=$sprint_report push=$push_report"
+      rm -f "$booked_plan"
+      # NOTHING REACHED THE DEFAULT BRANCH, so no status is owed yet.
+      echo "summary: phase=$phase_report record=$record_report index=$index_report sprint=$sprint_report push=$push_report tracker=skipped"
       exit 1
     fi
   fi
 fi
 
-echo "summary: phase=$phase_report record=$record_report index=$index_report sprint=$sprint_report push=$push_report"
+# THE TRACKER HEARS AFTER THE DELIVERY LANDED, and never decides it. The plan is
+# delivered; the tracker holds a copy of one fact about it. Every outcome of
+# plot-issue-status.sh, a failed write and an unreadable bundle included, is a
+# report on the summary line and leaves this script's exit code alone.
+tracker_out=$(bash "$script_dir/plot-issue-status.sh" "$booked_plan" 2>&1)
+printf '%s\n' "$tracker_out" | grep -v '^summary: ' | sed '/^$/d; s/^/  tracker: /'
+tracker_report=$(printf '%s' "$tracker_out" | sed -n 's/^summary: tracker=\([a-z-]*\).*/\1/p' | tail -1)
+[ -n "$tracker_report" ] || tracker_report="failed"
+rm -f "$booked_plan"
+
+echo "summary: phase=$phase_report record=$record_report index=$index_report sprint=$sprint_report push=$push_report tracker=$tracker_report"
 # THE RECEIPT IS SPENT HERE, on the action COMPLETING — never at the gate.
 # `plot-controller-gate.sh` clears on a receipt and LEAVES it, so an
 # interrupted run can be repeated on the same licence: this script documents

package/plot-dispatch.sh

@@ -4,6 +4,7 @@
 #                         [--max N] [--allow-local] <slug>
 #        plot-dispatch.sh --start [N] [--dry-run]
 #        plot-dispatch.sh --migrate [--yes] [--max N]
+#        plot-dispatch.sh --release <branch>
 #   --status    list fleet worktrees with worker pid, liveness, and last log
 #               line; then exit. Works regardless of plan phase.
 #   --stop <br> stop the worker on <br> (branch required — never "all").
@@ -23,6 +24,18 @@
 #               word), on a live worker, and on a PLOT-BLOCKED marker. The
 #               worktree is inherited exactly as it stands — uncommitted work
 #               is what a stall leaves behind, and this must not destroy it.
+#   --release <br>
+#               return an ABANDONED slice to the queue: clear the `branch` of
+#               every agent manifest naming <br>, then delete the claim ref
+#               origin/<br>. --stop ends a worker and KEEPS the claim, because
+#               stopping is not abandoning; --release is the act that gives the
+#               slice up. Deleting the ref by hand is not the same act: the
+#               manifest still names the branch. Branch required. Refuses on a
+#               PR (open or merged), a host it cannot ask, a live worker (named
+#               by pid), real work (a file-changing commit on origin/<br>, or
+#               unpushed commits or uncommitted changes on the local desk), and
+#               a PLOT-BLOCKED marker. A refusal writes nothing. The desk is
+#               never touched.
 #   --migrate   move legacy worktrees into the configured `Worktree root:`. An
 #               idle worktree (no live worker, no unlanded work) is moved; a
 #               busy one is skipped with the reason. Requires a `Worktree root:`
@@ -145,8 +158,10 @@
 #     think they won. Git is the lock only when the refs actually diverge.
 #   - Worktrees are adopted, never duplicated. A dispatcher that dies halfway
 #     through a fan-out is safe to re-run.
-#   - Nothing is ever deleted. Cleanup belongs to /plot-reconcile, which can
-#     tell a deliberately abandoned claim from a dead worker.
+#   - A fan-out deletes nothing. Cleanup belongs to /plot-reconcile, which can
+#     tell a deliberately abandoned claim from a dead worker. The one deletion
+#     here is `--release <branch>`, which a person runs after making that call,
+#     and which refuses wherever the claim is not abandoned.
 #   - The `Started:` record is booked on the DEFAULT BRANCH, after the claims,
 #     and only for branches this run newly claimed. A re-run books nothing it
 #     merely re-adopted. If the booking cannot be pushed, the fan-out stands
@@ -191,6 +206,12 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # shellcheck source=plot-default-branch.sh
 . "$script_dir/plot-default-branch.sh"
 
+# The ONE writer of a manifest's empty `branch` — `clear_manifest_branch`,
+# shared with `plot-worker-loop.sh`. `--release` clears an abandoned slice's
+# assignment with it rather than with a second writer.
+# shellcheck source=plot-agent-manifest.sh
+. "$script_dir/plot-agent-manifest.sh"
+
 # ---------------------------------------------------------------------------
 # WHERE THE WORKTREES LIVE, and by what name
 # ---------------------------------------------------------------------------
@@ -239,6 +260,7 @@ no_brief=0
 mode=dispatch
 stop_branch=""
 restart_branch=""
+release_branch=""
 # EMPTY MEANS "THE DEFAULT", AND THE DEFAULT IS THE RULE'S. `fleetSize` owns the
 # number and the argument for it; a literal here would be a second copy of a
 # decision that has one home. It is filled from the rule below.
@@ -275,6 +297,9 @@ while [ $# -gt 0 ]; do
     # plan for feature/x", which describes neither what was asked nor what
     # went wrong. The branch is consumed only when it looks like one.
     --restart)  mode=restart; case "${2:-}" in */*) restart_branch="$2"; shift ;; esac ;;
+    # The same rule once more: a bare `--release <slug>` must not delete a ref
+    # named after a plan slug.
+    --release)  mode=release; case "${2:-}" in */*) release_branch="$2"; shift ;; esac ;;
     # `--start [N]` brings FREE agents into existence — registered, waiting, and
     # holding no slice. The count is OPTIONAL and only a bare number is consumed,
     # the same rule `--stop` and `--restart` apply to a branch: a value that does
@@ -312,10 +337,11 @@ while [ $# -gt 0 ]; do
                 shift ;;
     # THE RANGE MOVED WITH THE HEADER IT PRINTS. It ended at `<slug>` and still
     # does; adding `--agent` above pushed that line from 59 to 69, and
-    # documenting the plan-declared kind pushed it from 69 to 78. Two records
+    # documenting the plan-declared kind pushed it from 69 to 78, and
+    # `--release` pushed it from 78 to 91. Two records
     # of one fact, and nothing compares them — a stale number here silently
     # truncates the help rather than failing, so it is checked by a test.
-    -h|--help)  sed -n '2,78p' "$0"; exit 0 ;;
+    -h|--help)  sed -n '2,91p' "$0"; exit 0 ;;
     *)          slug="$1" ;;
   esac
   shift
@@ -428,6 +454,23 @@ json_escape() {
 #
 # Written to a temp file and moved into place, so a scan reading the directory
 # never sees a half-written manifest. `mv` within one directory is atomic.
+# The directory the `Agent registry` key names, resolved against a repo root.
+#
+# The case split is `resolve_wt_root`'s: absolute taken as given, relative
+# joined onto the repo root, trailing slash trimmed as pure string work because
+# the directory need not exist yet. One resolver, read by `start_worker` when it
+# writes a manifest and by `--release` when it clears one, so the two cannot
+# look in different places.
+agent_registry_dir() { # $1=repo_root → prints the directory
+  local dir
+  dir=$("$script_dir/plot-config.sh" get "Agent registry" ".plot/agents")
+  case "$dir" in
+    /*) ;;
+    *)  dir="$1/$dir" ;;
+  esac
+  printf '%s' "${dir%/}"
+}
+
 write_agent_manifest() { # $1=path $2=session $3=branch $4=worktree $5=command
   local out="$1" tmp="$1.plot-tmp"
   {
@@ -1119,12 +1162,7 @@ start_worker() {
   # resolving a configured directory is a second way to be wrong.
   local session manifest_dir
   session=$(plot_session_id)
-  manifest_dir=$("$script_dir/plot-config.sh" get "Agent registry" ".plot/agents")
-  case "$manifest_dir" in
-    /*) ;;
-    *)  manifest_dir="$repo_root/$manifest_dir" ;;
-  esac
-  manifest_dir="${manifest_dir%/}"
+  manifest_dir=$(agent_registry_dir "$repo_root")
   mkdir -p "$manifest_dir" 2>/dev/null || true
   # `printf` per field with no interpretation: a command containing quotes,
   # newlines or backslashes must survive into valid JSON, and this is the one
@@ -1171,8 +1209,9 @@ start_worker() {
     echo "    refusing to start $branch — its agent manifest could not be written:"
     echo "      $manifest_dir/$session.json"
     echo "      An unregistered worker cannot be seen, stopped or reaped, and holds"
-    echo "      a claim nobody can release. The worktree and claim are untouched —"
-    echo "      fix the path above (see the 'Agent registry' key) and dispatch again."
+    echo "      a claim only 'plot-dispatch.sh --release $branch' can give up. The worktree"
+    echo "      and claim are untouched — fix the path above (see the 'Agent registry'"
+    echo "      key) and dispatch again."
     return 1
   fi
   # TWO PIDS, TWO NAMES. `.plot-worker.pid` must name the AGENT — the process
@@ -1699,7 +1738,8 @@ if [ "$mode" = "stop" ]; then
              exit 1; }
       # The worktree and its claim are left in place: the branch is still taken,
       # and deleting either would be the kind of write this design avoids.
-      echo "  worktree kept at $wt — the claim stands until you release it"
+      echo "  worktree kept at $wt — the claim stands until you release it:"
+      echo "    plot-dispatch.sh --release $stop_branch"
       ;;
     finished*|waiting*|stalled*|failed*|ended*) echo "$stop_branch is not running ($st)" ;;
     *)      echo "$stop_branch has no worker" ;;
@@ -1807,6 +1847,232 @@ if [ "$mode" = "restart" ]; then
   exit 0
 fi
 
+if [ "$mode" = "release" ]; then
+  # THE COUNTERPART TO --stop THAT NOBODY WROTE. `--stop` ends a worker and
+  # keeps the claim, because stopping is not abandoning. This is the act that
+  # gives an abandoned slice back to the queue.
+  #
+  # THE ASSIGNMENT HAS TWO RECORDS, and this clears both. The remote claim ref
+  # is what the scan and the registry's queue read as *somebody took this*; the
+  # agent manifest's `branch` field is what the registry wrote when it handed
+  # the slice over. Deleting only the ref — the repair `plot-reap.sh` and
+  # `plot-reconcile-scan.sh` leave to a person — leaves the manifest naming a
+  # slice the queue now offers to somebody else. Measured 2026-09-26:
+  # `feature/the-board-filters-to-my-work` was handed out twice after exactly
+  # that hand repair, and the second agent abandoned a desk with unpushed work.
+  #
+  # BEFORE THE PHASE GATE, beside --stop and --restart: a claimed branch is
+  # work in flight whatever the plan's phase now says.
+  if [ -z "$release_branch" ]; then
+    echo "plot-dispatch: --release needs a branch name, e.g. --release feature/x" >&2
+    echo "  A slug is not enough: which claim is abandoned is your call, and" >&2
+    echo "  a release deletes a ref that cannot be re-created." >&2
+    exit 1
+  fi
+  br="$release_branch"
+  MAIN=$(bash "$script_dir/plot-config.sh" get "Main branch")
+  [ -n "$MAIN" ] || MAIN=$(default_branch)
+  if [ -z "$MAIN" ]; then
+    echo "plot-dispatch: cannot resolve the default branch — refusing to release $br." >&2
+    echo "  Nothing was written." >&2
+    exit 1
+  fi
+
+  # THE REMOTE IS READ FRESH. A stale remote-tracking ref would hide commits a
+  # worker pushed since the last fetch, and those are the real work this must
+  # refuse on. A fetch that fails is a remote this cannot read.
+  if ! git fetch -q --prune origin </dev/null 2>/dev/null; then
+    echo "plot-dispatch: cannot fetch origin — refusing to release $br." >&2
+    echo "  Without a fresh reading this cannot tell a claim from pushed work." >&2
+    echo "  Nothing was written." >&2
+    exit 1
+  fi
+  ref_present=0
+  git rev-parse -q --verify "refs/remotes/origin/$br" >/dev/null 2>&1 && ref_present=1
+
+  # 1. A PULL REQUEST, ASKED FIRST — `handover_refusal`'s order and for its
+  # reason: a worker's exit state says nothing about whether its work reached
+  # review. A merged branch's ref belongs to `plot-release-refs.sh`; an open
+  # one is work under review.
+  #
+  # UNREACHABLE IS NOT "NO PR". `reached_review` reads a failed call as no PR,
+  # which is right for a rendering and wrong here: a deleted ref cannot be
+  # re-created, so a host that cannot be asked refuses. `--offline` promises no
+  # host call, so it refuses too.
+  if [ -n "$offline" ]; then
+    echo "plot-dispatch: --release asks the host whether $br has a PR, and --offline forbids that — refusing." >&2
+    echo "  Nothing was written." >&2
+    exit 1
+  fi
+  if ! pr_json=$("$script_dir/plot-host.sh" pr-state "$br" </dev/null 2>/dev/null); then
+    echo "plot-dispatch: the host could not be asked whether $br has a PR — refusing." >&2
+    echo "  A release deletes a ref that cannot be re-created, so silence is not" >&2
+    echo "  permission. Check the host (plot-host.sh pr-state $br) and retry." >&2
+    echo "  Nothing was written." >&2
+    exit 1
+  fi
+  pr_state=$(printf '%s' "$pr_json" | sed -n 's/.*"state":"\([A-Z]*\)".*/\1/p')
+  pr_num=$(printf '%s' "$pr_json" | sed -n 's/.*"number":\([0-9]*\).*/\1/p')
+  # ANY MERGED PR, NOT ONLY THE NEWEST — `pr-merged` reads `mergedAt` over every
+  # PR for the branch, because a newer unmerged PR can mask a merged one.
+  merged_answer=$("$script_dir/plot-host.sh" pr-merged "$br" </dev/null 2>/dev/null) || merged_answer=unknown
+  case "$pr_state:$merged_answer" in
+    OPEN:*|MERGED:*|*:merged)
+      echo "plot-dispatch: $br has a pull request (#${pr_num:-?}, ${pr_state:-MERGED}) — refusing." >&2
+      echo "  An open PR is work under review; a merged branch's ref is released by" >&2
+      echo "  plot-release-refs.sh when its plan is delivered. Nothing was written." >&2
+      exit 1
+      ;;
+    *:unknown|*:)
+      echo "plot-dispatch: the host could not say whether $br ever merged — refusing." >&2
+      echo "  Check it (plot-host.sh pr-merged $br) and retry. Nothing was written." >&2
+      exit 1
+      ;;
+  esac
+
+  # THE DESK, ASKED OF GIT — never rebuilt from the branch name, the rule every
+  # other verb here follows. A manifest naming this branch may name a desk git
+  # does not list (removed by hand), so its `worktree` is the fallback.
+  release_wt=$(git worktree list --porcelain </dev/null 2>/dev/null | awk -v want="refs/heads/$br" '
+    /^worktree /  { path = substr($0, 10) }
+    /^branch /    { if (substr($0, 8) == want) { print path; exit } }')
+  registry_dir=$(agent_registry_dir "$repo_root_early")
+  named_manifests=()
+  if [ -d "$registry_dir" ]; then
+    for m in "$registry_dir"/*.json; do
+      [ -f "$m" ] || continue
+      m_branch=$(node -e '
+        try {
+          const m = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+          process.stdout.write(typeof m.branch === "string" ? m.branch : "");
+        } catch { process.stdout.write(""); }
+      ' "$m" 2>/dev/null)
+      [ "$m_branch" = "$br" ] || continue
+      named_manifests+=("$m")
+      if [ -z "$release_wt" ]; then
+        m_wt=$(node -e '
+          try {
+            const m = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+            process.stdout.write(typeof m.worktree === "string" ? m.worktree : "");
+          } catch { process.stdout.write(""); }
+        ' "$m" 2>/dev/null)
+        [ -n "$m_wt" ] && [ -d "$m_wt" ] && release_wt="$m_wt"
+      fi
+    done
+  fi
+  [ -n "$release_wt" ] && [ -d "$release_wt" ] || release_wt=""
+
+  # 2. A LIVE WORKER — the measurement `--restart` makes, through the shared
+  # classifier, never `pgrep` by name. A live pid means somebody is working,
+  # and the one case where a claim is not abandoned.
+  if [ -n "$release_wt" ]; then
+    release_state=$(plot_worker_state "$release_wt" "" | cut -f1,2)
+    case "$release_state" in
+      running*)
+        echo "plot-dispatch: a worker is alive on $br (pid $(printf '%s' "$release_state" | cut -f2)) — refusing." >&2
+        echo "  A live worker has not abandoned its claim. Stop it first if you mean to:" >&2
+        echo "    plot-dispatch.sh --stop $br" >&2
+        echo "  Nothing was written." >&2
+        exit 1
+        ;;
+    esac
+  fi
+
+  # 3. REAL WORK. A claim is an EMPTY commit on the default branch's tip, so
+  # it changes no file; `-- .` limits the count to commits that change one,
+  # which is what separates a claim-only ref from pushed work. The local desk
+  # is asked too, because the measured victim held its work in UNPUSHED
+  # commits and uncommitted files that no remote reading can see. A count of
+  # commits, not an ancestry verdict: a count above zero only ever REFUSES.
+  if [ "$ref_present" = 1 ]; then
+    remote_work=$(git rev-list --count "refs/remotes/origin/$MAIN..refs/remotes/origin/$br" -- . </dev/null 2>/dev/null) || remote_work=""
+    if [ -z "$remote_work" ]; then
+      echo "plot-dispatch: cannot count the commits on origin/$br — refusing." >&2
+      echo "  Nothing was written." >&2
+      exit 1
+    fi
+    if [ "$remote_work" -gt 0 ]; then
+      echo "plot-dispatch: origin/$br carries $remote_work commit(s) that change files — refusing." >&2
+      echo "  That is work, not an abandoned claim. Review it, or open its PR:" >&2
+      echo "    plot-open-pr.sh $br" >&2
+      echo "  Nothing was written." >&2
+      exit 1
+    fi
+  fi
+  if [ -n "$release_wt" ]; then
+    desk_dirty=$(plot_worker_dirty "$release_wt")
+    if [ "$ref_present" = 1 ]; then desk_base="refs/remotes/origin/$br"; else desk_base="refs/remotes/origin/$MAIN"; fi
+    # Local commits the remote lacks exist nowhere else, so any refuses.
+    desk_unpushed=$(git -C "$release_wt" rev-list --count "$desk_base..HEAD" -- . </dev/null 2>/dev/null) || desk_unpushed=0
+    if [ -n "$desk_dirty" ] || [ "${desk_unpushed:-0}" -gt 0 ]; then
+      echo "plot-dispatch: the desk at $release_wt holds work for $br — refusing." >&2
+      [ "${desk_unpushed:-0}" -gt 0 ] && echo "  $desk_unpushed unpushed commit(s) that change files" >&2
+      [ -n "$desk_dirty" ] && echo "  uncommitted changes: $(printf '%s' "$desk_dirty" | tr '\n' ' ')" >&2
+      echo "  Releasing would hand the slice to an agent that cannot see this work." >&2
+      echo "  Push it, or hand the branch to a new worker: plot-dispatch.sh --restart $br" >&2
+      echo "  Nothing was written." >&2
+      exit 1
+    fi
+
+    # 4. A PLOT-BLOCKED MARKER: the agent is waiting on a person, and a slice
+    # waiting on an answer is not abandoned. Asked through
+    # `plot_worker_blocked_file`, where the marker's spelling lives.
+    if marker=$(plot_worker_blocked_file "$release_wt") && [ -n "$marker" ]; then
+      echo "plot-dispatch: $br is blocked on a question — refusing." >&2
+      echo "  the question is in $release_wt/$marker" >&2
+      echo "  Answer it and delete the marker; the agent's slice is not abandoned." >&2
+      echo "  Nothing was written." >&2
+      exit 1
+    fi
+  fi
+
+  if [ "$ref_present" = 0 ] && [ "${#named_manifests[@]}" -eq 0 ]; then
+    echo "$br holds no claim: origin/$br does not exist and no manifest names it."
+    echo "  Nothing to release."
+    exit 0
+  fi
+
+  # THE MANIFESTS FIRST, THEN THE REF. If the ref deletion fails, the manifest
+  # is already free and the ref still locks, so the scan still reads the slice
+  # as claimed and nothing hands it out twice. The reverse order would leave the
+  # measured failure on disk: no ref, and a manifest still naming the branch.
+  released_manifests=0
+  if [ "${#named_manifests[@]}" -eq 0 ]; then
+    echo "  no manifest in $registry_dir names $br"
+  fi
+  for m in ${named_manifests[@]+"${named_manifests[@]}"}; do
+    if ! clear_manifest_branch "$m"; then
+      echo "plot-dispatch: could not clear the assignment in $m — refusing to delete the ref." >&2
+      echo "  The claim on origin/$br stands; fix the file and run --release again." >&2
+      exit 1
+    fi
+    released_manifests=$((released_manifests + 1))
+    echo "  cleared the assignment in $m"
+  done
+
+  if [ "$ref_present" = 1 ]; then
+    if ! git push -q origin --delete "$br" </dev/null 2>/dev/null; then
+      # VERIFIED, NOT TRUSTED: the host has returned 503 on a push that landed.
+      git fetch -q --prune origin </dev/null 2>/dev/null || true
+      if git rev-parse -q --verify "refs/remotes/origin/$br" >/dev/null 2>&1; then
+        echo "plot-dispatch: could not delete origin/$br — the claim still locks the slice." >&2
+        echo "  The manifests are already free, so nothing hands it out twice. Retry:" >&2
+        echo "    plot-dispatch.sh --release $br" >&2
+        exit 1
+      fi
+    fi
+    echo "  deleted the claim ref origin/$br"
+  else
+    echo "  origin/$br does not exist — only the assignment needed releasing"
+  fi
+  if [ -n "$release_wt" ]; then
+    echo "  the desk at $release_wt still holds $br and is left as it is"
+  fi
+  echo "released $br — the slice returns to the queue"
+  echo "summary: released=1 manifests=$released_manifests ref=$([ "$ref_present" = 1 ] && echo deleted || echo absent)"
+  exit 0
+fi
+
 if [ "$mode" = "start" ]; then
   # THE LAST LINK IN THE CHAIN. `plot-dispatch.sh <slug>` queues slices and the
   # registry matches them to free agents, but until this verb existed nothing
@@ -3063,6 +3329,10 @@ append_started_line() { # $1=file $2=date $3=who $4=branch
       insert = start
       for (i = start + 1; i <= n; i++) {
         if (lines[i] ~ /^##[ \t]/) break
+        # An HTML comment ends the writable region. Checked BEFORE the
+        # placeholder arms so a commented-out `- **Started:**` template line
+        # is never mistaken for the slot to fill.
+        if (lines[i] ~ /<!--/) break
         if (lines[i] ~ /^[ \t]*[-*][ \t]*\*\*Started:\*\*[ \t]*$/) { slot = i; break }
         if (lines[i] ~ /^[ \t]*[-*][ \t]/) insert = i
       }