@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.
package/plot-dispatch.sh CHANGED
@@ -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
@@ -275,7 +271,6 @@ worktree_holding_branch() { # $1=branch → the first desk holding it, or nothin
275
271
  }
276
272
 
277
273
  dry_run=0
278
- show_monitors=0
279
274
  no_start=0
280
275
  no_brief=0
281
276
  mode=dispatch
@@ -297,16 +292,6 @@ agent=""
297
292
  while [ $# -gt 0 ]; do
298
293
  case "$1" in
299
294
  --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
295
  --status) mode=status ;;
311
296
  --migrate) mode=migrate ;;
312
297
  --yes) migrate_yes=1 ;;
@@ -366,7 +351,7 @@ while [ $# -gt 0 ]; do
366
351
  # `--release` pushed it from 78 to 91. Two records
367
352
  # of one fact, and nothing compares them — a stale number here silently
368
353
  # truncates the help rather than failing, so it is checked by a test.
369
- -h|--help) sed -n '2,93p' "$0"; exit 0 ;;
354
+ -h|--help) sed -n '2,89p' "$0"; exit 0 ;;
370
355
  *) slug="$1" ;;
371
356
  esac
372
357
  shift
@@ -487,7 +472,7 @@ write_agent_manifest() { # $1=path $2=session $3=branch $4=worktree $5=command
487
472
  printf ' "worktree": "%s",\n' "$(json_escape "$4")"
488
473
  printf ' "command": "%s",\n' "$(json_escape "$5")"
489
474
  printf ' "pid": "",\n'
490
- printf ' "attempts": 0,\n'
475
+ printf ' "attempts": 0,\n "agentProcess": "%s",\n' "$(json_escape "${PLOT_AGENT_PROCESS:-claude}")"
491
476
  printf ' "startedAt": "%s"\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
492
477
  printf '}\n'
493
478
  } > "$tmp" 2>/dev/null || { rm -f "$tmp"; return 1; }
@@ -548,7 +533,10 @@ write_agent_manifest() { # $1=path $2=session $3=branch $4=worktree $5=command
548
533
  # because a person will look either way): here the cost of guessing wrong is an
549
534
  # agent burning minutes on nothing.
550
535
  brief_path() { printf '.plot/briefs/%s.md' "${1##*/}"; }
551
- brief_ref() { printf 'origin/%s:%s' "$MAIN" "$(brief_path "$1")"; }
536
+ # The ref a path's records are read at: `origin/<main>`, or where `State branch`
537
+ # is declared the ref the domain's `recordRef` names (`board/plot-record-ref.mjs`).
538
+ rec_ref() { [ -n "${STATE_KEY:-}" ] && node "$script_dir/board/plot-record-ref.mjs" "$STATE_KEY" "$MAIN" "$1" 2>/dev/null || printf 'origin/%s' "$MAIN"; }
539
+ brief_ref() { printf '%s:%s' "$(rec_ref "$(brief_path "$1")")" "$(brief_path "$1")"; }
552
540
  brief_present() { # $1 = branch → 0 if a usable brief exists on origin/<main>
553
541
  local sz
554
542
  sz=$(git cat-file -s "$(brief_ref "$1")" 2>/dev/null) || return 1
@@ -836,7 +824,7 @@ request_brief() { # $1 = branch, $2 = slug → 0 if a command was started
836
824
  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
825
  ( set -m; cd "$repo_root" \
838
826
  && PLOT_UNATTENDED=1 PLOT_MAIN_CHECKOUT_WRITER=1 PLOT_PLAN_SLUG="$bslug" PLOT_BRIEF_BRANCH="$branch" \
839
- PLOT_AGENT_SETTINGS="$_brief_settings" \
827
+ PLOT_AGENT_SETTINGS="$_brief_settings" PLOT_GIT_COMMON_DIR= \
840
828
  exec nohup sh -c "$cmd \"\$@\"" plot-brief \
841
829
  "$(brief_prompt "$branch" "$bslug")" \
842
830
  >"$log" 2>&1 </dev/null & ) >/dev/null 2>&1 </dev/null
@@ -873,7 +861,7 @@ brief_staleness_note() { # $1 = branch → prints a hint, or nothing
873
861
  local branch="$1" bc pc bs ps
874
862
  [ -n "$gate_sha" ] || return 0 # nothing shared to compare against
875
863
  [ -n "${plan_path:-}" ] || return 0
876
- bc=$(git log -1 --format='%H %ct' "$gate_ref" -- "$(brief_path "$branch")" 2>/dev/null) || return 0
864
+ bc=$(git log -1 --format='%H %ct' "$(rec_ref "$(brief_path "$branch")")" -- "$(brief_path "$branch")" 2>/dev/null) || return 0
877
865
  pc=$(git log -1 --format='%H %ct' "$gate_ref" -- "$plan_path" 2>/dev/null) || return 0
878
866
  [ -n "$bc" ] && [ -n "$pc" ] || return 0
879
867
  bs=${bc##* }; ps=${pc##* }
@@ -1013,7 +1001,7 @@ ask_start_command() { # $1 = free | assigned
1013
1001
  start_cmd_configured=$("$script_dir/plot-config.sh" get "Worker command" "")
1014
1002
  start_cmd_bundle="$script_dir/board/plot-start-command.mjs"
1015
1003
  answer=$(printf '%s' "$start_cmd_configured" | node "$start_cmd_bundle" "$1" \
1016
- plot-worker-loop.sh "PLOT_UNATTENDED=1 plot-worker-loop.sh" 2>/dev/null)
1004
+ plot-worker-loop.sh "PLOT_UNATTENDED=1 plot-worker-loop.sh" "$repo_root" "$("$script_dir/plot-config.sh" get "Agent runner" "")" 2>/dev/null)
1017
1005
  rc=$?
1018
1006
  case "$rc:$answer" in
1019
1007
  0:run$'\t'*) start_cmd_verb=run; start_cmd_run=${answer#run$'\t'} ;;
@@ -1128,7 +1116,7 @@ start_worker() {
1128
1116
  return 1
1129
1117
  fi
1130
1118
  local log="$wt/.plot-worker.log"
1131
- rm -f "$wt/.plot-worker.exit"
1119
+ rm -f "$wt/.plot-worker.exit" "$wt/.plot-worker.token.fifo"
1132
1120
 
1133
1121
  # THE MANIFEST, AND WHY IT IS KEYED ON A SESSION ID RATHER THAN A BRANCH.
1134
1122
  #
@@ -1228,141 +1216,15 @@ start_worker() {
1228
1216
  echo " key) and dispatch again."
1229
1217
  return 1
1230
1218
  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.
1219
+ # THE WRAPPER IS `board/plot-worker-wrapper.mjs`, one process per launch. It
1220
+ # writes its own pid to `.plot-worker.wrapper.pid`, starts the AgentMonitor as
1221
+ # its child, starts the agent as `bash -c "$cmd"`, ignores `SIGTERM` itself,
1222
+ # writes the agent's pid and `ps -o lstart=` text, and stamps the manifest
1223
+ # through `writeManifestStamp`. Once the agent ends it appends one
1224
+ # WorkerMonitor line (`gone` for a non-zero exit, `clear` for 0) to the
1225
+ # watched desk and writes the code to `.plot-worker.exit`. `--stop` kills the
1226
+ # agent, and the wrapper survives to record the code. The paths travel as env
1227
+ # vars, so a path with spaces needs no quoting.
1366
1228
  # WHAT THIS AGENT MAY TOUCH — `PLOT_CAPABILITIES`, AND WHY IT IS RESOLVED HERE.
1367
1229
  #
1368
1230
  # A charter's `capabilities` list is the one differentiation Plot can express
@@ -1424,58 +1286,23 @@ start_worker() {
1424
1286
  fi
1425
1287
  fi
1426
1288
 
1427
- local agent_monitor=''
1428
- [ -x "$script_dir/plot-agent-monitor.sh" ] && agent_monitor="$script_dir/plot-agent-monitor.sh"
1429
1289
  local stamp_now
1430
1290
  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" && \
1291
+ # `PLOT_HARNESS`, `PLOT_MODEL` and `PLOT_EFFORT` are the three names the
1292
+ # charter declared, and empty where it declared none. `PLOT_AGENT` is
1293
+ # forwarded, so the loop's own `resolve_prompt_file` asks about the agent
1294
+ # this launch resolved.
1295
+ #
1296
+ # `board/plot-worker-start.mjs` STARTS THE WRAPPER DETACHED AND EXITS. The
1297
+ # wrapper leads its own session and process group, so its pid is its group
1298
+ # id: `--stop`'s group signal reaches this desk's wrapper and agent and no
1299
+ # sibling desk's, and a SIGKILL to the starter's group (`killGroup` in
1300
+ # `run-script.ts`) misses the agent. The wrapper's output goes to `$log`, so
1301
+ # the caller's streams close when the start exits. A Node major other than
1302
+ # the one `.nvmrc` pins starts no wrapper, and this function reports the
1303
+ # refusal.
1304
+ local start_err
1305
+ if ! start_err=$( ( cd "$wt" && \
1479
1306
  # AN `export`, NOT AN ENV PREFIX, AND THE REASON IS A MEASUREMENT. Bash
1480
1307
  # recognises an assignment prefix BEFORE it expands parameters, so a
1481
1308
  # `${caps:+PLOT_CAPABILITIES="$caps"}` in the prefix below is not an
@@ -1491,7 +1318,7 @@ start_worker() {
1491
1318
  # the export reaches the wrapper and nothing else.
1492
1319
  { [ -n "$capabilities" ] && export PLOT_CAPABILITIES="$capabilities"; true; } && \
1493
1320
  PLOT_BRANCH="$branch" PLOT_WORKTREE="$wt" \
1494
- PLOT_SLUG="$slug" PLOT_MAIN_CHECKOUT_WRITER= \
1321
+ PLOT_SLUG="$slug" PLOT_MAIN_CHECKOUT_WRITER= PLOT_GIT_COMMON_DIR= \
1495
1322
  PLOT_SESSION_ID="$session" \
1496
1323
  PLOT_AGENT="${PLOT_AGENT:-}" \
1497
1324
  PLOT_HARNESS="$launch_harness" \
@@ -1499,48 +1326,16 @@ start_worker() {
1499
1326
  PLOT_EFFORT="$launch_effort" \
1500
1327
  PLOT_MANIFEST_FILE="$manifest_dir/$session.json" \
1501
1328
  PLOT_STAMP_STARTED="$stamp_now" \
1502
- PLOT_AGENT_MONITOR="$agent_monitor" \
1503
1329
  PLOT_EXIT_FILE="$wt/.plot-worker.exit" PLOT_PID_FILE="$wt/.plot-worker.pid" \
1504
1330
  PLOT_PID_STARTED_FILE="$wt/.plot-worker.pid.startedAt" \
1505
1331
  PLOT_WRAPPER_PID_FILE="$wt/.plot-worker.wrapper.pid" \
1506
1332
  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
1333
+ PLOT_WORKER_LOG="$log" \
1334
+ node "$script_dir/board/plot-worker-start.mjs" "$cmd" ) 2>&1 >/dev/null </dev/null ); then
1335
+ echo " refusing to start ${branch:-a free agent} — the worker wrapper did not start:"
1336
+ printf '%s\n' "$start_err" | sed 's/^/ /'
1337
+ return 1
1338
+ fi
1544
1339
  echo " started worker (log: $log)"
1545
1340
  return 0
1546
1341
  }
@@ -1786,9 +1581,9 @@ if [ "$mode" = "stop" ]; then
1786
1581
  # THE WHOLE PROCESS GROUP, NOT ONE PID. Measured 2026-09-30 (#1084):
1787
1582
  # `--stop` signalled the wrapper, the group leader, and the loop, the
1788
1583
  # 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
1584
+ # `kill -TERM -<pgid>` ended all of them. `start_worker` starts the
1585
+ # wrapper detached, so an agent leads its own group and that group holds one
1586
+ # wrapper, its loop and its `claude`: the signal ends
1792
1587
  # this agent and nothing else. An agent started before that change still
1793
1588
  # shares its starter's group with every sibling the same run started and
1794
1589
  # with the starter itself. The guard below stays for those agents: the
@@ -1837,7 +1632,7 @@ if [ "$mode" = "restart" ]; then
1837
1632
  exit 1
1838
1633
  fi
1839
1634
  PLOT_RESTART_WORKTREE=$(worktree_holding_branch "$restart_branch") \
1840
- PLOT_RESTART_OFFLINE=$([ -n "$offline" ] && echo 1 || echo 0) \
1635
+ PLOT_RESTART_OFFLINE=$([ -n "$offline" ] && echo 1 || echo 0) PLOT_GIT_COMMON_DIR= \
1841
1636
  node "$script_dir/board/plot-restart-command.mjs" "$restart_branch" || exit 1
1842
1637
  spend_action_receipt "restart"
1843
1638
  exit 0
@@ -2687,6 +2482,7 @@ ACTIVE_DIR_CFG=$("$script_dir/plot-config.sh" get "Active index" "docs/plans/act
2687
2482
 
2688
2483
  gate_ref="origin/$MAIN"
2689
2484
  gate_sha=$(git rev-parse --verify --quiet "$gate_ref^{commit}" 2>/dev/null) || gate_sha=""
2485
+ STATE_KEY=$("$script_dir/plot-config.sh" get "State branch" "")
2690
2486
 
2691
2487
  # The plan as it exists on the shared ref. Path resolution runs against the ref
2692
2488
  # too (`git ls-tree`), not the filesystem: a plan that exists only locally must
@@ -2698,41 +2494,21 @@ gate_sha=$(git rev-parse --verify --quiet "$gate_ref^{commit}" 2>/dev/null) || g
2698
2494
  # follows the link and this never comes up; against a ref it must be
2699
2495
  # dereferenced by hand, or the gate parses a one-line path as a plan and reports
2700
2496
  # 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
- }
2497
+ 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
2498
 
2499
+ # WHERE `State branch` IS DECLARED the records sit on the state ref: candidates
2500
+ # come from both refs and each path is read at the ref `recordRef` names for it.
2727
2501
  plan_path=""
2728
2502
  if [ -n "$gate_sha" ]; then
2729
2503
  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
2504
+ $( { 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 \
2505
+ | sort -u | grep -E "/[0-9]{4}-[0-9]{2}-[0-9]{2}-${slug}\.md$|/${slug}\.md$"); do
2506
+ gate_ref=$(rec_ref "$cand")
2732
2507
  git cat-file -e "$gate_ref:$cand" 2>/dev/null || continue
2733
2508
  plan_path=$(deref_on_ref "$cand") || { plan_path=""; continue; }
2734
2509
  [ -n "$plan_path" ] && break
2735
2510
  done
2511
+ gate_sha=$(git rev-parse --verify --quiet "$gate_ref^{commit}" 2>/dev/null) || gate_sha=""
2736
2512
  fi
2737
2513
 
2738
2514
  # --allow-local: read the working tree instead, and say so. The escape for a
@@ -3258,7 +3034,7 @@ book_started() { # $@ = branches dispatched this run
3258
3034
  # The write itself. Every failure path returns non-zero after saying WHY on
3259
3035
  # stderr; the caller owns the one user-facing consequence line.
3260
3036
  write_started_record() { # $@ = branches
3261
- local who date rel tmpwt bookbr rc=0
3037
+ local who date rel tmpwt bookbr pushref rc=0
3262
3038
  who="${PLOT_CLAIM_WHO:-$(git config user.name 2>/dev/null || echo plot)}"
3263
3039
  date=$(date +%Y-%m-%d)
3264
3040
 
@@ -3275,20 +3051,13 @@ write_started_record() { # $@ = branches
3275
3051
  bookbr="plot/start-$slug"
3276
3052
  tmpwt="$wt_root/.plot-start-$slug.$$"
3277
3053
 
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.
3054
+ # The cut is the bundle's: from the declared `State branch` (else from
3055
+ # origin/<default>), fetched first even under --offline — booking is a push,
3056
+ # so the network is already required. It prints the ref the push goes at.
3057
+ # `-B` semantics hold: a leftover branch from an earlier failed booking is
3058
+ # disposable by construction.
3285
3059
  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
3060
+ if ! pushref=$(node "$script_dir/board/plot-state-cut.mjs" "$tmpwt" "$bookbr" "$MAIN"); then
3292
3061
  echo " The branches were dispatched; only the plan's Started record is missing." >&2
3293
3062
  return 1
3294
3063
  fi
@@ -3344,7 +3113,7 @@ write_started_record() { # $@ = branches
3344
3113
  # in so a `rejected` report is visible rather than swallowed by 2>/dev/null
3345
3114
  # somewhere upstream.
3346
3115
  if [ "$rc" = 0 ]; then
3347
- "$script_dir/plot-push-main.sh" "$bookbr" "$MAIN" 2>&1 | sed 's/^/ /'
3116
+ "$script_dir/plot-push-main.sh" "$bookbr" "$pushref" 2>&1 | sed 's/^/ /'
3348
3117
  # The pipeline's status is sed's, so ask the helper's directly.
3349
3118
  rc=${PIPESTATUS[0]}
3350
3119
  fi
@@ -3752,41 +3521,6 @@ work_in_flight() { # $1=branch to exclude (the candidate)
3752
3521
  IN_FLIGHT_MAX_FILES=6
3753
3522
  IN_FLIGHT_MAX_BRANCHES=8
3754
3523
 
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
3524
  report_in_flight() { # $1=candidate branch
3791
3525
  local br files shown extra n=0 total
3792
3526
  total=$(work_in_flight "$1" | wc -l | tr -d ' ')
@@ -3841,7 +3575,6 @@ if [ "$dry_run" = 1 ]; then
3841
3575
  # the one that reached here because the scan could not ask the host.
3842
3576
  is_waits_held "$br" && continue
3843
3577
  echo "would dispatch $br → $(worktree_for "$br")"
3844
- report_monitors "$(worktree_for "$br")"
3845
3578
  report_in_flight "$br"
3846
3579
  n_dispatched=$((n_dispatched + 1))
3847
3580
  # The scan's eligible set, plus whatever `--allow-waiting` freed. The scan
@@ -3909,17 +3642,8 @@ for branch in ${fan_out[@]+"${fan_out[@]}"}; do
3909
3642
  # with a scan-offered one where the two spellings differ.
3910
3643
  is_exhausted "$branch" && continue
3911
3644
 
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
3645
  if [ "$dry_run" = 1 ]; then
3921
3646
  echo "would hand over $branch → the registry"
3922
- report_monitors "$wt"
3923
3647
  report_in_flight "$branch"
3924
3648
  n_dispatched=$((n_dispatched + 1))
3925
3649
  continue