@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.
- package/README.md +1 -0
- package/bin/oats.mjs +153 -51
- package/docs/capabilities.md +11 -3
- package/docs/configuration.md +134 -88
- package/docs/desktop-cli-api.md +994 -71
- package/docs/desktop-instance-start.md +56 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +230 -59
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +73 -8
- package/docs/integrations.md +9 -8
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +43 -7
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +15 -5
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.51.0.md +156 -0
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/schedules.md +91 -4
- package/docs/servers.md +21 -2
- package/docs/souls-and-instances.md +113 -21
- package/docs/tui.md +152 -0
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +266 -0
- package/lib/core.mjs +845 -166
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-inspect.mjs +40 -11
- package/lib/instance-lifecycle.mjs +169 -47
- package/lib/launch-preference.mjs +16 -0
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/schedule-host.mjs +154 -22
- package/lib/schedule.mjs +73 -24
- package/lib/servers.mjs +20 -4
- package/lib/session-viewer.mjs +87 -10
- package/lib/system-tools.mjs +39 -0
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +5 -11
- package/lib/worktree-hooks.mjs +116 -23
- package/lib/worktree.mjs +89 -102
- package/package-catalog.json +3 -3
- package/package.json +7 -2
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +548 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +68 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +34 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +142 -0
- package/packages/client/deployment-read-cli.mjs +53 -0
- package/packages/client/display-text.mjs +44 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +54 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +74 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +22 -0
- package/packages/client/instance-tree.mjs +453 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +165 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +372 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +35 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +286 -0
- package/packages/client/readiness-contract.mjs +172 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +126 -0
- package/packages/client/remote-roster.mjs +67 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +183 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +119 -0
- package/packages/client/spawn-preview-cli.mjs +32 -0
- package/packages/client/spawn-preview-contract.mjs +314 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +147 -0
- package/packages/tui/README.md +46 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +29 -0
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/main.mjs +105 -0
- package/packages/tui/lib/term/keys.mjs +323 -0
- package/packages/tui/lib/term/screen.mjs +122 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +49 -0
- package/packages/tui/lib/term/tty.mjs +168 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/frame.mjs +62 -0
- package/packages/tui/lib/views/help.mjs +28 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +29 -22
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- 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
|
+
}
|