@orkestrel/scaffold 0.0.133 → 0.0.135

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 (92) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +61 -96
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
  3. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
  4. package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
  5. package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
  6. package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
  7. package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
  8. package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
  9. package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
  10. package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
  11. package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
  12. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
  13. package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
  14. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
  15. package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
  16. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1568 -213
  17. package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
  18. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
  19. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
  20. package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
  21. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +387 -109
  22. package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
  23. package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
  24. package/dist/bin/main.js +275 -33
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/AGENTS.md +1 -1
  27. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
  28. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
  29. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
  30. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
  31. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
  32. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
  33. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
  34. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
  35. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
  36. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
  37. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
  38. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
  39. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
  40. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
  41. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
  42. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
  43. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
  44. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
  45. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1990 -274
  46. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  47. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +28 -7
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  52. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +483 -127
  53. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  54. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  55. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  56. package/dist/host/claude/agents/orkestrel.md +16 -16
  57. package/dist/host/claude/rules/architecture.md +1 -1
  58. package/dist/host/claude/rules/documentation.md +1 -1
  59. package/dist/host/claude/rules/patterns.md +7 -4
  60. package/dist/host/claude/rules/styles.md +1 -1
  61. package/dist/host/claude/rules/tests.md +3 -3
  62. package/dist/host/claude/rules/workspace.md +50 -37
  63. package/dist/host/configs/helpers.ts +117 -71
  64. package/dist/host/dotfiles/oxlintrc.json +6 -0
  65. package/dist/host/guides/agent.md +989 -395
  66. package/dist/host/guides/database.md +357 -342
  67. package/dist/host/guides/form.md +79 -4
  68. package/dist/host/guides/middleware.md +5 -5
  69. package/dist/host/guides/ollama.md +41 -42
  70. package/dist/host/guides/scaffold.md +170 -70
  71. package/dist/host/guides/study.md +12 -12
  72. package/dist/host/guides/table.md +20 -6
  73. package/dist/host/guides/test.md +166 -52
  74. package/dist/host/guides/toolbox.md +127 -81
  75. package/dist/host/guides/workspace.md +21 -14
  76. package/dist/host/manifest.json +54 -54
  77. package/dist/host/tests/config.test.ts +251 -7
  78. package/dist/host/tests/policy.test.ts +14 -21
  79. package/dist/host/tests/setupPolicy.ts +43 -36
  80. package/dist/src/core/index.cjs +533 -139
  81. package/dist/src/core/index.cjs.map +1 -1
  82. package/dist/src/core/index.d.cts +223 -16
  83. package/dist/src/core/index.d.ts +223 -16
  84. package/dist/src/core/index.js +524 -139
  85. package/dist/src/core/index.js.map +1 -1
  86. package/dist/src/server/index.cjs +23 -14
  87. package/dist/src/server/index.cjs.map +1 -1
  88. package/dist/src/server/index.d.cts +3 -2
  89. package/dist/src/server/index.d.ts +3 -2
  90. package/dist/src/server/index.js +24 -15
  91. package/dist/src/server/index.js.map +1 -1
  92. package/package.json +2 -2
@@ -1,31 +1,56 @@
1
1
  import { spawn, spawnSync } from 'node:child_process';
2
- import { randomUUID } from 'node:crypto';
3
- import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
2
+ import { createHash, randomUUID } from 'node:crypto';
3
+ import { once } from 'node:events';
4
+ import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
4
5
  import { connect, createServer } from 'node:net';
5
- import { hostname, userInfo } from 'node:os';
6
- import { dirname, extname, join } from 'node:path';
6
+ import { constants, hostname, setPriority, userInfo } from 'node:os';
7
+ import { basename, dirname, extname, isAbsolute, join, resolve as resolvePath, sep, } from 'node:path';
7
8
  import { createInterface } from 'node:readline';
8
9
  import { fileURLToPath } from 'node:url';
10
+ import { parseArgs } from 'node:util';
9
11
  /** Holds the protocol version a ticket carries, so a process refuses a ticket it cannot read. */
10
12
  export const PROTOCOL = 1;
11
- /** Lists the flags that take a value. */
12
- export const VALUE_FLAGS = [
13
- '--label',
14
- '--journal',
15
- '--errors',
16
- '--cap',
17
- '--root',
18
- ];
19
- /** Lists the flags only a run reads, which `--status` refuses. */
20
- export const RUN_FLAGS = ['--label', '--journal', '--errors', '--cap'];
21
- /** Lists every flag the script reads, value flags and switches alike. */
22
- export const FLAGS = [...VALUE_FLAGS, '--status', '--json'];
13
+ /** Lists the flags only a run reads, which `--status` refuses, by the name `parseArgs` reads them under. */
14
+ export const RUN_OPTIONS = ['label', 'journal', 'errors', 'cap', 'solo'];
23
15
  /** Holds the usage line printed on a usage refusal. */
24
- export const USAGE = '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';
16
+ export const USAGE = 'usage: lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] [--solo] -- 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';
17
+ /** Declares every flag the script reads, for `parseArgs`. */
18
+ export const OPTIONS = Object.freeze({
19
+ label: Object.freeze({ type: 'string' }),
20
+ journal: Object.freeze({ type: 'string' }),
21
+ errors: Object.freeze({ type: 'string' }),
22
+ cap: Object.freeze({ type: 'string' }),
23
+ root: Object.freeze({ type: 'string' }),
24
+ status: Object.freeze({ type: 'boolean' }),
25
+ json: Object.freeze({ type: 'boolean' }),
26
+ solo: Object.freeze({ type: 'boolean' }),
27
+ });
28
+ /**
29
+ * Parses the arguments in strict mode against `OPTIONS`.
30
+ *
31
+ * @param argv - The arguments after the script path.
32
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
33
+ */
34
+ export function parseArguments(argv) {
35
+ try {
36
+ const { values, positionals } = parseArgs({
37
+ args: [...argv],
38
+ options: OPTIONS,
39
+ strict: true,
40
+ allowPositionals: false,
41
+ });
42
+ return { success: true, value: { values, positionals } };
43
+ }
44
+ catch (error) {
45
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
46
+ }
47
+ }
25
48
  /** Holds the longest cap in whole seconds, equal to the limit of the sibling launcher. */
26
49
  export const MAX_CAP_SECONDS = 2_147_483;
27
50
  /** Holds the digit count of a ticket name, which keeps a directory listing readable in order. */
28
51
  export const SEQUENCE_WIDTH = 12;
52
+ /** Holds the byte a light waiter writes to an earlier light ticket that does not hold yet. */
53
+ export const HOLD_BYTE = 'h';
29
54
  /** Holds the name ending of a stage file. */
30
55
  export const STAGE_SUFFIX = '.stage';
31
56
  /** Holds the name ending of a ticket. */
@@ -71,6 +96,174 @@ export const REMOVAL_RETRIES = 10;
71
96
  export const REMOVAL_DELAY_MS = 100;
72
97
  /** Holds the PowerShell text that prints one row per process with a creation date. */
73
98
  export const SNAPSHOT_COMMAND = "Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate | Where-Object { $_.CreationDate } | ForEach-Object { '{0} {1} {2}' -f $_.ProcessId, $_.ParentProcessId, ([DateTimeOffset]$_.CreationDate).ToUnixTimeMilliseconds() }";
99
+ /** Holds the name of the file under the root that holds the light lanes' limits. */
100
+ export const LIMITS_FILE = 'limits.json';
101
+ /** Holds the name of the directory under the root that holds each command's run records. */
102
+ export const HISTORY_DIRECTORY = 'history';
103
+ /** Holds the name ending of a run record under the history directory. */
104
+ export const OUTCOME_SUFFIX = '.json';
105
+ /** Holds the digit count of the end time that opens a record's name, which keeps a listing in time order. */
106
+ export const ENDED_WIDTH = 15;
107
+ /** Holds the count of latest records the light reading takes, which is also the count each key keeps. */
108
+ export const RECENT_RUNS = 3;
109
+ /** Holds the age in milliseconds past which a history key is pruned. */
110
+ export const HISTORY_AGE_MS = 7 * 24 * 60 * 60 * 1000;
111
+ /** Holds the count of history keys kept, the latest by their newest record. */
112
+ export const HISTORY_KEYS = 512;
113
+ /**
114
+ * Holds the longest wait in milliseconds for a sampler to ready before its holder starts the command
115
+ * unmeasured.
116
+ *
117
+ * @remarks
118
+ * The wait outlasts a sampler's start on a loaded host, and it bounds what a sampler that neither
119
+ * readies nor exits costs the lane.
120
+ */
121
+ export const READY_MS = 5000;
122
+ /**
123
+ * Holds the longest wait in milliseconds for a sampler's handover sample and for its exit after its
124
+ * stdin closes.
125
+ *
126
+ * @remarks
127
+ * A warm process query answered in about 140 ms on the Windows host measured 2026-11-12, so the wait
128
+ * outlasts a query on a loaded host, and it bounds what a sampler that hangs after it readied costs
129
+ * the lane at handover.
130
+ */
131
+ export const HANDOVER_MS = 5000;
132
+ /** Holds the pause in milliseconds between two samples of a holder's tree. */
133
+ export const SAMPLE_MS = 1000;
134
+ /** Holds the exit code of a light run its holder ended at a threshold. */
135
+ export const BREACH_CODE = 69;
136
+ /** Holds the exit code of a run whose tree still reads as present at handover. */
137
+ export const HELD_CODE = 70;
138
+ /** Holds the launcher's exit code at the cap. */
139
+ export const CAPPED_CODE = 124;
140
+ /** Lists the words that seed a command heavy: a journey, a study, a capture, a live-service run, and a release chain. */
141
+ export const HEAVY_WORDS = [
142
+ 'journey',
143
+ 'journeys',
144
+ 'study',
145
+ 'studies',
146
+ 'capture',
147
+ 'captures',
148
+ 'live',
149
+ 'prepublishonly',
150
+ ];
151
+ /** Lists the package-manager verbs that seed a command heavy: an install, a full suite, and a publish. */
152
+ export const HEAVY_VERBS = [
153
+ 'ci',
154
+ 'i',
155
+ 'install',
156
+ 'add',
157
+ 'update',
158
+ 'rebuild',
159
+ 'uninstall',
160
+ 'publish',
161
+ 'test',
162
+ 't',
163
+ ];
164
+ /**
165
+ * Lists the package scripts a seed reads heavy: the full suite, the aggregates that build and run
166
+ * several projects, the pack-and-install suite, the live-service suite, and the benchmark run.
167
+ */
168
+ export const HEAVY_SCRIPTS = [
169
+ 'test',
170
+ 'test:src',
171
+ 'test:app',
172
+ 'test:distribution',
173
+ 'test:service',
174
+ 'test:bench',
175
+ ];
176
+ /** Lists the Vitest projects a seed reads heavy: the pack-and-install project and the live-service project. */
177
+ export const HEAVY_PROJECTS = ['distribution', 'service'];
178
+ /** Matches a browser face's Vitest project, whose whole run a seed reads heavy: `src:browser`, `app:vue`. */
179
+ export const BROWSER_PROJECT = /(?:^|:)(?:browser|vue)$/u;
180
+ /** Matches a dotted flag such as `--outputFile.json`, whose separate value a seed skips. */
181
+ export const DOTTED_FLAG = /^--[^=.]+\.[^=]+$/u;
182
+ /** Lists the package managers whose verbs and scripts a seed reads. */
183
+ export const MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
184
+ /** Lists the package-manager verbs that run a tool, which a seed reads through to the tool. */
185
+ export const EXEC_VERBS = ['exec', 'x', 'dlx'];
186
+ /** Lists, by tool, the exec flags that take a separate value, so a seed reads no flag value as the tool. */
187
+ export const EXEC_VALUE_FLAGS = Object.freeze({
188
+ npm: Object.freeze(['--package', '-p', '--workspace', '-w']),
189
+ npx: Object.freeze(['--package', '-p', '--workspace', '-w']),
190
+ pnpm: Object.freeze(['--package']),
191
+ pnpx: Object.freeze(['--package']),
192
+ yarn: Object.freeze(['--package']),
193
+ bun: Object.freeze(['--package']),
194
+ bunx: Object.freeze(['--package']),
195
+ });
196
+ /**
197
+ * Lists, by package manager, the flags before the verb that take a separate value, so a seed reads no
198
+ * flag value as the verb.
199
+ *
200
+ * @remarks
201
+ * npm's `-w` names a workspace and takes a value; pnpm's `-w` is the boolean `--workspace-root`.
202
+ */
203
+ export const MANAGER_VALUE_FLAGS = Object.freeze({
204
+ npm: Object.freeze(['--prefix', '--workspace', '-w']),
205
+ pnpm: Object.freeze(['--dir', '-C', '--filter', '-F']),
206
+ yarn: Object.freeze(['--cwd']),
207
+ bun: Object.freeze(['--cwd']),
208
+ });
209
+ /** Lists the tools that run another tool the way `npx` does. */
210
+ export const NPX_TOOLS = ['npx', 'pnpx', 'bunx'];
211
+ /** Lists the `npm exec` and `npx` flags that run inline shell text, which names no tool a seed reads. */
212
+ export const EXEC_INLINE_FLAGS = ['-c', '--call'];
213
+ /** Holds the tool name of the falsify skill's `mutate` script, whose run a seed reads by its wrapped command. */
214
+ export const MUTATION_TOOL = 'mutate';
215
+ /** Holds the `mutate` flag that names the edits file, which a run's key leaves out. */
216
+ export const MUTATION_FLAG = '--edits';
217
+ /** Holds the `mutate` flag that writes saved originals back, which edits source and wraps no command. */
218
+ export const RESTORE_FLAG = '--restore';
219
+ /** Lists the tools a seed reads heavy by name: the release chain's step runner. */
220
+ export const HEAVY_TOOLS = ['steps'];
221
+ /** Lists the Vitest flags that take a separate value, so a seed reads no flag value as a file. */
222
+ export const VITEST_VALUE_FLAGS = [
223
+ '--config',
224
+ '-c',
225
+ '--project',
226
+ '--reporter',
227
+ '--mode',
228
+ '--root',
229
+ '-r',
230
+ '--dir',
231
+ '--outputFile',
232
+ '--pool',
233
+ '--environment',
234
+ '--shard',
235
+ '--testNamePattern',
236
+ '-t',
237
+ '--bail',
238
+ '--retry',
239
+ '--maxWorkers',
240
+ '--minWorkers',
241
+ '--testTimeout',
242
+ '--hookTimeout',
243
+ '--exclude',
244
+ '--include',
245
+ ];
246
+ /** Matches a package script that runs a type check: `check`, `typecheck`, `check:<scope>`, or `<tool>:check`. */
247
+ export const CHECK_SCRIPT = /^(?:check|typecheck|type-check)(?::|$)|:check$/u;
248
+ /** Matches a package script that runs one project's suite. */
249
+ export const SCOPED_SCRIPT = /^test:/u;
250
+ /** Matches one sampler row: process id, parent id, creation time in milliseconds, CPU time in 100 ns units, and private bytes. */
251
+ export const GAUGE_PATTERN = /^(\d+) (\d+) (\d+) (\d+) (\d+)$/u;
252
+ /** Holds the line a sampler prints when its first process query has run, which readies it. */
253
+ export const READY_LINE = 'ready';
254
+ /** Holds the byte a holder writes to its sampler to ask for one sample at once. */
255
+ export const SAMPLE_BYTE = 's';
256
+ /**
257
+ * Holds the PowerShell text of a sampler.
258
+ *
259
+ * @remarks
260
+ * The child runs one process query, the one a sample runs, so its first sample answers warm, and
261
+ * prints {@link READY_LINE}. Until the first byte it waits on its
262
+ * stdin with no timer. Each byte on its stdin starts one sample at once, and after the first byte it
263
+ * also samples every {@link SAMPLE_MS}. A sample prints one line: `1` for a sample a byte asked for or `0`, a `|`,
264
+ * and the rows separated by semicolons. The child exits when its stdin closes.
265
+ */
266
+ export const SAMPLER_COMMAND = `$i=[Console]::OpenStandardInput();$b=New-Object byte[] 1;$t=$i.ReadAsync($b,0,1);$null=Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate,KernelModeTime,UserModeTime,PrivatePageCount;[Console]::Out.WriteLine('${READY_LINE}');[Console]::Out.Flush();$a=$false;$q=0;$d=-1;while($true){if($a){$r=Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate,KernelModeTime,UserModeTime,PrivatePageCount | Where-Object { $_.CreationDate } | ForEach-Object { '{0} {1} {2} {3} {4}' -f $_.ProcessId,$_.ParentProcessId,([DateTimeOffset]$_.CreationDate).ToUnixTimeMilliseconds(),($_.KernelModeTime+$_.UserModeTime),$_.PrivatePageCount };[Console]::Out.WriteLine([string]$q+'|'+($r -join ';'));[Console]::Out.Flush();$q=0};if($t.Wait($d)){if($t.Status -ne 'RanToCompletion' -or $t.Result -eq 0){break};$a=$true;$q=1;$d=${String(SAMPLE_MS)};$t=$i.ReadAsync($b,0,1)}}`;
74
267
  /**
75
268
  * Holds a process's endpoint, whose existence is the process's liveness.
76
269
  *
@@ -81,8 +274,10 @@ export const SNAPSHOT_COMMAND = "Get-CimInstance Win32_Process -Property Process
81
274
  */
82
275
  export class Token {
83
276
  #sockets = new Set();
277
+ #waiters = new Set();
84
278
  #server;
85
279
  #published = false;
280
+ #holding = false;
86
281
  constructor() {
87
282
  this.#server = createServer((socket) => this.#admit(socket));
88
283
  }
@@ -93,14 +288,9 @@ export class Token {
93
288
  * @returns A promise that resolves when the endpoint accepts connections, and rejects with the
94
289
  * listen failure.
95
290
  */
96
- listen(endpoint) {
97
- return new Promise((resolve, reject) => {
98
- this.#server.once('error', reject);
99
- this.#server.listen(endpoint, () => {
100
- this.#server.removeListener('error', reject);
101
- resolve();
102
- });
103
- });
291
+ async listen(endpoint) {
292
+ this.#server.listen(endpoint);
293
+ await once(this.#server, 'listening');
104
294
  }
105
295
  /** Marks the stage as ended and closes every accepted connection, which wakes each waiter. */
106
296
  publish() {
@@ -108,81 +298,49 @@ export class Token {
108
298
  for (const socket of this.#sockets)
109
299
  socket.destroy();
110
300
  }
301
+ /** Marks the process as a holder and closes every connection that waits for it to hold. */
302
+ hold() {
303
+ this.#holding = true;
304
+ for (const socket of this.#waiters)
305
+ socket.destroy();
306
+ }
307
+ /** Marks the process as leaving, so a hold waiter that arrives later parks until the process ends. */
308
+ leave() {
309
+ this.#holding = false;
310
+ }
111
311
  /**
112
312
  * Closes the endpoint and every connection.
113
313
  *
114
314
  * @returns A promise that resolves when the server has closed.
115
315
  */
116
- destroy() {
316
+ async destroy() {
117
317
  for (const socket of this.#sockets)
118
318
  socket.destroy();
119
- return new Promise((resolve) => {
120
- this.#server.close(() => resolve());
121
- });
319
+ this.#server.close();
320
+ await once(this.#server, 'close');
122
321
  }
123
- // A byte after the publish comes from a stage waiter whose connection the allocation left unaccepted.
322
+ // Another byte after the publish comes from a stage waiter whose connection the allocation left unaccepted.
124
323
  #admit(socket) {
125
324
  this.#sockets.add(socket);
126
325
  socket.on('error', () => undefined);
127
- socket.on('close', () => this.#sockets.delete(socket));
128
- socket.on('data', () => {
129
- if (this.#published)
326
+ socket.on('close', () => {
327
+ this.#sockets.delete(socket);
328
+ this.#waiters.delete(socket);
329
+ });
330
+ socket.on('data', (data) => {
331
+ if (!data.includes(HOLD_BYTE)) {
332
+ if (this.#published)
333
+ socket.destroy();
334
+ }
335
+ else if (this.#holding) {
130
336
  socket.destroy();
337
+ }
338
+ else {
339
+ this.#waiters.add(socket);
340
+ }
131
341
  });
132
342
  }
133
343
  }
134
- /**
135
- * Reads the value that follows a flag.
136
- *
137
- * @remarks
138
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
139
- * and the `--flag=value` form is not read.
140
- *
141
- * @param argv - The arguments before the bare `--`.
142
- * @param name - The flag, such as `--label`.
143
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
144
- * another flag.
145
- */
146
- export function readOption(argv, name) {
147
- const index = argv.indexOf(name);
148
- const value = index === -1 ? undefined : argv[index + 1];
149
- return value === undefined || value.startsWith('--') ? undefined : value;
150
- }
151
- /**
152
- * Names the value flags a caller gave with no value.
153
- *
154
- * @param argv - The arguments before the bare `--`.
155
- * @param names - The flags that take a value.
156
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
157
- */
158
- export function readMissingFlags(argv, names) {
159
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
160
- }
161
- /**
162
- * Names the flags a caller gave that the script does not read.
163
- *
164
- * @remarks
165
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
166
- * scan, so the command after it keeps every argument.
167
- *
168
- * @param argv - The arguments after the script path.
169
- * @param flags - Every flag the script reads, value flags and switches alike.
170
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
171
- */
172
- export function readUnknownFlags(argv, flags) {
173
- const end = argv.indexOf('--');
174
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
175
- }
176
- /**
177
- * Reads the arguments that are neither a flag nor the value of a value flag.
178
- *
179
- * @param argv - The arguments before the bare `--`.
180
- * @param valueFlags - The flags that take a value.
181
- * @returns The positional arguments in order.
182
- */
183
- export function readPositionals(argv, valueFlags) {
184
- return argv.filter((argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''));
185
- }
186
344
  /**
187
345
  * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
188
346
  *
@@ -243,22 +401,14 @@ export function renderEndpoint(root, token) {
243
401
  : join(root, `${token}${SOCKET_SUFFIX}`);
244
402
  }
245
403
  /**
246
- * Renders the name of a ticket.
247
- *
248
- * @param sequence - The ticket's sequence.
249
- * @returns The file name, at a fixed width.
250
- */
251
- export function renderTicketName(sequence) {
252
- return `${String(sequence).padStart(SEQUENCE_WIDTH, '0')}${TICKET_SUFFIX}`;
253
- }
254
- /**
255
- * Renders the name of a run record.
404
+ * Renders the name of a ticket or a run record.
256
405
  *
257
406
  * @param sequence - The ticket's sequence.
407
+ * @param suffix - The name ending: `TICKET_SUFFIX` for a ticket, `RUN_SUFFIX` for its run record.
258
408
  * @returns The file name, at a fixed width.
259
409
  */
260
- export function renderRunName(sequence) {
261
- return `${String(sequence).padStart(SEQUENCE_WIDTH, '0')}${RUN_SUFFIX}`;
410
+ export function renderName(sequence, suffix) {
411
+ return `${String(sequence).padStart(SEQUENCE_WIDTH, '0')}${suffix}`;
262
412
  }
263
413
  /**
264
414
  * Lists a directory's names.
@@ -292,7 +442,8 @@ export function readSequences(names) {
292
442
  * Checks whether a value is a ticket record.
293
443
  *
294
444
  * @param value - The parsed JSON value.
295
- * @returns True when every field has its type and the token has the token's form; false otherwise.
445
+ * @returns True when every field has its type, each present optional field too, and the token has
446
+ * the token's form; false otherwise.
296
447
  */
297
448
  export function isTicket(value) {
298
449
  return (typeof value === 'object' &&
@@ -313,7 +464,78 @@ export function isTicket(value) {
313
464
  'cwd' in value &&
314
465
  typeof value.cwd === 'string' &&
315
466
  'arrived' in value &&
316
- typeof value.arrived === 'string');
467
+ typeof value.arrived === 'string' &&
468
+ (!('light' in value) || isUsage(value.light)) &&
469
+ (!('solo' in value) || typeof value.solo === 'boolean') &&
470
+ (!('edits' in value) || typeof value.edits === 'boolean'));
471
+ }
472
+ /**
473
+ * Checks whether a value is a footprint.
474
+ *
475
+ * @param value - The parsed JSON value.
476
+ * @returns True when `cores`, `memory`, and `processes` are finite numbers of at least 0; false
477
+ * otherwise.
478
+ */
479
+ export function isUsage(value) {
480
+ return (typeof value === 'object' &&
481
+ value !== null &&
482
+ 'cores' in value &&
483
+ isAmount(value.cores) &&
484
+ 'memory' in value &&
485
+ isAmount(value.memory) &&
486
+ 'processes' in value &&
487
+ isAmount(value.processes));
488
+ }
489
+ /**
490
+ * Checks whether a value is a finite number of at least 0.
491
+ *
492
+ * @param value - The value.
493
+ * @returns True for a finite number of at least 0; false otherwise.
494
+ */
495
+ export function isAmount(value) {
496
+ return typeof value === 'number' && Number.isFinite(value) && value >= 0;
497
+ }
498
+ /**
499
+ * Checks whether a value is the content of `limits.json`.
500
+ *
501
+ * @param value - The parsed JSON value.
502
+ * @returns True when `slots` is an integer of at least 1, `budget` is a footprint, and `threshold` is
503
+ * a footprint with a `duration`; false otherwise.
504
+ */
505
+ export function isLimits(value) {
506
+ return (typeof value === 'object' &&
507
+ value !== null &&
508
+ 'slots' in value &&
509
+ Number.isSafeInteger(value.slots) &&
510
+ typeof value.slots === 'number' &&
511
+ value.slots >= 1 &&
512
+ 'budget' in value &&
513
+ isUsage(value.budget) &&
514
+ 'threshold' in value &&
515
+ isUsage(value.threshold) &&
516
+ 'duration' in value.threshold &&
517
+ isAmount(value.threshold.duration));
518
+ }
519
+ /**
520
+ * Checks whether a value is a run's record.
521
+ *
522
+ * @param value - The parsed JSON value.
523
+ * @returns True when the measures are finite numbers of at least 0 and `code` is an integer; false
524
+ * otherwise.
525
+ */
526
+ export function isOutcome(value) {
527
+ return (typeof value === 'object' &&
528
+ value !== null &&
529
+ 'duration' in value &&
530
+ isAmount(value.duration) &&
531
+ 'cpu' in value &&
532
+ isAmount(value.cpu) &&
533
+ 'memory' in value &&
534
+ isAmount(value.memory) &&
535
+ 'processes' in value &&
536
+ isAmount(value.processes) &&
537
+ 'code' in value &&
538
+ Number.isSafeInteger(value.code));
317
539
  }
318
540
  /**
319
541
  * Checks whether a value is a run record.
@@ -354,7 +576,7 @@ export function parseText(text) {
354
576
  */
355
577
  export function readEntry(root, sequence) {
356
578
  try {
357
- const parsed = parseText(readFileSync(join(root, renderTicketName(sequence)), 'utf8'));
579
+ const parsed = parseText(readFileSync(join(root, renderName(sequence, TICKET_SUFFIX)), 'utf8'));
358
580
  return [{ sequence, ticket: isTicket(parsed) ? parsed : undefined }];
359
581
  }
360
582
  catch (error) {
@@ -388,7 +610,7 @@ export function readQueue(root) {
388
610
  */
389
611
  export function readRun(root, sequence) {
390
612
  try {
391
- const parsed = parseText(readFileSync(join(root, renderRunName(sequence)), 'utf8'));
613
+ const parsed = parseText(readFileSync(join(root, renderName(sequence, RUN_SUFFIX)), 'utf8'));
392
614
  return isRun(parsed)
393
615
  ? {
394
616
  started: parsed.started,
@@ -409,7 +631,7 @@ export function readRun(root, sequence) {
409
631
  * @param run - The record.
410
632
  */
411
633
  export function writeRun(root, sequence, run) {
412
- writeFileSync(join(root, renderRunName(sequence)), JSON.stringify(run));
634
+ writeFileSync(join(root, renderName(sequence, RUN_SUFFIX)), JSON.stringify(run));
413
635
  }
414
636
  /**
415
637
  * Removes a file inside the removal budget.
@@ -424,9 +646,14 @@ export function removeFile(path) {
424
646
  *
425
647
  * @param token - The process's token.
426
648
  * @param label - The run's label.
427
- * @returns The complete ticket.
649
+ * @param light - The footprint a light ticket counts, or undefined for a heavy ticket.
650
+ * @param solo - If `true`, marks a ticket that waits out every earlier light ticket; if `false`, omits
651
+ * the field.
652
+ * @param edits - If `true`, marks a `mutate` run that edits source in its working directory; if
653
+ * `false`, omits the field.
654
+ * @returns The complete ticket, carrying `light`, `solo`, and `edits` only when they are set.
428
655
  */
429
- export function buildTicket(token, label) {
656
+ export function buildTicket(token, label, light, solo = false, edits = false) {
430
657
  return {
431
658
  protocol: PROTOCOL,
432
659
  token,
@@ -436,8 +663,547 @@ export function buildTicket(token, label) {
436
663
  platform: process.platform,
437
664
  cwd: process.cwd(),
438
665
  arrived: new Date().toISOString(),
666
+ ...(light === undefined ? {} : { light }),
667
+ ...(solo ? { solo } : {}),
668
+ ...(edits ? { edits } : {}),
439
669
  };
440
670
  }
671
+ /**
672
+ * Reads `limits.json` under the root.
673
+ *
674
+ * @param root - The queue root.
675
+ * @returns The limits; `absent` when the file does not exist; `unread` when it cannot be read as
676
+ * limits.
677
+ */
678
+ export function readLimits(root) {
679
+ try {
680
+ const parsed = parseText(readFileSync(join(root, LIMITS_FILE), 'utf8'));
681
+ return isLimits(parsed) ? parsed : 'unread';
682
+ }
683
+ catch (error) {
684
+ return readCode(error) === 'ENOENT' ? 'absent' : 'unread';
685
+ }
686
+ }
687
+ /**
688
+ * Renders the key of a command's run records.
689
+ *
690
+ * @param cwd - The real working directory.
691
+ * @param command - The command and its arguments.
692
+ * @returns The hex sha256 of the directory and the arguments.
693
+ */
694
+ export function renderKey(cwd, command) {
695
+ return createHash('sha256')
696
+ .update(JSON.stringify([cwd, ...command]))
697
+ .digest('hex');
698
+ }
699
+ /**
700
+ * Renders the name of a run's record.
701
+ *
702
+ * @param ended - When the run ended, in epoch milliseconds.
703
+ * @param token - The run's token, which keeps two records of one key and one millisecond apart.
704
+ * @returns The file name, opening with the end time at a fixed width.
705
+ */
706
+ export function renderOutcomeName(ended, token) {
707
+ return `${String(ended).padStart(ENDED_WIDTH, '0')}-${token}${OUTCOME_SUFFIX}`;
708
+ }
709
+ /**
710
+ * Reads the names of a key's records, oldest first.
711
+ *
712
+ * @param root - The queue root.
713
+ * @param key - The command's key.
714
+ * @returns Every record name under the key, sorted by end time.
715
+ */
716
+ export function readOutcomeNames(root, key) {
717
+ return readNames(join(root, HISTORY_DIRECTORY, key))
718
+ .filter((name) => name.endsWith(OUTCOME_SUFFIX))
719
+ .toSorted();
720
+ }
721
+ /**
722
+ * Reads a key's latest records.
723
+ *
724
+ * @param root - The queue root.
725
+ * @param key - The command's key.
726
+ * @returns Up to {@link RECENT_RUNS} records, oldest first, each undefined when it cannot be read as
727
+ * a record; a record removed while it is read is skipped.
728
+ */
729
+ export function readOutcomes(root, key) {
730
+ return readOutcomeNames(root, key)
731
+ .slice(-RECENT_RUNS)
732
+ .flatMap((name) => {
733
+ try {
734
+ const parsed = parseText(readFileSync(join(root, HISTORY_DIRECTORY, key, name), 'utf8'));
735
+ return [isOutcome(parsed) ? parsed : undefined];
736
+ }
737
+ catch (error) {
738
+ return readCode(error) === 'ENOENT' ? [] : [undefined];
739
+ }
740
+ });
741
+ }
742
+ /**
743
+ * Writes a run's record once and prunes its key to the latest {@link RECENT_RUNS} records.
744
+ *
745
+ * @param root - The queue root.
746
+ * @param key - The command's key.
747
+ * @param name - The record's name.
748
+ * @param outcome - The record.
749
+ * @returns True when the write created the key's directory; false when the key existed.
750
+ */
751
+ export function writeOutcome(root, key, name, outcome) {
752
+ const directory = join(root, HISTORY_DIRECTORY, key);
753
+ const created = mkdirSync(directory, { recursive: true }) !== undefined;
754
+ writeFileSync(join(directory, name), JSON.stringify(outcome), { flag: 'wx' });
755
+ for (const stale of readOutcomeNames(root, key).slice(0, -RECENT_RUNS)) {
756
+ removeFile(join(directory, stale));
757
+ }
758
+ return created;
759
+ }
760
+ /**
761
+ * Reads when a history key was last written.
762
+ *
763
+ * @param root - The queue root.
764
+ * @param key - The key.
765
+ * @returns The end time its newest record's name opens with; the directory's modification time when
766
+ * it holds no record; `gone` when the entry no longer exists; `unread` when the host refuses to list
767
+ * it, as it does for a file that is no directory.
768
+ */
769
+ export function readKeyTime(root, key) {
770
+ try {
771
+ const newest = readOutcomeNames(root, key).at(-1);
772
+ if (newest !== undefined)
773
+ return Number(newest.slice(0, ENDED_WIDTH));
774
+ return statSync(join(root, HISTORY_DIRECTORY, key)).mtimeMs;
775
+ }
776
+ catch (error) {
777
+ return readCode(error) === 'ENOENT' ? 'gone' : 'unread';
778
+ }
779
+ }
780
+ /**
781
+ * Lists the names under the history directory.
782
+ *
783
+ * @param root - The queue root.
784
+ * @returns The names, empty when the directory is absent; undefined when the host refuses to list it.
785
+ */
786
+ export function readHistoryNames(root) {
787
+ try {
788
+ return readNames(join(root, HISTORY_DIRECTORY));
789
+ }
790
+ catch {
791
+ return undefined;
792
+ }
793
+ }
794
+ /**
795
+ * Removes one history key inside the removal budget.
796
+ *
797
+ * @param root - The queue root.
798
+ * @param key - The key.
799
+ * @returns True when the key is gone; false when the host refused the removal.
800
+ */
801
+ export function removeKey(root, key) {
802
+ try {
803
+ rmSync(join(root, HISTORY_DIRECTORY, key), {
804
+ recursive: true,
805
+ force: true,
806
+ maxRetries: REMOVAL_RETRIES,
807
+ retryDelay: REMOVAL_DELAY_MS,
808
+ });
809
+ return true;
810
+ }
811
+ catch {
812
+ return false;
813
+ }
814
+ }
815
+ /**
816
+ * Prunes the history to the keys written inside {@link HISTORY_AGE_MS}, at most the
817
+ * {@link HISTORY_KEYS} written last.
818
+ *
819
+ * @remarks
820
+ * The prune throws nothing, so it never changes the lane's exit: a name the host refuses to list or
821
+ * remove stays and is reported as skipped.
822
+ *
823
+ * @param root - The queue root.
824
+ * @param now - The current time in epoch milliseconds.
825
+ * @returns The keys removed, and the names skipped: `history` itself when it cannot be listed.
826
+ */
827
+ export function pruneHistory(root, now) {
828
+ const names = readHistoryNames(root);
829
+ if (names === undefined)
830
+ return { removed: [], skipped: [HISTORY_DIRECTORY] };
831
+ const times = names.map((key) => ({ key, time: readKeyTime(root, key) }));
832
+ const unread = times.flatMap((item) => (item.time === 'unread' ? [item.key] : []));
833
+ const results = times
834
+ .flatMap((item) => (typeof item.time === 'number' ? [{ key: item.key, time: item.time }] : []))
835
+ .toSorted((left, right) => right.time - left.time)
836
+ .filter((item, index) => index >= HISTORY_KEYS || item.time < now - HISTORY_AGE_MS)
837
+ .map((item) => ({ key: item.key, removed: removeKey(root, item.key) }));
838
+ return {
839
+ removed: results.flatMap((item) => (item.removed ? [item.key] : [])),
840
+ skipped: [...unread, ...results.flatMap((item) => (item.removed ? [] : [item.key]))],
841
+ };
842
+ }
843
+ /**
844
+ * Reads the average cores a run used.
845
+ *
846
+ * @param outcome - The run's record.
847
+ * @returns The CPU time over the duration; 0 for a run of no duration.
848
+ */
849
+ export function readCores(outcome) {
850
+ return outcome.duration > 0 ? outcome.cpu / outcome.duration : 0;
851
+ }
852
+ /**
853
+ * Checks whether a run's record breaches the per-run threshold.
854
+ *
855
+ * @param outcome - The run's record, or undefined when it cannot be read.
856
+ * @param threshold - The per-run threshold.
857
+ * @returns True for an unreadable record, a capped run, an exit of 69 or 70, and a measure past the
858
+ * threshold; false otherwise.
859
+ */
860
+ export function isBreach(outcome, threshold) {
861
+ return (outcome === undefined ||
862
+ outcome.code === CAPPED_CODE ||
863
+ outcome.code === HELD_CODE ||
864
+ outcome.code === BREACH_CODE ||
865
+ outcome.duration > threshold.duration ||
866
+ readCores(outcome) > threshold.cores ||
867
+ outcome.memory > threshold.memory ||
868
+ outcome.processes > threshold.processes);
869
+ }
870
+ /**
871
+ * Reads the footprint a light ticket counts from its command's records.
872
+ *
873
+ * @param outcomes - The records, none of which breaches.
874
+ * @returns The largest cores, memory, and process count across the records.
875
+ */
876
+ export function measurePeak(outcomes) {
877
+ return {
878
+ cores: Math.max(0, ...outcomes.map(readCores)),
879
+ memory: Math.max(0, ...outcomes.map((outcome) => outcome.memory)),
880
+ processes: Math.max(0, ...outcomes.map((outcome) => outcome.processes)),
881
+ };
882
+ }
883
+ /**
884
+ * Reads whether a command runs light, from its seed and its latest records.
885
+ *
886
+ * @remarks
887
+ * A seeded heavy command is heavy whatever its records hold. A seeded light command is light until a
888
+ * record breaches, and counts the threshold until {@link RECENT_RUNS} records exist. Any other
889
+ * command is light only when {@link RECENT_RUNS} records exist and none breaches.
890
+ *
891
+ * @param seed - The lane the command's kind seeds, or undefined when no kind names it.
892
+ * @param outcomes - The command's latest records.
893
+ * @param limits - The limits.
894
+ * @returns The footprint the ticket counts, or undefined when the command runs heavy.
895
+ */
896
+ export function classifyLight(seed, outcomes, limits) {
897
+ if (seed === 'heavy')
898
+ return undefined;
899
+ const clean = outcomes.flatMap((outcome) => outcome === undefined || isBreach(outcome, limits.threshold) ? [] : [outcome]);
900
+ if (clean.length < outcomes.length)
901
+ return undefined;
902
+ if (clean.length >= RECENT_RUNS)
903
+ return measurePeak(clean);
904
+ const { cores, memory, processes } = limits.threshold;
905
+ return seed === 'light' ? { cores, memory, processes } : undefined;
906
+ }
907
+ /**
908
+ * Checks whether light footprints fit the slots and every budget together.
909
+ *
910
+ * @param usages - The footprints of the light holders and the arrival.
911
+ * @param limits - The limits.
912
+ * @returns True when the count fits `slots` and each summed measure fits its budget; false otherwise.
913
+ */
914
+ export function fitsBudget(usages, limits) {
915
+ const total = usages.reduce((sum, usage) => ({
916
+ cores: sum.cores + usage.cores,
917
+ memory: sum.memory + usage.memory,
918
+ processes: sum.processes + usage.processes,
919
+ }), { cores: 0, memory: 0, processes: 0 });
920
+ return (usages.length <= limits.slots &&
921
+ total.cores <= limits.budget.cores &&
922
+ total.memory <= limits.budget.memory &&
923
+ total.processes <= limits.budget.processes);
924
+ }
925
+ /**
926
+ * Splits a command into the words a seed reads.
927
+ *
928
+ * @remarks
929
+ * An absolute path contributes its base name alone, so a checkout's location never seeds a command.
930
+ *
931
+ * @param args - The arguments after the executable.
932
+ * @returns The lowercase alphanumeric words.
933
+ */
934
+ export function readWords(args) {
935
+ return args.flatMap((argument) => (isAbsolute(argument) ? basename(argument) : argument)
936
+ .toLowerCase()
937
+ .split(/[^a-z0-9]+/u)
938
+ .filter((word) => word !== ''));
939
+ }
940
+ /**
941
+ * Reads a tool's name from an executable or script path.
942
+ *
943
+ * @param path - The path.
944
+ * @returns The lowercase base name without its extension, `npm-cli` and `npx-cli` read as `npm` and
945
+ * `npx`.
946
+ */
947
+ export function readToolName(path) {
948
+ const name = basename(path.replaceAll('\\', '/'))
949
+ .toLowerCase()
950
+ .replace(/\.(?:exe|cmd|bat|ps1|js|mjs|cjs|ts|mts|cts)$/u, '');
951
+ return name.replace(/-cli$/u, '');
952
+ }
953
+ /**
954
+ * Reads the tool a command runs and the tool's arguments, past Node, `npx`, `pnpx`, `bunx`, and a
955
+ * package manager's `exec`, `x`, or `dlx` verb.
956
+ *
957
+ * @param command - The command and its arguments.
958
+ * @returns The tool's name followed by its arguments; empty for inline Node code, inline exec text,
959
+ * or no script.
960
+ */
961
+ export function readTool(command) {
962
+ const [executable, ...rest] = command;
963
+ if (executable === undefined)
964
+ return [];
965
+ const name = readToolName(executable);
966
+ if (name === 'node') {
967
+ const script = rest.findIndex((argument) => !argument.startsWith('-'));
968
+ const flags = script === -1 ? rest : rest.slice(0, script);
969
+ if (script === -1 || flags.some((flag) => ['-e', '--eval', '-p', '--print'].includes(flag))) {
970
+ return [];
971
+ }
972
+ return readTool(rest.slice(script));
973
+ }
974
+ if (NPX_TOOLS.includes(name))
975
+ return readExecTool(rest, EXEC_VALUE_FLAGS[name]);
976
+ if (MANAGERS.includes(name)) {
977
+ const flags = MANAGER_VALUE_FLAGS[name] ?? [];
978
+ const verb = rest.findIndex((argument, index) => !argument.startsWith('-') && !flags.includes(rest[index - 1] ?? ''));
979
+ if (EXEC_VERBS.includes(rest[verb] ?? '')) {
980
+ return readExecTool(rest.slice(verb + 1), EXEC_VALUE_FLAGS[name]);
981
+ }
982
+ }
983
+ return [name, ...rest];
984
+ }
985
+ /**
986
+ * Reads the tool an `npx` or `npm exec` call runs, from the arguments after the verb.
987
+ *
988
+ * @remarks
989
+ * The tool is the first argument before a bare `--` that is neither a flag nor the value of a
990
+ * listed flag, else the first argument after the bare `--`. A flag {@link EXEC_INLINE_FLAGS} names
991
+ * before the tool runs shell text instead.
992
+ *
993
+ * @param args - The arguments after `npx` or after the exec verb.
994
+ * @param valueFlags - The flags that take a separate value, from {@link EXEC_VALUE_FLAGS}. Default:
995
+ * none.
996
+ * @returns The tool's name followed by its arguments; empty for inline text or no tool.
997
+ */
998
+ export function readExecTool(args, valueFlags = []) {
999
+ const end = args.indexOf('--');
1000
+ const named = args.findIndex((argument, index) => (end === -1 || index < end) &&
1001
+ !argument.startsWith('-') &&
1002
+ !valueFlags.includes(args[index - 1] ?? ''));
1003
+ const start = named !== -1 ? named : end === -1 ? -1 : end + 1;
1004
+ if (start === -1 || start >= args.length)
1005
+ return [];
1006
+ const inline = args
1007
+ .slice(0, start)
1008
+ .some((flag) => EXEC_INLINE_FLAGS.includes(flag) ||
1009
+ EXEC_INLINE_FLAGS.some((name) => flag.startsWith(`${name}=`)));
1010
+ return inline ? [] : readTool(args.slice(start));
1011
+ }
1012
+ /**
1013
+ * Checks whether a command is a `mutate --restore` run, which writes source files back.
1014
+ *
1015
+ * @param command - The command and its arguments.
1016
+ * @returns True for a `mutate` call with its restore flag before any bare `--`; false otherwise.
1017
+ */
1018
+ export function matchesRestore(command) {
1019
+ const [tool, ...args] = readTool(command);
1020
+ if (tool !== MUTATION_TOOL)
1021
+ return false;
1022
+ const end = args.indexOf('--');
1023
+ return (end === -1 ? args : args.slice(0, end)).some((flag) => flag === RESTORE_FLAG || flag.startsWith(`${RESTORE_FLAG}=`));
1024
+ }
1025
+ /**
1026
+ * Extracts the command a `mutate` run wraps.
1027
+ *
1028
+ * @param command - The command and its arguments.
1029
+ * @returns The arguments after the run's own bare `--`; undefined for any other command, or a
1030
+ * `mutate` call with no edits file or no wrapped command.
1031
+ */
1032
+ export function extractMutation(command) {
1033
+ const [tool, ...args] = readTool(command);
1034
+ if (tool !== MUTATION_TOOL)
1035
+ return undefined;
1036
+ const end = args.indexOf('--');
1037
+ if (end === -1)
1038
+ return undefined;
1039
+ const edits = args
1040
+ .slice(0, end)
1041
+ .some((flag) => flag === MUTATION_FLAG || flag.startsWith(`${MUTATION_FLAG}=`));
1042
+ const wrapped = args.slice(end + 1);
1043
+ return edits && wrapped.length > 0 ? wrapped : undefined;
1044
+ }
1045
+ /**
1046
+ * Normalizes a command to the arguments its key hashes.
1047
+ *
1048
+ * @remarks
1049
+ * A `mutate` run names a fresh edits file each time, so its key leaves the edits flag and its value
1050
+ * out, and every run of one wrapped command from one directory shares a key. The cut reads only the
1051
+ * script's own flags, between the script and its own bare `--`, so a launcher's `--` before the
1052
+ * script moves nothing.
1053
+ *
1054
+ * @param command - The command and its arguments.
1055
+ * @returns A `mutate` run without its edits flag and value; any other command unchanged.
1056
+ */
1057
+ export function normalizeCommand(command) {
1058
+ if (extractMutation(command) === undefined)
1059
+ return command;
1060
+ const start = command.length - readTool(command).length + 1;
1061
+ const end = command.indexOf('--', start);
1062
+ return command.filter((argument, index) => index < start ||
1063
+ index >= end ||
1064
+ !(argument === MUTATION_FLAG ||
1065
+ argument.startsWith(`${MUTATION_FLAG}=`) ||
1066
+ command[index - 1] === MUTATION_FLAG));
1067
+ }
1068
+ /**
1069
+ * Normalizes a working directory for the comparison that decides whether two tickets share it.
1070
+ *
1071
+ * @remarks
1072
+ * Every side of the comparison passes through this one function. It reads the real path through
1073
+ * `realpathSync.native`, which returns the name and the case the file system stores, so two
1074
+ * spellings of one directory compare equal without folding case.
1075
+ *
1076
+ * @param path - The directory.
1077
+ * @returns The real path; the resolved path when it cannot be read, as for a vanished directory.
1078
+ */
1079
+ export function normalizeDirectory(path) {
1080
+ try {
1081
+ return realpathSync.native(path);
1082
+ }
1083
+ catch {
1084
+ return resolvePath(path);
1085
+ }
1086
+ }
1087
+ /**
1088
+ * Checks whether two working directories share source.
1089
+ *
1090
+ * @remarks
1091
+ * Both sides pass through {@link normalizeDirectory}, so a child directory, such as a check run from
1092
+ * `packages/a`, shares source with a mutation at the checkout root, and the reverse.
1093
+ *
1094
+ * @param left - One directory.
1095
+ * @param right - The other directory.
1096
+ * @returns True when the two normalize to one directory or one sits inside the other at a separator
1097
+ * boundary; false otherwise.
1098
+ */
1099
+ export function sharesDirectory(left, right) {
1100
+ const one = normalizeDirectory(left);
1101
+ const other = normalizeDirectory(right);
1102
+ return one === other || matchesInside(one, other) || matchesInside(other, one);
1103
+ }
1104
+ /**
1105
+ * Checks whether a normalized path sits inside another at a separator boundary.
1106
+ *
1107
+ * @param inner - The path that might sit inside.
1108
+ * @param outer - The path that might contain it.
1109
+ * @returns True when `inner` opens with `outer` and a separator; false otherwise, the same path
1110
+ * included.
1111
+ */
1112
+ export function matchesInside(inner, outer) {
1113
+ return inner.startsWith(outer.endsWith(sep) ? outer : `${outer}${sep}`);
1114
+ }
1115
+ /**
1116
+ * Reads the positional arguments of a command, skipping each value of a value-taking flag.
1117
+ *
1118
+ * @param args - The arguments.
1119
+ * @param valueFlags - The flags that take a separate value.
1120
+ * @returns The arguments that are neither a flag nor the value of a listed or dotted flag.
1121
+ */
1122
+ export function readOperands(args, valueFlags) {
1123
+ return args.filter((argument, index) => !argument.startsWith('-') &&
1124
+ !valueFlags.includes(args[index - 1] ?? '') &&
1125
+ !DOTTED_FLAG.test(args[index - 1] ?? ''));
1126
+ }
1127
+ /**
1128
+ * Reads the lane a package script's name seeds.
1129
+ *
1130
+ * @param name - The script's name.
1131
+ * @returns `heavy` for a script {@link HEAVY_SCRIPTS} names, `light` for a type, format, or lint
1132
+ * check and any other `test:` suite, and undefined for any other script.
1133
+ */
1134
+ export function readScriptSeed(name) {
1135
+ if (HEAVY_SCRIPTS.includes(name))
1136
+ return 'heavy';
1137
+ return CHECK_SCRIPT.test(name) || SCOPED_SCRIPT.test(name) ? 'light' : undefined;
1138
+ }
1139
+ /**
1140
+ * Reads the lane a Vitest command seeds.
1141
+ *
1142
+ * @param args - The arguments after `vitest`.
1143
+ * @returns `heavy` for a run of every project, of several projects, of a project
1144
+ * {@link HEAVY_PROJECTS} names, or of a whole browser project; `light` for a run of named test files
1145
+ * or one other project; undefined for any other run or mode.
1146
+ */
1147
+ export function readVitestSeed(args) {
1148
+ const [mode, ...operands] = readOperands(args, VITEST_VALUE_FLAGS);
1149
+ if (mode !== 'run')
1150
+ return undefined;
1151
+ const projects = args.flatMap((argument, index) => {
1152
+ if (argument.startsWith('--project='))
1153
+ return [argument.slice('--project='.length)];
1154
+ return args[index - 1] === '--project' ? [argument] : [];
1155
+ });
1156
+ if (projects.length > 1 ||
1157
+ projects.some((project) => project.includes('*') || HEAVY_PROJECTS.includes(project))) {
1158
+ return 'heavy';
1159
+ }
1160
+ const files = operands.filter((operand) => /\.(?:test|spec)\./u.test(operand));
1161
+ if (files.length === 0 && projects.some((project) => BROWSER_PROJECT.test(project)))
1162
+ return 'heavy';
1163
+ if (files.length > 0 || projects.length === 1)
1164
+ return 'light';
1165
+ return projects.length === 0 && operands.length === 0 ? 'heavy' : undefined;
1166
+ }
1167
+ /**
1168
+ * Reads the lane a command's kind seeds.
1169
+ *
1170
+ * @remarks
1171
+ * Heavy wins: a word that names a journey, a study, a capture, a live-service run, or the release
1172
+ * chain seeds heavy wherever it appears, before any light kind is read. A `mutate --restore` run,
1173
+ * which writes source files back and wraps no command, seeds heavy.
1174
+ *
1175
+ * @param command - The command and its arguments.
1176
+ * @returns The seeded lane, or undefined when no kind names the command.
1177
+ */
1178
+ export function readSeed(command) {
1179
+ if (readWords(command.slice(1)).some((word) => HEAVY_WORDS.includes(word)))
1180
+ return 'heavy';
1181
+ const [tool, ...args] = readTool(command);
1182
+ if (tool === undefined)
1183
+ return undefined;
1184
+ if (HEAVY_TOOLS.includes(tool) || matchesRestore(command))
1185
+ return 'heavy';
1186
+ if (MANAGERS.includes(tool)) {
1187
+ const [verb, script] = readOperands(args, MANAGER_VALUE_FLAGS[tool] ?? []);
1188
+ if (verb === undefined)
1189
+ return undefined;
1190
+ if (HEAVY_VERBS.includes(verb))
1191
+ return 'heavy';
1192
+ return (verb === 'run' || verb === 'run-script') && script !== undefined
1193
+ ? readScriptSeed(script)
1194
+ : undefined;
1195
+ }
1196
+ if (tool === 'vitest')
1197
+ return readVitestSeed(args);
1198
+ if (tool === 'oxfmt' || tool === 'prettier')
1199
+ return args.includes('--check') ? 'light' : undefined;
1200
+ if (tool === 'oxlint' || tool === 'eslint') {
1201
+ return args.some((argument) => argument.startsWith('--fix')) ? undefined : 'light';
1202
+ }
1203
+ if (tool === 'tsc' || tool === 'vue-tsc')
1204
+ return args.includes('--noEmit') ? 'light' : undefined;
1205
+ return undefined;
1206
+ }
441
1207
  /**
442
1208
  * Writes the complete ticket to the stage file, which also marks this process as choosing.
443
1209
  *
@@ -479,7 +1245,7 @@ export function tryLink(from, to) {
479
1245
  */
480
1246
  export function linkStage(root, token) {
481
1247
  const sequence = Math.max(0, ...readSequences(readNames(root))) + 1;
482
- return tryLink(join(root, `${token}${STAGE_SUFFIX}`), join(root, renderTicketName(sequence)))
1248
+ return tryLink(join(root, `${token}${STAGE_SUFFIX}`), join(root, renderName(sequence, TICKET_SUFFIX)))
483
1249
  ? sequence
484
1250
  : linkStage(root, token);
485
1251
  }
@@ -489,25 +1255,109 @@ export function linkStage(root, token) {
489
1255
  * @remarks
490
1256
  * The two listings are separate, because one listing can miss both a ticket linked and a stage file
491
1257
  * removed while it runs. A stage file absent from the first listing belongs to a process whose own
492
- * listing sees this ticket, or to a ticket the second listing sees.
1258
+ * listing sees this ticket, or to a ticket the second listing sees. A ticket holds only when the
1259
+ * directory rule of {@link decideDirectory} names no ticket to wait on and its own lane's rule admits
1260
+ * it. Every rule names only an earlier ticket, and an earlier ticket can only leave, so no two tickets
1261
+ * wait on each other and no cycle of waits can form.
493
1262
  *
494
1263
  * @param root - The queue root.
495
1264
  * @param sequence - This process's sequence.
496
1265
  * @param token - This process's token.
497
- * @returns The holder state, the stage file to wait on, the nearest earlier ticket, or a refusal.
1266
+ * @param limits - The limits this process read at arrival, which a light ticket's admission needs.
1267
+ * @returns The holder state, the stage file to wait on, the earlier ticket or tickets to wait on, or
1268
+ * a refusal.
498
1269
  */
499
- export function decideTurn(root, sequence, token) {
1270
+ export function decideTurn(root, sequence, token, limits) {
500
1271
  const stage = readNames(root).find((name) => name.endsWith(STAGE_SUFFIX) && name !== `${token}${STAGE_SUFFIX}`);
501
1272
  if (stage !== undefined)
502
1273
  return { state: 'staged', name: stage };
503
1274
  const entries = readQueue(root);
504
1275
  const position = entries.findIndex((entry) => entry.sequence === sequence);
505
1276
  if (position === -1) {
506
- return { state: 'refused', reason: `ticket ${renderTicketName(sequence)} is gone` };
1277
+ return { state: 'refused', reason: `ticket ${renderName(sequence, TICKET_SUFFIX)} is gone` };
507
1278
  }
508
- const lower = entries[position - 1];
1279
+ const own = entries[position]?.ticket;
1280
+ const earlier = entries.slice(0, position);
1281
+ const shared = own === undefined ? undefined : decideDirectory(earlier, own);
1282
+ if (shared !== undefined)
1283
+ return shared;
1284
+ return own?.light === undefined || limits === undefined
1285
+ ? decideHeavy(earlier, own?.solo === true)
1286
+ : decideLight(root, earlier, own.light, limits);
1287
+ }
1288
+ /**
1289
+ * Decides which earlier ticket the directory rule makes a ticket wait on, whatever its lane.
1290
+ *
1291
+ * @remarks
1292
+ * Every ticket waits on the nearest earlier ticket that carries `edits` and shares its working
1293
+ * directory, because a `mutate` run edits source that ticket reads. A ticket that carries `edits`
1294
+ * also waits on the nearest earlier ticket of its working directory in either lane, and on an
1295
+ * earlier ticket it cannot read, which might share the directory; that wait refuses. The rule names
1296
+ * only earlier tickets, which can only leave, so it adds no cycle of waits. {@link normalizeDirectory}
1297
+ * reads both sides of every comparison.
1298
+ *
1299
+ * @param earlier - The tickets before this one, in arrival order.
1300
+ * @param own - This process's ticket.
1301
+ * @returns The ticket to wait on; undefined when the rule names none.
1302
+ */
1303
+ export function decideDirectory(earlier, own) {
1304
+ const entry = earlier.findLast((item) => {
1305
+ if (item.ticket === undefined)
1306
+ return own.edits === true;
1307
+ return ((own.edits === true || item.ticket.edits === true) &&
1308
+ sharesDirectory(own.cwd, item.ticket.cwd));
1309
+ });
1310
+ return entry === undefined ? undefined : { state: 'behind', entry };
1311
+ }
1312
+ /**
1313
+ * Decides what a heavy ticket does next.
1314
+ *
1315
+ * @remarks
1316
+ * A heavy ticket waits on the nearest earlier ticket that is not light, an unreadable one included. A
1317
+ * `--solo` ticket waits on the nearest earlier ticket of either lane, so it holds with no light
1318
+ * holder beside it. The rule names only an earlier ticket, so it adds no cycle of waits.
1319
+ *
1320
+ * @param earlier - The tickets before this one, in arrival order.
1321
+ * @param solo - If `true`, waits on light tickets too; if `false`, passes them.
1322
+ * @returns The holder state or the ticket to wait on.
1323
+ */
1324
+ export function decideHeavy(earlier, solo) {
1325
+ const lower = earlier.findLast((entry) => solo || entry.ticket?.light === undefined);
509
1326
  return lower === undefined ? { state: 'holder' } : { state: 'behind', entry: lower };
510
1327
  }
1328
+ /**
1329
+ * Decides what a light ticket does next.
1330
+ *
1331
+ * @remarks
1332
+ * A light ticket holds when every earlier light ticket holds, no earlier `--solo` ticket remains, and
1333
+ * the earlier light footprints with its own fit the limits; the earliest light ticket always fits.
1334
+ * The rule reads only earlier tickets, which can only leave, so an admission is never revoked. An
1335
+ * earlier ticket this process cannot read is waited on alone, which refuses.
1336
+ *
1337
+ * @param root - The queue root.
1338
+ * @param earlier - The tickets before this one, in arrival order.
1339
+ * @param light - This ticket's footprint.
1340
+ * @param limits - The limits.
1341
+ * @returns The holder state, the unreadable ticket to wait on, or every earlier light and `--solo`
1342
+ * ticket to wait on at once, with the light tickets that do not hold yet.
1343
+ */
1344
+ export function decideLight(root, earlier, light, limits) {
1345
+ const unread = earlier.find((entry) => entry.ticket === undefined || describeForeign(entry.ticket) !== undefined);
1346
+ if (unread !== undefined)
1347
+ return { state: 'behind', entry: unread };
1348
+ const lights = earlier.filter((entry) => entry.ticket?.light !== undefined);
1349
+ const solos = earlier.filter((entry) => entry.ticket?.solo === true);
1350
+ const pending = lights.flatMap((entry) => {
1351
+ const blocked = entry.ticket !== undefined &&
1352
+ decideDirectory(earlier.slice(0, earlier.indexOf(entry)), entry.ticket) !== undefined;
1353
+ return !blocked && readRun(root, entry.sequence) === 'absent' ? [entry.sequence] : [];
1354
+ });
1355
+ const usages = lights.flatMap((entry) => entry.ticket?.light === undefined ? [] : [entry.ticket.light]);
1356
+ const fits = usages.length === 0 || fitsBudget([...usages, light], limits);
1357
+ return solos.length === 0 && pending.length === 0 && fits
1358
+ ? { state: 'holder' }
1359
+ : { state: 'queued', entries: orderEntries([...lights, ...solos]), pending };
1360
+ }
511
1361
  /**
512
1362
  * Connects to an endpoint and parks until the connection closes.
513
1363
  *
@@ -515,11 +1365,19 @@ export function decideTurn(root, sequence, token) {
515
1365
  * @param stage - If `true`, writes the one byte a published owner closes the connection on; if
516
1366
  * `false`, writes nothing.
517
1367
  * @param parked - Called when the connection is open and the wait starts.
518
- * @returns The connect failure's code, or undefined after a connection opened and closed.
1368
+ * @param signal - Ends the wait and the connection when it aborts.
1369
+ * @param hold - If `true`, writes the byte a ticket closes the connection on when it holds; if
1370
+ * `false`, waits only for the process to end.
1371
+ * @returns The connect failure's code, or undefined after a connection opened and closed or the
1372
+ * signal aborted.
519
1373
  */
520
- export function parkOn(endpoint, stage, parked) {
1374
+ export function parkOn(endpoint, stage, parked, signal, hold = false) {
521
1375
  return new Promise((resolve) => {
522
1376
  const socket = connect(endpoint);
1377
+ signal?.addEventListener('abort', () => {
1378
+ socket.destroy();
1379
+ resolve(undefined);
1380
+ });
523
1381
  socket.once('error', (error) => resolve(readCode(error)));
524
1382
  socket.once('connect', () => {
525
1383
  socket.removeAllListeners('error');
@@ -528,26 +1386,12 @@ export function parkOn(endpoint, stage, parked) {
528
1386
  socket.resume();
529
1387
  if (stage)
530
1388
  socket.write('s');
1389
+ if (hold)
1390
+ socket.write(HOLD_BYTE);
531
1391
  parked();
532
1392
  });
533
1393
  });
534
1394
  }
535
- /**
536
- * Connects to an endpoint and leaves at once.
537
- *
538
- * @param endpoint - The endpoint.
539
- * @returns The connect failure's code, or undefined when the connection opened.
540
- */
541
- export function probeEndpoint(endpoint) {
542
- return new Promise((resolve) => {
543
- const socket = connect(endpoint);
544
- socket.once('error', (error) => resolve(readCode(error)));
545
- socket.once('connect', () => {
546
- socket.destroy();
547
- resolve(undefined);
548
- });
549
- });
550
- }
551
1395
  /**
552
1396
  * Checks whether a connect failure means the endpoint's owner is gone.
553
1397
  *
@@ -666,9 +1510,20 @@ export function readTree(run, ceiling) {
666
1510
  if (process.platform !== 'win32')
667
1511
  return readGroup(run.launcher);
668
1512
  const rows = readSnapshot();
669
- return rows === undefined
670
- ? undefined
671
- : selectMembers(rows, run.command === undefined ? [run.launcher] : [run.launcher, run.command], run.started - CLOCK_ALLOWANCE_MS, ceiling).map((row) => row.pid);
1513
+ return rows === undefined ? undefined : selectTree(rows, run, ceiling);
1514
+ }
1515
+ /**
1516
+ * Selects the members of one run's process tree from a Windows snapshot.
1517
+ *
1518
+ * @param rows - The snapshot.
1519
+ * @param run - The run record.
1520
+ * @param ceiling - The latest creation date a row of an exited seed can carry.
1521
+ * @returns The members' ids, or undefined when the record names no launcher.
1522
+ */
1523
+ export function selectTree(rows, run, ceiling) {
1524
+ if (run.launcher === undefined)
1525
+ return undefined;
1526
+ return selectMembers(rows, run.command === undefined ? [run.launcher] : [run.launcher, run.command], run.started - CLOCK_ALLOWANCE_MS, ceiling).map((row) => row.pid);
672
1527
  }
673
1528
  /**
674
1529
  * Kills each listed member.
@@ -730,7 +1585,7 @@ export function sweepTree(read, kill, budget) {
730
1585
  */
731
1586
  export function reclaimTicket(root, sequence, ticket) {
732
1587
  const run = readRun(root, sequence);
733
- const files = `${renderTicketName(sequence)} and ${renderRunName(sequence)} under ${root}`;
1588
+ const files = `${renderName(sequence, TICKET_SUFFIX)} and ${renderName(sequence, RUN_SUFFIX)} under ${root}`;
734
1589
  if (run === 'unread' || (run !== 'absent' && run.launcher === undefined)) {
735
1590
  return `the owner of ${quote(ticket.label)} (pid ${String(ticket.pid)}) ended before its tree could be identified; end its tree, then delete ${files}`;
736
1591
  }
@@ -739,9 +1594,9 @@ export function reclaimTicket(root, sequence, ticket) {
739
1594
  if (members === undefined || members.length > 0) {
740
1595
  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}`;
741
1596
  }
742
- removeFile(join(root, renderRunName(sequence)));
1597
+ removeFile(join(root, renderName(sequence, RUN_SUFFIX)));
743
1598
  }
744
- removeFile(join(root, renderTicketName(sequence)));
1599
+ removeFile(join(root, renderName(sequence, TICKET_SUFFIX)));
745
1600
  removeFile(join(root, `${ticket.token}${SOCKET_SUFFIX}`));
746
1601
  return undefined;
747
1602
  }
@@ -774,7 +1629,7 @@ export async function waitOnStage(root, name) {
774
1629
  * @returns The refusal, or undefined when the wait ended.
775
1630
  */
776
1631
  export async function waitOnTicket(root, entry, announced) {
777
- const name = renderTicketName(entry.sequence);
1632
+ const name = renderName(entry.sequence, TICKET_SUFFIX);
778
1633
  const ticket = entry.ticket;
779
1634
  if (ticket === undefined)
780
1635
  return `ticket ${name} under ${root} cannot be read`;
@@ -791,27 +1646,65 @@ export async function waitOnTicket(root, entry, announced) {
791
1646
  ? reclaimTicket(root, entry.sequence, ticket)
792
1647
  : `the endpoint of ticket ${name} reported ${code}`;
793
1648
  }
1649
+ /**
1650
+ * Waits on several earlier tickets at once, until the first leaves or a pending one holds, and
1651
+ * reclaims a ticket whose owner is gone.
1652
+ *
1653
+ * @param root - The queue root.
1654
+ * @param entries - The earlier tickets, each readable and of this host.
1655
+ * @param pending - The sequences of the light tickets among them that did not hold yet, whose hold
1656
+ * also ends the wait.
1657
+ * @param announced - The tokens this process last printed a waiting line for, joined by commas.
1658
+ * @returns The refusal, or undefined when the wait ended.
1659
+ */
1660
+ export async function waitOnTickets(root, entries, pending, announced) {
1661
+ const tickets = entries.flatMap((entry) => entry.ticket === undefined ? [] : [{ sequence: entry.sequence, ticket: entry.ticket }]);
1662
+ const key = tickets.map((item) => item.ticket.token).join(',');
1663
+ const controller = new AbortController();
1664
+ const opened = tickets.map(() => Promise.withResolvers());
1665
+ const waits = tickets.map((item, index) => parkOn(renderEndpoint(root, item.ticket.token), false, () => opened[index]?.resolve(), controller.signal, pending.includes(item.sequence)).then((code) => ({ ...item, code })));
1666
+ void Promise.all(opened.map((resolvers) => resolvers.promise)).then(() => {
1667
+ if (announced !== key && !controller.signal.aborted) {
1668
+ console.error(`lane: waiting behind ${tickets.map((item) => quote(item.ticket.label)).join(', ')}`);
1669
+ }
1670
+ });
1671
+ const first = await Promise.race(waits);
1672
+ controller.abort();
1673
+ if (first.code === undefined)
1674
+ return undefined;
1675
+ return isGone(first.code)
1676
+ ? reclaimTicket(root, first.sequence, first.ticket)
1677
+ : `the endpoint of ticket ${renderName(first.sequence, TICKET_SUFFIX)} reported ${first.code}`;
1678
+ }
794
1679
  /**
795
1680
  * Waits for this process's turn, parked on events with no timer.
796
1681
  *
797
1682
  * @param root - The queue root.
798
1683
  * @param sequence - This process's sequence.
799
1684
  * @param token - This process's token.
800
- * @param announced - The token this process last printed a waiting line for.
1685
+ * @param limits - The limits this process read at arrival.
1686
+ * @param announced - The token or tokens this process last printed a waiting line for.
801
1687
  * @returns The refusal, or undefined when this process holds the lane.
802
1688
  */
803
- export async function waitForTurn(root, sequence, token, announced) {
804
- const turn = decideTurn(root, sequence, token);
1689
+ export async function waitForTurn(root, sequence, token, limits, announced) {
1690
+ const turn = decideTurn(root, sequence, token, limits);
805
1691
  if (turn.state === 'holder')
806
1692
  return undefined;
807
1693
  if (turn.state === 'refused')
808
1694
  return turn.reason;
1695
+ if (turn.state === 'queued') {
1696
+ const refusal = await waitOnTickets(root, turn.entries, turn.pending, announced);
1697
+ if (refusal !== undefined)
1698
+ return refusal;
1699
+ const key = turn.entries.map((entry) => entry.ticket?.token).join(',');
1700
+ return waitForTurn(root, sequence, token, limits, key);
1701
+ }
809
1702
  const refusal = turn.state === 'staged'
810
1703
  ? await waitOnStage(root, turn.name)
811
1704
  : await waitOnTicket(root, turn.entry, announced);
812
1705
  if (refusal !== undefined)
813
1706
  return refusal;
814
- return waitForTurn(root, sequence, token, turn.state === 'behind' ? turn.entry.ticket?.token : announced);
1707
+ return waitForTurn(root, sequence, token, limits, turn.state === 'behind' ? turn.entry.ticket?.token : announced);
815
1708
  }
816
1709
  /**
817
1710
  * Reads the command id from a launcher line.
@@ -889,6 +1782,18 @@ export function waitForClose(child) {
889
1782
  child.once('close', (code) => resolve(code ?? undefined));
890
1783
  });
891
1784
  }
1785
+ /**
1786
+ * Waits for a started launcher to exit, which precedes the close of its streams.
1787
+ *
1788
+ * @param child - The started launcher.
1789
+ * @returns When it exited or failed, in epoch milliseconds.
1790
+ */
1791
+ export function waitForExit(child) {
1792
+ return new Promise((resolve) => {
1793
+ child.once('error', () => resolve(Date.now()));
1794
+ child.once('exit', () => resolve(Date.now()));
1795
+ });
1796
+ }
892
1797
  /**
893
1798
  * Writes a run record, leaving an unwritten id to the handover reading.
894
1799
  *
@@ -915,64 +1820,469 @@ export function tryWriteRun(root, sequence, run) {
915
1820
  */
916
1821
  export function releaseTicket(root, sequence) {
917
1822
  try {
918
- removeFile(join(root, renderRunName(sequence)));
919
- removeFile(join(root, renderTicketName(sequence)));
1823
+ removeFile(join(root, renderName(sequence, RUN_SUFFIX)));
1824
+ removeFile(join(root, renderName(sequence, TICKET_SUFFIX)));
920
1825
  return undefined;
921
1826
  }
922
1827
  catch (error) {
923
1828
  return readCode(error);
924
1829
  }
925
1830
  }
1831
+ /**
1832
+ * Parses one sampler line.
1833
+ *
1834
+ * @param line - One line of the sampler's stdout, its rows separated by semicolons.
1835
+ * @returns One gauge per row that has the row's form, its CPU time in milliseconds.
1836
+ */
1837
+ export function parseGauges(line) {
1838
+ return line.split(';').flatMap((item) => {
1839
+ const match = GAUGE_PATTERN.exec(item.trim());
1840
+ return match === null
1841
+ ? []
1842
+ : [
1843
+ {
1844
+ pid: Number(match[1]),
1845
+ parent: Number(match[2]),
1846
+ created: Number(match[3]),
1847
+ cpu: Number(match[4]) / 10_000,
1848
+ memory: Number(match[5]),
1849
+ },
1850
+ ];
1851
+ });
1852
+ }
1853
+ /**
1854
+ * Waits for a promise within a bound.
1855
+ *
1856
+ * @param promise - The promise.
1857
+ * @param budget - The longest wait in milliseconds.
1858
+ * @returns The promise's value; undefined when the budget runs out first.
1859
+ */
1860
+ export async function waitForBound(promise, budget) {
1861
+ const timer = Promise.withResolvers();
1862
+ const handle = setTimeout(() => timer.resolve(undefined), budget);
1863
+ try {
1864
+ return await Promise.race([promise, timer.promise]);
1865
+ }
1866
+ finally {
1867
+ clearTimeout(handle);
1868
+ }
1869
+ }
1870
+ /**
1871
+ * Parses one sample line of a sampler.
1872
+ *
1873
+ * @param line - One line of the sampler's stdout: `1` or `0`, a `|`, and the rows.
1874
+ * @returns Whether a byte asked for the sample, with its gauges; undefined for a line without the
1875
+ * marker, such as {@link READY_LINE}.
1876
+ */
1877
+ export function parseSample(line) {
1878
+ const split = line.indexOf('|');
1879
+ if (split === -1)
1880
+ return undefined;
1881
+ return { requested: line.slice(0, split) === '1', gauges: parseGauges(line.slice(split + 1)) };
1882
+ }
1883
+ /**
1884
+ * Folds one sample's members into a tally.
1885
+ *
1886
+ * @param tally - The tally so far.
1887
+ * @param members - The members one sample read.
1888
+ * @returns The tally with each member's latest CPU time, keyed by id and creation date, and the
1889
+ * larger of each peak.
1890
+ */
1891
+ export function tallySample(tally, members) {
1892
+ return {
1893
+ cpu: new Map([
1894
+ ...tally.cpu,
1895
+ ...members.map((member) => {
1896
+ const key = `${String(member.pid)}:${String(member.created)}`;
1897
+ return [key, Math.max(member.cpu, tally.cpu.get(key) ?? 0)];
1898
+ }),
1899
+ ]),
1900
+ memory: Math.max(tally.memory, members.reduce((sum, member) => sum + member.memory, 0)),
1901
+ processes: Math.max(tally.processes, members.length),
1902
+ };
1903
+ }
1904
+ /**
1905
+ * Builds a run's record from its tally.
1906
+ *
1907
+ * @param tally - The sampler's tally.
1908
+ * @param duration - The run's duration in milliseconds.
1909
+ * @param code - The lane's exit code for the run.
1910
+ * @returns The record, its CPU time summed across every member the samples read.
1911
+ */
1912
+ export function buildOutcome(tally, duration, code) {
1913
+ return {
1914
+ duration,
1915
+ cpu: [...tally.cpu.values()].reduce((sum, value) => sum + value, 0),
1916
+ memory: tally.memory,
1917
+ processes: tally.processes,
1918
+ code,
1919
+ };
1920
+ }
1921
+ /**
1922
+ * Sets a process to below-normal priority, which a Windows child inherits.
1923
+ *
1924
+ * @param pid - The process id.
1925
+ * @returns True when the host took the priority; false when it refused.
1926
+ */
1927
+ export function lowerPriority(pid) {
1928
+ try {
1929
+ setPriority(pid, constants.priority.PRIORITY_BELOW_NORMAL);
1930
+ return true;
1931
+ }
1932
+ catch {
1933
+ return false;
1934
+ }
1935
+ }
1936
+ /**
1937
+ * Writes a run's record, leaving a write the host refuses unrecorded.
1938
+ *
1939
+ * @param root - The queue root.
1940
+ * @param key - The command's key.
1941
+ * @param name - The record's name.
1942
+ * @param outcome - The record.
1943
+ * @returns True when the write created the key's directory; false when the key existed or the host
1944
+ * refused the write.
1945
+ */
1946
+ export function tryWriteOutcome(root, key, name, outcome) {
1947
+ try {
1948
+ return writeOutcome(root, key, name, outcome);
1949
+ }
1950
+ catch {
1951
+ return false;
1952
+ }
1953
+ }
1954
+ /**
1955
+ * Samples one holder's process tree through one PowerShell child at below-normal priority.
1956
+ *
1957
+ * @remarks
1958
+ * The child starts at arrival and readies while the ticket waits, so a holder starts its command
1959
+ * only after the child can answer at once. A {@link Sampler.sample} call starts one sample at once;
1960
+ * after the first, the child also samples every {@link SAMPLE_MS}. The child exits when its stdin
1961
+ * closes, which {@link Sampler.stop} and the end of this process both do. A threshold, given for a
1962
+ * light run, calls the breach handler once with the launcher's id, on the first sample before
1963
+ * {@link Sampler.seal} whose memory or process count passes it.
1964
+ */
1965
+ export class Sampler {
1966
+ #child;
1967
+ #closed;
1968
+ #ready = Promise.withResolvers();
1969
+ #waiters = new Map();
1970
+ #threshold;
1971
+ #breach;
1972
+ #seeds = [];
1973
+ #floor;
1974
+ #ceiling;
1975
+ #tally = { cpu: new Map(), memory: 0, processes: 0 };
1976
+ #breached = false;
1977
+ #asked = 0;
1978
+ #answered = 0;
1979
+ /**
1980
+ * Starts the sampler.
1981
+ *
1982
+ * @param threshold - The light run's threshold, or undefined for a heavy run.
1983
+ * @param breach - Called once with the launcher's id when a sample passes the threshold. The
1984
+ * launcher is the one seed the lane holds a live handle on until it exits, so ending its tree
1985
+ * reaches the command and never a reused id.
1986
+ * @param command - The PowerShell text the child runs, for a proof. Default: {@link SAMPLER_COMMAND}.
1987
+ */
1988
+ constructor(threshold, breach, command = SAMPLER_COMMAND) {
1989
+ this.#threshold = threshold;
1990
+ this.#breach = breach;
1991
+ this.#child = spawn('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });
1992
+ this.#closed = waitForClose(this.#child).then(() => {
1993
+ this.#ready.resolve(false);
1994
+ for (const resolve of this.#waiters.values())
1995
+ resolve(undefined);
1996
+ this.#waiters.clear();
1997
+ });
1998
+ this.#child.stdin?.on('error', () => undefined);
1999
+ if (this.#child.pid !== undefined)
2000
+ lowerPriority(this.#child.pid);
2001
+ if (this.#child.stdout !== null) {
2002
+ const lines = createInterface({ input: this.#child.stdout, crlfDelay: Infinity });
2003
+ lines.on('error', () => undefined);
2004
+ lines.on('line', (line) => this.#read(line));
2005
+ }
2006
+ }
2007
+ /** Holds the sampler's process id, undefined when it could not start. */
2008
+ get pid() {
2009
+ return this.#child.pid;
2010
+ }
2011
+ /** Holds what the samples read so far. */
2012
+ get tally() {
2013
+ return this.#tally;
2014
+ }
2015
+ /** Holds whether a sample passed the threshold. */
2016
+ get breached() {
2017
+ return this.#breached;
2018
+ }
2019
+ /**
2020
+ * Waits until the child can sample at once, within a budget.
2021
+ *
2022
+ * @param budget - The longest wait in milliseconds.
2023
+ * @returns A promise of true when the child readied; false when it ended first or the budget ran out.
2024
+ */
2025
+ async ready(budget) {
2026
+ return (await waitForBound(this.#ready.promise, budget)) ?? false;
2027
+ }
2028
+ /**
2029
+ * Names the ids whose trees later samples read.
2030
+ *
2031
+ * @param seeds - The launcher id and, once known, the command id.
2032
+ * @param floor - The earliest creation date the tree can carry.
2033
+ */
2034
+ seed(seeds, floor) {
2035
+ this.#seeds = seeds;
2036
+ this.#floor = floor;
2037
+ }
2038
+ /**
2039
+ * Marks the launcher's exit: a later sample reads no member created after it and triggers no
2040
+ * breach, so a reused id after the exit is never ended.
2041
+ *
2042
+ * @param ceiling - When the launcher exited, in epoch milliseconds.
2043
+ */
2044
+ seal(ceiling) {
2045
+ this.#ceiling = ceiling;
2046
+ }
2047
+ /**
2048
+ * Starts one sample at once.
2049
+ *
2050
+ * @param budget - The longest wait in milliseconds for the answer. Default: no bound.
2051
+ * @returns A promise of every row the sample read, taken after this call; undefined when the
2052
+ * child ends first, cannot take the request, or does not answer within the budget.
2053
+ */
2054
+ sample(budget) {
2055
+ const stdin = this.#child.stdin;
2056
+ if (stdin === null ||
2057
+ stdin.writableEnded ||
2058
+ this.#child.pid === undefined ||
2059
+ this.#child.exitCode !== null ||
2060
+ this.#child.signalCode !== null) {
2061
+ return Promise.resolve(undefined);
2062
+ }
2063
+ this.#asked += 1;
2064
+ const answer = Promise.withResolvers();
2065
+ this.#waiters.set(this.#asked, answer.resolve);
2066
+ stdin.write(SAMPLE_BYTE);
2067
+ return budget === undefined ? answer.promise : waitForBound(answer.promise, budget);
2068
+ }
2069
+ /**
2070
+ * Samples back to back until a time or an abort, one sample after the previous one answers.
2071
+ *
2072
+ * @param until - The epoch millisecond after which no further sample starts.
2073
+ * @param signal - Ends the burst after the sample in flight.
2074
+ * @returns A promise that resolves when the burst ends.
2075
+ */
2076
+ async burst(until, signal) {
2077
+ const rows = await this.sample();
2078
+ if (rows === undefined || signal.aborted || Date.now() >= until)
2079
+ return;
2080
+ await this.burst(until, signal);
2081
+ }
2082
+ /**
2083
+ * Closes the sampler's stdin, which ends it, and ends the child at once when it has not exited
2084
+ * within {@link HANDOVER_MS}.
2085
+ *
2086
+ * @returns A promise that resolves when the sampler has exited.
2087
+ */
2088
+ async stop() {
2089
+ this.#child.stdin?.end();
2090
+ const exited = await waitForBound(this.#closed.then(() => true), HANDOVER_MS);
2091
+ if (exited === undefined)
2092
+ await this.destroy();
2093
+ }
2094
+ /**
2095
+ * Ends the child at once, for a sampler that did not ready and might not read its stdin.
2096
+ *
2097
+ * @returns A promise that resolves when the child has exited.
2098
+ */
2099
+ destroy() {
2100
+ this.#child.stdin?.end();
2101
+ this.#child.kill();
2102
+ return this.#closed;
2103
+ }
2104
+ // A sample a byte asked for answers the oldest open request, because the child answers bytes in order.
2105
+ #read(line) {
2106
+ if (line === READY_LINE) {
2107
+ this.#ready.resolve(true);
2108
+ return;
2109
+ }
2110
+ const sample = parseSample(line);
2111
+ if (sample === undefined)
2112
+ return;
2113
+ if (sample.requested) {
2114
+ this.#answered += 1;
2115
+ this.#waiters.get(this.#answered)?.(sample.gauges);
2116
+ this.#waiters.delete(this.#answered);
2117
+ }
2118
+ if (this.#floor === undefined)
2119
+ return;
2120
+ const members = selectMembers(sample.gauges, this.#seeds, this.#floor, this.#ceiling ?? Date.now());
2121
+ this.#tally = tallySample(this.#tally, members);
2122
+ const threshold = this.#threshold;
2123
+ if (threshold === undefined ||
2124
+ this.#ceiling !== undefined ||
2125
+ this.#breached ||
2126
+ (this.#tally.memory <= threshold.memory && this.#tally.processes <= threshold.processes)) {
2127
+ return;
2128
+ }
2129
+ const [launcher] = this.#seeds;
2130
+ if (launcher === undefined)
2131
+ return;
2132
+ this.#breached = true;
2133
+ this.#breach(launcher);
2134
+ }
2135
+ }
926
2136
  /**
927
2137
  * Runs the command as the holder, reads the tree at handover, and releases.
928
2138
  *
2139
+ * @remarks
2140
+ * A measured holder starts its command after its sampler readies, samples the tree back to back
2141
+ * through the command's first {@link SAMPLE_MS} and once every {@link SAMPLE_MS} after, reads the
2142
+ * handover through one more sample, and writes the run's record before it releases, so the command's
2143
+ * next arrival reads it. When that sample lists a member, the handover reads, kills, and reads again
2144
+ * through fresh snapshots, each a second PowerShell. A sampler that does not ready within
2145
+ * {@link READY_MS} is destroyed, and the command runs unmeasured and records nothing. A record that
2146
+ * opened a key prunes the history after the release. A light holder lowers its own priority before
2147
+ * the spawn, and ends its tree when a sample passes the threshold.
2148
+ *
929
2149
  * @param options - The run.
930
2150
  * @param launcher - The launcher's path.
931
2151
  * @param sequence - This process's sequence.
932
- * @returns The launcher's code; 1 when a signal ended it; 70 when the tree still reads as present or
933
- * the ticket could not be removed; 75 when the launcher could not start.
2152
+ * @param measure - What a measured holder needs, or undefined when no limits apply.
2153
+ * @param token - This process's endpoint, which holds after the run record exists and leaves before
2154
+ * the run record is removed.
2155
+ * @param sampler - The measured holder's sampler, started at arrival; the caller stops it.
2156
+ * @returns The launcher's code; 1 when a signal ended it; 69 when a light run passed its threshold;
2157
+ * 70 when the tree still reads as present or the ticket could not be removed; 75 when the launcher
2158
+ * could not start, the priority could not be lowered, or the run record could not be written.
934
2159
  */
935
- export async function runHolder(options, launcher, sequence) {
2160
+ export async function runHolder(options, launcher, sequence, measure, token, sampler) {
936
2161
  const { root } = options;
2162
+ if (measure?.light !== undefined && !lowerPriority(process.pid)) {
2163
+ releaseTicket(root, sequence);
2164
+ console.error('lane: the host refused the light run its below-normal priority');
2165
+ return 75;
2166
+ }
2167
+ const measured = sampler !== undefined && (await sampler.ready(READY_MS));
2168
+ if (sampler !== undefined && !measured) {
2169
+ await sampler.destroy();
2170
+ console.error(`lane: the sampler did not ready within ${String(READY_MS)} ms; ${quote(options.label)} runs unmeasured`);
2171
+ }
2172
+ const active = measured ? sampler : undefined;
937
2173
  const started = Date.now();
938
- writeRun(root, sequence, { started, launcher: undefined, command: undefined });
2174
+ if (!tryWriteRun(root, sequence, { started, launcher: undefined, command: undefined })) {
2175
+ const refusal = releaseTicket(root, sequence);
2176
+ console.error(`lane: the run record ${renderName(sequence, RUN_SUFFIX)} under ${root} could not be written; ${refusal === undefined ? 'the ticket was removed' : `removing the ticket reported ${refusal}`}`);
2177
+ return refusal === undefined ? 75 : HELD_CODE;
2178
+ }
2179
+ token?.hold();
939
2180
  const child = startLauncher(launcher, options);
940
2181
  const id = child.pid;
941
2182
  if (id === undefined) {
2183
+ token?.leave();
942
2184
  releaseTicket(root, sequence);
943
2185
  console.error(`lane: ${quote(launcher)} could not start`);
944
2186
  return 75;
945
2187
  }
946
2188
  tryWriteRun(root, sequence, { started, launcher: id, command: undefined });
2189
+ const floor = started - CLOCK_ALLOWANCE_MS;
2190
+ const early = new AbortController();
2191
+ active?.seed([id], floor);
947
2192
  const unwatch = watchSignals(() => killMembers([id]));
948
2193
  const closed = waitForClose(child);
2194
+ const exited = waitForExit(child).then((at) => {
2195
+ active?.seal(at);
2196
+ return at;
2197
+ });
949
2198
  if (child.stdout !== null) {
950
2199
  const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
951
2200
  lines.on('error', () => undefined);
952
2201
  lines.on('line', (line) => {
953
2202
  console.log(line);
954
2203
  const command = readCommandId(line);
955
- if (command !== undefined)
956
- tryWriteRun(root, sequence, { started, launcher: id, command });
2204
+ if (command === undefined)
2205
+ return;
2206
+ tryWriteRun(root, sequence, { started, launcher: id, command });
2207
+ active?.seed([id, command], floor);
2208
+ void active?.burst(Date.now() + SAMPLE_MS, early.signal);
957
2209
  });
958
2210
  }
959
2211
  const code = await closed;
2212
+ const ended = await exited;
2213
+ early.abort();
960
2214
  unwatch();
961
- const ended = Date.now();
962
2215
  const run = readRun(root, sequence);
963
- const sweep = run === 'absent' || run === 'unread'
2216
+ const rows = typeof run === 'object' ? await active?.sample(HANDOVER_MS) : undefined;
2217
+ const hung = active !== undefined && typeof run === 'object' && rows === undefined;
2218
+ if (hung) {
2219
+ await active.destroy();
2220
+ console.error(`lane: the sampler did not answer the handover within ${String(HANDOVER_MS)} ms; ${quote(options.label)} records nothing`);
2221
+ }
2222
+ const quick = rows !== undefined && typeof run === 'object' ? selectTree(rows, run, ended) : undefined;
2223
+ const sweep = typeof run !== 'object'
964
2224
  ? { gone: false, members: [] }
965
- : sweepTree(() => readTree(run, ended), killMembers, KILL_BUDGET);
2225
+ : quick?.length === 0
2226
+ ? { gone: true, members: [] }
2227
+ : sweepTree(() => readTree(run, ended), killMembers, KILL_BUDGET);
2228
+ const stopped = active?.stop();
2229
+ const breached = active?.breached === true;
2230
+ const result = !sweep.gone ? HELD_CODE : breached ? BREACH_CODE : (code ?? 1);
2231
+ const opened = measure !== undefined &&
2232
+ active !== undefined &&
2233
+ !hung &&
2234
+ tryWriteOutcome(root, measure.key, renderOutcomeName(ended, measure.token), buildOutcome(active.tally, ended - started, result));
966
2235
  if (!sweep.gone) {
967
- console.error(`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}`);
968
- return 70;
2236
+ console.error(`lane: the tree of ${quote(options.label)} still reads as ${sweep.members.length === 0 ? 'unread' : `present: ${sweep.members.join(', ')}`}; the lane stays held by ${renderName(sequence, TICKET_SUFFIX)} and ${renderName(sequence, RUN_SUFFIX)} under ${root}`);
2237
+ await stopped;
2238
+ return HELD_CODE;
969
2239
  }
2240
+ token?.leave();
970
2241
  const refusal = releaseTicket(root, sequence);
2242
+ const prune = opened ? pruneHistory(root, Date.now()) : undefined;
2243
+ if (prune !== undefined && prune.skipped.length > 0) {
2244
+ console.error(`lane: the history prune under ${root} skipped ${String(prune.skipped.length)} entries it could not list or remove, such as ${quote(prune.skipped.join(', '))}`);
2245
+ }
2246
+ await stopped;
971
2247
  if (refusal !== undefined) {
972
- console.error(`lane: removing ${renderTicketName(sequence)} reported ${refusal}`);
973
- return 70;
2248
+ console.error(`lane: removing ${renderName(sequence, TICKET_SUFFIX)} reported ${refusal}`);
2249
+ return HELD_CODE;
2250
+ }
2251
+ if (breached) {
2252
+ console.error(`lane: ${quote(options.label)} passed the light threshold and was ended; its next arrival runs heavy`);
2253
+ }
2254
+ return result;
2255
+ }
2256
+ /**
2257
+ * Reads what a run measures at arrival: the limits, the command's key, and its light footprint.
2258
+ *
2259
+ * @remarks
2260
+ * A host other than Windows has no sampler, so it measures nothing and every ticket there is heavy.
2261
+ * A `--solo` run is heavy whatever its command reads. A `mutate` run is keyed without its edits
2262
+ * file and seeded by its wrapped command; {@link decideDirectory} keeps it apart from the tickets of
2263
+ * its working directory.
2264
+ *
2265
+ * @param options - The run.
2266
+ * @param token - This process's token.
2267
+ * @returns What the holder measures, or undefined when `limits.json` is absent or malformed or the
2268
+ * host has no sampler.
2269
+ */
2270
+ export function readMeasure(options, token) {
2271
+ if (process.platform !== 'win32')
2272
+ return undefined;
2273
+ const limits = readLimits(options.root);
2274
+ if (limits === 'unread') {
2275
+ console.error(`lane: ${LIMITS_FILE} under ${options.root} cannot be read as limits; the ticket runs heavy`);
974
2276
  }
975
- return code ?? 1;
2277
+ if (limits === 'absent' || limits === 'unread')
2278
+ return undefined;
2279
+ const key = renderKey(normalizeDirectory(process.cwd()), normalizeCommand(options.command));
2280
+ if (options.solo)
2281
+ return { limits, key, token, light: undefined };
2282
+ const mutation = extractMutation(options.command);
2283
+ const seed = readSeed(mutation ?? options.command);
2284
+ const light = classifyLight(seed, readOutcomes(options.root, key), limits);
2285
+ return { limits, key, token, light };
976
2286
  }
977
2287
  /**
978
2288
  * Takes a ticket, waits for this process's turn, and runs the command.
@@ -987,23 +2297,34 @@ export async function enterLane(options, launcher, tokenId, token) {
987
2297
  const { root } = options;
988
2298
  try {
989
2299
  mkdirSync(root, { recursive: true });
990
- await token.listen(renderEndpoint(root, tokenId));
991
- writeStage(root, buildTicket(tokenId, options.label));
992
- const sequence = linkStage(root, tokenId);
993
- removeFile(join(root, `${tokenId}${STAGE_SUFFIX}`));
994
- token.publish();
995
- const unwatch = watchSignals(() => {
996
- removeFile(join(root, renderTicketName(sequence)));
997
- removeFile(renderEndpoint(root, tokenId));
998
- process.exit(75);
999
- });
1000
- const refusal = await waitForTurn(root, sequence, tokenId);
1001
- unwatch();
1002
- if (refusal === undefined)
1003
- return await runHolder(options, launcher, sequence);
1004
- removeFile(join(root, renderTicketName(sequence)));
1005
- console.error(`lane: ${refusal}`);
1006
- return 75;
2300
+ const measure = readMeasure(options, tokenId);
2301
+ const sampler = measure === undefined
2302
+ ? undefined
2303
+ : new Sampler(measure.light === undefined ? undefined : measure.limits.threshold, (pid) => killMembers([pid]));
2304
+ try {
2305
+ await token.listen(renderEndpoint(root, tokenId));
2306
+ const edits = extractMutation(options.command) !== undefined || matchesRestore(options.command);
2307
+ writeStage(root, buildTicket(tokenId, options.label, measure?.light, options.solo, edits));
2308
+ const sequence = linkStage(root, tokenId);
2309
+ removeFile(join(root, `${tokenId}${STAGE_SUFFIX}`));
2310
+ token.publish();
2311
+ const unwatch = watchSignals(() => {
2312
+ removeFile(join(root, renderName(sequence, TICKET_SUFFIX)));
2313
+ removeFile(renderEndpoint(root, tokenId));
2314
+ process.exit(75);
2315
+ });
2316
+ const refusal = await waitForTurn(root, sequence, tokenId, measure?.limits);
2317
+ unwatch();
2318
+ if (refusal === undefined) {
2319
+ return await runHolder(options, launcher, sequence, measure, token, sampler);
2320
+ }
2321
+ removeFile(join(root, renderName(sequence, TICKET_SUFFIX)));
2322
+ console.error(`lane: ${refusal}`);
2323
+ return 75;
2324
+ }
2325
+ finally {
2326
+ await sampler?.stop();
2327
+ }
1007
2328
  }
1008
2329
  catch (error) {
1009
2330
  console.error(`lane: the queue under ${root} refused the run: ${String(error)}`);
@@ -1036,40 +2357,61 @@ export async function runLane(options) {
1036
2357
  */
1037
2358
  export async function readStatusRow(root, entry) {
1038
2359
  const ticket = entry.ticket;
1039
- const fields = { sequence: entry.sequence, label: ticket?.label, pid: ticket?.pid };
2360
+ const fields = {
2361
+ sequence: entry.sequence,
2362
+ label: ticket?.label,
2363
+ pid: ticket?.pid,
2364
+ light: ticket?.light !== undefined,
2365
+ solo: ticket?.solo === true,
2366
+ edits: ticket?.edits === true,
2367
+ };
1040
2368
  if (ticket === undefined || describeForeign(ticket) !== undefined) {
1041
- return { ...fields, state: 'unread' };
2369
+ return { ...fields, state: 'unread', holding: false };
1042
2370
  }
1043
- const code = await probeEndpoint(renderEndpoint(root, ticket.token));
1044
- if (code === undefined)
1045
- return { ...fields, state: 'live' };
1046
- return { ...fields, state: isGone(code) ? 'dead' : 'unread' };
2371
+ const probe = new AbortController();
2372
+ const code = await parkOn(renderEndpoint(root, ticket.token), false, () => probe.abort(), probe.signal);
2373
+ if (code === undefined) {
2374
+ const holding = existsSync(join(root, renderName(entry.sequence, RUN_SUFFIX)));
2375
+ return { ...fields, state: 'live', holding };
2376
+ }
2377
+ return { ...fields, state: isGone(code) ? 'dead' : 'unread', holding: false };
1047
2378
  }
1048
2379
  /**
1049
2380
  * Reads the queue for `--status`.
1050
2381
  *
1051
2382
  * @param root - The queue root.
1052
- * @returns Every ticket in arrival order, and the earliest live ticket with a run record.
2383
+ * @returns Every ticket in arrival order, and the earliest holding ticket that is not light.
1053
2384
  */
1054
2385
  export async function readStatus(root) {
1055
2386
  const tickets = await Promise.all(readQueue(root).map((entry) => readStatusRow(root, entry)));
1056
- return {
1057
- tickets,
1058
- holder: tickets.find((row) => row.state === 'live' && existsSync(join(root, renderRunName(row.sequence)))),
1059
- };
2387
+ return { tickets, holder: tickets.find((row) => row.holding && !row.light) };
1060
2388
  }
1061
2389
  /**
1062
2390
  * Renders the queue as text.
1063
2391
  *
1064
2392
  * @param status - What `--status` read.
1065
- * @returns One line for the holder and one per ticket, in arrival order.
2393
+ * @returns One line for the heavy holder, one naming every light holder, and one per ticket with its
2394
+ * lane, in arrival order.
1066
2395
  */
1067
2396
  export function renderStatus(status) {
2397
+ const lights = status.tickets.filter((row) => row.holding && row.light);
1068
2398
  return [
1069
2399
  `holder: ${status.holder === undefined ? 'none' : quote(status.holder.label ?? 'unread')}`,
1070
- ...status.tickets.map((row) => `${renderTicketName(row.sequence)} ${row.state} ${quote(row.label ?? 'unread')} pid ${String(row.pid)}`),
2400
+ `light: ${lights.length === 0 ? 'none' : lights.map((row) => quote(row.label ?? 'unread')).join(', ')}`,
2401
+ ...status.tickets.map((row) => `${renderName(row.sequence, TICKET_SUFFIX)} ${row.state} ${renderLane(row)}${row.edits ? ' edits' : ''}${row.holding ? ' holding' : ''} ${quote(row.label ?? 'unread')} pid ${String(row.pid)}`),
1071
2402
  ].join('\n');
1072
2403
  }
2404
+ /**
2405
+ * Names a ticket's lane for `--status`.
2406
+ *
2407
+ * @param row - The ticket's row.
2408
+ * @returns `solo`, `light`, or `heavy`.
2409
+ */
2410
+ export function renderLane(row) {
2411
+ if (row.solo)
2412
+ return 'solo';
2413
+ return row.light ? 'light' : 'heavy';
2414
+ }
1073
2415
  /**
1074
2416
  * Prints the queue, writing nothing under the root.
1075
2417
  *
@@ -1088,31 +2430,48 @@ export async function runStatus(root, json) {
1088
2430
  return 75;
1089
2431
  }
1090
2432
  }
2433
+ /**
2434
+ * Parses a cap given in seconds.
2435
+ *
2436
+ * @param text - The value after `--cap`.
2437
+ * @returns The cap, or undefined when the text is absent, not a finite number, not above 0, or past
2438
+ * the launcher's limit.
2439
+ */
2440
+ export function parseCap(text) {
2441
+ const cap = Number(text ?? Number.NaN);
2442
+ return Number.isFinite(cap) && cap > 0 && cap <= MAX_CAP_SECONDS ? cap : undefined;
2443
+ }
1091
2444
  /**
1092
2445
  * Validates a run's arguments.
1093
2446
  *
1094
- * @param own - The arguments before the bare `--`.
2447
+ * @param values - The flag values `parseArgs` read before the bare `--`.
1095
2448
  * @param command - The arguments after the bare `--`.
1096
2449
  * @returns The run, or undefined when a flag or the command is missing or out of range.
1097
2450
  */
1098
- export function readLaneOptions(own, command) {
1099
- const label = readOption(own, '--label');
1100
- const journal = readOption(own, '--journal');
1101
- const errors = readOption(own, '--errors');
1102
- const cap = Number(readOption(own, '--cap') ?? Number.NaN);
2451
+ export function readLaneOptions(values, command) {
2452
+ const label = typeof values.label === 'string' ? values.label : undefined;
2453
+ const journal = typeof values.journal === 'string' ? values.journal : undefined;
2454
+ const errors = typeof values.errors === 'string' ? values.errors : undefined;
2455
+ const cap = parseCap(typeof values.cap === 'string' ? values.cap : undefined);
1103
2456
  if (label === undefined ||
1104
2457
  label === '' ||
1105
2458
  journal === undefined ||
1106
2459
  errors === undefined ||
1107
2460
  journal === errors ||
1108
- !Number.isFinite(cap) ||
1109
- cap <= 0 ||
1110
- cap > MAX_CAP_SECONDS ||
2461
+ cap === undefined ||
1111
2462
  command[0] === undefined ||
1112
2463
  command[0] === '') {
1113
2464
  return undefined;
1114
2465
  }
1115
- return { root: resolveRoot(readOption(own, '--root')), label, journal, errors, cap, command };
2466
+ return {
2467
+ root: resolveRoot(typeof values.root === 'string' ? values.root : undefined),
2468
+ label,
2469
+ journal,
2470
+ errors,
2471
+ cap,
2472
+ solo: values.solo === true,
2473
+ command,
2474
+ };
1116
2475
  }
1117
2476
  /**
1118
2477
  * Runs the script on its arguments.
@@ -1125,31 +2484,27 @@ export function readLaneOptions(own, command) {
1125
2484
  */
1126
2485
  export async function main(argv) {
1127
2486
  const end = argv.indexOf('--');
1128
- const own = end === -1 ? argv : argv.slice(0, end);
1129
2487
  const command = end === -1 ? [] : argv.slice(end + 1);
1130
- const unknown = readUnknownFlags(argv, FLAGS);
1131
- if (unknown.length > 0) {
1132
- console.error(`lane: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
2488
+ const parsed = parseArguments(end === -1 ? argv : argv.slice(0, end));
2489
+ if (!parsed.success) {
2490
+ console.error(`lane: ${parsed.error}; ${USAGE}`);
1133
2491
  return 64;
1134
2492
  }
1135
- const missing = readMissingFlags(own, VALUE_FLAGS);
1136
- if (missing.length > 0) {
1137
- console.error(`lane: ${missing.join(', ')} given with no value; ${USAGE}`);
1138
- return 64;
1139
- }
1140
- if (readPositionals(own, VALUE_FLAGS).length > 0) {
1141
- console.error(USAGE);
1142
- return 64;
1143
- }
1144
- const status = own.includes('--status');
1145
- if (status) {
1146
- if (end !== -1 || RUN_FLAGS.some((flag) => own.includes(flag))) {
2493
+ const { values } = parsed.value;
2494
+ const root = typeof values.root === 'string' ? values.root : undefined;
2495
+ if (values.status === true) {
2496
+ if (end !== -1 || RUN_OPTIONS.some((name) => values[name] !== undefined)) {
1147
2497
  console.error(`lane: --status and a run are two modes; ${USAGE}`);
1148
2498
  return 64;
1149
2499
  }
1150
- return runStatus(resolveRoot(readOption(own, '--root')), own.includes('--json'));
2500
+ return runStatus(resolveRoot(root), values.json === true);
2501
+ }
2502
+ const cap = typeof values.cap === 'string' ? values.cap : undefined;
2503
+ if (cap !== undefined && parseCap(cap) === undefined) {
2504
+ console.error(`lane: --cap takes a number of seconds above 0 up to ${String(MAX_CAP_SECONDS)}, not ${quote(cap)}; ${USAGE}`);
2505
+ return 64;
1151
2506
  }
1152
- const options = own.includes('--json') ? undefined : readLaneOptions(own, command);
2507
+ const options = values.json === true ? undefined : readLaneOptions(values, command);
1153
2508
  if (options === undefined) {
1154
2509
  console.error(USAGE);
1155
2510
  return 64;