@orkestrel/scaffold 0.0.135 → 0.0.137

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +167 -4
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +20 -5
  3. package/dist/bin/main.js +12 -12
  4. package/dist/host/AGENTS.md +1 -1
  5. package/dist/host/agents/orchestration.md +2 -2
  6. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +201 -8
  7. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +24 -5
  8. package/dist/host/claude/agents/orkestrel.md +52 -52
  9. package/dist/host/claude/agents/reviewer.md +1 -1
  10. package/dist/host/claude/rules/documentation.md +1 -1
  11. package/dist/host/claude/rules/patterns.md +2 -2
  12. package/dist/host/claude/rules/workspace.md +9 -4
  13. package/dist/host/configs/helpers.ts +21 -6
  14. package/dist/host/guides/agent.md +3 -1
  15. package/dist/host/guides/brief.md +16 -16
  16. package/dist/host/guides/browser.md +1 -1
  17. package/dist/host/guides/contract.md +198 -163
  18. package/dist/host/guides/database.md +773 -310
  19. package/dist/host/guides/indexeddb.md +80 -66
  20. package/dist/host/guides/reason.md +1 -1
  21. package/dist/host/guides/relation.md +56 -32
  22. package/dist/host/guides/scaffold.md +8 -2
  23. package/dist/host/guides/sqlite.md +44 -23
  24. package/dist/host/guides/test.md +7 -3
  25. package/dist/host/guides/tool.md +2 -1
  26. package/dist/host/guides/toolbox.md +44 -44
  27. package/dist/host/guides/workflow.md +2 -2
  28. package/dist/host/manifest.json +26 -26
  29. package/dist/host/tests/config.test.ts +71 -3
  30. package/dist/src/core/index.cjs +112 -35
  31. package/dist/src/core/index.cjs.map +1 -1
  32. package/dist/src/core/index.d.cts +31 -5
  33. package/dist/src/core/index.d.ts +31 -5
  34. package/dist/src/core/index.js +112 -36
  35. package/dist/src/core/index.js.map +1 -1
  36. package/package.json +12 -12
@@ -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
- * Reads whether a process group still has a member.
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 The group id while the host reports the group; empty when it reports none.
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 readGroup(group) {
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/` is ignored, and the target is its work tree's root.
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/`, else undefined.
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.135",
13
+ version: "0.0.137",
14
14
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
15
15
  keywords: [
16
16
  "audit",
@@ -102,20 +102,20 @@ var package_default = {
102
102
  "prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:templates && npm run test:distribution -- --mode release"
103
103
  },
104
104
  dependencies: {
105
- "@orkestrel/console": "^0.0.20",
106
- "@orkestrel/contract": "^0.0.23",
107
- "@orkestrel/emitter": "^0.0.16",
108
- "@orkestrel/markdown": "^0.0.21",
109
- "@orkestrel/process": "^0.0.19",
110
- "@orkestrel/template": "^0.0.14"
105
+ "@orkestrel/console": "^0.0.21",
106
+ "@orkestrel/contract": "^0.0.24",
107
+ "@orkestrel/emitter": "^0.0.17",
108
+ "@orkestrel/markdown": "^0.0.22",
109
+ "@orkestrel/process": "^0.0.20",
110
+ "@orkestrel/template": "^0.0.15"
111
111
  },
112
112
  devDependencies: {
113
113
  "@microsoft/api-extractor": "^7.60.1",
114
- "@orkestrel/browser": "^0.0.33",
115
- "@orkestrel/guide": "^0.0.31",
116
- "@orkestrel/html": "^0.0.16",
117
- "@orkestrel/probe": "^0.0.30",
118
- "@orkestrel/test": "^0.0.38",
114
+ "@orkestrel/browser": "^0.0.34",
115
+ "@orkestrel/guide": "^0.0.32",
116
+ "@orkestrel/html": "^0.0.17",
117
+ "@orkestrel/probe": "^0.0.31",
118
+ "@orkestrel/test": "^0.0.40",
119
119
  "@types/node": "^24.19.2",
120
120
  "@vitest/browser-playwright": "^5.1.0",
121
121
  "oxfmt": "^0.78.0",
@@ -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 and voice are 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.
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. It reports comment, TSDoc, or guide wording only where the text contradicts the final behavior, and no fix round opens for prose alone.
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. On a host whose init does not reap, a killed member can keep reading as
121
- // present. The lane exits 70 and stays held.
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. Every non-Windows branch is unread on this host and needs a Linux run: the socket file, the
129
- // process group, and the signal handling.
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
- * Reads whether a process group still has a member.
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 group id while the host reports the group; empty when it reports none.
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 readGroup(group: number): readonly number[] {
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/` is ignored, and the target is its work tree's root.
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/`, else undefined.
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
  /**