@awebai/oats 0.49.0 → 0.51.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.
@@ -17,7 +17,7 @@
17
17
  * is a test seam, not a setting. */
18
18
  import { spawn as spawnProcess, execFileSync, spawnSync } from "node:child_process";
19
19
  import { closeSync, existsSync, fchmodSync, mkdirSync, openSync, readFileSync, realpathSync, writeSync } from "node:fs";
20
- import { dirname, join } from "node:path";
20
+ import { dirname, isAbsolute, join } from "node:path";
21
21
  import { terminateGroup, watchGroup, TERM_GRACE_MS } from "./process-group.mjs";
22
22
 
23
23
  export const WORKTREE_HOOK_TIMEOUT_MS = 30 * 60 * 1000;
@@ -36,12 +36,25 @@ export const interruptExitStatus = (signal) => 128 + (SIGNAL_NUMBERS[signal] ??
36
36
  // ---------- process identity: a pid is verified by its start time ----------
37
37
 
38
38
  /** Where a start time is read: /proc when this host has procfs, else `ps`. The test seam
39
- * OATS_TEST_PROCESS_START_PS=1 (not a setting) takes the `ps` path on a host with procfs. */
40
- const readsProc = () => process.env.OATS_TEST_PROCESS_START_PS !== "1" && existsSync("/proc/self/stat");
41
- /** `ps` runs with a fixed environment, nothing inherited: `lstart` is local time in the locale's
42
- * format, and two readers with another TZ or LANG would otherwise read one live process's start
43
- * differently, and take it for another. */
44
- const psEnv = () => ({ PATH: process.env.PATH ?? "/usr/bin:/bin", LC_ALL: "C", TZ: "UTC" });
39
+ * OATS_TEST_PROCESS_START_PS (not a setting; a launch configuration cannot set it) takes the `ps`
40
+ * path on any host: `1` runs the system `ps`, an absolute path runs that file as `ps`, and any
41
+ * other value reads no start at all (psProgram). */
42
+ const readsProc = () => process.env.OATS_TEST_PROCESS_START_PS === undefined && existsSync("/proc/self/stat");
43
+ /** `ps` runs with a fixed environment, nothing inherited. Its PATH is the system directories only,
44
+ * never the caller's: what `ps` reports is the identity a claim is held or taken over on, so the
45
+ * caller's PATH must not choose the program, and a caller whose PATH holds no `ps` reads the same
46
+ * start as any other. `lstart` is local time in the locale's format, and two readers with another
47
+ * TZ or LANG would otherwise read one live process's start differently, and take it for another. */
48
+ const PS_ENV = Object.freeze({ PATH: "/usr/bin:/bin", LC_ALL: "C", TZ: "UTC" });
49
+ /** The `ps` a start is read with → { file, name } | { reason }: the system one, or the file the
50
+ * test seam names by absolute path, run directly (no shell). A seam that names neither is never a
51
+ * fallback to /proc or to a `ps` found on PATH; nor is a named file that cannot be run (readStart). */
52
+ function psProgram() {
53
+ const seam = process.env.OATS_TEST_PROCESS_START_PS;
54
+ if (seam === undefined || seam === "1") return { file: "ps", name: "ps" };
55
+ if (isAbsolute(seam)) return { file: seam, name: `the ps OATS_TEST_PROCESS_START_PS names (${seam})` };
56
+ return { reason: `OATS_TEST_PROCESS_START_PS is ${JSON.stringify(seam)}, neither 1 nor an absolute path` };
57
+ }
45
58
 
46
59
  /** Whether `pid` exists, from the kernel itself: kill(pid, 0). ESRCH is gone; EPERM (another user's
47
60
  * process) and success are "exists"; anything else is unknown. Never from how procfs or `ps`
@@ -68,9 +81,11 @@ function readStart(pid) {
68
81
  const start = fields[19]; // field 22 overall: after pid, comm and the 19 before it
69
82
  return /^[0-9]+$/.test(start ?? "") ? { state: "alive", token: `proc:${start}` } : { state: "unknown", reason: `/proc/${pid}/stat has no start time` };
70
83
  }
71
- const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: psEnv(), timeout: 10_000 });
84
+ const ps = psProgram();
85
+ if (ps.reason) return { state: "unknown", reason: ps.reason };
86
+ const r = spawnSync(ps.file, ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: PS_ENV, timeout: 10_000 });
72
87
  const out = String(r.stdout ?? "").trim(), err = String(r.stderr ?? "").trim();
73
- if (r.error) return { state: "unknown", reason: `ps could not be run (${r.error.code || r.error.message})` };
88
+ if (r.error) return { state: "unknown", reason: `${ps.name} could not be run (${r.error.code || r.error.message})` };
74
89
  if (r.status === 0 && out) return { state: "alive", token: `ps:${out}` };
75
90
  return { state: "unknown", reason: `ps -o lstart= -p ${pid} answered ${r.status === null ? `signal ${r.signal}` : `exit ${r.status}`}${err ? `: ${err.split("\n")[0]}` : out ? " with output" : " with no output"}` };
76
91
  }
package/lib/worktree.mjs CHANGED
@@ -27,8 +27,8 @@ import { recordedTeams } from "./teams.mjs";
27
27
  import { canonicalCloneKey, memberCloneOf } from "./instance-resolution.mjs";
28
28
  import { loadLocal } from "./workspace.mjs";
29
29
  import { GIT_FETCH_TIMEOUT_MS } from "./remote.mjs";
30
- import { randomBytes } from "node:crypto";
31
30
  import { terminateGroup, watchGroup } from "./process-group.mjs";
31
+ import { CLAIM_WAIT_MS, acquireClaim, recordInClaim, releaseClaim } from "./claim.mjs";
32
32
  import {
33
33
  cloneOfMember, instanceSoulDir, isCapturedHome, isWorkspaceHome, capturedHomeRefusal, preWorkspaceHome, lifecycleHookEnv,
34
34
  retirePendingMarkerPath, stableSoulId, workspaceOf,
@@ -348,101 +348,29 @@ function withPurposeClaim(home, purpose, fn) {
348
348
  return withClaim(lock, fn, { busy });
349
349
  }
350
350
 
351
- const CLAIM_WAIT_MS = 3000;
352
- const CLAIM_MAX_DEPTH = 8;
353
- const pauseSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
354
- function readClaim(path) {
355
- try { const o = JSON.parse(readFileSync(path, "utf8")); return o && typeof o === "object" ? o : { unreadable: true }; }
356
- catch (e) { return e.code === "ENOENT" ? null : { unreadable: true }; }
357
- }
358
-
359
- /** Run `fn` holding the claim file `path`. Exported for its tests.
351
+ /** Run `fn` holding the claim file `path` (lib/claim.mjs: how a claim is taken, taken over from a
352
+ * dead holder and released). Exported for its tests.
360
353
  *
361
- * - Taking it: the owner's facts `{ pid, processStart, nonce }` are written to a private file and
362
- * hard-linked to `path`, which fails if `path` exists. So a claim is never seen without its
363
- * owner, and the nonce makes each holding distinct, even for the same process.
364
- * - Its owner is gone (processLiveness "gone"; "unknown" is refused, never taken over): the claim
365
- * is removed under a second claim,
366
- * `<path>.reclaim-<owner nonce>`, taken by this same protocol. Its holder re-reads `path` and
367
- * removes it only if it still names that owner. Nothing else removes another's claim: its
368
- * owner never releases it, and a new acquirer cannot write over an existing file. Two takeovers
369
- * of one dead owner are therefore serialized, and neither removes a claim made after it read.
370
- * A takeover cut short leaves its own claim behind, which the next takeover takes over in
371
- * turn, up to CLAIM_MAX_DEPTH nested levels.
372
- * - The holder's running git step (`gitPid`, `gitStart`; trackedGit) is in the claim. A takeover
373
- * ends it first (endRecordedGit) and refuses, keeping the claim, if it cannot be ended.
374
- * - Released by unlinking `path`, only while it still names this holding.
375
- * - An unreadable claim file is never removed: the command is refused as busy, naming the file. */
354
+ * The holder's running git step (`gitPid`, `gitStart`; trackedGit) is in the claim. A takeover
355
+ * ends it first (endRecordedGit) and refuses, keeping the claim, if it cannot be ended.
356
+ * `fn({ track, warnings })`; → Promise of what `fn` returns. An error with `keepClaim` leaves the
357
+ * claim held, for the step it names. */
376
358
  export async function withClaim(path, fn, { busy, waitMs = CLAIM_WAIT_MS } = {}) {
377
359
  const warnings = [];
378
- const me = acquireClaim(path, { busy, waitMs, warnings }, 0);
360
+ const me = acquireClaim(path, {
361
+ busy, waitMs, warnings,
362
+ ownStartUnreadable: (_reason, at) => Object.assign(busy(null), { message: `this process's start time cannot be read, so it cannot hold ${at} verifiably; nothing was done` }),
363
+ unreadableClaim: (at) => Object.assign(busy(null), { message: `${at} is not a readable claim; inspect it and remove it if no oats worktree command holds it; nothing was done` }),
364
+ endHolderStep: (holder, at) => ({ ...endRecordedGit(holder, at), details: { gitPid: holder.gitPid, gitStart: holder.gitStart ?? null } }),
365
+ });
379
366
  // Record (or clear) the holder's running git step in the claim; only its live holder writes it.
380
- const track = (gitStep) => {
381
- const tmp = `${path}.tmp-${process.pid}-${me.nonce}`;
382
- writeFileSync(tmp, JSON.stringify({ ...me, ...(gitStep ?? {}) }) + "\n", { mode: 0o600 });
383
- renameSync(tmp, path);
384
- };
367
+ const track = (gitStep) => recordInClaim(path, me, gitStep);
385
368
  let keep = false;
386
369
  try { return await fn({ track, warnings }); }
387
370
  catch (e) { keep = e?.keepClaim === true; throw e; }
388
371
  finally { if (!keep) releaseClaim(path, me); }
389
372
  }
390
373
 
391
- function acquireClaim(path, opts, depth) {
392
- const { busy, waitMs } = opts;
393
- const self = selfIdentity();
394
- if (!self.processStart) throw Object.assign(busy(null), { message: `this process's start time cannot be read, so it cannot hold ${path} verifiably; nothing was done` });
395
- const me = { ...self, nonce: randomBytes(16).toString("hex"), at: new Date().toISOString() };
396
- const tmp = `${path}.tmp-${process.pid}-${me.nonce}`;
397
- writeFileSync(tmp, JSON.stringify(me) + "\n", { mode: 0o600 });
398
- try {
399
- const deadline = Date.now() + waitMs;
400
- for (;;) {
401
- try { linkSync(tmp, path); return me; }
402
- catch (e) { if (e.code !== "EEXIST") throw e; }
403
- const holder = readClaim(path);
404
- if (holder === null) continue; // released in between
405
- if (holder.unreadable) throw Object.assign(busy(null), { message: `${path} is not a readable claim; inspect it and remove it if no oats worktree command holds it; nothing was done` });
406
- const live = processLiveness(holder);
407
- // Unreadable is never taken for gone: the claim is kept, and the refusal names the way out.
408
- if (live.state === "unknown") throw busy(holder, live.reason, path);
409
- if (live.state === "gone") {
410
- if (depth >= CLAIM_MAX_DEPTH || typeof holder.nonce !== "string" || !/^[0-9a-f]{32}$/.test(holder.nonce)) throw busy(holder, null, path);
411
- takeOver(path, holder, opts, depth);
412
- continue;
413
- }
414
- if (Date.now() >= deadline) throw busy(holder, null, path);
415
- pauseSync(50);
416
- }
417
- } finally {
418
- try { unlinkSync(tmp); } catch { /* gone */ }
419
- }
420
- }
421
-
422
- /** Remove `path`, held by the dead `holder`, under the claim that serializes takeovers of it. */
423
- function takeOver(path, holder, opts, depth) {
424
- const reclaim = `${path}.reclaim-${holder.nonce}`;
425
- const me = acquireClaim(reclaim, opts, depth + 1);
426
- try {
427
- const now = readClaim(path);
428
- if (now?.nonce === holder.nonce) {
429
- const ended = endRecordedGit(now, path);
430
- if (ended.owed) {
431
- const e = opts.busy(now);
432
- throw Object.assign(e, { message: `${ended.owed}; ${path} is kept and nothing was done — ${ended.remedy}`, details: { ...e.details, gitPid: now.gitPid, gitStart: now.gitStart ?? null } });
433
- }
434
- if (ended.warning) opts.warnings?.push(ended.warning);
435
- unlinkSync(path);
436
- }
437
- } finally {
438
- releaseClaim(reclaim, me);
439
- }
440
- }
441
-
442
- function releaseClaim(path, me) {
443
- if (readClaim(path)?.nonce === me.nonce) { try { unlinkSync(path); } catch { /* gone */ } }
444
- }
445
-
446
374
  /** A `creating` record whose adder may still run: its start cannot be read. Never rolled back on
447
375
  * that; the refusal names the pid and the record's exact path, the way out once the pid is
448
376
  * checked by hand. */
@@ -3,12 +3,12 @@
3
3
  "packages": {
4
4
  "oats.okf": {
5
5
  "url": "https://github.com/awebai/oats-okf.git",
6
- "ref": "v5.0.0",
6
+ "ref": "v5.0.1",
7
7
  "path": "oats-package"
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.23.2",
11
+ "ref": "v1.24.1",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "oats.framework": {
45
45
  "url": "https://github.com/awebai/oats.git",
46
- "ref": "oats-framework/v1.8.0",
46
+ "ref": "oats-framework/v1.9.1",
47
47
  "path": "oats-package"
48
48
  }
49
49
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.49.0",
3
+ "version": "0.51.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -60,7 +60,7 @@ members:
60
60
  - git:github.com/acme/agents # the host is a member too
61
61
  - git:github.com/acme/platform
62
62
  packages:
63
- oats.framework: v1.8.0 # bare versions resolve through the official catalog
63
+ oats.framework: v1.9.1 # bare versions resolve through the official catalog
64
64
  oats.okf: v4.1.1
65
65
  defaults:
66
66
  capabilities: { oats.core: { from: package } }