@orkestrel/scaffold 0.0.138 → 0.0.139

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.
@@ -6,6 +6,7 @@ import { connect, createServer } from 'node:net';
6
6
  import { constants, hostname, setPriority, userInfo } from 'node:os';
7
7
  import { basename, dirname, extname, isAbsolute, join, resolve as resolvePath, sep, } from 'node:path';
8
8
  import { createInterface } from 'node:readline';
9
+ import { setImmediate as yieldTurn, setTimeout as wait } from 'node:timers/promises';
9
10
  import { fileURLToPath } from 'node:url';
10
11
  import { parseArgs } from 'node:util';
11
12
  /** Holds the protocol version a ticket carries, so a process refuses a ticket it cannot read. */
@@ -83,11 +84,14 @@ export const STOP_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
83
84
  */
84
85
  export const CLOCK_ALLOWANCE_MS = 16;
85
86
  /**
86
- * Holds the kill attempts the handover reading makes before it stays held.
87
+ * Holds the kill attempts the handover reading makes before it stays held, and the readings a Linux
88
+ * breach kill takes toward a fixpoint.
87
89
  *
88
90
  * @remarks
89
91
  * Each attempt on Windows is a synchronous `taskkill` per member and a process snapshot. A member
90
92
  * that outlives this many forced kills is a defect a person reads rather than a wait the queue absorbs.
93
+ * A breach kill of a Chromium launch and of a tree of 41 to 46 processes settled in 1 or 2 readings
94
+ * of 1 to 4 ms each on the Linux container measured 2026-11-16.
91
95
  */
92
96
  export const KILL_BUDGET = 5;
93
97
  /** Holds the pause in milliseconds after a group signal, because no event reports a group's end. */
@@ -138,6 +142,26 @@ export const READY_MS = 5000;
138
142
  export const HANDOVER_MS = 5000;
139
143
  /** Holds the pause in milliseconds between two samples of a holder's tree. */
140
144
  export const SAMPLE_MS = 1000;
145
+ /**
146
+ * Holds the pause in milliseconds between two samples of a Linux holder's first second.
147
+ *
148
+ * @remarks
149
+ * A Linux sample reads the process table inside the lane process in a few milliseconds, so a burst
150
+ * paced back to back, as the Windows sampler's is, would hold a core for that second.
151
+ */
152
+ export const BURST_MS = 50;
153
+ /**
154
+ * Holds the milliseconds of one clock tick in the Linux process table.
155
+ *
156
+ * @remarks
157
+ * The table counts CPU time and a start time in `USER_HZ` ticks, which the kernel fixes at 100 per
158
+ * second on x86 and arm64; Node exposes no `sysconf` to read it.
159
+ */
160
+ export const CLOCK_TICK_MS = 10;
161
+ /** Matches the boot-time line of the Linux `/proc/stat`, in whole seconds since the epoch. */
162
+ export const BOOT_PATTERN = /^btime (\d+)$/u;
163
+ /** Matches the resident-memory line of a Linux `/proc/<pid>/status`, in kibibytes. */
164
+ export const RESIDENT_PATTERN = /^VmRSS:\s+(\d+) kB$/u;
141
165
  /** Holds the exit code of a light run its holder ended at a threshold. */
142
166
  export const BREACH_CODE = 69;
143
167
  /** Holds the exit code of a run whose tree still reads as present at handover. */
@@ -1656,6 +1680,292 @@ export function readGroup(group, read = readTasks) {
1656
1680
  const second = read(group);
1657
1681
  return second !== undefined && matchesEnded(first, second) ? [] : [group];
1658
1682
  }
1683
+ /**
1684
+ * Parses one Linux process-table `stat` line into a census member with no memory read yet.
1685
+ *
1686
+ * @remarks
1687
+ * The fields are read after the last `)`, as {@link parseStat} reads them: the state, the parent,
1688
+ * and the group open them, `utime` and `stime` are the twelfth and thirteenth, and the start time is
1689
+ * the twentieth.
1690
+ *
1691
+ * @param text - The content of `/proc/<pid>/stat`.
1692
+ * @param boot - The boot time in epoch milliseconds, which the start ticks count from.
1693
+ * @returns The member with its memory at 0, or undefined when the text does not have that form.
1694
+ */
1695
+ export function parseMember(text, boot) {
1696
+ const open = text.indexOf(' (');
1697
+ const close = text.lastIndexOf(')');
1698
+ if (open === -1 || close < open)
1699
+ return undefined;
1700
+ const pid = text.slice(0, open);
1701
+ const fields = text.slice(close + 2).split(' ');
1702
+ const [state, parent, group] = fields;
1703
+ const [user, system, start] = [fields[11], fields[12], fields[19]];
1704
+ const numbers = [pid, parent, group, user, system, start];
1705
+ if (state === undefined || state === '')
1706
+ return undefined;
1707
+ if (!numbers.every((value) => value !== undefined && /^\d+$/u.test(value)))
1708
+ return undefined;
1709
+ return {
1710
+ pid: Number(pid),
1711
+ parent: Number(parent),
1712
+ group: Number(group),
1713
+ state,
1714
+ created: boot + Number(start) * CLOCK_TICK_MS,
1715
+ cpu: (Number(user) + Number(system)) * CLOCK_TICK_MS,
1716
+ memory: 0,
1717
+ start: Number(start),
1718
+ };
1719
+ }
1720
+ /**
1721
+ * Parses the resident memory of one Linux `/proc/<pid>/status` text.
1722
+ *
1723
+ * @param text - The content of `/proc/<pid>/status`.
1724
+ * @returns The `VmRSS` value in bytes, or undefined when the text holds no such line, as a kernel
1725
+ * thread's does.
1726
+ */
1727
+ export function parseResident(text) {
1728
+ const match = text
1729
+ .split(/\r\n|\n/u)
1730
+ .map((line) => RESIDENT_PATTERN.exec(line.trim()))
1731
+ .find((item) => item !== null);
1732
+ return match?.[1] === undefined ? undefined : Number(match[1]) * 1024;
1733
+ }
1734
+ /**
1735
+ * Reads the Linux boot time from the process table.
1736
+ *
1737
+ * @param table - The process table's root. Default: {@link PROCESS_TABLE}.
1738
+ * @returns The `btime` line of `stat` in epoch milliseconds, or undefined when the file cannot be
1739
+ * read or holds no such line.
1740
+ */
1741
+ export function readBoot(table = PROCESS_TABLE) {
1742
+ try {
1743
+ const match = readFileSync(join(table, 'stat'), 'utf8')
1744
+ .split(/\r\n|\n/u)
1745
+ .map((line) => BOOT_PATTERN.exec(line.trim()))
1746
+ .find((item) => item !== null);
1747
+ return match?.[1] === undefined ? undefined : Number(match[1]) * 1000;
1748
+ }
1749
+ catch {
1750
+ return undefined;
1751
+ }
1752
+ }
1753
+ /**
1754
+ * Reads every live process of the Linux process table.
1755
+ *
1756
+ * @remarks
1757
+ * An entry whose `stat` is gone, unreadable, or malformed, and an entry that has exited
1758
+ * ({@link ENDED_STATES}), is skipped: an exited member holds no CPU or memory.
1759
+ *
1760
+ * @param table - The process table's root. Default: {@link PROCESS_TABLE}.
1761
+ * @returns One member per live process with its memory at 0, or undefined when the boot time or the
1762
+ * listing cannot be read.
1763
+ */
1764
+ export function readMembers(table = PROCESS_TABLE) {
1765
+ const boot = readBoot(table);
1766
+ const names = readListing(table);
1767
+ if (boot === undefined || names === undefined)
1768
+ return undefined;
1769
+ return names
1770
+ .filter((name) => /^\d+$/u.test(name))
1771
+ .flatMap((name) => {
1772
+ try {
1773
+ const member = parseMember(readFileSync(join(table, name, 'stat'), 'utf8'), boot);
1774
+ return member === undefined || ENDED_STATES.includes(member.state) ? [] : [member];
1775
+ }
1776
+ catch {
1777
+ return [];
1778
+ }
1779
+ });
1780
+ }
1781
+ /**
1782
+ * Reads the resident memory of one Linux process.
1783
+ *
1784
+ * @param pid - The process id.
1785
+ * @param table - The process table's root. Default: {@link PROCESS_TABLE}.
1786
+ * @returns The `VmRSS` value in bytes; 0 when the entry is gone, unreadable, or holds no such line.
1787
+ */
1788
+ export function readResident(pid, table = PROCESS_TABLE) {
1789
+ try {
1790
+ return parseResident(readFileSync(join(table, String(pid), 'status'), 'utf8')) ?? 0;
1791
+ }
1792
+ catch {
1793
+ return 0;
1794
+ }
1795
+ }
1796
+ /**
1797
+ * Selects the members of one run's process tree from a Linux census.
1798
+ *
1799
+ * @remarks
1800
+ * A member of the launcher's process group counts, and so does a known member the census still
1801
+ * shows with its start ticks, and every process a parent link reaches from a counted one, such as a
1802
+ * browser a test runner starts in a group of its own. A group id cannot be reused while the group
1803
+ * has a member, so a member never names an unrelated process.
1804
+ *
1805
+ * @param members - The census.
1806
+ * @param group - The launcher's id, which is its group's id.
1807
+ * @param known - Members an earlier reading counted. Default: none.
1808
+ * @returns The members.
1809
+ */
1810
+ export function selectGroup(members, group, known = []) {
1811
+ const starts = new Map(known.map((member) => [member.pid, member.start]));
1812
+ const reached = new Map(members
1813
+ .filter((member) => member.group === group || starts.get(member.pid) === member.start)
1814
+ .map((member) => [member.pid, member]));
1815
+ for (const member of reached.values()) {
1816
+ for (const row of members) {
1817
+ if (row.parent === member.pid && !reached.has(row.pid))
1818
+ reached.set(row.pid, row);
1819
+ }
1820
+ }
1821
+ return [...reached.values()];
1822
+ }
1823
+ /**
1824
+ * Checks whether a tally passes a light run's threshold.
1825
+ *
1826
+ * @param tally - What the samples read so far.
1827
+ * @param threshold - The light run's threshold.
1828
+ * @returns True when the peak memory or the peak process count is past its threshold; false
1829
+ * otherwise.
1830
+ */
1831
+ export function exceedsThreshold(tally, threshold) {
1832
+ return tally.memory > threshold.memory || tally.processes > threshold.processes;
1833
+ }
1834
+ /**
1835
+ * Reads one Linux process from the process table, with no memory read.
1836
+ *
1837
+ * @param pid - The process id.
1838
+ * @param table - The process table's root. Default: {@link PROCESS_TABLE}.
1839
+ * @returns The member its `stat` shows, its creation date counted from 0, or undefined when the
1840
+ * entry is gone, unreadable, or malformed.
1841
+ */
1842
+ export function readProcess(pid, table = PROCESS_TABLE) {
1843
+ try {
1844
+ return parseMember(readFileSync(join(table, String(pid), 'stat'), 'utf8'), 0);
1845
+ }
1846
+ catch {
1847
+ return undefined;
1848
+ }
1849
+ }
1850
+ /**
1851
+ * Sends one signal to a process id, or to a group when the target is negative.
1852
+ *
1853
+ * @param target - The process id, or the negated group id.
1854
+ * @param signal - The signal.
1855
+ */
1856
+ export function sendSignal(target, signal) {
1857
+ try {
1858
+ process.kill(target, signal);
1859
+ }
1860
+ catch { }
1861
+ }
1862
+ /**
1863
+ * Takes one reading of the process table, and reads a thrown error as a failed reading.
1864
+ *
1865
+ * @param read - Takes the reading; undefined means it could not read the table.
1866
+ * @returns The members the reading listed, or undefined when it failed or threw.
1867
+ */
1868
+ export function takeReading(read) {
1869
+ try {
1870
+ return read();
1871
+ }
1872
+ catch {
1873
+ return undefined;
1874
+ }
1875
+ }
1876
+ /**
1877
+ * Collects a breaching tree to a fixpoint: each reading selects the launcher's group, every member
1878
+ * of a group collected so far, the members collected so far that it still shows with their start
1879
+ * ticks, and every process a parent link reaches from those, and sends `SIGSTOP` to each selected
1880
+ * member's group that has received none.
1881
+ *
1882
+ * @remarks
1883
+ * A stopped parent keeps its children's parent field, so the next reading reaches what an earlier
1884
+ * one missed, and a group-directed signal reaches the child of a fork in flight. The collection
1885
+ * settles when a reading adds no group, and ends unsettled when a reading fails or the budget ends.
1886
+ *
1887
+ * @param read - Takes one reading of the process table; undefined means it could not read it.
1888
+ * @param signal - Sends a signal to a process id, or to a group when the target is negative.
1889
+ * @param collection - What the earlier readings collected.
1890
+ * @param budget - The readings left.
1891
+ * @returns What the readings collected.
1892
+ */
1893
+ export function collectTree(read, signal, collection, budget) {
1894
+ const members = budget > 0 ? takeReading(read) : undefined;
1895
+ if (members === undefined)
1896
+ return collection;
1897
+ const known = new Set(collection.groups);
1898
+ const selected = selectGroup(members, collection.group, [
1899
+ ...collection.members,
1900
+ ...members.filter((member) => known.has(member.group)),
1901
+ ]);
1902
+ const added = [...new Set(selected.map((member) => member.group))].filter((group) => !known.has(group));
1903
+ for (const group of added)
1904
+ signal(-group, 'SIGSTOP');
1905
+ const next = { ...collection, groups: [...collection.groups, ...added], members: selected };
1906
+ return added.length === 0
1907
+ ? { ...next, settled: true }
1908
+ : collectTree(read, signal, next, budget - 1);
1909
+ }
1910
+ /**
1911
+ * Kills what a breach collected: each collected group other than the launcher's, in reverse order
1912
+ * of collection; each collected member outside the launcher's group by its id; and the launcher's
1913
+ * group last.
1914
+ *
1915
+ * @remarks
1916
+ * A child group ends before the group of its parent, because the exit that orphans a group with
1917
+ * stopped members of the same session sends that group `SIGHUP` and `SIGCONT`. The by-id signal
1918
+ * reaches a member that left its group after the last reading. The launcher's group ends through
1919
+ * {@link killMembers}, which pauses after it. `SIGKILL` ends a stopped process, so nothing is left
1920
+ * stopped.
1921
+ *
1922
+ * @param collection - What the readings collected.
1923
+ * @param signal - Sends a signal, for a proof. Default: {@link sendSignal}.
1924
+ * @returns What the kill signalled, and whether the readings settled.
1925
+ */
1926
+ export function killTree(collection, signal = sendSignal) {
1927
+ const { group } = collection;
1928
+ const others = collection.groups.filter((id) => id !== group).toReversed();
1929
+ for (const id of others)
1930
+ signal(-id, 'SIGKILL');
1931
+ const outside = collection.members
1932
+ .filter((member) => member.group !== group)
1933
+ .map((member) => member.pid);
1934
+ for (const pid of outside)
1935
+ signal(pid, 'SIGKILL');
1936
+ killMembers([group], signal);
1937
+ return { settled: collection.settled, groups: [...others, group], members: outside };
1938
+ }
1939
+ /**
1940
+ * Ends the tree one Linux census sample breached: it stops the launcher's group and each counted
1941
+ * member's group, collects the tree to a fixpoint, and kills what it collected.
1942
+ *
1943
+ * @remarks
1944
+ * The launcher's group takes `SIGSTOP` first. A counted member outside it is a seed only while a
1945
+ * fresh read of its `stat` shows the start ticks the census sampled, and its group, as that read
1946
+ * shows it, takes `SIGSTOP` next. {@link collectTree} then reads up to {@link KILL_BUDGET} times,
1947
+ * and every path, a failed reading included, ends in {@link killTree}.
1948
+ *
1949
+ * @param group - The launcher's id, which is its group's id.
1950
+ * @param members - The members the breaching sample selected per {@link selectGroup}.
1951
+ * @param table - The process table's root, for a proof. Default: {@link PROCESS_TABLE}.
1952
+ * @param signal - Sends a signal, for a proof. Default: {@link sendSignal}.
1953
+ * @returns What the kill signalled, and whether its readings settled.
1954
+ */
1955
+ export function killCensus(group, members, table = PROCESS_TABLE, signal = sendSignal) {
1956
+ signal(-group, 'SIGSTOP');
1957
+ const seeds = members.flatMap((member) => {
1958
+ if (member.group === group)
1959
+ return [];
1960
+ const fresh = readProcess(member.pid, table);
1961
+ return fresh?.start === member.start ? [fresh] : [];
1962
+ });
1963
+ const groups = [...new Set(seeds.map((member) => member.group))].filter((id) => id !== group);
1964
+ for (const id of groups)
1965
+ signal(-id, 'SIGSTOP');
1966
+ const collection = collectTree(() => readMembers(table), signal, { group, groups: [group, ...groups], members: seeds, settled: false }, KILL_BUDGET);
1967
+ return killTree(collection, signal);
1968
+ }
1659
1969
  /**
1660
1970
  * Reads the members of one run's process tree.
1661
1971
  *
@@ -1697,8 +2007,10 @@ export function selectTree(rows, run, ceiling) {
1697
2007
  * group, and a pause follows, because no event reports the end of a foreign group.
1698
2008
  *
1699
2009
  * @param members - The ids a reading returned.
2010
+ * @param signal - Sends a signal on a host other than Windows, for a proof. Default:
2011
+ * {@link sendSignal}.
1700
2012
  */
1701
- export function killMembers(members) {
2013
+ export function killMembers(members, signal = sendSignal) {
1702
2014
  for (const member of members) {
1703
2015
  if (process.platform === 'win32') {
1704
2016
  spawnSync('taskkill', ['/pid', String(member), '/T', '/F'], {
@@ -1707,10 +2019,7 @@ export function killMembers(members) {
1707
2019
  });
1708
2020
  }
1709
2021
  else {
1710
- try {
1711
- process.kill(-member, 'SIGKILL');
1712
- }
1713
- catch { }
2022
+ signal(-member, 'SIGKILL');
1714
2023
  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, KILL_PAUSE_MS);
1715
2024
  }
1716
2025
  }
@@ -2286,7 +2595,7 @@ export class Sampler {
2286
2595
  if (threshold === undefined ||
2287
2596
  this.#ceiling !== undefined ||
2288
2597
  this.#breached ||
2289
- (this.#tally.memory <= threshold.memory && this.#tally.processes <= threshold.processes)) {
2598
+ !exceedsThreshold(this.#tally, threshold)) {
2290
2599
  return;
2291
2600
  }
2292
2601
  const [launcher] = this.#seeds;
@@ -2296,18 +2605,162 @@ export class Sampler {
2296
2605
  this.#breach(launcher);
2297
2606
  }
2298
2607
  }
2608
+ /**
2609
+ * Samples one holder's process tree from the Linux process table, inside the lane process.
2610
+ *
2611
+ * @remarks
2612
+ * A sample reads each entry's `stat` for its parent, group, state, start, and CPU time, selects the
2613
+ * tree per {@link selectGroup}, and reads each member's `VmRSS` from its `status`. The census starts
2614
+ * no process and readies at once when the table reads. A {@link Census.sample} call reads after one
2615
+ * turn of the event loop; after the first, a timer also samples every {@link SAMPLE_MS} until
2616
+ * {@link Census.stop}. A threshold, given for a light run, calls the breach handler once with the
2617
+ * launcher's id and the members that sample selected, on the first sample before
2618
+ * {@link Census.seal} whose memory or process count passes it. The holder passes {@link killCensus},
2619
+ * which stops those members' groups and collects what they started after the sample before it
2620
+ * kills.
2621
+ */
2622
+ export class Census {
2623
+ #table;
2624
+ #threshold;
2625
+ #breach;
2626
+ #group;
2627
+ #sealed = false;
2628
+ #tally = { cpu: new Map(), memory: 0, processes: 0 };
2629
+ #breached = false;
2630
+ #timer;
2631
+ #stopped = false;
2632
+ /**
2633
+ * Creates the census.
2634
+ *
2635
+ * @param threshold - The light run's threshold, or undefined for a heavy run.
2636
+ * @param breach - Called once with the launcher's id and the members the sample selected when a
2637
+ * sample passes the threshold.
2638
+ * @param table - The process table's root, for a proof. Default: {@link PROCESS_TABLE}.
2639
+ */
2640
+ constructor(threshold, breach, table = PROCESS_TABLE) {
2641
+ this.#threshold = threshold;
2642
+ this.#breach = breach;
2643
+ this.#table = table;
2644
+ }
2645
+ /** Holds what the samples read so far. */
2646
+ get tally() {
2647
+ return this.#tally;
2648
+ }
2649
+ /** Holds whether a sample passed the threshold. */
2650
+ get breached() {
2651
+ return this.#breached;
2652
+ }
2653
+ /**
2654
+ * Checks that the process table reads.
2655
+ *
2656
+ * @param _budget - Unused: the census starts no process to wait for.
2657
+ * @returns A promise of true when the table reads and the census has not stopped; false otherwise.
2658
+ */
2659
+ async ready(_budget) {
2660
+ return !this.#stopped && readMembers(this.#table) !== undefined;
2661
+ }
2662
+ /**
2663
+ * Names the launcher whose group later samples read.
2664
+ *
2665
+ * @param seeds - The launcher id and, when known, the command id; the launcher's id is its group's.
2666
+ * @param _floor - Unused: a group needs no creation bound.
2667
+ */
2668
+ seed(seeds, _floor) {
2669
+ const [launcher] = seeds;
2670
+ this.#group = launcher;
2671
+ }
2672
+ /**
2673
+ * Marks the launcher's exit: a later sample triggers no breach.
2674
+ *
2675
+ * @param _ceiling - Unused: a group id is not reused while the group has a member.
2676
+ */
2677
+ seal(_ceiling) {
2678
+ this.#sealed = true;
2679
+ }
2680
+ /**
2681
+ * Reads one sample after one turn of the event loop, and starts the timer on the first call.
2682
+ *
2683
+ * @param _budget - Unused: the read answers inside this process.
2684
+ * @returns A promise of the members the sample selected, empty before a seed; undefined after a
2685
+ * stop or when the table cannot be read.
2686
+ */
2687
+ async sample(_budget) {
2688
+ await yieldTurn();
2689
+ if (this.#stopped)
2690
+ return undefined;
2691
+ this.#timer ??= setInterval(() => this.#read(), SAMPLE_MS).unref();
2692
+ return this.#read();
2693
+ }
2694
+ /**
2695
+ * Samples every {@link BURST_MS} until a time or an abort.
2696
+ *
2697
+ * @param until - The epoch millisecond after which no further sample starts.
2698
+ * @param signal - Ends the burst after the sample in flight.
2699
+ * @returns A promise that resolves when the burst ends.
2700
+ */
2701
+ async burst(until, signal) {
2702
+ const rows = await this.sample();
2703
+ if (rows === undefined || signal.aborted || Date.now() >= until)
2704
+ return;
2705
+ await wait(BURST_MS);
2706
+ await this.burst(until, signal);
2707
+ }
2708
+ /**
2709
+ * Stops the timer; a later sample reads nothing.
2710
+ *
2711
+ * @returns A promise that resolves at once.
2712
+ */
2713
+ async stop() {
2714
+ this.#stopped = true;
2715
+ clearInterval(this.#timer);
2716
+ }
2717
+ /**
2718
+ * Stops the timer at once, as {@link Census.stop} does, for the holder's unmeasured path.
2719
+ *
2720
+ * @returns A promise that resolves at once.
2721
+ */
2722
+ async destroy() {
2723
+ this.#stopped = true;
2724
+ clearInterval(this.#timer);
2725
+ }
2726
+ #read() {
2727
+ const members = readMembers(this.#table);
2728
+ const group = this.#group;
2729
+ if (members === undefined)
2730
+ return undefined;
2731
+ if (group === undefined)
2732
+ return [];
2733
+ const selected = selectGroup(members, group).map((member) => ({
2734
+ ...member,
2735
+ memory: readResident(member.pid, this.#table),
2736
+ }));
2737
+ this.#tally = tallySample(this.#tally, selected);
2738
+ const threshold = this.#threshold;
2739
+ if (threshold === undefined ||
2740
+ this.#sealed ||
2741
+ this.#breached ||
2742
+ !exceedsThreshold(this.#tally, threshold)) {
2743
+ return selected;
2744
+ }
2745
+ this.#breached = true;
2746
+ this.#breach(group, selected);
2747
+ return selected;
2748
+ }
2749
+ }
2299
2750
  /**
2300
2751
  * Runs the command as the holder, reads the tree at handover, and releases.
2301
2752
  *
2302
2753
  * @remarks
2303
- * A measured holder starts its command after its sampler readies, samples the tree back to back
2304
- * through the command's first {@link SAMPLE_MS} and once every {@link SAMPLE_MS} after, reads the
2305
- * handover through one more sample, and writes the run's record before it releases, so the command's
2306
- * next arrival reads it. When that sample lists a member, the handover reads, kills, and reads again
2307
- * through fresh snapshots, each a second PowerShell. A sampler that does not ready within
2308
- * {@link READY_MS} is destroyed, and the command runs unmeasured and records nothing. A record that
2309
- * opened a key prunes the history after the release. A light holder lowers its own priority before
2310
- * the spawn, and ends its tree when a sample passes the threshold.
2754
+ * A measured holder starts its command after its sampler readies, samples the tree through the
2755
+ * command's first {@link SAMPLE_MS}, back to back on Windows and every {@link BURST_MS} on Linux, and
2756
+ * once every {@link SAMPLE_MS} after, reads the handover through one more sample, and writes the
2757
+ * run's record before it releases, so the command's next arrival reads it. On Windows, when that
2758
+ * sample lists a member, the handover reads, kills, and reads again through fresh snapshots, each a
2759
+ * second PowerShell; on Linux the handover reads the launcher's group, as an unmeasured run's does.
2760
+ * A sampler that does not ready within {@link READY_MS} is destroyed, and the command runs
2761
+ * unmeasured and records nothing. A record that opened a key prunes the history after the release. A
2762
+ * light holder lowers its own priority before the spawn, and ends its tree when a sample passes the
2763
+ * threshold.
2311
2764
  *
2312
2765
  * @param options - The run.
2313
2766
  * @param launcher - The launcher's path.
@@ -2315,7 +2768,8 @@ export class Sampler {
2315
2768
  * @param measure - What a measured holder needs, or undefined when no limits apply.
2316
2769
  * @param token - This process's endpoint, which holds after the run record exists and leaves before
2317
2770
  * the run record is removed.
2318
- * @param sampler - The measured holder's sampler, started at arrival; the caller stops it.
2771
+ * @param sampler - The measured holder's sampler, a Windows {@link Sampler} started at arrival or a
2772
+ * Linux {@link Census}; the caller stops it.
2319
2773
  * @returns The launcher's code; 1 when a signal ended it; 69 when a light run passed its threshold;
2320
2774
  * 70 when the tree still reads as present or the ticket could not be removed; 75 when the launcher
2321
2775
  * could not start, the priority could not be lowered, or the run record could not be written.
@@ -2382,7 +2836,10 @@ export async function runHolder(options, launcher, sequence, measure, token, sam
2382
2836
  await active.destroy();
2383
2837
  console.error(`lane: the sampler did not answer the handover within ${String(HANDOVER_MS)} ms; ${quote(options.label)} records nothing`);
2384
2838
  }
2385
- const quick = rows !== undefined && typeof run === 'object' ? selectTree(rows, run, ended) : undefined;
2839
+ // A Linux census row carries no creation date the Windows tree selection can bound.
2840
+ const quick = process.platform === 'win32' && rows !== undefined && typeof run === 'object'
2841
+ ? selectTree(rows, run, ended)
2842
+ : undefined;
2386
2843
  const sweep = typeof run !== 'object'
2387
2844
  ? { gone: false, members: [] }
2388
2845
  : quick?.length === 0
@@ -2420,10 +2877,11 @@ export async function runHolder(options, launcher, sequence, measure, token, sam
2420
2877
  * Reads what a run measures at arrival: the limits, the command's key, and its light footprint.
2421
2878
  *
2422
2879
  * @remarks
2423
- * A host other than Windows has no sampler, so it measures nothing and every ticket there is heavy.
2424
- * A `--solo` run is heavy whatever its command reads. A `mutate` run is keyed without its edits
2425
- * file and seeded by its wrapped command; {@link decideDirectory} keeps it apart from the tickets of
2426
- * its working directory.
2880
+ * The sampler is platform-defined: Windows has a PowerShell {@link Sampler} and Linux a
2881
+ * {@link Census} of its process table, and any other host has none, so it measures nothing and every
2882
+ * ticket there is heavy. A `--solo` run is heavy whatever its command reads. A `mutate` run is keyed
2883
+ * without its edits file and seeded by its wrapped command; {@link decideDirectory} keeps it apart
2884
+ * from the tickets of its working directory.
2427
2885
  *
2428
2886
  * @param options - The run.
2429
2887
  * @param token - This process's token.
@@ -2431,7 +2889,7 @@ export async function runHolder(options, launcher, sequence, measure, token, sam
2431
2889
  * host has no sampler.
2432
2890
  */
2433
2891
  export function readMeasure(options, token) {
2434
- if (process.platform !== 'win32')
2892
+ if (process.platform !== 'win32' && process.platform !== 'linux')
2435
2893
  return undefined;
2436
2894
  const limits = readLimits(options.root);
2437
2895
  if (limits === 'unread') {
@@ -2461,9 +2919,17 @@ export async function enterLane(options, launcher, tokenId, token) {
2461
2919
  try {
2462
2920
  mkdirSync(root, { recursive: true });
2463
2921
  const measure = readMeasure(options, tokenId);
2922
+ const threshold = measure?.light === undefined ? undefined : measure.limits.threshold;
2464
2923
  const sampler = measure === undefined
2465
2924
  ? undefined
2466
- : new Sampler(measure.light === undefined ? undefined : measure.limits.threshold, (pid) => killMembers([pid]));
2925
+ : process.platform === 'win32'
2926
+ ? new Sampler(threshold, (pid) => killMembers([pid]))
2927
+ : new Census(threshold, (group, members) => {
2928
+ const kill = killCensus(group, members);
2929
+ if (!kill.settled) {
2930
+ console.error(`lane: the breach readings of ${quote(options.label)} ended unsettled, at ${String(KILL_BUDGET)} readings or on a failed reading; the lane killed the groups ${kill.groups.join(', ')} and the members ${kill.members.join(', ') || 'none'} it collected`);
2931
+ }
2932
+ });
2467
2933
  try {
2468
2934
  await token.listen(renderEndpoint(root, tokenId));
2469
2935
  const edits = extractMutation(options.command) !== undefined || matchesRestore(options.command);
package/dist/bin/main.js CHANGED
@@ -10,7 +10,7 @@ import { readdirSync } from "node:fs";
10
10
  import { parseArgs } from "node:util";
11
11
  var package_default = {
12
12
  name: "@orkestrel/scaffold",
13
- version: "0.0.138",
13
+ version: "0.0.139",
14
14
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
15
15
  keywords: [
16
16
  "audit",
@@ -103,7 +103,7 @@ var package_default = {
103
103
  },
104
104
  dependencies: {
105
105
  "@orkestrel/console": "^0.0.21",
106
- "@orkestrel/contract": "^0.0.24",
106
+ "@orkestrel/contract": "^0.0.26",
107
107
  "@orkestrel/emitter": "^0.0.17",
108
108
  "@orkestrel/markdown": "^0.0.22",
109
109
  "@orkestrel/process": "^0.0.21",
@@ -115,11 +115,11 @@ var package_default = {
115
115
  "@orkestrel/guide": "^0.0.32",
116
116
  "@orkestrel/html": "^0.0.17",
117
117
  "@orkestrel/probe": "^0.0.31",
118
- "@orkestrel/test": "^0.0.42",
118
+ "@orkestrel/test": "^0.0.43",
119
119
  "@types/node": "^24.19.2",
120
120
  "@vitest/browser-playwright": "^5.1.0",
121
- "oxfmt": "^0.78.0",
122
- "oxlint": "^1.93.0",
121
+ "oxfmt": "^0.79.0",
122
+ "oxlint": "^1.94.0",
123
123
  "playwright": "^1.64.1",
124
124
  "typescript": "^7.0.2",
125
125
  "vite": "^8.3.8",
@@ -21,7 +21,7 @@ description: >-
21
21
  Run from the checkout root. The script's opening comment owns its behavior.
22
22
 
23
23
  - `scripts/cases.ts --report FILE.json [--passed NAME ...] [--failed NAME ...]` reads a Vitest `--reporter=json` report and requires every case a `--passed` name matches to have passed and every case a `--failed` name matches to have failed. A name matches a case's full name or its own title exactly; both flags repeat. A name that matches no case is missing, and a failed case no name matches is refused, as is a test file that failed with no failed case (it did not collect, or a hook threw) and a report whose `success` is false while nothing in it failed. It prints one summary line, each difference, and `ok` or `differences=N`. Exit 0 when the report matches, 3 when it does not, 2 when the report cannot be read as a Vitest report, 64 usage.
24
- - `scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] [--solo] -- COMMAND [ARGS...]` runs process-running commands on this host in one heavy lane and several light lanes, each in arrival order, across every checkout and shell of one user account: it takes a ticket, waits with no timer, runs the command through `.agents/skills/orkestrel-dispatch/scripts/launch.ts`, kills and reads the command's process tree until no member remains, and releases. A ticket runs light only while `limits.json` exists under the lane root and the command's kind or its own run records read it light; every other ticket runs heavy, one at a time. `npx` and `npm exec` read as the tool they run, and a `mutate` run of the falsify skill reads as the command it wraps, keyed without its edits file, and a `mutate --restore` run reads heavy; each waits on the earlier tickets of its working directory, and every later ticket of that directory waits on it. A run's record counts a command shorter than the sample interval when the command outlives one process query; a shorter command can record zero, per the opening comment's Sampling limit. A record that opens a history key prunes the history to the age and count bounds the opening comment names. `--solo` runs heavy with no light run beside it. `scripts/lane.ts --status [--root DIR] [--json]` prints each ticket in arrival order with its label, `live`, `dead`, or `unread`, its lane, and whether it holds, and names the heavy holder and every light holder; it writes nothing, and an absent root reads as an empty queue. The two forms are two modes, and `--status` with a run's flag is refused. Exit: the launcher's code, 1 when a signal ended the launcher, 64 usage, 69 when a light run passed its threshold and the lane ended it, 75 when the lane refused before the command ran, 70 when the command ran and its tree still reads as present or its ticket could not be removed; `--status` exits 0 on a read and 75 when the root cannot be listed. A command that itself exits 64, 69, 70, or 75 reads like the lane's own code. The opening comment owns the lane rules, the limits, and the migration stop.
24
+ - `scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] [--solo] -- COMMAND [ARGS...]` runs process-running commands on this host in one heavy lane and several light lanes, each in arrival order, across every checkout and shell of one user account: it takes a ticket, waits with no timer, runs the command through `.agents/skills/orkestrel-dispatch/scripts/launch.ts`, kills and reads the command's process tree until no member remains, and releases. A ticket runs light only on Windows or Linux, while `limits.json` exists under the lane root and the command's kind or its own run records read it light; every other ticket runs heavy, one at a time. `npx` and `npm exec` read as the tool they run, and a `mutate` run of the falsify skill reads as the command it wraps, keyed without its edits file, and a `mutate --restore` run reads heavy; each waits on the earlier tickets of its working directory, and every later ticket of that directory waits on it. A run's record counts a command shorter than the sample interval when the command outlives one process query; a shorter command can record zero, per the opening comment's Sampling limit. A record that opens a history key prunes the history to the age and count bounds the opening comment names. `--solo` runs heavy with no light run beside it. `scripts/lane.ts --status [--root DIR] [--json]` prints each ticket in arrival order with its label, `live`, `dead`, or `unread`, its lane, and whether it holds, and names the heavy holder and every light holder; it writes nothing, and an absent root reads as an empty queue. The two forms are two modes, and `--status` with a run's flag is refused. Exit: the launcher's code, 1 when a signal ended the launcher, 64 usage, 69 when a light run passed its threshold and the lane ended it, 75 when the lane refused before the command ran, 70 when the command ran and its tree still reads as present or its ticket could not be removed; `--status` exits 0 on a read and 75 when the root cannot be listed. A command that itself exits 64, 69, 70, or 75 reads like the lane's own code. The opening comment owns the lane rules, the limits, and the migration stop.
25
25
 
26
26
  ## Bound the host
27
27