@awebai/oats 0.51.0 → 0.53.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 (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  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/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
package/lib/claim.mjs CHANGED
@@ -1,45 +1,117 @@
1
1
  /** The claim: one file that says which process is doing a thing that must happen once at a time.
2
2
  * One protocol, used by `oats worktree add|remove` (the purpose's claim, lib/worktree.mjs
3
- * `withClaim`) and by `oats retire` (the home's claim, lib/core.mjs `retireInstance`).
3
+ * `withClaim`) and by `oats retire` and `oats instance stop` (the home's claim, lib/core.mjs
4
+ * `claimHomeFor`).
4
5
  *
5
6
  * Unlike lib/dir-lock.mjs, a claim left by a process that died is taken over, so a killed command
6
7
  * can always be run again: the owner is named by pid AND start time (processLiveness), never by a
7
8
  * pid alone, and a holder whose start cannot be read is never taken for gone.
8
9
  *
9
- * - Taking it: the owner's facts `{ pid, processStart, nonce, at }` are written to a private file
10
- * and hard-linked to `path`, which fails if `path` exists. So a claim is never seen without its
11
- * owner, and the nonce makes each holding distinct, even for the same process.
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.
12
14
  * - Its owner is alive: waited for up to `waitMs`, then refused (`busy`).
13
- * - Its owner is gone (processLiveness "gone"; "unknown" is refused, never taken over): the claim
14
- * is removed under a second claim, `<path>.reclaim-<owner nonce>`, taken by this same protocol.
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.
15
18
  * Its holder re-reads `path` and removes it only if it still names that owner. Nothing else
16
19
  * removes another's claim: its owner never releases it, and a new acquirer cannot write over an
17
20
  * existing file. Two takeovers of one dead owner are therefore serialized, and neither removes
18
21
  * a claim made after it read. A takeover cut short leaves its own claim behind, which the next
19
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.
20
31
  * - A step the holder recorded in its claim (recordInClaim) is ended by a takeover first
21
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.
22
40
  * - Released by unlinking `path`, only while it still names this holding.
23
- * - An unreadable claim file is never removed: the command is refused, naming the file.
41
+ * - A claim that could not be WRITTEN is marked as that, for the one caller that then reads it
42
+ * in place of taking it (`oats instance stop --apply`: lib/core.mjs claimHomeFor). The mark is
43
+ * made at the place, one of the claim's writes (claimWrite: its directory, its private file,
44
+ * its link, and the same of a takeover's own claim), for the system's code as it was thrown
45
+ * there, one of CLAIM_UNWRITABLE_CODES; it travels on the refusal (unwritableCode). No reader
46
+ * of an answer's code, words or details can tell this failure from another, and none tries:
47
+ * a defect, and a claim that could not be removed, are E_LIFECYCLE_FAILED too. Whether
48
+ * anybody holds a claim that was not taken is read by claimUnheld, which says "nobody" only
49
+ * of a path that is absent or of a claim whose holder is verifiably gone.
50
+ * - A claim is read back as whatever JSON is in its file, and the file is where others than its
51
+ * writer can write. Who holds it, and whether that process lives, is decided on the record as
52
+ * it is; what an ANSWER shows of it is only what shownHolder allows, never the file's text.
53
+ * - An unreadable claim file is never removed: the command is refused, naming the file. So is a
54
+ * path that exists and keeps reading as absent (a dangling symbolic link where the claim
55
+ * belongs), once the retries below are spent.
56
+ * - Every pass that does not take the claim falls through one check of its time and one pause
57
+ * (takeClaim): none starts the next pass at once, so no state of the path makes it spin, and
58
+ * each ends in a refusal within `waitMs` plus CLAIM_FREED_RETRIES pauses (awebai/oats#874).
59
+ * A claim that every one of those passes found held again by a process that is gone, after it
60
+ * took the one before over, is refused with `heldAgain`: an ordinary claim, which the next
61
+ * run takes over.
62
+ * - A claim that cannot be taken for a reason of the system's (its directory cannot be made, its
63
+ * private file cannot be written, the link fails otherwise than because the claim exists) is
64
+ * refused as E_LIFECYCLE_FAILED (claimUnavailable), never with the system's code
65
+ * (awebai/oats#874): the claim was not taken, so nothing was done.
24
66
  *
25
- * Everything is synchronous. What is the caller's own goes in `opts`:
26
- * busy(holder, unknown, at) the refusal for a holder that lives (`unknown` unset) or whose
27
- * liveness cannot be read (`unknown` is the reason); `at` is the
28
- * claim file that names it
29
- * ownStartUnreadable(reason, at) the refusal when this process's own start cannot be read, so
30
- * it could not hold `at` verifiably
31
- * unreadableClaim(at) the refusal for a claim file that does not parse
32
- * endHolderStep(holder, at) optional: end the step a dead holder recorded
33
- * → { owed?, remedy?, warning?, details? }
67
+ * Everything is synchronous. What is the caller's own goes in `opts`. Each refusal is an error
68
+ * whose message states its effects, once: in the caller's words for "nothing was done" before
69
+ * any effect, and as "nothing else was done" when `ended`, its last argument, names what this
70
+ * acquisition's takeovers ended before it:
71
+ * busy(holder, unknown, at, ended) the refusal for a holder that lives (`unknown` unset)
72
+ * or whose liveness cannot be read (`unknown` is the
73
+ * reason); `at` is the claim file that names it
74
+ * ownStartUnreadable(reason, at, ended) the refusal when this process's own start cannot be
75
+ * read, so it could not hold `at` verifiably
76
+ * unreadableClaim(at, ended) the refusal for a claim file that does not parse, or
77
+ * for a path that exists and cannot be read as one
78
+ * cannotTakeOver(holder, at, why, ended) the refusal for a holder that is gone and whose claim
79
+ * file `at` this kernel cannot take over; `why` is a
80
+ * clause saying what stops it
81
+ * heldAgain(holder, at, times, ended) the refusal for a claim that this command found
82
+ * without a live holder `times` times and that was
83
+ * taken again each time, the last time by `holder`,
84
+ * which is gone: nothing is wrong with `at`
85
+ * endHolderStep(holder, at, ended) optional: end the step a dead holder recorded
86
+ * → { refusal?, warning?, ended? }; `refusal` is the
87
+ * caller's answer for a step that could not be ended
88
+ * (`at` is kept); `ended` is a clause naming what it
89
+ * ended, when it ended something
34
90
  * waitMs how long a live holder is waited for (default CLAIM_WAIT_MS)
35
- * warnings optional array a takeover's warnings are pushed to */
36
- import { linkSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
91
+ * warnings optional array a takeover's warnings are pushed to
92
+ * facts optional object, what the caller's claim says besides its
93
+ * owner (a home's lifecycle claim: `action`, the holder's verb).
94
+ * It is in the record that is linked, so the claim is never
95
+ * seen without it; the owner's four fields win over it */
96
+ import { linkSync, lstatSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
37
97
  import { randomBytes } from "node:crypto";
38
- import { processLiveness, processStart } from "./worktree-hooks.mjs";
98
+ import { isStartToken, processLiveness, processStart } from "./worktree-hooks.mjs";
99
+ import { NOTHING_ELSE, afterEndedSteps, asKernelError, nothingAfter } from "./errors.mjs";
39
100
 
40
101
  export const CLAIM_WAIT_MS = 3000;
41
102
  const CLAIM_MAX_DEPTH = 8;
103
+ /** How long a pass that did not take the claim pauses before the next one. */
104
+ const CLAIM_PAUSE_MS = 50;
105
+ /** How many passes that found nobody holding the claim (it read as absent, or its holder was gone
106
+ * and it was taken over) are followed by another once `waitMs` is over; passes before that are
107
+ * not counted. With `waitMs: 0` that is every retry there is: enough for the true race, a claim
108
+ * released or freed between two steps of this process, and an end for a path that never becomes
109
+ * a claim. */
110
+ const CLAIM_FREED_RETRIES = 5;
42
111
  const NONCE_RE = /^[0-9a-f]{32}$/;
112
+ 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$/;
113
+ /** Whether `at` is an instant exactly as `toISOString()` gives it, and one that exists. */
114
+ const isInstant = (at) => typeof at === "string" && ISO_INSTANT.test(at) && !Number.isNaN(Date.parse(at)) && new Date(at).toISOString() === at;
43
115
  const pauseSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
44
116
 
45
117
  /** The claim at `path` → its record, `{ unreadable: true }` when it does not parse, null when there is none. */
@@ -48,53 +120,209 @@ export function readClaim(path) {
48
120
  catch (e) { return e.code === "ENOENT" ? null : { unreadable: true }; }
49
121
  }
50
122
 
51
- /** Take the claim `path` → this holding (`{ pid, processStart, nonce, at }`), to pass to
52
- * releaseClaim. Throws the caller's refusal when it cannot be taken. The directory exists. */
123
+ /** What of the claim record `record` may be shown in an answer → `{ pid, since, start }`, each
124
+ * null unless it has the shape takeClaim writes it in:
125
+ * pid the record's `pid`, a positive safe integer;
126
+ * since the record's `at`, exactly what `toISOString()` gives (`2026-01-01T00:00:00.000Z`);
127
+ * start the record's `processStart`, a token of the kernel's (worktree-hooks isStartToken).
128
+ * A claim is a file in a directory that other instances of the deployment can write, and it is
129
+ * read back as whatever JSON is there: text of it is never part of an answer. Every refusal of a
130
+ * claim names its holder through this, in its message and in its `details`; a caller's own
131
+ * fact (`facts`) has its own closed reading (lib/core.mjs claimAction). Only for what is shown:
132
+ * who holds the claim, and whether it lives, is decided on the record as it is. */
133
+ export function shownHolder(record) {
134
+ const { pid, at, processStart: start } = record && typeof record === "object" ? record : {};
135
+ return {
136
+ pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null,
137
+ since: isInstant(at) ? at : null,
138
+ start: isStartToken(start) ? start : null,
139
+ };
140
+ }
141
+
142
+ /** The system's codes for which a claim that cannot be written is read in place of being taken, by
143
+ * the one verb that may (a stop apply). Each is here for one reason: what stops this process
144
+ * from writing a claim in that directory stops a retire or another stop of the same user as
145
+ * well, so a claim that reads as held by nobody is held by nobody.
146
+ * ENOSPC the file system is full
147
+ * EDQUOT this user's quota is spent
148
+ * EROFS the file system is read-only
149
+ * EACCES, EPERM the claims directory is not writable by this user (EPERM also where the file
150
+ * system has no hard links). Every instance of a deployment can change that
151
+ * directory, and one that takes write permission from it must not take Stop from the
152
+ * operator.
153
+ * It is not true of space that is freed a moment later, nor of a process of another user. Any
154
+ * other code (EIO, EMFILE, ENAMETOOLONG, EEXIST from a file where the directory belongs) says
155
+ * nothing about who else could write there, and is never in this list. */
156
+ export const CLAIM_UNWRITABLE_CODES = Object.freeze(["ENOSPC", "EDQUOT", "EROFS", "EACCES", "EPERM"]);
157
+ const UNWRITABLE = Symbol("oats.claimUnwritable");
158
+ /** Make one of a claim's writes: `write()`, and what it returns. An error of the system's it
159
+ * throws with a code of CLAIM_UNWRITABLE_CODES is marked with that code and thrown as it is:
160
+ * the place and the code as thrown are what make a claim "one that could not be written"
161
+ * (unwritableCode). For the writes of taking a claim and for no other call: its directory
162
+ * (the caller's mkdir), its private file, its link. */
163
+ export function claimWrite(write) {
164
+ try { return write(); }
165
+ catch (e) {
166
+ if (e instanceof Error && typeof e.syscall === "string" && CLAIM_UNWRITABLE_CODES.includes(e.code)) Object.defineProperty(e, UNWRITABLE, { value: e.code });
167
+ throw e;
168
+ }
169
+ }
170
+ /** The code for which the claim behind `refusal` could not be written (CLAIM_UNWRITABLE_CODES),
171
+ * when that is why it was not taken and nothing was ended before; else undefined. `refusal` is
172
+ * what acquireClaim or claimUnavailable answered. */
173
+ export const unwritableCode = (refusal) => (refusal instanceof Error ? refusal[UNWRITABLE] : undefined);
174
+
175
+ /** The refusal for a claim `path` that could not be taken because of `e`, an error that is not the
176
+ * kernel's. The caller's command did nothing: it acts only once it holds its claim. Also for a
177
+ * caller that fails to make the claim's directory. `ended` is what this acquisition's takeovers
178
+ * ended before `e`: with it the answer names that first and says "nothing else was done". An
179
+ * error that is the kernel's is returned as it is before any effect, and after what was ended
180
+ * otherwise: the refusals of a claim are made for `ended` already, and one that was not still
181
+ * never says, by its code, that nothing happened. The one error on the way to a claim that itself
182
+ * comes after something was done says so (takeOver: the claim of a gone holder that cannot be
183
+ * removed once that holder's step was ended). */
184
+ export function claimUnavailable(path, e, ended) {
185
+ const refusal = asKernelError(e, "E_LIFECYCLE_FAILED", `the claim ${path} could not be taken (${e?.message ?? e}); ${nothingAfter(ended)}`);
186
+ // The mark of a write that failed (claimWrite) goes with the refusal. Once something was ended
187
+ // the answer is another error, made below, and carries none: nobody reads a claim in the place
188
+ // of an answer that says what was done.
189
+ const code = unwritableCode(e);
190
+ if (code && refusal !== e) Object.defineProperty(refusal, UNWRITABLE, { value: code });
191
+ return afterEndedSteps(ended, refusal);
192
+ }
193
+
194
+ /** Whether anybody holds the claim `path`, read and not taken: for the caller whose claim could
195
+ * not be written (unwritableCode). Returns when NOBODY holds it, which is said only of a path
196
+ * that is absent and of a claim whose holder is verifiably gone and that could be taken over
197
+ * (it is left as it is). Throws otherwise, what taking it would have answered for what is
198
+ * there, from the caller's refusals (`opts`, as acquireClaim takes them):
199
+ * a holder that lives, or whose liveness cannot be read busy
200
+ * bytes that are no claim; a directory; a path that is
201
+ * there and reads as absent (a dangling symbolic link) unreadableClaim
202
+ * a gone holder whose claim no kernel can take over cannotTakeOver
203
+ * and `otherwise`, the refusal of the write that failed, when the read itself fails for a
204
+ * reason of the system's: the path was not reached, so neither a holder nor nobody was
205
+ * established. The read is positive or it is nothing. */
206
+ export function claimUnheld(path, opts, otherwise) {
207
+ for (let pass = 0; ; pass++) {
208
+ let text;
209
+ try { text = readFileSync(path, "utf8"); }
210
+ catch (e) {
211
+ // Something is there that is no file to read: no claim, as the taking finds it.
212
+ if (e?.code === "EISDIR") throw opts.unreadableClaim(path, []);
213
+ if (e?.code !== "ENOENT") throw otherwise;
214
+ // Absent, unless the path itself is there: a link to nowhere reads as absent for ever.
215
+ let entry;
216
+ try { entry = lstatSync(path); } catch (e2) { if (e2?.code === "ENOENT") return; throw otherwise; }
217
+ // A claim made between the two reads is read again, once, and is a claim.
218
+ if (entry.isSymbolicLink() || pass) throw opts.unreadableClaim(path, []);
219
+ continue;
220
+ }
221
+ let holder;
222
+ try { holder = JSON.parse(text); } catch { holder = null; }
223
+ // readClaim's own reading of bytes that are no claim, `unreadable` in a record included.
224
+ if (!holder || typeof holder !== "object" || holder.unreadable) throw opts.unreadableClaim(path, []);
225
+ const live = processLiveness(holder);
226
+ if (live.state !== "gone") throw opts.busy(holder, live.state === "unknown" ? live.reason : null, path, []);
227
+ const stuck = cannotBeTakenOver(holder, 0);
228
+ if (stuck) throw opts.cannotTakeOver(holder, path, stuck, []);
229
+ return;
230
+ }
231
+ }
232
+
233
+ /** Take the claim `path` → this holding (`{ pid, processStart, nonce, at }`, with `opts.facts`), to
234
+ * pass to releaseClaim. Throws the caller's refusal when it cannot be taken, and claimUnavailable for
235
+ * any error that is not the kernel's. The directory exists. */
53
236
  export function acquireClaim(path, opts, depth = 0) {
237
+ const endedSteps = [];
238
+ try { return takeClaim(path, opts, depth, endedSteps); }
239
+ catch (e) { throw claimUnavailable(path, e, endedSteps); }
240
+ }
241
+
242
+ /** `endedSteps` collects what the takeovers of one acquisition ended, nested ones included; every
243
+ * refusal is handed it as it is when the refusal is made. */
244
+ function takeClaim(path, opts, depth, endedSteps) {
54
245
  const { busy, waitMs = CLAIM_WAIT_MS } = opts;
55
246
  const own = processStart(process.pid);
56
- if (own.state !== "alive") throw opts.ownStartUnreadable(own.reason ?? `pid ${process.pid} reads as ${own.state}`, path);
57
- const me = { pid: process.pid, processStart: own.token, nonce: randomBytes(16).toString("hex"), at: new Date().toISOString() };
247
+ if (own.state !== "alive") throw opts.ownStartUnreadable(own.reason ?? `pid ${process.pid} reads as ${own.state}`, path, endedSteps);
248
+ const me = { ...opts.facts, pid: process.pid, processStart: own.token, nonce: randomBytes(16).toString("hex"), at: new Date().toISOString() };
58
249
  const tmp = `${path}.tmp-${process.pid}-${me.nonce}`;
59
- writeFileSync(tmp, JSON.stringify(me) + "\n", { mode: 0o600 });
60
250
  try {
251
+ // Inside the block that removes it: a write that fails after the file was created (a full
252
+ // file system does exactly that) leaves nothing behind.
253
+ claimWrite(() => writeFileSync(tmp, JSON.stringify(me) + "\n", { mode: 0o600 }));
61
254
  const deadline = Date.now() + waitMs;
62
- for (;;) {
63
- try { linkSync(tmp, path); return me; }
64
- catch (e) { if (e.code !== "EEXIST") throw e; }
255
+ for (let freed = 0; ;) {
256
+ try { claimWrite(() => linkSync(tmp, path)); return me; }
257
+ catch (e) { if (e?.code !== "EEXIST") throw e; }
65
258
  const holder = readClaim(path);
66
- if (holder === null) continue; // released in between
67
- if (holder.unreadable) throw opts.unreadableClaim(path);
68
- const live = processLiveness(holder);
259
+ if (holder?.unreadable) throw opts.unreadableClaim(path, endedSteps);
260
+ const live = holder ? processLiveness(holder) : null;
69
261
  // Unreadable is never taken for gone: the claim is kept, and the refusal names the way out.
70
- if (live.state === "unknown") throw busy(holder, live.reason, path);
71
- if (live.state === "gone") {
72
- if (depth >= CLAIM_MAX_DEPTH || typeof holder.nonce !== "string" || !NONCE_RE.test(holder.nonce)) throw busy(holder, null, path);
73
- takeOver(path, holder, opts, depth);
74
- continue;
262
+ if (live?.state === "unknown") throw busy(holder, live.reason, path, endedSteps);
263
+ const gone = live?.state === "gone";
264
+ const stuck = gone ? cannotBeTakenOver(holder, depth) : null;
265
+ if (stuck) throw opts.cannotTakeOver(holder, path, stuck, endedSteps);
266
+ // Nobody holds it: the link said it exists and it reads as absent (released in between; or a
267
+ // path that never reads, a dangling symbolic link), or its holder is gone and it is taken
268
+ // over below. The next pass is owed even with no time to wait, but not for ever.
269
+ const free = !holder || gone;
270
+ // What this pass answers once its time is up, about the file as it has just been read. A
271
+ // gone holder here is the last of several: each pass took the one before over, and the
272
+ // claim was taken again before this process could. The file is a claim like any other.
273
+ const refusal = !holder ? () => opts.unreadableClaim(path, endedSteps)
274
+ : gone ? () => opts.heldAgain(holder, path, freed, endedSteps)
275
+ : () => busy(holder, null, path, endedSteps);
276
+ // One check of its time and one pause for every pass that did not take the claim: nothing
277
+ // above starts the next pass (lib/remote.mjs withCacheWriteLock, the same rule).
278
+ if (Date.now() >= deadline) {
279
+ if (!(free && freed < CLAIM_FREED_RETRIES)) throw refusal();
280
+ freed++;
75
281
  }
76
- if (Date.now() >= deadline) throw busy(holder, null, path);
77
- pauseSync(50);
282
+ if (gone) takeOver(path, holder, opts, depth, endedSteps);
283
+ pauseSync(CLAIM_PAUSE_MS);
78
284
  }
79
285
  } finally {
80
286
  try { unlinkSync(tmp); } catch { /* gone */ }
81
287
  }
82
288
  }
83
289
 
84
- /** Remove `path`, held by the dead `holder`, under the claim that serializes takeovers of it. */
85
- function takeOver(path, holder, opts, depth) {
290
+ /** Why the claim of the gone `holder`, met at `depth`, cannot be taken over → a clause, or null
291
+ * when it can. A takeover is serialized on the holder's nonce, so a file without one that this
292
+ * kernel writes is not removed by anybody (removeGoneClaim skips it too). */
293
+ function cannotBeTakenOver(holder, depth) {
294
+ if (typeof holder.nonce !== "string" || !NONCE_RE.test(holder.nonce)) return "its nonce is not the 32 hexadecimal digits a claim carries";
295
+ if (depth >= CLAIM_MAX_DEPTH) return `it is the claim of a takeover nested ${CLAIM_MAX_DEPTH} deep`;
296
+ return null;
297
+ }
298
+
299
+ /** Remove `path`, held by the dead `holder`, under the claim that serializes takeovers of it. What
300
+ * it ended of the holder's goes to `endedSteps`, once the claim is removed. */
301
+ function takeOver(path, holder, opts, depth, endedSteps) {
86
302
  const reclaim = `${path}.reclaim-${holder.nonce}`;
87
- const me = acquireClaim(reclaim, opts, depth + 1);
303
+ let me;
304
+ try { me = takeClaim(reclaim, opts, depth + 1, endedSteps); }
305
+ catch (e) {
306
+ // The system will not name the claim of this takeover: `path` is as deep as takeovers nest
307
+ // here. Its own answer is read, never a limit assumed, so this holds on any file system; and
308
+ // it comes before the holder's step is ended or anything is removed. A refusal from a level
309
+ // below is a kernel error and passes as it is, so the answer names the deepest claim reached.
310
+ 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);
311
+ throw claimUnavailable(reclaim, e, endedSteps);
312
+ }
88
313
  try {
89
314
  const now = readClaim(path);
90
315
  if (now?.nonce === holder.nonce) {
91
- const ended = opts.endHolderStep?.(now, path) ?? {};
92
- if (ended.owed) {
93
- const e = opts.busy(now);
94
- throw Object.assign(e, { message: `${ended.owed}; ${path} is kept and nothing was done — ${ended.remedy}`, details: { ...e.details, ...ended.details } });
95
- }
316
+ const ended = opts.endHolderStep?.(now, path, endedSteps) ?? {};
317
+ if (ended.refusal) throw ended.refusal;
96
318
  if (ended.warning) opts.warnings?.push(ended.warning);
97
- unlinkSync(path);
319
+ try { unlinkSync(path); }
320
+ catch (e) {
321
+ // The holder's step is ended by now: "nothing was done" (claimUnavailable) would not be true.
322
+ if (!ended.ended) throw e;
323
+ 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}`);
324
+ }
325
+ if (ended.ended) endedSteps.push(ended.ended);
98
326
  }
99
327
  } finally {
100
328
  releaseClaim(reclaim, me);
@@ -116,11 +344,12 @@ export function recordInClaim(path, me, step) {
116
344
 
117
345
  /** Remove the claim `path` when its holder is verifiably gone, through the takeover above, and
118
346
  * take nothing: for a claim nobody will come back for. → whether it was removed. A claim whose
119
- * holder is alive, unknown or unreadable is left as it is. Throws what a takeover throws. */
347
+ * holder is alive, unknown or unreadable, or that cannot be taken over (cannotBeTakenOver), is
348
+ * left as it is. Throws what a takeover throws. */
120
349
  export function removeGoneClaim(path, opts) {
121
350
  const holder = readClaim(path);
122
- if (!holder || holder.unreadable || typeof holder.nonce !== "string" || !NONCE_RE.test(holder.nonce)) return false;
351
+ if (!holder || holder.unreadable || cannotBeTakenOver(holder, 0)) return false;
123
352
  if (processLiveness(holder).state !== "gone") return false;
124
- takeOver(path, holder, opts, 0);
353
+ takeOver(path, holder, opts, 0, []);
125
354
  return readClaim(path)?.nonce !== holder.nonce;
126
355
  }
@@ -34,6 +34,9 @@ function boundedYaml(source, limits) {
34
34
  }
35
35
  return result;
36
36
  }
37
+ /** The syntax `format: "auto"` reads a document as: one that opens with `{` or `[` is strict JSON, anything
38
+ * else YAML. A writer that rewrites a document keeps it in the syntax this names (lib/local-edit.mjs). */
39
+ export const isJsonSource = (source) => /^[\s]*[\[{]/.test(source);
37
40
  export function parseConfigData(input, { format = "auto", origin = null, limits: requested = {} } = {}) {
38
41
  const limits = dataLimits({ maxBytes: 1024 * 1024, ...requested });
39
42
  const data = typeof input === "string" ? input : byteView(input);
@@ -42,7 +45,7 @@ export function parseConfigData(input, { format = "auto", origin = null, limits:
42
45
  const source = decodeUtf8(input);
43
46
  canonicalJson(origin, { maxBytes: 64 * 1024, maxDepth: 16, maxEntries: 1024 });
44
47
  if (!["auto", "json", "yaml"].includes(format)) throw oatsError("invalid-declaration", "unsupported configuration syntax");
45
- const json = format === "json" || (format === "auto" && /^[\s]*[\[{]/.test(source));
48
+ const json = format === "json" || (format === "auto" && isJsonSource(source));
46
49
  const origins = Object.create(null);
47
50
  let entries = 0;
48
51
  const mark = (pointer, depth, node) => {