@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/dist/board-server.mjs +340 -332
- package/package.json +2 -4
- package/plot-desk-root.sh +38 -12
- package/plot-dispatch.sh +69 -342
- package/plot-host.sh +119 -94
- package/plot-worker-state.sh +69 -93
- package/plot-agent-monitor.sh +0 -570
- package/plot-monitor-subject.sh +0 -245
package/plot-monitor-subject.sh
DELETED
|
@@ -1,245 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env bash
|
|
2
|
-
# Plot helper: the ONE answer to "is this monitor's subject still there?"
|
|
3
|
-
#
|
|
4
|
-
# SOURCED, NOT RUN, by `plot-agent-monitor.sh`. The same shape as
|
|
5
|
-
# `plot-worker-state.sh` and `plot-pr-merged.sh` — and the same reason.
|
|
6
|
-
# `plot-worker-state.sh` carried five of its six states in duplicate until
|
|
7
|
-
# 2026-08-18, and the copies had already drifted on the sixth. A monitor
|
|
8
|
-
# deciding independently when to stop, with its computation copied rather than
|
|
9
|
-
# shared, would drift the same way, and the failure would be silent: a monitor
|
|
10
|
-
# left running forever is exactly the leak this file exists to close.
|
|
11
|
-
#
|
|
12
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
13
|
-
# WHY A MONITOR NEEDS THIS AT ALL
|
|
14
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
15
|
-
#
|
|
16
|
-
# Measured 2026-08-30 and written up in
|
|
17
|
-
# `docs/research/2026-08-30-what-ends-a-monitor.md`: **nothing ended a monitor.**
|
|
18
|
-
# On an ordinary finish and on a `Worker bound` timeout alike, the wrapper's
|
|
19
|
-
# `wait "$agent"` returns, the wrapper writes `.plot-worker.exit` and exits, and
|
|
20
|
-
# both monitors are re-parented to `init` and loop forever. 34 of 40 monitors on
|
|
21
|
-
# the machine were `ppid=1` at the time of measurement, and 100 forks cost
|
|
22
|
-
# 23.3 ms against 4.8 ms on a quiet estate.
|
|
23
|
-
#
|
|
24
|
-
# The one run whose monitors WERE terminated is explained in that document and
|
|
25
|
-
# is not a mechanism: `nohup` does not `setsid`, so an orphan keeps the
|
|
26
|
-
# DISPATCHING SHELL's process group and a group kill sweeps it up collaterally.
|
|
27
|
-
# That fires when a human closes a terminal and never when a worker finishes —
|
|
28
|
-
# the opposite of a lifetime.
|
|
29
|
-
#
|
|
30
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
31
|
-
# THE SUBJECT IS THE AGENT, AND THAT IS THE WHOLE DESIGN
|
|
32
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
33
|
-
#
|
|
34
|
-
# A monitor exists to watch a dispatched agent. When that agent is gone there is
|
|
35
|
-
# nothing left to measure, so the monitor has finished its job rather than been
|
|
36
|
-
# interrupted — which is why this is a MEASUREMENT and not a timer.
|
|
37
|
-
#
|
|
38
|
-
# The plan forbids a timer explicitly, and the measurement says why: *"a monitor
|
|
39
|
-
# exiting after N seconds regardless would pass the visible assertions and
|
|
40
|
-
# destroy the property the whole plan rests on — a monitor that stops publishing
|
|
41
|
-
# means something."* A monitor that stops because its subject stopped carries
|
|
42
|
-
# information. One that stops because a clock ran out carries none, and is
|
|
43
|
-
# indistinguishable from one that crashed.
|
|
44
|
-
#
|
|
45
|
-
# THE AGENT COVERS ALL THREE ENDINGS. `--stop` kills the agent
|
|
46
|
-
# (`plot-dispatch.sh:752`); the `Worker bound` kills the agent
|
|
47
|
-
# (`plot-worker-loop.sh:172`); an ordinary finish is the agent exiting. In every
|
|
48
|
-
# case the wrapper survives just long enough to write `.plot-worker.exit` and
|
|
49
|
-
# then exits too. So watching the agent is sufficient, and watching the WRAPPER
|
|
50
|
-
# would be wrong: the wrapper outlives the agent by design, and a monitor bound
|
|
51
|
-
# to it would publish about a desk whose agent left.
|
|
52
|
-
#
|
|
53
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
54
|
-
# AN ABSENT PID FILE IS `starting`, NEVER `gone`
|
|
55
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
56
|
-
#
|
|
57
|
-
# `plot-dispatch.sh:478` records a sub-millisecond gap in which the wrapper has
|
|
58
|
-
# started and `.plot-worker.pid` is not yet written. The monitors start INSIDE
|
|
59
|
-
# that window — they are backgrounded before the agent, deliberately, so they
|
|
60
|
-
# exist before their subject does.
|
|
61
|
-
#
|
|
62
|
-
# So a monitor that read an absent pid file as `gone` would exit immediately on
|
|
63
|
-
# every single dispatch, and the leak would be replaced by a monitor that never
|
|
64
|
-
# runs. That is worse than the bug: an absent monitor is invisible, where an
|
|
65
|
-
# orphaned one at least shows up in `ps`.
|
|
66
|
-
#
|
|
67
|
-
# Three answers, not two:
|
|
68
|
-
#
|
|
69
|
-
# starting no pid file yet, or an unreadable one — the wrapper has not
|
|
70
|
-
# written it. Keep going; say nothing.
|
|
71
|
-
# alive the pid file names a process that exists. Keep going.
|
|
72
|
-
# gone the pid file names a process that does not exist. Stop.
|
|
73
|
-
#
|
|
74
|
-
# `starting` and `alive` are both "keep going", and they are kept apart anyway
|
|
75
|
-
# because the reason differs and a caller reporting them identically would lose
|
|
76
|
-
# the distinction the startup window depends on.
|
|
77
|
-
#
|
|
78
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
79
|
-
# THE LOWER BOUND IS THE CALLER'S, AND IT IS AN ORDERING
|
|
80
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
81
|
-
#
|
|
82
|
-
# The plan requires a monitor to outlive its agent long enough to record its
|
|
83
|
-
# finding — the Attaching slice's property, which this slice must not eat. This
|
|
84
|
-
# file does not enforce that, because it cannot: it answers a question and
|
|
85
|
-
# renders nothing.
|
|
86
|
-
#
|
|
87
|
-
# What enforces it is the ORDER in the callers: publish the pass, THEN ask.
|
|
88
|
-
# Every monitor therefore gets one final published pass after its agent has
|
|
89
|
-
# gone, which is the lower bound expressed as sequence rather than as a sleep.
|
|
90
|
-
# A caller that asked first and published second would satisfy the upper bound
|
|
91
|
-
# and silently lose the lower one — so the order is asserted in the tests, not
|
|
92
|
-
# left to a comment.
|
|
93
|
-
|
|
94
|
-
# `kill -0` is the liveness question, and it is the same one
|
|
95
|
-
# `plot-worker-state.sh` asks. It sends no signal; it only reports whether the
|
|
96
|
-
# pid can be signalled. A pid we do not own answers EPERM rather than ESRCH,
|
|
97
|
-
# which `kill -0` still reports as success — correct here, since a process we
|
|
98
|
-
# cannot signal is nonetheless a process that exists.
|
|
99
|
-
#
|
|
100
|
-
# `$1` = the path to the agent's pid file (`.plot-worker.pid`).
|
|
101
|
-
# Prints exactly one of: starting | alive | gone
|
|
102
|
-
plot_monitor_subject() {
|
|
103
|
-
local pid_file="${1:-}" pid
|
|
104
|
-
|
|
105
|
-
# No path at all: a hand-run monitor with no worktree, which has no subject to
|
|
106
|
-
# outlive and must not exit on its first pass. `starting` is the honest answer
|
|
107
|
-
# — there is nothing here that says the subject is gone.
|
|
108
|
-
[ -n "$pid_file" ] || { printf 'starting'; return 0; }
|
|
109
|
-
|
|
110
|
-
# NO PID FILE SPLITS TWO CASES, and reading them as one is what made monitors
|
|
111
|
-
# immortal. `starting` is right only while the desk is still there and the
|
|
112
|
-
# wrapper has not yet written the pid. If the DIRECTORY the pid file lives in
|
|
113
|
-
# is gone, the desk was removed — there is no subject to wait for and none is
|
|
114
|
-
# coming, so the honest answer is `gone`.
|
|
115
|
-
#
|
|
116
|
-
# Measured on CI 2026-08-31: 14 monitors at PPID 1, aged 11-13 minutes, each
|
|
117
|
-
# holding a `sleep 1`, after every test in the reconcile suite had PASSED.
|
|
118
|
-
# A test's fixture is removed at teardown, so its pid file vanishes BEFORE the
|
|
119
|
-
# agent does; `plot_monitor_wait` then never sees `gone` and loops forever,
|
|
120
|
-
# holding node's event loop open until the job ceiling kills it. That is the
|
|
121
|
-
# whole of the reconcile-suite hang, and it is why this is a two-case answer
|
|
122
|
-
# rather than one.
|
|
123
|
-
#
|
|
124
|
-
# PRODUCTION IS UNCHANGED: a real worktree outlives its agent, so the
|
|
125
|
-
# directory is present and this reads `starting` exactly as before.
|
|
126
|
-
if [ ! -f "$pid_file" ]; then
|
|
127
|
-
[ -d "${pid_file%/*}" ] && { printf 'starting'; return 0; }
|
|
128
|
-
printf 'gone'; return 0
|
|
129
|
-
fi
|
|
130
|
-
|
|
131
|
-
read -r pid < "$pid_file" 2>/dev/null
|
|
132
|
-
|
|
133
|
-
# A file that exists but holds no digits is a half-written pid, which is the
|
|
134
|
-
# startup window caught mid-`printf`. Not gone — UNLESS the wrapper has
|
|
135
|
-
# already recorded an exit beside it. `start_worker` removes that record
|
|
136
|
-
# before every start, so in the startup window it is absent. A worker loop
|
|
137
|
-
# that moves to a new desk empties the pid file it leaves
|
|
138
|
-
# (`move_worker_record`), and the wrapper still writes the exit into this
|
|
139
|
-
# desk when the loop ends; without this arm a monitor watching that desk
|
|
140
|
-
# would read `starting` forever.
|
|
141
|
-
case "$pid" in
|
|
142
|
-
'' | *[!0-9]*)
|
|
143
|
-
if [ -f "${pid_file%/*}/.plot-worker.exit" ]; then
|
|
144
|
-
printf 'gone'; return 0
|
|
145
|
-
fi
|
|
146
|
-
printf 'starting'; return 0 ;;
|
|
147
|
-
esac
|
|
148
|
-
|
|
149
|
-
if kill -0 "$pid" 2>/dev/null; then
|
|
150
|
-
printf 'alive'
|
|
151
|
-
else
|
|
152
|
-
printf 'gone'
|
|
153
|
-
fi
|
|
154
|
-
}
|
|
155
|
-
|
|
156
|
-
# Sleep up to `$1` seconds, but stop early the moment the subject at `$2` is
|
|
157
|
-
# gone. Returns 0 to publish another pass, 1 to leave.
|
|
158
|
-
#
|
|
159
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
160
|
-
# WHY THE WAIT IS SPLIT WHEN THE PUBLISHING IS NOT
|
|
161
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
162
|
-
#
|
|
163
|
-
# THE TWO CADENCES MUST STAY APART. The plan is explicit: the WorkerMonitor
|
|
164
|
-
# samples the process table every 30 s because a CPU delta is meaningless
|
|
165
|
-
# sampled further apart, and the AgentMonitor asks the host every 300 s because
|
|
166
|
-
# this repo has already measured what host questions on a fast loop cost. *"One
|
|
167
|
-
# subject wants tight sampling of a cheap fact; the other occasional sampling of
|
|
168
|
-
# an expensive one. Merging them would force one of those two to be wrong."*
|
|
169
|
-
#
|
|
170
|
-
# SO ONLY THE WAIT IS SPLIT, NEVER THE PASS. Publishing still happens on the
|
|
171
|
-
# monitor's own interval, unchanged — nothing here makes the AgentMonitor ask
|
|
172
|
-
# the host more often, and its 300 s stays 300 s. What is split is the IDLE TIME
|
|
173
|
-
# between passes, into short naps with a `kill -0` between them.
|
|
174
|
-
#
|
|
175
|
-
# WITHOUT THIS, THE UPPER BOUND IS THE INTERVAL. An AgentMonitor checking only
|
|
176
|
-
# after its full sleep would outlive an agent that finished in ten seconds by
|
|
177
|
-
# nearly five minutes. Bounded, technically — and still an orphan on every
|
|
178
|
-
# dispatch, on an estate where dispatches are frequent. The measurement that
|
|
179
|
-
# opened this slice counted 34 orphans; a five-minute window would have counted
|
|
180
|
-
# plenty too.
|
|
181
|
-
#
|
|
182
|
-
# THE PROBE IS FREE, WHICH IS WHY IT MAY BE FREQUENT. `kill -0` sends no signal
|
|
183
|
-
# and asks no host — it is a single syscall against the process table, the same
|
|
184
|
-
# question `plot-worker-state.sh` asks. The expensive half of an AgentMonitor
|
|
185
|
-
# pass is the host round trip, and that is in the PASS, not here.
|
|
186
|
-
#
|
|
187
|
-
# THE NAP IS THE GRANULARITY, and one second is chosen against the WorkerMonitor
|
|
188
|
-
# rather than in the abstract: a monitor may not outlive its agent by more than
|
|
189
|
-
# the tighter of the two cadences, or the fast monitor's exit would be slower
|
|
190
|
-
# than its own sampling. Any interval SHORTER than one nap sleeps once and is
|
|
191
|
-
# unaffected, which keeps `PLOT_MONITOR_INTERVAL=1` in a test behaving exactly
|
|
192
|
-
# as it reads.
|
|
193
|
-
plot_monitor_wait() { # $1 = seconds to wait, $2 = pid file
|
|
194
|
-
local remaining="${1:-0}" pid_file="${2:-}" nap
|
|
195
|
-
while [ "$remaining" -gt 0 ]; do
|
|
196
|
-
nap=1
|
|
197
|
-
[ "$remaining" -lt 1 ] && nap="$remaining"
|
|
198
|
-
sleep "$nap" || return 1
|
|
199
|
-
remaining=$((remaining - nap))
|
|
200
|
-
[ "$(plot_monitor_subject "$pid_file")" = gone ] && return 1
|
|
201
|
-
done
|
|
202
|
-
return 0
|
|
203
|
-
}
|
|
204
|
-
|
|
205
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
206
|
-
# WHICH DESK A MONITOR WATCHES THIS PASS, AFTER A HOP MAY HAVE MOVED ITS AGENT
|
|
207
|
-
# ═══════════════════════════════════════════════════════════════════════════
|
|
208
|
-
#
|
|
209
|
-
# `PLOT_WORKTREE` is fixed at launch, but `update_manifest_on_hop` rewrites the
|
|
210
|
-
# manifest's `worktree` field when the loop cuts a new desk — so a monitor that
|
|
211
|
-
# never re-reads it watches the launch desk forever. This is the shell twin of
|
|
212
|
-
# `watchedDesk` in `packages/domain/src/rules/desk-manifest.ts`, duplicated
|
|
213
|
-
# rather than called for the reason `docs/shell-and-domain.md` gives: both
|
|
214
|
-
# monitors re-read this every pass (30 s and 300 s), and a 39 ms bundle hop paid
|
|
215
|
-
# on every pass forever is the cost the shell side exists to avoid.
|
|
216
|
-
# `desk-manifest.corpus.test.ts` holds the pair; a disagreement stops the
|
|
217
|
-
# branch rather than being adjusted away.
|
|
218
|
-
#
|
|
219
|
-
# `$1` = the manifest file this monitor was handed (`PLOT_MANIFEST_FILE`), may
|
|
220
|
-
# be empty or absent.
|
|
221
|
-
# `$2` = the desk this monitor was launched on (`PLOT_WORKTREE`).
|
|
222
|
-
# Prints the desk to watch THIS pass.
|
|
223
|
-
plot_watched_desk() { # $1 = manifest file, $2 = launch desk → prints the watched desk
|
|
224
|
-
local manifest_file="${1:-}" launched="${2:-}" field
|
|
225
|
-
# ABSENT IS NOT FALSE. No manifest file named, or one that is gone, both mean
|
|
226
|
-
# "watch what you were launched on" — never a crash and never "watch
|
|
227
|
-
# nothing". A hand-started monitor with no `PLOT_MANIFEST_FILE` is a supported
|
|
228
|
-
# shape, not an error.
|
|
229
|
-
if [ -n "$manifest_file" ] && [ -f "$manifest_file" ]; then
|
|
230
|
-
# Same grep-and-sed idiom `plot_manifest_for_worktree` uses: the manifest is
|
|
231
|
-
# pretty-printed one field per line, so this avoids parsing JSON in bash.
|
|
232
|
-
field=$(grep -m1 '"worktree":' "$manifest_file" 2>/dev/null | sed 's/.*"worktree": *"\([^"]*\)".*/\1/')
|
|
233
|
-
else
|
|
234
|
-
field=''
|
|
235
|
-
fi
|
|
236
|
-
# Whitespace-only reads as absent too, matching the rule: trim leading and
|
|
237
|
-
# trailing space before testing for emptiness.
|
|
238
|
-
field="${field#"${field%%[![:space:]]*}"}"
|
|
239
|
-
field="${field%"${field##*[![:space:]]}"}"
|
|
240
|
-
if [ -n "$field" ]; then
|
|
241
|
-
printf '%s' "$field"
|
|
242
|
-
else
|
|
243
|
-
printf '%s' "$launched"
|
|
244
|
-
fi
|
|
245
|
-
}
|