@awebai/oats 0.67.1 → 0.68.1

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 (64) 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 +316 -63
  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/release-notes/v0.68.1.md +102 -0
  17. package/docs/servers.md +6 -1
  18. package/docs/souls-and-instances.md +38 -3
  19. package/docs/tui.md +663 -243
  20. package/docs/upgrading.md +66 -6
  21. package/docs/workspaces.md +2 -2
  22. package/lib/capability-contract.mjs +6 -5
  23. package/lib/core.mjs +222 -38
  24. package/lib/instance-events.mjs +1 -1
  25. package/lib/instance-resolution.mjs +5 -5
  26. package/lib/instance-upgrade.mjs +1445 -0
  27. package/lib/materialize.mjs +225 -78
  28. package/lib/servers.mjs +11 -7
  29. package/lib/upgrade-state.mjs +101 -0
  30. package/lib/workspace.mjs +4 -1
  31. package/lib/worktree.mjs +103 -12
  32. package/package-catalog.json +5 -4
  33. package/package.json +1 -1
  34. package/packages/client/cli-adapter.mjs +15 -1
  35. package/packages/client/cli-locator.mjs +2 -2
  36. package/packages/client/deployment-panel.mjs +6 -2
  37. package/packages/client/instance-display-name.mjs +18 -0
  38. package/packages/client/keymap.mjs +89 -45
  39. package/packages/client/keys-file.mjs +9 -5
  40. package/packages/client/panel-views.mjs +16 -3
  41. package/packages/client/spawn-naming.mjs +7 -6
  42. package/packages/client/spawn-preview-cli.mjs +37 -1
  43. package/packages/client/spawn-preview-contract.mjs +35 -0
  44. package/packages/client/spawn-preview.mjs +35 -2
  45. package/packages/client/team-members.mjs +4 -1
  46. package/packages/client/workspace-step.mjs +25 -0
  47. package/packages/tui/README.md +5 -5
  48. package/packages/tui/lib/actions.mjs +51 -27
  49. package/packages/tui/lib/client.mjs +4 -2
  50. package/packages/tui/lib/config.mjs +4 -4
  51. package/packages/tui/lib/main.mjs +27 -13
  52. package/packages/tui/lib/model.mjs +143 -21
  53. package/packages/tui/lib/store.mjs +343 -68
  54. package/packages/tui/lib/term/keys.mjs +5 -3
  55. package/packages/tui/lib/term/kitty.mjs +28 -10
  56. package/packages/tui/lib/term/screen.mjs +15 -6
  57. package/packages/tui/lib/term/through.mjs +33 -28
  58. package/packages/tui/lib/views/capabilities.mjs +6 -6
  59. package/packages/tui/lib/views/frame.mjs +88 -109
  60. package/packages/tui/lib/views/help.mjs +57 -35
  61. package/packages/tui/lib/views/instances.mjs +48 -30
  62. package/packages/tui/lib/views/souls.mjs +9 -8
  63. package/packages/tui/lib/views/workspaces.mjs +55 -0
  64. package/skills/oats-getting-started/SKILL.md +92 -43
@@ -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.
@@ -0,0 +1,102 @@
1
+ # OATS 0.68.1
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - **From 0.68.0:** [the steps](../upgrading.md#the-steps), the Desktop
8
+ first and the CLI second. The 0.68.1 Desktop accepts OATS CLIs
9
+ `>=0.26.0 <0.69.0`. The official catalog pins oats.engineering 1.13.0
10
+ (Provider updates, below) in place of 0.68.0's 1.11.0.
11
+
12
+ - **From 0.67 or earlier:** do [0.68.0's Upgrade steps](v0.68.0.md#upgrade)
13
+ first: a 0.67 Desktop refuses a 0.68 CLI. From 0.66 or earlier, do 0.67.0's
14
+ too, and the older ones [Upgrading](../upgrading.md#coming-from-an-older-version)
15
+ names.
16
+
17
+ ## Added
18
+
19
+ - **Desktop: a resizable sidebar, a little wider by default.** The sidebar
20
+ is 288px wide (it was 264px), and its right edge is a handle: drag it
21
+ between 240px and 480px (at most 45% of the window, so the terminals keep
22
+ the rest), or Tab to it and use ← and → (Shift for bigger steps), Home and
23
+ End. A double-click on it, Enter, or the palette's **Sidebar: reset width**
24
+ put it back to 288px. The width is remembered on this computer and kept
25
+ while the sidebar is hidden. Terminals refit as it moves and tell their
26
+ programs the new size once, at the end.
27
+ ([desktop.md](../desktop.md#workspaces),
28
+ [desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md#keyboard-audit))
29
+
30
+ ## Changed
31
+
32
+ - **Desktop: the sidebar shows an instance's name as words.** Each `-` is a
33
+ space, and the first letter is a capital: `oats-expert-maintainer-lanes`
34
+ reads "Oats expert maintainer lanes", on nested rows and on a spawn's
35
+ pending row too. Only the row's label changes. The hover card, the command
36
+ palette's search, terminal tabs, a screen reader and the CLI keep the real
37
+ name ([OATS Desktop](../desktop.md#the-sidebars-instance-tree)).
38
+
39
+ - **Desktop: an instance that needs input shows it on its dot.** In the
40
+ sidebar's instance tree, the row's dot becomes the needs-input mark, the
41
+ amber disc with a "!" that the terminal tab and the workspace list already
42
+ show, and the row's "Needs input" label is gone: its second line keeps the
43
+ soul and the repository. A screen reader still hears "Needs input" after the
44
+ name, the hover card keeps the reason and how long it has waited, and a
45
+ collapsed parent still shows "! N below" for the rows it hides
46
+ ([OATS Desktop](../desktop.md#the-sidebars-instance-tree)).
47
+ - **Desktop: yellow now means needs input only.** Unknown state has its own
48
+ look, a grey ring with a small grey centre, in the sidebar, the command
49
+ palette, Quick Open, the overview and a team's member list. The keyboard
50
+ shortcut clash dot, the Workspace page's Setup and Teams attention dot and
51
+ the Automations problem dots are red.
52
+
53
+ - **TUI: an instance's row shows its name as words**, as the Desktop's
54
+ sidebar does: each `-` a space and the first letter upper-case, so
55
+ `oats-expert-lead` reads `Oats expert lead`, nested rows included. Only
56
+ the row changes: the detail, the filter (`oats-expert` still finds the
57
+ row), the palette, the tabs, the confirmations and everything sent to
58
+ OATS keep the instance's name, and a row is cut as before. See
59
+ [What it shows](../tui.md#what-it-shows).
60
+
61
+ - **TUI: an instance that needs input shows it by its mark, not a tag in
62
+ words.** Its row draws `!` in place of its state mark, bold, in reverse
63
+ video in yellow (not reversed on the selected row, a gap in the
64
+ selection's bar), whatever its state and its colour; the row's
65
+ `Needs input` tag is gone, and its name is cut as before. Under
66
+ `NO_COLOR` the reverse video and the `!` carry it, and in ASCII it is the
67
+ same `!`. A folded row keeps its `N below` tag for the waiting instances
68
+ it folds away, whether or not it waits itself. The detail still says it
69
+ in words, with the reason and how long it has waited, and the help lists
70
+ the mark. Yellow now means needs input only: a state unknown (`?`) is
71
+ dim in the terminal's foreground, and the warnings of the Souls and
72
+ Capabilities views (a failed read, `Can't spawn here`, `· N on an older
73
+ version`) are bold red, and a `sand` instance or soul is in the
74
+ terminal's foreground colour.
75
+ ([tui.md](../tui.md#what-it-shows))
76
+
77
+ ## Provider updates
78
+
79
+ - **oats.engineering 1.13.0: one release lane, and one lane per project.**
80
+ The catalog and this workspace pin `oats.engineering: v1.13.0` (floor
81
+ unchanged). It carries 1.12.0 and 1.13.0 together, and supersedes 1.11.0's
82
+ "a maintainer the map doesn't name asks for a lane before it acts":
83
+ - **The release lane** does the final review and the merge of what the
84
+ other lanes hand it, owns and tags every release, and keeps the lane map.
85
+ - **Every other lane is a project lane.** A maintainer defines one, or
86
+ claims one with no active maintainer, when it holds none or its human
87
+ asks, and adds itself to the map; several maintainers may share a lane.
88
+ A project lane reviews its own work and hands each approved PR to the
89
+ release lane. The map may record another arrangement for a lane, agreed
90
+ with the release lane.
91
+ - **A human's high-level picture is the maintainer's intake.** The
92
+ maintainer writes the brief and launches the expert, which writes the
93
+ spec and plan. A lead launched for work in a lane the maintainer holds is
94
+ its child (`--parent`); work for another lane goes to that lane's
95
+ maintainer, or to a maintainer spawned for it, and the human is told who
96
+ has it.
97
+ - Also taught: splitting a lane, the owning lane's second read on a
98
+ cross-lane PR, confirming a relayed human decision directly, cleaning up
99
+ a cancelled effort, and a failed publication (re-run from the same tag).
100
+ - **Upgrade:** `oats sync` locks it; new spawns get it, or a stopped home
101
+ moved with `oats instance upgrade`. Peer maintainers record their lanes,
102
+ and any non-default arrangement, in their 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`, and `spawn-suggest-name` for `--suggest-name` |
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` |
@@ -251,6 +251,11 @@ sent as text or on stdin, never as paths.
251
251
  | `instance stop --plan\|--apply`, `retire --plan`, `retire --plan-revision … --idempotency-key …` | the instance's home | `lifecycle-plans` (`lifecycleApi: 1`) |
252
252
  | `instance color` | the instance's home | `instance-color` |
253
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`.
258
+
254
259
  Before every routed command except `status`, the kernel reads the server's
255
260
  `oats version --json`. A remote OATS older than 0.22.1 is refused, and so is a
256
261
  missing feature (`E_REMOTE_INCOMPATIBLE`), before anything is sent. A spawn is