@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.
- package/bin/oats.mjs +166 -17
- package/docs/capabilities.md +58 -9
- package/docs/capability-manifest.schema.json +5 -1
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +463 -13
- package/docs/desktop.md +363 -67
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +46 -6
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +8 -2
- package/docs/souls-and-instances.md +58 -6
- package/docs/tui.md +1033 -237
- package/docs/upgrading.md +164 -26
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +8 -7
- package/lib/core.mjs +331 -75
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +10 -6
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +287 -89
- package/lib/servers.mjs +24 -11
- package/lib/soul-composition.mjs +7 -3
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +52 -6
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +9 -3
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +133 -28
- package/packages/client/keys-file.mjs +126 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +78 -12
- package/packages/client/spawn-naming.mjs +32 -0
- package/packages/client/spawn-preview-cli.mjs +58 -7
- package/packages/client/spawn-preview-contract.mjs +59 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +81 -3
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +7 -7
- package/packages/tui/lib/actions.mjs +92 -25
- package/packages/tui/lib/client.mjs +9 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +65 -24
- package/packages/tui/lib/model.mjs +292 -75
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +469 -100
- package/packages/tui/lib/term/keys.mjs +22 -6
- package/packages/tui/lib/term/kitty.mjs +54 -11
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +66 -28
- package/packages/tui/lib/views/frame.mjs +223 -165
- package/packages/tui/lib/views/help.mjs +134 -29
- package/packages/tui/lib/views/instances.mjs +63 -22
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- 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
|
|
201
|
-
|
|
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 --
|
|
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
|
|
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
|
|
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
|
|