agentlane 0.5.0 → 0.6.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.
@@ -0,0 +1,384 @@
1
+ import { startMs } from "../processes.js";
2
+ import { isProven, judgeProcess } from "./owner.js";
3
+ import { readPark } from "./parks.js";
4
+ import { values } from "./rows.js";
5
+ import { int, optInt, optText, text } from "./store.js";
6
+ /** How long a running shared service is left up once no active lane, and no teardown, needs it. */
7
+ export const SHARED_IDLE_MS = 5 * 60_000;
8
+ /**
9
+ * How long after a failed stop the sweep tries that stop again: the MCP servers' sweep interval, so the commands passing
10
+ * by start a sweeper for it at most once a minute.
11
+ */
12
+ export const SHARED_STOP_RETRY_MS = 60_000;
13
+ /** The longest one run of a shared service's ready may take. */
14
+ export const SHARED_READY_RUN_MAX_MS = 30_000;
15
+ /** What a start or stop may take beyond its commands: the registry writes and process launches around them. */
16
+ export const SHARED_HOLD_MARGIN_MS = 30_000;
17
+ /** `ps` gives a process's start to the second, so the start of a command read back may be up to a second early. */
18
+ const PS_START_SLACK_MS = 2_000;
19
+ /**
20
+ * How long a live process may hold the start or stop of a shared service whose commands may take `timeoutMs` before the
21
+ * lanes waiting on it, and the sweep, count it as hung: a start's worst case, which is its first ready run, its start,
22
+ * then the window for ready to pass, plus SHARED_HOLD_MARGIN_MS. A stop takes at most its timeout.
23
+ */
24
+ export function sharedHoldMs(timeoutMs) {
25
+ return 2 * timeoutMs + Math.min(timeoutMs, SHARED_READY_RUN_MAX_MS) + SHARED_HOLD_MARGIN_MS;
26
+ }
27
+ function holdMsSql(timeout) {
28
+ return `(2 * ${timeout} + MIN(${timeout}, ${String(SHARED_READY_RUN_MAX_MS)}) + ${String(SHARED_HOLD_MARGIN_MS)})`;
29
+ }
30
+ /**
31
+ * Whether a lane counts as active for shared services: neither parked nor ended. A lane being parked is active until its
32
+ * park finishes, unless it was parked before, which a park retried by the sweep is.
33
+ */
34
+ export function laneActive(park) {
35
+ if (!park)
36
+ return true;
37
+ if (park.state === 'waking')
38
+ return true;
39
+ return park.state === 'parking' && park.parkedAt === null;
40
+ }
41
+ const ACTIVE_PARK = `(p.claim_id IS NULL OR p.state = 'waking' OR (p.state = 'parking' AND p.parked_at IS NULL))`;
42
+ const ACTIVE_NEEDERS = `SELECT n.claim_id AS id FROM shared_needs n JOIN claims c ON c.id = n.claim_id
43
+ LEFT JOIN parks p ON p.claim_id = c.id
44
+ WHERE c.project_root = ? AND n.name = ? AND ${ACTIVE_PARK}`;
45
+ const HELD_ROWS = `SELECT r.seq, r.claim_id, r.name, r.holder_pid, r.holder_start FROM resources r
46
+ WHERE r.holder_pid IS NOT NULL AND r.repository = ? AND EXISTS (SELECT 1 FROM json_each(r.needs) j WHERE j.value = ?)`;
47
+ /**
48
+ * A held resource row needing shared service `s` whose hold, at `:now`, is younger than its teardown's timeout plus the
49
+ * shared service's hold. The reads that ask no `ps` count it as needing the service; an older one's holder is left to
50
+ * the stop's claim, which asks `ps` whether it lives.
51
+ */
52
+ const RECENT_HOLD = `SELECT 1 FROM resources r WHERE r.holder_pid IS NOT NULL AND r.repository = s.repository
53
+ AND EXISTS (SELECT 1 FROM json_each(r.needs) j WHERE j.value = s.name)
54
+ AND r.holder_since > :now - (r.timeout_ms + ${holdMsSql('s.timeout_ms')})`;
55
+ function activeNeeders(db, key) {
56
+ return db
57
+ .prepare(`${ACTIVE_NEEDERS} ORDER BY n.claim_id`)
58
+ .all(key.repository, key.name)
59
+ .map(r => text(r, 'id'));
60
+ }
61
+ function heldRows(db, key) {
62
+ return db.prepare(`${HELD_ROWS} ORDER BY r.seq`).all(key.repository, key.name);
63
+ }
64
+ function commandsOf(row) {
65
+ return {
66
+ start: text(row, 'start'),
67
+ stop: text(row, 'stop'),
68
+ ready: text(row, 'ready'),
69
+ cwd: text(row, 'cwd'),
70
+ timeoutMs: int(row, 'timeout_ms'),
71
+ env: values(row, 'env'),
72
+ };
73
+ }
74
+ function holderOf(row) {
75
+ const pid = optInt(row, 'holder_pid');
76
+ const start = optText(row, 'holder_start');
77
+ return pid !== null && start !== null ? { pid, start } : null;
78
+ }
79
+ function commandOf(row) {
80
+ const pid = optInt(row, 'command_pid');
81
+ const start = optText(row, 'command_start');
82
+ return pid !== null && start !== null ? { pid, start } : null;
83
+ }
84
+ function readRow(db, key) {
85
+ return db.prepare('SELECT * FROM shared_services WHERE repository = ? AND name = ?').get(key.repository, key.name);
86
+ }
87
+ function seenKey(pid, start) {
88
+ return `${String(pid)}:${start}`;
89
+ }
90
+ export function sharedHoldersBeforeLock(db, processes) {
91
+ const seen = new Set();
92
+ const pids = new Set();
93
+ const holders = [
94
+ ...db.prepare('SELECT holder_pid AS pid, holder_start AS start FROM shared_services WHERE holder_pid IS NOT NULL').all(),
95
+ ...db.prepare('SELECT holder_pid AS pid, holder_start AS start FROM resources WHERE holder_pid IS NOT NULL').all(),
96
+ ];
97
+ const commands = db
98
+ .prepare('SELECT command_pid AS pid, command_start AS start FROM shared_services WHERE command_pid IS NOT NULL')
99
+ .all();
100
+ for (const row of [...holders, ...commands]) {
101
+ const pid = int(row, 'pid');
102
+ seen.add(seenKey(pid, text(row, 'start')));
103
+ pids.add(pid);
104
+ }
105
+ const table = pids.size === 0 ? new Map() : processes.startTimes([...pids]);
106
+ return { table, seen, wallNow: Date.now() };
107
+ }
108
+ /** Whether `holder` was in the snapshot and the snapshot proves it gone; a holder taken on after the snapshot counts as alive. */
109
+ function provenGone(holder, holders) {
110
+ if (!holders.seen.has(seenKey(holder.pid, holder.start)))
111
+ return false;
112
+ return isProven(judgeProcess(holder, holders.table));
113
+ }
114
+ function sameHolder(row, me) {
115
+ const holder = holderOf(row);
116
+ return holder !== null && holder.pid === me.pid && holder.start === me.start;
117
+ }
118
+ /**
119
+ * The command a row's holder recorded and left running, unless the snapshot proves its shell gone. A command has ended
120
+ * once its shell has exited, as it has for a live holder: what it left running then is the server it started. A command
121
+ * recorded after the snapshot counts as running.
122
+ */
123
+ function orphanOf(row, holders) {
124
+ const shell = commandOf(row);
125
+ if (!shell)
126
+ return null;
127
+ if (provenGone(shell, holders))
128
+ return null;
129
+ return { shell, overdue: holders.wallNow - startMs(shell.start) > int(row, 'timeout_ms') + PS_START_SLACK_MS };
130
+ }
131
+ function describeOrphan(state, holder, orphan) {
132
+ const what = state === 'starting' ? 'start' : 'stop';
133
+ return `the ${what} that pid ${String(holder.pid)} left running when it died still runs as pid ${String(orphan.shell.pid)}`;
134
+ }
135
+ /**
136
+ * Records what a lane needs: exactly `names`. A name it no longer needs is marked as unneeded from `now` when the lane
137
+ * is active and was the last active lane needing it; one it needs again is no longer marked while the lane is active.
138
+ */
139
+ export function recordLaneNeeds(db, laneId, repository, names, now) {
140
+ const before = new Set(db
141
+ .prepare('SELECT name FROM shared_needs WHERE claim_id = ?')
142
+ .all(laneId)
143
+ .map(r => text(r, 'name')));
144
+ const wanted = new Set(names);
145
+ const insert = db.prepare('INSERT OR IGNORE INTO shared_needs (claim_id, name) VALUES (?, ?)');
146
+ for (const name of wanted)
147
+ insert.run(laneId, name);
148
+ const dropped = [...before].filter(n => !wanted.has(n));
149
+ const remove = db.prepare('DELETE FROM shared_needs WHERE claim_id = ? AND name = ?');
150
+ for (const name of dropped)
151
+ remove.run(laneId, name);
152
+ if (!laneActive(readPark(db, laneId)))
153
+ return;
154
+ markUnneeded(db, repository, dropped, now);
155
+ const clear = db.prepare('UPDATE shared_services SET unneeded_since = NULL WHERE repository = ? AND name = ?');
156
+ for (const name of wanted)
157
+ clear.run(repository, name);
158
+ }
159
+ /** The shared services a lane needs and its repository, read before a transition that may end its need. */
160
+ export function laneNeeds(db, laneId) {
161
+ return db
162
+ .prepare('SELECT c.project_root AS repository, n.name FROM shared_needs n JOIN claims c ON c.id = n.claim_id WHERE n.claim_id = ?')
163
+ .all(laneId)
164
+ .map(r => ({ repository: text(r, 'repository'), name: text(r, 'name') }));
165
+ }
166
+ /**
167
+ * Marks each of `names` in `repository` as unneeded from `now` when no active lane needs it: the moment the last of
168
+ * them parked or ended, or a resource row that needs it let go. A held resource row doesn't hold the mark back: the
169
+ * stop's claim refuses while its holder lives, and its letting go marks the service again.
170
+ */
171
+ export function markUnneeded(db, repository, names, now) {
172
+ const mark = db.prepare('UPDATE shared_services SET unneeded_since = ? WHERE repository = ? AND name = ?');
173
+ for (const name of new Set(names)) {
174
+ if (activeNeeders(db, { repository, name }).length > 0)
175
+ continue;
176
+ mark.run(now, repository, name);
177
+ }
178
+ }
179
+ /** `markUnneeded` for what `needs` held, once a lane has stopped being active. */
180
+ export function markNeedsUnneeded(db, needs, now) {
181
+ for (const need of needs)
182
+ markUnneeded(db, need.repository, [need.name], now);
183
+ }
184
+ /**
185
+ * Takes the start of a shared service for `need`, or says why not: `running` when it is recorded as running with no
186
+ * problem (unless `foundDown`, when the caller found it not answering), `busy` while a live process starts or stops it,
187
+ * or while the shell of the command of one that died still runs. A start or stop whose holder the snapshot proves gone,
188
+ * and whose command's shell it proves exited, is taken over. The commands recorded are `spec`, or for a teardown, those of its last start.
189
+ * Either way it no longer counts as unneeded.
190
+ */
191
+ export function beginStart(db, need, name, spec, foundDown, me, holders, now) {
192
+ const key = { repository: need.repository, name };
193
+ const row = readRow(db, key);
194
+ if (need.kind === 'lane')
195
+ db.prepare('INSERT OR IGNORE INTO shared_needs (claim_id, name) VALUES (?, ?)').run(need.lane, name);
196
+ if (!row) {
197
+ if (!spec)
198
+ return { kind: 'unknown', key };
199
+ db.prepare(`INSERT INTO shared_services (repository, name, state, since, start, stop, ready, cwd, timeout_ms, env, holder_pid, holder_start)
200
+ VALUES (?, ?, 'starting', ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(key.repository, name, now, spec.start, spec.stop, spec.ready, spec.cwd, spec.timeoutMs, JSON.stringify(spec.env), me.pid, me.start);
201
+ return { kind: 'claimed', key, commands: spec, took: null };
202
+ }
203
+ db.prepare('UPDATE shared_services SET unneeded_since = NULL WHERE repository = ? AND name = ?').run(key.repository, name);
204
+ const state = text(row, 'state');
205
+ const holder = holderOf(row);
206
+ let took = null;
207
+ if (state === 'running' && optText(row, 'problem') === null && !foundDown) {
208
+ return { kind: 'running', key, commands: commandsOf(row) };
209
+ }
210
+ if ((state === 'starting' || state === 'stopping') && holder) {
211
+ const busy = { kind: 'busy', key, state, holder, since: int(row, 'since'), timeoutMs: int(row, 'timeout_ms') };
212
+ if (!provenGone(holder, holders))
213
+ return { ...busy, orphan: null };
214
+ const orphan = orphanOf(row, holders);
215
+ if (orphan)
216
+ return { ...busy, orphan };
217
+ took = { state, pid: holder.pid };
218
+ }
219
+ const commands = spec ?? commandsOf(row);
220
+ db.prepare(`UPDATE shared_services SET state = 'starting', since = ?, start = ?, stop = ?, ready = ?, cwd = ?, timeout_ms = ?, env = ?,
221
+ holder_pid = ?, holder_start = ?, command_pid = NULL, command_start = NULL WHERE repository = ? AND name = ?`).run(now, commands.start, commands.stop, commands.ready, commands.cwd, commands.timeoutMs, JSON.stringify(commands.env), me.pid, me.start, key.repository, name);
222
+ return { kind: 'claimed', key, commands, took };
223
+ }
224
+ /**
225
+ * Records the shell of the start or stop command `me` runs for a shared service, which leads a process group of its
226
+ * own, so a process taking over once `me` has died waits for that command. False when `me` no longer holds it.
227
+ */
228
+ export function noteCommand(db, key, shell, me) {
229
+ const noted = db
230
+ .prepare(`UPDATE shared_services SET command_pid = ?, command_start = ?
231
+ WHERE repository = ? AND name = ? AND holder_pid = ? AND holder_start = ?`)
232
+ .run(shell.pid, shell.start, key.repository, key.name, me.pid, me.start);
233
+ return noted.changes > 0;
234
+ }
235
+ /** Forgets the command `me` recorded, once it has ended. */
236
+ export function endCommand(db, key, me) {
237
+ db.prepare(`UPDATE shared_services SET command_pid = NULL, command_start = NULL
238
+ WHERE repository = ? AND name = ? AND holder_pid = ? AND holder_start = ?`).run(key.repository, key.name, me.pid, me.start);
239
+ }
240
+ const LET_GO = 'holder_pid = NULL, holder_start = NULL, command_pid = NULL, command_start = NULL';
241
+ /** Records the start `me` holds as done: the shared service runs. False when `me` no longer holds it. */
242
+ export function finishStart(db, key, me, now) {
243
+ const row = readRow(db, key);
244
+ if (!row || text(row, 'state') !== 'starting' || !sameHolder(row, me))
245
+ return false;
246
+ db.prepare(`UPDATE shared_services SET state = 'running', since = ?, ${LET_GO}, problem = NULL,
247
+ attempts = 0, last_attempt_at = NULL WHERE repository = ? AND name = ?`).run(now, key.repository, key.name);
248
+ return true;
249
+ }
250
+ /**
251
+ * Records the start `me` holds as failed. It may have left the server partly up, so the shared service stays recorded
252
+ * as running, with the problem: the sweep stops it once nothing needs it, and a lane's next start runs its start again.
253
+ */
254
+ export function failStart(db, key, problem, me, now) {
255
+ const row = readRow(db, key);
256
+ if (!row || text(row, 'state') !== 'starting' || !sameHolder(row, me))
257
+ return;
258
+ db.prepare(`UPDATE shared_services SET state = 'running', since = ?, ${LET_GO}, problem = ? WHERE repository = ? AND name = ?`).run(now, problem, key.repository, key.name);
259
+ }
260
+ /**
261
+ * Takes the stop of a shared service once nothing needs it: no active lane, and no resource row held by a process the
262
+ * snapshot doesn't prove gone. It must have been unneeded since `windows.idleSince`; one nothing needs that was never
263
+ * marked is marked now. A start or stop whose holder the snapshot proves gone is taken over once its command's shell
264
+ * has exited; until then it is left, with that command.
265
+ */
266
+ export function beginStop(db, key, me, holders, now, windows) {
267
+ const row = readRow(db, key);
268
+ if (!row)
269
+ return { kind: 'left', key, reason: 'it is not recorded' };
270
+ const state = text(row, 'state');
271
+ if (state === 'stopped')
272
+ return { kind: 'left', key, reason: 'it is stopped' };
273
+ const holder = holderOf(row);
274
+ let took = null;
275
+ if (holder) {
276
+ if (!provenGone(holder, holders))
277
+ return { kind: 'left', key, reason: `pid ${String(holder.pid)} is ${state} it` };
278
+ took = { state, pid: holder.pid };
279
+ }
280
+ const lanes = activeNeeders(db, key);
281
+ if (lanes.length > 0)
282
+ return { kind: 'left', key, reason: `lanes ${lanes.join(', ')} need it` };
283
+ const held = heldRows(db, key).find(r => {
284
+ const h = holderOf(r);
285
+ return h !== null && !provenGone(h, holders);
286
+ });
287
+ if (held) {
288
+ return {
289
+ kind: 'left',
290
+ key,
291
+ reason: `resource ${text(held, 'name')} of lane ${text(held, 'claim_id')}, which needs it, is being created or torn down`,
292
+ };
293
+ }
294
+ const lastAttempt = optInt(row, 'last_attempt_at');
295
+ if (state === 'running' && lastAttempt !== null && lastAttempt > windows.retrySince) {
296
+ return { kind: 'left', key, reason: 'its last stop failed lately' };
297
+ }
298
+ const unneededSince = optInt(row, 'unneeded_since');
299
+ if (unneededSince === null) {
300
+ db.prepare('UPDATE shared_services SET unneeded_since = ? WHERE repository = ? AND name = ?').run(now, key.repository, key.name);
301
+ return { kind: 'left', key, reason: 'nothing needs it from now' };
302
+ }
303
+ if (unneededSince > windows.idleSince)
304
+ return { kind: 'left', key, reason: 'it was needed lately' };
305
+ const orphan = holder ? orphanOf(row, holders) : null;
306
+ if (holder && orphan)
307
+ return { kind: 'left', key, reason: describeOrphan(state, holder, orphan), orphan };
308
+ db.prepare(`UPDATE shared_services SET state = 'stopping', since = ?, holder_pid = ?, holder_start = ?, command_pid = NULL,
309
+ command_start = NULL WHERE repository = ? AND name = ?`).run(now, me.pid, me.start, key.repository, key.name);
310
+ return { kind: 'claimed', key, commands: commandsOf(row), unneededSince, took };
311
+ }
312
+ /** Records the stop `me` holds as done. */
313
+ export function finishStop(db, key, me, now) {
314
+ const row = readRow(db, key);
315
+ if (!row || text(row, 'state') !== 'stopping' || !sameHolder(row, me))
316
+ return;
317
+ db.prepare(`UPDATE shared_services SET state = 'stopped', since = ?, ${LET_GO}, problem = NULL,
318
+ attempts = 0, last_attempt_at = NULL, unneeded_since = NULL WHERE repository = ? AND name = ?`).run(now, key.repository, key.name);
319
+ }
320
+ /** Records the stop `me` holds as failed: the shared service is still running, with the problem, until a later sweep's stop. */
321
+ export function failStop(db, key, problem, me, now) {
322
+ const row = readRow(db, key);
323
+ if (!row || text(row, 'state') !== 'stopping' || !sameHolder(row, me))
324
+ return;
325
+ db.prepare(`UPDATE shared_services SET state = 'running', since = ?, ${LET_GO}, problem = ?,
326
+ attempts = attempts + 1, last_attempt_at = ? WHERE repository = ? AND name = ?`).run(now, problem, now, key.repository, key.name);
327
+ }
328
+ const UNNEEDED = `NOT EXISTS (SELECT 1 FROM shared_needs n JOIN claims c ON c.id = n.claim_id
329
+ LEFT JOIN parks p ON p.claim_id = c.id
330
+ WHERE c.project_root = s.repository AND n.name = s.name AND ${ACTIVE_PARK})
331
+ AND NOT EXISTS (${RECENT_HOLD})`;
332
+ /**
333
+ * The shared services the sweep may have to stop or mark, by one read: those no active lane needs, unmarked or
334
+ * unneeded since `windows.idleSince`, that are running with no stop failed after `windows.retrySince`, or that a start
335
+ * or stop has held for longer than `sharedHoldMs`. A held resource row counts as needing its services while it was
336
+ * taken lately; an older one is left to the stop's claim, which asks `ps` whether its holder lives.
337
+ */
338
+ export function stopCandidates(db, now, windows) {
339
+ return db
340
+ .prepare(`SELECT s.repository, s.name FROM shared_services s
341
+ WHERE (s.unneeded_since IS NULL OR s.unneeded_since <= :idleSince)
342
+ AND ((s.state = 'running' AND (s.last_attempt_at IS NULL OR s.last_attempt_at <= :retrySince))
343
+ OR (s.state IN ('starting', 'stopping') AND s.since <= :now - ${holdMsSql('s.timeout_ms')}))
344
+ AND ${UNNEEDED}
345
+ ORDER BY s.repository, s.name`)
346
+ .all({ idleSince: windows.idleSince, retrySince: windows.retrySince, now })
347
+ .map(r => ({ repository: text(r, 'repository'), name: text(r, 'name') }));
348
+ }
349
+ function heldLately(db, key, now) {
350
+ return (db
351
+ .prepare(`SELECT 1 FROM shared_services s WHERE s.repository = :repository AND s.name = :name AND EXISTS (${RECENT_HOLD})`)
352
+ .get({ repository: key.repository, name: key.name, now }) !== undefined);
353
+ }
354
+ /** Every shared service with what needs it, and when the sweep stops it as of `now`. */
355
+ export function readShared(db, now) {
356
+ return db
357
+ .prepare('SELECT * FROM shared_services ORDER BY repository, name')
358
+ .all()
359
+ .map(row => {
360
+ const key = { repository: text(row, 'repository'), name: text(row, 'name') };
361
+ const state = text(row, 'state');
362
+ const lanes = activeNeeders(db, key);
363
+ const holding = heldRows(db, key).map(r => ({ lane: text(r, 'claim_id'), resource: text(r, 'name') }));
364
+ const unneededSince = optInt(row, 'unneeded_since');
365
+ const lastAttempt = optInt(row, 'last_attempt_at');
366
+ const idle = state === 'running' && lanes.length === 0 && !heldLately(db, key, now);
367
+ const stopsAt = idle && unneededSince !== null
368
+ ? Math.max(unneededSince + SHARED_IDLE_MS, lastAttempt === null ? 0 : lastAttempt + SHARED_STOP_RETRY_MS)
369
+ : null;
370
+ return {
371
+ ...key,
372
+ state,
373
+ since: int(row, 'since'),
374
+ lanes,
375
+ holding,
376
+ unneededSince,
377
+ stopsAt,
378
+ by: optInt(row, 'holder_pid'),
379
+ problem: optText(row, 'problem'),
380
+ attempts: int(row, 'attempts'),
381
+ commands: commandsOf(row),
382
+ };
383
+ });
384
+ }
@@ -4,8 +4,15 @@ import { readCheck, RETURN_WINDOW_MS } from "./owner-checks.js";
4
4
  import { readPark } from "./parks.js";
5
5
  import { pendingTeardowns } from "./resources.js";
6
6
  import { endedFromHistory, loadLaneInfo } from "./rows.js";
7
+ import { readShared } from "./shared.js";
7
8
  import { int, optText, text } from "./store.js";
8
9
  const RECENT_MS = 24 * 3_600_000;
10
+ /** What a 0.5.x registry lacks of the shared services' records; status reads such a registry as having none. */
11
+ const SHARED_ADDITIONS = ['shared_services', 'shared_needs', 'resources.repository', 'resources.needs'];
12
+ /** Whether status can read a registry that lacks `lacking` without upgrading it first. */
13
+ export function readsAsIs(lacking) {
14
+ return lacking.every(a => SHARED_ADDITIONS.includes(a));
15
+ }
9
16
  function processState(verdict) {
10
17
  if (verdict === 'alive')
11
18
  return 'running';
@@ -24,6 +31,7 @@ export function readStatus(store, sources) {
24
31
  queue: [],
25
32
  recent: [],
26
33
  teardowns: [],
34
+ shared: [],
27
35
  };
28
36
  if (!store)
29
37
  return report;
@@ -124,5 +132,7 @@ export function readStatus(store, sources) {
124
132
  .all(now - RECENT_MS)
125
133
  .map(endedFromHistory);
126
134
  report.teardowns = pendingTeardowns(db);
135
+ if (!store.lacking().some(a => SHARED_ADDITIONS.includes(a)))
136
+ report.shared = readShared(db, now);
127
137
  return report;
128
138
  }
@@ -96,8 +96,51 @@ CREATE TABLE IF NOT EXISTS owner_checks (
96
96
  AND (reaper_pid IS NULL) = (attempt IS NULL)),
97
97
  CHECK (reaper_pid IS NULL OR gone IS NOT NULL)
98
98
  ) STRICT;
99
+ CREATE TABLE IF NOT EXISTS shared_services (
100
+ repository TEXT NOT NULL,
101
+ name TEXT NOT NULL,
102
+ state TEXT NOT NULL,
103
+ since INTEGER NOT NULL,
104
+ start TEXT NOT NULL,
105
+ stop TEXT NOT NULL,
106
+ ready TEXT NOT NULL,
107
+ cwd TEXT NOT NULL,
108
+ timeout_ms INTEGER NOT NULL,
109
+ env TEXT NOT NULL,
110
+ unneeded_since INTEGER,
111
+ holder_pid INTEGER,
112
+ holder_start TEXT,
113
+ command_pid INTEGER,
114
+ command_start TEXT,
115
+ attempts INTEGER NOT NULL DEFAULT 0,
116
+ last_attempt_at INTEGER,
117
+ problem TEXT,
118
+ PRIMARY KEY (repository, name),
119
+ CHECK (state IN ('stopped', 'starting', 'running', 'stopping')),
120
+ CHECK ((holder_pid IS NULL) = (state IN ('stopped', 'running')) AND (holder_pid IS NULL) = (holder_start IS NULL)),
121
+ CHECK ((command_pid IS NULL) = (command_start IS NULL) AND (command_pid IS NULL OR holder_pid IS NOT NULL))
122
+ ) STRICT;
123
+ CREATE TABLE IF NOT EXISTS shared_needs (
124
+ claim_id TEXT NOT NULL REFERENCES claims(id) ON DELETE CASCADE,
125
+ name TEXT NOT NULL,
126
+ PRIMARY KEY (claim_id, name)
127
+ ) STRICT;
99
128
  `;
100
- const ADDED_TABLES = ['resources', 'browsers', 'process_alive', 'device_leases', 'parks', 'holds', 'owner_checks'];
129
+ const ADDED_TABLES = [
130
+ 'resources',
131
+ 'browsers',
132
+ 'process_alive',
133
+ 'device_leases',
134
+ 'parks',
135
+ 'holds',
136
+ 'owner_checks',
137
+ 'shared_services',
138
+ 'shared_needs',
139
+ ];
140
+ const ADDED_COLUMNS = [
141
+ { table: 'resources', column: 'repository', sql: 'ALTER TABLE resources ADD COLUMN repository TEXT' },
142
+ { table: 'resources', column: 'needs', sql: "ALTER TABLE resources ADD COLUMN needs TEXT NOT NULL DEFAULT '[]'" },
143
+ ];
101
144
  const SCHEMA = `
102
145
  CREATE TABLE claims (
103
146
  id TEXT PRIMARY KEY,
@@ -213,11 +256,15 @@ function untilFree(deadline, action, onTimeout) {
213
256
  }
214
257
  }
215
258
  }
259
+ function newerFormat(dir, version) {
260
+ return new UsageError(`${databasePath(dir)} is registry format ${String(version)}, newer than this ${TOOL} understands (${String(SCHEMA_VERSION)})`, `upgrade ${TOOL} to the version every project on this Mac uses`);
261
+ }
262
+ export const UNIDENTIFIED = 'an unidentified caller';
216
263
  export class Store {
217
264
  db;
218
265
  dir;
219
266
  lockWaitMs;
220
- actor = { who: 'an unidentified caller', folder: process.cwd() };
267
+ actor = { who: UNIDENTIFIED, folder: process.cwd() };
221
268
  constructor(dir, db, lockWaitMs) {
222
269
  this.dir = dir;
223
270
  this.db = db;
@@ -238,7 +285,7 @@ export class Store {
238
285
  const added = untilFree(deadline, () => store.hasAdditions(), () => store.busyRefusal());
239
286
  if (!added) {
240
287
  store.write(() => {
241
- store.db.exec(FORMAT_1_ADDITIONS);
288
+ store.addToFormat1();
242
289
  });
243
290
  }
244
291
  return store;
@@ -248,6 +295,41 @@ export class Store {
248
295
  return null;
249
296
  return Store.open(dir, lockWaitMs);
250
297
  }
298
+ /**
299
+ * Opens the registry for reading, without upgrading or writing it, or returns null when there is none yet. A
300
+ * registry an earlier 0.x wrote is read as it is; `lacking` names what it doesn't have.
301
+ */
302
+ static openToRead(dir, lockWaitMs) {
303
+ if (!fs.existsSync(databasePath(dir)))
304
+ return null;
305
+ const db = new DatabaseSync(databasePath(dir), { readOnly: true, timeout: Math.min(1000, lockWaitMs) });
306
+ const store = new Store(dir, db, lockWaitMs);
307
+ let version;
308
+ try {
309
+ version = untilFree(Date.now() + lockWaitMs, () => store.version(), () => store.busyRefusal());
310
+ }
311
+ catch (error) {
312
+ store.close();
313
+ throw error;
314
+ }
315
+ if (version === SCHEMA_VERSION)
316
+ return store;
317
+ store.close();
318
+ if (version > SCHEMA_VERSION)
319
+ throw newerFormat(dir, version);
320
+ return null;
321
+ }
322
+ /** The tables and columns later versions added to format 1 that this registry lacks, as `table` or `table.column`. */
323
+ lacking() {
324
+ const tables = new Set(this.db
325
+ .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
326
+ .all()
327
+ .map(row => text(row, 'name')));
328
+ return [
329
+ ...ADDED_TABLES.filter(t => !tables.has(t)),
330
+ ...ADDED_COLUMNS.filter(c => tables.has(c.table) && !this.hasColumn(c.table, c.column)).map(c => `${c.table}.${c.column}`),
331
+ ];
332
+ }
251
333
  close() {
252
334
  this.db.close();
253
335
  }
@@ -255,7 +337,18 @@ export class Store {
255
337
  const found = this.db
256
338
  .prepare(`SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name IN (${ADDED_TABLES.map(() => '?').join(', ')})`)
257
339
  .get(...ADDED_TABLES);
258
- return found !== undefined && int(found, 'n') === ADDED_TABLES.length;
340
+ if (found === undefined || int(found, 'n') !== ADDED_TABLES.length)
341
+ return false;
342
+ return ADDED_COLUMNS.every(c => this.hasColumn(c.table, c.column));
343
+ }
344
+ hasColumn(table, column) {
345
+ return this.db.prepare('SELECT 1 FROM pragma_table_info(?) WHERE name = ?').get(table, column) !== undefined;
346
+ }
347
+ addToFormat1() {
348
+ this.db.exec(FORMAT_1_ADDITIONS);
349
+ for (const c of ADDED_COLUMNS)
350
+ if (!this.hasColumn(c.table, c.column))
351
+ this.db.exec(c.sql);
259
352
  }
260
353
  version() {
261
354
  const row = this.db.prepare('PRAGMA user_version').get();
@@ -266,11 +359,10 @@ export class Store {
266
359
  const version = this.version();
267
360
  if (version === SCHEMA_VERSION)
268
361
  return;
269
- if (version > SCHEMA_VERSION) {
270
- throw new UsageError(`${databasePath(this.dir)} is registry format ${String(version)}, newer than this ${TOOL} understands (${String(SCHEMA_VERSION)})`, `upgrade ${TOOL} to the version every project on this Mac uses`);
271
- }
362
+ if (version > SCHEMA_VERSION)
363
+ throw newerFormat(this.dir, version);
272
364
  this.db.exec(SCHEMA);
273
- this.db.exec(FORMAT_1_ADDITIONS);
365
+ this.addToFormat1();
274
366
  this.db.exec(`PRAGMA user_version = ${String(SCHEMA_VERSION)}`);
275
367
  });
276
368
  }
@@ -19,10 +19,12 @@ import { readRegistryStatus, Registry } from "./registry/registry.js";
19
19
  import { DEFAULT_HOLD_MS, parseHoldTime } from "./registry/holds.js";
20
20
  import { recordCall } from "./registry/touch.js";
21
21
  import { describeRestarts } from "./registry/parks.js";
22
+ import { SHARED_IDLE_MS } from "./registry/shared.js";
22
23
  import { realServiceSystem } from "./services/system.js";
23
24
  import { LANE_FILES_KEEP_MS, pruneEndedLaneFiles } from "./up/lane-files.js";
24
25
  import { tearDownLane } from "./up/release.js";
25
26
  import { tearDownEndedResources } from "./up/resources.js";
27
+ import { sharedLog } from "./up/shared.js";
26
28
  import { runSweep, SWEEP_INTERVAL_MS } from "./up/sweep.js";
27
29
  import { systemClock } from "./clock.js";
28
30
  import { claudeSessionName } from "./plugin/session-name.js";
@@ -68,7 +70,8 @@ export const REGISTRY_HELP = {
68
70
  --worktree <dir> the folder whose lane to hold (default: this git worktree)
69
71
  `,
70
72
  status: ` status Every lane on this Mac: owner, folder, start, idle time, last action, and whether
71
- it is held or parked.
73
+ it is held or parked. Then every shared service ${TOOL} started: whether it runs, the
74
+ lanes that need it, when it stops once none does, and why its last start or stop failed.
72
75
  `,
73
76
  lanes: ` lanes --json: the same as status, as JSON for tools.
74
77
  `,
@@ -248,6 +251,45 @@ function laneLines(c, sessionName, now) {
248
251
  lines.push(` left alone: its owner can't be judged; ${CLI} release --lane ${c.id} --force frees it`);
249
252
  return lines;
250
253
  }
254
+ function laneCount(ids) {
255
+ return `${String(ids.length)} lane${ids.length === 1 ? '' : 's'} (${ids.join(', ')})`;
256
+ }
257
+ function idleShared(s, now) {
258
+ if (s.holding.length > 0)
259
+ return `held by ${s.holding.map(h => `resource ${h.resource} of lane ${h.lane}`).join(', ')}; it stops ${formatAge(SHARED_IDLE_MS)} after they let go`;
260
+ if (s.stopsAt === null)
261
+ return `it stops ${formatAge(SHARED_IDLE_MS)} after a sweep finds nothing needs it`;
262
+ if (s.stopsAt <= now)
263
+ return 'the next sweep stops it';
264
+ return `stops ${formatTime(s.stopsAt)} (in ${formatAge(s.stopsAt - now)})`;
265
+ }
266
+ function sharedHead(s, now) {
267
+ const by = s.by === null ? '' : ` by pid ${String(s.by)}`;
268
+ switch (s.state) {
269
+ case 'running':
270
+ return s.lanes.length > 0 ? `running, used by ${laneCount(s.lanes)}` : `running, used by no lane; ${idleShared(s, now)}`;
271
+ case 'stopped':
272
+ return s.lanes.length > 0 ? `stopped, needed by ${laneCount(s.lanes)}; ${CLI} up starts it` : 'stopped';
273
+ default:
274
+ return `${s.state}${by}${s.lanes.length > 0 ? `, used by ${laneCount(s.lanes)}` : ''}`;
275
+ }
276
+ }
277
+ function sharedProblem(s) {
278
+ if (s.attempts === 0)
279
+ return ` problem ${s.problem ?? ''}; the next ${CLI} up that needs it starts it again`;
280
+ const retry = s.stopsAt === null ? 'the sweep tries it again once nothing needs it' : 'the sweep tries it again then';
281
+ return ` stop failed ${String(s.attempts)} time${s.attempts === 1 ? '' : 's'}: ${s.problem ?? ''}; ${retry}`;
282
+ }
283
+ function sharedLines(s, report) {
284
+ const lines = [
285
+ `shared service ${s.name}: ${sharedHead(s, report.now)}`,
286
+ ` repository ${path.basename(s.repository)} (${s.repository}) ${s.state} since ${formatTime(s.since)}`,
287
+ ];
288
+ if (s.problem !== null) {
289
+ lines.push(sharedProblem(s), ` log ${sharedLog(report.stateDir, s)}`);
290
+ }
291
+ return lines;
292
+ }
251
293
  function poolLine(report) {
252
294
  const { config } = report;
253
295
  const count = (platform) => report.pool.filter(d => d.platform === platform).length;
@@ -272,6 +314,8 @@ export function renderStatus(report, sessionName = () => null) {
272
314
  for (const c of report.lanes)
273
315
  lines.push(...laneLines(c, sessionName, report.now));
274
316
  }
317
+ if (report.shared.length > 0)
318
+ lines.push('', ...report.shared.flatMap(s => sharedLines(s, report)));
275
319
  if (report.queue.length > 0) {
276
320
  lines.push('', 'queue:');
277
321
  for (const q of report.queue)
@@ -140,7 +140,7 @@ export async function inspectService(system, service, port, proc) {
140
140
  const leader = check?.state ?? 'not-started';
141
141
  const listeners = listenersOn(system, port, leader === 'alive' && proc ? proc.pid : null);
142
142
  const probe = await probeReady(service.ready, port);
143
- const ours = listeners !== null && listeners.length > 0 && listeners.every(l => l.ours);
143
+ const ours = listeners === null || (listeners.length > 0 && listeners.every(l => l.ours));
144
144
  return {
145
145
  service: service.name,
146
146
  port,
@@ -156,7 +156,9 @@ export async function inspectService(system, service, port, proc) {
156
156
  export function explainInspection(inspection) {
157
157
  const parts = [inspection.leaderDetail];
158
158
  if (inspection.listeners === null)
159
- parts.push(`the listener on ${String(inspection.port)} could not be read`);
159
+ parts.push(inspection.healthy
160
+ ? `the listener on ${String(inspection.port)} could not be read, so its ready check stands for it`
161
+ : `the listener on ${String(inspection.port)} could not be read`);
160
162
  else if (inspection.listeners.length === 0)
161
163
  parts.push(`nothing listens on ${String(inspection.port)}`);
162
164
  else {