@awebai/oats 0.61.0 → 0.63.0

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 (90) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +27 -12
  3. package/docs/capabilities.md +1 -1
  4. package/docs/desktop-cli-api.md +30 -2
  5. package/docs/execution-targets.md +89 -4
  6. package/docs/implementation.md +2 -1
  7. package/docs/named-test-runs.md +382 -0
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-lane.md +13 -0
  11. package/docs/release-notes/v0.62.0.md +223 -0
  12. package/docs/release-notes/v0.63.0.md +135 -0
  13. package/docs/souls-and-instances.md +6 -1
  14. package/docs/upgrading.md +135 -11
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +73 -23
  17. package/lib/doctor-capture.mjs +35 -0
  18. package/lib/session-viewer.mjs +86 -7
  19. package/lib/tree-copy.mjs +188 -7
  20. package/package-catalog.json +1 -1
  21. package/package.json +1 -1
  22. package/packages/client/cli-locator.mjs +2 -2
  23. package/packages/record/README.md +87 -13
  24. package/packages/record/bin/capture-hook.mjs +8 -0
  25. package/packages/record/bin/capture.mjs +200 -139
  26. package/packages/record/bin/recall.mjs +8 -3
  27. package/packages/record/bin/setup.mjs +116 -225
  28. package/packages/record/bin/turn-record.mjs +2 -2
  29. package/packages/record/docs/capture-service.md +1527 -28
  30. package/packages/record/docs/capture-status.schema.json +429 -12
  31. package/packages/record/lib/capture-admission.mjs +82 -0
  32. package/packages/record/lib/capture-aw-unit.mjs +137 -0
  33. package/packages/record/lib/capture-aw.mjs +31 -12
  34. package/packages/record/lib/capture-budget.mjs +31 -0
  35. package/packages/record/lib/capture-cc.mjs +39 -6
  36. package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
  37. package/packages/record/lib/capture-cleanup-work.mjs +77 -0
  38. package/packages/record/lib/capture-command-operation.mjs +37 -0
  39. package/packages/record/lib/capture-command-output.mjs +62 -0
  40. package/packages/record/lib/capture-command-worker.mjs +6 -0
  41. package/packages/record/lib/capture-command.mjs +65 -0
  42. package/packages/record/lib/capture-completion.mjs +152 -0
  43. package/packages/record/lib/capture-context.mjs +50 -0
  44. package/packages/record/lib/capture-default-roots.mjs +30 -0
  45. package/packages/record/lib/capture-discovery.mjs +114 -0
  46. package/packages/record/lib/capture-failures.mjs +45 -0
  47. package/packages/record/lib/capture-health-doctor.mjs +13 -0
  48. package/packages/record/lib/capture-health-installation.mjs +117 -0
  49. package/packages/record/lib/capture-health.mjs +116 -0
  50. package/packages/record/lib/capture-hook-ownership.mjs +58 -0
  51. package/packages/record/lib/capture-hook-runner.mjs +17 -0
  52. package/packages/record/lib/capture-hook.mjs +26 -0
  53. package/packages/record/lib/capture-index-inventory.mjs +205 -0
  54. package/packages/record/lib/capture-index-outcomes.mjs +113 -0
  55. package/packages/record/lib/capture-index-reset.mjs +110 -0
  56. package/packages/record/lib/capture-index-work.mjs +77 -0
  57. package/packages/record/lib/capture-issue-preparation.mjs +73 -0
  58. package/packages/record/lib/capture-issues.mjs +15 -2
  59. package/packages/record/lib/capture-lock.mjs +137 -17
  60. package/packages/record/lib/capture-native-unit.mjs +322 -0
  61. package/packages/record/lib/capture-pass.mjs +116 -0
  62. package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
  63. package/packages/record/lib/capture-retained-scratch.mjs +213 -0
  64. package/packages/record/lib/capture-retry.mjs +102 -0
  65. package/packages/record/lib/capture-run.mjs +125 -0
  66. package/packages/record/lib/capture-scratch.mjs +12 -3
  67. package/packages/record/lib/capture-service-definition.mjs +104 -0
  68. package/packages/record/lib/capture-service-install.mjs +362 -0
  69. package/packages/record/lib/capture-service-ownership.mjs +137 -0
  70. package/packages/record/lib/capture-service-runner.mjs +18 -0
  71. package/packages/record/lib/capture-small-snapshot.mjs +85 -0
  72. package/packages/record/lib/capture-source-discovery.mjs +319 -0
  73. package/packages/record/lib/capture-source-queue.mjs +199 -0
  74. package/packages/record/lib/capture-source-work.mjs +85 -0
  75. package/packages/record/lib/capture-state.mjs +16 -71
  76. package/packages/record/lib/capture-status.mjs +171 -0
  77. package/packages/record/lib/capture-supervisor.mjs +136 -0
  78. package/packages/record/lib/capture-watch.mjs +32 -0
  79. package/packages/record/lib/capture-work-session.mjs +241 -0
  80. package/packages/record/lib/capture-worker.mjs +74 -0
  81. package/packages/record/lib/derived-state.mjs +58 -17
  82. package/packages/record/lib/file-lines.mjs +22 -6
  83. package/packages/record/lib/formats.mjs +4 -3
  84. package/packages/record/lib/index-capture.mjs +97 -0
  85. package/packages/record/lib/index-db.mjs +121 -66
  86. package/packages/record/lib/index-reset.mjs +19 -0
  87. package/packages/record/lib/store.mjs +46 -14
  88. package/packages/record/lib/transcript-prefix.mjs +125 -0
  89. package/skills/oats-getting-started/SKILL.md +1 -1
  90. package/docs/macos-test-runs.md +0 -246
@@ -1,13 +1,12 @@
1
- // Shared capture status and operator recovery. Service supervision later fills
2
- // policy/run evidence; null means no such evidence has been supplied.
1
+ // Shared capture status and operator recovery. Null policy/run fields retain
2
+ // their algorithm-phase meaning: no such evidence has been supplied.
3
3
  import { randomUUID } from "node:crypto";
4
- import { closeSync, constants, fstatSync, fsyncSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
5
- import { join } from "node:path";
6
4
  import { DerivedState, invalidateLegacyMaps } from "./derived-state.mjs";
7
- import { readCurrentIssueBacklog, readIssueBacklog } from "./capture-issues.mjs";
5
+ import { readIssueBacklog } from "./capture-issues.mjs";
6
+ import { emptyCaptureStatus, readCaptureStatus, persistCaptureStatus } from "./capture-status.mjs";
8
7
 
9
8
  export const CAPTURE_SOURCES = ["aw", "cc", "pi", "codex"];
10
- export const SET_ASIDE_REMEDY = "Restore the captured prefix and run capture --retry-set-aside; or add the source to <root>/ignore (later turns from that session will not be captured). Retry revalidates; it never authorizes a changed prefix.";
9
+ export { captureHealth, SET_ASIDE_REMEDY } from "./capture-health.mjs";
11
10
 
12
11
  // Caller owns the root capture lock. One transaction persists every selected
13
12
  // generation; a missing source cursor cannot erase this rescan request.
@@ -26,7 +25,13 @@ export function retrySetAside(root) {
26
25
  const state = new DerivedState(root);
27
26
  try {
28
27
  state.transaction(() => {
29
- for (const { key, value } of state.entries("set-aside")) state.set("set-aside", key, { ...value, retry: true });
28
+ for (const { key, value } of state.entries("set-aside")) {
29
+ // A command's explicit retry invalidates an older staged proof once.
30
+ // Keep this private generation after the issue resolves, so subsequent
31
+ // workers do not restart merely because the active row was removed.
32
+ state.set("source-retry", key, randomUUID());
33
+ state.set("set-aside", key, { ...value, retry: true });
34
+ }
30
35
  });
31
36
  } finally { state.close(); }
32
37
  }
@@ -37,69 +42,9 @@ export function writeCaptureStatus(root, { pending = false } = {}) {
37
42
  try {
38
43
  backlog = readIssueBacklog(state.db, { pending });
39
44
  } finally { state.close(); }
40
- const status = { schemaVersion: 1, policy: null, lastRun: null, lastSuccess: null, lastFailure: null, lastProgressAt: null, backlog };
41
- const path = join(root, "capture-status.json"), temp = `${path}.${randomUUID()}.tmp`;
42
- let fd;
43
- try {
44
- fd = openSync(temp, "wx", 0o600);
45
- writeFileSync(fd, JSON.stringify(status) + "\n"); fsyncSync(fd); closeSync(fd); fd = undefined;
46
- renameSync(temp, path);
47
- } finally {
48
- if (fd !== undefined) closeSync(fd);
49
- try { unlinkSync(temp); } catch (err) { if (err.code !== "ENOENT") throw err; }
50
- }
51
- return status;
45
+ // Exact receipt callers update issue evidence, never erase prior worker run
46
+ // facts or turn their unbounded operation into a bounded-service success.
47
+ const prior = readCaptureStatus(root) ?? emptyCaptureStatus(backlog);
48
+ return persistCaptureStatus(root, { ...prior, backlog });
52
49
  }
53
50
 
54
- function validStatus(status) {
55
- const b = status?.backlog;
56
- return status?.schemaVersion === 1 && status.policy === null && status.lastRun === null && status.lastSuccess === null &&
57
- status.lastFailure === null && status.lastProgressAt === null && typeof b?.pending === "boolean" &&
58
- Number.isSafeInteger(b.setAsideCount) && b.setAsideCount >= 0 && Array.isArray(b.setAside) && b.setAside.length <= 100 &&
59
- b.setAside.length === Math.min(b.setAsideCount, 100) && b.truncated === (b.setAsideCount > 100) &&
60
- b.setAside.every(e => CAPTURE_SOURCES.includes(e.source) && typeof e.path === "string" && typeof e.reason === "string" &&
61
- Number.isSafeInteger(e.offset) && e.offset >= 0 && (e.line === undefined || Number.isSafeInteger(e.line) && e.line > 0));
62
- }
63
-
64
- // Read-only, including a never-installed/absent root: no writable DB construction,
65
- // directory creation, manager query, index rebuild or capture.
66
- export function captureHealth(root) {
67
- const path = join(root, "capture-status.json");
68
- let status = { lastRun: null, lastSuccess: null, lastFailure: null,
69
- backlog: { pending: false, setAsideCount: 0, setAside: [], truncated: false } };
70
- const rows = [];
71
- try {
72
- const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
73
- let text;
74
- try {
75
- const stat = fstatSync(fd);
76
- if (!stat.isFile()) throw new Error("status is not a regular file");
77
- const limit = 1024 * 1024;
78
- if (stat.size > limit) throw new Error("status exceeds 1 MiB");
79
- const bytes = Buffer.alloc(limit + 1);
80
- let size = 0;
81
- while (size < bytes.length) {
82
- const count = readSync(fd, bytes, size, bytes.length - size, size);
83
- if (!count) break;
84
- size += count;
85
- }
86
- if (size > limit) throw new Error("status exceeds 1 MiB");
87
- text = bytes.toString("utf8", 0, size);
88
- } finally { closeSync(fd); }
89
- const parsed = JSON.parse(text);
90
- if (!validStatus(parsed)) throw new Error("unsupported or malformed status");
91
- status = parsed;
92
- } catch (err) {
93
- if (err.code !== "ENOENT") rows.push({ code: "capture-status-invalid", message: `Cannot read capture status at ${path}: ${err.message}` });
94
- }
95
- let backlog;
96
- try {
97
- backlog = readCurrentIssueBacklog(root);
98
- if (!backlog && status.backlog.setAsideCount) throw new Error("capture.db is missing but the last command reported active set-aside inputs");
99
- } catch (err) { throw new Error(`Cannot read current capture issues at ${join(root, "index", "capture.db")}: ${err.message}`, { cause: err }); }
100
- backlog ??= { pending: false, setAsideCount: 0, setAside: [], truncated: false };
101
- if (backlog.setAsideCount) rows.push({ code: "capture-input-set-aside", message:
102
- `${backlog.setAsideCount} capture inputs set aside. ${SET_ASIDE_REMEDY.replace("<root>", root)}` });
103
- return { schemaVersion: 1, status: rows.length ? "warning" : "ok", rows,
104
- lastRun: status.lastRun, lastSuccess: status.lastSuccess, lastFailure: status.lastFailure, backlog };
105
- }
@@ -0,0 +1,171 @@
1
+ // Shared status format and atomic file I/O. This module neither creates a run
2
+ // nor infers success from counters. Only admitted command workers publish run
3
+ // facts; exact receipt commands may refresh backlog while retaining history.
4
+ import { randomUUID } from "node:crypto";
5
+ import { closeSync, constants, fstatSync, fsyncSync, openSync, readdirSync, readSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
6
+ import { join } from "node:path";
7
+ import { CAPTURE_POLICY } from "./capture-budget.mjs";
8
+ import { validFailureBacklog } from "./capture-failures.mjs";
9
+
10
+ export const CAPTURE_COUNT_FIELDS = Object.freeze(["filesVisited", "bytesCommitted", "turnsAppended", "turnsIndexed",
11
+ "inputsPending", "inputsSetAside", "inputsFailed", "inputsIgnored"]);
12
+ export const emptyCaptureCounts = () => Object.fromEntries(CAPTURE_COUNT_FIELDS.map(key => [key, 0]));
13
+ const triggers = new Set(["service", "hook", "setup", "manual", "watch"]);
14
+ const reasons = new Set(["deadline", "rss", "heap", "interrupted", "input", "io"]);
15
+ const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
16
+ const integer = value => Number.isSafeInteger(value) && value >= 0;
17
+ const exact = (value, required, optional = []) => object(value) && required.every(key => Object.hasOwn(value, key)) &&
18
+ Object.keys(value).every(key => required.includes(key) || optional.includes(key));
19
+ const stamp = (value, now) => typeof value === "string" && Number.isFinite(Date.parse(value)) &&
20
+ new Date(value).toISOString() === value && Date.parse(value) <= now;
21
+ const peak = value => value === null || integer(value);
22
+ const counts = value => exact(value, CAPTURE_COUNT_FIELDS) && CAPTURE_COUNT_FIELDS.every(key => integer(value[key]));
23
+ const reclaimed = (value, now) => exact(value, ["pid", "startedAt"]) && Number.isSafeInteger(value.pid) && value.pid > 0 &&
24
+ stamp(value.startedAt, now);
25
+ const identityKeys = ["id", "trigger", "pid", "startedAt"];
26
+ const summaryKeys = [...identityKeys, "finishedAt", "counts", "peakRssBytes"];
27
+ function identity(value, now) {
28
+ return object(value) && typeof value.id === "string" && value.id.length > 0 && triggers.has(value.trigger) &&
29
+ Number.isSafeInteger(value.pid) && value.pid > 0 && stamp(value.startedAt, now);
30
+ }
31
+ function summary(value, now, failure = false) {
32
+ return exact(value, [...summaryKeys, ...(failure ? ["reason", "message"] : [])], failure ? ["path", "offset"] : []) &&
33
+ identity(value, now) && stamp(value.finishedAt, now) && value.startedAt <= value.finishedAt && counts(value.counts) && peak(value.peakRssBytes) &&
34
+ (!failure || reasons.has(value.reason) && typeof value.message === "string" && value.message.length > 0 && value.message.length <= 2048 &&
35
+ (value.path === undefined || typeof value.path === "string") && (value.offset === undefined || integer(value.offset)));
36
+ }
37
+ function run(value, now) {
38
+ if (!exact(value, [...summaryKeys, "outcome", "reason", "reclaimedLock"]) || !identity(value, now) ||
39
+ !counts(value.counts) || !peak(value.peakRssBytes) ||
40
+ !["running", "complete", "partial", "failed"].includes(value.outcome) || value.reason !== null && !reasons.has(value.reason)) return false;
41
+ if (value.reclaimedLock !== null && !reclaimed(value.reclaimedLock, now)) return false;
42
+ if (value.outcome === "running") return value.finishedAt === null && value.reason === null;
43
+ return stamp(value.finishedAt, now) && value.startedAt <= value.finishedAt &&
44
+ (value.outcome !== "complete" || value.reason === null) && (value.outcome !== "failed" || value.reason !== null);
45
+ }
46
+ function backlog(value) {
47
+ return exact(value, ["pending", "setAsideCount", "setAside", "truncated"], ["failedCount", "failed", "failedTruncated"]) &&
48
+ typeof value.pending === "boolean" && integer(value.setAsideCount) && Array.isArray(value.setAside) &&
49
+ value.setAside.length === Math.min(value.setAsideCount, 100) && value.truncated === (value.setAsideCount > 100) &&
50
+ validFailureBacklog(value, { legacy: true }) &&
51
+ (value.failed === undefined || value.failed.every(row => exact(row, ["stream", "offset", "reason", "attempts", "nextRetryAt"]))) &&
52
+ value.setAside.every(row =>
53
+ exact(row, ["source", "path", "offset", "reason"], ["line"]) && ["aw", "cc", "pi", "codex"].includes(row.source) &&
54
+ typeof row.path === "string" && typeof row.reason === "string" && integer(row.offset) &&
55
+ (row.line === undefined || Number.isSafeInteger(row.line) && row.line > 0));
56
+ }
57
+
58
+ export function validCaptureStatus(status, { now = Date.now() } = {}) {
59
+ if (!exact(status, ["schemaVersion", "policy", "lastRun", "lastSuccess", "lastFailure", "lastProgressAt", "backlog"]) ||
60
+ status.schemaVersion !== 1 || !backlog(status.backlog)) return false;
61
+ if (status.policy !== null && !(exact(status.policy, Object.keys(CAPTURE_POLICY)) &&
62
+ Object.keys(CAPTURE_POLICY).every(key => status.policy[key] === CAPTURE_POLICY[key]))) return false;
63
+ if (status.lastRun !== null && !run(status.lastRun, now) || status.lastSuccess !== null && !summary(status.lastSuccess, now) ||
64
+ status.lastFailure !== null && !summary(status.lastFailure, now, true) ||
65
+ status.lastProgressAt !== null && !stamp(status.lastProgressAt, now)) return false;
66
+ // Algorithm-phase nulls are valid absence of evidence; service facts cannot
67
+ // be published as an unqualified null-policy algorithm snapshot.
68
+ return status.policy !== null || [status.lastRun, status.lastSuccess, status.lastFailure, status.lastProgressAt].every(value => value === null);
69
+ }
70
+
71
+ // Reclaim evidence is optional. A dead owner record with a missing,
72
+ // nonstandard or future start (clock step, skewed shared home) is published
73
+ // as null rather than refusing this run's receipt.
74
+ export function captureReclaimedLock(value, { now = Date.now() } = {}) {
75
+ const evidence = value ? { pid: value.pid, startedAt: value.startedAt } : null;
76
+ return evidence && reclaimed(evidence, now) ? evidence : null;
77
+ }
78
+
79
+ export function emptyCaptureStatus(backlog) {
80
+ return { schemaVersion: 1, policy: null, lastRun: null, lastSuccess: null, lastFailure: null, lastProgressAt: null, backlog };
81
+ }
82
+
83
+ // The health transport carries the same nullable receipt/backlog components,
84
+ // without a policy/progress snapshot. Reuse their validators here; consumers
85
+ // validate this envelope, never read status or reinterpret diagnosis rules.
86
+ export function validCaptureHealthEnvelope(value, { now = Date.now() } = {}) {
87
+ return exact(value, ["schemaVersion", "status", "rows", "lastRun", "lastSuccess", "lastFailure", "backlog"]) &&
88
+ value.schemaVersion === 1 && Array.isArray(value.rows) &&
89
+ value.status === (value.rows.length ? "warning" : "ok") &&
90
+ value.rows.every(row => exact(row, ["code", "message"]) &&
91
+ typeof row.code === "string" && /^capture-[a-z]+(?:-[a-z]+)*$/.test(row.code) &&
92
+ typeof row.message === "string" && row.message.length > 0) &&
93
+ (value.lastRun === null || run(value.lastRun, now)) &&
94
+ (value.lastSuccess === null || summary(value.lastSuccess, now)) &&
95
+ (value.lastFailure === null || summary(value.lastFailure, now, true)) && backlog(value.backlog);
96
+ }
97
+
98
+ export function readCaptureStatus(root, options) {
99
+ const path = join(root, "capture-status.json");
100
+ let fd;
101
+ try { fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK); }
102
+ catch (error) { if (error.code === "ENOENT") return null; throw error; }
103
+ let text;
104
+ try {
105
+ const stat = fstatSync(fd), limit = 1024 * 1024;
106
+ if (!stat.isFile() || stat.size > limit) throw new Error("capture status is not a regular file within 1 MiB");
107
+ const bytes = Buffer.alloc(limit + 1); let size = 0;
108
+ while (size < bytes.length) {
109
+ const count = readSync(fd, bytes, size, bytes.length - size, size);
110
+ if (!count) break; size += count;
111
+ }
112
+ if (size > limit) throw new Error("capture status exceeds 1 MiB");
113
+ text = bytes.toString("utf8", 0, size);
114
+ } finally { closeSync(fd); }
115
+ let parsed;
116
+ try { parsed = JSON.parse(text); } catch { throw new Error("malformed capture status JSON"); }
117
+ if (!validCaptureStatus(parsed, options)) throw new Error("unsupported, malformed or future-dated capture status");
118
+ return parsed;
119
+ }
120
+
121
+ const INVALID_PREFIX = "capture-status.json.invalid-";
122
+ function syncDirectory(path) {
123
+ const fd = openSync(path, constants.O_RDONLY);
124
+ try { fsyncSync(fd); } finally { closeSync(fd); }
125
+ }
126
+
127
+ /** A malformed, oversized, non-regular or future-dated status is no evidence
128
+ * and would stop every pass that reads it. It is moved aside, never
129
+ * overwritten, to `capture-status.json.invalid-<UTC stamp>` (the root
130
+ * directory synced after the rename), so the next publication starts from an
131
+ * empty status with no history; one moved-aside copy is kept. A system error
132
+ * reading it (permission, I/O, descriptors) says nothing about its content
133
+ * and is thrown, as is a failed rename: the original stays in place.
134
+ * → { path, reason, stale? } of the moved-aside copy (`stale` lists older
135
+ * copies that could not be removed), or null when the status is absent or
136
+ * readable. */
137
+ export function setAsideInvalidCaptureStatus(root, { now = Date.now() } = {}) {
138
+ let reason;
139
+ try { readCaptureStatus(root, { now }); return null; }
140
+ catch (error) { if (error.code) throw error; reason = error.message; }
141
+ const path = join(root, "capture-status.json");
142
+ const aside = join(root, INVALID_PREFIX + new Date(now).toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z"));
143
+ const older = readdirSync(root).filter(name => name.startsWith(INVALID_PREFIX)).map(name => join(root, name)).filter(name => name !== aside);
144
+ try { renameSync(path, aside); }
145
+ catch (error) { throw new Error(`capture status ${path} is unreadable (${reason}) and could not be moved aside: ${error.message}; it was left in place`); }
146
+ // Moved but not confirmed durable: the error says where the status now is.
147
+ try { syncDirectory(root); }
148
+ catch (error) {
149
+ throw Object.assign(new Error(`capture status ${path} is unreadable (${reason}); it was moved aside to ${aside}, but syncing ${root} failed (${error.message}), so the move may not be durable`),
150
+ { invalidStatus: { path: aside, reason } });
151
+ }
152
+ // The new copy is already safe: an older one that cannot go stays, reported.
153
+ const stale = older.filter(name => { try { unlinkSync(name); return false; } catch (error) { return error.code !== "ENOENT"; } });
154
+ if (older.length > stale.length) try { syncDirectory(root); } catch { /* the removals are diagnostics housekeeping */ }
155
+ return { path: aside, reason, ...(stale.length ? { stale } : {}) };
156
+ }
157
+
158
+ export function persistCaptureStatus(root, status, options) {
159
+ if (!validCaptureStatus(status, options)) throw new Error("refusing invalid capture status publication");
160
+ const path = join(root, "capture-status.json"), temp = `${path}.${randomUUID()}.tmp`;
161
+ let fd;
162
+ try {
163
+ fd = openSync(temp, "wx", 0o600);
164
+ writeFileSync(fd, JSON.stringify(status) + "\n"); fsyncSync(fd); closeSync(fd); fd = undefined;
165
+ renameSync(temp, path);
166
+ } finally {
167
+ if (fd !== undefined) closeSync(fd);
168
+ try { unlinkSync(temp); } catch (error) { if (error.code !== "ENOENT") throw error; }
169
+ }
170
+ return status;
171
+ }
@@ -0,0 +1,136 @@
1
+ // Private process transport, separate from reconciliation and status writing.
2
+ // The caller supplies the package worker entry; no shell, inherited execArgv,
3
+ // or caller-controlled NODE_OPTIONS can override its fixed heap policy.
4
+ import { spawn } from "node:child_process";
5
+ import { CAPTURE_POLICY } from "./capture-budget.mjs";
6
+ import { acquireCaptureLock } from "./capture-lock.mjs";
7
+
8
+ // hrtime uses the same monotonic origin in both local processes. Startup and
9
+ // lock publication consume this budget; the child never starts a new 300s clock.
10
+ export const captureMonotonicMs = () => Number(process.hrtime.bigint() / 1000000n);
11
+ // A signal received during synchronous work stays pending until a poll phase.
12
+ // One setImmediate can resume before that phase; two hops allow one between.
13
+ export const captureSignalPoll = () => new Promise(resolve => setImmediate(() => setImmediate(resolve)));
14
+ export function captureWorkerEnvironment(env = process.env) {
15
+ const out = {};
16
+ for (const key of ["HOME", "PATH", "TMPDIR", "TMP", "TEMP", "XDG_CACHE_HOME", "XDG_CONFIG_HOME", "LANG", "LC_ALL", "TZ", "USERPROFILE", "SYSTEMROOT"])
17
+ if (env[key] !== undefined) out[key] = env[key];
18
+ return out;
19
+ }
20
+
21
+ const outcomes = new Set(["complete", "partial", "failed"]);
22
+ const reasons = new Set([null, "deadline", "rss", "heap", "interrupted", "input", "io"]);
23
+ const MESSAGE_LENGTH = 512, CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
24
+ // A failed worker's private one-line diagnostic for the supervising command's
25
+ // stderr, never published status. Parser messages can quote input bytes, so a
26
+ // SyntaxError is reduced to its class name.
27
+ export function captureWorkerMessage(error) {
28
+ const text = error instanceof SyntaxError ? "SyntaxError" : error instanceof Error ? String(error.message) : "non-Error exception";
29
+ const message = text.replace(new RegExp(CONTROL.source + "+", "g"), " ").trim().slice(0, MESSAGE_LENGTH).replace(/[\ud800-\udbff]$/, "").trim();
30
+ return message || "unexplained operational failure";
31
+ }
32
+ export function validWorkerResult(value) {
33
+ return value && outcomes.has(value.outcome) && reasons.has(value.reason) &&
34
+ (value.outcome !== "complete" || value.reason === null) &&
35
+ (value.outcome !== "failed" || value.reason !== null) &&
36
+ (value.message === undefined || value.outcome === "failed" && typeof value.message === "string" &&
37
+ value.message.length > 0 && value.message.length <= MESSAGE_LENGTH && !CONTROL.test(value.message)) &&
38
+ (value.continuation === undefined || typeof value.continuation === "boolean") &&
39
+ (value.resetRequired === undefined || value.resetRequired === true && value.outcome === "partial" && value.continuation === true) &&
40
+ !(value.outcome === "complete" && value.continuation);
41
+ }
42
+
43
+ /** Internal seams are for isolated tests, not public tuning. Only the worker
44
+ * writes run/status facts. The supervisor owns admission, process lifetime and
45
+ * its command result; a forced death leaves an unfinished worker receipt.
46
+ *
47
+ * TERM/INT is a cooperative stop: a started worker is asked, through its own
48
+ * owner record, to stop at its next bounded check and write its interrupted
49
+ * receipt. The first signal starts one grace (`graceMs`, capped by the
50
+ * absolute deadline) after which the exact child is killed; later signals
51
+ * neither shorten nor extend it. A child not yet started is killed at once. */
52
+ export async function superviseCapture(root, options, {
53
+ workerPath, policy = CAPTURE_POLICY, drainSeconds = 5, graceMs = 5000,
54
+ executable = process.execPath, env = process.env, clock = captureMonotonicMs,
55
+ acquire = acquireCaptureLock, spawnChild = spawn,
56
+ window, pass,
57
+ } = {}) {
58
+ if (typeof workerPath !== "string" || !workerPath) throw new Error("capture worker entry is required");
59
+ if (window && (![window.drainAt, window.finalizeAt, window.hardAt].every(Number.isFinite) ||
60
+ window.drainAt > window.finalizeAt || window.finalizeAt > window.hardAt)) throw new Error("invalid capture child time window");
61
+ const started = clock(), deadline = Math.min(started + policy.deadlineSeconds * 1000, window?.hardAt ?? Infinity);
62
+ const drainAt = Math.min(deadline, window?.drainAt ?? Math.max(started, deadline - drainSeconds * 1000));
63
+ const finalizeAt = Math.min(deadline, window?.finalizeAt ?? deadline);
64
+ const lock = acquire(root);
65
+ if (!lock.release) return { outcome: "overlap", reason: null, exitCode: 0, held: lock.held };
66
+ let child, timer, grace, finish, forced, result, admitted = false, ready = false, diagnostics = "", outputBytes = 0;
67
+ const stop = reason => {
68
+ forced ??= reason;
69
+ // ChildProcess owns this exact child until exit/reaping. Never derive a
70
+ // process group, or signal a PID recovered from a persisted lock record.
71
+ if (child?.pid > 0 && child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
72
+ };
73
+ const interrupted = () => {
74
+ if (grace !== undefined || forced) return;
75
+ if (!admitted) { stop("interrupted"); return; }
76
+ // A worker that already sent its result keeps it; it still must exit
77
+ // within the same grace.
78
+ if (!result) {
79
+ try { lock.requestStop(); } catch { stop("interrupted"); return; }
80
+ }
81
+ grace = setTimeout(() => stop("interrupted"), Math.max(0, Math.min(deadline, clock() + graceMs) - clock()));
82
+ };
83
+ try {
84
+ process.on("SIGTERM", interrupted); process.on("SIGINT", interrupted);
85
+ child = spawnChild(executable, [`--max-old-space-size=${policy.heapMiB}`, "--no-warnings",
86
+ // Node 22.5–22.12 need this flag. It does not import SQLite or alter the
87
+ // heap, and unlike execArgv it cannot forward arbitrary preload code.
88
+ ...(Number(process.versions.node.split(".")[0]) === 22 && Number(process.versions.node.split(".")[1]) < 13 ? ["--experimental-sqlite"] : []),
89
+ workerPath], { env: captureWorkerEnvironment(env), stdio: ["ignore", "ignore", "pipe", "ipc"], serialization: "json" });
90
+ finish = new Promise(resolve => {
91
+ let spawnError;
92
+ child.once("error", () => { spawnError = true; stop("io"); });
93
+ child.once("close", (code, signal) => resolve({ code, signal, spawnError }));
94
+ });
95
+ child.stderr?.on("data", chunk => {
96
+ outputBytes += chunk.length;
97
+ if (outputBytes > 64 * 1024) { stop("io"); return; }
98
+ diagnostics += chunk.toString("utf8");
99
+ });
100
+ child.on("message", message => {
101
+ if (forced) return;
102
+ if (!ready && message?.type === "ready" && message.pid === child.pid &&
103
+ typeof message.nonce === "string" && /^[a-f0-9]{32}$/.test(message.nonce) &&
104
+ typeof message.startedAt === "string" && Number.isFinite(Date.parse(message.startedAt))) {
105
+ ready = true;
106
+ try {
107
+ lock.registerWorker(message);
108
+ if (clock() >= deadline) { stop("deadline"); return; }
109
+ admitted = true;
110
+ child.send({ type: "start", root, options, policy, parent: { pid: process.pid, nonce: lock.nonce },
111
+ workerNonce: message.nonce, drainAt, finalizeAt, hardAt: deadline, pass,
112
+ reclaimedLock: lock.reclaimed ?? null }, error => { if (error) stop("io"); });
113
+ } catch { stop("io"); }
114
+ } else if (ready && !result && message?.type === "result" && validWorkerResult(message.result)) {
115
+ result = message.result;
116
+ } else stop("io");
117
+ });
118
+ timer = setTimeout(() => stop("deadline"), Math.max(0, deadline - clock()));
119
+ const ended = await finish;
120
+ if (forced || ended.spawnError || ended.signal || !result || ended.code !== (result.outcome === "failed" ? 1 : 0)) {
121
+ const heap = /heap out of memory|allocation failed.*heap/i.test(diagnostics);
122
+ return { outcome: "failed", reason: heap ? "heap" : forced ?? (ended.signal ? "interrupted" : "io"), exitCode: 1 };
123
+ }
124
+ return { ...result, exitCode: result.outcome === "failed" ? 1 : 0 };
125
+ } catch {
126
+ stop("io");
127
+ if (finish) await finish;
128
+ return { outcome: "failed", reason: "io", exitCode: 1 };
129
+ } finally {
130
+ clearTimeout(timer); clearTimeout(grace);
131
+ process.off("SIGTERM", interrupted); process.off("SIGINT", interrupted);
132
+ const released = lock.release();
133
+ // Cleanup failure is an operational error even after a successful worker.
134
+ if (!released.released) throw Object.assign(new Error("capture supervisor could not release its lock"), { release: released });
135
+ }
136
+ }
@@ -0,0 +1,32 @@
1
+ // Foreground notification scheduling only. A queued event never authorizes
2
+ // capture, selects roots or certifies progress; each pass owns those decisions.
3
+ export function captureWatchQueue(run, { onError = error => console.error(error), delay = 2000, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
4
+ let timer = null, active = null, pending = false, closed = false;
5
+ const drain = async () => {
6
+ while (pending && !closed) {
7
+ pending = false;
8
+ try { await run(); } catch (error) {
9
+ // A broken diagnostic sink must not strand the queue or turn a timer
10
+ // callback into an unhandled rejection. It supplies no run evidence.
11
+ try { onError(error); } catch { /* best-effort diagnostics */ }
12
+ }
13
+ }
14
+ };
15
+ const ready = () => {
16
+ timer = null;
17
+ if (closed) return;
18
+ pending = true;
19
+ if (!active) active = drain().finally(() => { active = null; });
20
+ };
21
+ return {
22
+ schedule() {
23
+ if (closed) return;
24
+ if (timer !== null) clearTimer(timer);
25
+ timer = setTimer(ready, delay);
26
+ },
27
+ // Do not abandon an admitted child. Its supervisor handles signals and
28
+ // reaps it; closing only cancels future notification-driven passes.
29
+ close() { closed = true; pending = false; if (timer !== null) clearTimer(timer); timer = null; },
30
+ async settled() { await active; },
31
+ };
32
+ }