@plot-pm/board 0.22.0 → 0.23.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.
@@ -269,73 +269,109 @@ plot_manifest_for_worktree() { # $1=worktree → manifest path, or "" (non-zero)
269
269
  printf '%s' "$found"
270
270
  }
271
271
 
272
- # Read pid and startedAt from a manifest → "pid\tstartedAt", or "" (non-zero).
273
- #
274
- # Both fields are extracted; if either is missing the result is empty. A manifest
275
- # with no pid (an older format or a placeholder) returns nothing, which falls
276
- # through to the worktree's `.plot-worker.pid` for backward compatibility.
277
- plot_read_manifest_pid() { # $1=manifest path → "pid\tstartedAt", or "" (non-zero)
278
- local manifest="$1" pid started
272
+ # Read pid, startedAt and pidStartedAt from a manifest →
273
+ # "pid\tstartedAt\tpidStartedAt", or "" (non-zero).
274
+ #
275
+ # `pid` and `startedAt` are required; if either is missing the result is empty.
276
+ # A manifest with no pid (an older format or a placeholder) returns nothing,
277
+ # which falls through to the worktree's `.plot-worker.pid` for backward
278
+ # compatibility. `pidStartedAt` — the pid's OWN recorded start, `ps -o lstart`
279
+ # text stamped beside it at launch — is optional: an older manifest predating
280
+ # that field reads as the empty third column, which `plot_pid_is_current`
281
+ # reads as "none recorded" and falls back to its one-sided check.
282
+ plot_read_manifest_pid() { # $1=manifest path → "pid\tstartedAt\tpidStartedAt", or "" (non-zero)
283
+ local manifest="$1" pid started pid_started
279
284
  [ -f "$manifest" ] || return 1
280
285
 
281
286
  # Extract fields. The manifest is pretty-printed, one per line.
282
287
  pid=$(grep -m1 '"pid":' "$manifest" 2>/dev/null | sed 's/.*"pid": *"\([^"]*\)".*/\1/')
283
288
  started=$(grep -m1 '"startedAt":' "$manifest" 2>/dev/null | sed 's/.*"startedAt": *"\([^"]*\)".*/\1/')
289
+ pid_started=$(grep -m1 '"pidStartedAt":' "$manifest" 2>/dev/null | sed 's/.*"pidStartedAt": *"\([^"]*\)".*/\1/')
284
290
 
285
291
  [ -n "$pid" ] && [ -n "$started" ] || return 1
286
- printf '%s\t%s' "$pid" "$started"
292
+ printf '%s\t%s\t%s' "$pid" "$started" "$pid_started"
293
+ }
294
+
295
+ # Convert a `ps -o lstart=` string to epoch seconds, trying macOS's two
296
+ # `date -j` formats and then GNU's `-d`. Shared by both readings
297
+ # `plot_pid_is_current` compares — the live process's start and a pid's own
298
+ # recorded start use the same `ps -o lstart` shape.
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 \
301
+ || date -j -f "%c" "$1" +%s 2>/dev/null \
302
+ || date -d "$1" +%s 2>/dev/null
287
303
  }
288
304
 
289
- # Validate a pid against the manifest's startedAt → 0 if valid, non-zero if stale.
305
+ # Read a worktree's pid, startedAt and pidStartedAt — manifest first, then the
306
+ # bare `.plot-worker.pid`(`.startedAt`) fallback. Shared by `plot_worker_state`
307
+ # and `plot_worker_readings`, which both read the same three fields the same
308
+ # way before diverging on what they report.
309
+ _plot_pid_readings() { # $1=worktree → "pid\tstartedAt\tpidStartedAt" (pid empty if none found)
310
+ local wt="$1" manifest="" pid="" started="" pid_started=""
311
+ if manifest=$(plot_manifest_for_worktree "$wt" 2>/dev/null) && [ -n "$manifest" ]; then
312
+ IFS=$'\t' read -r pid started pid_started < <(plot_read_manifest_pid "$manifest")
313
+ fi
314
+ if [ -z "$pid" ] && [ -n "$wt" ] && [ -f "$wt/.plot-worker.pid" ]; then
315
+ pid=$(cat "$wt/.plot-worker.pid" 2>/dev/null | tr -d ' \n')
316
+ [ -f "$wt/.plot-worker.pid.startedAt" ] && pid_started=$(cat "$wt/.plot-worker.pid.startedAt" 2>/dev/null | tr -d '\n')
317
+ fi
318
+ printf '%s\t%s\t%s' "$pid" "$started" "$pid_started"
319
+ }
320
+
321
+ # Validate a pid against a recorded start → 0 if valid, non-zero if stale.
290
322
  #
291
- # A pid is stale when the process that holds it started BEFORE the manifest's
292
- # `startedAt`. The operating system reuses pids, so a recorded pid that now
293
- # belongs to an older, unrelated process must not read as `running`.
323
+ # A pid is stale when the process that holds it is not the one Plot recorded.
324
+ # The operating system reuses pids, so a recorded pid that now belongs to an
325
+ # unrelated process must not read as `running`.
294
326
  #
295
327
  # THE CHECK IS ON PROCESS START TIME, not existence. `kill -0` only says the pid
296
- # exists; this says whether it is the SAME process the dispatcher started.
328
+ # exists; this says whether it is the SAME process Plot started.
329
+ #
330
+ # Two readings, two comparisons:
331
+ # - $3 (the pid's OWN recorded start, `pidStartedAt`) when given: TWO-SIDED,
332
+ # within 3 s on either side. This is the per-pid start a writer stamped
333
+ # beside the pid itself, so an identical start is the expected case, not an
334
+ # edge one — a live worker's start never drifts from what was recorded for
335
+ # it, while a reused pid's real start lands outside the window in either
336
+ # direction (earlier for a process that predates the write, later for one
337
+ # that started after).
338
+ # - absent: ONE-SIDED, as before — the live process must have started at or
339
+ # after the manifest's own `startedAt` ($2), with the same 3 s slack. This
340
+ # is the fallback for a manifest stamped before `pidStartedAt` existed.
297
341
  #
298
342
  # Returns non-zero (stale) on any failure — an unparseable time, a process that
299
343
  # cannot be inspected, or a platform without `ps -o lstart`. The honest answer
300
344
  # for an uncheckable pid is "unknown", which the caller turns into `ended`.
301
- plot_pid_is_current() { # $1=pid $2=startedAt (ISO-8601) → 0 if current, 1 if stale
302
- local pid="$1" started="$2" proc_start manifest_epoch proc_epoch
303
-
304
- # Convert the manifest's startedAt (ISO-8601) to epoch seconds.
305
- # `date -j -f` is macOS; `date -d` is GNU. Try both.
306
- if manifest_epoch=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$started" +%s 2>/dev/null); then
307
- :
308
- elif manifest_epoch=$(date -d "$started" +%s 2>/dev/null); then
309
- :
310
- else
311
- return 1 # Cannot parse; treat as stale to be safe.
312
- fi
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
+ local pid="$1" started="$2" pid_started="${3:-}" proc_start manifest_epoch proc_epoch recorded_epoch slack=3
313
347
 
314
348
  # Get the process's start time from `ps -o lstart=`. This is portable across
315
349
  # macOS and Linux, though the format differs.
316
350
  proc_start=$(ps -o lstart= -p "$pid" 2>/dev/null | tr -d '\n')
317
351
  [ -n "$proc_start" ] || return 1 # Process does not exist.
318
-
319
- # Convert the process start time to epoch seconds.
320
- # macOS format: "Mon Aug 24 08:31:25 2026"
321
- # Linux format: varies; `date -d` handles it.
322
- if proc_epoch=$(date -j -f "%a %b %d %H:%M:%S %Y" "$proc_start" +%s 2>/dev/null); then
323
- :
324
- elif proc_epoch=$(date -j -f "%c" "$proc_start" +%s 2>/dev/null); then
325
- :
326
- elif proc_epoch=$(date -d "$proc_start" +%s 2>/dev/null); then
327
- :
328
- else
329
- return 1 # Cannot parse; treat as stale.
352
+ proc_epoch=$(_plot_lstart_epoch "$proc_start") || return 1 # Cannot parse; treat as stale.
353
+
354
+ if [ -n "$pid_started" ]; then
355
+ # TWO-SIDED: the pid's own recorded start, same `ps -o lstart` shape as the
356
+ # live reading, so the same parse helper handles both.
357
+ recorded_epoch=$(_plot_lstart_epoch "$pid_started") || return 1 # Cannot parse; treat as stale.
358
+ local diff=$((proc_epoch - recorded_epoch))
359
+ [ "$diff" -ge "-$slack" ] && [ "$diff" -le "$slack" ]
360
+ return
330
361
  fi
331
362
 
363
+ # ONE-SIDED fallback: no per-pid start recorded. Convert the manifest's
364
+ # startedAt (ISO-8601) to epoch seconds. `date -j -f` is macOS; `date -d` is
365
+ # 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.
368
+
332
369
  # A process that started BEFORE the manifest's startedAt is a reused pid.
333
370
  # A process that started AT or AFTER is the real worker. The slack is 3 s:
334
371
  # the wrapper writes the pid and then the manifest's awk stamps it, so the
335
372
  # second can tick over in between, and procps on Linux reports a start 0.8 to
336
373
  # 1.2 s early (`SKEW_MS` in `test/reconcile/own-process.mjs`). The stamp is
337
374
  # UTC, so the macOS parse takes `-u`; without it the stamp read as local time.
338
- local slack=3
339
375
  [ "$proc_epoch" -ge "$((manifest_epoch - slack))" ]
340
376
  }
341
377
 
@@ -1194,29 +1230,19 @@ plot_desk_loops() { PLOT_MANIFEST_DIR="${PLOT_MANIFEST_DIR:-}" node "${_plot_wst
1194
1230
  # Prints "state\tpid\tcode" — pid and code empty where they do not apply.
1195
1231
  # Never fails; an unreadable worktree is `none`, which is the honest answer.
1196
1232
  plot_worker_state() { # $1=worktree $2=pr-fact → "state\tpid\tcode"
1197
- local wt="$1" has_pr="${2:-}" pid="" code="" started_at="" manifest_data="" manifest=""
1198
-
1199
- # -------------------------------------------------------------------------
1200
- # Read the pid — first from the manifest, then from the worktree file.
1201
- # -------------------------------------------------------------------------
1202
- #
1203
- # THE MANIFEST IS PRIMARY. It carries both `pid` and `startedAt`, so a pid
1204
- # read here can be validated against the process's actual start time.
1205
- if manifest=$(plot_manifest_for_worktree "$wt" 2>/dev/null) && [ -n "$manifest" ]; then
1206
- if manifest_data=$(plot_read_manifest_pid "$manifest") && [ -n "$manifest_data" ]; then
1207
- pid=$(printf '%s' "$manifest_data" | cut -f1)
1208
- started_at=$(printf '%s' "$manifest_data" | cut -f2)
1209
- fi
1210
- fi
1211
-
1212
- # FALLBACK to the worktree pid file when the manifest has no usable pid.
1213
- # `started_at` stays empty; the staleness check is skipped, and the old
1214
- # behaviour applies — `kill -0` is trusted.
1215
- if [ -z "$pid" ]; then
1216
- [ -n "$wt" ] && [ -f "$wt/.plot-worker.pid" ] || { printf 'none\t\t'; return; }
1217
- pid=$(cat "$wt/.plot-worker.pid" 2>/dev/null | tr -d ' \n')
1218
- [ -n "$pid" ] || { printf 'none\t\t'; return; }
1219
- fi
1233
+ local wt="$1" has_pr="${2:-}" pid="" code="" started_at="" pid_started_at="" readings=""
1234
+
1235
+ # THE MANIFEST IS PRIMARY, with the worktree pid file as FALLBACK — carrying
1236
+ # `pid`, `startedAt` and the pid's own `pidStartedAt` together where a
1237
+ # manifest exists, or just the pid and its sidecar `pidStartedAt` where it
1238
+ # does not (a hand-started worker, or a manifest predating `startedAt`).
1239
+ # `_plot_pid_readings` reads both paths; `plot_pid_is_current` already
1240
+ # treats an empty `pidStartedAt` as "none recorded".
1241
+ readings=$(_plot_pid_readings "$wt")
1242
+ pid=$(printf '%s' "$readings" | cut -f1)
1243
+ started_at=$(printf '%s' "$readings" | cut -f2)
1244
+ pid_started_at=$(printf '%s' "$readings" | cut -f3)
1245
+ [ -n "$pid" ] || { printf 'none\t\t'; return; }
1220
1246
 
1221
1247
  # -------------------------------------------------------------------------
1222
1248
  # Validate the pid.
@@ -1238,13 +1264,13 @@ plot_worker_state() { # $1=worktree $2=pr-fact → "state\tpid\tcode"
1238
1264
  # only if the process holding it started at or after the time the manifest
1239
1265
  # was stamped.
1240
1266
  #
1241
- # Without `startedAt`, the old behaviour applies: `kill -0` alone decides.
1242
- # This keeps the fallback honest — an uncheckable pid is reported as running
1243
- # when it answers `kill -0`, exactly as before.
1267
+ # Without EITHER `startedAt` or `pidStartedAt`, the old behaviour applies:
1268
+ # `kill -0` alone decides. This keeps the fallback honest — an uncheckable
1269
+ # pid is reported as running when it answers `kill -0`, exactly as before.
1244
1270
  if kill -0 "$pid" 2>/dev/null; then
1245
- if [ -n "$started_at" ]; then
1271
+ if [ -n "$started_at" ] || [ -n "$pid_started_at" ]; then
1246
1272
  # STALENESS CHECK: is the process the one we started?
1247
- if ! plot_pid_is_current "$pid" "$started_at"; then
1273
+ if ! plot_pid_is_current "$pid" "$started_at" "$pid_started_at"; then
1248
1274
  # The pid exists but belongs to an older process — a REUSE. The worker
1249
1275
  # is dead; treat this as `ended` (no exit file can be trusted either).
1250
1276
  printf 'ended\t%s\t' "$pid"
@@ -1403,7 +1429,7 @@ plot_worker_state() { # $1=worktree $2=pr-fact → "state\tpid\tcode"
1403
1429
  # because it was told they differ. The PR fact is NOT here: it comes from the
1404
1430
  # caller, exactly as it does for `plot_worker_state`.
1405
1431
  plot_worker_readings() { # $1=worktree → "here\tpid\tliveness\texit\tblocked\tdirty\tunpushed"
1406
- local wt="$1" pid="" started_at="" manifest_data="" manifest=""
1432
+ local wt="$1" pid="" started_at="" pid_started_at="" manifest_data=""
1407
1433
  local here=1 pid_recorded=0 liveness=dead exit_field='-' blocked=0 dirty=0 ahead=""
1408
1434
 
1409
1435
  # NO WORKTREE IS ANSWERED FIRST, and it is a question about the worktree LIST
@@ -1415,17 +1441,14 @@ plot_worker_readings() { # $1=worktree → "here\tpid\tliveness\texit\tblocked\t
1415
1441
  return
1416
1442
  fi
1417
1443
 
1418
- # THE MANIFEST IS PRIMARY, as above: it carries `pid` and `startedAt`
1419
- # together, and `startedAt` is what tells a reused pid from the real worker.
1420
- if manifest=$(plot_manifest_for_worktree "$wt" 2>/dev/null) && [ -n "$manifest" ]; then
1421
- if manifest_data=$(plot_read_manifest_pid "$manifest") && [ -n "$manifest_data" ]; then
1422
- pid=$(printf '%s' "$manifest_data" | cut -f1)
1423
- started_at=$(printf '%s' "$manifest_data" | cut -f2)
1424
- fi
1425
- fi
1426
- if [ -z "$pid" ] && [ -f "$wt/.plot-worker.pid" ]; then
1427
- pid=$(cat "$wt/.plot-worker.pid" 2>/dev/null | tr -d ' \n')
1428
- fi
1444
+ # THE MANIFEST IS PRIMARY, as above: it carries `pid`, `startedAt` and
1445
+ # `pidStartedAt` together, and the pid's own start is what tells a reused
1446
+ # pid from the real worker. `_plot_pid_readings` reads it and the worktree
1447
+ # pid file fallback the same way `plot_worker_state` does.
1448
+ manifest_data=$(_plot_pid_readings "$wt")
1449
+ pid=$(printf '%s' "$manifest_data" | cut -f1)
1450
+ started_at=$(printf '%s' "$manifest_data" | cut -f2)
1451
+ pid_started_at=$(printf '%s' "$manifest_data" | cut -f3)
1429
1452
 
1430
1453
  # A pid of 0 and any non-numeric junk are NOT pids. `kill -0 0` signals the
1431
1454
  # whole process group and succeeds, so a zero read as live reports `running`
@@ -1440,7 +1463,7 @@ plot_worker_readings() { # $1=worktree → "here\tpid\tliveness\texit\tblocked\t
1440
1463
  # A recorded start time closes the pid-reuse window. Without one the old
1441
1464
  # behaviour applies and `kill -0` alone decides, which keeps an
1442
1465
  # uncheckable pid honest rather than pessimistic.
1443
- if [ -n "$started_at" ] && ! plot_pid_is_current "$pid" "$started_at"; then
1466
+ if { [ -n "$started_at" ] || [ -n "$pid_started_at" ]; } && ! plot_pid_is_current "$pid" "$started_at" "$pid_started_at"; then
1444
1467
  liveness=stale
1445
1468
  elif [ ! -f "$wt/.plot-worker.wrapper.pid" ]; then
1446
1469
  # NO WRAPPER FILE, NO AGENT QUESTION — the gate `plot_worker_state`