@plot-pm/board 0.25.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.
@@ -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
- }