@awebai/oats 0.69.1 → 0.69.2

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 +79 -15
  2. package/docs/capabilities.md +24 -5
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  5. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  6. package/docs/desktop-cli-api.md +260 -28
  7. package/docs/desktop-instance-start.md +8 -37
  8. package/docs/desktop.md +76 -9
  9. package/docs/execution-targets.md +27 -5
  10. package/docs/implementation.md +6 -5
  11. package/docs/integrations.md +1 -1
  12. package/docs/knowledge.md +25 -16
  13. package/docs/official-catalog.md +3 -3
  14. package/docs/packages.md +12 -12
  15. package/docs/release-notes/v0.69.2.md +259 -0
  16. package/docs/servers.md +7 -2
  17. package/docs/soul.schema.json +1 -0
  18. package/docs/souls-and-instances.md +35 -2
  19. package/docs/tui.md +100 -9
  20. package/docs/upgrading.md +9 -5
  21. package/docs/workspaces.md +2 -2
  22. package/injects/instance-boundary.md +19 -33
  23. package/injects/work-attached.md +8 -13
  24. package/injects/work-checkout.md +16 -30
  25. package/injects/work-directory.md +9 -15
  26. package/injects/work-workspace.md +8 -19
  27. package/injects/work-worktree.md +18 -33
  28. package/lib/capability-contract.mjs +2 -2
  29. package/lib/core.mjs +162 -49
  30. package/lib/instance-background.mjs +54 -0
  31. package/lib/instance-inspect.mjs +3 -0
  32. package/lib/instance-lifecycle.mjs +35 -0
  33. package/lib/instance-resolution.mjs +3 -2
  34. package/lib/instance-same-work.mjs +67 -0
  35. package/lib/instance-upgrade.mjs +18 -0
  36. package/lib/materialize.mjs +23 -2
  37. package/lib/resolve.mjs +32 -5
  38. package/lib/servers.mjs +19 -4
  39. package/lib/session-resume-contract.mjs +1 -0
  40. package/lib/session-resume.mjs +36 -9
  41. package/lib/soul-composition.mjs +13 -10
  42. package/lib/workspace.mjs +3 -2
  43. package/package-catalog.json +2 -2
  44. package/package.json +1 -1
  45. package/packages/client/cli-adapter.mjs +30 -8
  46. package/packages/client/deployment-data.mjs +9 -0
  47. package/packages/client/deployment-panel.mjs +4 -0
  48. package/packages/client/instance-tree.mjs +64 -14
  49. package/packages/client/panel-views.mjs +11 -3
  50. package/packages/client/remote-roster.mjs +5 -1
  51. package/packages/client/roster-sections.mjs +50 -6
  52. package/packages/client/same-work.mjs +49 -0
  53. package/packages/client/session-resume.mjs +1 -1
  54. package/packages/client/soul-rows.mjs +2 -0
  55. package/packages/client/spawn-apply-contract.mjs +2 -1
  56. package/packages/client/spawn-decision.mjs +4 -1
  57. package/packages/client/spawn-preview-contract.mjs +12 -1
  58. package/packages/client/spawn-preview.mjs +2 -0
  59. package/packages/tui/README.md +2 -2
  60. package/packages/tui/lib/client.mjs +6 -2
  61. package/packages/tui/lib/main.mjs +44 -11
  62. package/packages/tui/lib/model.mjs +101 -43
  63. package/packages/tui/lib/store.mjs +76 -20
  64. package/packages/tui/lib/views/frame.mjs +2 -0
  65. package/packages/tui/lib/views/help.mjs +2 -0
  66. package/packages/tui/lib/views/instances.mjs +38 -1
  67. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -0,0 +1,259 @@
1
+ # OATS 0.69.2
2
+
3
+ Unreleased
4
+
5
+ 0.69.2 fixes a retire that a session resume could undo, and adds background
6
+ instances, the same-work flag, the TUI's session resume and a composed
7
+ `AGENTS.md` in the soul's capability order. OATS Desktop and `oats tui` no
8
+ longer say anything about a resume.
9
+
10
+ ## Upgrade
11
+
12
+ - **Install the Desktop first and the CLI second,** as
13
+ [Upgrading](../upgrading.md) says. The 0.69.2 Desktop accepts OATS CLIs
14
+ `>=0.26.0 <0.70.0`, so a 0.69.1 Desktop also works with this CLI.
15
+ - **The retire fix is in the CLI.** With the 0.69.2 CLI installed, a resume
16
+ started by any Desktop, `oats tui` or `oats session resume` no longer brings
17
+ back a home OATS is retiring or stopping (Fixed, below). Until a host has
18
+ it, quit OATS Desktop while you retire a batch of instances.
19
+ - **Package moves:** the official catalog pins oats.framework 1.16.1 and
20
+ oats.okf 5.5.0 (Provider updates, below). A deployment takes them with
21
+ `oats sync`. New spawns use them, and a stopped home moves to them with
22
+ `oats instance upgrade`.
23
+ - **oats.okf 5.5.0 before 5.5.0 sources harvest.** A harvester on oats.okf
24
+ 5.4.0 or older refuses the `, incarnation` suffix 5.5.0 adds to a proposal's
25
+ `Source:` line, so sync each deployment before its instances on 5.5.0 write
26
+ proposals.
27
+ - **A soul's `background: true`** is refused by kernels before 0.69.2: commit
28
+ it only once every deployment of the workspace runs 0.69.2 or later.
29
+ - **Existing homes keep their `AGENTS.md`.** The new composition order and
30
+ the shorter instructions reach new spawns, and a stopped home that
31
+ `oats instance upgrade` moves.
32
+
33
+ ## Added
34
+
35
+ - **TUI: lost sessions are resumed when `oats tui` opens**
36
+ ([#1559](https://github.com/awebai/oats/issues/1559)). After a shutdown, a
37
+ reboot or a crash, `oats tui` asks OATS to resume every instance whose
38
+ session was lost, on every deployment on this computer, without holding up
39
+ its first screen. It asks again whenever a read shows a session lost while
40
+ it is open, at most every 30 seconds. `oats tui` says nothing about a
41
+ resume: the list is read again after each one, so a resumed instance shows
42
+ running. `oats session resume --plan --json` shows what a resume would do,
43
+ and `oats session resume` run by hand says why an instance could not be
44
+ resumed. Quitting while the sessions are being resumed does not cut that
45
+ short. There is no setting: stop an instance with OATS to keep it down.
46
+ `S` and `R` are unchanged and never resume a conversation. See
47
+ [Resuming lost sessions](../tui.md#resuming-lost-sessions).
48
+
49
+ - **An instance can record that it does the same work as its parent**
50
+ (feature `instance-same-work`,
51
+ [#1577](https://github.com/awebai/oats/issues/1577)). Clients draw the
52
+ parent→child line for an instance that carries the flag.
53
+ `oats spawn … --same-work` sets it on the new instance, bound to the
54
+ parent the new home records (a child, a sibling of an anchor with a
55
+ parent, a `--relation parent` over an anchor with a parent, an attached
56
+ spawn); a spawn that would record no parent is refused with `E_BAD_ARGS`
57
+ before anything is created. `oats instance same-work <instance> on|off`
58
+ sets or clears it on an existing instance, addressed as
59
+ `oats instance color` addresses one; `on` needs a recorded parent, and
60
+ the answer is `{instance, sameWork}`. The flag is kept in the home's own
61
+ record, `.oats-same-work.json`, naming the parent it was set against: it
62
+ survives a restart, a stop and a start, a resume and
63
+ `oats instance upgrade`, and only `off` or retirement clears it. It is on
64
+ only while that parent is still the home's recorded `parentInstance`, so
65
+ after a reparent (a retire's lineage splice, a `--relation parent` spawn
66
+ re-pointing its anchor) it reads off until `on` rebinds it.
67
+ `oats status --json` rows and `oats server roster --json` rows carry
68
+ `sameWork: true` while it is on, and no `sameWork` key otherwise. Both the
69
+ flag and the verb are routed with `--server`; a host without the feature
70
+ is refused with `E_REMOTE_INCOMPATIBLE` and nothing is sent
71
+ ([Same work as the parent](../desktop-cli-api.md#same-work-as-the-parent-oats-instance-same-work)).
72
+
73
+ - **Background instances** ([#1579](https://github.com/awebai/oats/issues/1579),
74
+ feature `instance-background`). An instance can be recorded as background,
75
+ so that clients list it under a Background section of its own. Like the
76
+ colour, it is presentation only: a background instance spawns, starts,
77
+ takes input, messages and retires like any other.
78
+ - A soul gives the default with `background: true` in `soul.yaml`. Add it to
79
+ a committed soul only once every deployment that reads it runs this
80
+ release, because earlier kernels refuse the key.
81
+ - `oats spawn … --background` or `--no-background` wins over the soul. The
82
+ preview and the result carry `background` and `backgroundFrom` (`flag` or
83
+ `soul`). A routed spawn sends either flag only to a host that has the
84
+ feature.
85
+ - `oats instance background <instance> on|off` changes it later, locally or
86
+ with `--server`, under the same rules as `oats instance color`.
87
+ - The home keeps it in `.oats-background.json` through restart, stop, resume
88
+ and `oats instance upgrade`. A later edit of the soul moves no existing
89
+ instance, and retire never counts the file as work.
90
+ - `background: true` appears on `oats status --json` rows, remote roster
91
+ rows, `oats inspect --home` and the soul rows of `oats souls --json`. The
92
+ `oats status` text marks a row `[background]`.
93
+
94
+ See
95
+ [Background instances](../desktop-cli-api.md#background-instances-oats-instance-background).
96
+
97
+ - **Desktop and TUI: background instances are listed apart, under one
98
+ closed Background heading** ([#1579](https://github.com/awebai/oats/issues/1579)).
99
+ - An instance whose `background` is on (`oats instance background`, or
100
+ a soul's `background: true` at spawn) leaves the main tree, and so do
101
+ the instances below it. They are listed under a **Background** heading
102
+ at the end of the sidebar's list, with how many there are. The heading
103
+ starts closed in every new Desktop window and TUI session.
104
+ - Inside, the rows form their own tree, with the machine headings of a
105
+ workspace of two or more machines. No line joins the section to the main
106
+ tree.
107
+ - While a background instance waits on you, the heading says **Needs
108
+ input**, open or closed, and the workspace's mark counts it.
109
+ - The command palette still lists every instance. The previous and next
110
+ instance keys pass over a closed section, and opening an instance's tab
111
+ leaves the section as it was.
112
+ - Desktop: the **Spawn** dialog's **Run in background** switch starts
113
+ from the soul's default, and a row's context menu offers **Move to
114
+ background** and **Move out of background**.
115
+ - It needs OATS with the `instance-background` feature, on the server too
116
+ for a server's instance. With an older OATS nothing changes. See
117
+ [Background instances](../desktop.md#background-instances) and
118
+ [the TUI's list](../tui.md#what-it-shows).
119
+
120
+ ## Changed
121
+
122
+ - **Desktop: no notice about resumed sessions**
123
+ ([#1559](https://github.com/awebai/oats/issues/1559)). OATS Desktop still
124
+ asks OATS to resume lost sessions when it opens and when a roster shows one
125
+ lost, exactly as before, but it no longer shows a notice about what was
126
+ resumed, started fresh, left waiting or could not be resumed. A resumed
127
+ instance shows running in the roster. A sweep that fails still writes one
128
+ line with its code to Desktop's log. `oats tui` says nothing about a resume
129
+ either. See
130
+ [When Desktop opens](../desktop-instance-start.md#when-desktop-opens).
131
+
132
+ - **`.oats-same-work` is a kernel-owned home name**: a capability's
133
+ `retirement.disposable.home` cannot declare it
134
+ ([capabilities.md](../capabilities.md)).
135
+
136
+ - **Desktop and TUI: a parent's line joins only the children that do its
137
+ work.** With an OATS that has the `instance-same-work` feature, the
138
+ Desktop's sidebar and command palette draw a parent's line only to a child
139
+ flagged as doing the same work (`sameWork: true`), and list those children
140
+ first under their parent; the TUI, which draws no lines, lists them first
141
+ too. The tree keeps its rows, indent and groups. So once the clients read the
142
+ feature, the lines go away until flags are set: experts with live developers
143
+ set them with the CLI, `oats instance same-work <instance> on`. Nothing is
144
+ migrated automatically. A host without the feature keeps today's lines
145
+ ([desktop.md](../desktop.md#the-sidebars-instance-tree),
146
+ [tui.md](../tui.md#what-it-shows)).
147
+
148
+ - **A composed `AGENTS.md` puts the capabilities in the soul's order, and the
149
+ kernel's blocks last.** It is the soul's own `AGENTS.md`, then the inject
150
+ of each capability the soul lists, in its `capabilities:` order, then the
151
+ workspace defaults the soul does not list, in the order the workspace's
152
+ `defaults:` lists them, then the instance-boundary and work-mode blocks.
153
+ Before, the kernel's blocks came right after the soul's body and the
154
+ injects followed in capability-name order. A soul entry that re-lists a
155
+ workspace default sits at the soul's place; a standalone soul's kernel
156
+ default, `oats.core`, follows the capabilities it lists. A capability
157
+ name made only of digits comes first in its list. Spawn, `instance.json`
158
+ `instructions` and `composition.expected`, `oats inspect --soul
159
+ --instructions` and `oats doctor --soul` all list the blocks in the new
160
+ order; no JSON shape changes. Modules, skills and hooks keep their name
161
+ order, and the resolution's revisions do not move, so no instance reports
162
+ drift. An existing home keeps the `AGENTS.md` it has; `oats instance
163
+ upgrade` recomposes it in the capability order it recorded, with the
164
+ kernel's blocks last
165
+ ([capabilities.md](../capabilities.md#what-an-instance-receives)).
166
+
167
+ - **Shorter always-loaded instructions.** The kernel's instance-boundary and
168
+ work-mode blocks are about half their former size. The oats.core "You run
169
+ on OATS" block is shorter too, despite the new rule below. They keep
170
+ their behaviour rules, the pinned home/work boundary sentences among them,
171
+ in emphatic form, and name which skill to load and when for the detail
172
+ (`/oats-operate`, `/oats-souls`, `/oats-token-saving`). The instance-boundary
173
+ block opens with "ALWAYS FOLLOW THESE INSTRUCTIONS FOR WORKING". The
174
+ extra-trees commands are unchanged. Existing instances keep the AGENTS.md
175
+ they were spawned with; new spawns get the new text.
176
+ - **oats.core: needs-input through the parent.** When a human talks to an
177
+ instance's parent rather than to the instance, the instance sends its
178
+ question to the parent, which sets its own needs-input claim naming the
179
+ child and relays the answer ([capabilities.md](../capabilities.md)).
180
+ - **oats.core: an instance acts on other instances or the deployment also
181
+ when its soul's capabilities say so,** besides its task or its human
182
+ (`/oats-operate`, and the "You run on OATS" block).
183
+
184
+ ## Fixed
185
+
186
+ - **The sweep could bring back a home that was being retired**
187
+ ([#1559](https://github.com/awebai/oats/issues/1559)). A retire ended its
188
+ instance's session without recording the stop, so for a moment the home read
189
+ as lost, and a sweep that ran then (OATS Desktop or `oats tui` opening, or
190
+ `oats session resume`) started it again in the home that the retire then
191
+ removed. Now a home OATS is stopping, upgrading or retiring, or whose retire
192
+ did not finish, is never resumed:
193
+ - `oats session start --resume` holds the home's lifecycle claim for the whole
194
+ start, as a retire, a stop and an upgrade do. Beside a retire it answers
195
+ `E_INSTANCE_RETIRING`; beside a stop, an upgrade or another resume it
196
+ answers `E_LIFECYCLE_BUSY`. A retire, stop or upgrade that meets a resume
197
+ answers `E_LIFECYCLE_BUSY`, and the claim names `action: "resume"`.
198
+ - The sweep reports such a home `skipped`, with the new reason
199
+ `lifecycle-busy`, and starts nothing. What OATS was doing decides what the
200
+ home is next, and a later sweep reads it again.
201
+ - A retire records the stop before it ends the window. A home it was retiring
202
+ reads `stopped`, never `lost`, also when the retire fails afterwards. The
203
+ exception is a stop record that cannot be written (a full disk) followed by
204
+ a retire that fails as well: that home reads `lost`, as before 0.69.2.
205
+
206
+ The new reason and the new `action` value are additive. A client that does
207
+ not know them treats the row as skipped and the claim as busy. See
208
+ [Resume after a shutdown](../execution-targets.md#resume-after-a-shutdown).
209
+
210
+ - **Desktop: the terminal font size belongs to its face**
211
+ ([#1571](https://github.com/awebai/oats/issues/1571)). Omarchy's font in the
212
+ terminals used a size chosen for Inconsolata, which in the wider face is a
213
+ fifth larger. Each face now keeps its own size and default: Omarchy's font
214
+ 13px, Inconsolata (System font, macOS, and Omarchy's font where it shows
215
+ System font's faces) 15px, on every computer. A size stored before keeps
216
+ applying to Inconsolata; Omarchy's font starts at its default. Changing the
217
+ size (⌘= / ⌘-, the palette, Settings → Terminal) or resetting it (⌘0,
218
+ **Terminal: reset typography**, Settings' **Reset to default**) changes the
219
+ face in use only. A font change gives open terminals that face's size in
220
+ place, and Settings shows its default (**Theme and font**, under
221
+ [Workspaces](../desktop.md#workspaces)).
222
+
223
+ ## Provider updates
224
+
225
+ - **oats.framework 1.16.1: oats.core 2.9.0 and oats.setup 2.9.3.** oats.core
226
+ carries three changes:
227
+ - its shorter "You run on OATS" inject (#1580);
228
+ - the needs-input rule for a child whose human talks to its parent: the
229
+ child asks its parent, which sets its own claim naming the child and
230
+ relays the answer (#1580);
231
+ - the skill lines for background instances (#1579). `oats-operate` shows
232
+ `oats spawn … --background`, and `oats-souls` shows a soul's
233
+ `background: true`. Both name OATS 0.69.2, the release that adds them,
234
+ and say an earlier kernel refuses the key and the flags.
235
+
236
+ oats.setup's `/oats-onboarding` pins `oats.okf: v5.5.0` in its knowledge
237
+ section (text only). 1.16.0 carried the oats.core changes alone; 1.16.1
238
+ adds the onboarding pin. The floors are unchanged, and the other
239
+ capabilities are unchanged.
240
+ - **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
241
+ `oats.framework: v1.16.1`. New spawns get it, and a stopped home moves with
242
+ `oats instance upgrade`, from OATS 0.68.0.
243
+ - **oats.okf 5.5.0: proposals name the source's incarnation; a shorter
244
+ inject.** The catalog and this workspace pin `oats.okf: v5.5.0`, from
245
+ 5.3.0 (floor unchanged, OATS >=0.49.0). It carries 5.4.0 too.
246
+ - 5.4.0: `oats instance upgrade` (OATS 0.68.0 and later) can move a stopped
247
+ 5.x home (oats-okf#106). A home spawned under 4.x is refused, with the
248
+ remedy to retire and respawn it.
249
+ - A proposal's `Source:` line ends `, incarnation <createdAt>`, copied from
250
+ the source's `instance.json`, so a live source whose name was used
251
+ before can harvest (oats-okf#111). A line without it still works for an
252
+ unambiguous source.
253
+ - The always-loaded inject is shorter; it loads the consultation and
254
+ instance-knowledge skills at task start and after compaction. An
255
+ instance runs its final checkpoint before it reports its work done, and
256
+ says in the report whether a harvest still waits (oats-okf#112).
257
+ - **Upgrade:** a harvester on 5.4.0 or older refuses the new `Source:` line.
258
+ Run `oats sync` to 5.5.0 before instances on 5.5.0 write proposals: the
259
+ harvester is spawned from the lock.
package/docs/servers.md CHANGED
@@ -266,7 +266,7 @@ sent as text or on stdin, never as paths.
266
266
 
267
267
  | Command | Where it runs | The server must advertise |
268
268
  |---|---|---|
269
- | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-preview-2` for `--preview`; `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply |
269
+ | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-preview-2` for `--preview`; `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-same-work` for `--same-work` |
270
270
  | `status` | registered workspace | |
271
271
  | `retire` | the instance's home | `retire-home` to retire by exact home |
272
272
  | `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key`; `session-attach-no-status-line` for `attach --no-status-line`, which a host without it ignores |
@@ -281,6 +281,8 @@ sent as text or on stdin, never as paths.
281
281
  | `instance git`, `instance diff` | the instance's home; the Git runs there | `instance-git` (`instanceGitApi: 1`) |
282
282
  | `instance stop --plan\|--apply`, `retire --plan`, `retire --plan-revision … --idempotency-key …` | the instance's home | `lifecycle-plans` (`lifecycleApi: 1`) |
283
283
  | `instance color` | the instance's home | `instance-color` |
284
+ | `instance background` | the instance's home | `instance-background` |
285
+ | `instance same-work` | the instance's home | `instance-same-work` |
284
286
 
285
287
  `instance suggest-name` and `instance upgrade` are never routed: `--server` is
286
288
  `E_BAD_ARGS`. `instance suggest-name` names a spawn on the machine that asks,
@@ -405,7 +407,10 @@ carries `waitingOnYou` (needs input) when the host's kernel reports it, and
405
407
  only then: an older host's row has no such key. `retire` (0.59.0, a retire
406
408
  of the home running, unknown, failed or interrupted) is relayed the same
407
409
  way, through the kernel's own read of it, and a value that read refuses is
408
- dropped ([`retire`](desktop-cli-api.md#row-retire)). A removed or edited registration keeps
410
+ dropped ([`retire`](desktop-cli-api.md#row-retire)). `sameWork` (feature
411
+ `instance-same-work`, the instance does the same work as its parent) is
412
+ relayed only when the host's row has `sameWork: true`, and is absent
413
+ otherwise ([`sameWork`](desktop-cli-api.md#row-same-work)). A removed or edited registration keeps
409
414
  its group from the saved routes. State is pulled on every call, from every
410
415
  group at once: each probe has its own deadline, `--per-target` (default 20 s)
411
416
  capped by `--budget` (default 45 s, the deadline of the whole answer), and a
@@ -8,6 +8,7 @@
8
8
  "additionalProperties": false,
9
9
  "properties": {
10
10
  "launch": { "description": "The soul's launch preference (0.30; feature launch-preference): what the role should run on. Only harness and model: args, env, yolo and the executable stay host facts (launch configurations). A machine overrides it in oats-local.yaml souls.launch; explicit flags win over both. A committed soul gains it only when every deployment runs 0.30 (0.29 refuses the key).", "type": "object", "additionalProperties": false, "required": ["harness"], "properties": { "harness": { "enum": ["pi", "claude", "codex"], "description": "The harness the role should run on." }, "model": { "type": "string", "minLength": 1, "pattern": "^[^\\s-][^\\s]*$", "description": "A model id for that harness; absent: the harness's own model." } } },
11
+ "background": { "type": "boolean", "description": "The role's default placement (feature instance-background, awebai/oats#1579): true lists a new instance of this soul under the clients' Background section. Presentation only, never identity or policy; absent means false. A spawn's --background / --no-background wins; the value is recorded in the home at spawn (`.oats-background.json`), so a later edit of the soul does not move an existing instance (`oats instance background` does). A committed soul gains it only when every deployment reading it runs the release that adds it (earlier kernels refuse the key)." },
11
12
  "schemaVersion": { "const": 2 },
12
13
  "name": { "$ref": "#/$defs/slug" },
13
14
  "description": { "type": "string" },
@@ -73,6 +73,7 @@ compatibility: # optional floors on PACKAGE versions:
73
73
  oats.okf: ">=4.0"
74
74
 
75
75
  launch: { harness: claude, model: claude-opus-5-5 } # optional (0.30): what the role should run on
76
+ background: true # optional: list new instances under the clients' Background section
76
77
  ```
77
78
 
78
79
  | Key | Meaning |
@@ -82,6 +83,7 @@ launch: { harness: claude, model: claude-opus-5-5 } # optional (0.30): what th
82
83
  | `knowledge` / `messaging` / `tasks` | The slot's provider payload (true of every instance of the soul), or `none`. Merged with `oats-local.yaml` `settings.<cap>` and `spawn --provider <cap>`; the provider refuses keys its manifest does not declare. For `oats.okf`, what the soul owns and reads lives in `souls/<name>/okf.json`. |
83
84
  | `compatibility` | `<cap>: <semver range>` checked against the locked package version (`E_COMPATIBILITY`). |
84
85
  | `launch` | Optional (0.30): `{ harness: pi \| claude \| codex, model? }`, the role's launch preference. Only a harness and a model: args, env, yolo and the executable stay host facts. Each machine may override it (`oats-local.yaml` `souls.launch`), and spawn flags win over both ([launch preferences](configuration.md#launch-preferences)). Add it to a committed soul only once every deployment runs 0.30. |
86
+ | `background` | Optional `true \| false` (default `false`, feature `instance-background`): the role's default placement. `true` lists a new instance under the clients' Background section; presentation only, never identity or policy. `spawn --background` / `--no-background` win, the value is recorded in the home at spawn, and `oats instance background <instance> on\|off` changes it later ([Background instances](desktop-cli-api.md#background-instances-oats-instance-background)). Add it to a committed soul only once every deployment reading it runs the release that adds it: an earlier kernel refuses the key. |
85
87
 
86
88
  Schema: [`soul.schema.json`](soul.schema.json). Which teams a soul joins is the
87
89
  deployment's choice (`oats-local.yaml`, [workspaces.md](workspaces.md#teams)),
@@ -127,7 +129,7 @@ full copy** of every capability the soul resolved to:
127
129
 
128
130
  ```text
129
131
  <agents-root>/<soul>/instances/<instance>/
130
- AGENTS.md # generated: soul AGENTS.md + kernel/work-mode blocks + each module's inject
132
+ AGENTS.md # generated: soul AGENTS.md + each module's inject + kernel/work-mode blocks
131
133
  CLAUDE.md → AGENTS.md
132
134
  .agents/skills/ # canonical skill tree, flat: the soul's skills and every module's, full copies
133
135
  <skill>/SKILL.md # one level deep, where every harness discovers skills
@@ -341,6 +343,12 @@ so that user's name stays numbered (`harness-failed`). The preview then answers
341
343
  only; any other harness, and any failure of the call, leaves the name numbered
342
344
  and says why
343
345
  ([The suggested name](desktop-cli-api.md#the-suggested-name-feature-spawn-suggest-name)).
346
+ `--background` or `--no-background` says whether the clients list the instance
347
+ under their Background section, over the soul's `background:`; with neither,
348
+ the soul decides, and a soul that says nothing means no. The home records it
349
+ at spawn (`.oats-background.json`), so a later soul edit moves no existing
350
+ instance; `oats instance background <instance> on|off` does. Both flags
351
+ together are `E_BAD_ARGS`.
344
352
  An apply takes `--suggest-name` too (without `--name` or `--purpose`): the
345
353
  machine that spawns makes the same call, names the instance
346
354
  `<descriptive>-<role>`, de-duplicated the same way, and numbers it on any
@@ -444,6 +452,30 @@ extra trees: see [`attached`](#attached--another-instances-tree)),
444
452
  because an attached agent serves that owner; relation flags other than a
445
453
  redundant child-of-owner are rejected.
446
454
 
455
+ `--same-work` (feature `instance-same-work`) records that the new instance
456
+ does the same work as its parent; clients draw the parent→child line for an
457
+ instance that carries it. It is bound to the parent the new home records,
458
+ whichever relation gave it: a child, a sibling of an anchor that has a
459
+ parent, a `parent` relation whose anchor had a parent (the new instance
460
+ inherits it), or an attached spawn (the owner). A spawn that would record no
461
+ parent (unrelated, a sibling of a root, a `parent` relation over a root
462
+ anchor) is refused with `E_BAD_ARGS` before anything is created, a preview
463
+ included. The flag is the home's own file, `.oats-same-work.json`, naming the
464
+ parent it was set against, and it is on only while that is still the home's
465
+ recorded `parentInstance`: after a reparent (a retire's lineage splice, or a
466
+ `parent` spawn re-pointing its anchor) it reads off. It survives a restart, a
467
+ stop and a start, a resume and `oats instance upgrade`; only `off` or
468
+ retirement clears it.
469
+
470
+ `oats instance same-work <instance> on|off` sets or clears the flag on an
471
+ existing instance, addressed as `oats instance color` addresses it and routed
472
+ with `--server`. `on` needs a recorded parent and binds the flag to the
473
+ current one, so it also rebinds after a reparent; `off` always succeeds. An
474
+ instance with the flag on carries `sameWork: true` on its `oats status
475
+ --json` row; otherwise the key is absent. The answer, the errors and the
476
+ remote relay are in
477
+ [desktop-cli-api.md](desktop-cli-api.md#same-work-as-the-parent-oats-instance-same-work).
478
+
447
479
  `spawnOrigin` records the caller independently of these links. For new spawns
448
480
  from OATS 0.64.0, it is `instance` when the caller's `OATS_INSTANCE` and/or
449
481
  `OATS_INSTANCE_HOME` resolve consistently to an extant home in this deployment;
@@ -1644,7 +1676,8 @@ branch stays in the repository either way.
1644
1676
 
1645
1677
  A work mode decides what `./work` points at and what discipline the agent must
1646
1678
  follow. Every mode sits inside the same home/work boundary, which the generated
1647
- instructions state first (`injects/instance-boundary.md`):
1679
+ instructions state just before the work-mode block, the two closing the file
1680
+ after the capability injects (`injects/instance-boundary.md`):
1648
1681
 
1649
1682
  - `<instance-home>` — the gitignored instance directory, `$OATS_INSTANCE_HOME` —
1650
1683
  holds the brain (the composed `AGENTS.md`; there is no soul link), the task, the provenance
package/docs/tui.md CHANGED
@@ -178,7 +178,10 @@ while a terminal is open); under 80 columns it has the whole width.
178
178
  order, from the same code. It is in name order, by each group's top
179
179
  instance, so starting or stopping an instance moves nothing. An instance
180
180
  that others were spawned from has them indented under it, and keeps its
181
- place when it gains or loses one. An empty row stands between each run
181
+ place when it gains or loses one. Under one parent, the instances that do
182
+ its work (the kernel's `sameWork`, from an OATS with `instance-same-work`)
183
+ come first, then the others, each part in name order, as the Desktop lists
184
+ them. An empty row stands between each run
182
185
  of instances related to no other and the group before or after it. The
183
186
  indent alone says which instance is under which: no mark is drawn for
184
187
  it. A row whose instances are folded away (`h`) says how many after its
@@ -237,6 +240,27 @@ while a terminal is open); under 80 columns it has the whole width.
237
240
  own deployment, and a name that is no instance there, or two of them, is
238
241
  not shown. From 80 columns up it stands beside the sidebar; on a narrower
239
242
  terminal `Tab` opens it as a page over the whole screen.
243
+ - **Background instances** ([#1579](https://github.com/awebai/oats/issues/1579))
244
+ are listed apart, as in the Desktop's sidebar. An instance whose
245
+ `background` is on (`oats instance background`, or its soul's default at
246
+ spawn) leaves the list, and so do the instances below it, whatever their
247
+ own setting. They stand under one heading at the very end of the list:
248
+ `▸ Background 3` (`>` in ASCII), the word in bold and the count dim. The
249
+ heading starts closed in every run, and stays as you leave it for each
250
+ workspace while the TUI runs. It can be selected: `Enter` or `Space`
251
+ opens or closes it, `Right` opens it (on an open one, goes to its first
252
+ row) and `Left` closes it. Open (`▾`), its rows form their own tree, with
253
+ the deployments' headings in a view of two or more; a background instance
254
+ whose parent is in the list above is a top row there. While one of its
255
+ instances needs input, open or closed, the heading carries `Needs input`
256
+ at its right edge in the roll-up's look (only the `!` on a narrow row),
257
+ and the help's count of instances that need input counts it. A filter
258
+ shows the matching background rows with the section open, without
259
+ changing whether it is kept open, and the heading then counts the
260
+ matches. The movement keys pass over the rows of a closed section, and
261
+ showing a background instance's terminal from the palette leaves the
262
+ section as it was. The palette lists every instance. Without OATS's
263
+ `instance-background` feature every instance stays in the list.
240
264
  - **Opening an agent.** `Enter` on an instance that runs opens its terminal
241
265
  beside the sidebar, where the detail was, as a tab: see
242
266
  [Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
@@ -1272,6 +1296,63 @@ The exit status never depends on it.
1272
1296
  there can leave `.oats-stop-pending.json` in the agent's home, and then
1273
1297
  the agent can be started but not stopped while that file exists.
1274
1298
 
1299
+ ## Resuming lost sessions
1300
+
1301
+ After a shutdown, a reboot or a crash, the instances that were running have
1302
+ lost their sessions. When `oats tui` opens, it asks the kernel to resume
1303
+ them: it runs `oats session resume --json`, and the kernel does the rest.
1304
+ The kernel looks at every deployment on this computer's list (local
1305
+ deployments only, never another machine's) and resumes each lost session as
1306
+ it decides. What it does to a session, when it starts one fresh from its
1307
+ briefing instead, and when it stops trying for one that keeps losing its
1308
+ session, is the kernel's rule, written beside the command. A session lost
1309
+ long ago is not resumed automatically; `oats session start --resume` still
1310
+ brings it back by hand. `oats tui` owns no session: it runs the command, and
1311
+ says nothing about it.
1312
+
1313
+ **When it runs.** Once the run has started, whether it started in a
1314
+ deployment or in [the switcher](#the-switcher): after the deployment it
1315
+ started in has been added to this computer's list (the sweep reads that
1316
+ list), and without holding up the first frame or the first read. Then
1317
+ again whenever a read of a deployment open in the run shows an instance of
1318
+ this computer whose session was lost and that is not running (another
1319
+ machine's instances shown in the same workspace never count). Never two at
1320
+ a time, and never sooner than 30 seconds after the last one began. After a
1321
+ sweep that a read started, every instance it was started for waits until it
1322
+ changes (it runs, or it is no longer lost); so does an instance any sweep
1323
+ could not resume, found was not lost, or left because it was lost long ago.
1324
+ Such an instance sets off no sweep until a later read shows it running or no
1325
+ longer lost, or a sweep resumes it. There
1326
+ is no timer and no queue: a read that comes too soon starts nothing, and the
1327
+ next read asks again. The rule is the shared client's
1328
+ (`packages/client/session-resume-trigger.mjs`). It runs only when the kernel
1329
+ advertises the `session-resume` feature; without it, nothing runs.
1330
+
1331
+ **What it says.** Nothing. `oats tui` says nothing about a resume: no line
1332
+ when the sweep resumed an instance, started one fresh, left one waiting for
1333
+ you or could not resume one, none when the sweep failed or another sweep
1334
+ held the machine, and none after leaving. The list shows each instance as
1335
+ it is after the next read: after a sweep that ran, the list is read at
1336
+ once, so a resumed instance shows running, and one the sweep did not resume
1337
+ shows not running. To see what a sweep would do, run
1338
+ `oats session resume --plan --json`; `oats session resume` run by hand says
1339
+ what it did, and why it could not resume an instance.
1340
+
1341
+ **There is no setting to turn it off.** To keep an instance down, stop it
1342
+ with OATS (`X`, or `oats instance stop`): a stopped instance is not lost,
1343
+ and the sweep leaves it alone.
1344
+
1345
+ **Quitting does not stop a sweep.** It is a change, like an act you
1346
+ confirmed ([above](#stopping-starting-restarting-and-retiring)): it runs in
1347
+ a session of its own, writes its answer to files of its own, and is never
1348
+ signalled by `oats tui`. Quitting while it runs leaves it to finish, without
1349
+ a word: unlike an act, a sweep still running is not named after the screen
1350
+ is left.
1351
+
1352
+ `S` and `R` are unchanged: a start or restart from `oats tui` starts the
1353
+ instance as it was last launched, and never resumes a conversation. Only
1354
+ the sweep resumes.
1355
+
1275
1356
  ## Spawning an agent
1276
1357
 
1277
1358
  `n` spawns an agent of a soul of the open workspace, on this machine, with
@@ -1614,8 +1695,9 @@ from every focus, an agent's terminal included: the agent never gets them.
1614
1695
  | `Up` `k`, `Down` `j` | move the selection; with the detail focused, scroll it |
1615
1696
  | `g` `Home`, `G` `End` | first row, last row |
1616
1697
  | `PageUp`, `PageDown` | one page |
1617
- | `Left` `h` | fold the instances below the row away; on a row with none, or already folded, go to its parent |
1618
- | `Right` `l` | show them again; on a row already open, go to its first child |
1698
+ | `Left` `h` | fold the instances below the row away; on a row with none, or already folded, go to its parent (from a top row of the Background section, its heading); on the Background heading, close it |
1699
+ | `Right` `l` | show them again; on a row already open, go to its first child; on the Background heading, open it, or go to its first row |
1700
+ | `Enter`, `Space` | on the Background heading, open or close it |
1619
1701
  | `Tab` | move between the list and the detail; under 80 columns, open and close the detail page |
1620
1702
  | `/` | filter |
1621
1703
  | `r` | read now |
@@ -1644,8 +1726,8 @@ from every focus, an agent's terminal included: the agent never gets them.
1644
1726
  | `Ctrl+Z` | suspends: the shell gets the terminal back as it was; `fg` returns, redraws and reads at once |
1645
1727
  | `Ctrl+L` | redraws the whole screen, and sets the terminal's modes again if something reset them |
1646
1728
 
1647
- The selection stands on instances only, and in the switcher on its rows: a
1648
- heading, a reason and a note are passed over. What stands above the first
1729
+ The selection stands on instances and the Background heading only, and in
1730
+ the switcher on its rows: any other heading, a reason and a note are passed over. What stands above the first
1649
1731
  instance or under the last one comes into view with it. When a movement key
1650
1732
  has no instance to go to (the selection is on the first or the last one, or
1651
1733
  the list has none), it scrolls the list instead, so the rows after the last
@@ -2340,6 +2422,11 @@ with the Desktop (`packages/client/`).
2340
2422
 
2341
2423
  An add and a remove are changes: `oats tui` never ends one, and one still
2342
2424
  running as it leaves is named in one line after the screen is left.
2425
+ - **The kernel's machine sweep**, `oats session resume --json`, by the same
2426
+ kernel, from `/`, with no time limit: when the run starts, and when a
2427
+ read shows a lost session ([Resuming lost sessions](#resuming-lost-sessions)).
2428
+ It is a change, as an add is, but one still running as `oats tui` leaves
2429
+ is not named.
2343
2430
  - **The workspace of each row of that list the run has not opened** is
2344
2431
  one more read, `oats status --dir <path> --json` with `--max-age 60`, by
2345
2432
  the same kernel ([the switcher](#the-switcher)): at the start, when the
@@ -2492,6 +2579,7 @@ with the Desktop (`packages/client/`).
2492
2579
  | To | Run |
2493
2580
  |---|---|
2494
2581
  | start an agent with another harness or model | `oats session start --home <home>` with its options |
2582
+ | move an instance into or out of the background | `oats instance background <name> on\|off` |
2495
2583
  | spawn an agent on another machine | `oats spawn <soul> --server <id>` |
2496
2584
  | spawn an agent with another harness, model or task | `oats spawn <soul>` with its options |
2497
2585
  | see a capability's skills and files | `oats capabilities show <name>` |
@@ -2649,7 +2737,9 @@ alone. The next run removes the directory that is left, with its `tmux`,
2649
2737
  server, session, window or pane. Its probe only lists panes. An agent's
2650
2738
  own session is started, ended or restarted only by the kernel's commands
2651
2739
  of an act you confirmed
2652
- ([above](#stopping-starting-restarting-and-retiring)), and an agent's
2740
+ ([above](#stopping-starting-restarting-and-retiring)) and by the kernel's
2741
+ machine sweep, which resumes lost sessions
2742
+ ([above](#resuming-lost-sessions)), and an agent's
2653
2743
  terminal is opened by `oats session attach`, which makes its own viewer
2654
2744
  session on the agents' tmux server and removes it. The one tmux server
2655
2745
  `oats tui` runs is its own private one
@@ -2660,11 +2750,12 @@ alone. The next run removes the directory that is left, with its `tmux`,
2660
2750
  ([above](#what-it-reads-and-what-it-runs)), and a spawn's empty task file
2661
2751
  ([above](#what-it-reads-and-what-it-runs)). The processes it starts are
2662
2752
  the reads above, when you open an agent its private tmux server and the
2663
- viewers in it, one for each tab, and the acts you confirm. No read, server or viewer
2753
+ viewers in it, one for each tab, the acts you confirm and the kernel's
2754
+ machine sweep. No read, server or viewer
2664
2755
  outlives it on every way out a process can handle; after SIGKILL a read
2665
2756
  in flight runs to its own end, and the private server and its viewers end
2666
- by themselves. An act you confirmed is never ended by `oats tui`: it runs
2667
- to its own end. A spawn is ended only at its deadline, while `oats tui`
2757
+ by themselves. An act you confirmed, and the machine sweep, are never
2758
+ ended by `oats tui`: each runs to its own end. A spawn is ended only at its deadline, while `oats tui`
2668
2759
  runs ([above](#what-it-reads-and-what-it-runs)): never on the way out,
2669
2760
  and never after it.
2670
2761
  - It **changes this computer's list of deployments only through the
package/docs/upgrading.md CHANGED
@@ -6,11 +6,11 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.1** ([release notes](release-notes/v0.69.1.md)).
10
- The 0.69.1 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.2** ([release notes](release-notes/v0.69.2.md)).
10
+ The 0.69.2 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
11
11
 
12
12
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.69.1,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.2,** in the [release notes](release-notes/): it says what to do before
14
14
  the CLI changes, and what else must change with it (the Desktop, another
15
15
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
16
  names the releases that ask for more than the steps below. `oats version`
@@ -19,8 +19,8 @@ prints the version you have.
19
19
  Then, on each host:
20
20
 
21
21
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.69.1 first
23
- npm install -g @awebai/oats@0.69.1 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.2 first
23
+ npm install -g @awebai/oats@0.69.2 # 1. the CLI
24
24
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
25
  oats doctor # 3. in the same deployment
26
26
  ```
@@ -166,6 +166,10 @@ of the Desktop and the CLI, and an optional package pin. A change a script
166
166
  must follow is in its release's Upgrade section whether or not it is listed
167
167
  here.
168
168
 
169
+ - **[0.69.2](release-notes/v0.69.2.md#upgrade):** the catalog pins
170
+ oats.framework 1.16.1 and oats.okf 5.5.0. Sync each deployment before its
171
+ instances on oats.okf 5.5.0 write proposals: an older harvester refuses
172
+ them. A soul's `background: true` waits until every deployment runs 0.69.2.
169
173
  - **[0.69.1](release-notes/v0.69.1.md#upgrade):** 0.69.0 was tagged but never
170
174
  published; 0.69.1 carries all of it, so follow
171
175
  [0.69.0's Upgrade section](release-notes/v0.69.0.md#upgrade): the Desktop
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.15.1 # bare version → resolves through the official catalog
58
- oats.okf: v5.3.0
57
+ oats.framework: v1.16.1 # bare version → resolves through the official catalog
58
+ oats.okf: v5.5.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone