@orkestrel/scaffold 0.0.121 → 0.0.123

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.
Files changed (85) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +57 -9
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +22 -2
  3. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +539 -0
  4. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1163 -0
  5. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +5 -5
  6. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +67 -5
  7. package/dist/bin/main.js +8 -6
  8. package/dist/bin/main.js.map +1 -1
  9. package/dist/host/agents/orchestration.md +29 -18
  10. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +7 -6
  11. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +3 -2
  12. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +65 -9
  13. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +28 -2
  14. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -2
  15. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +3 -2
  16. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +24 -11
  17. package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +18 -12
  18. package/dist/host/agents/skills/orkestrel-harden/references/document.md +1 -0
  19. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +2 -1
  20. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +4 -4
  21. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +642 -0
  22. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +665 -0
  23. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +16 -15
  24. package/dist/host/agents/skills/orkestrel-parallel/references/{claude.md → claude-code.md} +13 -13
  25. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +1 -0
  26. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1433 -0
  27. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +12 -9
  28. package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
  29. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +39 -8
  30. package/dist/host/agents/skills/orkestrel-publish/references/window.md +5 -1
  31. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +5 -5
  32. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +86 -7
  33. package/dist/host/claude/AGENTS.md +2 -2
  34. package/dist/host/claude/agents/analyst.md +1 -1
  35. package/dist/host/claude/agents/builder.md +1 -1
  36. package/dist/host/claude/agents/distiller.md +2 -1
  37. package/dist/host/claude/agents/grok.md +2 -2
  38. package/dist/host/claude/agents/opus.md +8 -7
  39. package/dist/host/claude/agents/orkestrel.md +7 -7
  40. package/dist/host/claude/agents/planner.md +3 -3
  41. package/dist/host/claude/agents/reviewer.md +3 -3
  42. package/dist/host/claude/agents/scout.md +2 -1
  43. package/dist/host/claude/agents/verifier.md +2 -2
  44. package/dist/host/claude/rules/campaign.md +15 -13
  45. package/dist/host/claude/rules/documentation.md +1 -0
  46. package/dist/host/claude/rules/names.md +13 -7
  47. package/dist/host/claude/rules/patterns.md +14 -0
  48. package/dist/host/claude/rules/quality.md +4 -1
  49. package/dist/host/claude/rules/tests.md +5 -1
  50. package/dist/host/claude/rules/workspace.md +9 -0
  51. package/dist/host/claude/rules/writing.md +1 -1
  52. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  53. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  54. package/dist/host/codex/agents/analyst.toml +6 -6
  55. package/dist/host/codex/agents/astra.toml +1 -1
  56. package/dist/host/codex/agents/builder.toml +1 -1
  57. package/dist/host/codex/agents/distiller.toml +4 -2
  58. package/dist/host/codex/agents/grok.toml +5 -2
  59. package/dist/host/codex/agents/opus.toml +6 -4
  60. package/dist/host/codex/agents/planner.toml +6 -5
  61. package/dist/host/codex/agents/reviewer.toml +9 -8
  62. package/dist/host/codex/agents/scout.toml +5 -1
  63. package/dist/host/codex/agents/verifier.toml +8 -3
  64. package/dist/host/dotfiles/gitignore +1 -2
  65. package/dist/host/guides/agent.md +1119 -457
  66. package/dist/host/guides/ndjson.md +81 -21
  67. package/dist/host/guides/ollama.md +22 -18
  68. package/dist/host/guides/probe.md +29 -27
  69. package/dist/host/guides/scaffold.md +42 -15
  70. package/dist/host/guides/study.md +538 -450
  71. package/dist/host/manifest.json +81 -63
  72. package/dist/host/tests/config.test.ts +7 -0
  73. package/dist/src/core/index.cjs +14 -8
  74. package/dist/src/core/index.cjs.map +1 -1
  75. package/dist/src/core/index.d.cts +1 -4
  76. package/dist/src/core/index.d.ts +1 -4
  77. package/dist/src/core/index.js +14 -8
  78. package/dist/src/core/index.js.map +1 -1
  79. package/dist/src/server/index.cjs +87 -8
  80. package/dist/src/server/index.cjs.map +1 -1
  81. package/dist/src/server/index.d.cts +50 -6
  82. package/dist/src/server/index.d.ts +50 -6
  83. package/dist/src/server/index.js +87 -10
  84. package/dist/src/server/index.js.map +1 -1
  85. package/package.json +2 -2
@@ -0,0 +1,1433 @@
1
+ // Run one process-running command at a time on this host, in arrival order, across every checkout
2
+ // and shell of one user account. Run from the checkout root:
3
+ // node .agents/skills/orkestrel-parallel/scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] -- COMMAND [ARGS...]
4
+ // node .agents/skills/orkestrel-parallel/scripts/lane.ts --status [--root DIR] [--json]
5
+ // A run takes a ticket, waits for every earlier ticket, runs the command through the dispatch skill's
6
+ // `launch` script, reads the process tree, and releases. The launcher owns the cap, the journal, and
7
+ // the errors file; its stdout lines pass through verbatim, and the cap must be above 0. The two forms
8
+ // are two operation modes, so `--status` with a run's flag or a bare `--` is refused, and `--json`
9
+ // belongs to `--status` alone. A run therefore cannot ask the launcher for its own `--status` files.
10
+ // `--status` prints each ticket in arrival order with its label and
11
+ // `live`, `dead`, or `unread`, and names the holder: the earliest live ticket with a run record. It
12
+ // writes nothing, removes nothing, and creates no root; an absent root reads as an empty queue. The
13
+ // root is `.orkestrel/lane` under the account's home directory, read from the account record and
14
+ // never from an environment variable; `--root DIR` is for a proof. Bench execs stay outside the lane,
15
+ // because the host bound counts process-running commands.
16
+ // Exit: the launcher's code (the command's code, 124 when capped, 127 when the command could not
17
+ // start); 1 when a signal ended the launcher; 64 on usage; 75 when the lane refused before the
18
+ // command ran; 70 when the command ran and its tree still reads as present, or its ticket could not
19
+ // be removed. `--status` exits 0 on a read and 75 when the root cannot be listed. A command that itself
20
+ // exits 64, 70, or 75 reads like the lane's own code.
21
+ // Protocol: a process listens on an endpoint named by a random token, writes the complete ticket to
22
+ // `<token>.stage`, and hard-links that file to `<sequence>.ticket`, which publishes it in one step.
23
+ // A waiter parks on the `close` of the nearest earlier ticket's endpoint with no timer, and a refused
24
+ // connect means that owner is gone. A waiter on a stage file writes one byte, and a published owner
25
+ // closes that connection, because a connection its synchronous allocation left unaccepted would
26
+ // otherwise stay parked on a process that waits behind it.
27
+ // Limits:
28
+ // - Process-identifier reuse, Windows. A row is matched by id and creation date, bounded by a clock
29
+ // comparison, so a reuse of an exited seed's id inside the clock allowance can misattribute a row.
30
+ // Only the holder kills, and only inside its own bounds.
31
+ // - Process-identifier reuse, other hosts. A group id cannot be reused while the group has a member.
32
+ // An empty group's id can be reused by a later group leader, so a reclaimer might refuse on a stale
33
+ // run record. It never kills on one.
34
+ // - A descendant that detached itself. A process that left the group, a run started through the WMI
35
+ // detach of `.agents/platforms/windows.md`, and a Windows descendant whose parent exited before the
36
+ // reading and is no recorded seed are all outside every reading. A background child of a `bash`
37
+ // command can be that case, so pass a command directly rather than through `bash -c`. "No surviving
38
+ // process tree" means the group, or the parent-link closure, and no more.
39
+ // - An owner ended alone mid-run. No event reports a foreign tree's end. Arrivals exit 75 until that
40
+ // tree is gone, and the next arrival then reclaims.
41
+ // - An owner ended between the run record and the launcher id. The tree cannot be identified. Arrivals
42
+ // exit 75 until a person deletes the named files. An owner ended between the launcher id and the
43
+ // command id leaves the command as no seed, so its tree reads through the launcher alone.
44
+ // - An unreaped member. On a host whose init does not reap, a killed member can keep reading as
45
+ // present. The lane exits 70 and stays held.
46
+ // - Listing completeness. No probe proves that a listing returns every stable entry. The design takes
47
+ // it from the documented directory-read contract.
48
+ // - Queue scope. The queue is one per user account per host. A wiped root, a second account, or a
49
+ // `--root` outside a proof gives a second queue that does not see the first.
50
+ // - A denied root. A sandbox that refuses the root or the endpoint exits 75; no sandboxed bench exec
51
+ // has run this script.
52
+ // - Linux. Every non-Windows branch is unread on this host and needs a Linux run: the socket file, the
53
+ // process group, and the signal handling.
54
+ // Migration stop: a second queue does not see the first, so while a host's sessions run another
55
+ // serializer, no caller moves. After a scaffold release carries this script and no command runs on the
56
+ // host, move every caller in one step and delete the serializer this replaces.
57
+ import type { ChildProcess } from 'node:child_process'
58
+ import type { Server, Socket } from 'node:net'
59
+ import { spawn, spawnSync } from 'node:child_process'
60
+ import { randomUUID } from 'node:crypto'
61
+ import {
62
+ existsSync,
63
+ linkSync,
64
+ mkdirSync,
65
+ readdirSync,
66
+ readFileSync,
67
+ realpathSync,
68
+ rmSync,
69
+ writeFileSync,
70
+ } from 'node:fs'
71
+ import { connect, createServer } from 'node:net'
72
+ import { hostname, userInfo } from 'node:os'
73
+ import { dirname, extname, join } from 'node:path'
74
+ import { createInterface } from 'node:readline'
75
+ import { fileURLToPath } from 'node:url'
76
+
77
+ /** Holds the protocol version a ticket carries, so a process refuses a ticket it cannot read. */
78
+ export const PROTOCOL = 1
79
+
80
+ /** Lists the flags that take a value. */
81
+ export const VALUE_FLAGS: readonly string[] = [
82
+ '--label',
83
+ '--journal',
84
+ '--errors',
85
+ '--cap',
86
+ '--root',
87
+ ]
88
+
89
+ /** Lists the flags only a run reads, which `--status` refuses. */
90
+ export const RUN_FLAGS: readonly string[] = ['--label', '--journal', '--errors', '--cap']
91
+
92
+ /** Lists every flag the script reads, value flags and switches alike. */
93
+ export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--status', '--json']
94
+
95
+ /** Holds the usage line printed on a usage refusal. */
96
+ export const USAGE =
97
+ 'usage: lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] -- COMMAND [ARGS...] | lane.ts --status [--root DIR] [--json]; the journal and the errors file differ, and the cap is a number of seconds above 0 up to 2147483'
98
+
99
+ /** Holds the longest cap in whole seconds, equal to the limit of the sibling launcher. */
100
+ export const MAX_CAP_SECONDS = 2_147_483
101
+
102
+ /** Holds the digit count of a ticket name, which keeps a directory listing readable in order. */
103
+ export const SEQUENCE_WIDTH = 12
104
+
105
+ /** Holds the name ending of a stage file. */
106
+ export const STAGE_SUFFIX = '.stage'
107
+
108
+ /** Holds the name ending of a ticket. */
109
+ export const TICKET_SUFFIX = '.ticket'
110
+
111
+ /** Holds the name ending of a run record. */
112
+ export const RUN_SUFFIX = '.run'
113
+
114
+ /** Holds the name ending of a token's socket file on a host without named pipes. */
115
+ export const SOCKET_SUFFIX = '.sock'
116
+
117
+ /** Matches a token, which every endpoint name and stage file name is built from. */
118
+ export const TOKEN_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u
119
+
120
+ /** Matches a ticket name and captures its sequence. */
121
+ export const TICKET_PATTERN = /^(\d+)\.ticket$/u
122
+
123
+ /** Matches one snapshot row: process id, parent id, and creation time in milliseconds. */
124
+ export const ROW_PATTERN = /^(\d+) (\d+) (\d+)$/u
125
+
126
+ /** Lists the signals that interrupt a lane on a host that delivers them. */
127
+ export const STOP_SIGNALS: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP']
128
+
129
+ /**
130
+ * Holds the clock allowance in milliseconds between `Date.now` and a process's creation date.
131
+ *
132
+ * @remarks
133
+ * The allowance is one default clock tick of 15.625 ms, rounded up, in case the kernel stamps from
134
+ * the tick.
135
+ */
136
+ export const CLOCK_ALLOWANCE_MS = 16
137
+
138
+ /**
139
+ * Holds the kill attempts the handover reading makes before it stays held.
140
+ *
141
+ * @remarks
142
+ * Each attempt on Windows is a synchronous `taskkill` per member and a process snapshot. A member
143
+ * that outlives this many forced kills is a defect a person reads rather than a wait the queue absorbs.
144
+ */
145
+ export const KILL_BUDGET = 5
146
+
147
+ /** Holds the pause in milliseconds after a group signal, because no event reports a group's end. */
148
+ export const KILL_PAUSE_MS = 200
149
+
150
+ /**
151
+ * Holds the removal retries, each `rmSync` delay growing by {@link REMOVAL_DELAY_MS}.
152
+ *
153
+ * @remarks
154
+ * The retries outlast a scanner holding a file.
155
+ */
156
+ export const REMOVAL_RETRIES = 10
157
+
158
+ /** Holds the base delay in milliseconds between removal retries. */
159
+ export const REMOVAL_DELAY_MS = 100
160
+
161
+ /** Holds the PowerShell text that prints one row per process with a creation date. */
162
+ export const SNAPSHOT_COMMAND =
163
+ "Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate | Where-Object { $_.CreationDate } | ForEach-Object { '{0} {1} {2}' -f $_.ProcessId, $_.ParentProcessId, ([DateTimeOffset]$_.CreationDate).ToUnixTimeMilliseconds() }"
164
+
165
+ /** Describes the complete record a stage file holds and a ticket publishes. */
166
+ export interface Ticket {
167
+ readonly protocol: number
168
+ readonly token: string
169
+ readonly label: string
170
+ readonly pid: number
171
+ readonly host: string
172
+ readonly platform: string
173
+ readonly cwd: string
174
+ readonly arrived: string
175
+ }
176
+
177
+ /** Describes one ticket in the queue: its sequence and its record, undefined when unreadable. */
178
+ export interface Entry {
179
+ readonly sequence: number
180
+ readonly ticket: Ticket | undefined
181
+ }
182
+
183
+ /** Describes the record of a started command: when it started and the ids that seed its tree. */
184
+ export interface Run {
185
+ readonly started: number
186
+ readonly launcher: number | undefined
187
+ readonly command: number | undefined
188
+ }
189
+
190
+ /** Describes one process in a Windows snapshot. */
191
+ export interface Row {
192
+ readonly pid: number
193
+ readonly parent: number
194
+ readonly created: number
195
+ }
196
+
197
+ /** Describes what a process does next on the queue. */
198
+ export type Turn =
199
+ | { readonly state: 'holder' }
200
+ | { readonly state: 'staged'; readonly name: string }
201
+ | { readonly state: 'behind'; readonly entry: Entry }
202
+ | { readonly state: 'refused'; readonly reason: string }
203
+
204
+ /** Describes what a sweep confirmed: whether the tree reads as gone, and the members it left. */
205
+ export interface Sweep {
206
+ readonly gone: boolean
207
+ readonly members: readonly number[]
208
+ }
209
+
210
+ /** Describes one ticket as `--status` reports it. */
211
+ export interface StatusRow {
212
+ readonly sequence: number
213
+ readonly label: string | undefined
214
+ readonly pid: number | undefined
215
+ readonly state: 'live' | 'dead' | 'unread'
216
+ }
217
+
218
+ /** Describes what `--status` reads: every ticket in arrival order and the holder among them. */
219
+ export interface Status {
220
+ readonly tickets: readonly StatusRow[]
221
+ readonly holder: StatusRow | undefined
222
+ }
223
+
224
+ /** Describes one validated run. */
225
+ export interface LaneOptions {
226
+ readonly root: string
227
+ readonly label: string
228
+ readonly journal: string
229
+ readonly errors: string
230
+ readonly cap: number
231
+ readonly command: readonly string[]
232
+ }
233
+
234
+ /**
235
+ * Holds a process's endpoint, whose existence is the process's liveness.
236
+ *
237
+ * @remarks
238
+ * The host closes the endpoint however the process ends. The server sends nothing. A stage waiter
239
+ * writes one byte, and a published owner closes that connection on reading it; the connection of a
240
+ * ticket waiter stays open until the process ends.
241
+ */
242
+ export class Token {
243
+ readonly #sockets = new Set<Socket>()
244
+ readonly #server: Server
245
+ #published = false
246
+
247
+ constructor() {
248
+ this.#server = createServer((socket) => this.#admit(socket))
249
+ }
250
+
251
+ /**
252
+ * Starts listening.
253
+ *
254
+ * @param endpoint - The endpoint to listen on.
255
+ * @returns A promise that resolves when the endpoint accepts connections, and rejects with the
256
+ * listen failure.
257
+ */
258
+ listen(endpoint: string): Promise<void> {
259
+ return new Promise((resolve, reject) => {
260
+ this.#server.once('error', reject)
261
+ this.#server.listen(endpoint, () => {
262
+ this.#server.removeListener('error', reject)
263
+ resolve()
264
+ })
265
+ })
266
+ }
267
+
268
+ /** Marks the stage as ended and closes every accepted connection, which wakes each waiter. */
269
+ publish(): void {
270
+ this.#published = true
271
+ for (const socket of this.#sockets) socket.destroy()
272
+ }
273
+
274
+ /**
275
+ * Closes the endpoint and every connection.
276
+ *
277
+ * @returns A promise that resolves when the server has closed.
278
+ */
279
+ destroy(): Promise<void> {
280
+ for (const socket of this.#sockets) socket.destroy()
281
+ return new Promise((resolve) => {
282
+ this.#server.close(() => resolve())
283
+ })
284
+ }
285
+
286
+ // A byte after the publish comes from a stage waiter whose connection the allocation left unaccepted.
287
+ #admit(socket: Socket): void {
288
+ this.#sockets.add(socket)
289
+ socket.on('error', () => undefined)
290
+ socket.on('close', () => this.#sockets.delete(socket))
291
+ socket.on('data', () => {
292
+ if (this.#published) socket.destroy()
293
+ })
294
+ }
295
+ }
296
+
297
+ /**
298
+ * Reads the value that follows a flag.
299
+ *
300
+ * @remarks
301
+ * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
302
+ * and the `--flag=value` form is not read.
303
+ *
304
+ * @param argv - The arguments before the bare `--`.
305
+ * @param name - The flag, such as `--label`.
306
+ * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
307
+ * another flag.
308
+ */
309
+ export function readOption(argv: readonly string[], name: string): string | undefined {
310
+ const index = argv.indexOf(name)
311
+ const value = index === -1 ? undefined : argv[index + 1]
312
+ return value === undefined || value.startsWith('--') ? undefined : value
313
+ }
314
+
315
+ /**
316
+ * Names the value flags a caller gave with no value.
317
+ *
318
+ * @param argv - The arguments before the bare `--`.
319
+ * @param names - The flags that take a value.
320
+ * @returns Each named flag that appears last or is followed by another flag, in argument order.
321
+ */
322
+ export function readMissingFlags(
323
+ argv: readonly string[],
324
+ names: readonly string[],
325
+ ): readonly string[] {
326
+ return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
327
+ }
328
+
329
+ /**
330
+ * Names the flags a caller gave that the script does not read.
331
+ *
332
+ * @remarks
333
+ * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
334
+ * scan, so the command after it keeps every argument.
335
+ *
336
+ * @param argv - The arguments after the script path.
337
+ * @param flags - Every flag the script reads, value flags and switches alike.
338
+ * @returns Each argument that opens with `--` and is not a read flag, in argument order.
339
+ */
340
+ export function readUnknownFlags(
341
+ argv: readonly string[],
342
+ flags: readonly string[],
343
+ ): readonly string[] {
344
+ const end = argv.indexOf('--')
345
+ return (end === -1 ? argv : argv.slice(0, end)).filter(
346
+ (argument) => argument.startsWith('--') && !flags.includes(argument),
347
+ )
348
+ }
349
+
350
+ /**
351
+ * Reads the arguments that are neither a flag nor the value of a value flag.
352
+ *
353
+ * @param argv - The arguments before the bare `--`.
354
+ * @param valueFlags - The flags that take a value.
355
+ * @returns The positional arguments in order.
356
+ */
357
+ export function readPositionals(
358
+ argv: readonly string[],
359
+ valueFlags: readonly string[],
360
+ ): readonly string[] {
361
+ return argv.filter(
362
+ (argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''),
363
+ )
364
+ }
365
+
366
+ /**
367
+ * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
368
+ *
369
+ * @param text - The text to quote.
370
+ * @returns The JSON string literal of the text, ending in an ellipsis inside the quotes when cut.
371
+ */
372
+ export function quote(text: string): string {
373
+ return JSON.stringify(text.length > 80 ? `${text.slice(0, 80)}…` : text)
374
+ }
375
+
376
+ /**
377
+ * Reads the system error code a thrown value carries.
378
+ *
379
+ * @param error - The thrown value.
380
+ * @returns The code, or the value's text when it carries none.
381
+ */
382
+ export function readCode(error: unknown): string {
383
+ return error instanceof Error && 'code' in error && typeof error.code === 'string'
384
+ ? error.code
385
+ : String(error)
386
+ }
387
+
388
+ /**
389
+ * Resolves the queue root.
390
+ *
391
+ * @remarks
392
+ * `os.userInfo` reads the account record rather than `HOME`, `USERPROFILE`, or `TEMP`, so every
393
+ * checkout and shell of one account resolves one directory.
394
+ *
395
+ * @param argument - The `--root` value, for a proof.
396
+ * @returns The directory that holds the queue.
397
+ */
398
+ export function resolveRoot(argument?: string): string {
399
+ return argument ?? join(userInfo().homedir, '.orkestrel', 'lane')
400
+ }
401
+
402
+ /**
403
+ * Resolves the sibling launcher from the running file, so a built twin spawns its `.js` sibling.
404
+ *
405
+ * @returns The path of the dispatch skill's `launch` script.
406
+ */
407
+ export function resolveLauncher(): string {
408
+ const self = fileURLToPath(import.meta.url)
409
+ return join(dirname(self), '..', '..', 'orkestrel-dispatch', 'scripts', `launch${extname(self)}`)
410
+ }
411
+
412
+ /**
413
+ * Renders the endpoint a token names.
414
+ *
415
+ * @remarks
416
+ * The form is platform-defined: Windows has named pipes, and any other host takes a socket file
417
+ * under the root. The Windows host closes a pipe with its process, and a socket file outlives its
418
+ * process, so a reclaimer removes it.
419
+ *
420
+ * @param root - The queue root.
421
+ * @param token - The token.
422
+ * @returns The path `net.listen` and `net.connect` take.
423
+ */
424
+ export function renderEndpoint(root: string, token: string): string {
425
+ return process.platform === 'win32'
426
+ ? `\\\\.\\pipe\\orkestrel-lane-${token}`
427
+ : join(root, `${token}${SOCKET_SUFFIX}`)
428
+ }
429
+
430
+ /**
431
+ * Renders the name of a ticket.
432
+ *
433
+ * @param sequence - The ticket's sequence.
434
+ * @returns The file name, at a fixed width.
435
+ */
436
+ export function renderTicketName(sequence: number): string {
437
+ return `${String(sequence).padStart(SEQUENCE_WIDTH, '0')}${TICKET_SUFFIX}`
438
+ }
439
+
440
+ /**
441
+ * Renders the name of a run record.
442
+ *
443
+ * @param sequence - The ticket's sequence.
444
+ * @returns The file name, at a fixed width.
445
+ */
446
+ export function renderRunName(sequence: number): string {
447
+ return `${String(sequence).padStart(SEQUENCE_WIDTH, '0')}${RUN_SUFFIX}`
448
+ }
449
+
450
+ /**
451
+ * Lists a directory's names.
452
+ *
453
+ * @param root - The queue root.
454
+ * @returns The names; empty when the directory is absent.
455
+ */
456
+ export function readNames(root: string): readonly string[] {
457
+ try {
458
+ return readdirSync(root)
459
+ } catch (error) {
460
+ if (readCode(error) === 'ENOENT') return []
461
+ throw error
462
+ }
463
+ }
464
+
465
+ /**
466
+ * Reads the sequences a listing holds.
467
+ *
468
+ * @param names - The directory's names.
469
+ * @returns Each ticket's sequence, in no promised order.
470
+ */
471
+ export function readSequences(names: readonly string[]): readonly number[] {
472
+ return names.flatMap((name) => {
473
+ const match = TICKET_PATTERN.exec(name)
474
+ return match?.[1] === undefined ? [] : [Number(match[1])]
475
+ })
476
+ }
477
+
478
+ /**
479
+ * Checks whether a value is a ticket record.
480
+ *
481
+ * @param value - The parsed JSON value.
482
+ * @returns True when every field has its type and the token has the token's form; false otherwise.
483
+ */
484
+ export function isTicket(value: unknown): value is Ticket {
485
+ return (
486
+ typeof value === 'object' &&
487
+ value !== null &&
488
+ 'protocol' in value &&
489
+ typeof value.protocol === 'number' &&
490
+ 'token' in value &&
491
+ typeof value.token === 'string' &&
492
+ TOKEN_PATTERN.test(value.token) &&
493
+ 'label' in value &&
494
+ typeof value.label === 'string' &&
495
+ 'pid' in value &&
496
+ typeof value.pid === 'number' &&
497
+ 'host' in value &&
498
+ typeof value.host === 'string' &&
499
+ 'platform' in value &&
500
+ typeof value.platform === 'string' &&
501
+ 'cwd' in value &&
502
+ typeof value.cwd === 'string' &&
503
+ 'arrived' in value &&
504
+ typeof value.arrived === 'string'
505
+ )
506
+ }
507
+
508
+ /**
509
+ * Checks whether a value is a run record.
510
+ *
511
+ * @param value - The parsed JSON value.
512
+ * @returns True when `started` is a number and each present id is a number; false otherwise.
513
+ */
514
+ export function isRun(value: unknown): value is Run {
515
+ return (
516
+ typeof value === 'object' &&
517
+ value !== null &&
518
+ 'started' in value &&
519
+ typeof value.started === 'number' &&
520
+ (!('launcher' in value) || typeof value.launcher === 'number') &&
521
+ (!('command' in value) || typeof value.command === 'number')
522
+ )
523
+ }
524
+
525
+ /**
526
+ * Parses text as JSON.
527
+ *
528
+ * @param text - The text.
529
+ * @returns The parsed value, or undefined when the text is not JSON.
530
+ */
531
+ export function parseText(text: string): unknown {
532
+ try {
533
+ const parsed: unknown = JSON.parse(text)
534
+ return parsed
535
+ } catch {
536
+ return undefined
537
+ }
538
+ }
539
+
540
+ /**
541
+ * Reads one queue entry.
542
+ *
543
+ * @param root - The queue root.
544
+ * @param sequence - The ticket's sequence.
545
+ * @returns The entry, its ticket undefined when the file is unreadable or malformed; empty when the
546
+ * ticket is gone.
547
+ */
548
+ export function readEntry(root: string, sequence: number): readonly Entry[] {
549
+ try {
550
+ const parsed = parseText(readFileSync(join(root, renderTicketName(sequence)), 'utf8'))
551
+ return [{ sequence, ticket: isTicket(parsed) ? parsed : undefined }]
552
+ } catch (error) {
553
+ return readCode(error) === 'ENOENT' ? [] : [{ sequence, ticket: undefined }]
554
+ }
555
+ }
556
+
557
+ /**
558
+ * Orders entries by arrival.
559
+ *
560
+ * @param entries - The entries in any order.
561
+ * @returns The entries by ascending sequence, which the exclusive link allocated.
562
+ */
563
+ export function orderEntries(entries: readonly Entry[]): readonly Entry[] {
564
+ return entries.toSorted((left, right) => left.sequence - right.sequence)
565
+ }
566
+
567
+ /**
568
+ * Reads the queue in arrival order.
569
+ *
570
+ * @param root - The queue root.
571
+ * @returns Every ticket that exists when it is read.
572
+ */
573
+ export function readQueue(root: string): readonly Entry[] {
574
+ return orderEntries(
575
+ readSequences(readNames(root)).flatMap((sequence) => readEntry(root, sequence)),
576
+ )
577
+ }
578
+
579
+ /**
580
+ * Reads a run record.
581
+ *
582
+ * @param root - The queue root.
583
+ * @param sequence - The ticket's sequence.
584
+ * @returns The record; `absent` when no record exists; `unread` when it cannot be read as a record.
585
+ */
586
+ export function readRun(root: string, sequence: number): Run | 'absent' | 'unread' {
587
+ try {
588
+ const parsed = parseText(readFileSync(join(root, renderRunName(sequence)), 'utf8'))
589
+ return isRun(parsed)
590
+ ? {
591
+ started: parsed.started,
592
+ launcher: parsed.launcher,
593
+ command: parsed.command,
594
+ }
595
+ : 'unread'
596
+ } catch (error) {
597
+ return readCode(error) === 'ENOENT' ? 'absent' : 'unread'
598
+ }
599
+ }
600
+
601
+ /**
602
+ * Writes a run record.
603
+ *
604
+ * @param root - The queue root.
605
+ * @param sequence - The ticket's sequence.
606
+ * @param run - The record.
607
+ */
608
+ export function writeRun(root: string, sequence: number, run: Run): void {
609
+ writeFileSync(join(root, renderRunName(sequence)), JSON.stringify(run))
610
+ }
611
+
612
+ /**
613
+ * Removes a file inside the removal budget.
614
+ *
615
+ * @param path - The file; a file that is already gone is not an error.
616
+ */
617
+ export function removeFile(path: string): void {
618
+ rmSync(path, { force: true, maxRetries: REMOVAL_RETRIES, retryDelay: REMOVAL_DELAY_MS })
619
+ }
620
+
621
+ /**
622
+ * Builds the ticket of this process.
623
+ *
624
+ * @param token - The process's token.
625
+ * @param label - The run's label.
626
+ * @returns The complete ticket.
627
+ */
628
+ export function buildTicket(token: string, label: string): Ticket {
629
+ return {
630
+ protocol: PROTOCOL,
631
+ token,
632
+ label,
633
+ pid: process.pid,
634
+ host: hostname(),
635
+ platform: process.platform,
636
+ cwd: process.cwd(),
637
+ arrived: new Date().toISOString(),
638
+ }
639
+ }
640
+
641
+ /**
642
+ * Writes the complete ticket to the stage file, which also marks this process as choosing.
643
+ *
644
+ * @param root - The queue root.
645
+ * @param ticket - The ticket.
646
+ */
647
+ export function writeStage(root: string, ticket: Ticket): void {
648
+ writeFileSync(join(root, `${ticket.token}${STAGE_SUFFIX}`), JSON.stringify(ticket))
649
+ }
650
+
651
+ /**
652
+ * Links a file to a name, reporting a name another process took.
653
+ *
654
+ * @param from - The existing file.
655
+ * @param to - The name to take.
656
+ * @returns True when this call took the name; false when the name exists. Thrown when the host
657
+ * refuses the link for any other reason.
658
+ */
659
+ export function tryLink(from: string, to: string): boolean {
660
+ try {
661
+ linkSync(from, to)
662
+ return true
663
+ } catch (error) {
664
+ if (readCode(error) === 'EEXIST') return false
665
+ throw error
666
+ }
667
+ }
668
+
669
+ /**
670
+ * Publishes a stage file as the next ticket in one step.
671
+ *
672
+ * @remarks
673
+ * The sequence comes from a listing and the exclusive link, never from a clock, so tickets in one
674
+ * millisecond cannot tie. A lost link lists again.
675
+ *
676
+ * @param root - The queue root.
677
+ * @param token - The token that names the stage file.
678
+ * @returns The sequence this process took.
679
+ */
680
+ export function linkStage(root: string, token: string): number {
681
+ const sequence = Math.max(0, ...readSequences(readNames(root))) + 1
682
+ return tryLink(join(root, `${token}${STAGE_SUFFIX}`), join(root, renderTicketName(sequence)))
683
+ ? sequence
684
+ : linkStage(root, token)
685
+ }
686
+
687
+ /**
688
+ * Decides what a process with a ticket does next.
689
+ *
690
+ * @remarks
691
+ * The two listings are separate, because one listing can miss both a ticket linked and a stage file
692
+ * removed while it runs. A stage file absent from the first listing belongs to a process whose own
693
+ * listing sees this ticket, or to a ticket the second listing sees.
694
+ *
695
+ * @param root - The queue root.
696
+ * @param sequence - This process's sequence.
697
+ * @param token - This process's token.
698
+ * @returns The holder state, the stage file to wait on, the nearest earlier ticket, or a refusal.
699
+ */
700
+ export function decideTurn(root: string, sequence: number, token: string): Turn {
701
+ const stage = readNames(root).find(
702
+ (name) => name.endsWith(STAGE_SUFFIX) && name !== `${token}${STAGE_SUFFIX}`,
703
+ )
704
+ if (stage !== undefined) return { state: 'staged', name: stage }
705
+ const entries = readQueue(root)
706
+ const position = entries.findIndex((entry) => entry.sequence === sequence)
707
+ if (position === -1) {
708
+ return { state: 'refused', reason: `ticket ${renderTicketName(sequence)} is gone` }
709
+ }
710
+ const lower = entries[position - 1]
711
+ return lower === undefined ? { state: 'holder' } : { state: 'behind', entry: lower }
712
+ }
713
+
714
+ /**
715
+ * Connects to an endpoint and parks until the connection closes.
716
+ *
717
+ * @param endpoint - The endpoint.
718
+ * @param stage - If `true`, writes the one byte a published owner closes the connection on; if
719
+ * `false`, writes nothing.
720
+ * @param parked - Called when the connection is open and the wait starts.
721
+ * @returns The connect failure's code, or undefined after a connection opened and closed.
722
+ */
723
+ export function parkOn(
724
+ endpoint: string,
725
+ stage: boolean,
726
+ parked: () => void,
727
+ ): Promise<string | undefined> {
728
+ return new Promise((resolve) => {
729
+ const socket = connect(endpoint)
730
+ socket.once('error', (error) => resolve(readCode(error)))
731
+ socket.once('connect', () => {
732
+ socket.removeAllListeners('error')
733
+ socket.on('error', () => undefined)
734
+ socket.once('close', () => resolve(undefined))
735
+ socket.resume()
736
+ if (stage) socket.write('s')
737
+ parked()
738
+ })
739
+ })
740
+ }
741
+
742
+ /**
743
+ * Connects to an endpoint and leaves at once.
744
+ *
745
+ * @param endpoint - The endpoint.
746
+ * @returns The connect failure's code, or undefined when the connection opened.
747
+ */
748
+ export function probeEndpoint(endpoint: string): Promise<string | undefined> {
749
+ return new Promise((resolve) => {
750
+ const socket = connect(endpoint)
751
+ socket.once('error', (error) => resolve(readCode(error)))
752
+ socket.once('connect', () => {
753
+ socket.destroy()
754
+ resolve(undefined)
755
+ })
756
+ })
757
+ }
758
+
759
+ /**
760
+ * Checks whether a connect failure means the endpoint's owner is gone.
761
+ *
762
+ * @remarks
763
+ * A token is unique and its endpoint listens before any file names it, so only a refused connect on
764
+ * that name reads as gone. A busy endpoint or any other failure proves nothing.
765
+ *
766
+ * @param code - The connect failure's code.
767
+ * @returns True for `ENOENT` and `ECONNREFUSED`; false otherwise.
768
+ */
769
+ export function isGone(code: string): boolean {
770
+ return code === 'ENOENT' || code === 'ECONNREFUSED'
771
+ }
772
+
773
+ /**
774
+ * Names what makes a ticket unreadable to this process.
775
+ *
776
+ * @param ticket - The ticket.
777
+ * @returns A description of the differing protocol, host, or platform; undefined when it matches.
778
+ */
779
+ export function describeForeign(ticket: Ticket): string | undefined {
780
+ if (ticket.protocol !== PROTOCOL) return `protocol ${String(ticket.protocol)}`
781
+ if (ticket.host !== hostname()) return `host ${quote(ticket.host)}`
782
+ return ticket.platform === process.platform ? undefined : `platform ${quote(ticket.platform)}`
783
+ }
784
+
785
+ /**
786
+ * Parses the snapshot's text.
787
+ *
788
+ * @param text - The snapshot's standard output.
789
+ * @returns One row per line that has the row's form.
790
+ */
791
+ export function parseRows(text: string): readonly Row[] {
792
+ return text.split(/\r\n|\n/u).flatMap((line) => {
793
+ const match = ROW_PATTERN.exec(line.trim())
794
+ return match === null
795
+ ? []
796
+ : [{ pid: Number(match[1]), parent: Number(match[2]), created: Number(match[3]) }]
797
+ })
798
+ }
799
+
800
+ /**
801
+ * Reads one snapshot of the host's processes.
802
+ *
803
+ * @returns The rows, or undefined when the snapshot cannot be read.
804
+ */
805
+ export function readSnapshot(): readonly Row[] | undefined {
806
+ const result = spawnSync(
807
+ 'powershell.exe',
808
+ ['-NoProfile', '-NonInteractive', '-Command', SNAPSHOT_COMMAND],
809
+ { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 },
810
+ )
811
+ const rows = result.status === 0 ? parseRows(result.stdout) : []
812
+ return rows.length === 0 ? undefined : rows
813
+ }
814
+
815
+ /**
816
+ * Selects the rows of one run's process tree from a snapshot.
817
+ *
818
+ * @remarks
819
+ * A seed row inside the bounds is a member. A seed row outside them reused an exited seed's id and
820
+ * is excluded with its children. An exited seed's child keeps the seed's id as its parent, so it
821
+ * counts inside the bounds, and earlier than any row that reused the id. Below that, a row counts
822
+ * when its creation date is no earlier than its parent's. A process whose parent exited and is no
823
+ * seed is outside the reading.
824
+ *
825
+ * @param rows - The snapshot.
826
+ * @param seeds - The launcher id and the command id.
827
+ * @param floor - The earliest creation date a seed's tree can carry.
828
+ * @param ceiling - The latest creation date a row of an exited seed can carry.
829
+ * @returns The members.
830
+ */
831
+ export function selectMembers(
832
+ rows: readonly Row[],
833
+ seeds: readonly number[],
834
+ floor: number,
835
+ ceiling: number,
836
+ ): readonly Row[] {
837
+ const roots = seeds.flatMap((seed) => {
838
+ const own = rows.find((row) => row.pid === seed)
839
+ return own !== undefined && own.created >= floor && own.created <= ceiling
840
+ ? [own]
841
+ : rows.filter(
842
+ (row) =>
843
+ row.parent === seed &&
844
+ row.created >= floor &&
845
+ row.created <= ceiling &&
846
+ (own === undefined || row.created < own.created),
847
+ )
848
+ })
849
+ const members = new Map(roots.map((row) => [row.pid, row]))
850
+ for (const member of members.values()) {
851
+ for (const row of rows) {
852
+ if (row.parent === member.pid && row.created >= member.created && !members.has(row.pid)) {
853
+ members.set(row.pid, row)
854
+ }
855
+ }
856
+ }
857
+ return [...members.values()]
858
+ }
859
+
860
+ /**
861
+ * Reads whether a process group still has a member.
862
+ *
863
+ * @param group - The group id.
864
+ * @returns The group id while the host reports the group; empty when it reports none.
865
+ */
866
+ export function readGroup(group: number): readonly number[] {
867
+ try {
868
+ process.kill(-group, 0)
869
+ return [group]
870
+ } catch (error) {
871
+ return readCode(error) === 'ESRCH' ? [] : [group]
872
+ }
873
+ }
874
+
875
+ /**
876
+ * Reads the members of one run's process tree.
877
+ *
878
+ * @remarks
879
+ * The reading is platform-defined: Windows has no process group a descendant inherits, so it reads
880
+ * parent links, and any other host reads the launcher's group.
881
+ *
882
+ * @param run - The run record.
883
+ * @param ceiling - The latest creation date a row of an exited seed can carry.
884
+ * @returns The ids to kill, or undefined when the tree cannot be read.
885
+ */
886
+ export function readTree(run: Run, ceiling: number): readonly number[] | undefined {
887
+ if (run.launcher === undefined) return undefined
888
+ if (process.platform !== 'win32') return readGroup(run.launcher)
889
+ const rows = readSnapshot()
890
+ return rows === undefined
891
+ ? undefined
892
+ : selectMembers(
893
+ rows,
894
+ run.command === undefined ? [run.launcher] : [run.launcher, run.command],
895
+ run.started - CLOCK_ALLOWANCE_MS,
896
+ ceiling,
897
+ ).map((row) => row.pid)
898
+ }
899
+
900
+ /**
901
+ * Kills each listed member.
902
+ *
903
+ * @remarks
904
+ * The kill is platform-defined: Windows ends a process by id with `taskkill`, whose `/T` ends
905
+ * nothing under a root that exited, so each member takes its own kill. Any other host signals the
906
+ * group, and a pause follows, because no event reports the end of a foreign group.
907
+ *
908
+ * @param members - The ids a reading returned.
909
+ */
910
+ export function killMembers(members: readonly number[]): void {
911
+ for (const member of members) {
912
+ if (process.platform === 'win32') {
913
+ spawnSync('taskkill', ['/pid', String(member), '/T', '/F'], {
914
+ stdio: 'ignore',
915
+ windowsHide: true,
916
+ })
917
+ } else {
918
+ try {
919
+ process.kill(-member, 'SIGKILL')
920
+ } catch {}
921
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, KILL_PAUSE_MS)
922
+ }
923
+ }
924
+ }
925
+
926
+ /**
927
+ * Reads a tree, kills what it lists, and reads again, inside a bounded budget.
928
+ *
929
+ * @param read - Takes one reading; undefined means the tree cannot be read.
930
+ * @param kill - Kills what a reading listed.
931
+ * @param budget - The kills left.
932
+ * @returns Gone only after a reading lists no member; otherwise the members the last reading listed.
933
+ */
934
+ export function sweepTree(
935
+ read: () => readonly number[] | undefined,
936
+ kill: (members: readonly number[]) => void,
937
+ budget: number,
938
+ ): Sweep {
939
+ const members = read()
940
+ if (members === undefined) return { gone: false, members: [] }
941
+ if (members.length === 0) return { gone: true, members }
942
+ if (budget <= 0) return { gone: false, members }
943
+ kill(members)
944
+ return sweepTree(read, kill, budget - 1)
945
+ }
946
+
947
+ /**
948
+ * Reclaims the ticket of an owner whose endpoint refused a connect.
949
+ *
950
+ * @remarks
951
+ * A reclaimer never kills, because the parallel skill forbids ending another session's process.
952
+ *
953
+ * @param root - The queue root.
954
+ * @param sequence - The dead ticket's sequence.
955
+ * @param ticket - The dead ticket.
956
+ * @returns The refusal when the owner's tree reads as present or cannot be identified; undefined
957
+ * after the ticket and its files are removed.
958
+ */
959
+ export function reclaimTicket(root: string, sequence: number, ticket: Ticket): string | undefined {
960
+ const run = readRun(root, sequence)
961
+ const files = `${renderTicketName(sequence)} and ${renderRunName(sequence)} under ${root}`
962
+ if (run === 'unread' || (run !== 'absent' && run.launcher === undefined)) {
963
+ return `the owner of ${quote(ticket.label)} (pid ${String(ticket.pid)}) ended before its tree could be identified; end its tree, then delete ${files}`
964
+ }
965
+ if (run !== 'absent') {
966
+ const members = readTree(run, Date.now())
967
+ if (members === undefined || members.length > 0) {
968
+ return `the owner of ${quote(ticket.label)} (pid ${String(ticket.pid)}) is gone and its tree reads as ${members === undefined ? 'unread' : `present: ${members.join(', ')}`}; launcher ${String(run.launcher)}, command ${String(run.command)}, files ${files}`
969
+ }
970
+ removeFile(join(root, renderRunName(sequence)))
971
+ }
972
+ removeFile(join(root, renderTicketName(sequence)))
973
+ removeFile(join(root, `${ticket.token}${SOCKET_SUFFIX}`))
974
+ return undefined
975
+ }
976
+
977
+ /**
978
+ * Waits on one stage file and removes it when its owner is gone.
979
+ *
980
+ * @param root - The queue root.
981
+ * @param name - The stage file's name.
982
+ * @returns The refusal, or undefined when the stage ended.
983
+ */
984
+ export async function waitOnStage(root: string, name: string): Promise<string | undefined> {
985
+ const token = name.slice(0, -STAGE_SUFFIX.length)
986
+ if (!TOKEN_PATTERN.test(token)) return `stage file ${quote(name)} under ${root} names no token`
987
+ const code = await parkOn(renderEndpoint(root, token), true, () =>
988
+ console.error('lane: waiting behind an arrival'),
989
+ )
990
+ if (code === undefined) return undefined
991
+ if (!isGone(code)) return `the endpoint of ${quote(name)} reported ${code}`
992
+ removeFile(join(root, name))
993
+ removeFile(join(root, `${token}${SOCKET_SUFFIX}`))
994
+ return undefined
995
+ }
996
+
997
+ /**
998
+ * Waits on the nearest earlier ticket and reclaims it when its owner is gone.
999
+ *
1000
+ * @param root - The queue root.
1001
+ * @param entry - The earlier ticket.
1002
+ * @param announced - The token this process last printed a waiting line for.
1003
+ * @returns The refusal, or undefined when the wait ended.
1004
+ */
1005
+ export async function waitOnTicket(
1006
+ root: string,
1007
+ entry: Entry,
1008
+ announced: string | undefined,
1009
+ ): Promise<string | undefined> {
1010
+ const name = renderTicketName(entry.sequence)
1011
+ const ticket = entry.ticket
1012
+ if (ticket === undefined) return `ticket ${name} under ${root} cannot be read`
1013
+ const foreign = describeForeign(ticket)
1014
+ if (foreign !== undefined) return `ticket ${name} under ${root} carries ${foreign}`
1015
+ const code = await parkOn(renderEndpoint(root, ticket.token), false, () => {
1016
+ if (announced !== ticket.token) console.error(`lane: waiting behind ${quote(ticket.label)}`)
1017
+ })
1018
+ if (code === undefined) return undefined
1019
+ return isGone(code)
1020
+ ? reclaimTicket(root, entry.sequence, ticket)
1021
+ : `the endpoint of ticket ${name} reported ${code}`
1022
+ }
1023
+
1024
+ /**
1025
+ * Waits for this process's turn, parked on events with no timer.
1026
+ *
1027
+ * @param root - The queue root.
1028
+ * @param sequence - This process's sequence.
1029
+ * @param token - This process's token.
1030
+ * @param announced - The token this process last printed a waiting line for.
1031
+ * @returns The refusal, or undefined when this process holds the lane.
1032
+ */
1033
+ export async function waitForTurn(
1034
+ root: string,
1035
+ sequence: number,
1036
+ token: string,
1037
+ announced?: string,
1038
+ ): Promise<string | undefined> {
1039
+ const turn = decideTurn(root, sequence, token)
1040
+ if (turn.state === 'holder') return undefined
1041
+ if (turn.state === 'refused') return turn.reason
1042
+ const refusal =
1043
+ turn.state === 'staged'
1044
+ ? await waitOnStage(root, turn.name)
1045
+ : await waitOnTicket(root, turn.entry, announced)
1046
+ if (refusal !== undefined) return refusal
1047
+ return waitForTurn(
1048
+ root,
1049
+ sequence,
1050
+ token,
1051
+ turn.state === 'behind' ? turn.entry.ticket?.token : announced,
1052
+ )
1053
+ }
1054
+
1055
+ /**
1056
+ * Reads the command id from a launcher line.
1057
+ *
1058
+ * @param line - One line of the launcher's stdout.
1059
+ * @returns The pid of the spawn line; undefined for any other line.
1060
+ */
1061
+ export function readCommandId(line: string): number | undefined {
1062
+ const parsed = parseText(line)
1063
+ return typeof parsed === 'object' &&
1064
+ parsed !== null &&
1065
+ 'pid' in parsed &&
1066
+ typeof parsed.pid === 'number' &&
1067
+ !('exit' in parsed)
1068
+ ? parsed.pid
1069
+ : undefined
1070
+ }
1071
+
1072
+ /**
1073
+ * Registers a handler on every stop signal, on a host that delivers them.
1074
+ *
1075
+ * @remarks
1076
+ * Windows runs no signal handler for a forced kill, so an ended lane process there is the reclaim
1077
+ * case.
1078
+ *
1079
+ * @param handler - The handler.
1080
+ * @returns The call that removes the handler.
1081
+ */
1082
+ export function watchSignals(handler: () => void): () => void {
1083
+ if (process.platform === 'win32') return () => undefined
1084
+ for (const signal of STOP_SIGNALS) process.on(signal, handler)
1085
+ return () => {
1086
+ for (const signal of STOP_SIGNALS) process.removeListener(signal, handler)
1087
+ }
1088
+ }
1089
+
1090
+ /**
1091
+ * Starts the sibling launcher.
1092
+ *
1093
+ * @remarks
1094
+ * A host other than Windows starts it as a group leader, so the launcher's id is the group a
1095
+ * handover reads.
1096
+ *
1097
+ * @param launcher - The launcher's path.
1098
+ * @param options - The run.
1099
+ * @returns The started launcher.
1100
+ */
1101
+ export function startLauncher(launcher: string, options: LaneOptions): ChildProcess {
1102
+ return spawn(
1103
+ process.execPath,
1104
+ [
1105
+ launcher,
1106
+ '--journal',
1107
+ options.journal,
1108
+ '--errors',
1109
+ options.errors,
1110
+ '--cap',
1111
+ String(options.cap),
1112
+ '--',
1113
+ ...options.command,
1114
+ ],
1115
+ {
1116
+ stdio: ['ignore', 'pipe', 'inherit'],
1117
+ windowsHide: true,
1118
+ detached: process.platform !== 'win32',
1119
+ },
1120
+ )
1121
+ }
1122
+
1123
+ /**
1124
+ * Waits for a started launcher to close.
1125
+ *
1126
+ * @param child - The started launcher.
1127
+ * @returns Its exit code, or undefined when a signal ended it or it could not start.
1128
+ */
1129
+ export function waitForClose(child: ChildProcess): Promise<number | undefined> {
1130
+ return new Promise((resolve) => {
1131
+ child.once('error', () => resolve(undefined))
1132
+ child.once('close', (code) => resolve(code ?? undefined))
1133
+ })
1134
+ }
1135
+
1136
+ /**
1137
+ * Writes a run record, leaving an unwritten id to the handover reading.
1138
+ *
1139
+ * @param root - The queue root.
1140
+ * @param sequence - The ticket's sequence.
1141
+ * @param run - The record.
1142
+ * @returns True when the record was written; false otherwise.
1143
+ */
1144
+ export function tryWriteRun(root: string, sequence: number, run: Run): boolean {
1145
+ try {
1146
+ writeRun(root, sequence, run)
1147
+ return true
1148
+ } catch {
1149
+ return false
1150
+ }
1151
+ }
1152
+
1153
+ /**
1154
+ * Removes a holder's run record and ticket.
1155
+ *
1156
+ * @param root - The queue root.
1157
+ * @param sequence - The ticket's sequence.
1158
+ * @returns The host's refusal when the removal budget ended; undefined after both are gone.
1159
+ */
1160
+ export function releaseTicket(root: string, sequence: number): string | undefined {
1161
+ try {
1162
+ removeFile(join(root, renderRunName(sequence)))
1163
+ removeFile(join(root, renderTicketName(sequence)))
1164
+ return undefined
1165
+ } catch (error) {
1166
+ return readCode(error)
1167
+ }
1168
+ }
1169
+
1170
+ /**
1171
+ * Runs the command as the holder, reads the tree at handover, and releases.
1172
+ *
1173
+ * @param options - The run.
1174
+ * @param launcher - The launcher's path.
1175
+ * @param sequence - This process's sequence.
1176
+ * @returns The launcher's code; 1 when a signal ended it; 70 when the tree still reads as present or
1177
+ * the ticket could not be removed; 75 when the launcher could not start.
1178
+ */
1179
+ export async function runHolder(
1180
+ options: LaneOptions,
1181
+ launcher: string,
1182
+ sequence: number,
1183
+ ): Promise<number> {
1184
+ const { root } = options
1185
+ const started = Date.now()
1186
+ writeRun(root, sequence, { started, launcher: undefined, command: undefined })
1187
+ const child = startLauncher(launcher, options)
1188
+ const id = child.pid
1189
+ if (id === undefined) {
1190
+ releaseTicket(root, sequence)
1191
+ console.error(`lane: ${quote(launcher)} could not start`)
1192
+ return 75
1193
+ }
1194
+ tryWriteRun(root, sequence, { started, launcher: id, command: undefined })
1195
+ const unwatch = watchSignals(() => killMembers([id]))
1196
+ const closed = waitForClose(child)
1197
+ if (child.stdout !== null) {
1198
+ const lines = createInterface({ input: child.stdout, crlfDelay: Infinity })
1199
+ lines.on('error', () => undefined)
1200
+ lines.on('line', (line) => {
1201
+ console.log(line)
1202
+ const command = readCommandId(line)
1203
+ if (command !== undefined) tryWriteRun(root, sequence, { started, launcher: id, command })
1204
+ })
1205
+ }
1206
+ const code = await closed
1207
+ unwatch()
1208
+ const ended = Date.now()
1209
+ const run = readRun(root, sequence)
1210
+ const sweep =
1211
+ run === 'absent' || run === 'unread'
1212
+ ? { gone: false, members: [] }
1213
+ : sweepTree(() => readTree(run, ended), killMembers, KILL_BUDGET)
1214
+ if (!sweep.gone) {
1215
+ console.error(
1216
+ `lane: the tree of ${quote(options.label)} still reads as ${sweep.members.length === 0 ? 'unread' : `present: ${sweep.members.join(', ')}`}; the lane stays held by ${renderTicketName(sequence)} and ${renderRunName(sequence)} under ${root}`,
1217
+ )
1218
+ return 70
1219
+ }
1220
+ const refusal = releaseTicket(root, sequence)
1221
+ if (refusal !== undefined) {
1222
+ console.error(`lane: removing ${renderTicketName(sequence)} reported ${refusal}`)
1223
+ return 70
1224
+ }
1225
+ return code ?? 1
1226
+ }
1227
+
1228
+ /**
1229
+ * Takes a ticket, waits for this process's turn, and runs the command.
1230
+ *
1231
+ * @param options - The run.
1232
+ * @param launcher - The launcher's path.
1233
+ * @param tokenId - This process's token.
1234
+ * @param token - This process's listening endpoint.
1235
+ * @returns The exit code.
1236
+ */
1237
+ export async function enterLane(
1238
+ options: LaneOptions,
1239
+ launcher: string,
1240
+ tokenId: string,
1241
+ token: Token,
1242
+ ): Promise<number> {
1243
+ const { root } = options
1244
+ try {
1245
+ mkdirSync(root, { recursive: true })
1246
+ await token.listen(renderEndpoint(root, tokenId))
1247
+ writeStage(root, buildTicket(tokenId, options.label))
1248
+ const sequence = linkStage(root, tokenId)
1249
+ removeFile(join(root, `${tokenId}${STAGE_SUFFIX}`))
1250
+ token.publish()
1251
+ const unwatch = watchSignals(() => {
1252
+ removeFile(join(root, renderTicketName(sequence)))
1253
+ removeFile(renderEndpoint(root, tokenId))
1254
+ process.exit(75)
1255
+ })
1256
+ const refusal = await waitForTurn(root, sequence, tokenId)
1257
+ unwatch()
1258
+ if (refusal === undefined) return await runHolder(options, launcher, sequence)
1259
+ removeFile(join(root, renderTicketName(sequence)))
1260
+ console.error(`lane: ${refusal}`)
1261
+ return 75
1262
+ } catch (error) {
1263
+ console.error(`lane: the queue under ${root} refused the run: ${String(error)}`)
1264
+ return 75
1265
+ }
1266
+ }
1267
+
1268
+ /**
1269
+ * Runs one validated command on the lane.
1270
+ *
1271
+ * @param options - The run.
1272
+ * @returns The exit code.
1273
+ */
1274
+ export async function runLane(options: LaneOptions): Promise<number> {
1275
+ const launcher = resolveLauncher()
1276
+ if (!existsSync(launcher)) {
1277
+ console.error(`lane: the launcher ${quote(launcher)} does not exist`)
1278
+ return 75
1279
+ }
1280
+ const token = new Token()
1281
+ const code = await enterLane(options, launcher, randomUUID(), token)
1282
+ await token.destroy()
1283
+ return code
1284
+ }
1285
+
1286
+ /**
1287
+ * Reads one ticket's state for `--status`, connecting to its endpoint and writing nothing.
1288
+ *
1289
+ * @param root - The queue root.
1290
+ * @param entry - The ticket.
1291
+ * @returns The ticket's row.
1292
+ */
1293
+ export async function readStatusRow(root: string, entry: Entry): Promise<StatusRow> {
1294
+ const ticket = entry.ticket
1295
+ const fields = { sequence: entry.sequence, label: ticket?.label, pid: ticket?.pid }
1296
+ if (ticket === undefined || describeForeign(ticket) !== undefined) {
1297
+ return { ...fields, state: 'unread' }
1298
+ }
1299
+ const code = await probeEndpoint(renderEndpoint(root, ticket.token))
1300
+ if (code === undefined) return { ...fields, state: 'live' }
1301
+ return { ...fields, state: isGone(code) ? 'dead' : 'unread' }
1302
+ }
1303
+
1304
+ /**
1305
+ * Reads the queue for `--status`.
1306
+ *
1307
+ * @param root - The queue root.
1308
+ * @returns Every ticket in arrival order, and the earliest live ticket with a run record.
1309
+ */
1310
+ export async function readStatus(root: string): Promise<Status> {
1311
+ const tickets = await Promise.all(readQueue(root).map((entry) => readStatusRow(root, entry)))
1312
+ return {
1313
+ tickets,
1314
+ holder: tickets.find(
1315
+ (row) => row.state === 'live' && existsSync(join(root, renderRunName(row.sequence))),
1316
+ ),
1317
+ }
1318
+ }
1319
+
1320
+ /**
1321
+ * Renders the queue as text.
1322
+ *
1323
+ * @param status - What `--status` read.
1324
+ * @returns One line for the holder and one per ticket, in arrival order.
1325
+ */
1326
+ export function renderStatus(status: Status): string {
1327
+ return [
1328
+ `holder: ${status.holder === undefined ? 'none' : quote(status.holder.label ?? 'unread')}`,
1329
+ ...status.tickets.map(
1330
+ (row) =>
1331
+ `${renderTicketName(row.sequence)} ${row.state} ${quote(row.label ?? 'unread')} pid ${String(row.pid)}`,
1332
+ ),
1333
+ ].join('\n')
1334
+ }
1335
+
1336
+ /**
1337
+ * Prints the queue, writing nothing under the root.
1338
+ *
1339
+ * @param root - The queue root.
1340
+ * @param json - If `true`, prints JSON; if `false`, prints text.
1341
+ * @returns 0 on a read; 75 when the root cannot be listed.
1342
+ */
1343
+ export async function runStatus(root: string, json: boolean): Promise<number> {
1344
+ try {
1345
+ const status = await readStatus(root)
1346
+ console.log(json ? JSON.stringify(status) : renderStatus(status))
1347
+ return 0
1348
+ } catch (error) {
1349
+ console.error(`lane: the queue under ${root} cannot be read: ${readCode(error)}`)
1350
+ return 75
1351
+ }
1352
+ }
1353
+
1354
+ /**
1355
+ * Validates a run's arguments.
1356
+ *
1357
+ * @param own - The arguments before the bare `--`.
1358
+ * @param command - The arguments after the bare `--`.
1359
+ * @returns The run, or undefined when a flag or the command is missing or out of range.
1360
+ */
1361
+ export function readLaneOptions(
1362
+ own: readonly string[],
1363
+ command: readonly string[],
1364
+ ): LaneOptions | undefined {
1365
+ const label = readOption(own, '--label')
1366
+ const journal = readOption(own, '--journal')
1367
+ const errors = readOption(own, '--errors')
1368
+ const cap = Number(readOption(own, '--cap') ?? Number.NaN)
1369
+ if (
1370
+ label === undefined ||
1371
+ label === '' ||
1372
+ journal === undefined ||
1373
+ errors === undefined ||
1374
+ journal === errors ||
1375
+ !Number.isFinite(cap) ||
1376
+ cap <= 0 ||
1377
+ cap > MAX_CAP_SECONDS ||
1378
+ command[0] === undefined ||
1379
+ command[0] === ''
1380
+ ) {
1381
+ return undefined
1382
+ }
1383
+ return { root: resolveRoot(readOption(own, '--root')), label, journal, errors, cap, command }
1384
+ }
1385
+
1386
+ /**
1387
+ * Runs the script on its arguments.
1388
+ *
1389
+ * @remarks
1390
+ * Every usage fault returns before a ticket exists, so none surfaces after a wait.
1391
+ *
1392
+ * @param argv - The arguments after the script path.
1393
+ * @returns The exit code the opening comment names.
1394
+ */
1395
+ export async function main(argv: readonly string[]): Promise<number> {
1396
+ const end = argv.indexOf('--')
1397
+ const own = end === -1 ? argv : argv.slice(0, end)
1398
+ const command = end === -1 ? [] : argv.slice(end + 1)
1399
+ const unknown = readUnknownFlags(argv, FLAGS)
1400
+ if (unknown.length > 0) {
1401
+ console.error(`lane: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
1402
+ return 64
1403
+ }
1404
+ const missing = readMissingFlags(own, VALUE_FLAGS)
1405
+ if (missing.length > 0) {
1406
+ console.error(`lane: ${missing.join(', ')} given with no value; ${USAGE}`)
1407
+ return 64
1408
+ }
1409
+ if (readPositionals(own, VALUE_FLAGS).length > 0) {
1410
+ console.error(USAGE)
1411
+ return 64
1412
+ }
1413
+ const status = own.includes('--status')
1414
+ if (status) {
1415
+ if (end !== -1 || RUN_FLAGS.some((flag) => own.includes(flag))) {
1416
+ console.error(`lane: --status and a run are two modes; ${USAGE}`)
1417
+ return 64
1418
+ }
1419
+ return runStatus(resolveRoot(readOption(own, '--root')), own.includes('--json'))
1420
+ }
1421
+ const options = own.includes('--json') ? undefined : readLaneOptions(own, command)
1422
+ if (options === undefined) {
1423
+ console.error(USAGE)
1424
+ return 64
1425
+ }
1426
+ return runLane(options)
1427
+ }
1428
+
1429
+ if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
1430
+ main(process.argv.slice(2)).then((code) => {
1431
+ process.exitCode = code
1432
+ })
1433
+ }