@awebai/oats 0.68.1 → 0.69.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/bin/oats.mjs +102 -22
  2. package/docs/capabilities.md +49 -5
  3. package/docs/configuration.md +68 -2
  4. package/docs/desktop-cli-api.md +355 -12
  5. package/docs/desktop-instance-start.md +88 -3
  6. package/docs/desktop.md +108 -10
  7. package/docs/execution-targets.md +514 -62
  8. package/docs/harness-trust.md +3 -1
  9. package/docs/implementation.md +28 -11
  10. package/docs/integrations.md +1 -1
  11. package/docs/oats-local.schema.json +2 -2
  12. package/docs/official-catalog.md +4 -3
  13. package/docs/packages.md +7 -7
  14. package/docs/release-notes/v0.69.0.md +658 -0
  15. package/docs/release-notes/v0.69.1.md +25 -0
  16. package/docs/servers.md +44 -5
  17. package/docs/souls-and-instances.md +11 -7
  18. package/docs/tui.md +77 -12
  19. package/docs/upgrading.md +12 -7
  20. package/docs/workspaces.md +1 -1
  21. package/lib/core.mjs +345 -89
  22. package/lib/file-pieces.mjs +49 -0
  23. package/lib/instance-events.mjs +25 -4
  24. package/lib/launch-prompt-fixtures/README.md +62 -0
  25. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  26. package/lib/launch-prompt-fixtures.mjs +49 -0
  27. package/lib/launch-prompt-resume.mjs +55 -0
  28. package/lib/login-environment.mjs +27 -9
  29. package/lib/schedule.mjs +3 -3
  30. package/lib/servers.mjs +117 -23
  31. package/lib/session-end.mjs +82 -0
  32. package/lib/session-input.mjs +43 -9
  33. package/lib/session-resume-contract.mjs +32 -0
  34. package/lib/session-resume.mjs +310 -0
  35. package/lib/session-seen.mjs +163 -0
  36. package/lib/session-viewer.mjs +147 -44
  37. package/lib/soul-composition.mjs +2 -1
  38. package/lib/start-env.mjs +110 -0
  39. package/lib/tmux-server-scope.mjs +139 -14
  40. package/lib/workspace.mjs +38 -4
  41. package/package-catalog.json +10 -4
  42. package/package.json +1 -1
  43. package/packages/client/cli-adapter.mjs +9 -0
  44. package/packages/client/cli-locator.mjs +3 -2
  45. package/packages/client/deployment-data.mjs +7 -0
  46. package/packages/client/deployment-panel.mjs +3 -0
  47. package/packages/client/file-output-exec.mjs +98 -0
  48. package/packages/client/launch-prompt-outcome.mjs +25 -13
  49. package/packages/client/own-codes.mjs +2 -0
  50. package/packages/client/session-attach.mjs +35 -5
  51. package/packages/client/session-resume-cli.mjs +64 -0
  52. package/packages/client/session-resume-trigger.mjs +167 -0
  53. package/packages/client/session-resume.mjs +332 -0
  54. package/packages/client/tmux-status.mjs +30 -7
  55. package/packages/client/waiting-on-you.mjs +11 -4
  56. package/packages/client/workspace-step.mjs +17 -5
  57. package/packages/record/lib/last-conversation.mjs +123 -0
  58. package/packages/record/lib/session-roots.mjs +10 -1
  59. package/packages/tui/lib/client.mjs +1 -1
  60. package/packages/tui/lib/main.mjs +5 -3
  61. package/packages/tui/lib/model.mjs +45 -12
  62. package/packages/tui/lib/store.mjs +8 -7
  63. package/packages/tui/lib/term/text.mjs +12 -9
  64. package/packages/tui/lib/views/frame.mjs +72 -7
  65. package/packages/tui/lib/views/help.mjs +8 -3
  66. package/packages/tui/lib/views/instances.mjs +3 -2
  67. package/skills/oats-getting-started/SKILL.md +117 -4
@@ -0,0 +1,658 @@
1
+ # OATS 0.69.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.68 Desktop refuses a 0.69.0 CLI. The
9
+ 0.69.0 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
10
+
11
+ - **Package moves:** the official catalog pins oats.aweb 1.32.0,
12
+ oats.framework 1.15.1 and oats.engineering 1.15.0 (Provider updates, below).
13
+ oats.aweb 1.32.0 requires OATS >=0.68.0: every host that shares a
14
+ workspace runs OATS 0.68.0 or later before any of them syncs to it. A
15
+ deployment then takes them with `oats sync`; new spawns use them, and a
16
+ stopped home moves to them with `oats instance upgrade`.
17
+
18
+ - A broken machine file (unreadable, not YAML, empty, another top-level key,
19
+ an invalid entry) refuses every launch that reads launch configurations,
20
+ with `E_LAUNCH_CONFIG_INVALID` naming the file. A missing file changes
21
+ nothing.
22
+
23
+ - An instance last started before this version has no record of its launch
24
+ environment. Its first resume after the upgrade goes ahead with one warning:
25
+ "`<instance>`'s launch environment could not be verified this once (it was
26
+ last started before OATS recorded it); its next start records it". From
27
+ then on it is checked (#1559).
28
+
29
+ - **Run `oats status` once before you restart.** After upgrading, open OATS
30
+ Desktop or `oats tui`, or run `oats status`, once before you restart this
31
+ computer, or nothing from before the upgrade comes back: the sweep only
32
+ resumes what OATS saw running.
33
+ - **A boot nobody looked at.** A whole boot with no OATS read leaves that boot
34
+ unknown: what ran in it and was lost there is not resumed.
35
+ - **One legacy gap.** An instance spawned before this release, never
36
+ restarted since, whose harness ends by itself after the upgrade, reads
37
+ `lost` and comes back once. Its next start records what is needed; stop it
38
+ with OATS to keep it stopped.
39
+ - **Claude's resume-cost dialog.** On some plans Claude asks, at the first
40
+ message of a resumed long conversation, whether to resume from a summary or
41
+ in full. OATS sends no key: the person chooses. The resume is reported
42
+ waiting (`resume-confirmation`), open the instance's terminal to answer.
43
+ The dialog is recognised from Claude Code's strings and documentation, not
44
+ from a captured screen.
45
+ - **Codex starts fresh.** A Codex instance is not resumed until a Codex resume
46
+ is proven end to end on a signed-in host: it starts fresh on `TASK.md`
47
+ (`resume-unproven`).
48
+ - **No recovery copy for an exited harness.** The exit marker no longer counts
49
+ as changed home bytes at retire, so an instance whose harness ended needs no
50
+ recovery copy because of it. Retirement baselines keep their digest version.
51
+
52
+ ## Added
53
+
54
+ - Sessions come back after a shutdown, a reboot or a crash (feature
55
+ `session-resume`, #1559). `oats session resume` starts every instance whose
56
+ session OATS saw alive and then lost, on every deployment in this
57
+ computer's list, each in its
58
+ own harness conversation (Claude `--resume`, pi `--session`) with the launch
59
+ it recorded and a one-line resume notice as its prompt. Running instances
60
+ are left alone; instances stopped with OATS, or whose harness ended by
61
+ itself, stay stopped: stopping with OATS is the only way to keep an instance
62
+ down. One sweep runs per machine (`E_RESUME_BUSY`); each loss is answered
63
+ once, so a refused resume is not tried again, after a reboot either; and a
64
+ home is started by sweeps at most 3 times in a boot (on Linux and macOS,
65
+ which have a boot to count in), then reported `keeps-getting-lost` and left
66
+ down, after a reboot too, until someone starts it.
67
+ **An agent killed outside OATS (closed from tmux, or killed by a signal)
68
+ comes back within 24 hours: only `oats instance stop` keeps it down.** The
69
+ clients run it when they open, in a later change. See
70
+ [Resume after a shutdown](../execution-targets.md#resume-after-a-shutdown).
71
+ - `oats session start --resume --home <abs>`: one home's resume. It refuses a
72
+ launch choice (`E_BAD_ARGS`) and a home that did not lose its session
73
+ (`E_RESUME_NOT_LOST`); with no conversation to continue it starts fresh on
74
+ `TASK.md` and says why (`resumed: false`). Its answer and the sweep's are in
75
+ the [Desktop CLI API](../desktop-cli-api.md#resume-a-lost-session---resume).
76
+ A warning the sweep's starts say of the computer rather than of their
77
+ instance (today only that harnesses get no scope of their own) is said once,
78
+ in the sweep's own `warnings`, not in each row.
79
+ - `sessionEnd` (`lost`, `stopped`, `exited`) on `oats status --json` rows of
80
+ launched instances that do not run.
81
+ - Only a loss OATS saw is resumed. The sweep brings back a lost instance when
82
+ OATS saw it running (in `oats status`, OATS Desktop or `oats tui`), no
83
+ earlier sweep has answered that loss, OATS first saw it stopped less than a
84
+ day ago, and, if the computer did not restart in between, it stopped less
85
+ than a day after OATS last saw it run. Any other lost instance is reported
86
+ `not-seen-recently` and left as it is; start it by hand to bring it back.
87
+ So an agent killed in the night comes back in the morning, and a laptop
88
+ closed for two weeks brings back what ran when it was closed.
89
+ - A local `oats status` now records what it saw of each instance, for the
90
+ sweep: in a private file under `~/.oats/session-resume/`, one per
91
+ deployment. It never changes what status prints or exits with. A status
92
+ run on another machine with `--server` records nothing on this one.
93
+
94
+ - **Desktop: lost sessions are resumed.** After a shutdown, a reboot or a
95
+ crash, opening Desktop asks OATS to resume every instance whose session was
96
+ lost, on every deployment on this computer. While Desktop is open, it asks
97
+ again when it sees a session that was lost, at most once every 30 seconds,
98
+ and not again for an instance OATS could not resume. None of this holds
99
+ anything up. When an instance was resumed, started fresh, is waiting for you
100
+ or could not be resumed, a notice says so and stays until you dismiss it.
101
+ Its Details name each instance and what happened to it, and say which
102
+ deployments were not checked. An instance that keeps losing its session is
103
+ named once, and OATS stops resuming it until you start it yourself. More
104
+ than three notices fold into one. Nothing lost means no notice. Quitting
105
+ Desktop while the sessions are being resumed does not cut that short
106
+ ([desktop-instance-start.md](../desktop-instance-start.md#when-desktop-opens)).
107
+
108
+ - A resume starts only under the `{fromEnv: SRC}` values its instance's last
109
+ start ran with. A value that changed since refuses the resume before
110
+ anything is launched: `E_LAUNCH_ENV_CHANGED`, naming the variables, never
111
+ their values. `oats session resume` reports it as a refused start
112
+ (`refused`, `start-refused`), and `--plan` predicts it. Start the instance
113
+ yourself to use the new values: an ordinary start never compares. Every
114
+ start records its launch environment as a keyed one-way digest per variable,
115
+ in two kernel-private files in the home. A value, which may be a credential,
116
+ is never written (#1559). See
117
+ [The launch environment a resume runs under](../execution-targets.md#the-launch-environment-a-resume-runs-under).
118
+
119
+ - **`Shift+PageUp` scrolls back in `oats session attach`**
120
+ ([#1476](https://github.com/awebai/oats/issues/1476)). Every viewer binds
121
+ it to tmux's copy mode, a page up, with or without `--detach-key`. Under an
122
+ agent that takes the mouse, as Claude Code does, the wheel goes to the agent,
123
+ and a viewer had no way to scroll back. In copy mode `PageUp` and `PageDown`
124
+ move and `q` leaves it. See
125
+ [Inspect, input and attach](../execution-targets.md#inspect-input-and-attach).
126
+
127
+ - **Desktop: scroll back in a terminal with the keyboard.** Shift+PgUp, or
128
+ Ctrl+B then `[`, scrolls back through an agent's output, as the wheel does,
129
+ in every terminal tab on this computer, and on another computer running
130
+ OATS 0.69.0 or later. Ctrl+B followed by any other key still reaches the
131
+ agent as both keys. Ctrl+B `[` needs tmux 3.3 or later on the computer the
132
+ agent runs on. The shortcuts window lists the three under Tabs
133
+ ([desktop.md](../desktop.md#copy-from-a-terminal),
134
+ [desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
135
+
136
+ - **Desktop: the shortcuts window's Most useful names how to scroll back in a
137
+ terminal** ([#1502](https://github.com/awebai/oats/issues/1502)): "Wheel
138
+ up, Shift+PgUp or Ctrl+B then `[`", as the Tabs group's row does. The Tabs
139
+ row's tooltip also says that on another computer the two keys need OATS
140
+ 0.69.0 or later there. On Linux and Windows, when a shortcut that works in
141
+ a terminal is bound to Ctrl+B, both rows leave Ctrl+B `[` out and the
142
+ tooltip names the shortcut
143
+ ([desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
144
+
145
+ - **Desktop: an agent's question shows over its terminal.** While an instance
146
+ waits on you, each terminal tab that shows it has a row over the terminal.
147
+ The row says **Needs input** and how long it has waited, and under that the
148
+ agent's question, as plain text. When the agent left no text, the row gives
149
+ the reason in words, for example "Waiting for a tool approval". The question
150
+ wraps to at most three lines, never takes more than a quarter of the pane,
151
+ and ends with "…" when it is longer. The terminal resizes only when the wait
152
+ starts, ends or its text changes, never as the age ticks over. In a split,
153
+ each group has its own row
154
+ ([desktop.md](../desktop.md#when-an-agent-waits-on-you)).
155
+
156
+ - **TUI: the cheat sheet names a terminal's scroll keys**
157
+ ([#1502](https://github.com/awebai/oats/issues/1502)). While a terminal
158
+ has the focus, the cheat sheet and, where it has room, a zoomed
159
+ terminal's title row name the viewer's own keys: `Shift+PageUp or
160
+ Ctrl+B [`, then `scroll back` (`Ctrl+B [` alone where the row holds one
161
+ key). In the Alt family a zoomed terminal 120 columns wide or less has no
162
+ room for them: its chords keep the row.
163
+ - The keys are the ones the tab's host's kernel says its viewer takes:
164
+ `Shift+PageUp` where it lists `session-attach-prefix-scroll`, and
165
+ `Ctrl+B [` too where its `sessionViewer.prefixScroll` is true. That is
166
+ this machine's `oats version --json` for a local tab, and the roster
167
+ probe of its server for a remote one. A host without the feature gets
168
+ no scroll keys named. `Ctrl+B [` is never named when the leader is
169
+ `Ctrl+B` (`open.detachKey: "C-b"`), which takes that key first.
170
+ - Each tab's viewer runs without its own status line where the kernel
171
+ has `--no-status-line`: the cheat sheet says it instead.
172
+ - See [the TUI's tabs](../tui.md#tabs).
173
+
174
+ - **TUI: an open agent that waits on you says what it waits on, above its
175
+ terminal** ([#1502](https://github.com/awebai/oats/issues/1502)).
176
+ - While the shown tab's agent has a live claim, a row stands under its
177
+ tab bar: `Needs input`, how long it has waited, and the claim's
178
+ message.
179
+ - A claim with no message says what it waits on, for example
180
+ `waiting on a permission prompt`.
181
+ - The message wraps to at most 3 rows, and to a quarter of the group's
182
+ height at most.
183
+ - The agent's pane is resized only when the claim starts, clears or
184
+ changes its text. Before, the question showed only in the agent's
185
+ detail, which an open terminal covers. See
186
+ [Tabs](../tui.md#tabs).
187
+
188
+ - **`C-b [` scrolls back in `oats session attach`, and the viewer says how**
189
+ ([#1502](https://github.com/awebai/oats/issues/1502)). Not every keyboard
190
+ has a PageUp.
191
+ - **`C-b [`:** a viewer without `--detach-key` takes it to enter tmux's copy
192
+ mode, as a tmux prefix does. It is the viewer's only `C-b` key. Any other
193
+ key after `C-b` still reaches the agent as both keys (`C-b n`, `C-b c`,
194
+ `C-b C-b`), with no timeout. It needs tmux 3.3 or later, whose
195
+ `send-keys` can re-send the key after `C-b`. On an older tmux the viewer
196
+ has no `C-b` key, and the line names `Shift+PgUp` alone.
197
+ - **The status line:** the viewer shows one line under the agent,
198
+ `Shift+PgUp or C-b [ to scroll back`. It takes the terminal's last row.
199
+ - **`--no-status-line`** (feature `session-attach-no-status-line`) drops
200
+ the line, for a caller that shows the keys itself.
201
+ - **`sessionViewer.prefixScroll`** (feature `session-attach-prefix-scroll`)
202
+ on `oats version --json` and `oats status --json`, relayed as each
203
+ roster group's `probe.sessionViewer`: whether that host's viewer takes
204
+ `C-b [`, read from its tmux afresh at each run. A caller that names the
205
+ keys itself reads it per host.
206
+ - **Copy mode is the agent pane's.** While one viewer scrolls back, every
207
+ other viewer of that agent shows the same frozen screen.
208
+ - **Each viewer reads key tables of its own**, named as its session and
209
+ removed with it. Before, every viewer without a detach key shared one
210
+ server-wide table, `oatsview-locked`.
211
+ - **A tmux limitation:** a `C-b` pressed in the instant another viewer of
212
+ the same tmux server opens is dropped. tmux resets every client's key
213
+ table when any session sets `key-table`. The key after it reaches the
214
+ agent alone.
215
+ - See
216
+ [Inspect, input and attach](../execution-targets.md#inspect-input-and-attach).
217
+
218
+ - This machine's launch configurations: `~/.oats/config/launch-configs.yaml`
219
+ (`$OATS_HOME_DIR/config/` when set) declares launch configurations for every
220
+ deployment on the machine. Its one key is `launch-configs:`, with the
221
+ deployment block's schema. A deployment entry with the same name replaces
222
+ the machine's whole and lists the machine file in `shadows`. A deployment's
223
+ `default: true` for a harness wins over the machine's. With no deployment
224
+ in reach, the machine's entries alone apply. A relative `executable`
225
+ resolves against `~/.oats/config`. The person or an installer writes the
226
+ file; `oats launch-config set|remove` keep writing only `oats-local.yaml`.
227
+ See [This machine's launch configurations](../configuration.md#this-machines-launch-configurations).
228
+ - `oats launch-config list` gives each entry's `source` and `shadows`, and its
229
+ text marks machine entries. `oats spawn --preview` names the machine file
230
+ when it supplied the configuration, and its `--json` carries
231
+ `launchConfigSource`, the declaring file's directory. `oats doctor` reports the file, and its
232
+ `--json` carries `machineLaunchConfigs` (`file`, `present`, `ok`,
233
+ `configurations`, `error`).
234
+
235
+ - **Desktop: a font picker.** **Font…** in the settings cog's menu, or
236
+ **Font: choose…** in the command palette (no default shortcut; give it one
237
+ in the shortcuts editor), chooses between
238
+ **Omarchy's font** and **System font**. The choice is kept on this computer
239
+ and applies at once: open terminals switch font in place and keep their
240
+ session. The terminal font size and zoom are unchanged (**Theme and
241
+ font**, under [Workspaces](../desktop.md#workspaces)).
242
+
243
+ - **`oats.machine` is an official package** at `v0.1.1`
244
+ ([official catalog](../official-catalog.md)). It brings a steward for one
245
+ computer, `oats.machine/steward`, and a technician that handles one machine
246
+ problem at a time; both use the `oats.machine-care` capability, which the
247
+ catalog aliases to the package. A workspace pins it as
248
+ `oats.machine: v0.1.1`.
249
+
250
+ ## Changed
251
+
252
+ - On Linux, on the unified cgroup hierarchy, each agent's harness now runs in
253
+ a systemd scope of its own, `oats-agent-<hash>-<random>.scope` in the user
254
+ manager's default slice, at every launch (spawn, session start and restart),
255
+ wherever the OATS tmux server runs: systemd-oomd, which ends a whole cgroup
256
+ under memory pressure, then ends one agent, never the server or the others.
257
+ The harness stays the pane's direct child, and nothing recorded changes (the
258
+ home's command, its launch recipe, receipts, `oats spawn --preview`). Before
259
+ it wraps, a launch checks with `systemd-run --user --scope -- true`, in the
260
+ pane's environment, that a scope can be created. When it cannot on a host
261
+ booted with systemd (no user manager or bus in the pane, no `systemd-run`),
262
+ the harness is launched as before, and the answer's `warnings` say `the agent's harness runs in the OATS
263
+ tmux server's cgroup, not a scope of its own: <reason>`, as does a
264
+ `launch-warning` event once the launch is recorded (a start refused after
265
+ the check leaves none). Off Linux, on a Linux host not booted with systemd
266
+ (a container's own init, another init system) and on the old or hybrid
267
+ hierarchy, nothing changes and nothing is said (#1559).
268
+ - The OATS tmux server is now started in a scope of its own from inside any
269
+ unit of the user manager, not only a service: a client launched from a
270
+ desktop session (OATS Desktop or `oats tui` in its `app-*.scope`), a
271
+ terminal's scope, an agent's scope. A login session's `session-N.scope` (an
272
+ ssh or tty login) starts the server as before. A server that already runs
273
+ keeps the cgroup it has (#1559). See
274
+ [Where sessions run](../execution-targets.md#where-sessions-run-the-servers-scope-and-each-agents).
275
+
276
+ - **Desktop: the command that opens Workspace › Souls is named for what it
277
+ does.** ⌘N / Ctrl+Shift+N, in the command palette and the shortcuts editor,
278
+ now reads **Souls: choose a soul to spawn (Workspace › Souls)**, where it
279
+ read **Spawn instance: choose a soul in Workspace**, so it is not mistaken
280
+ for the sidebar's **Spawn instance** button, which opens Quick Open. Its
281
+ keys are unchanged
282
+ ([Keyboard shortcuts](../../packages/desktop/docs/desktop-keyboard.md)).
283
+
284
+ - **Desktop: on Omarchy, the font is Omarchy's by default.** On a computer
285
+ that runs Omarchy, the window and its terminals use the computer's
286
+ monospace font, the one `omarchy font set` changes (fontconfig's
287
+ `monospace`), and the terminal's default size is 13px (JetBrains Mono,
288
+ Omarchy's default face, at 13px; 15px elsewhere). In Omarchy's font,
289
+ instance names in the sidebar and on tabs are 12px, a little smaller than
290
+ System font's 12.5px. Everywhere else the
291
+ default stays **System font**, the previous faces; **Omarchy's font** can be
292
+ chosen there too (on Windows the system's monospace font; on macOS JetBrains
293
+ Mono, with the terminals keeping Inconsolata). A chosen font or terminal size
294
+ always wins. A terminal font family set with **Terminal: set font
295
+ family…** still wins. Where the computer's monospace font does not draw at
296
+ a fixed width (none installed, or a bitmap font), Omarchy's font shows
297
+ System font's faces and its row in the picker says so.
298
+
299
+ - **Desktop: the sidebar's rows sit closer to the window's left edge.** The
300
+ workspace and instance rows, their headings and the foot's OATS mark all
301
+ move 4px left and stay in one column. The right side is unchanged.
302
+
303
+ - **Desktop: switching back to a workspace puts the keyboard back where you
304
+ left it.** The terminal you were typing in has the focus again, ready to
305
+ type, with no click; so does the instance's row in the list of instances
306
+ (once the list is read), the tab, or the page's control. Picking a workspace
307
+ from the list of workspaces, a move (Alt+↑ / ↓, ⌥↑ / ↓, the leader's
308
+ ↑ / ↓) and a window falling back after another window took its workspace
309
+ over all do it. A move made from the list of workspaces leaves the focus on
310
+ the list. A tab that closed meanwhile gives the focus to the tab active in
311
+ its place, or to the page
312
+ ([desktop.md](../desktop.md#one-window-per-workspace)).
313
+
314
+ - **Desktop: the workspace moves wrap around.** Alt+↓ (⌥↓ on macOS, the
315
+ leader's ↓) on the last workspace of the list shows the first, and Alt+↑
316
+ on the first shows the last, instead of saying "No workspace below this
317
+ one." / "No workspace above this one." With only one workspace to show,
318
+ nothing moves and one line says "No other workspace to show." The TUI's
319
+ moves wrap too
320
+ ([desktop.md](../desktop.md#workspaces)).
321
+
322
+ - **`oats-getting-started` sets up a machine's steward with a global
323
+ address** when its prompt hands it a machine found-list (a found-list with
324
+ `machine.platform` set, as oats-omarchy's installer writes):
325
+ - Step 1 is the machine's own round. It asks once, with a default for
326
+ every value: the workspace and the namespace (both the machine's
327
+ hostname, normalised), the steward's name (`steward`), the deployment
328
+ directory, and the harness when the found-list names none. Enter
329
+ accepts them all. No question comes after that round: a step that would
330
+ ask tells the person what happened and stops.
331
+ - The person's harness is recorded as the steward's launch preference
332
+ (`oats soul launch set`), so harness trust, readiness and the spawn all
333
+ use it.
334
+ - The new workspace is the machine's own. It pins `oats.machine`, and its
335
+ setup soul is `oats.machine/steward`; no `<workspace>-oats-setup-expert`
336
+ soul is written.
337
+ - Once messaging is set up, the agent creates the steward's resident with
338
+ `oats aweb resident create <name> --team-label <label>`: first with
339
+ `--plan`, then for real. It runs with no `AWEB_API_KEY`, using the team
340
+ root that signup made. The agent then spawns the steward with the grant-seat
341
+ options the provider prints. The steward's address is contacts-only:
342
+ `<namespace>/<name>`.
343
+ - With oats.aweb below 1.33.0, aw below 1.36.48, a machine that joined an
344
+ existing workspace by invite, or a plan that does not take the root route,
345
+ the steward gets a local team identity instead. The person is told so in
346
+ one line, with no question asked. oats.aweb 1.33.0 is not released yet,
347
+ so for now every steward gets the local team identity.
348
+
349
+ - **TUI: the workspace moves wrap around, as the Desktop's do.** The
350
+ leader then `Down` (or `Alt+Down` in the Alt family and on macOS) on the
351
+ last workspace of the list of workspaces opens the
352
+ first, and the leader then `Up` on the first opens the last, instead of
353
+ saying "No workspace below this one." / "No workspace above this one."
354
+ With only one workspace to open, nothing moves and one line says "No
355
+ other workspace to show." The list's own `Up` and `Down`, while it has
356
+ the focus, still stop at its ends
357
+ ([tui.md](../tui.md#the-list-of-workspaces)).
358
+
359
+ - **Desktop: the sidebar's instance rows have no ⋯ button.** Their actions
360
+ (Open in split, Open pull request…, Knowledge & capabilities…, Start…,
361
+ Restart with…, Stop…, Retire instance…, and Forget… for an instance its
362
+ server no longer lists) are in the row's context menu (right-click,
363
+ Shift+F10 or the ContextMenu key), as a workspace row's are. A right-click
364
+ never opens the row's terminal. While the menu can't be used (the roster is
365
+ out of date, one of its actions is still running, or the row can't be used
366
+ from this computer), it opens nothing and says why in the line at the
367
+ bottom of the main area
368
+ ([desktop.md](../desktop.md#the-sidebars-instance-tree),
369
+ [desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
370
+
371
+ - OATS Desktop runs with the desktop session's environment, not your shell's.
372
+ A `fromEnv` variable exported only in a shell profile is not set there, so
373
+ the Desktop's sweep refuses that instance (`E_LAUNCH_ENV_MISSING`) while
374
+ `oats tui` run from that shell resumes it. Put the variable in the session's
375
+ environment, or use a literal in the launch configuration (#1559).
376
+ - A command you typed into an instance's window is not resumed. A resume runs
377
+ the instance's OATS launch, with the launch configuration, model and yolo its
378
+ last start chose. Put a custom command in a launch configuration (#1559).
379
+
380
+ - A start opens a fresh conversation on `TASK.md`, **except a resume**, which
381
+ continues the instance's own last conversation. This replaces the rule that
382
+ every start opened a new one.
383
+ - The window a spawn makes now records how its harness ended, as a start's
384
+ window does, and a spawn records its launch's `startId`; `oats instance
385
+ stop` records the start it ended, and records a stop of an instance that
386
+ already reads `lost` too, signalling nothing. These files are
387
+ kernel-private: read `sessionEnd`. Stop an instance with OATS to keep it stopped: a tmux window
388
+ killed by hand reads as lost and comes back.
389
+
390
+ ## Fixed
391
+
392
+ - **An instance whose window has another pane is no longer unreachable**
393
+ ([#1569](https://github.com/awebai/oats/issues/1569)). A split window, such
394
+ as oats.setup's no-echo prompt opens beside the agent, made status read the
395
+ instance `unreachable` and session inspect, input, wakes, attach, stop and
396
+ restart refuse it. Status and every session command now act on the agent's
397
+ pane alone, and the other panes never make the instance unknown. See
398
+ [which pane is the agent's](../execution-targets.md#which-pane-is-the-agents).
399
+ - **The mark.** OATS sets the tmux pane option `@oats-agent`, its value the
400
+ instance name, on the agent's pane whenever it creates or respawns it: a
401
+ spawn's window, a start's or restart's new window, and a restart in place.
402
+ A mark that cannot be set does not fail the launch. It is internal, not an
403
+ interface.
404
+ - **The rule.** In a window with one pane, that pane is the agent's. With
405
+ several, the pane marked with the instance's name; when none is, the
406
+ unmarked pane with the lowest pane id (the window's own pane comes before
407
+ any split of it). A pane marked with another instance's name is never the
408
+ agent's. A window launched before this release has no mark and resolves
409
+ to its lowest pane id until the next start or restart marks it.
410
+ - Wakes and `oats session input` paste into the agent's pane even when the
411
+ person's focus is in another pane. Stop signals only the processes under
412
+ the agent's pane, and a restart in place respawns that pane alone. No JSON
413
+ field or state name changed.
414
+ - **The viewer** (`oats session attach`, the Desktop and the TUI) still
415
+ shows the whole window, every pane. In a window with more than one pane it
416
+ selects the agent's pane before its client attaches, so typing goes to
417
+ the agent. The viewer has no key or click that moves to another pane.
418
+ - **When OATS cannot tell** (two panes marked with the instance's name, or
419
+ several panes and none unmarked or marked with it), status reads
420
+ `running: null`, `runtimeState: "unreachable"`, and the sentence that
421
+ names the panes and how to close them is the `runtimeError`; session
422
+ inspect, input, attach, stop and restart refuse with the same sentence.
423
+ - **oats.setup route 2 guidance.** The no-echo prompt's instructions no
424
+ longer say that the window is refused while the prompt is open: wakes and
425
+ input keep reaching the agent, and a viewer opened after the prompt
426
+ selects the agent's pane, so the agent closes the prompt and opens it
427
+ again while the person watches. It
428
+ reaches deployments with the next oats.framework release.
429
+ - **Known limit.** A development-channel Claude started or restarted in
430
+ place on a split window comes back with its launch prompt `blocked`,
431
+ Claude waiting at its development-channel prompt: the confirmation still
432
+ requires the agent's window to have one pane. Close the other pane before
433
+ the restart
434
+ ([the development-channel confirmation](../configuration.md#the-development-channel-confirmation)).
435
+
436
+ - **Desktop and TUI: an agent whose window has a second pane can be opened
437
+ again** ([#1569](https://github.com/awebai/oats/issues/1569)). A window
438
+ with more than one pane read as unknown, "Instance window has multiple
439
+ panes; check its terminal before starting", and its row had no Open. So
440
+ you couldn't reach the extra pane to close it. OATS's own setup splits one
441
+ off for a no-echo prompt, such as an API key or an invite token.
442
+ - Desktop's and TUI's own terminal check now read the agent's pane as
443
+ the kernel does. That's the pane OATS marks as the agent's; for a
444
+ window from before the mark, the window's own first pane. The other
445
+ panes never make the agent unknown. When it can't tell (two panes marked
446
+ as the agent's, or none that can be), the row stays unknown and says
447
+ which panes, with the kernel's sentence.
448
+ - Desktop: a terminal opened on such a window starts on the agent's pane,
449
+ wherever the focus was, so typing goes to the agent and never into a
450
+ forgotten prompt. In the TUI, and in Desktop for another machine, the
451
+ kernel's viewer does the same. A click doesn't select a pane in these
452
+ terminals, so a terminal opened after the split can't reach the prompt:
453
+ the agent closes the prompt and opens it again while you watch.
454
+ - Desktop: a pull request's **Send N threads to <instance>** pastes into
455
+ the agent's pane, as the kernel names it, never the window's active pane. When the kernel can't
456
+ tell which pane is the agent's, nothing is pasted.
457
+
458
+ - **Desktop: a waiting instance's row says why, in words.** A message of
459
+ only spaces showed as a blank line; it now reads as no message, so the
460
+ row, the tab's tooltip and the sidebar's card give the reason in words.
461
+ An instance waiting for a reason Desktop doesn't know read "Needs input"
462
+ twice in its terminal's row, its tab's tooltip and an unavailable sidebar
463
+ row's tooltip; they now say it once
464
+ ([desktop.md](../desktop.md#when-an-agent-waits-on-you)).
465
+
466
+ - **A question to the person is no longer hidden by a later claim with no
467
+ text** ([#1502](https://github.com/awebai/oats/issues/1502)). On a new
468
+ user's machine the steward's yes/no question sat unseen for 2.5 days: a
469
+ later `oats.core` permission claim with `message: null` replaced it in
470
+ `waitingOnYou`.
471
+ - `waitingOnYou` in `oats status`, `oats session inspect` and
472
+ `oats instance events` now shows the newest claim that has a message. A
473
+ text-less claim only fills in the reason when the shown claim has none.
474
+ With no message anywhere, the newest claim is shown, as before.
475
+ - **oats.core 2.8.0: Claude Code's waiting claims carry the prompt's
476
+ text.** An `AskUserQuestion` gives the question's own words. A permission
477
+ prompt gives Claude's "Claude needs your permission to use <tool>". See
478
+ [the Claude Code emitter](../capabilities.md). It reaches deployments
479
+ with the next oats.framework release.
480
+
481
+ - **Add a machine (`oats server connect`) finds an OATS and npm that only the
482
+ host's login files put on PATH**
483
+ ([#1517](https://github.com/awebai/oats/issues/1517)). Without `--path`, connect
484
+ asks the host user's own login shell (bash, zsh or fish, run `-l -i`) for its
485
+ PATH once. It records that PATH as the registration's `path`, and the oats it
486
+ finds there as `oatsPath`, so installing, onboarding, readiness and every later
487
+ `--server` command use the same environment. When the shell cannot be read,
488
+ the `ssh` step's detail says why and connect uses ssh's own PATH. When even the
489
+ login shell has no npm, the remedy names the PATH it searched and a command
490
+ that checks it on the host, and you act on it by checking again, in Desktop
491
+ too. An explicit `--path` is used as given. A machine registered before keeps
492
+ its `path` and `oatsPath`; connect fills in only the ones it lacks.
493
+
494
+ - **`oats instance upgrade` moves a home whose oats.framework changes**
495
+ ([#1549](https://github.com/awebai/oats/issues/1549)). oats.core has spawn
496
+ and launch hooks but declared no `upgrade` hook, so the upgrade refused every
497
+ home that carries it ("oats.core does not declare an upgrade hook; respawn
498
+ the instance to change it").
499
+ - **oats.core 2.8.0 declares a non-required `upgrade` hook.** The hook that
500
+ runs is the destination's, so homes spawned on any earlier oats.core are
501
+ covered, including framework 1.4.1, 1.8.0 and 1.14.1 homes.
502
+ - `plan` adopts when the home records no oats.core metadata (no oats.core
503
+ ever wrote any), `{}`, or a falsy value (`null`, `false`, `0`, `""`),
504
+ which the kernel passes as `{}`. Any other recorded value is refused with
505
+ the remedy `respawn the instance: oats retire <instance>, then oats spawn`.
506
+ - `apply` carries the empty metadata unchanged. Neither phase reads the home
507
+ or calls the host. The next start's launch hook rewrites the Claude Code
508
+ waiting hooks for the moved module copy.
509
+ - **oats.core's kernel floor rises from 0.40.0 to 0.49.0.** A kernel before
510
+ 0.49.0 drops a capability that declares a hook event it does not know, so
511
+ it would lose oats.core on every soul. From 0.49.0 the kernel ignores the
512
+ hook; only OATS 0.68.0 and later (`oats instance upgrade`) run it.
513
+ - Known effect: after the move, the record holds
514
+ `capabilityMeta["oats.core"]: {}`, as oats.aweb-tasks' adoption leaves it.
515
+ - See [oats.core across `oats instance upgrade`](../capabilities.md#oatscore-needs-input).
516
+ It reaches deployments with the next oats.framework release.
517
+
518
+ - **An instance with a file over 2 GiB in its work retires**
519
+ ([#617](https://github.com/awebai/oats/issues/617)). The retire refused such
520
+ an instance before doing anything, with `E_WORK_INSPECTION_FAILED: ... File
521
+ size (...) is greater than 2 GiB`. A Git clone with a large pack in a
522
+ directory instance's `work/` was enough. The retire's digests now read
523
+ every file in pieces of 1 MiB, and so does the verification of its recovery
524
+ copy. A home's `instance.json`, whose stored digest leaves out the fields
525
+ the kernel writes after spawn, is read whole up to 16 MiB; a larger one is
526
+ hashed as it is. Otherwise a digest is the same as before for the same
527
+ bytes, so spawn baselines stay valid. A file that shrinks while the retire
528
+ reads it refuses the retire with `E_WORK_INSPECTION_FAILED`, `<path>
529
+ changed while it was read`. Retry once nothing writes to it. See
530
+ [souls-and-instances.md](../souls-and-instances.md).
531
+
532
+ - **Desktop on Linux: a right-click on a workspace in the sidebar's list opens
533
+ its menu (Open in new window) and keeps it open.** It used to close as soon
534
+ as the mouse button came up. Shift+F10 and the ContextMenu key were not
535
+ affected.
536
+
537
+ - **Desktop: Instance: name and colour… from the command palette keeps your
538
+ place when there is no instance to act on.** It says "No instance is focused
539
+ or selected." and the focus goes back where it was before the palette
540
+ opened; it used to be lost.
541
+
542
+ ## Provider updates
543
+
544
+ - **oats.aweb 1.32.0: stopped seats upgrade in place, and joined teams mint
545
+ only from a member root.** The catalog and this workspace pin
546
+ `oats.aweb: v1.32.0`. It requires OATS >=0.68.0; the aw floor is unchanged.
547
+ - **`oats instance upgrade` moves a stopped seat** (local, global grant or
548
+ retained, including 1.17.1 metadata) to the locked package. Plan is
549
+ read-only. Apply keeps the identity and grant, and makes no host
550
+ registration or `aw` call. The next start re-registers the home and, where
551
+ configured, renews the grant before revoking the old one. That ends the
552
+ lost wakes after an upgrade or a restart: a grant seat's new grant home is
553
+ registered first, and a local Codex seat recorded under `delivery: channel`
554
+ registers `<home>/.aw` as a session home. `oats.aweb-tasks` adopts with it.
555
+ - **A team other than the default** is joined at spawn, and its roster read,
556
+ only from `roots[team]` or `root`, and only when `aw team list --json`
557
+ there lists the team. The cwd, `OATS_WORKSPACE` and the home's own `.aw`
558
+ never mint for it. A missing or non-member root refuses, naming the team,
559
+ the root tried and the remedy (`oats aweb setup --join <label>
560
+ --invite-stdin`, then a respawn). `oats aweb join --labels L --plan`
561
+ shows the root a join would use, without inviting.
562
+ - **Claude channel:** a start clears a cached aweb-channel failure, which
563
+ made every Claude started in the next 15 minutes skip the channel, and
564
+ readiness reads Claude's MCP log to prove a home registered on the channel
565
+ (`channel-not-connected`, with the restart remedy).
566
+ - **Upgrade:** every host sharing the workspace runs OATS >=0.68.0 first.
567
+ Then `oats sync` locks it; new spawns get it, or a stopped home moved with
568
+ `oats instance upgrade`.
569
+
570
+ - **oats.engineering 1.14.0: maintainers per human, and shorter instructions.**
571
+ The catalog and this workspace now pin 1.15.0, which carries it (below);
572
+ the floor is unchanged.
573
+ - **What a lane is.** A lane is a standing area of work: areas of the
574
+ repository, a kind of work, or one human's requests. Work that would be
575
+ finished when one goal lands is an effort in an existing lane. Any
576
+ maintainer opens a lane with nobody's sign-off.
577
+ - **One maintainer per human in each project lane.** The release lane stays
578
+ one maintainer for the whole project, with the final say on merges and
579
+ releases. A lane's maintainer owns its lane: it doesn't report to the
580
+ maintainer that spawned it. By default a lane merges its own PRs once the
581
+ release lane has signed off at that head.
582
+ - **The lane map shows who holds each seat and what each maintainer is
583
+ on.** Each maintainer keeps an entry of its own on it. Your messaging
584
+ layer's presence says which maintainers are running.
585
+ - **Experts find their maintainer.** An expert that no maintainer launched
586
+ finds its human's maintainer in its lane. If there is none, it spawns
587
+ one.
588
+ - **Shorter injects.** The maintainer, expert and developer injects open
589
+ with a short block of IMPORTANT, ALWAYS and NEVER rules, and run about
590
+ half as long. The skills are about a fifth shorter, and no rule was
591
+ dropped.
592
+ - **Upgrade:**
593
+ - `oats sync` locks it. New spawns get it, and a stopped home moves to it
594
+ with `oats instance upgrade`.
595
+ - Maintainers add their entry to the lane map at their next intake.
596
+
597
+ - **oats.engineering 1.15.0: maintainers trust what experts relay from their
598
+ human.** The catalog and this workspace pin `oats.engineering: v1.15.0`,
599
+ which carries 1.14.0 (above); the floor is unchanged.
600
+ - **A decision is trusted.** When an expert reports a decision it made
601
+ with its own human, the maintainer takes it as that human's decision
602
+ without asking them again. That covers an architecture, a design, a
603
+ scope or a product call, and the same holds for a peer maintainer
604
+ relaying its own human. The maintainer still gates it on soundness, the
605
+ roadmap, the product direction and the architecture.
606
+ - **A relay says "Decided with <human>: <decision>"** and where it is
607
+ recorded. Anything else is a proposal.
608
+ - **Authority is still confirmed with the human directly.** That covers a
609
+ merge without its second reader, a hold or freeze exception, a tag or
610
+ publication, a deploy, a destructive or outward-facing act, and marking
611
+ another maintainer `left`.
612
+ - **Upgrade:** `oats sync` locks it. New spawns get it, and a stopped home
613
+ moves to it with `oats instance upgrade`. Experts relay their human's
614
+ decisions in the "Decided with" form.
615
+
616
+ - **oats.framework 1.15.0: oats.core 2.8.0.** oats.core's floor
617
+ (`compatibility.oats`) rises from 0.40.0 to 0.49.0. The other three
618
+ capabilities are unchanged.
619
+ - **`oats instance upgrade` moves a home's oats.framework.** oats.core
620
+ declares a non-required `upgrade` hook
621
+ ([#1549](https://github.com/awebai/oats/issues/1549)), so a
622
+ stopped home is upgraded in place instead of refused with "respawn". A
623
+ kernel before 0.49.0 would drop a capability that declares a hook event it
624
+ does not know, so oats.core now refuses such a kernel with the kernel's own
625
+ compatibility message. Only OATS 0.68.0 and later run the hook.
626
+ - **A waiting question carries its text**
627
+ ([#1502](https://github.com/awebai/oats/issues/1502)). oats.core's Claude Code
628
+ emitter puts the prompt's own words on its needs-input claim: the
629
+ question, or Claude's "needs your permission to use <tool>". A claim with
630
+ text is shown over one without. `/oats-operate` says so, from oats.core
631
+ 2.8.0.
632
+ - **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
633
+ `oats.framework: v1.15.0`. New spawns get it; a stopped home moves with
634
+ `oats instance upgrade`, from OATS 0.68.0. Every host that shares the
635
+ workspace runs OATS 0.49.0 or later first.
636
+
637
+ - **oats.framework 1.15.1: oats.setup 2.9.2.** oats.setup's inject follows
638
+ the split-window fix (#1569). While an instance's no-echo prompt pane is
639
+ open, OATS 0.69.0 and later keep reaching the instance's own pane, so wakes
640
+ and `oats session input` still arrive, and status reads it as before. The
641
+ inject names that version and says what an earlier OATS does instead. The
642
+ floors are unchanged, and the other three capabilities are unchanged.
643
+ - **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
644
+ `oats.framework: v1.15.1`. New spawns get it, and a stopped home moves with
645
+ `oats instance upgrade`, from OATS 0.68.0.
646
+
647
+ ## Documentation
648
+
649
+ - **A test Desktop or TUI never restarts the operator's agents.** The live-check rule
650
+ (`electron-live-verification`, and the Desktop and kernel developer souls) now gives a test
651
+ Desktop or TUI a private `HOME`, `OATS_HOME_DIR` and `TMUX_TMPDIR`, and runs every command that
652
+ builds or reads its fixture with the same three. The session resume sweep a client runs when it
653
+ opens restarts the lost homes it may resume on this computer's deployments list, which lives
654
+ under `OATS_HOME_DIR`, and the list's first use imports `$HOME/Agents`. With all three private, a
655
+ test client's sweep sees only its own fixture: a home of the operator's that was lost is never
656
+ restarted on the test's private tmux server, out of the operator's sight, and the fixture never
657
+ joins the operator's list. The rule also opens only the fixture deployment, names the CLI by
658
+ absolute path and never runs the sweep, `--plan` included, under the operator's environment.