@awebai/oats 0.69.14 → 0.69.16

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 (60) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +79 -18
  3. package/docs/capabilities.md +57 -14
  4. package/docs/container.md +111 -17
  5. package/docs/desktop-cli-api.md +215 -19
  6. package/docs/desktop.md +3 -3
  7. package/docs/execution-targets.md +15 -3
  8. package/docs/first-team.md +4 -3
  9. package/docs/implementation.md +19 -9
  10. package/docs/integrations.md +9 -8
  11. package/docs/knowledge-and-learning.md +2 -2
  12. package/docs/knowledge-theory.md +17 -15
  13. package/docs/knowledge.md +202 -179
  14. package/docs/official-catalog.md +4 -4
  15. package/docs/packages.md +13 -13
  16. package/docs/release-notes/v0.69.15.md +444 -0
  17. package/docs/release-notes/v0.69.16.md +169 -0
  18. package/docs/schedules.md +168 -34
  19. package/docs/servers.md +64 -3
  20. package/docs/souls-and-instances.md +100 -19
  21. package/docs/upgrading.md +26 -6
  22. package/docs/workspaces.md +2 -2
  23. package/lib/claim.mjs +2 -3
  24. package/lib/command-flags.mjs +4 -2
  25. package/lib/core.mjs +215 -72
  26. package/lib/dir-lock.mjs +17 -0
  27. package/lib/errors.mjs +2 -1
  28. package/lib/host-run.mjs +218 -0
  29. package/lib/host-stop-child.mjs +21 -0
  30. package/lib/instance-git.mjs +32 -6
  31. package/lib/instance-lifecycle.mjs +4 -3
  32. package/lib/instance-listing.mjs +35 -6
  33. package/lib/kernel-features.mjs +4 -1
  34. package/lib/read-call.mjs +1 -1
  35. package/lib/remote.mjs +17 -14
  36. package/lib/schedule.mjs +237 -20
  37. package/lib/servers.mjs +83 -5
  38. package/lib/session-end.mjs +28 -8
  39. package/lib/session-resume.mjs +10 -18
  40. package/lib/session-seen.mjs +4 -64
  41. package/lib/status-words.mjs +11 -4
  42. package/lib/system-tools.mjs +1 -36
  43. package/lib/worktree-hooks.mjs +6 -175
  44. package/lib/worktree.mjs +19 -10
  45. package/package-catalog.json +3 -3
  46. package/package.json +4 -1
  47. package/packages/record/README.md +56 -21
  48. package/packages/record/docs/capture-service.md +8 -5
  49. package/packages/record/docs/turn-record-sot.md +9 -0
  50. package/packages/record/lib/capture-health.mjs +6 -4
  51. package/packages/record/lib/capture-lock.mjs +31 -27
  52. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  53. package/packages/record/lib/capture-scratch.mjs +2 -1
  54. package/packages/record/lib/derived-state.mjs +4 -2
  55. package/packages/record/lib/index-db.mjs +4 -2
  56. package/packages/record/lib/lock-holder.mjs +21 -0
  57. package/packages/record/lib/private-files.mjs +18 -0
  58. package/packages/record/lib/process-identity.mjs +310 -0
  59. package/packages/record/lib/store.mjs +31 -25
  60. package/skills/oats-getting-started/SKILL.md +9 -6
@@ -0,0 +1,310 @@
1
+ /** Process identity: what a lock record names its holder by, and how a recorded holder is judged.
2
+ * The start token of a pid (processStart, processStartToken), whether the process a record names
3
+ * can still act (processLiveness), this boot's identity (bootId, thisBoot), the rule for a
4
+ * record taken in another boot (takenInAnotherBoot) and the state of the holder a lock record
5
+ * names, which composes them (identityHolderState), with the lookup of the system tools they run
6
+ * (systemTool: `ps`, `sysctl`). The kernel reads all of them from here (lib/system-tools.mjs,
7
+ * lib/worktree-hooks.mjs, lib/session-seen.mjs), and so do this package's locks. Dependency-free. */
8
+ import { execFileSync, spawnSync } from "node:child_process";
9
+ import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
10
+ import { isAbsolute, join } from "node:path";
11
+
12
+ // ---------- system tools: programs run from the system's own directories ----------
13
+
14
+ /** Where a system tool is looked for, in order. */
15
+ export const SYSTEM_TOOL_DIRS = Object.freeze(["/usr/bin", "/bin", "/usr/sbin", "/sbin"]);
16
+
17
+ /** The directories a system tool is looked for in → { dirs } | { reason }. SYSTEM_TOOL_DIRS, or for a
18
+ * test only, OATS_TEST_SYSTEM_TOOL_DIRS: absolute directories separated by `:`. A seam with any other
19
+ * value names no tool at all, never a PATH-like lookup. */
20
+ export function systemToolDirs() {
21
+ const seam = process.env.OATS_TEST_SYSTEM_TOOL_DIRS;
22
+ if (seam === undefined) return { dirs: SYSTEM_TOOL_DIRS };
23
+ const dirs = seam.split(":");
24
+ if (dirs.some((dir) => !isAbsolute(dir))) return { reason: `OATS_TEST_SYSTEM_TOOL_DIRS is ${JSON.stringify(seam)}, not absolute directories` };
25
+ return { dirs };
26
+ }
27
+
28
+ /** `name` in the system directories (`dirs`, else systemToolDirs) → { file } (the first regular
29
+ * executable file, an absolute path) or { reason } (none, and where it looked). Nothing is run. */
30
+ export function systemTool(name, { dirs } = {}) {
31
+ if (typeof name !== "string" || !/^[A-Za-z0-9._+-]+$/.test(name) || name === "." || name === "..") return { reason: `${JSON.stringify(name)} is not a tool name` };
32
+ if (dirs === undefined) {
33
+ const where = systemToolDirs();
34
+ if (where.reason) return { reason: where.reason };
35
+ dirs = where.dirs;
36
+ }
37
+ for (const dir of dirs) {
38
+ const file = join(dir, name);
39
+ try {
40
+ if (!statSync(file).isFile()) continue;
41
+ accessSync(file, constants.X_OK);
42
+ return { file };
43
+ } catch { /* not here */ }
44
+ }
45
+ return { reason: `no executable ${name} in ${dirs.join(", ")}` };
46
+ }
47
+
48
+ // ---------- process identity: a pid is verified by its start time ----------
49
+
50
+ /** Where a start time is read: /proc when this host has procfs, else `ps`. The test seam
51
+ * OATS_TEST_PROCESS_START_PS (not a setting; a launch configuration cannot set it) takes the `ps`
52
+ * path on any host: `1` runs the system `ps`, an absolute path runs that file as `ps`, and any
53
+ * other value reads no start at all (psProgram). */
54
+ const readsProc = () => process.env.OATS_TEST_PROCESS_START_PS === undefined && existsSync("/proc/self/stat");
55
+ /** `ps` runs with a fixed environment, nothing inherited (runPs). Its PATH is the system directories only (SYSTEM_TOOL_DIRS),
56
+ * never the caller's: what `ps` reports is the identity a claim is held or taken over on, so the
57
+ * caller's PATH must not choose the program, and a caller whose PATH holds no `ps` reads the same
58
+ * start as any other. `lstart` is local time in the locale's format, and two readers with another
59
+ * TZ or LANG would otherwise read one live process's start differently, and take it for another. */
60
+ export const PS_ENV = Object.freeze({ PATH: SYSTEM_TOOL_DIRS.join(":"), LC_ALL: "C", TZ: "UTC" });
61
+ /** The `ps` a start is read with → { file, name } | { reason }: the system one, or the file the
62
+ * test seam names by absolute path, run directly (no shell). A seam that names neither is never a
63
+ * fallback to /proc or to a `ps` found on PATH; nor is a named file that cannot be run (readStart). */
64
+ function psProgram() {
65
+ const seam = process.env.OATS_TEST_PROCESS_START_PS;
66
+ if (seam === undefined || seam === "1") return { file: "ps", name: "ps" };
67
+ if (isAbsolute(seam)) return { file: seam, name: `the ps OATS_TEST_PROCESS_START_PS names (${seam})` };
68
+ return { reason: `OATS_TEST_PROCESS_START_PS is ${JSON.stringify(seam)}, neither 1 nor an absolute path` };
69
+ }
70
+
71
+ /** Whether `pid` exists, from the kernel itself: kill(pid, 0). ESRCH is gone; EPERM (another user's
72
+ * process) and success are "exists"; anything else is unknown. Never from how procfs or `ps`
73
+ * word an absence: macOS's `ps` answers a pid that does not exist with an error and exit 1, which
74
+ * says nothing a failing `ps` does not also say. */
75
+ export function existence(pid) {
76
+ try { process.kill(pid, 0); return { state: "exists" }; }
77
+ catch (e) {
78
+ if (e.code === "ESRCH") return { state: "gone" };
79
+ if (e.code === "EPERM") return { state: "exists" };
80
+ return { state: "unknown", reason: `kill(${pid}, 0) failed (${e.code || e.message})` };
81
+ }
82
+ }
83
+
84
+ /** Run the system `ps` once: `ps -o <column>= … <selection>`, each column without its header.
85
+ * → { out } — its stdout as it was written, when it exited 0 and answered something;
86
+ * → { reason } — it could not be run, was ended, failed or answered nothing: one line saying which.
87
+ * The one way the kernel calls `ps` (awebai/oats#870, #882): the program (psProgram), the fixed
88
+ * environment (PS_ENV), the time it is given and how its answer is classified are decided here.
89
+ * `selection` is the rest of its arguments (`["-p", "<pid>"]`, `["-ax"]`). The environment is
90
+ * PS_ENV whoever calls: what `ps` answers under it is the same for every reader. `path`, when
91
+ * given, is the PATH the program is found on, in place of PS_ENV's and of nothing else in it: an
92
+ * explicit argument, never read from the caller's environment here. The start reader passes
93
+ * none, so the caller's PATH never chooses the program an identity is read with (#878). */
94
+ export function runPs(columns, selection, { path } = {}) {
95
+ const ps = psProgram();
96
+ if (ps.reason) return { reason: ps.reason };
97
+ const argv = [...columns.flatMap((column) => ["-o", `${column}=`]), ...selection];
98
+ const r = spawnSync(ps.file, argv, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: path === undefined ? PS_ENV : { ...PS_ENV, PATH: path }, timeout: 10_000, maxBuffer: 4 * 1024 * 1024 });
99
+ if (r.error) return { reason: `${ps.name} could not be run (${r.error.code || r.error.message})` };
100
+ const out = String(r.stdout ?? ""), err = String(r.stderr ?? "").trim();
101
+ if (r.status === 0 && out.trim()) return { out };
102
+ return { reason: `ps ${argv.join(" ")} answered ${r.status === null ? `signal ${r.signal}` : `exit ${r.status}`}${err ? `: ${err.split("\n")[0]}` : out.trim() ? " with output" : " with no output"}` };
103
+ }
104
+
105
+ /** The start of a pid that exists, and whether it is a zombie (it exited, or was killed, and its
106
+ * parent has not reaped it): one read gives both.
107
+ * Linux: /proc/<pid>/stat, field 22 (clock ticks since boot) and field 3 (its state: `Z`, or `X`,
108
+ * a process being removed). Elsewhere `ps -o lstart= -o stat=` (runPs): the start, then a state
109
+ * that begins with `Z` (procps `Z`, macOS `Z` and `Z+`).
110
+ * → { state: "alive", token, zombie? } | { state: "unknown", reason }. `zombie` is set only when
111
+ * it is true. A state that cannot be read makes no zombie, and the start is what it was before
112
+ * there was a second column: whatever `ps` prints as a state (`?` included) is only ever cut off
113
+ * the start, and a `ps` that answers the start alone gives the start.
114
+ * The token is what released kernels recorded, byte for byte (`proc:<ticks>`, `ps:<lstart>`): a
115
+ * claim, a tree record or a marker written by an older kernel names its live holder by it, and a
116
+ * reader that gave that holder another token would take it for a reused pid, which is gone. */
117
+ function readStart(pid) {
118
+ if (readsProc()) {
119
+ let stat;
120
+ try { stat = readFileSync(`/proc/${pid}/stat`, "utf8"); }
121
+ catch (e) { return { state: "unknown", reason: `/proc/${pid}/stat could not be read (${e.code || e.message})` }; }
122
+ // comm (field 2) is in parentheses and may hold spaces or parentheses itself.
123
+ const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
124
+ const start = fields[19]; // field 22 overall: after pid, comm and the 19 before it
125
+ if (!/^[0-9]+$/.test(start ?? "")) return { state: "unknown", reason: `/proc/${pid}/stat has no start time` };
126
+ return { state: "alive", token: `proc:${start}`, ...(fields[0] === "Z" || fields[0] === "X" ? { zombie: true } : {}) };
127
+ }
128
+ const r = runPs(["lstart", "stat"], ["-p", String(pid)]);
129
+ if (r.reason) return { state: "unknown", reason: r.reason };
130
+ // `Thu Jan 1 00:00:00 2026 Ss`: the state is the last field, one word whatever it says, and the
131
+ // start before it is taken whole, as `ps -o lstart=` alone prints it. A start ends with its year,
132
+ // so a last field of digits only is the start's own: that `ps` answered no state.
133
+ const out = r.out.trim();
134
+ const column = /^(.*\S)\s+(\S+)$/s.exec(out);
135
+ if (!column || /^[0-9]+$/.test(column[2])) return { state: "alive", token: `ps:${out}` };
136
+ return { state: "alive", token: `ps:${column[1]}`, ...(column[2].startsWith("Z") ? { zombie: true } : {}) };
137
+ }
138
+
139
+ /** Whether `token` has a shape readStart writes: `proc:` and a count of clock ticks (64 bits: at
140
+ * most 20 digits), or `ps:` and a start as `ps -o lstart=` prints it under PS_ENV
141
+ * (`Thu Jan 1 00:00:00 2026`). The shape is said here, beside its writer, and nowhere else.
142
+ * It decides only what of a record may be SHOWN: a record is a file that others than its writer
143
+ * can write, and text that is not the kernel's enters an answer only as an id or a code. It is
144
+ * never a liveness decision: processLiveness compares the recorded string as it is, and a real
145
+ * token this does not know (a `ps` that prints a start otherwise) is shown as none, never read
146
+ * as gone. */
147
+ const START_TOKEN = /^(?:proc:[0-9]{1,20}|ps:[A-Z][a-z]{2} [A-Z][a-z]{2} [ 0-9][0-9] [0-9]{2}:[0-9]{2}:[0-9]{2} [0-9]{4})$/;
148
+ export const isStartToken = (token) => typeof token === "string" && START_TOKEN.test(token);
149
+
150
+ /** When `pid` started, read three ways apart (lessons/observation-must-not-harm-the-observer.md:
151
+ * "absent" never collapses with "unreadable"). One rule on every host: whether the pid exists is
152
+ * the kernel's answer (existence), and only a pid that exists has its start read.
153
+ * → { state: "alive", token, zombie? } — an opaque token for its start; two processes that held
154
+ * one pid at different times never share it, so a pid is only ever compared WITH its token;
155
+ * → { state: "gone" } — kill(pid, 0) answers ESRCH, before the read or (it exited in between)
156
+ * after a read that failed;
157
+ * → { state: "unknown", reason } — anything else: the pid exists and its start could not be read,
158
+ * or kill(pid, 0) failed otherwise. Every caller fails safe on it.
159
+ *
160
+ * This answers WHOSE the pid is, and a zombie still holds its pid and its start: it is "alive"
161
+ * here, with `zombie: true` as a fact beside it. That is what a recorded process group needs
162
+ * (terminateRecordedGroup): while its leader is a zombie the group's id cannot be reused, so a
163
+ * zombie leader with the recorded start is the best proof there is that the group is still that
164
+ * run's, and its members are ended. Whether a process can still ACT is another question, and
165
+ * processLiveness answers it (awebai/oats#870). */
166
+ export function processStart(pid) {
167
+ if (!Number.isSafeInteger(pid) || pid <= 0) return { state: "gone" };
168
+ const before = existence(pid);
169
+ if (before.state !== "exists") return before;
170
+ const read = readStart(pid);
171
+ if (read.state === "alive") return read;
172
+ return existence(pid).state === "gone" ? { state: "gone" } : read;
173
+ }
174
+
175
+ /** The token of `processStart(pid)` when it is running, else null: for recording a process. A
176
+ * liveness decision never uses this, since null merges "gone" with "unknown" (processLiveness). */
177
+ export function processStartToken(pid) {
178
+ const s = processStart(pid);
179
+ return s.state === "alive" ? s.token : null;
180
+ }
181
+
182
+ /** Whether the COMMAND a record names (`{ pid, processStart }`) can still act:
183
+ * → { state: "alive" } — its pid runs with the recorded start;
184
+ * → { state: "gone", zombie? } — its pid does not run, or runs with another start (a reused pid),
185
+ * or is a zombie (`zombie: true`): it exited or was killed and its parent has not reaped it;
186
+ * → { state: "unknown", reason } — the start could not be read, or the record has none to
187
+ * compare while its pid runs. Every caller fails safe on it: nothing is taken over, rolled back,
188
+ * retired or signalled, and the refusal names the way out.
189
+ *
190
+ * A zombie is gone here (awebai/oats#870), though processStart still reads its pid and start. It
191
+ * will never run again, and a parent that never waits for it would otherwise keep its claim or
192
+ * marker refused for ever, with the advice to wait for it. Taking over from it is as safe as from
193
+ * a holder that was killed and reaped: a process's children are re-parented when it exits, not
194
+ * when it is reaped, so what a zombie leaves behind is exactly what that holder leaves: the steps
195
+ * it recorded, which each takeover ends (lib/claim.mjs `endHolderStep`; the hook group of a tree
196
+ * record or a spawn's marker), and for a retire its hook children (awebai/oats#865). The zombie
197
+ * adds nothing to that; it only delays the takeover until a reap that may never come.
198
+ * It is decided before the start is compared: a pid that is a zombie now is not a running
199
+ * holder whichever start the record names (it is that holder, or the pid was reused), and so
200
+ * neither when the record names none.
201
+ *
202
+ * WHOM THIS MAY BE ASKED ABOUT: the process of an `oats` command itself, which is what every
203
+ * record read with it names (a claim's holder, the adder of a tree record, a spawn's `inProgress`,
204
+ * a self-retire's completion). That is what makes "a zombie cannot act" true. On Linux a process
205
+ * whose main thread has exited while other threads run also reads `Z` in /proc/<pid>/stat, and
206
+ * it still acts; Node exits as a whole, so it does not arise for those records. Never ask this
207
+ * about a hook's or a harness's pid: for a process that is not the kernel's own, a `Z` does not
208
+ * say it is finished. (A recorded group's leader is asked through processStart, not through this.) */
209
+ export function processLiveness(record) {
210
+ const pid = record?.pid;
211
+ if (!Number.isSafeInteger(pid) || pid <= 0) return { state: "gone" };
212
+ const s = processStart(pid);
213
+ if (s.state !== "alive") return s;
214
+ if (s.zombie) return { state: "gone", zombie: true };
215
+ if (typeof record.processStart !== "string" || !record.processStart) return { state: "unknown", reason: `pid ${pid} runs, and the record names no start time to compare it with` };
216
+ return s.token === record.processStart ? { state: "alive" } : { state: "gone" };
217
+ }
218
+
219
+ // ---------- the boot a record was taken in ----------
220
+
221
+ /** What says this process runs in a container: a file each runtime puts in its containers, or the
222
+ * variable Kubernetes sets in every pod. Docker writes `/.dockerenv`, Podman `/run/.containerenv`. */
223
+ const CONTAINER_FILES = ["/.dockerenv", "/run/.containerenv"];
224
+ const inContainer = (exists, env) => CONTAINER_FILES.some((file) => exists(file)) || Boolean(env.KUBERNETES_SERVICE_HOST);
225
+
226
+ /** When PID 1 started, as this process sees PID 1: field 22 of `/proc/1/stat`, in clock ticks after
227
+ * the kernel's boot, as the digits the kernel printed; null when the file cannot be read or does
228
+ * not hold it. The fields are counted after the last ")": the name (field 2) may hold spaces and
229
+ * parentheses. */
230
+ function initStart(read) {
231
+ try {
232
+ const stat = read("/proc/1/stat"), named = stat.lastIndexOf(")");
233
+ const start = named < 0 ? undefined : stat.slice(named + 1).trim().split(/\s+/)[19];
234
+ return typeof start === "string" && /^\d+$/.test(start) ? start : null;
235
+ } catch { return null; }
236
+ }
237
+
238
+ /** macOS's boot time, from the system's sysctl (systemTool), never one the caller's PATH names: a
239
+ * PATH without /usr/sbin, or with another sysctl first, must not change or lose the boot id. */
240
+ function systemSysctl() {
241
+ const tool = systemTool("sysctl");
242
+ if (!tool.file) throw new Error(tool.reason);
243
+ return execFileSync(tool.file, ["-n", "kern.boottime"], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] });
244
+ }
245
+ /** This boot's identity, or null where the kernel cannot read one. A boot is what ends every
246
+ * process the kernel may have recorded: the sessions, their terminal server, a sweep.
247
+ * - macOS: the boot time (`sysctl -n kern.boottime`, its `sec`/`usec`).
248
+ * - Linux: the kernel's boot id (`/proc/sys/kernel/random/boot_id`).
249
+ * - Linux in a container (inContainer): `<boot id>:<PID 1's start>`. A container shares its
250
+ * host's kernel and so its boot id, which outlives a stop and start of the container; its PID 1
251
+ * does not. PID 1 starts once per run of the container and ends every process of the run when
252
+ * it ends, so its start is the same for every process of one run and another in the next; the
253
+ * boot id keeps a start apart from the same number of ticks after another kernel boot. When
254
+ * PID 1's start cannot be read there, the boot id alone: the sweep then counts a home's starts
255
+ * across the runs and applies the in-boot clause across them, so it starts less, never more.
256
+ * PID 1's start is read only in a container. A process in a PID namespace of its own on a host (a
257
+ * command a harness runs in a sandbox) reads that namespace's PID 1, which is not the machine's,
258
+ * and it is on the host's boot all the same.
259
+ * Each is read from the kernel without privileges and written nowhere. */
260
+ export function bootId({ platform = process.platform, read = (p) => readFileSync(p, "utf8"), exists = existsSync, env = process.env, sysctl = systemSysctl } = {}) {
261
+ try {
262
+ if (platform === "linux") {
263
+ const id = read("/proc/sys/kernel/random/boot_id").trim();
264
+ if (!id) return null;
265
+ const start = inContainer(exists, env) ? initStart(read) : null;
266
+ return start === null ? id : `${id}:${start}`;
267
+ }
268
+ if (platform === "darwin") { const m = /sec = (\d+), usec = (\d+)/.exec(sysctl()); return m ? `${m[1]}.${m[2]}` : null; }
269
+ } catch { /* unknown */ }
270
+ return null;
271
+ }
272
+ let processBoot;
273
+ /** bootId, read once per process: a process never outlives its boot. */
274
+ export const thisBoot = () => (processBoot === undefined ? (processBoot = bootId()) : processBoot);
275
+ /** Whether the lock record `holder` (the sweep's lock, a cache write lock: lib/remote.mjs) was taken
276
+ * in another boot than `boot`: its holder is gone then, whatever its pid reads as. A boot ends
277
+ * every process, and a pid and a start counted from the boot can both come again in the next (in a
278
+ * container, a boot is one run: bootId). Without a boot id on either side the process alone is
279
+ * judged. */
280
+ export const takenInAnotherBoot = (boot) => (holder) => Boolean(boot) && typeof holder.bootId === "string" && holder.bootId !== "" && holder.bootId !== boot;
281
+
282
+ /** Whether a lock record names the boot it was taken in or its holder's start (`bootId`,
283
+ * `processStart`), whatever their values. */
284
+ export const namesIdentity = (holder) => "bootId" in holder || "processStart" in holder;
285
+
286
+ /** Whether `pid` is a process ID: a positive integer a process can have. Zero and a negative number
287
+ * name a process group to kill(2), never a process. */
288
+ export function validPid(pid) { return Number.isInteger(pid) && pid > 0 && pid <= 2147483647; }
289
+
290
+ /** The state of the holder a lock record names → "gone" | "alive" | "unknown". The one place the
291
+ * rule is composed, for a cache write lock (lib/remote.mjs ownerGone) and the turn record's
292
+ * capture and stream locks (lock-holder.mjs holderLiveness):
293
+ * - a record whose pid is no process ID (validPid) is unknown, whatever else it names, and
294
+ * nothing is read: it proves nothing about a process;
295
+ * - a record that names its identity (namesIdentity) is gone when taken in another boot
296
+ * (takenInAnotherBoot), and has its process's state otherwise (processLiveness): gone when its
297
+ * pid is gone, runs with another start (a reused pid) or is a zombie; unknown when its start
298
+ * cannot be read, or when it names none while its pid runs;
299
+ * - a record that names neither is judged by its pid alone (existence): alive when the pid
300
+ * exists, another user's too, and unknown when that cannot be read (kill answers neither
301
+ * ESRCH nor EPERM).
302
+ * Only "gone" lets a caller take a lock over: "unknown" is waited for or refused, as "alive" is.
303
+ * A claim's holder is judged by lib/claim.mjs holderLiveness, which takes its caller's own
304
+ * `holderGone`. `boot`, `liveness` and `exists` are seams for tests. */
305
+ export function identityHolderState(holder, { boot = thisBoot(), liveness = processLiveness, exists = existence } = {}) {
306
+ if (!validPid(holder?.pid)) return "unknown";
307
+ if (namesIdentity(holder)) return takenInAnotherBoot(boot)(holder) ? "gone" : liveness(holder).state;
308
+ const { state } = exists(holder.pid);
309
+ return state === "exists" ? "alive" : state;
310
+ }
@@ -21,7 +21,6 @@ import {
21
21
  fsyncSync,
22
22
  ftruncateSync,
23
23
  linkSync,
24
- mkdirSync,
25
24
  openSync,
26
25
  opendirSync,
27
26
  readdirSync,
@@ -34,6 +33,8 @@ import {
34
33
  } from "node:fs";
35
34
  import { DerivedState, fileVersion, sameVersion, invalidateLegacyMaps } from "./derived-state.mjs";
36
35
  import { captureContext } from "./capture-context.mjs";
36
+ import { holderIdentity, holderLiveness, namesIdentity } from "./lock-holder.mjs";
37
+ import { PRIVATE_FILE, makePrivateDir } from "./private-files.mjs";
37
38
  import { randomBytes } from "node:crypto";
38
39
  import { hostname } from "node:os";
39
40
  import { join } from "node:path";
@@ -150,7 +151,8 @@ export function parseJournal(input) {
150
151
  // ----------------------------------------------------------- stream lock
151
152
  //
152
153
  // The per-stream lock is an exclusive-create lockfile carrying an OWNER
153
- // TOKEN: the creating process's pid, its hostname, and a random nonce.
154
+ // TOKEN: the creating process's pid, its hostname, a random nonce, and the
155
+ // boot and process start its holder is judged by (`bootId`, `processStart`).
154
156
  // Two properties follow from the token that a bare lockfile cannot give:
155
157
  //
156
158
  // - staleness is judged against the HOLDER'S LIVENESS, not the lock's
@@ -160,20 +162,27 @@ export function parseJournal(input) {
160
162
  // nonce, so a holder whose lock was reclaimed cannot delete the
161
163
  // replacement lock out from under its new owner.
162
164
  //
163
- // Crash recovery is preserved: a lock whose pid is gone from this host is
164
- // provably stale and is reclaimed at once, without waiting out any age.
165
+ // Crash recovery is preserved: a lock whose holder is gone is provably
166
+ // stale and is reclaimed at once, without waiting out any age. A token that
167
+ // names its boot or start is judged by them (lock-holder.mjs
168
+ // holderLiveness), whatever host it names: gone when taken in another boot
169
+ // (a container that is created again), or when its pid is gone or runs with
170
+ // another start (a reused pid). A token that names neither is judged by its
171
+ // pid alone, on this host.
165
172
  //
166
173
  // Age remains the fallback for the two cases where liveness is not
167
- // knowable here: a lock created on another host (file sync can copy one
168
- // in) and a lock with no readable token (written by an older version, or
169
- // by hand).
174
+ // knowable here: a lock that names neither boot nor start and was created
175
+ // on another host (file sync can copy one in) and a lock with no readable
176
+ // token (written by an older version, or by hand).
170
177
 
171
- function newLockToken() {
178
+ // `identity` is the holder's boot and process start (holderIdentity).
179
+ function newLockToken(identity) {
172
180
  return {
173
181
  pid: process.pid,
174
182
  host: hostname(),
175
183
  nonce: randomBytes(12).toString("hex"),
176
184
  acquiredAt: new Date().toISOString(),
185
+ ...identity,
177
186
  };
178
187
  }
179
188
 
@@ -184,7 +193,7 @@ function newLockToken() {
184
193
  function createLock(lockPath, dir, token) {
185
194
  const tmp = join(dir, `.lock.tmp-${token.pid}-${token.nonce}`);
186
195
  try {
187
- writeFileSync(tmp, JSON.stringify(token) + "\n");
196
+ writeFileSync(tmp, JSON.stringify(token) + "\n", { mode: PRIVATE_FILE });
188
197
  try {
189
198
  linkSync(tmp, lockPath);
190
199
  return true;
@@ -238,16 +247,12 @@ function readLock(lockPath) {
238
247
  }
239
248
 
240
249
  // true / false when the holder's liveness is knowable from this process,
241
- // null when it is not (the lock was created on another host). EPERM means
242
- // the process exists and belongs to another user: alive.
250
+ // null when it is not (the token names neither boot nor start, and the lock
251
+ // was created on another host). Only a holder that is proven gone is not
252
+ // alive: one whose liveness cannot be read is waited for.
243
253
  function holderAlive(token) {
244
- if (token.host !== hostname()) return null;
245
- try {
246
- process.kill(token.pid, 0);
247
- return true;
248
- } catch (err) {
249
- return err.code === "ESRCH" ? false : true;
250
- }
254
+ if (!namesIdentity(token) && token.host !== hostname()) return null;
255
+ return holderLiveness(token) !== "dead";
251
256
  }
252
257
 
253
258
  function lockIsProvenStale(held, staleMs) {
@@ -357,9 +362,10 @@ export class RecordStore {
357
362
  return fn();
358
363
  }
359
364
  const dir = join(this.streamsDir(), streamId);
360
- mkdirSync(dir, { recursive: true });
365
+ makePrivateDir(dir);
361
366
  const lockPath = join(dir, ".lock");
362
- const token = newLockToken();
367
+ // This process's start is read once per store: it never changes.
368
+ const token = newLockToken((this.lockIdentity ??= holderIdentity(process.pid)));
363
369
  const deadline = Date.now() + this.lockTimeoutMs;
364
370
  // Every iteration that fails to acquire falls through to ONE deadline
365
371
  // check and one sleep — there is deliberately no `continue` above them,
@@ -664,7 +670,7 @@ export class RecordStore {
664
670
  let chunk = [], chunkBytes = 0, appended = 0;
665
671
  const flush = () => {
666
672
  if (!chunk.length) return;
667
- appendFileSync(path, chunk.join("\n") + "\n");
673
+ appendFileSync(path, chunk.join("\n") + "\n", { mode: PRIVATE_FILE });
668
674
  chunk = []; chunkBytes = 0;
669
675
  };
670
676
  // A failed transaction can leave appended journal bytes. Its old version
@@ -702,9 +708,9 @@ export class RecordStore {
702
708
  const digest = sha256Hex(bytes);
703
709
  const path = this.objectPath(digest);
704
710
  if (!existsSync(path)) {
705
- mkdirSync(join(this.root, "objects", "sha256", digest.slice(0, 2)), { recursive: true });
711
+ makePrivateDir(join(this.root, "objects", "sha256", digest.slice(0, 2)));
706
712
  const tmp = path + ".tmp-" + process.pid;
707
- writeFileSync(tmp, bytes);
713
+ writeFileSync(tmp, bytes, { mode: PRIVATE_FILE });
708
714
  renameSync(tmp, path);
709
715
  }
710
716
  return "sha256:" + digest;
@@ -737,7 +743,7 @@ export class RecordStore {
737
743
  for (let i = 0; i < shorter.length; i++) {
738
744
  if (shorter[i].id !== longer[i].id) {
739
745
  const qPath = join(this.streamsDir(), streamId, `quarantine-${Date.now()}.jsonl`);
740
- writeFileSync(qPath, foreignTurns.map((t) => JSON.stringify(t)).join("\n") + "\n");
746
+ writeFileSync(qPath, foreignTurns.map((t) => JSON.stringify(t)).join("\n") + "\n", { mode: PRIVATE_FILE });
741
747
  throw new StoreError(
742
748
  `non-prefix copies of stream ${streamId}: foreign copy quarantined at ${qPath}`,
743
749
  );
@@ -746,7 +752,7 @@ export class RecordStore {
746
752
  if (longer === local) return { extended: 0 };
747
753
  repairTail(path);
748
754
  const suffix = longer.slice(local.length);
749
- appendFileSync(path, suffix.map((t) => JSON.stringify(t)).join("\n") + "\n");
755
+ appendFileSync(path, suffix.map((t) => JSON.stringify(t)).join("\n") + "\n", { mode: PRIVATE_FILE });
750
756
  syncPath(path);
751
757
  return { extended: suffix.length };
752
758
  });
@@ -353,7 +353,7 @@ On Linux x64, also check the Desktop's system libraries, ALSA and FUSE 2
353
353
  for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -p | grep -q "$l" || echo "MISSING $l"; done
354
354
  ```
355
355
 
356
- - **Versions:** Node 22 or later; Git 2.45 or later recommended (partial
356
+ - **Versions:** Node 22.5 or later; Git 2.45 or later recommended (partial
357
357
  caches; older Git works with whole-tree fetches); `gh` 2.49 or later
358
358
  (step 3 uses `gh attestation`).
359
359
  - **The harness** they chose must be installed and logged in (`claude
@@ -533,7 +533,7 @@ installed CLI's catalog:
533
533
  node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
534
534
  ```
535
535
 
536
- It prints the two refs, for example `oats-framework/v1.23.0 v1.37.0`. If the
536
+ It prints the two refs, for example `oats-framework/v1.24.0 v1.39.0`. If the
537
537
  framework's version (after the `/`) is below `1.19.0`, or with aweb
538
538
  `oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
539
539
  skill: stop, and tell the person to wait for the next OATS
@@ -544,8 +544,11 @@ wakes an agent when mail arrives (skip this without messaging): Claude
544
544
  `claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
545
545
  pi `pi install npm:@awebai/pi`, then its entry in pi's `settings.json` set
546
546
  to load none of the skills it bundles (pi's extension is installed without
547
- its skills, so it puts none on the computer; each agent gets its own);
548
- Codex nothing (the setup expert sets up its wake). Claude's aweb channel
547
+ its skills, so it puts none on the computer; each agent gets its own;
548
+ from 0.5.0 it bundles none, and the setting is harmless, so set it
549
+ whatever the version). Never install `@awebai/claude-skills` in that pi
550
+ folder: its skills would load in every agent there, and each agent gets
551
+ its own skills from OATS. Codex nothing (the setup expert sets up its wake). Claude's aweb channel
549
552
  plugin still carries one skill of its own, until aweb ships it without
550
553
  (a known gap). The pi entry, which matches `npm:@awebai/pi` alone or with
551
554
  `@` and a version, never another `@awebai/pi-…` package, and prints it so
@@ -765,8 +768,8 @@ name: acme
765
768
  members:
766
769
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
767
770
  packages:
768
- oats.framework: v1.23.0 # the installed CLI's catalog versions (below)
769
- oats.aweb: v1.37.0 # messaging: agent identities, mail and chat
771
+ oats.framework: v1.24.0 # the installed CLI's catalog versions (below)
772
+ oats.aweb: v1.39.0 # messaging: agent identities, mail and chat
770
773
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
771
774
  defaults:
772
775
  capabilities: