@plot-pm/board 0.25.0 → 0.27.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.
package/plot-dispatch.sh CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env bash
2
2
  # Plot helper: hand one slice + its brief to the registry per eligible branch.
3
3
  # Usage: plot-dispatch.sh [--dry-run] [--no-start] [--no-brief] [--offline]
4
- # [--max N] [--allow-local] <slug>
4
+ # [--max N] [--branch <br>] [--allow-local] <slug>
5
5
  # plot-dispatch.sh --start [N] [--dry-run]
6
6
  # plot-dispatch.sh --migrate [--yes] [--max N]
7
7
  # plot-dispatch.sh --release <branch>
@@ -44,10 +44,6 @@
44
44
  # config — without one there is no destination. --dry-run by
45
45
  # default; --yes to actually move.
46
46
  # --dry-run print what would happen; create nothing, push nothing
47
- # --monitors with --dry-run, also name which monitors would be attached to
48
- # which worktree. Opt-in so the default --dry-run output stays
49
- # byte-identical, which is what lets it be diffed against a run
50
- # from before a change to this script.
51
47
  # --yes with --migrate, actually move the worktrees (default is dry-run)
52
48
  # --no-start record that no worker was wanted: the run still hands its slices
53
49
  # over, and reports `worker=suppressed` rather than a missing
@@ -90,6 +86,8 @@
90
86
  # written when the plan was drafted. A charter this clone does
91
87
  # not hold is REPORTED and dispatched anyway; see
92
88
  # `plan_declared_agent`.
89
+ # --branch <br> hand over only <br>, one branch of the plan; any other
90
+ # eligible branch is left in the queue.
93
91
  # <slug> the plan to fan out
94
92
  # Output: one line per branch, each optionally followed by an indented
95
93
  # `in flight:` line naming a branch that already holds files, then the
@@ -275,7 +273,6 @@ worktree_holding_branch() { # $1=branch → the first desk holding it, or nothin
275
273
  }
276
274
 
277
275
  dry_run=0
278
- show_monitors=0
279
276
  no_start=0
280
277
  no_brief=0
281
278
  mode=dispatch
@@ -297,16 +294,6 @@ agent=""
297
294
  while [ $# -gt 0 ]; do
298
295
  case "$1" in
299
296
  --dry-run) dry_run=1 ;;
300
- # --monitors NAMES what would be attached, and it is OPT-IN for a reason
301
- # that is a protection rather than a preference. `plot-dispatch.sh` is the
302
- # largest script here and a mistake in start_worker starts no workers at
303
- # all, so this slice pins `--dry-run` output as BYTE-IDENTICAL before and
304
- # after on the same estate — the dry run exercises every refusal against
305
- # real worktrees and real pids without starting or removing anything, which
306
- # is the same protection the reap and dispatch domain work used. A line
307
- # added to the default output would forfeit exactly that check. So the
308
- # naming lives behind its own flag: `--dry-run --monitors`.
309
- --monitors) show_monitors=1 ;;
310
297
  --status) mode=status ;;
311
298
  --migrate) mode=migrate ;;
312
299
  --yes) migrate_yes=1 ;;
@@ -355,6 +342,8 @@ while [ $# -gt 0 ]; do
355
342
  -*) echo "plot-dispatch: --agent needs a charter name, got '$agent'" >&2; exit 1 ;;
356
343
  esac
357
344
  shift ;;
345
+ # `--branch <br>` hands over that one branch of the plan and no other.
346
+ --branch) only_branch="${2:?--branch needs a branch name}"; shift ;;
358
347
  --max) max="${2:?--max needs a value}"
359
348
  case "$max" in
360
349
  ''|*[!0-9]*) echo "plot-dispatch: --max needs a number, got '$max'" >&2; exit 1 ;;
@@ -363,10 +352,10 @@ while [ $# -gt 0 ]; do
363
352
  # THE RANGE MOVED WITH THE HEADER IT PRINTS. It ended at `<slug>` and still
364
353
  # does; adding `--agent` above pushed that line from 59 to 69, and
365
354
  # documenting the plan-declared kind pushed it from 69 to 78, and
366
- # `--release` pushed it from 78 to 91. Two records
355
+ # `--release` pushed it from 78 to 91, and `--branch` from 89 to 91. Two records
367
356
  # of one fact, and nothing compares them — a stale number here silently
368
357
  # truncates the help rather than failing, so it is checked by a test.
369
- -h|--help) sed -n '2,93p' "$0"; exit 0 ;;
358
+ -h|--help) sed -n '2,91p' "$0"; exit 0 ;;
370
359
  *) slug="$1" ;;
371
360
  esac
372
361
  shift
@@ -487,7 +476,7 @@ write_agent_manifest() { # $1=path $2=session $3=branch $4=worktree $5=command
487
476
  printf ' "worktree": "%s",\n' "$(json_escape "$4")"
488
477
  printf ' "command": "%s",\n' "$(json_escape "$5")"
489
478
  printf ' "pid": "",\n'
490
- printf ' "attempts": 0,\n'
479
+ printf ' "attempts": 0,\n "agentProcess": "%s",\n' "$(json_escape "${PLOT_AGENT_PROCESS:-claude}")"
491
480
  printf ' "startedAt": "%s"\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
492
481
  printf '}\n'
493
482
  } > "$tmp" 2>/dev/null || { rm -f "$tmp"; return 1; }
@@ -548,7 +537,10 @@ write_agent_manifest() { # $1=path $2=session $3=branch $4=worktree $5=command
548
537
  # because a person will look either way): here the cost of guessing wrong is an
549
538
  # agent burning minutes on nothing.
550
539
  brief_path() { printf '.plot/briefs/%s.md' "${1##*/}"; }
551
- brief_ref() { printf 'origin/%s:%s' "$MAIN" "$(brief_path "$1")"; }
540
+ # The ref a path's records are read at: `origin/<main>`, or where `State branch`
541
+ # is declared the ref the domain's `recordRef` names (`board/plot-record-ref.mjs`).
542
+ rec_ref() { [ -n "${STATE_KEY:-}" ] && node "$script_dir/board/plot-record-ref.mjs" "$STATE_KEY" "$MAIN" "$1" 2>/dev/null || printf 'origin/%s' "$MAIN"; }
543
+ brief_ref() { printf '%s:%s' "$(rec_ref "$(brief_path "$1")")" "$(brief_path "$1")"; }
552
544
  brief_present() { # $1 = branch → 0 if a usable brief exists on origin/<main>
553
545
  local sz
554
546
  sz=$(git cat-file -s "$(brief_ref "$1")" 2>/dev/null) || return 1
@@ -836,7 +828,7 @@ request_brief() { # $1 = branch, $2 = slug → 0 if a command was started
836
828
  export PLOT_SPAWN_CONTRACT="$(node "$script_dir/board/plot-prompt.mjs" --background-gate 2>/dev/null | sed -n "s/^export PLOT_SPAWN_CONTRACT='\\(.*\\)'$/\\1/p")"
837
829
  ( set -m; cd "$repo_root" \
838
830
  && PLOT_UNATTENDED=1 PLOT_MAIN_CHECKOUT_WRITER=1 PLOT_PLAN_SLUG="$bslug" PLOT_BRIEF_BRANCH="$branch" \
839
- PLOT_AGENT_SETTINGS="$_brief_settings" \
831
+ PLOT_AGENT_SETTINGS="$_brief_settings" PLOT_GIT_COMMON_DIR= \
840
832
  exec nohup sh -c "$cmd \"\$@\"" plot-brief \
841
833
  "$(brief_prompt "$branch" "$bslug")" \
842
834
  >"$log" 2>&1 </dev/null & ) >/dev/null 2>&1 </dev/null
@@ -873,7 +865,7 @@ brief_staleness_note() { # $1 = branch → prints a hint, or nothing
873
865
  local branch="$1" bc pc bs ps
874
866
  [ -n "$gate_sha" ] || return 0 # nothing shared to compare against
875
867
  [ -n "${plan_path:-}" ] || return 0
876
- bc=$(git log -1 --format='%H %ct' "$gate_ref" -- "$(brief_path "$branch")" 2>/dev/null) || return 0
868
+ bc=$(git log -1 --format='%H %ct' "$(rec_ref "$(brief_path "$branch")")" -- "$(brief_path "$branch")" 2>/dev/null) || return 0
877
869
  pc=$(git log -1 --format='%H %ct' "$gate_ref" -- "$plan_path" 2>/dev/null) || return 0
878
870
  [ -n "$bc" ] && [ -n "$pc" ] || return 0
879
871
  bs=${bc##* }; ps=${pc##* }
@@ -1128,7 +1120,7 @@ start_worker() {
1128
1120
  return 1
1129
1121
  fi
1130
1122
  local log="$wt/.plot-worker.log"
1131
- rm -f "$wt/.plot-worker.exit"
1123
+ rm -f "$wt/.plot-worker.exit" "$wt/.plot-worker.token.fifo"
1132
1124
 
1133
1125
  # THE MANIFEST, AND WHY IT IS KEYED ON A SESSION ID RATHER THAN A BRANCH.
1134
1126
  #
@@ -1228,141 +1220,15 @@ start_worker() {
1228
1220
  echo " key) and dispatch again."
1229
1221
  return 1
1230
1222
  fi
1231
- # TWO PIDS, TWO NAMES. `.plot-worker.pid` must name the AGENT — the process
1232
- # doing the work, which is what the panel, `--status` and the scan describe.
1233
- # `$!` from the parent names the `sh -c` WRAPPER, and recording that is the
1234
- # bug this fixes: every field read correctly off the dispatcher's shell rather
1235
- # than off the agent. The wrapper is the one thing that knows its own child,
1236
- # so the wrapper writes the agent's pid; only the wrapper can, and a `pgrep`
1237
- # by command string is the failure this repo already recorded (`wait on your
1238
- # own PID, not a process name`).
1239
- #
1240
- # The wrapper's own pid is KEPT, under `.plot-worker.wrapper.pid`, because the
1241
- # wrapper is what writes `.plot-worker.exit` when the agent exits and that must
1242
- # keep working — `--stop` kills the agent, the wrapper survives to record the
1243
- # code. The paths travel as env vars so no quoting level inside the
1244
- # single-quoted `sh -c` mangles a path with spaces, exactly as the exit file
1245
- # already does.
1246
- #
1247
- # AND THE WRAPPER WRITES IT ITSELF, from `$$` inside the `sh -c`. Until
1248
- # 2026-08-31 the dispatcher wrote `echo $!` beside the spawn, which named an
1249
- # intermediate subshell rather than the wrapper: three of three live workers
1250
- # measured that day recorded a pid one process above the agent's real parent
1251
- # (7357 against 7358, 71953 against 71954, 92947 against 92949).
1252
- #
1253
- # THE LAUNCH NOW ENDS IN `exec`, so the forked bash IS the wrapper: `$$`
1254
- # inside the `sh -c` and the pid bash forked name one process, and no process
1255
- # carrying the dispatcher's command line survives the launch. The wrapper
1256
- # reparents to init — measured 2026-10-01, its PPID is 1.
1257
- #
1258
- # `exec` is also what gives the caller its streams back. The outer subshell
1259
- # inherited the dispatcher's stdout, and the inner redirect applies to the
1260
- # backgrounded job alone, so a reader on a pipe waited for an EOF the forked
1261
- # bash held for as long as the agent lived: measured 2026-10-01, `--start 1`
1262
- # took 20.39 s through `| cat` against 1.12 s with `exec`. The subshell is
1263
- # redirected too, because `exec` alone leaves the wrapper holding that pipe.
1264
- #
1265
- # So the same rule the agent pid already follows applies here: THE PROCESS
1266
- # THAT KNOWS A PID IS THE ONE THAT WRITES IT. The wrapper knows `$$`; no
1267
- # ancestor can name it without guessing. It is written FIRST, before the
1268
- # monitors and the agent, so the file exists as early as it can.
1269
- #
1270
- # The agent runs backgrounded inside the wrapper so the wrapper can capture its
1271
- # `$!` and `wait` for it. There is a sub-millisecond window after the wrapper
1272
- # starts and before it writes `.plot-worker.pid`; a scan landing in it reads an
1273
- # absent pid file as `none` — honest, never "running" off a stale value.
1274
- #
1275
- # THE WRAPPER ALSO STAMPS THE MANIFEST PID, for the same reason it writes the
1276
- # pid file: it is the one process that knows the agent's own pid. The manifest
1277
- # path travels as `PLOT_MANIFEST_FILE`, beside the exit/pid paths, so no quoting
1278
- # level inside the single-quoted `sh -c` mangles a path with spaces. The stamp
1279
- # is inline `awk` rather than a bash helper, because a helper would live in this
1280
- # bash script and the detached `sh -c` is a fresh shell with no access to it —
1281
- # the same isolation that makes the wrapper own the pid.
1282
- #
1283
- # ONE CONTRACT, TWO IMPLEMENTATIONS. This inline `awk` is the mechanical twin of
1284
- # `manifest-stamp.ts`'s `stampManifest`; `/api/continue` calls that helper, and a
1285
- # parity test (`manifest-stamp-parity.test.ts`) runs THIS awk against the same
1286
- # inputs and asserts a byte-identical result. The two exist because the callers
1287
- # cannot share code — a detached `sh -c` reaches no TypeScript, and a bash helper
1288
- # is out of a fresh shell's reach — but they must not drift, the
1289
- # `plot-worker-state.sh` lesson after five of six states diverged in duplicate.
1290
- #
1291
- # It replaces ANY `pid` line, not only the empty placeholder — a full-line
1292
- # anchored match on bytes we control, so nothing in the command value (one
1293
- # escaped JSON string on its own line) can be mistaken for it. On a FIRST
1294
- # dispatch the placeholder is empty: the pid is filled and nothing else changes,
1295
- # byte-identical to the manifest before relaunch bookkeeping existed. On a
1296
- # RELAUNCH the line already holds a pid: it is overwritten, `startedAt` is
1297
- # rewritten to now, and two lines are inserted after `pid` — `previousPid` (the
1298
- # corpse displaced) and `relaunches` (the restart count, +1 from any it carried).
1299
- # The dispatcher mints a fresh session per launch so its own manifest is always a
1300
- # first stamp; the relaunch arms exist for parity with `/api/continue`, which
1301
- # reuses a worktree's existing manifest. A pid is digits, so no JSON escaping is
1302
- # needed. Rewritten through a temp file and `mv`, atomic like the original write.
1303
- # Any failure leaves the pid untouched — the registry reads an absent one as
1304
- # `unknown`.
1305
- #
1306
- # The awk reads the manifest TWICE — the same file passed as two arguments, so
1307
- # `FNR==NR` is the pre-scan. Pass one learns whether the pid is already filled
1308
- # (a relaunch) and the count any prior `relaunches` line held; pass two rewrites.
1309
- # This mirror of a two-pass read is what lets a SECOND relaunch increment rather
1310
- # than reset: the old count sits AFTER the pid line, so a single pass could not
1311
- # know it when it must emit the new `relaunches` immediately after `pid`.
1312
- #
1313
- # On the pid line: an empty placeholder is filled and nothing else changes (a
1314
- # first stamp, byte-identical to before); a filled pid is overwritten and the
1315
- # two relaunch records — `previousPid` then `relaunches` — are emitted right
1316
- # after it, then any stale copies of those lines are dropped and `startedAt` is
1317
- # rewritten to the current run. This is exactly `stampManifest`, line for line,
1318
- # which the parity test pins byte for byte.
1319
- #
1320
- # EVERY WORKER IS BORN MONITORED, AND THAT IS ENFORCED HERE OR NOWHERE.
1321
- #
1322
- # The AgentMonitor starts INSIDE the wrapper, as its child, immediately
1323
- # before the agent, watching the desk. The PROCESS is no longer a monitor's
1324
- # subject: since `bug/the-loop-reports-idle` the loop's own watcher judges `idle`
1325
- # (`board/plot-worker-loop.mjs`'s `idleVerdict`, built from the domain's
1326
- # `idleNow`), and the wrapper itself reports `gone`/`clear` after
1327
- # `wait "$agent"` returns, below.
1328
- #
1329
- # WHY INSIDE THE WRAPPER RATHER THAN BESIDE IT. The wrapper already outlives
1330
- # its agent by construction — it must, or there would be no exit code to
1331
- # write — so a child of it inherits that survival for free. Two processes
1332
- # started SIDE BY SIDE are independently mortal: the monitor could be killed
1333
- # or crash with nothing noticing, which is the failure being fixed one level
1334
- # up. `--stop` kills the agent; the monitors and the exit record survive it.
1335
- #
1336
- # WHY HERE RATHER THAN ANYWHERE ELSE. `start_worker` is the single path to a
1337
- # worker, which is what makes "every worker is born monitored" a gate rather
1338
- # than a rule: there is no other place to forget. Ask CLAUDE.md's test — *can
1339
- # you answer "did I attach a monitor?" without doing the work?* Here you
1340
- # cannot: no monitor start, no monitored worker, and a mutation test says so.
1341
- #
1342
- # ORDER, AND WHY IT IS THIS WAY ROUND. The monitors are backgrounded FIRST so
1343
- # they exist before their subject does; the agent is backgrounded next and
1344
- # `$!` is captured on the VERY NEXT command, because `$!` names the most
1345
- # recent background job and the pid file must name the AGENT. Starting a
1346
- # monitor between the agent and its `$!` would record a monitor's pid as the
1347
- # worker's — the panel bug the two-pid split already exists to prevent.
1348
- #
1349
- # THEY INHERIT THE STARTUP WINDOW RATHER THAN WIDENING IT. There is a
1350
- # sub-millisecond gap after the wrapper starts and before `.plot-worker.pid`
1351
- # is written, and a scan landing in it reads `none` — honest. The monitors
1352
- # start inside that same window; they must never turn an unwritten pid file
1353
- # into a finding of their own, which is why the no-op reads no pid at all and
1354
- # the next slice treats an absent pid file as *not yet*.
1355
- #
1356
- # THE PATHS TRAVEL AS ENV VARS, like every other path the wrapper needs. The
1357
- # `sh -c` body is single-quoted and a path with spaces would not survive
1358
- # interpolation into it — the same reason the exit, pid and manifest paths are
1359
- # passed this way. An EMPTY value means "not attached", which is what keeps a
1360
- # missing script from turning into `command not found` in a detached shell
1361
- # nobody is reading.
1362
- #
1363
- # A HAND-MADE WORKTREE GETS NEITHER, and that falls out rather than being
1364
- # enforced: this is the only code that starts a wrapper, and a worktree with
1365
- # no wrapper has nothing for a monitor to be a child of.
1223
+ # THE WRAPPER IS `board/plot-worker-wrapper.mjs`, one process per launch. It
1224
+ # writes its own pid to `.plot-worker.wrapper.pid`, starts the AgentMonitor as
1225
+ # its child, starts the agent as `bash -c "$cmd"`, ignores `SIGTERM` itself,
1226
+ # writes the agent's pid and `ps -o lstart=` text, and stamps the manifest
1227
+ # through `writeManifestStamp`. Once the agent ends it appends one
1228
+ # WorkerMonitor line (`gone` for a non-zero exit, `clear` for 0) to the
1229
+ # watched desk and writes the code to `.plot-worker.exit`. `--stop` kills the
1230
+ # agent, and the wrapper survives to record the code. The paths travel as env
1231
+ # vars, so a path with spaces needs no quoting.
1366
1232
  # WHAT THIS AGENT MAY TOUCH — `PLOT_CAPABILITIES`, AND WHY IT IS RESOLVED HERE.
1367
1233
  #
1368
1234
  # A charter's `capabilities` list is the one differentiation Plot can express
@@ -1424,58 +1290,23 @@ start_worker() {
1424
1290
  fi
1425
1291
  fi
1426
1292
 
1427
- local agent_monitor=''
1428
- [ -x "$script_dir/plot-agent-monitor.sh" ] && agent_monitor="$script_dir/plot-agent-monitor.sh"
1429
1293
  local stamp_now
1430
1294
  stamp_now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
1431
- # THE THREE NAMES THE CHARTER DECLARED, and they travel as env vars for the
1432
- # reason every other path here does: the `sh -c` body is single-quoted, so a
1433
- # value with spaces would not survive interpolation into it.
1434
- #
1435
- # EMPTY IS THE ESTATE TODAY and must stay indistinguishable from before. An
1436
- # agent with no charter exports three empty strings, a prompt file
1437
- # interpolating `${PLOT_MODEL:-}` gets nothing, and the command line is
1438
- # byte-identical to what it was — which is the 100% case, since zero charters
1439
- # exist. `PLOT_AGENT` is forwarded too, so the loop's own `resolve_prompt_file`
1440
- # asks about the same agent this launch resolved.
1441
- #
1442
- # `set -m` FIRST: THE AGENT LEADS ITS OWN PROCESS GROUP. With job control on,
1443
- # the backgrounded list below is a job, the job gets a group of its own, and
1444
- # `exec` keeps the job's pid, so the wrapper's pid IS its group id. A SIGKILL
1445
- # to the starter's group — `killGroup` in `run-script.ts` — then misses the
1446
- # agent, and `--stop` on one agent ends that wrapper's group and no sibling's.
1447
- # It goes in this bash subshell and never in the `sh -c` body: dash refuses
1448
- # `set -m` without a terminal.
1449
- #
1450
- # THE WRAPPER IGNORES SIGTERM, AND ONLY AFTER ITS CHILDREN EXIST. `--stop`
1451
- # signals this whole group, and the wrapper must outlive the agent to write
1452
- # `.plot-worker.exit` (`test/e2e/monitors-attached.test.mjs`). `trap "" TERM`
1453
- # comes after `agent=$!`, because an ignored signal is inherited by every child
1454
- # started after it: set earlier, the monitors and the agent would ignore the
1455
- # stop too. The wrapper then records the exit code and ends on its own.
1456
- #
1457
- # THE WRAPPER ALSO REPORTS `gone`/`clear` ITSELF, right after `wait "$agent"`
1458
- # returns inside the `sh -c` body below. It already knows the instant the
1459
- # agent ends, because it `wait`s on it — the same fact `workerAlive` reads in
1460
- # `rules/supervision.ts`. A non-zero exit (124, 137 for SIGKILL, anything
1461
- # else) appends `gone`; exit 0 appends `clear`, so a finished agent asks for
1462
- # no restart and no earlier `idle` stays the newest line. The appended line
1463
- # matches `publish()`'s own shape exactly (`monitor`, `branch`, `worktree`,
1464
- # `finding`, `since`, `evidence`, `measuredAt`, `monitor: "WorkerMonitor"`),
1465
- # so the board's reader cannot tell the difference. This replaces the
1466
- # WorkerMonitor process `bug/the-loop-reports-idle` removed — which published
1467
- # `gone` on ANY death of the watched pid, including an honest exit 0, where
1468
- # this reports `clear` instead.
1469
- #
1470
- # THE LINE LANDS IN THE WATCHED DESK, ASKED ONCE, RIGHT AFTER `wait "$agent"`
1471
- # RETURNS. `PLOT_WORKTREE` is fixed at launch, but a hop rewrites the
1472
- # manifest's `worktree` field before the agent exits — so the wrapper sources
1473
- # `plot-monitor-subject.sh` off `$PATH` (set further down, before the agent
1474
- # starts) and asks `plot_watched_desk` for the desk to write into, exactly
1475
- # once. Reading it once here, rather than threading `PLOT_WORKTREE` through
1476
- # the publish, is what keeps a killed hopped agent's `gone` line landing where
1477
- # the loop's watcher (and the board's reader) actually look.
1478
- ( set -m; cd "$wt" && \
1295
+ # `PLOT_HARNESS`, `PLOT_MODEL` and `PLOT_EFFORT` are the three names the
1296
+ # charter declared, and empty where it declared none. `PLOT_AGENT` is
1297
+ # forwarded, so the loop's own `resolve_prompt_file` asks about the agent
1298
+ # this launch resolved.
1299
+ #
1300
+ # `board/plot-worker-start.mjs` STARTS THE WRAPPER DETACHED AND EXITS. The
1301
+ # wrapper leads its own session and process group, so its pid is its group
1302
+ # id: `--stop`'s group signal reaches this desk's wrapper and agent and no
1303
+ # sibling desk's, and a SIGKILL to the starter's group (`killGroup` in
1304
+ # `run-script.ts`) misses the agent. The wrapper's output goes to `$log`, so
1305
+ # the caller's streams close when the start exits. A Node major other than
1306
+ # the one `.nvmrc` pins starts no wrapper, and this function reports the
1307
+ # refusal.
1308
+ local start_err
1309
+ if ! start_err=$( ( cd "$wt" && \
1479
1310
  # AN `export`, NOT AN ENV PREFIX, AND THE REASON IS A MEASUREMENT. Bash
1480
1311
  # recognises an assignment prefix BEFORE it expands parameters, so a
1481
1312
  # `${caps:+PLOT_CAPABILITIES="$caps"}` in the prefix below is not an
@@ -1491,7 +1322,7 @@ start_worker() {
1491
1322
  # the export reaches the wrapper and nothing else.
1492
1323
  { [ -n "$capabilities" ] && export PLOT_CAPABILITIES="$capabilities"; true; } && \
1493
1324
  PLOT_BRANCH="$branch" PLOT_WORKTREE="$wt" \
1494
- PLOT_SLUG="$slug" PLOT_MAIN_CHECKOUT_WRITER= \
1325
+ PLOT_SLUG="$slug" PLOT_MAIN_CHECKOUT_WRITER= PLOT_GIT_COMMON_DIR= \
1495
1326
  PLOT_SESSION_ID="$session" \
1496
1327
  PLOT_AGENT="${PLOT_AGENT:-}" \
1497
1328
  PLOT_HARNESS="$launch_harness" \
@@ -1499,48 +1330,16 @@ start_worker() {
1499
1330
  PLOT_EFFORT="$launch_effort" \
1500
1331
  PLOT_MANIFEST_FILE="$manifest_dir/$session.json" \
1501
1332
  PLOT_STAMP_STARTED="$stamp_now" \
1502
- PLOT_AGENT_MONITOR="$agent_monitor" \
1503
1333
  PLOT_EXIT_FILE="$wt/.plot-worker.exit" PLOT_PID_FILE="$wt/.plot-worker.pid" \
1504
1334
  PLOT_PID_STARTED_FILE="$wt/.plot-worker.pid.startedAt" \
1505
1335
  PLOT_WRAPPER_PID_FILE="$wt/.plot-worker.wrapper.pid" \
1506
1336
  PLOT_SCRIPT_DIR="$script_dir" \
1507
- exec nohup sh -c 'printf "%s" "$$" > "$PLOT_WRAPPER_PID_FILE"; wrapperstarted=$(ps -o lstart= -p "$$" 2>/dev/null); wmon=""; amon=""; if [ -n "$PLOT_AGENT_MONITOR" ]; then "$PLOT_AGENT_MONITOR" & amon=$!; fi; PATH="$PLOT_SCRIPT_DIR:$PATH"; export PATH; ( '"$cmd"' ) & agent=$!; trap "" TERM; printf "%s" "$agent" > "$PLOT_PID_FILE"; agentstarted=$(ps -o lstart= -p "$agent" 2>/dev/null); printf "%s" "$agentstarted" > "$PLOT_PID_STARTED_FILE"; if [ -f "$PLOT_MANIFEST_FILE" ]; then awk -v pid="$agent" -v pidstarted="$agentstarted" -v started="$PLOT_STAMP_STARTED" -v wrapper="$$" -v wrapperstarted="$wrapperstarted" -v wmon="$wmon" -v amon="$amon" '"'"'
1508
- BEGIN { relaunch = 0; count = 1; stamped = 0 }
1509
- FNR == NR {
1510
- if ($0 ~ /^ "pid": "[^"]*",$/) {
1511
- p = $0; sub(/^ "pid": "/, "", p); sub(/",$/, "", p)
1512
- if (p != "") { relaunch = 1; displaced = p }
1513
- }
1514
- if ($0 ~ /^ "relaunches": [0-9]+,$/) {
1515
- n = $0; sub(/^ "relaunches": /, "", n); sub(/,$/, "", n); count = n + 1
1516
- }
1517
- next
1518
- }
1519
- !stamped && $0 ~ /^ "pid": "[^"]*",$/ {
1520
- stamped = 1
1521
- print " \"pid\": \"" pid "\","
1522
- print " \"pidStartedAt\": \"" pidstarted "\","
1523
- print " \"wrapperPid\": \"" wrapper "\","
1524
- print " \"wrapperPidStartedAt\": \"" wrapperstarted "\","
1525
- print " \"workerMonitorPid\": \"" wmon "\","
1526
- print " \"agentMonitorPid\": \"" amon "\","
1527
- if (relaunch) {
1528
- print " \"previousPid\": \"" displaced "\","
1529
- print " \"relaunches\": " count ","
1530
- }
1531
- next
1532
- }
1533
- $0 ~ /^ "pidStartedAt": "[^"]*",$/ { next }
1534
- $0 ~ /^ "wrapperPid": "[^"]*",$/ { next }
1535
- $0 ~ /^ "wrapperPidStartedAt": "[^"]*",$/ { next }
1536
- $0 ~ /^ "workerMonitorPid": "[^"]*",$/ { next }
1537
- $0 ~ /^ "agentMonitorPid": "[^"]*",$/ { next }
1538
- relaunch && $0 ~ /^ "previousPid": "[^"]*",$/ { next }
1539
- relaunch && $0 ~ /^ "relaunches": [0-9]+,$/ { next }
1540
- relaunch && $0 ~ /^ "startedAt": "[^"]*"$/ { print " \"startedAt\": \"" started "\""; next }
1541
- { print }
1542
- '"'"' "$PLOT_MANIFEST_FILE" "$PLOT_MANIFEST_FILE" > "$PLOT_MANIFEST_FILE.plot-pid-tmp" 2>/dev/null && mv "$PLOT_MANIFEST_FILE.plot-pid-tmp" "$PLOT_MANIFEST_FILE" 2>/dev/null || rm -f "$PLOT_MANIFEST_FILE.plot-pid-tmp"; fi; wait "$agent"; rc=$?; wd="$PLOT_WORKTREE"; . plot-monitor-subject.sh 2>/dev/null && wd=$(plot_watched_desk "$PLOT_MANIFEST_FILE" "$PLOT_WORKTREE"); wf="$wd/.plot-worker.monitor.worker.jsonl"; if [ -n "$wd" ]; then now=$(date -u +%Y-%m-%dT%H:%M:%SZ); if [ "$rc" -ne 0 ]; then f=gone; e="the agent pid $agent exited $rc; the wrapper that started it is unattended"; else f=clear; e="the agent pid $agent exited 0; the worker is finished"; fi; printf "{\"monitor\":\"WorkerMonitor\",\"branch\":\"%s\",\"worktree\":\"%s\",\"finding\":\"%s\",\"since\":\"%s\",\"evidence\":\"%s\",\"measuredAt\":\"%s\"}\n" "$PLOT_BRANCH" "$wd" "$f" "$now" "$e" "$now" >> "$wf" 2>/dev/null; fi; printf "%s" "$rc" > "$PLOT_EXIT_FILE"' \
1543
- >"$log" 2>&1 </dev/null & ) >/dev/null 2>&1 </dev/null
1337
+ PLOT_WORKER_LOG="$log" \
1338
+ node "$script_dir/board/plot-worker-start.mjs" "$cmd" ) 2>&1 >/dev/null </dev/null ); then
1339
+ echo " refusing to start ${branch:-a free agent} — the worker wrapper did not start:"
1340
+ printf '%s\n' "$start_err" | sed 's/^/ /'
1341
+ return 1
1342
+ fi
1544
1343
  echo " started worker (log: $log)"
1545
1344
  return 0
1546
1345
  }
@@ -1786,9 +1585,9 @@ if [ "$mode" = "stop" ]; then
1786
1585
  # THE WHOLE PROCESS GROUP, NOT ONE PID. Measured 2026-09-30 (#1084):
1787
1586
  # `--stop` signalled the wrapper, the group leader, and the loop, the
1788
1587
  # prompt shell, `claude` and its children survived reparented to pid 1;
1789
- # `kill -TERM -<pgid>` ended all of them. `start_worker` launches under
1790
- # `set -m`, so an agent leads its own group and that group holds one
1791
- # wrapper with its monitors, its loop and its `claude`: the signal ends
1588
+ # `kill -TERM -<pgid>` ended all of them. `start_worker` starts the
1589
+ # wrapper detached, so an agent leads its own group and that group holds one
1590
+ # wrapper, its loop and its `claude`: the signal ends
1792
1591
  # this agent and nothing else. An agent started before that change still
1793
1592
  # shares its starter's group with every sibling the same run started and
1794
1593
  # with the starter itself. The guard below stays for those agents: the
@@ -1837,7 +1636,7 @@ if [ "$mode" = "restart" ]; then
1837
1636
  exit 1
1838
1637
  fi
1839
1638
  PLOT_RESTART_WORKTREE=$(worktree_holding_branch "$restart_branch") \
1840
- PLOT_RESTART_OFFLINE=$([ -n "$offline" ] && echo 1 || echo 0) \
1639
+ PLOT_RESTART_OFFLINE=$([ -n "$offline" ] && echo 1 || echo 0) PLOT_GIT_COMMON_DIR= \
1841
1640
  node "$script_dir/board/plot-restart-command.mjs" "$restart_branch" || exit 1
1842
1641
  spend_action_receipt "restart"
1843
1642
  exit 0
@@ -2687,6 +2486,7 @@ ACTIVE_DIR_CFG=$("$script_dir/plot-config.sh" get "Active index" "docs/plans/act
2687
2486
 
2688
2487
  gate_ref="origin/$MAIN"
2689
2488
  gate_sha=$(git rev-parse --verify --quiet "$gate_ref^{commit}" 2>/dev/null) || gate_sha=""
2489
+ STATE_KEY=$("$script_dir/plot-config.sh" get "State branch" "")
2690
2490
 
2691
2491
  # The plan as it exists on the shared ref. Path resolution runs against the ref
2692
2492
  # too (`git ls-tree`), not the filesystem: a plan that exists only locally must
@@ -2698,41 +2498,21 @@ gate_sha=$(git rev-parse --verify --quiet "$gate_ref^{commit}" 2>/dev/null) || g
2698
2498
  # follows the link and this never comes up; against a ref it must be
2699
2499
  # dereferenced by hand, or the gate parses a one-line path as a plan and reports
2700
2500
  # an unreadable phase instead of the real one.
2701
- deref_on_ref() { # $1=path on $gate_ref → prints the path the blob really lives at
2702
- local p="$1" target dir hops=0
2703
- while [ "$(git ls-tree "$gate_ref" -- "$p" 2>/dev/null | awk '{print $1}')" = "120000" ]; do
2704
- hops=$((hops + 1))
2705
- [ "$hops" -le 8 ] || return 1 # a symlink cycle must not hang the gate
2706
- target=$(git show "$gate_ref:$p" 2>/dev/null) || return 1
2707
- case "$target" in
2708
- /*) return 1 ;; # absolute: not a path within the ref
2709
- *) dir=$(dirname "$p")
2710
- # Normalise ../ and ./ without touching the filesystem.
2711
- p=$(printf '%s\n' "$dir/$target" | awk -F/ '{
2712
- n=0
2713
- for (i=1; i<=NF; i++) {
2714
- if ($i == "" || $i == ".") continue
2715
- if ($i == "..") { if (n>0) n--; continue }
2716
- s[++n]=$i
2717
- }
2718
- out=""
2719
- for (i=1; i<=n; i++) out = (i==1 ? s[i] : out "/" s[i])
2720
- print out
2721
- }') ;;
2722
- esac
2723
- done
2724
- printf '%s\n' "$p"
2725
- }
2501
+ deref_on_ref() { node "$script_dir/board/plot-record-ref.mjs" --deref "$gate_ref" "$1" 2>/dev/null; } # $1=path on $gate_ref → the path the blob really lives at
2726
2502
 
2503
+ # WHERE `State branch` IS DECLARED the records sit on the state ref: candidates
2504
+ # come from both refs and each path is read at the ref `recordRef` names for it.
2727
2505
  plan_path=""
2728
2506
  if [ -n "$gate_sha" ]; then
2729
2507
  for cand in "$ACTIVE_DIR_CFG$slug.md" \
2730
- $(git ls-tree -r --name-only "$gate_ref" -- "$PLAN_DIR_CFG" 2>/dev/null \
2731
- | grep -E "/[0-9]{4}-[0-9]{2}-[0-9]{2}-${slug}\.md$|/${slug}\.md$"); do
2508
+ $( { git ls-tree -r --name-only "origin/$MAIN" -- "$PLAN_DIR_CFG"; [ -z "$STATE_KEY" ] || git ls-tree -r --name-only "$(rec_ref)" -- "$PLAN_DIR_CFG"; } 2>/dev/null \
2509
+ | sort -u | grep -E "/[0-9]{4}-[0-9]{2}-[0-9]{2}-${slug}\.md$|/${slug}\.md$"); do
2510
+ gate_ref=$(rec_ref "$cand")
2732
2511
  git cat-file -e "$gate_ref:$cand" 2>/dev/null || continue
2733
2512
  plan_path=$(deref_on_ref "$cand") || { plan_path=""; continue; }
2734
2513
  [ -n "$plan_path" ] && break
2735
2514
  done
2515
+ gate_sha=$(git rev-parse --verify --quiet "$gate_ref^{commit}" 2>/dev/null) || gate_sha=""
2736
2516
  fi
2737
2517
 
2738
2518
  # --allow-local: read the working tree instead, and say so. The escape for a
@@ -3258,7 +3038,7 @@ book_started() { # $@ = branches dispatched this run
3258
3038
  # The write itself. Every failure path returns non-zero after saying WHY on
3259
3039
  # stderr; the caller owns the one user-facing consequence line.
3260
3040
  write_started_record() { # $@ = branches
3261
- local who date rel tmpwt bookbr rc=0
3041
+ local who date rel tmpwt bookbr pushref rc=0
3262
3042
  who="${PLOT_CLAIM_WHO:-$(git config user.name 2>/dev/null || echo plot)}"
3263
3043
  date=$(date +%Y-%m-%d)
3264
3044
 
@@ -3275,20 +3055,13 @@ write_started_record() { # $@ = branches
3275
3055
  bookbr="plot/start-$slug"
3276
3056
  tmpwt="$wt_root/.plot-start-$slug.$$"
3277
3057
 
3278
- # Fetch even under --offline: booking is a push, so the network is already
3279
- # required. Without a fresh origin/<default> the branch would fork from a
3280
- # stale tip and the push would be a guaranteed non-fast-forward.
3281
- git fetch -q origin "$MAIN" 2>/dev/null
3282
-
3283
- # `git worktree add` creates the desk root when it is missing; exclude it
3284
- # first so the booking leaves no untracked `.worktrees/` behind.
3058
+ # The cut is the bundle's: from the declared `State branch` (else from
3059
+ # origin/<default>), fetched first even under --offline — booking is a push,
3060
+ # so the network is already required. It prints the ref the push goes at.
3061
+ # `-B` semantics hold: a leftover branch from an earlier failed booking is
3062
+ # disposable by construction.
3285
3063
  plot_exclude_desk_root "$(plot_repo_root)"
3286
- # -B: a leftover branch from an earlier failed booking must not block this
3287
- # one. It is disposable by construction — created here, pushed, deleted.
3288
- if ! git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null; then
3289
- echo "plot-dispatch: could not prepare a booking worktree at $tmpwt" >&2
3290
- echo " Most often origin/$MAIN is not fetched, or '$bookbr' is checked out in" >&2
3291
- echo " another worktree. Check both: git fetch origin $MAIN && git worktree list" >&2
3064
+ if ! pushref=$(node "$script_dir/board/plot-state-cut.mjs" "$tmpwt" "$bookbr" "$MAIN"); then
3292
3065
  echo " The branches were dispatched; only the plan's Started record is missing." >&2
3293
3066
  return 1
3294
3067
  fi
@@ -3344,7 +3117,7 @@ write_started_record() { # $@ = branches
3344
3117
  # in so a `rejected` report is visible rather than swallowed by 2>/dev/null
3345
3118
  # somewhere upstream.
3346
3119
  if [ "$rc" = 0 ]; then
3347
- "$script_dir/plot-push-main.sh" "$bookbr" "$MAIN" 2>&1 | sed 's/^/ /'
3120
+ "$script_dir/plot-push-main.sh" "$bookbr" "$pushref" 2>&1 | sed 's/^/ /'
3348
3121
  # The pipeline's status is sed's, so ask the helper's directly.
3349
3122
  rc=${PIPESTATUS[0]}
3350
3123
  fi
@@ -3723,7 +3496,6 @@ work_in_flight() { # $1=branch to exclude (the candidate)
3723
3496
  # rather than a map. Sorted output keeps the report stable between runs.
3724
3497
  git for-each-ref --format='%(refname:short)' refs/heads/ </dev/null 2>/dev/null \
3725
3498
  | while read -r br; do
3726
- [ -n "$br" ] || continue
3727
3499
  [ "$br" = "$exclude" ] && continue
3728
3500
  [ "$br" = "$MAIN" ] && continue
3729
3501
  files=$( { committed_files "$br"; uncommitted_files "$(worktree_for "$br")"; } \
@@ -3752,41 +3524,6 @@ work_in_flight() { # $1=branch to exclude (the candidate)
3752
3524
  IN_FLIGHT_MAX_FILES=6
3753
3525
  IN_FLIGHT_MAX_BRANCHES=8
3754
3526
 
3755
- # What a real run would attach, named per worktree — behind `--monitors`.
3756
- #
3757
- # SILENT UNLESS ASKED, which is what keeps the default `--dry-run` output
3758
- # byte-identical to a run from before the monitors existed. That diff is this
3759
- # slice's protection against the one failure that matters here: a mistake in
3760
- # `start_worker` starts no workers at all, and the dry run exercises every
3761
- # refusal against real worktrees and real pids without starting anything.
3762
- #
3763
- # IT NAMES THE SCRIPT PATH, not just the monitor. The question a reader has at
3764
- # a dry run is *which code would run against my worktree* — a bare "2 monitors"
3765
- # would send them into this script to find out, and a path they can `cat` is
3766
- # the same courtesy the manifest refusal above pays by naming its directory.
3767
- #
3768
- # IT REPORTS ABSENCE TOO. A monitor script that is missing or non-executable
3769
- # means an unmonitored worker, and the empty env var that produces is invisible
3770
- # at launch by design (a detached `sh -c` nobody reads must not spew `command
3771
- # not found`). The dry run is the one place that silence can be made audible
3772
- # before it matters.
3773
- report_monitors() { # $1=worktree
3774
- [ "$show_monitors" = 1 ] || return 0
3775
- local wt="$1" m
3776
- # ONLY `agent` IS A SCRIPT ANY MORE. `bug/the-loop-reports-idle` removed
3777
- # `plot-worker-monitor.sh`: the PROCESS no longer has a monitor to report —
3778
- # the loop's own watcher judges `idle` and the wrapper itself reports
3779
- # `gone`/`clear`, neither of which this dry run can name as a script path.
3780
- for m in agent; do
3781
- local script="$script_dir/plot-$m-monitor.sh"
3782
- if [ -x "$script" ]; then
3783
- echo " would attach: $script → $wt"
3784
- else
3785
- echo " would attach NOTHING for the $m monitor — $script is missing or not executable"
3786
- fi
3787
- done
3788
- }
3789
-
3790
3527
  report_in_flight() { # $1=candidate branch
3791
3528
  local br files shown extra n=0 total
3792
3529
  total=$(work_in_flight "$1" | wc -l | tr -d ' ')
@@ -3826,8 +3563,8 @@ run_waits_preflight
3826
3563
  # set once. (`--next` would loop forever here: without a claim it keeps
3827
3564
  # returning the same branch.)
3828
3565
  if [ "$dry_run" = 1 ]; then
3566
+ # The list below drops empty lines (`grep -v '^$'`), so every `br` names a branch.
3829
3567
  while read -r br; do
3830
- [ -n "$br" ] || continue
3831
3568
  # The gate, BEFORE the "would dispatch" line — this loop's whole output is
3832
3569
  # a prediction, and predicting a dispatch the real run refuses is the
3833
3570
  # failure the gate exists to stop.
@@ -3841,7 +3578,6 @@ if [ "$dry_run" = 1 ]; then
3841
3578
  # the one that reached here because the scan could not ask the host.
3842
3579
  is_waits_held "$br" && continue
3843
3580
  echo "would dispatch $br → $(worktree_for "$br")"
3844
- report_monitors "$(worktree_for "$br")"
3845
3581
  report_in_flight "$br"
3846
3582
  n_dispatched=$((n_dispatched + 1))
3847
3583
  # The scan's eligible set, plus whatever `--allow-waiting` freed. The scan
@@ -3850,7 +3586,7 @@ if [ "$dry_run" = 1 ]; then
3850
3586
  # branch the scan DID offer (its host call failed where the preflight's
3851
3587
  # succeeded) must be dispatched once, not twice.
3852
3588
  done < <({ "$script_dir/plot-fleet-scan.sh" $offline --list-eligible "$slug" 2>/dev/null
3853
- printf '%s\n' ${waits_freed[@]+"${waits_freed[@]}"}; } | grep -v '^$' | sort -u)
3589
+ printf '%s\n' ${waits_freed[@]+"${waits_freed[@]}"}; } | grep -v '^$' | sort -u | awk -v b="${only_branch:-}" 'b == "" || $0 == b')
3854
3590
  # A dry run starts nothing BY CONSTRUCTION, so its `started=0` carries no
3855
3591
  # information about the config — reporting "no workers started" here would be
3856
3592
  # true and useless, and would train the reader to skip the line on the real
@@ -3899,7 +3635,7 @@ while IFS= read -r _line; do
3899
3635
  fan_out+=("$_line")
3900
3636
  done < <({ "$script_dir/plot-fleet-scan.sh" $offline --list-eligible "$slug" 2>/dev/null
3901
3637
  [ "$allow_waiting" = 1 ] && printf '%s\n' ${waits_freed[@]+"${waits_freed[@]}"}
3902
- :; } | grep -v '^$' | sort -u)
3638
+ :; } | grep -v '^$' | sort -u | awk -v b="${only_branch:-}" 'b == "" || $0 == b')
3903
3639
 
3904
3640
  for branch in ${fan_out[@]+"${fan_out[@]}"}; do
3905
3641
  [ "$max" -gt 0 ] && [ "$n_dispatched" -ge "$max" ] && break
@@ -3909,17 +3645,8 @@ for branch in ${fan_out[@]+"${fan_out[@]}"}; do
3909
3645
  # with a scan-offered one where the two spellings differ.
3910
3646
  is_exhausted "$branch" && continue
3911
3647
 
3912
- # THE PATH DISPATCH NO LONGER CREATES, still composed for the two readers that
3913
- # need it: the dry run, which names where a desk WOULD go, and the monitor
3914
- # report. The agent decides its own desk now, so this is a prediction rather
3915
- # than a destination — and it stays flattened whole, because `feature/api` and
3916
- # `bug/api` are different work and must not name one directory.
3917
- suffix=$(printf '%s' "$branch" | tr '/' '-')
3918
- wt="$wt_root/$wt_prefix$suffix"
3919
-
3920
3648
  if [ "$dry_run" = 1 ]; then
3921
3649
  echo "would hand over $branch → the registry"
3922
- report_monitors "$wt"
3923
3650
  report_in_flight "$branch"
3924
3651
  n_dispatched=$((n_dispatched + 1))
3925
3652
  continue