@awebai/oats 0.66.0 → 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 (81) hide show
  1. package/bin/oats.mjs +166 -17
  2. package/docs/capabilities.md +58 -9
  3. package/docs/capability-manifest.schema.json +5 -1
  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 +463 -13
  7. package/docs/desktop.md +363 -67
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +46 -6
  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-lane.md +16 -0
  16. package/docs/release-notes/v0.67.0.md +366 -0
  17. package/docs/release-notes/v0.67.1.md +64 -0
  18. package/docs/release-notes/v0.68.0.md +504 -0
  19. package/docs/servers.md +8 -2
  20. package/docs/souls-and-instances.md +58 -6
  21. package/docs/tui.md +1033 -237
  22. package/docs/upgrading.md +164 -26
  23. package/docs/workspaces.md +2 -2
  24. package/lib/capability-contract.mjs +8 -7
  25. package/lib/core.mjs +331 -75
  26. package/lib/instance-color.mjs +58 -0
  27. package/lib/instance-events.mjs +1 -1
  28. package/lib/instance-inspect.mjs +107 -23
  29. package/lib/instance-lifecycle.mjs +21 -1
  30. package/lib/instance-naming.mjs +187 -0
  31. package/lib/instance-resolution.mjs +10 -6
  32. package/lib/instance-upgrade.mjs +1445 -0
  33. package/lib/materialize.mjs +287 -89
  34. package/lib/servers.mjs +24 -11
  35. package/lib/soul-composition.mjs +7 -3
  36. package/lib/upgrade-state.mjs +101 -0
  37. package/lib/workspace.mjs +4 -1
  38. package/lib/worktree.mjs +103 -12
  39. package/package-catalog.json +5 -4
  40. package/package.json +1 -1
  41. package/packages/client/cli-adapter.mjs +52 -6
  42. package/packages/client/cli-locator.mjs +2 -2
  43. package/packages/client/composed-gate.mjs +10 -2
  44. package/packages/client/deployment-data.mjs +5 -0
  45. package/packages/client/deployment-identity.mjs +40 -0
  46. package/packages/client/deployment-panel.mjs +9 -3
  47. package/packages/client/inspect-boundary.mjs +11 -7
  48. package/packages/client/inspect-cache.mjs +2 -2
  49. package/packages/client/instance-name.mjs +28 -0
  50. package/packages/client/instance-presentation.mjs +11 -0
  51. package/packages/client/keymap.mjs +133 -28
  52. package/packages/client/keys-file.mjs +126 -0
  53. package/packages/client/own-codes.mjs +4 -2
  54. package/packages/client/panel-views.mjs +78 -12
  55. package/packages/client/spawn-naming.mjs +32 -0
  56. package/packages/client/spawn-preview-cli.mjs +58 -7
  57. package/packages/client/spawn-preview-contract.mjs +59 -0
  58. package/packages/client/spawn-preview-facts.mjs +8 -4
  59. package/packages/client/spawn-preview.mjs +81 -3
  60. package/packages/client/team-members.mjs +4 -1
  61. package/packages/client/workspace-step.mjs +25 -0
  62. package/packages/tui/README.md +7 -7
  63. package/packages/tui/lib/actions.mjs +92 -25
  64. package/packages/tui/lib/client.mjs +9 -4
  65. package/packages/tui/lib/config.mjs +50 -9
  66. package/packages/tui/lib/main.mjs +65 -24
  67. package/packages/tui/lib/model.mjs +292 -75
  68. package/packages/tui/lib/read.mjs +53 -1
  69. package/packages/tui/lib/store.mjs +469 -100
  70. package/packages/tui/lib/term/keys.mjs +22 -6
  71. package/packages/tui/lib/term/kitty.mjs +54 -11
  72. package/packages/tui/lib/term/screen.mjs +15 -6
  73. package/packages/tui/lib/term/through.mjs +66 -28
  74. package/packages/tui/lib/views/frame.mjs +223 -165
  75. package/packages/tui/lib/views/help.mjs +134 -29
  76. package/packages/tui/lib/views/instances.mjs +63 -22
  77. package/packages/tui/lib/views/palette.mjs +14 -4
  78. package/packages/tui/lib/views/souls.mjs +2 -2
  79. package/packages/tui/lib/views/switcher.mjs +6 -1
  80. package/packages/tui/lib/views/workspaces.mjs +55 -0
  81. package/skills/oats-getting-started/SKILL.md +96 -42
@@ -0,0 +1,504 @@
1
+ # OATS 0.68.0
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.67 Desktop refuses a 0.68.0 CLI. The
9
+ 0.68.0 Desktop accepts OATS CLIs `>=0.26.0 <0.69.0`.
10
+
11
+ - **Package moves:** the official catalog pins oats.framework 1.14.1,
12
+ oats.okf 5.3.0, oats.engineering 1.11.0 and oats.aweb 1.31.0 (Provider
13
+ updates, below). A deployment that pins them takes them with `oats sync`;
14
+ new spawns use them, and existing homes move with the step below. No floor
15
+ changes: oats.aweb 1.31.0 still needs OATS >=0.52.0 and aw >=1.36.33.
16
+
17
+ - After bumping a package pin and running `oats sync`, stop each existing home
18
+ that should adopt it and review `oats instance upgrade <instance> --plan`.
19
+ Apply with the plan revision and an idempotency key, then start the session.
20
+ Providers with state must support the `upgrade` adoption hook; a provider
21
+ refusal names the remedy. oats.aweb's hook ships after this release, in
22
+ oats.aweb 1.32.0: until a deployment pins that, a plan that moves oats.aweb
23
+ refuses and names respawn. See [the deploy step](../upgrading.md#moving-existing-homes-to-locked-package-versions).
24
+ This command requires a kernel advertising `instance-upgrade`; older
25
+ kernels keep their existing spawn-only behavior.
26
+
27
+ ## Added
28
+
29
+ - `oats instance upgrade` moves a stopped local home's package modules to the
30
+ deployment lock, recomposing skills, instructions and hooks while keeping
31
+ the recorded soul and member modules. Plans show provider adoption and
32
+ composition changes and whether the home changed since spawn. Dirty homes
33
+ retain their original retirement baseline for recovery, including with older
34
+ kernels; work-tree baselines never change. Apply checks the revision and supports idempotent
35
+ retries. Undo verifies the latest saved state and asks the restored version
36
+ to adopt it. Before commit, a partial upgrade after a successful provider
37
+ hook or an interrupted hook with an uncertain outcome finishes forward
38
+ with the same key and blocks start with
39
+ `E_UPGRADE_PARTIAL`. After commit, a cleanup failure permits start with a
40
+ warning and the same-key retry finishes event publication and cleanup; another move waits
41
+ until cleanup finishes.
42
+ - Start and restart report package drift and the command to move those
43
+ modules. Their JSON includes `drift`; they keep the recorded copies. An
44
+ unreadable lock yields one warning and no `drift`, without blocking launch.
45
+ `modules.<cap>.previous` records the latest move, and `modules-upgraded`
46
+ records its completion in instance events. Desktop tolerates the additive
47
+ `previous` field and labels the new events: `modules-upgraded`, and
48
+ `upgrade-refused` with its failed step and reported reason.
49
+
50
+ - **Desktop: a spawn on another machine is named from its task.** With Name
51
+ left empty, a spawn on a server whose OATS takes an exact name is now named
52
+ from its Opening instruction, as a spawn on this computer is: the Desktop
53
+ asks this computer's harness and model for a name (OATS here with feature
54
+ `instance-suggest-name`), shows it in the field and under it, and the
55
+ server spawns under it. When this computer can't name it, the server names
56
+ it from its task if its OATS can (feature `spawn-apply-suggest-name`), and
57
+ otherwise numbers it as before. The help under an empty Name says which,
58
+ before you press Spawn, and a notification says why when the instance was
59
+ numbered instead. Naming never stops a spawn
60
+ ([desktop.md](../desktop.md)).
61
+
62
+ - **Desktop: Workspace › Capabilities shows the workspace's defaults.** A new
63
+ **Workspace defaults** section, above Workspace owned, shows what every soul
64
+ starts with unless it turns one off:
65
+ - **Core capabilities**: Knowledge, Messaging and Tasks, at most one of
66
+ each per soul. A filled slot shows the capability and where it comes
67
+ from, and opens its page. An empty one says there is no workspace
68
+ default and each soul chooses its own.
69
+ - **Additional capabilities**: any number per soul, the other capabilities
70
+ the workspace gives every soul, shown the same way. One the workspace
71
+ turned off is struck through.
72
+ - A workspace with no defaults, such as a standalone deployment, says so in
73
+ one line. The search and the repository pills never hide the section,
74
+ which comes first, above **All capabilities** and its section jump. With
75
+ an OATS that does not
76
+ report the defaults, the section is not shown.
77
+ - **Desktop: "What capabilities are".** The round **i** button after the
78
+ section jump explains what a capability gives a soul's instances, the three
79
+ places one comes from, which capabilities are core and which are
80
+ additional, and what workspace defaults are and why they matter.
81
+ Workspace › Souls has the same button, **About souls**, which explains what
82
+ a soul is
83
+ ([Desktop](../desktop.md#capabilities-and-spawning)).
84
+
85
+ - `oats instance suggest-name --soul <soul> --task-file <f> --json`
86
+ (feature `instance-suggest-name`) chooses the name a `--suggest-name` spawn
87
+ of a soul would get, on this machine, for a spawn that may land on another:
88
+ the soul only gives the role and needn't exist here. It resolves no
89
+ workspace, writes nothing, records nothing and reserves no name; it reads
90
+ only this machine's launch configurations and the OATS tmux server's
91
+ environment. Its model call is bounded as the preview's is, and the task
92
+ text goes to this machine's harness and model, as the preview's naming
93
+ does. [A name for a spawn elsewhere](../desktop-cli-api.md#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name).
94
+ The name is not made unique: the host the spawn lands on does that.
95
+ A naming failure answers a numbered result with its reason, never an error.
96
+ It is never routed: `--server` is refused.
97
+ - `oats spawn <soul> --suggest-name` on an apply (feature
98
+ `spawn-apply-suggest-name`): without `--preview`, the machine that spawns
99
+ names the instance `<descriptive>-<role>`, made unique as today, and
100
+ numbers it on any failure. The result carries `naming`. The naming call
101
+ can add up to 20 s to the apply. A spawn without the flag is unchanged.
102
+ Routed, the host needs the feature (`E_REMOTE_INCOMPATIBLE`, nothing sent).
103
+ [Desktop CLI API](../desktop-cli-api.md#on-an-apply-feature-spawn-apply-suggest-name)
104
+
105
+ - **Desktop: show only the current workspace.** A toggle before the **+** in
106
+ the Workspace heading hides every row of the list but the current one, for
107
+ working in one workspace at a time. Nothing stands for the hidden ones: no
108
+ "N more" line and no needs-input mark. It is also ⌥⇧⌘O on macOS and
109
+ Ctrl+Alt+Shift+O on Linux and Windows, the same in every chord family and
110
+ from a terminal, and the palette's **Workspaces: show only the current workspace (on / off)**. The
111
+ choice is remembered on this computer.
112
+ ([desktop.md](../desktop.md#workspaces),
113
+ [desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md#the-list-of-workspaces))
114
+
115
+ ## Changed
116
+
117
+ - **The `oats-getting-started` agent does more of the setup itself,
118
+ instead of handing it to the person**
119
+ ([#1314](https://github.com/awebai/oats/issues/1314)). A clean-machine trial of the skill
120
+ showed it handing back work at the end. Now:
121
+ - It adds `~/.local/bin` to the shell's startup file when it set a
122
+ per-user npm folder.
123
+ - It opens the GitHub device page in the browser.
124
+ - It opens the person's terminal with the exact command in it, for each
125
+ step that needs a password or token typed there (a `sudo` or Homebrew
126
+ password, an aweb invite token) and for the TUI. The person types only
127
+ the secret.
128
+ - On Linux it starts OATS Desktop on the new deployment through the
129
+ session manager (`systemd-run --user`), so it gets the desktop session's
130
+ environment rather than the agent's. It checks that it is running.
131
+ - It quits a running Desktop before installing over it.
132
+ - Without FUSE it uses `--appimage-extract-and-run`, which needs no
133
+ `sudo`.
134
+
135
+ - **Desktop: an instance's card on Workspace › Machines has two buttons.**
136
+ Clicking an instance shows what it reports, as before, and two buttons:
137
+ - **Go to instance** opens the instance's terminal tab. For a stopped
138
+ instance, which has no terminal, it reads **Start…** and opens the Start
139
+ dialog. Double-click, Enter and `T` do the same.
140
+ - **Go to soul** opens the soul the instance was spawned from on the
141
+ Workspace page: that exact soul, never another of the same name. When it
142
+ can't be told exactly, the button is disabled and says why, for example
143
+ when the soul is no longer among the deployment's souls, or the instance
144
+ is on a deployment other than the one the Workspace page shows.
145
+
146
+ The card's Git, Restart with…, Brain and Workspace buttons are gone, and so
147
+ is the `B` key there, which only said Brain was unavailable. Restart with…
148
+ is in the instance's menu and its panel, Git on the panel's Developer page,
149
+ and Workspace in the rail and on `S`
150
+ ([desktop.md](../desktop.md),
151
+ [desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
152
+
153
+ - **Desktop and TUI: pressing the leader (Ctrl+X) shows nothing.** The panel
154
+ of keys at the bottom of the Desktop's main area, and the TUI's leader hint
155
+ in place of its cheat sheet, are gone. The leader still waits for its key
156
+ exactly as before. Its table is in the Desktop's shortcuts editor (`?` after
157
+ the leader, or ⌘, / Ctrl+,) and in the TUI's help (`?`). In the Desktop, a
158
+ screen reader still hears that a key is awaited, and a key that cannot act
159
+ still says why in one quiet line
160
+ ([desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md),
161
+ [TUI](../tui.md)).
162
+
163
+ - **Desktop: the spawn dialog's section keys follow the form.** The Opening
164
+ instruction, the form's first field, is now ⌘1 / Ctrl+1, and Name, its last
165
+ before **Developer settings**, ⌘6 / Ctrl+6 (they were the other way round).
166
+ ⌘2–⌘5 and ⌘7 are unchanged. A shortcut you rebound is kept, and where one of
167
+ yours now shares a key with a section's new default, yours is the one that
168
+ runs, as the shortcuts editor says
169
+ ([desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
170
+ - **Desktop: the instance name is proposed sooner.** Once the Opening
171
+ instruction holds seven words, the Desktop asks OATS for a name as you type
172
+ (it waited for three words and a pause of about a second and a half). The
173
+ Name field's placeholder shows the proposed name alone, without "will be
174
+ named". ([Desktop](../desktop.md))
175
+
176
+ - **TUI: each workspace keeps its tabs, layout and place across a switch.**
177
+ - Opening another workspace still closes the open terminals' viewers (the
178
+ agents keep running), but coming back opens them again: the tabs in their
179
+ order and groups, the split, each group's shown tab, and where the focus
180
+ was, zoom included.
181
+ - A tab whose instance is gone or stopped is dropped; another machine's tab
182
+ is asked first again.
183
+ - The selection, the scroll and, new, the filter come back with their
184
+ workspace. Before, the filter was dropped on every switch, and a filter
185
+ still being typed in is kept as `Enter` keeps it.
186
+ - The palette (Ctrl+X then `k`) keeps each workspace's own recency, its last
187
+ 50 instances, so working in another workspace leaves it as it was.
188
+ - Nothing is kept after the TUI exits ([TUI](../tui.md)).
189
+
190
+ - **Desktop and TUI on Linux and Windows: the shortcuts are Alt chords by
191
+ default.**
192
+ - Alt+K is the palette, Alt+P Quick Open (a spawn, in the TUI), Alt+O the
193
+ list of workspaces, Alt+Z focus mode, Alt+W close the tab, Alt+E /
194
+ Alt+Shift+E split, and Alt+F the filter.
195
+ - Alt+← / → move between tabs, and Alt+Shift+← / → between split groups.
196
+ - Alt+↑ / ↓ move between workspaces.
197
+ - Alt+1–9 go to a tab.
198
+ - Alt+Shift+↑ / ↓ still open the previous / next instance.
199
+ - In a focused terminal, the family takes these keys from the program,
200
+ among them Alt+F (readline's forward-word) and Alt+O, which #1433 had
201
+ left to the program.
202
+ - **macOS: ⌥ with an arrow moves.** ⌥← / → go between tabs, ⌥⇧← / → between
203
+ split groups, and ⌥↑ / ↓ between workspaces. ⌥⌘↑ / ↓ still open the
204
+ previous / next instance, and the letters and digits stay on ⌘. ⌥⌘← / →
205
+ no longer move between tabs, and ⌥⌘A no longer goes to the next group.
206
+ - A text field keeps its ⌥ arrows for moving the cursor; a focused
207
+ terminal does not. To give them back to the shell, rebind them in the
208
+ Desktop's shortcuts editor.
209
+ - The TUI takes them only where the terminal sends ⌥ arrows as such
210
+ (iTerm2, kitty, WezTerm, Alacritty). Terminal.app, Ghostty and VS Code
211
+ send ⌥← / → as word moves unless set otherwise; the docs give each
212
+ setting. The leader moves everywhere.
213
+ - The TUI on macOS shows no tab numbers, since no key there reaches a tab
214
+ by number. The Desktop does (⌥⌘1–9).
215
+ - **Ctrl+Alt is still there, for programs that need Alt.** Choose it in the
216
+ Desktop's Shortcuts page, or in `keys.json` (`"chords": "ctrl+alt"`), which
217
+ both clients share. If you already chose Ctrl+Alt or Ctrl+Shift, you keep
218
+ it; only those who never chose move to Alt.
219
+ - Ctrl+Alt and Ctrl+Shift leave Alt+↑ / ↓ to the program. Ctrl+X then ↑ / ↓
220
+ moves between workspaces in every family.
221
+ - In the Alt family, Esc then the key reaches the program where the program
222
+ reads Esc as Meta (readline, zsh, Emacs, irssi). Otherwise choose
223
+ Ctrl+Alt.
224
+ - The docs list each key the family takes from Claude Code, Codex, pi, the
225
+ shell and the others, and how to reach it.
226
+ - **Each tab shows a small number**, the N that Alt+N goes to: 1–8, then 9 on
227
+ the last tab of a strip with nine or more. In a split, each group numbers
228
+ its own tabs. The Desktop's tab tooltip names the key. In the TUI, the
229
+ numbers are the first thing dropped when the tab bar is too narrow for
230
+ every name.
231
+ - **Ctrl+X then Shift+Tab** goes to the previous split group, as Ctrl+X then
232
+ Tab goes to the next.
233
+ - On AltGr keyboard layouts, AltGr still types its characters and never fires
234
+ an Alt chord.
235
+ ([desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md),
236
+ [TUI](../tui.md))
237
+
238
+ - **Desktop: the Workspace tabs read Souls, Capabilities, Teams, Machines,
239
+ Setup.** Teams was first, and Machines is the Deployments page of before.
240
+ The page still opens on Souls, and the arrow keys, Home and End follow the
241
+ new order
242
+ ([desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
243
+
244
+ - **New workspaces get aweb tasks.** The getting-started skill's workspace
245
+ file pins `oats.aweb` at v1.31.0 or later and sets
246
+ `defaults.tasks: { oats.aweb-tasks: { from: package } }` when the
247
+ workspace has messaging, so agents assign, claim and hand off work as aweb
248
+ tasks. A workspace on Jira or Linear writes that provider instead. An
249
+ existing workspace opts in as [integrations.md](../integrations.md#official-providers)
250
+ describes.
251
+
252
+ - `--suggest-name` with `--expect-decision`, which a preview accepted and
253
+ ignored, is refused (`E_BAD_ARGS`): the decision already binds a name.
254
+
255
+ - **Desktop and TUI: a list of workspaces at the top of the sidebar.** It
256
+ replaces the workspace menu and is always shown: one line per workspace you
257
+ can open, by name, whatever machines it is on. The current one is marked.
258
+ A click, or Enter on a row, shows that workspace in the same window. The
259
+ workspace's own pages show its machines and deployments.
260
+ - Each workspace keeps its own tabs, layout, selection and recency, as
261
+ before, so Ctrl+X then `k` (⌘K) still lists its instances, the most
262
+ recently selected first.
263
+ - In the Desktop, a workspace another window shows moves to this window,
264
+ with its terminals and its split. Its file, brain and view tabs close in
265
+ the other window. **Open in new window** is ⌘Enter / Ctrl+Enter on a row,
266
+ or the row's context menu.
267
+ - `w` in the sidebar, Ctrl+X then `o`, and the palette's
268
+ **Workspace: switch…** focus the list.
269
+ - **A yellow dot on a workspace where an instance needs input**, after its
270
+ name. Screen readers also get it as words, "needs input", and the TUI's help
271
+ explains the dot. A workspace that hasn't been read recently shows no dot,
272
+ never an old one.
273
+ - **Ctrl+X ↑ / ↓ move to the previous / next workspace of the list**, in both
274
+ clients. They don't wrap. They used to open the previous / next instance.
275
+ That move keeps its chords, Alt+Shift+↑ / ↓ (⌥⌘↑ / ⌥⌘↓ in the Desktop on
276
+ macOS), and the roster's own arrow keys. On macOS the TUI has no chords, so
277
+ there it's the roster's ↑ / ↓ then Enter.
278
+ - **Desktop: this computer's deployments that aren't opened yet are in
279
+ Add local workspace…**, not in the list.
280
+ - One click adds and opens one.
281
+ - Deployments that can't be opened (missing, not a deployment any more,
282
+ can't be checked) are listed after them, each with its **Remove**.
283
+ - While the Desktop has no workspace at all (a first launch), a new window
284
+ opens with this dialog.
285
+ - **TUI:** this machine's deployments that aren't opened yet stay in the
286
+ switcher (`w` `w`).
287
+ ([desktop.md](../desktop.md),
288
+ [desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md),
289
+ [TUI](../tui.md))
290
+
291
+ - **Desktop: Deployments is now Machines, a tab of the Workspace page.**
292
+ The sidebar's views are **Workspace overview** and **Automations**. The
293
+ Workspace page's tabs are Souls, Capabilities, Teams, **Machines** and
294
+ Setup. Machines says once what a machine is: each machine runs the
295
+ workspace in a folder of its own, and the instances under a machine run on
296
+ it. Each machine's tree has "Instances on this
297
+ machine" (or on the named machine) under its name. ⌘1 / Ctrl+1, the
298
+ palette's **View: Workspace › Machines** and every link that opened
299
+ Deployments open it there. A window opens on the Workspace page at launch
300
+ and after you choose a workspace. The Setup tab's machines box is now called
301
+ **Registered machines**.
302
+ - **Desktop: the instance rows show the soul and the repository.** The line
303
+ under an instance's name is its soul at the left and its repository at the
304
+ right. The branch and the pull request are in the row's hover card.
305
+ - **Desktop: the sidebar's foot.** One bar: the OATS mark at its left with the
306
+ sidebar toggle after it, and **Spawn instance** (its words alone, a ground
307
+ only on hover) and a
308
+ settings cog at its right. Spawn instance opens Quick Open (⌘P on macOS,
309
+ Alt+P on Linux and Windows), where you pick the soul. The cog's menu holds **Theme…** and **Keyboard
310
+ shortcuts…**. The logo in the heading, and the Settings, theme, shortcuts
311
+ and command-palette buttons, are gone. Connections is in the palette
312
+ (**Settings: Connections…**), and the palette is on ⌘K on macOS, Alt+K on
313
+ Linux and Windows, and Ctrl+X then `k`.
314
+ - **Desktop: the sidebar's lines.** A line sets the list of workspaces apart
315
+ from the views, and another the views from the instances. There is no line
316
+ under the Workspace heading, and the list of workspaces sits closer under
317
+ it, its rows a little closer together.
318
+ - **Desktop: the instances have no filter field.** To find an instance by
319
+ name, type it in the command palette. ⌘F / Alt+F, renamed **Focus the
320
+ instance roster** and still rebindable under its old id, goes to the
321
+ roster's current row. On an empty roster it goes to **Spawn instance**, as
322
+ F6 does. The TUI keeps its filter.
323
+ - **Desktop: Workspace › Capabilities in two parts.** **Workspace defaults**
324
+ comes first, then **All capabilities**, each with its title. The segments
325
+ that jump to Workspace owned, Repo owned and Packages sit under the All
326
+ capabilities title, and there is no Defaults segment.
327
+ - **Desktop: the Workspace pages name no deployment.** The "On This Mac ·
328
+ ~/…" line is gone from every Workspace tab, from Automations, and from a
329
+ capability's, a team's and a soul's page. They read the same deployment as
330
+ before; the side panel and the Machines tab still say which.
331
+ - **The list of workspaces, polished.**
332
+ - Desktop: its heading reads **Workspace**. Every row has the circle an
333
+ instance row has; the current workspace's is filled and its name bold,
334
+ so it no longer looks like the current view.
335
+ - Desktop: a workspace whose instance needs input shows an exclamation mark
336
+ at the row's right end. "N more below" shows it too when a workspace cut
337
+ off below waits. An instance's **Needs input** pill leads with the same
338
+ mark.
339
+ - Desktop: the Add local workspace dialog is named as its button and counts
340
+ only what can be added. It lists the folders that can't be opened under
341
+ their own heading.
342
+ - TUI: at either end of the list, Ctrl+X ↑ / ↓ keep the focus in the list,
343
+ and the "No workspace above / below" line moves nothing.
344
+ - TUI: `+N` carries the dot when a workspace it hides needs input.
345
+
346
+ ([desktop.md](../desktop.md), [TUI](../tui.md))
347
+
348
+ - **Desktop: the shortcuts window opens with a "Most useful" section.** It
349
+ lists the keys worth knowing first: the command palette, Quick Open,
350
+ previous / next tab, go to tab 1–9, previous / next workspace, split right /
351
+ down, previous / next split pane, close tab, focus mode, and the leader
352
+ then `?` for everything. The keys are read from the live keymap, so they
353
+ follow your platform, your chord family and your rebinds. Where the family
354
+ has no chord for a move, the leader's key is shown instead.
355
+ - **What has no sidebar button is in the shortcuts list:** the palette,
356
+ Connections ("Settings: Connections…", unbound and rebindable), and
357
+ Workspace › Machines (⌘1 / Ctrl+1), beside Workspace overview and
358
+ Automations, each with where it lands. The sidebar's Spawn instance is
359
+ Quick Open's row, and the settings cog's **Keyboard shortcuts…** opens the
360
+ list ([desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
361
+
362
+ ## Fixed
363
+
364
+ - `oats worktree remove` completes Git's partial deletion of a clean extra
365
+ tree containing read-only ignored output, such as a Go module cache. A
366
+ retry of an unregistered tree with a dangling `.git` file verifies its
367
+ surviving files against the recorded branch before deletion, refusing
368
+ modified or nonignored untracked paths even when tracked `.gitignore`
369
+ files were deleted. Permission changes stay within the tree and never
370
+ follow symlinks. Cleanup preserves `.git` until other entries are gone.
371
+ Incomplete removal keeps the record and reports partial deletion
372
+ accurately, with a manual recovery step when Git removed `.git` too.
373
+
374
+ - **Desktop: the tab and instance keys no longer skip a press.**
375
+ - In a split, the tab keys (Ctrl+Tab, Alt+Shift+←/→, ⌥←/→, the leader's
376
+ ←/→ and ⌥⌘1–9 / Ctrl+Alt+1–9) went through every tab in the order they
377
+ were opened, across both groups. They now stay in the focused group, in
378
+ the order its strip shows.
379
+ - Moving to the previous or next instance (the leader's ↑/↓,
380
+ Alt+Shift+↑/↓, ⌥⌘↑/↓) could re-open the instance already being opened
381
+ when pressed again before its terminal arrived. Each press now moves one
382
+ instance on.
383
+
384
+ - **Desktop: a spawn on another machine keeps the name you give it.** Spawning
385
+ onto a server (Where to run, or a soul listed from a server) named the
386
+ instance `<soul>-<what you typed>`, while the same name typed for this
387
+ computer became exactly `<what you typed>-<role>`. Now a spawn on a server is
388
+ named the same way as a local one when that machine's OATS can take an exact
389
+ name (feature `spawn-name`, OATS 0.26.0 and later, as its last roster answer
390
+ reports it): no `<soul>-` prefix in the field, the final name on the line
391
+ under it, and a name that machine refuses as taken or invalid is explained
392
+ there too. With an older OATS on either side, or a machine this computer has
393
+ not heard from, what you type is still a purpose, with its prefix shown
394
+ ([desktop.md](../desktop.md)).
395
+ - **Routed spawns check `--name` against the host.** `oats spawn --server <id>
396
+ --name <name>` is refused with `E_REMOTE_INCOMPATIBLE`, before anything is
397
+ sent, when the host does not advertise `spawn-name`, and with
398
+ `E_ROUTE_EXISTS` when a saved route here already holds that name
399
+ ([servers.md](../servers.md#run-there)).
400
+
401
+ - **Desktop: Electron 43.8.3, from 43.2.0, for Electron's security fixes.**
402
+ It carries the fixes for
403
+ [CVE-2026-102674](https://github.com/electron/electron/security/advisories/GHSA-gr2m-v5gq-v685)
404
+ (windows opened from a sandboxed top-level document did not inherit its
405
+ sandbox restrictions; fixed in 43.4.1) and
406
+ [CVE-2026-102677](https://github.com/electron/electron/security/advisories/GHSA-qmv3-fv6v-rmhq)
407
+ (the sandboxed preload code cache did not check that a cached entry matched
408
+ its preload; first released in 43.5.0), the block of the compromised
409
+ eMudhra intermediate certificates
410
+ ([GHSA-jr5w-w6x2-84p9](https://github.com/electron/electron/security/advisories/GHSA-jr5w-w6x2-84p9),
411
+ 43.8.1), and the other Electron advisories fixed on the 43 line since
412
+ 43.2.0. Neither CVE was reachable in the Desktop: it refuses every window a
413
+ page tries to open, its windows load only its own local files, and its
414
+ preload does not run sandboxed. Electron 43.8.3 bundles Node.js 24.22.0, so
415
+ the Node.js security release of 2026-10-21 (24.22.1) is not in it yet. The
416
+ Desktop's own code on that Node.js, its main process and its backend, makes
417
+ no TLS, DNS or outbound network connections: it reaches its backend over
418
+ 127.0.0.1 only.
419
+
420
+ - **Desktop: opening a new version while an older one runs says so.**
421
+ Installing a new Desktop (an AppImage, a DEB, another copy) while an older
422
+ one was running used to open a window of the old one, silently: the new
423
+ version's features seemed missing. Now the running Desktop opens or focuses
424
+ the window as before, then says which version you opened and which is still
425
+ running, and offers **Restart into** the new one (it closes Desktop's
426
+ windows and starts the version you opened; your agents keep running in their
427
+ sessions) or **Keep** the running one. When the copy you opened can't be
428
+ started again, it says to quit Desktop and open it again. This takes effect
429
+ once the running Desktop is this version or later: an older running Desktop
430
+ still opens its own window, so quit it once, by hand
431
+ ([desktop.md](../desktop.md#updating)).
432
+
433
+ ## Provider updates
434
+
435
+ - **oats.framework 1.14.1: oats.core 2.7.0, oats.setup 2.9.1.** Text only:
436
+ neither floor (`compatibility.oats`) changes. (1.14.0 was tagged but never
437
+ pinned by a release; 1.14.1 adds the last item below.)
438
+ - **`/oats-upgrade` reaches deployments.** oats.setup carries the skill
439
+ for "upgrade OATS" and "update to the latest": it reads the upgrade page
440
+ and release notes at the latest release's tag, not the installed copy,
441
+ and the setup inject lists it. `/oats-setup-model` points at it for an
442
+ upgrade ([#1440](https://github.com/awebai/oats/issues/1440)).
443
+ - **`/oats-operate` teaches moving a stopped home's package modules.** A
444
+ new section covers `oats instance upgrade`: stop, plan, apply with the
445
+ plan's revision and an idempotency key, then start; a partial move that
446
+ must finish forward; and `--undo` for the latest move. Its lines name
447
+ their version, "from OATS 0.68.0"
448
+ ([#1450](https://github.com/awebai/oats/issues/1450)).
449
+ - **`/oats-operate` on a half-done `oats worktree remove`.** From OATS
450
+ 0.68.0, `remove` finishes a deletion Git left half done on read-only
451
+ ignored output, and checks an unregistered residue against its branch
452
+ before removing it ([#1451](https://github.com/awebai/oats/issues/1451)).
453
+ - **`/oats-onboarding` pins `oats.okf: v5.3.0`** and describes its harvest
454
+ checkpoints and named harvesters.
455
+
456
+ - **oats.aweb 1.31.0: an official aweb provider for the tasks slot.** The
457
+ catalog and this workspace pin `oats.aweb: v1.31.0`. The package now ships
458
+ `oats.aweb-tasks` (`layer: tasks`) beside `oats.aweb` (messaging), and the
459
+ catalog aliases `oats.aweb-tasks` to it.
460
+ - A workspace selects it with
461
+ `defaults.tasks: { oats.aweb-tasks: { from: package } }` (or a soul's
462
+ `capabilities:`). Tasks use the instance's own oats.aweb identity in its
463
+ default team: the `/aweb-tasks` skill covers finding work, claims,
464
+ assignment, status, dependencies as blockers, handoff and epics through
465
+ `aw task` and `aw work`, with every prose field read from a file.
466
+ - The oats.aweb messaging instructions now point task state at the
467
+ selected tasks layer; `aw lock` and `aw roles` stay outside OATS.
468
+ - Readiness has no tasks-slot item for this provider. Its spawn hook adds a
469
+ fixed brief line and makes no aw calls.
470
+ - The floors are unchanged (OATS >=0.52.0, aw >=1.36.33). A pinned
471
+ `oats.aweb: v1.31.0` selects `oats.aweb-tasks` on older CLIs too, without
472
+ this alias (verified on 0.67.1). A deployment gets it by pinning the
473
+ version and running `oats sync`; only new spawns use it.
474
+
475
+ - **oats.okf 5.3.0: named harvest checkpoints; instances name their
476
+ harvesters.** The catalog and this workspace pin `oats.okf: v5.3.0`
477
+ (floor unchanged, OATS >=0.49.0).
478
+ - The checkpoints are a PR handed over for review, a finished task and, in
479
+ a long-lived role such as a maintainer's, a feature ready, a release or
480
+ deploy shipped, and a direction decision taken with the human. Each gets
481
+ one proposal carrying only what no earlier proposal carried, and a line
482
+ in `log.md` even when there is nothing to propose.
483
+ - The available-memory gate before a harvester spawn is gone. A proposal
484
+ held back by a harvester that is still listed launches at the next
485
+ checkpoint.
486
+ - The proposer names each harvester:
487
+ `oats spawn oats.okf/knowledge-harvester --name <harvester-name> …`,
488
+ with a name **okf-propose** prints from the source's name and a fresh
489
+ UUID. The kernel's numbered default could land on an alias that a
490
+ retired harvester's messaging certificate still holds, and the spawn
491
+ then failed at identity minting. `E_INSTANCE_NAME_TAKEN` and identity
492
+ failures stop and are reported, with no automatic rename.
493
+ - See [Knowledge](../knowledge.md#the-flow).
494
+ - **oats.engineering 1.11.0: the release lane.** The catalog and this
495
+ workspace pin `oats.engineering: v1.11.0` (floor unchanged). One
496
+ maintainer lane is the release lane: it plans and tags every release and
497
+ keeps the lane map, which says when another lane's merge needs its
498
+ sign-off. A maintainer the map doesn't name asks for a lane before it
499
+ acts. The maintainer's harvest checkpoints defer to the knowledge layer's
500
+ rules.
501
+ - **Upgrade:** `oats sync` locks both; only new spawns get them, or a
502
+ stopped home moved with `oats instance upgrade` (from OATS 0.68.0).
503
+ Peer maintainers name the release lane and the sign-off rule in their
504
+ lane map.
package/docs/servers.md CHANGED
@@ -235,7 +235,7 @@ sent as text or on stdin, never as paths.
235
235
 
236
236
  | Command | Where it runs | The server must advertise |
237
237
  |---|---|---|
238
- | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-preview-2` for `--preview` |
238
+ | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-preview-2` for `--preview`; `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply |
239
239
  | `status` | registered workspace | |
240
240
  | `retire` | the instance's home | `retire-home` to retire by exact home |
241
241
  | `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key` |
@@ -244,11 +244,17 @@ sent as text or on stdin, never as paths.
244
244
  | `okf harvest --instance <name>` | the saved home | `harvest` |
245
245
  | `schedule ...` | registered workspace | `schedule` |
246
246
  | `launch-config list\|set\|remove\|preview` | `--dir`, the instance's home, or the registered workspace | `launch-config` |
247
- | `inspect`, `operation run` | `--dir`, the instance's home, or the registered workspace | `operations`; `inspect --instructions` also `soul-composed-instructions`, `inspect --skills` also `soul-skills` |
247
+ | `inspect`, `operation run` | `--dir`, the instance's home, or the registered workspace | `operations`; `inspect --instructions` also `soul-composed-instructions`, `inspect --skills` also `soul-skills`, `inspect --composed-skills` also `soul-composed-skills` |
248
248
  | `readiness` | the instance's home, `--dir`, or the registered workspace | `readiness` (`readinessApi: 2`) |
249
249
  | `instance events` | the instance's home | `instance-events-2` (`eventsApi: 2`) |
250
250
  | `instance git`, `instance diff` | the instance's home; the Git runs there | `instance-git` (`instanceGitApi: 1`) |
251
251
  | `instance stop --plan\|--apply`, `retire --plan`, `retire --plan-revision … --idempotency-key …` | the instance's home | `lifecycle-plans` (`lifecycleApi: 1`) |
252
+ | `instance color` | the instance's home | `instance-color` |
253
+
254
+ `instance suggest-name` and `instance upgrade` are never routed: `--server` is
255
+ `E_BAD_ARGS`. `instance suggest-name` names a spawn on the machine that asks,
256
+ for a spawn that may land on another; the host it lands on makes the name
257
+ unique, or names an unnamed spawn itself with `--suggest-name`.
252
258
 
253
259
  Before every routed command except `status`, the kernel reads the server's
254
260
  `oats version --json`. A remote OATS older than 0.22.1 is refused, and so is a
@@ -197,8 +197,10 @@ For current settings and the respawn/cleanup sequence, see [knowledge.md](knowle
197
197
  A running home's hooks and messaging commands read the teams live
198
198
  ([capabilities.md](capabilities.md#teams-in-the-provider-environment)).
199
199
 
200
- A running instance never changes under itself: a member moving or a package
201
- bump affects only new spawns.
200
+ A running instance never changes under itself; a stopped one can be moved to
201
+ the locked package versions with `oats instance upgrade`. Member modules and
202
+ the soul body still require a new spawn. See
203
+ [upgrading package modules](upgrading.md#moving-existing-homes-to-locked-package-versions).
202
204
 
203
205
  ### The harness starts normally
204
206
 
@@ -313,15 +315,44 @@ locally refused legacy instance selector. For preview confirmation and receipt
313
315
  replay, see the [spawn decision and apply contract](desktop-cli-api.md#the-decision).
314
316
 
315
317
  ```bash
316
- oats spawn release-manager --purpose cut-3.2 --task "…" # a soul of a confirmed member
318
+ oats spawn release-manager --name cut-3-2-manager --task "…" # a soul of a confirmed member
317
319
  oats spawn release-manager --preview --json # decide everything, create nothing
318
320
  oats spawn release-manager --provider oats.aweb identity.source=/abs/path/to/retained/.aw # instance-level payload
319
321
  ```
320
322
 
321
- An instance is named `<soul>-<purpose>` by default, or exactly `--name <slug>`.
323
+ An instance is named exactly `--name <slug>`, or `<soul>-<purpose>` with
324
+ `--purpose`; with neither, the kernel numbers it. The convention for a name a
325
+ person or an agent chooses is `<descriptive>-<role>` through `--name`: a few
326
+ words for the instance's work, then the soul's role, the last word of the
327
+ soul's name after any package qualifier (`--name desktop-improvements-expert`
328
+ for an `oats-desktop-expert`). `--purpose` derives the name from the soul, for
329
+ automations and scripts that know only the soul and a purpose.
322
330
  Names are unique per deployment (a workspace-model deployment has one agents
323
331
  root): a derived name in use gets `-2`, `-3`…; an explicit `--name` in use is
324
- refused (`E_INSTANCE_NAME_TAKEN`).
332
+ refused (`E_INSTANCE_NAME_TAKEN`). The Desktop's spawn dialog adds the role to
333
+ a typed name.
334
+ `oats spawn <soul> --preview --suggest-name --task-file <f>` asks the soul's
335
+ own harness for the descriptive words, from the task, in one call that starts
336
+ none of the user's MCP servers, hooks, plugins or extensions. Claude Code's
337
+ built-in plugins, the host's managed-policy hooks and pi's credential commands
338
+ are the stated exceptions; a claude login through `apiKeyHelper` is not read,
339
+ so that user's name stays numbered (`harness-failed`). The preview then answers for
340
+ `--name <descriptive>-<role>`, de-duplicated the same way. On claude and pi
341
+ only; any other harness, and any failure of the call, leaves the name numbered
342
+ and says why
343
+ ([The suggested name](desktop-cli-api.md#the-suggested-name-feature-spawn-suggest-name)).
344
+ An apply takes `--suggest-name` too (without `--name` or `--purpose`): the
345
+ machine that spawns makes the same call, names the instance
346
+ `<descriptive>-<role>`, de-duplicated the same way, and numbers it on any
347
+ failure; the result's `naming` says which, and the apply may take up to 20 s
348
+ longer ([On an apply](desktop-cli-api.md#on-an-apply-feature-spawn-apply-suggest-name)).
349
+ Without the flag an apply is numbered, as before.
350
+ `oats instance suggest-name --soul <soul> --task-file <f>` asks for the same
351
+ words on this machine for a spawn that will land on another (the Desktop's
352
+ dialog, spawning through `--server`): the soul only gives the role and needn't
353
+ exist here, nothing is written or reserved, and the name is not made unique,
354
+ which the landing host does
355
+ ([A name for a spawn elsewhere](desktop-cli-api.md#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)).
325
356
 
326
357
  From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
327
358
  discovers the workspace over its remotes and confirms membership → finds the
@@ -1918,7 +1949,28 @@ that is `E_WORKTREE_DIRTY`, with Git's message, and the record is kept;
1918
1949
  commit and push the work, or discard it, then run `remove` again. A purpose
1919
1950
  with no record is `E_BAD_ARGS`: remove a tree made another way with
1920
1951
  `git worktree remove`. Any other refusal is `E_WORK_PRESERVATION_FAILED`,
1921
- and nothing is removed. On a `creating` record whose process is gone, `remove`
1952
+ and the record is kept. Git can remove its registration and some files before
1953
+ failing on read-only ignored output (for example, a Go module cache). Once
1954
+ Git's clean check has passed and its registration is gone, `remove` makes
1955
+ the remaining files writable and deletes them, without following symlinks
1956
+ outside the tree. It then prunes, verifies removal and drops the record.
1957
+
1958
+ A retry of an unregistered tree whose `.git` file points at a missing gitdir
1959
+ first compares its surviving files with the recorded branch through a
1960
+ temporary Git index. Deleted files are allowed; modified files and untracked
1961
+ files that are not ignored are `E_WORKTREE_DIRTY`, with their paths listed.
1962
+ Deleted entries are marked skip-worktree in that private index so Git can
1963
+ still read deleted `.gitignore` files from the branch when checking ignored
1964
+ output. This never changes the clone's index. Cleanup grants directories
1965
+ owner read, write and search access, and keeps `.git` until all other entries
1966
+ are deleted, so a failed deletion can be retried.
1967
+ An unreadable branch or a failed inspection keeps the tree and record.
1968
+ Failures after Git started removing files say that removal may be partial
1969
+ and name the retry. If Git already removed `.git` too, automatic comparison
1970
+ is refused: save any work and remove the directory by hand, then run
1971
+ `oats worktree remove --purpose <p>` again to drop the record. The refusal
1972
+ names that step.
1973
+ On a `creating` record whose process is gone, `remove`
1922
1974
  completes the rollback instead. Its answer then says whether the branch was
1923
1975
  kept (`branchKept`, `branchKeptReason`).
1924
1976