@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
@@ -0,0 +1,73 @@
1
+ // Private command preparation. Page mutations and their resume key commit
2
+ // together; this is retry intent, never source/custody or completion proof.
3
+ import { basename } from "node:path";
4
+ import { SESSION_FORMATS } from "./formats.mjs";
5
+ import { loadIgnore } from "./ignore.mjs";
6
+
7
+ const formats = ["cc", "pi", "codex", "aw"];
8
+ export class CaptureIssuePreparation {
9
+ constructor(state, queue, { runId, sources, retry = false }) {
10
+ if (typeof runId !== "string" || !runId || typeof retry !== "boolean" ||
11
+ !Array.isArray(sources) || new Set(sources).size !== sources.length || sources.some(source => !formats.includes(source)) ||
12
+ retry && sources.length !== formats.length)
13
+ throw new Error("invalid capture issue preparation");
14
+ this.state = state; this.queue = queue; this.runId = runId; this.retry = retry;
15
+ this.sources = formats.filter(source => sources.includes(source));
16
+ this.scope = queue.current().id;
17
+ }
18
+
19
+ current() {
20
+ if (this.queue.current().id !== this.scope) throw new Error("capture issue preparation scope changed");
21
+ const row = this.state.get("capture-issue-preparation", this.queue.owner);
22
+ if (!row || row.runId !== this.runId) return null;
23
+ if (row.scope !== this.scope || row.retry !== this.retry || JSON.stringify(row.sources) !== JSON.stringify(this.sources) ||
24
+ row.after !== null && typeof row.after !== "string" || typeof row.complete !== "boolean")
25
+ throw new Error("capture issue preparation selection changed");
26
+ return row;
27
+ }
28
+
29
+ complete() { return this.current()?.complete === true; }
30
+
31
+ advance(root, { stopped = () => false, finalize = false, limit = 128 } = {}) {
32
+ if (this.state.depth || !Number.isSafeInteger(limit) || limit < 1 || limit > 128)
33
+ throw new Error("capture issue preparation requires a bounded standalone transaction");
34
+ if (finalize || stopped()) return { complete: false, stopped: true, checked: 0 };
35
+ if (this.complete()) return { complete: true, checked: 0 };
36
+ // Privacy failure must propagate; it cannot authorize opening inputs.
37
+ const ignore = loadIgnore(root);
38
+ return this.state.transaction(() => {
39
+ const row = this.current() ?? { runId: this.runId, scope: this.scope, retry: this.retry,
40
+ sources: this.sources, after: null, complete: false };
41
+ const page = this.state.db.prepare(`SELECT key,value FROM state WHERE kind='set-aside'
42
+ ${row.after === null ? "" : "AND key>?"} ORDER BY key LIMIT ?`)
43
+ .all(...(row.after === null ? [limit] : [row.after, limit]));
44
+ let checked = 0;
45
+ for (const { key, value } of page) {
46
+ if (stopped()) break;
47
+ const issue = JSON.parse(value), fmt = SESSION_FORMATS[issue.source];
48
+ if (!formats.includes(issue.source) || typeof issue.path !== "string")
49
+ throw new Error("invalid capture issue during preparation");
50
+ // Preserve native public reconciliation for missing/ignored inputs,
51
+ // but do not clear another owner or an excluded format's evidence.
52
+ const ignored = fmt && issue.owner === this.queue.owner && this.sources.includes(issue.source) &&
53
+ ignore.ignores(issue.path, [basename(issue.path), fmt.sessionId(issue.path), ...(fmt.ignoreKeys?.(issue.path) ?? [])]);
54
+ if (this.retry) {
55
+ // The existing explicit all-input retry marks the root's issues,
56
+ // including other owners, without changing their source selection.
57
+ // Run identity stays stable across replacement and partial pages.
58
+ this.state.set("source-retry", key, this.runId);
59
+ }
60
+ if (ignored) this.state.delete("set-aside", key);
61
+ else if (this.retry) this.state.set("set-aside", key, { ...issue, retry: true });
62
+ if ((ignored || this.retry) && issue.owner === this.queue.owner && this.sources.includes(issue.source)) {
63
+ this.state.db.prepare("UPDATE capture_sources SET outcome='ready' WHERE scope=? AND source=? AND path=? AND outcome='set-aside'")
64
+ .run(this.scope, issue.source, issue.path);
65
+ }
66
+ row.after = key; checked++;
67
+ }
68
+ row.complete = checked === page.length && page.length < limit;
69
+ this.state.set("capture-issue-preparation", this.queue.owner, row);
70
+ return { complete: row.complete, stopped: stopped(), checked };
71
+ });
72
+ }
73
+ }
@@ -2,6 +2,7 @@ import { statSync } from "node:fs";
2
2
  import { spawnSync } from "node:child_process";
3
3
  import { fileURLToPath } from "node:url";
4
4
  import { join } from "node:path";
5
+ import { validFailure, validFailureBacklog } from "./capture-failures.mjs";
5
6
  // Feature landed separately on the two release lines; 23.0/23.1 lack it.
6
7
  export function supportsReadOnlySqlite(version) {
7
8
  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
@@ -33,8 +34,20 @@ export function readIssueBacklog(db, { pending = false, validate = false } = {})
33
34
  }
34
35
  return { source, path, offset, reason, ...(line === undefined ? {} : { line }) };
35
36
  });
37
+ // Both inventories share this read snapshot, but have independent samples.
38
+ // Private generation/admission fields never enter the public projection.
39
+ const failedCount = Number(db.prepare("SELECT count(*) AS n FROM state WHERE kind = 'capture-failed'").get().n);
40
+ const failed = db.prepare("SELECT value FROM state WHERE kind = 'capture-failed' ORDER BY key LIMIT 100").all()
41
+ .map(({ value }) => {
42
+ const { stream, offset, reason, attempts, nextRetryAt } = JSON.parse(value);
43
+ const row = { stream, offset, reason, attempts, nextRetryAt };
44
+ if (!validFailure(row)) throw new Error("malformed capture failure row");
45
+ return row;
46
+ });
47
+ const deferred = db.prepare("SELECT 1 AS found FROM state WHERE kind = 'capture-retry' LIMIT 1").get()?.found === 1;
36
48
  db.exec("COMMIT");
37
- return { pending: pending || count > 0, setAsideCount: count, setAside, truncated: count > sample.length };
49
+ return { pending: pending || count > 0 || failedCount > 0 || deferred, setAsideCount: count, setAside, truncated: count > sample.length,
50
+ failedCount, failed, failedTruncated: failedCount > failed.length };
38
51
  } catch (err) { db.exec("ROLLBACK"); throw err; }
39
52
  }
40
53
 
@@ -59,6 +72,6 @@ export function readCurrentIssueBacklog(root) {
59
72
  const b = response.backlog;
60
73
  if (!b || typeof b.pending !== "boolean" || !Number.isSafeInteger(b.setAsideCount) || b.setAsideCount < 0 ||
61
74
  !Array.isArray(b.setAside) || b.setAside.length !== Math.min(b.setAsideCount, 100) ||
62
- b.truncated !== (b.setAsideCount > 100)) throw new Error("malformed capture database reader output");
75
+ b.truncated !== (b.setAsideCount > 100) || !validFailureBacklog(b)) throw new Error("malformed capture database reader output");
63
76
  return b;
64
77
  }
@@ -9,7 +9,7 @@
9
9
  // initializing (owner-less) lock refuses the pass and names the holder and
10
10
  // the operator recovery; it is never stolen.
11
11
  //
12
- // A lock whose recorded owner is DEAD on this host is reclaimed (a capture
12
+ // A lock whose recorded owner AND registered worker are DEAD on this host is reclaimed (a capture
13
13
  // killed mid-pass by a hook or caller timeout runs no finally). Records
14
14
  // without host predate host recording and live under this user's home, so
15
15
  // they count as this host's (RECLAIM_HOSTLESS_RECORDS). Reclaimers
@@ -19,10 +19,12 @@
19
19
  // meanwhile. A guard whose holder died is never removed (that would race
20
20
  // exactly as removing the lock does); it is named with its recovery.
21
21
  // Acquire never waits: it reclaims once or skips, and the next pass catches up.
22
- // There is no signal handler: a pass is synchronous, so a JS handler would
23
- // only run after the whole pass (turning a caller's timeout kill into a full
24
- // pass), and SIGKILL cannot be handled; the reclaim is the recovery.
25
- import { closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
22
+ // A supervisor publishes its idle child's identity before permitting work.
23
+ // The worker is part of the same lock, not a second independently reclaimed
24
+ // lock. A live/reused/unknown child PID prevents release and reclamation even
25
+ // when the supervisor died. Callers own child termination/reaping; this module
26
+ // never sends a terminating signal or infers a process group.
27
+ import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
26
28
  import { randomBytes } from "node:crypto";
27
29
  import { hostname } from "node:os";
28
30
  import { join } from "node:path";
@@ -35,18 +37,62 @@ export function captureLockPath(root) { return join(root, ".capture.lock"); }
35
37
 
36
38
  /** "alive" | "dead" | "unknown" for an owner pid ("unknown" = exists but not signalable). */
37
39
  export function holderLiveness(pid) {
38
- if (!Number.isInteger(pid) || pid <= 0) return "unknown";
39
- try { process.kill(pid, 0); return "alive"; } catch (e) { return e.code === "EPERM" ? "unknown" : "dead"; }
40
+ if (!Number.isInteger(pid) || pid <= 0 || pid > 2147483647) return "unknown";
41
+ try { process.kill(pid, 0); return "alive"; } catch (e) { return e.code === "ESRCH" ? "dead" : "unknown"; }
40
42
  }
41
43
 
42
- const readJson = (path) => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; } };
43
- const readOwner = (dir) => readJson(join(dir, "owner.json"));
44
+ const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
45
+ const readJson = (path) => {
46
+ let fd;
47
+ try {
48
+ const before = lstatSync(path, { bigint: true });
49
+ if (!before.isFile() || before.isSymbolicLink() || before.size > 4096n) return undefined;
50
+ fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
51
+ const opened = fstatSync(fd, { bigint: true });
52
+ if (!sameFile(before, opened)) return undefined;
53
+ const bytes = Buffer.alloc(Number(opened.size)); let offset = 0;
54
+ while (offset < bytes.length) { const n = readSync(fd, bytes, offset, bytes.length - offset, offset); if (!n) return undefined; offset += n; }
55
+ if (!sameFile(opened, fstatSync(fd, { bigint: true })) || !sameFile(opened, lstatSync(path, { bigint: true }))) return undefined;
56
+ return JSON.parse(bytes.toString("utf8"));
57
+ } catch { return undefined; }
58
+ finally { if (fd !== undefined) closeSync(fd); }
59
+ };
60
+ const readOwner = (dir) => {
61
+ try { const st = lstatSync(dir); return st.isDirectory() && !st.isSymbolicLink() ? readJson(join(dir, "owner.json")) : undefined; }
62
+ catch { return undefined; }
63
+ };
64
+ export const readCaptureLockOwner = root => readOwner(captureLockPath(root));
65
+
66
+ // Diagnostic attribution in a fresh owner record: which command took the
67
+ // lock, from which entry and trigger, and the immediate parent process. Fixed
68
+ // labels and direct process facts only, never argv, environment or a guessed
69
+ // external caller; an entry that is not known is left out. It never confers authority: identity, liveness and reclaim
70
+ // read only pid, nonce, startedAt, host and worker.
71
+ const COMMANDS = new Set(["pass", "home", "file", "reset-cursors", "retry"]);
72
+ const ENTRIES = new Set(["oats", "turn-record", "hook-runner", "service-runner"]);
73
+ const TRIGGERS = new Set(["manual", "watch", "hook", "setup", "service"]);
74
+ export function captureLockAttribution({ command, caller, ppid = process.ppid } = {}) {
75
+ if (command === undefined && caller === undefined) return {};
76
+ if (!COMMANDS.has(command) || caller?.entry !== undefined && !ENTRIES.has(caller.entry) || !TRIGGERS.has(caller?.trigger) ||
77
+ Object.keys(caller).some(key => key !== "entry" && key !== "trigger")) throw new Error("invalid capture lock attribution");
78
+ return { command, caller: { ...(caller.entry !== undefined ? { entry: caller.entry } : {}), trigger: caller.trigger },
79
+ ...(validPid(ppid) ? { ppid } : {}) };
80
+ }
81
+
82
+ function validPid(pid) { return Number.isInteger(pid) && pid > 0 && pid <= 2147483647; }
83
+ function workerDead(owner, { host, liveness }) {
84
+ if (!Object.hasOwn(owner, "worker")) return true;
85
+ const worker = owner.worker;
86
+ return validPid(worker?.pid) && worker.pid !== owner.pid && worker.host === host && typeof worker.nonce === "string" &&
87
+ worker.nonce.length > 0 && worker.nonce.length <= 128 && typeof worker.startedAt === "string" &&
88
+ Number.isFinite(Date.parse(worker.startedAt)) && liveness(worker.pid) === "dead";
89
+ }
44
90
 
45
91
  /** Whether `owner` is a record of this host whose process is dead: the only lock this module reclaims. */
46
92
  function deadHere(owner, { host, liveness, reclaimHostless }) {
47
- if (!owner || !Number.isInteger(owner.pid)) return false;
93
+ if (!owner || !validPid(owner.pid)) return false;
48
94
  const here = owner.host === undefined ? reclaimHostless : owner.host === host;
49
- return here && liveness(owner.pid) === "dead";
95
+ return here && liveness(owner.pid) === "dead" && workerDead(owner, { host, liveness });
50
96
  }
51
97
 
52
98
  /** Remove the lock `dir` held by the dead `owner`, serialized by the guard `<dir>.reclaim`. → { removed }
@@ -60,7 +106,7 @@ function reclaimDeadLock(dir, owner, me, opts) {
60
106
  const g = readJson(guard);
61
107
  return g && deadHere(g, opts) ? { abandoned: { guard, pid: g.pid } } : { removed: false };
62
108
  }
63
- const same = (o) => o && o.pid === owner.pid && o.nonce === owner.nonce && o.startedAt === owner.startedAt;
109
+ const same = (o) => o && o.pid === owner.pid && o.nonce === owner.nonce && o.startedAt === owner.startedAt && JSON.stringify(o.worker) === JSON.stringify(owner.worker);
64
110
  let removed = false;
65
111
  try {
66
112
  const now = readOwner(dir);
@@ -79,6 +125,7 @@ export function shellQuote(s) { return "'" + String(s).replace(/'/g, "'\\''") +
79
125
  /** The operator's recovery line for a lock that is not ours. */
80
126
  export function recoveryInstruction(dir, owner, liveness) {
81
127
  const remove = `rm -r -- ${shellQuote(dir)}`;
128
+ if (owner && Object.hasOwn(owner, "worker")) return `${dir} records supervisor pid ${owner.pid} (${liveness}) and worker pid ${owner.worker?.pid ?? "unknown"}; wait for both to finish. If interrupted, stop capture triggers and verify BOTH processes are gone before removing the lock with: ${remove} and rerun`;
82
129
  if (!owner?.pid) return `${dir} is held by a pass that has not written its owner record yet (initializing, or killed before it could); stop capture triggers (hooks, launchd), verify no capture process is running (pgrep -f capture.mjs), then remove the lock with: ${remove} and rerun`;
83
130
  const who = `pid ${owner.pid} (started ${owner.startedAt || "?"}, now ${liveness})`;
84
131
  if (liveness === "alive") return `${dir} is held by ${who}; let it finish, the next pass catches up`;
@@ -103,21 +150,23 @@ export function recoveryInstruction(dir, owner, liveness) {
103
150
  * saying what happened. And `release()` never throws: it answers
104
151
  * `{ released: true }` only when the lock is verifiably gone, otherwise
105
152
  * `{ released: false, reason: "gone" | "unknown-owner" | "not-owner" |
106
- * "remove-failed", ... }` with the actual observation, never a guess.
153
+ * "remove-failed" | "worker-active", ... }` with the actual observation, never a guess.
107
154
  *
108
155
  * The owner record carries a per-acquisition nonce, so a release kept from
109
156
  * an earlier acquisition cannot erase a later one by the same pid (an
110
157
  * operator recovery followed by a new pass in the same long-lived process).
111
158
  *
112
159
  * `io` exists for fault injection in tests only. */
113
- export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, liveness = holderLiveness, host = hostname(), reclaimHostless = RECLAIM_HOSTLESS_RECORDS, io = {} } = {}) {
114
- const fs = { writeFileSync, rmSync, openSync, closeSync, lstatSync, ...io };
160
+ export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, liveness = holderLiveness, host = hostname(), reclaimHostless = RECLAIM_HOSTLESS_RECORDS, io = {}, command, caller } = {}) {
161
+ if (!validPid(pid)) throw new Error("capture lock owner must have a positive process ID");
162
+ const attribution = captureLockAttribution({ command, caller });
163
+ const fs = { writeFileSync, rmSync, openSync, closeSync, lstatSync, fsyncSync, renameSync, ...io };
115
164
  const dir = captureLockPath(root);
116
165
  const nonce = randomBytes(8).toString("hex");
117
166
  mkdirSync(root, { recursive: true }); // the store creates the root lazily; the lock may come first
118
167
  let reclaimed;
119
168
  for (let attempt = 0; ; attempt++) {
120
- try { mkdirSync(dir); break; }
169
+ try { mkdirSync(dir, { mode: 0o700 }); break; }
121
170
  catch (e) {
122
171
  if (e.code !== "EEXIST") throw e;
123
172
  const owner = readOwner(dir);
@@ -148,7 +197,7 @@ export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, li
148
197
  // a record-less replacement look like the directory we created.
149
198
  directoryFd = fs.openSync(dir, "r");
150
199
  identity = fstatSync(directoryFd);
151
- fs.writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid, nonce, startedAt: new Date(now()).toISOString(), host }));
200
+ fs.writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid, nonce, startedAt: new Date(now()).toISOString(), host, ...attribution }), { mode: 0o600 });
152
201
  } catch (err) {
153
202
  // Ownership was proven by the mkdir, not by the moment of cleanup: the
154
203
  // directory is removed only if it is still ours (same inode) and holds
@@ -173,14 +222,85 @@ export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, li
173
222
  } finally {
174
223
  if (directoryFd !== undefined) fs.closeSync(directoryFd);
175
224
  }
225
+ const ownCurrent = message => {
226
+ const current = readOwner(dir), st = fs.lstatSync(dir);
227
+ if (st.dev !== identity.dev || st.ino !== identity.ino || current?.pid !== pid || current?.nonce !== nonce) throw new Error(message);
228
+ return current;
229
+ };
230
+ // Durably replace this acquisition's owner record with `next`, only while it
231
+ // is still exactly `current` in the directory this call created.
232
+ const replaceOwner = (current, next, what, label) => {
233
+ const temp = join(dir, `${label}-${nonce}.tmp`); let fd, dirFd, rootFd, temporary, published = false;
234
+ try {
235
+ dirFd = fs.openSync(dir, constants.O_RDONLY | constants.O_NOFOLLOW);
236
+ const pinned = fstatSync(dirFd);
237
+ if (pinned.dev !== identity.dev || pinned.ino !== identity.ino) throw new Error(`capture lock changed before ${what}`);
238
+ fd = fs.openSync(temp, "wx", 0o600);
239
+ fs.writeFileSync(fd, JSON.stringify(next));
240
+ fs.fsyncSync(fd); temporary = fstatSync(fd, { bigint: true });
241
+ const again = readOwner(dir), named = fs.lstatSync(dir);
242
+ if (named.dev !== identity.dev || named.ino !== identity.ino || JSON.stringify(again) !== JSON.stringify(current) || !sameFile(temporary, fs.lstatSync(temp, { bigint: true }))) throw new Error(`capture lock changed during ${what}`);
243
+ fs.renameSync(temp, join(dir, "owner.json"));
244
+ published = true;
245
+ // Publish file bytes, their rename, and the lock directory's parent
246
+ // entry before GO. A failure is not permission to start the worker.
247
+ fs.fsyncSync(dirFd);
248
+ rootFd = fs.openSync(root, "r"); fs.fsyncSync(rootFd);
249
+ } finally {
250
+ // Never remove a path another caller replaced, even after a failed
251
+ // publication. An unpublished/unverifiable file is conservatively kept.
252
+ if (!published && temporary) {
253
+ try {
254
+ const named = fs.lstatSync(dir);
255
+ if (named.dev === identity.dev && named.ino === identity.ino && sameFile(temporary, fs.lstatSync(temp, { bigint: true }))) unlinkSync(temp);
256
+ } catch { /* absent or unknown: preserve */ }
257
+ }
258
+ if (fd !== undefined) fs.closeSync(fd);
259
+ if (rootFd !== undefined) fs.closeSync(rootFd);
260
+ if (dirFd !== undefined) fs.closeSync(dirFd);
261
+ }
262
+ };
176
263
  return {
177
264
  path: dir,
265
+ nonce,
178
266
  ...(reclaimed ? { reclaimed } : {}),
267
+ // The child must remain idle until this durable publication succeeds.
268
+ // A dead supervisor's lock cannot then be reclaimed while its worker lives.
269
+ registerWorker(worker, { previous } = {}) {
270
+ if (!validPid(worker?.pid) || worker.pid === pid || typeof worker.nonce !== "string" || !worker.nonce || worker.nonce.length > 128 || typeof worker.startedAt !== "string" || !Number.isFinite(Date.parse(worker.startedAt))) throw new Error("invalid capture worker identity");
271
+ const current = ownCurrent("capture lock changed before worker registration");
272
+ // Continuation never drops the root lock between children. Replace only
273
+ // the caller's exact previous publication, after positive death proof;
274
+ // reused PIDs and uncertain liveness preserve the old lock unchanged.
275
+ if (Object.hasOwn(current, "worker")) {
276
+ if (!previous || current.worker?.pid !== previous.pid || current.worker?.nonce !== previous.nonce ||
277
+ current.worker?.startedAt !== previous.startedAt || !workerDead(current, { host, liveness })) {
278
+ throw new Error("previous capture worker is not proven dead and unchanged");
279
+ }
280
+ } else if (previous) throw new Error("capture lock changed before worker continuation");
281
+ replaceOwner(current, { ...current, worker: { pid: worker.pid, nonce: worker.nonce, startedAt: worker.startedAt, host } }, "worker registration", "worker");
282
+ },
283
+ // A cooperative stop request for this acquisition's worker, which reads the
284
+ // owner record between bounded units. It is not a lock release, changes no
285
+ // identity field and confers nothing: reclaim and release ignore it.
286
+ requestStop() {
287
+ const current = ownCurrent("capture lock changed before stop request");
288
+ if (current.stop === true) return;
289
+ replaceOwner(current, { ...current, stop: true }, "stop request", "stop");
290
+ },
179
291
  release: () => {
180
292
  if (!existsSync(dir)) return { released: false, reason: "gone" };
181
293
  const cur = readOwner(dir);
182
294
  if (!cur) return { released: false, reason: "unknown-owner", recovery: recoveryInstruction(dir, undefined, "unknown") };
183
295
  if (cur.pid !== pid || cur.nonce !== nonce) return { released: false, reason: "not-owner", owner: cur };
296
+ try {
297
+ const named = fs.lstatSync(dir);
298
+ if (!named.isDirectory() || named.dev !== identity.dev || named.ino !== identity.ino) return { released: false, reason: "not-owner", owner: cur };
299
+ } catch (err) {
300
+ return { released: false, reason: "remove-failed", error: err.message,
301
+ recovery: "could not verify capture lock identity before removal; inspect the filesystem error and rerun capture" };
302
+ }
303
+ if (!workerDead(cur, { host, liveness })) return { released: false, reason: "worker-active", recovery: recoveryInstruction(dir, cur, "alive") };
184
304
  let error;
185
305
  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (e) { error = e; }
186
306
  let remains;