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