@aisac/cli 0.4.0-beta.21 → 0.4.0-beta.22

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,1921 @@
1
+ // The local file bus of the manager feature (spec aisac-engineering-manager,
2
+ // D3, D4, FR2, FR11; ADR-0058): rooms, the session registry, private files
3
+ // written by rename, the content-free audit and the sweeps. Nothing here
4
+ // listens on anything, and nothing here reads or writes message text: that is
5
+ // `messages.mjs`. Node built-ins only, because the worker role loads this
6
+ // module inside the Codex adapter process.
7
+ //
8
+ // Every file another process may have written is read with `readBoundedFile`:
9
+ // opened without following a symlink and without blocking, checked on the
10
+ // open handle (a regular file of this user, within its size limit) and read
11
+ // at most to that limit. Every sweep checks first that the room's directories
12
+ // are real directories of this user, so that it never deletes through a
13
+ // symlink, and runs its destructive steps under the room lock.
14
+
15
+ import { createHash, randomBytes } from 'node:crypto';
16
+ import { constants, readFileSync } from 'node:fs';
17
+ import {
18
+ chmod,
19
+ link,
20
+ lstat,
21
+ mkdir,
22
+ open,
23
+ readdir,
24
+ rename,
25
+ rm,
26
+ unlink,
27
+ writeFile,
28
+ } from 'node:fs/promises';
29
+ import { dirname, join, resolve } from 'node:path';
30
+
31
+ export const BUS_SCHEMA_VERSION = 1;
32
+ export const BUS_DIRECTORY = 'bus';
33
+ export const MANAGER_NAME = 'manager';
34
+ /** The manager's inbox and pending records belong to the room, not to a session (FR2). */
35
+ export const MANAGER_RECIPIENT = 'manager';
36
+ export const NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/u;
37
+ export const SESSION_ID_PATTERN = /^[0-9a-f]{32}$/u;
38
+ export const ROOM_ID_PATTERN = /^[0-9a-f]{32}$/u;
39
+ export const CODE_PATTERN = /^[a-z0-9_]{1,64}$/u;
40
+ /** An audit reason: a code of the client, or an error kind of the app-server (`contextWindowExceeded`). */
41
+ export const AUDIT_REASON_PATTERN = /^[A-Za-z0-9_]{1,64}$/u;
42
+ /** A message id: its creation time in milliseconds (13 digits) and 16 random hexadecimal characters (FR3). */
43
+ export const MESSAGE_ID_PATTERN = /^\d{13}-[0-9a-f]{16}$/u;
44
+ /** A value the app-server reports (sandbox, approval policy), as the worker's adapter keeps it. */
45
+ export const REPORTED_VALUE_PATTERN = /^[A-Za-z0-9_.:-]{1,64}$/u;
46
+ /** A host version: `0.166.0`, `2.1.323`, `1.0.0-beta.1+build`. */
47
+ export const VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,63}$/u;
48
+ /** What identifies one process over its life: the boot id and the start time in clock ticks (Linux). */
49
+ export const START_TOKEN_PATTERN = /^(?:[0-9a-f-]{36}:)?\d{1,20}$/u;
50
+
51
+ /** Set by the launcher for the Codex chain: the worker role, as JSON. */
52
+ export const WORKER_ROLE_ENV = 'AISAC_WORKER_ROLE';
53
+ /** Set by the launcher for the Codex chain: absolute path of `manager/worker.mjs`. */
54
+ export const WORKER_MODULE_ENV = 'AISAC_WORKER_MODULE';
55
+ /** Set by the launcher for the manager's Claude Code process and its MCP entry: the manager role, as JSON. */
56
+ export const MANAGER_ROLE_ENV = 'AISAC_MANAGER_ROLE';
57
+
58
+ const MINUTE_MS = 60_000;
59
+ const HOUR_MS = 60 * MINUTE_MS;
60
+ const DAY_MS = 24 * HOUR_MS;
61
+ const KIBIBYTE = 1024;
62
+ const MEBIBYTE = 1024 * KIBIBYTE;
63
+
64
+ /** Every limit of the spec in one place (FR2, FR3, FR6, FR9, FR13). */
65
+ export const LIMITS = Object.freeze({
66
+ workersPerRoom: 16,
67
+ queuedPerWorker: 8,
68
+ pendingPerRoom: 32,
69
+ sendsPerWindow: 30,
70
+ sendWindowMs: 10 * MINUTE_MS,
71
+ requestTextMax: 16_000,
72
+ replyTextMax: 64_000,
73
+ fileBytesMax: 256 * KIBIBYTE,
74
+ ttlDefaultMs: 30 * MINUTE_MS,
75
+ ttlMinMs: MINUTE_MS,
76
+ ttlMaxMs: DAY_MS,
77
+ retentionMs: DAY_MS,
78
+ /** A pending record outlives its request's expiry by this much, so a late reply still finds it. */
79
+ pendingGraceMs: HOUR_MS,
80
+ idempotencyWindowMs: 10 * MINUTE_MS,
81
+ idempotencyKeyMax: 64,
82
+ auditRotateBytes: MEBIBYTE,
83
+ readPageChars: 8_000,
84
+ waitIdsMax: 16,
85
+ waitTimeoutMaxSeconds: 120,
86
+ waitTimeoutDefaultSeconds: 30,
87
+ wakeTimeoutDefaultSeconds: 30 * 60,
88
+ wakeTimeoutMaxSeconds: 6 * 60 * 60,
89
+ holdMs: 10 * MINUTE_MS,
90
+ delegatedPerHour: 30,
91
+ delegationMinMs: 10 * MINUTE_MS,
92
+ delegationMaxMs: DAY_MS,
93
+ delegationDefaultMs: 8 * HOUR_MS,
94
+ decisionReasonMax: 500,
95
+ commandTextMax: 4_000,
96
+ decisionsRotateBytes: 4 * MEBIBYTE,
97
+ decisionsRetentionMs: 30 * DAY_MS,
98
+ });
99
+
100
+ const PRIVATE_DIRECTORY_MODE = 0o700;
101
+ const PRIVATE_FILE_MODE = 0o600;
102
+ const NOT_PRIVATE_MASK = 0o077;
103
+ const SESSION_FILE_BYTES_MAX = 16 * KIBIBYTE;
104
+ const ROOM_FILE_BYTES_MAX = 4 * KIBIBYTE;
105
+ export const PENDING_FILE_BYTES_MAX = 2 * KIBIBYTE;
106
+ const LOCK_FILE_BYTES_MAX = 256;
107
+ const PATH_LENGTH_MAX = 4096;
108
+ const LABEL_MAX = 128;
109
+ const HELD_APPROVALS_MAX = 32;
110
+ const LOCK_STALE_MS = 10_000;
111
+ const LOCK_WAIT_MS = 3_000;
112
+ const LOCK_RETRY_MS = 25;
113
+ /** A hard stop for the lock loop, so that a clock that never moves cannot spin it forever. */
114
+ const LOCK_ATTEMPTS_MAX = 4 * Math.ceil(LOCK_WAIT_MS / LOCK_RETRY_MS);
115
+ const LOCK_NONCE_BYTES = 16;
116
+ const RANDOM_NAME_BYTES = 8;
117
+ const REGISTER_ATTEMPTS_MAX = 3;
118
+ const TEMPORARY_FILE_MAX_AGE_MS = HOUR_MS;
119
+ const JSON_SUFFIX = '.json';
120
+ const JSON_FILE = /\.json$/u;
121
+ const MESSAGE_TIME = /^(\d{13})-/u;
122
+ const REMOVED_ROOM_PATTERN = /^\.removed-[0-9a-f]{32}$/u;
123
+ const LOCK_LINE = /^(\d{1,10}) (\d{1,16}) ([0-9a-f]{32}) (-|(?:[0-9a-f-]{36}:)?\d{1,20})\n$/u;
124
+ const NO_TOKEN = '-';
125
+ const BREAKER_SUFFIX = '.break';
126
+ const PROC_STAT_START_TIME_INDEX = 19;
127
+ const BOOT_ID_FILE = '/proc/sys/kernel/random/boot_id';
128
+ const BOOT_ID_PATTERN = /^[0-9a-f-]{36}$/u;
129
+ const DIGITS = /^\d{1,20}$/u;
130
+ const REPLACEMENT_CHARACTER = '�';
131
+ const C0_LAST = 0x1f;
132
+ const DELETE = 0x7f;
133
+ const C1_LAST = 0x9f;
134
+ const HIGH_SURROGATE_FIRST = 0xd800;
135
+ const HIGH_SURROGATE_LAST = 0xdbff;
136
+ /** Invisible format characters, bidirectional overrides and lone surrogates. */
137
+ const INVISIBLE_RANGES = Object.freeze([
138
+ [0x00ad, 0x00ad],
139
+ [0x061c, 0x061c],
140
+ [0x180e, 0x180e],
141
+ [0x200b, 0x200f],
142
+ [0x2028, 0x202e],
143
+ [0x2060, 0x206f],
144
+ [0xd800, 0xdfff],
145
+ [0xfeff, 0xfeff],
146
+ [0xfff9, 0xfffb],
147
+ ]);
148
+ const READ_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
149
+ const APPEND_FLAGS =
150
+ constants.O_WRONLY |
151
+ constants.O_APPEND |
152
+ constants.O_CREAT |
153
+ (constants.O_NOFOLLOW ?? 0) |
154
+ (constants.O_NONBLOCK ?? 0);
155
+ /** What `open` reports for an entry that is not a regular file it may open: a symlink (`O_NOFOLLOW`), a socket. */
156
+ const NOT_A_FILE_ERRORS = ['ELOOP', 'EMLINK', 'ENXIO', 'EOPNOTSUPP', 'EISDIR'];
157
+ const MISSING_ERRORS = ['ENOENT', 'ENOTDIR'];
158
+
159
+ /** @typedef {'pt-BR' | 'en'} BusLocale */
160
+ /** @typedef {'manager' | 'worker'} Role */
161
+ /** @typedef {'claude' | 'codex'} Host */
162
+ /** @typedef {'starting' | 'idle' | 'busy' | 'waiting_approval'} SessionState */
163
+ /** @typedef {'command' | 'fileChange' | 'permissions'} ApprovalKind */
164
+ /**
165
+ * @typedef {object} SessionApproval
166
+ * @property {ApprovalKind} kind
167
+ * @property {'user' | 'manager'} decider who answers it: the terminal's user, or the manager under a delegation (FR13)
168
+ * @property {number} since
169
+ */
170
+ /**
171
+ * One live role session (FR2). The launcher writes it at registration; from
172
+ * then on only the session's own role process replaces it.
173
+ * @typedef {object} SessionRecord
174
+ * @property {1} schemaVersion
175
+ * @property {string} sessionId 128 random bits, hexadecimal
176
+ * @property {string} name
177
+ * @property {Role} role
178
+ * @property {Host} host
179
+ * @property {string | null} hostVersion
180
+ * @property {number} launcherPid
181
+ * @property {number | null} childPid the role process (the adapter, or the manager's MCP server), written by itself
182
+ * @property {number} startedAt
183
+ * @property {string} cwd
184
+ * @property {BusLocale} locale
185
+ * @property {SessionState} state
186
+ * @property {number} stateSince
187
+ * @property {'user' | 'manager' | null} turnOrigin
188
+ * @property {number} queued
189
+ * @property {string} sandbox as the app-server reports it, `unknown` otherwise
190
+ * @property {string} approvalPolicy as the app-server reports it, `unknown` otherwise
191
+ * @property {SessionApproval | null} approval the approval the session waits for, without any request text
192
+ * @property {string[]} heldApprovals ids of the approval requests the worker's adapter holds for the manager right now (FR13)
193
+ * @property {string | null} [launcherStartTime] what identifies the launcher process (`processStartToken`), filled at registration; absent or null: pid only
194
+ * @property {string | null} [childStartTime] what identifies the role process, filled by `writeSession` when the role process writes its own pid
195
+ */
196
+ /**
197
+ * @typedef {object} RoomDescriptor
198
+ * @property {string} id
199
+ * @property {'repository' | 'named'} kind
200
+ * @property {string} label
201
+ */
202
+ /**
203
+ * @typedef {object} RoomPaths
204
+ * @property {string} bus
205
+ * @property {string} rooms
206
+ * @property {string} room
207
+ * @property {string} roomFile
208
+ * @property {string} sessions
209
+ * @property {string} inbox
210
+ * @property {string} claimed
211
+ * @property {string} manager
212
+ * @property {string} pending
213
+ * @property {string} tmp
214
+ * @property {string} delegation
215
+ * @property {string} decisions
216
+ * @property {string} audit
217
+ * @property {string} lock
218
+ */
219
+ /**
220
+ * @typedef {object} BusClock
221
+ * @property {() => number} [now]
222
+ * @property {(pid: number) => boolean} [alive]
223
+ * @property {(milliseconds: number) => Promise<void>} [delay]
224
+ * @property {(pid: number) => string | null} [startToken] what identifies a live process; null when it cannot be told
225
+ */
226
+
227
+ /** A coded failure of the bus. The code is the whole public message. */
228
+ export class BusError extends Error {
229
+ /** @param {string} code @param {string} [detail] */
230
+ constructor(code, detail) {
231
+ super(code);
232
+ this.name = 'BusError';
233
+ this.code = code;
234
+ this.detail = detail ?? null;
235
+ }
236
+ }
237
+
238
+ /** @param {unknown} value @returns {value is Record<string, unknown>} */
239
+ export function isPlainRecord(value) {
240
+ return (
241
+ typeof value === 'object' &&
242
+ value !== null &&
243
+ !Array.isArray(value) &&
244
+ Object.getPrototypeOf(value) === Object.prototype
245
+ );
246
+ }
247
+
248
+ /** @param {unknown} error @returns {string | null} */
249
+ function errorCode(error) {
250
+ if (typeof error !== 'object' || error === null) return null;
251
+ const code = /** @type {{ code?: unknown }} */ (error).code;
252
+ return typeof code === 'string' ? code : null;
253
+ }
254
+
255
+ /** @param {unknown} value */
256
+ function isPid(value) {
257
+ return Number.isSafeInteger(value) && /** @type {number} */ (value) > 0;
258
+ }
259
+
260
+ /**
261
+ * Whether a process of this user with that pid exists. A process of another
262
+ * user (`EPERM`) is never a session of this user: every bus session runs as
263
+ * the user who owns the state root.
264
+ * @param {number} pid
265
+ */
266
+ export function processAlive(pid) {
267
+ if (!isPid(pid)) return false;
268
+ try {
269
+ process.kill(pid, 0);
270
+ return true;
271
+ } catch {
272
+ return false;
273
+ }
274
+ }
275
+
276
+ /** @type {string | null | undefined} */
277
+ let cachedBootId;
278
+
279
+ function bootId() {
280
+ if (cachedBootId !== undefined) return cachedBootId;
281
+ try {
282
+ const text = readFileSync(BOOT_ID_FILE, 'utf8').trim();
283
+ cachedBootId = BOOT_ID_PATTERN.test(text) ? text : null;
284
+ } catch {
285
+ cachedBootId = null;
286
+ }
287
+ return cachedBootId;
288
+ }
289
+
290
+ /**
291
+ * What identifies one process over its whole life, so that a pid reused by a
292
+ * later process is not taken for it: on Linux the boot id and the start time
293
+ * (field 22 of `/proc/<pid>/stat`, clock ticks since boot). Where there is no
294
+ * `/proc` (macOS), or the process is gone, null: liveness is then the pid
295
+ * alone, with `EPERM` as "not ours" (`processAlive`).
296
+ * @param {number} pid
297
+ * @returns {string | null}
298
+ */
299
+ export function processStartToken(pid) {
300
+ if (!isPid(pid)) return null;
301
+ let text;
302
+ try {
303
+ text = readFileSync(`/proc/${pid}/stat`, 'latin1');
304
+ } catch {
305
+ return null;
306
+ }
307
+ // The command name (field 2) is in parentheses and may hold spaces or `)`.
308
+ const close = text.lastIndexOf(')');
309
+ if (close === -1) return null;
310
+ const start = text.slice(close + 2).split(' ')[PROC_STAT_START_TIME_INDEX];
311
+ if (start === undefined || !DIGITS.test(start)) return null;
312
+ const boot = bootId();
313
+ return boot === null ? start : `${boot}:${start}`;
314
+ }
315
+
316
+ /** @param {number} milliseconds @returns {Promise<void>} */
317
+ function realDelay(milliseconds) {
318
+ return new Promise((resolvePromise) => {
319
+ setTimeout(resolvePromise, milliseconds);
320
+ });
321
+ }
322
+
323
+ /** @param {BusClock} [clock] */
324
+ function clockOf(clock = {}) {
325
+ return {
326
+ now: clock.now ?? (() => Date.now()),
327
+ alive: clock.alive ?? processAlive,
328
+ delay: clock.delay ?? realDelay,
329
+ startToken: clock.startToken ?? processStartToken,
330
+ };
331
+ }
332
+
333
+ /**
334
+ * Whether a pid is still the process a record names: alive, and, when the
335
+ * record has its start time, started at that time.
336
+ * @param {number} pid
337
+ * @param {string | null | undefined} token
338
+ * @param {(pid: number) => boolean} alive
339
+ * @param {(pid: number) => string | null} startToken
340
+ */
341
+ function pidIsProcess(pid, token, alive, startToken) {
342
+ if (!alive(pid)) return false;
343
+ if (typeof token !== 'string') return true;
344
+ const current = startToken(pid);
345
+ // Unreadable for an instant (it may be exiting): the next listing decides.
346
+ return current === null || current === token;
347
+ }
348
+
349
+ // ------------------------------------------------------------------ text
350
+
351
+ /** @param {number} codePoint */
352
+ export function isUnsafeCodePoint(codePoint) {
353
+ if (codePoint <= C0_LAST || (codePoint >= DELETE && codePoint <= C1_LAST)) return true;
354
+ return INVISIBLE_RANGES.some(([first, last]) => codePoint >= first && codePoint <= last);
355
+ }
356
+
357
+ /**
358
+ * Text with every control character, invisible format character and lone
359
+ * surrogate replaced by U+FFFD, one for one, so that it can repaint no
360
+ * terminal and its length is unchanged.
361
+ * @param {string} text
362
+ */
363
+ export function sanitizeText(text) {
364
+ let result = '';
365
+ for (const character of text)
366
+ result += isUnsafeCodePoint(character.codePointAt(0) ?? 0)
367
+ ? REPLACEMENT_CHARACTER.repeat(character.length)
368
+ : character;
369
+ return result;
370
+ }
371
+
372
+ /** @param {unknown} value @param {number} max @returns {value is string} */
373
+ function isSafeText(value, max) {
374
+ if (typeof value !== 'string' || value.length === 0 || value.length > max) return false;
375
+ for (const character of value) if (isUnsafeCodePoint(character.codePointAt(0) ?? 0)) return false;
376
+ return true;
377
+ }
378
+
379
+ /** @param {string} text @param {number} max */
380
+ function cutCodeUnits(text, max) {
381
+ if (text.length <= max) return text;
382
+ const last = text.charCodeAt(max - 1);
383
+ return text.slice(0, last >= HIGH_SURROGATE_FIRST && last <= HIGH_SURROGATE_LAST ? max - 1 : max);
384
+ }
385
+
386
+ /**
387
+ * A room's label as it is stored and shown: no control characters, at most
388
+ * 128 code units.
389
+ * @param {string} label
390
+ */
391
+ export function roomLabel(label) {
392
+ return cutCodeUnits(sanitizeText(label), LABEL_MAX);
393
+ }
394
+
395
+ // ------------------------------------------------------------------ ids and paths
396
+
397
+ /** @returns {string} 128 random bits, hexadecimal */
398
+ export function newSessionId() {
399
+ return randomBytes(16).toString('hex');
400
+ }
401
+
402
+ /** @returns {string} */
403
+ function randomName() {
404
+ return randomBytes(RANDOM_NAME_BYTES).toString('hex');
405
+ }
406
+
407
+ /**
408
+ * The room id of an identity (`repository:<real path>` or `named:<name>`).
409
+ * @param {string} identity
410
+ */
411
+ export function roomIdFor(identity) {
412
+ return createHash('sha256').update(identity, 'utf8').digest('hex').slice(0, 32);
413
+ }
414
+
415
+ /** @param {string} stateRoot */
416
+ export function busRoot(stateRoot) {
417
+ return join(resolve(stateRoot), BUS_DIRECTORY);
418
+ }
419
+
420
+ /**
421
+ * @param {string} stateRoot
422
+ * @param {string} roomId
423
+ * @returns {RoomPaths}
424
+ */
425
+ export function roomPaths(stateRoot, roomId) {
426
+ if (!ROOM_ID_PATTERN.test(roomId)) throw new BusError('bus_unavailable', 'room_id_invalid');
427
+ const bus = busRoot(stateRoot);
428
+ const rooms = join(bus, 'rooms');
429
+ const room = join(rooms, roomId);
430
+ const manager = join(room, 'manager');
431
+ return {
432
+ bus,
433
+ rooms,
434
+ room,
435
+ roomFile: join(room, 'room.json'),
436
+ sessions: join(room, 'sessions'),
437
+ inbox: join(room, 'inbox'),
438
+ claimed: join(room, 'claimed'),
439
+ manager,
440
+ pending: join(manager, 'pending'),
441
+ tmp: join(room, 'tmp'),
442
+ delegation: join(room, 'delegation'),
443
+ decisions: join(room, 'decisions.jsonl'),
444
+ audit: join(room, 'audit.jsonl'),
445
+ lock: join(room, 'lock'),
446
+ };
447
+ }
448
+
449
+ /**
450
+ * A recipient's directory inside `inbox/` or `claimed/`. The key is a worker's
451
+ * session id or the literal `manager`.
452
+ * @param {RoomPaths} paths
453
+ * @param {'inbox' | 'claimed'} box
454
+ * @param {string} recipient
455
+ */
456
+ export function mailboxDirectory(paths, box, recipient) {
457
+ if (recipient !== MANAGER_RECIPIENT && !SESSION_ID_PATTERN.test(recipient))
458
+ throw new BusError('bus_unavailable', 'recipient_invalid');
459
+ return join(box === 'inbox' ? paths.inbox : paths.claimed, recipient);
460
+ }
461
+
462
+ /** Every directory of a room, the room itself first. @param {RoomPaths} paths */
463
+ function roomDirectories(paths) {
464
+ return [
465
+ paths.room,
466
+ paths.sessions,
467
+ paths.inbox,
468
+ paths.claimed,
469
+ paths.manager,
470
+ paths.pending,
471
+ paths.tmp,
472
+ paths.delegation,
473
+ mailboxDirectory(paths, 'inbox', MANAGER_RECIPIENT),
474
+ mailboxDirectory(paths, 'claimed', MANAGER_RECIPIENT),
475
+ ];
476
+ }
477
+
478
+ // ------------------------------------------------------------------ the file system
479
+
480
+ /** @param {import('node:fs').Stats} entry */
481
+ function ownedByUser(entry) {
482
+ return typeof process.getuid !== 'function' || entry.uid === process.getuid();
483
+ }
484
+
485
+ /**
486
+ * What one path is, without following it: a real directory of this user, not
487
+ * there at all, or anything else (a symlink, a file, another user's).
488
+ * @param {string} path
489
+ * @returns {Promise<'directory' | 'missing' | 'unsafe'>}
490
+ */
491
+ async function directoryState(path) {
492
+ try {
493
+ const entry = await lstat(path);
494
+ return entry.isDirectory() && ownedByUser(entry) ? 'directory' : 'unsafe';
495
+ } catch (error) {
496
+ return MISSING_ERRORS.includes(errorCode(error) ?? '') ? 'missing' : 'unsafe';
497
+ }
498
+ }
499
+
500
+ /**
501
+ * Whether a path is a real directory of this user, not a symlink to one.
502
+ * @param {string} path
503
+ */
504
+ export async function isPrivateDirectory(path) {
505
+ return (await directoryState(path)) === 'directory';
506
+ }
507
+
508
+ /**
509
+ * Whether a sweep may touch the room: the bus, `rooms/`, the room and each of
510
+ * its directories are real directories of this user. A directory that is
511
+ * missing is fine (there is nothing to sweep in it); a symlink is not.
512
+ * @param {RoomPaths} paths
513
+ */
514
+ export async function roomIsSafe(paths) {
515
+ if ((await directoryState(paths.bus)) !== 'directory') return false;
516
+ if ((await directoryState(paths.rooms)) !== 'directory') return false;
517
+ if ((await directoryState(paths.room)) !== 'directory') return false;
518
+ for (const directory of roomDirectories(paths).slice(1))
519
+ if ((await directoryState(directory)) === 'unsafe') return false;
520
+ return true;
521
+ }
522
+
523
+ /** @param {number | null} modifiedAt @param {number} limit */
524
+ function isOlderThan(modifiedAt, limit) {
525
+ return modifiedAt !== null && modifiedAt < limit;
526
+ }
527
+
528
+ /**
529
+ * Create, or confirm, one private directory: a real directory of this user
530
+ * with no group or other permission bits.
531
+ * @param {string} path
532
+ */
533
+ export async function ensurePrivateDirectory(path) {
534
+ await mkdir(path, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
535
+ const entry = await lstat(path);
536
+ if (!entry.isDirectory()) throw new BusError('bus_unavailable', 'not_a_directory');
537
+ if (!ownedByUser(entry)) throw new BusError('bus_unavailable', 'owner_mismatch');
538
+ if ((entry.mode & NOT_PRIVATE_MASK) !== 0) await chmod(path, PRIVATE_DIRECTORY_MODE);
539
+ return path;
540
+ }
541
+
542
+ /**
543
+ * Write one private file by rename: the bytes go to a file in `tmp/` first, so
544
+ * a reader of the target directory never sees a partial file (FR3). Nothing
545
+ * is written through a `tmp/` or a target directory that is a symlink or not
546
+ * this user's (`bus_unavailable`, `not_a_directory`); a missing one fails as
547
+ * the file system reports it.
548
+ * @param {RoomPaths} paths
549
+ * @param {string} target
550
+ * @param {string | Uint8Array} bytes
551
+ */
552
+ export async function writePrivateFile(paths, target, bytes) {
553
+ for (const directory of [paths.tmp, dirname(target)])
554
+ if ((await directoryState(directory)) === 'unsafe')
555
+ throw new BusError('bus_unavailable', 'not_a_directory');
556
+ const temporary = join(paths.tmp, `${process.pid}-${randomName()}.tmp`);
557
+ try {
558
+ await writeFile(temporary, bytes, { mode: PRIVATE_FILE_MODE, flag: 'wx' });
559
+ await chmod(temporary, PRIVATE_FILE_MODE);
560
+ await rename(temporary, target);
561
+ } catch (error) {
562
+ await unlink(temporary).catch(() => undefined);
563
+ throw error;
564
+ }
565
+ }
566
+
567
+ /**
568
+ * @typedef {'missing' | 'not_a_file' | 'owner_mismatch' | 'too_large' | 'io_error'} ReadFailure
569
+ * `io_error` is a read that failed for another reason (a permission, the
570
+ * system's file table): the file may be valid, so no caller deletes it.
571
+ */
572
+ /**
573
+ * @typedef {{ ok: true, data: Buffer, size: number, modifiedAt: number, ino: number }
574
+ * | { ok: false, reason: ReadFailure, size: number, modifiedAt: number | null, ino: number | null }} BoundedRead
575
+ */
576
+
577
+ /** @param {unknown} error @returns {ReadFailure} */
578
+ function openFailure(error) {
579
+ const code = errorCode(error) ?? '';
580
+ if (MISSING_ERRORS.includes(code)) return 'missing';
581
+ if (NOT_A_FILE_ERRORS.includes(code)) return 'not_a_file';
582
+ return 'io_error';
583
+ }
584
+
585
+ /**
586
+ * The facts of an entry that could not be opened, read without following it,
587
+ * so that a caller can still age it.
588
+ * @param {string} path
589
+ * @param {ReadFailure} reason
590
+ * @returns {Promise<BoundedRead>}
591
+ */
592
+ async function failedRead(path, reason) {
593
+ if (reason === 'missing') return { ok: false, reason, size: 0, modifiedAt: null, ino: null };
594
+ return lstat(path).then(
595
+ (entry) => ({ ok: false, reason, size: entry.size, modifiedAt: entry.mtimeMs, ino: entry.ino }),
596
+ () => ({ ok: false, reason, size: 0, modifiedAt: null, ino: null }),
597
+ );
598
+ }
599
+
600
+ /**
601
+ * @param {import('node:fs/promises').FileHandle} handle
602
+ * @param {number} length
603
+ * @param {number} position
604
+ */
605
+ async function readFromHandle(handle, length, position) {
606
+ const buffer = Buffer.alloc(length);
607
+ let filled = 0;
608
+ while (filled < length) {
609
+ const { bytesRead } = await handle.read(buffer, filled, length - filled, position + filled);
610
+ if (bytesRead === 0) break;
611
+ filled += bytesRead;
612
+ }
613
+ return buffer.subarray(0, filled);
614
+ }
615
+
616
+ /**
617
+ * Read one file another process may have written. It is opened without
618
+ * following a symlink and without blocking (a FIFO never stalls the reader),
619
+ * checked on the open handle (a regular file of this user, within the limit)
620
+ * and read at most to the limit. With `tail`, a larger file is not refused:
621
+ * its last `bytesMax` bytes are read. Never throws.
622
+ * @param {string} path
623
+ * @param {number} bytesMax
624
+ * @param {{ tail?: boolean }} [options]
625
+ * @returns {Promise<BoundedRead>}
626
+ */
627
+ export async function readBoundedFile(path, bytesMax, options = {}) {
628
+ let handle;
629
+ try {
630
+ handle = await open(path, READ_FLAGS);
631
+ } catch (error) {
632
+ return failedRead(path, openFailure(error));
633
+ }
634
+ try {
635
+ const entry = await handle.stat();
636
+ const facts = { size: entry.size, modifiedAt: entry.mtimeMs, ino: entry.ino };
637
+ if (!entry.isFile()) return { ok: false, reason: 'not_a_file', ...facts };
638
+ if (!ownedByUser(entry)) return { ok: false, reason: 'owner_mismatch', ...facts };
639
+ const tail = options.tail === true;
640
+ if (entry.size > bytesMax && !tail) return { ok: false, reason: 'too_large', ...facts };
641
+ const position = tail ? Math.max(0, entry.size - bytesMax) : 0;
642
+ // One byte more than allowed tells a file that grew after the check.
643
+ const data = await readFromHandle(handle, tail ? bytesMax : bytesMax + 1, position);
644
+ if (data.length > bytesMax) return { ok: false, reason: 'too_large', ...facts };
645
+ return { ok: true, data, ...facts };
646
+ } catch {
647
+ return { ok: false, reason: 'io_error', size: 0, modifiedAt: null, ino: null };
648
+ } finally {
649
+ await handle.close().catch(() => undefined);
650
+ }
651
+ }
652
+
653
+ /**
654
+ * @typedef {{ ok: true, value: unknown, bytes: number, modifiedAt: number, ino: number }
655
+ * | { ok: false, reason: ReadFailure | 'invalid_json', bytes: number, modifiedAt: number | null, ino: number | null }} JsonFileResult
656
+ */
657
+
658
+ /**
659
+ * Read one JSON file another process may have written (`readBoundedFile`).
660
+ * Never throws; the reason is a code.
661
+ * @param {string} path
662
+ * @param {number} bytesMax
663
+ * @returns {Promise<JsonFileResult>}
664
+ */
665
+ export async function readJsonFile(path, bytesMax) {
666
+ const read = await readBoundedFile(path, bytesMax);
667
+ if (!read.ok)
668
+ return {
669
+ ok: false,
670
+ reason: read.reason,
671
+ bytes: read.size,
672
+ modifiedAt: read.modifiedAt,
673
+ ino: read.ino,
674
+ };
675
+ try {
676
+ return {
677
+ ok: true,
678
+ value: JSON.parse(read.data.toString('utf8')),
679
+ bytes: read.size,
680
+ modifiedAt: read.modifiedAt,
681
+ ino: read.ino,
682
+ };
683
+ } catch {
684
+ return {
685
+ ok: false,
686
+ reason: 'invalid_json',
687
+ bytes: read.size,
688
+ modifiedAt: read.modifiedAt,
689
+ ino: read.ino,
690
+ };
691
+ }
692
+ }
693
+
694
+ /**
695
+ * Remove an entry, but only while it is still the file that was read (same
696
+ * inode), so that a file renamed into its place meanwhile survives, and only
697
+ * when its directory is a real directory of this user (never through a link).
698
+ * @param {string} path
699
+ * @param {number | null} ino
700
+ */
701
+ export async function removeIfUnchanged(path, ino) {
702
+ if (ino === null) return;
703
+ if ((await directoryState(dirname(path))) !== 'directory') return;
704
+ const entry = await lstat(path).catch(() => null);
705
+ if (entry !== null && entry.ino === ino) await rm(path, { force: true }).catch(() => undefined);
706
+ }
707
+
708
+ // ------------------------------------------------------------------ rooms
709
+
710
+ /**
711
+ * The rooms this process prepared with `ensureRoom`, so that a registration
712
+ * whose room a sweep removed meanwhile can build it again.
713
+ * @type {WeakMap<RoomPaths, { stateRoot: string, room: RoomDescriptor }>}
714
+ */
715
+ const preparedRooms = new WeakMap();
716
+
717
+ /** @param {RoomPaths} paths @param {RoomDescriptor} room @param {number} now */
718
+ async function writeRoomFile(paths, room, now) {
719
+ const descriptor = {
720
+ schemaVersion: BUS_SCHEMA_VERSION,
721
+ id: room.id,
722
+ kind: room.kind,
723
+ label: roomLabel(room.label),
724
+ createdAt: now,
725
+ };
726
+ await writePrivateFile(paths, paths.roomFile, `${JSON.stringify(descriptor)}\n`);
727
+ }
728
+
729
+ /** @param {RoomPaths} paths @param {RoomDescriptor} room @param {number} now */
730
+ async function prepareRoom(paths, room, now) {
731
+ for (const directory of [paths.bus, paths.rooms, ...roomDirectories(paths)])
732
+ await ensurePrivateDirectory(directory);
733
+ const existing = await readJsonFile(paths.roomFile, ROOM_FILE_BYTES_MAX);
734
+ // Also the rename probe: a file system without it cannot carry the bus.
735
+ if (!existing.ok) await writeRoomFile(paths, room, now);
736
+ }
737
+
738
+ /**
739
+ * A failure that means the room went away meanwhile: another launch's sweep
740
+ * removed it as empty.
741
+ * @param {unknown} error
742
+ */
743
+ function isRoomGone(error) {
744
+ const code = error instanceof BusError ? error.detail : errorCode(error);
745
+ return code !== null && MISSING_ERRORS.includes(code);
746
+ }
747
+
748
+ /**
749
+ * Create the room's private directories and its descriptor, and prove that a
750
+ * rename works there. A room that another launch's sweep removes meanwhile is
751
+ * built again, up to three times. Any failure is `bus_unavailable` (FR1: the
752
+ * role never blocks a launch; the caller starts the host without it).
753
+ * @param {string} stateRoot
754
+ * @param {RoomDescriptor} room
755
+ * @param {BusClock} [clock]
756
+ * @returns {Promise<RoomPaths>}
757
+ */
758
+ export async function ensureRoom(stateRoot, room, clock) {
759
+ const { now } = clockOf(clock);
760
+ const paths = roomPaths(stateRoot, room.id);
761
+ for (let attempt = 1; ; attempt += 1) {
762
+ try {
763
+ await prepareRoom(paths, room, now());
764
+ break;
765
+ } catch (error) {
766
+ if (isRoomGone(error) && attempt < REGISTER_ATTEMPTS_MAX) continue;
767
+ if (error instanceof BusError) throw error;
768
+ throw new BusError('bus_unavailable', errorCode(error) ?? 'io_error');
769
+ }
770
+ }
771
+ preparedRooms.set(paths, {
772
+ stateRoot,
773
+ room: { id: room.id, kind: room.kind, label: room.label },
774
+ });
775
+ return paths;
776
+ }
777
+
778
+ /**
779
+ * @param {RoomPaths} paths
780
+ * @returns {Promise<RoomDescriptor | null>}
781
+ */
782
+ export async function readRoom(paths) {
783
+ const file = await readJsonFile(paths.roomFile, ROOM_FILE_BYTES_MAX);
784
+ if (!file.ok || !isPlainRecord(file.value)) return null;
785
+ const { id, kind, label } = file.value;
786
+ if (typeof id !== 'string' || !ROOM_ID_PATTERN.test(id)) return null;
787
+ if (kind !== 'repository' && kind !== 'named') return null;
788
+ if (typeof label !== 'string' || label.length > LABEL_MAX) return null;
789
+ return { id, kind, label: roomLabel(label) };
790
+ }
791
+
792
+ // ------------------------------------------------------------------ locks
793
+
794
+ /**
795
+ * @typedef {object} LockOwner
796
+ * @property {number} pid
797
+ * @property {number} at
798
+ * @property {string} nonce
799
+ * @property {string | null} token
800
+ */
801
+ /**
802
+ * A lock as one waiter saw it. `text` is its whole content, so that a lock
803
+ * created later on a reused inode number is not taken for it.
804
+ * @typedef {{ ino: number | null, modifiedAt: number | null, text: string | null, owner: LockOwner | null }} HeldLock
805
+ */
806
+
807
+ /** @param {number} pid @param {number} at @param {string} nonce @param {string | null} token */
808
+ function lockLine(pid, at, nonce, token) {
809
+ return `${pid} ${at} ${nonce} ${token ?? NO_TOKEN}\n`;
810
+ }
811
+
812
+ /** @param {string} text @returns {LockOwner | null} */
813
+ function parseLockLine(text) {
814
+ const match = LOCK_LINE.exec(text);
815
+ if (!match) return null;
816
+ const [, pid, at, nonce, token] = /** @type {[string, string, string, string, string]} */ (
817
+ /** @type {unknown} */ (match)
818
+ );
819
+ return { pid: Number(pid), at: Number(at), nonce, token: token === NO_TOKEN ? null : token };
820
+ }
821
+
822
+ /**
823
+ * Create the lock already holding its owner line: the line is written to a
824
+ * temporary file that is then hard-linked to the lock's name, which fails when
825
+ * the name exists. No reader ever sees a lock without its owner.
826
+ * @param {string} lockPath
827
+ * @param {string} temporaryDirectory
828
+ * @param {string} line
829
+ * @returns {Promise<boolean>} false when the lock is held
830
+ */
831
+ async function createLock(lockPath, temporaryDirectory, line) {
832
+ const temporary = join(temporaryDirectory, `${process.pid}-${randomName()}.lock`);
833
+ await writeFile(temporary, line, { mode: PRIVATE_FILE_MODE, flag: 'wx' });
834
+ try {
835
+ await link(temporary, lockPath);
836
+ return true;
837
+ } catch (error) {
838
+ if (errorCode(error) === 'EEXIST') return false;
839
+ throw error;
840
+ } finally {
841
+ await unlink(temporary).catch(() => undefined);
842
+ }
843
+ }
844
+
845
+ /** @param {string} lockPath @returns {Promise<HeldLock | null>} null when there is no lock */
846
+ async function inspectLock(lockPath) {
847
+ const read = await readBoundedFile(lockPath, LOCK_FILE_BYTES_MAX);
848
+ if (!read.ok && read.reason === 'missing') return null;
849
+ const text = read.ok ? read.data.toString('utf8') : null;
850
+ return {
851
+ ino: read.ino,
852
+ modifiedAt: read.modifiedAt,
853
+ text,
854
+ owner: text === null ? null : parseLockLine(text),
855
+ };
856
+ }
857
+
858
+ /** Whether two looks at a lock saw the same file. @param {HeldLock} left @param {HeldLock} right */
859
+ function sameLock(left, right) {
860
+ return (
861
+ left.ino !== null &&
862
+ left.ino === right.ino &&
863
+ left.modifiedAt === right.modifiedAt &&
864
+ left.text === right.text
865
+ );
866
+ }
867
+
868
+ /**
869
+ * A lock is stale when its owner is gone. A lock without a readable owner
870
+ * line is held until it is older than ten seconds; a live owner's lock is
871
+ * never broken, however old.
872
+ * @param {HeldLock} held
873
+ * @param {number} now
874
+ * @param {ReturnType<typeof clockOf>} clock
875
+ */
876
+ function lockIsStale(held, now, clock) {
877
+ if (held.owner === null) return isOlderThan(held.modifiedAt, now - LOCK_STALE_MS);
878
+ return !pidIsProcess(held.owner.pid, held.owner.token, clock.alive, clock.startToken);
879
+ }
880
+
881
+ /**
882
+ * Remove a breaker lock whose owner died inside its few instructions, when it
883
+ * is still the file that was judged.
884
+ * @param {string} breaker
885
+ * @param {ReturnType<typeof clockOf>} timing
886
+ */
887
+ async function clearDeadBreaker(breaker, timing) {
888
+ const held = await inspectLock(breaker);
889
+ if (held === null || !lockIsStale(held, timing.now(), timing)) return;
890
+ const current = await inspectLock(breaker);
891
+ if (current !== null && sameLock(current, held)) await unlink(breaker).catch(() => undefined);
892
+ }
893
+
894
+ /**
895
+ * Break a stale lock. Waiters break one at a time, under a breaker lock
896
+ * (`<lock>.break`), and only while the lock is still the file that was judged:
897
+ * the same inode and the same content (another waiter may have broken it and
898
+ * taken the room meanwhile, on a reused inode number). While the stale lock
899
+ * exists nobody else can create one, so nothing replaces it between that
900
+ * check and the removal.
901
+ * @param {string} lockPath
902
+ * @param {string} temporaryDirectory
903
+ * @param {HeldLock} held
904
+ * @param {ReturnType<typeof clockOf>} timing
905
+ * @returns {Promise<boolean>} whether the lock is gone, so the waiter may try at once
906
+ */
907
+ async function breakLock(lockPath, temporaryDirectory, held, timing) {
908
+ const breaker = `${lockPath}${BREAKER_SUFFIX}`;
909
+ const nonce = randomBytes(LOCK_NONCE_BYTES).toString('hex');
910
+ const line = lockLine(process.pid, timing.now(), nonce, timing.startToken(process.pid));
911
+ try {
912
+ if (!(await createLock(breaker, temporaryDirectory, line))) {
913
+ await clearDeadBreaker(breaker, timing);
914
+ return false;
915
+ }
916
+ } catch {
917
+ return false;
918
+ }
919
+ try {
920
+ const current = await inspectLock(lockPath);
921
+ if (current === null) return true;
922
+ if (!sameLock(current, held)) return false;
923
+ await unlink(lockPath);
924
+ return true;
925
+ } catch {
926
+ return false;
927
+ } finally {
928
+ await releaseLock(breaker, nonce);
929
+ }
930
+ }
931
+
932
+ /** @param {string} lockPath @param {string} nonce */
933
+ async function releaseLock(lockPath, nonce) {
934
+ const read = await readBoundedFile(lockPath, LOCK_FILE_BYTES_MAX);
935
+ if (!read.ok) return;
936
+ const owner = parseLockLine(read.data.toString('utf8'));
937
+ if (owner?.nonce === nonce && owner.pid === process.pid)
938
+ await removeIfUnchanged(lockPath, read.ino);
939
+ }
940
+
941
+ /**
942
+ * Run one task while holding a lock file (see `withRoomLock`).
943
+ * @template T
944
+ * @param {string} lockPath
945
+ * @param {string} temporaryDirectory
946
+ * @param {() => Promise<T>} task
947
+ * @param {BusClock} [clock]
948
+ * @returns {Promise<T>}
949
+ */
950
+ async function withFileLock(lockPath, temporaryDirectory, task, clock) {
951
+ const timing = clockOf(clock);
952
+ const nonce = randomBytes(LOCK_NONCE_BYTES).toString('hex');
953
+ const token = timing.startToken(process.pid);
954
+ const deadline = timing.now() + LOCK_WAIT_MS;
955
+ for (let attempt = 1; ; attempt += 1) {
956
+ let acquired;
957
+ try {
958
+ acquired = await createLock(
959
+ lockPath,
960
+ temporaryDirectory,
961
+ lockLine(process.pid, timing.now(), nonce, token),
962
+ );
963
+ } catch (error) {
964
+ throw new BusError('bus_unavailable', errorCode(error) ?? 'lock_failed');
965
+ }
966
+ if (acquired) break;
967
+ const held = await inspectLock(lockPath);
968
+ const free =
969
+ held === null ||
970
+ (lockIsStale(held, timing.now(), timing) &&
971
+ (await breakLock(lockPath, temporaryDirectory, held, timing)));
972
+ if (timing.now() >= deadline || attempt >= LOCK_ATTEMPTS_MAX)
973
+ throw new BusError('bus_unavailable', 'lock_timeout');
974
+ if (!free) await timing.delay(LOCK_RETRY_MS);
975
+ }
976
+ try {
977
+ return await task();
978
+ } finally {
979
+ await releaseLock(lockPath, nonce);
980
+ }
981
+ }
982
+
983
+ /**
984
+ * Run one task while holding the room's lock: a file created with its owner
985
+ * line already in it (pid, time, a nonce and the process start time), broken
986
+ * only when its owner is gone (`breakLock`), released only by its owner. The
987
+ * wait is three seconds at most; then `bus_unavailable` with `lock_timeout`.
988
+ * Not re-entrant: a task that takes the room lock again (`registerSession`,
989
+ * `sweepRoom`) waits for itself and fails with `lock_timeout`. Writing the
990
+ * audit or the decision record inside it is fine: their rotation has a lock
991
+ * file of its own.
992
+ * @template T
993
+ * @param {RoomPaths} paths
994
+ * @param {() => Promise<T>} task
995
+ * @param {BusClock} [clock]
996
+ * @returns {Promise<T>}
997
+ */
998
+ export function withRoomLock(paths, task, clock) {
999
+ return withFileLock(paths.lock, paths.tmp, task, clock);
1000
+ }
1001
+
1002
+ // ------------------------------------------------------------------ session records
1003
+
1004
+ /** @param {unknown} value */
1005
+ function isTime(value) {
1006
+ return Number.isSafeInteger(value) && /** @type {number} */ (value) >= 0;
1007
+ }
1008
+
1009
+ /** @param {unknown} value */
1010
+ function isOptionalToken(value) {
1011
+ return (
1012
+ value === undefined ||
1013
+ value === null ||
1014
+ (typeof value === 'string' && START_TOKEN_PATTERN.test(value))
1015
+ );
1016
+ }
1017
+
1018
+ const SESSION_KEYS = [
1019
+ 'schemaVersion',
1020
+ 'sessionId',
1021
+ 'name',
1022
+ 'role',
1023
+ 'host',
1024
+ 'hostVersion',
1025
+ 'launcherPid',
1026
+ 'childPid',
1027
+ 'startedAt',
1028
+ 'cwd',
1029
+ 'locale',
1030
+ 'state',
1031
+ 'stateSince',
1032
+ 'turnOrigin',
1033
+ 'queued',
1034
+ 'sandbox',
1035
+ 'approvalPolicy',
1036
+ 'approval',
1037
+ 'heldApprovals',
1038
+ ];
1039
+ /** Added after the first records were written: a record without them is still valid. */
1040
+ const OPTIONAL_SESSION_KEYS = ['launcherStartTime', 'childStartTime'];
1041
+ const SESSION_STATES = ['starting', 'idle', 'busy', 'waiting_approval'];
1042
+ const APPROVAL_KINDS = ['command', 'fileChange', 'permissions'];
1043
+ const UNKNOWN_VALUE = 'unknown';
1044
+
1045
+ /** @param {unknown} value @returns {value is SessionApproval} */
1046
+ function isSessionApproval(value) {
1047
+ if (!isPlainRecord(value)) return false;
1048
+ if (Object.keys(value).some((key) => !['kind', 'decider', 'since'].includes(key))) return false;
1049
+ return (
1050
+ APPROVAL_KINDS.includes(/** @type {string} */ (value.kind)) &&
1051
+ (value.decider === 'user' || value.decider === 'manager') &&
1052
+ isTime(value.since)
1053
+ );
1054
+ }
1055
+
1056
+ /** @param {Record<string, unknown>} value */
1057
+ function hasSessionKeys(value) {
1058
+ const keys = Object.keys(value);
1059
+ return (
1060
+ keys.every((key) => SESSION_KEYS.includes(key) || OPTIONAL_SESSION_KEYS.includes(key)) &&
1061
+ SESSION_KEYS.every((key) => Object.hasOwn(value, key))
1062
+ );
1063
+ }
1064
+
1065
+ /** @param {Record<string, unknown>} value */
1066
+ function hasValidReportedValues(value) {
1067
+ return (
1068
+ (value.hostVersion === null ||
1069
+ (typeof value.hostVersion === 'string' && VERSION_PATTERN.test(value.hostVersion))) &&
1070
+ typeof value.sandbox === 'string' &&
1071
+ REPORTED_VALUE_PATTERN.test(value.sandbox) &&
1072
+ typeof value.approvalPolicy === 'string' &&
1073
+ REPORTED_VALUE_PATTERN.test(value.approvalPolicy)
1074
+ );
1075
+ }
1076
+
1077
+ /**
1078
+ * Strict: no unknown keys, every field of the expected type and size; the
1079
+ * reported values short identifiers, the working directory free of control
1080
+ * characters.
1081
+ * @param {unknown} value
1082
+ * @returns {value is SessionRecord}
1083
+ */
1084
+ export function isSessionRecord(value) {
1085
+ if (!isPlainRecord(value) || !hasSessionKeys(value)) return false;
1086
+ const role = value.role;
1087
+ const name = value.name;
1088
+ if (role !== 'manager' && role !== 'worker') return false;
1089
+ if (typeof name !== 'string' || !NAME_PATTERN.test(name)) return false;
1090
+ if ((role === 'manager') !== (name === MANAGER_NAME)) return false;
1091
+ return (
1092
+ value.schemaVersion === BUS_SCHEMA_VERSION &&
1093
+ typeof value.sessionId === 'string' &&
1094
+ SESSION_ID_PATTERN.test(value.sessionId) &&
1095
+ (value.host === 'claude' || value.host === 'codex') &&
1096
+ hasValidReportedValues(value) &&
1097
+ isPid(value.launcherPid) &&
1098
+ (value.childPid === null || isPid(value.childPid)) &&
1099
+ isOptionalToken(value.launcherStartTime) &&
1100
+ isOptionalToken(value.childStartTime) &&
1101
+ isTime(value.startedAt) &&
1102
+ isSafeText(value.cwd, PATH_LENGTH_MAX) &&
1103
+ (value.locale === 'pt-BR' || value.locale === 'en') &&
1104
+ SESSION_STATES.includes(/** @type {string} */ (value.state)) &&
1105
+ isTime(value.stateSince) &&
1106
+ (value.turnOrigin === null || value.turnOrigin === 'user' || value.turnOrigin === 'manager') &&
1107
+ Number.isSafeInteger(value.queued) &&
1108
+ /** @type {number} */ (value.queued) >= 0 &&
1109
+ (value.approval === null || isSessionApproval(value.approval)) &&
1110
+ Array.isArray(value.heldApprovals) &&
1111
+ value.heldApprovals.length <= HELD_APPROVALS_MAX &&
1112
+ value.heldApprovals.every((id) => typeof id === 'string' && MESSAGE_ID_PATTERN.test(id))
1113
+ );
1114
+ }
1115
+
1116
+ /**
1117
+ * The record as it may be written: a working directory with its control
1118
+ * characters replaced, a host version that is not a version dropped, a
1119
+ * reported value that is not an identifier `unknown`. A strange directory
1120
+ * name or host output never stops a registration. Other fields are left for
1121
+ * `isSessionRecord` to judge.
1122
+ * @param {unknown} record
1123
+ * @returns {unknown}
1124
+ */
1125
+ function normalizeSessionRecord(record) {
1126
+ if (!isPlainRecord(record)) return record;
1127
+ /** @param {unknown} value */
1128
+ const reported = (value) =>
1129
+ typeof value === 'string' && !REPORTED_VALUE_PATTERN.test(value) ? UNKNOWN_VALUE : value;
1130
+ return {
1131
+ ...record,
1132
+ hostVersion:
1133
+ typeof record.hostVersion === 'string' && !VERSION_PATTERN.test(record.hostVersion)
1134
+ ? null
1135
+ : record.hostVersion,
1136
+ cwd:
1137
+ typeof record.cwd === 'string'
1138
+ ? cutCodeUnits(sanitizeText(record.cwd), PATH_LENGTH_MAX)
1139
+ : record.cwd,
1140
+ sandbox: reported(record.sandbox),
1141
+ approvalPolicy: reported(record.approvalPolicy),
1142
+ };
1143
+ }
1144
+
1145
+ /**
1146
+ * A session's recipient key: its own id for a worker, `manager` for the manager.
1147
+ * @param {Pick<SessionRecord, 'role' | 'sessionId'>} record
1148
+ */
1149
+ export function recipientOf(record) {
1150
+ return record.role === 'manager' ? MANAGER_RECIPIENT : record.sessionId;
1151
+ }
1152
+
1153
+ /** @param {RoomPaths} paths @param {string} sessionId */
1154
+ function sessionFile(paths, sessionId) {
1155
+ if (!SESSION_ID_PATTERN.test(sessionId))
1156
+ throw new BusError('bus_unavailable', 'session_id_invalid');
1157
+ return join(paths.sessions, `${sessionId}${JSON_SUFFIX}`);
1158
+ }
1159
+
1160
+ /**
1161
+ * Replace a session's record. Only the session's own processes call this. A
1162
+ * record whose child is this process gets this process's start time, so that
1163
+ * the role process that spreads the launcher's record and writes its own pid
1164
+ * is identified by it.
1165
+ * @param {RoomPaths} paths
1166
+ * @param {SessionRecord} record
1167
+ */
1168
+ export async function writeSession(paths, record) {
1169
+ const normalized = normalizeSessionRecord(record);
1170
+ const complete =
1171
+ isPlainRecord(normalized) && normalized.childPid === process.pid
1172
+ ? { ...normalized, childStartTime: processStartToken(process.pid) }
1173
+ : normalized;
1174
+ if (!isSessionRecord(complete)) throw new BusError('bus_unavailable', 'session_record_invalid');
1175
+ await writePrivateFile(
1176
+ paths,
1177
+ sessionFile(paths, complete.sessionId),
1178
+ `${JSON.stringify(complete)}\n`,
1179
+ );
1180
+ }
1181
+
1182
+ /**
1183
+ * @param {RoomPaths} paths
1184
+ * @param {string} sessionId
1185
+ * @returns {Promise<SessionRecord | null>}
1186
+ */
1187
+ export async function readSession(paths, sessionId) {
1188
+ const file = await readJsonFile(sessionFile(paths, sessionId), SESSION_FILE_BYTES_MAX);
1189
+ return file.ok && isSessionRecord(file.value) && file.value.sessionId === sessionId
1190
+ ? file.value
1191
+ : null;
1192
+ }
1193
+
1194
+ /**
1195
+ * A session is live while its launcher or its role process is (FR2): a
1196
+ * process with that pid exists, belongs to this user, and, when the record
1197
+ * has its start time, is the process that started then (not a reused pid).
1198
+ * @param {SessionRecord} record
1199
+ * @param {(pid: number) => boolean} alive
1200
+ * @param {(pid: number) => string | null} [startToken]
1201
+ */
1202
+ export function sessionLive(record, alive, startToken = processStartToken) {
1203
+ return (
1204
+ pidIsProcess(record.launcherPid, record.launcherStartTime, alive, startToken) ||
1205
+ (record.childPid !== null &&
1206
+ pidIsProcess(record.childPid, record.childStartTime, alive, startToken))
1207
+ );
1208
+ }
1209
+
1210
+ /**
1211
+ * Remove what a session leaves behind: its record, and for a worker its inbox,
1212
+ * its claimed directory and its delegation. The manager's inbox stays: it
1213
+ * belongs to the room. Nothing is removed through a directory that is not a
1214
+ * real directory of this user.
1215
+ * @param {RoomPaths} paths
1216
+ * @param {string} sessionId
1217
+ * @param {Role} role
1218
+ */
1219
+ export async function removeSession(paths, sessionId, role) {
1220
+ const file = sessionFile(paths, sessionId);
1221
+ /** @type {[string, string][]} */
1222
+ const targets = [[paths.sessions, file]];
1223
+ if (role === 'worker')
1224
+ targets.push(
1225
+ [paths.inbox, mailboxDirectory(paths, 'inbox', sessionId)],
1226
+ [paths.claimed, mailboxDirectory(paths, 'claimed', sessionId)],
1227
+ [paths.delegation, join(paths.delegation, `${sessionId}${JSON_SUFFIX}`)],
1228
+ );
1229
+ for (const [parent, target] of targets)
1230
+ if ((await directoryState(parent)) === 'directory')
1231
+ await rm(target, { recursive: true, force: true }).catch(() => undefined);
1232
+ }
1233
+
1234
+ /**
1235
+ * @typedef {object} SessionScan
1236
+ * @property {SessionRecord[]} live the live sessions
1237
+ * @property {Set<string>} present every session id that still has a record file, live or not
1238
+ */
1239
+
1240
+ /**
1241
+ * Read every record of the room. A valid record whose processes are gone is
1242
+ * removed with what it left. A record this client cannot validate (a newer
1243
+ * schema, a damaged file) is not live, and is removed only a day after its
1244
+ * last change; a record that could not be read at all is left alone.
1245
+ * @param {RoomPaths} paths
1246
+ * @param {BusClock & { sweep?: boolean }} [options]
1247
+ * @returns {Promise<SessionScan>}
1248
+ */
1249
+ async function scanSessions(paths, options = {}) {
1250
+ const timing = clockOf(options);
1251
+ /** @type {SessionScan} */
1252
+ const scan = { live: [], present: new Set() };
1253
+ let names;
1254
+ try {
1255
+ names = await readdir(paths.sessions);
1256
+ } catch {
1257
+ return scan;
1258
+ }
1259
+ const sweep = options.sweep !== false && (await directoryState(paths.sessions)) === 'directory';
1260
+ const staleBefore = timing.now() - LIMITS.retentionMs;
1261
+ for (const name of names.sort()) {
1262
+ if (!JSON_FILE.test(name)) continue;
1263
+ const sessionId = name.slice(0, -JSON_SUFFIX.length);
1264
+ if (!SESSION_ID_PATTERN.test(sessionId)) continue;
1265
+ const file = await readJsonFile(join(paths.sessions, name), SESSION_FILE_BYTES_MAX);
1266
+ if (!file.ok && file.reason === 'missing') continue;
1267
+ scan.present.add(sessionId);
1268
+ if (!file.ok && file.reason === 'io_error') continue;
1269
+ const record =
1270
+ file.ok && isSessionRecord(file.value) && file.value.sessionId === sessionId
1271
+ ? file.value
1272
+ : null;
1273
+ if (record !== null && sessionLive(record, timing.alive, timing.startToken)) {
1274
+ scan.live.push(record);
1275
+ continue;
1276
+ }
1277
+ if (!sweep || (record === null && !isOlderThan(file.modifiedAt, staleBefore))) continue;
1278
+ await removeSession(paths, sessionId, record?.role ?? 'worker');
1279
+ scan.present.delete(sessionId);
1280
+ }
1281
+ return scan;
1282
+ }
1283
+
1284
+ /**
1285
+ * The room's live sessions. A record whose processes are gone is removed with
1286
+ * what it left (FR2), unless `sweep` is false; see `scanSessions` for records
1287
+ * this client cannot read.
1288
+ * @param {RoomPaths} paths
1289
+ * @param {BusClock & { sweep?: boolean }} [options]
1290
+ * @returns {Promise<SessionRecord[]>}
1291
+ */
1292
+ export async function listSessions(paths, options = {}) {
1293
+ return (await scanSessions(paths, options)).live;
1294
+ }
1295
+
1296
+ /**
1297
+ * Inside the room lock: the room is still there and safe; directories a
1298
+ * damaged room lost are made again, and its descriptor too when this process
1299
+ * prepared the room.
1300
+ * @param {RoomPaths} paths
1301
+ * @param {{ stateRoot: string, room: RoomDescriptor } | null} prepared
1302
+ * @param {number} now
1303
+ */
1304
+ async function confirmRoom(paths, prepared, now) {
1305
+ if (!(await roomIsSafe(paths))) throw new BusError('bus_unavailable', 'room_unsafe');
1306
+ for (const directory of roomDirectories(paths)) await ensurePrivateDirectory(directory);
1307
+ if (prepared !== null && (await readRoom(paths)) === null)
1308
+ await writeRoomFile(paths, prepared.room, now);
1309
+ }
1310
+
1311
+ /**
1312
+ * @param {unknown} error
1313
+ * @param {{ stateRoot: string, room: RoomDescriptor } | null} prepared
1314
+ */
1315
+ function roomWasRemoved(error, prepared) {
1316
+ return (
1317
+ prepared !== null &&
1318
+ error instanceof BusError &&
1319
+ error.code === 'bus_unavailable' &&
1320
+ isRoomGone(error)
1321
+ );
1322
+ }
1323
+
1324
+ /**
1325
+ * Register one session under the room's lock (FR1): one live manager per room,
1326
+ * a worker name unique among the live sessions, at most sixteen workers. The
1327
+ * record gets the launcher's start time. A room a sweep removed between
1328
+ * `ensureRoom` and this call is built again, up to three times.
1329
+ * @param {RoomPaths} paths
1330
+ * @param {SessionRecord} record
1331
+ * @param {BusClock} [clock]
1332
+ */
1333
+ export async function registerSession(paths, record, clock) {
1334
+ const timing = clockOf(clock);
1335
+ const normalized = normalizeSessionRecord(record);
1336
+ if (!isSessionRecord(normalized)) throw new BusError('bus_unavailable', 'session_record_invalid');
1337
+ /** @type {SessionRecord} */
1338
+ const complete = {
1339
+ ...normalized,
1340
+ launcherStartTime: normalized.launcherStartTime ?? timing.startToken(normalized.launcherPid),
1341
+ childStartTime:
1342
+ normalized.childPid === null
1343
+ ? null
1344
+ : (normalized.childStartTime ?? timing.startToken(normalized.childPid)),
1345
+ };
1346
+ const prepared = preparedRooms.get(paths) ?? null;
1347
+ for (let attempt = 1; ; attempt += 1) {
1348
+ try {
1349
+ await withRoomLock(paths, () => registerLocked(paths, complete, prepared, clock), clock);
1350
+ return;
1351
+ } catch (error) {
1352
+ if (!roomWasRemoved(error, prepared) || attempt >= REGISTER_ATTEMPTS_MAX) throw error;
1353
+ const again = /** @type {{ stateRoot: string, room: RoomDescriptor }} */ (prepared);
1354
+ await ensureRoom(again.stateRoot, again.room, clock);
1355
+ }
1356
+ }
1357
+ }
1358
+
1359
+ /**
1360
+ * @param {RoomPaths} paths
1361
+ * @param {SessionRecord} record
1362
+ * @param {{ stateRoot: string, room: RoomDescriptor } | null} prepared
1363
+ * @param {BusClock} [clock]
1364
+ */
1365
+ async function registerLocked(paths, record, prepared, clock) {
1366
+ await confirmRoom(paths, prepared, clockOf(clock).now());
1367
+ const live = await listSessions(paths, clock);
1368
+ if (record.role === 'manager' && live.some((entry) => entry.role === 'manager'))
1369
+ throw new BusError('manager_already_active');
1370
+ if (record.role === 'worker') {
1371
+ if (live.some((entry) => entry.name === record.name)) throw new BusError('worker_name_taken');
1372
+ if (live.filter((entry) => entry.role === 'worker').length >= LIMITS.workersPerRoom)
1373
+ throw new BusError('room_full');
1374
+ }
1375
+ const recipient = recipientOf(record);
1376
+ await ensurePrivateDirectory(mailboxDirectory(paths, 'inbox', recipient));
1377
+ await ensurePrivateDirectory(mailboxDirectory(paths, 'claimed', recipient));
1378
+ await writeSession(paths, record);
1379
+ }
1380
+
1381
+ /**
1382
+ * The live manager of the room, or null.
1383
+ * @param {RoomPaths} paths
1384
+ * @param {BusClock} [clock]
1385
+ */
1386
+ export async function liveManager(paths, clock) {
1387
+ const live = await listSessions(paths, { ...clock, sweep: false });
1388
+ return live.find((entry) => entry.role === 'manager') ?? null;
1389
+ }
1390
+
1391
+ // ------------------------------------------------------------------ audit
1392
+
1393
+ export const AUDIT_EVENTS = Object.freeze([
1394
+ 'registered',
1395
+ 'closed',
1396
+ 'sent',
1397
+ 'queued',
1398
+ 'started',
1399
+ 'replied',
1400
+ 'expired',
1401
+ 'refused',
1402
+ 'cancelled',
1403
+ 'rejected',
1404
+ 'approval_wait',
1405
+ 'delegated',
1406
+ 'delegation_ended',
1407
+ 'approval_held',
1408
+ 'approval_outcome',
1409
+ ]);
1410
+
1411
+ /**
1412
+ * One audit line (FR11). Every field is an id, a number or a short code, so
1413
+ * message text, command text and paths cannot be written here by mistake.
1414
+ * @typedef {object} AuditEvent
1415
+ * @property {(typeof AUDIT_EVENTS)[number]} event
1416
+ * @property {string} [sessionId]
1417
+ * @property {string} [peerSessionId]
1418
+ * @property {string} [messageId] the correlation id of the whole exchange
1419
+ * @property {number} [bytes]
1420
+ * @property {number} [count]
1421
+ * @property {string} [kind]
1422
+ * @property {string} [outcome]
1423
+ * @property {string} [reason]
1424
+ */
1425
+
1426
+ const AUDIT_ID_FIELDS = /** @type {const} */ (['sessionId', 'peerSessionId', 'messageId']);
1427
+ const AUDIT_NUMBER_FIELDS = /** @type {const} */ (['bytes', 'count']);
1428
+ const AUDIT_CODE_FIELDS = /** @type {const} */ (['kind', 'outcome']);
1429
+ const AUDIT_ID_PATTERN = /^(?:manager|[0-9a-f]{32}|\d{13}-[0-9a-f]{16})$/u;
1430
+
1431
+ /**
1432
+ * The line that will be written for an event: unknown fields and values that
1433
+ * are not an id, a count or a code are dropped.
1434
+ * @param {AuditEvent} event
1435
+ * @param {number} at
1436
+ * @returns {Record<string, string | number> | null}
1437
+ */
1438
+ export function auditLine(event, at) {
1439
+ if (!AUDIT_EVENTS.includes(event.event)) return null;
1440
+ /** @type {Record<string, string | number>} */
1441
+ const line = { at, event: event.event };
1442
+ for (const field of AUDIT_ID_FIELDS) {
1443
+ const value = event[field];
1444
+ if (typeof value === 'string' && AUDIT_ID_PATTERN.test(value)) line[field] = value;
1445
+ }
1446
+ for (const field of AUDIT_NUMBER_FIELDS) {
1447
+ const value = event[field];
1448
+ if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) line[field] = value;
1449
+ }
1450
+ for (const field of AUDIT_CODE_FIELDS) {
1451
+ const value = event[field];
1452
+ if (typeof value === 'string' && CODE_PATTERN.test(value)) line[field] = value;
1453
+ }
1454
+ if (typeof event.reason === 'string' && AUDIT_REASON_PATTERN.test(event.reason))
1455
+ line.reason = event.reason;
1456
+ return line;
1457
+ }
1458
+
1459
+ /**
1460
+ * Append one line to a private file opened without following a symlink and
1461
+ * without blocking: a regular file of this user, or nothing is written.
1462
+ * @param {string} path
1463
+ * @param {string} text
1464
+ */
1465
+ async function appendPrivateLine(path, text) {
1466
+ const handle = await open(path, APPEND_FLAGS, PRIVATE_FILE_MODE);
1467
+ try {
1468
+ const entry = await handle.stat();
1469
+ if (!entry.isFile() || !ownedByUser(entry)) throw new BusError('bus_unavailable', 'not_a_file');
1470
+ await handle.writeFile(text);
1471
+ } finally {
1472
+ await handle.close().catch(() => undefined);
1473
+ }
1474
+ }
1475
+
1476
+ /**
1477
+ * Move a full JSON-lines file to `<file>.1`. With the room's paths this runs
1478
+ * under a lock of that file and checks the size again inside it, so two
1479
+ * writers that crossed the limit together rotate once and the previous file
1480
+ * survives. A busy lock skips the rotation; the line is still written.
1481
+ * @param {string} path
1482
+ * @param {number} rotateBytes
1483
+ * @param {{ paths?: RoomPaths, clock?: BusClock | undefined }} options
1484
+ */
1485
+ async function rotateJsonLines(path, rotateBytes, options) {
1486
+ const rotate = async () => {
1487
+ const entry = await lstat(path).catch(() => null);
1488
+ if (entry !== null && entry.isFile() && entry.size >= rotateBytes)
1489
+ await rename(path, `${path}.1`);
1490
+ };
1491
+ if (options.paths === undefined) {
1492
+ await rotate().catch(() => undefined);
1493
+ return;
1494
+ }
1495
+ await withFileLock(`${path}.lock`, options.paths.tmp, rotate, options.clock).catch(
1496
+ () => undefined,
1497
+ );
1498
+ }
1499
+
1500
+ /**
1501
+ * Append one line to a private JSON-lines file, rotating it first when it is
1502
+ * over the limit (one previous file is kept). Pass the room's paths so that
1503
+ * concurrent writers rotate once (`rotateJsonLines`).
1504
+ * @param {string} path
1505
+ * @param {unknown} line
1506
+ * @param {number} rotateBytes
1507
+ * @param {{ paths?: RoomPaths, clock?: BusClock | undefined }} [options]
1508
+ */
1509
+ export async function appendJsonLine(path, line, rotateBytes, options = {}) {
1510
+ const size = await lstat(path).then(
1511
+ (entry) => entry.size,
1512
+ () => 0,
1513
+ );
1514
+ if (size >= rotateBytes) await rotateJsonLines(path, rotateBytes, options);
1515
+ await appendPrivateLine(path, `${JSON.stringify(line)}\n`);
1516
+ }
1517
+
1518
+ /**
1519
+ * Write one audit line. Never throws: the audit must not stop a delivery.
1520
+ * @param {RoomPaths} paths
1521
+ * @param {AuditEvent} event
1522
+ * @param {BusClock} [clock]
1523
+ */
1524
+ export async function audit(paths, event, clock) {
1525
+ try {
1526
+ const line = auditLine(event, clockOf(clock).now());
1527
+ if (line === null) return;
1528
+ await appendJsonLine(paths.audit, line, LIMITS.auditRotateBytes, { paths, clock });
1529
+ } catch {
1530
+ // The audit never stops what it records.
1531
+ }
1532
+ }
1533
+
1534
+ // ------------------------------------------------------------------ pending records
1535
+
1536
+ /**
1537
+ * One request without a final reply (FR2). The full typedef is
1538
+ * `PendingRecord` in `messages.mjs`; the sweep needs only its times.
1539
+ * @param {unknown} value
1540
+ * @returns {value is { schemaVersion: 1, messageId: string, workerSessionId: string, workerName: string, createdAt: number, expiresAt: number }}
1541
+ */
1542
+ export function isPendingRecord(value) {
1543
+ if (!isPlainRecord(value)) return false;
1544
+ const keys = Object.keys(value);
1545
+ const expected = [
1546
+ 'schemaVersion',
1547
+ 'messageId',
1548
+ 'workerSessionId',
1549
+ 'workerName',
1550
+ 'createdAt',
1551
+ 'expiresAt',
1552
+ ];
1553
+ if (keys.length !== expected.length || !keys.every((key) => expected.includes(key))) return false;
1554
+ return (
1555
+ value.schemaVersion === BUS_SCHEMA_VERSION &&
1556
+ typeof value.messageId === 'string' &&
1557
+ MESSAGE_ID_PATTERN.test(value.messageId) &&
1558
+ typeof value.workerSessionId === 'string' &&
1559
+ SESSION_ID_PATTERN.test(value.workerSessionId) &&
1560
+ typeof value.workerName === 'string' &&
1561
+ NAME_PATTERN.test(value.workerName) &&
1562
+ isTime(value.createdAt) &&
1563
+ isTime(value.expiresAt)
1564
+ );
1565
+ }
1566
+
1567
+ /**
1568
+ * How long a pending record is kept (FR3): 24 hours after its request was
1569
+ * created, or one hour after the request expired, whichever is later, so that
1570
+ * a turn that started late and ends after 24 hours still finds it.
1571
+ * @param {{ createdAt: number, expiresAt: number }} record
1572
+ */
1573
+ export function pendingKeptUntil(record) {
1574
+ return Math.max(record.createdAt + LIMITS.retentionMs, record.expiresAt + LIMITS.pendingGraceMs);
1575
+ }
1576
+
1577
+ // ------------------------------------------------------------------ sweeps
1578
+
1579
+ /**
1580
+ * The time a bus entry was created: from its name when it is a message id,
1581
+ * from its modification time otherwise (never following a symlink).
1582
+ * @param {string} directory
1583
+ * @param {string} name
1584
+ * @param {boolean} byName
1585
+ * @returns {Promise<number | null>}
1586
+ */
1587
+ async function entryCreatedAt(directory, name, byName) {
1588
+ const match = byName ? MESSAGE_TIME.exec(name) : null;
1589
+ if (match) return Number(match[1]);
1590
+ return lstat(join(directory, name)).then(
1591
+ (entry) => entry.mtimeMs,
1592
+ () => null,
1593
+ );
1594
+ }
1595
+
1596
+ /**
1597
+ * Remove the entries of one directory that are older than a limit, when it is
1598
+ * a real directory of this user (a recipient's mailbox may be a symlink).
1599
+ * @param {string} directory
1600
+ * @param {number} olderThan
1601
+ * @param {{ byName: boolean }} options
1602
+ * @returns {Promise<number>} entries still there
1603
+ */
1604
+ async function sweepOlderThan(directory, olderThan, { byName }) {
1605
+ if ((await directoryState(directory)) !== 'directory') return 0;
1606
+ let names;
1607
+ try {
1608
+ names = await readdir(directory);
1609
+ } catch {
1610
+ return 0;
1611
+ }
1612
+ let kept = 0;
1613
+ for (const name of names) {
1614
+ if (isOlderThan(await entryCreatedAt(directory, name, byName), olderThan))
1615
+ await rm(join(directory, name), { recursive: true, force: true }).catch(() => undefined);
1616
+ else kept += 1;
1617
+ }
1618
+ return kept;
1619
+ }
1620
+
1621
+ /**
1622
+ * The directories of worker recipients that no session record names any
1623
+ * more. An entry that is not a session id is removed only a day after its
1624
+ * last change.
1625
+ * @param {string} box
1626
+ * @param {Set<string>} present
1627
+ * @param {number} staleBefore
1628
+ */
1629
+ async function sweepOrphanMailboxes(box, present, staleBefore) {
1630
+ let names;
1631
+ try {
1632
+ names = await readdir(box);
1633
+ } catch {
1634
+ return;
1635
+ }
1636
+ for (const name of names) {
1637
+ if (name === MANAGER_RECIPIENT || present.has(name)) continue;
1638
+ if (
1639
+ !SESSION_ID_PATTERN.test(name) &&
1640
+ !isOlderThan(await entryCreatedAt(box, name, false), staleBefore)
1641
+ )
1642
+ continue;
1643
+ await rm(join(box, name), { recursive: true, force: true }).catch(() => undefined);
1644
+ }
1645
+ }
1646
+
1647
+ /**
1648
+ * Grants of workers that no session record names any more. An entry that is
1649
+ * not a grant's name is removed only a day after its last change.
1650
+ * @param {RoomPaths} paths
1651
+ * @param {Set<string>} present
1652
+ * @param {number} staleBefore
1653
+ */
1654
+ async function sweepGrants(paths, present, staleBefore) {
1655
+ const names = await readdir(paths.delegation).catch(() => []);
1656
+ for (const name of names) {
1657
+ const sessionId = name.endsWith(JSON_SUFFIX) ? name.slice(0, -JSON_SUFFIX.length) : null;
1658
+ const isGrantName = sessionId !== null && SESSION_ID_PATTERN.test(sessionId);
1659
+ if (isGrantName && present.has(/** @type {string} */ (sessionId))) continue;
1660
+ if (
1661
+ !isGrantName &&
1662
+ !isOlderThan(await entryCreatedAt(paths.delegation, name, false), staleBefore)
1663
+ )
1664
+ continue;
1665
+ await rm(join(paths.delegation, name), { recursive: true, force: true }).catch(() => undefined);
1666
+ }
1667
+ }
1668
+
1669
+ /**
1670
+ * Pending records past `pendingKeptUntil` are removed; a file that is not a
1671
+ * pending record a day after its last change.
1672
+ * @param {RoomPaths} paths
1673
+ * @param {number} now
1674
+ * @returns {Promise<number>} pending records still kept
1675
+ */
1676
+ async function sweepPending(paths, now) {
1677
+ const names = await readdir(paths.pending).catch(() => []);
1678
+ let kept = 0;
1679
+ for (const name of names) {
1680
+ const path = join(paths.pending, name);
1681
+ const file = await readJsonFile(path, PENDING_FILE_BYTES_MAX);
1682
+ if (!file.ok && file.reason === 'missing') continue;
1683
+ if (!file.ok && file.reason === 'io_error') {
1684
+ kept += 1;
1685
+ continue;
1686
+ }
1687
+ const record = file.ok && isPendingRecord(file.value) ? file.value : null;
1688
+ if (record !== null && `${record.messageId}${JSON_SUFFIX}` === name) {
1689
+ if (now < pendingKeptUntil(record)) kept += 1;
1690
+ else await removeIfUnchanged(path, file.ino);
1691
+ continue;
1692
+ }
1693
+ if (isOlderThan(file.modifiedAt, now - LIMITS.retentionMs))
1694
+ await rm(path, { recursive: true, force: true }).catch(() => undefined);
1695
+ }
1696
+ return kept;
1697
+ }
1698
+
1699
+ /**
1700
+ * The decision record and its previous file, each deleted thirty days after
1701
+ * its last line (FR13).
1702
+ * @param {RoomPaths} paths
1703
+ * @param {number} now
1704
+ * @returns {Promise<boolean>} whether any of them is still kept
1705
+ */
1706
+ async function purgeDecisions(paths, now) {
1707
+ let kept = false;
1708
+ for (const file of [paths.decisions, `${paths.decisions}.1`]) {
1709
+ const entry = await lstat(file).catch(() => null);
1710
+ if (entry === null) continue;
1711
+ if (now - entry.mtimeMs <= LIMITS.decisionsRetentionMs) kept = true;
1712
+ else await rm(file, { force: true }).catch(() => undefined);
1713
+ }
1714
+ return kept;
1715
+ }
1716
+
1717
+ /**
1718
+ * @typedef {object} RoomLeft
1719
+ * @property {number} sessions live sessions
1720
+ * @property {number} records session records still there, live or not
1721
+ * @property {number} pending pending records still kept
1722
+ * @property {boolean} decisions a decision record younger than thirty days
1723
+ */
1724
+
1725
+ /**
1726
+ * The destructive part of a sweep, called under the room lock once the room
1727
+ * is known to be safe (FR2, FR3, D12, FR13).
1728
+ * @param {RoomPaths} paths
1729
+ * @param {BusClock} [clock]
1730
+ * @returns {Promise<RoomLeft>}
1731
+ */
1732
+ async function sweepRoomContents(paths, clock) {
1733
+ const { now } = clockOf(clock);
1734
+ const { live, present } = await scanSessions(paths, clock);
1735
+ const at = now();
1736
+ const staleBefore = at - LIMITS.retentionMs;
1737
+ await sweepOrphanMailboxes(paths.inbox, present, staleBefore);
1738
+ await sweepOrphanMailboxes(paths.claimed, present, staleBefore);
1739
+ // Message bodies live 24 hours, whoever their recipient is (D12).
1740
+ for (const recipient of [MANAGER_RECIPIENT, ...present])
1741
+ for (const box of /** @type {const} */ (['inbox', 'claimed']))
1742
+ await sweepOlderThan(mailboxDirectory(paths, box, recipient), staleBefore, {
1743
+ byName: true,
1744
+ });
1745
+ const pending = await sweepPending(paths, at);
1746
+ await sweepOlderThan(paths.tmp, at - TEMPORARY_FILE_MAX_AGE_MS, { byName: false });
1747
+ await sweepGrants(paths, present, staleBefore);
1748
+ const decisions = await purgeDecisions(paths, at);
1749
+ return { sessions: live.length, records: present.size, pending, decisions };
1750
+ }
1751
+
1752
+ /**
1753
+ * Sweep one room (FR2, FR3): sessions whose processes are gone with what they
1754
+ * left, message bodies, pending records and temporary files past their time,
1755
+ * grants of workers that are gone, a decision record past thirty days. A room
1756
+ * whose directories are not real directories of this user is left alone; the
1757
+ * rest runs under the room lock. Never throws.
1758
+ * @param {RoomPaths} paths
1759
+ * @param {BusClock} [clock]
1760
+ * @returns {Promise<{ sessions: number, pending: number }>} what is still live
1761
+ */
1762
+ export async function sweepRoom(paths, clock) {
1763
+ const nothing = { sessions: 0, pending: 0 };
1764
+ try {
1765
+ if (!(await roomIsSafe(paths))) return nothing;
1766
+ const left = await withRoomLock(
1767
+ paths,
1768
+ async () => ((await roomIsSafe(paths)) ? sweepRoomContents(paths, clock) : null),
1769
+ clock,
1770
+ );
1771
+ return left === null ? nothing : { sessions: left.sessions, pending: left.pending };
1772
+ } catch {
1773
+ return nothing;
1774
+ }
1775
+ }
1776
+
1777
+ /**
1778
+ * Sweep one room and, when nothing is left in it, remove it: renamed aside
1779
+ * under its lock, so that a launch waiting for the lock finds the room gone
1780
+ * and builds it again, then deleted.
1781
+ * @param {RoomPaths} paths
1782
+ * @param {BusClock} [clock]
1783
+ * @returns {Promise<boolean>} whether the room was removed
1784
+ */
1785
+ async function sweepOrRemoveRoom(paths, clock) {
1786
+ if (!(await roomIsSafe(paths))) return false;
1787
+ let aside = null;
1788
+ try {
1789
+ aside = await withRoomLock(
1790
+ paths,
1791
+ async () => {
1792
+ if (!(await roomIsSafe(paths))) return null;
1793
+ const left = await sweepRoomContents(paths, clock);
1794
+ if (left.sessions > 0 || left.records > 0 || left.pending > 0 || left.decisions)
1795
+ return null;
1796
+ const target = join(paths.rooms, `.removed-${newSessionId()}`);
1797
+ await rename(paths.room, target);
1798
+ return target;
1799
+ },
1800
+ clock,
1801
+ );
1802
+ } catch {
1803
+ return false;
1804
+ }
1805
+ if (aside === null) return false;
1806
+ await rm(aside, { recursive: true, force: true }).catch(() => undefined);
1807
+ return true;
1808
+ }
1809
+
1810
+ /**
1811
+ * Sweep every room of the bus, and remove a room that has no session record,
1812
+ * no pending record still kept and no decision record left to review. Called
1813
+ * by each launch and each listing, like `sweepStaleLaunches`. Never throws.
1814
+ * @param {string} stateRoot
1815
+ * @param {BusClock} [clock]
1816
+ * @returns {Promise<number>} rooms removed
1817
+ */
1818
+ export async function sweepBus(stateRoot, clock) {
1819
+ try {
1820
+ const bus = busRoot(stateRoot);
1821
+ const rooms = join(bus, 'rooms');
1822
+ if ((await directoryState(bus)) !== 'directory') return 0;
1823
+ if ((await directoryState(rooms)) !== 'directory') return 0;
1824
+ const entries = await readdir(rooms, { withFileTypes: true }).catch(() => []);
1825
+ let removed = 0;
1826
+ for (const entry of entries) {
1827
+ if (!entry.isDirectory()) continue;
1828
+ if (REMOVED_ROOM_PATTERN.test(entry.name)) {
1829
+ // Left by a sweep that stopped between its rename and its delete.
1830
+ await rm(join(rooms, entry.name), { recursive: true, force: true }).catch(() => undefined);
1831
+ continue;
1832
+ }
1833
+ if (!ROOM_ID_PATTERN.test(entry.name)) continue;
1834
+ if (await sweepOrRemoveRoom(roomPaths(stateRoot, entry.name), clock)) removed += 1;
1835
+ }
1836
+ return removed;
1837
+ } catch {
1838
+ return 0;
1839
+ }
1840
+ }
1841
+
1842
+ /**
1843
+ * Every room of the bus with its descriptor, for `aisac doctor` and listings.
1844
+ * @param {string} stateRoot
1845
+ * @returns {Promise<{ descriptor: RoomDescriptor, paths: RoomPaths }[]>}
1846
+ */
1847
+ export async function listRooms(stateRoot) {
1848
+ const rooms = join(busRoot(stateRoot), 'rooms');
1849
+ const entries = await readdir(rooms, { withFileTypes: true }).catch(() => []);
1850
+ /** @type {{ descriptor: RoomDescriptor, paths: RoomPaths }[]} */
1851
+ const found = [];
1852
+ for (const entry of entries.sort((left, right) => (left.name < right.name ? -1 : 1))) {
1853
+ if (!entry.isDirectory() || !ROOM_ID_PATTERN.test(entry.name)) continue;
1854
+ const paths = roomPaths(stateRoot, entry.name);
1855
+ const descriptor = await readRoom(paths);
1856
+ if (descriptor !== null && descriptor.id === entry.name) found.push({ descriptor, paths });
1857
+ }
1858
+ return found;
1859
+ }
1860
+
1861
+ // ------------------------------------------------------------------ the role environment
1862
+
1863
+ /**
1864
+ * @typedef {object} RoleEnvironment
1865
+ * @property {1} schemaVersion
1866
+ * @property {Role} role
1867
+ * @property {string} stateRoot
1868
+ * @property {string} roomId
1869
+ * @property {string} sessionId
1870
+ * @property {string} name
1871
+ * @property {BusLocale} locale
1872
+ */
1873
+
1874
+ /**
1875
+ * The value the launcher puts in `AISAC_WORKER_ROLE` or `AISAC_MANAGER_ROLE`.
1876
+ * Identity reaches a role process only this way (spec §8).
1877
+ * @param {Omit<RoleEnvironment, 'schemaVersion'>} role
1878
+ */
1879
+ export function roleEnvironmentValue(role) {
1880
+ return JSON.stringify({ schemaVersion: BUS_SCHEMA_VERSION, ...role });
1881
+ }
1882
+
1883
+ const ROLE_KEYS = ['schemaVersion', 'role', 'stateRoot', 'roomId', 'sessionId', 'name', 'locale'];
1884
+ const ROLE_VALUE_BYTES_MAX = 8 * KIBIBYTE;
1885
+
1886
+ /**
1887
+ * Parse the role a launcher handed to this process. Anything that is not
1888
+ * exactly the expected shape is no role at all.
1889
+ * @param {string | undefined} value
1890
+ * @param {Role} role
1891
+ * @returns {RoleEnvironment | null}
1892
+ */
1893
+ export function parseRoleEnvironment(value, role) {
1894
+ if (typeof value !== 'string' || value.length === 0 || value.length > ROLE_VALUE_BYTES_MAX)
1895
+ return null;
1896
+ /** @type {unknown} */
1897
+ let parsed;
1898
+ try {
1899
+ parsed = JSON.parse(value);
1900
+ } catch {
1901
+ return null;
1902
+ }
1903
+ if (!isPlainRecord(parsed)) return null;
1904
+ const keys = Object.keys(parsed);
1905
+ if (keys.length !== ROLE_KEYS.length || keys.some((key) => !ROLE_KEYS.includes(key))) return null;
1906
+ const { stateRoot, roomId, sessionId, name, locale } = parsed;
1907
+ if (parsed.schemaVersion !== BUS_SCHEMA_VERSION || parsed.role !== role) return null;
1908
+ if (
1909
+ typeof stateRoot !== 'string' ||
1910
+ !stateRoot.startsWith('/') ||
1911
+ resolve(stateRoot) !== stateRoot
1912
+ )
1913
+ return null;
1914
+ if (stateRoot.length > PATH_LENGTH_MAX) return null;
1915
+ if (typeof roomId !== 'string' || !ROOM_ID_PATTERN.test(roomId)) return null;
1916
+ if (typeof sessionId !== 'string' || !SESSION_ID_PATTERN.test(sessionId)) return null;
1917
+ if (typeof name !== 'string' || !NAME_PATTERN.test(name)) return null;
1918
+ if ((role === 'manager') !== (name === MANAGER_NAME)) return null;
1919
+ if (locale !== 'pt-BR' && locale !== 'en') return null;
1920
+ return { schemaVersion: BUS_SCHEMA_VERSION, role, stateRoot, roomId, sessionId, name, locale };
1921
+ }