@plot-pm/board 0.24.0 → 0.26.0

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.
@@ -148,16 +148,14 @@ desk_dirt_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/plot-desk-dirt.sh"
148
148
  # `plot-desk-root.sh` does: `git worktree list` prints resolved paths, and a
149
149
  # directory composed from a logical one (`/tmp` against `/private/tmp` on macOS)
150
150
  # is a prefix no worktree path starts with.
151
+ #
152
+ # AN EXPORTED ANSWER IS TAKEN WHEN IT IS THIS DIRECTORY'S, and git is asked
153
+ # otherwise: see `plot_given_common_dir` (`plot-desk-root.sh`).
151
154
  plot_main_checkout_of() { # $1=directory → the main checkout, or "" (non-zero)
152
- local at="$1" common root=''
153
- [ -n "$at" ] && [ -d "$at" ] || return 1
154
- common=$(git -C "$at" rev-parse --git-common-dir 2>/dev/null) && [ -n "$common" ] && {
155
- common=$(cd -- "$at" 2>/dev/null && cd -- "$common" 2>/dev/null && pwd -P) || common=''
156
- [ -n "$common" ] && root=$(dirname -- "$common")
157
- }
158
- [ -n "$root" ] || root=$(git -C "$at" rev-parse --show-toplevel 2>/dev/null) || return 1
159
- [ -n "$root" ] || return 1
160
- printf '%s' "$root"
155
+ local at="$1" common
156
+ [ -n "$at" ] || return 1
157
+ common=$(plot_given_common_dir "$at") || { common=$(git -C "$at" rev-parse --git-common-dir 2>/dev/null) && common=$(cd -- "$at" && cd -- "$common" && pwd -P); } || return 1
158
+ printf '%s' "${common%/*}"
161
159
  }
162
160
 
163
161
  # The `Agent registry` directory for a main checkout — `manifestDirectory`'s rule.
@@ -179,9 +177,7 @@ plot_main_checkout_of() { # $1=directory → the main checkout, or "" (non-zero)
179
177
  # so leaving the variable unset would reintroduce #1086 one layer down.
180
178
  plot_manifest_dir_for() { # $1=main checkout → prints the directory
181
179
  local root="$1" dir=''
182
- if [ -x "$_plot_wstate_config" ] || [ -r "$_plot_wstate_config" ]; then
183
- dir=$(PLOT_REPO_ROOT="$root" bash "$_plot_wstate_config" get "Agent registry" "" 2>/dev/null) || dir=''
184
- fi
180
+ dir=$(PLOT_REPO_ROOT="$root" bash "$_plot_wstate_config" get "Agent registry" "" 2>/dev/null) || dir=''
185
181
  # Whitespace alone is a key nobody filled in.
186
182
  dir=$(printf '%s' "$dir" | tr -d '[:space:]')
187
183
  [ -n "$dir" ] || dir=".plot/agents"
@@ -196,6 +192,7 @@ plot_manifest_dir_for() { # $1=main checkout → prints the directory
196
192
  # resolves its own bundle: reading `BASH_SOURCE[0]` inside a function reads the
197
193
  # CALLER's file once the function has been exported.
198
194
  _plot_wstate_config="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/plot-config.sh"
195
+ . "${_plot_wstate_config%/*}/plot-desk-root.sh"
199
196
 
200
197
  # THE DIRECTORY IS RESOLVED AT SOURCE TIME, AND THAT IS NOT A STYLE CHOICE.
201
198
  # Both callers invoke the lookup as `manifest=$(plot_manifest_for_worktree …)`,
@@ -205,13 +202,16 @@ _plot_wstate_config="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/plot-co
205
202
  #
206
203
  # A CALLER-SET VALUE WINS and is never overwritten: the dispatcher and the tests
207
204
  # set it, and they know their repo root without being asked.
208
- if [ -z "$PLOT_MANIFEST_DIR" ]; then
209
- _plot_wstate_root=$(plot_main_checkout_of "$PWD" 2>/dev/null) || _plot_wstate_root=''
210
- if [ -n "$_plot_wstate_root" ]; then
211
- PLOT_MANIFEST_DIR=$(plot_manifest_dir_for "$_plot_wstate_root")
212
- fi
213
- unset _plot_wstate_root
205
+ #
206
+ # THE COMMON DIR IS EXPORTED for every process this one starts: a child that
207
+ # sources this file in a worktree of the same repository reads it and asks git
208
+ # nothing (`plot_given_common_dir`). Each dispatch launch blanks it, so an agent
209
+ # asks for itself.
210
+ if [ -z "$PLOT_MANIFEST_DIR" ] && _plot_wstate_root=$(plot_main_checkout_of "$PWD" 2>/dev/null); then
211
+ export PLOT_GIT_COMMON_DIR="$_plot_wstate_root/.git"
212
+ PLOT_MANIFEST_DIR=$(plot_manifest_dir_for "$_plot_wstate_root")
214
213
  fi
214
+ unset _plot_wstate_root
215
215
 
216
216
  # Find the manifest for a worktree → the full path, or "" (non-zero).
217
217
  #
@@ -297,7 +297,7 @@ plot_read_manifest_pid() { # $1=manifest path → "pid\tstartedAt\tpidStartedAt"
297
297
  # `plot_pid_is_current` compares — the live process's start and a pid's own
298
298
  # recorded start use the same `ps -o lstart` shape.
299
299
  _plot_lstart_epoch() { # $1=ps -o lstart= text → epoch seconds, or "" (non-zero)
300
- date -j -f "%a %b %d %H:%M:%S %Y" "$1" +%s 2>/dev/null \
300
+ LC_ALL=C date -j -f "%a %b %d %H:%M:%S %Y" "$1" +%s 2>/dev/null \
301
301
  || date -j -f "%c" "$1" +%s 2>/dev/null \
302
302
  || date -d "$1" +%s 2>/dev/null
303
303
  }
@@ -344,10 +344,11 @@ _plot_pid_readings() { # $1=worktree → "pid\tstartedAt\tpidStartedAt" (pid emp
344
344
  # for an uncheckable pid is "unknown", which the caller turns into `ended`.
345
345
  plot_pid_is_current() { # $1=pid $2=startedAt (ISO-8601) $3=pidStartedAt (ps -o lstart text, optional) → 0 if current, 1 if stale
346
346
  local pid="$1" started="$2" pid_started="${3:-}" proc_start manifest_epoch proc_epoch recorded_epoch slack=3
347
+ local iso='^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$'
347
348
 
348
349
  # Get the process's start time from `ps -o lstart=`. This is portable across
349
350
  # macOS and Linux, though the format differs.
350
- proc_start=$(ps -o lstart= -p "$pid" 2>/dev/null | tr -d '\n')
351
+ proc_start=$(LC_ALL=C ps -o lstart= -p "$pid" 2>/dev/null | tr -d '\n')
351
352
  [ -n "$proc_start" ] || return 1 # Process does not exist.
352
353
  proc_epoch=$(_plot_lstart_epoch "$proc_start") || return 1 # Cannot parse; treat as stale.
353
354
 
@@ -363,8 +364,11 @@ plot_pid_is_current() { # $1=pid $2=startedAt (ISO-8601) $3=pidStartedAt (ps -o
363
364
  # ONE-SIDED fallback: no per-pid start recorded. Convert the manifest's
364
365
  # startedAt (ISO-8601) to epoch seconds. `date -j -f` is macOS; `date -d` is
365
366
  # GNU. Try both.
366
- manifest_epoch=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$started" +%s 2>/dev/null || date -d "$started" +%s 2>/dev/null) \
367
- || return 1 # Cannot parse; treat as stale to be safe.
367
+ # ONLY THE DISPATCHER'S OWN STAMP IS READ, as `pidIsCurrent` reads it: GNU
368
+ # `date -d` also reads free text such as `yesterday`, which BSD `date` and
369
+ # the rule read as stale (decided 2026-11-09, jwloka).
370
+ [[ "$started" =~ $iso ]] && manifest_epoch=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$started" +%s 2>/dev/null || date -d "$started" +%s 2>/dev/null) \
371
+ || return 1 # Not an ISO stamp, or cannot parse; treat as stale to be safe.
368
372
 
369
373
  # A process that started BEFORE the manifest's startedAt is a reused pid.
370
374
  # A process that started AT or AFTER is the real worker. The slack is 3 s:
@@ -406,32 +410,6 @@ PLOT_EDITOR_LEFTOVER='\.(tmp[0-9]*|swp|orig|rej|bak)$'
406
410
  # can hold; what it is not is a directory nobody will ever commit.
407
411
  PLOT_TOOL_SCRATCH='(^|/)\.(playwright-mcp|plot/agents|plot/state|omc/state)(/|$)'
408
412
 
409
- # Where the worker's log lives in this worktree, when one is there at all.
410
- #
411
- # THIS FILE OWNS THE RECORD'S FILENAMES, and that ownership is enforced rather
412
- # than merely intended: `workerstate.test.mjs` asserts that plot-fleet-scan.sh
413
- # never names `.plot-worker.` itself, because a read-only scan that touches the
414
- # worker record has started classifying workers again — the duplication removed
415
- # on 2026-08-18, after the two copies had already drifted.
416
- #
417
- # So the caller that needs the log's mtime asks for the PATH and reads the time
418
- # itself. The split is the same one this whole file draws: what Plot's records
419
- # are called is knowledge that lives here; what a timestamp MEANS is the
420
- # caller's question. `changed_ago_of` in plot-fleet-scan.sh is the one consumer
421
- # — the log is the only source that keeps moving while a build runs, so a
422
- # measurement of "when did anything last change" that could not see it would
423
- # report every worker mid-suite as maximally quiet.
424
- #
425
- # ABSENT IS ABSENT: no worktree, or no log in it, prints nothing and returns
426
- # non-zero. plot-dispatch writes the log only where it started the worker
427
- # itself, so a hand-started worker legitimately has none.
428
- plot_worker_log() { # $1=worktree → path to the worker log, or "" (non-zero)
429
- local wt="$1"
430
- [ -n "$wt" ] || return 1
431
- [ -e "$wt/.plot-worker.log" ] || return 1
432
- printf '%s' "$wt/.plot-worker.log"
433
- }
434
-
435
413
  # Is a person being waited on inside this worktree?
436
414
  #
437
415
  # A MARKER FILE IN THE TREE, NOT A STRING IN A FILE. A blocked worker writes a
@@ -466,14 +444,9 @@ plot_worker_log() { # $1=worktree → path to the worker log, or "" (non-zero)
466
444
  # so this does not bite in production; it is recorded here rather than papered
467
445
  # over, because the honest state is "correct under the callers' shell, noisy
468
446
  # under a shell no caller uses" — not "identical under both".
469
- plot_worker_blocked() { # $1=worktree → 0 when a person owes this branch an answer
470
- local wt="$1" f
471
- [ -n "$wt" ] && [ -d "$wt" ] || return 1
472
- for f in "$wt"/PLOT-BLOCKED*; do
473
- [ -e "$f" ] && return 0
474
- done
475
- return 1
476
- }
447
+ #
448
+ # ONE GLOB: the answer is whether `plot_worker_blocked_file` below names a file.
449
+ plot_worker_blocked() { plot_worker_blocked_file "$1" >/dev/null; } # $1=worktree → 0 when a person owes this branch an answer
477
450
 
478
451
  # WHICH file carries the question — the basename, for a caller that must name it.
479
452
  #
@@ -543,9 +516,7 @@ plot_worker_dirty() { # $1=worktree → the dirty files, one per line, leftovers
543
516
  # Best-effort: a desk that cannot take the line still works. Always returns 0.
544
517
  plot_desk_exclude() { # $1=worktree $2=the exact line to exclude
545
518
  local common excl
546
- common=$(git -C "$1" rev-parse --git-common-dir 2>/dev/null) || return 0
547
- [ -n "$common" ] || return 0
548
- case "$common" in /*) ;; *) common="$1/$common" ;; esac
519
+ common=$(plot_given_common_dir "$1" || git -C "$1" rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || return 0
549
520
  excl="$common/info/exclude"
550
521
  mkdir -p "$common/info" 2>/dev/null || return 0
551
522
  grep -qxF "$2" "$excl" 2>/dev/null || printf '%s\n' "$2" >> "$excl" 2>/dev/null || true
@@ -668,12 +639,7 @@ plot_worker_tree_quiet_seconds() { # $1=worktree → seconds | unreadable
668
639
  # THE SAME FILTER THE FINGERPRINT USED, for the same reason: this script's own
669
640
  # records and the monitor's findings file are not work an agent left, and a
670
641
  # raw status would make the monitor watch itself.
671
- paths=''
672
- if command -v plot_worker_dirty_filter >/dev/null 2>&1; then
673
- paths=$(plot_worker_dirty_filter "$status")
674
- else
675
- paths=$(printf '%s' "$status" | cut -c4-)
676
- fi
642
+ paths=$(plot_worker_dirty_filter "$status")
677
643
 
678
644
  # Every path to stat, one per line, absolute. Built in awk rather than a bash
679
645
  # loop so a desk holding hundreds of dirty paths costs one fork.
@@ -794,26 +760,16 @@ plot_worker_tree_quiet_seconds() { # $1=worktree → seconds | unreadable
794
760
  # question each withhold the finding, because a failure to observe is not
795
761
  # evidence of something to see.
796
762
  plot_worker_idle_now() { # $1..$7 as above → idle | silent
797
- local pid="$1" spoken="$2" silence="$3" activity="$4" tree="$5" commits="$6" window="$7"
798
-
799
- [ "$pid" = 'alive' ] || { printf 'silent'; return 0; }
800
- [ "$spoken" = '1' ] || { printf 'silent'; return 0; }
801
-
763
+ local pid="$1" spoken="$2" silence="$3" activity="$4" tree="$5" commits="$6" window="$7" num='^[0-9]+$'
802
764
  # A non-numeric duration is a reading that was not taken. `unavailable`,
803
- # `unreadable` and an empty string all land here, and so would a filesystem
765
+ # `unreadable` and an empty string answer `silent`, and so would a filesystem
804
766
  # report that slipped past the validation above.
805
- case "$window" in ''|*[!0-9]*) printf 'silent'; return 0 ;; esac
806
- case "$silence" in ''|*[!0-9]*) printf 'silent'; return 0 ;; esac
807
- [ "$silence" -ge "$window" ] || { printf 'silent'; return 0; }
808
-
809
- [ "$activity" = 'working' ] && { printf 'silent'; return 0; }
810
-
811
- case "$tree" in ''|*[!0-9]*) printf 'silent'; return 0 ;; esac
812
- [ "$tree" -ge "$window" ] || { printf 'silent'; return 0; }
813
-
814
- [ "$commits" = 'yes' ] || { printf 'silent'; return 0; }
815
- printf 'idle'
816
- return 0
767
+ if [ "$pid" = 'alive' ] && [ "$spoken" = '1' ] && [[ "$window" =~ $num && "$silence" =~ $num && "$tree" =~ $num ]] \
768
+ && [ "$silence" -ge "$window" ] && [ "$activity" != 'working' ] && [ "$tree" -ge "$window" ] && [ "$commits" = 'yes' ]; then
769
+ printf 'idle'
770
+ else
771
+ printf 'silent'
772
+ fi
817
773
  }
818
774
 
819
775
  # ---------------------------------------------------------------------------
@@ -861,8 +817,7 @@ plot_worker_has_commits() { # $1=worktree → 0 yes | 1 no | 2 unanswerable
861
817
  # empty marker of its own is correctly not counted as work either.
862
818
  n=$(git -C "$wt" rev-list --count "$base..HEAD" -- . 2>/dev/null) || return 2
863
819
  case "$n" in ''|*[!0-9]*) return 2 ;; esac
864
- [ "$n" -gt 0 ] && return 0
865
- return 1
820
+ [ "$n" -gt 0 ]
866
821
  }
867
822
 
868
823
  # The total CPU time, in centiseconds, of a pid and every process descended from
@@ -1194,6 +1149,24 @@ plot_worker_waits_free() { # $1=worktree $2=pid → 0 when the record names $2
1194
1149
  # line per desk (`board/plot-desk-loop.mjs`). Asked once per operator command.
1195
1150
  plot_desk_loops() { PLOT_MANIFEST_DIR="${PLOT_MANIFEST_DIR:-}" node "${_plot_wstate_config%/*}/board/plot-desk-loop.mjs" "$@"; }
1196
1151
 
1152
+ # A held liveness token outranks an exit record of 128 or more → 0 when it does.
1153
+ #
1154
+ # `workerLiveness`'s order, held to it by `worker-readings.corpus.test.ts`: a
1155
+ # wrapper whose loop was killed records 128 plus the signal while the harness
1156
+ # the loop started still holds the token. The desk reads `stray-holder` until
1157
+ # `Worker bound` from `startedAt`; a code below 128 keeps its exit arm. Perl
1158
+ # reads the token as `livenessTokenFifo` does: an `lstat` FIFO opened
1159
+ # `O_RDONLY | O_NONBLOCK` is held on `EAGAIN` and released on end-of-file.
1160
+ _plot_stray_holder() { # $1=worktree $2=exit code $3=startedAt (ISO-8601, optional)
1161
+ local bound="${PLOT_WORKER_BOUND:-}" started
1162
+ [[ "$2" =~ ^[0-9]+$ ]] && [ "$2" -ge 128 ] || return 1
1163
+ perl -MFcntl -e 'lstat($ARGV[0]) && -p _ && sysopen(F, $ARGV[0], O_RDONLY | O_NONBLOCK) or exit 2; exit(defined(sysread(F, $b, 1)) ? 1 : $!{EAGAIN} ? 0 : 2)' "$1/.plot-worker.token.fifo" 2>/dev/null || return 1
1164
+ [ -n "$3" ] && started=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$3" +%s 2>/dev/null || date -d "$3" +%s 2>/dev/null) || return 0
1165
+ [[ "$bound" =~ ^[0-9]+$ ]] || bound=$(PLOT_REPO_ROOT="$(plot_main_checkout_of "$1")" bash "$_plot_wstate_config" get "Worker bound" "" 2>/dev/null)
1166
+ [[ "$bound" =~ ^[0-9]+$ ]] || bound=28800
1167
+ [ "$bound" -eq 0 ] || [ $(($(date +%s) - started)) -lt "$bound" ]
1168
+ }
1169
+
1197
1170
  # Classify the worker in a worktree.
1198
1171
  #
1199
1172
  # $1 = worktree path
@@ -1383,7 +1356,8 @@ plot_worker_state() { # $1=worktree $2=pr-fact → "state\tpid\tcode"
1383
1356
  # `failed` — the guess in the other direction, calling a genuine crash
1384
1357
  # finished, is the one this must never make. A PR is the fact that
1385
1358
  # licenses it, because a PR means the work reached a reviewer.
1386
- *) if [ "$has_pr" = pr ]; then
1359
+ *) _plot_stray_holder "$wt" "$code" "$started_at" && { printf 'running\t%s\t' "$pid"; return; }
1360
+ if [ "$has_pr" = pr ]; then
1387
1361
  printf '%s\t%s\t%s' "$(plot_worker_task_state "$wt" "$has_pr")" "$pid" "$code"
1388
1362
  else
1389
1363
  printf 'failed\t%s\t%s' "$pid" "$code"
@@ -1417,18 +1391,19 @@ plot_worker_state() { # $1=worktree $2=pr-fact → "state\tpid\tcode"
1417
1391
  # and the same dirty filter. A second gathering that drifted would make the
1418
1392
  # corpus test compare this file against itself and pass while production broke.
1419
1393
  #
1420
- # Prints one TAB-separated line, six fields:
1394
+ # Prints one TAB-separated line, eight fields:
1421
1395
  #
1422
- # worktree_here pid_recorded liveness exit blocked dirty unpushed
1396
+ # worktree_here pid_recorded liveness exit blocked dirty unpushed free_wait
1423
1397
  #
1424
- # `liveness` is `live`, `stale`, `orphaned` or `dead` — `orphaned` being a pid
1398
+ # `liveness` is `live`, `stale`, `orphaned`, `stray-holder` or `dead` — `stray-holder`
1399
+ # being a dead pid whose exit record yields to a held token, `orphaned` being a pid
1425
1400
  # that answers with no agent process under it, which is a live wrapper whose
1426
1401
  # agent has gone; `exit` is the code as read, empty for
1427
1402
  # an unreadable record and the literal `-` for an absent one, because an empty
1428
1403
  # field cannot say which of the two it is and the rule answers them alike only
1429
1404
  # because it was told they differ. The PR fact is NOT here: it comes from the
1430
1405
  # caller, exactly as it does for `plot_worker_state`.
1431
- plot_worker_readings() { # $1=worktree → "here\tpid\tliveness\texit\tblocked\tdirty\tunpushed"
1406
+ plot_worker_readings() { # $1=worktree → "here\tpid\tliveness\texit\tblocked\tdirty\tunpushed\tfree_wait"
1432
1407
  local wt="$1" pid="" started_at="" pid_started_at="" manifest_data=""
1433
1408
  local here=1 pid_recorded=0 liveness=dead exit_field='-' blocked=0 dirty=0 ahead=""
1434
1409
 
@@ -1437,7 +1412,7 @@ plot_worker_readings() { # $1=worktree → "here\tpid\tliveness\texit\tblocked\t
1437
1412
  # `plot-fleet-scan.sh`, where `elsewhere` is decided before this file is
1438
1413
  # reached. A caller iterating worktrees it found never sees this arm.
1439
1414
  if [ -z "$wt" ] || [ ! -d "$wt" ]; then
1440
- printf '0\t0\tdead\t-\t0\t0\t'
1415
+ printf '0\t0\tdead\t-\t0\t0\t\t0'
1441
1416
  return
1442
1417
  fi
1443
1418
 
@@ -1493,6 +1468,7 @@ plot_worker_readings() { # $1=worktree → "here\tpid\tliveness\texit\tblocked\t
1493
1468
  if [ -f "$wt/.plot-worker.exit" ]; then
1494
1469
  exit_field=$(cat "$wt/.plot-worker.exit" 2>/dev/null | tr -d ' \n')
1495
1470
  fi
1471
+ [ "$liveness$pid_recorded" = dead1 ] && _plot_stray_holder "$wt" "$exit_field" "$started_at" && liveness=stray-holder
1496
1472
 
1497
1473
  plot_worker_blocked "$wt" && blocked=1 || blocked=0
1498
1474
  [ -n "$(plot_worker_dirty "$wt")" ] && dirty=1 || dirty=0
@@ -1501,6 +1477,6 @@ plot_worker_readings() { # $1=worktree → "here\tpid\tliveness\texit\tblocked\t
1501
1477
  # cannot be asked at all.
1502
1478
  ahead=$(git -C "$wt" rev-list --count '@{upstream}..HEAD' 2>/dev/null) || ahead=""
1503
1479
 
1504
- printf '%s\t%s\t%s\t%s\t%s\t%s\t%s' \
1505
- "$here" "$pid_recorded" "$liveness" "$exit_field" "$blocked" "$dirty" "$ahead"
1480
+ printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s' \
1481
+ "$here" "$pid_recorded" "$liveness" "$exit_field" "$blocked" "$dirty" "$ahead" "$([ -n "$started_at" ] && plot_worker_waits_free "$wt" "$pid" && echo 1 || echo 0)"
1506
1482
  }