@awebai/oats 0.55.1 → 0.57.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/bin/oats.mjs +96 -72
  2. package/docs/capabilities.md +67 -3
  3. package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
  4. package/docs/desktop-cli-api.md +375 -37
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +65 -11
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +153 -11
  10. package/docs/integrations.md +5 -3
  11. package/docs/knowledge.md +117 -43
  12. package/docs/official-catalog.md +3 -3
  13. package/docs/packages.md +12 -12
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.56.0.md +699 -0
  16. package/docs/release-notes/v0.57.0.md +283 -0
  17. package/docs/schedules.md +8 -3
  18. package/docs/servers.md +21 -5
  19. package/docs/souls-and-instances.md +134 -19
  20. package/docs/tui.md +215 -31
  21. package/docs/upgrading.md +4 -1
  22. package/docs/workspaces.md +26 -6
  23. package/lib/automations.mjs +3 -4
  24. package/lib/bounded-read.mjs +18 -0
  25. package/lib/capability-show.mjs +13 -2
  26. package/lib/claim.mjs +3 -4
  27. package/lib/core.mjs +919 -278
  28. package/lib/errors.mjs +39 -0
  29. package/lib/harness-trust-write.mjs +119 -40
  30. package/lib/harness-trust.mjs +31 -18
  31. package/lib/instance-inspect.mjs +160 -11
  32. package/lib/instance-lifecycle.mjs +90 -37
  33. package/lib/packages.mjs +8 -5
  34. package/lib/pi-bridge.mjs +18 -19
  35. package/lib/remote.mjs +88 -51
  36. package/lib/retire-output.mjs +9 -4
  37. package/lib/schedule.mjs +3 -4
  38. package/lib/servers.mjs +39 -6
  39. package/lib/session-viewer.mjs +25 -1
  40. package/lib/triggers.mjs +3 -4
  41. package/lib/workspace.mjs +6 -6
  42. package/lib/worktree.mjs +33 -8
  43. package/lib/write-through-private-file.mjs +26 -0
  44. package/package-catalog.json +2 -2
  45. package/package.json +1 -1
  46. package/packages/client/cli-adapter.mjs +108 -13
  47. package/packages/client/cli-locator.mjs +16 -14
  48. package/packages/client/deployment-panel.mjs +4 -3
  49. package/packages/client/display-text.mjs +2 -1
  50. package/packages/client/instance-events-contract.mjs +4 -3
  51. package/packages/client/instance-lifecycle.mjs +235 -0
  52. package/packages/client/instance-presentation.mjs +9 -0
  53. package/packages/client/instance-tree.mjs +10 -8
  54. package/packages/client/kernel-lines.mjs +3 -3
  55. package/packages/client/launch-contract.mjs +11 -0
  56. package/packages/client/launch-prompt-outcome.mjs +1 -1
  57. package/packages/client/lifecycle-cli.mjs +12 -6
  58. package/packages/client/lifecycle-confirmation.mjs +407 -0
  59. package/packages/client/lifecycle-contract.mjs +6 -2
  60. package/packages/client/own-codes.mjs +1 -0
  61. package/packages/client/panel-views.mjs +39 -2
  62. package/packages/client/readiness-contract.mjs +2 -2
  63. package/packages/client/remote-roster.mjs +50 -5
  64. package/packages/client/roster-sections.mjs +3 -3
  65. package/packages/client/session-start.mjs +98 -0
  66. package/packages/client/start-gate.mjs +46 -0
  67. package/packages/client/start-messages.mjs +17 -0
  68. package/packages/client/workspace-views.mjs +2 -2
  69. package/packages/tui/README.md +21 -8
  70. package/packages/tui/lib/actions.mjs +11 -2
  71. package/packages/tui/lib/client.mjs +9 -2
  72. package/packages/tui/lib/config.mjs +39 -9
  73. package/packages/tui/lib/main.mjs +168 -20
  74. package/packages/tui/lib/model.mjs +315 -13
  75. package/packages/tui/lib/open.mjs +45 -0
  76. package/packages/tui/lib/read.mjs +171 -16
  77. package/packages/tui/lib/store.mjs +171 -10
  78. package/packages/tui/lib/term/tty.mjs +71 -12
  79. package/packages/tui/lib/views/act.mjs +85 -0
  80. package/packages/tui/lib/views/frame.mjs +145 -33
  81. package/packages/tui/lib/views/help.mjs +46 -11
  82. package/skills/oats-getting-started/SKILL.md +6 -3
@@ -0,0 +1,283 @@
1
+ # OATS 0.57.0
2
+
3
+ 2026-10-15
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.56 Desktop refuses a 0.57.0 CLI. The
9
+ 0.57.0 Desktop accepts OATS CLIs `>=0.26.0 <0.58.0`.
10
+
11
+ - **A script that runs `oats worktree remove`** may now get
12
+ `E_CHILDREN_RUNNING`: the tree is the work of an attached instance whose
13
+ session is running or cannot be read. Nothing is removed, and no flag
14
+ removes anyway: stop that instance (`oats instance stop <instance>`) or
15
+ retire it, then remove again. **A script that attaches a spawn to a tree of
16
+ no known instance** gets one `E_BAD_ARGS` naming every flag still missing,
17
+ where it got a repository refusal and then `E_SPAWN_FAILED` on the retry.
18
+ See Changed ([#958](https://github.com/awebai/oats/issues/958),
19
+ [#964](https://github.com/awebai/oats/issues/964)).
20
+
21
+ - **A retire plan taken before the upgrade** is refused once by the 0.57.0
22
+ kernel with `E_PLAN_STALE` and the fresh plan: the plan's revision now also
23
+ binds the instances attached to each tree. Read the fresh plan and retire
24
+ with it. See Changed ([#964](https://github.com/awebai/oats/issues/964)).
25
+
26
+ - **On Linux and Windows the Desktop's palette is Ctrl+Shift+K,** and
27
+ Ctrl+Shift+P now opens Quick Open, from a focused terminal too. macOS keeps
28
+ ⌘K and ⌘P. See Changed
29
+ ([#1217](https://github.com/awebai/oats/issues/1217)).
30
+
31
+ - **To get the new provider versions,** pin `oats.framework: v1.10.2` and
32
+ `oats.okf: v5.2.0` in your workspace and run `oats sync`. Instances already
33
+ running keep what they were spawned with. See Provider updates.
34
+
35
+ - **Pin `oats.okf: v5.2.0` and run `oats sync`; only new spawns get the
36
+ capability-owned harvest duty.** Existing homes keep their copied provider
37
+ and instructions, including across session restarts. Deployments whose
38
+ task briefings never mentioned harvests now propose eligible knowledge at
39
+ finished tasks or PR hand-overs. Souls not ready for that must declare
40
+ `knowledge: { harvest: off }`; consultation and working-memory upkeep
41
+ remain. OATS >=0.49.0 is still required.
42
+
43
+ - **The official catalog's versions in this release** are oats.framework
44
+ 1.10.2, oats.okf 5.2.0, oats.aweb 1.27.3, oats.engineering 1.10.0,
45
+ oats.cloning 1.0.1, oats.authoring 1.0.3, oats.jira 1.0.1, oats.linear 1.0.1
46
+ and oats.apps 1.0.0.
47
+
48
+ ## Added
49
+
50
+ - **`oats tui` stops, starts, restarts and retires an agent**
51
+ ([#855](https://github.com/awebai/oats/issues/855)). With an instance
52
+ selected, `X` stops it, `D` retires it, `S` starts it and `R` restarts it,
53
+ each after a confirmation that opens with the focus on `Cancel`: the act
54
+ takes a move (`Left`/`Right` or `Tab`) and a press of `Enter`, and pasted
55
+ text never acts. The rules and the words are the Desktop's: a stop or a
56
+ retire shows the kernel's plan first and applies exactly that plan, on
57
+ this machine or on a registered one; a start or a restart uses the launch
58
+ recorded for the agent. An act you sent runs to its end whatever
59
+ `oats tui` does: closing the confirmation, quitting, a suspend or a signal
60
+ never ends it, and when you leave while one runs a line on standard error
61
+ says so. `tui.json` changes the keys (`stop`, `retire`, `start`,
62
+ `restart`). See [the TUI page](../tui.md#stopping-starting-restarting-and-retiring).
63
+
64
+ - **Desktop: each team has its own page, with your instances on it.** Click
65
+ a card under Workspace › Teams, or press Enter on its name, to open it. The
66
+ page shows the team's card at the top (its default, description, who may
67
+ join, address, problems and actions), then **Your instances on this team**:
68
+ how many there are, how many run, how many are stopped or need attention,
69
+ and on how many machines. Below that, each machine gets a card, with a
70
+ table of its instances: the name, the soul, the state, when it was created
71
+ and a Terminal button when it can be opened. A click on the name shows the
72
+ instance in the roster. The page lists only your instances, the ones on
73
+ this computer and on the machines you added to this workspace. Instances
74
+ other people run on the team are not listed. Back or Esc returns to the
75
+ board, on that team's card.
76
+
77
+ ## Changed
78
+
79
+ - **The Desktop accepts OATS CLIs `>=0.26.0 <0.58.0`**
80
+ ([#1211](https://github.com/awebai/oats/issues/1211)). The compatibility band
81
+ admits 0.57; a 0.56 Desktop refuses a 0.57 CLI. No new gate on the band.
82
+ `oats tui` runs the kernel it ships with and is held to the same band.
83
+
84
+ - **Desktop on Linux and Windows: the palette is Ctrl+Shift+K, and Quick Open
85
+ is Ctrl+Shift+P and works from a focused terminal**
86
+ ([#1217](https://github.com/awebai/oats/issues/1217)). Quick Open was
87
+ Ctrl+P, which a focused terminal keeps for the program in it (shell
88
+ history), so it did not open from there. **Ctrl+Shift+P changes meaning:**
89
+ it has opened the palette since 0.30.3 and now opens Quick Open; the
90
+ palette moves to Ctrl+Shift+K. While the palette is open, Ctrl+Shift+K
91
+ moves down its rows and ArrowUp moves up. xterm sends nothing for either
92
+ chord, so plain Ctrl+K and Ctrl+P still reach the program. A shortcut you
93
+ set yourself is kept; when it is one of these two chords, the shortcuts
94
+ editor shows the clash. A Quick Open shortcut you set yourself now works
95
+ from a terminal too: if it is a plain Ctrl+letter, such as Ctrl+P, the
96
+ program no longer gets that key, so choose a Ctrl+Shift chord. macOS is
97
+ unchanged (⌘K, ⌘P). See
98
+ [Desktop keyboard](../../packages/desktop/docs/desktop-keyboard.md).
99
+
100
+ - **An attached spawn on an extra tree derives its owner and its repository
101
+ (#958).** `oats spawn <soul> --work attached --work-dir
102
+ <home>/.work-<purpose>` was refused twice: first for the repository
103
+ (`pass --repo`), then, with that given, for the owner (`--parent
104
+ <instance>`). For `<home>/work` the kernel derived both. An extra tree of
105
+ a home is that home's tree too, so the same command now spawns with
106
+ neither flag: the owner is the instance in whose home the tree is, the new
107
+ instance is its child, and its repository is the repository of the tree
108
+ it is attached to (for an extra tree the one Git names for it, which can
109
+ be another member repository than the owner's own). `--parent <owner>`
110
+ and `--repo` given explicitly still work, so a command that passes both
111
+ runs on this kernel and on earlier ones. The tree is an extra tree by the
112
+ kernel's own test (a registered linked worktree in a home), never by the
113
+ shape of its path. Nothing changes for `<home>/work`, and no flag, key or
114
+ field changes.
115
+
116
+ A tree of no known instance still needs both flags. Its refusal is now
117
+ one, `E_BAD_ARGS`, and names every flag still missing: `attached workDir
118
+ <path> is not a known instance's <home>/work or an extra tree of a known
119
+ instance's home (<home>/.work-<purpose>), so neither its owner nor its
120
+ repository is derived — pass both: --parent <instance> (the owning
121
+ instance) and --repo <repository>`. With one of the two given it names
122
+ the other. Before, the missing repository was refused first (`no
123
+ repository for a attached instance — pass --repo (the work tree's owner
124
+ records none)`), and the missing owner only on the retry, under the code
125
+ `E_SPAWN_FAILED`. See
126
+ [`attached`](../souls-and-instances.md#attached--another-instances-tree).
127
+
128
+ - **A tree that goes away says what it leaves its attached instances with
129
+ (#964).** An instance can be attached to an extra tree of its owner as to
130
+ the owner's `work/` (#958). Four things change for such a tree:
131
+
132
+ - **A retire that re-homes an extra tree repoints its attached children**
133
+ to the tree's new path, as it does for `work/`: only the recorded
134
+ children the retire stopped, only once the tree is seen at its new path
135
+ with nothing left at the old one, and only a link that is still the one
136
+ the retire found. One that cannot be repointed is a warning in the
137
+ receipt, with the command to do it by hand.
138
+ - **A retire that removes a tree names the attached children it leaves
139
+ without one.** A clean extra tree is removed, as before, and so is
140
+ `work/` with `--discard-worktree`. The plan's note for the tree now
141
+ names its attached children and says that their `work` link would then
142
+ point at a path that is gone, and the receipt's `warnings` (and the
143
+ summary) say so afterwards, naming each child, the tree and the link.
144
+ Before, the plan and the receipt said nothing of them.
145
+ - **An attached instance the retire does not act on is named too.** An
146
+ instance that records the owner as its parent under a name that is not
147
+ unique is listed under the plan's `ambiguous` and is never stopped, so
148
+ its link is not repointed either. The plan's note for the tree it is
149
+ attached to (an extra tree, or `work/`) now names it and says that its
150
+ `work` link would then point at a path that is gone, and the receipt's
151
+ `warnings` say so for each tree that was moved or removed, with the
152
+ command to repoint the link by hand where the tree was re-homed. A
153
+ `--self` retirement's receipt does not carry those warnings.
154
+ - **`oats worktree remove` refuses a tree under a running session.** When
155
+ an instance attached to the tree has a session that is running, or that
156
+ cannot be read, the command answers `E_CHILDREN_RUNNING` before Git is
157
+ asked anything: nothing is removed and the record is kept. `details` is
158
+ `{purpose, path, children: [{instance, home, session}]}`, `session` being
159
+ `"running"` or `"unknown"`. The message names each instance and the
160
+ step: stop it (`oats instance stop <instance>`) or retire it, then remove
161
+ again. The command stops nobody, and no flag removes the tree anyway. An
162
+ attached instance whose session is stopped does not refuse: the tree is
163
+ removed and the answer's `warnings` name the instance and its link.
164
+
165
+ The new sentences are strings in arrays the plan and the answers already
166
+ have (`notes`, `warnings`): no key, field or flag is new, and a tree with
167
+ no attached instance is handled as before. `E_CHILDREN_RUNNING` is the code
168
+ a retire already answers, there for a child it asked to stop and that did
169
+ not; `oats worktree remove` answers it with `details` of its own and no
170
+ `childrenStopped`. See
171
+ [extra trees at retire](../souls-and-instances.md#extra-trees-at-retire)
172
+ and [extra trees](../souls-and-instances.md#extra-trees).
173
+
174
+ - **Desktop: the Workspace › Setup tab reads as one column.** The List view
175
+ puts what the workspace shares through Git above what lives only on this
176
+ computer. It shows the same facts as before.
177
+ - **Under the workspace's name**, a summary counts the members (and those
178
+ that need attention), the packages and the state of the lock. The line
179
+ under it says where the workspace is declared, for example "Declared in
180
+ agents's oats-workspace.yaml at 1a2b3c4."
181
+ - **An Overview** says that the host repository defines the workspace: its
182
+ members and its packages. **For developers**, folded, explains the two
183
+ links that make a repository a member: the host's workspace file lists
184
+ it, and its membership file names the workspace back. It also says what
185
+ each member state means. The Graph view shows the Overview too. The
186
+ legend of badges is gone.
187
+ - **Shared through Git** holds Members, Packages and Defaults. Only the
188
+ host's row carries a tag, **Host** with its workspace file; the Member
189
+ tag is gone from every row. A confirmed member shows a check and
190
+ "confirmed". Any other state keeps its warning chip. In a wide enough
191
+ window every row takes one line.
192
+ - **This computer** holds the deployment's folder, settings, lock, lock
193
+ file, CLI, instances and disabled souls, then the member clones, then the
194
+ Machines box. Instances reads "3, 1 running". The Machines box no longer
195
+ carries a "Not shared" tag; the zone says it.
196
+ - **The Graph view** labels read "Shared through Git", "Members, latest"
197
+ and "Packages, pinned", in sentence case.
198
+
199
+ - **Desktop: the Teams board is one calm column.** Shared teams, local teams
200
+ and which teams each soul may join each have a heading and one line saying
201
+ what they are. A team's card no longer lists its instances: it shows the
202
+ team's facts in labelled rows (Default for, May join, Address), any
203
+ warning with its fix, and a summary line at the bottom ("3 of your
204
+ instances, 1 on other machines"). A click anywhere on the card opens the
205
+ team's page, and each card is one Tab stop. Which teams each soul may join
206
+ is now a table: the pattern, its default team, and the other teams it may
207
+ also join. The type is calmer: fewer sizes and styles, no uppercase labels,
208
+ and the facts that matter stand out by size and weight, not by new colours.
209
+
210
+ ## Fixed
211
+
212
+ - **Released in 0.56.0, not noted there: the Desktop's terminals draw again
213
+ after a GPU process restart
214
+ ([#1190](https://github.com/awebai/oats/issues/1190), #1192).** After the GPU
215
+ process restarted, xterm's shared glyph store went stale and terminals
216
+ stopped drawing. They now draw again. A 0.56.0 or later Desktop has the
217
+ fix.
218
+
219
+ - **A retire's recovery of a worktree carries a stopped cherry-pick, revert,
220
+ rebase or merge, and the stash, in both ref formats
221
+ ([#1038](https://github.com/awebai/oats/issues/1038)).** The recovery
222
+ copied an operation's state as files of the Git directory. Three things
223
+ were missing from it, and nothing said so:
224
+ - where the repository stores its refs in the reftable format,
225
+ `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD` and `AUTO_MERGE` are not
226
+ files. The recovery had none of them, and its `git status` no longer said
227
+ a cherry-pick or a revert was in progress. The stash's log is not a file
228
+ there either: the recovery's `git stash list` was empty;
229
+ - in both formats, the commit or tree those refs and `MERGE_HEAD` name is
230
+ often in no branch (a commit reset away, a conflict's tree). The recovery
231
+ named it without holding it, so `git cherry-pick --continue`, `git merge
232
+ --continue` or a diff against `AUTO_MERGE` failed there;
233
+ - a link at one of the copied names was left out when it led nowhere.
234
+
235
+ The recovery now writes those four refs through Git at the same ids and
236
+ holds every object they and `MERGE_HEAD` name. It stores the stash's
237
+ entries again, oldest first, with their messages, so `git stash list`
238
+ reads the same. A link is copied as the same link. A ref the source holds
239
+ in the reftable format without its object cannot be written, and refuses
240
+ the retire with `E_WORK_PRESERVATION_FAILED`, the home kept, as any
241
+ recovery that cannot be made does. Which homes a retire recovers, the
242
+ receipt and every code are unchanged.
243
+
244
+ ## Provider updates
245
+
246
+ - **oats.okf 5.2.0:** the IMPORTANT inject block requires current instance
247
+ knowledge and compulsory reading of `okf-propose`. The skill holds the
248
+ bounded checkpoint procedure, promotion/search checks, proposal format and
249
+ memory/concurrency gates. No harvest or proposal direction remains in the
250
+ working instance's TASK brief. At most one proposal per completed task or
251
+ PR hand-over, one harvester per instance, and no spawn under memory pressure
252
+ or below 8 GB available; most checkpoints propose nothing. An unrelated
253
+ harvester can outlive its proposer. These limits are instructions, not a
254
+ scheduler or resource reservation.
255
+ - `oats okf status` exposes the duty written by the provider at spawn (`on`,
256
+ `off`, or missing-state `unknown`). An unknown answer or failure permits no
257
+ proposal. Shared inject/skill text explicitly exempts opted-out souls, and
258
+ the harvester independently refuses their recorded source material. No
259
+ kernel composition mechanism is added.
260
+
261
+ - **oats.framework 1.10.2: oats.core 2.6.1 and oats.setup 2.5.4.**
262
+ Instruction text in two skills; no hook, command, schema or provider
263
+ contract changes, and the capability floors are unchanged (oats.core
264
+ `>=0.40.0`, oats.setup `>=0.30.0`).
265
+ - `oats-operate` (oats.core) says that from OATS 0.57.0 `oats worktree
266
+ remove` refuses a tree that is the work of an attached instance whose
267
+ session is running or cannot be read (`E_CHILDREN_RUNNING`): stop that
268
+ instance or retire it, then remove again, as the entry under Changed
269
+ says ([#964](https://github.com/awebai/oats/issues/964)).
270
+ - `oats-onboarding` (oats.setup) pins `oats.okf: v5.2.0` in its knowledge
271
+ section and describes the harvest duty that oats.okf 5.2.0 gives every
272
+ working soul: the compulsory `okf-propose` skill, `oats okf status`, and
273
+ the soul's own opt-out, as the oats.okf entry says.
274
+ - A deployment gets it by pinning `oats.framework: v1.10.2` and running
275
+ `oats sync`. Instances already running keep the skills they were spawned
276
+ with; new spawns get the new ones.
277
+
278
+ ## Documentation
279
+
280
+ - [Knowledge operations](../knowledge.md#the-flow) now describes the
281
+ capability-owned flow, opt-out/status answer, narrow checkpoints and
282
+ deferred hand-back. Catalog/workspace pins, package examples, mirrors and
283
+ clean-room composition assertions move together to 5.2.0.
package/docs/schedules.md CHANGED
@@ -841,9 +841,14 @@ fails, the spawn result still carries the instance receipt, plus
841
841
 
842
842
  ## Knowledge harvest and review
843
843
 
844
- **oats.okf 5.0 does not schedule harvest jobs.** At important checkpoints a
845
- working instance updates its notes, writes its own proposal (what to save,
846
- why, and backing notes), and directly spawns the package harvester:
844
+ **oats.okf 5.x does not schedule harvest jobs.** In 5.2 the capability's
845
+ IMPORTANT inject and compulsory `okf-propose` skill give the duty, not TASK.md.
846
+ A working instance keeps its notes current, checks `oats okf status`, and at
847
+ a finished task or PR hand-over proposes only durable, non-duplicate claims.
848
+ At most one proposal per completed unit of work, one harvester at a time,
849
+ and no spawn under memory pressure or below 8 GB available; otherwise defer
850
+ and hand back the pending claims. Most checkpoints propose nothing. When the
851
+ skill's gates pass, the instance directly spawns the package harvester:
847
852
 
848
853
  ```sh
849
854
  oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
package/docs/servers.md CHANGED
@@ -217,7 +217,7 @@ sent as text or on stdin, never as paths.
217
217
 
218
218
  | Command | Where it runs | The server must advertise |
219
219
  |---|---|---|
220
- | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule |
220
+ | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-preview-2` for `--preview` |
221
221
  | `status` | registered workspace | |
222
222
  | `retire` | the instance's home | `retire-home` to retire by exact home |
223
223
  | `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key` |
@@ -226,7 +226,7 @@ sent as text or on stdin, never as paths.
226
226
  | `okf harvest --instance <name>` | the saved home | `harvest` |
227
227
  | `schedule ...` | registered workspace | `schedule` |
228
228
  | `launch-config list\|set\|remove\|preview` | `--dir`, the instance's home, or the registered workspace | `launch-config` |
229
- | `inspect`, `operation run` | `--dir`, the instance's home, or the registered workspace | `operations`; `inspect --instructions` also `soul-composed-instructions` |
229
+ | `inspect`, `operation run` | `--dir`, the instance's home, or the registered workspace | `operations`; `inspect --instructions` also `soul-composed-instructions`, `inspect --skills` also `soul-skills` |
230
230
  | `readiness` | the instance's home, `--dir`, or the registered workspace | `readiness` (`readinessApi: 2`) |
231
231
  | `instance events` | the instance's home | `instance-events-2` (`eventsApi: 2`) |
232
232
  | `instance git`, `instance diff` | the instance's home; the Git runs there | `instance-git` (`instanceGitApi: 1`) |
@@ -239,6 +239,17 @@ checked against the harness it would use (the flag, or the soul's default as
239
239
  the remote roster reports it). A host that advertises no harness list is
240
240
  assumed to run only pi and claude, on tmux, with no launch options.
241
241
 
242
+ **A routed preview.** `oats spawn <soul> --server <id> --preview` runs the
243
+ spawn's checks here (`E_ROUTE_CHANGED`, `E_ROUTE_EXISTS`, the harness and
244
+ options), then asks the server's kernel for its preview. It prints the local
245
+ preview's line with the server named (`preview <soul> → <instance> on <id> …;
246
+ nothing was created`), and saves no route or other state on this machine. Its
247
+ `--json` result is the server's preview plus `server` and `target`. When a
248
+ saved route already holds the previewed name for another home, a warning says
249
+ a spawn would save no route. A server that does not advertise
250
+ `spawn-preview-2` is refused (`E_REMOTE_INCOMPATIBLE`) before the spawn is
251
+ sent, since an older kernel might spawn for real.
252
+
242
253
  **Addressing an instance.** Instance commands (`retire`, the `session`
243
254
  commands, `inspect`, `operation`, `launch-config`) reach any instance on the
244
255
  server, whoever spawned it, by `--home </remote/home>` or by name
@@ -338,7 +349,12 @@ capped by `--budget` (default 45 s, the deadline of the whole answer), and a
338
349
  group that fails or does not answer in time reports its own `E_SSH`, so a
339
350
  host that is switched off never hides the others. The groups keep their
340
351
  registration order whatever order their probes finish in. `--server <id>`
341
- narrows it.
352
+ narrows it. `--workspace-key <key>` (0.56.0, repeatable) narrows it to the
353
+ groups that can belong to those workspaces: a registration recorded for one
354
+ of them, a registration whose workspace is not known yet, and a group of
355
+ saved routes only, whose workspace is unknown; a registration recorded for
356
+ another workspace is not probed at all
357
+ ([the flag](desktop-cli-api.md#roster-workspace-key)).
342
358
 
343
359
  The group's `probe` also relays the host's kernel features (0.49.0,
344
360
  `probe.features`): the top-level `features` of the same `status --json`
@@ -353,8 +369,8 @@ instance's saved home on the server and relays its envelope.
353
369
  ## What this machine keeps
354
370
 
355
371
  A **saved route** per remote instance, under `~/.oats/remote/<server>/`,
356
- written at spawn: the ssh host, workspace, oats path and PATH prefix, and the
357
- remote home. Retire, harvest and session commands use
372
+ written at spawn (never by a preview): the ssh host, workspace, oats path and
373
+ PATH prefix, and the remote home. Retire, harvest and session commands use
358
374
  the saved route, not the current registration, so editing or removing a
359
375
  registration never orphans a remote home. The route is removed when the
360
376
  remote kernel reports the home gone.
@@ -231,8 +231,9 @@ operation and partial-failure recovery.
231
231
  to a Git root. An intervening repository can prevent deployment-root inheritance;
232
232
  the command does not automatically trust another root. The native field is
233
233
  `projects["<deployment>"].hasTrustDialogAccepted` in `~/.claude.json`
234
- (`$CLAUDE_CONFIG_DIR/.claude.json` when the launch's environment, host or
235
- launch configuration, sets it).
234
+ (`$CLAUDE_CONFIG_DIR/.claude.json` when the launch's environment sets it:
235
+ its launch configuration, else its tmux pane's, never the calling
236
+ process's in its place).
236
237
  - **Codex** applies only an exact entry: a trusted parent does not cover the
237
238
  folders below it. The explicit deployment-root command records
238
239
  `[projects."<deployment>"] trust_level = "trusted"` in
@@ -247,11 +248,14 @@ operation and partial-failure recovery.
247
248
 
248
249
  When the file a claude or codex launch reads does not trust the deployment,
249
250
  the spawn says so (text and `--json` `warnings`): `<harness> folder trust is
250
- not established in <file>: oats harness trust --dir <deployment>`. A missing
251
+ not established in <file> (<where the launch gets that file from>): oats
252
+ harness trust --dir <deployment>`. A missing
251
253
  entry does not prove a prompt, so it does not say the session will stop.
252
254
  `oats readiness` reports the same in `checks.configured` (code
253
255
  `harness-trust`, not required), and a passing item naming the file when trust
254
- is established.
256
+ is established. When the file cannot be established, or no pane exists to
257
+ read it from, both say that instead
258
+ ([launch-time checks](harness-trust.md#launch-time-checks-and-readiness)).
255
259
 
256
260
  [The development-channel confirmation](configuration.md#the-development-channel-confirmation)
257
261
  does not cover folder-trust prompts, and never writes trust settings.
@@ -398,7 +402,9 @@ sugar for `--relative-to <instance> --relation child`):
398
402
  `oats status --json` (`parentInstance` + `siblingInstance` edges).
399
403
  - **unrelated** (default): no link, operator-origin, top-level.
400
404
 
401
- Attached-mode spawns are ALWAYS children of the owner of the shared work tree,
405
+ Attached-mode spawns are ALWAYS children of the owner of the shared work tree
406
+ (the instance in whose home the tree is, as its `work/` or as one of its
407
+ extra trees: see [`attached`](#attached--another-instances-tree)),
402
408
  because an attached agent serves that owner; relation flags other than a
403
409
  redundant child-of-owner are rejected. Any other spawn, including one from a
404
410
  shell that inherited an agent's environment variables, is operator-origin and
@@ -550,8 +556,16 @@ parses it, so it copies the files Git reads:
550
556
  - what the copy takes from the Git directories as files, each with its bytes
551
557
  and its permission bits: the state of an operation in progress (a merge, a
552
558
  rebase, a cherry-pick, a revert, a bisect), `info/attributes` and the
553
- stash's log;
554
- - its tags and its stash;
559
+ stash's log. A link at one of the operation's entries is copied as the same
560
+ link, also one that leads nowhere;
561
+ - the refs an operation leaves that are not files where the refs are stored
562
+ in the reftable format: `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`
563
+ and `AUTO_MERGE`, each written into the copy through Git at the same object
564
+ id. The copy itself always stores its refs as files, whatever format the
565
+ operator's Git configuration or environment gives a new repository;
566
+ - its tags and its stash. Where the stash's log is not a file (the reftable
567
+ format), its entries are read through Git and stored again in the copy,
568
+ oldest first, each with its message, so `git stash list` reads the same;
555
569
  - its exclude rules (`core.excludesFile` with the file the copy reads for it,
556
570
  and `info/exclude`) and the settings that change what `git status` reports
557
571
  (`core.fileMode`, `core.ignoreCase`, `core.precomposeUnicode`,
@@ -704,7 +718,11 @@ Git in the recovery. Set by hand in the recovery only what you trust.
704
718
  **Every object the copy's Git metadata names is in it.** For the worktree's
705
719
  copy and for each nested repository's alike, the copier collects what the
706
720
  Git metadata it carries names: every commit the stash's log names (the new
707
- id of each entry, as `git log -g refs/stash` shows them), for a nested
721
+ id of each entry, as `git log -g refs/stash` shows them), the commit each of
722
+ `CHERRY_PICK_HEAD`, `REVERT_HEAD` and `REBASE_HEAD` names, every commit
723
+ `MERGE_HEAD` names (one per line), and the tree `AUTO_MERGE` names with the
724
+ trees and blobs under it that the copy lacks (a conflict's files are in no
725
+ commit), whether the copy took the ref as a file or wrote it, for a nested
708
726
  repository the commit of each of its local branches (its own `refs/heads`,
709
727
  including a branch its configuration hides from a clone) and every commit
710
728
  its `HEAD` and branch reflogs name, and every blob
@@ -715,8 +733,12 @@ the missing blobs by content (a staged blob or a resolved conflict's side
715
733
  can be in no commit), then checks the whole set again. An object the
716
734
  source cannot supply (a partial clone that lacks it: the retire never
717
735
  fetches from a promisor remote) refuses the copy with
718
- `E_WORK_PRESERVATION_FAILED`, naming it. So `git stash show stash@{2}` and
719
- `git checkout -m <path>` work in the copy as in the source. What the copier
736
+ `E_WORK_PRESERVATION_FAILED`, naming it. An operation's ref that names an
737
+ object the source itself lacks is copied as it is and names nothing in the
738
+ copy either; where that ref must be written (the reftable format), Git
739
+ refuses to write it, and so the copy is refused. So `git stash show
740
+ stash@{2}`, `git checkout -m <path>` and `git cherry-pick --continue` work in
741
+ the copy as in the source. What the copier
720
742
  cannot carry at all (an entry that is not a file, a directory or a symbolic
721
743
  link, or a nested repository whose path is not valid UTF-8) refuses the copy,
722
744
  here as anywhere.
@@ -1216,10 +1238,14 @@ retry. A relink that fails is a warning in the summary and the receipt's
1216
1238
  `warnings`, with the command to repoint the link by hand; the retire is not
1217
1239
  undone. A child that is not attached, whose link leads elsewhere, or that this
1218
1240
  retire did not stop is not touched. With `--discard-worktree` the worktree is
1219
- removed and an attached child's link dangles. The retire plan names the
1220
- attached children in one note that covers both cases. Only the link changes:
1241
+ removed and an attached child's link then points at a path that is gone: the
1242
+ summary and the receipt's `warnings` name each such child, the tree and the
1243
+ link. The retire plan names the attached children in one note that covers
1244
+ both cases. Only the link changes:
1221
1245
  the child's `instance.json` is not rewritten, and its AGENTS.md and TASK.md
1222
- still name the old path.
1246
+ still name the old path. A child attached to one of the home's extra trees
1247
+ is handled the same way, tree by tree
1248
+ ([extra trees at retire](#extra-trees-at-retire)).
1223
1249
 
1224
1250
  #### What `work/` is at retire
1225
1251
 
@@ -1366,6 +1392,38 @@ leaves `work/` untouched. For each tree:
1366
1392
  handled, and the message says what was done. `--force` does not bypass it:
1367
1393
  it forces past hook cleanup, not past local work.
1368
1394
 
1395
+ An instance can be attached to an extra tree as it can to `work/`
1396
+ ([`attached`](#attached--another-instances-tree)). The retire finds the
1397
+ attached children of every tree before it moves or removes any of them, among
1398
+ the recorded children it stopped and by the test it uses for `work/`:
1399
+
1400
+ - **Where the tree is re-homed**, each one's `work` link is repointed to the
1401
+ tree's new path, under the conditions `work/` has (the tree is seen at its
1402
+ new path, nothing is left at the old one, and the child's link is still the
1403
+ one that was found) and with the same warnings when it cannot be done. It
1404
+ is done right after that tree's move, not at the end of the retire: a later
1405
+ step can still refuse and keep the home, and the tree has left it either
1406
+ way.
1407
+ - **Where a clean tree is removed**, it is removed as any other, and the
1408
+ child's link then points at a path that is gone. The receipt's `warnings`
1409
+ and the summary name each such child, the tree and the link.
1410
+
1411
+ The plan's note for a tree names its attached children and says which of the
1412
+ two the retire would do. A retire that refuses after it has handled trees
1413
+ says, with the trees it handled, each warning it has about their attached
1414
+ children.
1415
+
1416
+ All of this is about the recorded children, for `work/` too. An attached
1417
+ instance that the plan lists under `ambiguous` (it records this instance as
1418
+ its parent under a name that is not unique) is not asked to stop, so the
1419
+ retire does not repoint its link, which then points at the path the tree
1420
+ has left. The retire says so. The plan's note for an extra tree names such
1421
+ instances in a clause of its own, and `work/` has a note of its own for
1422
+ them. The receipt's `warnings` name each one for every tree the retire moved
1423
+ or removed, with the command to repoint its link by hand where the tree was
1424
+ re-homed. The receipt of a `--self` retirement does not carry those
1425
+ warnings; its plan's notes are the same.
1426
+
1369
1427
  `--discard-worktree` applies to `work/` only: a tree that is not clean is
1370
1428
  always re-homed. The retire writes one workspace event per handled tree
1371
1429
  (`worktree-removed` or `worktree-retained`, with `extra: true` and the tree's
@@ -1594,16 +1652,56 @@ Rules:
1594
1652
  ### `attached` — another instance's tree
1595
1653
 
1596
1654
  `work/` points at **another instance's work tree** — same branch, same
1597
- uncommitted state. Spawning attached requires `workDir` (the owning
1598
- instance's `<home>/work`); it is a spawn-time choice (`--work attached`) for
1599
- service agents such as reviewers.
1655
+ uncommitted state. Spawning attached requires `workDir` (`--work-dir`): a
1656
+ tree in the owning instance's home, its `<home>/work` or one of its
1657
+ [extra trees](#extra-trees) (`<home>/.work-<purpose>`). It is a spawn-time
1658
+ choice (`--work attached`) for service agents such as reviewers.
1659
+
1660
+ The kernel derives the owner and the repository from the tree named on the
1661
+ command line, so the spawn needs no `--repo` and no relation flag (an extra
1662
+ tree from 0.57.0, #958):
1663
+
1664
+ ```text
1665
+ oats spawn <soul> --work attached --work-dir <home>/work
1666
+ oats spawn <soul> --work attached --work-dir <home>/.work-<purpose>
1667
+ ```
1668
+
1669
+ - **The owner** is the instance in whose home the tree is, and the new
1670
+ instance is its child. It must be an instance of the deployment the spawn
1671
+ runs in, and its name must resolve back to that home from there: a name
1672
+ that resolves to another instance is refused, since the parent link would
1673
+ be ambiguous. The parent is never read from the caller's environment.
1674
+ - **An attached instance's repository is the repository of the tree it is
1675
+ attached to.** For `<home>/work` that is the repository its owner
1676
+ recorded. For an extra tree it is the repository Git names for that tree,
1677
+ which can be another member repository than the owner's own
1678
+ (`oats worktree add --repo`).
1679
+ - `--parent <owner>` and `--repo <repository>` given explicitly are
1680
+ accepted. A relation that is not "child of the owner" is refused.
1681
+ - An extra tree is one by the kernel's test of it, the same one a retire
1682
+ uses ([extra trees at retire](#extra-trees-at-retire)): a linked worktree
1683
+ in the home that Git confirms is registered in a repository outside the
1684
+ home. The shape of the path decides nothing. A directory named `.work-x`
1685
+ that is not such a tree (a plain directory, a clone of its own, a tree of
1686
+ a repository inside the home, a tree whose registration was pruned) is a
1687
+ tree of no instance, and so is a path inside an extra tree.
1688
+ - **A tree of no known instance** (an integration worktree, for example)
1689
+ has nothing to derive from: the spawn needs `--parent <instance>` and
1690
+ `--repo <repository>`. One refusal (`E_BAD_ARGS`) names every one still
1691
+ missing, so one retry is enough.
1600
1692
 
1601
1693
  Attached agents are guests: never switch branches or rewrite history, touch
1602
1694
  only what the briefing names, keep commits small and attributable. Retiring
1603
1695
  an attached instance never removes the shared tree. When its owner retires
1604
- and the tree is re-homed, the attached instance's `work` link is repointed to
1605
- the tree's new path ([retire](#retire)); its AGENTS.md and TASK.md still name
1606
- the old one. The packaged
1696
+ and the tree is re-homed, `work/` or an extra tree, the `work` link of an
1697
+ instance attached to it is repointed to the tree's new path
1698
+ ([retire](#retire), [extra trees at retire](#extra-trees-at-retire)); its
1699
+ AGENTS.md and TASK.md still name the old one. When the retire removes the
1700
+ tree (a clean extra tree, or `work/` with `--discard-worktree`), the link
1701
+ then points at a path that is gone: the plan says so beforehand and the
1702
+ receipt's `warnings` afterwards, each naming the instance and the tree. The
1703
+ owner's `oats worktree remove` does not remove an extra tree while an
1704
+ instance attached to it is running ([extra trees](#extra-trees)). The packaged
1607
1705
  `work-attached` instruction source carries this discipline into each generated instance AGENTS.md.
1608
1706
 
1609
1707
  ### `directory` — independent execution
@@ -1769,6 +1867,23 @@ and nothing is removed. On a `creating` record whose process is gone, `remove`
1769
1867
  completes the rollback instead. Its answer then says whether the branch was
1770
1868
  kept (`branchKept`, `branchKeptReason`).
1771
1869
 
1870
+ `remove` does not remove a tree under a running session. An instance is
1871
+ attached to the tree when its `instance.json` says `work: "attached"` and its
1872
+ `work` is a link to it ([`attached`](#attached--another-instances-tree)).
1873
+ When such an instance's session is running, or cannot be read, `remove`
1874
+ refuses with `E_CHILDREN_RUNNING` before it asks Git anything: nothing is
1875
+ removed and the record is kept. The message names each such instance and
1876
+ what was seen (an unread session is not called running), and gives the step:
1877
+ stop it (`oats instance stop <instance>`) or retire it, then run `remove`
1878
+ again. `remove` stops nobody, and no flag removes the tree anyway. An
1879
+ attached instance whose session is stopped does not refuse: the tree is
1880
+ removed, and the answer's `warnings` name the instance and its `work` link,
1881
+ which then points at a path that is gone. The instances looked at are the
1882
+ recorded children of the tree's owner, as its retire plan lists them, and
1883
+ those the plan lists as `ambiguous` (they record the owner as their parent
1884
+ under a name that is not unique): the link makes an instance attached, not
1885
+ its lineage. A tree that is already gone from disk is not checked.
1886
+
1772
1887
  **Working in the tree.**
1773
1888
 
1774
1889
  - `git switch` needs Git 2.23 or later.