@awebai/oats 0.68.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 (99) hide show
  1. package/bin/oats.mjs +180 -36
  2. package/docs/capabilities.md +73 -10
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/configuration.md +68 -2
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  6. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  7. package/docs/desktop-cli-api.md +600 -25
  8. package/docs/desktop-instance-start.md +59 -3
  9. package/docs/desktop.md +175 -10
  10. package/docs/execution-targets.md +536 -62
  11. package/docs/harness-trust.md +3 -1
  12. package/docs/implementation.md +33 -15
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge.md +25 -16
  15. package/docs/oats-local.schema.json +2 -2
  16. package/docs/official-catalog.md +6 -5
  17. package/docs/packages.md +14 -14
  18. package/docs/release-notes/v0.69.0.md +658 -0
  19. package/docs/release-notes/v0.69.1.md +25 -0
  20. package/docs/release-notes/v0.69.2.md +259 -0
  21. package/docs/servers.md +51 -7
  22. package/docs/soul.schema.json +1 -0
  23. package/docs/souls-and-instances.md +46 -9
  24. package/docs/tui.md +177 -21
  25. package/docs/upgrading.md +16 -7
  26. package/docs/workspaces.md +2 -2
  27. package/injects/instance-boundary.md +19 -33
  28. package/injects/work-attached.md +8 -13
  29. package/injects/work-checkout.md +16 -30
  30. package/injects/work-directory.md +9 -15
  31. package/injects/work-workspace.md +8 -19
  32. package/injects/work-worktree.md +18 -33
  33. package/lib/capability-contract.mjs +2 -2
  34. package/lib/core.mjs +496 -127
  35. package/lib/file-pieces.mjs +49 -0
  36. package/lib/instance-background.mjs +54 -0
  37. package/lib/instance-events.mjs +25 -4
  38. package/lib/instance-inspect.mjs +3 -0
  39. package/lib/instance-lifecycle.mjs +35 -0
  40. package/lib/instance-resolution.mjs +3 -2
  41. package/lib/instance-same-work.mjs +67 -0
  42. package/lib/instance-upgrade.mjs +18 -0
  43. package/lib/launch-prompt-fixtures/README.md +62 -0
  44. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  45. package/lib/launch-prompt-fixtures.mjs +49 -0
  46. package/lib/launch-prompt-resume.mjs +55 -0
  47. package/lib/login-environment.mjs +27 -9
  48. package/lib/materialize.mjs +23 -2
  49. package/lib/resolve.mjs +32 -5
  50. package/lib/schedule.mjs +3 -3
  51. package/lib/servers.mjs +136 -27
  52. package/lib/session-end.mjs +82 -0
  53. package/lib/session-input.mjs +43 -9
  54. package/lib/session-resume-contract.mjs +33 -0
  55. package/lib/session-resume.mjs +337 -0
  56. package/lib/session-seen.mjs +163 -0
  57. package/lib/session-viewer.mjs +147 -44
  58. package/lib/soul-composition.mjs +15 -11
  59. package/lib/start-env.mjs +110 -0
  60. package/lib/tmux-server-scope.mjs +139 -14
  61. package/lib/workspace.mjs +41 -6
  62. package/package-catalog.json +11 -5
  63. package/package.json +1 -1
  64. package/packages/client/cli-adapter.mjs +39 -8
  65. package/packages/client/cli-locator.mjs +3 -2
  66. package/packages/client/deployment-data.mjs +16 -0
  67. package/packages/client/deployment-panel.mjs +7 -0
  68. package/packages/client/file-output-exec.mjs +98 -0
  69. package/packages/client/instance-tree.mjs +64 -14
  70. package/packages/client/launch-prompt-outcome.mjs +25 -13
  71. package/packages/client/own-codes.mjs +2 -0
  72. package/packages/client/panel-views.mjs +11 -3
  73. package/packages/client/remote-roster.mjs +5 -1
  74. package/packages/client/roster-sections.mjs +50 -6
  75. package/packages/client/same-work.mjs +49 -0
  76. package/packages/client/session-attach.mjs +35 -5
  77. package/packages/client/session-resume-cli.mjs +64 -0
  78. package/packages/client/session-resume-trigger.mjs +167 -0
  79. package/packages/client/session-resume.mjs +332 -0
  80. package/packages/client/soul-rows.mjs +2 -0
  81. package/packages/client/spawn-apply-contract.mjs +2 -1
  82. package/packages/client/spawn-decision.mjs +4 -1
  83. package/packages/client/spawn-preview-contract.mjs +12 -1
  84. package/packages/client/spawn-preview.mjs +2 -0
  85. package/packages/client/tmux-status.mjs +30 -7
  86. package/packages/client/waiting-on-you.mjs +11 -4
  87. package/packages/client/workspace-step.mjs +17 -5
  88. package/packages/record/lib/last-conversation.mjs +123 -0
  89. package/packages/record/lib/session-roots.mjs +10 -1
  90. package/packages/tui/README.md +2 -2
  91. package/packages/tui/lib/client.mjs +7 -3
  92. package/packages/tui/lib/main.mjs +49 -14
  93. package/packages/tui/lib/model.mjs +146 -55
  94. package/packages/tui/lib/store.mjs +84 -27
  95. package/packages/tui/lib/term/text.mjs +12 -9
  96. package/packages/tui/lib/views/frame.mjs +74 -7
  97. package/packages/tui/lib/views/help.mjs +10 -3
  98. package/packages/tui/lib/views/instances.mjs +41 -3
  99. package/skills/oats-getting-started/SKILL.md +117 -4
@@ -0,0 +1,25 @@
1
+ # OATS 0.69.1
2
+
3
+ Unreleased
4
+
5
+ 0.69.0 was tagged but never published: its release run failed on a macOS-only
6
+ test before anything was released. 0.69.1 is the first 0.69 release, and it
7
+ carries everything in [0.69.0's notes](v0.69.0.md): session resume, the agent's
8
+ pane in a split window, the scroll keys, the waiting row, oats.aweb 1.32.0,
9
+ oats.engineering 1.15.0 and oats.framework 1.15.1.
10
+
11
+ ## Upgrade
12
+
13
+ - **Follow [0.69.0's Upgrade section](v0.69.0.md#upgrade)**: install the
14
+ Desktop first and the CLI second (a 0.68 Desktop refuses a 0.69 CLI). The
15
+ 0.69.1 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`. Every host that shares
16
+ a workspace runs OATS 0.68.0 or later before any of them syncs to
17
+ oats.aweb 1.32.0. Then run `oats status` once before you restart, so the
18
+ session resume sweep knows what was running.
19
+
20
+ ## Fixed
21
+
22
+ - **The Desktop's tests pass on macOS.** A test of the session resume
23
+ runner compared a working directory without resolving macOS's `/var` →
24
+ `/private/var` link, which failed both macOS Desktop builds of 0.69.0
25
+ (#1590). No behaviour changes.
@@ -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
@@ -71,7 +71,7 @@ which is where a [macOS keychain](#git-on-a-macos-host) problem shows up.
71
71
  ## Connect a machine
72
72
 
73
73
  ```bash
74
- oats server connect altair-aweb --ssh altair --dir '~/acme' --path /opt/homebrew/bin --install-oats
74
+ oats server connect altair-aweb --ssh altair --dir '~/acme' --install-oats
75
75
  ```
76
76
 
77
77
  Run from a deployment, `server connect` puts that deployment's workspace on
@@ -83,7 +83,7 @@ missing, so after a human step you run the same command again.
83
83
  |---|---|
84
84
  | `--dir <path>` | none, inside a deployment too: the folder on the host for this deployment, absolute or `~/…` (resolved by the host). Without it: `E_BAD_ARGS` "--dir <path on the host> is required: the folder on `<host>` for this deployment (absolute, or ~/… resolved there)". A registration made before it was required is unchanged |
85
85
  | `--workspace-ref <ref>` | this deployment's `oats-local.yaml` `workspace:` |
86
- | `--oats <path>`, `--path <dirs>`, `--label <text>` | as for `server add`; `--path` is where the host finds `npm`, `oats` and the harnesses |
86
+ | `--oats <path>`, `--path <dirs>`, `--label <text>` | as for `server add`; `--path` is where the host finds `npm`, `oats` and the harnesses. Without it, connect uses the PATH of the host user's [login shell](#the-hosts-login-shell-path) |
87
87
  | `--install-oats` | off: a missing or older OATS is a human step |
88
88
  | `--replace` | off: an id registered for another host or directory is refused |
89
89
 
@@ -91,8 +91,8 @@ The steps, in order:
91
91
 
92
92
  | Step | Checks | When something is missing |
93
93
  |---|---|---|
94
- | `ssh` | the host answers a non-interactive ssh | `failed` `E_SSH` |
95
- | `oats` | `oats version --json` there is this kernel's version or newer and advertises `server-connect` (a build of the same version without it is not enough) | with `--install-oats`: runs `npm install -g @awebai/oats@<this version>` there (`done`); without it, or with no `npm` on the host's PATH: `needs-human` with the command to run |
94
+ | `ssh` | the host answers a non-interactive ssh; without `--path`, the PATH of the host user's [login shell](#the-hosts-login-shell-path) is read (its `detail` says whether) | `failed` `E_SSH` |
95
+ | `oats` | `oats version --json` there is this kernel's version or newer and advertises `server-connect` (a build of the same version without it is not enough) | with `--install-oats`: runs `npm install -g @awebai/oats@<this version>` there (`done`); without it: `needs-human` with the command to run. With no `npm` on the PATH it searched (named in `detail`): `needs-human` to install Node.js there, with a command that checks the login shell finds `npm`, then check again |
96
96
  | `git` | the host's Git reads the workspace remote | `needs-human` with the remedy (and the [keychain hint](#git-on-a-macos-host)) |
97
97
  | `deployment` | `--dir` holds a deployment of this workspace | an absent or empty directory is onboarded there (`done`); a deployment of another workspace is `failed` `E_SERVER_WORKSPACE_MISMATCH`; a non-empty directory without `oats-local.yaml` is `failed` `E_DIR_NOT_EMPTY` and nothing is written into it |
98
98
  | `register` | the registration exists, with its `workspaceKey` | written (`done`); an id registered for another target is `failed` `E_SERVER_EXISTS` unless `--replace` (checked before anything else, so a requested id never reports ready while it routes elsewhere); a new id whose host and directory are already registered under another id is reported (`ok`, naming that id; the text result then names that id to spawn with) and not registered twice |
@@ -105,6 +105,37 @@ human. Connect never handles credentials: what Git on the host cannot read
105
105
  is always a human step there. The `--json` shape is in
106
106
  [desktop-cli-api.md](desktop-cli-api.md#oats-server-connect).
107
107
 
108
+ ### The host's login-shell PATH
109
+
110
+ A non-interactive ssh command does not read the user's login files, so on a
111
+ host whose PATH comes from `~/.zprofile`, `~/.bash_profile` or `~/.profile`
112
+ (a Homebrew or version-manager directory, say) it finds neither `npm` nor
113
+ `oats`. Without `--path`, connect therefore asks the host user's own login
114
+ shell for its PATH once, in the `ssh` step, by the rules OATS uses for the
115
+ local login environment ([execution-targets.md](execution-targets.md)):
116
+
117
+ - The shell is the host's `$SHELL`, which sshd sets from the host's password
118
+ database. Only bash, zsh or fish at an absolute path is run; it runs
119
+ `-l -i -c` (login and interactive, so both its profile and its rc files are
120
+ read) and prints its PATH between two delimiters that carry a random nonce,
121
+ within 15 s and 1 MiB.
122
+ - The PATH's absolute directories (each once, in order) become the
123
+ registration's `path`, the field `--path` sets, so every later step and
124
+ every later `--server` command runs with them. `oats` found on that PATH is
125
+ recorded as `oatsPath` by its absolute path.
126
+ - Another shell, no answer in time, or an answer that is not one PATH: the
127
+ `ssh` step stays `ok`, its `detail` says why the PATH could not be read, and
128
+ connect goes on with ssh's own PATH.
129
+ - An explicit `--path` always wins: the login shell is not asked. An explicit
130
+ `--oats` is kept as given.
131
+ - A registration of the same host and directory made before keeps the `path`
132
+ and `oatsPath` it has; connect only fills in the ones it lacks (`register`
133
+ `done`, "recorded …"), and `--replace` rewrites them with what it found.
134
+ - The recorded `path` and `oatsPath` are a snapshot of the login shell at
135
+ connect time. On a host whose Node comes from a version manager (nvm,
136
+ asdf), a later Node upgrade can leave `oatsPath` pointing at a directory
137
+ that is gone; `oats server connect … --replace` reads them again.
138
+
108
139
  ### What connect runs on the host
109
140
 
110
141
  Besides `version --json`, `status --json`, `souls --json` and `readiness
@@ -235,10 +266,10 @@ sent as text or on stdin, never as paths.
235
266
 
236
267
  | Command | Where it runs | The server must advertise |
237
268
  |---|---|---|
238
- | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-preview-2` for `--preview`; `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply |
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` |
239
270
  | `status` | registered workspace | |
240
271
  | `retire` | the instance's home | `retire-home` to retire by exact home |
241
- | `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key` |
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 |
242
273
  | `session start`, `session restart` | the instance's home | `session-start`; `session-restart`; `launch-config` when `--launch-config`, `--harness` or `--yolo` is given |
243
274
  | `session upload` | the instance's home | `session-upload` |
244
275
  | `okf harvest --instance <name>` | the saved home | `harvest` |
@@ -250,6 +281,8 @@ sent as text or on stdin, never as paths.
250
281
  | `instance git`, `instance diff` | the instance's home; the Git runs there | `instance-git` (`instanceGitApi: 1`) |
251
282
  | `instance stop --plan\|--apply`, `retire --plan`, `retire --plan-revision … --idempotency-key …` | the instance's home | `lifecycle-plans` (`lifecycleApi: 1`) |
252
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` |
253
286
 
254
287
  `instance suggest-name` and `instance upgrade` are never routed: `--server` is
255
288
  `E_BAD_ARGS`. `instance suggest-name` names a spawn on the machine that asks,
@@ -331,6 +364,11 @@ nothing was sent`. Under `--json` the envelope's `error.details` is
331
364
  under `--print`, which otherwise skips it: a printed command must not carry
332
365
  a flag its host would ignore.
333
366
 
367
+ `--no-status-line` travels as it is, with no probe of its own: a host that
368
+ does not advertise `session-attach-no-status-line` ignores it and shows the
369
+ viewer's status line, which loses nothing
370
+ ([execution-targets.md](execution-targets.md#inspect-input-and-attach)).
371
+
334
372
  **Not routed.** `session input` runs on the execution host, where schedules
335
373
  and messaging capabilities call it. `session restart --stop-grace` is refused
336
374
  with `--server`; the remote default applies. `session attach --print` shows
@@ -369,7 +407,10 @@ carries `waitingOnYou` (needs input) when the host's kernel reports it, and
369
407
  only then: an older host's row has no such key. `retire` (0.59.0, a retire
370
408
  of the home running, unknown, failed or interrupted) is relayed the same
371
409
  way, through the kernel's own read of it, and a value that read refuses is
372
- 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
373
414
  its group from the saved routes. State is pulled on every call, from every
374
415
  group at once: each probe has its own deadline, `--per-target` (default 20 s)
375
416
  capped by `--budget` (default 45 s, the deadline of the whole answer), and a
@@ -389,6 +430,9 @@ answer, never a separate `version --json`, kept only when it is a valid list
389
430
  of feature names and otherwise `null` (unknown, as from a host before
390
431
  0.49.0); a failed probe has no `features` key
391
432
  ([the field](desktop-cli-api.md#the-remote-roster-oats-server-roster---json)).
433
+ It relays the host's viewer fact the same way, `probe.sessionViewer`
434
+ (`{prefixScroll}`, feature `session-attach-prefix-scroll`): whether that
435
+ host's viewer takes `C-b [`, or `null` when unknown.
392
436
 
393
437
  **Harvest** runs the knowledge capability's `okf harvest --json` in the
394
438
  instance's saved home on the server and relays its envelope.
@@ -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;
@@ -982,8 +1014,10 @@ A worktree that cannot be proven unchanged is copied without the read, so
982
1014
  there the refusal comes from the copy, as `E_WORK_PRESERVATION_FAILED`.
983
1015
 
984
1016
  **A file in the worktree that cannot be read.** The same read refuses a file
985
- it cannot read: one without read permission, or one over 2 GiB, which a
986
- single read cannot take. Two kinds of file are read although they are nothing
1017
+ it cannot read: one without read permission, or one that ends before the
1018
+ size it had when it was opened, because it shrank while it was read. A
1019
+ file of any size is read in pieces of 1 MiB, so a file over 2 GiB is read
1020
+ like any other. Two kinds of file are read although they are nothing
987
1021
  to preserve: a tracked file that is unchanged, and a file under a work root
988
1022
  that a capability declared disposable (`retirement.disposable.work`). So a
989
1023
  retire that has only the home to preserve refuses for such a file, with
@@ -992,10 +1026,9 @@ retire that has only the home to preserve refuses for such a file, with
992
1026
  or a FIFO refused before the hooks, the retire has already stopped the
993
1027
  session of a launched instance by then, the instance is not retired, and its
994
1028
  home is kept. The message is `could not read the worktree at <work>:
995
- <reason>`. For a file without read permission the reason names the file. For
996
- a file over 2 GiB it gives the size, and `find <work> -type f -size
997
- +2147483647c` finds the file. To continue, move the file out of the worktree
998
- or make it readable, then run `oats retire <instance>` again. With nothing to
1029
+ <reason>`. The reason names the file. To continue, make the file readable,
1030
+ move it out of the worktree, or stop what writes to it, then run
1031
+ `oats retire <instance>` again. With nothing to
999
1032
  preserve, the files are not read and the retire goes through.
1000
1033
 
1001
1034
  **A home whose `instance.json` cannot be read.** The record is what
@@ -1053,7 +1086,10 @@ of the whole home.
1053
1086
  untracked and ignored files, have anything to preserve is decided against
1054
1087
  two digests the spawn baseline stores: one of the home (without `work/`, the
1055
1088
  provider-owned entries declared at spawn, the kernel's records above, and
1056
- the fields the kernel writes into `instance.json` after spawn), and one of
1089
+ the fields the kernel writes into `instance.json` after spawn, for an
1090
+ `instance.json` of at most 16 MiB: a larger one is taken as its bytes, so a
1091
+ baseline that took it without those fields reads the home as changed and
1092
+ the retire copies the home to the recovery), and one of
1057
1093
  the worktree's untracked and ignored paths outside the roots a capability
1058
1094
  declared disposable. A spawn by 0.49.0 or later records `digestVersion: 2`
1059
1095
  in the baseline, and its digests order entries by the bytes of their names,
@@ -1640,7 +1676,8 @@ branch stays in the repository either way.
1640
1676
 
1641
1677
  A work mode decides what `./work` points at and what discipline the agent must
1642
1678
  follow. Every mode sits inside the same home/work boundary, which the generated
1643
- 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`):
1644
1681
 
1645
1682
  - `<instance-home>` — the gitignored instance directory, `$OATS_INSTANCE_HOME` —
1646
1683
  holds the brain (the composed `AGENTS.md`; there is no soul link), the task, the provenance