@plot-pm/board 0.14.4 → 0.16.0

package/plot-config.sh

@@ -39,7 +39,11 @@
 #                       Non-numeric or empty falls back to the default. It bounds
 #                       a HUNG agent — one whose CLI crashed without exiting — so
 #                       one dead worker cannot hold a slot for hours.
-#   Agent registry      the directory the dispatcher writes agent manifests to,
+#   Temp sweep after    hours before `plot-reap.sh --sweep-temp` removes an
+#                       owned `$TMPDIR/plot-*` entry or a dead pid's budget
+#                       memo that a SIGKILL left behind. Default 24; a value
+#                       that is not a whole number is refused by the sweep.
+#   Agent registry     the directory the dispatcher writes agent manifests to,
 #                       read by the board's registry. Default `.plot/agents`
 #                       (repo-relative, gitignored, hence per-worktree). A board
 #                       served from a worktree the dispatcher never wrote to
@@ -48,6 +52,53 @@
 #                       the board finds the registry wherever it was started.
 #                       Absent = the default, so a single-checkout project is
 #                       unaffected.
+#   Board artifact      the board-server.mjs this repository runs, read by
+#                       plot-board-probe.sh. Declared, it is resolved FIRST and
+#                       reported as `artifact_source: checkout`; absent, the
+#                       order stays plugin, npm, checkout — the adopting
+#                       project's case, unchanged. It exists because a
+#                       repository that BUILDS the artifact must run the one it
+#                       built: without it `pnpm build:board` writes a file the
+#                       board never reads whenever a plugin is installed, and
+#                       the symptom looks like the fix not working.
+#                       A relative value resolves against the MAIN CHECKOUT (the
+#                       parent of `--git-common-dir`), never `--show-toplevel`,
+#                       so a dispatch desk resolves the same file rather than
+#                       its own copy; an absolute one is taken as given.
+#                       A declared file that is missing reports `none` and does
+#                       NOT fall back to the plugin — the key names which
+#                       artifact runs, so a silent substitution is the wrong
+#                       answer it removes. Absent = today's order.
+#   Agent settings      a JSON settings file every `claude -p` the fleet starts
+#                       is given, through `--settings`. It names the plugins this
+#                       project's agents start WITHOUT. Every dispatched agent
+#                       inherits every `SessionStart` hook the operator's plugins
+#                       declare, and the fleet starts a session on every worker
+#                       start, restart, retry and hop plus every agent-runner
+#                       command the board runs: measured 2026-09-30, one plugin's
+#                       lockless sync ran three times at once, the 1-minute load
+#                       reached 195, and the supervisor did not tick for 12
+#                       minutes.
+#                       Resolved by `plot-agent-settings.sh`, which prints an
+#                       absolute path (exit 0), nothing for an absent or empty key
+#                       (exit 0), or nothing with the reason on stderr (exit 3)
+#                       for a missing, unparseable or gate-disabling file. A
+#                       relative value resolves against the MAIN CHECKOUT (the
+#                       parent of `--git-common-dir`), never `--show-toplevel`,
+#                       for `Board artifact`'s reason: a desk must resolve the
+#                       same file, and one cut from an older main may not hold it.
+#                       The path travels to every consumer as
+#                       `PLOT_AGENT_SETTINGS`, and each command key interpolates
+#                       `${PLOT_AGENT_SETTINGS:+--settings "$PLOT_AGENT_SETTINGS"}`
+#                       itself — Plot rewrites no configured command.
+#                       A file setting any `plot@…` plugin false, `disableAllHooks`
+#                       true, or ANY `env` key is REFUSED: those switch Plot's own
+#                       four gates off, and a settings `PATH` hiding the gates'
+#                       tools makes them fail open. It is a check against an
+#                       accidental switch-off, not a boundary — the file is
+#                       project-owned and reviewed like this one.
+#                       Absent or empty = no change, so an adopting project that
+#                       sets nothing behaves exactly as today.
 #   Worktree root       where /plot-dispatch creates fleet worktrees. A relative
 #                       value resolves against the repo root, an absolute one is
 #                       taken as given. Absent = the default `repo_root/..` with
@@ -80,6 +131,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 +153,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 +210,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.
@@ -48,6 +51,7 @@
 set -uo pipefail
 
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+. "$script_dir/plot-tmp.sh"
 
 # The receipt this script leaves for plot-state-gate.sh, which refuses every
 # other writer of a `State:` line. Sourced rather than run: the gate and the
@@ -654,6 +658,13 @@ 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=""
+plot_tmpfile booked_plan deliver-plan
+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 +705,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
@@ -163,6 +178,7 @@
 set -uo pipefail
 
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+. "$script_dir/plot-tmp.sh"
 
 # The shared worker classifier. Sourced by both this script and
 # plot-fleet-scan.sh so a worker has ONE state, not one per reader.
@@ -191,6 +207,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 +261,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 +298,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 +338,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
@@ -366,28 +393,9 @@ fi
 # until this moved. Nothing here executes at definition time; only the position
 # changed.
 
-# A session id, in the shape the runtime uses for its transcript filename.
-#
-# `uuidgen` where it exists (macOS and most Linux), falling back to `/dev/urandom`
-# — never to `$RANDOM` or a timestamp. Two workers launched in the same second by
-# the same fan-out would collide on either, and a collision here silently merges
-# two agents into one manifest.
-#
-# Lowercased because the runtime writes its transcript filename in lowercase and
-# the board joins on exact string equality; `uuidgen` on macOS returns uppercase.
-plot_session_id() {
-  local id=""
-  if command -v uuidgen >/dev/null 2>&1; then
-    id=$(uuidgen 2>/dev/null | tr 'A-Z' 'a-z')
-  fi
-  if [ -z "$id" ]; then
-    # 16 random bytes rendered as a v4-shaped id. The shape matters only for
-    # recognisability; nothing parses it.
-    id=$(od -An -tx1 -N16 /dev/urandom 2>/dev/null | tr -d ' \n' \
-         | sed -E 's/(.{8})(.{4})(.{4})(.{4})(.{12})/\1-\2-\3-\4-\5/')
-  fi
-  printf '%s' "$id"
-}
+# `plot_session_id` — the session id a launch records — is SOURCED from
+# `plot-agent-manifest.sh` above, because the worker loop mints one on a hop to
+# a new branch and two generators of one id drift.
 
 # JSON-escape one string for a manifest value.
 #
@@ -428,6 +436,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"
   {
@@ -763,8 +788,20 @@ request_brief() { # $1 = branch, $2 = slug → 0 if a command was started
   # this outlives the dispatch run by design, because the fan-out must not block
   # on a `claude -p` session of unknown length. `setsid` is not used — it does
   # not exist on macOS, where most of this fleet runs.
+  # THE SETTINGS FILE THIS PROJECT STARTS ITS AGENTS WITH. The `Brief command` is
+  # a `claude -p` session like any other agent and inherits every `SessionStart`
+  # hook the operator's plugins declare, so it carries the same variable the
+  # worker loop exports — and the configured command interpolates
+  # `${PLOT_AGENT_SETTINGS:+--settings "$PLOT_AGENT_SETTINGS"}` itself.
+  #
+  # SET INLINE rather than exported, because this spawn already names its
+  # environment on the command line. A refusal or an absent key leaves it EMPTY,
+  # which `${VAR:+…}` reads as nothing — so a broken config cannot stop a brief
+  # being written.
+  _brief_settings="$(bash "$(dirname "${BASH_SOURCE[0]}")/plot-agent-settings.sh" 2>/dev/null || echo "")"
   ( cd "$repo_root" \
     && PLOT_UNATTENDED=1 PLOT_PLAN_SLUG="$bslug" PLOT_BRIEF_BRANCH="$branch" \
+       PLOT_AGENT_SETTINGS="$_brief_settings" \
        nohup sh -c "$cmd \"\$@\"" plot-brief \
        "$(brief_prompt "$branch" "$bslug")" \
        >"$log" 2>&1 </dev/null & ) 2>/dev/null
@@ -1119,12 +1156,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 +1203,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 +1732,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 +1841,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
@@ -2393,18 +2653,18 @@ fi
 # materialised into a temp file rather than parsed here — the parser stays the
 # one place that knows what a plan file looks like.
 #
-# The template's X's must TRAIL: BSD mktemp (macOS) rejects a template with a
-# suffix after them, while GNU accepts it. The first version wrote
-# `plot-gate-XXXXXX.md` and failed on macOS — and because the failure fell back
-# to the working tree, the gate silently went back to reading the exact surface
-# this fix exists to stop reading. Hence also: NO working-tree fallback below.
-# If the shared blob cannot be materialised, the gate refuses.
+# `plot-tmp.sh` puts the template's X's last: BSD mktemp (macOS) rejects a
+# template with a suffix after them, while GNU accepts it. The first version
+# wrote `plot-gate-XXXXXX.md` and failed on macOS — and because the failure fell
+# back to the working tree, the gate silently went back to reading the exact
+# surface this fix exists to stop reading. Hence also: NO working-tree fallback
+# below. If the shared blob cannot be materialised, the gate refuses.
 plan_file="$plan_path"
 gate_blob=""
 if [ -n "$gate_sha" ]; then
-  gate_dir=$(mktemp -d "${TMPDIR:-/tmp}/plot-gate-XXXXXX") || gate_dir=""
+  gate_dir=""
+  plot_tmpdir gate_dir gate || gate_dir=""
   if [ -n "$gate_dir" ]; then
-    trap 'rm -rf "$gate_dir"' EXIT
     gate_blob="$gate_dir/$(basename "$plan_path")"
     git show "$gate_ref:$plan_path" >"$gate_blob" 2>/dev/null || gate_blob=""
   fi
@@ -3063,6 +3323,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
       }