@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,699 @@
1
+ # OATS 0.56.0
2
+
3
+ 2026-10-14
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.55 Desktop refuses a 0.56.0 CLI. The
9
+ 0.56.0 Desktop accepts OATS CLIs `>=0.26.0 <0.57.0`; a CLI of the 0.25 line
10
+ is no longer accepted. `oats update` now prints this order itself when it
11
+ installs a CLI of another minor.
12
+
13
+ - **A script that matched `E_HARNESS_PACKAGE`** matches
14
+ `E_HARNESS_RESOURCE_MISSING` now. **A script or capability that read
15
+ `E_SPAWN_FAILED` from `oats spawn` as "the spawn failed"** now gets the
16
+ kernel's own code: match on the exit status or on `ok: false` instead, and
17
+ read `details.unconfirmed` for how far a spawn got. See Changed
18
+ ([#1047](https://github.com/awebai/oats/issues/1047)).
19
+
20
+ - **A `tui.json` that names the action `open-workspace`** is refused with
21
+ `open-workspace is called open now; rename it`: rename it to `open`. See
22
+ Added ([#855](https://github.com/awebai/oats/issues/855)).
23
+
24
+ - **To get the new provider versions,** pin `oats.framework: v1.10.1` and
25
+ `oats.okf: v5.1.0` in your workspace and run `oats sync`. oats.okf 5.1.0
26
+ needs OATS 0.49.0 or later: upgrade the kernel first, then re-spawn your
27
+ harvesters for the new hook. Instances already running keep what they were
28
+ spawned with. See Provider updates.
29
+
30
+ - **The official catalog's versions in this release** are oats.framework
31
+ 1.10.1, oats.okf 5.1.0, oats.aweb 1.27.3, oats.engineering 1.10.0,
32
+ oats.cloning 1.0.1, oats.authoring 1.0.3, oats.jira 1.0.1, oats.linear 1.0.1
33
+ and oats.apps 1.0.0.
34
+
35
+ - **A launch now gets exactly its capabilities' declared environment**
36
+ ([#1123](https://github.com/awebai/oats/issues/1123)). An instance that
37
+ relied on an ambient value of a variable one of its capabilities declares
38
+ (in the tmux server's or the session's environment, the login shell's, the
39
+ Desktop's) and that the capability's hooks do not return now starts without
40
+ it. Nothing is required of you. An ambient value set before stays in the
41
+ tmux environment until the server or the session is recreated, but no
42
+ longer reaches a launch whose capabilities declare it; an instance already
43
+ running keeps the environment it started with until it is restarted. To
44
+ clear a stale value: `tmux -L oats set-environment -t <session> -u NAME`
45
+ for a session, `tmux -L oats set-environment -g -u NAME` for the server,
46
+ or recreate the server; then restart the affected instances.
47
+
48
+ ## Added
49
+
50
+ - **Feature `spawn-kernel-codes` (#1047).** `oats spawn` answers the
51
+ kernel's own code; a kernel without the word may answer `E_SPAWN_FAILED`
52
+ where a kernel code was raised. See
53
+ [spawn errors](../desktop-cli-api.md#spawn-errors).
54
+
55
+ - The Desktop's [Install](../desktop.md#install) section states what Linux the installers need: glibc 2.34 or later (for example Ubuntu 22.04, Debian 12, RHEL 9 or later), and the Linux installer build fails when any file of the DEB or the AppImage needs a newer glibc, GLIBCXX or CXXABI than that.
56
+
57
+ - **Desktop: the Start and Restart dialog offers the bare harness**
58
+ ([#1079](https://github.com/awebai/oats/issues/1079)). The Launch
59
+ configuration list has a second entry, "No launch configuration (the harness
60
+ as installed)". It runs the harness itself, with no configuration's
61
+ executable, arguments or environment, and without the default configuration
62
+ the host declares for that harness. The Harness list stays usable with it:
63
+ alone it starts the recorded harness bare, and beside a picked harness, that
64
+ one. "Preview invocation" shows the same choice. It is what
65
+ `--launch-config none` does on the command line.
66
+ - **For an instance on a server** the entry is offered only when the host
67
+ is known to read it: a host on OATS 0.49.0 or later, read through an OATS
68
+ here that relays the hosts' feature lists. On an older host, pick a
69
+ configuration, or use the command line there.
70
+ [Starting an existing instance](../desktop-instance-start.md) has the
71
+ whole of it.
72
+
73
+ - **`oats server roster --workspace-key <key>`** (feature
74
+ `roster-workspace-key`, repeatable) probes and returns only the groups that
75
+ can belong to the given workspaces: a registration recorded for one of
76
+ them, a registration whose workspace is not known yet, and a server known
77
+ only from saved routes, which is always probed because its workspace is
78
+ unknown. A host registered for another workspace is not asked, so a
79
+ switched-off host no longer delays the roster of every other workspace's
80
+ window. The answer's shape is unchanged; without the flag it is exactly as
81
+ before. A key is compared exactly with the registration's `workspaceKey`;
82
+ an empty, missing or malformed value is `E_BAD_ARGS`
83
+ ([the flag](../desktop-cli-api.md#roster-workspace-key),
84
+ [#1124](https://github.com/awebai/oats/issues/1124)).
85
+
86
+ - **Forget… on an instance its server no longer lists.** In the Desktop, a
87
+ remote instance that is gone from its server now offers **Forget…** in its
88
+ roster row's actions menu and in the context panel. After a confirmation,
89
+ the Desktop runs `oats server forget <server> --instance <instance>` for
90
+ that row, which removes only this computer's saved route and nothing on the
91
+ server, then reads the roster again. Before, the only remedy was to type
92
+ that command
93
+ ([`oats server forget --json`](../desktop-cli-api.md#forget-a-saved-route-oats-server-forget---json),
94
+ [#1131](https://github.com/awebai/oats/issues/1131)).
95
+
96
+ - **A soul's own skills on its soul page.** In the Desktop, the soul page's
97
+ Instructions card has a Skills group between "This soul" and "Instance": each
98
+ skill from the soul's own `skills/` (not those its capabilities bring), with
99
+ its description, expands to its files, and each file reads in place under its
100
+ repository path, through the same strict reader as a capability's Contents.
101
+ The Desktop asks only a CLI that reports them (feature `soul-skills`,
102
+ `oats inspect --soul <name> --skills`), and for a soul on another machine
103
+ only when that host reports them too; otherwise the group says this OATS
104
+ doesn't report a soul's skills.
105
+
106
+ - **A soul's own skills, before a spawn.** `oats inspect --soul <soul>
107
+ --skills --json` adds `souls[0].skills`: the skills a spawn of the soul
108
+ copies (not its capabilities' skills), each with its `description` and
109
+ every file's text, by the rules of `oats capabilities show`. The whole
110
+ field carries at most 1 MiB of text; the files past that are listed with
111
+ `omitted: true`. Nothing is read without the flag. No symbolic link is
112
+ followed, and a skill whose files cannot all be listed and read has
113
+ `files: null` with a problem. `--skills` combines with `--instructions`,
114
+ refuses `--home`, and is routed with `--server` to a host that advertises
115
+ the new feature `soul-skills`
116
+ ([`oats inspect`](../desktop-cli-api.md#oats-inspect---home-----soul----dir----json--operationsapi-2),
117
+ [#1144](https://github.com/awebai/oats/issues/1144)).
118
+
119
+ - **`oats tui` opens an agent's terminal**
120
+ ([#855](https://github.com/awebai/oats/issues/855)). `Enter` on an
121
+ instance that runs, on this machine or on a registered one, gives your
122
+ terminal to the agent through `oats session attach`; `Ctrl+\` brings
123
+ `oats tui` back and the agent keeps running. `tui.json`'s
124
+ `open.detachKey` changes the key. After the return one line says what
125
+ happened, and `Enter` on an instance that cannot be opened says why. An
126
+ agent on a machine whose OATS is older than 0.51.0 is not opened: it has
127
+ no key to leave a viewer. The action `open-workspace` is now `open`, and a
128
+ `tui.json` that names `open-workspace` is refused with
129
+ `open-workspace is called open now; rename it`.
130
+
131
+ ## Changed
132
+
133
+ - **`oats retire --server` prints the receipt's warnings
134
+ ([#1006](https://github.com/awebai/oats/issues/1006)).** The routed
135
+ retire's text (without `--json`) printed the recovery and extra-tree lines
136
+ of the host's receipt and none of its `warnings`. It now prints them as a
137
+ local retire does, one `WARNING:` line each, after the extra-tree lines:
138
+ what a retire left an attached child with, which repository it read from
139
+ Git, where a link at `work/` led. The JSON is relayed as it was.
140
+ - **More text lines spell what a terminal would act on
141
+ ([#1006](https://github.com/awebai/oats/issues/1006)).** The `note:`
142
+ lines of `oats retire --plan`, `oats instance stop --plan`,
143
+ `oats instance git` and `oats readiness`; the `WARNING:` lines of
144
+ `oats spawn` (local and with `--server`), of the `oats session` commands
145
+ and of `oats doctor`; and the retire's recovery and extra-tree lines, local
146
+ and with `--server`, spell a control character (an escape, a newline), a
147
+ line separator or a bidi override as `\u{<hex>}`, as the local retire's
148
+ warnings have since 0.53.0. A line that holds no such character is printed
149
+ as it was. No JSON answer changes. See
150
+ [Text output](../desktop-cli-api.md#text-output).
151
+
152
+ - **`oats spawn` answers the kernel's own code (#1047).** Apply and
153
+ `--preview`, text and `--json`: an error with a kernel code is answered
154
+ with that code, as the lifecycle commands have done since 0.52.0, and
155
+ `E_SPAWN_FAILED` is what an error with no kernel code is answered with,
156
+ with `details.cause` for one that has a system code or is a defect (its
157
+ stack on stderr). Until now the spawn's kernel stage passed a list of
158
+ codes and answered every other one as `E_SPAWN_FAILED`, so a refusal with
159
+ a remedy, such as a missing harness package (`E_HARNESS_RESOURCE_MISSING`)
160
+ or a tmux server that cannot be read (`E_RUNTIME_ENDPOINT_UNKNOWN`),
161
+ reached a client as a failure of the spawn mechanism. An operator's script
162
+ or a capability that matched `E_SPAWN_FAILED` to mean "the spawn failed"
163
+ now sees the specific code: match on the command's exit status, or on
164
+ `ok: false`, to mean "it failed". A code is not a stable signal of how far
165
+ a spawn got: `details.unconfirmed` is. The details of each code are what
166
+ they were: a code that carried details keeps exactly those, and every
167
+ other one carries the error's details only when `unconfirmed` is true. In
168
+ text mode an error with no kernel code that a spawn meets outside its
169
+ kernel stage prints `oats: <message>` where it printed Node's trace (a
170
+ defect still prints its stack on stderr). See
171
+ [spawn errors](../desktop-cli-api.md#spawn-errors).
172
+ - **The harness-package gate has one name, `E_HARNESS_RESOURCE_MISSING`
173
+ (#1047).** A start or a restart refused for a missing harness package
174
+ answers `E_HARNESS_RESOURCE_MISSING` where it answered
175
+ `E_HARNESS_PACKAGE`, and so does the `harness-packages` check of a launch
176
+ plan (`oats launch-config preview`); the message is unchanged, and a spawn
177
+ answers the same code. A script that matched `E_HARNESS_PACKAGE` matches
178
+ `E_HARNESS_RESOURCE_MISSING` now. A preview in which the gate itself
179
+ faults (an error that is no verdict on a package) now fails as a fault,
180
+ where it showed a row that called the fault a missing package.
181
+
182
+ - **Every retire plan has a new `planRevision`, once (#1065).** A retire
183
+ plan's revision now binds everything the plan shows, except the facts
184
+ that move by themselves, in every home (the defect is under Fixed). So a
185
+ plan read under an older kernel is stale under this one: its guarded apply is refused
186
+ with `E_PLAN_STALE` and the fresh plan in `details.plan`, nothing is
187
+ stopped, run or removed, and the person confirms again. The revision's
188
+ form is unchanged (24 lowercase hex characters), a client treats it as
189
+ opaque as before, and there is no feature word and no change of
190
+ `lifecycleApi`. A repeated apply with the idempotency key of a retire
191
+ that did run is answered from its stored receipt as before, whatever
192
+ revision it carries. A changed recovery exclusion changes the revision:
193
+ the declared roots a recovery leaves out are part of it, as the spawn's
194
+ receipt gives them, where since 0.42.0 they changed the plan's note and
195
+ not its revision. A stop plan's revision is unchanged. See [the retire
196
+ plan](../desktop-cli-api.md#retire-revision-work), which also names what
197
+ is left out of the revision and why.
198
+ - **A guarded retire after the record was rewritten is refused as stale
199
+ (#1065).** These went through, or were refused late, on a plan that no
200
+ longer said what the kernel read:
201
+ - with nothing at `work/`, a plan read under a record that said
202
+ `worktree` and applied after the record said `attached` went through;
203
+ - a plan applied after the record's `branch` was rewritten went through;
204
+ - a plan applied after the record's `repo` was rewritten to a path that
205
+ is no repository was refused only after the retire hooks had run
206
+ (`E_WORK_PRESERVATION_FAILED`).
207
+
208
+ Each is now `E_PLAN_STALE` with the fresh plan, before anything runs.
209
+ Where such an apply was refused for the retire's own reason before
210
+ anything ran (`E_WORK_INSPECTION_FAILED`: a file at `work/`; an own tree,
211
+ or a link, under a record rewritten to `directory`), the answer is now
212
+ `E_PLAN_STALE` first, and the fresh plan's revision meets that refusal as
213
+ before.
214
+
215
+ - A failed or unparseable Git version probe now refuses the remote read with
216
+ `E_REMOTE_UNREADABLE` and an existing reason instead of falling back to a
217
+ whole-tree fetch. Only a successfully parsed version below Git 2.45 triggers
218
+ a version-driven rebuild of a partial cache. Existing full caches stay full.
219
+
220
+ - **Desktop: the Start and Restart dialog says in its own words a start that
221
+ OATS refuses for want of a configuration**
222
+ ([#1079](https://github.com/awebai/oats/issues/1079)). When OATS refuses a
223
+ start or a restart with `E_LAUNCH_CONFIG_AMBIGUOUS` (the start names a
224
+ harness and no configuration, several configurations are declared for that
225
+ harness, and none is the default), the dialog's status reads "More than one
226
+ launch configuration is declared for the chosen harness, and none is the
227
+ default. Choose one under Launch configuration, or choose "No launch
228
+ configuration" to run the harness as installed.", and under it "OATS says:
229
+ `<message>`" as one line, in place of OATS's message, written in
230
+ command-line flags, as the status. A message that looks like a credential
231
+ reads "[withheld]", with no name before it.
232
+ - **"Preview invocation"** refused with that code reads the same sentence,
233
+ then "Preview only. No agent was started or stopped.", with OATS's line
234
+ under it. That refusal's message is no longer cut at 300 characters.
235
+ - **Unchanged:** every other refusal of a start, a restart or a preview
236
+ reads as before, and after any refusal Start is offered again once
237
+ "Refresh status" is pressed.
238
+
239
+ - Roster rows whose state is unknown now stand after the running rows and
240
+ before the stopped ones, in a fixed order by name, where they used to keep
241
+ the order the read gave them.
242
+
243
+ - **The Desktop no longer accepts an OATS CLI of the 0.25 line: it accepts
244
+ `>=0.26.0 <0.57.0`.** A 0.25 kernel is told so once, in the card
245
+ "Compatible `oats` CLI required", with its version and the required range,
246
+ where it was told at each workspace and deployment read to update OATS.
247
+
248
+ - **Desktop: an OATS Desktop older than the installed `oats` CLI says so, and
249
+ offers no downgrade** ([#1107](https://github.com/awebai/oats/issues/1107)).
250
+ When the CLI it finds is a released version above the range the Desktop
251
+ works with (usually because the CLI was updated first), the card reads "This
252
+ Desktop is older than the installed `oats` CLI" and names the OATS Desktop
253
+ version to install. It no longer offers `npm install -g @awebai/oats@<the
254
+ Desktop's version>`, which would have downgraded the CLI. **Choose oats…**,
255
+ **Retry** and the docs link stay, and reads and terminals keep working
256
+ meanwhile. For a CLI below the range, a prerelease, or any other refusal, the
257
+ card is as before. [OATS Desktop](../desktop.md#troubleshooting) has the
258
+ card's states.
259
+
260
+ - `oats update` now says, in one line under its steps, that the Desktop goes
261
+ first when its plan installs a CLI of another minor or major version: `OATS
262
+ Desktop refuses a CLI newer than its own minor version: if you use it,
263
+ install OATS Desktop <version> first.` It prints the line with `--check`,
264
+ before it asks, and without a terminal. A patch update, or a prerelease to
265
+ its own release, prints nothing. Nothing detects an installed Desktop, so
266
+ the line also shows on hosts without one ([Upgrading](../upgrading.md#the-steps),
267
+ [#1107](https://github.com/awebai/oats/issues/1107)).
268
+
269
+ - Direct callers of `lib/remote.mjs` must select `displayRepoRef` for
270
+ repository-reference display or `displayDiagnosticText` for kernel-authored
271
+ diagnostic prose; Git lines continue to use `scrubGitLine`. The implicit
272
+ `redactUrl` export is removed without a compatibility shim. These entries
273
+ share the existing private renderer and preserve diagnostic output and
274
+ disclosure rules. `lib/remote.mjs` is not in the package export map; this
275
+ migration affects internal and direct-module callers. See the
276
+ [entry-point signatures](../implementation.md#remote-diagnostic-display).
277
+
278
+ - With an OATS CLI that lists `roster-workspace-key`, the Desktop's roster read
279
+ contacts only the machines of the workspaces its windows show, plus those
280
+ whose workspace is not known yet and those known only from a saved route. A
281
+ machine registered for another workspace is no longer contacted, so one
282
+ that is switched off no longer slows every window's roster. Opening a window
283
+ on another workspace reads its machines at once; with an older CLI every
284
+ machine is read, as before ([Which machines the Desktop
285
+ reads](../desktop.md#a-workspaces-machines),
286
+ [#1124](https://github.com/awebai/oats/issues/1124)).
287
+
288
+ - **The Desktop's Forget… runs only for an instance the last roster read
289
+ showed gone from its server
290
+ ([#1170](https://github.com/awebai/oats/issues/1170)).**
291
+
292
+ - **The Desktop accepts OATS CLIs `>=0.26.0 <0.57.0`**
293
+ ([#1188](https://github.com/awebai/oats/issues/1188)). The compatibility band
294
+ admits 0.56; a 0.55 Desktop refuses a 0.56 CLI. No new gate on the band.
295
+ `oats tui` runs the kernel it ships with and is held to the same band.
296
+
297
+ - **`oats spawn --server <id> --preview --json` no longer carries
298
+ `snapshot`.** The field named a saved-route file that a preview should never
299
+ have written. The answer is now the server's preview plus `server` and
300
+ `target`, the two fields a routed spawn adds
301
+ ([servers.md](../servers.md#run-there)).
302
+
303
+ - The context panel offers Stop for a stopped instance and for one whose state is unknown, as the roster menu does. Stop also stops an instance's children, so it is how a stopped parent's running children are stopped. When it offers no lifecycle action, as for an instance its server does not report addressable, it says why.
304
+
305
+ - A stop, retire or start runs in a process session of its own, so neither closing the Desktop nor interrupting the terminal that started it interrupts it. When a stop or retire takes longer than ten minutes, the Desktop stops waiting and says the result is not confirmed; the command keeps running, and Check again reads its result. When a start or restart takes longer than 60 seconds, the Desktop stops waiting and says the start is not confirmed; the start keeps running, and the roster shows its result. Another stop or retire asked meanwhile names the one still running.
306
+
307
+ - When the Desktop cannot run the OATS CLI for a start or restart, the dialog now says the start could not be confirmed and to refresh the instance's status, instead of showing the system's error.
308
+
309
+ - **A launch whose harness package cannot be checked in its pane's account
310
+ is refused, where it passed before
311
+ ([#993](https://github.com/awebai/oats/issues/993)).** The check of a
312
+ required harness package now runs with the `PATH`, `HOME` and harness
313
+ folder the launch's tmux pane will have. When a server runs and one of
314
+ those cannot be read from it, a spawn or a start whose capabilities require
315
+ a package is refused before anything is probed. That first check comes
316
+ before anything is created. A spawn whose pane differs from the one it
317
+ checked (another creator started the server first) checks again on the
318
+ pane it got, once its home, work and hooks exist, and a refusal there rolls
319
+ the spawn back. The case that
320
+ passed until now: a launch configuration that declares an absolute
321
+ `executable`, in a session whose `PATH` is cleared or cannot be read as
322
+ data. A launch with no package requirement is not affected.
323
+ - **What you do:** the message names the name, where it was read and what
324
+ makes it readable. Either set that name in the launch configuration's
325
+ `env`, or give the session or the server a value OATS can read (`tmux -L
326
+ oats set-environment -g PATH <value>`), or start the OATS tmux server
327
+ from your own shell.
328
+ - **The code** is `E_RUNTIME_ENDPOINT_UNKNOWN` at `oats spawn`,
329
+ `oats session start` and `restart`, and in a preview's
330
+ `harness-packages` item, with the same message
331
+ ([#1047](https://github.com/awebai/oats/issues/1047)).
332
+ - **`oats harness trust` writes for the file launches read, and refuses when
333
+ it cannot tell which.** Its ambient file is the one a launch with no launch
334
+ configuration reads: the server's or the session's `CLAUDE_CONFIG_DIR` or
335
+ `CODEX_HOME`, else the default file under their `HOME`, where it was the
336
+ operator's own shell's before. `--plan` shows the file and what selects
337
+ it. With no server running it is the operator's own, as before, and
338
+ `warnings` says so. When a server runs and its environment cannot be read,
339
+ or tmux could not say whether one runs (`tmux -L oats list-sessions`
340
+ refused or cut off),
341
+ nothing is written and the answer is `E_RUNTIME_ENDPOINT_UNKNOWN`
342
+ (`E_CONFIG_BROKEN` when a launch configuration's target is refused as
343
+ well).
344
+ - **What you do:** run it where `tmux -L oats list-sessions` answers.
345
+ With no tmux on its `PATH` the command makes no read and writes the
346
+ operator's own file, as before, and `warnings` says so.
347
+ - **One more target.** A launch configuration that sets `HOME` and no
348
+ `CLAUDE_CONFIG_DIR` or `CODEX_HOME` gets the default file under that
349
+ `HOME` written, when the session and the server set no such variable
350
+ either: that is the file its launch reads. It had no target before.
351
+ - **The `harness-trust` item of `oats readiness` is `unknown` when no OATS
352
+ tmux server runs** and the launch configuration does not set the harness
353
+ folder: the file it can read is the calling process's, not known to be the
354
+ one a launch will read, and `reason` says so. The item is optional, as
355
+ before, and `ready` does not change with it. It is also `unknown`, with
356
+ `file` null, when a server runs and its environment cannot be read.
357
+
358
+ - **The Desktop's command palette lists instances by last focus.** With an
359
+ empty query, ⌘K / Ctrl+Shift+P starts with a **Recent** group: every
360
+ instance of the window's workspace whose terminal you have focused, most
361
+ recent first, each with its parent as quiet text. The instances you have
362
+ not focused follow in the sidebar's tree order. When the most recent is the
363
+ terminal in front, the palette opens on the one before it, so ⌘K then Enter
364
+ returns to the previous agent. With a query, recent matches come first. The
365
+ sidebar roster keeps its stable order. The record stays on this machine, in
366
+ the Desktop's own storage (the 200 most recent per workspace), and survives a
367
+ restart; it is never written to a deployment.
368
+
369
+ - **Desktop: the active terminal tab's instance is always shown in the
370
+ sidebar.** When another terminal tab becomes active (a click on a tab,
371
+ Ctrl+Tab, go to tab, closing a tab, focusing another split group), the
372
+ instance list scrolls just enough to show that instance's row and marks it
373
+ selected at once. A click on the tab that is already active does the same.
374
+ Focus stays where it was. The list does not move while the sidebar is hidden
375
+ or in focus mode, or when your filter hides the row. A row under a collapsed
376
+ parent shows its parent's row instead, and the parent stays collapsed.
377
+
378
+ - **Desktop: the sidebar's instance list no longer shows a scrollbar.** On
379
+ Linux the list showed the platform's heavy classic scrollbar when the roster
380
+ overflowed. It now scrolls like the tab strips, with the wheel or the
381
+ touchpad. Moving through the rows with the keyboard (the arrows, Home/End,
382
+ Down from the filter, F6) scrolls the list just enough to show the whole
383
+ focused row, its tools included.
384
+
385
+ - **The Desktop's keyboard shortcuts editor is searchable and easier to
386
+ read.** A search at the top, focused when the editor opens, filters by an
387
+ action's name, its group or its keys: `shift+b` or `ctrl shift b` finds
388
+ Ctrl+Shift+B. Down moves from the search into the list, and Esc clears the
389
+ search before it closes the editor. Each shortcut shows as keycaps. A quiet
390
+ "terminal" marks the ones that work while a terminal has focus, and
391
+ "changed" marks the ones that differ from the default, next to their Reset.
392
+ Group headings stay in view while their shortcuts scroll. See
393
+ [Desktop keyboard](../../packages/desktop/docs/desktop-keyboard.md).
394
+
395
+ - **Desktop: the instance panel starts closed and stays as you leave it.**
396
+ Opening an instance's terminal (from the sidebar, the palette, the overview,
397
+ Quick Open or a tab switch) no longer opens the panel on the right. Whether
398
+ it is open is remembered on this computer: open it once (its shortcut, the
399
+ palette's **Instance panel: show / hide**, or **Show instance panel**) and
400
+ it stays open for every instance until you close it. The Workspace view's
401
+ soul inspector still opens when you select a soul.
402
+ - **Desktop: a closed sidebar or panel leaves nothing behind.** The thin strip
403
+ left by a hidden sidebar and the narrow rail of a collapsed panel are gone:
404
+ the terminal gets the whole width. To open them again, besides their
405
+ shortcuts and the palette, the top bar has **Show sidebar** at its start
406
+ while the sidebar is hidden or focus mode is on, and **Show instance panel**
407
+ at its end while the panel is closed. Show instance panel carries the
408
+ Developer page's dot when that page has changes.
409
+
410
+ - **Desktop shortcuts work from a focused terminal on Linux and Windows.**
411
+ Three defaults moved so they no longer take a key a program reads: the
412
+ sidebar is Ctrl+Shift+B (was Ctrl+B, the tmux prefix), the instance panel
413
+ Ctrl+Shift+I (was Ctrl+I, the Tab key) and filter instances Ctrl+Shift+F
414
+ (was Ctrl+F). These three, the stages (Ctrl+1, Ctrl+2, Ctrl+3), the
415
+ shortcuts editor (Ctrl+,) and terminal zoom (Ctrl+= Ctrl+- Ctrl+0) now work
416
+ while a terminal has focus. Plain Ctrl+B, Ctrl+I and Ctrl+F reach the
417
+ program, and a shortcut you set yourself is kept. Ctrl+3 from a terminal now
418
+ opens Automations instead of sending ESC: use Esc. macOS is unchanged. See
419
+ [Desktop keyboard](../../packages/desktop/docs/desktop-keyboard.md).
420
+
421
+ - OATS Desktop shows `[withheld]` where it showed `[Detail withheld]`, the
422
+ word the terminal client already uses: both clients now show one word for
423
+ any text they withhold.
424
+
425
+ ## Fixed
426
+
427
+ - **A path, a branch name or a hook's words could rewrite the terminal
428
+ through these lines
429
+ ([#1006](https://github.com/awebai/oats/issues/1006)).** A hook's warning,
430
+ a pi folder's path, an extra tree's path or a branch name printed as it is
431
+ could clear the screen, add a line of its own or reverse what followed it.
432
+ It is now spelled (see Changed).
433
+
434
+ - The kernel's check that keeps a value carrying a URL with credentials out
435
+ of the parsed cache now takes time in proportion to the value's length.
436
+ Before, a long run of dotted, hyphenated or plus-joined words in a
437
+ repository value (such as `a.b.c.…`) made the check take time growing with
438
+ the square of the run: a fraction of a second at 16 KiB, several seconds at
439
+ 64 KiB, on every read that wrote that value to the cache. Which values are
440
+ kept out of the cache is unchanged.
441
+ ([#1036](https://github.com/awebai/oats/issues/1036))
442
+
443
+ - **A retire plan's revision did not bind what the plan showed of the
444
+ record (#1065).** A plan's revision is hashed from the facts that make
445
+ the retire safe, and a guarded apply is refused when one of them moved.
446
+ The record is a file the instance can write, and the revision held
447
+ little of it: not its work mode, its repository or its branch, and of
448
+ the session only the state. So the record could be rewritten between a
449
+ plan and its apply without the revision moving, and two plans that
450
+ differed in `facts.ownWorktree`, `defaults.retainWorktree`,
451
+ `facts.repo`, `facts.recordedBranch`, a note or the text's `defaults:`
452
+ line shared one `planRevision`. So did two plans that differed in what
453
+ Git says of `work/` beyond its commit, branch and counts (the reason it
454
+ gives no answer, a detached `HEAD`, whether the tree is on the recorded
455
+ branch, the branch's upstream, the remote),
456
+ and in the reason of an edge that could not be followed. The revision now
457
+ holds everything a retire plan shows but the facts that move by
458
+ themselves: the instant, the counts against the upstream and the default
459
+ branch with that branch's name, and a child's session. 0.55.0 and every
460
+ release before it have the defect: it is older than 0.53.0.
461
+
462
+ - Git version probe failures preserve existing partial remote caches and all
463
+ their commit pins. Failed probes are not cached, so later reads can retry;
464
+ each caller may stop waiting on its own timeout or cancellation, including
465
+ reads without a session. A shared probe still uses the launching caller's
466
+ timeout and signal, whose failure reaches every remaining waiter.
467
+
468
+ - **A failed write of the scheduler's, the triggers' or an extra tree's
469
+ files leaves no private file behind
470
+ ([#1076](https://github.com/awebai/oats/issues/1076)).** The kernel writes
471
+ each of these files through a private file beside it, renamed into place:
472
+ the automations snapshot (`.agents/automations/snapshot.json`), the
473
+ schedules (`oats-schedules.json`), their run state and the triggers' state
474
+ (`.agents/schedules/state.json`, `triggers.json`), the host scheduler's
475
+ `~/.oats/schedules/registry.json` and `state.json`, an extra tree's record
476
+ (`.oats/trees/<purpose>.json`) and the step `oats worktree add` records in
477
+ its claim (`.oats/trees/<purpose>.lock`). On a file system with no space
478
+ the private file was created, its write failed, and nothing removed it:
479
+ each failed attempt left one more empty `<name>.tmp-<pid>` (for a claim,
480
+ `<name>.tmp-<pid>-<nonce>`) beside the file. Each of them now removes its
481
+ private file when the write or the rename fails, as the two writers of a
482
+ stop have since 0.53.0, and every such write goes through one writer in
483
+ the kernel. The error answered is the one answered before. An upgrade does
484
+ not remove the files an earlier version left.
485
+
486
+ - **A session command's refusal names the file it could not read
487
+ ([#1092](https://github.com/awebai/oats/issues/1092)).** For a home whose
488
+ `instance.json` is not JSON, `oats session inspect`, `attach` and `input`
489
+ said `cannot read session receipt for <home>: <the parser's words>`, though
490
+ the receipt was intact: the file that could not be read was the record, and
491
+ nothing in the sentence said so. The receipt and the record are now read
492
+ apart, and each refusal names its own file by its path:
493
+ `cannot read <home>/instance.json: <why>` for the record (`it is missing`
494
+ for one that is not there, `it holds no JSON object` for one that is JSON
495
+ and no object), `cannot read session receipt for <home> at <path>: <why>`
496
+ for the receipt. The code is `E_RUNTIME_ENDPOINT_UNKNOWN` for either, as
497
+ before. The same sentences reach the error a schedule records for a job
498
+ whose instance's session cannot be inspected, and the row of `oats instance
499
+ stop` for a home without its `instance.json`. `oats session start` and
500
+ `restart` are unchanged: they refuse such a home earlier, with their own
501
+ sentence.
502
+
503
+ - When `oats harness trust` refuses a configuration file, the refused row now
504
+ says which check refused it (for example a macOS extended-attribute marker,
505
+ more than one hard link, another owner, or an unsupported format), without
506
+ repeating the file's content. A refused row no longer prints an empty current
507
+ value and "missing" digests, which read as if the file had no trust, and the
508
+ error message lists every refusal (#1109).
509
+
510
+ - **An instance no longer inherits another instance's provider settings
511
+ through the tmux session or server**
512
+ ([#1123](https://github.com/awebai/oats/issues/1123)). OATS set only the
513
+ variables a capability's hook returned; a variable the capability declares
514
+ in its manifest `environment` but left out of its answer kept whatever the
515
+ pane's environment held. A Claude Code instance on the aweb channel path
516
+ started with `AWEB_DELIVERY=session` that way, so its channel delivered
517
+ nothing and it was never woken. Now, for every capability, a declared
518
+ variable its hooks leave out is removed from the launch: each window's
519
+ command unsets it (for a spawn, a start, a start in place and a restart),
520
+ and the checks of the launch read it as not set. A launch configuration's
521
+ explicit `env` still applies. The persisted launch command does not
522
+ change. See
523
+ [a declared name is the provider's](../capabilities.md#a-declared-name-is-the-providers).
524
+
525
+ - `oats harness trust` names the right reason when a launch configuration that
526
+ sets only `HOME` points at a path that is not a usable directory (a file, or
527
+ a path under one): it says the `HOME` does not select a usable configuration
528
+ directory, where it used to say the path is not absolute (#1171).
529
+
530
+ - Desktop terminals draw text again after the computer wakes from sleep or
531
+ after a switch of Spaces or windows. When the graphics process restarted,
532
+ every terminal pane went blank, showing only its background and the cursor,
533
+ for old output and new alike, until the app was reloaded. Now, once the
534
+ graphics contexts are back, the app redraws the text of every open terminal,
535
+ hidden tabs included.
536
+ ([#1190](https://github.com/awebai/oats/issues/1190))
537
+
538
+ - **`oats session attach` asks tmux for synchronized output
539
+ ([#1193](https://github.com/awebai/oats/issues/1193)).** Every `oats session
540
+ attach` client, the Desktop's remote terminals and the TUI included, now
541
+ starts its tmux client with the `sync` terminal feature when the host's
542
+ tmux is 3.2 or later. tmux then wraps each redraw in DEC mode 2026, so a
543
+ terminal that supports the mode no longer paints a half-drawn redraw (in
544
+ the Desktop, the cursor flickering while you type in a remote instance's
545
+ input box). A terminal without the mode ignores it. The feature is the
546
+ viewer's client's alone: the agent's session, other clients and the tmux
547
+ server's options are unchanged. With tmux before 3.2, or a `tmux -V` the
548
+ kernel cannot read, the client starts as before.
549
+ [Inspect, input and attach](../execution-targets.md#inspect-input-and-attach).
550
+
551
+ - **Desktop: the cursor no longer flashes while you type in a terminal tab**
552
+ ([#1193](https://github.com/awebai/oats/issues/1193)). Each keystroke in a
553
+ program like Claude Code reaches the tab as one redraw that hides the cursor,
554
+ repaints the line and shows the cursor again; a redraw that arrived in two
555
+ pieces was sometimes painted half done, with the cursor hidden. The Desktop
556
+ now attaches its tmux viewer with synchronized output (on tmux 3.2 and later)
557
+ and paints each redraw only once it is whole. Local terminal tabs have the fix
558
+ now; a tab on another machine has it once that machine's oats has the
559
+ matching viewer change.
560
+
561
+ - **A routed spawn preview no longer saves a route.**
562
+ `oats spawn <soul> --server <id> --preview` used to print
563
+ `Spawned <instance> on <id> … — not launched` with a remote home, a route
564
+ snapshot and an attach hint, and saved a route under
565
+ `~/.oats/remote/<id>/`, though the server had only answered a preview and
566
+ created nothing. That stale route then showed in `oats status --server` and
567
+ `oats server roster`, made `oats retire --server` fail with
568
+ `E_HOME_MISMATCH`, and, after `oats server add --replace`, made the next
569
+ `oats spawn --server` fail with `E_ROUTE_CHANGED`. A routed preview now runs
570
+ the spawn's own checks here, asks the server for its preview, and prints the
571
+ local preview's line with the server named
572
+ (`preview <soul> → <instance> on <id> …; nothing was created`). It saves
573
+ no route or other state on this machine. A server that does not advertise
574
+ `spawn-preview-2` is refused with `E_REMOTE_INCOMPATIBLE` before the spawn
575
+ is sent. Drop a route an earlier preview saved with
576
+ `oats server forget <id> --instance <instance>`.
577
+
578
+ - **The checks of a launch read the environment its pane will have, not the
579
+ one of the process that spawns
580
+ ([#993](https://github.com/awebai/oats/issues/993)).** A harness runs in a
581
+ tmux pane, with the session's and the server's `HOME` and harness folder
582
+ (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PI_CODING_AGENT_DIR`). The folder-trust
583
+ check and the harness package check read those names from the process that
584
+ ran the spawn instead, so the two disagreed whenever that process had
585
+ another account than the server: a spawn was refused for a package that
586
+ the pane's account has, or passed and then launched without it; folder
587
+ trust was reported for a file the launch never reads, and a codex launch
588
+ trusted its home by that file. Now the lookup of the harness, the
589
+ folder-trust check, the package check and the command its refusal names,
590
+ the `harness-trust` item of `oats readiness`, a preview and `oats harness
591
+ trust` read one answer: the launch configuration's `env`, else the
592
+ session's entry, else the server's, else what the server is created with.
593
+ - **Who sees a different answer after upgrading:** a host whose OATS tmux
594
+ server or session holds `CLAUDE_CONFIG_DIR`, `CODEX_HOME` or
595
+ `PI_CODING_AGENT_DIR` (the checks now read that account, and no longer
596
+ the shell's), and agents that spawn from a session with a folder of their
597
+ own (their own folder is no longer the one checked: the launch's is). A
598
+ host where the spawning process and the server have the same account sees
599
+ the same answers.
600
+ - **No selector is an answer.** A session or a server that sets none, or a
601
+ session that clears it, launches with the default folder under the
602
+ pane's `HOME`: the checks read that file, and the package check's command
603
+ starts with no selector.
604
+ - **Folder trust never guesses.** When the pane's environment cannot be
605
+ read, the warning is `<harness> folder trust: the configuration file this
606
+ launch will read could not be established (…); nothing is said about its
607
+ trust`. Otherwise the warning names where the launch gets the file from:
608
+ `… is not established in <file> (the CLAUDE_CONFIG_DIR of tmux session
609
+ <name>): oats harness trust --dir <deployment>`.
610
+ - **A preview says what it could not know.** With no server running, a
611
+ preview, `oats readiness` and `oats harness trust` do not start one, and
612
+ do not start your login shell. They read the launch configuration's
613
+ value, else the calling process's, and say so, for `PATH` as well: `the
614
+ pane's environment is not established until a spawn starts the OATS tmux
615
+ server (none runs); read instead: this process's PATH`. A preview carries
616
+ it in the `executable` item's `detail`, a spawn preview in `warnings`.
617
+ The package check does not refuse on that alone.
618
+ - **A spawn with `--no-launch`** checks against the calling process, as
619
+ before, and the start that follows checks again on its own session. It
620
+ now says whose values it read where it already says something: in the
621
+ folder-trust warning and in a refusal for a missing package.
622
+ - **The package check runs the program the lookup selected**, by its
623
+ full path, with the pane's `PATH` as the pane reads it. With a relative
624
+ entry in that `PATH`, the check could run another program, found from
625
+ the directory the command ran in, than the one the launch starts.
626
+ - **A spawn judges again on the session it gets**, as the lookup already
627
+ did: when another creator won the race to start the server, the package
628
+ check and the folder-trust check are made on that server's account.
629
+
630
+ [Every check of a launch reads the environment its pane will have](../execution-targets.md#the-checks-read-the-pane).
631
+
632
+ ## Removed
633
+
634
+ - **`E_REQUIREMENT_INACTIVE` (#1047),** documented as an answer of
635
+ `oats spawn` and of `oats inspect --soul`, and never raised since 0.26.0:
636
+ no OATS from 0.26.0 raises this code. It leaves the contract page and the
637
+ kernel. Nothing a released kernel answers changes.
638
+
639
+ ## Provider updates
640
+
641
+ - **oats.framework 1.10.1: oats.setup 2.5.3.** Instruction text in two
642
+ oats.setup skills; no hook, command, schema or provider contract changes,
643
+ and the capability floors are unchanged (oats.setup `>=0.30.0`).
644
+ - `oats-onboarding` and `oats-workspace-config` say that from OATS 0.56.0 a
645
+ failed or unparseable Git version probe keeps the remote cache and its
646
+ pins, as the entry under Fixed says
647
+ ([#1074](https://github.com/awebai/oats/issues/1074)): fix the local Git
648
+ failure and retry, without deleting the cache. A `cannot-read` is now
649
+ fixed in the operator's Git environment, not only its Git access.
650
+ - `oats-onboarding`'s knowledge section names oats.okf 5.1.0 and the kernel
651
+ it needs, OATS 0.49.0 or later (the instance-event lookup after a source
652
+ retires), as the oats.okf entry says.
653
+ - A deployment gets it by pinning `oats.framework: v1.10.1` and running
654
+ `oats sync`. Instances already running keep the skills they were spawned
655
+ with; new spawns get the new ones.
656
+
657
+ - **oats.okf 5.1.0** (from 5.0.5), mirrored from the published `v5.1.0`
658
+ tag at `40265ac79eca54a76ae648462dbfc83ac370dbbe`. The mirror, catalog and
659
+ workspace pin move together; the mirror and inventory are generated by
660
+ the parity checker from that tag.
661
+ - **A harvest survives its proposer's retirement.** The required spawn
662
+ hook verifies the source's live record or event-named retirement recovery,
663
+ then atomically captures the proposal, source declarations/bindings and
664
+ only named backing notes in the harvester's own home. Later retirement
665
+ or recovery disposal cannot remove captured input. Missing/ambiguous
666
+ provenance still refuses; soul opt-out, unrelated harvesters, the no-wait
667
+ rule and reviewed acceptance remain unchanged.
668
+ - **Requires OATS >=0.49.0**, where the public source-event lookup first
669
+ works after home removal. Upgrade the kernel before the provider pin;
670
+ re-spawn harvesters for the new hook and instructions. Restarting keeps
671
+ a home's copied provider. The onboarding skill now names 5.1.0 and this
672
+ kernel floor; that skill change ships with the next framework release.
673
+ - **Binding URL sequencing:** change a binding's `repository` to the plain
674
+ URL only after every reading seat has been re-spawned on oats.okf 5.0.4
675
+ or later; a session restart does not upgrade its copied modules.
676
+ - Source capture refuses reused/ambiguous source incarnations and incomplete
677
+ event histories. Legacy note references are preserved or explicitly
678
+ refused, never silently dropped or replaced by a shorter filename.
679
+
680
+ Provider changes: [oats-okf#82](https://github.com/awebai/oats-okf/pull/82).
681
+ The generated mirror/pin change is not evidence of deployment adoption or
682
+ a model-run harvest; existing homes and deployments remain unchanged until
683
+ explicitly upgraded.
684
+
685
+ ## Documentation
686
+
687
+ - **Every release's notes open their Upgrade section with the order of the
688
+ Desktop and the CLI** ([#1107](https://github.com/awebai/oats/issues/1107)).
689
+ A new minor says to install the Desktop first, because the previous Desktop
690
+ refuses the new CLI; a patch says that either order works.
691
+ [The release lane](../release-lane.md) holds the rule for the tag owner.
692
+
693
+ - [Harness trust](../harness-trust.md#when-the-writer-refuses) explains each
694
+ refusal and the way forward on macOS when the file carries an attribute such
695
+ as `com.apple.provenance`: leave the file as it is, accept Claude's own
696
+ folder-trust dialog for the deployment folder under the configuration
697
+ directory the launch uses, and check the `harness-trust` item of
698
+ `oats readiness`. A refusal does not hold back `oats sync`, `oats readiness`
699
+ or `oats doctor` (#1109).