@awebai/oats 0.56.0 → 0.57.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/bin/oats.mjs +18 -10
  2. package/docs/configuration.md +17 -27
  3. package/docs/desktop-cli-api.md +59 -3
  4. package/docs/desktop.md +25 -4
  5. package/docs/execution-targets.md +6 -1
  6. package/docs/implementation.md +106 -5
  7. package/docs/integrations.md +8 -4
  8. package/docs/knowledge.md +93 -38
  9. package/docs/official-catalog.md +3 -3
  10. package/docs/packages.md +12 -12
  11. package/docs/release-notes/v0.57.0.md +283 -0
  12. package/docs/release-notes/v0.57.1.md +275 -0
  13. package/docs/schedules.md +8 -3
  14. package/docs/servers.md +18 -0
  15. package/docs/souls-and-instances.md +126 -15
  16. package/docs/tui.md +333 -95
  17. package/docs/workspaces.md +2 -2
  18. package/lib/core.mjs +439 -126
  19. package/lib/instance-lifecycle.mjs +45 -9
  20. package/lib/session-viewer.mjs +29 -4
  21. package/lib/worktree.mjs +23 -2
  22. package/package-catalog.json +2 -2
  23. package/package.json +1 -1
  24. package/packages/client/cli-adapter.mjs +9 -7
  25. package/packages/client/cli-locator.mjs +2 -2
  26. package/packages/client/composed-gate.mjs +34 -0
  27. package/packages/client/inspect-boundary.mjs +157 -0
  28. package/packages/client/inspect-cache.mjs +86 -0
  29. package/packages/client/instance-lifecycle.mjs +10 -3
  30. package/packages/client/keyed-catalog.mjs +132 -0
  31. package/packages/client/launch-prompt-outcome.mjs +1 -1
  32. package/packages/client/launch-view.mjs +46 -0
  33. package/packages/client/session-attach.mjs +7 -5
  34. package/packages/client/soul-catalog.mjs +77 -0
  35. package/packages/client/soul-colors.mjs +31 -0
  36. package/packages/client/soul-facts.mjs +85 -0
  37. package/packages/client/soul-rows.mjs +48 -0
  38. package/packages/client/spawn-apply-cli.mjs +11 -6
  39. package/packages/client/spawn-apply.mjs +212 -0
  40. package/packages/client/spawn-messages.mjs +131 -85
  41. package/packages/client/spawn-preview-contract.mjs +3 -0
  42. package/packages/client/spawn-preview-facts.mjs +119 -0
  43. package/packages/client/spawn-preview.mjs +152 -0
  44. package/packages/client/spawn-transaction.mjs +136 -0
  45. package/packages/tui/README.md +43 -13
  46. package/packages/tui/lib/actions.mjs +18 -2
  47. package/packages/tui/lib/client.mjs +4 -0
  48. package/packages/tui/lib/config.mjs +9 -14
  49. package/packages/tui/lib/main.mjs +241 -55
  50. package/packages/tui/lib/model.mjs +230 -29
  51. package/packages/tui/lib/panel.mjs +955 -0
  52. package/packages/tui/lib/read.mjs +134 -24
  53. package/packages/tui/lib/store.mjs +184 -31
  54. package/packages/tui/lib/term/capture.mjs +260 -0
  55. package/packages/tui/lib/term/screen.mjs +44 -8
  56. package/packages/tui/lib/term/style.mjs +78 -6
  57. package/packages/tui/lib/term/text.mjs +24 -4
  58. package/packages/tui/lib/term/through.mjs +213 -0
  59. package/packages/tui/lib/term/tty.mjs +7 -60
  60. package/packages/tui/lib/views/act.mjs +85 -0
  61. package/packages/tui/lib/views/frame.mjs +153 -37
  62. package/packages/tui/lib/views/help.mjs +22 -14
  63. package/skills/oats-getting-started/SKILL.md +4 -3
  64. package/packages/tui/lib/open.mjs +0 -45
@@ -0,0 +1,275 @@
1
+ # OATS 0.57.1
2
+
3
+ 2026-10-15
4
+
5
+ ## Upgrade
6
+
7
+ - **Either order of Desktop and CLI works:** a 0.57.0 Desktop accepts a
8
+ 0.57.1 CLI, and the other way round. The 0.57.1 Desktop accepts OATS CLIs
9
+ `>=0.26.0 <0.58.0`.
10
+
11
+ - **Upgrade the hosts a Desktop reaches over `--server`, too.** A routed
12
+ attach runs its viewer on the host, so the viewer fixes (it ends with the
13
+ agent's window under `detach-on-destroy off`, and a late hang-up no longer
14
+ leaves an `oatsview-*` session behind) hold for a remote terminal only once
15
+ that host runs 0.57.1. See Fixed
16
+ ([#1237](https://github.com/awebai/oats/issues/1237),
17
+ [#1243](https://github.com/awebai/oats/issues/1243)).
18
+
19
+ - **`oats tui`: the whole-screen open is gone.** `Enter` opens an agent's
20
+ terminal in a panel beside the list; `z` gives it the whole body. The panel
21
+ needs tmux 3.2 or later. `open.detachKey` in `tui.json` keeps its name and
22
+ the keys it accepts, and now means the back key to the list; a key outside
23
+ them is refused when `tui.json` is read. See Changed
24
+ ([#855](https://github.com/awebai/oats/issues/855)).
25
+
26
+ - **pi homes: run `oats update`** to move the `@awebai/oats-pi` bridge in
27
+ your pi folders to this release (by hand: see [Upgrading](../upgrading.md));
28
+ the kernel alone doesn't change it. A freshly spawned pi home then no
29
+ longer starts by "continuing" from an empty `STATE.md`. See Fixed
30
+ ([#1251](https://github.com/awebai/oats/issues/1251)).
31
+
32
+ - **To get the new framework skills,** pin `oats.framework: v1.12.0` in your
33
+ workspace and run `oats sync`: `/oats-host-delivery` and `/oats-git-setup`
34
+ in oats.setup 2.7.0. Instances already running keep what they were spawned
35
+ with. See Provider updates.
36
+
37
+ - **The official catalog's versions in this release** are oats.framework
38
+ 1.12.0, oats.okf 5.2.0, oats.aweb 1.27.3, oats.engineering 1.10.0,
39
+ oats.cloning 1.0.1, oats.authoring 1.0.3, oats.jira 1.0.1, oats.linear 1.0.1
40
+ and oats.apps 1.0.0.
41
+
42
+ ## Changed
43
+
44
+ - **A spawn runs in a process session of its own.** The `oats spawn` child of
45
+ a confirmed spawn now runs in a process session of its own, so a hang-up or
46
+ a Ctrl-C in the terminal that started the client does not reach a spawn
47
+ while its worktree hooks run. The deadline the confirmed preview implies
48
+ still interrupts it, and the kernel rolls it back.
49
+
50
+ - **`oats tui` opens an agent's terminal in a panel beside the list**
51
+ ([#855](https://github.com/awebai/oats/issues/855)). `Enter` on an
52
+ instance that runs shows its terminal where the detail was, with the list
53
+ still on screen and the focus in the terminal: everything you type goes to
54
+ the agent but the back key (`Ctrl+\`, or `open.detachKey` in `tui.json`),
55
+ which gives the focus to the list while the terminal stays open and live.
56
+ From the list, `Enter` on its row goes back to it, `z` gives it the whole
57
+ body and `c` closes it; `Enter` on another instance opens that one
58
+ instead. A terminal whose viewer ends closes with a line that says why,
59
+ and is never opened again by itself. **The whole-screen open of the
60
+ previous version is gone**: `z` replaces it. The viewer now runs in a tmux
61
+ server private to the run (tmux 3.2 or later), ended on every way out, a
62
+ `kill -9` of `oats tui` included; a later run removes what a killed one
63
+ left. `open.detachKey` keeps its name
64
+ and the keys it accepts, and now means the back key; a key outside them is
65
+ refused when `tui.json` is read, and an older OATS on another machine is
66
+ opened like a newer one. See [the TUI page](../tui.md#open-an-agents-terminal).
67
+ - **The header's second row reads as navigation:** `Instances Souls
68
+ Capabilities`, the open view in reverse video and the views not built yet
69
+ dim. The keys `1`, `2` and `3` are in the help, not beside the names, and
70
+ the footer names them as one hint, `1-3 views`; `2` and `3` say what to
71
+ run instead. Every frame is now one
72
+ synchronized update (`CSI ?2026h` … `CSI ?2026l`).
73
+
74
+ ## Fixed
75
+
76
+ - **Desktop: a team card's warning can be copied.** On the Teams board, the
77
+ text of a team's warning or blocking problem, with its fix, can be
78
+ selected and copied, and a click on that box no longer opens the team's
79
+ page. A click anywhere else on the card still opens it, and the card is
80
+ still one Tab stop.
81
+ - **Desktop: a Make default confirmation closes with the team's page.** A
82
+ confirmation opened on a team's page no longer stays open after Back, Esc,
83
+ a tab change or the team going away, and the Teams board updates again
84
+ when your instances change.
85
+ - **Desktop: a failed read shows on an open team page.** When the teams on
86
+ this computer can't be read, the open team's page says so in its card, in
87
+ the board's words, instead of showing facts that may be out of date.
88
+
89
+ - **Desktop: a retired instance's tabs close**
90
+ ([#1237](https://github.com/awebai/oats/issues/1237)). When a roster read
91
+ shows an instance retired, whether the Desktop, the CLI, another agent or
92
+ another machine retired it, every tab of that instance closes, in every
93
+ split. The next tab becomes active, and the focus moves only if it was in
94
+ a closed tab. A remote instance's tabs close only when its server answers
95
+ without it, never because the server can't be reached. Stopping an
96
+ instance still leaves its tab open, and an instance respawned under the
97
+ same name opens a new tab.
98
+ - **Desktop: a tab no longer shows another instance's terminal**
99
+ ([#1237](https://github.com/awebai/oats/issues/1237)). With tmux's
100
+ `detach-on-destroy off` in your configuration, retiring an instance moved
101
+ its tab to another session, often another tab's agent: the tab kept its
102
+ name, and what you typed went to that agent. The tab's terminal now ends
103
+ ("session ended") when its instance's window goes. Only the Desktop's own
104
+ viewer sessions are set this way; your global option and your own
105
+ sessions are untouched.
106
+
107
+ - **`oats session attach`: the viewer ends with the agent's window, even under
108
+ `detach-on-destroy off`**
109
+ ([#1237](https://github.com/awebai/oats/issues/1237)). When an attached
110
+ instance was retired, a tmux configured with `set -g detach-on-destroy off`
111
+ moved the viewer's client to another session, so the terminal went on
112
+ showing, and typing into, another agent. The viewer session now sets
113
+ `detach-on-destroy on` for itself alone, and the viewer ends as it does
114
+ under tmux's default. Your own sessions keep your setting. A routed attach
115
+ (`--server`) runs the viewer on the host, so this holds there once the host
116
+ runs this release. Remote Desktop terminals use that viewer.
117
+
118
+ - **`oats session attach`: a late hang-up no longer leaves the viewer session
119
+ behind** ([#1243](https://github.com/awebai/oats/issues/1243)). A hang-up,
120
+ termination or interrupt can reach `oats session attach` late, for example
121
+ under a wrapping shell or a terminal profile, where it arrives once the
122
+ wrapper has died and goes to the whole process group. If it arrived just
123
+ after the viewer's client had exited, or while the viewer was still being
124
+ prepared, it could end `oats` before its cleanup, or kill the cleanup's
125
+ tmux call, and leave the `oatsview-*` session (and a keyed viewer's key
126
+ table) on the agents' tmux server. `oats` now handles these signals from
127
+ before it creates the viewer until its cleanup has finished, and runs its
128
+ tmux calls outside its own process group, so the viewer is always removed.
129
+ Exit statuses are unchanged. A routed attach (`--server`) runs the viewer on
130
+ the host, so this holds there once the host runs this release.
131
+
132
+ - **pi: a freshly spawned home no longer starts by "continuing" from an empty
133
+ `STATE.md`**
134
+ ([#1251](https://github.com/awebai/oats/issues/1251)). At session start the
135
+ `@awebai/oats-pi` bridge sends the nudge "Read ./STATE.md … then continue
136
+ from STATE.md's Next section". It held the nudge back only while `STATE.md`
137
+ still held template text that no package writes any more, so every fresh
138
+ home got it, ahead of its opening task. A startup now gets the nudge only
139
+ when pi kept an earlier session of the home (pi keeps one once it holds a
140
+ message) and
141
+ `STATE.md` exists, whatever a knowledge capability seeded into it. Sessions
142
+ of an earlier instance with the same name, at the same path, don't count.
143
+ The bridge writes nothing in the home to tell. Run `oats update` to move
144
+ the bridge in your pi folders to this release (by hand: see
145
+ [Upgrading](../upgrading.md)); the kernel alone doesn't change it.
146
+
147
+ ## Provider updates
148
+
149
+ - **oats.framework 1.11.0: oats.setup 2.6.0. Onboarding now makes a host's two
150
+ delivery choices and checks them**
151
+ ([#1224](https://github.com/awebai/oats/issues/1224)).
152
+ - **Why.** A host could finish onboarding with `oats doctor` clean and still
153
+ have two problems nobody had chosen:
154
+ - its Claude homes ran in development channel mode, because
155
+ `claudeChannelMode` was unset;
156
+ - no host wake broker ran, so every joined team was poll-only, and Codex
157
+ and `delivery: session` homes were not woken at all.
158
+ - **A new skill, `/oats-host-delivery`,** is the one place that teaches both
159
+ choices. `/oats-workspace-config` now points to it, instead of holding
160
+ the approved-route steps itself:
161
+ - **Choice 1, Claude channel delivery:** the approved route (the
162
+ managed-settings file, `claudeChannelMode: approved`, the plugin in the
163
+ launch's `CLAUDE_CONFIG_DIR`, respawning homes, the banner check) as the
164
+ default for unattended hosts. The development fallback is written
165
+ explicitly, with its costs stated. Session delivery is the third
166
+ option.
167
+ - **Choice 2, the host wake broker:** when a host needs it (a joined
168
+ team, Codex, `delivery: session`); how the operator installs `aw wake
169
+ run` as a per-user systemd or launchd service, with `AW_WAKE_OATS_BIN`
170
+ and a `PATH` that reaches `oats`, `node` and `tmux`; the restart after an aw upgrade; the check (`aw wake status
171
+ --json`, and readiness free of `wake-daemon-*` and
172
+ `joined-team-poll-only`); and the false `wake-status-stale` of oats.aweb
173
+ 1.27.2 ([oats-aweb#116](https://github.com/awebai/oats-aweb/issues/116),
174
+ fixed in 1.27.3).
175
+ - **`/oats-onboarding`:**
176
+ - card 4 requires both choices to be made and recorded: the broker is
177
+ installed once aw meets its floor, before the first spawn;
178
+ - card 8 checks each recorded choice, and the hand-back records both;
179
+ - card 4 also requires Git that works without a terminal on a macOS
180
+ host that another machine drives, linking
181
+ [Git on a macOS host](../servers.md#git-on-a-macos-host).
182
+ - **`/oats-setup-model`** names both host facts and answers “why didn't my
183
+ agent wake”. `/oats-teams` reopens Choice 2 at a host's first joined
184
+ team.
185
+ - Instruction text and one new skill: there is no hook, command, schema or
186
+ provider contract change, and the capability floors are unchanged
187
+ (oats.setup `>=0.30.0`).
188
+ - A deployment gets it by pinning `oats.framework: v1.11.0` and running
189
+ `oats sync`. Instances already running keep the skills they were spawned
190
+ with.
191
+
192
+ - **oats.framework 1.11.1, oats.setup 2.6.1: `/oats-host-delivery` teaches
193
+ `oats aweb wake install` (oats.aweb 1.28.0)**
194
+ ([#1224](https://github.com/awebai/oats/issues/1224)).
195
+ - Choice 2 now leads with the oats.aweb 1.28.0 command: `--plan`,
196
+ `install`, `status`, `uninstall`, and rerunning `install` after an aw
197
+ upgrade.
198
+ - The hand-written systemd and launchd units remain as the fallback, for
199
+ older providers or an operator's own unit.
200
+ - It names the migration from the hand-written `ai.aweb.wake` unit that
201
+ oats.setup 2.6.0 taught: that unit carries no install marker, so `install`
202
+ refuses it with `E_WAKE_UNIT_CONFLICT`. Retire it with the printed steps,
203
+ then rerun.
204
+ - On macOS, `install` runs at the desktop login. Over ssh, `launchctl
205
+ bootstrap` can fail after the plist is written (`E_WAKE_UNIT`); rerun it
206
+ at the desktop.
207
+ - The broker is installed before onboarding card 6. From oats.aweb 1.28.0,
208
+ card 6's readiness fails without it for a soul with `delivery: session` or
209
+ a join.
210
+ - Choice 1 and the checks name the new readiness warning
211
+ `claude-channel-mode-default`, and the soul-scope broker check.
212
+ - Instruction text only; the floors are unchanged.
213
+ - A deployment gets it by pinning `oats.framework: v1.11.1` and running
214
+ `oats sync`. Instances already running keep the skills they were spawned
215
+ with.
216
+
217
+ - **oats.framework 1.12.0: oats.setup 2.7.0. A guided Git and GitHub setup
218
+ for a person who isn't a developer**
219
+ ([#1233](https://github.com/awebai/oats/issues/1233)).
220
+ - **Why.** OATS reads its workspace with Git, and agents commit as the
221
+ person who runs them, but nothing taught that person to set Git up. The
222
+ kernel never prompts: it reads `git:` references over `https://` with
223
+ the credential helper and runs ssh in batch mode. A host could reach
224
+ onboarding with no GitHub credentials for Git, no known `github.com`
225
+ host key, or commits that GitHub shows as Unverified.
226
+ - **A new skill, `/oats-git-setup`,** walks through it on macOS and
227
+ Linux. Each step says what to run, what you should see, and what to do
228
+ when you see something else:
229
+ - installing `git` and `gh`, and checking that `gh` has the flags the
230
+ steps use;
231
+ - one SSH key, registered on GitHub both as an authentication key and as
232
+ a signing key, with the admin scopes removed from gh's token again
233
+ afterwards;
234
+ - `gh auth setup-git` for `https://` remotes, and the first `ssh -T
235
+ git@github.com` checked against GitHub's published fingerprint;
236
+ - the identity, with an email verified on GitHub, and SSH commit signing;
237
+ - a DCO sign-off on every commit through a global `core.hooksPath` hook
238
+ that still runs each repository's own hooks;
239
+ - a check: SSH auth, a signed and signed-off commit that GitHub's API
240
+ reports as `verified: true`, and `gh auth status`.
241
+ - **The macOS credential helper.** On macOS, a Git process run without
242
+ `HOME` skips `~/.gitconfig` and uses the system file, where Homebrew's
243
+ Git sets `credential.helper osxkeychain`. That raised repeated keychain
244
+ popups on one host. The skill leaves credentials to gh and SSH, checks
245
+ which helper a Git without `HOME` would use, and says why it matters.
246
+ - **`/oats-onboarding`:** card 2, which makes the first Git reads, starts
247
+ with `/oats-git-setup` when the person's Git and GitHub setup is missing
248
+ or unchecked. `/oats-setup-model` and
249
+ `/oats-workspace-config` name where these facts live.
250
+ - Instruction text and one new skill: there is no hook, command, schema or
251
+ provider contract change, and the capability floors are unchanged
252
+ (oats.setup `>=0.30.0`).
253
+ - A deployment gets it by pinning `oats.framework: v1.12.0` and running
254
+ `oats sync`. Instances already running keep the skills they were spawned
255
+ with.
256
+
257
+ ## Documentation
258
+
259
+ - [Configuration](../configuration.md), “Claude channel delivery: the approved
260
+ route”:
261
+ - an unset `claudeChannelMode` is development mode, so set it explicitly;
262
+ - the host wake broker is the other host delivery choice;
263
+ - the operator's procedure for both is oats.setup's `/oats-host-delivery`
264
+ ([#1224](https://github.com/awebai/oats/issues/1224)).
265
+ - [Servers](../servers.md), “Git on a macOS host”, adds four things:
266
+ - which remedy applies to an `https://` remote and which to a
267
+ `git@github.com:` one;
268
+ - that SSH commit signing has the same requirement;
269
+ - the `--insecure-storage` trade-off;
270
+ - when to set it up, and how to verify it from a session without a
271
+ terminal ([#1224](https://github.com/awebai/oats/issues/1224)).
272
+
273
+ - [Servers](../servers.md), “Git on a macOS host”, points to `/oats-git-setup`
274
+ for the person's whole Git and GitHub setup
275
+ ([#1233](https://github.com/awebai/oats/issues/1233)).
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
@@ -146,6 +146,24 @@ login agent in the shell's startup file (for zsh, `~/.zshenv`, which
146
146
  non-interactive sessions read). OATS never reads or changes credentials
147
147
  itself; the hint is about where Git ran, not a probe of the keychain.
148
148
 
149
+ - **Which remedy applies depends on the remote.**
150
+ - An `https://` remote is read through the credential helper: gh's token.
151
+ - A `git@github.com:` remote is read through the SSH key. Its
152
+ `UseKeychain yes` works only in the desktop session.
153
+ - SSH commit signing (`gpg.format=ssh`) reaches its key the same way, so it
154
+ has the same requirement.
155
+ - **The trade-off.** `--insecure-storage` keeps gh's token in gh's own
156
+ configuration file, protected by file permissions instead of the keychain.
157
+ The machine's operator makes that choice.
158
+ - **When to set it up.** At onboarding (`/oats-onboarding` card 4), on a Mac
159
+ that another machine will drive (`oats server add`), or that runs Git from
160
+ background jobs. The person's whole Git and GitHub setup, including the
161
+ system `osxkeychain` helper a Git without `HOME` falls back to, is
162
+ oats.setup's `/oats-git-setup`.
163
+ - **Verify** from a session without a terminal: `ssh <host> git ls-remote
164
+ <workspace remote> HEAD`, or `oats server check <id>` from the driving
165
+ machine.
166
+
149
167
  ## Connections
150
168
 
151
169
  Every routed ssh call carries these options, before `--` and the host:
@@ -402,7 +402,9 @@ sugar for `--relative-to <instance> --relation child`):
402
402
  `oats status --json` (`parentInstance` + `siblingInstance` edges).
403
403
  - **unrelated** (default): no link, operator-origin, top-level.
404
404
 
405
- 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)),
406
408
  because an attached agent serves that owner; relation flags other than a
407
409
  redundant child-of-owner are rejected. Any other spawn, including one from a
408
410
  shell that inherited an agent's environment variables, is operator-origin and
@@ -554,8 +556,16 @@ parses it, so it copies the files Git reads:
554
556
  - what the copy takes from the Git directories as files, each with its bytes
555
557
  and its permission bits: the state of an operation in progress (a merge, a
556
558
  rebase, a cherry-pick, a revert, a bisect), `info/attributes` and the
557
- stash's log;
558
- - 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;
559
569
  - its exclude rules (`core.excludesFile` with the file the copy reads for it,
560
570
  and `info/exclude`) and the settings that change what `git status` reports
561
571
  (`core.fileMode`, `core.ignoreCase`, `core.precomposeUnicode`,
@@ -708,7 +718,11 @@ Git in the recovery. Set by hand in the recovery only what you trust.
708
718
  **Every object the copy's Git metadata names is in it.** For the worktree's
709
719
  copy and for each nested repository's alike, the copier collects what the
710
720
  Git metadata it carries names: every commit the stash's log names (the new
711
- 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
712
726
  repository the commit of each of its local branches (its own `refs/heads`,
713
727
  including a branch its configuration hides from a clone) and every commit
714
728
  its `HEAD` and branch reflogs name, and every blob
@@ -719,8 +733,12 @@ the missing blobs by content (a staged blob or a resolved conflict's side
719
733
  can be in no commit), then checks the whole set again. An object the
720
734
  source cannot supply (a partial clone that lacks it: the retire never
721
735
  fetches from a promisor remote) refuses the copy with
722
- `E_WORK_PRESERVATION_FAILED`, naming it. So `git stash show stash@{2}` and
723
- `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
724
742
  cannot carry at all (an entry that is not a file, a directory or a symbolic
725
743
  link, or a nested repository whose path is not valid UTF-8) refuses the copy,
726
744
  here as anywhere.
@@ -1220,10 +1238,14 @@ retry. A relink that fails is a warning in the summary and the receipt's
1220
1238
  `warnings`, with the command to repoint the link by hand; the retire is not
1221
1239
  undone. A child that is not attached, whose link leads elsewhere, or that this
1222
1240
  retire did not stop is not touched. With `--discard-worktree` the worktree is
1223
- removed and an attached child's link dangles. The retire plan names the
1224
- 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:
1225
1245
  the child's `instance.json` is not rewritten, and its AGENTS.md and TASK.md
1226
- 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)).
1227
1249
 
1228
1250
  #### What `work/` is at retire
1229
1251
 
@@ -1370,6 +1392,38 @@ leaves `work/` untouched. For each tree:
1370
1392
  handled, and the message says what was done. `--force` does not bypass it:
1371
1393
  it forces past hook cleanup, not past local work.
1372
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
+
1373
1427
  `--discard-worktree` applies to `work/` only: a tree that is not clean is
1374
1428
  always re-homed. The retire writes one workspace event per handled tree
1375
1429
  (`worktree-removed` or `worktree-retained`, with `extra: true` and the tree's
@@ -1598,16 +1652,56 @@ Rules:
1598
1652
  ### `attached` — another instance's tree
1599
1653
 
1600
1654
  `work/` points at **another instance's work tree** — same branch, same
1601
- uncommitted state. Spawning attached requires `workDir` (the owning
1602
- instance's `<home>/work`); it is a spawn-time choice (`--work attached`) for
1603
- 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.
1604
1692
 
1605
1693
  Attached agents are guests: never switch branches or rewrite history, touch
1606
1694
  only what the briefing names, keep commits small and attributable. Retiring
1607
1695
  an attached instance never removes the shared tree. When its owner retires
1608
- and the tree is re-homed, the attached instance's `work` link is repointed to
1609
- the tree's new path ([retire](#retire)); its AGENTS.md and TASK.md still name
1610
- 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
1611
1705
  `work-attached` instruction source carries this discipline into each generated instance AGENTS.md.
1612
1706
 
1613
1707
  ### `directory` — independent execution
@@ -1773,6 +1867,23 @@ and nothing is removed. On a `creating` record whose process is gone, `remove`
1773
1867
  completes the rollback instead. Its answer then says whether the branch was
1774
1868
  kept (`branchKept`, `branchKeptReason`).
1775
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
+
1776
1887
  **Working in the tree.**
1777
1888
 
1778
1889
  - `git switch` needs Git 2.23 or later.