@plot-pm/board 0.16.1 → 0.16.3

package/plot-approve.sh

@@ -107,12 +107,13 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 . "$script_dir/plot-state-receipt.sh"
 
 dry_run=0
-who_override=""
+who_flag_given=0
+who_flag=""
 slug=""
 while [ $# -gt 0 ]; do
   case "$1" in
     --dry-run) dry_run=1 ;;
-    --who) who_override="${2:?--who needs a value}"; shift ;;
+    --who) who_flag_given=1; who_flag="${2:-}"; shift ;;
     -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
     -*) echo "plot-approve: unknown flag '$1'" >&2; exit 1 ;;
     *) slug="$1" ;;
@@ -128,7 +129,13 @@ git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository — run thi
 cfg() { bash "$script_dir/plot-config.sh" get "$1" "$2"; }
 
 repo_root=$(git rev-parse --show-toplevel)
-wt_root=$(cd "$repo_root/.." && pwd)
+# The booking worktree goes under the desk root of the MAIN checkout, never of
+# this tree: inside a desk `--show-toplevel` answers the desk, and the default
+# `.worktrees` would resolve beneath it. No fallback — `plot-desk-root.sh`.
+# shellcheck source=plot-desk-root.sh
+. "$script_dir/plot-desk-root.sh"
+main_root=$(plot_repo_root)
+wt_root=$(plot_desk_root "$main_root") || die "cannot resolve where the booking worktree goes (see above)"
 
 PLAN_DIR=$(cfg "Plan directory" "docs/plans/")
 ACTIVE_DIR=$(cfg "Active index" "docs/plans/active/")
@@ -189,11 +196,40 @@ esac
 # NONE means a pre-Plot-2 plan on an idea branch, which the skill documents as
 # `pr` by default. An unrecognised value is refused rather than defaulted:
 # "carry on" is the shape of stale assumption this whole story keeps finding.
+#
+# `in-session` IS NO LONGER A REFUSAL HERE, which is this slice's whole change.
+# `plot-approve.sh --who <handle> <slug>` performs the seven mechanical steps
+# for it exactly as it does for `pr`, because #1185 made the domain able to
+# decide the write (`approveTransition` takes `who` and `people`). What stays a
+# refusal is the absence of a usable reviewer: no `--who` at all, an empty one,
+# or one `People` does not declare — the domain's `review-human` and
+# `reviewer-undeclared` gates, asked through `decide_transition` below rather
+# than re-implemented here. There is no `--reviewer`: a round-1 panel measured
+# that spelling exiting 2 at the controller gate, and `--who` is the one flag
+# this script already declares.
+#
+# UNDER `PLOT_UNATTENDED=1` THIS STILL REFUSES, `--who` or not. The reviewer is
+# a human in a session that, by definition, has nobody in it under an
+# unattended run — the same argument `plot-approve/SKILL.md` already makes for
+# the skill's own in-session walkthrough. A default here would let the machine
+# name the reviewer, which is exactly what `--who`'s absence of a fallback (no
+# `PLOT_APPROVE_WHO`, no `git config user.name`) refuses for the same channel.
+in_session=0
 case "$review" in
   pr|NONE) ;;
   in-session)
-    die "plan '$slug' declares 'Review: in-session' — the reviewer is a human in the room.
-  A script cannot stand in for one. Approve it with /plot-approve $slug." ;;
+    if [ "${PLOT_UNATTENDED:-}" = "1" ]; then
+      die "plan '$slug' declares 'Review: in-session' — the reviewer is a human in the room.
+  Refusing under PLOT_UNATTENDED=1: there is nobody here to name. Approve it from a session: /plot-approve $slug"
+    fi
+    # No reviewer named: refuse before any git work. The domain's `review-human`
+    # gate says the same thing later, after a booking worktree exists; asking
+    # here keeps a refusal local and cheap. `--who` has no default.
+    if [ -z "$(printf '%s' "$who_flag" | tr -d '[:space:]')" ]; then
+      die "plan '$slug' declares 'Review: in-session' — name the reviewer with --who."
+    fi
+    in_session=1
+    ;;
   ballot)
     die "plan '$slug' declares 'Review: ballot' — the tally is the approval.
   A script cannot read a ballot. Approve it with /plot-approve $slug." ;;
@@ -202,71 +238,134 @@ case "$review" in
   Refusing rather than treating it as 'pr' — that would approve a plan nobody discussed." ;;
 esac
 
+# The declared handles, for the domain's `reviewer-undeclared` gate. Read
+# unconditionally — cheap, and a `pr` or `ballot` plan never reaches the branch
+# that uses it — from `People`'s `handle = Spelling; handle = Spelling` form:
+# only the text before each `=` is a handle, and `People` may be absent.
+people_raw=$(cfg "People" "")
+people_csv=$(printf '%s' "$people_raw" | tr ';' '\n' | while IFS= read -r entry; do
+  h="${entry%%=*}"
+  h="$(printf '%s' "$h" | sed -e 's/^[ \t]*//' -e 's/[ \t]*$//' | tr '[:upper:]' '[:lower:]')"
+  [ -n "$h" ] && printf '%s\n' "$h"
+done | paste -sd, -)
+[ -n "$people_csv" ] || people_csv=""
+
+# Read even for in-session: the booking worktree below (every non-same-branch
+# flow, in-session included) fetches and books against it.
 MAIN=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')
 [ -n "$MAIN" ] || MAIN=$(bash "$script_dir/plot-host.sh" default-branch 2>/dev/null) || MAIN=""
 [ -n "$MAIN" ] || MAIN="main"
 
-# The PR that carries the plan. `Impl: same branch` puts plan and code on the
-# work branch, so its PR is the WORK branch's — and it must not be merged here
-# (it merges once, at the end, carrying the implementation with it).
-same_branch=0
-[ "$impl" = "same-branch" ] && same_branch=1
-
-if [ "$same_branch" = 1 ]; then
-  pr_branch="$slug"
-  for p in $(cfg "Branch prefixes" "idea/, feature/, bug/, docs/, infra/" | tr ',' ' '); do
-    p="${p%/}"; p="${p# }"
-    [ -z "$p" ] && continue
-    [ "$p" = "idea" ] && continue
-    if git show-ref --verify --quiet "refs/heads/$p/$slug" \
-      || git show-ref --verify --quiet "refs/remotes/origin/$p/$slug"; then
-      pr_branch="$p/$slug"
-      break
-    fi
-  done
+if [ "$in_session" = 1 ]; then
+  # No plan PR to read or merge: the approval IS the reviewer's go, not a host
+  # state. `same_branch` stays 0 — in-session records through the same booking
+  # worktree the `pr` flow uses, since an in-session plan has no work branch of
+  # its own to record on.
+  same_branch=0
+  pr_number=0
+  pr_state="NONE"
+  pr_draft="false"
+  echo "step: plan $plan_file — phase=$phase review=${review} impl=${impl} (in-session, no plan PR)"
 else
-  pr_branch="idea/$slug"
-fi
+  # The PR that carries the plan. `Impl: same branch` puts plan and code on the
+  # work branch, so its PR is the WORK branch's — and it must not be merged here
+  # (it merges once, at the end, carrying the implementation with it).
+  same_branch=0
+  [ "$impl" = "same-branch" ] && same_branch=1
+
+  if [ "$same_branch" = 1 ]; then
+    pr_branch="$slug"
+    for p in $(cfg "Branch prefixes" "idea/, feature/, bug/, docs/, infra/" | tr ',' ' '); do
+      p="${p%/}"; p="${p# }"
+      [ -z "$p" ] && continue
+      [ "$p" = "idea" ] && continue
+      if git show-ref --verify --quiet "refs/heads/$p/$slug" \
+        || git show-ref --verify --quiet "refs/remotes/origin/$p/$slug"; then
+        pr_branch="$p/$slug"
+        break
+      fi
+    done
+  else
+    pr_branch="idea/$slug"
+  fi
 
-# 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=""
-plot_tmpfile pr_err_file approve-pr
-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).
+  # 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=""
+  plot_tmpfile pr_err_file approve-pr
+  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).
+  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)
-pr_draft=$(printf '%s' "$pr_json" | jq -r '.draft // false' 2>/dev/null)
-
-# --- refusal 3: the PR ------------------------------------------------------
-case "$pr_state" in
-  MERGED) ;;
-  OPEN) ;;
-  CLOSED)
-    die "the plan PR for '$slug' (#$pr_number) is closed.
+  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)
+  pr_draft=$(printf '%s' "$pr_json" | jq -r '.draft // false' 2>/dev/null)
+
+  # --- refusal 3: the PR ------------------------------------------------------
+  case "$pr_state" in
+    MERGED) ;;
+    OPEN) ;;
+    CLOSED)
+      die "the plan PR for '$slug' (#$pr_number) is closed.
   Reopen it on the host, or push '$pr_branch' again and open a new one." ;;
-  NONE|*)
-    die "no PR found for branch '$pr_branch'.
+    NONE|*)
+      die "no PR found for branch '$pr_branch'.
   Push the branch: git push -u origin $pr_branch
   Then open its PR — or run /plot-idea, which does both." ;;
-esac
+  esac
+fi
 
-echo "step: plan $plan_file — phase=$phase review=${review} impl=${impl} pr=#$pr_number($pr_state)"
+# --- refusal 4: a branch under no slice heading -----------------------------
+#
+# BEFORE THE MERGE, which is the whole point of its position. Step 2 merges the
+# plan PR, and a refusal fired after that leaves the PR merged, the plan still
+# Draft, and a refusal the operator can clear only by editing a merged plan. So
+# it sits with refusals 1 to 3, reading the same `$meta` step 1 took, and it
+# writes nothing.
+#
+# The heading is the slice's name on the board and the title of its PR
+# (`openSlicePr` refuses `slice-unnamed`), so it is owed on the default branch
+# before any agent starts. Without this an agent meets that refusal, writes the
+# heading on its own branch, and the board reads `(unnamed)` until the PR
+# merges (#1057).
+#
+# The rule is the domain's and it is asked, never re-implemented here:
+# `decide_transition` asks the same one through the same bundle, so the two can
+# never disagree about one plan.
+transition_check_mjs="$script_dir/board/plot-transition.mjs"
+if [ -f "$transition_check_mjs" ]; then
+  slice_err_file=""
+  plot_tmpfile slice_err_file approve-slices
+  slice_rc=0
+  printf '%s' "$meta" | node "$transition_check_mjs" --check-slices "$slug" \
+    2>"$slice_err_file" >/dev/null || slice_rc=$?
+  slice_err=$(cat "$slice_err_file" 2>/dev/null); rm -f "$slice_err_file"
+  if [ "$slice_rc" = 1 ]; then
+    die "$(printf '%s' "$slice_err" | cut -f2-)
+  The plan was not approved, nothing was merged and its phase is unchanged."
+  elif [ "$slice_rc" != 0 ]; then
+    die "cannot read the slices of '$plan_file' (plot-transition.mjs --check-slices exited $slice_rc).
+  ${slice_err:-The bundle gave no reason.}
+  Refusing rather than approving a plan whose slice headings were never read."
+  fi
+else
+  echo "plot-approve: cannot find $transition_check_mjs — slice headings went unchecked. Run 'pnpm build:board'." >&2
+fi
+
+[ "$in_session" = 1 ] || echo "step: plan $plan_file — phase=$phase review=${review} impl=${impl} pr=#$pr_number($pr_state)"
 
 # --- a DRAFT is taken out of draft, not refused ------------------------------
 #
@@ -284,16 +383,35 @@ echo "step: plan $plan_file — phase=$phase review=${review} impl=${impl} pr=#$
 # mergeable on either host — and stated as its own `step:` line so a caller
 # reading the output can see which half happened if the second one fails.
 
-who="${who_override:-${PLOT_APPROVE_WHO:-$(git config user.name 2>/dev/null || echo plot)}}"
+# `in-session` TAKES NO DEFAULT. A default here would let the machine name the
+# reviewer, which is the one thing a script must never do for a channel that
+# exists because a human is in the room — so `--who` alone answers, and an
+# empty or absent one reaches the domain's `review-human` refusal below rather
+# than silently becoming `git config user.name`. `pr` and the direct/same-branch
+# flow keep the existing chain: `PLOT_APPROVE_WHO`, then the git identity.
+if [ "$in_session" = 1 ]; then
+  who="$who_flag"
+  channel="in-session"
+else
+  who="${who_flag:-${PLOT_APPROVE_WHO:-$(git config user.name 2>/dev/null || echo plot)}}"
+fi
 today=$(date +%Y-%m-%d)
 
 if [ "$dry_run" = 1 ]; then
-  [ "$pr_draft" = "true" ] && echo "step: would mark PR #$pr_number ready for review"
-  echo "step: would merge PR #$pr_number"
-  echo "step: would flip Phase → Approved and fill Approved: $today, $who, plan-PR #$pr_number merged"
-  echo "step: would clear .plot/hold entries for: $(printf '%s' "$plan_branches" | tr '\n' ' ')"
-  echo "step: would update the sprint annotation${sprint:+ in $SPRINT_DIR (sprint $sprint)}"
-  echo "summary: merged=would phase=would record=would holds=would sprint=would push=would"
+  if [ "$in_session" = 1 ]; then
+    echo "step: would flip Phase → Approved and fill Approved: $today, $who, in-session"
+    echo "step: would clear .plot/hold entries for: $(printf '%s' "$plan_branches" | tr '\n' ' ')"
+    echo "step: would update the sprint annotation${sprint:+ in $SPRINT_DIR (sprint $sprint)}"
+    echo "step: would append a row to .plot/state/in-session-approvals.tsv"
+    echo "summary: merged=skipped-in-session phase=would record=would holds=would sprint=would push=would"
+  else
+    [ "$pr_draft" = "true" ] && echo "step: would mark PR #$pr_number ready for review"
+    echo "step: would merge PR #$pr_number"
+    echo "step: would flip Phase → Approved and fill Approved: $today, $who, plan-PR #$pr_number merged"
+    echo "step: would clear .plot/hold entries for: $(printf '%s' "$plan_branches" | tr '\n' ' ')"
+    echo "step: would update the sprint annotation${sprint:+ in $SPRINT_DIR (sprint $sprint)}"
+    echo "summary: merged=would phase=would record=would holds=would sprint=would push=would"
+  fi
   exit 0
 fi
 
@@ -307,7 +425,11 @@ fi
 # Merge commits, not squash: plan refinement history is the context a later
 # reader wants. `--delete-branch` retires idea/<slug>, which has no further job.
 merged_report="already"
-if [ "$same_branch" = 1 ]; then
+if [ "$in_session" = 1 ]; then
+  # No plan PR exists for this channel: the approval is the reviewer's go,
+  # read nowhere on a host.
+  merged_report="skipped-in-session"
+elif [ "$same_branch" = 1 ]; then
   # Plan and code ride one branch; the PR merges once, at the end, and merging
   # it here would land an unfinished implementation on the default branch.
   merged_report="skipped-same-branch"
@@ -507,16 +629,30 @@ decide_transition() { # $1=file $2=channel  → prints "<Phase>\t<record>\t<writ
     || { echo "plot-approve: cannot find $transition_mjs — run 'pnpm build:board'." >&2; return 1; }
   m=$(bash "$script_dir/plot-plan-meta.sh" "$f" 2>/dev/null) || m=""
   [ -n "$m" ] || { echo "plot-approve: cannot parse $f — refusing rather than guessing." >&2; return 1; }
-  answer=$(printf 'approve\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t\n' \
+  # THE SLICES TRAVEL WITH THE TRANSITION, not only with the early check above.
+  # Measured 2026-10-02 by disabling that check: this call approved an unnamed
+  # plan outright — merged, flipped and recorded — because the field line
+  # carries no slices and the domain reads an absent reading as unmeasured. So
+  # the rule is asked twice, the second time from the file this re-parses, which
+  # on the `pr` flow is the plan on the default branch.
+  #
+  # Out of band rather than a field of its own, which is why `People` widening
+  # the line to twelve did not touch this: the slices are a nested list, and
+  # `requestFrom` pads nothing.
+  local slices_file=""
+  plot_tmpfile slices_file approve-transition-slices
+  printf '%s' "$m" > "$slices_file"
+  answer=$(printf 'approve\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t\t%s\n' \
     "$slug" \
     "$(printf '%s' "$m" | jq -r '.phase // ""')" \
     "$(printf '%s' "$m" | jq -r '.review // ""')" \
     "$(printf '%s' "$m" | jq -r '.approved_raw // ""')" \
     "$(printf '%s' "$m" | jq -r '.delivered_raw // ""')" \
     "$(printf '%s' "$m" | jq -r '.released_raw // ""')" \
-    "$today" "$who" "$channel" \
-    | node "$transition_mjs" 2>&1)
+    "$today" "$who" "$channel" "$people_csv" \
+    | node "$transition_mjs" --slices "$slices_file" 2>&1)
   rc=$?
+  rm -f "$slices_file"
   # Exit 1 is the domain's refusal and its sentence, tab-separated after the
   # rule that fired. Exit 2 is this script handing it something unreadable,
   # which no operator can act on — so it reports as the bug it is.
@@ -684,10 +820,11 @@ apply_local_writes() { # $1=root  → sets phase_report record_report holds_repo
   # here rather than trusted from the caller's copy, because on the `pr` flow
   # those are different files and the plan on the default branch is the one that
   # counts.
-  local channel="plan-PR #$pr_number merged"
-  [ "$same_branch" = 1 ] && channel="plan-PR #$pr_number reviewed"
+  local write_channel="plan-PR #$pr_number merged"
+  [ "$same_branch" = 1 ] && write_channel="plan-PR #$pr_number reviewed"
+  [ "$in_session" = 1 ] && write_channel="$channel"
   local decided record action recorded
-  decided=$(decide_transition "$f" "$channel") || return 1
+  decided=$(decide_transition "$f" "$write_channel") || return 1
   record=$(printf '%s' "$decided" | cut -f2)
   action=$(printf '%s' "$decided" | cut -f3)
   recorded=$(printf '%s' "$decided" | cut -f4)
@@ -735,6 +872,9 @@ else
 
   bookbr="plot/approve-$slug"
   tmpwt="$wt_root/.plot-approve-$slug.$$"
+  # `git worktree add` creates the desk root when it is missing, so exclude it
+  # first: a booking run must not leave `.worktrees/` untracked in `git status`.
+  plot_exclude_desk_root "$main_root"
   # -B: a leftover branch from an earlier failed run must not block this one.
   # It is disposable by construction — created here, pushed, deleted.
   git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null \
@@ -782,13 +922,16 @@ else
       cleanup
     else
       # BRANCH PROTECTION FALLBACK — the only path where a micro-PR is right.
-      # Never leave the merged plan stranded at `Phase: Draft`: the merge is
-      # done and irreversible, so the recorded phase must follow it.
+      # Never leave the approved plan stranded at `Phase: Draft`: the approval
+      # is decided and irreversible once committed, so the recorded phase must
+      # follow it.
+      micro_body="Records the approval of \`$slug\` (plan-PR #$pr_number merged)."
+      [ "$in_session" = 1 ] && micro_body="Records the in-session approval of \`$slug\` by $who."
       echo "step: push rejected — opening a micro-PR instead"
       if git push -q origin "$bookbr" 2>/dev/null \
         && micro_url=$(bash "$script_dir/plot-host.sh" pr-create \
              --title "plot: approve $slug" \
-             --body "Records the approval of \`$slug\` (plan-PR #$pr_number merged)." \
+             --body "$micro_body" \
              --base "$MAIN" --head "$bookbr" 2>/dev/null) \
         && micro_num=$(printf '%s' "$micro_url" | sed 's#.*/##') \
         && bash "$script_dir/plot-host.sh" pr-merge "$micro_num" --delete-branch >/dev/null 2>&1
@@ -798,8 +941,10 @@ else
         cleanup
       else
         push_report="rejected"
+        stranded_reason="PR #$pr_number IS MERGED"
+        [ "$in_session" = 1 ] && stranded_reason="the in-session approval IS DECIDED"
         echo "plot-approve: the approval is committed on '$bookbr' but could not reach $MAIN." >&2
-        echo "  PR #$pr_number IS MERGED — the plan must not stay at Phase: Draft." >&2
+        echo "  $stranded_reason — the plan must not stay at Phase: Draft." >&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: merged=$merged_report phase=$phase_report record=$record_report holds=$holds_report sprint=$sprint_report push=$push_report"
@@ -809,6 +954,21 @@ else
   fi
 fi
 
+# THE LOG REPLACES A COUNT, NEVER A RECEIPT. Appended ONLY after the push
+# landed this run — `nothing-to-commit` means an earlier run already recorded
+# this approval (and, with it, this row), so appending again would double a
+# count that exists to say how many in-session approvals happened, not how
+# many times this script ran. A refused or interrupted run reaches neither
+# this line nor a row, which is `plot-agent-settings.sh`'s rule applied here:
+# read the exit code, not the emptiness.
+if [ "$in_session" = 1 ] && [ "$push_report" != "nothing-to-commit" ] && [ "$push_report" != "n/a" ]; then
+  entry="script"
+  [ "${PLOT_APPROVE_ENTRY:-}" = "board" ] && entry="board"
+  log_dir="$main_root/.plot/state"
+  mkdir -p "$log_dir" 2>/dev/null \
+    && printf '%s\t%s\t%s\t%s\n' "$today" "$slug" "$who" "$entry" >> "$log_dir/in-session-approvals.tsv" 2>/dev/null
+fi
+
 echo "summary: merged=$merged_report phase=$phase_report record=$record_report holds=$holds_report sprint=$sprint_report push=$push_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

package/plot-build-monitor.sh

@@ -101,9 +101,13 @@ Started by plot-dispatch.sh inside the worker's wrapper. Reads its subject from
 the environment, exactly as the wrapper's other children do:
 
   PLOT_BRANCH        the branch whose builds this monitor will report
-  PLOT_WORKTREE      the desk it reads the head sha from
+  PLOT_WORKTREE      the desk it STARTS on; it follows the manifest's
+                     `worktree` from then on (PLOT_MANIFEST_FILE below)
+  PLOT_MANIFEST_FILE the manifest this agent is named in, re-read each pass;
+                     absent or unreadable keeps watching PLOT_WORKTREE
   PLOT_MONITOR_FILE  where findings are published (default:
-                     $PLOT_WORKTREE/.plot-worker.monitor.build.jsonl)
+                     $PLOT_WORKTREE/.plot-worker.monitor.build.jsonl). Set
+                     explicitly, it WINS and does not follow a hop.
   PLOT_MONITOR_INTERVAL  seconds between passes (default 30)
 
   --once   take one sample and exit, rather than looping. A test
@@ -124,7 +128,17 @@ done
 monitor='BuildMonitor'
 
 branch="${PLOT_BRANCH:-}"
-worktree="${PLOT_WORKTREE:-}"
+# The branch at start, kept for a detached or unreadable desk; `monitor_branch`
+# re-reads the desk on every pass.
+start_branch="$branch"
+# THE DESK THIS MONITOR WAS LAUNCHED ON, FIXED FOR ITS WHOLE LIFE. `worktree`
+# itself is no longer fixed: `monitor_pass` reassigns it every pass by asking
+# `plot_watched_desk`, which follows a hop to the manifest's new `worktree`
+# field. This is the launch desk `plot_watched_desk` falls back to when the
+# manifest carries no override — never read directly after startup.
+launched_worktree="${PLOT_WORKTREE:-}"
+worktree="$launched_worktree"
+manifest_file="${PLOT_MANIFEST_FILE:-}"
 # THIRTY SECONDS IS AFFORDABLE ONLY BECAUSE OF THE SILENCE RULE. This cadence
 # matches the WorkerMonitor's rather than the AgentMonitor's, and it asks a HOST
 # — which would be the rate problem the AgentMonitor's 300 s exists to avoid,
@@ -132,7 +146,11 @@ worktree="${PLOT_WORKTREE:-}"
 # is bounded by how long a build takes, not by how long a worker lives.
 interval="${PLOT_MONITOR_INTERVAL:-30}"
 
-findings="${PLOT_MONITOR_FILE:-${worktree:+$worktree/.plot-worker.monitor.build.jsonl}}"
+# IF `PLOT_MONITOR_FILE` IS SET IT WINS AND DOES NOT FOLLOW THE DESK — the
+# existing contract this usage text already states. Otherwise `findings`
+# follows `worktree`, reassigned alongside it at the top of `monitor_pass`.
+monitor_file_override="${PLOT_MONITOR_FILE:-}"
+findings="${monitor_file_override:-${worktree:+$worktree/.plot-worker.monitor.build.jsonl}}"
 
 # THE SUBJECT, read the same way the other two monitors read it.
 pid_file="${PLOT_PID_FILE:-${worktree:+$worktree/.plot-worker.pid}}"
@@ -209,6 +227,25 @@ monitor_head_sha() { # → prints a sha, or nothing
   git -C "$worktree" rev-parse --verify --quiet HEAD 2>/dev/null || true
 }
 
+# Which branch does the desk hold, right now?
+#
+# → prints the branch, or the branch the monitor started with when the desk is
+#   detached or unreadable
+#
+# READ ON EVERY PASS, NOT ONCE. A free agent starts with an empty `PLOT_BRANCH`
+# and is handed its slices later, in the same desk; a dispatched agent hops to
+# its next slice in the same desk too. A branch fixed at start made this monitor
+# unaskable for every free agent (`monitor_run_for_sha` returns 2 on an empty
+# branch) and wrong after every hop, so the correction path in
+# `plot-worker-loop.sh` received no finding for most slices.
+monitor_branch() { # → prints a branch, or nothing
+  local current=''
+  if [ -n "$worktree" ] && [ -d "$worktree" ]; then
+    current=$(git -C "$worktree" branch --show-current 2>/dev/null || true)
+  fi
+  printf '%s' "${current:-$start_branch}"
+}
+
 # What does the host say about the run for ONE sha?
 #
 # → prints the run JSON, or nothing when there is no run for it
@@ -376,6 +413,14 @@ sample_finding() { # → prints "finding\tevidence", or nothing
 # One full pass: sample, publish only on a change of ANSWER-ABOUT-A-COMMIT.
 monitor_pass() {
   local row finding evidence head
+  # REASSIGNED ONCE, HERE, RATHER THAN THREADED THROUGH EACH READER. `worktree`
+  # feeds `monitor_head_sha`, `monitor_branch` and `publish()`'s own field, so a
+  # hop is picked up in one place rather than three. `PLOT_MONITOR_FILE`, when
+  # set, WINS and does not follow the desk — the existing contract the usage
+  # text states.
+  worktree=$(plot_watched_desk "$manifest_file" "$launched_worktree")
+  findings="${monitor_file_override:-${worktree:+$worktree/.plot-worker.monitor.build.jsonl}}"
+  branch=$(monitor_branch)
   head=$(monitor_head_sha)
   row=$(sample_finding)
   finding="${row%%	*}"

package/plot-config.sh

@@ -27,12 +27,7 @@
 #   Project board | Branch prefixes | Plan directory | Active index |
 #   Delivered index | Sprint directory | Story directory | Story index |
 #   Plan template | Worker prompt template | Main branch | Board command
-#   Worktree root       where /plot-dispatch puts its worktrees. Read by
-#                       plot-dispatch.sh; default is the repo's PARENT, which
-#                       scatters `plot-wt-*` beside the checkout. An absolute
-#                       path is taken as given; a relative one resolves against
-#                       the repo root, so `.worktrees` gathers them inside it.
-#                       The default is kept for repos that never set it.
+#   Worktree root       the desk root; see its entry under the agent keys below.
 #   Worker bound        seconds a single prompt run may take in the worker loop
 #                       before it is ended and the worker exits (no hop). Read by
 #                       plot-worker-loop.sh; default 3600 (~1h), `0` disables it.
@@ -99,14 +94,15 @@
 #                       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
-#                       the `plot-wt-` prefix — today's behaviour, so no existing
-#                       checkout moves. Under a dedicated root the prefix is
-#                       dropped: the directory already says these are Plot's. Read
-#                       only by the CREATION path; every "which worktree holds this
-#                       branch" read asks `git worktree list` instead.
+#   Worktree root       the desk root: where /plot-dispatch creates fleet
+#                       worktrees and the board writes its action records. A
+#                       relative value resolves against the MAIN checkout, an
+#                       absolute one is taken as given. Absent or empty =
+#                       `<repo>/.worktrees`. The rule is `deskRoot`, asked through
+#                       `plot-desk-root.sh`; no script resolves it itself. Desks
+#                       carry no prefix; `plot-wt-*` desks an older dispatch made
+#                       beside the repo stay there. Every "which worktree holds
+#                       this branch" read asks `git worktree list` instead.
 # Agent-runner keys (optional; Plot hardcodes no agent tooling, Principle 5):
 #   Worker command      how /plot-dispatch runs an agent headless on a worktree.
 #                       /plot-init writes `PLOT_UNATTENDED=1 plot-worker-loop.sh`;