@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
@@ -1,10 +1,10 @@
1
1
  import { spawn, spawnSync } from 'node:child_process';
2
2
  import { createHash, randomUUID } from 'node:crypto';
3
3
  import { once } from 'node:events';
4
- import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
4
+ import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
5
5
  import { connect, createServer } from 'node:net';
6
6
  import { constants, hostname, setPriority, userInfo } from 'node:os';
7
- import { basename, dirname, extname, isAbsolute, join } from 'node:path';
7
+ import { basename, dirname, extname, isAbsolute, join, resolve as resolvePath, sep, } from 'node:path';
8
8
  import { createInterface } from 'node:readline';
9
9
  import { fileURLToPath } from 'node:url';
10
10
  import { parseArgs } from 'node:util';
@@ -106,6 +106,29 @@ export const OUTCOME_SUFFIX = '.json';
106
106
  export const ENDED_WIDTH = 15;
107
107
  /** Holds the count of latest records the light reading takes, which is also the count each key keeps. */
108
108
  export const RECENT_RUNS = 3;
109
+ /** Holds the age in milliseconds past which a history key is pruned. */
110
+ export const HISTORY_AGE_MS = 7 * 24 * 60 * 60 * 1000;
111
+ /** Holds the count of history keys kept, the latest by their newest record. */
112
+ export const HISTORY_KEYS = 512;
113
+ /**
114
+ * Holds the longest wait in milliseconds for a sampler to ready before its holder starts the command
115
+ * unmeasured.
116
+ *
117
+ * @remarks
118
+ * The wait outlasts a sampler's start on a loaded host, and it bounds what a sampler that neither
119
+ * readies nor exits costs the lane.
120
+ */
121
+ export const READY_MS = 5000;
122
+ /**
123
+ * Holds the longest wait in milliseconds for a sampler's handover sample and for its exit after its
124
+ * stdin closes.
125
+ *
126
+ * @remarks
127
+ * A warm process query answered in about 140 ms on the Windows host measured 2026-11-12, so the wait
128
+ * outlasts a query on a loaded host, and it bounds what a sampler that hangs after it readied costs
129
+ * the lane at handover.
130
+ */
131
+ export const HANDOVER_MS = 5000;
109
132
  /** Holds the pause in milliseconds between two samples of a holder's tree. */
110
133
  export const SAMPLE_MS = 1000;
111
134
  /** Holds the exit code of a light run its holder ended at a threshold. */
@@ -158,6 +181,41 @@ export const BROWSER_PROJECT = /(?:^|:)(?:browser|vue)$/u;
158
181
  export const DOTTED_FLAG = /^--[^=.]+\.[^=]+$/u;
159
182
  /** Lists the package managers whose verbs and scripts a seed reads. */
160
183
  export const MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
184
+ /** Lists the package-manager verbs that run a tool, which a seed reads through to the tool. */
185
+ export const EXEC_VERBS = ['exec', 'x', 'dlx'];
186
+ /** Lists, by tool, the exec flags that take a separate value, so a seed reads no flag value as the tool. */
187
+ export const EXEC_VALUE_FLAGS = Object.freeze({
188
+ npm: Object.freeze(['--package', '-p', '--workspace', '-w']),
189
+ npx: Object.freeze(['--package', '-p', '--workspace', '-w']),
190
+ pnpm: Object.freeze(['--package']),
191
+ pnpx: Object.freeze(['--package']),
192
+ yarn: Object.freeze(['--package']),
193
+ bun: Object.freeze(['--package']),
194
+ bunx: Object.freeze(['--package']),
195
+ });
196
+ /**
197
+ * Lists, by package manager, the flags before the verb that take a separate value, so a seed reads no
198
+ * flag value as the verb.
199
+ *
200
+ * @remarks
201
+ * npm's `-w` names a workspace and takes a value; pnpm's `-w` is the boolean `--workspace-root`.
202
+ */
203
+ export const MANAGER_VALUE_FLAGS = Object.freeze({
204
+ npm: Object.freeze(['--prefix', '--workspace', '-w']),
205
+ pnpm: Object.freeze(['--dir', '-C', '--filter', '-F']),
206
+ yarn: Object.freeze(['--cwd']),
207
+ bun: Object.freeze(['--cwd']),
208
+ });
209
+ /** Lists the tools that run another tool the way `npx` does. */
210
+ export const NPX_TOOLS = ['npx', 'pnpx', 'bunx'];
211
+ /** Lists the `npm exec` and `npx` flags that run inline shell text, which names no tool a seed reads. */
212
+ export const EXEC_INLINE_FLAGS = ['-c', '--call'];
213
+ /** Holds the tool name of the falsify skill's `mutate` script, whose run a seed reads by its wrapped command. */
214
+ export const MUTATION_TOOL = 'mutate';
215
+ /** Holds the `mutate` flag that names the edits file, which a run's key leaves out. */
216
+ export const MUTATION_FLAG = '--edits';
217
+ /** Holds the `mutate` flag that writes saved originals back, which edits source and wraps no command. */
218
+ export const RESTORE_FLAG = '--restore';
161
219
  /** Lists the tools a seed reads heavy by name: the release chain's step runner. */
162
220
  export const HEAVY_TOOLS = ['steps'];
163
221
  /** Lists the Vitest flags that take a separate value, so a seed reads no flag value as a file. */
@@ -191,8 +249,21 @@ export const CHECK_SCRIPT = /^(?:check|typecheck|type-check)(?::|$)|:check$/u;
191
249
  export const SCOPED_SCRIPT = /^test:/u;
192
250
  /** Matches one sampler row: process id, parent id, creation time in milliseconds, CPU time in 100 ns units, and private bytes. */
193
251
  export const GAUGE_PATTERN = /^(\d+) (\d+) (\d+) (\d+) (\d+)$/u;
194
- /** Holds the PowerShell text that prints one line of rows per sample until its stdin closes. */
195
- 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)}}`;
252
+ /** Holds the line a sampler prints when its first process query has run, which readies it. */
253
+ export const READY_LINE = 'ready';
254
+ /** Holds the byte a holder writes to its sampler to ask for one sample at once. */
255
+ export const SAMPLE_BYTE = 's';
256
+ /**
257
+ * Holds the PowerShell text of a sampler.
258
+ *
259
+ * @remarks
260
+ * The child runs one process query, the one a sample runs, so its first sample answers warm, and
261
+ * prints {@link READY_LINE}. Until the first byte it waits on its
262
+ * stdin with no timer. Each byte on its stdin starts one sample at once, and after the first byte it
263
+ * also samples every {@link SAMPLE_MS}. A sample prints one line: `1` for a sample a byte asked for or `0`, a `|`,
264
+ * and the rows separated by semicolons. The child exits when its stdin closes.
265
+ */
266
+ export const SAMPLER_COMMAND = `$i=[Console]::OpenStandardInput();$b=New-Object byte[] 1;$t=$i.ReadAsync($b,0,1);$null=Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate,KernelModeTime,UserModeTime,PrivatePageCount;[Console]::Out.WriteLine('${READY_LINE}');[Console]::Out.Flush();$a=$false;$q=0;$d=-1;while($true){if($a){$r=Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate,KernelModeTime,UserModeTime,PrivatePageCount | Where-Object { $_.CreationDate } | ForEach-Object { '{0} {1} {2} {3} {4}' -f $_.ProcessId,$_.ParentProcessId,([DateTimeOffset]$_.CreationDate).ToUnixTimeMilliseconds(),($_.KernelModeTime+$_.UserModeTime),$_.PrivatePageCount };[Console]::Out.WriteLine([string]$q+'|'+($r -join ';'));[Console]::Out.Flush();$q=0};if($t.Wait($d)){if($t.Status -ne 'RanToCompletion' -or $t.Result -eq 0){break};$a=$true;$q=1;$d=${String(SAMPLE_MS)};$t=$i.ReadAsync($b,0,1)}}`;
196
267
  /**
197
268
  * Holds a process's endpoint, whose existence is the process's liveness.
198
269
  *
@@ -395,7 +466,8 @@ export function isTicket(value) {
395
466
  'arrived' in value &&
396
467
  typeof value.arrived === 'string' &&
397
468
  (!('light' in value) || isUsage(value.light)) &&
398
- (!('solo' in value) || typeof value.solo === 'boolean'));
469
+ (!('solo' in value) || typeof value.solo === 'boolean') &&
470
+ (!('edits' in value) || typeof value.edits === 'boolean'));
399
471
  }
400
472
  /**
401
473
  * Checks whether a value is a footprint.
@@ -577,9 +649,11 @@ export function removeFile(path) {
577
649
  * @param light - The footprint a light ticket counts, or undefined for a heavy ticket.
578
650
  * @param solo - If `true`, marks a ticket that waits out every earlier light ticket; if `false`, omits
579
651
  * the field.
580
- * @returns The complete ticket, carrying `light` and `solo` only when they are set.
652
+ * @param edits - If `true`, marks a `mutate` run that edits source in its working directory; if
653
+ * `false`, omits the field.
654
+ * @returns The complete ticket, carrying `light`, `solo`, and `edits` only when they are set.
581
655
  */
582
- export function buildTicket(token, label, light, solo = false) {
656
+ export function buildTicket(token, label, light, solo = false, edits = false) {
583
657
  return {
584
658
  protocol: PROTOCOL,
585
659
  token,
@@ -591,6 +665,7 @@ export function buildTicket(token, label, light, solo = false) {
591
665
  arrived: new Date().toISOString(),
592
666
  ...(light === undefined ? {} : { light }),
593
667
  ...(solo ? { solo } : {}),
668
+ ...(edits ? { edits } : {}),
594
669
  };
595
670
  }
596
671
  /**
@@ -671,14 +746,99 @@ export function readOutcomes(root, key) {
671
746
  * @param key - The command's key.
672
747
  * @param name - The record's name.
673
748
  * @param outcome - The record.
749
+ * @returns True when the write created the key's directory; false when the key existed.
674
750
  */
675
751
  export function writeOutcome(root, key, name, outcome) {
676
752
  const directory = join(root, HISTORY_DIRECTORY, key);
677
- mkdirSync(directory, { recursive: true });
753
+ const created = mkdirSync(directory, { recursive: true }) !== undefined;
678
754
  writeFileSync(join(directory, name), JSON.stringify(outcome), { flag: 'wx' });
679
755
  for (const stale of readOutcomeNames(root, key).slice(0, -RECENT_RUNS)) {
680
756
  removeFile(join(directory, stale));
681
757
  }
758
+ return created;
759
+ }
760
+ /**
761
+ * Reads when a history key was last written.
762
+ *
763
+ * @param root - The queue root.
764
+ * @param key - The key.
765
+ * @returns The end time its newest record's name opens with; the directory's modification time when
766
+ * it holds no record; `gone` when the entry no longer exists; `unread` when the host refuses to list
767
+ * it, as it does for a file that is no directory.
768
+ */
769
+ export function readKeyTime(root, key) {
770
+ try {
771
+ const newest = readOutcomeNames(root, key).at(-1);
772
+ if (newest !== undefined)
773
+ return Number(newest.slice(0, ENDED_WIDTH));
774
+ return statSync(join(root, HISTORY_DIRECTORY, key)).mtimeMs;
775
+ }
776
+ catch (error) {
777
+ return readCode(error) === 'ENOENT' ? 'gone' : 'unread';
778
+ }
779
+ }
780
+ /**
781
+ * Lists the names under the history directory.
782
+ *
783
+ * @param root - The queue root.
784
+ * @returns The names, empty when the directory is absent; undefined when the host refuses to list it.
785
+ */
786
+ export function readHistoryNames(root) {
787
+ try {
788
+ return readNames(join(root, HISTORY_DIRECTORY));
789
+ }
790
+ catch {
791
+ return undefined;
792
+ }
793
+ }
794
+ /**
795
+ * Removes one history key inside the removal budget.
796
+ *
797
+ * @param root - The queue root.
798
+ * @param key - The key.
799
+ * @returns True when the key is gone; false when the host refused the removal.
800
+ */
801
+ export function removeKey(root, key) {
802
+ try {
803
+ rmSync(join(root, HISTORY_DIRECTORY, key), {
804
+ recursive: true,
805
+ force: true,
806
+ maxRetries: REMOVAL_RETRIES,
807
+ retryDelay: REMOVAL_DELAY_MS,
808
+ });
809
+ return true;
810
+ }
811
+ catch {
812
+ return false;
813
+ }
814
+ }
815
+ /**
816
+ * Prunes the history to the keys written inside {@link HISTORY_AGE_MS}, at most the
817
+ * {@link HISTORY_KEYS} written last.
818
+ *
819
+ * @remarks
820
+ * The prune throws nothing, so it never changes the lane's exit: a name the host refuses to list or
821
+ * remove stays and is reported as skipped.
822
+ *
823
+ * @param root - The queue root.
824
+ * @param now - The current time in epoch milliseconds.
825
+ * @returns The keys removed, and the names skipped: `history` itself when it cannot be listed.
826
+ */
827
+ export function pruneHistory(root, now) {
828
+ const names = readHistoryNames(root);
829
+ if (names === undefined)
830
+ return { removed: [], skipped: [HISTORY_DIRECTORY] };
831
+ const times = names.map((key) => ({ key, time: readKeyTime(root, key) }));
832
+ const unread = times.flatMap((item) => (item.time === 'unread' ? [item.key] : []));
833
+ const results = times
834
+ .flatMap((item) => (typeof item.time === 'number' ? [{ key: item.key, time: item.time }] : []))
835
+ .toSorted((left, right) => right.time - left.time)
836
+ .filter((item, index) => index >= HISTORY_KEYS || item.time < now - HISTORY_AGE_MS)
837
+ .map((item) => ({ key: item.key, removed: removeKey(root, item.key) }));
838
+ return {
839
+ removed: results.flatMap((item) => (item.removed ? [item.key] : [])),
840
+ skipped: [...unread, ...results.flatMap((item) => (item.removed ? [] : [item.key]))],
841
+ };
682
842
  }
683
843
  /**
684
844
  * Reads the average cores a run used.
@@ -791,10 +951,12 @@ export function readToolName(path) {
791
951
  return name.replace(/-cli$/u, '');
792
952
  }
793
953
  /**
794
- * Reads the tool a command runs and the tool's arguments, past Node and `npx`.
954
+ * Reads the tool a command runs and the tool's arguments, past Node, `npx`, `pnpx`, `bunx`, and a
955
+ * package manager's `exec`, `x`, or `dlx` verb.
795
956
  *
796
957
  * @param command - The command and its arguments.
797
- * @returns The tool's name followed by its arguments; empty for inline Node code or no script.
958
+ * @returns The tool's name followed by its arguments; empty for inline Node code, inline exec text,
959
+ * or no script.
798
960
  */
799
961
  export function readTool(command) {
800
962
  const [executable, ...rest] = command;
@@ -809,12 +971,147 @@ export function readTool(command) {
809
971
  }
810
972
  return readTool(rest.slice(script));
811
973
  }
812
- if (name === 'npx') {
813
- const tool = rest.findIndex((argument) => !argument.startsWith('-'));
814
- return tool === -1 ? [] : readTool(rest.slice(tool));
974
+ if (NPX_TOOLS.includes(name))
975
+ return readExecTool(rest, EXEC_VALUE_FLAGS[name]);
976
+ if (MANAGERS.includes(name)) {
977
+ const flags = MANAGER_VALUE_FLAGS[name] ?? [];
978
+ const verb = rest.findIndex((argument, index) => !argument.startsWith('-') && !flags.includes(rest[index - 1] ?? ''));
979
+ if (EXEC_VERBS.includes(rest[verb] ?? '')) {
980
+ return readExecTool(rest.slice(verb + 1), EXEC_VALUE_FLAGS[name]);
981
+ }
815
982
  }
816
983
  return [name, ...rest];
817
984
  }
985
+ /**
986
+ * Reads the tool an `npx` or `npm exec` call runs, from the arguments after the verb.
987
+ *
988
+ * @remarks
989
+ * The tool is the first argument before a bare `--` that is neither a flag nor the value of a
990
+ * listed flag, else the first argument after the bare `--`. A flag {@link EXEC_INLINE_FLAGS} names
991
+ * before the tool runs shell text instead.
992
+ *
993
+ * @param args - The arguments after `npx` or after the exec verb.
994
+ * @param valueFlags - The flags that take a separate value, from {@link EXEC_VALUE_FLAGS}. Default:
995
+ * none.
996
+ * @returns The tool's name followed by its arguments; empty for inline text or no tool.
997
+ */
998
+ export function readExecTool(args, valueFlags = []) {
999
+ const end = args.indexOf('--');
1000
+ const named = args.findIndex((argument, index) => (end === -1 || index < end) &&
1001
+ !argument.startsWith('-') &&
1002
+ !valueFlags.includes(args[index - 1] ?? ''));
1003
+ const start = named !== -1 ? named : end === -1 ? -1 : end + 1;
1004
+ if (start === -1 || start >= args.length)
1005
+ return [];
1006
+ const inline = args
1007
+ .slice(0, start)
1008
+ .some((flag) => EXEC_INLINE_FLAGS.includes(flag) ||
1009
+ EXEC_INLINE_FLAGS.some((name) => flag.startsWith(`${name}=`)));
1010
+ return inline ? [] : readTool(args.slice(start));
1011
+ }
1012
+ /**
1013
+ * Checks whether a command is a `mutate --restore` run, which writes source files back.
1014
+ *
1015
+ * @param command - The command and its arguments.
1016
+ * @returns True for a `mutate` call with its restore flag before any bare `--`; false otherwise.
1017
+ */
1018
+ export function matchesRestore(command) {
1019
+ const [tool, ...args] = readTool(command);
1020
+ if (tool !== MUTATION_TOOL)
1021
+ return false;
1022
+ const end = args.indexOf('--');
1023
+ return (end === -1 ? args : args.slice(0, end)).some((flag) => flag === RESTORE_FLAG || flag.startsWith(`${RESTORE_FLAG}=`));
1024
+ }
1025
+ /**
1026
+ * Extracts the command a `mutate` run wraps.
1027
+ *
1028
+ * @param command - The command and its arguments.
1029
+ * @returns The arguments after the run's own bare `--`; undefined for any other command, or a
1030
+ * `mutate` call with no edits file or no wrapped command.
1031
+ */
1032
+ export function extractMutation(command) {
1033
+ const [tool, ...args] = readTool(command);
1034
+ if (tool !== MUTATION_TOOL)
1035
+ return undefined;
1036
+ const end = args.indexOf('--');
1037
+ if (end === -1)
1038
+ return undefined;
1039
+ const edits = args
1040
+ .slice(0, end)
1041
+ .some((flag) => flag === MUTATION_FLAG || flag.startsWith(`${MUTATION_FLAG}=`));
1042
+ const wrapped = args.slice(end + 1);
1043
+ return edits && wrapped.length > 0 ? wrapped : undefined;
1044
+ }
1045
+ /**
1046
+ * Normalizes a command to the arguments its key hashes.
1047
+ *
1048
+ * @remarks
1049
+ * A `mutate` run names a fresh edits file each time, so its key leaves the edits flag and its value
1050
+ * out, and every run of one wrapped command from one directory shares a key. The cut reads only the
1051
+ * script's own flags, between the script and its own bare `--`, so a launcher's `--` before the
1052
+ * script moves nothing.
1053
+ *
1054
+ * @param command - The command and its arguments.
1055
+ * @returns A `mutate` run without its edits flag and value; any other command unchanged.
1056
+ */
1057
+ export function normalizeCommand(command) {
1058
+ if (extractMutation(command) === undefined)
1059
+ return command;
1060
+ const start = command.length - readTool(command).length + 1;
1061
+ const end = command.indexOf('--', start);
1062
+ return command.filter((argument, index) => index < start ||
1063
+ index >= end ||
1064
+ !(argument === MUTATION_FLAG ||
1065
+ argument.startsWith(`${MUTATION_FLAG}=`) ||
1066
+ command[index - 1] === MUTATION_FLAG));
1067
+ }
1068
+ /**
1069
+ * Normalizes a working directory for the comparison that decides whether two tickets share it.
1070
+ *
1071
+ * @remarks
1072
+ * Every side of the comparison passes through this one function. It reads the real path through
1073
+ * `realpathSync.native`, which returns the name and the case the file system stores, so two
1074
+ * spellings of one directory compare equal without folding case.
1075
+ *
1076
+ * @param path - The directory.
1077
+ * @returns The real path; the resolved path when it cannot be read, as for a vanished directory.
1078
+ */
1079
+ export function normalizeDirectory(path) {
1080
+ try {
1081
+ return realpathSync.native(path);
1082
+ }
1083
+ catch {
1084
+ return resolvePath(path);
1085
+ }
1086
+ }
1087
+ /**
1088
+ * Checks whether two working directories share source.
1089
+ *
1090
+ * @remarks
1091
+ * Both sides pass through {@link normalizeDirectory}, so a child directory, such as a check run from
1092
+ * `packages/a`, shares source with a mutation at the checkout root, and the reverse.
1093
+ *
1094
+ * @param left - One directory.
1095
+ * @param right - The other directory.
1096
+ * @returns True when the two normalize to one directory or one sits inside the other at a separator
1097
+ * boundary; false otherwise.
1098
+ */
1099
+ export function sharesDirectory(left, right) {
1100
+ const one = normalizeDirectory(left);
1101
+ const other = normalizeDirectory(right);
1102
+ return one === other || matchesInside(one, other) || matchesInside(other, one);
1103
+ }
1104
+ /**
1105
+ * Checks whether a normalized path sits inside another at a separator boundary.
1106
+ *
1107
+ * @param inner - The path that might sit inside.
1108
+ * @param outer - The path that might contain it.
1109
+ * @returns True when `inner` opens with `outer` and a separator; false otherwise, the same path
1110
+ * included.
1111
+ */
1112
+ export function matchesInside(inner, outer) {
1113
+ return inner.startsWith(outer.endsWith(sep) ? outer : `${outer}${sep}`);
1114
+ }
818
1115
  /**
819
1116
  * Reads the positional arguments of a command, skipping each value of a value-taking flag.
820
1117
  *
@@ -872,7 +1169,8 @@ export function readVitestSeed(args) {
872
1169
  *
873
1170
  * @remarks
874
1171
  * Heavy wins: a word that names a journey, a study, a capture, a live-service run, or the release
875
- * chain seeds heavy wherever it appears, before any light kind is read.
1172
+ * chain seeds heavy wherever it appears, before any light kind is read. A `mutate --restore` run,
1173
+ * which writes source files back and wraps no command, seeds heavy.
876
1174
  *
877
1175
  * @param command - The command and its arguments.
878
1176
  * @returns The seeded lane, or undefined when no kind names the command.
@@ -883,10 +1181,10 @@ export function readSeed(command) {
883
1181
  const [tool, ...args] = readTool(command);
884
1182
  if (tool === undefined)
885
1183
  return undefined;
886
- if (HEAVY_TOOLS.includes(tool))
1184
+ if (HEAVY_TOOLS.includes(tool) || matchesRestore(command))
887
1185
  return 'heavy';
888
1186
  if (MANAGERS.includes(tool)) {
889
- const [verb, script] = readOperands(args, []);
1187
+ const [verb, script] = readOperands(args, MANAGER_VALUE_FLAGS[tool] ?? []);
890
1188
  if (verb === undefined)
891
1189
  return undefined;
892
1190
  if (HEAVY_VERBS.includes(verb))
@@ -957,7 +1255,10 @@ export function linkStage(root, token) {
957
1255
  * @remarks
958
1256
  * The two listings are separate, because one listing can miss both a ticket linked and a stage file
959
1257
  * removed while it runs. A stage file absent from the first listing belongs to a process whose own
960
- * listing sees this ticket, or to a ticket the second listing sees.
1258
+ * listing sees this ticket, or to a ticket the second listing sees. A ticket holds only when the
1259
+ * directory rule of {@link decideDirectory} names no ticket to wait on and its own lane's rule admits
1260
+ * it. Every rule names only an earlier ticket, and an earlier ticket can only leave, so no two tickets
1261
+ * wait on each other and no cycle of waits can form.
961
1262
  *
962
1263
  * @param root - The queue root.
963
1264
  * @param sequence - This process's sequence.
@@ -977,17 +1278,44 @@ export function decideTurn(root, sequence, token, limits) {
977
1278
  }
978
1279
  const own = entries[position]?.ticket;
979
1280
  const earlier = entries.slice(0, position);
1281
+ const shared = own === undefined ? undefined : decideDirectory(earlier, own);
1282
+ if (shared !== undefined)
1283
+ return shared;
980
1284
  return own?.light === undefined || limits === undefined
981
1285
  ? decideHeavy(earlier, own?.solo === true)
982
1286
  : decideLight(root, earlier, own.light, limits);
983
1287
  }
1288
+ /**
1289
+ * Decides which earlier ticket the directory rule makes a ticket wait on, whatever its lane.
1290
+ *
1291
+ * @remarks
1292
+ * Every ticket waits on the nearest earlier ticket that carries `edits` and shares its working
1293
+ * directory, because a `mutate` run edits source that ticket reads. A ticket that carries `edits`
1294
+ * also waits on the nearest earlier ticket of its working directory in either lane, and on an
1295
+ * earlier ticket it cannot read, which might share the directory; that wait refuses. The rule names
1296
+ * only earlier tickets, which can only leave, so it adds no cycle of waits. {@link normalizeDirectory}
1297
+ * reads both sides of every comparison.
1298
+ *
1299
+ * @param earlier - The tickets before this one, in arrival order.
1300
+ * @param own - This process's ticket.
1301
+ * @returns The ticket to wait on; undefined when the rule names none.
1302
+ */
1303
+ export function decideDirectory(earlier, own) {
1304
+ const entry = earlier.findLast((item) => {
1305
+ if (item.ticket === undefined)
1306
+ return own.edits === true;
1307
+ return ((own.edits === true || item.ticket.edits === true) &&
1308
+ sharesDirectory(own.cwd, item.ticket.cwd));
1309
+ });
1310
+ return entry === undefined ? undefined : { state: 'behind', entry };
1311
+ }
984
1312
  /**
985
1313
  * Decides what a heavy ticket does next.
986
1314
  *
987
1315
  * @remarks
988
1316
  * A heavy ticket waits on the nearest earlier ticket that is not light, an unreadable one included. A
989
1317
  * `--solo` ticket waits on the nearest earlier ticket of either lane, so it holds with no light
990
- * holder beside it.
1318
+ * holder beside it. The rule names only an earlier ticket, so it adds no cycle of waits.
991
1319
  *
992
1320
  * @param earlier - The tickets before this one, in arrival order.
993
1321
  * @param solo - If `true`, waits on light tickets too; if `false`, passes them.
@@ -1019,7 +1347,11 @@ export function decideLight(root, earlier, light, limits) {
1019
1347
  return { state: 'behind', entry: unread };
1020
1348
  const lights = earlier.filter((entry) => entry.ticket?.light !== undefined);
1021
1349
  const solos = earlier.filter((entry) => entry.ticket?.solo === true);
1022
- const pending = lights.flatMap((entry) => readRun(root, entry.sequence) === 'absent' ? [entry.sequence] : []);
1350
+ const pending = lights.flatMap((entry) => {
1351
+ const blocked = entry.ticket !== undefined &&
1352
+ decideDirectory(earlier.slice(0, earlier.indexOf(entry)), entry.ticket) !== undefined;
1353
+ return !blocked && readRun(root, entry.sequence) === 'absent' ? [entry.sequence] : [];
1354
+ });
1023
1355
  const usages = lights.flatMap((entry) => entry.ticket?.light === undefined ? [] : [entry.ticket.light]);
1024
1356
  const fits = usages.length === 0 || fitsBudget([...usages, light], limits);
1025
1357
  return solos.length === 0 && pending.length === 0 && fits
@@ -1178,9 +1510,20 @@ export function readTree(run, ceiling) {
1178
1510
  if (process.platform !== 'win32')
1179
1511
  return readGroup(run.launcher);
1180
1512
  const rows = readSnapshot();
1181
- return rows === undefined
1182
- ? undefined
1183
- : selectMembers(rows, run.command === undefined ? [run.launcher] : [run.launcher, run.command], run.started - CLOCK_ALLOWANCE_MS, ceiling).map((row) => row.pid);
1513
+ return rows === undefined ? undefined : selectTree(rows, run, ceiling);
1514
+ }
1515
+ /**
1516
+ * Selects the members of one run's process tree from a Windows snapshot.
1517
+ *
1518
+ * @param rows - The snapshot.
1519
+ * @param run - The run record.
1520
+ * @param ceiling - The latest creation date a row of an exited seed can carry.
1521
+ * @returns The members' ids, or undefined when the record names no launcher.
1522
+ */
1523
+ export function selectTree(rows, run, ceiling) {
1524
+ if (run.launcher === undefined)
1525
+ return undefined;
1526
+ return selectMembers(rows, run.command === undefined ? [run.launcher] : [run.launcher, run.command], run.started - CLOCK_ALLOWANCE_MS, ceiling).map((row) => row.pid);
1184
1527
  }
1185
1528
  /**
1186
1529
  * Kills each listed member.
@@ -1439,6 +1782,18 @@ export function waitForClose(child) {
1439
1782
  child.once('close', (code) => resolve(code ?? undefined));
1440
1783
  });
1441
1784
  }
1785
+ /**
1786
+ * Waits for a started launcher to exit, which precedes the close of its streams.
1787
+ *
1788
+ * @param child - The started launcher.
1789
+ * @returns When it exited or failed, in epoch milliseconds.
1790
+ */
1791
+ export function waitForExit(child) {
1792
+ return new Promise((resolve) => {
1793
+ child.once('error', () => resolve(Date.now()));
1794
+ child.once('exit', () => resolve(Date.now()));
1795
+ });
1796
+ }
1442
1797
  /**
1443
1798
  * Writes a run record, leaving an unwritten id to the handover reading.
1444
1799
  *
@@ -1495,6 +1850,36 @@ export function parseGauges(line) {
1495
1850
  ];
1496
1851
  });
1497
1852
  }
1853
+ /**
1854
+ * Waits for a promise within a bound.
1855
+ *
1856
+ * @param promise - The promise.
1857
+ * @param budget - The longest wait in milliseconds.
1858
+ * @returns The promise's value; undefined when the budget runs out first.
1859
+ */
1860
+ export async function waitForBound(promise, budget) {
1861
+ const timer = Promise.withResolvers();
1862
+ const handle = setTimeout(() => timer.resolve(undefined), budget);
1863
+ try {
1864
+ return await Promise.race([promise, timer.promise]);
1865
+ }
1866
+ finally {
1867
+ clearTimeout(handle);
1868
+ }
1869
+ }
1870
+ /**
1871
+ * Parses one sample line of a sampler.
1872
+ *
1873
+ * @param line - One line of the sampler's stdout: `1` or `0`, a `|`, and the rows.
1874
+ * @returns Whether a byte asked for the sample, with its gauges; undefined for a line without the
1875
+ * marker, such as {@link READY_LINE}.
1876
+ */
1877
+ export function parseSample(line) {
1878
+ const split = line.indexOf('|');
1879
+ if (split === -1)
1880
+ return undefined;
1881
+ return { requested: line.slice(0, split) === '1', gauges: parseGauges(line.slice(split + 1)) };
1882
+ }
1498
1883
  /**
1499
1884
  * Folds one sample's members into a tally.
1500
1885
  *
@@ -1555,12 +1940,12 @@ export function lowerPriority(pid) {
1555
1940
  * @param key - The command's key.
1556
1941
  * @param name - The record's name.
1557
1942
  * @param outcome - The record.
1558
- * @returns True when the record was written; false otherwise.
1943
+ * @returns True when the write created the key's directory; false when the key existed or the host
1944
+ * refused the write.
1559
1945
  */
1560
1946
  export function tryWriteOutcome(root, key, name, outcome) {
1561
1947
  try {
1562
- writeOutcome(root, key, name, outcome);
1563
- return true;
1948
+ return writeOutcome(root, key, name, outcome);
1564
1949
  }
1565
1950
  catch {
1566
1951
  return false;
@@ -1570,32 +1955,46 @@ export function tryWriteOutcome(root, key, name, outcome) {
1570
1955
  * Samples one holder's process tree through one PowerShell child at below-normal priority.
1571
1956
  *
1572
1957
  * @remarks
1573
- * The child exits when its stdin closes, which {@link Sampler.stop} and the end of this process both
1574
- * do. A threshold, given for a light run, calls the breach handler once, on the first sample whose
1575
- * memory or process count passes it.
1958
+ * The child starts at arrival and readies while the ticket waits, so a holder starts its command
1959
+ * only after the child can answer at once. A {@link Sampler.sample} call starts one sample at once;
1960
+ * after the first, the child also samples every {@link SAMPLE_MS}. The child exits when its stdin
1961
+ * closes, which {@link Sampler.stop} and the end of this process both do. A threshold, given for a
1962
+ * light run, calls the breach handler once with the launcher's id, on the first sample before
1963
+ * {@link Sampler.seal} whose memory or process count passes it.
1576
1964
  */
1577
1965
  export class Sampler {
1578
1966
  #child;
1579
1967
  #closed;
1580
- #floor;
1968
+ #ready = Promise.withResolvers();
1969
+ #waiters = new Map();
1581
1970
  #threshold;
1582
1971
  #breach;
1583
1972
  #seeds = [];
1973
+ #floor;
1974
+ #ceiling;
1584
1975
  #tally = { cpu: new Map(), memory: 0, processes: 0 };
1585
1976
  #breached = false;
1977
+ #asked = 0;
1978
+ #answered = 0;
1586
1979
  /**
1587
1980
  * Starts the sampler.
1588
1981
  *
1589
- * @param floor - The earliest creation date the tree can carry.
1590
1982
  * @param threshold - The light run's threshold, or undefined for a heavy run.
1591
- * @param breach - Called once when a sample passes the threshold.
1983
+ * @param breach - Called once with the launcher's id when a sample passes the threshold. The
1984
+ * launcher is the one seed the lane holds a live handle on until it exits, so ending its tree
1985
+ * reaches the command and never a reused id.
1986
+ * @param command - The PowerShell text the child runs, for a proof. Default: {@link SAMPLER_COMMAND}.
1592
1987
  */
1593
- constructor(floor, threshold, breach) {
1594
- this.#floor = floor;
1988
+ constructor(threshold, breach, command = SAMPLER_COMMAND) {
1595
1989
  this.#threshold = threshold;
1596
1990
  this.#breach = breach;
1597
- this.#child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', SAMPLER_COMMAND], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });
1598
- this.#closed = waitForClose(this.#child).then(() => undefined);
1991
+ this.#child = spawn('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });
1992
+ this.#closed = waitForClose(this.#child).then(() => {
1993
+ this.#ready.resolve(false);
1994
+ for (const resolve of this.#waiters.values())
1995
+ resolve(undefined);
1996
+ this.#waiters.clear();
1997
+ });
1599
1998
  this.#child.stdin?.on('error', () => undefined);
1600
1999
  if (this.#child.pid !== undefined)
1601
2000
  lowerPriority(this.#child.pid);
@@ -1617,43 +2016,135 @@ export class Sampler {
1617
2016
  get breached() {
1618
2017
  return this.#breached;
1619
2018
  }
2019
+ /**
2020
+ * Waits until the child can sample at once, within a budget.
2021
+ *
2022
+ * @param budget - The longest wait in milliseconds.
2023
+ * @returns A promise of true when the child readied; false when it ended first or the budget ran out.
2024
+ */
2025
+ async ready(budget) {
2026
+ return (await waitForBound(this.#ready.promise, budget)) ?? false;
2027
+ }
1620
2028
  /**
1621
2029
  * Names the ids whose trees later samples read.
1622
2030
  *
1623
2031
  * @param seeds - The launcher id and, once known, the command id.
2032
+ * @param floor - The earliest creation date the tree can carry.
1624
2033
  */
1625
- seed(seeds) {
2034
+ seed(seeds, floor) {
1626
2035
  this.#seeds = seeds;
2036
+ this.#floor = floor;
2037
+ }
2038
+ /**
2039
+ * Marks the launcher's exit: a later sample reads no member created after it and triggers no
2040
+ * breach, so a reused id after the exit is never ended.
2041
+ *
2042
+ * @param ceiling - When the launcher exited, in epoch milliseconds.
2043
+ */
2044
+ seal(ceiling) {
2045
+ this.#ceiling = ceiling;
2046
+ }
2047
+ /**
2048
+ * Starts one sample at once.
2049
+ *
2050
+ * @param budget - The longest wait in milliseconds for the answer. Default: no bound.
2051
+ * @returns A promise of every row the sample read, taken after this call; undefined when the
2052
+ * child ends first, cannot take the request, or does not answer within the budget.
2053
+ */
2054
+ sample(budget) {
2055
+ const stdin = this.#child.stdin;
2056
+ if (stdin === null ||
2057
+ stdin.writableEnded ||
2058
+ this.#child.pid === undefined ||
2059
+ this.#child.exitCode !== null ||
2060
+ this.#child.signalCode !== null) {
2061
+ return Promise.resolve(undefined);
2062
+ }
2063
+ this.#asked += 1;
2064
+ const answer = Promise.withResolvers();
2065
+ this.#waiters.set(this.#asked, answer.resolve);
2066
+ stdin.write(SAMPLE_BYTE);
2067
+ return budget === undefined ? answer.promise : waitForBound(answer.promise, budget);
1627
2068
  }
1628
2069
  /**
1629
- * Closes the sampler's stdin, which ends it.
2070
+ * Samples back to back until a time or an abort, one sample after the previous one answers.
2071
+ *
2072
+ * @param until - The epoch millisecond after which no further sample starts.
2073
+ * @param signal - Ends the burst after the sample in flight.
2074
+ * @returns A promise that resolves when the burst ends.
2075
+ */
2076
+ async burst(until, signal) {
2077
+ const rows = await this.sample();
2078
+ if (rows === undefined || signal.aborted || Date.now() >= until)
2079
+ return;
2080
+ await this.burst(until, signal);
2081
+ }
2082
+ /**
2083
+ * Closes the sampler's stdin, which ends it, and ends the child at once when it has not exited
2084
+ * within {@link HANDOVER_MS}.
1630
2085
  *
1631
2086
  * @returns A promise that resolves when the sampler has exited.
1632
2087
  */
1633
- stop() {
2088
+ async stop() {
2089
+ this.#child.stdin?.end();
2090
+ const exited = await waitForBound(this.#closed.then(() => true), HANDOVER_MS);
2091
+ if (exited === undefined)
2092
+ await this.destroy();
2093
+ }
2094
+ /**
2095
+ * Ends the child at once, for a sampler that did not ready and might not read its stdin.
2096
+ *
2097
+ * @returns A promise that resolves when the child has exited.
2098
+ */
2099
+ destroy() {
1634
2100
  this.#child.stdin?.end();
2101
+ this.#child.kill();
1635
2102
  return this.#closed;
1636
2103
  }
2104
+ // A sample a byte asked for answers the oldest open request, because the child answers bytes in order.
1637
2105
  #read(line) {
1638
- const members = selectMembers(parseGauges(line), this.#seeds, this.#floor, Date.now());
2106
+ if (line === READY_LINE) {
2107
+ this.#ready.resolve(true);
2108
+ return;
2109
+ }
2110
+ const sample = parseSample(line);
2111
+ if (sample === undefined)
2112
+ return;
2113
+ if (sample.requested) {
2114
+ this.#answered += 1;
2115
+ this.#waiters.get(this.#answered)?.(sample.gauges);
2116
+ this.#waiters.delete(this.#answered);
2117
+ }
2118
+ if (this.#floor === undefined)
2119
+ return;
2120
+ const members = selectMembers(sample.gauges, this.#seeds, this.#floor, this.#ceiling ?? Date.now());
1639
2121
  this.#tally = tallySample(this.#tally, members);
1640
2122
  const threshold = this.#threshold;
1641
2123
  if (threshold === undefined ||
2124
+ this.#ceiling !== undefined ||
1642
2125
  this.#breached ||
1643
2126
  (this.#tally.memory <= threshold.memory && this.#tally.processes <= threshold.processes)) {
1644
2127
  return;
1645
2128
  }
2129
+ const [launcher] = this.#seeds;
2130
+ if (launcher === undefined)
2131
+ return;
1646
2132
  this.#breached = true;
1647
- this.#breach();
2133
+ this.#breach(launcher);
1648
2134
  }
1649
2135
  }
1650
2136
  /**
1651
2137
  * Runs the command as the holder, reads the tree at handover, and releases.
1652
2138
  *
1653
2139
  * @remarks
1654
- * A measured holder samples its tree and writes the run's record before it releases, so the
1655
- * command's next arrival reads it. A light holder lowers its own priority before the spawn, and ends
1656
- * its tree when a sample passes the threshold.
2140
+ * A measured holder starts its command after its sampler readies, samples the tree back to back
2141
+ * through the command's first {@link SAMPLE_MS} and once every {@link SAMPLE_MS} after, reads the
2142
+ * handover through one more sample, and writes the run's record before it releases, so the command's
2143
+ * next arrival reads it. When that sample lists a member, the handover reads, kills, and reads again
2144
+ * through fresh snapshots, each a second PowerShell. A sampler that does not ready within
2145
+ * {@link READY_MS} is destroyed, and the command runs unmeasured and records nothing. A record that
2146
+ * opened a key prunes the history after the release. A light holder lowers its own priority before
2147
+ * the spawn, and ends its tree when a sample passes the threshold.
1657
2148
  *
1658
2149
  * @param options - The run.
1659
2150
  * @param launcher - The launcher's path.
@@ -1661,17 +2152,24 @@ export class Sampler {
1661
2152
  * @param measure - What a measured holder needs, or undefined when no limits apply.
1662
2153
  * @param token - This process's endpoint, which holds after the run record exists and leaves before
1663
2154
  * the run record is removed.
2155
+ * @param sampler - The measured holder's sampler, started at arrival; the caller stops it.
1664
2156
  * @returns The launcher's code; 1 when a signal ended it; 69 when a light run passed its threshold;
1665
2157
  * 70 when the tree still reads as present or the ticket could not be removed; 75 when the launcher
1666
2158
  * could not start, the priority could not be lowered, or the run record could not be written.
1667
2159
  */
1668
- export async function runHolder(options, launcher, sequence, measure, token) {
2160
+ export async function runHolder(options, launcher, sequence, measure, token, sampler) {
1669
2161
  const { root } = options;
1670
2162
  if (measure?.light !== undefined && !lowerPriority(process.pid)) {
1671
2163
  releaseTicket(root, sequence);
1672
2164
  console.error('lane: the host refused the light run its below-normal priority');
1673
2165
  return 75;
1674
2166
  }
2167
+ const measured = sampler !== undefined && (await sampler.ready(READY_MS));
2168
+ if (sampler !== undefined && !measured) {
2169
+ await sampler.destroy();
2170
+ console.error(`lane: the sampler did not ready within ${String(READY_MS)} ms; ${quote(options.label)} runs unmeasured`);
2171
+ }
2172
+ const active = measured ? sampler : undefined;
1675
2173
  const started = Date.now();
1676
2174
  if (!tryWriteRun(root, sequence, { started, launcher: undefined, command: undefined })) {
1677
2175
  const refusal = releaseTicket(root, sequence);
@@ -1688,12 +2186,15 @@ export async function runHolder(options, launcher, sequence, measure, token) {
1688
2186
  return 75;
1689
2187
  }
1690
2188
  tryWriteRun(root, sequence, { started, launcher: id, command: undefined });
1691
- const sampler = measure === undefined
1692
- ? undefined
1693
- : new Sampler(started - CLOCK_ALLOWANCE_MS, measure.light === undefined ? undefined : measure.limits.threshold, () => killMembers([id]));
1694
- sampler?.seed([id]);
2189
+ const floor = started - CLOCK_ALLOWANCE_MS;
2190
+ const early = new AbortController();
2191
+ active?.seed([id], floor);
1695
2192
  const unwatch = watchSignals(() => killMembers([id]));
1696
2193
  const closed = waitForClose(child);
2194
+ const exited = waitForExit(child).then((at) => {
2195
+ active?.seal(at);
2196
+ return at;
2197
+ });
1697
2198
  if (child.stdout !== null) {
1698
2199
  const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
1699
2200
  lines.on('error', () => undefined);
@@ -1703,22 +2204,34 @@ export async function runHolder(options, launcher, sequence, measure, token) {
1703
2204
  if (command === undefined)
1704
2205
  return;
1705
2206
  tryWriteRun(root, sequence, { started, launcher: id, command });
1706
- sampler?.seed([id, command]);
2207
+ active?.seed([id, command], floor);
2208
+ void active?.burst(Date.now() + SAMPLE_MS, early.signal);
1707
2209
  });
1708
2210
  }
1709
2211
  const code = await closed;
2212
+ const ended = await exited;
2213
+ early.abort();
1710
2214
  unwatch();
1711
- const ended = Date.now();
1712
- const stopped = sampler?.stop();
1713
2215
  const run = readRun(root, sequence);
1714
- const sweep = run === 'absent' || run === 'unread'
2216
+ const rows = typeof run === 'object' ? await active?.sample(HANDOVER_MS) : undefined;
2217
+ const hung = active !== undefined && typeof run === 'object' && rows === undefined;
2218
+ if (hung) {
2219
+ await active.destroy();
2220
+ console.error(`lane: the sampler did not answer the handover within ${String(HANDOVER_MS)} ms; ${quote(options.label)} records nothing`);
2221
+ }
2222
+ const quick = rows !== undefined && typeof run === 'object' ? selectTree(rows, run, ended) : undefined;
2223
+ const sweep = typeof run !== 'object'
1715
2224
  ? { gone: false, members: [] }
1716
- : sweepTree(() => readTree(run, ended), killMembers, KILL_BUDGET);
1717
- const breached = sampler?.breached === true;
2225
+ : quick?.length === 0
2226
+ ? { gone: true, members: [] }
2227
+ : sweepTree(() => readTree(run, ended), killMembers, KILL_BUDGET);
2228
+ const stopped = active?.stop();
2229
+ const breached = active?.breached === true;
1718
2230
  const result = !sweep.gone ? HELD_CODE : breached ? BREACH_CODE : (code ?? 1);
1719
- if (measure !== undefined && sampler !== undefined) {
1720
- tryWriteOutcome(root, measure.key, renderOutcomeName(ended, measure.token), buildOutcome(sampler.tally, ended - started, result));
1721
- }
2231
+ const opened = measure !== undefined &&
2232
+ active !== undefined &&
2233
+ !hung &&
2234
+ tryWriteOutcome(root, measure.key, renderOutcomeName(ended, measure.token), buildOutcome(active.tally, ended - started, result));
1722
2235
  if (!sweep.gone) {
1723
2236
  console.error(`lane: the tree of ${quote(options.label)} still reads as ${sweep.members.length === 0 ? 'unread' : `present: ${sweep.members.join(', ')}`}; the lane stays held by ${renderName(sequence, TICKET_SUFFIX)} and ${renderName(sequence, RUN_SUFFIX)} under ${root}`);
1724
2237
  await stopped;
@@ -1726,6 +2239,10 @@ export async function runHolder(options, launcher, sequence, measure, token) {
1726
2239
  }
1727
2240
  token?.leave();
1728
2241
  const refusal = releaseTicket(root, sequence);
2242
+ const prune = opened ? pruneHistory(root, Date.now()) : undefined;
2243
+ if (prune !== undefined && prune.skipped.length > 0) {
2244
+ console.error(`lane: the history prune under ${root} skipped ${String(prune.skipped.length)} entries it could not list or remove, such as ${quote(prune.skipped.join(', '))}`);
2245
+ }
1729
2246
  await stopped;
1730
2247
  if (refusal !== undefined) {
1731
2248
  console.error(`lane: removing ${renderName(sequence, TICKET_SUFFIX)} reported ${refusal}`);
@@ -1741,7 +2258,9 @@ export async function runHolder(options, launcher, sequence, measure, token) {
1741
2258
  *
1742
2259
  * @remarks
1743
2260
  * A host other than Windows has no sampler, so it measures nothing and every ticket there is heavy.
1744
- * A `--solo` run is heavy whatever its command reads.
2261
+ * A `--solo` run is heavy whatever its command reads. A `mutate` run is keyed without its edits
2262
+ * file and seeded by its wrapped command; {@link decideDirectory} keeps it apart from the tickets of
2263
+ * its working directory.
1745
2264
  *
1746
2265
  * @param options - The run.
1747
2266
  * @param token - This process's token.
@@ -1757,10 +2276,12 @@ export function readMeasure(options, token) {
1757
2276
  }
1758
2277
  if (limits === 'absent' || limits === 'unread')
1759
2278
  return undefined;
1760
- const key = renderKey(realpathSync(process.cwd()), options.command);
1761
- const light = options.solo
1762
- ? undefined
1763
- : classifyLight(readSeed(options.command), readOutcomes(options.root, key), limits);
2279
+ const key = renderKey(normalizeDirectory(process.cwd()), normalizeCommand(options.command));
2280
+ if (options.solo)
2281
+ return { limits, key, token, light: undefined };
2282
+ const mutation = extractMutation(options.command);
2283
+ const seed = readSeed(mutation ?? options.command);
2284
+ const light = classifyLight(seed, readOutcomes(options.root, key), limits);
1764
2285
  return { limits, key, token, light };
1765
2286
  }
1766
2287
  /**
@@ -1777,24 +2298,33 @@ export async function enterLane(options, launcher, tokenId, token) {
1777
2298
  try {
1778
2299
  mkdirSync(root, { recursive: true });
1779
2300
  const measure = readMeasure(options, tokenId);
1780
- await token.listen(renderEndpoint(root, tokenId));
1781
- writeStage(root, buildTicket(tokenId, options.label, measure?.light, options.solo));
1782
- const sequence = linkStage(root, tokenId);
1783
- removeFile(join(root, `${tokenId}${STAGE_SUFFIX}`));
1784
- token.publish();
1785
- const unwatch = watchSignals(() => {
2301
+ const sampler = measure === undefined
2302
+ ? undefined
2303
+ : new Sampler(measure.light === undefined ? undefined : measure.limits.threshold, (pid) => killMembers([pid]));
2304
+ try {
2305
+ await token.listen(renderEndpoint(root, tokenId));
2306
+ const edits = extractMutation(options.command) !== undefined || matchesRestore(options.command);
2307
+ writeStage(root, buildTicket(tokenId, options.label, measure?.light, options.solo, edits));
2308
+ const sequence = linkStage(root, tokenId);
2309
+ removeFile(join(root, `${tokenId}${STAGE_SUFFIX}`));
2310
+ token.publish();
2311
+ const unwatch = watchSignals(() => {
2312
+ removeFile(join(root, renderName(sequence, TICKET_SUFFIX)));
2313
+ removeFile(renderEndpoint(root, tokenId));
2314
+ process.exit(75);
2315
+ });
2316
+ const refusal = await waitForTurn(root, sequence, tokenId, measure?.limits);
2317
+ unwatch();
2318
+ if (refusal === undefined) {
2319
+ return await runHolder(options, launcher, sequence, measure, token, sampler);
2320
+ }
1786
2321
  removeFile(join(root, renderName(sequence, TICKET_SUFFIX)));
1787
- removeFile(renderEndpoint(root, tokenId));
1788
- process.exit(75);
1789
- });
1790
- const refusal = await waitForTurn(root, sequence, tokenId, measure?.limits);
1791
- unwatch();
1792
- if (refusal === undefined) {
1793
- return await runHolder(options, launcher, sequence, measure, token);
2322
+ console.error(`lane: ${refusal}`);
2323
+ return 75;
2324
+ }
2325
+ finally {
2326
+ await sampler?.stop();
1794
2327
  }
1795
- removeFile(join(root, renderName(sequence, TICKET_SUFFIX)));
1796
- console.error(`lane: ${refusal}`);
1797
- return 75;
1798
2328
  }
1799
2329
  catch (error) {
1800
2330
  console.error(`lane: the queue under ${root} refused the run: ${String(error)}`);
@@ -1833,6 +2363,7 @@ export async function readStatusRow(root, entry) {
1833
2363
  pid: ticket?.pid,
1834
2364
  light: ticket?.light !== undefined,
1835
2365
  solo: ticket?.solo === true,
2366
+ edits: ticket?.edits === true,
1836
2367
  };
1837
2368
  if (ticket === undefined || describeForeign(ticket) !== undefined) {
1838
2369
  return { ...fields, state: 'unread', holding: false };
@@ -1867,7 +2398,7 @@ export function renderStatus(status) {
1867
2398
  return [
1868
2399
  `holder: ${status.holder === undefined ? 'none' : quote(status.holder.label ?? 'unread')}`,
1869
2400
  `light: ${lights.length === 0 ? 'none' : lights.map((row) => quote(row.label ?? 'unread')).join(', ')}`,
1870
- ...status.tickets.map((row) => `${renderName(row.sequence, TICKET_SUFFIX)} ${row.state} ${renderLane(row)}${row.holding ? ' holding' : ''} ${quote(row.label ?? 'unread')} pid ${String(row.pid)}`),
2401
+ ...status.tickets.map((row) => `${renderName(row.sequence, TICKET_SUFFIX)} ${row.state} ${renderLane(row)}${row.edits ? ' edits' : ''}${row.holding ? ' holding' : ''} ${quote(row.label ?? 'unread')} pid ${String(row.pid)}`),
1871
2402
  ].join('\n');
1872
2403
  }
1873
2404
  /**