@plot-pm/board 0.19.0 → 0.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plot-pm/board",
3
- "version": "0.19.0",
3
+ "version": "0.19.1",
4
4
  "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/plot-dispatch.sh CHANGED
@@ -1014,8 +1014,8 @@ resolve_launch() { # $1 = repo root, $2 = agent name ('' when none)
1014
1014
  # makes `failed` safe to include — and including it is the point: a gate that
1015
1015
  # simply refused `failed` would pass every refusal test and leave the verb
1016
1016
  # unable to do the one thing it exists for.
1017
- handover_refusal() { # $1=branch $2=worktree $3=state → 0 may hand over, 1 refused
1018
- local branch="$1" wt="$2" state="$3" pr_json pr_num pr_state marker
1017
+ handover_refusal() { # $1=branch $2=worktree $3=state $4=plot_desk_loops line → 0 may hand over, 1 refused
1018
+ local branch="$1" wt="$2" state="$3" loop="${4:-none}" pr_json pr_num pr_state marker lpid lsrc lwait
1019
1019
 
1020
1020
  if reached_review "$branch"; then
1021
1021
  pr_json=$("$script_dir/plot-host.sh" pr-state "$branch" </dev/null 2>/dev/null || true)
@@ -1028,11 +1028,20 @@ handover_refusal() { # $1=branch $2=worktree $3=state → 0 may hand over, 1 ref
1028
1028
  return 1
1029
1029
  fi
1030
1030
 
1031
+ # A LIVE LOOP REFUSES WHATEVER THE STATE WORD SAYS (#1450). A loop sleeping on
1032
+ # checks, on a usage limit or between passes has no agent beneath it and reads
1033
+ # `stalled` or `finished`, yet a second loop beside it shares the desk.
1034
+ # `deskLoopAlive` reads all three recorded pids; an unread answer refuses too.
1035
+ case "$loop" in
1036
+ none) ;;
1037
+ alive*) IFS=$'\t' read -r _ lpid lsrc lwait <<<"$loop"
1038
+ [ "$lwait" = free ] && printf 'plot-dispatch: a free agent is waiting on %s (pid %s) — refusing.\n Its loop is idle, polling for a hand-over. Confirm before replacing it:\n plot-dispatch.sh --stop %s\n' "$branch" "$lpid" "$branch" >&2 && return 1
1039
+ case "$state" in running*) ;; *) printf 'plot-dispatch: a loop is alive on %s (pid %s, from %s) — refusing.\n It reads %s, which --stop leaves alone, as the reaper does. Let it\n finish its pass, or end pid %s yourself if you mean to replace it.\n' "$branch" "$lpid" "$lsrc" "${state%% *}" "$lpid" >&2; return 1 ;; esac ;;
1040
+ *) printf 'plot-dispatch: could not read whether a loop is alive on %s — refusing.\n' "$branch" >&2; return 1 ;;
1041
+ esac
1031
1042
  case "$state" in
1032
1043
  running*)
1033
- echo "plot-dispatch: a worker is alive on $branch (pid ${state#running }) — refusing." >&2
1034
- echo " Stop it first if you mean to replace it:" >&2
1035
- echo " plot-dispatch.sh --stop $branch" >&2
1044
+ printf 'plot-dispatch: a worker is alive on %s (pid %s) — refusing.\n Stop it first if you mean to replace it:\n plot-dispatch.sh --stop %s\n' "$branch" "${state#running }" "$branch" >&2
1036
1045
  return 1
1037
1046
  ;;
1038
1047
  waiting*)
@@ -1824,14 +1833,12 @@ if [ "$mode" = "stop" ]; then
1824
1833
  wt_guess="$wt_root_early/$wt_prefix_early$(printf '%s' "$stop_branch" | tr '/' '-')"
1825
1834
  [ -n "$wt" ] && [ -d "$wt" ] || wt="$wt_guess"
1826
1835
  if [ ! -d "$wt" ]; then
1827
- echo "plot-dispatch: no worktree holds '$stop_branch' — nothing to stop." >&2
1828
- echo " Asked git for every worktree, and looked at $wt_guess." >&2
1829
- echo " If a worker is running somewhere this cannot see, that machine is" >&2
1830
- echo " where to stop it: /plot-dispatch --status names the desks here." >&2
1831
- echo " Nothing was killed." >&2
1836
+ printf "plot-dispatch: no worktree holds '%s' — nothing to stop.\n Asked git for every worktree, and looked at %s.\n If a worker is running somewhere this cannot see, that machine is\n where to stop it: /plot-dispatch --status names the desks here.\n Nothing was killed.\n" "$stop_branch" "$wt_guess" >&2
1832
1837
  exit 1
1833
1838
  fi
1834
1839
  st=$(worker_state "$wt" "$stop_branch")
1840
+ # A LIVE LOOP IS STOPPED WHATEVER ITS STATE WORD, so the loop `--restart`
1841
+ # refuses on is one this verb can end (`deskLoopAlive`, #1450).
1835
1842
  case "$st" in
1836
1843
  running*)
1837
1844
  pid=${st#running }
@@ -1863,10 +1870,14 @@ if [ "$mode" = "stop" ]; then
1863
1870
  else
1864
1871
  echo " signalled its whole process group $stop_pgid"
1865
1872
  fi
1873
+ # A PERSON'S STOP IS RECORDED AS ONE, so the supervisor's tick leaves the
1874
+ # desk alone. A worker that exits non-zero with no ending gets a fresh
1875
+ # agent from the tick (`killedWorkerEnding`); a `stopped` ending answers
1876
+ # `leave` in `endingAction`, and the desk keeps its claim.
1877
+ printf '{"reason":"stopped","actor":"operator","branch":"%s","detail":"plot-dispatch --stop"}\n' "$stop_branch" 2>/dev/null >"$wt/.plot-worker.ending.json" || true
1866
1878
  # The worktree and its claim are left in place: the branch is still taken,
1867
1879
  # and deleting either would be the kind of write this design avoids.
1868
- echo " worktree kept at $wt — the claim stands until you release it:"
1869
- echo " plot-dispatch.sh --release $stop_branch"
1880
+ printf ' worktree kept at %s — the claim stands until you release it:\n plot-dispatch.sh --release %s\n' "$wt" "$stop_branch"
1870
1881
  ;;
1871
1882
  finished*|waiting*|stalled*|failed*|ended*) echo "$stop_branch is not running ($st)" ;;
1872
1883
  *) echo "$stop_branch has no worker" ;;
@@ -1894,9 +1905,7 @@ if [ "$mode" = "restart" ]; then
1894
1905
  # stopped worker on it should be replaced. Refusing on phase would strand
1895
1906
  # exactly the branch this exists to rescue.
1896
1907
  if [ -z "$restart_branch" ]; then
1897
- echo "plot-dispatch: --restart needs a branch name, e.g. --restart feature/x" >&2
1898
- echo " A slug is not enough: which stopped branch to hand to a new worker" >&2
1899
- echo " is your call, not something this should guess." >&2
1908
+ printf 'plot-dispatch: --restart needs a branch name, e.g. --restart feature/x\n A slug is not enough: which stopped branch to hand to a new worker\n is your call, not something this should guess.\n' >&2
1900
1909
  exit 1
1901
1910
  fi
1902
1911
 
@@ -1908,9 +1917,7 @@ if [ "$mode" = "restart" ]; then
1908
1917
  # them, and a hand-made worktree rarely follows dispatch's naming.
1909
1918
  restart_wt=$(worktree_holding_branch "$restart_branch")
1910
1919
  if [ -z "$restart_wt" ] || [ ! -d "$restart_wt" ]; then
1911
- echo "plot-dispatch: no worktree holds '$restart_branch' — nothing to restart." >&2
1912
- echo " --restart hands an EXISTING checkout to a new worker; it creates none." >&2
1913
- echo " To start this branch fresh, dispatch its plan." >&2
1920
+ printf "plot-dispatch: no worktree holds '%s' — nothing to restart.\n --restart hands an EXISTING checkout to a new worker; it creates none.\n To start this branch fresh, dispatch its plan.\n" "$restart_branch" >&2
1914
1921
  exit 1
1915
1922
  fi
1916
1923
 
@@ -1935,7 +1942,8 @@ if [ "$mode" = "restart" ]; then
1935
1942
  # running here" — asked rather than re-derived, so this cannot drift from
1936
1943
  # `--status` and the scan the way five of six states already did once.
1937
1944
  restart_state=$(worker_state "$restart_wt" "$restart_branch")
1938
- handover_refusal "$restart_branch" "$restart_wt" "$restart_state" || exit 1
1945
+ restart_loop=$(printf '%s\n' "$restart_wt" | plot_desk_loops) || restart_loop="unread"
1946
+ handover_refusal "$restart_branch" "$restart_wt" "$restart_state" "${restart_loop:-unread}" || exit 1
1939
1947
  # `stalled`, `failed`, `ended` and `no worker` all restart. The PR question
1940
1948
  # above is what makes `failed` safe to include — and including it is the
1941
1949
  # point: a gate that simply refused `failed` would pass every refusal test
@@ -2310,8 +2318,11 @@ if [ "$mode" = "start" ]; then
2310
2318
  [ -n "$start_main" ] || start_main="main"
2311
2319
 
2312
2320
  # HOW MANY WORKERS ARE ALREADY UP, counted from the desks on this disk rather
2313
- # than from the registry. A manifest records a launch; a live pid records a
2314
- # worker, and the question `--start` asks is about the machine's load. The
2321
+ # than from the registry. A manifest records a launch; a live loop records a
2322
+ # worker, and the question `--start` asks is about the machine's load. A loop
2323
+ # counts whatever its state word: one sleeping on checks, on a usage limit or
2324
+ # between passes holds no agent and still loads the machine. `deskLoopAlive`
2325
+ # answers, through `plot_desk_loops`, the reading `--restart` refuses on. The
2315
2326
  # count is what `fleetSize` subtracts, so asking for three twice gives three
2316
2327
  # agents rather than six.
2317
2328
  #
@@ -2338,14 +2349,7 @@ if [ "$mode" = "start" ]; then
2338
2349
  if [ -n "${PLOT_START_ONE:-}" ]; then
2339
2350
  start_count=1
2340
2351
  else
2341
- while IFS= read -r wt; do
2342
- [ -n "$wt" ] || continue
2343
- [ -f "$wt/.plot-worker.pid" ] || continue
2344
- p=$(cat "$wt/.plot-worker.pid" 2>/dev/null) || continue
2345
- [ -n "$p" ] && ps -p "$p" >/dev/null 2>&1 && start_running=$((start_running + 1))
2346
- done <<EOF
2347
- $(git worktree list --porcelain </dev/null 2>/dev/null | awk '/^worktree /{print $2}')
2348
- EOF
2352
+ start_running=$(git worktree list --porcelain </dev/null 2>/dev/null | awk '/^worktree /{print $2}' | plot_desk_loops --count) || start_running=""
2349
2353
  fi
2350
2354
 
2351
2355
  # THE MACHINE'S OWN READING, one timed fork. `machine-system.ts` samples five
@@ -2406,8 +2410,13 @@ EOF
2406
2410
  # missing node, a module that throws all leave the answer empty. The direction
2407
2411
  # is the reaper's: silence is never permission, and here permission would spawn
2408
2412
  # detached processes.
2409
- start_bundle="$script_dir/board/plot-fleet-size.mjs"
2410
- start_answer=$(printf '%s\t%s\t%s' "$start_count" "$start_running" "$start_cost" \
2413
+ #
2414
+ # A COUNT THAT CANNOT BE READ IS THE SAME REFUSAL: an empty `start_running`
2415
+ # means `plot-desk-loop.mjs` answered nothing, and the refusal below names
2416
+ # that bundle, because an undercount would start too many agents.
2417
+ start_bundle="$script_dir/board/plot-fleet-size.mjs" start_answer=""
2418
+ [ -n "$start_running" ] || start_bundle="$script_dir/board/plot-desk-loop.mjs"
2419
+ [ -z "$start_running" ] || start_answer=$(printf '%s\t%s\t%s' "$start_count" "$start_running" "$start_cost" \
2411
2420
  | node "$start_bundle" 2>/dev/null)
2412
2421
 
2413
2422
  if [ -z "$start_answer" ]; then
@@ -221,7 +221,7 @@
221
221
  #
222
222
  # 2. `.plot/state/last-pulse.json` — the bridge, written by `write_bridge` on
223
223
  # the success path of `--stream` (unless PLOT_SCAN_RECORD=0) and `--log-pulse`
224
- # (what /plot-pulse passes). Those are the two callers that produce a pulse
224
+ # (what /plot-pulse passes; not while the fleet's writer holds the bridge). Those are the two callers that produce a pulse
225
225
  # for somebody to READ; plain `--json` is a query and records nothing. That
226
226
  # is a CACHE WITH AN EXPIRY: `pulse-bridge.ts` discards it after 15 minutes
227
227
  # and on a version mismatch, so it can only ever be a shortcut to an answer
@@ -5122,8 +5122,8 @@ fi
5122
5122
  # each with `toMap`, which yields an empty Map for anything it cannot use, and
5123
5123
  # `branchUrlBase` falls back to `''`. So a scan-written bridge serves the rows,
5124
5124
  # the verdicts and the counts, with unknown ages and no branch links — degraded
5125
- # in the direction the board already handles, and overwritten by the board's own
5126
- # richer write seconds later on the refresh it always issues.
5125
+ # in the direction the board already handles. While the fleet runs, its
5126
+ # `writeScan` writes the full bridge and `--log-pulse` writes none.
5127
5127
  #
5128
5128
  # TEMP FILE PLUS RENAME, carrying the pid, exactly as `writeBridge` does and for
5129
5129
  # the same reason: `rename` is atomic within a filesystem, so a board reading
@@ -5173,8 +5173,11 @@ write_bridge() {
5173
5173
  # git rather than assuming the two agree.
5174
5174
  local root file tmp
5175
5175
  root=$(git rev-parse --show-toplevel 2>/dev/null) || return 0
5176
- [ -n "$root" ] || return 0
5177
5176
  file="$root/.plot/state/last-pulse.json"
5177
+ # `--log-pulse` leaves a bridge the fleet's writer holds (`fleetHoldsBridge`):
5178
+ # one writer while a fleet runs. A missing, stale or thin bridge, or a failed
5179
+ # ask, writes as before, so a repository with no board and no fleet keeps its history.
5180
+ [ "$log_pulse" = 1 ] && [ -f "$file" ] && node "$script_dir/board/plot-delta.mjs" --held < "$file" 2>/dev/null && return 0
5178
5181
  mkdir -p "$root/.plot/state" 2>/dev/null || return 0
5179
5182
  tmp="$file.$$.tmp"
5180
5183
  # `at` is when the scan COMPLETED, which is what `pulse-bridge.ts:81` asks for
package/plot-plan-meta.sh CHANGED
@@ -173,6 +173,10 @@
173
173
  # are a plan's evidence, and plot-host.sh resolves where each
174
174
  # one lives. An absent PR contributes nothing — not "", not 0 —
175
175
  # the same rule `Issue:` follows.
176
+ # deferred_prs PR numbers read from a branch line or slice heading that
177
+ # carries a `deferred:`/`moved:` annotation, in document order.
178
+ # Every one is also in `prs`. The release record reads the last
179
+ # PR of `prs` that is not here. [] when no deferred line names one.
176
180
  # malformed_prs near-miss annotations, verbatim — currently `→#NNN` with no
177
181
  # space. Reported rather than dropped: "no annotation" is a
178
182
  # claim the sweep acts on, so a typo that reads as absence
@@ -307,7 +311,7 @@ if [ ${#files[@]} -eq 0 ] && [ ${#missing[@]} -eq 0 ]; then
307
311
  fi
308
312
 
309
313
  for f in ${missing[@]+"${missing[@]}"}; do
310
- printf '{"file":"%s","format":"none","error":"file not found","phase_raw":"","phase":"NONE","phase_alt_raw":"","phase_alt":"NONE","type":"","title":"","sprint":"","story":"","assignee":"","branches":[],"prs":[],"issues":[],"malformed_prs":[],"changelog":[],"long_wave_names":[],"unread_branch_headings":[],"unread_waits":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
314
+ printf '{"file":"%s","format":"none","error":"file not found","phase_raw":"","phase":"NONE","phase_alt_raw":"","phase_alt":"NONE","type":"","title":"","sprint":"","story":"","assignee":"","branches":[],"prs":[],"deferred_prs":[],"issues":[],"malformed_prs":[],"changelog":[],"long_wave_names":[],"unread_branch_headings":[],"unread_waits":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
311
315
  "$(printf '%s' "$f" | sed 's/\\/\\\\/g; s/"/\\"/g')"
312
316
  done
313
317
 
@@ -495,7 +499,7 @@ function reset_state() {
495
499
  block_rounds = ""
496
500
  in_fm = 0; section = ""; in_comment = 0; in_challenge = 0; in_fence = 0; slices_seen = 0; slice_shape = ""
497
501
  delete branches; n_branches = 0
498
- delete prs; n_prs = 0
502
+ delete prs; n_prs = 0; delete dprs; n_dprs = 0
499
503
  delete malformed_prs; n_malformed_prs = 0
500
504
  fm_issue = ""; canon_issue = ""
501
505
  delete issues; n_issues = 0
@@ -645,7 +649,7 @@ function emit_record( fmt, praw, palt_raw, traw, title, sprint, story, assigne
645
649
  for (i = 1; i <= nb; i++) out = out (i > 1 ? "," : "") "\"" jesc(sorted_b[i]) "\""
646
650
  out = out "],\"prs\":["
647
651
  for (i = 1; i <= np; i++) out = out (i > 1 ? "," : "") sorted_p[i]
648
- out = out "],\"issues\":["
652
+ out = out "],\"deferred_prs\":["; for (i = 1; i <= n_dprs; i++) out = out (i > 1 ? "," : "") (dprs[i] + 0); out = out "],\"issues\":["
649
653
  for (i = 1; i <= ni; i++) {
650
654
  # Numeric issues output as JSON numbers; string issues (Jira keys) as quoted.
651
655
  if (sorted_i[i] in issue_is_str)
@@ -1245,7 +1249,7 @@ section == "slices" && slice_shape != "heading" {
1245
1249
  while (match(line, /→ ([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+)?#[0-9]+/)) {
1246
1250
  p = substr(line, RSTART, RLENGTH)
1247
1251
  sub(/^.*#/, "", p)
1248
- prs[++n_prs] = p
1252
+ prs[++n_prs] = p; if ($0 ~ /<!--[ \t]*(deferred|moved)[ \t]*(:|-->)/) dprs[++n_dprs] = p
1249
1253
  line = substr(line, RSTART + RLENGTH)
1250
1254
  }
1251
1255
  # A near-miss is REPORTED, never silently dropped. `→#44` (no space) is the
@@ -1382,7 +1386,7 @@ section == "slices" && slice_shape == "heading" {
1382
1386
  if (match($0, /PR:[ \t]*#[0-9]+/)) {
1383
1387
  p = substr($0, RSTART, RLENGTH)
1384
1388
  sub(/^.*#/, "", p)
1385
- prs[++n_prs] = p
1389
+ prs[++n_prs] = p; if ($0 ~ /<!--[ \t]*(deferred|moved)[ \t]*(:|-->)/) dprs[++n_dprs] = p
1386
1390
  }
1387
1391
  next
1388
1392
  }
package/plot-pr-merged.sh CHANGED
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env bash
2
2
  # Plot helper: the ONE answer to "did the host merge ANY PR for this branch?"
3
3
  #
4
- # SOURCED, NOT RUN. `. "$script_dir/plot-pr-merged.sh"` defines `pr_merged`,
5
- # `pr_open` and `pr_merged_heads`; the file does nothing else on load. That is what makes sourcing it
4
+ # SOURCED, NOT RUN. `. "$script_dir/plot-pr-merged.sh"` defines `pr_merged` and
5
+ # `pr_open`; the file does nothing else on load. That is what makes sourcing it
6
6
  # safe, and it is the same shape — and the same reason — as
7
7
  # `plot-worker-state.sh`: the logic could not simply stay in `plot-reap.sh`,
8
8
  # because that file parses `$@` and `exit 2`s on an unknown argument at load
@@ -72,9 +72,8 @@
72
72
  #
73
73
  # AN EMPTY BRANCH IS NOT ASKED ABOUT. `gh pr list --head ""` applies no filter,
74
74
  # so every PR in the repository matches: measured 2026-10-01 on `origin/main`
75
- # (`56a978ea`), `_plot_merged_lookup ""` answered `found`, `pr_merged ""` exited
76
- # 0 — merged — and `pr_merged_heads ""` printed 98 lines, the head of every
77
- # merged PR here. So each of the three lookups refuses an empty branch BEFORE
75
+ # (`56a978ea`), `_plot_merged_lookup ""` answered `found` and `pr_merged ""`
76
+ # exited 0 — merged. So each of the two lookups refuses an empty branch BEFORE
78
77
  # `command -v gh`, answering `unaskable` rather than `none` because a lookup that
79
78
  # did not run is silence and `none` would claim the host spoke; `pr_open ""` then
80
79
  # casts no veto, which is safe only because `pr_merged ""` refuses on the same
@@ -193,31 +192,3 @@ pr_open() {
193
192
  answer=$(_plot_landed none "$(_plot_open_lookup "$1")") || return 1
194
193
  case "$answer" in *" open-pr") return 0 ;; *) return 1 ;; esac
195
194
  }
196
-
197
- # Which commits did the host merge for this branch? One `headRefOid` per merged
198
- # PR, one per line.
199
- #
200
- # A THIRD QUESTION, asked by `plot-reap.sh` only. After a squash merge the
201
- # host deletes the branch (`delete_branch_on_merge`), `git fetch --prune`
202
- # drops the remote-tracking ref, and the branch's own commits are then on no
203
- # remote ref at all. So "which commits did no remote ever hold?" needs the
204
- # head the host merged: a commit reachable from it was pushed; a commit beyond
205
- # it exists only on the desk.
206
- #
207
- # Returns 1 when the host cannot be asked. The caller reads that as
208
- # `unknown`, which keeps the desk: here a failure to observe is the case that
209
- # loses work. It prints nothing and returns 0 when the host answered and no PR
210
- # merged.
211
- pr_merged_heads() {
212
- local br="$1" out
213
- [ -n "$br" ] || return 1
214
- command -v gh >/dev/null 2>&1 || return 1
215
- out=$(gh pr list --head "$br" --state all --limit 100 --json mergedAt,headRefOid 2>/dev/null) \
216
- || return 1
217
- printf '%s' "$out" | node -e '
218
- let s = "";
219
- process.stdin.on("data", (d) => { s += d; }).on("end", () => {
220
- const rows = JSON.parse(s);
221
- for (const r of rows) if (r.mergedAt && r.headRefOid) console.log(r.headRefOid);
222
- });' 2>/dev/null || return 1
223
- }
package/plot-tmp.sh CHANGED
@@ -85,10 +85,16 @@ _plot_tmp_create() {
85
85
  trap '__plot_tmp_pending="TERM 15"' TERM
86
86
  trap '__plot_tmp_pending="PIPE 13"' PIPE
87
87
  fi
88
+ # `mktemp` IGNORES THE GROUP SIGNAL. It is a process of its own in the
89
+ # script's group, and the handlers above do not reach it: a group TERM after
90
+ # it creates the path and before it prints the name ends it, and the name
91
+ # never reaches the registry. CI run 38169324238 left one
92
+ # `plot-host-prlist-err.*` this way (#1582). Ignored signals pass to the child,
93
+ # so it always prints the name; this shell still records the signal.
88
94
  if [ "${3:-}" = -d ]; then
89
- __plot_tmp_new=$(mktemp -d "${TMPDIR:-/tmp}/plot-$2.XXXXXX")
95
+ __plot_tmp_new=$(trap '' INT TERM PIPE; mktemp -d "${TMPDIR:-/tmp}/plot-$2.XXXXXX")
90
96
  else
91
- __plot_tmp_new=$(mktemp "${TMPDIR:-/tmp}/plot-$2.XXXXXX")
97
+ __plot_tmp_new=$(trap '' INT TERM PIPE; mktemp "${TMPDIR:-/tmp}/plot-$2.XXXXXX")
92
98
  fi
93
99
  __plot_tmp_rc=$?
94
100
  # THE PATH IS REGISTERED WHEN IT EXISTS, whatever the status says. bash 3.2
@@ -303,7 +303,7 @@ plot_pid_is_current() { # $1=pid $2=startedAt (ISO-8601) → 0 if current, 1 if
303
303
 
304
304
  # Convert the manifest's startedAt (ISO-8601) to epoch seconds.
305
305
  # `date -j -f` is macOS; `date -d` is GNU. Try both.
306
- if manifest_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$started" +%s 2>/dev/null); then
306
+ if manifest_epoch=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$started" +%s 2>/dev/null); then
307
307
  :
308
308
  elif manifest_epoch=$(date -d "$started" +%s 2>/dev/null); then
309
309
  :
@@ -330,11 +330,12 @@ plot_pid_is_current() { # $1=pid $2=startedAt (ISO-8601) → 0 if current, 1 if
330
330
  fi
331
331
 
332
332
  # A process that started BEFORE the manifest's startedAt is a reused pid.
333
- # A process that started AT or AFTER is the real worker. We allow 2 seconds
334
- # of slack for clock skew and rounding — the wrapper writes the pid and then
335
- # the manifest's awk stamps it; if the second ticks over in between, the
336
- # process appears to have started 1 second before the manifest says.
337
- local slack=2
333
+ # A process that started AT or AFTER is the real worker. The slack is 3 s:
334
+ # the wrapper writes the pid and then the manifest's awk stamps it, so the
335
+ # second can tick over in between, and procps on Linux reports a start 0.8 to
336
+ # 1.2 s early (`SKEW_MS` in `test/reconcile/own-process.mjs`). The stamp is
337
+ # UTC, so the macOS parse takes `-u`; without it the stamp read as local time.
338
+ local slack=3
338
339
  [ "$proc_epoch" -ge "$((manifest_epoch - slack))" ]
339
340
  }
340
341
 
@@ -1188,6 +1189,20 @@ plot_worker_task_state() { # $1=worktree $2=pr-fact → finished|waiting|stalled
1188
1189
  printf '%s' "$answer"
1189
1190
  }
1190
1191
 
1192
+ # Whether the loop `$2` at the desk `$1` is a free agent waiting for a hand-over:
1193
+ # `.plot-worker.freewait`, with leading and trailing whitespace removed, names
1194
+ # exactly that pid. A DECLARED DUPLICATE of `deskWaitsFree`: `plot_worker_state`
1195
+ # runs once per desk per fleet-scan pass, so it does not ask a bundle, and
1196
+ # `packages/domain/corpus/desk-waits-free.corpus.test.ts` holds the pair.
1197
+ plot_worker_waits_free() { # $1=worktree $2=pid → 0 when the record names $2
1198
+ local fw; [ -n "$2" ] && [ -f "$1/.plot-worker.freewait" ] && fw=$(<"$1/.plot-worker.freewait") || return 1
1199
+ fw="${fw#"${fw%%[![:space:]]*}"}"; [ "${fw%"${fw##*[![:space:]]}"}" = "$2" ]
1200
+ }
1201
+
1202
+ # `deskLoopAlive` and `deskWaitsFree` for the desk paths on stdin, one answer
1203
+ # line per desk (`board/plot-desk-loop.mjs`). Asked once per operator command.
1204
+ plot_desk_loops() { PLOT_MANIFEST_DIR="${PLOT_MANIFEST_DIR:-}" node "${_plot_wstate_config%/*}/board/plot-desk-loop.mjs" "$@"; }
1205
+
1191
1206
  # Classify the worker in a worktree.
1192
1207
  #
1193
1208
  # $1 = worktree path
@@ -1324,6 +1339,14 @@ plot_worker_state() { # $1=worktree $2=pr-fact → "state\tpid\tcode"
1324
1339
  # means — `stalled` for work only this machine holds, `waiting` for a
1325
1340
  # marker, `finished` for a desk that is clear — because the process has
1326
1341
  # nothing left to say. No exit file exists: the wrapper has not exited.
1342
+ #
1343
+ # A FREE AGENT WAITS HERE: its loop polls for a hand-over with no agent
1344
+ # beneath it, and `.plot-worker.freewait` names the loop's pid
1345
+ # (`deskWaitsFree`'s reading). That desk is occupied, so it reads `running`.
1346
+ # ONLY FOR A PID WHOSE OWNERSHIP IS PROVEN: `started_at` is set only when
1347
+ # the manifest's `startedAt` passed `plot_pid_is_current` above, so a
1348
+ # reused pid, or a pid from the bare pid file, never reads as a free agent.
1349
+ [ -n "$started_at" ] && plot_worker_waits_free "$wt" "$pid" && { printf 'running\t%s\t' "$pid"; return; }
1327
1350
  printf '%s\t%s\t' "$(plot_worker_task_state "$wt" "$has_pr")" "$pid"
1328
1351
  return
1329
1352
  fi