@plot-pm/board 0.14.3 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.14.3",
+  "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-budget.sh

@@ -221,7 +221,7 @@ BUDGET_FALLBACK_WINDOW_MS=3600000
 # which is a reading about whichever pool was spent last — so a caller deciding
 # whether a bucket is spent must name that bucket. `graphql_budget_spent` does,
 # and this is why.
-budget_rate() {
+budget_rate_read() {
   local connector="${1:-}" account="${2:-}" bucket="${3:-}" now="${4:-}"
   local path
   [ -n "$now" ] || now="$(budget_now_ms)"
@@ -321,6 +321,171 @@ budget_rate() {
   ' "$path" 2>/dev/null || echo '{"spent":0,"spanMs":0,"perHour":null,"lines":0,"unreadable":0,"limit":null,"remaining":null,"resetAt":null,"basis":"unknown"}'
 }
 
+# THE SAME ANSWER IS SCANNED FOR ONCE PER PROCESS, and that is the whole of this
+# memo. Measured on `quatico/quaweb-website` at Plot 2.19.0: `budget.tsv` holds
+# 312589 lines across 17.6 MB, one read of it takes **516 ms** against 5 ms over
+# fifty lines, and a single `pr-list` calls this three times for the same answer.
+# The file is append-only and a process that asks twice is asking about the same
+# window, so the second scan buys nothing a caller can observe.
+#
+# THE MEMO IS A FILE, AND A VARIABLE ALONE COULD NOT HAVE WORKED. Every caller
+# in `plot-host.sh` writes `rate="$(budget_rate ...)"`, and a command
+# substitution is a SUBSHELL: a variable the function sets inside one dies when
+# the substitution closes. Measured on this branch with a counter — three
+# substituted calls on one key scanned the ledger 3 times with a variable memo
+# in place, against 1 for three direct calls. A variable memo is not slow at the
+# call sites that exist, it is ABSENT from them, and every behavioural test
+# still passes because the three answers are identical.
+#
+# `$$`, NOT `BASHPID`, IS THE SCOPE. `$$` is the invoking shell's pid and is
+# deliberately NOT updated inside a subshell, so it names the process TREE —
+# which is exactly "the life of the process" this memo is bounded by. `BASHPID`
+# tracks the fork and would give every substitution its own empty cache, which
+# is the variable memo's defect with an extra file write.
+#
+# THE COST IS PAID BACK ABOUT TWO THOUSAND TIMES. Measured here: a builtin
+# `read` of one memo line is 82 us and a write 153 us, against 188 ms for one
+# scan of a 40000-line ledger and the 516 ms reported above. The read is a
+# builtin with no fork, which is what keeps it in that range.
+#
+# PER PROCESS IS THE WHOLE BOUND. There is no TTL, no `stat` of the record and
+# no invalidation hook, because a `plot-host.sh` invocation is short-lived and a
+# memo that tried to notice the file moving would re-`stat` on every call — the
+# cost this exists to remove, re-introduced in a smaller form. `budget_append`
+# writes between two reads and the second read is deliberately served the first
+# one's answer.
+#
+# THE KEY IS THE TRIPLE, NEVER ONE FIELD OF IT. An EMPTY bucket means *every
+# bucket* and is a different question from any named one — `budget_rate_read`
+# says so in its own words above, and the two live in one process: measured with
+# a probe, one `pr-list` asks `(github,jwloka,'')` for the concurrency bound and
+# `(github,jwloka,graphql)` for the transport choice. A memo keyed on less than
+# the triple answers the first with the second's reading.
+#
+# AN EXPLICIT `now` BYPASSES THE MEMO ENTIRELY, and a reader will ask why. It is
+# a FOURTH question rather than a fourth key: a caller naming a moment is asking
+# what the record looked like THEN, and every window boundary above is computed
+# from it. Keying on it would make every lookup a miss, because the callers that
+# omit it get `budget_now_ms()` and differ by milliseconds — a memo that is dead
+# code and still passes every behavioural test. Serving a memo across different
+# `now` values would answer a named moment with another one's window. Only the
+# callers that omit it — every one in `plot-host.sh` — are memoised.
+#
+# NOT-YET-COMPUTED AND COMPUTED-TO-EMPTY ARE TWO STATES, and the FILE'S
+# EXISTENCE is what separates them. The zero object is a well-formed answer for
+# a missing record and for a `budget_path` that failed, so it is CACHED like any
+# other — a memo that treated it as no-answer-worth-keeping would restore the
+# scan on exactly the machines with nothing to scan. The entry is never empty:
+# `budget_rate_read` prints a JSON object on every path, so a zero-byte entry
+# means a torn write and is re-read rather than served.
+#
+# PUBLISHED BY `mv`, NEVER BY `>`, for `budget_slot_acquire`'s reason one
+# paragraph down: a redirect creates the NAME before the CONTENT, so a sibling
+# subshell can open the file and read half an answer. The rename is atomic
+# within a directory, so the name and the answer arrive together.
+budget_rate() {
+  local connector="${1:-}" account="${2:-}" bucket="${3:-}" now="${4:-}"
+
+  # A caller that named a moment is asking a different question. Straight
+  # through, neither read nor written.
+  if [ -n "$now" ]; then
+    budget_rate_read "$connector" "$account" "$bucket" "$now"
+    return $?
+  fi
+
+  local key slot
+  key="${connector}|${account}|${bucket}"
+  # Every character a variable name may not hold becomes `_`. Two distinct
+  # triples could collide only by differing in punctuation alone, which no
+  # connector, account or bucket name does.
+  slot="_budget_rate_memo_$(printf '%s' "$key" | LC_ALL=C tr -c '[:alnum:]_' '_')"
+
+  # TIER ONE, FREE: the same shell asking twice. SET, NOT NON-EMPTY — the zero
+  # object is a real answer and an empty one is a state this memo never stores.
+  if eval "[ -n \"\${${slot}+set}\" ]"; then
+    eval "printf '%s\\n' \"\${${slot}}\""
+    return 0
+  fi
+
+  # TIER TWO, 82 us: a subshell asking what its parent already asked. This is
+  # the tier that fires at every call site `plot-host.sh` actually has.
+  local dir file answer
+  dir="$(budget_memo_dir)" || dir=''
+  if [ -n "$dir" ]; then
+    file="$dir/$slot"
+    # `-s`, NOT `-f`. A zero-byte entry is a torn write, never an answer.
+    if [ -s "$file" ]; then
+      IFS= read -r answer < "$file" 2>/dev/null || answer=''
+      if [ -n "$answer" ]; then
+        eval "${slot}=\$answer"
+        printf '%s\n' "$answer"
+        return 0
+      fi
+    fi
+  fi
+
+  local rc
+  # THE EXIT CODE IS THE READ'S, never this wrapper's. `budget_rate_read`
+  # returns 0 on every path today and its callers test the CONTENT, so a memo
+  # that invented an exit status would be the one place the two disagree.
+  answer="$(budget_rate_read "$connector" "$account" "$bucket")"; rc=$?
+  if [ "$rc" -ne 0 ]; then
+    # A read that failed is not an answer, so nothing is remembered: the next
+    # caller asks again rather than inheriting a failure for the process life.
+    printf '%s\n' "$answer"
+    return "$rc"
+  fi
+  eval "${slot}=\$answer"
+  # NEVER FAILS ITS CALLER, `budget_append`'s rule for the same reason: the memo
+  # is an optimisation beside an answer that is already correct, so a cache that
+  # cannot be written must not turn a good reading into a failed one.
+  if [ -n "$dir" ] && mkdir -p "$dir" 2>/dev/null; then
+    if printf '%s\n' "$answer" >"$file.$BASHPID.tmp" 2>/dev/null; then
+      mv -f "$file.$BASHPID.tmp" "$file" 2>/dev/null || rm -f "$file.$BASHPID.tmp" 2>/dev/null || true
+    fi
+  fi
+  printf '%s\n' "$answer"
+  return 0
+}
+
+# Where THIS PROCESS's memoised rates live, and it is deliberately not beside
+# the record. `$PLOT_BUDGET_HOME/memo/<pid>` — same override as the record and
+# the slots, so a test pointing `PLOT_BUDGET_HOME` at a sandbox gets a sandboxed
+# cache too, and a `$PLOT_BUDGET_HOME` that cannot be resolved means no cache
+# rather than a cache in the wrong place.
+#
+# `$$` IS THE DIRECTORY NAME because it is the one identifier that is stable
+# across a command substitution — see `budget_rate` above, where that property
+# is the whole reason this file exists. A pid is reused by the kernel after the
+# process ends, so an entry could in principle be inherited by a later,
+# unrelated process holding the same pid. That is bounded by `budget_memo_clear`
+# below, which the adapter calls on exit, and it is why the cache holds a
+# DERIVED reading rather than anything a caller could act on irreversibly: the
+# worst case is one stale rate, which is the same staleness the memo grants
+# within a process by design.
+budget_memo_dir() {
+  local home="${PLOT_BUDGET_HOME:-}"
+  if [ -z "$home" ]; then
+    [ -n "${HOME:-}" ] || return 1
+    home="$HOME/.plot/state"
+  fi
+  printf '%s\n' "$home/memo/$$"
+}
+
+# Removes this process's memo directory. Called on exit by the adapter, so a
+# long-lived machine does not accumulate one directory per `plot-host.sh` call.
+#
+# NEVER FAILS ITS CALLER. It runs in a trap beside work that has already
+# happened, and a cache that cannot be cleared must not change an exit status.
+budget_memo_clear() {
+  local dir
+  dir="$(budget_memo_dir)" || return 0
+  case "$dir" in
+    */memo/[0-9]*) rm -rf "$dir" 2>/dev/null || true ;;
+  esac
+  return 0
+}
+
 # ── The concurrency bound ────────────────────────────────────────────────────
 #
 # HOW MANY CALLS THIS ACCOUNT HAS OPEN AT ONCE, bounded across PROCESSES. The

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