@orkestrel/scaffold 0.0.138 → 0.0.140
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.
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +489 -23
- package/dist/bin/main.js +89 -29
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +628 -41
- package/dist/host/claude/agents/orkestrel.md +52 -52
- package/dist/host/guides/abort.md +2 -0
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/contract.md +314 -210
- package/dist/host/guides/guide.md +10 -2
- package/dist/host/guides/mcp.md +9 -9
- package/dist/host/guides/middleware.md +474 -259
- package/dist/host/guides/probe.md +1 -2
- package/dist/host/guides/router.md +282 -165
- package/dist/host/guides/scaffold.md +27 -18
- package/dist/host/guides/server.md +419 -183
- package/dist/host/manifest.json +14 -14
- package/dist/host/scripts/browsers.sh +0 -0
- package/dist/host/scripts/codex.sh +0 -0
- package/dist/host/scripts/cursor.sh +0 -0
- package/dist/host/scripts/deps.sh +0 -0
- package/dist/host/scripts/npm.sh +0 -0
- package/dist/host/scripts/ollama.sh +0 -0
- package/dist/src/core/index.cjs +17 -17
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +17 -17
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +6 -24
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +1 -1
- package/dist/src/server/index.d.ts +1 -1
- package/dist/src/server/index.js +7 -25
- package/dist/src/server/index.js.map +1 -1
- package/package.json +14 -14
|
@@ -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
|
-
|
|
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
|
|
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
|
|
2304
|
-
*
|
|
2305
|
-
*
|
|
2306
|
-
*
|
|
2307
|
-
*
|
|
2308
|
-
*
|
|
2309
|
-
*
|
|
2310
|
-
*
|
|
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
|
|
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
|
-
|
|
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
|
-
*
|
|
2424
|
-
*
|
|
2425
|
-
*
|
|
2426
|
-
* its
|
|
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
|
-
:
|
|
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);
|