@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,29 +1,75 @@
1
- // Run one process-running command at a time on this host, in arrival order, across every checkout
2
- // and shell of one user account. Run from the checkout root:
3
- // node .agents/skills/orkestrel-parallel/scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] -- COMMAND [ARGS...]
1
+ // Run process-running commands on this host in one heavy lane and several light lanes, in arrival
2
+ // order, across every checkout and shell of one user account. Run from the checkout root:
3
+ // node .agents/skills/orkestrel-parallel/scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] [--solo] -- COMMAND [ARGS...]
4
4
  // node .agents/skills/orkestrel-parallel/scripts/lane.ts --status [--root DIR] [--json]
5
- // A run takes a ticket, waits for every earlier ticket, runs the command through the dispatch skill's
6
- // `launch` script, reads the process tree, and releases. The launcher owns the cap, the journal, and
7
- // the errors file; its stdout lines pass through verbatim, and the cap must be above 0. The two forms
8
- // are two operation modes, so `--status` with a run's flag or a bare `--` is refused, and `--json`
9
- // belongs to `--status` alone. A run therefore cannot ask the launcher for its own `--status` files.
10
- // `--status` prints each ticket in arrival order with its label and
11
- // `live`, `dead`, or `unread`, and names the holder: the earliest live ticket with a run record. It
12
- // writes nothing, removes nothing, and creates no root; an absent root reads as an empty queue. The
13
- // root is `.orkestrel/lane` under the account's home directory, read from the account record and
14
- // never from an environment variable; `--root DIR` is for a proof. Bench execs stay outside the lane,
15
- // because the host bound counts process-running commands.
5
+ // A run takes a ticket, waits for its turn, runs the command through the dispatch skill's `launch`
6
+ // script, reads the process tree, and releases. The launcher owns the cap, the journal, and the
7
+ // errors file; its stdout lines pass through verbatim, and the cap must be above 0. The script reads
8
+ // its flags before the first bare `--` with `parseArgs` in strict mode, and passes every argument
9
+ // after it to the command. The two forms are two operation modes, so `--status` with a run's flag
10
+ // (`--solo` included) or a bare `--` is refused, and `--json` belongs to `--status` alone. A run
11
+ // therefore cannot ask the launcher for its own `--status` files.
12
+ // Lanes: a ticket is heavy unless its arrival reads it light, and the reading is frozen in the
13
+ // ticket. A heavy ticket holds when it is the earliest live non-light ticket; a `--solo` ticket is
14
+ // heavy and also waits out every earlier light ticket. A light ticket holds when every earlier light
15
+ // ticket that the directory rule does not block holds, no earlier `--solo` ticket is live, and the
16
+ // earlier light tickets' summed peaks with its own fit `slots` and each budget; the earliest light
17
+ // ticket always fits. A light holder runs at below-normal priority, and its holder ends it and exits
18
+ // 69 when a sample taken before the launcher exits passes the memory or process threshold; a sample
19
+ // after the exit reads no member created after it and ends nothing.
20
+ // Directories: a run of the falsify skill's `mutate` script, `--restore` included, publishes
21
+ // `edits` in its ticket, because it edits source in its working directory. Every ticket also waits
22
+ // on the nearest earlier ticket that carries `edits` and shares its working directory, and a ticket
23
+ // that carries `edits` also waits on the nearest earlier ticket of its working directory in either
24
+ // lane, and on an earlier ticket it cannot read. That last wait is the lane's existing refusal,
25
+ // because a ticket's endpoint token lives in its record, so a mutation exits 75 on any unreadable
26
+ // earlier ticket, one a writer has not finished included. Two directories share source when their
27
+ // real paths, as the file system stores them, are equal or one sits inside the other. Every wait
28
+ // names an earlier ticket, so no cycle of waits forms, and each process derives from the earlier
29
+ // tickets alone which light tickets the rule blocks.
30
+ // Light reading: `<root>/limits.json` holds `slots`, the `budget` and the per-run `threshold`; while
31
+ // it is absent or malformed, or on a host other than Windows, every ticket is heavy, no sampler runs,
32
+ // and no record is written. Otherwise each run starts one PowerShell sampler at arrival, which readies
33
+ // while the ticket waits, with no timer until its first sample, and exits when its stdin closes. The
34
+ // holder starts its command after the sampler readies, or unmeasured once `READY_MS` passes, samples
35
+ // the tree back to back through the command's first second and once a second after, and reads the
36
+ // handover through one more sample; when that sample lists a member or no sampler answers, the
37
+ // handover reads, kills, and reads again through fresh snapshots, each a second PowerShell. The
38
+ // holder writes one record per run under `<root>/history/<key>/`, keyed by the working directory and
39
+ // the command, keeping the latest runs. A record that opens a key prunes the history after the
40
+ // release, keeping only the keys written inside `HISTORY_AGE_MS` (7 days), and of those at most the
41
+ // `HISTORY_KEYS` (512) written last; a
42
+ // name it cannot list or remove stays, one stderr line names it, and the exit stays the run's. The
43
+ // command's kind seeds the reading: a format check, a lint check, a type check, and a scoped test run
44
+ // read light until a record breaches; a full suite, a run of several projects, an install, a
45
+ // pack-and-install suite, a release chain, a journey, a study, a capture, and a live-service run read
46
+ // heavy; `npx` and a package manager's `exec`, `x`, or `dlx` verb read as the tool they run; any other
47
+ // command reads light only when its latest runs each sit inside the threshold, none capped and none
48
+ // ending 69 or 70. A `mutate` run is keyed without its edits file and seeded by the command after its
49
+ // own `--`, so it reads light when that command's records allow; a `mutate --restore` run wraps no
50
+ // command and reads heavy.
51
+ // `--status` prints each ticket in arrival order with its label, `live`, `dead`, or `unread`, its
52
+ // lane, `edits` for a `mutate` run, and `holding` for a holder, and names the heavy holder and every
53
+ // light holder. It writes nothing, removes nothing, and creates no root; an absent root reads as an
54
+ // empty queue. The root is `.orkestrel/lane` under the account's home directory, read from the
55
+ // account record and never from an environment variable; `--root DIR` is for a proof. Bench execs
56
+ // stay outside the lane, because the host bound counts process-running commands.
16
57
  // Exit: the launcher's code (the command's code, 124 when capped, 127 when the command could not
17
- // start); 1 when a signal ended the launcher; 64 on usage; 75 when the lane refused before the
18
- // command ran; 70 when the command ran and its tree still reads as present, or its ticket could not
19
- // be removed. `--status` exits 0 on a read and 75 when the root cannot be listed. A command that itself
20
- // exits 64, 70, or 75 reads like the lane's own code.
58
+ // start); 1 when a signal ended the launcher; 64 on usage; 69 when a light run passed its threshold
59
+ // and its holder ended it; 75 when the lane refused before the command ran; 70 when the command ran
60
+ // and its tree still reads as present, or its ticket could not be removed. `--status` exits 0 on a
61
+ // read and 75 when the root cannot be listed. A command that itself exits 64, 69, 70, or 75 reads
62
+ // like the lane's own code.
21
63
  // Protocol: a process listens on an endpoint named by a random token, writes the complete ticket to
22
64
  // `<token>.stage`, and hard-links that file to `<sequence>.ticket`, which publishes it in one step.
23
- // A waiter parks on the `close` of the nearest earlier ticket's endpoint with no timer, and a refused
24
- // connect means that owner is gone. A waiter on a stage file writes one byte, and a published owner
25
- // closes that connection, because a connection its synchronous allocation left unaccepted would
26
- // otherwise stay parked on a process that waits behind it.
65
+ // A waiter parks on the `close` of each earlier ticket's endpoint it waits on with no timer, and a
66
+ // refused connect means that owner is gone. A waiter on a stage file writes one byte, and a published
67
+ // owner closes that connection, because a connection its synchronous allocation left unaccepted
68
+ // would otherwise stay parked on a process that waits behind it. A light waiter writes `h` to an
69
+ // earlier light ticket that did not hold yet, and that owner closes the connection when it holds,
70
+ // so the waiter decides again; a byte that reaches an owner that is releasing parks until it ends.
71
+ // The protocol stays 1: the `light`, `solo`, and `edits` ticket fields are optional, a ticket
72
+ // without them reads as heavy, and a process of the first release holds only as the earliest ticket.
27
73
  // Limits:
28
74
  // - Process-identifier reuse, Windows. A row is matched by id and creation date, bounded by a clock
29
75
  // comparison, so a reuse of an exited seed's id inside the clock allowance can misattribute a row.
@@ -41,6 +87,36 @@
41
87
  // - An owner ended between the run record and the launcher id. The tree cannot be identified. Arrivals
42
88
  // exit 75 until a person deletes the named files. An owner ended between the launcher id and the
43
89
  // command id leaves the command as no seed, so its tree reads through the launcher alone.
90
+ // - A dead light holder with a live tree. Light arrivals exit 75 until that tree is gone. A heavy
91
+ // arrival passes it, unless the directory rule points the arrival at it; that arrival waits on it,
92
+ // then exits 75 while its tree lives.
93
+ // - Sampling. A process that lives between two samples goes uncounted, the CPU time of a member that
94
+ // exits between samples is lost, and disk input and output are not measured. A command that ends
95
+ // before one process query answers, about 140 ms on the Windows host measured 2026-11-12, can
96
+ // record zero, so it counts nothing until a later run is read.
97
+ // - Transition. A process of an earlier release reads no `edits` field: it does not wait on a mutation
98
+ // of its directory, a `mutate` run it carries publishes no `edits`, so the directory rule cannot see
99
+ // that run, and as a light ticket it counts a directory-blocked light ticket of this release as one
100
+ // that has not held, so it queues behind it. Every checkout on an earlier `@orkestrel/scaffold`
101
+ // keeps starting such processes on the shared root until that checkout adopts this release, so the
102
+ // bound is the last adoption, not one process's exit. A mutation of this release does wait on an
103
+ // earlier ticket of its directory, whichever release wrote it.
104
+ // - Heavy throughput. A heavy ticket that the directory rule blocks still keeps every later heavy
105
+ // ticket out, from every directory, because passing it would let two heavy tickets hold at once.
106
+ // - Light budget. A light ticket that the directory rule blocks is not one later light tickets wait to
107
+ // hold, but its footprint still counts in their budget sums and their slot count. Where the per-run
108
+ // threshold is over the budget, as in the live `limits.json` of 2026-11-12, one blocked ticket with
109
+ // fewer than `RECENT_RUNS` records fills the budget, so every later light ticket on the host queues
110
+ // until the mutation ends and that ticket has run and left. The count stays, because leaving the ticket out and
111
+ // counting later holders when it unblocks would race two processes on one budget.
112
+ // - The ready wait. A holder waits for its sampler before it writes its run record and signals that
113
+ // it holds, so later light tickets count it as one that has not held for up to `READY_MS` when its
114
+ // sampler never reports ready.
115
+ // - The idle sampler. Each queued measured ticket keeps its PowerShell sampler from arrival, about
116
+ // 75 MB of private memory once ready on the Windows host measured 2026-11-13, and no budget counts
117
+ // that memory, so a long queue of measured tickets costs that much per ticket.
118
+ // - A prune beside a write. A holder that writes a record to an existing key that is past a bound can
119
+ // lose that record to another holder's prune, which removes the key with the record in it.
44
120
  // - An unreaped member. On a host whose init does not reap, a killed member can keep reading as
45
121
  // present. The lane exits 70 and stays held.
46
122
  // - Listing completeness. No probe proves that a listing returns every stable entry. The design takes
@@ -54,10 +130,12 @@
54
130
  // Migration stop: a second queue does not see the first, so while a host's sessions run another
55
131
  // serializer, no caller moves. After a scaffold release carries this script and no command runs on the
56
132
  // host, move every caller in one step and delete the serializer this replaces.
133
+ import type { ParseArgsOptionsConfig } from 'node:util'
57
134
  import type { ChildProcess } from 'node:child_process'
58
135
  import type { Server, Socket } from 'node:net'
59
136
  import { spawn, spawnSync } from 'node:child_process'
60
- import { randomUUID } from 'node:crypto'
137
+ import { createHash, randomUUID } from 'node:crypto'
138
+ import { once } from 'node:events'
61
139
  import {
62
140
  existsSync,
63
141
  linkSync,
@@ -66,35 +144,78 @@ import {
66
144
  readFileSync,
67
145
  realpathSync,
68
146
  rmSync,
147
+ statSync,
69
148
  writeFileSync,
70
149
  } from 'node:fs'
71
150
  import { connect, createServer } from 'node:net'
72
- import { hostname, userInfo } from 'node:os'
73
- import { dirname, extname, join } from 'node:path'
151
+ import { constants, hostname, setPriority, userInfo } from 'node:os'
152
+ import {
153
+ basename,
154
+ dirname,
155
+ extname,
156
+ isAbsolute,
157
+ join,
158
+ resolve as resolvePath,
159
+ sep,
160
+ } from 'node:path'
74
161
  import { createInterface } from 'node:readline'
75
162
  import { fileURLToPath } from 'node:url'
163
+ import { parseArgs } from 'node:util'
76
164
 
77
165
  /** Holds the protocol version a ticket carries, so a process refuses a ticket it cannot read. */
78
166
  export const PROTOCOL = 1
79
167
 
80
- /** Lists the flags that take a value. */
81
- export const VALUE_FLAGS: readonly string[] = [
82
- '--label',
83
- '--journal',
84
- '--errors',
85
- '--cap',
86
- '--root',
87
- ]
88
-
89
- /** Lists the flags only a run reads, which `--status` refuses. */
90
- export const RUN_FLAGS: readonly string[] = ['--label', '--journal', '--errors', '--cap']
91
-
92
- /** Lists every flag the script reads, value flags and switches alike. */
93
- export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--status', '--json']
168
+ /** Lists the flags only a run reads, which `--status` refuses, by the name `parseArgs` reads them under. */
169
+ export const RUN_OPTIONS: readonly string[] = ['label', 'journal', 'errors', 'cap', 'solo']
94
170
 
95
171
  /** Holds the usage line printed on a usage refusal. */
96
172
  export const USAGE =
97
- 'usage: lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] -- COMMAND [ARGS...] | lane.ts --status [--root DIR] [--json]; the journal and the errors file differ, and the cap is a number of seconds above 0 up to 2147483'
173
+ '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'
174
+
175
+ /** Declares every flag the script reads, for `parseArgs`. */
176
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
177
+ label: Object.freeze({ type: 'string' }),
178
+ journal: Object.freeze({ type: 'string' }),
179
+ errors: Object.freeze({ type: 'string' }),
180
+ cap: Object.freeze({ type: 'string' }),
181
+ root: Object.freeze({ type: 'string' }),
182
+ status: Object.freeze({ type: 'boolean' }),
183
+ json: Object.freeze({ type: 'boolean' }),
184
+ solo: Object.freeze({ type: 'boolean' }),
185
+ })
186
+
187
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
188
+ export interface Arguments {
189
+ readonly values: Readonly<
190
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
191
+ >
192
+ readonly positionals: readonly string[]
193
+ }
194
+
195
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
196
+ export type ArgumentsResult =
197
+ | { readonly success: true; readonly value: Arguments }
198
+ | { readonly success: false; readonly error: string }
199
+
200
+ /**
201
+ * Parses the arguments in strict mode against `OPTIONS`.
202
+ *
203
+ * @param argv - The arguments after the script path.
204
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
205
+ */
206
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
207
+ try {
208
+ const { values, positionals } = parseArgs({
209
+ args: [...argv],
210
+ options: OPTIONS,
211
+ strict: true,
212
+ allowPositionals: false,
213
+ })
214
+ return { success: true, value: { values, positionals } }
215
+ } catch (error) {
216
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
217
+ }
218
+ }
98
219
 
99
220
  /** Holds the longest cap in whole seconds, equal to the limit of the sibling launcher. */
100
221
  export const MAX_CAP_SECONDS = 2_147_483
@@ -102,6 +223,9 @@ export const MAX_CAP_SECONDS = 2_147_483
102
223
  /** Holds the digit count of a ticket name, which keeps a directory listing readable in order. */
103
224
  export const SEQUENCE_WIDTH = 12
104
225
 
226
+ /** Holds the byte a light waiter writes to an earlier light ticket that does not hold yet. */
227
+ export const HOLD_BYTE = 'h'
228
+
105
229
  /** Holds the name ending of a stage file. */
106
230
  export const STAGE_SUFFIX = '.stage'
107
231
 
@@ -162,7 +286,278 @@ export const REMOVAL_DELAY_MS = 100
162
286
  export const SNAPSHOT_COMMAND =
163
287
  "Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate | Where-Object { $_.CreationDate } | ForEach-Object { '{0} {1} {2}' -f $_.ProcessId, $_.ParentProcessId, ([DateTimeOffset]$_.CreationDate).ToUnixTimeMilliseconds() }"
164
288
 
165
- /** Describes the complete record a stage file holds and a ticket publishes. */
289
+ /** Holds the name of the file under the root that holds the light lanes' limits. */
290
+ export const LIMITS_FILE = 'limits.json'
291
+
292
+ /** Holds the name of the directory under the root that holds each command's run records. */
293
+ export const HISTORY_DIRECTORY = 'history'
294
+
295
+ /** Holds the name ending of a run record under the history directory. */
296
+ export const OUTCOME_SUFFIX = '.json'
297
+
298
+ /** Holds the digit count of the end time that opens a record's name, which keeps a listing in time order. */
299
+ export const ENDED_WIDTH = 15
300
+
301
+ /** Holds the count of latest records the light reading takes, which is also the count each key keeps. */
302
+ export const RECENT_RUNS = 3
303
+
304
+ /** Holds the age in milliseconds past which a history key is pruned. */
305
+ export const HISTORY_AGE_MS = 7 * 24 * 60 * 60 * 1000
306
+
307
+ /** Holds the count of history keys kept, the latest by their newest record. */
308
+ export const HISTORY_KEYS = 512
309
+
310
+ /**
311
+ * Holds the longest wait in milliseconds for a sampler to ready before its holder starts the command
312
+ * unmeasured.
313
+ *
314
+ * @remarks
315
+ * The wait outlasts a sampler's start on a loaded host, and it bounds what a sampler that neither
316
+ * readies nor exits costs the lane.
317
+ */
318
+ export const READY_MS = 5000
319
+
320
+ /**
321
+ * Holds the longest wait in milliseconds for a sampler's handover sample and for its exit after its
322
+ * stdin closes.
323
+ *
324
+ * @remarks
325
+ * A warm process query answered in about 140 ms on the Windows host measured 2026-11-12, so the wait
326
+ * outlasts a query on a loaded host, and it bounds what a sampler that hangs after it readied costs
327
+ * the lane at handover.
328
+ */
329
+ export const HANDOVER_MS = 5000
330
+
331
+ /** Holds the pause in milliseconds between two samples of a holder's tree. */
332
+ export const SAMPLE_MS = 1000
333
+
334
+ /** Holds the exit code of a light run its holder ended at a threshold. */
335
+ export const BREACH_CODE = 69
336
+
337
+ /** Holds the exit code of a run whose tree still reads as present at handover. */
338
+ export const HELD_CODE = 70
339
+
340
+ /** Holds the launcher's exit code at the cap. */
341
+ export const CAPPED_CODE = 124
342
+
343
+ /** Lists the words that seed a command heavy: a journey, a study, a capture, a live-service run, and a release chain. */
344
+ export const HEAVY_WORDS: readonly string[] = [
345
+ 'journey',
346
+ 'journeys',
347
+ 'study',
348
+ 'studies',
349
+ 'capture',
350
+ 'captures',
351
+ 'live',
352
+ 'prepublishonly',
353
+ ]
354
+
355
+ /** Lists the package-manager verbs that seed a command heavy: an install, a full suite, and a publish. */
356
+ export const HEAVY_VERBS: readonly string[] = [
357
+ 'ci',
358
+ 'i',
359
+ 'install',
360
+ 'add',
361
+ 'update',
362
+ 'rebuild',
363
+ 'uninstall',
364
+ 'publish',
365
+ 'test',
366
+ 't',
367
+ ]
368
+
369
+ /**
370
+ * Lists the package scripts a seed reads heavy: the full suite, the aggregates that build and run
371
+ * several projects, the pack-and-install suite, the live-service suite, and the benchmark run.
372
+ */
373
+ export const HEAVY_SCRIPTS: readonly string[] = [
374
+ 'test',
375
+ 'test:src',
376
+ 'test:app',
377
+ 'test:distribution',
378
+ 'test:service',
379
+ 'test:bench',
380
+ ]
381
+
382
+ /** Lists the Vitest projects a seed reads heavy: the pack-and-install project and the live-service project. */
383
+ export const HEAVY_PROJECTS: readonly string[] = ['distribution', 'service']
384
+
385
+ /** Matches a browser face's Vitest project, whose whole run a seed reads heavy: `src:browser`, `app:vue`. */
386
+ export const BROWSER_PROJECT = /(?:^|:)(?:browser|vue)$/u
387
+
388
+ /** Matches a dotted flag such as `--outputFile.json`, whose separate value a seed skips. */
389
+ export const DOTTED_FLAG = /^--[^=.]+\.[^=]+$/u
390
+
391
+ /** Lists the package managers whose verbs and scripts a seed reads. */
392
+ export const MANAGERS: readonly string[] = ['npm', 'pnpm', 'yarn', 'bun']
393
+
394
+ /** Lists the package-manager verbs that run a tool, which a seed reads through to the tool. */
395
+ export const EXEC_VERBS: readonly string[] = ['exec', 'x', 'dlx']
396
+
397
+ /** Lists, by tool, the exec flags that take a separate value, so a seed reads no flag value as the tool. */
398
+ export const EXEC_VALUE_FLAGS: Readonly<Record<string, readonly string[]>> = Object.freeze({
399
+ npm: Object.freeze(['--package', '-p', '--workspace', '-w']),
400
+ npx: Object.freeze(['--package', '-p', '--workspace', '-w']),
401
+ pnpm: Object.freeze(['--package']),
402
+ pnpx: Object.freeze(['--package']),
403
+ yarn: Object.freeze(['--package']),
404
+ bun: Object.freeze(['--package']),
405
+ bunx: Object.freeze(['--package']),
406
+ })
407
+
408
+ /**
409
+ * Lists, by package manager, the flags before the verb that take a separate value, so a seed reads no
410
+ * flag value as the verb.
411
+ *
412
+ * @remarks
413
+ * npm's `-w` names a workspace and takes a value; pnpm's `-w` is the boolean `--workspace-root`.
414
+ */
415
+ export const MANAGER_VALUE_FLAGS: Readonly<Record<string, readonly string[]>> = Object.freeze({
416
+ npm: Object.freeze(['--prefix', '--workspace', '-w']),
417
+ pnpm: Object.freeze(['--dir', '-C', '--filter', '-F']),
418
+ yarn: Object.freeze(['--cwd']),
419
+ bun: Object.freeze(['--cwd']),
420
+ })
421
+
422
+ /** Lists the tools that run another tool the way `npx` does. */
423
+ export const NPX_TOOLS: readonly string[] = ['npx', 'pnpx', 'bunx']
424
+
425
+ /** Lists the `npm exec` and `npx` flags that run inline shell text, which names no tool a seed reads. */
426
+ export const EXEC_INLINE_FLAGS: readonly string[] = ['-c', '--call']
427
+
428
+ /** Holds the tool name of the falsify skill's `mutate` script, whose run a seed reads by its wrapped command. */
429
+ export const MUTATION_TOOL = 'mutate'
430
+
431
+ /** Holds the `mutate` flag that names the edits file, which a run's key leaves out. */
432
+ export const MUTATION_FLAG = '--edits'
433
+
434
+ /** Holds the `mutate` flag that writes saved originals back, which edits source and wraps no command. */
435
+ export const RESTORE_FLAG = '--restore'
436
+
437
+ /** Lists the tools a seed reads heavy by name: the release chain's step runner. */
438
+ export const HEAVY_TOOLS: readonly string[] = ['steps']
439
+
440
+ /** Lists the Vitest flags that take a separate value, so a seed reads no flag value as a file. */
441
+ export const VITEST_VALUE_FLAGS: readonly string[] = [
442
+ '--config',
443
+ '-c',
444
+ '--project',
445
+ '--reporter',
446
+ '--mode',
447
+ '--root',
448
+ '-r',
449
+ '--dir',
450
+ '--outputFile',
451
+ '--pool',
452
+ '--environment',
453
+ '--shard',
454
+ '--testNamePattern',
455
+ '-t',
456
+ '--bail',
457
+ '--retry',
458
+ '--maxWorkers',
459
+ '--minWorkers',
460
+ '--testTimeout',
461
+ '--hookTimeout',
462
+ '--exclude',
463
+ '--include',
464
+ ]
465
+
466
+ /** Matches a package script that runs a type check: `check`, `typecheck`, `check:<scope>`, or `<tool>:check`. */
467
+ export const CHECK_SCRIPT = /^(?:check|typecheck|type-check)(?::|$)|:check$/u
468
+
469
+ /** Matches a package script that runs one project's suite. */
470
+ export const SCOPED_SCRIPT = /^test:/u
471
+
472
+ /** Matches one sampler row: process id, parent id, creation time in milliseconds, CPU time in 100 ns units, and private bytes. */
473
+ export const GAUGE_PATTERN = /^(\d+) (\d+) (\d+) (\d+) (\d+)$/u
474
+
475
+ /** Holds the line a sampler prints when its first process query has run, which readies it. */
476
+ export const READY_LINE = 'ready'
477
+
478
+ /** Holds the byte a holder writes to its sampler to ask for one sample at once. */
479
+ export const SAMPLE_BYTE = 's'
480
+
481
+ /**
482
+ * Holds the PowerShell text of a sampler.
483
+ *
484
+ * @remarks
485
+ * The child runs one process query, the one a sample runs, so its first sample answers warm, and
486
+ * prints {@link READY_LINE}. Until the first byte it waits on its
487
+ * stdin with no timer. Each byte on its stdin starts one sample at once, and after the first byte it
488
+ * also samples every {@link SAMPLE_MS}. A sample prints one line: `1` for a sample a byte asked for or `0`, a `|`,
489
+ * and the rows separated by semicolons. The child exits when its stdin closes.
490
+ */
491
+ 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)}}`
492
+
493
+ /** Describes the footprint the light lanes add up: average cores, peak private bytes, and peak processes. */
494
+ export interface Usage {
495
+ readonly cores: number
496
+ readonly memory: number
497
+ readonly processes: number
498
+ }
499
+
500
+ /** Describes the per-run threshold of a light run: a footprint and a duration in milliseconds. */
501
+ export interface Threshold extends Usage {
502
+ readonly duration: number
503
+ }
504
+
505
+ /** Describes `limits.json`: the light holders allowed at once, their summed budget, and the per-run threshold. */
506
+ export interface Limits {
507
+ readonly slots: number
508
+ readonly budget: Usage
509
+ readonly threshold: Threshold
510
+ }
511
+
512
+ /** Describes one run's record: its duration and CPU time in milliseconds, its peaks, and its exit code. */
513
+ export interface Outcome {
514
+ readonly duration: number
515
+ readonly cpu: number
516
+ readonly memory: number
517
+ readonly processes: number
518
+ readonly code: number
519
+ }
520
+
521
+ /** Names the lane a command's kind seeds. */
522
+ export type Seed = 'light' | 'heavy'
523
+
524
+ /** Describes one process in a sampler row: a snapshot row with its CPU time and private bytes. */
525
+ export interface Gauge extends Row {
526
+ readonly cpu: number
527
+ readonly memory: number
528
+ }
529
+
530
+ /** Describes what a history prune did: the keys it removed and the names it skipped. */
531
+ export interface Prune {
532
+ readonly removed: readonly string[]
533
+ readonly skipped: readonly string[]
534
+ }
535
+
536
+ /** Describes one sample line: whether a byte asked for it, and its rows. */
537
+ export interface Sample {
538
+ readonly requested: boolean
539
+ readonly gauges: readonly Gauge[]
540
+ }
541
+
542
+ /** Describes what a sampler has read: each member's latest CPU time by id and creation date, and the peaks. */
543
+ export interface Tally {
544
+ readonly cpu: ReadonlyMap<string, number>
545
+ readonly memory: number
546
+ readonly processes: number
547
+ }
548
+
549
+ /** Describes what a measured holder needs: the limits, the command's key, its token, and its light footprint, undefined for a heavy run. */
550
+ export interface Measure {
551
+ readonly limits: Limits
552
+ readonly key: string
553
+ readonly token: string
554
+ readonly light: Usage | undefined
555
+ }
556
+
557
+ /**
558
+ * Describes the complete record a stage file holds and a ticket publishes; `light` holds the footprint
559
+ * a light ticket counts, and `edits` marks a `mutate` run that edits source in its working directory.
560
+ */
166
561
  export interface Ticket {
167
562
  readonly protocol: number
168
563
  readonly token: string
@@ -172,6 +567,9 @@ export interface Ticket {
172
567
  readonly platform: string
173
568
  readonly cwd: string
174
569
  readonly arrived: string
570
+ readonly light?: Usage
571
+ readonly solo?: boolean
572
+ readonly edits?: boolean
175
573
  }
176
574
 
177
575
  /** Describes one ticket in the queue: its sequence and its record, undefined when unreadable. */
@@ -194,11 +592,19 @@ export interface Row {
194
592
  readonly created: number
195
593
  }
196
594
 
197
- /** Describes what a process does next on the queue. */
595
+ /**
596
+ * Describes what a process does next on the queue; a light waiter that parks on several earlier
597
+ * tickets is `queued`, and `pending` names the earlier light tickets that did not hold yet.
598
+ */
198
599
  export type Turn =
199
600
  | { readonly state: 'holder' }
200
601
  | { readonly state: 'staged'; readonly name: string }
201
602
  | { readonly state: 'behind'; readonly entry: Entry }
603
+ | {
604
+ readonly state: 'queued'
605
+ readonly entries: readonly Entry[]
606
+ readonly pending: readonly number[]
607
+ }
202
608
  | { readonly state: 'refused'; readonly reason: string }
203
609
 
204
610
  /** Describes what a sweep confirmed: whether the tree reads as gone, and the members it left. */
@@ -207,15 +613,19 @@ export interface Sweep {
207
613
  readonly members: readonly number[]
208
614
  }
209
615
 
210
- /** Describes one ticket as `--status` reports it. */
616
+ /** Describes one ticket as `--status` reports it; `edits` marks a `mutate` run, and `holding` a live ticket with a run record. */
211
617
  export interface StatusRow {
212
618
  readonly sequence: number
213
619
  readonly label: string | undefined
214
620
  readonly pid: number | undefined
215
621
  readonly state: 'live' | 'dead' | 'unread'
622
+ readonly light: boolean
623
+ readonly solo: boolean
624
+ readonly edits: boolean
625
+ readonly holding: boolean
216
626
  }
217
627
 
218
- /** Describes what `--status` reads: every ticket in arrival order and the holder among them. */
628
+ /** Describes what `--status` reads: every ticket in arrival order and the heavy holder among them. */
219
629
  export interface Status {
220
630
  readonly tickets: readonly StatusRow[]
221
631
  readonly holder: StatusRow | undefined
@@ -228,6 +638,7 @@ export interface LaneOptions {
228
638
  readonly journal: string
229
639
  readonly errors: string
230
640
  readonly cap: number
641
+ readonly solo: boolean
231
642
  readonly command: readonly string[]
232
643
  }
233
644
 
@@ -241,8 +652,10 @@ export interface LaneOptions {
241
652
  */
242
653
  export class Token {
243
654
  readonly #sockets = new Set<Socket>()
655
+ readonly #waiters = new Set<Socket>()
244
656
  readonly #server: Server
245
657
  #published = false
658
+ #holding = false
246
659
 
247
660
  constructor() {
248
661
  this.#server = createServer((socket) => this.#admit(socket))
@@ -255,14 +668,9 @@ export class Token {
255
668
  * @returns A promise that resolves when the endpoint accepts connections, and rejects with the
256
669
  * listen failure.
257
670
  */
258
- listen(endpoint: string): Promise<void> {
259
- return new Promise((resolve, reject) => {
260
- this.#server.once('error', reject)
261
- this.#server.listen(endpoint, () => {
262
- this.#server.removeListener('error', reject)
263
- resolve()
264
- })
265
- })
671
+ async listen(endpoint: string): Promise<void> {
672
+ this.#server.listen(endpoint)
673
+ await once(this.#server, 'listening')
266
674
  }
267
675
 
268
676
  /** Marks the stage as ended and closes every accepted connection, which wakes each waiter. */
@@ -271,98 +679,48 @@ export class Token {
271
679
  for (const socket of this.#sockets) socket.destroy()
272
680
  }
273
681
 
682
+ /** Marks the process as a holder and closes every connection that waits for it to hold. */
683
+ hold(): void {
684
+ this.#holding = true
685
+ for (const socket of this.#waiters) socket.destroy()
686
+ }
687
+
688
+ /** Marks the process as leaving, so a hold waiter that arrives later parks until the process ends. */
689
+ leave(): void {
690
+ this.#holding = false
691
+ }
692
+
274
693
  /**
275
694
  * Closes the endpoint and every connection.
276
695
  *
277
696
  * @returns A promise that resolves when the server has closed.
278
697
  */
279
- destroy(): Promise<void> {
698
+ async destroy(): Promise<void> {
280
699
  for (const socket of this.#sockets) socket.destroy()
281
- return new Promise((resolve) => {
282
- this.#server.close(() => resolve())
283
- })
700
+ this.#server.close()
701
+ await once(this.#server, 'close')
284
702
  }
285
703
 
286
- // A byte after the publish comes from a stage waiter whose connection the allocation left unaccepted.
704
+ // Another byte after the publish comes from a stage waiter whose connection the allocation left unaccepted.
287
705
  #admit(socket: Socket): void {
288
706
  this.#sockets.add(socket)
289
707
  socket.on('error', () => undefined)
290
- socket.on('close', () => this.#sockets.delete(socket))
291
- socket.on('data', () => {
292
- if (this.#published) socket.destroy()
708
+ socket.on('close', () => {
709
+ this.#sockets.delete(socket)
710
+ this.#waiters.delete(socket)
711
+ })
712
+ socket.on('data', (data: Buffer) => {
713
+ if (!data.includes(HOLD_BYTE)) {
714
+ if (this.#published) socket.destroy()
715
+ } else if (this.#holding) {
716
+ socket.destroy()
717
+ } else {
718
+ this.#waiters.add(socket)
719
+ }
293
720
  })
294
721
  }
295
722
  }
296
723
 
297
- /**
298
- * Reads the value that follows a flag.
299
- *
300
- * @remarks
301
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
302
- * and the `--flag=value` form is not read.
303
- *
304
- * @param argv - The arguments before the bare `--`.
305
- * @param name - The flag, such as `--label`.
306
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
307
- * another flag.
308
- */
309
- export function readOption(argv: readonly string[], name: string): string | undefined {
310
- const index = argv.indexOf(name)
311
- const value = index === -1 ? undefined : argv[index + 1]
312
- return value === undefined || value.startsWith('--') ? undefined : value
313
- }
314
-
315
- /**
316
- * Names the value flags a caller gave with no value.
317
- *
318
- * @param argv - The arguments before the bare `--`.
319
- * @param names - The flags that take a value.
320
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
321
- */
322
- export function readMissingFlags(
323
- argv: readonly string[],
324
- names: readonly string[],
325
- ): readonly string[] {
326
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
327
- }
328
-
329
- /**
330
- * Names the flags a caller gave that the script does not read.
331
- *
332
- * @remarks
333
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
334
- * scan, so the command after it keeps every argument.
335
- *
336
- * @param argv - The arguments after the script path.
337
- * @param flags - Every flag the script reads, value flags and switches alike.
338
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
339
- */
340
- export function readUnknownFlags(
341
- argv: readonly string[],
342
- flags: readonly string[],
343
- ): readonly string[] {
344
- const end = argv.indexOf('--')
345
- return (end === -1 ? argv : argv.slice(0, end)).filter(
346
- (argument) => argument.startsWith('--') && !flags.includes(argument),
347
- )
348
- }
349
-
350
- /**
351
- * Reads the arguments that are neither a flag nor the value of a value flag.
352
- *
353
- * @param argv - The arguments before the bare `--`.
354
- * @param valueFlags - The flags that take a value.
355
- * @returns The positional arguments in order.
356
- */
357
- export function readPositionals(
358
- argv: readonly string[],
359
- valueFlags: readonly string[],
360
- ): readonly string[] {
361
- return argv.filter(
362
- (argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''),
363
- )
364
- }
365
-
366
724
  /**
367
725
  * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
368
726
  *
@@ -428,23 +786,14 @@ export function renderEndpoint(root: string, token: string): string {
428
786
  }
429
787
 
430
788
  /**
431
- * Renders the name of a ticket.
432
- *
433
- * @param sequence - The ticket's sequence.
434
- * @returns The file name, at a fixed width.
435
- */
436
- export function renderTicketName(sequence: number): string {
437
- return `${String(sequence).padStart(SEQUENCE_WIDTH, '0')}${TICKET_SUFFIX}`
438
- }
439
-
440
- /**
441
- * Renders the name of a run record.
789
+ * Renders the name of a ticket or a run record.
442
790
  *
443
791
  * @param sequence - The ticket's sequence.
792
+ * @param suffix - The name ending: `TICKET_SUFFIX` for a ticket, `RUN_SUFFIX` for its run record.
444
793
  * @returns The file name, at a fixed width.
445
794
  */
446
- export function renderRunName(sequence: number): string {
447
- return `${String(sequence).padStart(SEQUENCE_WIDTH, '0')}${RUN_SUFFIX}`
795
+ export function renderName(sequence: number, suffix: string): string {
796
+ return `${String(sequence).padStart(SEQUENCE_WIDTH, '0')}${suffix}`
448
797
  }
449
798
 
450
799
  /**
@@ -479,7 +828,8 @@ export function readSequences(names: readonly string[]): readonly number[] {
479
828
  * Checks whether a value is a ticket record.
480
829
  *
481
830
  * @param value - The parsed JSON value.
482
- * @returns True when every field has its type and the token has the token's form; false otherwise.
831
+ * @returns True when every field has its type, each present optional field too, and the token has
832
+ * the token's form; false otherwise.
483
833
  */
484
834
  export function isTicket(value: unknown): value is Ticket {
485
835
  return (
@@ -501,7 +851,88 @@ export function isTicket(value: unknown): value is Ticket {
501
851
  'cwd' in value &&
502
852
  typeof value.cwd === 'string' &&
503
853
  'arrived' in value &&
504
- typeof value.arrived === 'string'
854
+ typeof value.arrived === 'string' &&
855
+ (!('light' in value) || isUsage(value.light)) &&
856
+ (!('solo' in value) || typeof value.solo === 'boolean') &&
857
+ (!('edits' in value) || typeof value.edits === 'boolean')
858
+ )
859
+ }
860
+
861
+ /**
862
+ * Checks whether a value is a footprint.
863
+ *
864
+ * @param value - The parsed JSON value.
865
+ * @returns True when `cores`, `memory`, and `processes` are finite numbers of at least 0; false
866
+ * otherwise.
867
+ */
868
+ export function isUsage(value: unknown): value is Usage {
869
+ return (
870
+ typeof value === 'object' &&
871
+ value !== null &&
872
+ 'cores' in value &&
873
+ isAmount(value.cores) &&
874
+ 'memory' in value &&
875
+ isAmount(value.memory) &&
876
+ 'processes' in value &&
877
+ isAmount(value.processes)
878
+ )
879
+ }
880
+
881
+ /**
882
+ * Checks whether a value is a finite number of at least 0.
883
+ *
884
+ * @param value - The value.
885
+ * @returns True for a finite number of at least 0; false otherwise.
886
+ */
887
+ export function isAmount(value: unknown): value is number {
888
+ return typeof value === 'number' && Number.isFinite(value) && value >= 0
889
+ }
890
+
891
+ /**
892
+ * Checks whether a value is the content of `limits.json`.
893
+ *
894
+ * @param value - The parsed JSON value.
895
+ * @returns True when `slots` is an integer of at least 1, `budget` is a footprint, and `threshold` is
896
+ * a footprint with a `duration`; false otherwise.
897
+ */
898
+ export function isLimits(value: unknown): value is Limits {
899
+ return (
900
+ typeof value === 'object' &&
901
+ value !== null &&
902
+ 'slots' in value &&
903
+ Number.isSafeInteger(value.slots) &&
904
+ typeof value.slots === 'number' &&
905
+ value.slots >= 1 &&
906
+ 'budget' in value &&
907
+ isUsage(value.budget) &&
908
+ 'threshold' in value &&
909
+ isUsage(value.threshold) &&
910
+ 'duration' in value.threshold &&
911
+ isAmount(value.threshold.duration)
912
+ )
913
+ }
914
+
915
+ /**
916
+ * Checks whether a value is a run's record.
917
+ *
918
+ * @param value - The parsed JSON value.
919
+ * @returns True when the measures are finite numbers of at least 0 and `code` is an integer; false
920
+ * otherwise.
921
+ */
922
+ export function isOutcome(value: unknown): value is Outcome {
923
+ return (
924
+ typeof value === 'object' &&
925
+ value !== null &&
926
+ 'duration' in value &&
927
+ isAmount(value.duration) &&
928
+ 'cpu' in value &&
929
+ isAmount(value.cpu) &&
930
+ 'memory' in value &&
931
+ isAmount(value.memory) &&
932
+ 'processes' in value &&
933
+ isAmount(value.processes) &&
934
+ 'code' in value &&
935
+ Number.isSafeInteger(value.code)
505
936
  )
506
937
  }
507
938
 
@@ -547,7 +978,7 @@ export function parseText(text: string): unknown {
547
978
  */
548
979
  export function readEntry(root: string, sequence: number): readonly Entry[] {
549
980
  try {
550
- const parsed = parseText(readFileSync(join(root, renderTicketName(sequence)), 'utf8'))
981
+ const parsed = parseText(readFileSync(join(root, renderName(sequence, TICKET_SUFFIX)), 'utf8'))
551
982
  return [{ sequence, ticket: isTicket(parsed) ? parsed : undefined }]
552
983
  } catch (error) {
553
984
  return readCode(error) === 'ENOENT' ? [] : [{ sequence, ticket: undefined }]
@@ -585,7 +1016,7 @@ export function readQueue(root: string): readonly Entry[] {
585
1016
  */
586
1017
  export function readRun(root: string, sequence: number): Run | 'absent' | 'unread' {
587
1018
  try {
588
- const parsed = parseText(readFileSync(join(root, renderRunName(sequence)), 'utf8'))
1019
+ const parsed = parseText(readFileSync(join(root, renderName(sequence, RUN_SUFFIX)), 'utf8'))
589
1020
  return isRun(parsed)
590
1021
  ? {
591
1022
  started: parsed.started,
@@ -606,7 +1037,7 @@ export function readRun(root: string, sequence: number): Run | 'absent' | 'unrea
606
1037
  * @param run - The record.
607
1038
  */
608
1039
  export function writeRun(root: string, sequence: number, run: Run): void {
609
- writeFileSync(join(root, renderRunName(sequence)), JSON.stringify(run))
1040
+ writeFileSync(join(root, renderName(sequence, RUN_SUFFIX)), JSON.stringify(run))
610
1041
  }
611
1042
 
612
1043
  /**
@@ -623,9 +1054,20 @@ export function removeFile(path: string): void {
623
1054
  *
624
1055
  * @param token - The process's token.
625
1056
  * @param label - The run's label.
626
- * @returns The complete ticket.
1057
+ * @param light - The footprint a light ticket counts, or undefined for a heavy ticket.
1058
+ * @param solo - If `true`, marks a ticket that waits out every earlier light ticket; if `false`, omits
1059
+ * the field.
1060
+ * @param edits - If `true`, marks a `mutate` run that edits source in its working directory; if
1061
+ * `false`, omits the field.
1062
+ * @returns The complete ticket, carrying `light`, `solo`, and `edits` only when they are set.
627
1063
  */
628
- export function buildTicket(token: string, label: string): Ticket {
1064
+ export function buildTicket(
1065
+ token: string,
1066
+ label: string,
1067
+ light?: Usage,
1068
+ solo = false,
1069
+ edits = false,
1070
+ ): Ticket {
629
1071
  return {
630
1072
  protocol: PROTOCOL,
631
1073
  token,
@@ -635,7 +1077,586 @@ export function buildTicket(token: string, label: string): Ticket {
635
1077
  platform: process.platform,
636
1078
  cwd: process.cwd(),
637
1079
  arrived: new Date().toISOString(),
1080
+ ...(light === undefined ? {} : { light }),
1081
+ ...(solo ? { solo } : {}),
1082
+ ...(edits ? { edits } : {}),
1083
+ }
1084
+ }
1085
+
1086
+ /**
1087
+ * Reads `limits.json` under the root.
1088
+ *
1089
+ * @param root - The queue root.
1090
+ * @returns The limits; `absent` when the file does not exist; `unread` when it cannot be read as
1091
+ * limits.
1092
+ */
1093
+ export function readLimits(root: string): Limits | 'absent' | 'unread' {
1094
+ try {
1095
+ const parsed = parseText(readFileSync(join(root, LIMITS_FILE), 'utf8'))
1096
+ return isLimits(parsed) ? parsed : 'unread'
1097
+ } catch (error) {
1098
+ return readCode(error) === 'ENOENT' ? 'absent' : 'unread'
1099
+ }
1100
+ }
1101
+
1102
+ /**
1103
+ * Renders the key of a command's run records.
1104
+ *
1105
+ * @param cwd - The real working directory.
1106
+ * @param command - The command and its arguments.
1107
+ * @returns The hex sha256 of the directory and the arguments.
1108
+ */
1109
+ export function renderKey(cwd: string, command: readonly string[]): string {
1110
+ return createHash('sha256')
1111
+ .update(JSON.stringify([cwd, ...command]))
1112
+ .digest('hex')
1113
+ }
1114
+
1115
+ /**
1116
+ * Renders the name of a run's record.
1117
+ *
1118
+ * @param ended - When the run ended, in epoch milliseconds.
1119
+ * @param token - The run's token, which keeps two records of one key and one millisecond apart.
1120
+ * @returns The file name, opening with the end time at a fixed width.
1121
+ */
1122
+ export function renderOutcomeName(ended: number, token: string): string {
1123
+ return `${String(ended).padStart(ENDED_WIDTH, '0')}-${token}${OUTCOME_SUFFIX}`
1124
+ }
1125
+
1126
+ /**
1127
+ * Reads the names of a key's records, oldest first.
1128
+ *
1129
+ * @param root - The queue root.
1130
+ * @param key - The command's key.
1131
+ * @returns Every record name under the key, sorted by end time.
1132
+ */
1133
+ export function readOutcomeNames(root: string, key: string): readonly string[] {
1134
+ return readNames(join(root, HISTORY_DIRECTORY, key))
1135
+ .filter((name) => name.endsWith(OUTCOME_SUFFIX))
1136
+ .toSorted()
1137
+ }
1138
+
1139
+ /**
1140
+ * Reads a key's latest records.
1141
+ *
1142
+ * @param root - The queue root.
1143
+ * @param key - The command's key.
1144
+ * @returns Up to {@link RECENT_RUNS} records, oldest first, each undefined when it cannot be read as
1145
+ * a record; a record removed while it is read is skipped.
1146
+ */
1147
+ export function readOutcomes(root: string, key: string): ReadonlyArray<Outcome | undefined> {
1148
+ return readOutcomeNames(root, key)
1149
+ .slice(-RECENT_RUNS)
1150
+ .flatMap((name) => {
1151
+ try {
1152
+ const parsed = parseText(readFileSync(join(root, HISTORY_DIRECTORY, key, name), 'utf8'))
1153
+ return [isOutcome(parsed) ? parsed : undefined]
1154
+ } catch (error) {
1155
+ return readCode(error) === 'ENOENT' ? [] : [undefined]
1156
+ }
1157
+ })
1158
+ }
1159
+
1160
+ /**
1161
+ * Writes a run's record once and prunes its key to the latest {@link RECENT_RUNS} records.
1162
+ *
1163
+ * @param root - The queue root.
1164
+ * @param key - The command's key.
1165
+ * @param name - The record's name.
1166
+ * @param outcome - The record.
1167
+ * @returns True when the write created the key's directory; false when the key existed.
1168
+ */
1169
+ export function writeOutcome(root: string, key: string, name: string, outcome: Outcome): boolean {
1170
+ const directory = join(root, HISTORY_DIRECTORY, key)
1171
+ const created = mkdirSync(directory, { recursive: true }) !== undefined
1172
+ writeFileSync(join(directory, name), JSON.stringify(outcome), { flag: 'wx' })
1173
+ for (const stale of readOutcomeNames(root, key).slice(0, -RECENT_RUNS)) {
1174
+ removeFile(join(directory, stale))
638
1175
  }
1176
+ return created
1177
+ }
1178
+
1179
+ /**
1180
+ * Reads when a history key was last written.
1181
+ *
1182
+ * @param root - The queue root.
1183
+ * @param key - The key.
1184
+ * @returns The end time its newest record's name opens with; the directory's modification time when
1185
+ * it holds no record; `gone` when the entry no longer exists; `unread` when the host refuses to list
1186
+ * it, as it does for a file that is no directory.
1187
+ */
1188
+ export function readKeyTime(root: string, key: string): number | 'gone' | 'unread' {
1189
+ try {
1190
+ const newest = readOutcomeNames(root, key).at(-1)
1191
+ if (newest !== undefined) return Number(newest.slice(0, ENDED_WIDTH))
1192
+ return statSync(join(root, HISTORY_DIRECTORY, key)).mtimeMs
1193
+ } catch (error) {
1194
+ return readCode(error) === 'ENOENT' ? 'gone' : 'unread'
1195
+ }
1196
+ }
1197
+
1198
+ /**
1199
+ * Lists the names under the history directory.
1200
+ *
1201
+ * @param root - The queue root.
1202
+ * @returns The names, empty when the directory is absent; undefined when the host refuses to list it.
1203
+ */
1204
+ export function readHistoryNames(root: string): readonly string[] | undefined {
1205
+ try {
1206
+ return readNames(join(root, HISTORY_DIRECTORY))
1207
+ } catch {
1208
+ return undefined
1209
+ }
1210
+ }
1211
+
1212
+ /**
1213
+ * Removes one history key inside the removal budget.
1214
+ *
1215
+ * @param root - The queue root.
1216
+ * @param key - The key.
1217
+ * @returns True when the key is gone; false when the host refused the removal.
1218
+ */
1219
+ export function removeKey(root: string, key: string): boolean {
1220
+ try {
1221
+ rmSync(join(root, HISTORY_DIRECTORY, key), {
1222
+ recursive: true,
1223
+ force: true,
1224
+ maxRetries: REMOVAL_RETRIES,
1225
+ retryDelay: REMOVAL_DELAY_MS,
1226
+ })
1227
+ return true
1228
+ } catch {
1229
+ return false
1230
+ }
1231
+ }
1232
+
1233
+ /**
1234
+ * Prunes the history to the keys written inside {@link HISTORY_AGE_MS}, at most the
1235
+ * {@link HISTORY_KEYS} written last.
1236
+ *
1237
+ * @remarks
1238
+ * The prune throws nothing, so it never changes the lane's exit: a name the host refuses to list or
1239
+ * remove stays and is reported as skipped.
1240
+ *
1241
+ * @param root - The queue root.
1242
+ * @param now - The current time in epoch milliseconds.
1243
+ * @returns The keys removed, and the names skipped: `history` itself when it cannot be listed.
1244
+ */
1245
+ export function pruneHistory(root: string, now: number): Prune {
1246
+ const names = readHistoryNames(root)
1247
+ if (names === undefined) return { removed: [], skipped: [HISTORY_DIRECTORY] }
1248
+ const times = names.map((key) => ({ key, time: readKeyTime(root, key) }))
1249
+ const unread = times.flatMap((item) => (item.time === 'unread' ? [item.key] : []))
1250
+ const results = times
1251
+ .flatMap((item) => (typeof item.time === 'number' ? [{ key: item.key, time: item.time }] : []))
1252
+ .toSorted((left, right) => right.time - left.time)
1253
+ .filter((item, index) => index >= HISTORY_KEYS || item.time < now - HISTORY_AGE_MS)
1254
+ .map((item) => ({ key: item.key, removed: removeKey(root, item.key) }))
1255
+ return {
1256
+ removed: results.flatMap((item) => (item.removed ? [item.key] : [])),
1257
+ skipped: [...unread, ...results.flatMap((item) => (item.removed ? [] : [item.key]))],
1258
+ }
1259
+ }
1260
+
1261
+ /**
1262
+ * Reads the average cores a run used.
1263
+ *
1264
+ * @param outcome - The run's record.
1265
+ * @returns The CPU time over the duration; 0 for a run of no duration.
1266
+ */
1267
+ export function readCores(outcome: Outcome): number {
1268
+ return outcome.duration > 0 ? outcome.cpu / outcome.duration : 0
1269
+ }
1270
+
1271
+ /**
1272
+ * Checks whether a run's record breaches the per-run threshold.
1273
+ *
1274
+ * @param outcome - The run's record, or undefined when it cannot be read.
1275
+ * @param threshold - The per-run threshold.
1276
+ * @returns True for an unreadable record, a capped run, an exit of 69 or 70, and a measure past the
1277
+ * threshold; false otherwise.
1278
+ */
1279
+ export function isBreach(outcome: Outcome | undefined, threshold: Threshold): boolean {
1280
+ return (
1281
+ outcome === undefined ||
1282
+ outcome.code === CAPPED_CODE ||
1283
+ outcome.code === HELD_CODE ||
1284
+ outcome.code === BREACH_CODE ||
1285
+ outcome.duration > threshold.duration ||
1286
+ readCores(outcome) > threshold.cores ||
1287
+ outcome.memory > threshold.memory ||
1288
+ outcome.processes > threshold.processes
1289
+ )
1290
+ }
1291
+
1292
+ /**
1293
+ * Reads the footprint a light ticket counts from its command's records.
1294
+ *
1295
+ * @param outcomes - The records, none of which breaches.
1296
+ * @returns The largest cores, memory, and process count across the records.
1297
+ */
1298
+ export function measurePeak(outcomes: readonly Outcome[]): Usage {
1299
+ return {
1300
+ cores: Math.max(0, ...outcomes.map(readCores)),
1301
+ memory: Math.max(0, ...outcomes.map((outcome) => outcome.memory)),
1302
+ processes: Math.max(0, ...outcomes.map((outcome) => outcome.processes)),
1303
+ }
1304
+ }
1305
+
1306
+ /**
1307
+ * Reads whether a command runs light, from its seed and its latest records.
1308
+ *
1309
+ * @remarks
1310
+ * A seeded heavy command is heavy whatever its records hold. A seeded light command is light until a
1311
+ * record breaches, and counts the threshold until {@link RECENT_RUNS} records exist. Any other
1312
+ * command is light only when {@link RECENT_RUNS} records exist and none breaches.
1313
+ *
1314
+ * @param seed - The lane the command's kind seeds, or undefined when no kind names it.
1315
+ * @param outcomes - The command's latest records.
1316
+ * @param limits - The limits.
1317
+ * @returns The footprint the ticket counts, or undefined when the command runs heavy.
1318
+ */
1319
+ export function classifyLight(
1320
+ seed: Seed | undefined,
1321
+ outcomes: ReadonlyArray<Outcome | undefined>,
1322
+ limits: Limits,
1323
+ ): Usage | undefined {
1324
+ if (seed === 'heavy') return undefined
1325
+ const clean = outcomes.flatMap((outcome) =>
1326
+ outcome === undefined || isBreach(outcome, limits.threshold) ? [] : [outcome],
1327
+ )
1328
+ if (clean.length < outcomes.length) return undefined
1329
+ if (clean.length >= RECENT_RUNS) return measurePeak(clean)
1330
+ const { cores, memory, processes } = limits.threshold
1331
+ return seed === 'light' ? { cores, memory, processes } : undefined
1332
+ }
1333
+
1334
+ /**
1335
+ * Checks whether light footprints fit the slots and every budget together.
1336
+ *
1337
+ * @param usages - The footprints of the light holders and the arrival.
1338
+ * @param limits - The limits.
1339
+ * @returns True when the count fits `slots` and each summed measure fits its budget; false otherwise.
1340
+ */
1341
+ export function fitsBudget(usages: readonly Usage[], limits: Limits): boolean {
1342
+ const total = usages.reduce(
1343
+ (sum, usage) => ({
1344
+ cores: sum.cores + usage.cores,
1345
+ memory: sum.memory + usage.memory,
1346
+ processes: sum.processes + usage.processes,
1347
+ }),
1348
+ { cores: 0, memory: 0, processes: 0 },
1349
+ )
1350
+ return (
1351
+ usages.length <= limits.slots &&
1352
+ total.cores <= limits.budget.cores &&
1353
+ total.memory <= limits.budget.memory &&
1354
+ total.processes <= limits.budget.processes
1355
+ )
1356
+ }
1357
+
1358
+ /**
1359
+ * Splits a command into the words a seed reads.
1360
+ *
1361
+ * @remarks
1362
+ * An absolute path contributes its base name alone, so a checkout's location never seeds a command.
1363
+ *
1364
+ * @param args - The arguments after the executable.
1365
+ * @returns The lowercase alphanumeric words.
1366
+ */
1367
+ export function readWords(args: readonly string[]): readonly string[] {
1368
+ return args.flatMap((argument) =>
1369
+ (isAbsolute(argument) ? basename(argument) : argument)
1370
+ .toLowerCase()
1371
+ .split(/[^a-z0-9]+/u)
1372
+ .filter((word) => word !== ''),
1373
+ )
1374
+ }
1375
+
1376
+ /**
1377
+ * Reads a tool's name from an executable or script path.
1378
+ *
1379
+ * @param path - The path.
1380
+ * @returns The lowercase base name without its extension, `npm-cli` and `npx-cli` read as `npm` and
1381
+ * `npx`.
1382
+ */
1383
+ export function readToolName(path: string): string {
1384
+ const name = basename(path.replaceAll('\\', '/'))
1385
+ .toLowerCase()
1386
+ .replace(/\.(?:exe|cmd|bat|ps1|js|mjs|cjs|ts|mts|cts)$/u, '')
1387
+ return name.replace(/-cli$/u, '')
1388
+ }
1389
+
1390
+ /**
1391
+ * Reads the tool a command runs and the tool's arguments, past Node, `npx`, `pnpx`, `bunx`, and a
1392
+ * package manager's `exec`, `x`, or `dlx` verb.
1393
+ *
1394
+ * @param command - The command and its arguments.
1395
+ * @returns The tool's name followed by its arguments; empty for inline Node code, inline exec text,
1396
+ * or no script.
1397
+ */
1398
+ export function readTool(command: readonly string[]): readonly string[] {
1399
+ const [executable, ...rest] = command
1400
+ if (executable === undefined) return []
1401
+ const name = readToolName(executable)
1402
+ if (name === 'node') {
1403
+ const script = rest.findIndex((argument) => !argument.startsWith('-'))
1404
+ const flags = script === -1 ? rest : rest.slice(0, script)
1405
+ if (script === -1 || flags.some((flag) => ['-e', '--eval', '-p', '--print'].includes(flag))) {
1406
+ return []
1407
+ }
1408
+ return readTool(rest.slice(script))
1409
+ }
1410
+ if (NPX_TOOLS.includes(name)) return readExecTool(rest, EXEC_VALUE_FLAGS[name])
1411
+ if (MANAGERS.includes(name)) {
1412
+ const flags = MANAGER_VALUE_FLAGS[name] ?? []
1413
+ const verb = rest.findIndex(
1414
+ (argument, index) => !argument.startsWith('-') && !flags.includes(rest[index - 1] ?? ''),
1415
+ )
1416
+ if (EXEC_VERBS.includes(rest[verb] ?? '')) {
1417
+ return readExecTool(rest.slice(verb + 1), EXEC_VALUE_FLAGS[name])
1418
+ }
1419
+ }
1420
+ return [name, ...rest]
1421
+ }
1422
+
1423
+ /**
1424
+ * Reads the tool an `npx` or `npm exec` call runs, from the arguments after the verb.
1425
+ *
1426
+ * @remarks
1427
+ * The tool is the first argument before a bare `--` that is neither a flag nor the value of a
1428
+ * listed flag, else the first argument after the bare `--`. A flag {@link EXEC_INLINE_FLAGS} names
1429
+ * before the tool runs shell text instead.
1430
+ *
1431
+ * @param args - The arguments after `npx` or after the exec verb.
1432
+ * @param valueFlags - The flags that take a separate value, from {@link EXEC_VALUE_FLAGS}. Default:
1433
+ * none.
1434
+ * @returns The tool's name followed by its arguments; empty for inline text or no tool.
1435
+ */
1436
+ export function readExecTool(
1437
+ args: readonly string[],
1438
+ valueFlags: readonly string[] = [],
1439
+ ): readonly string[] {
1440
+ const end = args.indexOf('--')
1441
+ const named = args.findIndex(
1442
+ (argument, index) =>
1443
+ (end === -1 || index < end) &&
1444
+ !argument.startsWith('-') &&
1445
+ !valueFlags.includes(args[index - 1] ?? ''),
1446
+ )
1447
+ const start = named !== -1 ? named : end === -1 ? -1 : end + 1
1448
+ if (start === -1 || start >= args.length) return []
1449
+ const inline = args
1450
+ .slice(0, start)
1451
+ .some(
1452
+ (flag) =>
1453
+ EXEC_INLINE_FLAGS.includes(flag) ||
1454
+ EXEC_INLINE_FLAGS.some((name) => flag.startsWith(`${name}=`)),
1455
+ )
1456
+ return inline ? [] : readTool(args.slice(start))
1457
+ }
1458
+
1459
+ /**
1460
+ * Checks whether a command is a `mutate --restore` run, which writes source files back.
1461
+ *
1462
+ * @param command - The command and its arguments.
1463
+ * @returns True for a `mutate` call with its restore flag before any bare `--`; false otherwise.
1464
+ */
1465
+ export function matchesRestore(command: readonly string[]): boolean {
1466
+ const [tool, ...args] = readTool(command)
1467
+ if (tool !== MUTATION_TOOL) return false
1468
+ const end = args.indexOf('--')
1469
+ return (end === -1 ? args : args.slice(0, end)).some(
1470
+ (flag) => flag === RESTORE_FLAG || flag.startsWith(`${RESTORE_FLAG}=`),
1471
+ )
1472
+ }
1473
+
1474
+ /**
1475
+ * Extracts the command a `mutate` run wraps.
1476
+ *
1477
+ * @param command - The command and its arguments.
1478
+ * @returns The arguments after the run's own bare `--`; undefined for any other command, or a
1479
+ * `mutate` call with no edits file or no wrapped command.
1480
+ */
1481
+ export function extractMutation(command: readonly string[]): readonly string[] | undefined {
1482
+ const [tool, ...args] = readTool(command)
1483
+ if (tool !== MUTATION_TOOL) return undefined
1484
+ const end = args.indexOf('--')
1485
+ if (end === -1) return undefined
1486
+ const edits = args
1487
+ .slice(0, end)
1488
+ .some((flag) => flag === MUTATION_FLAG || flag.startsWith(`${MUTATION_FLAG}=`))
1489
+ const wrapped = args.slice(end + 1)
1490
+ return edits && wrapped.length > 0 ? wrapped : undefined
1491
+ }
1492
+
1493
+ /**
1494
+ * Normalizes a command to the arguments its key hashes.
1495
+ *
1496
+ * @remarks
1497
+ * A `mutate` run names a fresh edits file each time, so its key leaves the edits flag and its value
1498
+ * out, and every run of one wrapped command from one directory shares a key. The cut reads only the
1499
+ * script's own flags, between the script and its own bare `--`, so a launcher's `--` before the
1500
+ * script moves nothing.
1501
+ *
1502
+ * @param command - The command and its arguments.
1503
+ * @returns A `mutate` run without its edits flag and value; any other command unchanged.
1504
+ */
1505
+ export function normalizeCommand(command: readonly string[]): readonly string[] {
1506
+ if (extractMutation(command) === undefined) return command
1507
+ const start = command.length - readTool(command).length + 1
1508
+ const end = command.indexOf('--', start)
1509
+ return command.filter(
1510
+ (argument, index) =>
1511
+ index < start ||
1512
+ index >= end ||
1513
+ !(
1514
+ argument === MUTATION_FLAG ||
1515
+ argument.startsWith(`${MUTATION_FLAG}=`) ||
1516
+ command[index - 1] === MUTATION_FLAG
1517
+ ),
1518
+ )
1519
+ }
1520
+
1521
+ /**
1522
+ * Normalizes a working directory for the comparison that decides whether two tickets share it.
1523
+ *
1524
+ * @remarks
1525
+ * Every side of the comparison passes through this one function. It reads the real path through
1526
+ * `realpathSync.native`, which returns the name and the case the file system stores, so two
1527
+ * spellings of one directory compare equal without folding case.
1528
+ *
1529
+ * @param path - The directory.
1530
+ * @returns The real path; the resolved path when it cannot be read, as for a vanished directory.
1531
+ */
1532
+ export function normalizeDirectory(path: string): string {
1533
+ try {
1534
+ return realpathSync.native(path)
1535
+ } catch {
1536
+ return resolvePath(path)
1537
+ }
1538
+ }
1539
+
1540
+ /**
1541
+ * Checks whether two working directories share source.
1542
+ *
1543
+ * @remarks
1544
+ * Both sides pass through {@link normalizeDirectory}, so a child directory, such as a check run from
1545
+ * `packages/a`, shares source with a mutation at the checkout root, and the reverse.
1546
+ *
1547
+ * @param left - One directory.
1548
+ * @param right - The other directory.
1549
+ * @returns True when the two normalize to one directory or one sits inside the other at a separator
1550
+ * boundary; false otherwise.
1551
+ */
1552
+ export function sharesDirectory(left: string, right: string): boolean {
1553
+ const one = normalizeDirectory(left)
1554
+ const other = normalizeDirectory(right)
1555
+ return one === other || matchesInside(one, other) || matchesInside(other, one)
1556
+ }
1557
+
1558
+ /**
1559
+ * Checks whether a normalized path sits inside another at a separator boundary.
1560
+ *
1561
+ * @param inner - The path that might sit inside.
1562
+ * @param outer - The path that might contain it.
1563
+ * @returns True when `inner` opens with `outer` and a separator; false otherwise, the same path
1564
+ * included.
1565
+ */
1566
+ export function matchesInside(inner: string, outer: string): boolean {
1567
+ return inner.startsWith(outer.endsWith(sep) ? outer : `${outer}${sep}`)
1568
+ }
1569
+
1570
+ /**
1571
+ * Reads the positional arguments of a command, skipping each value of a value-taking flag.
1572
+ *
1573
+ * @param args - The arguments.
1574
+ * @param valueFlags - The flags that take a separate value.
1575
+ * @returns The arguments that are neither a flag nor the value of a listed or dotted flag.
1576
+ */
1577
+ export function readOperands(
1578
+ args: readonly string[],
1579
+ valueFlags: readonly string[],
1580
+ ): readonly string[] {
1581
+ return args.filter(
1582
+ (argument, index) =>
1583
+ !argument.startsWith('-') &&
1584
+ !valueFlags.includes(args[index - 1] ?? '') &&
1585
+ !DOTTED_FLAG.test(args[index - 1] ?? ''),
1586
+ )
1587
+ }
1588
+
1589
+ /**
1590
+ * Reads the lane a package script's name seeds.
1591
+ *
1592
+ * @param name - The script's name.
1593
+ * @returns `heavy` for a script {@link HEAVY_SCRIPTS} names, `light` for a type, format, or lint
1594
+ * check and any other `test:` suite, and undefined for any other script.
1595
+ */
1596
+ export function readScriptSeed(name: string): Seed | undefined {
1597
+ if (HEAVY_SCRIPTS.includes(name)) return 'heavy'
1598
+ return CHECK_SCRIPT.test(name) || SCOPED_SCRIPT.test(name) ? 'light' : undefined
1599
+ }
1600
+
1601
+ /**
1602
+ * Reads the lane a Vitest command seeds.
1603
+ *
1604
+ * @param args - The arguments after `vitest`.
1605
+ * @returns `heavy` for a run of every project, of several projects, of a project
1606
+ * {@link HEAVY_PROJECTS} names, or of a whole browser project; `light` for a run of named test files
1607
+ * or one other project; undefined for any other run or mode.
1608
+ */
1609
+ export function readVitestSeed(args: readonly string[]): Seed | undefined {
1610
+ const [mode, ...operands] = readOperands(args, VITEST_VALUE_FLAGS)
1611
+ if (mode !== 'run') return undefined
1612
+ const projects = args.flatMap((argument, index) => {
1613
+ if (argument.startsWith('--project=')) return [argument.slice('--project='.length)]
1614
+ return args[index - 1] === '--project' ? [argument] : []
1615
+ })
1616
+ if (
1617
+ projects.length > 1 ||
1618
+ projects.some((project) => project.includes('*') || HEAVY_PROJECTS.includes(project))
1619
+ ) {
1620
+ return 'heavy'
1621
+ }
1622
+ const files = operands.filter((operand) => /\.(?:test|spec)\./u.test(operand))
1623
+ if (files.length === 0 && projects.some((project) => BROWSER_PROJECT.test(project)))
1624
+ return 'heavy'
1625
+ if (files.length > 0 || projects.length === 1) return 'light'
1626
+ return projects.length === 0 && operands.length === 0 ? 'heavy' : undefined
1627
+ }
1628
+
1629
+ /**
1630
+ * Reads the lane a command's kind seeds.
1631
+ *
1632
+ * @remarks
1633
+ * Heavy wins: a word that names a journey, a study, a capture, a live-service run, or the release
1634
+ * chain seeds heavy wherever it appears, before any light kind is read. A `mutate --restore` run,
1635
+ * which writes source files back and wraps no command, seeds heavy.
1636
+ *
1637
+ * @param command - The command and its arguments.
1638
+ * @returns The seeded lane, or undefined when no kind names the command.
1639
+ */
1640
+ export function readSeed(command: readonly string[]): Seed | undefined {
1641
+ if (readWords(command.slice(1)).some((word) => HEAVY_WORDS.includes(word))) return 'heavy'
1642
+ const [tool, ...args] = readTool(command)
1643
+ if (tool === undefined) return undefined
1644
+ if (HEAVY_TOOLS.includes(tool) || matchesRestore(command)) return 'heavy'
1645
+ if (MANAGERS.includes(tool)) {
1646
+ const [verb, script] = readOperands(args, MANAGER_VALUE_FLAGS[tool] ?? [])
1647
+ if (verb === undefined) return undefined
1648
+ if (HEAVY_VERBS.includes(verb)) return 'heavy'
1649
+ return (verb === 'run' || verb === 'run-script') && script !== undefined
1650
+ ? readScriptSeed(script)
1651
+ : undefined
1652
+ }
1653
+ if (tool === 'vitest') return readVitestSeed(args)
1654
+ if (tool === 'oxfmt' || tool === 'prettier') return args.includes('--check') ? 'light' : undefined
1655
+ if (tool === 'oxlint' || tool === 'eslint') {
1656
+ return args.some((argument) => argument.startsWith('--fix')) ? undefined : 'light'
1657
+ }
1658
+ if (tool === 'tsc' || tool === 'vue-tsc') return args.includes('--noEmit') ? 'light' : undefined
1659
+ return undefined
639
1660
  }
640
1661
 
641
1662
  /**
@@ -679,7 +1700,10 @@ export function tryLink(from: string, to: string): boolean {
679
1700
  */
680
1701
  export function linkStage(root: string, token: string): number {
681
1702
  const sequence = Math.max(0, ...readSequences(readNames(root))) + 1
682
- return tryLink(join(root, `${token}${STAGE_SUFFIX}`), join(root, renderTicketName(sequence)))
1703
+ return tryLink(
1704
+ join(root, `${token}${STAGE_SUFFIX}`),
1705
+ join(root, renderName(sequence, TICKET_SUFFIX)),
1706
+ )
683
1707
  ? sequence
684
1708
  : linkStage(root, token)
685
1709
  }
@@ -688,27 +1712,123 @@ export function linkStage(root: string, token: string): number {
688
1712
  * Decides what a process with a ticket does next.
689
1713
  *
690
1714
  * @remarks
691
- * The two listings are separate, because one listing can miss both a ticket linked and a stage file
692
- * removed while it runs. A stage file absent from the first listing belongs to a process whose own
693
- * listing sees this ticket, or to a ticket the second listing sees.
1715
+ * The two listings are separate, because one listing can miss both a ticket linked and a stage file
1716
+ * removed while it runs. A stage file absent from the first listing belongs to a process whose own
1717
+ * listing sees this ticket, or to a ticket the second listing sees. A ticket holds only when the
1718
+ * directory rule of {@link decideDirectory} names no ticket to wait on and its own lane's rule admits
1719
+ * it. Every rule names only an earlier ticket, and an earlier ticket can only leave, so no two tickets
1720
+ * wait on each other and no cycle of waits can form.
1721
+ *
1722
+ * @param root - The queue root.
1723
+ * @param sequence - This process's sequence.
1724
+ * @param token - This process's token.
1725
+ * @param limits - The limits this process read at arrival, which a light ticket's admission needs.
1726
+ * @returns The holder state, the stage file to wait on, the earlier ticket or tickets to wait on, or
1727
+ * a refusal.
1728
+ */
1729
+ export function decideTurn(root: string, sequence: number, token: string, limits?: Limits): Turn {
1730
+ const stage = readNames(root).find(
1731
+ (name) => name.endsWith(STAGE_SUFFIX) && name !== `${token}${STAGE_SUFFIX}`,
1732
+ )
1733
+ if (stage !== undefined) return { state: 'staged', name: stage }
1734
+ const entries = readQueue(root)
1735
+ const position = entries.findIndex((entry) => entry.sequence === sequence)
1736
+ if (position === -1) {
1737
+ return { state: 'refused', reason: `ticket ${renderName(sequence, TICKET_SUFFIX)} is gone` }
1738
+ }
1739
+ const own = entries[position]?.ticket
1740
+ const earlier = entries.slice(0, position)
1741
+ const shared = own === undefined ? undefined : decideDirectory(earlier, own)
1742
+ if (shared !== undefined) return shared
1743
+ return own?.light === undefined || limits === undefined
1744
+ ? decideHeavy(earlier, own?.solo === true)
1745
+ : decideLight(root, earlier, own.light, limits)
1746
+ }
1747
+
1748
+ /**
1749
+ * Decides which earlier ticket the directory rule makes a ticket wait on, whatever its lane.
1750
+ *
1751
+ * @remarks
1752
+ * Every ticket waits on the nearest earlier ticket that carries `edits` and shares its working
1753
+ * directory, because a `mutate` run edits source that ticket reads. A ticket that carries `edits`
1754
+ * also waits on the nearest earlier ticket of its working directory in either lane, and on an
1755
+ * earlier ticket it cannot read, which might share the directory; that wait refuses. The rule names
1756
+ * only earlier tickets, which can only leave, so it adds no cycle of waits. {@link normalizeDirectory}
1757
+ * reads both sides of every comparison.
1758
+ *
1759
+ * @param earlier - The tickets before this one, in arrival order.
1760
+ * @param own - This process's ticket.
1761
+ * @returns The ticket to wait on; undefined when the rule names none.
1762
+ */
1763
+ export function decideDirectory(earlier: readonly Entry[], own: Ticket): Turn | undefined {
1764
+ const entry = earlier.findLast((item) => {
1765
+ if (item.ticket === undefined) return own.edits === true
1766
+ return (
1767
+ (own.edits === true || item.ticket.edits === true) &&
1768
+ sharesDirectory(own.cwd, item.ticket.cwd)
1769
+ )
1770
+ })
1771
+ return entry === undefined ? undefined : { state: 'behind', entry }
1772
+ }
1773
+
1774
+ /**
1775
+ * Decides what a heavy ticket does next.
1776
+ *
1777
+ * @remarks
1778
+ * A heavy ticket waits on the nearest earlier ticket that is not light, an unreadable one included. A
1779
+ * `--solo` ticket waits on the nearest earlier ticket of either lane, so it holds with no light
1780
+ * holder beside it. The rule names only an earlier ticket, so it adds no cycle of waits.
1781
+ *
1782
+ * @param earlier - The tickets before this one, in arrival order.
1783
+ * @param solo - If `true`, waits on light tickets too; if `false`, passes them.
1784
+ * @returns The holder state or the ticket to wait on.
1785
+ */
1786
+ export function decideHeavy(earlier: readonly Entry[], solo: boolean): Turn {
1787
+ const lower = earlier.findLast((entry) => solo || entry.ticket?.light === undefined)
1788
+ return lower === undefined ? { state: 'holder' } : { state: 'behind', entry: lower }
1789
+ }
1790
+
1791
+ /**
1792
+ * Decides what a light ticket does next.
1793
+ *
1794
+ * @remarks
1795
+ * A light ticket holds when every earlier light ticket holds, no earlier `--solo` ticket remains, and
1796
+ * the earlier light footprints with its own fit the limits; the earliest light ticket always fits.
1797
+ * The rule reads only earlier tickets, which can only leave, so an admission is never revoked. An
1798
+ * earlier ticket this process cannot read is waited on alone, which refuses.
694
1799
  *
695
1800
  * @param root - The queue root.
696
- * @param sequence - This process's sequence.
697
- * @param token - This process's token.
698
- * @returns The holder state, the stage file to wait on, the nearest earlier ticket, or a refusal.
1801
+ * @param earlier - The tickets before this one, in arrival order.
1802
+ * @param light - This ticket's footprint.
1803
+ * @param limits - The limits.
1804
+ * @returns The holder state, the unreadable ticket to wait on, or every earlier light and `--solo`
1805
+ * ticket to wait on at once, with the light tickets that do not hold yet.
699
1806
  */
700
- export function decideTurn(root: string, sequence: number, token: string): Turn {
701
- const stage = readNames(root).find(
702
- (name) => name.endsWith(STAGE_SUFFIX) && name !== `${token}${STAGE_SUFFIX}`,
1807
+ export function decideLight(
1808
+ root: string,
1809
+ earlier: readonly Entry[],
1810
+ light: Usage,
1811
+ limits: Limits,
1812
+ ): Turn {
1813
+ const unread = earlier.find(
1814
+ (entry) => entry.ticket === undefined || describeForeign(entry.ticket) !== undefined,
703
1815
  )
704
- if (stage !== undefined) return { state: 'staged', name: stage }
705
- const entries = readQueue(root)
706
- const position = entries.findIndex((entry) => entry.sequence === sequence)
707
- if (position === -1) {
708
- return { state: 'refused', reason: `ticket ${renderTicketName(sequence)} is gone` }
709
- }
710
- const lower = entries[position - 1]
711
- return lower === undefined ? { state: 'holder' } : { state: 'behind', entry: lower }
1816
+ if (unread !== undefined) return { state: 'behind', entry: unread }
1817
+ const lights = earlier.filter((entry) => entry.ticket?.light !== undefined)
1818
+ const solos = earlier.filter((entry) => entry.ticket?.solo === true)
1819
+ const pending = lights.flatMap((entry) => {
1820
+ const blocked =
1821
+ entry.ticket !== undefined &&
1822
+ decideDirectory(earlier.slice(0, earlier.indexOf(entry)), entry.ticket) !== undefined
1823
+ return !blocked && readRun(root, entry.sequence) === 'absent' ? [entry.sequence] : []
1824
+ })
1825
+ const usages = lights.flatMap((entry) =>
1826
+ entry.ticket?.light === undefined ? [] : [entry.ticket.light],
1827
+ )
1828
+ const fits = usages.length === 0 || fitsBudget([...usages, light], limits)
1829
+ return solos.length === 0 && pending.length === 0 && fits
1830
+ ? { state: 'holder' }
1831
+ : { state: 'queued', entries: orderEntries([...lights, ...solos]), pending }
712
1832
  }
713
1833
 
714
1834
  /**
@@ -718,15 +1838,25 @@ export function decideTurn(root: string, sequence: number, token: string): Turn
718
1838
  * @param stage - If `true`, writes the one byte a published owner closes the connection on; if
719
1839
  * `false`, writes nothing.
720
1840
  * @param parked - Called when the connection is open and the wait starts.
721
- * @returns The connect failure's code, or undefined after a connection opened and closed.
1841
+ * @param signal - Ends the wait and the connection when it aborts.
1842
+ * @param hold - If `true`, writes the byte a ticket closes the connection on when it holds; if
1843
+ * `false`, waits only for the process to end.
1844
+ * @returns The connect failure's code, or undefined after a connection opened and closed or the
1845
+ * signal aborted.
722
1846
  */
723
1847
  export function parkOn(
724
1848
  endpoint: string,
725
1849
  stage: boolean,
726
1850
  parked: () => void,
1851
+ signal?: AbortSignal,
1852
+ hold = false,
727
1853
  ): Promise<string | undefined> {
728
1854
  return new Promise((resolve) => {
729
1855
  const socket = connect(endpoint)
1856
+ signal?.addEventListener('abort', () => {
1857
+ socket.destroy()
1858
+ resolve(undefined)
1859
+ })
730
1860
  socket.once('error', (error) => resolve(readCode(error)))
731
1861
  socket.once('connect', () => {
732
1862
  socket.removeAllListeners('error')
@@ -734,28 +1864,12 @@ export function parkOn(
734
1864
  socket.once('close', () => resolve(undefined))
735
1865
  socket.resume()
736
1866
  if (stage) socket.write('s')
1867
+ if (hold) socket.write(HOLD_BYTE)
737
1868
  parked()
738
1869
  })
739
1870
  })
740
1871
  }
741
1872
 
742
- /**
743
- * Connects to an endpoint and leaves at once.
744
- *
745
- * @param endpoint - The endpoint.
746
- * @returns The connect failure's code, or undefined when the connection opened.
747
- */
748
- export function probeEndpoint(endpoint: string): Promise<string | undefined> {
749
- return new Promise((resolve) => {
750
- const socket = connect(endpoint)
751
- socket.once('error', (error) => resolve(readCode(error)))
752
- socket.once('connect', () => {
753
- socket.destroy()
754
- resolve(undefined)
755
- })
756
- })
757
- }
758
-
759
1873
  /**
760
1874
  * Checks whether a connect failure means the endpoint's owner is gone.
761
1875
  *
@@ -828,12 +1942,12 @@ export function readSnapshot(): readonly Row[] | undefined {
828
1942
  * @param ceiling - The latest creation date a row of an exited seed can carry.
829
1943
  * @returns The members.
830
1944
  */
831
- export function selectMembers(
832
- rows: readonly Row[],
1945
+ export function selectMembers<T extends Row>(
1946
+ rows: readonly T[],
833
1947
  seeds: readonly number[],
834
1948
  floor: number,
835
1949
  ceiling: number,
836
- ): readonly Row[] {
1950
+ ): readonly T[] {
837
1951
  const roots = seeds.flatMap((seed) => {
838
1952
  const own = rows.find((row) => row.pid === seed)
839
1953
  return own !== undefined && own.created >= floor && own.created <= ceiling
@@ -887,14 +2001,29 @@ export function readTree(run: Run, ceiling: number): readonly number[] | undefin
887
2001
  if (run.launcher === undefined) return undefined
888
2002
  if (process.platform !== 'win32') return readGroup(run.launcher)
889
2003
  const rows = readSnapshot()
890
- return rows === undefined
891
- ? undefined
892
- : selectMembers(
893
- rows,
894
- run.command === undefined ? [run.launcher] : [run.launcher, run.command],
895
- run.started - CLOCK_ALLOWANCE_MS,
896
- ceiling,
897
- ).map((row) => row.pid)
2004
+ return rows === undefined ? undefined : selectTree(rows, run, ceiling)
2005
+ }
2006
+
2007
+ /**
2008
+ * Selects the members of one run's process tree from a Windows snapshot.
2009
+ *
2010
+ * @param rows - The snapshot.
2011
+ * @param run - The run record.
2012
+ * @param ceiling - The latest creation date a row of an exited seed can carry.
2013
+ * @returns The members' ids, or undefined when the record names no launcher.
2014
+ */
2015
+ export function selectTree(
2016
+ rows: readonly Row[],
2017
+ run: Run,
2018
+ ceiling: number,
2019
+ ): readonly number[] | undefined {
2020
+ if (run.launcher === undefined) return undefined
2021
+ return selectMembers(
2022
+ rows,
2023
+ run.command === undefined ? [run.launcher] : [run.launcher, run.command],
2024
+ run.started - CLOCK_ALLOWANCE_MS,
2025
+ ceiling,
2026
+ ).map((row) => row.pid)
898
2027
  }
899
2028
 
900
2029
  /**
@@ -958,7 +2087,7 @@ export function sweepTree(
958
2087
  */
959
2088
  export function reclaimTicket(root: string, sequence: number, ticket: Ticket): string | undefined {
960
2089
  const run = readRun(root, sequence)
961
- const files = `${renderTicketName(sequence)} and ${renderRunName(sequence)} under ${root}`
2090
+ const files = `${renderName(sequence, TICKET_SUFFIX)} and ${renderName(sequence, RUN_SUFFIX)} under ${root}`
962
2091
  if (run === 'unread' || (run !== 'absent' && run.launcher === undefined)) {
963
2092
  return `the owner of ${quote(ticket.label)} (pid ${String(ticket.pid)}) ended before its tree could be identified; end its tree, then delete ${files}`
964
2093
  }
@@ -967,9 +2096,9 @@ export function reclaimTicket(root: string, sequence: number, ticket: Ticket): s
967
2096
  if (members === undefined || members.length > 0) {
968
2097
  return `the owner of ${quote(ticket.label)} (pid ${String(ticket.pid)}) is gone and its tree reads as ${members === undefined ? 'unread' : `present: ${members.join(', ')}`}; launcher ${String(run.launcher)}, command ${String(run.command)}, files ${files}`
969
2098
  }
970
- removeFile(join(root, renderRunName(sequence)))
2099
+ removeFile(join(root, renderName(sequence, RUN_SUFFIX)))
971
2100
  }
972
- removeFile(join(root, renderTicketName(sequence)))
2101
+ removeFile(join(root, renderName(sequence, TICKET_SUFFIX)))
973
2102
  removeFile(join(root, `${ticket.token}${SOCKET_SUFFIX}`))
974
2103
  return undefined
975
2104
  }
@@ -1007,7 +2136,7 @@ export async function waitOnTicket(
1007
2136
  entry: Entry,
1008
2137
  announced: string | undefined,
1009
2138
  ): Promise<string | undefined> {
1010
- const name = renderTicketName(entry.sequence)
2139
+ const name = renderName(entry.sequence, TICKET_SUFFIX)
1011
2140
  const ticket = entry.ticket
1012
2141
  if (ticket === undefined) return `ticket ${name} under ${root} cannot be read`
1013
2142
  const foreign = describeForeign(ticket)
@@ -1021,24 +2150,79 @@ export async function waitOnTicket(
1021
2150
  : `the endpoint of ticket ${name} reported ${code}`
1022
2151
  }
1023
2152
 
2153
+ /**
2154
+ * Waits on several earlier tickets at once, until the first leaves or a pending one holds, and
2155
+ * reclaims a ticket whose owner is gone.
2156
+ *
2157
+ * @param root - The queue root.
2158
+ * @param entries - The earlier tickets, each readable and of this host.
2159
+ * @param pending - The sequences of the light tickets among them that did not hold yet, whose hold
2160
+ * also ends the wait.
2161
+ * @param announced - The tokens this process last printed a waiting line for, joined by commas.
2162
+ * @returns The refusal, or undefined when the wait ended.
2163
+ */
2164
+ export async function waitOnTickets(
2165
+ root: string,
2166
+ entries: readonly Entry[],
2167
+ pending: readonly number[],
2168
+ announced: string | undefined,
2169
+ ): Promise<string | undefined> {
2170
+ const tickets = entries.flatMap((entry) =>
2171
+ entry.ticket === undefined ? [] : [{ sequence: entry.sequence, ticket: entry.ticket }],
2172
+ )
2173
+ const key = tickets.map((item) => item.ticket.token).join(',')
2174
+ const controller = new AbortController()
2175
+ const opened = tickets.map(() => Promise.withResolvers<void>())
2176
+ const waits = tickets.map((item, index) =>
2177
+ parkOn(
2178
+ renderEndpoint(root, item.ticket.token),
2179
+ false,
2180
+ () => opened[index]?.resolve(),
2181
+ controller.signal,
2182
+ pending.includes(item.sequence),
2183
+ ).then((code) => ({ ...item, code })),
2184
+ )
2185
+ void Promise.all(opened.map((resolvers) => resolvers.promise)).then(() => {
2186
+ if (announced !== key && !controller.signal.aborted) {
2187
+ console.error(
2188
+ `lane: waiting behind ${tickets.map((item) => quote(item.ticket.label)).join(', ')}`,
2189
+ )
2190
+ }
2191
+ })
2192
+ const first = await Promise.race(waits)
2193
+ controller.abort()
2194
+ if (first.code === undefined) return undefined
2195
+ return isGone(first.code)
2196
+ ? reclaimTicket(root, first.sequence, first.ticket)
2197
+ : `the endpoint of ticket ${renderName(first.sequence, TICKET_SUFFIX)} reported ${first.code}`
2198
+ }
2199
+
1024
2200
  /**
1025
2201
  * Waits for this process's turn, parked on events with no timer.
1026
2202
  *
1027
2203
  * @param root - The queue root.
1028
2204
  * @param sequence - This process's sequence.
1029
2205
  * @param token - This process's token.
1030
- * @param announced - The token this process last printed a waiting line for.
2206
+ * @param limits - The limits this process read at arrival.
2207
+ * @param announced - The token or tokens this process last printed a waiting line for.
1031
2208
  * @returns The refusal, or undefined when this process holds the lane.
1032
2209
  */
1033
2210
  export async function waitForTurn(
1034
2211
  root: string,
1035
2212
  sequence: number,
1036
2213
  token: string,
2214
+ limits: Limits | undefined,
1037
2215
  announced?: string,
1038
2216
  ): Promise<string | undefined> {
1039
- const turn = decideTurn(root, sequence, token)
2217
+ const turn = decideTurn(root, sequence, token, limits)
1040
2218
  if (turn.state === 'holder') return undefined
1041
2219
  if (turn.state === 'refused') return turn.reason
2220
+ if (turn.state === 'queued') {
2221
+ const refusal = await waitOnTickets(root, turn.entries, turn.pending, announced)
2222
+ if (refusal !== undefined) return refusal
2223
+ const key = turn.entries.map((entry) => entry.ticket?.token).join(',')
2224
+ return waitForTurn(root, sequence, token, limits, key)
2225
+ }
1042
2226
  const refusal =
1043
2227
  turn.state === 'staged'
1044
2228
  ? await waitOnStage(root, turn.name)
@@ -1048,6 +2232,7 @@ export async function waitForTurn(
1048
2232
  root,
1049
2233
  sequence,
1050
2234
  token,
2235
+ limits,
1051
2236
  turn.state === 'behind' ? turn.entry.ticket?.token : announced,
1052
2237
  )
1053
2238
  }
@@ -1133,6 +2318,19 @@ export function waitForClose(child: ChildProcess): Promise<number | undefined> {
1133
2318
  })
1134
2319
  }
1135
2320
 
2321
+ /**
2322
+ * Waits for a started launcher to exit, which precedes the close of its streams.
2323
+ *
2324
+ * @param child - The started launcher.
2325
+ * @returns When it exited or failed, in epoch milliseconds.
2326
+ */
2327
+ export function waitForExit(child: ChildProcess): Promise<number> {
2328
+ return new Promise((resolve) => {
2329
+ child.once('error', () => resolve(Date.now()))
2330
+ child.once('exit', () => resolve(Date.now()))
2331
+ })
2332
+ }
2333
+
1136
2334
  /**
1137
2335
  * Writes a run record, leaving an unwritten id to the handover reading.
1138
2336
  *
@@ -1159,70 +2357,532 @@ export function tryWriteRun(root: string, sequence: number, run: Run): boolean {
1159
2357
  */
1160
2358
  export function releaseTicket(root: string, sequence: number): string | undefined {
1161
2359
  try {
1162
- removeFile(join(root, renderRunName(sequence)))
1163
- removeFile(join(root, renderTicketName(sequence)))
2360
+ removeFile(join(root, renderName(sequence, RUN_SUFFIX)))
2361
+ removeFile(join(root, renderName(sequence, TICKET_SUFFIX)))
1164
2362
  return undefined
1165
2363
  } catch (error) {
1166
2364
  return readCode(error)
1167
2365
  }
1168
2366
  }
1169
2367
 
2368
+ /**
2369
+ * Parses one sampler line.
2370
+ *
2371
+ * @param line - One line of the sampler's stdout, its rows separated by semicolons.
2372
+ * @returns One gauge per row that has the row's form, its CPU time in milliseconds.
2373
+ */
2374
+ export function parseGauges(line: string): readonly Gauge[] {
2375
+ return line.split(';').flatMap((item) => {
2376
+ const match = GAUGE_PATTERN.exec(item.trim())
2377
+ return match === null
2378
+ ? []
2379
+ : [
2380
+ {
2381
+ pid: Number(match[1]),
2382
+ parent: Number(match[2]),
2383
+ created: Number(match[3]),
2384
+ cpu: Number(match[4]) / 10_000,
2385
+ memory: Number(match[5]),
2386
+ },
2387
+ ]
2388
+ })
2389
+ }
2390
+
2391
+ /**
2392
+ * Waits for a promise within a bound.
2393
+ *
2394
+ * @param promise - The promise.
2395
+ * @param budget - The longest wait in milliseconds.
2396
+ * @returns The promise's value; undefined when the budget runs out first.
2397
+ */
2398
+ export async function waitForBound<T>(promise: Promise<T>, budget: number): Promise<T | undefined> {
2399
+ const timer = Promise.withResolvers<undefined>()
2400
+ const handle = setTimeout(() => timer.resolve(undefined), budget)
2401
+ try {
2402
+ return await Promise.race([promise, timer.promise])
2403
+ } finally {
2404
+ clearTimeout(handle)
2405
+ }
2406
+ }
2407
+
2408
+ /**
2409
+ * Parses one sample line of a sampler.
2410
+ *
2411
+ * @param line - One line of the sampler's stdout: `1` or `0`, a `|`, and the rows.
2412
+ * @returns Whether a byte asked for the sample, with its gauges; undefined for a line without the
2413
+ * marker, such as {@link READY_LINE}.
2414
+ */
2415
+ export function parseSample(line: string): Sample | undefined {
2416
+ const split = line.indexOf('|')
2417
+ if (split === -1) return undefined
2418
+ return { requested: line.slice(0, split) === '1', gauges: parseGauges(line.slice(split + 1)) }
2419
+ }
2420
+
2421
+ /**
2422
+ * Folds one sample's members into a tally.
2423
+ *
2424
+ * @param tally - The tally so far.
2425
+ * @param members - The members one sample read.
2426
+ * @returns The tally with each member's latest CPU time, keyed by id and creation date, and the
2427
+ * larger of each peak.
2428
+ */
2429
+ export function tallySample(tally: Tally, members: readonly Gauge[]): Tally {
2430
+ return {
2431
+ cpu: new Map([
2432
+ ...tally.cpu,
2433
+ ...members.map((member): [string, number] => {
2434
+ const key = `${String(member.pid)}:${String(member.created)}`
2435
+ return [key, Math.max(member.cpu, tally.cpu.get(key) ?? 0)]
2436
+ }),
2437
+ ]),
2438
+ memory: Math.max(
2439
+ tally.memory,
2440
+ members.reduce((sum, member) => sum + member.memory, 0),
2441
+ ),
2442
+ processes: Math.max(tally.processes, members.length),
2443
+ }
2444
+ }
2445
+
2446
+ /**
2447
+ * Builds a run's record from its tally.
2448
+ *
2449
+ * @param tally - The sampler's tally.
2450
+ * @param duration - The run's duration in milliseconds.
2451
+ * @param code - The lane's exit code for the run.
2452
+ * @returns The record, its CPU time summed across every member the samples read.
2453
+ */
2454
+ export function buildOutcome(tally: Tally, duration: number, code: number): Outcome {
2455
+ return {
2456
+ duration,
2457
+ cpu: [...tally.cpu.values()].reduce((sum, value) => sum + value, 0),
2458
+ memory: tally.memory,
2459
+ processes: tally.processes,
2460
+ code,
2461
+ }
2462
+ }
2463
+
2464
+ /**
2465
+ * Sets a process to below-normal priority, which a Windows child inherits.
2466
+ *
2467
+ * @param pid - The process id.
2468
+ * @returns True when the host took the priority; false when it refused.
2469
+ */
2470
+ export function lowerPriority(pid: number): boolean {
2471
+ try {
2472
+ setPriority(pid, constants.priority.PRIORITY_BELOW_NORMAL)
2473
+ return true
2474
+ } catch {
2475
+ return false
2476
+ }
2477
+ }
2478
+
2479
+ /**
2480
+ * Writes a run's record, leaving a write the host refuses unrecorded.
2481
+ *
2482
+ * @param root - The queue root.
2483
+ * @param key - The command's key.
2484
+ * @param name - The record's name.
2485
+ * @param outcome - The record.
2486
+ * @returns True when the write created the key's directory; false when the key existed or the host
2487
+ * refused the write.
2488
+ */
2489
+ export function tryWriteOutcome(
2490
+ root: string,
2491
+ key: string,
2492
+ name: string,
2493
+ outcome: Outcome,
2494
+ ): boolean {
2495
+ try {
2496
+ return writeOutcome(root, key, name, outcome)
2497
+ } catch {
2498
+ return false
2499
+ }
2500
+ }
2501
+
2502
+ /**
2503
+ * Samples one holder's process tree through one PowerShell child at below-normal priority.
2504
+ *
2505
+ * @remarks
2506
+ * The child starts at arrival and readies while the ticket waits, so a holder starts its command
2507
+ * only after the child can answer at once. A {@link Sampler.sample} call starts one sample at once;
2508
+ * after the first, the child also samples every {@link SAMPLE_MS}. The child exits when its stdin
2509
+ * closes, which {@link Sampler.stop} and the end of this process both do. A threshold, given for a
2510
+ * light run, calls the breach handler once with the launcher's id, on the first sample before
2511
+ * {@link Sampler.seal} whose memory or process count passes it.
2512
+ */
2513
+ export class Sampler {
2514
+ readonly #child: ChildProcess
2515
+ readonly #closed: Promise<void>
2516
+ readonly #ready = Promise.withResolvers<boolean>()
2517
+ readonly #waiters = new Map<number, (gauges: readonly Gauge[] | undefined) => void>()
2518
+ readonly #threshold: Usage | undefined
2519
+ readonly #breach: (launcher: number) => void
2520
+ #seeds: readonly number[] = []
2521
+ #floor: number | undefined
2522
+ #ceiling: number | undefined
2523
+ #tally: Tally = { cpu: new Map(), memory: 0, processes: 0 }
2524
+ #breached = false
2525
+ #asked = 0
2526
+ #answered = 0
2527
+
2528
+ /**
2529
+ * Starts the sampler.
2530
+ *
2531
+ * @param threshold - The light run's threshold, or undefined for a heavy run.
2532
+ * @param breach - Called once with the launcher's id when a sample passes the threshold. The
2533
+ * launcher is the one seed the lane holds a live handle on until it exits, so ending its tree
2534
+ * reaches the command and never a reused id.
2535
+ * @param command - The PowerShell text the child runs, for a proof. Default: {@link SAMPLER_COMMAND}.
2536
+ */
2537
+ constructor(
2538
+ threshold: Usage | undefined,
2539
+ breach: (launcher: number) => void,
2540
+ command = SAMPLER_COMMAND,
2541
+ ) {
2542
+ this.#threshold = threshold
2543
+ this.#breach = breach
2544
+ this.#child = spawn(
2545
+ 'powershell.exe',
2546
+ ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command],
2547
+ { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true },
2548
+ )
2549
+ this.#closed = waitForClose(this.#child).then(() => {
2550
+ this.#ready.resolve(false)
2551
+ for (const resolve of this.#waiters.values()) resolve(undefined)
2552
+ this.#waiters.clear()
2553
+ })
2554
+ this.#child.stdin?.on('error', () => undefined)
2555
+ if (this.#child.pid !== undefined) lowerPriority(this.#child.pid)
2556
+ if (this.#child.stdout !== null) {
2557
+ const lines = createInterface({ input: this.#child.stdout, crlfDelay: Infinity })
2558
+ lines.on('error', () => undefined)
2559
+ lines.on('line', (line) => this.#read(line))
2560
+ }
2561
+ }
2562
+
2563
+ /** Holds the sampler's process id, undefined when it could not start. */
2564
+ get pid(): number | undefined {
2565
+ return this.#child.pid
2566
+ }
2567
+
2568
+ /** Holds what the samples read so far. */
2569
+ get tally(): Tally {
2570
+ return this.#tally
2571
+ }
2572
+
2573
+ /** Holds whether a sample passed the threshold. */
2574
+ get breached(): boolean {
2575
+ return this.#breached
2576
+ }
2577
+
2578
+ /**
2579
+ * Waits until the child can sample at once, within a budget.
2580
+ *
2581
+ * @param budget - The longest wait in milliseconds.
2582
+ * @returns A promise of true when the child readied; false when it ended first or the budget ran out.
2583
+ */
2584
+ async ready(budget: number): Promise<boolean> {
2585
+ return (await waitForBound(this.#ready.promise, budget)) ?? false
2586
+ }
2587
+
2588
+ /**
2589
+ * Names the ids whose trees later samples read.
2590
+ *
2591
+ * @param seeds - The launcher id and, once known, the command id.
2592
+ * @param floor - The earliest creation date the tree can carry.
2593
+ */
2594
+ seed(seeds: readonly number[], floor: number): void {
2595
+ this.#seeds = seeds
2596
+ this.#floor = floor
2597
+ }
2598
+
2599
+ /**
2600
+ * Marks the launcher's exit: a later sample reads no member created after it and triggers no
2601
+ * breach, so a reused id after the exit is never ended.
2602
+ *
2603
+ * @param ceiling - When the launcher exited, in epoch milliseconds.
2604
+ */
2605
+ seal(ceiling: number): void {
2606
+ this.#ceiling = ceiling
2607
+ }
2608
+
2609
+ /**
2610
+ * Starts one sample at once.
2611
+ *
2612
+ * @param budget - The longest wait in milliseconds for the answer. Default: no bound.
2613
+ * @returns A promise of every row the sample read, taken after this call; undefined when the
2614
+ * child ends first, cannot take the request, or does not answer within the budget.
2615
+ */
2616
+ sample(budget?: number): Promise<readonly Gauge[] | undefined> {
2617
+ const stdin = this.#child.stdin
2618
+ if (
2619
+ stdin === null ||
2620
+ stdin.writableEnded ||
2621
+ this.#child.pid === undefined ||
2622
+ this.#child.exitCode !== null ||
2623
+ this.#child.signalCode !== null
2624
+ ) {
2625
+ return Promise.resolve(undefined)
2626
+ }
2627
+ this.#asked += 1
2628
+ const answer = Promise.withResolvers<readonly Gauge[] | undefined>()
2629
+ this.#waiters.set(this.#asked, answer.resolve)
2630
+ stdin.write(SAMPLE_BYTE)
2631
+ return budget === undefined ? answer.promise : waitForBound(answer.promise, budget)
2632
+ }
2633
+
2634
+ /**
2635
+ * Samples back to back until a time or an abort, one sample after the previous one answers.
2636
+ *
2637
+ * @param until - The epoch millisecond after which no further sample starts.
2638
+ * @param signal - Ends the burst after the sample in flight.
2639
+ * @returns A promise that resolves when the burst ends.
2640
+ */
2641
+ async burst(until: number, signal: AbortSignal): Promise<void> {
2642
+ const rows = await this.sample()
2643
+ if (rows === undefined || signal.aborted || Date.now() >= until) return
2644
+ await this.burst(until, signal)
2645
+ }
2646
+
2647
+ /**
2648
+ * Closes the sampler's stdin, which ends it, and ends the child at once when it has not exited
2649
+ * within {@link HANDOVER_MS}.
2650
+ *
2651
+ * @returns A promise that resolves when the sampler has exited.
2652
+ */
2653
+ async stop(): Promise<void> {
2654
+ this.#child.stdin?.end()
2655
+ const exited = await waitForBound(
2656
+ this.#closed.then(() => true),
2657
+ HANDOVER_MS,
2658
+ )
2659
+ if (exited === undefined) await this.destroy()
2660
+ }
2661
+
2662
+ /**
2663
+ * Ends the child at once, for a sampler that did not ready and might not read its stdin.
2664
+ *
2665
+ * @returns A promise that resolves when the child has exited.
2666
+ */
2667
+ destroy(): Promise<void> {
2668
+ this.#child.stdin?.end()
2669
+ this.#child.kill()
2670
+ return this.#closed
2671
+ }
2672
+
2673
+ // A sample a byte asked for answers the oldest open request, because the child answers bytes in order.
2674
+ #read(line: string): void {
2675
+ if (line === READY_LINE) {
2676
+ this.#ready.resolve(true)
2677
+ return
2678
+ }
2679
+ const sample = parseSample(line)
2680
+ if (sample === undefined) return
2681
+ if (sample.requested) {
2682
+ this.#answered += 1
2683
+ this.#waiters.get(this.#answered)?.(sample.gauges)
2684
+ this.#waiters.delete(this.#answered)
2685
+ }
2686
+ if (this.#floor === undefined) return
2687
+ const members = selectMembers(
2688
+ sample.gauges,
2689
+ this.#seeds,
2690
+ this.#floor,
2691
+ this.#ceiling ?? Date.now(),
2692
+ )
2693
+ this.#tally = tallySample(this.#tally, members)
2694
+ const threshold = this.#threshold
2695
+ if (
2696
+ threshold === undefined ||
2697
+ this.#ceiling !== undefined ||
2698
+ this.#breached ||
2699
+ (this.#tally.memory <= threshold.memory && this.#tally.processes <= threshold.processes)
2700
+ ) {
2701
+ return
2702
+ }
2703
+ const [launcher] = this.#seeds
2704
+ if (launcher === undefined) return
2705
+ this.#breached = true
2706
+ this.#breach(launcher)
2707
+ }
2708
+ }
2709
+
1170
2710
  /**
1171
2711
  * Runs the command as the holder, reads the tree at handover, and releases.
1172
2712
  *
2713
+ * @remarks
2714
+ * A measured holder starts its command after its sampler readies, samples the tree back to back
2715
+ * through the command's first {@link SAMPLE_MS} and once every {@link SAMPLE_MS} after, reads the
2716
+ * handover through one more sample, and writes the run's record before it releases, so the command's
2717
+ * next arrival reads it. When that sample lists a member, the handover reads, kills, and reads again
2718
+ * through fresh snapshots, each a second PowerShell. A sampler that does not ready within
2719
+ * {@link READY_MS} is destroyed, and the command runs unmeasured and records nothing. A record that
2720
+ * opened a key prunes the history after the release. A light holder lowers its own priority before
2721
+ * the spawn, and ends its tree when a sample passes the threshold.
2722
+ *
1173
2723
  * @param options - The run.
1174
2724
  * @param launcher - The launcher's path.
1175
2725
  * @param sequence - This process's sequence.
1176
- * @returns The launcher's code; 1 when a signal ended it; 70 when the tree still reads as present or
1177
- * the ticket could not be removed; 75 when the launcher could not start.
2726
+ * @param measure - What a measured holder needs, or undefined when no limits apply.
2727
+ * @param token - This process's endpoint, which holds after the run record exists and leaves before
2728
+ * the run record is removed.
2729
+ * @param sampler - The measured holder's sampler, started at arrival; the caller stops it.
2730
+ * @returns The launcher's code; 1 when a signal ended it; 69 when a light run passed its threshold;
2731
+ * 70 when the tree still reads as present or the ticket could not be removed; 75 when the launcher
2732
+ * could not start, the priority could not be lowered, or the run record could not be written.
1178
2733
  */
1179
2734
  export async function runHolder(
1180
2735
  options: LaneOptions,
1181
2736
  launcher: string,
1182
2737
  sequence: number,
2738
+ measure?: Measure,
2739
+ token?: Token,
2740
+ sampler?: Sampler,
1183
2741
  ): Promise<number> {
1184
2742
  const { root } = options
2743
+ if (measure?.light !== undefined && !lowerPriority(process.pid)) {
2744
+ releaseTicket(root, sequence)
2745
+ console.error('lane: the host refused the light run its below-normal priority')
2746
+ return 75
2747
+ }
2748
+ const measured = sampler !== undefined && (await sampler.ready(READY_MS))
2749
+ if (sampler !== undefined && !measured) {
2750
+ await sampler.destroy()
2751
+ console.error(
2752
+ `lane: the sampler did not ready within ${String(READY_MS)} ms; ${quote(options.label)} runs unmeasured`,
2753
+ )
2754
+ }
2755
+ const active = measured ? sampler : undefined
1185
2756
  const started = Date.now()
1186
- writeRun(root, sequence, { started, launcher: undefined, command: undefined })
2757
+ if (!tryWriteRun(root, sequence, { started, launcher: undefined, command: undefined })) {
2758
+ const refusal = releaseTicket(root, sequence)
2759
+ console.error(
2760
+ `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}`}`,
2761
+ )
2762
+ return refusal === undefined ? 75 : HELD_CODE
2763
+ }
2764
+ token?.hold()
1187
2765
  const child = startLauncher(launcher, options)
1188
2766
  const id = child.pid
1189
2767
  if (id === undefined) {
2768
+ token?.leave()
1190
2769
  releaseTicket(root, sequence)
1191
2770
  console.error(`lane: ${quote(launcher)} could not start`)
1192
2771
  return 75
1193
2772
  }
1194
2773
  tryWriteRun(root, sequence, { started, launcher: id, command: undefined })
2774
+ const floor = started - CLOCK_ALLOWANCE_MS
2775
+ const early = new AbortController()
2776
+ active?.seed([id], floor)
1195
2777
  const unwatch = watchSignals(() => killMembers([id]))
1196
2778
  const closed = waitForClose(child)
2779
+ const exited = waitForExit(child).then((at) => {
2780
+ active?.seal(at)
2781
+ return at
2782
+ })
1197
2783
  if (child.stdout !== null) {
1198
2784
  const lines = createInterface({ input: child.stdout, crlfDelay: Infinity })
1199
2785
  lines.on('error', () => undefined)
1200
2786
  lines.on('line', (line) => {
1201
2787
  console.log(line)
1202
2788
  const command = readCommandId(line)
1203
- if (command !== undefined) tryWriteRun(root, sequence, { started, launcher: id, command })
2789
+ if (command === undefined) return
2790
+ tryWriteRun(root, sequence, { started, launcher: id, command })
2791
+ active?.seed([id, command], floor)
2792
+ void active?.burst(Date.now() + SAMPLE_MS, early.signal)
1204
2793
  })
1205
2794
  }
1206
2795
  const code = await closed
2796
+ const ended = await exited
2797
+ early.abort()
1207
2798
  unwatch()
1208
- const ended = Date.now()
1209
2799
  const run = readRun(root, sequence)
2800
+ const rows = typeof run === 'object' ? await active?.sample(HANDOVER_MS) : undefined
2801
+ const hung = active !== undefined && typeof run === 'object' && rows === undefined
2802
+ if (hung) {
2803
+ await active.destroy()
2804
+ console.error(
2805
+ `lane: the sampler did not answer the handover within ${String(HANDOVER_MS)} ms; ${quote(options.label)} records nothing`,
2806
+ )
2807
+ }
2808
+ const quick =
2809
+ rows !== undefined && typeof run === 'object' ? selectTree(rows, run, ended) : undefined
1210
2810
  const sweep =
1211
- run === 'absent' || run === 'unread'
2811
+ typeof run !== 'object'
1212
2812
  ? { gone: false, members: [] }
1213
- : sweepTree(() => readTree(run, ended), killMembers, KILL_BUDGET)
2813
+ : quick?.length === 0
2814
+ ? { gone: true, members: [] }
2815
+ : sweepTree(() => readTree(run, ended), killMembers, KILL_BUDGET)
2816
+ const stopped = active?.stop()
2817
+ const breached = active?.breached === true
2818
+ const result = !sweep.gone ? HELD_CODE : breached ? BREACH_CODE : (code ?? 1)
2819
+ const opened =
2820
+ measure !== undefined &&
2821
+ active !== undefined &&
2822
+ !hung &&
2823
+ tryWriteOutcome(
2824
+ root,
2825
+ measure.key,
2826
+ renderOutcomeName(ended, measure.token),
2827
+ buildOutcome(active.tally, ended - started, result),
2828
+ )
1214
2829
  if (!sweep.gone) {
1215
2830
  console.error(
1216
- `lane: the tree of ${quote(options.label)} still reads as ${sweep.members.length === 0 ? 'unread' : `present: ${sweep.members.join(', ')}`}; the lane stays held by ${renderTicketName(sequence)} and ${renderRunName(sequence)} under ${root}`,
2831
+ `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}`,
1217
2832
  )
1218
- return 70
2833
+ await stopped
2834
+ return HELD_CODE
1219
2835
  }
2836
+ token?.leave()
1220
2837
  const refusal = releaseTicket(root, sequence)
2838
+ const prune = opened ? pruneHistory(root, Date.now()) : undefined
2839
+ if (prune !== undefined && prune.skipped.length > 0) {
2840
+ console.error(
2841
+ `lane: the history prune under ${root} skipped ${String(prune.skipped.length)} entries it could not list or remove, such as ${quote(prune.skipped.join(', '))}`,
2842
+ )
2843
+ }
2844
+ await stopped
1221
2845
  if (refusal !== undefined) {
1222
- console.error(`lane: removing ${renderTicketName(sequence)} reported ${refusal}`)
1223
- return 70
2846
+ console.error(`lane: removing ${renderName(sequence, TICKET_SUFFIX)} reported ${refusal}`)
2847
+ return HELD_CODE
1224
2848
  }
1225
- return code ?? 1
2849
+ if (breached) {
2850
+ console.error(
2851
+ `lane: ${quote(options.label)} passed the light threshold and was ended; its next arrival runs heavy`,
2852
+ )
2853
+ }
2854
+ return result
2855
+ }
2856
+
2857
+ /**
2858
+ * Reads what a run measures at arrival: the limits, the command's key, and its light footprint.
2859
+ *
2860
+ * @remarks
2861
+ * A host other than Windows has no sampler, so it measures nothing and every ticket there is heavy.
2862
+ * A `--solo` run is heavy whatever its command reads. A `mutate` run is keyed without its edits
2863
+ * file and seeded by its wrapped command; {@link decideDirectory} keeps it apart from the tickets of
2864
+ * its working directory.
2865
+ *
2866
+ * @param options - The run.
2867
+ * @param token - This process's token.
2868
+ * @returns What the holder measures, or undefined when `limits.json` is absent or malformed or the
2869
+ * host has no sampler.
2870
+ */
2871
+ export function readMeasure(options: LaneOptions, token: string): Measure | undefined {
2872
+ if (process.platform !== 'win32') return undefined
2873
+ const limits = readLimits(options.root)
2874
+ if (limits === 'unread') {
2875
+ console.error(
2876
+ `lane: ${LIMITS_FILE} under ${options.root} cannot be read as limits; the ticket runs heavy`,
2877
+ )
2878
+ }
2879
+ if (limits === 'absent' || limits === 'unread') return undefined
2880
+ const key = renderKey(normalizeDirectory(process.cwd()), normalizeCommand(options.command))
2881
+ if (options.solo) return { limits, key, token, light: undefined }
2882
+ const mutation = extractMutation(options.command)
2883
+ const seed = readSeed(mutation ?? options.command)
2884
+ const light = classifyLight(seed, readOutcomes(options.root, key), limits)
2885
+ return { limits, key, token, light }
1226
2886
  }
1227
2887
 
1228
2888
  /**
@@ -1243,22 +2903,37 @@ export async function enterLane(
1243
2903
  const { root } = options
1244
2904
  try {
1245
2905
  mkdirSync(root, { recursive: true })
1246
- await token.listen(renderEndpoint(root, tokenId))
1247
- writeStage(root, buildTicket(tokenId, options.label))
1248
- const sequence = linkStage(root, tokenId)
1249
- removeFile(join(root, `${tokenId}${STAGE_SUFFIX}`))
1250
- token.publish()
1251
- const unwatch = watchSignals(() => {
1252
- removeFile(join(root, renderTicketName(sequence)))
1253
- removeFile(renderEndpoint(root, tokenId))
1254
- process.exit(75)
1255
- })
1256
- const refusal = await waitForTurn(root, sequence, tokenId)
1257
- unwatch()
1258
- if (refusal === undefined) return await runHolder(options, launcher, sequence)
1259
- removeFile(join(root, renderTicketName(sequence)))
1260
- console.error(`lane: ${refusal}`)
1261
- return 75
2906
+ const measure = readMeasure(options, tokenId)
2907
+ const sampler =
2908
+ measure === undefined
2909
+ ? undefined
2910
+ : new Sampler(measure.light === undefined ? undefined : measure.limits.threshold, (pid) =>
2911
+ killMembers([pid]),
2912
+ )
2913
+ try {
2914
+ await token.listen(renderEndpoint(root, tokenId))
2915
+ const edits =
2916
+ extractMutation(options.command) !== undefined || matchesRestore(options.command)
2917
+ writeStage(root, buildTicket(tokenId, options.label, measure?.light, options.solo, edits))
2918
+ const sequence = linkStage(root, tokenId)
2919
+ removeFile(join(root, `${tokenId}${STAGE_SUFFIX}`))
2920
+ token.publish()
2921
+ const unwatch = watchSignals(() => {
2922
+ removeFile(join(root, renderName(sequence, TICKET_SUFFIX)))
2923
+ removeFile(renderEndpoint(root, tokenId))
2924
+ process.exit(75)
2925
+ })
2926
+ const refusal = await waitForTurn(root, sequence, tokenId, measure?.limits)
2927
+ unwatch()
2928
+ if (refusal === undefined) {
2929
+ return await runHolder(options, launcher, sequence, measure, token, sampler)
2930
+ }
2931
+ removeFile(join(root, renderName(sequence, TICKET_SUFFIX)))
2932
+ console.error(`lane: ${refusal}`)
2933
+ return 75
2934
+ } finally {
2935
+ await sampler?.stop()
2936
+ }
1262
2937
  } catch (error) {
1263
2938
  console.error(`lane: the queue under ${root} refused the run: ${String(error)}`)
1264
2939
  return 75
@@ -1292,47 +2967,72 @@ export async function runLane(options: LaneOptions): Promise<number> {
1292
2967
  */
1293
2968
  export async function readStatusRow(root: string, entry: Entry): Promise<StatusRow> {
1294
2969
  const ticket = entry.ticket
1295
- const fields = { sequence: entry.sequence, label: ticket?.label, pid: ticket?.pid }
2970
+ const fields = {
2971
+ sequence: entry.sequence,
2972
+ label: ticket?.label,
2973
+ pid: ticket?.pid,
2974
+ light: ticket?.light !== undefined,
2975
+ solo: ticket?.solo === true,
2976
+ edits: ticket?.edits === true,
2977
+ }
1296
2978
  if (ticket === undefined || describeForeign(ticket) !== undefined) {
1297
- return { ...fields, state: 'unread' }
2979
+ return { ...fields, state: 'unread', holding: false }
2980
+ }
2981
+ const probe = new AbortController()
2982
+ const code = await parkOn(
2983
+ renderEndpoint(root, ticket.token),
2984
+ false,
2985
+ () => probe.abort(),
2986
+ probe.signal,
2987
+ )
2988
+ if (code === undefined) {
2989
+ const holding = existsSync(join(root, renderName(entry.sequence, RUN_SUFFIX)))
2990
+ return { ...fields, state: 'live', holding }
1298
2991
  }
1299
- const code = await probeEndpoint(renderEndpoint(root, ticket.token))
1300
- if (code === undefined) return { ...fields, state: 'live' }
1301
- return { ...fields, state: isGone(code) ? 'dead' : 'unread' }
2992
+ return { ...fields, state: isGone(code) ? 'dead' : 'unread', holding: false }
1302
2993
  }
1303
2994
 
1304
2995
  /**
1305
2996
  * Reads the queue for `--status`.
1306
2997
  *
1307
2998
  * @param root - The queue root.
1308
- * @returns Every ticket in arrival order, and the earliest live ticket with a run record.
2999
+ * @returns Every ticket in arrival order, and the earliest holding ticket that is not light.
1309
3000
  */
1310
3001
  export async function readStatus(root: string): Promise<Status> {
1311
3002
  const tickets = await Promise.all(readQueue(root).map((entry) => readStatusRow(root, entry)))
1312
- return {
1313
- tickets,
1314
- holder: tickets.find(
1315
- (row) => row.state === 'live' && existsSync(join(root, renderRunName(row.sequence))),
1316
- ),
1317
- }
3003
+ return { tickets, holder: tickets.find((row) => row.holding && !row.light) }
1318
3004
  }
1319
3005
 
1320
3006
  /**
1321
3007
  * Renders the queue as text.
1322
3008
  *
1323
3009
  * @param status - What `--status` read.
1324
- * @returns One line for the holder and one per ticket, in arrival order.
3010
+ * @returns One line for the heavy holder, one naming every light holder, and one per ticket with its
3011
+ * lane, in arrival order.
1325
3012
  */
1326
3013
  export function renderStatus(status: Status): string {
3014
+ const lights = status.tickets.filter((row) => row.holding && row.light)
1327
3015
  return [
1328
3016
  `holder: ${status.holder === undefined ? 'none' : quote(status.holder.label ?? 'unread')}`,
3017
+ `light: ${lights.length === 0 ? 'none' : lights.map((row) => quote(row.label ?? 'unread')).join(', ')}`,
1329
3018
  ...status.tickets.map(
1330
3019
  (row) =>
1331
- `${renderTicketName(row.sequence)} ${row.state} ${quote(row.label ?? 'unread')} pid ${String(row.pid)}`,
3020
+ `${renderName(row.sequence, TICKET_SUFFIX)} ${row.state} ${renderLane(row)}${row.edits ? ' edits' : ''}${row.holding ? ' holding' : ''} ${quote(row.label ?? 'unread')} pid ${String(row.pid)}`,
1332
3021
  ),
1333
3022
  ].join('\n')
1334
3023
  }
1335
3024
 
3025
+ /**
3026
+ * Names a ticket's lane for `--status`.
3027
+ *
3028
+ * @param row - The ticket's row.
3029
+ * @returns `solo`, `light`, or `heavy`.
3030
+ */
3031
+ export function renderLane(row: StatusRow): string {
3032
+ if (row.solo) return 'solo'
3033
+ return row.light ? 'light' : 'heavy'
3034
+ }
3035
+
1336
3036
  /**
1337
3037
  * Prints the queue, writing nothing under the root.
1338
3038
  *
@@ -1351,36 +3051,54 @@ export async function runStatus(root: string, json: boolean): Promise<number> {
1351
3051
  }
1352
3052
  }
1353
3053
 
3054
+ /**
3055
+ * Parses a cap given in seconds.
3056
+ *
3057
+ * @param text - The value after `--cap`.
3058
+ * @returns The cap, or undefined when the text is absent, not a finite number, not above 0, or past
3059
+ * the launcher's limit.
3060
+ */
3061
+ export function parseCap(text: string | undefined): number | undefined {
3062
+ const cap = Number(text ?? Number.NaN)
3063
+ return Number.isFinite(cap) && cap > 0 && cap <= MAX_CAP_SECONDS ? cap : undefined
3064
+ }
3065
+
1354
3066
  /**
1355
3067
  * Validates a run's arguments.
1356
3068
  *
1357
- * @param own - The arguments before the bare `--`.
3069
+ * @param values - The flag values `parseArgs` read before the bare `--`.
1358
3070
  * @param command - The arguments after the bare `--`.
1359
3071
  * @returns The run, or undefined when a flag or the command is missing or out of range.
1360
3072
  */
1361
3073
  export function readLaneOptions(
1362
- own: readonly string[],
3074
+ values: Arguments['values'],
1363
3075
  command: readonly string[],
1364
3076
  ): LaneOptions | undefined {
1365
- const label = readOption(own, '--label')
1366
- const journal = readOption(own, '--journal')
1367
- const errors = readOption(own, '--errors')
1368
- const cap = Number(readOption(own, '--cap') ?? Number.NaN)
3077
+ const label = typeof values.label === 'string' ? values.label : undefined
3078
+ const journal = typeof values.journal === 'string' ? values.journal : undefined
3079
+ const errors = typeof values.errors === 'string' ? values.errors : undefined
3080
+ const cap = parseCap(typeof values.cap === 'string' ? values.cap : undefined)
1369
3081
  if (
1370
3082
  label === undefined ||
1371
3083
  label === '' ||
1372
3084
  journal === undefined ||
1373
3085
  errors === undefined ||
1374
3086
  journal === errors ||
1375
- !Number.isFinite(cap) ||
1376
- cap <= 0 ||
1377
- cap > MAX_CAP_SECONDS ||
3087
+ cap === undefined ||
1378
3088
  command[0] === undefined ||
1379
3089
  command[0] === ''
1380
3090
  ) {
1381
3091
  return undefined
1382
3092
  }
1383
- return { root: resolveRoot(readOption(own, '--root')), label, journal, errors, cap, command }
3093
+ return {
3094
+ root: resolveRoot(typeof values.root === 'string' ? values.root : undefined),
3095
+ label,
3096
+ journal,
3097
+ errors,
3098
+ cap,
3099
+ solo: values.solo === true,
3100
+ command,
3101
+ }
1384
3102
  }
1385
3103
 
1386
3104
  /**
@@ -1394,31 +3112,29 @@ export function readLaneOptions(
1394
3112
  */
1395
3113
  export async function main(argv: readonly string[]): Promise<number> {
1396
3114
  const end = argv.indexOf('--')
1397
- const own = end === -1 ? argv : argv.slice(0, end)
1398
3115
  const command = end === -1 ? [] : argv.slice(end + 1)
1399
- const unknown = readUnknownFlags(argv, FLAGS)
1400
- if (unknown.length > 0) {
1401
- console.error(`lane: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
1402
- return 64
1403
- }
1404
- const missing = readMissingFlags(own, VALUE_FLAGS)
1405
- if (missing.length > 0) {
1406
- console.error(`lane: ${missing.join(', ')} given with no value; ${USAGE}`)
1407
- return 64
1408
- }
1409
- if (readPositionals(own, VALUE_FLAGS).length > 0) {
1410
- console.error(USAGE)
3116
+ const parsed = parseArguments(end === -1 ? argv : argv.slice(0, end))
3117
+ if (!parsed.success) {
3118
+ console.error(`lane: ${parsed.error}; ${USAGE}`)
1411
3119
  return 64
1412
3120
  }
1413
- const status = own.includes('--status')
1414
- if (status) {
1415
- if (end !== -1 || RUN_FLAGS.some((flag) => own.includes(flag))) {
3121
+ const { values } = parsed.value
3122
+ const root = typeof values.root === 'string' ? values.root : undefined
3123
+ if (values.status === true) {
3124
+ if (end !== -1 || RUN_OPTIONS.some((name) => values[name] !== undefined)) {
1416
3125
  console.error(`lane: --status and a run are two modes; ${USAGE}`)
1417
3126
  return 64
1418
3127
  }
1419
- return runStatus(resolveRoot(readOption(own, '--root')), own.includes('--json'))
3128
+ return runStatus(resolveRoot(root), values.json === true)
3129
+ }
3130
+ const cap = typeof values.cap === 'string' ? values.cap : undefined
3131
+ if (cap !== undefined && parseCap(cap) === undefined) {
3132
+ console.error(
3133
+ `lane: --cap takes a number of seconds above 0 up to ${String(MAX_CAP_SECONDS)}, not ${quote(cap)}; ${USAGE}`,
3134
+ )
3135
+ return 64
1420
3136
  }
1421
- const options = own.includes('--json') ? undefined : readLaneOptions(own, command)
3137
+ const options = values.json === true ? undefined : readLaneOptions(values, command)
1422
3138
  if (options === undefined) {
1423
3139
  console.error(USAGE)
1424
3140
  return 64