@awebai/oats 0.51.0 → 0.52.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 (128) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +109 -37
  3. package/docs/capabilities.md +9 -2
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +927 -92
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +144 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +66 -9
  12. package/docs/integrations.md +9 -8
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/oats-local.schema.json +4 -3
  20. package/docs/official-catalog.md +4 -4
  21. package/docs/packages.md +14 -14
  22. package/docs/release-lane.md +15 -5
  23. package/docs/release-notes/v0.44.0.md +1 -1
  24. package/docs/release-notes/v0.52.0.md +933 -0
  25. package/docs/schedules.md +91 -4
  26. package/docs/souls-and-instances.md +95 -25
  27. package/docs/tui.md +152 -0
  28. package/docs/workspaces.md +2 -2
  29. package/lib/claim.mjs +186 -46
  30. package/lib/core.mjs +730 -185
  31. package/lib/errors.mjs +170 -0
  32. package/lib/harness-trust-write.mjs +68 -27
  33. package/lib/harness-trust.mjs +34 -16
  34. package/lib/instance-inspect.mjs +40 -11
  35. package/lib/instance-lifecycle.mjs +169 -47
  36. package/lib/launch-preference.mjs +16 -0
  37. package/lib/launch-prompt-completion.mjs +7 -43
  38. package/lib/launch-prompt-evidence.mjs +14 -7
  39. package/lib/launch-prompt-fixtures/README.md +86 -152
  40. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  41. package/lib/launch-prompt-fixtures.mjs +122 -109
  42. package/lib/launch-prompt-transport.mjs +2 -56
  43. package/lib/launch-prompts.mjs +102 -100
  44. package/lib/schedule-host.mjs +154 -22
  45. package/lib/schedule.mjs +73 -24
  46. package/lib/system-tools.mjs +39 -0
  47. package/lib/tmux-server-scope.mjs +62 -0
  48. package/lib/triggers.mjs +4 -4
  49. package/lib/workspace.mjs +5 -11
  50. package/lib/worktree-hooks.mjs +98 -20
  51. package/lib/worktree.mjs +83 -24
  52. package/package-catalog.json +3 -3
  53. package/package.json +7 -2
  54. package/packages/client/capability-show-contract.mjs +230 -0
  55. package/packages/client/capability-warnings-contract.mjs +57 -0
  56. package/packages/client/cli-adapter.mjs +548 -0
  57. package/packages/client/cli-environment.mjs +53 -0
  58. package/packages/client/cli-locator.mjs +253 -0
  59. package/packages/client/cli-probe-contract.mjs +47 -0
  60. package/packages/client/client-terms.mjs +60 -0
  61. package/packages/client/deployment-contract.mjs +68 -0
  62. package/packages/client/deployment-data.mjs +483 -0
  63. package/packages/client/deployment-facts.mjs +34 -0
  64. package/packages/client/deployment-label.mjs +76 -0
  65. package/packages/client/deployment-observer.mjs +89 -0
  66. package/packages/client/deployment-panel.mjs +142 -0
  67. package/packages/client/deployment-read-cli.mjs +53 -0
  68. package/packages/client/display-text.mjs +44 -0
  69. package/packages/client/harness-names.mjs +30 -0
  70. package/packages/client/inspect-contract.mjs +62 -0
  71. package/packages/client/instance-acts.mjs +54 -0
  72. package/packages/client/instance-admission.mjs +45 -0
  73. package/packages/client/instance-events-contract.mjs +74 -0
  74. package/packages/client/instance-git-contract.mjs +80 -0
  75. package/packages/client/instance-presentation.mjs +22 -0
  76. package/packages/client/instance-tree.mjs +453 -0
  77. package/packages/client/kernel-environment.mjs +11 -0
  78. package/packages/client/launch-contract.mjs +51 -0
  79. package/packages/client/launch-prompt-outcome.mjs +165 -0
  80. package/packages/client/lifecycle-cli.mjs +61 -0
  81. package/packages/client/lifecycle-contract.mjs +372 -0
  82. package/packages/client/liveness-main.mjs +10 -0
  83. package/packages/client/liveness.mjs +35 -0
  84. package/packages/client/machine-contract.mjs +123 -0
  85. package/packages/client/own-environment.mjs +22 -0
  86. package/packages/client/panel-views.mjs +286 -0
  87. package/packages/client/readiness-contract.mjs +172 -0
  88. package/packages/client/refresh-loop.mjs +52 -0
  89. package/packages/client/remote-address.mjs +126 -0
  90. package/packages/client/remote-roster.mjs +67 -0
  91. package/packages/client/roster-sections.mjs +80 -0
  92. package/packages/client/spawn-apply-cli.mjs +104 -0
  93. package/packages/client/spawn-apply-contract.mjs +183 -0
  94. package/packages/client/spawn-decision.mjs +46 -0
  95. package/packages/client/spawn-messages.mjs +119 -0
  96. package/packages/client/spawn-preview-cli.mjs +32 -0
  97. package/packages/client/spawn-preview-contract.mjs +314 -0
  98. package/packages/client/team-members.mjs +41 -0
  99. package/packages/client/team-rows.mjs +45 -0
  100. package/packages/client/terminal-contract.mjs +57 -0
  101. package/packages/client/tmux-status.mjs +66 -0
  102. package/packages/client/waiting-on-you.mjs +88 -0
  103. package/packages/client/workspace-admission.mjs +45 -0
  104. package/packages/client/workspace-cli.mjs +142 -0
  105. package/packages/client/workspace-views.mjs +147 -0
  106. package/packages/tui/README.md +46 -0
  107. package/packages/tui/bin/tui.mjs +7 -0
  108. package/packages/tui/lib/actions.mjs +29 -0
  109. package/packages/tui/lib/client.mjs +4 -0
  110. package/packages/tui/lib/main.mjs +105 -0
  111. package/packages/tui/lib/term/keys.mjs +323 -0
  112. package/packages/tui/lib/term/screen.mjs +122 -0
  113. package/packages/tui/lib/term/style.mjs +43 -0
  114. package/packages/tui/lib/term/text.mjs +49 -0
  115. package/packages/tui/lib/term/tty.mjs +168 -0
  116. package/packages/tui/lib/term/width.mjs +124 -0
  117. package/packages/tui/lib/views/frame.mjs +62 -0
  118. package/packages/tui/lib/views/help.mjs +28 -0
  119. package/packages/tui/package.json +8 -0
  120. package/skills/oats-getting-started/SKILL.md +29 -22
  121. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  122. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  123. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  124. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  127. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  128. package/lib/launch-prompt-policy.mjs +0 -87
package/lib/triggers.mjs CHANGED
@@ -39,7 +39,7 @@ import { createHash } from "node:crypto";
39
39
  import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
40
40
  import { dirname, join } from "node:path";
41
41
  import { fileURLToPath } from "node:url";
42
- import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath } from "./schedule.mjs";
42
+ import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath, runWarnings } from "./schedule.mjs";
43
43
  import { herdrSettingRemoved } from "./errors.mjs";
44
44
  import { MODEL_RE, SNAPSHOT_MAX_AGE_MS, automationError, baseRow, localEntry, localId, parseOwner, qualifiedId, soulOriginOf, validateDescription } from "./automations.mjs";
45
45
  import { judgeAnswer, pollFailure, triggerSourcesOf } from "./trigger-sources.mjs";
@@ -774,7 +774,7 @@ const isNewEvent = (ts, key) => !ts.fired[key] && !ts.pending[key];
774
774
  const pendingQueue = (ts) => Object.values(ts.pending).map(withSubject).sort((a, b) => a.observedAt.localeCompare(b.observedAt) || a.key.localeCompare(b.key));
775
775
  /** Record a spawned event as fired (only after its spawn succeeded: at least once). */
776
776
  function recordFired(ts, ev, run, now) {
777
- ts.fired[ev.key] = { at: now.toISOString(), instance: run.instance ?? null, home: run.home ?? null, event: ev.event, number: ev.number ?? null, subject: ev.subject };
777
+ ts.fired[ev.key] = { at: now.toISOString(), instance: run.instance ?? null, home: run.home ?? null, event: ev.event, number: ev.number ?? null, subject: ev.subject, ...runWarnings(run) };
778
778
  delete ts.pending[ev.key];
779
779
  ts.lastFiredAt = now.toISOString();
780
780
  }
@@ -882,7 +882,7 @@ export function spawnForEvent(ws, def, ev, io, pv = previewSoul(ws, def, io)) {
882
882
  if (r.timedOut) throw triggerError("E_SPAWN_UNCONFIRMED", "the trigger's spawn timed out; a home may exist (it counts toward concurrency) — the event is retried on the next poll");
883
883
  if (!r.envelope || typeof r.envelope.ok !== "boolean") throw triggerError("E_SPAWN_UNCONFIRMED", `the trigger's spawn answered no envelope (exit ${r.status})${r.stderr ? `: ${r.stderr.trim().split("\n").pop()}` : ""}`);
884
884
  if (!r.envelope.ok) throw triggerError(r.envelope.error?.code || "E_SPAWN_FAILED", String(r.envelope.error?.message || "spawn failed"), { details: r.envelope.error?.details });
885
- return { instance: r.envelope.result?.instance, home: r.envelope.result?.home };
885
+ return { instance: r.envelope.result?.instance, home: r.envelope.result?.home, ...runWarnings(r.envelope.result) };
886
886
  }
887
887
 
888
888
  /** Admission of one pending event against the trigger's concurrency. → null | reason */
@@ -1053,7 +1053,7 @@ function triggerRow(ws, e, st, ctx) {
1053
1053
  const ts = stateFor(st.triggers[e.id], e.definition?.on?.source);
1054
1054
  const fired = Object.entries(ts?.fired || {}).map(([key, f]) => ({ key, ...f })).sort((a, b) => b.at.localeCompare(a.at));
1055
1055
  const pollMs = parsePoll(e.definition?.on?.poll ?? DEFAULT_POLL);
1056
- const lastRun = fired[0] ? { at: fired[0].at, instance: fired[0].instance ?? null, home: fired[0].home ?? null, event: fired[0].event, number: fired[0].number, subject: subjectOf(fired[0]), key: fired[0].key } : null;
1056
+ const lastRun = fired[0] ? { at: fired[0].at, instance: fired[0].instance ?? null, home: fired[0].home ?? null, event: fired[0].event, number: fired[0].number, subject: subjectOf(fired[0]), key: fired[0].key, ...runWarnings(fired[0]) } : null;
1057
1057
  const nextDue = e.placement.runsHere && ts?.lastPollAt && pollMs ? new Date(Date.parse(ts.lastPollAt) + pollMs).toISOString() : null;
1058
1058
  const local = e.member === "local";
1059
1059
  const def = e.definition || {};
package/lib/workspace.mjs CHANGED
@@ -12,7 +12,6 @@
12
12
  */
13
13
  import { readFileSync, existsSync } from "node:fs";
14
14
  import { dirname, join, resolve } from "node:path";
15
- import { launchPromptPolicyProblems } from "./launch-prompt-policy.mjs";
16
15
  import { recordLocalInput } from "./local-inputs.mjs";
17
16
  import { parseConfigData } from "./config-data.mjs";
18
17
  import { oatsError } from "./errors.mjs";
@@ -282,6 +281,11 @@ const REMOVED_KEYS = {
282
281
  local: [
283
282
  { at: (v) => (isObject(v?.souls) && Object.hasOwn(v.souls, "teams") ? ["/souls/teams"] : []), message: "souls.teams was removed in 0.38.0 (team model 3): which teams a soul may join is souls: in oats-workspace.yaml" },
284
283
  { at: (v) => (isObject(v?.souls) && Object.hasOwn(v.souls, "default") ? ["/souls/default"] : []), message: "souls.default was removed in 0.38.0 (team model 3): a soul's default team is souls: in oats-workspace.yaml (default:)" },
284
+ // 0.52.0: launchPromptAnswers is ignored (core.mjs launchPromptAnswersNotice), except an
285
+ // operator's explicit refusal, which this kernel cannot honour and so must not drop silently.
286
+ { at: (v) => (isObject(v?.launchPromptAnswers?.homes) ? Object.entries(v.launchPromptAnswers.homes)
287
+ .filter(([, e]) => isObject(e) && e.awebDevelopmentChannel === false).map(([home]) => `/launchPromptAnswers/homes/${pointerKey(home)}`) : []),
288
+ message: "launchPromptAnswers awebDevelopmentChannel: false cannot be honoured: OATS confirms Claude's development-channel prompt whenever it launches Claude with --dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace. To keep the prompt unanswered, set settings.oats.aweb.delivery: session or settings.oats.aweb.claudeChannelMode: approved in oats-local.yaml, then remove launchPromptAnswers" },
285
289
  ],
286
290
  };
287
291
  function withRemovedKeys(problems, value, removed) {
@@ -339,16 +343,6 @@ export function validateLocal(value) {
339
343
  problems.push({ path: `/launch-configs/${pointerKey(name)}/runtime`, reason: "harness-conflict", message: `harness ${show(entry.harness)} and runtime ${show(entry.runtime)} disagree: \`runtime\` is the pre-0.27 name of \`harness\` — keep one` });
340
344
  }
341
345
  }
342
- if (isObject(value) && Object.hasOwn(value, "launchPromptAnswers")) {
343
- // Shape is checked by the schema; add filesystem-dependent canonical-home checks.
344
- for (const problem of launchPromptPolicyProblems(value.launchPromptAnswers)) {
345
- if (problem.reason === "unsupported-launch-prompt") {
346
- const index = problems.findIndex((p) => p.path === problem.path);
347
- if (index !== -1) problems.splice(index, 1);
348
- problems.push(problem);
349
- } else if (problem.reason === "noncanonical-home") problems.push(problem);
350
- }
351
- }
352
346
  return problems;
353
347
  }
354
348
 
@@ -19,6 +19,7 @@ import { spawn as spawnProcess, execFileSync, spawnSync } from "node:child_proce
19
19
  import { closeSync, existsSync, fchmodSync, mkdirSync, openSync, readFileSync, realpathSync, writeSync } from "node:fs";
20
20
  import { dirname, isAbsolute, join } from "node:path";
21
21
  import { terminateGroup, watchGroup, TERM_GRACE_MS } from "./process-group.mjs";
22
+ import { SYSTEM_TOOL_DIRS } from "./system-tools.mjs";
22
23
 
23
24
  export const WORKTREE_HOOK_TIMEOUT_MS = 30 * 60 * 1000;
24
25
  /** The fixed timeout, or the test seam's value (a positive integer of milliseconds). */
@@ -40,12 +41,12 @@ export const interruptExitStatus = (signal) => 128 + (SIGNAL_NUMBERS[signal] ??
40
41
  * path on any host: `1` runs the system `ps`, an absolute path runs that file as `ps`, and any
41
42
  * other value reads no start at all (psProgram). */
42
43
  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
+ /** `ps` runs with a fixed environment, nothing inherited (runPs). Its PATH is the system directories only (SYSTEM_TOOL_DIRS),
44
45
  * never the caller's: what `ps` reports is the identity a claim is held or taken over on, so the
45
46
  * caller's PATH must not choose the program, and a caller whose PATH holds no `ps` reads the same
46
47
  * start as any other. `lstart` is local time in the locale's format, and two readers with another
47
48
  * 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
+ export const PS_ENV = Object.freeze({ PATH: SYSTEM_TOOL_DIRS.join(":"), LC_ALL: "C", TZ: "UTC" });
49
50
  /** The `ps` a start is read with → { file, name } | { reason }: the system one, or the file the
50
51
  * test seam names by absolute path, run directly (no shell). A seam that names neither is never a
51
52
  * fallback to /proc or to a `ps` found on PATH; nor is a named file that cannot be run (readStart). */
@@ -69,8 +70,39 @@ function existence(pid) {
69
70
  }
70
71
  }
71
72
 
72
- /** The start of a pid that exists: /proc/<pid>/stat field 22 (clock ticks since boot) on Linux,
73
- * elsewhere `ps -o lstart=` in a fixed environment. → { state: "alive", token } | { state: "unknown", reason }. */
73
+ /** Run the system `ps` once: `ps -o <column>= … <selection>`, each column without its header.
74
+ * → { out } — its stdout as it was written, when it exited 0 and answered something;
75
+ * → { reason } — it could not be run, was ended, failed or answered nothing: one line saying which.
76
+ * The one way the kernel calls `ps` (awebai/oats#870, #882): the program (psProgram), the fixed
77
+ * environment (PS_ENV), the time it is given and how its answer is classified are decided here.
78
+ * `selection` is the rest of its arguments (`["-p", "<pid>"]`, `["-ax"]`). The environment is
79
+ * PS_ENV whoever calls: what `ps` answers under it is the same for every reader. `path`, when
80
+ * given, is the PATH the program is found on, in place of PS_ENV's and of nothing else in it: an
81
+ * explicit argument, never read from the caller's environment here. The start reader passes
82
+ * none, so the caller's PATH never chooses the program an identity is read with (#878). */
83
+ export function runPs(columns, selection, { path } = {}) {
84
+ const ps = psProgram();
85
+ if (ps.reason) return { reason: ps.reason };
86
+ const argv = [...columns.flatMap((column) => ["-o", `${column}=`]), ...selection];
87
+ 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 });
88
+ if (r.error) return { reason: `${ps.name} could not be run (${r.error.code || r.error.message})` };
89
+ const out = String(r.stdout ?? ""), err = String(r.stderr ?? "").trim();
90
+ if (r.status === 0 && out.trim()) return { out };
91
+ 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"}` };
92
+ }
93
+
94
+ /** The start of a pid that exists, and whether it is a zombie (it exited, or was killed, and its
95
+ * parent has not reaped it): one read gives both.
96
+ * Linux: /proc/<pid>/stat, field 22 (clock ticks since boot) and field 3 (its state: `Z`, or `X`,
97
+ * a process being removed). Elsewhere `ps -o lstart= -o stat=` (runPs): the start, then a state
98
+ * that begins with `Z` (procps `Z`, macOS `Z` and `Z+`).
99
+ * → { state: "alive", token, zombie? } | { state: "unknown", reason }. `zombie` is set only when
100
+ * it is true. A state that cannot be read makes no zombie, and the start is what it was before
101
+ * there was a second column: whatever `ps` prints as a state (`?` included) is only ever cut off
102
+ * the start, and a `ps` that answers the start alone gives the start.
103
+ * The token is what released kernels recorded, byte for byte (`proc:<ticks>`, `ps:<lstart>`): a
104
+ * claim, a tree record or a marker written by an older kernel names its live holder by it, and a
105
+ * reader that gave that holder another token would take it for a reused pid, which is gone. */
74
106
  function readStart(pid) {
75
107
  if (readsProc()) {
76
108
  let stat;
@@ -79,26 +111,47 @@ function readStart(pid) {
79
111
  // comm (field 2) is in parentheses and may hold spaces or parentheses itself.
80
112
  const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
81
113
  const start = fields[19]; // field 22 overall: after pid, comm and the 19 before it
82
- return /^[0-9]+$/.test(start ?? "") ? { state: "alive", token: `proc:${start}` } : { state: "unknown", reason: `/proc/${pid}/stat has no start time` };
114
+ if (!/^[0-9]+$/.test(start ?? "")) return { state: "unknown", reason: `/proc/${pid}/stat has no start time` };
115
+ return { state: "alive", token: `proc:${start}`, ...(fields[0] === "Z" || fields[0] === "X" ? { zombie: true } : {}) };
83
116
  }
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 });
87
- const out = String(r.stdout ?? "").trim(), err = String(r.stderr ?? "").trim();
88
- if (r.error) return { state: "unknown", reason: `${ps.name} could not be run (${r.error.code || r.error.message})` };
89
- if (r.status === 0 && out) return { state: "alive", token: `ps:${out}` };
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"}` };
117
+ const r = runPs(["lstart", "stat"], ["-p", String(pid)]);
118
+ if (r.reason) return { state: "unknown", reason: r.reason };
119
+ // `Thu Jan 1 00:00:00 2026 Ss`: the state is the last field, one word whatever it says, and the
120
+ // start before it is taken whole, as `ps -o lstart=` alone prints it. A start ends with its year,
121
+ // so a last field of digits only is the start's own: that `ps` answered no state.
122
+ const out = r.out.trim();
123
+ const column = /^(.*\S)\s+(\S+)$/s.exec(out);
124
+ if (!column || /^[0-9]+$/.test(column[2])) return { state: "alive", token: `ps:${out}` };
125
+ return { state: "alive", token: `ps:${column[1]}`, ...(column[2].startsWith("Z") ? { zombie: true } : {}) };
91
126
  }
92
127
 
128
+ /** Whether `token` has a shape readStart writes: `proc:` and a count of clock ticks (64 bits: at
129
+ * most 20 digits), or `ps:` and a start as `ps -o lstart=` prints it under PS_ENV
130
+ * (`Thu Jan 1 00:00:00 2026`). The shape is said here, beside its writer, and nowhere else.
131
+ * It decides only what of a record may be SHOWN: a record is a file that others than its writer
132
+ * can write, and text that is not the kernel's enters an answer only as an id or a code. It is
133
+ * never a liveness decision: processLiveness compares the recorded string as it is, and a real
134
+ * token this does not know (a `ps` that prints a start otherwise) is shown as none, never read
135
+ * as gone. */
136
+ 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})$/;
137
+ export const isStartToken = (token) => typeof token === "string" && START_TOKEN.test(token);
138
+
93
139
  /** When `pid` started, read three ways apart (lessons/observation-must-not-harm-the-observer.md:
94
140
  * "absent" never collapses with "unreadable"). One rule on every host: whether the pid exists is
95
141
  * the kernel's answer (existence), and only a pid that exists has its start read.
96
- * → { state: "alive", token } — an opaque token for its start; two processes that held one pid at
97
- * different times never share it, so a pid is only ever compared WITH its token;
142
+ * → { state: "alive", token, zombie? } — an opaque token for its start; two processes that held
143
+ * one pid at different times never share it, so a pid is only ever compared WITH its token;
98
144
  * → { state: "gone" } — kill(pid, 0) answers ESRCH, before the read or (it exited in between)
99
145
  * after a read that failed;
100
146
  * → { state: "unknown", reason } — anything else: the pid exists and its start could not be read,
101
- * or kill(pid, 0) failed otherwise. Every caller fails safe on it. */
147
+ * or kill(pid, 0) failed otherwise. Every caller fails safe on it.
148
+ *
149
+ * This answers WHOSE the pid is, and a zombie still holds its pid and its start: it is "alive"
150
+ * here, with `zombie: true` as a fact beside it. That is what a recorded process group needs
151
+ * (terminateRecordedGroup): while its leader is a zombie the group's id cannot be reused, so a
152
+ * zombie leader with the recorded start is the best proof there is that the group is still that
153
+ * run's, and its members are ended. Whether a process can still ACT is another question, and
154
+ * processLiveness answers it (awebai/oats#870). */
102
155
  export function processStart(pid) {
103
156
  if (!Number.isSafeInteger(pid) || pid <= 0) return { state: "gone" };
104
157
  const before = existence(pid);
@@ -121,17 +174,39 @@ export function selfIdentity() {
121
174
  return { pid: process.pid, processStart: processStartToken(process.pid) };
122
175
  }
123
176
 
124
- /** Whether the process a record names (`{ pid, processStart }`) still runs:
177
+ /** Whether the COMMAND a record names (`{ pid, processStart }`) can still act:
125
178
  * → { state: "alive" } — its pid runs with the recorded start;
126
- * → { state: "gone" } — its pid does not run, or runs with another start (a reused pid);
179
+ * → { state: "gone", zombie? } — its pid does not run, or runs with another start (a reused pid),
180
+ * or is a zombie (`zombie: true`): it exited or was killed and its parent has not reaped it;
127
181
  * → { state: "unknown", reason } — the start could not be read, or the record has none to
128
182
  * compare while its pid runs. Every caller fails safe on it: nothing is taken over, rolled back,
129
- * retired or signalled, and the refusal names the way out. */
183
+ * retired or signalled, and the refusal names the way out.
184
+ *
185
+ * A zombie is gone here (awebai/oats#870), though processStart still reads its pid and start. It
186
+ * will never run again, and a parent that never waits for it would otherwise keep its claim or
187
+ * marker refused for ever, with the advice to wait for it. Taking over from it is as safe as from
188
+ * a holder that was killed and reaped: a process's children are re-parented when it exits, not
189
+ * when it is reaped, so what a zombie leaves behind is exactly what that holder leaves: the steps
190
+ * it recorded, which each takeover ends (lib/claim.mjs `endHolderStep`; the hook group of a tree
191
+ * record or a spawn's marker), and for a retire its hook children (awebai/oats#865). The zombie
192
+ * adds nothing to that; it only delays the takeover until a reap that may never come.
193
+ * It is decided before the start is compared: a pid that is a zombie now is not a running
194
+ * holder whichever start the record names (it is that holder, or the pid was reused), and so
195
+ * neither when the record names none.
196
+ *
197
+ * WHOM THIS MAY BE ASKED ABOUT: the process of an `oats` command itself, which is what every
198
+ * record read with it names (a claim's holder, the adder of a tree record, a spawn's `inProgress`,
199
+ * a self-retire's completion). That is what makes "a zombie cannot act" true. On Linux a process
200
+ * whose main thread has exited while other threads run also reads `Z` in /proc/<pid>/stat, and
201
+ * it still acts; Node exits as a whole, so it does not arise for those records. Never ask this
202
+ * about a hook's or a harness's pid: for a process that is not the kernel's own, a `Z` does not
203
+ * say it is finished. (A recorded group's leader is asked through processStart, not through this.) */
130
204
  export function processLiveness(record) {
131
205
  const pid = record?.pid;
132
206
  if (!Number.isSafeInteger(pid) || pid <= 0) return { state: "gone" };
133
207
  const s = processStart(pid);
134
208
  if (s.state !== "alive") return s;
209
+ if (s.zombie) return { state: "gone", zombie: true };
135
210
  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` };
136
211
  return s.token === record.processStart ? { state: "alive" } : { state: "gone" };
137
212
  }
@@ -171,11 +246,14 @@ export const unverifiedGroupWarning = (pgid, what = "hook") =>
171
246
  `${what} process group ${pgid} was not signalled: its leader exited, so the group cannot be proven to be this run's; end any leftover processes yourself`;
172
247
 
173
248
  /** What a refusal says of an "unknown" group (terminateRecordedGroup): its id, the recorded start
174
- * of its leader and why that start cannot be read now. The caller adds what it kept and the way out. */
249
+ * of its leader and why that start cannot be read now. The caller adds what it kept and the way out.
250
+ * The recorded start is printed only when it is a token of the kernel's (isStartToken), else as
251
+ * `none`: `rec` is read from a file (a claim, a tree record, a spawn's marker). The id is an
252
+ * integer whenever a group is "unknown". */
175
253
  export function unknownGroupNote(rec, what = "hook") {
176
254
  const s = processStart(rec.hookPgid);
177
255
  const reason = s.state === "unknown" ? s.reason : "its leader's start time could not be read";
178
- return `${what} process group ${rec.hookPgid} (leader pid ${rec.hookPgid}, recorded start ${rec.hookStart ?? "none"}) still has members, and its leader's start cannot be read (${reason}), so whether it is still that ${what} cannot be told and it was not signalled`;
256
+ return `${what} process group ${rec.hookPgid} (leader pid ${rec.hookPgid}, recorded start ${isStartToken(rec.hookStart) ? rec.hookStart : "none"}) still has members, and its leader's start cannot be read (${reason}), so whether it is still that ${what} cannot be told and it was not signalled`;
179
257
  }
180
258
 
181
259
  /** End the group of a hook this process is running, synchronously, once its leader has
package/lib/worktree.mjs CHANGED
@@ -21,20 +21,20 @@
21
21
  import { execFileSync, spawn as spawnChild, spawnSync } from "node:child_process";
22
22
  import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
23
23
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
24
- import { oatsError } from "./errors.mjs";
24
+ import { checkHolderByHand, ifItDoesNotEnd, lifecycleBusy, nothingAfter, oatsError, OWN_START_REMEDY } from "./errors.mjs";
25
25
  import { appendEvent } from "./instance-events.mjs";
26
26
  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
30
  import { terminateGroup, watchGroup } from "./process-group.mjs";
31
- import { CLAIM_WAIT_MS, acquireClaim, recordInClaim, releaseClaim } from "./claim.mjs";
31
+ import { CLAIM_WAIT_MS, acquireClaim, claimUnavailable, recordInClaim, releaseClaim, shownHolder } from "./claim.mjs";
32
32
  import {
33
33
  cloneOfMember, instanceSoulDir, isCapturedHome, isWorkspaceHome, capturedHomeRefusal, preWorkspaceHome, lifecycleHookEnv,
34
- retirePendingMarkerPath, stableSoulId, workspaceOf,
34
+ refuseBesideRetire, retirePendingMarkerPath, stableSoulId, workspaceOf,
35
35
  } from "./core.mjs";
36
36
  import {
37
- endOwnGroupSync, interruptExitStatus, processStartToken, runWorktreeHooks, scrubRemoteUrl, selfIdentity, signalGuard, terminateRecordedGroup, treeStillThere,
37
+ endOwnGroupSync, interruptExitStatus, isStartToken, processStartToken, runWorktreeHooks, scrubRemoteUrl, selfIdentity, signalGuard, terminateRecordedGroup, treeStillThere,
38
38
  processLiveness, unknownGroupNote, unverifiedGroupWarning, verifiedAlive, worktreeHooksOf,
39
39
  } from "./worktree-hooks.mjs";
40
40
 
@@ -90,7 +90,7 @@ export function trackedGit(argv, { track, timeout = 120_000 }) {
90
90
  // holds no pipe would outlive it. One that survives SIGKILL keeps its identity recorded, and the
91
91
  // command stops here (keepClaim: the claim holding it is not released).
92
92
  if (timedOut && tracked && endOwnGroupSync(child.pid) === "survived") {
93
- return fail(Object.assign(oatsError("E_LIFECYCLE_BUSY", `a git step that timed out could not be ended (process group ${child.pid} survived SIGKILL); it stays recorded, and nothing more was done — end that process, then retry`), { details: { gitPid: child.pid }, keepClaim: true }));
93
+ return fail(Object.assign(lifecycleBusy("none", `a git step that timed out could not be ended (process group ${child.pid} survived SIGKILL); it stays recorded, and nothing more was done`, "end that process, then retry", { gitPid: child.pid }), { keepClaim: true }));
94
94
  }
95
95
  if (!tracked) return done({ ok: false, out: "", err: `the git step was not run: ${trackError ? `its process could not be recorded (${trackError.message})` : "its start time could not be read"}`, status: null });
96
96
  try { track(null); } catch { /* the record or claim is gone: nothing left to clear */ }
@@ -101,8 +101,9 @@ export function trackedGit(argv, { track, timeout = 120_000 }) {
101
101
 
102
102
  /** End the git step a dead holder recorded (`{ gitPid, gitStart }`), only when its leader runs with
103
103
  * the recorded start time (terminateRecordedGroup): SIGTERM, which git answers by removing its lock
104
- * files, then SIGKILL. → { owed?, remedy?, warning? }: `owed` stops the caller, which keeps `at` (the
105
- * claim or record naming the step); `remedy` is the way out. A step whose leader's start cannot be
104
+ * files, then SIGKILL. → { owed?, remedy?, warning?, ended? }: `owed` stops the caller, which keeps `at` (the
105
+ * claim or record naming the step); `remedy` is the way out; `ended` says that the step was signalled and
106
+ * is gone, for a caller that then fails (lib/claim.mjs takeOver). A step whose leader's start cannot be
106
107
  * read is owed, never a warning: it may still be that git, about to change the tree or the branch. */
107
108
  function endRecordedGit(holder, at, otherwise = `remove ${at}`) {
108
109
  if (!holder?.gitPid) return {};
@@ -111,6 +112,7 @@ function endRecordedGit(holder, at, otherwise = `remove ${at}`) {
111
112
  if (ended === "survived") return { owed: `git process group ${holder.gitPid}, left running by a killed oats worktree command, survived SIGKILL`, remedy: "end that process, then retry" };
112
113
  if (ended === "unknown") return { owed: unknownGroupNote(rec, "git"), remedy: unknownGroupRemedy(holder.gitPid, "git", otherwise) };
113
114
  if (ended === "unverified") return { warning: unverifiedGroupWarning(holder.gitPid, "git") };
115
+ if (ended === "terminated" || ended === "killed") return { ended: `git process group ${holder.gitPid}, left running by a killed oats worktree command, was ended` };
114
116
  return {};
115
117
  }
116
118
 
@@ -164,6 +166,9 @@ export function readTreeHome(home) {
164
166
  if (!isWorkspaceHome(meta)) throw preWorkspaceHome(home, "no tree was made");
165
167
  if (existsSync(join(home, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${home} is a quarantined home (or a spawn still in progress); finish its retirement (oats retire) before making trees in it`);
166
168
  if (existsSync(retirePendingMarkerPath(home))) throw oatsError("E_INSTANCE_RETIRING", `${basename(home)} is being retired; no tree was made`);
169
+ // A retire in flight holds the home's lifecycle claim. Read, never taken: an add runs hooks for
170
+ // minutes and has its purpose's claim.
171
+ refuseBesideRetire("worktree add", home);
167
172
  return { home, meta };
168
173
  }
169
174
 
@@ -232,7 +237,9 @@ function createRecord(path, rec) {
232
237
  const tmp = `${path}.tmp-${process.pid}`;
233
238
  writeFileSync(tmp, JSON.stringify(rec, null, 2) + "\n", { mode: 0o600 });
234
239
  try { linkSync(tmp, path); }
235
- catch (e) { if (e.code === "EEXIST") throw oatsError("E_LIFECYCLE_BUSY", `another oats worktree add of purpose ${rec.purpose} started at the same moment; nothing was done`); throw e; }
240
+ // Reached only when a record appeared after this add, which holds the purpose's claim, read that
241
+ // there was none: whoever wrote it did not hold the claim, and whether it still runs was not read.
242
+ catch (e) { if (e.code === "EEXIST") throw lifecycleBusy("unknown", `another oats worktree add of purpose ${rec.purpose} wrote ${path} at the same moment; nothing was done`, `check whether the process that record names still runs (its \`pid\`), then run the command again`, { purpose: rec.purpose, record: path }); throw e; }
236
243
  finally { try { unlinkSync(tmp); } catch { /* gone */ } }
237
244
  }
238
245
 
@@ -334,18 +341,60 @@ const worktreeFields = (out, field) => out.split("\0").filter((f) => f.startsWit
334
341
  * recovery) is taken over, so a killed command can always be run again: the owner is named by
335
342
  * pid AND start time (processLiveness), never by a pid alone, and a holder whose start cannot be
336
343
  * read is never taken for gone. A claim held by a live process is
337
- * waited for up to `CLAIM_WAIT_MS`, then refused as E_LIFECYCLE_BUSY. The holder's git steps
344
+ * waited for up to `CLAIM_WAIT_MS`, then refused as E_LIFECYCLE_BUSY; so is, with its own sentence,
345
+ * a file at the claim's path that is no claim this kernel can read or take over. The holder's git steps
338
346
  * are recorded in the claim (trackedGit), and a takeover ends one still running first: a dead
339
- * holder's git never finishes late on a tree made after the takeover.
347
+ * holder's git never finishes late on a tree made after the takeover. A command that is refused the
348
+ * claim after its takeover ended such a step answers E_LIFECYCLE_FAILED, naming what it ended first:
349
+ * E_LIFECYCLE_BUSY says that nothing happened (lib/errors.mjs afterEndedSteps).
340
350
  * `fn({ track, warnings })`; → Promise of what `fn` returns. */
341
351
  function withPurposeClaim(home, purpose, fn) {
342
352
  const dir = join(home, ".oats", "trees");
343
- mkdirSync(dir, { recursive: true, mode: 0o700 });
344
353
  const lock = join(dir, `${purpose}.lock`);
345
- const busy = (holder, unknown, at = lock) => Object.assign(oatsError("E_LIFECYCLE_BUSY", unknown
346
- ? `whether pid ${holder?.pid ?? "?"} (recorded start ${holder?.processStart ?? "none"}), which holds ${at}, still runs cannot be read (${unknown}); nothing was done — check that pid by hand, and if it is not an oats worktree command, remove ${at}, then retry`
347
- : `another oats worktree add or remove of purpose ${purpose} is running (pid ${holder?.pid ?? "?"} holds ${at}); nothing was done — retry when it has finished`), { details: { purpose, lock: at, ...(holder?.pid ? { pid: holder.pid } : {}), ...(unknown ? { unknown } : {}) } });
348
- return withClaim(lock, fn, { busy });
354
+ // A directory that cannot be made is a claim that cannot be taken: nothing was done (#874).
355
+ try { mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch (e) { throw claimUnavailable(lock, e); }
356
+ return withClaim(lock, fn, { busy: purposeClaimBusy(purpose, lock) });
357
+ }
358
+
359
+ /** The `busy` refusal of the claim `lock` of `purpose` (lib/claim.mjs): E_LIFECYCLE_BUSY, one line
360
+ * that says nothing was done; `details.lock` is the file that names the holder. The holder is
361
+ * named as lib/claim.mjs shownHolder allows, here and in every refusal made from this one
362
+ * (worktreeClaimRefusals): a pid or a start that is not the kernel's is `?` or `none` in the
363
+ * message, and `details` has no `pid`. A holder that runs is waited for; the step also says what
364
+ * to check when it does not end (lib/errors.mjs ifItDoesNotEnd): alive is all that was
365
+ * established of the pid, not that it is an oats worktree command. `ended` is what
366
+ * the claim's takeovers ended before it: then the line says "nothing else was done" and the answer
367
+ * is E_LIFECYCLE_FAILED, what was ended first (lib/errors.mjs afterEndedSteps). Exported for its tests. */
368
+ export function purposeClaimBusy(purpose, lock) {
369
+ return (holder, unknown, at = lock, ended = []) => {
370
+ const shown = shownHolder(holder);
371
+ const details = { purpose, lock: at, ...(shown.pid ? { pid: shown.pid } : {}) };
372
+ return unknown
373
+ ? lifecycleBusy("unknown", `whether pid ${shown.pid ?? "?"} (recorded start ${shown.start ?? "none"}), which holds ${at}, still runs cannot be read (${unknown}); ${nothingAfter(ended)}`, checkHolderByHand("an oats worktree command", at), { ...details, unknown }, ended)
374
+ : lifecycleBusy("running", `another oats worktree add or remove of purpose ${purpose} is running (pid ${shown.pid ?? "?"} holds ${at}); ${nothingAfter(ended)}`, `retry when it has finished; ${ifItDoesNotEnd("an oats worktree command", at)}`, details, ended);
375
+ };
376
+ }
377
+
378
+ /** The refusals of an `oats worktree` command that cannot take a claim, as lib/claim.mjs asks for
379
+ * them, each made from the caller's `busy` with its own sentence. Every one says "nothing was
380
+ * done", once; "nothing else was done" when `ended`, its last argument, names what the claim's
381
+ * takeovers ended before it. Exported for its tests. */
382
+ export function worktreeClaimRefusals(busy) {
383
+ // The caller's details (its purpose, the file, the holder's pid), with this refusal's own
384
+ // sentence, remedy and `holder`: in none of the four is anybody known to be running.
385
+ const refuse = (holder, at, value, said, remedy, ended) => lifecycleBusy(value, said, remedy, busy(holder, null, at).details, ended);
386
+ return {
387
+ busy,
388
+ ownStartUnreadable: (reason, at, ended = []) => refuse(null, at, "none", `this process's start time cannot be read (${reason}), so it cannot hold ${at} verifiably; ${nothingAfter(ended)}`,
389
+ OWN_START_REMEDY, ended),
390
+ unreadableClaim: (at, ended = []) => refuse(null, at, "unknown", `${at} is not a readable claim; ${nothingAfter(ended)}`, "inspect it and remove it if no oats worktree command holds it, then retry", ended),
391
+ cannotTakeOver: (holder, at, why, ended = []) => refuse(holder, at, "none", `the process that held ${at} (pid ${shownHolder(holder).pid ?? "?"}) is gone, and this file is not a claim this kernel can take over (${why}); ${nothingAfter(ended)}`,
392
+ `inspect ${at} and remove it if no oats worktree command holds it, then retry`, ended),
393
+ // Nothing is wrong with the file: each command that took the claim died, and this one came
394
+ // after each of them. The next run takes over the one that is there.
395
+ heldAgain: (holder, at, times, ended = []) => refuse(holder, at, "none", `the claim ${at} was found without a live holder ${times} times and was taken again each time, the last time by a process that is gone (pid ${shownHolder(holder).pid ?? "?"}); ${nothingAfter(ended)}`,
396
+ "run the command again", ended),
397
+ };
349
398
  }
350
399
 
351
400
  /** Run `fn` holding the claim file `path` (lib/claim.mjs: how a claim is taken, taken over from a
@@ -358,10 +407,15 @@ function withPurposeClaim(home, purpose, fn) {
358
407
  export async function withClaim(path, fn, { busy, waitMs = CLAIM_WAIT_MS } = {}) {
359
408
  const warnings = [];
360
409
  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 } }),
410
+ ...worktreeClaimRefusals(busy), waitMs, warnings,
411
+ // A step that could not be ended refuses, and `at` is kept: `holder: "none"`, since the holder
412
+ // is gone and its git has to be ended by hand; the caller's details, with the step's (`gitPid`
413
+ // is an integer whenever a step is owed; `gitStart` is shown only as a token of the kernel's).
414
+ // `before` is what this acquisition's takeovers ended before this step.
415
+ endHolderStep: (holder, at, before = []) => {
416
+ const ended = endRecordedGit(holder, at);
417
+ return ended.owed ? { refusal: lifecycleBusy("none", `${ended.owed}; ${at} is kept and ${nothingAfter(before)}`, ended.remedy, { ...busy(holder).details, gitPid: holder.gitPid, gitStart: isStartToken(holder.gitStart) ? holder.gitStart : null }, before) } : ended;
418
+ },
365
419
  });
366
420
  // Record (or clear) the holder's running git step in the claim; only its live holder writes it.
367
421
  const track = (gitStep) => recordInClaim(path, me, gitStep);
@@ -371,11 +425,16 @@ export async function withClaim(path, fn, { busy, waitMs = CLAIM_WAIT_MS } = {})
371
425
  finally { if (!keep) releaseClaim(path, me); }
372
426
  }
373
427
 
428
+ /** What ends an interrupted add's rollback that could not be completed: nobody is running, and
429
+ * what the message lists as owed has to be dealt with before the rollback can finish. */
430
+ const owedRollbackRemedy = (purpose) => `deal with what is listed (end the process group, or remove the tree or the branch with Git), then run \`oats worktree remove --purpose ${purpose}\`, which finishes the rollback`;
431
+
374
432
  /** A `creating` record whose adder may still run: its start cannot be read. Never rolled back on
375
433
  * that; the refusal names the pid and the record's exact path, the way out once the pid is
376
434
  * checked by hand. */
377
435
  function unknownAdderRefusal({ purpose, tree, recPath, rec, reason }) {
378
- return Object.assign(oatsError("E_LIFECYCLE_BUSY", `whether the oats worktree add of purpose ${purpose} (pid ${rec.pid}, recorded start ${rec.processStart ?? "none"}) still runs cannot be read (${reason}); nothing was done — check that pid by hand, and if it is not an oats worktree add, ${leftoverRemedy(recPath, tree, rec)} and retry`), { details: { purpose, path: tree, record: recPath, pid: rec.pid, unknown: reason } });
436
+ return lifecycleBusy("unknown", `whether the oats worktree add of purpose ${purpose} (pid ${rec.pid}, recorded start ${rec.processStart ?? "none"}) still runs cannot be read (${reason}); nothing was done`,
437
+ `check that pid by hand, and if it is not an oats worktree add, ${leftoverRemedy(recPath, tree, rec)} and retry`, { purpose, path: tree, record: recPath, pid: rec.pid, unknown: reason });
379
438
  }
380
439
 
381
440
  // ---------- add ----------
@@ -418,7 +477,7 @@ export async function worktreeAdd(homeArg, o = {}) {
418
477
  if (found?.state === "unreadable") throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${recPath} is not a readable tree record; inspect it (and the tree at ${tree}), remove what is not yours, then retry`), { details: { purpose, path: tree, record: recPath } });
419
478
  if (found?.state === "creating") {
420
479
  const live = processLiveness(found);
421
- if (live.state === "alive") throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `an oats worktree add of purpose ${purpose} is still running (pid ${found.pid}, since ${found.startedAt}); nothing was done`), { details: { purpose, path: tree, pid: found.pid } });
480
+ if (live.state === "alive") throw lifecycleBusy("running", `an oats worktree add of purpose ${purpose} is still running (pid ${found.pid}, since ${found.startedAt}); nothing was done`, null, { purpose, path: tree, pid: found.pid });
422
481
  if (live.state === "unknown") throw unknownAdder(found, live.reason);
423
482
  return { recover: found };
424
483
  }
@@ -455,7 +514,7 @@ export async function worktreeAdd(homeArg, o = {}) {
455
514
  if (d.recover) {
456
515
  const rb = await rollbackTree(home, d.recover, { track });
457
516
  recoveryWarnings.push(...rb.warnings);
458
- if (rb.owed.length) throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `an earlier oats worktree add of purpose ${purpose} was interrupted and its rollback could not be completed: ${rb.owed.join("; ")}; nothing new was done`), { details: { purpose, path: tree, owed: rb.owed, ...(rb.warnings.length ? { warnings: rb.warnings } : {}) } });
517
+ if (rb.owed.length) throw lifecycleBusy("none", `an earlier oats worktree add of purpose ${purpose} was interrupted and its rollback could not be completed: ${rb.owed.join("; ")}; nothing new was done`, owedRollbackRemedy(purpose), { purpose, path: tree, owed: rb.owed, ...(rb.warnings.length ? { warnings: rb.warnings } : {}) });
459
518
  checkFresh("after the rollback of an interrupted add");
460
519
  }
461
520
  rec = { version: RECORD_VERSION, purpose, state: "creating", path: tree, clone, remote, member, branch, base, ...selfIdentity(), startedAt: new Date().toISOString() };
@@ -559,11 +618,11 @@ export async function worktreeRemove(homeArg, o = {}) {
559
618
  if (rec.state === "unreadable") throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${recPath} is not a readable tree record; inspect it and the tree at ${tree}`), { details: { purpose, path: tree, record: recPath } });
560
619
  if (rec.state === "creating") {
561
620
  const live = processLiveness(rec);
562
- if (live.state === "alive") throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `an oats worktree add of purpose ${purpose} is still running (pid ${rec.pid}); nothing was removed`), { details: { purpose, path: tree, pid: rec.pid } });
621
+ if (live.state === "alive") throw lifecycleBusy("running", `an oats worktree add of purpose ${purpose} is still running (pid ${rec.pid}); nothing was removed`, null, { purpose, path: tree, pid: rec.pid });
563
622
  if (live.state === "unknown") throw unknownAdderRefusal({ purpose, tree, recPath, rec, reason: live.reason });
564
623
  const rb = await rollbackTree(home, rec, { track });
565
624
  const warned = [...claimWarnings, ...rb.warnings];
566
- if (rb.owed.length) throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `the rollback of an interrupted add of purpose ${purpose} could not be completed: ${rb.owed.join("; ")}`), { details: { purpose, path: tree, owed: rb.owed, ...(warned.length ? { warnings: warned } : {}) } });
625
+ if (rb.owed.length) throw lifecycleBusy("none", `the rollback of an interrupted add of purpose ${purpose} could not be completed: ${rb.owed.join("; ")}`, owedRollbackRemedy(purpose), { purpose, path: tree, owed: rb.owed, ...(warned.length ? { warnings: warned } : {}) });
567
626
  return { purpose, path: tree, removed: true, rolledBack: true, branch: rec.branch, branchKept: rb.branchKept, ...(rb.branchKeptReason ? { branchKeptReason: rb.branchKeptReason } : {}), ...(warned.length ? { warnings: warned } : {}) };
568
627
  }
569
628
  const clone = rec.clone;
@@ -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.1",
6
+ "ref": "v5.0.2",
7
7
  "path": "oats-package"
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.24.1",
11
+ "ref": "v1.27.0",
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.9.1",
46
+ "ref": "oats-framework/v1.9.3",
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.51.0",
3
+ "version": "0.52.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",
@@ -39,7 +39,12 @@
39
39
  "packages/record/docs/",
40
40
  "packages/record/test/vectors/",
41
41
  "packages/record/README.md",
42
- "packages/record/package.json"
42
+ "packages/record/package.json",
43
+ "packages/client/",
44
+ "packages/tui/bin/",
45
+ "packages/tui/lib/",
46
+ "packages/tui/README.md",
47
+ "packages/tui/package.json"
43
48
  ],
44
49
  "dependencies": {
45
50
  "@awebai/pi": "^0.2.1",