@awebai/oats 0.67.1 → 0.68.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 (60) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +278 -61
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/servers.md +6 -1
  17. package/docs/souls-and-instances.md +38 -3
  18. package/docs/tui.md +625 -223
  19. package/docs/upgrading.md +62 -6
  20. package/docs/workspaces.md +2 -2
  21. package/lib/capability-contract.mjs +6 -5
  22. package/lib/core.mjs +222 -38
  23. package/lib/instance-events.mjs +1 -1
  24. package/lib/instance-resolution.mjs +5 -5
  25. package/lib/instance-upgrade.mjs +1445 -0
  26. package/lib/materialize.mjs +225 -78
  27. package/lib/servers.mjs +11 -7
  28. package/lib/upgrade-state.mjs +101 -0
  29. package/lib/workspace.mjs +4 -1
  30. package/lib/worktree.mjs +103 -12
  31. package/package-catalog.json +5 -4
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +15 -1
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/deployment-panel.mjs +6 -2
  36. package/packages/client/keymap.mjs +89 -45
  37. package/packages/client/keys-file.mjs +9 -5
  38. package/packages/client/panel-views.mjs +16 -3
  39. package/packages/client/spawn-naming.mjs +7 -6
  40. package/packages/client/spawn-preview-cli.mjs +37 -1
  41. package/packages/client/spawn-preview-contract.mjs +35 -0
  42. package/packages/client/spawn-preview.mjs +35 -2
  43. package/packages/client/team-members.mjs +4 -1
  44. package/packages/client/workspace-step.mjs +25 -0
  45. package/packages/tui/README.md +5 -5
  46. package/packages/tui/lib/actions.mjs +51 -27
  47. package/packages/tui/lib/client.mjs +3 -2
  48. package/packages/tui/lib/config.mjs +4 -4
  49. package/packages/tui/lib/main.mjs +27 -13
  50. package/packages/tui/lib/model.mjs +132 -19
  51. package/packages/tui/lib/store.mjs +343 -68
  52. package/packages/tui/lib/term/keys.mjs +5 -3
  53. package/packages/tui/lib/term/kitty.mjs +28 -10
  54. package/packages/tui/lib/term/screen.mjs +15 -6
  55. package/packages/tui/lib/term/through.mjs +33 -28
  56. package/packages/tui/lib/views/frame.mjs +88 -109
  57. package/packages/tui/lib/views/help.mjs +56 -34
  58. package/packages/tui/lib/views/instances.mjs +4 -2
  59. package/packages/tui/lib/views/workspaces.mjs +55 -0
  60. package/skills/oats-getting-started/SKILL.md +92 -43
package/docs/desktop.md CHANGED
@@ -112,6 +112,23 @@ PATH, not the Desktop's. A tmux server that was already running keeps its own
112
112
  environment; restart it if its sessions should get the new PATH, which ends
113
113
  its sessions: `tmux -L oats kill-server` for the OATS tmux server, where instances run, and `tmux kill-server` for your default server, where an instance started by an earlier kernel may still be.
114
114
 
115
+ ## Updating
116
+
117
+ Installing a new version doesn't change a Desktop that is already running: an
118
+ AppImage runs from its own mount, and a DEB or another copy of the app hands
119
+ its launch to the running app, which opens or focuses a window and carries on
120
+ in the old version. To switch, quit Desktop (close every window) and open it
121
+ again.
122
+
123
+ From this version on, a launch of a different version says so: the running
124
+ Desktop opens or focuses the window as usual, then asks whether to **Restart
125
+ into** the version you opened, naming the file it starts, or **Keep** the
126
+ running one. Restarting closes Desktop's windows and starts the version you
127
+ opened; your agents keep running in their sessions. When the copy you opened can't be found again (its file was
128
+ moved or removed), the message only tells you to quit and open it again. Both
129
+ copies must be this version or later: a running Desktop older than this one
130
+ can't tell you, and neither can a launch of one.
131
+
115
132
  ## Opening a workspace
116
133
 
117
134
  The app opens the workspaces you had open, plus the directory it was
@@ -119,17 +136,12 @@ launched with (`--dir`, or the folder it was started from) when that is an
119
136
  OATS deployment — the directory (the operator's choice) holding
120
137
  `oats-local.yaml` and `agents/`. A folder that is not a deployment is never
121
138
  opened: started from Finder, with nothing open to restore, the window shows
122
- the workspace switcher instead. It lists the deployments on this computer
123
- under **On this computer**: those on this computer's deployments list
124
- (`oats deployments`, see [Workspaces](workspaces.md)) and a saved one,
125
- that are not open. Click one to open it in this window. A deployment the list
126
- holds but that can't be opened says why: missing (the folder is gone, or its
127
- volume isn't mounted), not a deployment any more, or can't be checked. **Remove**
128
- beside a row takes it off the list (Right Arrow, then Enter, from the
129
- keyboard); nothing on disk changes. With an oats that has no such list, the
130
- switcher shows the saved deployments and says "This oats can't list this
131
- computer's deployments. Update oats." **Add local workspace… → Browse**
132
- points it at any other deployment.
139
+ "Choose a workspace" and opens **Add local workspace…** (the **+** at the top
140
+ of the sidebar). The dialog lists the deployments on this computer that are
141
+ not open: those on this computer's deployments list (`oats deployments`, see
142
+ [Workspaces](workspaces.md)) and a saved one. Click one, or press Enter on it,
143
+ to add it and open it in this window. **Browse…** points it at any other
144
+ deployment.
133
145
  A picked folder without `oats-local.yaml` is offered onboarding instead. The
134
146
  Desktop never parses the deployment: its members, lock state and header come
135
147
  from `oats workspace status`, and its instances from the deployment's one
@@ -148,17 +160,19 @@ Launch flags for scripted use: `--dir <workspace>` and `OATS_DESKTOP_PORT`.
148
160
  Each workspace has at most one window, titled with the workspace's name (a
149
161
  workspace on a server: `name — server`).
150
162
 
151
- - **Switching.** Choosing a workspace in the switcher shows it in the current
152
- window. If that workspace already has a window, that window comes to the
153
- front instead and the current one doesn't change.
154
- - **Open in new window.** Each workspace in the switcher has an **Open in new
155
- window** button beside it. From the keyboard: Right Arrow on the workspace,
156
- then Enter, or ⌘Enter on macOS / Ctrl+Enter on Linux and Windows. A
157
- workspace that already has a window is brought to the front.
163
+ - **Switching.** Picking a workspace in the sidebar's list shows it in the
164
+ current window. If another window shows it, it moves to this window, and the
165
+ other window shows another workspace ([A workspace another window
166
+ shows](#a-workspace-another-window-shows)). No other window comes to the
167
+ front.
168
+ - **Open in new window.** A workspace's row in the list opens it in its own
169
+ window from its context menu (a right-click, or Shift+F10 or the Menu key),
170
+ or with ⌘Enter on macOS / Ctrl+Enter on Linux and Windows. A workspace that
171
+ already has a window is brought to the front.
158
172
  - **New Window.** On macOS, **File → New Window** (⌘⇧N); everywhere,
159
173
  **Window: new window** in the command palette. The new window has no
160
- workspace yet: it opens the switcher, and shows "Choose a workspace" until
161
- you pick one. It reads nothing until then.
174
+ workspace yet: it shows "Choose a workspace" and focuses the list of
175
+ workspaces until you pick one. It reads nothing until then.
162
176
  - **Moving between windows.** On macOS, ⌘\` cycles the app's windows, and the
163
177
  **Window** menu lists them.
164
178
  - **Restore.** Quitting and relaunching brings every window back with its
@@ -169,12 +183,14 @@ workspace on a server: `name — server`).
169
183
  - **Launching again.** Running the app again (`open -a "OATS Desktop" --args
170
184
  --dir <deployment>`, or from inside a deployment) adds that deployment if
171
185
  needed and brings its window to the front, opening one if it has none. Any
172
- other launch brings the most recently used window to the front.
186
+ other launch brings the most recently used window to the front. A launch of
187
+ another version also offers to restart into it ([Updating](#updating)).
173
188
  - **Closing.** Closing a window leaves the other windows, and their
174
189
  terminals, running. Closing the last window quits the app.
175
190
  - Tabs belong to their window: a workspace's terminals and tabs stay in the
176
191
  window they were opened in, and switching that window back to the
177
- workspace brings them back.
192
+ workspace brings them back. A window whose workspace another window takes
193
+ over closes its tabs of that workspace.
178
194
  - A tab's terminal ends ("session ended") when its instance's tmux window
179
195
  goes, whatever your tmux `detach-on-destroy` setting: a tab never shows
180
196
  another instance's terminal. Stopping an instance leaves its tab open.
@@ -186,10 +202,139 @@ workspace on a server: `name — server`).
186
202
  An instance respawned under the same name is a new instance: opening it
187
203
  opens a new tab.
188
204
 
205
+ ## Workspaces
206
+
207
+ The sidebar, top to bottom: the **Workspace** heading, with **Show only the
208
+ current workspace** and **Add local workspace…** at its end, over the list of
209
+ workspaces; a thin line; the two main views, **Workspace overview** and
210
+ **Automations**, one under the other; another line; **Instances**, a heading
211
+ with the running count over the list of instances; and, over a line, the
212
+ foot, one bar: the OATS mark and the sidebar toggle (**Hide the sidebar**)
213
+ after it, and at the bar's right **Spawn instance**, its words alone (a ground
214
+ only on hover), which
215
+ opens Quick Open (⌘P / Alt+P, named in its tooltip) to pick a soul and then
216
+ the spawn dialog, and the settings cog, whose menu holds **Theme…** and **Keyboard
217
+ shortcuts…**, each with its shortcut. A window opens on the **Workspace
218
+ overview** page, on its **Souls** tab: at launch, and after you choose a
219
+ workspace for it. Connections is in the command palette
220
+ (**Settings: Connections…**), and the palette opens with its shortcut or
221
+ Ctrl+X then `k`.
222
+ The instances have no search field: to find one by name, type it in the
223
+ command palette, which opens its terminal. ⌘F / Alt+F (**Focus the
224
+ instance roster**) and `/` in the sidebar go to the roster's current row;
225
+ on an empty roster, to its one action, the foot's **Spawn instance**, where
226
+ F6 lands too (a failed read's **Retry** comes first).
227
+
228
+ The list of workspaces is always shown. Its heading holds **Add local
229
+ workspace…** (the **+**). The list has one row per workspace this window can show, whatever
230
+ machine it is on: every workspace the Desktop serves, those only on servers
231
+ included, and the deployments no workspace matched ([One workspace, several
232
+ machines](#one-workspace-several-machines)), after them in the same list.
233
+
234
+ With one workspace the list is one compact row. With many it scrolls within
235
+ about six rows, the current row stays in view, and while rows are cut off
236
+ below, a line under the list says how many ("2 more below"), with the
237
+ needs-input mark at its right when one of them has an instance that needs
238
+ input.
239
+
240
+ **Show only the current workspace** is the toggle before the **+** in the
241
+ heading, for working in one workspace at a time. Pressed (its icon in the
242
+ accent colour), the list shows the current workspace's row alone. Nothing
243
+ stands for the others: no "N more" line, and no needs-input mark for one of
244
+ them that waits. Press it again, or use ⌥⇧⌘O on macOS / Ctrl+Alt+Shift+O on
245
+ Linux and Windows (the same in every chord family, and from a terminal) or the
246
+ palette's **Show only the current workspace**, to see every workspace again.
247
+ Ctrl+X then ↑ / ↓ still move to the previous / next workspace, which then
248
+ shows alone. A window choosing a workspace shows them all. The choice is remembered on this
249
+ computer.
250
+
251
+ - **A row is one line: a circle and the workspace's name.** No icon, no
252
+ machine, no state: a workspace's own pages show its machines and
253
+ deployments. The circle is the one an instance row has, in the same place.
254
+ A long name ends in an ellipsis, and the row's tooltip is the whole name.
255
+ - **The current workspace** has its circle filled, like a running
256
+ instance's, and its name in bold; the others have the ring a stopped
257
+ instance has. It has no background of its own: the selection's background
258
+ marks the current page (Workspace overview or Automations), so the
259
+ sidebar fills one "you are here" row. A screen reader hears it as current,
260
+ and the list's description names it, by the same name as its row.
261
+ - **The needs-input mark.** A row has an exclamation mark (a small amber
262
+ disc with a "!") at its right end when an instance of that workspace needs
263
+ input, the same mark an instance's **Needs input** pill starts with: the claim the instance roster shows
264
+ for that instance, from a running session (OATS with the `waiting-on-you`
265
+ feature), as the Desktop already reads it for the workspaces it serves.
266
+ Every row can have it, the current one included. The row's name then ends
267
+ in ", needs input" for a screen reader, and its tooltip says "An instance
268
+ here needs input". What isn't known shows no mark, never a guess: a
269
+ deployment that isn't live (stale, not reached, its last read failed) and
270
+ an oats without `waiting-on-you`. The mark never moves a row: the order
271
+ stays the same whoever waits.
272
+ - **Picking a row** (a click, Enter, or the leader's ↑ / ↓, Ctrl+X then ↑ /
273
+ ↓, which are also ⌥↑ / ⌥↓ on macOS and Alt+↑ / Alt+↓ on Linux and Windows
274
+ in the Alt family, the default) shows that workspace in this window, with its own tabs, layout and
275
+ selection; one another window shows moves here ([A workspace another window
276
+ shows](#a-workspace-another-window-shows)). The leader's ↑ / ↓ go to the
277
+ previous / next row, and stop at the ends ("No workspace above this one." /
278
+ "No workspace below this one."). Each is a pick, so walking the list with
279
+ them moves every workspace it passes that another window shows into this
280
+ window.
281
+ - **Open in new window** is in a row's context menu (a right-click, or
282
+ Shift+F10 or the Menu key), and ⌘Enter on macOS / Ctrl+Enter on Linux and
283
+ Windows does it from the keyboard. It opens the workspace in its own window,
284
+ or brings the window that shows it to the front.
285
+ - **Keyboard.** The list is one Tab stop, Up/Down/Home/End move in it, and
286
+ `w` in the sidebar, Ctrl+X then `o`, ⌥⌘O / Alt+O and the palette's
287
+ **Workspace: switch…** focus it. The full keys are in [the keyboard
288
+ reference](../packages/desktop/docs/desktop-keyboard.md#the-list-of-workspaces).
289
+
290
+ **Add local workspace…** lists the deployments on this computer that are not
291
+ open: those on this computer's deployments list and a saved one. Each is one
292
+ button: a click, or Enter on it, adds it (checked first) and opens it in this
293
+ window; a failure says why in the dialog, with focus back on it. The dialog
294
+ counts these alone ("2 workspaces to add"). After them, under **Can't be
295
+ opened**, come the rows of this computer's list that can't be opened, each
296
+ saying why in a word, and they open nothing: **Missing** (the folder is gone, or its volume
297
+ isn't mounted), **Not a deployment** (no `oats-local.yaml` any more), or
298
+ **Can't be checked** (OATS couldn't read the folder). The full sentence is the
299
+ row's tooltip and what a screen reader hears. **Remove** beside such a row
300
+ takes it off the list (Right Arrow, then Enter, from the keyboard); nothing on
301
+ disk changes. With an oats that has no deployments list, the dialog offers the
302
+ saved deployments alone and says "This oats can't list this computer's
303
+ deployments. Update oats."; a list read that failed says "Couldn't read this
304
+ computer's deployments:" and why. **Browse…** chooses any other folder, and one without
305
+ `oats-local.yaml` is offered onboarding.
306
+
307
+ A window with no workspace (a New Window, or one whose workspace moved to
308
+ another window) shows "Choose a workspace" and focuses the list. When the
309
+ Desktop serves no workspace at all, so the list is empty, it opens **Add local
310
+ workspace…** instead. Closing the dialog leaves "Choose a workspace", whose
311
+ button opens it again.
312
+
313
+ ### A workspace another window shows
314
+
315
+ Picking a workspace another window shows moves it to this window: a pick from
316
+ the list, the workspace select of
317
+ the Workspace page, and a spawn whose new instance is in that workspace.
318
+ Nothing else comes to the front. The other window lets the workspace go: it
319
+ shows the workspace it showed most recently before that one among those the
320
+ Desktop still serves and no other window shows, else no workspace ("Choose a
321
+ workspace"). It closes every tab it had of the workspace that moved. The
322
+ Desktop waits at most 2 seconds for the other window; one that answers late
323
+ ends the same way, and so does one that was still opening or reloading:
324
+ once it comes up it shows no workspace, never the one that moved. **Open in
325
+ new window** still brings the other window to the front instead.
326
+
327
+ Only the terminals and the split move with the workspace: this window opens
328
+ the same terminal tabs in the same split, each with a fresh viewer, and the
329
+ agents keep running. File, brain and view tabs do not move: they close in the
330
+ other window.
331
+
189
332
  ## Capabilities and spawning
190
333
 
191
- **Workspace › Capabilities** lists what the workspace offers, in three
192
- sections: **Workspace owned** (from the member repos, for every soul),
334
+ **Workspace › Capabilities** is in two parts, each with its title:
335
+ **Workspace defaults** (below), then **All capabilities**, what the
336
+ workspace offers. Under the **All capabilities** title, a row of segments
337
+ jumps to its three sections: **Workspace owned** (from the member repos, for every soul),
193
338
  **Repo owned** (only for souls of the same repo) and **Packages** (pinned
194
339
  versions). Workspace owned and Repo owned are grouped by the repository
195
340
  that defines each capability. The groups are headed like the Souls tab:
@@ -200,6 +345,42 @@ pills (**All**, then one per repository, each with its count) show one
200
345
  repository at a time; "N of M shown" appears while a pill or the search
201
346
  narrows the list.
202
347
 
348
+ Above All capabilities, **Workspace defaults** shows what every soul of the
349
+ workspace starts with, unless it turns one off. It is one panel with two
350
+ groups. **Core capabilities** (at most one of each per soul) is always
351
+ **Knowledge**, **Messaging** and **Tasks**. **Additional capabilities** (any
352
+ number per soul) lists the other capabilities the workspace gives every soul,
353
+ or says there are none. Each default is shown the same way: its tile, the
354
+ capability and its source (a package and its pinned version, or a repository
355
+ and "latest"). Click it to open the capability's page. An empty core slot
356
+ shows **None**: there is no workspace default, and each soul chooses its
357
+ own. A core capability the workspace names among its other defaults, rather
358
+ than in its slot, is shown under Core, in that slot, as the kernel fills the
359
+ slot with it. An additional default the workspace turned off is struck through and
360
+ says "turned off by the workspace". A workspace that sets no defaults, a
361
+ standalone deployment for example, shows one line saying so. The search and
362
+ the repository pills never narrow or hide this section. It is read from
363
+ `oats workspace status --json`: an OATS that does not report the defaults
364
+ shows no such part, and the Desktop does not guess them from the souls. The
365
+ defaults have no segment of their own: the segments are All capabilities'.
366
+ Teams add no capabilities (removed in 0.30), so there are no team defaults
367
+ to show.
368
+
369
+ The round **i** button in the toolbar, beside the search (**About capabilities**), opens
370
+ **What capabilities are**: what a capability gives a soul's instances (skills,
371
+ commands and instructions, the instructions injected into each instance's
372
+ composed `AGENTS.md` after the soul's own), the three places one comes from
373
+ (Workspace owned, Repo owned, Packages), which three capabilities are core
374
+ (knowledge, messaging and tasks, at most one of each per soul) and that every
375
+ other one is additional, and what workspace defaults are and why they
376
+ matter: every soul gets them, they give an organisation's agents one shared
377
+ way of working, and a knowledge default keeps what agents learn and the
378
+ procedures the organisation writes down for later instances; a soul can turn
379
+ one off and name its own in its place.
380
+ **Close** or Esc closes it and returns the focus to the button; leaving the
381
+ tab or the workspace closes it too. **Workspace › Souls** has the same button
382
+ at the end of its toolbar, **About souls**, which explains what a soul is.
383
+
203
384
  A soul's page (open a soul from **Workspace › Souls**) ends with
204
385
  **Instructions**, what its instances are told, read like a capability's
205
386
  injected instructions (a navigation tree on the left, the file on the right).
@@ -260,31 +441,50 @@ name, as its suffix:
260
441
  `desktop-improvements` for `oats-desktop-expert` becomes
261
442
  `desktop-improvements-expert`. A name that already ends in the role, or is
262
443
  the role, stays as typed. The line under the field shows the final name, and a
263
- name that is too long, invalid or already taken is explained there. With an
264
- OATS older than 0.26.0, which can't take an exact name, and for a spawn on a
265
- server, what you type is a purpose instead: the instance is named
266
- `<soul>-<purpose>`, and the field shows that prefix.
444
+ name that is too long, invalid or already taken is explained there. A spawn
445
+ on a server takes the exact name the same way when that machine's OATS can
446
+ take one (feature `spawn-name`, read from its last roster answer), and its
447
+ name is explained there too when that machine refuses it. With an OATS older
448
+ than 0.26.0 on either side, which can't take an exact name, or a server whose
449
+ OATS this computer has not heard from, what you type is a purpose instead: the
450
+ instance is named `<soul>-<purpose>`, and the field shows that prefix.
267
451
 
268
452
  **Named from its task.** When the installed OATS can suggest names (feature
269
453
  `spawn-suggest-name`), the help under an empty Name reads "Left empty, the
270
454
  instance is named from its task." Once the Opening instruction holds at
271
- least three words and you stop typing for about a second and a half, the
272
- Desktop asks OATS for a name. The soul's own harness reads the instruction
273
- and replies with a short name for the work, and the role is added as its
274
- suffix. The name shows as the field's placeholder ("will be named
275
- release-notes-manager"), on the line under the field ("(from the task)") and
276
- in **What will be created**. It belongs to the instruction it was made for:
277
- when you change the instruction it goes, until the next pause. Typing in Name
278
- replaces it and stops suggestions for the rest of the dialog, even if you
279
- empty the field again. Press **Spawn** with Name empty and no name yet, and the
455
+ least seven words, the Desktop asks OATS for a name as you type. The soul's
456
+ own harness reads the instruction and replies with a short name for the work,
457
+ and the role is added as its suffix. The name shows as the field's
458
+ placeholder ("release-notes-manager"), on the line under the field ("(from
459
+ the task)") and in **What will be created**. It belongs to the instruction it
460
+ was made for: when you change the instruction it goes, and the Desktop asks
461
+ again for the new instruction while it holds seven words or more. Typing in
462
+ Name replaces it and stops suggestions for the rest of the dialog, even if
463
+ you empty the field again. Press **Spawn** with Name empty and no name yet, and the
280
464
  dialog says **Naming…** and asks once, however short the instruction. When OATS
281
465
  can't name it, the instance is numbered and a notification says why, for
282
466
  example "Named oats-desktop-expert-3: naming took longer than 20 seconds."
283
467
  That happens when there is no instruction, when the harness doesn't suggest
284
468
  names (Codex), when there is no answer within 20 seconds, when the harness
285
469
  couldn't be asked, and when its reply wasn't a name. Each request is a call
286
- to the harness's model: nothing is asked before you type, nothing runs on a
287
- timer, and a spawn on a server is not named this way.
470
+ to the harness's model: nothing is asked before you type, and nothing runs on
471
+ a timer.
472
+
473
+ A spawn on a server whose OATS takes an exact name is named from its task the
474
+ same way, with one difference: the name is chosen on this computer. The
475
+ Opening instruction is sent to this computer's harness and model, as for a
476
+ spawn here: the Harness you chose, else the soul's default on that server,
477
+ else Claude Code, with this computer's launch configuration for it. That needs
478
+ an OATS here that can name a spawn for another machine (feature
479
+ `instance-suggest-name`). When it can't, or the name couldn't be chosen here,
480
+ the server names the instance itself from its task if its OATS can (feature
481
+ `spawn-apply-suggest-name`): the help reads "Left empty, the instance is named
482
+ from its task on <server>." Otherwise the server numbers it, and the help reads
483
+ "Named by <server> when it spawns." Naming never stops a spawn on a server.
484
+ When the instance is numbered where it would have been named, a notification
485
+ says why, as for a spawn here. A name chosen here is not checked on the server
486
+ until the spawn: one that is already taken there is refused, and explained
487
+ under the field.
288
488
 
289
489
  When capabilities set up the new worktree (OATS 0.49.0 and later), **Setup**
290
490
  names them, in the order they run, and says this can take several minutes. Such
@@ -351,21 +551,34 @@ When the retire has ended without finishing, the row says so and offers only
351
551
 
352
552
  ## One workspace, several machines
353
553
 
354
- The switcher lists each workspace once, however many deployments it has: the
554
+ The list of workspaces has each workspace once, however many deployments it has: the
355
555
  deployments you opened on this Mac and those your registered servers report,
356
556
  matched by the workspace each one reports (its repository key and default
357
557
  team, by the kernel's rules). It needs a CLI with the `workspace-identity`
358
558
  feature (OATS 0.36.0); without it each deployment has its own entry.
359
559
 
360
- - **Deployments.** The **Deployments** page (formerly the Active overview)
361
- shows the workspace's overview trees. **All** stacks one section per
362
- deployment, each headed by its machine and folder ("This Mac ·
363
- ~/acme", "altair · ~/northwind"). Then each deployment has a tab of
364
- its own, named by its machine ("altair"; "This Mac · oats-v2" when this Mac
365
- holds two). A workspace with one deployment shows just that deployment's
366
- tab. The tab you chose is remembered per workspace. With two or more
367
- deployments, the sidebar's instance list is grouped under one heading per
368
- machine; with one, it has no headings.
560
+ - **Machines.** **Workspace › Machines** (once the Deployments page, and
561
+ the Active overview before that) shows the workspace's overview trees.
562
+ One sentence above them says what a machine is: "Each machine runs this
563
+ workspace in a folder of its own. The instances under a machine run on
564
+ that machine." **All** stacks one section per deployment, each headed by
565
+ its machine and folder ("This Mac · ~/acme", "altair · ~/northwind"),
566
+ with "Instances on this machine" or "Instances on altair" under it. Then
567
+ each deployment has a tab of its own, named by its machine ("altair";
568
+ "This Mac · oats-v2" when this Mac holds two). A workspace with one
569
+ deployment shows just that deployment's tab, its tree under the same
570
+ heading. The tab you chose is
571
+ remembered per workspace. With two or more deployments, the sidebar's
572
+ instance list is grouped under one heading per machine; with one, it has
573
+ no headings.
574
+ - **An instance's card.** Clicking an instance on the Machines tab shows
575
+ what it reports and two buttons. **Go to instance** opens its terminal tab;
576
+ for a stopped instance it reads **Start…** and opens the Start dialog.
577
+ **Go to soul** opens the soul it was spawned from on the Workspace page. It
578
+ is disabled, and says why, when that soul can't be told or shown exactly:
579
+ the instance records none, it is no longer among the deployment's souls,
580
+ several match, another soul of the deployment has the same name, or the
581
+ instance is on a deployment other than the one the Workspace page shows. Restart with… stays in the instance's menu and its panel.
369
582
  - **Not shown live.** A deployment that can't be shown live says why in a few
370
583
  words on its heading ("ssh needs a prompt", "Timed out", "OATS too old to
371
584
  report its workspace"), and **How to fix** under it gives the full sentence
@@ -374,19 +587,22 @@ feature (OATS 0.36.0); without it each deployment has its own entry.
374
587
  needs `oats sync` or fixing in `oats-local.yaml`, or this computer's OATS
375
588
  can't read other machines. A server that can't be reached stays under the
376
589
  workspace it last reported, marked "remembered".
377
- - **The switcher.** Each workspace names its machines on one line ("This Mac ·
590
+ - **The list of workspaces.** Each workspace names its machines on one line ("This Mac ·
378
591
  altair"), with a mark when one of them isn't live.
379
592
  - **Not matched to a workspace.** A deployment that can't be matched is
380
- listed on its own under that heading in the switcher, with its machine and
381
- a short reason; choosing it opens its tab on the Deployments page. When this
593
+ listed on its own under that heading in the list, with its machine and
594
+ a short reason; choosing it opens its tab on the Machines tab. When this
382
595
  computer's OATS is too old to report workspaces, nothing can be matched:
383
596
  each deployment is listed on its own, as before, and its heading says to
384
597
  update OATS.
385
598
  - **Actions.** Everything you do to an instance goes to that instance's own
386
599
  deployment. Workspace-wide pages (Setup, Capabilities, Sync, Automations,
387
600
  Schedules, Teams configuration) act on the workspace's first deployment on
388
- this Mac, else its first, and say "On <deployment>" when there are two or
389
- more.
601
+ this Mac, else its first. None of them names it: not Souls,
602
+ Capabilities, Teams or Setup, nor the Automations page, nor a soul's, a
603
+ capability's or a team's page. The side panel names it ("On This Mac ·
604
+ ~/acme", under a soul's name) when there are two or more, as do Brain and
605
+ the Sync sheet, and the Machines tab shows each deployment on its own tab.
390
606
  - **Spawn.** With two or more deployments, the Spawn dialog asks first which
391
607
  one to spawn in (and says "Runs on" in its summary), starting on the one you last used in that workspace when it
392
608
  offers the soul, else the first that does (this Mac first). With one, it
@@ -398,7 +614,8 @@ deployment. Details are in
398
614
 
399
615
  ## Scheduling agents and wake messages
400
616
 
401
- Open **Schedules** in the selected workspace to launch a new agent on a cron,
617
+ Open **Automations › Schedules** in the selected workspace (the sidebar's
618
+ **Automations**, or ⌘3 / Ctrl+3) to launch a new agent on a cron,
402
619
  wake an existing agent with a message, or harvest its knowledge. **Schedule…**
403
620
  on a Soul roster card preselects that soul. Choose the task or message, repeat
404
621
  pattern and time zone; new agent jobs also offer harness, model, permissions
@@ -465,7 +682,7 @@ member and what each member state means. Then **Shared through Git** lists
465
682
  what the workspace declares (Members, with the host first and tagged
466
683
  **Host**, Packages and Defaults). **This computer** lists what is not shared:
467
684
  this deployment's settings, lock, CLI and instances, the member clones, and
468
- the machines that run the workspace.
685
+ the machines that run the workspace (**Registered machines**).
469
686
 
470
687
  ## A workspace's machines
471
688
 
@@ -473,7 +690,7 @@ A window offers only the machines that run its workspace: those whose
473
690
  registration reports the same workspace key as the window's deployment on this
474
691
  computer (OATS CLI with `servers-per-workspace` and `server-connect`). The
475
692
  spawn dialog's **Where to run** lists "This computer" and those machines; the
476
- Workspace › Setup tab lists them with their OATS version and whether they can
693
+ Workspace › Setup tab's **Registered machines** lists them with their OATS version and whether they can
477
694
  be reached, with **Check** and **Remove**. Registrations whose key is not known
478
695
  yet are checked once in the background after the Desktop starts.
479
696
 
@@ -494,8 +711,8 @@ saved route. A machine registered for a workspace no window shows is not
494
711
  contacted, so a machine that is switched off no longer slows every window's
495
712
  roster. Opening a window on another workspace reads its machines at once. Until
496
713
  it does, that workspace's machines are shown as they were last read, marked
497
- stale, and the switcher still lists them, not counted live. The read covers every machine again while a window
498
- shows the switcher, and on the first read after the Desktop starts. With an
714
+ stale, and the list of workspaces still lists them, not counted live. The read covers every machine again while a window
715
+ has no workspace, and on the first read after the Desktop starts. With an
499
716
  older CLI, every registered machine is read, as before.
500
717
 
501
718
  ## Instances on servers
@@ -611,7 +828,7 @@ instance whose state is unknown keeps the warning dot, and one without a colour
611
828
  looks as before. The shape says the state, never the colour alone.
612
829
 
613
830
  To set it, open **Instance: name and colour…** from the command palette, or
614
- press Ctrl+Alt+R (⌥⌘R on macOS). It acts on the instance of the terminal you
831
+ press Alt+R (⌥⌘R on macOS; Ctrl+Alt+R in the Ctrl+Alt family). It acts on the instance of the terminal you
615
832
  are in, else the focused sidebar row, else the active terminal tab's instance.
616
833
  The dialog shows the instance's name, which can't be changed yet, and the
617
834
  colours as buttons: **None** and the six. Arrow keys move between them; Enter,
@@ -676,7 +893,7 @@ unknown or unreported harness shows "?". Sources and licences are in
676
893
  | Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: wheel up first for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
677
894
  | macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
678
895
  | Log says `server on 4820 — this app's server at version X (this app is Y), not started by this app — left running — starting a dedicated one on 4821` | Another OATS Desktop server holds the default port: another installed version or a dev checkout that is running, or one an earlier Desktop left running. The app serves from the port it names and never stops a server it did not start. From 0.49.0 a server the app starts exits when the app ends, however it ends (quit, crash or kill). A server left by an earlier Desktop (seen on Linux, where it outlived the app in its own `app-…scope`) must be stopped once by hand: find it with `ss -ltnp 'sport = :4820'` (or `lsof -iTCP:4820 -sTCP:LISTEN` on macOS) and stop that pid, or its scope (`systemctl --user stop <scope>`), then restart the app. |
679
- | Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use the workspace switcher → Add workspace to select the right folder. |
896
+ | Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use **Add local workspace…** (the **+** at the top of the sidebar) to select the right folder. |
680
897
 
681
898
  For bugs, attach the terminal output of the app (`OATS Desktop` prints
682
899
  server and CLI-discovery logs to stdout) and your platform/arch.
@@ -163,9 +163,11 @@ in section 2). The instance home is
163
163
  `agents/<soul>/instances/<instance>/`; `work/` is its repository view;
164
164
  `.oats/modules/<cap>/` are the copied capabilities and `.agents/skills/<skill>/` their skills;
165
165
  `instance.json` records `modules` (from, commit, digest), `providers` and
166
- `workspace`. A running instance never changes under itself — a member that
167
- moves affects only new spawns, and `oats status` shows the drift
168
- (`member moved since (now @ …)` / `capability no longer present`).
166
+ `workspace`. A running instance never changes under itself; a stopped one can
167
+ be moved to the locked package versions with `oats instance upgrade`. Member
168
+ modules and the soul body still require a new spawn. `oats status` shows the
169
+ drift (`member moved since (now @ …)` / `capability no longer present`). See
170
+ [upgrading package modules](upgrading.md#moving-existing-homes-to-locked-package-versions).
169
171
 
170
172
  Instance-specific provider values belong to the spawn:
171
173
  `oats spawn <soul> --provider <cap> key=value` (repeatable; dotted keys nest),
@@ -93,11 +93,13 @@ and the rules its tests pin.
93
93
  | `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
94
94
  | `packages.mjs` | `packages:`, the catalog, `oats sync`, `oats-lock.json` |
95
95
  | `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, and of `--composed-skills` (`composedSkillsIn`), which adds the capability skills of the scratch composition |
96
- | `materialize.mjs` | copying modules into a home and composing it; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
96
+ | `materialize.mjs` | the shared home composer for spawn and module upgrade: `stageMaterialize` stages module copies and derived files, then a durable rename journal commits or rolls back a replacement in an existing home; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
97
+ | `instance-upgrade.mjs` | `planUpgrade` and `applyUpgrade`: verified package-module staging, provider adoption, idempotent forward completion, undo and retirement baseline refresh for a stopped local home, using the shared composer for derived home files |
98
+ | `upgrade-state.mjs` | upgrade receipt state and the partial-upgrade guard used before session start; receipts remain lifecycle state, and provider adoption stays in the module's upgrade hook |
97
99
  | `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) |
98
100
  | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
99
101
  | `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul`, `inspect --soul --instructions` and `--composed-skills` (its `inScratch` reads the scratch home before it is removed, so the two flags share one materialization) |
100
- | `instance-naming.mjs` | the suggested instance name of `spawn --preview --suggest-name`: the prompt, the soul's role (`soulRole`, the clients' rule), the name built from a reply, each harness's proven naming call (`NAMING_CALLS`) and the isolated call itself; driven by `core.mjs` `spawnBody`, after the preview's harness checks, where a suggested name is then placed as `--name` would place it. The test seam `OATS_TEST_NAMING_TIMEOUT_MS` shortens the call's 20 s limit |
102
+ | `instance-naming.mjs` | the suggested instance name of `spawn --suggest-name` (a preview's or an apply's) and of `oats instance suggest-name`: the prompt, the soul's role (`soulRole`, the clients' rule), the name built from a reply, each harness's proven naming call (`NAMING_CALLS`) and the isolated call itself. Two drivers in `core.mjs`, both reusing it unchanged: `spawnBody`, after the spawn's harness checks, where a suggested name is then placed as `--name` would place it (a preview's call within its preflight budget, an apply's within its own 20 s); and `suggestSpawnName`, for a spawn elsewhere, which resolves the launch configuration and executable the way a spawn here would but places nothing and passes a `taken` that is always false. The test seam `OATS_TEST_NAMING_TIMEOUT_MS` shortens the call's 20 s limit |
101
103
  | `doctor-capture.mjs` | one fixed bounded package health child for deployment doctor, excluded from `--soul`; package-owned envelope validation and existing warning-row mapping. No kernel status/DB/freshness parser. Command failures become `capture-health-unavailable`; see [the package boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation) |
102
104
  | `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
103
105
  | `local-edit.mjs` | the one way a verb rewrites `oats-local.yaml` in place (`editLocal`): the file as it is now, the deployment's local lock, compare-and-swap, the local schema and the caller's check before the rename, and the permission bits of the file it replaces on the new one (a link at that path is replaced by a regular file with its target's bits, and the target is not written). Every kernel command that rewrites that file writes through it (`grep editLocal` lists them; this row does not), and a new writer does too, so that no two drop each other's change. An edit changes the parsed document, which is then rendered, or returns the text to write when the command has a writer of its own for its block (`oats launch-config set\|remove`, whose write leaves every byte outside `launch-configs` as it was) |
@@ -112,7 +114,7 @@ and the rules its tests pin.
112
114
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
113
115
  | `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
114
116
  | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through |
115
- | `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 |
117
+ | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, the rollback of an interrupted add, and completion of Git's partial removal. An unregistered residue with a dangling `.git` file is compared with the recorded branch through a private temporary index (`read-tree`, refresh, `diff-files` allowing deletions, and `ls-files --others --exclude-standard`) before permissions or files change; the clone's index is never used. Only clean residue is made writable, without following symlinks, and deleted |
116
118
  | `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 |
117
119
  | `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 |
118
120
  | `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 |
@@ -139,6 +141,43 @@ and the rules its tests pin.
139
141
  | `harness-trust-json.mjs`, `harness-trust-toml.mjs` | bounded native parsers and byte-preserving edits of one trust leaf |
140
142
  | `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 |
141
143
 
144
+ An upgrade records a hook's in-flight marker before spawning it. A resumed
145
+ unknown outcome is durably recorded as uncertain before any retry work,
146
+ because the provider may already have changed host state even when no success
147
+ was recorded. Success or uncertainty makes the act forward-only. Only a
148
+ non-zero result observed and recorded in the same invocation, with no prior
149
+ success or uncertainty, permits rollback of composed bytes. An uncertain hook
150
+ is retried idempotently; a later refusal cannot turn that recovery into a
151
+ rollback.
152
+
153
+ Start and upgrade share the `.oats-start.lock` path through exclusive
154
+ acquisition: start uses `mkdir`, while upgrade creates a regular file with
155
+ `wx`. Both treat `EEXIST` as held. Upgrade takes the lifecycle claim before
156
+ reclaiming an interrupted upgrade's regular-file mutex, including an empty
157
+ file left by a killed opener, and never reclaims a directory. Start never
158
+ reclaims this path. Upgrade releases it only after persisting its final
159
+ invocation receipt.
160
+
161
+ Upgrade compares the home with its independent spawn baseline before it
162
+ changes anything there. A dirty home retains the entire baseline byte for
163
+ byte, so older kernels also recover its edits at retire. A clean home updates
164
+ only `homeFingerprint`; work fingerprints, digest versions, exclusions and
165
+ runtime authority remain as recorded. `retirementHomeChanged` and
166
+ `rebaseUpgradeRetirementBaseline` use retirement's existing comparison and
167
+ exclusions, without changing recovery or copy semantics.
168
+
169
+ The fingerprint helpers accept call-scoped `transientHomePaths`: exact
170
+ relative paths, no globs, each an existing regular file. Upgrade projects out
171
+ only `.oats-start.lock`. This is not a permanent exclusion: a later retire
172
+ hashes any leftover mutex as changed home bytes. The completed receipt is
173
+ published before the success event. A same-key retry deduplicates the event
174
+ and removes staging, without repeating adoption or composition.
175
+
176
+ Baseline replacement uses the existing atomic private-file writer. The
177
+ exclusive-create option still refuses an existing baseline. An interrupted replacement leaves a complete
178
+ old or new baseline, preserving the independent session authority required
179
+ to resume forward recovery.
180
+
142
181
  The schedule registry stores explicit concurrency caps, leaving the schedule
143
182
  cap absent for its effective default of five. `readRegistry()` is a pure,
144
183
  bounded atomic-file snapshot: it takes no lock and writes nothing, projecting