@awebai/oats 0.55.1 → 0.56.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 (78) hide show
  1. package/bin/oats.mjs +78 -62
  2. package/docs/capabilities.md +67 -3
  3. package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
  4. package/docs/desktop-cli-api.md +317 -35
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +54 -7
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +54 -7
  10. package/docs/integrations.md +1 -1
  11. package/docs/knowledge.md +35 -16
  12. package/docs/official-catalog.md +3 -3
  13. package/docs/packages.md +12 -12
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.56.0.md +699 -0
  16. package/docs/servers.md +21 -5
  17. package/docs/souls-and-instances.md +8 -4
  18. package/docs/tui.md +99 -26
  19. package/docs/upgrading.md +4 -1
  20. package/docs/workspaces.md +26 -6
  21. package/lib/automations.mjs +3 -4
  22. package/lib/bounded-read.mjs +18 -0
  23. package/lib/capability-show.mjs +13 -2
  24. package/lib/claim.mjs +3 -4
  25. package/lib/core.mjs +480 -152
  26. package/lib/errors.mjs +39 -0
  27. package/lib/harness-trust-write.mjs +119 -40
  28. package/lib/harness-trust.mjs +31 -18
  29. package/lib/instance-inspect.mjs +160 -11
  30. package/lib/instance-lifecycle.mjs +47 -30
  31. package/lib/packages.mjs +8 -5
  32. package/lib/pi-bridge.mjs +18 -19
  33. package/lib/remote.mjs +88 -51
  34. package/lib/retire-output.mjs +9 -4
  35. package/lib/schedule.mjs +3 -4
  36. package/lib/servers.mjs +39 -6
  37. package/lib/session-viewer.mjs +25 -1
  38. package/lib/triggers.mjs +3 -4
  39. package/lib/workspace.mjs +6 -6
  40. package/lib/worktree.mjs +10 -6
  41. package/lib/write-through-private-file.mjs +26 -0
  42. package/package-catalog.json +2 -2
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +108 -13
  45. package/packages/client/cli-locator.mjs +16 -14
  46. package/packages/client/deployment-panel.mjs +4 -3
  47. package/packages/client/display-text.mjs +2 -1
  48. package/packages/client/instance-events-contract.mjs +4 -3
  49. package/packages/client/instance-lifecycle.mjs +228 -0
  50. package/packages/client/instance-presentation.mjs +9 -0
  51. package/packages/client/instance-tree.mjs +10 -8
  52. package/packages/client/kernel-lines.mjs +3 -3
  53. package/packages/client/launch-contract.mjs +11 -0
  54. package/packages/client/lifecycle-cli.mjs +12 -6
  55. package/packages/client/lifecycle-confirmation.mjs +407 -0
  56. package/packages/client/lifecycle-contract.mjs +6 -2
  57. package/packages/client/own-codes.mjs +1 -0
  58. package/packages/client/panel-views.mjs +39 -2
  59. package/packages/client/readiness-contract.mjs +2 -2
  60. package/packages/client/remote-roster.mjs +50 -5
  61. package/packages/client/roster-sections.mjs +3 -3
  62. package/packages/client/session-start.mjs +98 -0
  63. package/packages/client/start-gate.mjs +46 -0
  64. package/packages/client/start-messages.mjs +17 -0
  65. package/packages/client/workspace-views.mjs +2 -2
  66. package/packages/tui/README.md +10 -6
  67. package/packages/tui/lib/actions.mjs +4 -2
  68. package/packages/tui/lib/client.mjs +5 -2
  69. package/packages/tui/lib/config.mjs +39 -9
  70. package/packages/tui/lib/main.mjs +83 -13
  71. package/packages/tui/lib/model.mjs +116 -11
  72. package/packages/tui/lib/open.mjs +45 -0
  73. package/packages/tui/lib/read.mjs +46 -10
  74. package/packages/tui/lib/store.mjs +64 -9
  75. package/packages/tui/lib/term/tty.mjs +71 -12
  76. package/packages/tui/lib/views/frame.mjs +115 -33
  77. package/packages/tui/lib/views/help.mjs +37 -8
  78. package/skills/oats-getting-started/SKILL.md +6 -3
@@ -27,19 +27,30 @@ The command writes only the canonical deployment root's native trust leaf:
27
27
  It writes that leaf into every configuration file a launch of the deployment
28
28
  reads. The targets of each selected harness are:
29
29
 
30
- - the ambient file, selected by the operator's own `CLAUDE_CONFIG_DIR` or
31
- `CODEX_HOME`, else the default above;
30
+ - the ambient file: the one a launch of this deployment with no launch
31
+ configuration reads. It is read as every check of a launch reads it
32
+ ([the checks read the pane](execution-targets.md#the-checks-read-the-pane)):
33
+ the `CLAUDE_CONFIG_DIR` or `CODEX_HOME` of the deployment's tmux
34
+ session, else of the OATS tmux server, else the default above under that
35
+ session's or server's `HOME`. It is not the operator's own shell's when
36
+ the server holds another account;
32
37
  - one file for each launch configuration (`launch-configs:` in the
33
38
  deployment's `oats-local.yaml`) of that harness whose `env` sets
34
39
  `CLAUDE_CONFIG_DIR` (claude) or `CODEX_HOME` (codex), as a literal or a
35
40
  `{fromEnv: NAME}` reference resolved from the environment the command runs
36
- in.
41
+ in;
42
+ - one file for each launch configuration of that harness whose `env` sets
43
+ `HOME` and not that variable, when its launch has no such variable at
44
+ all (the session and the server set none either): the default file above
45
+ under that `HOME`, which is the file its launch reads. When the session
46
+ or the server sets the variable, that launch reads the ambient file, and
47
+ the configuration has no file of its own.
37
48
 
38
49
  Targets with the same canonical directory are one file. Each plan entry says
39
50
  whether it is the ambient file (`ambient`) and which launch configurations
40
51
  use it (`launchConfigs`). A launch configuration whose reference is not set,
41
- whose path is not absolute, or whose directory does not exist is a named
42
- `problem` on its entry. OATS never creates a harness configuration directory:
52
+ whose path is not absolute or selects no usable directory, or whose directory does not exist is a named
53
+ `problem` on its entry, for a `HOME` as for the harness's own variable. OATS never creates a harness configuration directory:
43
54
  create it, or start the harness with it once, then rerun. A missing ambient
44
55
  directory (`~/.codex` for a user who has never run Codex, for example) means
45
56
  the harness has not run as this user: with `--harness all` that harness's
@@ -49,6 +60,42 @@ whole plan before a write, as an unsupported file does.
49
60
  Each file is verified through the reader under the environment that selects
50
61
  it.
51
62
 
63
+ The plan shows what will be written before anything is. `warnings` says
64
+ what selects the ambient file when a selector does (`CLAUDE_CONFIG_DIR
65
+ selects <dir> (the global CLAUDE_CONFIG_DIR of the OATS tmux server
66
+ (<socket>)); effective file <file>`). Four cases have no pane to read:
67
+
68
+ - **No OATS tmux server runs.** The command does not start one, and does not
69
+ start your login shell to find out what one would hold. The ambient file
70
+ is then the operator's own, and `warnings` says so: `claude: the pane's
71
+ environment is not established until a spawn starts the OATS tmux server
72
+ (none runs); read instead: this process's CLAUDE_CONFIG_DIR (not set),
73
+ this process's HOME`.
74
+ - **The command has no tmux on its `PATH`.** It makes no read, and no
75
+ prediction: the ambient file is the operator's own, as with no server, and
76
+ `warnings` says so: `claude: the pane's environment is not established:
77
+ this process has no tmux on its PATH to read the OATS tmux server with;
78
+ read instead: …`. If a server does run on this host, run the command with
79
+ a `PATH` that holds tmux, so that it writes for the file launches read.
80
+ - **tmux could not say whether the server runs.** `tmux -L oats
81
+ list-sessions` was refused or cut off. That is a read that failed, not
82
+ "no server runs": one may run, under another account. The ambient target is `refused`, nothing is written, to
83
+ any file, and the command answers `E_RUNTIME_ENDPOINT_UNKNOWN` with what
84
+ failed: `… could not read the OATS tmux server for session <name>:
85
+ <failure>. What has to answer, as this process: \`tmux -L oats
86
+ list-sessions\`. A server that could not be asked may run under another
87
+ account than this process's, so this process's file is not written in its
88
+ place`. Run the command where that tmux command answers.
89
+ - **A server runs and its environment cannot be read** (the read fails, or
90
+ the value holds a `$`, a line break or a character tmux prints encoded;
91
+ `HOME` cleared or missing when there is no selector). The ambient target
92
+ is `refused` with a `problem` that names which name, where it was read
93
+ and what would make it readable, and nothing is written, to any file: the
94
+ command answers `E_RUNTIME_ENDPOINT_UNKNOWN`. It never writes to a file
95
+ guessed from the operator's shell. When a launch configuration's target is
96
+ refused as well, the code is `E_CONFIG_BROKEN`, as for that target alone,
97
+ and the details hold both.
98
+
52
99
  Nonempty override directories must be absolute. Directory aliases are resolved;
53
100
  symlink/nonregular/hardlinked leaves, foreign ownership and ACLs refuse. On Linux, GNU ls's single `.` security-context marker is accepted;
54
101
  the context must be readable, match the same-directory candidate before replacement,
@@ -59,8 +106,8 @@ they are not a live SELinux-host qualification.
59
106
 
60
107
  On macOS, any extended-attribute (`@`) or ACL (`+`) marker deliberately refuses,
61
108
  including `com.apple.provenance`. This v1 writer does not copy or remove those
62
- attributes. Inspect the selected file; a refusal never authorizes stripping its
63
- metadata automatically. Existing file permissions are preserved.
109
+ attributes. See [When the writer refuses](#when-the-writer-refuses); a refusal
110
+ never authorizes stripping its metadata automatically. Existing file permissions are preserved.
64
111
  No configuration directory is ever created; a new file uses 0600. The plan shows the effective file,
65
112
  semantic key, current/desired trust scalar, byte digests and override provenance;
66
113
  it never returns other config values or credentials.
@@ -71,6 +118,55 @@ records. Existing Codex root-trust/yolo per-invocation overrides are unchanged.
71
118
  This command does not enable development-channel prompt consent, change permission
72
119
  mode, authenticate, install a plugin, or establish model/channel readiness.
73
120
 
121
+ ## When the writer refuses
122
+
123
+ The writer refuses a configuration file it cannot replace exactly as it found
124
+ it, and then writes nothing at all. The refused entry's `problem` names the
125
+ file and the check that refused it, in fixed wording; it never repeats the
126
+ file's content or a parser message:
127
+
128
+ | `problem` says the file | Meaning |
129
+ | --- | --- |
130
+ | is not a regular file (a symbolic link, directory or other type) | The path is a link, a directory or another type; only a plain file is replaced. |
131
+ | has more than one hard link | Replacing it would split it from its other names. |
132
+ | is owned by another user | Only a file the current user owns is replaced. |
133
+ | has setuid, setgid or sticky bits set | Special mode bits are not carried across a replacement. |
134
+ | has an extended-attribute (@) or ACL (+) marker in ls ... | macOS extended attributes (such as `com.apple.provenance`) or an ACL, or an ACL on Linux: this writer neither copies nor removes them. The `problem` also gives the way forward, below. |
135
+ | has a Linux security context that cannot be read | `ls -Z` gave no usable context for a file whose `ls` mode shows one. |
136
+ | its metadata could not be read (the ls probe failed or its answer is not recognized) | `ls` failed, or printed a mode this writer does not recognize. |
137
+ | changed while it was being read | Another writer replaced it during the read; rerun. |
138
+ | is not in a usable configuration directory (a path that is not a directory, or one with no existing ancestor) | The directory that should hold the file is not a directory. Target resolution normally reports this first, as the named problem below. |
139
+ | is larger than 8 MiB | The file is over the size the writer reads. |
140
+ | is not valid UTF-8 | The bytes do not decode losslessly. |
141
+ | is not in the supported format (see "Qualified scope and formats" in docs/harness-trust.md) | The editor or the trust reader does not support its shape; see [Qualified scope and formats](#qualified-scope-and-formats). |
142
+ | could not be read (`<errno code>`) | Any other read error, by its code alone (for example `EACCES`). |
143
+
144
+ When the `CLAUDE_CONFIG_DIR`, `CODEX_HOME` or `HOME` that selects the ambient
145
+ file (read as described above) is not an absolute path, or selects no usable
146
+ directory, the ambient entry's `problem` names that variable and where it was
147
+ read, never its value: `the file a claude launch with no launch configuration
148
+ reads could not be established: <where> is not an absolute path`.
149
+ Launch-configuration, missing-directory and unreadable-environment problems
150
+ are described above.
151
+
152
+ **The macOS marker.** On macOS, a configuration file that Claude rewrites can
153
+ carry `com.apple.provenance`, and the writer refuses it. Do not edit the file or
154
+ its attributes. Instead, start a Claude session with the configuration
155
+ directory the launch uses (the same `CLAUDE_CONFIG_DIR`, or none for
156
+ `~/.claude.json`), in the deployment folder, and accept Claude's own
157
+ folder-trust dialog there. The `harness-trust` item of `oats readiness` is the
158
+ check that this is met: it reads the file without the writer's metadata
159
+ checks. Until it passes, spawns in that deployment warn with the line shown in
160
+ [Launch-time checks and readiness](#launch-time-checks-and-readiness). The
161
+ same applies to an ACL marker on Linux, and to Codex with its own trust prompt
162
+ and `CODEX_HOME`.
163
+
164
+ **A refusal does not block the rest of an upgrade.** Only
165
+ `oats harness trust` runs the writer. `oats sync`, `oats readiness` and
166
+ `oats doctor` never call it and start no session; the `harness-trust` item of
167
+ readiness is never required, so a missing trust does not make the deployment
168
+ not ready.
169
+
74
170
  ## Qualified scope and formats
75
171
 
76
172
  Claude 2.1.289 darwin-arm64 was qualified against pinned native source and a
@@ -118,19 +214,40 @@ do not automatically write a second root or answer a trust dialog.
118
214
 
119
215
  Spawn, `session start|restart`, `launch-config preview` and `oats readiness`
120
216
  read folder trust from the file the launch's own environment selects: the
121
- host's environment plus the launch configuration's `env`. Codex's
122
- per-invocation home trust follows the same file. They never write it.
217
+ launch configuration's `env`, else the environment the launch's tmux pane
218
+ will have, never the calling process's in its place
219
+ ([the checks read the pane](execution-targets.md#the-checks-read-the-pane)).
220
+ Codex's per-invocation home trust follows the same file. They never write
221
+ it.
123
222
 
124
223
  Readiness reports one `harness-trust` item (in `checks.configured`, never
125
224
  required) for the launch a home recorded, or for the launch a soul selects.
126
225
  It passes, naming the file, when that file trusts the deployment root or an
127
226
  ancestor (for Claude, up to a Git boundary; a yolo Codex launch always
128
- passes). Otherwise it warns, and the spawn warns with the same text:
227
+ passes). Otherwise it warns, and the spawn warns with the same text, which
228
+ names where the launch gets the file from:
129
229
 
130
230
  ```text
131
- <harness> folder trust is not established in <file>: oats harness trust --dir <deployment>
231
+ <harness> folder trust is not established in <file> (<where from>): oats harness trust --dir <deployment>
132
232
  ```
133
233
 
234
+ `<where from>` is, for example, `the CLAUDE_CONFIG_DIR of launch
235
+ configuration work`, `the CODEX_HOME of tmux session agents` or `under the
236
+ global HOME of the OATS tmux server (<socket>)`. Two more answers:
237
+
238
+ - **The pane's environment could not be read** (a spawn or a start, and
239
+ readiness with a server running): `<harness> folder trust: the
240
+ configuration file this launch will read could not be established (<why,
241
+ and what would make it readable>); nothing is said about its trust`. The
242
+ readiness item is `unknown`, with `file` null.
243
+ - **No pane to read** (readiness with no server running, a spawn with
244
+ `--no-launch`): the file read is the calling process's, and `<where
245
+ from>` says so (`the pane's environment is not established until a spawn
246
+ starts the OATS tmux server (none runs); read instead: this process's
247
+ CODEX_HOME (not set), this process's HOME`). The readiness item is then
248
+ `unknown` whether or not that file establishes trust; a spawn with
249
+ `--no-launch` warns only when it does not.
250
+
134
251
  A missing root entry does not prove that the harness will prompt (a native
135
252
  gate can skip the question), so neither says the session will stop. A launch
136
253
  configuration whose reference is not set on this host is named instead of a
@@ -86,12 +86,12 @@ and the rules its tests pin.
86
86
 
87
87
  | module | owns |
88
88
  |---|---|
89
- | `remote.mjs` | repo refs, reading Git remotes, content digests; `redactUrl` owns [reference display construction and withholding](workspaces.md#repository-references-in-diagnostics). Selected original refused references first use the contract's bounded plain-value rule; other values supply only validated scheme/SCP, host, supported port and path components, or are withheld whole. Raw host/path fragments inherit plain eligibility only from the original selected source, never from the fragment alone; nonplain originals cannot use that exception. Plain-reference recognition is not a secret detector: credential-like text within the permitted alphabet stays visible. Display recognition shares the parser's character rules without calling its error path, and never changes admission or transport. Explicit pinned-source context retains only a constructed reference plus a validated 40-hex commit, remains idempotent, and has no plain fallback; the default context does not infer pins. Each rejection boundary explicitly names its rejected-input fields; the seven selected argument fields use the same bounded plain-value predicate through the renderer, including spaces and colons and without trimming or decoding, never a global field-name rule. Rejected-input messages quote the rendered fields through a formatter at that boundary, so rejected words cannot replace identical words in the fixed reason. Valid operational values are untouched. Refusal context owns the explanation once; forwarding preserves it. `scrubGitLine` delegates the linked whole-Git-line disclosure rule to the renderer before control/length formatting: only proven unchanged original operation refs plus an original line without `@` permit disclosure; all other lines become the fixed notice, with no substring recovery. Construction tests audit raw Git error-text access and quoting routes; generated invariants cover selected diagnostic routes |
89
+ | `remote.mjs` | repo refs, reading Git remotes, content digests; `displayRepoRef` and `displayDiagnosticText` select reference-value and kernel-prose contexts for one private renderer, which owns [reference display construction and withholding](workspaces.md#repository-references-in-diagnostics). Selected original refused references first use the contract's bounded plain-value rule; other values supply only validated scheme/SCP, host, supported port and path components, or are withheld whole. Raw host/path fragments inherit plain eligibility only from the original selected source, never from the fragment alone; nonplain originals cannot use that exception. Plain-reference recognition is not a secret detector: credential-like text within the permitted alphabet stays visible. Display recognition shares the parser's character rules without calling its error path, and never changes admission or transport. Explicit pinned-source context retains only a constructed reference plus a validated 40-hex commit, remains idempotent, and has no plain fallback; the default context does not infer pins. Each rejection boundary explicitly names its rejected-input fields; the seven selected argument fields use the same bounded plain-value predicate through the renderer, including spaces and colons and without trimming or decoding, never a global field-name rule. Rejected-input messages quote the rendered fields through a formatter at that boundary, so rejected words cannot replace identical words in the fixed reason. Valid operational values are untouched. Refusal context owns the explanation once; forwarding preserves it. `scrubGitLine` delegates the linked whole-Git-line disclosure rule to the renderer before control/length formatting: only proven unchanged original operation refs plus an original line without `@` permit disclosure; all other lines become the fixed notice, with no substring recovery. Construction tests audit raw Git error-text access and quoting routes; generated invariants cover selected diagnostic routes |
90
90
  | `local-inputs.mjs` | the local configuration a command read, for `observation.localRevision` |
91
91
  | `workspace.mjs` | workspace, membership and soul files; discovery |
92
92
  | `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
93
93
  | `packages.mjs` | `packages:`, the catalog, `oats sync`, `oats-lock.json` |
94
- | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit |
94
+ | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally |
95
95
  | `materialize.mjs` | copying modules into a home and composing it |
96
96
  | `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
97
97
  | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
@@ -112,6 +112,7 @@ and the rules its tests pin.
112
112
  | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, and the rollback of an interrupted add |
113
113
  | `errors.mjs` | `oatsError`, and the door of the lifecycle verbs: `isKernelCode` (the shape of a kernel code, `^E_[A-Z0-9_]+$`, never a list of codes), `kernelCode`, `asKernelError` and `errorCause`. An answer of `oats retire`, `oats instance stop`, `oats session` and `oats worktree` carries a kernel code, or one of the two names every command answers as they are (`OWN_NAME_FAILURES`: `unsafe-config-key`, `unsafe-config-value`), and no other: `isAnswerCode` is what the door and its wrappers keep, `isKernelCode` stays the test of the shape. An error of the system's or of Node's, a refusal written as a plain `Error` without a code, and a defect (`isDefect`: a `TypeError` and its like without a code, or a thrown value that is no `Error`), is wrapped at the boundary (`bin/oats.mjs` `lifecycleFail`; in a retire, `core.mjs` `retireClaimed`, which also says what the retire had done by then) and its own code goes to `details.cause` (a defect's name does; a plain `Error` without a code has no cause, and is answered with the general code and its message alone, which is what an ordinary refusal of `tmux`, `git` or the kernel itself must read as). New code that answers an error tests the shape with these, never `e.code \|\| "E_…"`: a system error has a `code` too. Whoever ends an error's way up prints the stack of a defect with `reportDefect`: the door, and any code that turns a caught error into a row of results (a stop's `results[]`, a retire's `childrenStopped[]`), after which nobody else can. Two more rules of the lifecycle verbs live here. **`lifecycleBusy(holder, said, remedy, details)` is the only way `E_LIFECYCLE_BUSY` is made** (`test/lifecycle-busy-holder.test.mjs` scans `lib/` and `bin/` for any other): it sets `details.holder` (`BUSY_HOLDERS`: `"running"` only where the kernel established that the other command is alive, `"unknown"`, `"none"`) and refuses to build an `"unknown"` or `"none"` answer without the step that ends it. **`BEFORE_EFFECT_CODES` lists, per verb, the codes that verb answers only before any effect**; `afterFirstEffect` turns a listed code raised after a verb's first effect into a defect (`E_LIFECYCLE_FAILED`, `cause.name: "LateRefusal"`), and is called at the one place of each verb that knows how far it got (`core.mjs` `retireFailure`, from `at.phase`; `instance-lifecycle.mjs` `applyStop`, from whether a target's stop began). A code may join the list only when every place that raises it in that verb is before the first effect; a place found after it gets a code of its own, never the net |
114
114
  | `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire` and `oats instance stop --apply` (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too |
115
+ | `write-through-private-file.mjs` | the one writer of a file written through a private file beside it and renamed over it (`writeThroughPrivateFile`): a failed write or rename removes the private file and throws that failure's error (#1076). The caller gives the private name, the bytes and the mode. A writer that needs more (an exclusive link, an exact mode, a failed removal reported, a sync) keeps its own code |
115
116
  | `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time, and the credential-free `origin` URL. Two questions, two functions: `processStart` says whose a pid is (a zombie still holds its pid and start, which is what proves a recorded process group), `processLiveness` says whether the `oats` command a record names can still act (a zombie cannot: it is gone). Ask `processLiveness` only about an `oats` command's own process, never about a hook's or a harness's pid. `runPs` is the one way the kernel calls `ps` where an identity is read: the program, the fixed environment and how the answer is classified. `isStartToken` says the shape of a start token, once, beside its writer: it decides what of a record may be shown (`claim.mjs` `shownHolder`, `unknownGroupNote`), never whether a process lives |
116
117
  | `system-tools.mjs` | `systemTool`: a program the kernel runs from the system directories (`SYSTEM_TOOL_DIRS`), never from the caller's `PATH`. `ps` runs on the same directories: `worktree-hooks.mjs`'s `PS_ENV` takes its `PATH` from them |
117
118
  | `tmux-server-scope.mjs` | whether the OATS tmux server starts in a systemd scope of its own: the creator's cgroup judged (Linux, inside a `.service`, unified hierarchy), the scope's name and the warning when it cannot |
@@ -125,10 +126,10 @@ and the rules its tests pin.
125
126
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
126
127
  | `launch-prompt-fixtures.mjs` | the development-channel tolerance list (`launch-prompt-fixtures/dev-channel-confirmation.json`): engagement from the argv, the enumerated normalization, equality matching, the `flag-ignored` notice block, the running-session banner hint, what differed, and the Claude version read from the executable's path |
127
128
  | `launch-prompts.mjs`, `launch-prompt-transport.mjs` | bounded launch-only controller and visible-screen transport; private process authority, injectable clock/transport, durable checked receipts, one Enter only on equality with a tolerance entry |
128
- | `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches |
129
+ | `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches; the table of the variable that moves each harness's folder (`HARNESS_FOLDER_VAR`) and the one reader of a launch configuration's (`launchConfigFolder`), used by the trust code, `pi-bridge.mjs` and `core.mjs`: it reads only files and imports none of them. What a launch's pane will have for those variables, `PATH` and `HOME` is `launchEnvironment` in `core.mjs`, the one answer every check of a launch reads ([execution-targets.md](execution-targets.md#the-checks-read-the-pane)); it carries the names the launch removes (`removedLaunchEnv`: declared by its capabilities, not in their payload), which `launchEffectiveEnv` leaves out and the window command (`paneCommand`) unsets ([capabilities.md](capabilities.md#a-declared-name-is-the-providers)) |
129
130
  | `harness-trust-write.mjs` | explicit operator plan/apply, cooperating locks, durable deployment audit and no-rollback outcomes |
130
131
  | `harness-trust-json.mjs`, `harness-trust-toml.mjs` | bounded native parsers and byte-preserving edits of one trust leaf |
131
- | `pi-bridge.mjs` | the pi bridge (`@awebai/oats-pi`) in every pi folder a launch of a deployment uses: the folder list (the default, the process's own `PI_CODING_AGENT_DIR`, each pi launch configuration's, by real path), the bridge read in each, `oats doctor`'s skew warnings and the plan `oats update` runs ([upgrading](upgrading.md)). Reads only: `bin/oats.mjs` runs the steps |
132
+ | `pi-bridge.mjs` | the pi bridge (`@awebai/oats-pi`) in every pi folder a launch of a deployment uses: the folder list (the default, the process's own `PI_CODING_AGENT_DIR`, each pi launch configuration's, by real path), the bridge read in each, `oats doctor`'s skew warnings, and the plan `oats update` runs with its line that the Desktop goes first ([upgrading](upgrading.md)). Reads only: `bin/oats.mjs` runs the steps |
132
133
 
133
134
  The schedule registry stores explicit concurrency caps, leaving the schedule
134
135
  cap absent for its effective default of five. `readRegistry()` is a pure,
@@ -192,6 +193,30 @@ The kernel is runtime-neutral: nothing in `lib/` depends on a harness or on
192
193
  a provider. Provider behaviour lives in capabilities; the kernel supplies
193
194
  their contracts ([layers](layers.md)).
194
195
 
196
+ ### Remote diagnostic display
197
+
198
+ `lib/remote.mjs` exposes explicit display entry points for direct module callers:
199
+
200
+ - `displayRepoRef(value, { pinned = false, rejectedValue = false } = {})`
201
+ renders selected reference values, including nested keys and values. For a
202
+ pinned source, `pinned: true` splits the complete `<ref>@<commit>` value;
203
+ `pinned: { ref, commit }` supplies its original components. Both forms
204
+ require a recognised reference and a 40-hex commit, with no plain fallback.
205
+ - `displayDiagnosticText(value, source = null, { fragment = false, refusal = false, substitute = true, rejectedValue = false } = {})`
206
+ renders kernel-authored diagnostic prose using its selected original source
207
+ values, including fragments and refusal explanations.
208
+ - `scrubGitLine(line, url = null)` handles Git-authored lines through the
209
+ [whole-line disclosure rule](workspaces.md#repository-references-in-diagnostics)
210
+ before control and length formatting.
211
+
212
+ All three delegate to the existing private `renderRemoteDisplay`; construction
213
+ and withholding policy live there. Each public entry fixes its context and
214
+ extracts only its named options, so an extra option cannot select Git-line
215
+ handling through either of the other entry points. These exports are for
216
+ internal/direct-module callers: `lib/remote.mjs` is not in the package export
217
+ map. Call sites choose the entry matching the origin of the value or prose;
218
+ there is no implicit-context `redactUrl` export or compatibility shim.
219
+
195
220
  ### The remote read path
196
221
 
197
222
  Every CLI command owns one read session (`createReadSession` in
@@ -301,9 +326,31 @@ fetch passes it with `-c remote.origin.url=`). A server without partial
301
326
  fetches gets whole trees; the cache records that (`oats.fetch = full` in its
302
327
  config) and the CLI prints the session's notice once, on stderr. Partial
303
328
  caches need git 2.45 or later (`PARTIAL_FETCH_GIT`, the first git with
304
- `GIT_NO_LAZY_FETCH`): with an older git every cache fetches whole trees, a
305
- partial cache it meets is deleted and fetched again whole, and the same
306
- notice says why.
329
+ `GIT_NO_LAZY_FETCH`): only a successfully parsed version below that floor
330
+ authorizes a version-driven rebuild. With that older git every cache fetches
331
+ whole trees, a partial cache it meets is deleted and fetched again whole,
332
+ and the same notice says why. An existing full cache stays full even when a
333
+ later probe reports a modern git.
334
+
335
+ One private strict version probe owns the memo per `exec`: concurrent callers
336
+ share the in-flight probe, and a parsed success is retained. A rejection,
337
+ unparseable result, or waiter leaving on timeout/cancellation removes only
338
+ that probe's own memo entry, so a later call
339
+ can retry without an old failure evicting a newer probe. `gitVersion(exec,
340
+ opts)` wraps this same probe for compatibility, returning a version or `null`;
341
+ it never memoizes a failure as `null`. The cache read path's `readVersion`
342
+ uses the strict probe and maps failure through the existing
343
+ `E_REMOTE_UNREADABLE` classification. Unparseable output is `unknown`; a
344
+ probe's own `timedOut` remains `timeout` even before a session deadline.
345
+ Each waiter can leave on its own timeout or cancellation. The launching
346
+ caller supplies the shared Git process's timeout and signal: when those end
347
+ the probe, every remaining waiter receives that original failure, even with
348
+ time left on its own deadline. A later call retries; leaving a wait never
349
+ changes the outcome delivered to peers still awaiting that probe.
350
+ These refusals apply with or without a read session and preserve the
351
+ existing partial cache, its fetch mode and its commit pins; failure never
352
+ reaches the version comparison as an older git. Raw version stdout and
353
+ command arguments are not diagnostic text.
307
354
 
308
355
  The fetch of a commit negotiates: git tells the server the commits the cache
309
356
  holds (its pins), and the pack holds only what they lack, a few kilobytes for
@@ -40,7 +40,7 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.0.5
43
+ oats.okf: v5.1.0
44
44
  oats.aweb: v1.27.3
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 5.0.5**. Provider implementation and
9
+ This is the operator guide for **oats.okf 5.1.0** (OATS **>=0.49.0**). Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
 
12
12
  | Surface | What it holds |
@@ -14,6 +14,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
14
14
  | Accepted Git or directory bases | Soul knowledge: OKF concepts in owned nodes. |
15
15
  | `souls/<name>/okf.json` | The soul's stable owner and owned/read nodes. |
16
16
  | Instance home: `STATE.md`, `log.md`, `notes/` | The instance's working knowledge. |
17
+ | Harvester home: `harvest-source/` | Private source evidence captured at spawn, not accepted knowledge. |
17
18
  | Bindings file and `stateDir` | Host base locations and consultation/binding state, not a harvest queue. |
18
19
 
19
20
  ## Setup
@@ -23,7 +24,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
23
24
  ```yaml
24
25
  # oats-workspace.yaml (excerpt)
25
26
  packages:
26
- oats.okf: v5.0.5
27
+ oats.okf: v5.1.0
27
28
  defaults:
28
29
  knowledge: { oats.okf: { from: package } }
29
30
  stores:
@@ -46,9 +47,12 @@ settings:
46
47
  state-dir: /absolute/okf/state
47
48
  ```
48
49
 
49
- Upgrading an existing deployment requires the ordered
50
+ Upgrading from 4.x requires the ordered
50
51
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
51
- just editing a version line.
52
+ just editing a version line. For 5.1.0, upgrade to OATS >=0.49.0 before moving
53
+ the provider pin: that kernel first supports the public source-event lookup
54
+ after retirement. Re-spawn harvesters to receive the new capture hook and
55
+ instructions; restarting a session keeps its copied provider.
52
56
 
53
57
  ### Bindings document
54
58
 
@@ -79,6 +83,9 @@ from the document's directory:
79
83
  - Git bases may use HTTPS, SSH or a durable local repository; `root: "."`
80
84
  means the whole repository. Embedded credentials are refused. Harvest
81
85
  proposals use same-repository GitHub PRs through ordinary `git` and `gh`.
86
+ Change a binding's `repository` to a plain URL only after every seat that
87
+ reads it has been re-spawned on oats.okf 5.0.4 or later; a session restart
88
+ does not update the copied provider.
82
89
  - Directory bases need no Git and must not sit inside a Git worktree. They
83
90
  support consultation and explicit provisioning/migration, **not automatic
84
91
  harvest publication**. The 5.0 harvester reports directory harvest as
@@ -159,13 +166,15 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
159
166
 
160
167
  Never combine `--relation unrelated` with `--relative-to`. There is no
161
168
  automatic transcript capture, source registry, worker cursor or retire
162
- harvest. An unrelated harvester can outlive its source; this is a
163
- lifecycle property, not proof that missing source authority can be ignored.
169
+ harvest. An unrelated harvester can outlive its source. Proposers need
170
+ not stay alive: the harvester can check their recorded retirement recovery.
171
+ Keep backing evidence in the source home or that recovery until capture;
172
+ never treat missing source authority as permission to invent it.
164
173
 
165
174
  One proposal per checkpoint, each concept a claim of its own in it, and
166
175
  claims only for the nodes the source soul owns; a lesson for a node it only
167
176
  reads goes in one line in the instance's hand-back, for that node's owner.
168
- One harvester at a time, per instance (oats.okf 5.0.5): the source notes the
177
+ One harvester at a time, per instance: the source notes the
169
178
  harvester's instance name and spawns no other while `oats status` still
170
179
  lists it, since a harvester retires once it has handed over. What it learns
171
180
  meanwhile goes into its next proposal; an instance that hands back with one
@@ -173,11 +182,20 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
173
182
  after a publication failure stays listed, so it holds back its source's
174
183
  later proposals: once that failure is dealt with, the operator retires it
175
184
  (`oats retire <harvester>`).
176
- 3. **Judge and submit.** The harvester checks recorded source configuration,
177
- accepted knowledge and open/recent harvest PRs. It reads named backing
178
- notes, edits only owned nodes in its own Git checkout, validates the
179
- **whole base**, and creates a normal `okf-harvest`-labelled PR with v2
180
- provenance. Proposal text is data written with the native file tool into
185
+ 3. **Capture, judge and submit.** Before the model starts, the required spawn
186
+ hook checks the source's live record or the completed recovery named by
187
+ its public retirement event. Source identity, single-incarnation history,
188
+ recovery manifest and soul opt-out must agree; guessed copies and reused
189
+ or ambiguous identities refuse. It atomically captures the proposal,
190
+ verified source declarations/bindings and only named notes into the
191
+ harvester's own `harvest-source/`. The model uses that snapshot, not a later
192
+ live-source read: retirement or recovery disposal after capture cannot
193
+ remove its input. Missing/refused notes have no hash and claims relying
194
+ on them are dropped. Legacy note forms are preserved or explicitly refused,
195
+ never silently discarded.
196
+ The harvester then checks accepted knowledge and open/recent harvest PRs,
197
+ edits only owned nodes in its own Git checkout, validates the **whole base**,
198
+ and creates a normal `okf-harvest`-labelled PR with v2 provenance. Proposal text is data written with the native file tool into
181
199
  commit-message/PR-body files, never shell command text. A publication ref
182
200
  is `okf-harvest/<UTC YYYYMMDD>-<fresh UUID>`, with no source/harvester
183
201
  name in it; Git validates the full ref and the push must create a new
@@ -221,10 +239,11 @@ review):
221
239
 
222
240
  The sentence also covers the names provenance publishes as written: note
223
241
  file names, task refs and instance names. These exclusions are instructions
224
- to agents and guarantee nothing. No program reads a harvest's content, and
225
- the first reader other than the harvester is the reviewer of the pushed pull
226
- request. The one control enforced in code is the soul's opt-out
227
- ([The harvest switch](#the-harvest-switch)). It is per soul, and it covers
242
+ to agents and guarantee nothing. Source capture copies evidence but does not
243
+ judge its content. The first publication reviewer other than the harvester
244
+ reads the already-pushed pull request. Source capture/provenance checks and
245
+ the soul's opt-out are enforced in code; neither is a privacy guarantee.
246
+ The opt-out ([The harvest switch](#the-harvest-switch)) is per soul and covers
228
247
  that soul's own proposals, not what its instances write to other seats. A
229
248
  soul whose work is reading third-party correspondence should opt out.
230
249
 
@@ -9,8 +9,8 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.10.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.0.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
12
+ | `oats.framework` | `oats-framework/v1.10.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.1.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.27.3` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
29
29
  ## Find and use packages
30
30
 
31
31
  - A workspace pins an official package by **bare version** in its
32
- `packages:` map (`oats.okf: v5.0.5`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.1.0`); `oats sync` resolves it through the
33
33
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
34
34
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
35
35
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v5.0.5 # bare version → the official catalog
47
+ oats.okf: v5.1.0 # bare version → the official catalog
48
48
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
49
  ```
50
50
 
51
- - **Bare version** (`v5.0.5`, `5.0.5`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.1.0`, `5.1.0`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.0.5` or `oats-framework/v1.10.0`) and the payload path. An id
54
+ convention (`v5.1.0` or `oats-framework/v1.10.1`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,8 +74,8 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.10.0
78
- oats.okf: v5.0.5
77
+ oats.framework: v1.10.1
78
+ oats.okf: v5.1.0
79
79
  oats.aweb: v1.27.3
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
@@ -105,7 +105,7 @@ decision recorded in the lock.
105
105
  $ oats sync
106
106
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
107
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.5 ✓ (@ 73b85020)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.1.0 ✓ (@ 40265ac7)
109
109
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
110
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
111
  teams platform (shared) · this deployment's: oats teams
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
160
160
  "source": "catalog:oats.okf",
161
161
  "url": "https://github.com/awebai/oats-okf.git",
162
162
  "path": "oats-package",
163
- "version": "5.0.5",
164
- "commit": "73b85020e52b8584cb15f153a39712f900e69918",
163
+ "version": "5.1.0",
164
+ "commit": "40265ac79eca54a76ae648462dbfc83ac370dbbe",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
352
352
  {
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.5", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.0", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.1.0", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.1", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.10.0`
362
- resolves to tag `oats-framework/v1.10.0`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.10.1`
362
+ resolves to tag `oats-framework/v1.10.1`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -74,7 +74,11 @@ node scripts/release-lane.mjs desktop --tag v0.22.0 --arch x64 # needs Rosett
74
74
  node scripts/release-lane.mjs status --tag v0.22.0
75
75
  ```
76
76
 
77
- On the Linux host, from a checkout of the same commit:
77
+ On the Linux host, from a checkout of the same commit. Besides the build tools,
78
+ the host needs binutils (`readelf` and `ar`) and `tar`. The `desktop` phase's
79
+ `dist:smoke` reads every ELF file of the DEB and the AppImage and checks it
80
+ against the installers' glibc floor (`packages/desktop/scripts/linux-floor.json`).
81
+ No flag skips that check, and it stops naming the tool when one is missing.
78
82
 
79
83
  ```bash
80
84
  node scripts/release-lane.mjs build --tag v0.22.0
@@ -251,6 +255,16 @@ module's number follows the runner that builds it: the symbols it needs at
251
255
  2.34 are the ones a module gets when it is built on a system whose glibc is
252
256
  2.34 or later.
253
257
 
258
+ **The build now holds that number.** `docs/desktop.md` states it (glibc 2.34)
259
+ and `packages/desktop/scripts/linux-floor.json` holds it with libstdc++'s
260
+ `GLIBCXX` and `CXXABI` (`packages/desktop/test/linux-floor.test.mjs` keeps the
261
+ two equal). On the Linux leg of both workflows, `dist:smoke` unpacks the DEB
262
+ and the AppImage (its runtime and the libraries it adds included), reads the
263
+ version-needs table of every ELF file with `readelf -V -W`, and fails naming
264
+ each file that needs a newer version than the floor. A move of the runner, a
265
+ new `node-pty` or a new Electron that raises it is then a pull request that
266
+ changes that file and the page together.
267
+
254
268
  ## Release-notes entries
255
269
 
256
270
  A release ships one notes file, `docs/release-notes/v<version>.md`. Between
@@ -332,6 +346,17 @@ node scripts/assemble-release-notes.mjs --tag v0.54.0
332
346
  file, which `test/release-packaging.test.mjs` requires for the version the
333
347
  manifests carry. The release-prep pull request runs it again for the
334
348
  entries merged since, which go after the earlier ones.
349
+ - **The Upgrade section opens with the order of the Desktop and the CLI.**
350
+ The tag owner writes it in the release-prep pull request, for every
351
+ release, from `ACCEPT_RANGE` in `packages/client/cli-locator.mjs`:
352
+ - when the release moves the range's upper bound (a new minor), the first
353
+ Upgrade line says to install the Desktop first and the CLI second,
354
+ because the previous Desktop refuses this CLI ([Upgrading](upgrading.md));
355
+ - when the range already admits the new version (a patch), it says that
356
+ either order works.
357
+
358
+ No entry file writes this line: only the tag owner knows the release's
359
+ version when the notes are assembled.
335
360
  - **A tag is refused while anything is under `docs/release-notes/next/`:** by
336
361
  the `build-and-test` job of `release.yml` and by `release-lane.mjs build`,
337
362
  each right after its notes-file gate and before anything is built. Each