@orkestrel/scaffold 0.0.134 → 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 (40) hide show
  1. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +610 -79
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +307 -16
  3. package/dist/bin/main.js +253 -35
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/AGENTS.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  7. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +782 -115
  8. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  9. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -5
  10. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +379 -27
  11. package/dist/host/claude/agents/orkestrel.md +14 -14
  12. package/dist/host/claude/rules/architecture.md +1 -1
  13. package/dist/host/claude/rules/patterns.md +2 -0
  14. package/dist/host/claude/rules/workspace.md +64 -63
  15. package/dist/host/configs/helpers.ts +88 -67
  16. package/dist/host/dotfiles/oxlintrc.json +1 -57
  17. package/dist/host/guides/agent.md +989 -395
  18. package/dist/host/guides/database.md +357 -342
  19. package/dist/host/guides/middleware.md +5 -5
  20. package/dist/host/guides/ollama.md +41 -42
  21. package/dist/host/guides/scaffold.md +177 -105
  22. package/dist/host/guides/study.md +12 -12
  23. package/dist/host/guides/test.md +158 -46
  24. package/dist/host/guides/toolbox.md +127 -81
  25. package/dist/host/guides/workspace.md +21 -14
  26. package/dist/host/manifest.json +23 -23
  27. package/dist/host/tests/config.test.ts +166 -112
  28. package/dist/src/core/index.cjs +491 -195
  29. package/dist/src/core/index.cjs.map +1 -1
  30. package/dist/src/core/index.d.cts +217 -24
  31. package/dist/src/core/index.d.ts +217 -24
  32. package/dist/src/core/index.js +482 -193
  33. package/dist/src/core/index.js.map +1 -1
  34. package/dist/src/server/index.cjs +18 -8
  35. package/dist/src/server/index.cjs.map +1 -1
  36. package/dist/src/server/index.d.cts +4 -3
  37. package/dist/src/server/index.d.ts +4 -3
  38. package/dist/src/server/index.js +19 -9
  39. package/dist/src/server/index.js.map +1 -1
  40. package/package.json +2 -2
@@ -12,25 +12,48 @@
12
12
  // Lanes: a ticket is heavy unless its arrival reads it light, and the reading is frozen in the
13
13
  // ticket. A heavy ticket holds when it is the earliest live non-light ticket; a `--solo` ticket is
14
14
  // heavy and also waits out every earlier light ticket. A light ticket holds when every earlier light
15
- // ticket holds, no earlier `--solo` ticket is live, and the light holders' summed peaks with its own
16
- // fit `slots` and each budget; the earliest light ticket always fits. A light holder runs at
17
- // below-normal priority, and its holder ends it and exits 69 when a sample passes the memory or
18
- // process threshold.
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.
19
30
  // Light reading: `<root>/limits.json` holds `slots`, the `budget` and the per-run `threshold`; while
20
31
  // it is absent or malformed, or on a host other than Windows, every ticket is heavy, no sampler runs,
21
- // and no record is written. Otherwise each holder samples its tree through one PowerShell child that
22
- // exits when its stdin closes, and writes one record per run under `<root>/history/<key>/`, keyed by
23
- // the working directory and the command, keeping the latest runs. The command's kind seeds the
24
- // reading: a format check, a lint check, a type check, and a scoped test run read light until a
25
- // record breaches; a full suite, a run of several projects, an install, a pack-and-install suite, a
26
- // release chain, a journey, a study, a capture, and a live-service run read heavy; any other command reads light only when its latest runs each sit
27
- // inside the threshold, none capped and none ending 69 or 70.
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.
28
51
  // `--status` prints each ticket in arrival order with its label, `live`, `dead`, or `unread`, its
29
- // lane, and `holding` for a holder, and names the heavy holder and every light holder. It writes
30
- // nothing, removes nothing, and creates no root; an absent root reads as an empty queue. The root is
31
- // `.orkestrel/lane` under the account's home directory, read from the account record and never from
32
- // an environment variable; `--root DIR` is for a proof. Bench execs stay outside the lane, because
33
- // the host bound counts process-running commands.
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.
34
57
  // Exit: the launcher's code (the command's code, 124 when capped, 127 when the command could not
35
58
  // start); 1 when a signal ended the launcher; 64 on usage; 69 when a light run passed its threshold
36
59
  // and its holder ended it; 75 when the lane refused before the command ran; 70 when the command ran
@@ -44,9 +67,9 @@
44
67
  // owner closes that connection, because a connection its synchronous allocation left unaccepted
45
68
  // would otherwise stay parked on a process that waits behind it. A light waiter writes `h` to an
46
69
  // earlier light ticket that did not hold yet, and that owner closes the connection when it holds,
47
- // so the waiter decides again; a byte that reaches an owner that is releasing parks until it ends. The protocol stays 1: the `light` and `solo` ticket fields are
48
- // optional, a ticket without them reads as heavy, and a process of the first release holds only as
49
- // the earliest ticket.
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.
50
73
  // Limits:
51
74
  // - Process-identifier reuse, Windows. A row is matched by id and creation date, bounded by a clock
52
75
  // comparison, so a reuse of an exited seed's id inside the clock allowance can misattribute a row.
@@ -64,10 +87,36 @@
64
87
  // - An owner ended between the run record and the launcher id. The tree cannot be identified. Arrivals
65
88
  // exit 75 until a person deletes the named files. An owner ended between the launcher id and the
66
89
  // command id leaves the command as no seed, so its tree reads through the launcher alone.
67
- // - A dead light holder with a live tree. Light arrivals exit 75 until that tree is gone; heavy
68
- // arrivals do not wait on it.
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.
69
93
  // - Sampling. A process that lives between two samples goes uncounted, the CPU time of a member that
70
- // exits between samples is lost, and disk input and output are not measured.
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.
71
120
  // - An unreaped member. On a host whose init does not reap, a killed member can keep reading as
72
121
  // present. The lane exits 70 and stays held.
73
122
  // - Listing completeness. No probe proves that a listing returns every stable entry. The design takes
@@ -95,11 +144,20 @@ import {
95
144
  readFileSync,
96
145
  realpathSync,
97
146
  rmSync,
147
+ statSync,
98
148
  writeFileSync,
99
149
  } from 'node:fs'
100
150
  import { connect, createServer } from 'node:net'
101
151
  import { constants, hostname, setPriority, userInfo } from 'node:os'
102
- import { basename, dirname, extname, isAbsolute, join } from 'node:path'
152
+ import {
153
+ basename,
154
+ dirname,
155
+ extname,
156
+ isAbsolute,
157
+ join,
158
+ resolve as resolvePath,
159
+ sep,
160
+ } from 'node:path'
103
161
  import { createInterface } from 'node:readline'
104
162
  import { fileURLToPath } from 'node:url'
105
163
  import { parseArgs } from 'node:util'
@@ -243,6 +301,33 @@ export const ENDED_WIDTH = 15
243
301
  /** Holds the count of latest records the light reading takes, which is also the count each key keeps. */
244
302
  export const RECENT_RUNS = 3
245
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
+
246
331
  /** Holds the pause in milliseconds between two samples of a holder's tree. */
247
332
  export const SAMPLE_MS = 1000
248
333
 
@@ -306,6 +391,49 @@ export const DOTTED_FLAG = /^--[^=.]+\.[^=]+$/u
306
391
  /** Lists the package managers whose verbs and scripts a seed reads. */
307
392
  export const MANAGERS: readonly string[] = ['npm', 'pnpm', 'yarn', 'bun']
308
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
+
309
437
  /** Lists the tools a seed reads heavy by name: the release chain's step runner. */
310
438
  export const HEAVY_TOOLS: readonly string[] = ['steps']
311
439
 
@@ -344,8 +472,23 @@ export const SCOPED_SCRIPT = /^test:/u
344
472
  /** Matches one sampler row: process id, parent id, creation time in milliseconds, CPU time in 100 ns units, and private bytes. */
345
473
  export const GAUGE_PATTERN = /^(\d+) (\d+) (\d+) (\d+) (\d+)$/u
346
474
 
347
- /** Holds the PowerShell text that prints one line of rows per sample until its stdin closes. */
348
- export const SAMPLER_COMMAND = `$i=[Console]::OpenStandardInput();$b=New-Object byte[] 1;$t=$i.ReadAsync($b,0,1);while(-not $t.IsCompleted){$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($r -join ';');[Console]::Out.Flush();Start-Sleep -Milliseconds ${String(SAMPLE_MS)}}`
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)}}`
349
492
 
350
493
  /** Describes the footprint the light lanes add up: average cores, peak private bytes, and peak processes. */
351
494
  export interface Usage {
@@ -384,6 +527,18 @@ export interface Gauge extends Row {
384
527
  readonly memory: number
385
528
  }
386
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
+
387
542
  /** Describes what a sampler has read: each member's latest CPU time by id and creation date, and the peaks. */
388
543
  export interface Tally {
389
544
  readonly cpu: ReadonlyMap<string, number>
@@ -399,7 +554,10 @@ export interface Measure {
399
554
  readonly light: Usage | undefined
400
555
  }
401
556
 
402
- /** Describes the complete record a stage file holds and a ticket publishes; `light` holds the footprint a light ticket counts. */
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
+ */
403
561
  export interface Ticket {
404
562
  readonly protocol: number
405
563
  readonly token: string
@@ -411,6 +569,7 @@ export interface Ticket {
411
569
  readonly arrived: string
412
570
  readonly light?: Usage
413
571
  readonly solo?: boolean
572
+ readonly edits?: boolean
414
573
  }
415
574
 
416
575
  /** Describes one ticket in the queue: its sequence and its record, undefined when unreadable. */
@@ -454,7 +613,7 @@ export interface Sweep {
454
613
  readonly members: readonly number[]
455
614
  }
456
615
 
457
- /** Describes one ticket as `--status` reports it; `holding` marks a live ticket with a run record. */
616
+ /** Describes one ticket as `--status` reports it; `edits` marks a `mutate` run, and `holding` a live ticket with a run record. */
458
617
  export interface StatusRow {
459
618
  readonly sequence: number
460
619
  readonly label: string | undefined
@@ -462,6 +621,7 @@ export interface StatusRow {
462
621
  readonly state: 'live' | 'dead' | 'unread'
463
622
  readonly light: boolean
464
623
  readonly solo: boolean
624
+ readonly edits: boolean
465
625
  readonly holding: boolean
466
626
  }
467
627
 
@@ -693,7 +853,8 @@ export function isTicket(value: unknown): value is Ticket {
693
853
  'arrived' in value &&
694
854
  typeof value.arrived === 'string' &&
695
855
  (!('light' in value) || isUsage(value.light)) &&
696
- (!('solo' in value) || typeof value.solo === 'boolean')
856
+ (!('solo' in value) || typeof value.solo === 'boolean') &&
857
+ (!('edits' in value) || typeof value.edits === 'boolean')
697
858
  )
698
859
  }
699
860
 
@@ -896,9 +1057,17 @@ export function removeFile(path: string): void {
896
1057
  * @param light - The footprint a light ticket counts, or undefined for a heavy ticket.
897
1058
  * @param solo - If `true`, marks a ticket that waits out every earlier light ticket; if `false`, omits
898
1059
  * the field.
899
- * @returns The complete ticket, carrying `light` and `solo` only when they are set.
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.
900
1063
  */
901
- export function buildTicket(token: string, label: string, light?: Usage, solo = false): Ticket {
1064
+ export function buildTicket(
1065
+ token: string,
1066
+ label: string,
1067
+ light?: Usage,
1068
+ solo = false,
1069
+ edits = false,
1070
+ ): Ticket {
902
1071
  return {
903
1072
  protocol: PROTOCOL,
904
1073
  token,
@@ -910,6 +1079,7 @@ export function buildTicket(token: string, label: string, light?: Usage, solo =
910
1079
  arrived: new Date().toISOString(),
911
1080
  ...(light === undefined ? {} : { light }),
912
1081
  ...(solo ? { solo } : {}),
1082
+ ...(edits ? { edits } : {}),
913
1083
  }
914
1084
  }
915
1085
 
@@ -994,14 +1164,98 @@ export function readOutcomes(root: string, key: string): ReadonlyArray<Outcome |
994
1164
  * @param key - The command's key.
995
1165
  * @param name - The record's name.
996
1166
  * @param outcome - The record.
1167
+ * @returns True when the write created the key's directory; false when the key existed.
997
1168
  */
998
- export function writeOutcome(root: string, key: string, name: string, outcome: Outcome): void {
1169
+ export function writeOutcome(root: string, key: string, name: string, outcome: Outcome): boolean {
999
1170
  const directory = join(root, HISTORY_DIRECTORY, key)
1000
- mkdirSync(directory, { recursive: true })
1171
+ const created = mkdirSync(directory, { recursive: true }) !== undefined
1001
1172
  writeFileSync(join(directory, name), JSON.stringify(outcome), { flag: 'wx' })
1002
1173
  for (const stale of readOutcomeNames(root, key).slice(0, -RECENT_RUNS)) {
1003
1174
  removeFile(join(directory, stale))
1004
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
+ }
1005
1259
  }
1006
1260
 
1007
1261
  /**
@@ -1134,10 +1388,12 @@ export function readToolName(path: string): string {
1134
1388
  }
1135
1389
 
1136
1390
  /**
1137
- * Reads the tool a command runs and the tool's arguments, past Node and `npx`.
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.
1138
1393
  *
1139
1394
  * @param command - The command and its arguments.
1140
- * @returns The tool's name followed by its arguments; empty for inline Node code or no script.
1395
+ * @returns The tool's name followed by its arguments; empty for inline Node code, inline exec text,
1396
+ * or no script.
1141
1397
  */
1142
1398
  export function readTool(command: readonly string[]): readonly string[] {
1143
1399
  const [executable, ...rest] = command
@@ -1151,13 +1407,166 @@ export function readTool(command: readonly string[]): readonly string[] {
1151
1407
  }
1152
1408
  return readTool(rest.slice(script))
1153
1409
  }
1154
- if (name === 'npx') {
1155
- const tool = rest.findIndex((argument) => !argument.startsWith('-'))
1156
- return tool === -1 ? [] : readTool(rest.slice(tool))
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
+ }
1157
1419
  }
1158
1420
  return [name, ...rest]
1159
1421
  }
1160
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
+
1161
1570
  /**
1162
1571
  * Reads the positional arguments of a command, skipping each value of a value-taking flag.
1163
1572
  *
@@ -1222,7 +1631,8 @@ export function readVitestSeed(args: readonly string[]): Seed | undefined {
1222
1631
  *
1223
1632
  * @remarks
1224
1633
  * Heavy wins: a word that names a journey, a study, a capture, a live-service run, or the release
1225
- * chain seeds heavy wherever it appears, before any light kind is read.
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.
1226
1636
  *
1227
1637
  * @param command - The command and its arguments.
1228
1638
  * @returns The seeded lane, or undefined when no kind names the command.
@@ -1231,9 +1641,9 @@ export function readSeed(command: readonly string[]): Seed | undefined {
1231
1641
  if (readWords(command.slice(1)).some((word) => HEAVY_WORDS.includes(word))) return 'heavy'
1232
1642
  const [tool, ...args] = readTool(command)
1233
1643
  if (tool === undefined) return undefined
1234
- if (HEAVY_TOOLS.includes(tool)) return 'heavy'
1644
+ if (HEAVY_TOOLS.includes(tool) || matchesRestore(command)) return 'heavy'
1235
1645
  if (MANAGERS.includes(tool)) {
1236
- const [verb, script] = readOperands(args, [])
1646
+ const [verb, script] = readOperands(args, MANAGER_VALUE_FLAGS[tool] ?? [])
1237
1647
  if (verb === undefined) return undefined
1238
1648
  if (HEAVY_VERBS.includes(verb)) return 'heavy'
1239
1649
  return (verb === 'run' || verb === 'run-script') && script !== undefined
@@ -1304,7 +1714,10 @@ export function linkStage(root: string, token: string): number {
1304
1714
  * @remarks
1305
1715
  * The two listings are separate, because one listing can miss both a ticket linked and a stage file
1306
1716
  * removed while it runs. A stage file absent from the first listing belongs to a process whose own
1307
- * listing sees this ticket, or to a ticket the second listing sees.
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.
1308
1721
  *
1309
1722
  * @param root - The queue root.
1310
1723
  * @param sequence - This process's sequence.
@@ -1325,18 +1738,46 @@ export function decideTurn(root: string, sequence: number, token: string, limits
1325
1738
  }
1326
1739
  const own = entries[position]?.ticket
1327
1740
  const earlier = entries.slice(0, position)
1741
+ const shared = own === undefined ? undefined : decideDirectory(earlier, own)
1742
+ if (shared !== undefined) return shared
1328
1743
  return own?.light === undefined || limits === undefined
1329
1744
  ? decideHeavy(earlier, own?.solo === true)
1330
1745
  : decideLight(root, earlier, own.light, limits)
1331
1746
  }
1332
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
+
1333
1774
  /**
1334
1775
  * Decides what a heavy ticket does next.
1335
1776
  *
1336
1777
  * @remarks
1337
1778
  * A heavy ticket waits on the nearest earlier ticket that is not light, an unreadable one included. A
1338
1779
  * `--solo` ticket waits on the nearest earlier ticket of either lane, so it holds with no light
1339
- * holder beside it.
1780
+ * holder beside it. The rule names only an earlier ticket, so it adds no cycle of waits.
1340
1781
  *
1341
1782
  * @param earlier - The tickets before this one, in arrival order.
1342
1783
  * @param solo - If `true`, waits on light tickets too; if `false`, passes them.
@@ -1375,9 +1816,12 @@ export function decideLight(
1375
1816
  if (unread !== undefined) return { state: 'behind', entry: unread }
1376
1817
  const lights = earlier.filter((entry) => entry.ticket?.light !== undefined)
1377
1818
  const solos = earlier.filter((entry) => entry.ticket?.solo === true)
1378
- const pending = lights.flatMap((entry) =>
1379
- readRun(root, entry.sequence) === 'absent' ? [entry.sequence] : [],
1380
- )
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
+ })
1381
1825
  const usages = lights.flatMap((entry) =>
1382
1826
  entry.ticket?.light === undefined ? [] : [entry.ticket.light],
1383
1827
  )
@@ -1557,14 +2001,29 @@ export function readTree(run: Run, ceiling: number): readonly number[] | undefin
1557
2001
  if (run.launcher === undefined) return undefined
1558
2002
  if (process.platform !== 'win32') return readGroup(run.launcher)
1559
2003
  const rows = readSnapshot()
1560
- return rows === undefined
1561
- ? undefined
1562
- : selectMembers(
1563
- rows,
1564
- run.command === undefined ? [run.launcher] : [run.launcher, run.command],
1565
- run.started - CLOCK_ALLOWANCE_MS,
1566
- ceiling,
1567
- ).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)
1568
2027
  }
1569
2028
 
1570
2029
  /**
@@ -1859,6 +2318,19 @@ export function waitForClose(child: ChildProcess): Promise<number | undefined> {
1859
2318
  })
1860
2319
  }
1861
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
+
1862
2334
  /**
1863
2335
  * Writes a run record, leaving an unwritten id to the handover reading.
1864
2336
  *
@@ -1916,6 +2388,36 @@ export function parseGauges(line: string): readonly Gauge[] {
1916
2388
  })
1917
2389
  }
1918
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
+
1919
2421
  /**
1920
2422
  * Folds one sample's members into a tally.
1921
2423
  *
@@ -1981,7 +2483,8 @@ export function lowerPriority(pid: number): boolean {
1981
2483
  * @param key - The command's key.
1982
2484
  * @param name - The record's name.
1983
2485
  * @param outcome - The record.
1984
- * @returns True when the record was written; false otherwise.
2486
+ * @returns True when the write created the key's directory; false when the key existed or the host
2487
+ * refused the write.
1985
2488
  */
1986
2489
  export function tryWriteOutcome(
1987
2490
  root: string,
@@ -1990,8 +2493,7 @@ export function tryWriteOutcome(
1990
2493
  outcome: Outcome,
1991
2494
  ): boolean {
1992
2495
  try {
1993
- writeOutcome(root, key, name, outcome)
1994
- return true
2496
+ return writeOutcome(root, key, name, outcome)
1995
2497
  } catch {
1996
2498
  return false
1997
2499
  }
@@ -2001,37 +2503,54 @@ export function tryWriteOutcome(
2001
2503
  * Samples one holder's process tree through one PowerShell child at below-normal priority.
2002
2504
  *
2003
2505
  * @remarks
2004
- * The child exits when its stdin closes, which {@link Sampler.stop} and the end of this process both
2005
- * do. A threshold, given for a light run, calls the breach handler once, on the first sample whose
2006
- * memory or process count passes it.
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.
2007
2512
  */
2008
2513
  export class Sampler {
2009
2514
  readonly #child: ChildProcess
2010
2515
  readonly #closed: Promise<void>
2011
- readonly #floor: number
2516
+ readonly #ready = Promise.withResolvers<boolean>()
2517
+ readonly #waiters = new Map<number, (gauges: readonly Gauge[] | undefined) => void>()
2012
2518
  readonly #threshold: Usage | undefined
2013
- readonly #breach: () => void
2519
+ readonly #breach: (launcher: number) => void
2014
2520
  #seeds: readonly number[] = []
2521
+ #floor: number | undefined
2522
+ #ceiling: number | undefined
2015
2523
  #tally: Tally = { cpu: new Map(), memory: 0, processes: 0 }
2016
2524
  #breached = false
2525
+ #asked = 0
2526
+ #answered = 0
2017
2527
 
2018
2528
  /**
2019
2529
  * Starts the sampler.
2020
2530
  *
2021
- * @param floor - The earliest creation date the tree can carry.
2022
2531
  * @param threshold - The light run's threshold, or undefined for a heavy run.
2023
- * @param breach - Called once when a sample passes the threshold.
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}.
2024
2536
  */
2025
- constructor(floor: number, threshold: Usage | undefined, breach: () => void) {
2026
- this.#floor = floor
2537
+ constructor(
2538
+ threshold: Usage | undefined,
2539
+ breach: (launcher: number) => void,
2540
+ command = SAMPLER_COMMAND,
2541
+ ) {
2027
2542
  this.#threshold = threshold
2028
2543
  this.#breach = breach
2029
2544
  this.#child = spawn(
2030
2545
  'powershell.exe',
2031
- ['-NoProfile', '-NonInteractive', '-Command', SAMPLER_COMMAND],
2546
+ ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command],
2032
2547
  { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true },
2033
2548
  )
2034
- this.#closed = waitForClose(this.#child).then(() => undefined)
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
+ })
2035
2554
  this.#child.stdin?.on('error', () => undefined)
2036
2555
  if (this.#child.pid !== undefined) lowerPriority(this.#child.pid)
2037
2556
  if (this.#child.stdout !== null) {
@@ -2056,38 +2575,135 @@ export class Sampler {
2056
2575
  return this.#breached
2057
2576
  }
2058
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
+
2059
2588
  /**
2060
2589
  * Names the ids whose trees later samples read.
2061
2590
  *
2062
2591
  * @param seeds - The launcher id and, once known, the command id.
2592
+ * @param floor - The earliest creation date the tree can carry.
2063
2593
  */
2064
- seed(seeds: readonly number[]): void {
2594
+ seed(seeds: readonly number[], floor: number): void {
2065
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)
2066
2645
  }
2067
2646
 
2068
2647
  /**
2069
- * Closes the sampler's stdin, which ends it.
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}.
2070
2650
  *
2071
2651
  * @returns A promise that resolves when the sampler has exited.
2072
2652
  */
2073
- stop(): Promise<void> {
2653
+ async stop(): Promise<void> {
2074
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()
2075
2670
  return this.#closed
2076
2671
  }
2077
2672
 
2673
+ // A sample a byte asked for answers the oldest open request, because the child answers bytes in order.
2078
2674
  #read(line: string): void {
2079
- const members = selectMembers(parseGauges(line), this.#seeds, this.#floor, Date.now())
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
+ )
2080
2693
  this.#tally = tallySample(this.#tally, members)
2081
2694
  const threshold = this.#threshold
2082
2695
  if (
2083
2696
  threshold === undefined ||
2697
+ this.#ceiling !== undefined ||
2084
2698
  this.#breached ||
2085
2699
  (this.#tally.memory <= threshold.memory && this.#tally.processes <= threshold.processes)
2086
2700
  ) {
2087
2701
  return
2088
2702
  }
2703
+ const [launcher] = this.#seeds
2704
+ if (launcher === undefined) return
2089
2705
  this.#breached = true
2090
- this.#breach()
2706
+ this.#breach(launcher)
2091
2707
  }
2092
2708
  }
2093
2709
 
@@ -2095,9 +2711,14 @@ export class Sampler {
2095
2711
  * Runs the command as the holder, reads the tree at handover, and releases.
2096
2712
  *
2097
2713
  * @remarks
2098
- * A measured holder samples its tree and writes the run's record before it releases, so the
2099
- * command's next arrival reads it. A light holder lowers its own priority before the spawn, and ends
2100
- * its tree when a sample passes the threshold.
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.
2101
2722
  *
2102
2723
  * @param options - The run.
2103
2724
  * @param launcher - The launcher's path.
@@ -2105,6 +2726,7 @@ export class Sampler {
2105
2726
  * @param measure - What a measured holder needs, or undefined when no limits apply.
2106
2727
  * @param token - This process's endpoint, which holds after the run record exists and leaves before
2107
2728
  * the run record is removed.
2729
+ * @param sampler - The measured holder's sampler, started at arrival; the caller stops it.
2108
2730
  * @returns The launcher's code; 1 when a signal ended it; 69 when a light run passed its threshold;
2109
2731
  * 70 when the tree still reads as present or the ticket could not be removed; 75 when the launcher
2110
2732
  * could not start, the priority could not be lowered, or the run record could not be written.
@@ -2115,6 +2737,7 @@ export async function runHolder(
2115
2737
  sequence: number,
2116
2738
  measure?: Measure,
2117
2739
  token?: Token,
2740
+ sampler?: Sampler,
2118
2741
  ): Promise<number> {
2119
2742
  const { root } = options
2120
2743
  if (measure?.light !== undefined && !lowerPriority(process.pid)) {
@@ -2122,6 +2745,14 @@ export async function runHolder(
2122
2745
  console.error('lane: the host refused the light run its below-normal priority')
2123
2746
  return 75
2124
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
2125
2756
  const started = Date.now()
2126
2757
  if (!tryWriteRun(root, sequence, { started, launcher: undefined, command: undefined })) {
2127
2758
  const refusal = releaseTicket(root, sequence)
@@ -2140,17 +2771,15 @@ export async function runHolder(
2140
2771
  return 75
2141
2772
  }
2142
2773
  tryWriteRun(root, sequence, { started, launcher: id, command: undefined })
2143
- const sampler =
2144
- measure === undefined
2145
- ? undefined
2146
- : new Sampler(
2147
- started - CLOCK_ALLOWANCE_MS,
2148
- measure.light === undefined ? undefined : measure.limits.threshold,
2149
- () => killMembers([id]),
2150
- )
2151
- sampler?.seed([id])
2774
+ const floor = started - CLOCK_ALLOWANCE_MS
2775
+ const early = new AbortController()
2776
+ active?.seed([id], floor)
2152
2777
  const unwatch = watchSignals(() => killMembers([id]))
2153
2778
  const closed = waitForClose(child)
2779
+ const exited = waitForExit(child).then((at) => {
2780
+ active?.seal(at)
2781
+ return at
2782
+ })
2154
2783
  if (child.stdout !== null) {
2155
2784
  const lines = createInterface({ input: child.stdout, crlfDelay: Infinity })
2156
2785
  lines.on('error', () => undefined)
@@ -2159,28 +2788,44 @@ export async function runHolder(
2159
2788
  const command = readCommandId(line)
2160
2789
  if (command === undefined) return
2161
2790
  tryWriteRun(root, sequence, { started, launcher: id, command })
2162
- sampler?.seed([id, command])
2791
+ active?.seed([id, command], floor)
2792
+ void active?.burst(Date.now() + SAMPLE_MS, early.signal)
2163
2793
  })
2164
2794
  }
2165
2795
  const code = await closed
2796
+ const ended = await exited
2797
+ early.abort()
2166
2798
  unwatch()
2167
- const ended = Date.now()
2168
- const stopped = sampler?.stop()
2169
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
2170
2810
  const sweep =
2171
- run === 'absent' || run === 'unread'
2811
+ typeof run !== 'object'
2172
2812
  ? { gone: false, members: [] }
2173
- : sweepTree(() => readTree(run, ended), killMembers, KILL_BUDGET)
2174
- const breached = sampler?.breached === true
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
2175
2818
  const result = !sweep.gone ? HELD_CODE : breached ? BREACH_CODE : (code ?? 1)
2176
- if (measure !== undefined && sampler !== undefined) {
2819
+ const opened =
2820
+ measure !== undefined &&
2821
+ active !== undefined &&
2822
+ !hung &&
2177
2823
  tryWriteOutcome(
2178
2824
  root,
2179
2825
  measure.key,
2180
2826
  renderOutcomeName(ended, measure.token),
2181
- buildOutcome(sampler.tally, ended - started, result),
2827
+ buildOutcome(active.tally, ended - started, result),
2182
2828
  )
2183
- }
2184
2829
  if (!sweep.gone) {
2185
2830
  console.error(
2186
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}`,
@@ -2190,6 +2835,12 @@ export async function runHolder(
2190
2835
  }
2191
2836
  token?.leave()
2192
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
+ }
2193
2844
  await stopped
2194
2845
  if (refusal !== undefined) {
2195
2846
  console.error(`lane: removing ${renderName(sequence, TICKET_SUFFIX)} reported ${refusal}`)
@@ -2208,7 +2859,9 @@ export async function runHolder(
2208
2859
  *
2209
2860
  * @remarks
2210
2861
  * A host other than Windows has no sampler, so it measures nothing and every ticket there is heavy.
2211
- * A `--solo` run is heavy whatever its command reads.
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.
2212
2865
  *
2213
2866
  * @param options - The run.
2214
2867
  * @param token - This process's token.
@@ -2224,10 +2877,11 @@ export function readMeasure(options: LaneOptions, token: string): Measure | unde
2224
2877
  )
2225
2878
  }
2226
2879
  if (limits === 'absent' || limits === 'unread') return undefined
2227
- const key = renderKey(realpathSync(process.cwd()), options.command)
2228
- const light = options.solo
2229
- ? undefined
2230
- : classifyLight(readSeed(options.command), readOutcomes(options.root, key), limits)
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)
2231
2885
  return { limits, key, token, light }
2232
2886
  }
2233
2887
 
@@ -2250,24 +2904,36 @@ export async function enterLane(
2250
2904
  try {
2251
2905
  mkdirSync(root, { recursive: true })
2252
2906
  const measure = readMeasure(options, tokenId)
2253
- await token.listen(renderEndpoint(root, tokenId))
2254
- writeStage(root, buildTicket(tokenId, options.label, measure?.light, options.solo))
2255
- const sequence = linkStage(root, tokenId)
2256
- removeFile(join(root, `${tokenId}${STAGE_SUFFIX}`))
2257
- token.publish()
2258
- const unwatch = watchSignals(() => {
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
+ }
2259
2931
  removeFile(join(root, renderName(sequence, TICKET_SUFFIX)))
2260
- removeFile(renderEndpoint(root, tokenId))
2261
- process.exit(75)
2262
- })
2263
- const refusal = await waitForTurn(root, sequence, tokenId, measure?.limits)
2264
- unwatch()
2265
- if (refusal === undefined) {
2266
- return await runHolder(options, launcher, sequence, measure, token)
2932
+ console.error(`lane: ${refusal}`)
2933
+ return 75
2934
+ } finally {
2935
+ await sampler?.stop()
2267
2936
  }
2268
- removeFile(join(root, renderName(sequence, TICKET_SUFFIX)))
2269
- console.error(`lane: ${refusal}`)
2270
- return 75
2271
2937
  } catch (error) {
2272
2938
  console.error(`lane: the queue under ${root} refused the run: ${String(error)}`)
2273
2939
  return 75
@@ -2307,6 +2973,7 @@ export async function readStatusRow(root: string, entry: Entry): Promise<StatusR
2307
2973
  pid: ticket?.pid,
2308
2974
  light: ticket?.light !== undefined,
2309
2975
  solo: ticket?.solo === true,
2976
+ edits: ticket?.edits === true,
2310
2977
  }
2311
2978
  if (ticket === undefined || describeForeign(ticket) !== undefined) {
2312
2979
  return { ...fields, state: 'unread', holding: false }
@@ -2350,7 +3017,7 @@ export function renderStatus(status: Status): string {
2350
3017
  `light: ${lights.length === 0 ? 'none' : lights.map((row) => quote(row.label ?? 'unread')).join(', ')}`,
2351
3018
  ...status.tickets.map(
2352
3019
  (row) =>
2353
- `${renderName(row.sequence, TICKET_SUFFIX)} ${row.state} ${renderLane(row)}${row.holding ? ' holding' : ''} ${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)}`,
2354
3021
  ),
2355
3022
  ].join('\n')
2356
3023
  }