@awebai/oats 0.50.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 (132) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +153 -51
  3. package/docs/capabilities.md +11 -3
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +994 -71
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +230 -59
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +73 -8
  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 +43 -7
  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.51.0.md +156 -0
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/schedules.md +91 -4
  27. package/docs/servers.md +21 -2
  28. package/docs/souls-and-instances.md +113 -21
  29. package/docs/tui.md +152 -0
  30. package/docs/workspaces.md +2 -2
  31. package/lib/claim.mjs +266 -0
  32. package/lib/core.mjs +845 -166
  33. package/lib/errors.mjs +170 -0
  34. package/lib/harness-trust-write.mjs +68 -27
  35. package/lib/harness-trust.mjs +34 -16
  36. package/lib/instance-inspect.mjs +40 -11
  37. package/lib/instance-lifecycle.mjs +169 -47
  38. package/lib/launch-preference.mjs +16 -0
  39. package/lib/launch-prompt-completion.mjs +7 -43
  40. package/lib/launch-prompt-evidence.mjs +14 -7
  41. package/lib/launch-prompt-fixtures/README.md +86 -152
  42. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  43. package/lib/launch-prompt-fixtures.mjs +122 -109
  44. package/lib/launch-prompt-transport.mjs +2 -56
  45. package/lib/launch-prompts.mjs +102 -100
  46. package/lib/schedule-host.mjs +154 -22
  47. package/lib/schedule.mjs +73 -24
  48. package/lib/servers.mjs +20 -4
  49. package/lib/session-viewer.mjs +87 -10
  50. package/lib/system-tools.mjs +39 -0
  51. package/lib/tmux-server-scope.mjs +62 -0
  52. package/lib/triggers.mjs +4 -4
  53. package/lib/workspace.mjs +5 -11
  54. package/lib/worktree-hooks.mjs +116 -23
  55. package/lib/worktree.mjs +89 -102
  56. package/package-catalog.json +3 -3
  57. package/package.json +7 -2
  58. package/packages/client/capability-show-contract.mjs +230 -0
  59. package/packages/client/capability-warnings-contract.mjs +57 -0
  60. package/packages/client/cli-adapter.mjs +548 -0
  61. package/packages/client/cli-environment.mjs +53 -0
  62. package/packages/client/cli-locator.mjs +253 -0
  63. package/packages/client/cli-probe-contract.mjs +47 -0
  64. package/packages/client/client-terms.mjs +60 -0
  65. package/packages/client/deployment-contract.mjs +68 -0
  66. package/packages/client/deployment-data.mjs +483 -0
  67. package/packages/client/deployment-facts.mjs +34 -0
  68. package/packages/client/deployment-label.mjs +76 -0
  69. package/packages/client/deployment-observer.mjs +89 -0
  70. package/packages/client/deployment-panel.mjs +142 -0
  71. package/packages/client/deployment-read-cli.mjs +53 -0
  72. package/packages/client/display-text.mjs +44 -0
  73. package/packages/client/harness-names.mjs +30 -0
  74. package/packages/client/inspect-contract.mjs +62 -0
  75. package/packages/client/instance-acts.mjs +54 -0
  76. package/packages/client/instance-admission.mjs +45 -0
  77. package/packages/client/instance-events-contract.mjs +74 -0
  78. package/packages/client/instance-git-contract.mjs +80 -0
  79. package/packages/client/instance-presentation.mjs +22 -0
  80. package/packages/client/instance-tree.mjs +453 -0
  81. package/packages/client/kernel-environment.mjs +11 -0
  82. package/packages/client/launch-contract.mjs +51 -0
  83. package/packages/client/launch-prompt-outcome.mjs +165 -0
  84. package/packages/client/lifecycle-cli.mjs +61 -0
  85. package/packages/client/lifecycle-contract.mjs +372 -0
  86. package/packages/client/liveness-main.mjs +10 -0
  87. package/packages/client/liveness.mjs +35 -0
  88. package/packages/client/machine-contract.mjs +123 -0
  89. package/packages/client/own-environment.mjs +22 -0
  90. package/packages/client/panel-views.mjs +286 -0
  91. package/packages/client/readiness-contract.mjs +172 -0
  92. package/packages/client/refresh-loop.mjs +52 -0
  93. package/packages/client/remote-address.mjs +126 -0
  94. package/packages/client/remote-roster.mjs +67 -0
  95. package/packages/client/roster-sections.mjs +80 -0
  96. package/packages/client/spawn-apply-cli.mjs +104 -0
  97. package/packages/client/spawn-apply-contract.mjs +183 -0
  98. package/packages/client/spawn-decision.mjs +46 -0
  99. package/packages/client/spawn-messages.mjs +119 -0
  100. package/packages/client/spawn-preview-cli.mjs +32 -0
  101. package/packages/client/spawn-preview-contract.mjs +314 -0
  102. package/packages/client/team-members.mjs +41 -0
  103. package/packages/client/team-rows.mjs +45 -0
  104. package/packages/client/terminal-contract.mjs +57 -0
  105. package/packages/client/tmux-status.mjs +66 -0
  106. package/packages/client/waiting-on-you.mjs +88 -0
  107. package/packages/client/workspace-admission.mjs +45 -0
  108. package/packages/client/workspace-cli.mjs +142 -0
  109. package/packages/client/workspace-views.mjs +147 -0
  110. package/packages/tui/README.md +46 -0
  111. package/packages/tui/bin/tui.mjs +7 -0
  112. package/packages/tui/lib/actions.mjs +29 -0
  113. package/packages/tui/lib/client.mjs +4 -0
  114. package/packages/tui/lib/main.mjs +105 -0
  115. package/packages/tui/lib/term/keys.mjs +323 -0
  116. package/packages/tui/lib/term/screen.mjs +122 -0
  117. package/packages/tui/lib/term/style.mjs +43 -0
  118. package/packages/tui/lib/term/text.mjs +49 -0
  119. package/packages/tui/lib/term/tty.mjs +168 -0
  120. package/packages/tui/lib/term/width.mjs +124 -0
  121. package/packages/tui/lib/views/frame.mjs +62 -0
  122. package/packages/tui/lib/views/help.mjs +28 -0
  123. package/packages/tui/package.json +8 -0
  124. package/skills/oats-getting-started/SKILL.md +29 -22
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  127. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  128. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  129. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  130. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  131. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  132. package/lib/launch-prompt-policy.mjs +0 -87
package/lib/claim.mjs ADDED
@@ -0,0 +1,266 @@
1
+ /** The claim: one file that says which process is doing a thing that must happen once at a time.
2
+ * One protocol, used by `oats worktree add|remove` (the purpose's claim, lib/worktree.mjs
3
+ * `withClaim`) and by `oats retire` and `oats instance stop` (the home's claim, lib/core.mjs
4
+ * `claimHomeFor`).
5
+ *
6
+ * Unlike lib/dir-lock.mjs, a claim left by a process that died is taken over, so a killed command
7
+ * can always be run again: the owner is named by pid AND start time (processLiveness), never by a
8
+ * pid alone, and a holder whose start cannot be read is never taken for gone.
9
+ *
10
+ * - Taking it: the owner's facts `{ pid, processStart, nonce, at }`, with what the caller adds to
11
+ * them (`facts`), are written to a private file and hard-linked to `path`, which fails if
12
+ * `path` exists. So a claim is never seen without its owner, and the nonce makes each holding
13
+ * distinct, even for the same process.
14
+ * - Its owner is alive: waited for up to `waitMs`, then refused (`busy`).
15
+ * - Its owner is gone (processLiveness "gone", which a zombie is too; "unknown" is refused, never
16
+ * taken over): the claim is removed under a second claim, `<path>.reclaim-<owner nonce>`, taken
17
+ * by this same protocol.
18
+ * Its holder re-reads `path` and removes it only if it still names that owner. Nothing else
19
+ * removes another's claim: its owner never releases it, and a new acquirer cannot write over an
20
+ * existing file. Two takeovers of one dead owner are therefore serialized, and neither removes
21
+ * a claim made after it read. A takeover cut short leaves its own claim behind, which the next
22
+ * takeover takes over in turn, up to CLAIM_MAX_DEPTH nested levels.
23
+ * - Its owner is gone and the file cannot be taken over: refused with `cannotTakeOver`, which
24
+ * says that the holder is gone and what to do with the file. Never with `busy`: nobody is
25
+ * running (awebai/oats#874). That is a file whose `nonce` is not the 32 hex digits a claim
26
+ * carries, so no takeover can be serialized on it; the claim of a takeover nested
27
+ * CLAIM_MAX_DEPTH deep; and, which comes first on the file systems there are, one whose
28
+ * takeover claim the system refuses to name: each nested level adds 41 bytes to the name, so a
29
+ * chain of four or five dead takeovers reaches the limit of a file name (ENAMETOOLONG). The
30
+ * refusal names the file whose takeover could not be named, the one to remove.
31
+ * - A step the holder recorded in its claim (recordInClaim) is ended by a takeover first
32
+ * (`endHolderStep`), which refuses, keeping the claim, if the step cannot be ended.
33
+ * - Once a takeover has ended a holder's step, no later answer of that acquisition says that
34
+ * nothing was done: whatever it is then refused with, or fails on, is answered
35
+ * E_LIFECYCLE_FAILED, naming first what was ended. Every refusal is handed what was ended so
36
+ * far (`ended`, the clauses in order; empty before any effect) and writes its own sentence
37
+ * for it (lib/errors.mjs nothingAfter, afterEndedSteps; lifecycleBusy takes `ended`): no
38
+ * message is rewritten here. A refusal that was made without them is still answered after
39
+ * them (claimUnavailable). A refusal before any effect stays what its caller made it.
40
+ * - Released by unlinking `path`, only while it still names this holding.
41
+ * - A claim is read back as whatever JSON is in its file, and the file is where others than its
42
+ * writer can write. Who holds it, and whether that process lives, is decided on the record as
43
+ * it is; what an ANSWER shows of it is only what shownHolder allows, never the file's text.
44
+ * - An unreadable claim file is never removed: the command is refused, naming the file. So is a
45
+ * path that exists and keeps reading as absent (a dangling symbolic link where the claim
46
+ * belongs), once the retries below are spent.
47
+ * - Every pass that does not take the claim falls through one check of its time and one pause
48
+ * (takeClaim): none starts the next pass at once, so no state of the path makes it spin, and
49
+ * each ends in a refusal within `waitMs` plus CLAIM_FREED_RETRIES pauses (awebai/oats#874).
50
+ * A claim that every one of those passes found held again by a process that is gone, after it
51
+ * took the one before over, is refused with `heldAgain`: an ordinary claim, which the next
52
+ * run takes over.
53
+ * - A claim that cannot be taken for a reason of the system's (its directory cannot be made, its
54
+ * private file cannot be written, the link fails otherwise than because the claim exists) is
55
+ * refused as E_LIFECYCLE_FAILED (claimUnavailable), never with the system's code
56
+ * (awebai/oats#874): the claim was not taken, so nothing was done.
57
+ *
58
+ * Everything is synchronous. What is the caller's own goes in `opts`. Each refusal is an error
59
+ * whose message states its effects, once: in the caller's words for "nothing was done" before
60
+ * any effect, and as "nothing else was done" when `ended`, its last argument, names what this
61
+ * acquisition's takeovers ended before it:
62
+ * busy(holder, unknown, at, ended) the refusal for a holder that lives (`unknown` unset)
63
+ * or whose liveness cannot be read (`unknown` is the
64
+ * reason); `at` is the claim file that names it
65
+ * ownStartUnreadable(reason, at, ended) the refusal when this process's own start cannot be
66
+ * read, so it could not hold `at` verifiably
67
+ * unreadableClaim(at, ended) the refusal for a claim file that does not parse, or
68
+ * for a path that exists and cannot be read as one
69
+ * cannotTakeOver(holder, at, why, ended) the refusal for a holder that is gone and whose claim
70
+ * file `at` this kernel cannot take over; `why` is a
71
+ * clause saying what stops it
72
+ * heldAgain(holder, at, times, ended) the refusal for a claim that this command found
73
+ * without a live holder `times` times and that was
74
+ * taken again each time, the last time by `holder`,
75
+ * which is gone: nothing is wrong with `at`
76
+ * endHolderStep(holder, at, ended) optional: end the step a dead holder recorded
77
+ * → { refusal?, warning?, ended? }; `refusal` is the
78
+ * caller's answer for a step that could not be ended
79
+ * (`at` is kept); `ended` is a clause naming what it
80
+ * ended, when it ended something
81
+ * waitMs how long a live holder is waited for (default CLAIM_WAIT_MS)
82
+ * warnings optional array a takeover's warnings are pushed to
83
+ * facts optional object, what the caller's claim says besides its
84
+ * owner (a home's lifecycle claim: `action`, the holder's verb).
85
+ * It is in the record that is linked, so the claim is never
86
+ * seen without it; the owner's four fields win over it */
87
+ import { linkSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
88
+ import { randomBytes } from "node:crypto";
89
+ import { isStartToken, processLiveness, processStart } from "./worktree-hooks.mjs";
90
+ import { NOTHING_ELSE, afterEndedSteps, asKernelError, nothingAfter } from "./errors.mjs";
91
+
92
+ export const CLAIM_WAIT_MS = 3000;
93
+ const CLAIM_MAX_DEPTH = 8;
94
+ /** How long a pass that did not take the claim pauses before the next one. */
95
+ const CLAIM_PAUSE_MS = 50;
96
+ /** How many passes that found nobody holding the claim (it read as absent, or its holder was gone
97
+ * and it was taken over) are followed by another once `waitMs` is over; passes before that are
98
+ * not counted. With `waitMs: 0` that is every retry there is: enough for the true race, a claim
99
+ * released or freed between two steps of this process, and an end for a path that never becomes
100
+ * a claim. */
101
+ const CLAIM_FREED_RETRIES = 5;
102
+ const NONCE_RE = /^[0-9a-f]{32}$/;
103
+ const ISO_INSTANT = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$/;
104
+ /** Whether `at` is an instant exactly as `toISOString()` gives it, and one that exists. */
105
+ const isInstant = (at) => typeof at === "string" && ISO_INSTANT.test(at) && !Number.isNaN(Date.parse(at)) && new Date(at).toISOString() === at;
106
+ const pauseSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
107
+
108
+ /** The claim at `path` → its record, `{ unreadable: true }` when it does not parse, null when there is none. */
109
+ export function readClaim(path) {
110
+ try { const o = JSON.parse(readFileSync(path, "utf8")); return o && typeof o === "object" ? o : { unreadable: true }; }
111
+ catch (e) { return e.code === "ENOENT" ? null : { unreadable: true }; }
112
+ }
113
+
114
+ /** What of the claim record `record` may be shown in an answer → `{ pid, since, start }`, each
115
+ * null unless it has the shape takeClaim writes it in:
116
+ * pid the record's `pid`, a positive safe integer;
117
+ * since the record's `at`, exactly what `toISOString()` gives (`2026-01-01T00:00:00.000Z`);
118
+ * start the record's `processStart`, a token of the kernel's (worktree-hooks isStartToken).
119
+ * A claim is a file in a directory that other instances of the deployment can write, and it is
120
+ * read back as whatever JSON is there: text of it is never part of an answer. Every refusal of a
121
+ * claim names its holder through this, in its message and in its `details`; a caller's own
122
+ * fact (`facts`) has its own closed reading (lib/core.mjs claimAction). Only for what is shown:
123
+ * who holds the claim, and whether it lives, is decided on the record as it is. */
124
+ export function shownHolder(record) {
125
+ const { pid, at, processStart: start } = record && typeof record === "object" ? record : {};
126
+ return {
127
+ pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null,
128
+ since: isInstant(at) ? at : null,
129
+ start: isStartToken(start) ? start : null,
130
+ };
131
+ }
132
+
133
+ /** The refusal for a claim `path` that could not be taken because of `e`, an error that is not the
134
+ * kernel's. The caller's command did nothing: it acts only once it holds its claim. Also for a
135
+ * caller that fails to make the claim's directory. `ended` is what this acquisition's takeovers
136
+ * ended before `e`: with it the answer names that first and says "nothing else was done". An
137
+ * error that is the kernel's is returned as it is before any effect, and after what was ended
138
+ * otherwise: the refusals of a claim are made for `ended` already, and one that was not still
139
+ * never says, by its code, that nothing happened. The one error on the way to a claim that itself
140
+ * comes after something was done says so (takeOver: the claim of a gone holder that cannot be
141
+ * removed once that holder's step was ended). */
142
+ export function claimUnavailable(path, e, ended) {
143
+ return afterEndedSteps(ended, asKernelError(e, "E_LIFECYCLE_FAILED", `the claim ${path} could not be taken (${e?.message ?? e}); ${nothingAfter(ended)}`));
144
+ }
145
+
146
+ /** Take the claim `path` → this holding (`{ pid, processStart, nonce, at }`, with `opts.facts`), to
147
+ * pass to releaseClaim. Throws the caller's refusal when it cannot be taken, and claimUnavailable for
148
+ * any error that is not the kernel's. The directory exists. */
149
+ export function acquireClaim(path, opts, depth = 0) {
150
+ const endedSteps = [];
151
+ try { return takeClaim(path, opts, depth, endedSteps); }
152
+ catch (e) { throw claimUnavailable(path, e, endedSteps); }
153
+ }
154
+
155
+ /** `endedSteps` collects what the takeovers of one acquisition ended, nested ones included; every
156
+ * refusal is handed it as it is when the refusal is made. */
157
+ function takeClaim(path, opts, depth, endedSteps) {
158
+ const { busy, waitMs = CLAIM_WAIT_MS } = opts;
159
+ const own = processStart(process.pid);
160
+ if (own.state !== "alive") throw opts.ownStartUnreadable(own.reason ?? `pid ${process.pid} reads as ${own.state}`, path, endedSteps);
161
+ const me = { ...opts.facts, pid: process.pid, processStart: own.token, nonce: randomBytes(16).toString("hex"), at: new Date().toISOString() };
162
+ const tmp = `${path}.tmp-${process.pid}-${me.nonce}`;
163
+ writeFileSync(tmp, JSON.stringify(me) + "\n", { mode: 0o600 });
164
+ try {
165
+ const deadline = Date.now() + waitMs;
166
+ for (let freed = 0; ;) {
167
+ try { linkSync(tmp, path); return me; }
168
+ catch (e) { if (e?.code !== "EEXIST") throw e; }
169
+ const holder = readClaim(path);
170
+ if (holder?.unreadable) throw opts.unreadableClaim(path, endedSteps);
171
+ const live = holder ? processLiveness(holder) : null;
172
+ // Unreadable is never taken for gone: the claim is kept, and the refusal names the way out.
173
+ if (live?.state === "unknown") throw busy(holder, live.reason, path, endedSteps);
174
+ const gone = live?.state === "gone";
175
+ const stuck = gone ? cannotBeTakenOver(holder, depth) : null;
176
+ if (stuck) throw opts.cannotTakeOver(holder, path, stuck, endedSteps);
177
+ // Nobody holds it: the link said it exists and it reads as absent (released in between; or a
178
+ // path that never reads, a dangling symbolic link), or its holder is gone and it is taken
179
+ // over below. The next pass is owed even with no time to wait, but not for ever.
180
+ const free = !holder || gone;
181
+ // What this pass answers once its time is up, about the file as it has just been read. A
182
+ // gone holder here is the last of several: each pass took the one before over, and the
183
+ // claim was taken again before this process could. The file is a claim like any other.
184
+ const refusal = !holder ? () => opts.unreadableClaim(path, endedSteps)
185
+ : gone ? () => opts.heldAgain(holder, path, freed, endedSteps)
186
+ : () => busy(holder, null, path, endedSteps);
187
+ // One check of its time and one pause for every pass that did not take the claim: nothing
188
+ // above starts the next pass (lib/remote.mjs withCacheWriteLock, the same rule).
189
+ if (Date.now() >= deadline) {
190
+ if (!(free && freed < CLAIM_FREED_RETRIES)) throw refusal();
191
+ freed++;
192
+ }
193
+ if (gone) takeOver(path, holder, opts, depth, endedSteps);
194
+ pauseSync(CLAIM_PAUSE_MS);
195
+ }
196
+ } finally {
197
+ try { unlinkSync(tmp); } catch { /* gone */ }
198
+ }
199
+ }
200
+
201
+ /** Why the claim of the gone `holder`, met at `depth`, cannot be taken over → a clause, or null
202
+ * when it can. A takeover is serialized on the holder's nonce, so a file without one that this
203
+ * kernel writes is not removed by anybody (removeGoneClaim skips it too). */
204
+ function cannotBeTakenOver(holder, depth) {
205
+ if (typeof holder.nonce !== "string" || !NONCE_RE.test(holder.nonce)) return "its nonce is not the 32 hexadecimal digits a claim carries";
206
+ if (depth >= CLAIM_MAX_DEPTH) return `it is the claim of a takeover nested ${CLAIM_MAX_DEPTH} deep`;
207
+ return null;
208
+ }
209
+
210
+ /** Remove `path`, held by the dead `holder`, under the claim that serializes takeovers of it. What
211
+ * it ended of the holder's goes to `endedSteps`, once the claim is removed. */
212
+ function takeOver(path, holder, opts, depth, endedSteps) {
213
+ const reclaim = `${path}.reclaim-${holder.nonce}`;
214
+ let me;
215
+ try { me = takeClaim(reclaim, opts, depth + 1, endedSteps); }
216
+ catch (e) {
217
+ // The system will not name the claim of this takeover: `path` is as deep as takeovers nest
218
+ // here. Its own answer is read, never a limit assumed, so this holds on any file system; and
219
+ // it comes before the holder's step is ended or anything is removed. A refusal from a level
220
+ // below is a kernel error and passes as it is, so the answer names the deepest claim reached.
221
+ if (e?.code === "ENAMETOOLONG") throw opts.cannotTakeOver(holder, path, "the claim of one more takeover would have a name longer than this file system allows", endedSteps);
222
+ throw claimUnavailable(reclaim, e, endedSteps);
223
+ }
224
+ try {
225
+ const now = readClaim(path);
226
+ if (now?.nonce === holder.nonce) {
227
+ const ended = opts.endHolderStep?.(now, path, endedSteps) ?? {};
228
+ if (ended.refusal) throw ended.refusal;
229
+ if (ended.warning) opts.warnings?.push(ended.warning);
230
+ try { unlinkSync(path); }
231
+ catch (e) {
232
+ // The holder's step is ended by now: "nothing was done" (claimUnavailable) would not be true.
233
+ if (!ended.ended) throw e;
234
+ throw asKernelError(e, "E_LIFECYCLE_FAILED", `the claim ${path} could not be taken (${e?.message ?? e}): ${ended.ended}, and the claim it left is kept; ${NOTHING_ELSE}`);
235
+ }
236
+ if (ended.ended) endedSteps.push(ended.ended);
237
+ }
238
+ } finally {
239
+ releaseClaim(reclaim, me);
240
+ }
241
+ }
242
+
243
+ /** Release the claim `path`, only while it still names the holding `me`. */
244
+ export function releaseClaim(path, me) {
245
+ if (readClaim(path)?.nonce === me.nonce) { try { unlinkSync(path); } catch { /* gone */ } }
246
+ }
247
+
248
+ /** Record (or, with null, clear) a step of the holding `me` in its claim `path`, for a takeover to
249
+ * end (`endHolderStep`). Only the live holder writes its claim. */
250
+ export function recordInClaim(path, me, step) {
251
+ const tmp = `${path}.tmp-${process.pid}-${me.nonce}`;
252
+ writeFileSync(tmp, JSON.stringify({ ...me, ...(step ?? {}) }) + "\n", { mode: 0o600 });
253
+ renameSync(tmp, path);
254
+ }
255
+
256
+ /** Remove the claim `path` when its holder is verifiably gone, through the takeover above, and
257
+ * take nothing: for a claim nobody will come back for. → whether it was removed. A claim whose
258
+ * holder is alive, unknown or unreadable, or that cannot be taken over (cannotBeTakenOver), is
259
+ * left as it is. Throws what a takeover throws. */
260
+ export function removeGoneClaim(path, opts) {
261
+ const holder = readClaim(path);
262
+ if (!holder || holder.unreadable || cannotBeTakenOver(holder, 0)) return false;
263
+ if (processLiveness(holder).state !== "gone") return false;
264
+ takeOver(path, holder, opts, 0, []);
265
+ return readClaim(path)?.nonce !== holder.nonce;
266
+ }