@awebai/oats 0.57.0 → 0.58.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 (60) hide show
  1. package/bin/oats.mjs +24 -11
  2. package/docs/configuration.md +19 -28
  3. package/docs/desktop-cli-api.md +38 -15
  4. package/docs/desktop.md +14 -0
  5. package/docs/execution-targets.md +10 -1
  6. package/docs/implementation.md +7 -1
  7. package/docs/integrations.md +3 -1
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-notes/v0.57.1.md +275 -0
  11. package/docs/release-notes/v0.58.0.md +107 -0
  12. package/docs/servers.md +18 -0
  13. package/docs/souls-and-instances.md +9 -0
  14. package/docs/tui.md +224 -87
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +11 -4
  17. package/lib/session-viewer.mjs +29 -4
  18. package/package-catalog.json +1 -1
  19. package/package.json +1 -1
  20. package/packages/client/cli-adapter.mjs +9 -7
  21. package/packages/client/cli-locator.mjs +2 -2
  22. package/packages/client/composed-gate.mjs +34 -0
  23. package/packages/client/inspect-boundary.mjs +157 -0
  24. package/packages/client/inspect-cache.mjs +86 -0
  25. package/packages/client/keyed-catalog.mjs +132 -0
  26. package/packages/client/launch-view.mjs +46 -0
  27. package/packages/client/panel-views.mjs +1 -1
  28. package/packages/client/session-attach.mjs +7 -5
  29. package/packages/client/soul-catalog.mjs +77 -0
  30. package/packages/client/soul-colors.mjs +31 -0
  31. package/packages/client/soul-facts.mjs +85 -0
  32. package/packages/client/soul-rows.mjs +48 -0
  33. package/packages/client/spawn-apply-cli.mjs +19 -8
  34. package/packages/client/spawn-apply.mjs +216 -0
  35. package/packages/client/spawn-messages.mjs +131 -85
  36. package/packages/client/spawn-preview-cli.mjs +2 -1
  37. package/packages/client/spawn-preview-contract.mjs +3 -0
  38. package/packages/client/spawn-preview-facts.mjs +119 -0
  39. package/packages/client/spawn-preview.mjs +164 -0
  40. package/packages/client/spawn-transaction.mjs +136 -0
  41. package/packages/record/lib/directory-identity.mjs +14 -0
  42. package/packages/record/lib/native-history.mjs +6 -5
  43. package/packages/tui/README.md +32 -11
  44. package/packages/tui/lib/actions.mjs +10 -1
  45. package/packages/tui/lib/config.mjs +9 -14
  46. package/packages/tui/lib/main.mjs +165 -57
  47. package/packages/tui/lib/model.mjs +28 -24
  48. package/packages/tui/lib/panel.mjs +1019 -0
  49. package/packages/tui/lib/read.mjs +5 -14
  50. package/packages/tui/lib/store.mjs +77 -30
  51. package/packages/tui/lib/term/capture.mjs +260 -0
  52. package/packages/tui/lib/term/screen.mjs +44 -8
  53. package/packages/tui/lib/term/style.mjs +78 -6
  54. package/packages/tui/lib/term/text.mjs +24 -4
  55. package/packages/tui/lib/term/through.mjs +213 -0
  56. package/packages/tui/lib/term/tty.mjs +7 -60
  57. package/packages/tui/lib/views/frame.mjs +126 -40
  58. package/packages/tui/lib/views/help.mjs +12 -10
  59. package/skills/oats-getting-started/SKILL.md +3 -2
  60. 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)).
@@ -0,0 +1,107 @@
1
+ # OATS 0.58.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.57 Desktop refuses a 0.58.0 CLI. The
9
+ 0.58.0 Desktop accepts OATS CLIs `>=0.26.0 <0.59.0`.
10
+
11
+ - **On a Mac, upgrade the CLI before the next reboot.** Up to 0.57.1, every
12
+ directory-mode instance refused `oats session start` after a macOS reboot
13
+ ("directory home was exchanged"). With 0.58.0 those homes start again, with
14
+ no edit, including homes spawned before the upgrade. A host that is already
15
+ stuck needs only the new CLI. See Fixed
16
+ ([#1261](https://github.com/awebai/oats/issues/1261)).
17
+
18
+ - **A client that drives `oats spawn` itself** may pass `--max-age` on an
19
+ apply bound by `--expect-decision`, when `oats version --json` lists
20
+ `spawn-apply-max-age`. An older kernel refuses the flag (`E_BAD_ARGS`). See
21
+ Added ([#1246](https://github.com/awebai/oats/issues/1246)).
22
+
23
+ - **The official catalog's versions are unchanged in this release:**
24
+ oats.framework 1.12.0, oats.okf 5.2.0, oats.aweb 1.27.3, oats.engineering
25
+ 1.10.0, oats.cloning 1.0.1, oats.authoring 1.0.3, oats.jira 1.0.1,
26
+ oats.linear 1.0.1 and oats.apps 1.0.0.
27
+
28
+ ## Added
29
+
30
+ - **`oats spawn … --expect-decision <revision> --max-age <seconds>`: a
31
+ confirmed spawn reuses its preview's observations** (feature
32
+ `spawn-apply-max-age`, [#1246](https://github.com/awebai/oats/issues/1246)).
33
+ An apply bound by `--expect-decision` now takes `--max-age`, as
34
+ `spawn --preview` already did: it reuses member heads this machine observed
35
+ at most that many seconds ago instead of asking each remote again, which
36
+ saves the apply's `git ls-remote` round (about 0.3–0.45 s). The decision is
37
+ computed from those heads, and one that differs from the confirmed revision
38
+ is still `E_DECISION_STALE`, with nothing created. `--max-age 0` is live, as
39
+ without the flag. The apply's answer is unchanged: it carries no
40
+ `observation` block. A spawn apply without `--expect-decision` still refuses
41
+ the flag (`E_BAD_ARGS`), now with a message that says so, and `--server`
42
+ still refuses it. A client passes the flag on an apply only when
43
+ `oats version --json` lists `spawn-apply-max-age`: an older kernel refuses
44
+ it ([Apply](../desktop-cli-api.md#apply)).
45
+
46
+ ## Changed
47
+
48
+ - **Desktop: a spawn no longer re-reads every member repository at the
49
+ press** ([#1246](https://github.com/awebai/oats/issues/1246)). With a
50
+ kernel that can reuse them, the Desktop's spawn lets the kernel use the
51
+ member repositories' heads it observed in the last minute instead of
52
+ reading each one again when you press Spawn. If the kernel then works out
53
+ a different spawn from what the dialog showed, the spawn is still refused
54
+ as before ("Something changed before the spawn went through…") and the
55
+ values are read again.
56
+
57
+ - **Desktop: a spawn reaches its terminal sooner**
58
+ ([#1246](https://github.com/awebai/oats/issues/1246)). Pressing Spawn no
59
+ longer runs a second spawn preview when the dialog has been open more than
60
+ a minute: the press uses the preview on screen for up to five minutes, and
61
+ if anything changed meanwhile the spawn is refused as before ("Something
62
+ changed before the spawn went through…") and the values are read again.
63
+ Once the spawn is created, the Desktop reads that one workspace at once
64
+ instead of waiting for its next full refresh, so the new instance's row and
65
+ terminal appear without the extra second or more.
66
+
67
+ - **Spawn preview and apply are about 0.4 s faster on Claude souls whose
68
+ capabilities require a Claude plugin**
69
+ ([#1246](https://github.com/awebai/oats/issues/1246)). The harness-package
70
+ check's probe, `claude plugin list --json`, now runs with
71
+ `DISABLE_TELEMETRY=1` set for its own run, so Claude no longer flushes
72
+ telemetry before it exits. The probe's answer, and so the check, is
73
+ unchanged; the launch, the install steps and every other probe run as
74
+ before ([The checks read the pane](../execution-targets.md#the-checks-read-the-pane)).
75
+
76
+ - **The Desktop accepts OATS CLIs `>=0.26.0 <0.59.0`**
77
+ ([#1261](https://github.com/awebai/oats/issues/1261)). The compatibility band
78
+ admits 0.58; a 0.57 Desktop refuses a 0.58 CLI. No new gate on the band.
79
+ `oats tui` runs the kernel it ships with and is held to the same band.
80
+
81
+ ## Fixed
82
+
83
+ - **A directory-mode instance starts again after a macOS reboot**
84
+ ([#1261](https://github.com/awebai/oats/issues/1261)). macOS gives a volume a
85
+ new device number each time it is mounted, so after every reboot
86
+ `oats session start` refused every directory-mode home with "directory home
87
+ was exchanged; restore the owned root before retrying start", although its
88
+ home and `work/` were the same directories. On macOS a start now accepts a
89
+ root whose inode matches the one the spawn recorded, and whose birth time
90
+ matches too when one was recorded. A spawn now records each root's birth
91
+ time; homes spawned earlier, whose baselines hold none, start with no edit.
92
+ A real exchange, another directory renamed into the home's or `work/`'s
93
+ place, is still refused with the same error, and Linux keeps comparing
94
+ device and inode. Captured Pi sessions on macOS had the same problem at the
95
+ next start after a reboot ("original Pi session directory was replaced");
96
+ the same rule now applies to their session directory
97
+ ([`directory` — independent execution](../souls-and-instances.md#directory--independent-execution)).
98
+
99
+ - **`oats tui`: an agent's terminal that ends says why again.** On tmux 3.2 to
100
+ 3.4, a terminal whose viewer ended at once, for example because the agent's
101
+ window had just gone, could close with the line that the viewer "ended
102
+ without saying why", and without the viewer's error output under it. The
103
+ cause: tmux reports a pane as dead a moment before it has the exit status.
104
+ The panel now waits for that status, for at most 10 seconds (2.5 seconds
105
+ on tmux 3.2), so the line and the viewer's error output show again
106
+ ([#855](https://github.com/awebai/oats/issues/855); see
107
+ [`oats tui`](../tui.md)).
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:
@@ -1721,6 +1721,15 @@ change to work is in the same recovery, under
1721
1721
  nothing needed preserving before the hooks). The work-root cannot be
1722
1722
  exchanged for a symlink. Recovery does not replace the worker's delivery protocol.
1723
1723
 
1724
+ A start refuses a directory home whose home or `work/` is no longer the
1725
+ directory the spawn recorded (`directory home was exchanged` or `directory work
1726
+ was exchanged`), for example when another directory was renamed into its
1727
+ place. The spawn records each root's device, inode and birth time. A root is
1728
+ the same directory when its device and inode match. On macOS, which gives a
1729
+ volume a new device number each time it is mounted (every reboot), an equal
1730
+ inode is enough, provided the birth time also matches when one was recorded
1731
+ (a home spawned by a kernel that recorded none is judged by the inode alone).
1732
+
1724
1733
  ### `workspace` — cross-repo coordinator
1725
1734
 
1726
1735
  `work/` is a symlink to the **whole deployment**: the directory holding