@orkestrel/scaffold 0.0.135 → 0.0.136
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 +167 -4
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +20 -5
- package/dist/bin/main.js +3 -3
- package/dist/host/AGENTS.md +1 -1
- package/dist/host/agents/orchestration.md +2 -2
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +201 -8
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +24 -5
- package/dist/host/claude/agents/orkestrel.md +7 -7
- package/dist/host/claude/agents/reviewer.md +1 -1
- package/dist/host/claude/rules/documentation.md +1 -1
- package/dist/host/claude/rules/patterns.md +2 -2
- package/dist/host/claude/rules/workspace.md +9 -4
- package/dist/host/configs/helpers.ts +21 -6
- package/dist/host/guides/contract.md +198 -163
- package/dist/host/guides/database.md +760 -300
- package/dist/host/guides/indexeddb.md +80 -66
- package/dist/host/guides/relation.md +56 -32
- package/dist/host/guides/scaffold.md +8 -2
- package/dist/host/guides/sqlite.md +44 -23
- package/dist/host/guides/test.md +7 -3
- package/dist/host/manifest.json +19 -19
- 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/host/tests/config.test.ts +71 -3
- package/dist/src/core/index.cjs +103 -26
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +31 -5
- package/dist/src/core/index.d.ts +31 -5
- package/dist/src/core/index.js +103 -27
- package/dist/src/core/index.js.map +1 -1
- package/package.json +3 -3
|
@@ -65,6 +65,13 @@ export const TOKEN_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[
|
|
|
65
65
|
export const TICKET_PATTERN = /^(\d+)\.ticket$/u;
|
|
66
66
|
/** Matches one snapshot row: process id, parent id, and creation time in milliseconds. */
|
|
67
67
|
export const ROW_PATTERN = /^(\d+) (\d+) (\d+)$/u;
|
|
68
|
+
/** Names the directory where a Linux host publishes its process table. */
|
|
69
|
+
export const PROCESS_TABLE = '/proc';
|
|
70
|
+
/**
|
|
71
|
+
* Lists the process-table states of a member that has exited and that its parent has not reaped:
|
|
72
|
+
* `Z` for a zombie, and `X` for a process the kernel is releasing.
|
|
73
|
+
*/
|
|
74
|
+
export const ENDED_STATES = ['Z', 'X'];
|
|
68
75
|
/** Lists the signals that interrupt a lane on a host that delivers them. */
|
|
69
76
|
export const STOP_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
|
|
70
77
|
/**
|
|
@@ -1479,19 +1486,175 @@ export function selectMembers(rows, seeds, floor, ceiling) {
|
|
|
1479
1486
|
return [...members.values()];
|
|
1480
1487
|
}
|
|
1481
1488
|
/**
|
|
1482
|
-
*
|
|
1489
|
+
* Parses one process-table `stat` line into its state and its process group.
|
|
1490
|
+
*
|
|
1491
|
+
* @remarks
|
|
1492
|
+
* The command name sits in parentheses and can hold spaces and parentheses itself, so the fields
|
|
1493
|
+
* are read after the last `)`: the state, the parent id, then the group id.
|
|
1494
|
+
*
|
|
1495
|
+
* @param text - The content of `/proc/<pid>/stat`.
|
|
1496
|
+
* @returns The state and the group, or undefined when the text does not have that form.
|
|
1497
|
+
*/
|
|
1498
|
+
export function parseStat(text) {
|
|
1499
|
+
const close = text.lastIndexOf(')');
|
|
1500
|
+
if (close === -1)
|
|
1501
|
+
return undefined;
|
|
1502
|
+
const [state, , group] = text.slice(close + 2).split(' ');
|
|
1503
|
+
return state === undefined || state === '' || group === undefined || !/^\d+$/u.test(group)
|
|
1504
|
+
? undefined
|
|
1505
|
+
: { state, group: Number(group) };
|
|
1506
|
+
}
|
|
1507
|
+
/**
|
|
1508
|
+
* Lists the entries of one process-table directory.
|
|
1509
|
+
*
|
|
1510
|
+
* @param path - The directory.
|
|
1511
|
+
* @returns The entry names, or undefined when the listing fails.
|
|
1512
|
+
*/
|
|
1513
|
+
export function readListing(path) {
|
|
1514
|
+
try {
|
|
1515
|
+
return readdirSync(path);
|
|
1516
|
+
}
|
|
1517
|
+
catch {
|
|
1518
|
+
return undefined;
|
|
1519
|
+
}
|
|
1520
|
+
}
|
|
1521
|
+
/**
|
|
1522
|
+
* Reads one thread's state from its own process-table entry.
|
|
1523
|
+
*
|
|
1524
|
+
* @param pid - The process id, as its process-table entry names it.
|
|
1525
|
+
* @param tid - The thread id, as the process's `task` listing names it.
|
|
1526
|
+
* @param table - The process table's root. Default: {@link PROCESS_TABLE}.
|
|
1527
|
+
* @returns The task keyed `<pid>/<tid>`, or undefined when its `stat` cannot be read or parsed.
|
|
1528
|
+
*/
|
|
1529
|
+
export function readTask(pid, tid, table = PROCESS_TABLE) {
|
|
1530
|
+
try {
|
|
1531
|
+
const stat = parseStat(readFileSync(join(table, pid, 'task', tid, 'stat'), 'utf8'));
|
|
1532
|
+
return stat === undefined ? undefined : { id: `${pid}/${tid}`, state: stat.state };
|
|
1533
|
+
}
|
|
1534
|
+
catch {
|
|
1535
|
+
return undefined;
|
|
1536
|
+
}
|
|
1537
|
+
}
|
|
1538
|
+
/**
|
|
1539
|
+
* Reads the state of every thread of one process from the process table.
|
|
1540
|
+
*
|
|
1541
|
+
* @param pid - The process id, as its process-table entry names it.
|
|
1542
|
+
* @returns One task per thread, keyed `<pid>/<tid>`, or undefined when the `task` listing fails,
|
|
1543
|
+
* lists no thread, or holds a thread whose `stat` cannot be read: what the reading cannot read
|
|
1544
|
+
* counts as present.
|
|
1545
|
+
* @param table - The process table's root. Default: {@link PROCESS_TABLE}.
|
|
1546
|
+
*/
|
|
1547
|
+
export function readThreads(pid, table = PROCESS_TABLE) {
|
|
1548
|
+
const tids = readListing(join(table, pid, 'task'));
|
|
1549
|
+
if (tids === undefined || tids.length === 0)
|
|
1550
|
+
return undefined;
|
|
1551
|
+
const tasks = tids.map((tid) => readTask(pid, tid, table));
|
|
1552
|
+
return tasks.includes(undefined)
|
|
1553
|
+
? undefined
|
|
1554
|
+
: tasks.flatMap((task) => (task === undefined ? [] : [task]));
|
|
1555
|
+
}
|
|
1556
|
+
/**
|
|
1557
|
+
* Reads the threads of one process-table entry when it belongs to a process group.
|
|
1558
|
+
*
|
|
1559
|
+
* @param name - The process id, as the process-table listing names it.
|
|
1560
|
+
* @param group - The group id.
|
|
1561
|
+
* @returns The entry's threads when it belongs to the group, none when it belongs to another group
|
|
1562
|
+
* or its `stat` is gone (`ENOENT`, a process that ended), or undefined when its `stat` cannot be
|
|
1563
|
+
* read for any other reason or cannot be parsed, or its threads cannot be read.
|
|
1564
|
+
* @param table - The process table's root. Default: {@link PROCESS_TABLE}.
|
|
1565
|
+
*/
|
|
1566
|
+
export function readMember(name, group, table = PROCESS_TABLE) {
|
|
1567
|
+
try {
|
|
1568
|
+
const stat = parseStat(readFileSync(join(table, name, 'stat'), 'utf8'));
|
|
1569
|
+
if (stat === undefined)
|
|
1570
|
+
return undefined;
|
|
1571
|
+
return stat.group === group ? readThreads(name, table) : [];
|
|
1572
|
+
}
|
|
1573
|
+
catch (error) {
|
|
1574
|
+
return readCode(error) === 'ENOENT' ? [] : undefined;
|
|
1575
|
+
}
|
|
1576
|
+
}
|
|
1577
|
+
/**
|
|
1578
|
+
* Reads every thread of every member of a process group from the process table.
|
|
1483
1579
|
*
|
|
1484
1580
|
* @param group - The group id.
|
|
1485
|
-
* @returns
|
|
1581
|
+
* @returns One task per thread of each member, or undefined when the host publishes no process
|
|
1582
|
+
* table, the table cannot be listed, or any entry cannot be read; a process whose `stat` is gone
|
|
1583
|
+
* is skipped.
|
|
1584
|
+
* @param table - The process table's root. Default: {@link PROCESS_TABLE}.
|
|
1486
1585
|
*/
|
|
1487
|
-
export function
|
|
1586
|
+
export function readTasks(group, table = PROCESS_TABLE) {
|
|
1587
|
+
if (!existsSync(join(table, 'self', 'stat')))
|
|
1588
|
+
return undefined;
|
|
1589
|
+
const names = readListing(table);
|
|
1590
|
+
if (names === undefined)
|
|
1591
|
+
return undefined;
|
|
1592
|
+
const members = names
|
|
1593
|
+
.filter((name) => /^\d+$/u.test(name))
|
|
1594
|
+
.map((name) => readMember(name, group, table));
|
|
1595
|
+
return members.includes(undefined)
|
|
1596
|
+
? undefined
|
|
1597
|
+
: members.flatMap((member) => (member === undefined ? [] : member));
|
|
1598
|
+
}
|
|
1599
|
+
/**
|
|
1600
|
+
* Checks whether two readings of one group show the same threads, every one of them exited.
|
|
1601
|
+
*
|
|
1602
|
+
* @remarks
|
|
1603
|
+
* A thread read as exited cannot start another process or thread after that read, so every process
|
|
1604
|
+
* that joined the group and every thread created before the first reading finished exists when the
|
|
1605
|
+
* second listing starts. A second reading of the same tasks therefore leaves none of them out, and a
|
|
1606
|
+
* member that forked between its listing and its read shows up as a task the first reading lacks.
|
|
1607
|
+
* An empty reading reads as not ended, because the probe signal reached a member the table did not
|
|
1608
|
+
* show, as a table from another PID namespace does.
|
|
1609
|
+
*
|
|
1610
|
+
* @param first - The first reading.
|
|
1611
|
+
* @param second - The reading taken after the first finished.
|
|
1612
|
+
* @returns True if both readings hold at least one task, list the same task ids, and show every
|
|
1613
|
+
* task as {@link ENDED_STATES}; false otherwise.
|
|
1614
|
+
*/
|
|
1615
|
+
export function matchesEnded(first, second) {
|
|
1616
|
+
return (first.length > 0 &&
|
|
1617
|
+
first
|
|
1618
|
+
.map((task) => task.id)
|
|
1619
|
+
.toSorted()
|
|
1620
|
+
.join(' ') ===
|
|
1621
|
+
second
|
|
1622
|
+
.map((task) => task.id)
|
|
1623
|
+
.toSorted()
|
|
1624
|
+
.join(' ') &&
|
|
1625
|
+
[...first, ...second].every((task) => ENDED_STATES.includes(task.state)));
|
|
1626
|
+
}
|
|
1627
|
+
/**
|
|
1628
|
+
* Reads whether a process group still has a member that has not exited.
|
|
1629
|
+
*
|
|
1630
|
+
* @remarks
|
|
1631
|
+
* A signal reaches a zombie, so a group whose members have all exited still answers the probe
|
|
1632
|
+
* signal until their parent reaps them, which an init that does not reap as a child ends leaves
|
|
1633
|
+
* for later. Where the host publishes a process table, a group reads as ended when two readings
|
|
1634
|
+
* taken one after the other show the same threads of its members, every one {@link ENDED_STATES},
|
|
1635
|
+
* per {@link matchesEnded}. A zombie whose threads have all exited holds no CPU, memory, or file
|
|
1636
|
+
* handle; a process whose main thread exited while another thread runs shows `Z` for itself and
|
|
1637
|
+
* reads as present through that thread. A host without that table, and a reading that cannot read
|
|
1638
|
+
* part of it, read such a group as present.
|
|
1639
|
+
*
|
|
1640
|
+
* @param group - The group id.
|
|
1641
|
+
* @param read - Takes one reading of the group's threads; undefined means the reading could not
|
|
1642
|
+
* read the table. Default: {@link readTasks}.
|
|
1643
|
+
* @returns The group id while the host reports a member that has not exited or the reading
|
|
1644
|
+
* cannot read the table; empty when it reports none.
|
|
1645
|
+
*/
|
|
1646
|
+
export function readGroup(group, read = readTasks) {
|
|
1488
1647
|
try {
|
|
1489
1648
|
process.kill(-group, 0);
|
|
1490
|
-
return [group];
|
|
1491
1649
|
}
|
|
1492
1650
|
catch (error) {
|
|
1493
1651
|
return readCode(error) === 'ESRCH' ? [] : [group];
|
|
1494
1652
|
}
|
|
1653
|
+
const first = read(group);
|
|
1654
|
+
if (first === undefined)
|
|
1655
|
+
return [group];
|
|
1656
|
+
const second = read(group);
|
|
1657
|
+
return second !== undefined && matchesEnded(first, second) ? [] : [group];
|
|
1495
1658
|
}
|
|
1496
1659
|
/**
|
|
1497
1660
|
* Reads the members of one run's process tree.
|
|
@@ -678,7 +678,8 @@ export function refuseLocalSpecs(runner, step) {
|
|
|
678
678
|
*
|
|
679
679
|
* @param runner - The visit's state.
|
|
680
680
|
* @returns The first refusal, or undefined when the lock is tracked and clean, the manifest holds no
|
|
681
|
-
* local spec or workspace, `tmp
|
|
681
|
+
* local spec or workspace, `tmp/units/wave` crosses no link inside the target, `tmp/` is ignored,
|
|
682
|
+
* and the target is its work tree's root.
|
|
682
683
|
*/
|
|
683
684
|
export function readRegenerationRefusal(runner) {
|
|
684
685
|
if (runStep(runner, 'regenerate', 'git', ['ls-files', '--error-unmatch', 'package-lock.json'], runner.target)?.status !== 0)
|
|
@@ -692,6 +693,13 @@ export function readRegenerationRefusal(runner) {
|
|
|
692
693
|
return `local dependency specs: ${specs.map(([path, spec]) => `${path}: ${spec}`).join(', ')}`;
|
|
693
694
|
if (manifest !== undefined && 'workspaces' in manifest)
|
|
694
695
|
return 'the manifest declares workspaces';
|
|
696
|
+
// Git refuses a pathspec beyond a link with exit 128, which reads as an unignored `tmp/`.
|
|
697
|
+
try {
|
|
698
|
+
validateWavePath(runner.target, join(runner.target, 'tmp', 'units', 'wave'));
|
|
699
|
+
}
|
|
700
|
+
catch (error) {
|
|
701
|
+
return error instanceof Error ? error.message : String(error);
|
|
702
|
+
}
|
|
695
703
|
if (runStep(runner, 'regenerate', 'git', ['check-ignore', '-q', 'tmp/units/wave/probe'], runner.target)?.status !== 0)
|
|
696
704
|
return 'tmp/ is not git-ignored';
|
|
697
705
|
const root = runStep(runner, 'regenerate', 'git', ['rev-parse', '--show-toplevel'], runner.target);
|
|
@@ -1839,7 +1847,8 @@ export function runVisit(values) {
|
|
|
1839
1847
|
*
|
|
1840
1848
|
* @param target - The target directory.
|
|
1841
1849
|
* @returns A new stamped directory under the target's `tmp/units/wave/` when the target is inside a
|
|
1842
|
-
* work tree that ignores `tmp/`,
|
|
1850
|
+
* work tree that ignores `tmp/`, or when that path crosses a link, which the caller's link check
|
|
1851
|
+
* refuses; else undefined.
|
|
1843
1852
|
*/
|
|
1844
1853
|
export function readJournalDirectory(target) {
|
|
1845
1854
|
const inside = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
|
|
@@ -1849,14 +1858,20 @@ export function readJournalDirectory(target) {
|
|
|
1849
1858
|
});
|
|
1850
1859
|
if (inside.status !== 0 || inside.stdout.trim() !== 'true')
|
|
1851
1860
|
return undefined;
|
|
1861
|
+
const directory = join(target, 'tmp', 'units', 'wave', new Date().toISOString().replace(/[:.]/gu, '-'));
|
|
1862
|
+
// Git refuses a pathspec beyond a link with exit 128, which reads as an unignored `tmp/`.
|
|
1863
|
+
try {
|
|
1864
|
+
validateWavePath(target, join(target, 'tmp', 'units', 'wave'));
|
|
1865
|
+
}
|
|
1866
|
+
catch {
|
|
1867
|
+
return directory;
|
|
1868
|
+
}
|
|
1852
1869
|
const ignored = spawnSync('git', ['check-ignore', '-q', 'tmp/units/wave/probe'], {
|
|
1853
1870
|
cwd: target,
|
|
1854
1871
|
encoding: 'utf8',
|
|
1855
1872
|
windowsHide: true,
|
|
1856
1873
|
});
|
|
1857
|
-
return ignored.status === 0
|
|
1858
|
-
? join(target, 'tmp', 'units', 'wave', new Date().toISOString().replace(/[:.]/gu, '-'))
|
|
1859
|
-
: undefined;
|
|
1874
|
+
return ignored.status === 0 ? directory : undefined;
|
|
1860
1875
|
}
|
|
1861
1876
|
/**
|
|
1862
1877
|
* Reads the packages by layer out of the catalog table.
|
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.
|
|
13
|
+
version: "0.0.136",
|
|
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.20",
|
|
106
|
-
"@orkestrel/contract": "^0.0.
|
|
106
|
+
"@orkestrel/contract": "^0.0.24",
|
|
107
107
|
"@orkestrel/emitter": "^0.0.16",
|
|
108
108
|
"@orkestrel/markdown": "^0.0.21",
|
|
109
109
|
"@orkestrel/process": "^0.0.19",
|
|
@@ -115,7 +115,7 @@ var package_default = {
|
|
|
115
115
|
"@orkestrel/guide": "^0.0.31",
|
|
116
116
|
"@orkestrel/html": "^0.0.16",
|
|
117
117
|
"@orkestrel/probe": "^0.0.30",
|
|
118
|
-
"@orkestrel/test": "^0.0.
|
|
118
|
+
"@orkestrel/test": "^0.0.39",
|
|
119
119
|
"@types/node": "^24.19.2",
|
|
120
120
|
"@vitest/browser-playwright": "^5.1.0",
|
|
121
121
|
"oxfmt": "^0.78.0",
|
package/dist/host/AGENTS.md
CHANGED
|
@@ -91,7 +91,7 @@ Within the size, in order:
|
|
|
91
91
|
3. **Implement.** Conform to the types. Place each declaration in its kind file. Update the barrel.
|
|
92
92
|
4. **Test.** Cover happy paths, edge cases, failures, and boundaries with deterministic tests against real implementations. For a defect, record the failing command and count before the fix and the same command green after.
|
|
93
93
|
5. **Consolidate.** Remove duplication, nested functions, and superfluous wrappers without widening the API.
|
|
94
|
-
6. **Document.** After the implementation is final, update the matching guide, comments, and TSDoc in one minimal pass. Before then, write, revise, and review no prose.
|
|
94
|
+
6. **Document.** After the implementation is final, update the matching guide, comments, and TSDoc in one minimal pass: what `tests/guides.test.ts` asserts, plus each sentence the change made false. Before then, write, revise, and review no prose: a brief carries no wording row, a review reports no wording finding, and no fix round opens for wording. A line that states something false is the one exception, and it changes in the round that made it false.
|
|
95
95
|
|
|
96
96
|
Test ladder, narrowest first; stop at the boundary the change size names:
|
|
97
97
|
|
|
@@ -45,7 +45,7 @@ The harness's own engine orchestrates: Claude Fable 5.2 or Claude Opus 5.5 in Cl
|
|
|
45
45
|
|
|
46
46
|
- Name the role and its engine in every dispatch. Reach a role by its own name. When a hosting harness offers both columns, the dispatch names the column each lane runs on.
|
|
47
47
|
- The capability column names the lane a role holds by default and the one a dispatch may assign (`reviewer`: subjective by default, objective when assigned; `orkestrel`: reader).
|
|
48
|
-
- A role holding the subjective lane judges whether the requested shape
|
|
48
|
+
- A role holding the subjective lane judges whether the requested shape is present, names and boundaries are coherent, the work sits at the right layer, each concept earns its place, and the guide matches the code. A role holding the objective lane judges correctness under adverse orderings, what the contracts and installed declarations permit, dependency and range truth, the missing seam or the assertion that cannot fail, and the letter of the rules. A charter points here for both lenses.
|
|
49
49
|
- In a falsify round, where a claim about a name or a comment is no claim, both lanes hold the same claims and differ by posture: the subjective lane drives the subject as a real caller would and reports what that caller meets, and the objective lane tests the contract's letter across adverse orderings.
|
|
50
50
|
- Read the word `lane` by its qualifier: a subjective or an objective lane is the lens a role holds, a writer, runner, or review lane is a unit at work, and the execution lane is the host resource `.agents/skills/orkestrel-parallel/SKILL.md` § Share an execution lane between sessions orders. Read the word `census` the same way: the `map.ts --census` flag counts a term, the `discovery.ts` script lists test collection, `.agents/skills/orkestrel-harden/references/bindings.md` sweeps a binding key, and a class census under § Depth, breadth, and machinery lists one defect class across packages.
|
|
51
51
|
- `planner` also carries the read-only consultation § Engines admits for Claude Fable 5.2, on the engine the dispatch names.
|
|
@@ -135,7 +135,7 @@ The harness's own engine orchestrates: Claude Fable 5.2 or Claude Opus 5.5 in Cl
|
|
|
135
135
|
| large | one independent round: `planner` and `analyst`, same brief, clean contexts, blind to each other | disjoint units in parallel | one `orkestrel-falsify` round on the integrated result | `verifier` tree-wide, once |
|
|
136
136
|
|
|
137
137
|
- Never run a review on a small change. Never run a second design round on the same brief. A design question a repair round opens is its own brief, not a second design round on the campaign's brief.
|
|
138
|
-
- A review judges types, tests, and implementation.
|
|
138
|
+
- A review judges types, tests, and implementation; `AGENTS.md` § Work loop step 6 rules what it reports about wording.
|
|
139
139
|
- When a brief restates a ruling, give the reviewer the ruling's own text beside the brief, and make any disagreement between the two a claim.
|
|
140
140
|
- Before a repair is dispatched, class its remedy as a correction, a design question, or a deferral; a remedy that adds a mechanism (a file operation, a state, a protocol step, or a retry class) is a design question that goes to one `planner` or `analyst` pass carrying measured platform facts.
|
|
141
141
|
- A fix round re-audits the repaired claim only, in a fresh context. After the re-audit's findings are repaired, one closure check reads whether each closed and tests no other claim. A fix that departs from the reviewer's prescription gets one pass by an independent reviewer per § Engines.
|
|
@@ -117,16 +117,25 @@
|
|
|
117
117
|
// that memory, so a long queue of measured tickets costs that much per ticket.
|
|
118
118
|
// - A prune beside a write. A holder that writes a record to an existing key that is past a bound can
|
|
119
119
|
// lose that record to another holder's prune, which removes the key with the record in it.
|
|
120
|
-
// - An unreaped member.
|
|
121
|
-
//
|
|
120
|
+
// - An unreaped member. A group reads as ended when two readings of the process table at `/proc`,
|
|
121
|
+
// one after the other, show the same threads of its members and every one exited (`Z` or `X`),
|
|
122
|
+
// whether or not the host's init has reaped them; a member whose main thread exited while another
|
|
123
|
+
// thread runs reads as present. An empty reading reads as present, and so does any reading that
|
|
124
|
+
// cannot list the table, a member's threads, or an entry's `stat` for a reason other than the
|
|
125
|
+
// entry being gone. Three cases are outside the reading: a process that joins the group from
|
|
126
|
+
// outside it through `setpgid` during the second listing; a chain of members that each fork,
|
|
127
|
+
// exit, and are reaped between the listing and the read, in both readings; and a member the host
|
|
128
|
+
// hides from `/proc` entirely (`hidepid=2`). On a host without that table, a killed member its
|
|
129
|
+
// parent has not reaped keeps reading as present, and the lane exits 70 and stays held.
|
|
122
130
|
// - Listing completeness. No probe proves that a listing returns every stable entry. The design takes
|
|
123
131
|
// it from the documented directory-read contract.
|
|
124
132
|
// - Queue scope. The queue is one per user account per host. A wiped root, a second account, or a
|
|
125
133
|
// `--root` outside a proof gives a second queue that does not see the first.
|
|
126
134
|
// - A denied root. A sandbox that refuses the root or the endpoint exits 75; no sandboxed bench exec
|
|
127
135
|
// has run this script.
|
|
128
|
-
// - Linux.
|
|
129
|
-
//
|
|
136
|
+
// - Linux. The socket file, the process group, and the zombie reading were read on a Linux container
|
|
137
|
+
// on 2026-11-14 (Node 22.23.5, an init that does not reap as a child ends); the signal handling is
|
|
138
|
+
// unread on Linux.
|
|
130
139
|
// Migration stop: a second queue does not see the first, so while a host's sessions run another
|
|
131
140
|
// serializer, no caller moves. After a scaffold release carries this script and no command runs on the
|
|
132
141
|
// host, move every caller in one step and delete the serializer this replaces.
|
|
@@ -247,6 +256,15 @@ export const TICKET_PATTERN = /^(\d+)\.ticket$/u
|
|
|
247
256
|
/** Matches one snapshot row: process id, parent id, and creation time in milliseconds. */
|
|
248
257
|
export const ROW_PATTERN = /^(\d+) (\d+) (\d+)$/u
|
|
249
258
|
|
|
259
|
+
/** Names the directory where a Linux host publishes its process table. */
|
|
260
|
+
export const PROCESS_TABLE = '/proc'
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Lists the process-table states of a member that has exited and that its parent has not reaped:
|
|
264
|
+
* `Z` for a zombie, and `X` for a process the kernel is releasing.
|
|
265
|
+
*/
|
|
266
|
+
export const ENDED_STATES: readonly string[] = ['Z', 'X']
|
|
267
|
+
|
|
250
268
|
/** Lists the signals that interrupt a lane on a host that delivers them. */
|
|
251
269
|
export const STOP_SIGNALS: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP']
|
|
252
270
|
|
|
@@ -607,6 +625,18 @@ export type Turn =
|
|
|
607
625
|
}
|
|
608
626
|
| { readonly state: 'refused'; readonly reason: string }
|
|
609
627
|
|
|
628
|
+
/** Describes one process-table entry the group reading needs: its state and its process group. */
|
|
629
|
+
export interface Stat {
|
|
630
|
+
readonly state: string
|
|
631
|
+
readonly group: number
|
|
632
|
+
}
|
|
633
|
+
|
|
634
|
+
/** Describes one thread of a group member: its `<pid>/<tid>` key and its process-table state. */
|
|
635
|
+
export interface Task {
|
|
636
|
+
readonly id: string
|
|
637
|
+
readonly state: string
|
|
638
|
+
}
|
|
639
|
+
|
|
610
640
|
/** Describes what a sweep confirmed: whether the tree reads as gone, and the members it left. */
|
|
611
641
|
export interface Sweep {
|
|
612
642
|
readonly gone: boolean
|
|
@@ -1972,18 +2002,181 @@ export function selectMembers<T extends Row>(
|
|
|
1972
2002
|
}
|
|
1973
2003
|
|
|
1974
2004
|
/**
|
|
1975
|
-
*
|
|
2005
|
+
* Parses one process-table `stat` line into its state and its process group.
|
|
2006
|
+
*
|
|
2007
|
+
* @remarks
|
|
2008
|
+
* The command name sits in parentheses and can hold spaces and parentheses itself, so the fields
|
|
2009
|
+
* are read after the last `)`: the state, the parent id, then the group id.
|
|
2010
|
+
*
|
|
2011
|
+
* @param text - The content of `/proc/<pid>/stat`.
|
|
2012
|
+
* @returns The state and the group, or undefined when the text does not have that form.
|
|
2013
|
+
*/
|
|
2014
|
+
export function parseStat(text: string): Stat | undefined {
|
|
2015
|
+
const close = text.lastIndexOf(')')
|
|
2016
|
+
if (close === -1) return undefined
|
|
2017
|
+
const [state, , group] = text.slice(close + 2).split(' ')
|
|
2018
|
+
return state === undefined || state === '' || group === undefined || !/^\d+$/u.test(group)
|
|
2019
|
+
? undefined
|
|
2020
|
+
: { state, group: Number(group) }
|
|
2021
|
+
}
|
|
2022
|
+
|
|
2023
|
+
/**
|
|
2024
|
+
* Lists the entries of one process-table directory.
|
|
2025
|
+
*
|
|
2026
|
+
* @param path - The directory.
|
|
2027
|
+
* @returns The entry names, or undefined when the listing fails.
|
|
2028
|
+
*/
|
|
2029
|
+
export function readListing(path: string): readonly string[] | undefined {
|
|
2030
|
+
try {
|
|
2031
|
+
return readdirSync(path)
|
|
2032
|
+
} catch {
|
|
2033
|
+
return undefined
|
|
2034
|
+
}
|
|
2035
|
+
}
|
|
2036
|
+
|
|
2037
|
+
/**
|
|
2038
|
+
* Reads one thread's state from its own process-table entry.
|
|
1976
2039
|
*
|
|
2040
|
+
* @param pid - The process id, as its process-table entry names it.
|
|
2041
|
+
* @param tid - The thread id, as the process's `task` listing names it.
|
|
2042
|
+
* @param table - The process table's root. Default: {@link PROCESS_TABLE}.
|
|
2043
|
+
* @returns The task keyed `<pid>/<tid>`, or undefined when its `stat` cannot be read or parsed.
|
|
2044
|
+
*/
|
|
2045
|
+
export function readTask(pid: string, tid: string, table = PROCESS_TABLE): Task | undefined {
|
|
2046
|
+
try {
|
|
2047
|
+
const stat = parseStat(readFileSync(join(table, pid, 'task', tid, 'stat'), 'utf8'))
|
|
2048
|
+
return stat === undefined ? undefined : { id: `${pid}/${tid}`, state: stat.state }
|
|
2049
|
+
} catch {
|
|
2050
|
+
return undefined
|
|
2051
|
+
}
|
|
2052
|
+
}
|
|
2053
|
+
|
|
2054
|
+
/**
|
|
2055
|
+
* Reads the state of every thread of one process from the process table.
|
|
2056
|
+
*
|
|
2057
|
+
* @param pid - The process id, as its process-table entry names it.
|
|
2058
|
+
* @returns One task per thread, keyed `<pid>/<tid>`, or undefined when the `task` listing fails,
|
|
2059
|
+
* lists no thread, or holds a thread whose `stat` cannot be read: what the reading cannot read
|
|
2060
|
+
* counts as present.
|
|
2061
|
+
* @param table - The process table's root. Default: {@link PROCESS_TABLE}.
|
|
2062
|
+
*/
|
|
2063
|
+
export function readThreads(pid: string, table = PROCESS_TABLE): readonly Task[] | undefined {
|
|
2064
|
+
const tids = readListing(join(table, pid, 'task'))
|
|
2065
|
+
if (tids === undefined || tids.length === 0) return undefined
|
|
2066
|
+
const tasks = tids.map((tid) => readTask(pid, tid, table))
|
|
2067
|
+
return tasks.includes(undefined)
|
|
2068
|
+
? undefined
|
|
2069
|
+
: tasks.flatMap((task) => (task === undefined ? [] : [task]))
|
|
2070
|
+
}
|
|
2071
|
+
|
|
2072
|
+
/**
|
|
2073
|
+
* Reads the threads of one process-table entry when it belongs to a process group.
|
|
2074
|
+
*
|
|
2075
|
+
* @param name - The process id, as the process-table listing names it.
|
|
1977
2076
|
* @param group - The group id.
|
|
1978
|
-
* @returns The
|
|
2077
|
+
* @returns The entry's threads when it belongs to the group, none when it belongs to another group
|
|
2078
|
+
* or its `stat` is gone (`ENOENT`, a process that ended), or undefined when its `stat` cannot be
|
|
2079
|
+
* read for any other reason or cannot be parsed, or its threads cannot be read.
|
|
2080
|
+
* @param table - The process table's root. Default: {@link PROCESS_TABLE}.
|
|
1979
2081
|
*/
|
|
1980
|
-
export function
|
|
2082
|
+
export function readMember(
|
|
2083
|
+
name: string,
|
|
2084
|
+
group: number,
|
|
2085
|
+
table = PROCESS_TABLE,
|
|
2086
|
+
): readonly Task[] | undefined {
|
|
2087
|
+
try {
|
|
2088
|
+
const stat = parseStat(readFileSync(join(table, name, 'stat'), 'utf8'))
|
|
2089
|
+
if (stat === undefined) return undefined
|
|
2090
|
+
return stat.group === group ? readThreads(name, table) : []
|
|
2091
|
+
} catch (error) {
|
|
2092
|
+
return readCode(error) === 'ENOENT' ? [] : undefined
|
|
2093
|
+
}
|
|
2094
|
+
}
|
|
2095
|
+
|
|
2096
|
+
/**
|
|
2097
|
+
* Reads every thread of every member of a process group from the process table.
|
|
2098
|
+
*
|
|
2099
|
+
* @param group - The group id.
|
|
2100
|
+
* @returns One task per thread of each member, or undefined when the host publishes no process
|
|
2101
|
+
* table, the table cannot be listed, or any entry cannot be read; a process whose `stat` is gone
|
|
2102
|
+
* is skipped.
|
|
2103
|
+
* @param table - The process table's root. Default: {@link PROCESS_TABLE}.
|
|
2104
|
+
*/
|
|
2105
|
+
export function readTasks(group: number, table = PROCESS_TABLE): readonly Task[] | undefined {
|
|
2106
|
+
if (!existsSync(join(table, 'self', 'stat'))) return undefined
|
|
2107
|
+
const names = readListing(table)
|
|
2108
|
+
if (names === undefined) return undefined
|
|
2109
|
+
const members = names
|
|
2110
|
+
.filter((name) => /^\d+$/u.test(name))
|
|
2111
|
+
.map((name) => readMember(name, group, table))
|
|
2112
|
+
return members.includes(undefined)
|
|
2113
|
+
? undefined
|
|
2114
|
+
: members.flatMap((member) => (member === undefined ? [] : member))
|
|
2115
|
+
}
|
|
2116
|
+
|
|
2117
|
+
/**
|
|
2118
|
+
* Checks whether two readings of one group show the same threads, every one of them exited.
|
|
2119
|
+
*
|
|
2120
|
+
* @remarks
|
|
2121
|
+
* A thread read as exited cannot start another process or thread after that read, so every process
|
|
2122
|
+
* that joined the group and every thread created before the first reading finished exists when the
|
|
2123
|
+
* second listing starts. A second reading of the same tasks therefore leaves none of them out, and a
|
|
2124
|
+
* member that forked between its listing and its read shows up as a task the first reading lacks.
|
|
2125
|
+
* An empty reading reads as not ended, because the probe signal reached a member the table did not
|
|
2126
|
+
* show, as a table from another PID namespace does.
|
|
2127
|
+
*
|
|
2128
|
+
* @param first - The first reading.
|
|
2129
|
+
* @param second - The reading taken after the first finished.
|
|
2130
|
+
* @returns True if both readings hold at least one task, list the same task ids, and show every
|
|
2131
|
+
* task as {@link ENDED_STATES}; false otherwise.
|
|
2132
|
+
*/
|
|
2133
|
+
export function matchesEnded(first: readonly Task[], second: readonly Task[]): boolean {
|
|
2134
|
+
return (
|
|
2135
|
+
first.length > 0 &&
|
|
2136
|
+
first
|
|
2137
|
+
.map((task) => task.id)
|
|
2138
|
+
.toSorted()
|
|
2139
|
+
.join(' ') ===
|
|
2140
|
+
second
|
|
2141
|
+
.map((task) => task.id)
|
|
2142
|
+
.toSorted()
|
|
2143
|
+
.join(' ') &&
|
|
2144
|
+
[...first, ...second].every((task) => ENDED_STATES.includes(task.state))
|
|
2145
|
+
)
|
|
2146
|
+
}
|
|
2147
|
+
|
|
2148
|
+
/**
|
|
2149
|
+
* Reads whether a process group still has a member that has not exited.
|
|
2150
|
+
*
|
|
2151
|
+
* @remarks
|
|
2152
|
+
* A signal reaches a zombie, so a group whose members have all exited still answers the probe
|
|
2153
|
+
* signal until their parent reaps them, which an init that does not reap as a child ends leaves
|
|
2154
|
+
* for later. Where the host publishes a process table, a group reads as ended when two readings
|
|
2155
|
+
* taken one after the other show the same threads of its members, every one {@link ENDED_STATES},
|
|
2156
|
+
* per {@link matchesEnded}. A zombie whose threads have all exited holds no CPU, memory, or file
|
|
2157
|
+
* handle; a process whose main thread exited while another thread runs shows `Z` for itself and
|
|
2158
|
+
* reads as present through that thread. A host without that table, and a reading that cannot read
|
|
2159
|
+
* part of it, read such a group as present.
|
|
2160
|
+
*
|
|
2161
|
+
* @param group - The group id.
|
|
2162
|
+
* @param read - Takes one reading of the group's threads; undefined means the reading could not
|
|
2163
|
+
* read the table. Default: {@link readTasks}.
|
|
2164
|
+
* @returns The group id while the host reports a member that has not exited or the reading
|
|
2165
|
+
* cannot read the table; empty when it reports none.
|
|
2166
|
+
*/
|
|
2167
|
+
export function readGroup(
|
|
2168
|
+
group: number,
|
|
2169
|
+
read: (group: number) => readonly Task[] | undefined = readTasks,
|
|
2170
|
+
): readonly number[] {
|
|
1981
2171
|
try {
|
|
1982
2172
|
process.kill(-group, 0)
|
|
1983
|
-
return [group]
|
|
1984
2173
|
} catch (error) {
|
|
1985
2174
|
return readCode(error) === 'ESRCH' ? [] : [group]
|
|
1986
2175
|
}
|
|
2176
|
+
const first = read(group)
|
|
2177
|
+
if (first === undefined) return [group]
|
|
2178
|
+
const second = read(group)
|
|
2179
|
+
return second !== undefined && matchesEnded(first, second) ? [] : [group]
|
|
1987
2180
|
}
|
|
1988
2181
|
|
|
1989
2182
|
/**
|
|
@@ -988,7 +988,8 @@ export function refuseLocalSpecs(runner: Runner, step: string): boolean {
|
|
|
988
988
|
*
|
|
989
989
|
* @param runner - The visit's state.
|
|
990
990
|
* @returns The first refusal, or undefined when the lock is tracked and clean, the manifest holds no
|
|
991
|
-
* local spec or workspace, `tmp
|
|
991
|
+
* local spec or workspace, `tmp/units/wave` crosses no link inside the target, `tmp/` is ignored,
|
|
992
|
+
* and the target is its work tree's root.
|
|
992
993
|
*/
|
|
993
994
|
export function readRegenerationRefusal(runner: Runner): string | undefined {
|
|
994
995
|
if (
|
|
@@ -1015,6 +1016,12 @@ export function readRegenerationRefusal(runner: Runner): string | undefined {
|
|
|
1015
1016
|
if (specs.length > 0)
|
|
1016
1017
|
return `local dependency specs: ${specs.map(([path, spec]) => `${path}: ${spec}`).join(', ')}`
|
|
1017
1018
|
if (manifest !== undefined && 'workspaces' in manifest) return 'the manifest declares workspaces'
|
|
1019
|
+
// Git refuses a pathspec beyond a link with exit 128, which reads as an unignored `tmp/`.
|
|
1020
|
+
try {
|
|
1021
|
+
validateWavePath(runner.target, join(runner.target, 'tmp', 'units', 'wave'))
|
|
1022
|
+
} catch (error) {
|
|
1023
|
+
return error instanceof Error ? error.message : String(error)
|
|
1024
|
+
}
|
|
1018
1025
|
if (
|
|
1019
1026
|
runStep(
|
|
1020
1027
|
runner,
|
|
@@ -2451,7 +2458,8 @@ export function runVisit(values: Arguments['values']): Visit | undefined {
|
|
|
2451
2458
|
*
|
|
2452
2459
|
* @param target - The target directory.
|
|
2453
2460
|
* @returns A new stamped directory under the target's `tmp/units/wave/` when the target is inside a
|
|
2454
|
-
* work tree that ignores `tmp/`,
|
|
2461
|
+
* work tree that ignores `tmp/`, or when that path crosses a link, which the caller's link check
|
|
2462
|
+
* refuses; else undefined.
|
|
2455
2463
|
*/
|
|
2456
2464
|
export function readJournalDirectory(target: string): string | undefined {
|
|
2457
2465
|
const inside = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
|
|
@@ -2460,14 +2468,25 @@ export function readJournalDirectory(target: string): string | undefined {
|
|
|
2460
2468
|
windowsHide: true,
|
|
2461
2469
|
})
|
|
2462
2470
|
if (inside.status !== 0 || inside.stdout.trim() !== 'true') return undefined
|
|
2471
|
+
const directory = join(
|
|
2472
|
+
target,
|
|
2473
|
+
'tmp',
|
|
2474
|
+
'units',
|
|
2475
|
+
'wave',
|
|
2476
|
+
new Date().toISOString().replace(/[:.]/gu, '-'),
|
|
2477
|
+
)
|
|
2478
|
+
// Git refuses a pathspec beyond a link with exit 128, which reads as an unignored `tmp/`.
|
|
2479
|
+
try {
|
|
2480
|
+
validateWavePath(target, join(target, 'tmp', 'units', 'wave'))
|
|
2481
|
+
} catch {
|
|
2482
|
+
return directory
|
|
2483
|
+
}
|
|
2463
2484
|
const ignored = spawnSync('git', ['check-ignore', '-q', 'tmp/units/wave/probe'], {
|
|
2464
2485
|
cwd: target,
|
|
2465
2486
|
encoding: 'utf8',
|
|
2466
2487
|
windowsHide: true,
|
|
2467
2488
|
})
|
|
2468
|
-
return ignored.status === 0
|
|
2469
|
-
? join(target, 'tmp', 'units', 'wave', new Date().toISOString().replace(/[:.]/gu, '-'))
|
|
2470
|
-
: undefined
|
|
2489
|
+
return ignored.status === 0 ? directory : undefined
|
|
2471
2490
|
}
|
|
2472
2491
|
|
|
2473
2492
|
/**
|