@awebai/oats 0.69.12 → 0.69.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +216 -178
- package/bin/oats.mjs +254 -201
- package/docs/capabilities.md +58 -13
- package/docs/configuration.md +63 -5
- package/docs/container.md +291 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +590 -55
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +84 -9
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +99 -32
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/schedules.md +159 -5
- package/docs/servers.md +241 -7
- package/docs/souls-and-instances.md +223 -14
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +36 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +20 -5
- package/lib/command-flags.mjs +240 -0
- package/lib/core.mjs +1004 -633
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +145 -33
- package/lib/errors.mjs +3 -2
- package/lib/harness-token.mjs +110 -0
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +165 -14
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +114 -43
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/kernel-features.mjs +4 -1
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +4 -1
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +126 -31
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +239 -21
- package/lib/servers.mjs +161 -28
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +63 -56
- package/lib/session-seen.mjs +3 -14
- package/lib/start-env.mjs +13 -7
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +68 -10
- package/package-catalog.json +1 -1
- package/package.json +5 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +93 -26
- package/lib/tmux-config.mjs +0 -35
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
// The record store holds agents' conversations, so what it creates is for its
|
|
2
|
+
// owner alone: files 0600, directories 0700. A mode applies when the file or
|
|
3
|
+
// directory is created; one that exists keeps the permissions it has.
|
|
4
|
+
import { closeSync, mkdirSync, openSync } from "node:fs";
|
|
5
|
+
|
|
6
|
+
export const PRIVATE_FILE = 0o600;
|
|
7
|
+
export const PRIVATE_DIR = 0o700;
|
|
8
|
+
|
|
9
|
+
/** Create `path` and its missing ancestors, each private. */
|
|
10
|
+
export function makePrivateDir(path) {
|
|
11
|
+
mkdirSync(path, { recursive: true, mode: PRIVATE_DIR });
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/** Create `path` as an empty private file when it is absent, for an opener
|
|
15
|
+
* that takes no mode (SQLite, whose journal files take the database's). */
|
|
16
|
+
export function ensurePrivateFile(path) {
|
|
17
|
+
closeSync(openSync(path, "a", PRIVATE_FILE));
|
|
18
|
+
}
|
|
@@ -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,
|
|
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
|
|
164
|
-
//
|
|
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
|
|
168
|
-
// in) and a lock with no readable
|
|
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
|
-
|
|
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
|
|
242
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
365
|
+
makePrivateDir(dir);
|
|
361
366
|
const lockPath = join(dir, ".lock");
|
|
362
|
-
|
|
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
|
-
|
|
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
|
});
|