@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
@@ -9,8 +9,9 @@ The policy it satisfies: no release capability may permanently depend on
9
9
  GitHub or GitHub Actions. Registry publish works on its own; tags and hosted
10
10
  release assets can follow later.
11
11
 
12
- The last two sections cover the post-publish Desktop check and mirroring a
13
- released `oats.okf`.
12
+ The sections after the lane's own cover release-notes entries, the
13
+ post-publish Desktop check, mirroring a released `oats.okf` and releasing
14
+ `oats.framework`.
14
15
 
15
16
  ## When to use it
16
17
 
@@ -27,13 +28,15 @@ released `oats.okf`.
27
28
 
28
29
  Every phase takes `--tag vX.Y.Z` and reads or writes `stage/<tag>/`
29
30
  (gitignored; `--stage <dir>` overrides). `MANIFEST.json` there records the
30
- SHA, the tarballs and their digests, the assets, and which phases completed.
31
+ SHA, the Node and npm versions it was built with (`node`, `npmVersion`), the
32
+ tarballs and their digests (`npm.tarballs`), the assets, and which phases
33
+ completed.
31
34
  Every external command is printed before it runs and its output is logged
32
35
  under `stage/<tag>/logs/`; a failing step exits non-zero with the log path.
33
36
 
34
37
  | Phase | Mirrors in `release.yml` | Writes |
35
38
  | --- | --- | --- |
36
- | `build --tag vX.Y.Z [--sha <commit>]` | jobs `build-and-test` and `tests` (the lane runs the suite unsharded): notes gate, three-manifest bump, `node --check`, `npm ci`, `npm run check`, Desktop test deps, `npm test`, `pack:check` and the tarball greps, `smoke:tarball`, the `version --json` probe | `npm/*.tgz`, `MANIFEST.json` |
39
+ | `build --tag vX.Y.Z [--sha <commit>]` | jobs `build-and-test` and `tests` (the lane runs the suite unsharded): notes gate, unassembled-entries gate, three-manifest bump, `node --check`, `npm ci`, `npm run check`, Desktop test deps, `npm test`, `pack:check` and the tarball greps, `smoke:tarball`, the `version --json` probe | `npm/*.tgz`, `MANIFEST.json` |
37
40
  | `desktop --tag vX.Y.Z --arch arm64\|x64` | one `desktop-build` matrix leg: desktop `npm ci`, `npm test`, `npm run dist -- --<arch>`, strict deep `codesign --verify` (macOS), `dist:smoke` in build-verify mode | `assets/oats-desktop-*` |
38
41
  | `stage --tag vX.Y.Z` | publish job, "Checksums" (`shasum -a 256`) | `assets/SHA256SUMS.txt` |
39
42
  | `publish-npm --tag vX.Y.Z [--dry-run] --yes` | publish job, the two guarded `npm publish --access public` steps, kernel then adapter | — |
@@ -59,7 +62,9 @@ through `NPM_CONFIG_USERCONFIG` and deleted afterwards, never into the repo.
59
62
  ## A full release from a Mac plus a Linux host
60
63
 
61
64
  Release notes must exist at `docs/release-notes/<tag>.md` on the commit being
62
- released, and the commit must be on `origin/main`. On the Mac:
65
+ released, with no entry file left under `docs/release-notes/next/`
66
+ ([Release-notes entries](#release-notes-entries)), and the commit must be on
67
+ `origin/main`. On the Mac:
63
68
 
64
69
  ```bash
65
70
  git fetch origin
@@ -123,8 +128,20 @@ Everything after `build` reads `MANIFEST.json` and the files already staged:
123
128
  so no checks run on it by themselves; close and reopen it to run them, and
124
129
  do not read missing checks as green. Open the PR by hand if the workflow
125
130
  does not run.
131
+ - **The accepted range also decides which kernel `oats tui` accepts.**
132
+ `ACCEPT_RANGE` (`packages/client/cli-locator.mjs`) is read by the Desktop
133
+ and by the terminal client, which runs the kernel it ships with: a bump
134
+ that leaves the new version outside the range ships an `oats tui` that
135
+ stops at its start with `E_TUI_KERNEL`. The test "the accepted band admits
136
+ the kernel version this Desktop ships with"
137
+ (`packages/desktop/test/cli-locator.test.mjs`) fails for such a bump.
126
138
  - **Legs for hosts you do not have.** The Linux AppImage/DEB need a Linux
127
139
  host; the lane says so and `stage` lists what is missing.
140
+ - **The packaged window launch.** `release.yml` launches the packaged window
141
+ on its Linux leg, under xvfb. The lane's `desktop` phase launches nothing on
142
+ any host, so a lane release reports the Linux launch check as not run. The
143
+ obligation stays open until a hosted run (pushing the tag runs
144
+ `release.yml`) or a person's launch covers it.
128
145
 
129
146
  ## How it relates to `release.yml`
130
147
 
@@ -138,6 +155,196 @@ logic against fixtures, with `npm` stubbed. The two can run in either order:
138
155
  a lane release followed by a workflow run, or a broken workflow run finished
139
156
  by the lane, and neither republishes what the other already did.
140
157
 
158
+ ## The workflow's actions are named by commit
159
+
160
+ `release.yml` holds the publishing rights, so it names every action it uses
161
+ by a full commit id, with the exact version in a comment beside it:
162
+
163
+ ```yaml
164
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
165
+ ```
166
+
167
+ A tag is the action owner's to move, and a commit is not: the code that runs
168
+ with the publishing rights is the code that was read. `build-installers.yml`
169
+ runs the same installer steps, so it names the same commits. Every other
170
+ workflow keeps tags (`actions/checkout@v4`): nothing is published from them.
171
+
172
+ `test/workflow-no-cache.test.mjs` holds this. Its table of the actions that
173
+ were read has a row for each action: `action`, `id`, `version`. In the two files
174
+ every `uses:` is a row's id, the same action is the same id in both, and the
175
+ comment beside an id is the row's version. In every other workflow a `uses:`
176
+ is the major of a row's version.
177
+
178
+ **An id is moved by a pull request, reviewed like any change to that
179
+ workflow.** It changes these together, and nothing else in the two workflow
180
+ files:
181
+
182
+ - the id and the version comment, on every `uses:` line of that action in
183
+ `release.yml` and `build-installers.yml`;
184
+ - the action's row in the table.
185
+
186
+ **The id is read from an exact version tag of the action's own repository**
187
+ (`v4.4.0`, not the moving `v4`). For an annotated tag it is the commit the tag
188
+ object points at:
189
+
190
+ ```bash
191
+ gh api repos/actions/checkout/git/ref/tags/v4.4.0 --jq '.object.type, .object.sha'
192
+ # type `commit`: that is the id. Type `tag`: the id is the tag object's commit:
193
+ gh api repos/actions/checkout/git/tags/<sha of the tag object> --jq '.object.sha'
194
+
195
+ # The same with git. For an annotated tag, the line that ends in ^{} has the id.
196
+ git ls-remote https://github.com/actions/checkout refs/tags/v4.4.0 'refs/tags/v4.4.0^{}'
197
+ ```
198
+
199
+ Never take an id because it resolves, and never copy one from another
200
+ project's workflow. GitHub resolves `owner/action@<id>` for a commit of any
201
+ fork of that action, so an id that works says nothing about whose commit it
202
+ is. The pull request gives, for each id it moves, the tag, the id and the
203
+ command that read it, so that its reviewer repeats the reading.
204
+
205
+ **The commit is read before its row is written**, for whether the action
206
+ saves or restores an Actions cache by itself: its `action.yml`, the actions
207
+ and packages it depends on, and what its entry points call of a cache.
208
+
209
+ - A composite action names other actions. Check, at the id, that its inner
210
+ `uses:` are full commit ids too: then the outer id fixes them.
211
+ - A version of `actions/setup-node` that caches by itself (v5 and later)
212
+ needs `package-manager-cache: false` on every step. The test takes the
213
+ version of an id from the row, so it refuses a step without it.
214
+
215
+ **The two files name their runners by version too** (`ubuntu-24.04`, as they
216
+ name `macos-14`), never by a label that GitHub moves to another system by
217
+ itself (`ubuntu-latest`). The Linux installers are built on that runner, and
218
+ what they need of a system follows the system that built them.
219
+ `pull-request.yml` keeps `ubuntu-latest` on purpose: when the label moves, a
220
+ break on the new system shows in pull-request CI first and not at a release.
221
+
222
+ The labels the two files may name are a list beside the table of actions in
223
+ `test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and `macos-14`. Every job
224
+ of the two files runs on a label of that list, and both files build on the
225
+ same Linux. A label is added to the list by whoever decides the runner, as an
226
+ action's row is by whoever read it.
227
+
228
+ **Moving the runner is a pull request** that changes the label in the two
229
+ files and in the list together, and says what the installers then need.
230
+
231
+ **What the Linux installer needs today**, to compare with at the next move.
232
+ Read from `oats-desktop-0.52.0-linux-amd64.deb`, built on `ubuntu-24.04`
233
+ (sha256
234
+ `a6148c8a7b49404d73e46c81523568accc560843ed2fab0c54ca501f09c481b7`):
235
+
236
+ | part of the DEB | highest glibc symbol version it needs |
237
+ |---|---|
238
+ | the Electron binary, `oats-desktop` | `GLIBC_2.25` |
239
+ | the native module, `node-pty`'s `pty.node` | `GLIBC_2.34` |
240
+
241
+ ```bash
242
+ ar x oats-desktop-<version>-linux-amd64.deb && tar -xf data.tar.xz
243
+ # for the binary and for each native module under resources/app.asar.unpacked:
244
+ objdump -T <file> | grep -o 'GLIBC_[0-9.]*' | sort -uV | tail -1
245
+ ```
246
+
247
+ Nothing of the package is run to read it. The numbers are what the DEB's files
248
+ ask of the system's glibc, not a floor anybody tested on an older system. The
249
+ AppImage, built in the same leg from the same build, was not read. The
250
+ module's number follows the runner that builds it: the symbols it needs at
251
+ 2.34 are the ones a module gets when it is built on a system whose glibc is
252
+ 2.34 or later.
253
+
254
+ ## Release-notes entries
255
+
256
+ A release ships one notes file, `docs/release-notes/v<version>.md`. Between
257
+ releases a pull request does not write its entry into it: it adds its entry
258
+ as a file of its own, and one command moves the entries into the notes file
259
+ in the release-prep pull request. Two pull requests that share no code
260
+ therefore never conflict over their entries.
261
+
262
+ ### For the author of a pull request
263
+
264
+ - **One file, `docs/release-notes/next/<name>.md`**, added by the pull
265
+ request that makes the change. The entry does not go into
266
+ `docs/release-notes/v<next>.md`, which a pull request touches for one
267
+ reason only, the next point.
268
+ - **Correcting an unreleased entry.** A pull request that makes an existing
269
+ unreleased entry untrue corrects that entry where it stands: in the
270
+ unreleased notes file, or in the entry file of the earlier pull request
271
+ while that file is still under `docs/release-notes/next/`. It adds its own
272
+ entry in its own entry file. In the earlier entry it changes only the
273
+ sentences it makes untrue, and its description names them. A released notes
274
+ file is never corrected this way.
275
+ - **The name** is the issue's number and a short slug:
276
+ `991-update-every-pi-folder.md`. Lower-case letters, digits and hyphens,
277
+ then `.md`. The number is a convention: nothing reads the name but the
278
+ order of assembly.
279
+ - **The content is a piece of the notes file:** one or more `## <Section>`
280
+ headings, each followed by its entries, and nothing else. No title, no text
281
+ before the first heading. Write the entry as it will read in the notes
282
+ file. The sections, in the notes file's order, are `Upgrade`, `Added`,
283
+ `Changed`, `Fixed`, `Removed`, `Provider updates` and `Documentation`. A
284
+ heading is one of them exactly, from the first column.
285
+ - **Links are written for `docs/release-notes/`**, the directory the text
286
+ moves into: a link to `docs/tui.md` has the target `../tui.md`.
287
+ `npm run validate` resolves an entry file's links from that directory. Such
288
+ a link does not resolve when the entry file is opened on its own in a
289
+ browser.
290
+ - **`test/release-notes-entries.test.mjs` holds every entry file on the tree
291
+ to these rules:** the name; a regular file directly in the directory; only
292
+ the seven sections, each at most once; at least one non-blank line under
293
+ each heading; no `# ` title; every fenced block closed. A `## ` line inside
294
+ a fenced block is text.
295
+ - **The directory exists only while it holds entries.** It has no README and
296
+ no placeholder: anything in it counts as an unassembled entry.
297
+
298
+ ### For the tag owner
299
+
300
+ ```bash
301
+ node scripts/assemble-release-notes.mjs --tag v0.54.0
302
+ ```
303
+
304
+ - **It moves every entry into `docs/release-notes/v0.54.0.md`** and removes
305
+ the entry files and the emptied directory. A notes file that does not exist
306
+ is created, with the title `# OATS 0.54.0` and the line `Unreleased`.
307
+ `--root <dir>` works in another tree.
308
+ - **Order.** Files are taken by name as plain strings, what `LC_ALL=C ls`
309
+ prints: `1002-…` comes before `996-…`. In each section a file's text goes
310
+ after what the section already holds. A section the notes file lacks is
311
+ created at its place in the order above. A heading that is not one of the
312
+ seven, such as a hand-written highlight, stays where it is.
313
+ - **It moves text and rewrites none.** Every line it did not add is kept as
314
+ it is, except blank lines where text goes in. It sets no date in place of
315
+ `Unreleased` and sorts nothing inside a section: reorder entries by hand in
316
+ the prep pull request, where the result is reviewed as a diff.
317
+ - **All or nothing.** With a problem in any entry, or a notes file that holds
318
+ a section twice or a fenced block that is never closed, it prints every
319
+ problem, writes nothing, removes nothing and exits 2.
320
+ - **An interrupted run.** The command writes the notes file first and removes
321
+ the entry files after it. A run that stops in between leaves entry files
322
+ beside a notes file that already holds their text, and a second run would
323
+ add that text again. Put the tree back first, one of two ways: delete the
324
+ entry files that are left, whose text the notes file holds, and the run is
325
+ complete; or return all of `docs/release-notes/` to what Git has, which is
326
+ the notes file (deleted, if this run created it) and the entry files
327
+ already removed, and run the command again. A run that stops before it
328
+ writes the notes file has changed neither; at most it leaves a `.tmp` file
329
+ beside the notes file.
330
+ - **Running it more than once in a release is normal.** The pull request that
331
+ moves the manifests to a new version runs it to create that version's notes
332
+ file, which `test/release-packaging.test.mjs` requires for the version the
333
+ manifests carry. The release-prep pull request runs it again for the
334
+ entries merged since, which go after the earlier ones.
335
+ - **A tag is refused while anything is under `docs/release-notes/next/`:** by
336
+ the `build-and-test` job of `release.yml` and by `release-lane.mjs build`,
337
+ each right after its notes-file gate and before anything is built. Each
338
+ names the command to run. The kernel package carries all of `docs/`, so
339
+ these two gates are also what keeps an unassembled entry out of a published
340
+ tarball.
341
+
342
+ ### When it starts
343
+
344
+ When the change that adds this section is on `main`. Entries already in
345
+ `docs/release-notes/v0.53.0.md` stay there. A pull request in flight that has
346
+ to rebase for the notes anyway may move its entry into a file at that rebase.
347
+
141
348
  ## Desktop release verification
142
349
 
143
350
  Installer CI gates what headless runners can prove reliably for every
@@ -150,11 +357,16 @@ The macOS x64 leg cross-builds on macos-14 and installs Rosetta 2 so that its
150
357
  x64 Electron + node-pty ABI probe really executes; a wrong-architecture
151
358
  native module fails that leg.
152
359
 
153
- CI does **not** gate the packaged GUI launch: ad-hoc-signed, non-notarized
154
- Electron apps do not
155
- have a reliable interactive windowserver in headless CI. Post-publish launch
156
- acceptance is therefore owned by the operator/maintainer, using the actual
157
- released installers (not a source checkout):
360
+ CI launches the packaged window on the Linux leg only: `release.yml` and
361
+ `build-installers.yml` run the smoke once more with its launch phase, under
362
+ xvfb, and a window that does not reach the shell fails the leg. That is the
363
+ unpacked Linux build, not an installed AppImage or DEB. CI does **not** gate
364
+ the macOS launch: ad-hoc-signed, non-notarized Electron apps do not
365
+ have a reliable interactive windowserver in headless CI. The lane does not
366
+ launch the window: see
367
+ [What the lane cannot produce](#what-the-lane-cannot-produce). Post-publish
368
+ launch acceptance is therefore owned by the operator/maintainer, using the
369
+ actual released installers (not a source checkout):
158
370
 
159
371
  1. Verify the asset checksum/attestation, install it outside the source tree,
160
372
  and on macOS use right-click → **Open** for the Gatekeeper step (ad-hoc
@@ -237,7 +449,9 @@ When the diff is not empty:
237
449
 
238
450
  1. **The framework prep PR.** Bump `version` in the `oats.json` of each
239
451
  changed capability and in `oats-package/oats-package.json`, and add the
240
- release-notes entry. Read the skill lines added since the last tag: a
452
+ release-notes entry as a file under `docs/release-notes/next/`
453
+ ([Release-notes entries](#release-notes-entries)). Read the skill lines
454
+ added since the last tag: a
241
455
  command or behaviour that an older kernel the capability still admits does
242
456
  not have names the version it starts in. Guidance text alone does not
243
457
  raise a capability's `compatibility.oats`.
@@ -32,7 +32,7 @@
32
32
  - Other model, billing, effort or permission banners after a submitted Enter
33
33
  still block (`E_SPAWN_INCOMPLETE`, `blocked`).
34
34
 
35
- See [configuration](../configuration.md#exact-home-launch-prompt-consent)
35
+ See [configuration](../configuration.md#the-development-channel-confirmation)
36
36
  and [recovery](../execution-targets.md#launch-prompt-outcomes).
37
37
  - **The Desktop shows launch-prompt consent and retained launches**
38
38
  ([#711](https://github.com/awebai/oats/issues/711)). The spawn dialog shows a