@awebai/oats 0.51.0 → 0.52.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 (128) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +109 -37
  3. package/docs/capabilities.md +9 -2
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +927 -92
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +144 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +66 -9
  12. package/docs/integrations.md +9 -8
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/oats-local.schema.json +4 -3
  20. package/docs/official-catalog.md +4 -4
  21. package/docs/packages.md +14 -14
  22. package/docs/release-lane.md +15 -5
  23. package/docs/release-notes/v0.44.0.md +1 -1
  24. package/docs/release-notes/v0.52.0.md +933 -0
  25. package/docs/schedules.md +91 -4
  26. package/docs/souls-and-instances.md +95 -25
  27. package/docs/tui.md +152 -0
  28. package/docs/workspaces.md +2 -2
  29. package/lib/claim.mjs +186 -46
  30. package/lib/core.mjs +730 -185
  31. package/lib/errors.mjs +170 -0
  32. package/lib/harness-trust-write.mjs +68 -27
  33. package/lib/harness-trust.mjs +34 -16
  34. package/lib/instance-inspect.mjs +40 -11
  35. package/lib/instance-lifecycle.mjs +169 -47
  36. package/lib/launch-preference.mjs +16 -0
  37. package/lib/launch-prompt-completion.mjs +7 -43
  38. package/lib/launch-prompt-evidence.mjs +14 -7
  39. package/lib/launch-prompt-fixtures/README.md +86 -152
  40. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  41. package/lib/launch-prompt-fixtures.mjs +122 -109
  42. package/lib/launch-prompt-transport.mjs +2 -56
  43. package/lib/launch-prompts.mjs +102 -100
  44. package/lib/schedule-host.mjs +154 -22
  45. package/lib/schedule.mjs +73 -24
  46. package/lib/system-tools.mjs +39 -0
  47. package/lib/tmux-server-scope.mjs +62 -0
  48. package/lib/triggers.mjs +4 -4
  49. package/lib/workspace.mjs +5 -11
  50. package/lib/worktree-hooks.mjs +98 -20
  51. package/lib/worktree.mjs +83 -24
  52. package/package-catalog.json +3 -3
  53. package/package.json +7 -2
  54. package/packages/client/capability-show-contract.mjs +230 -0
  55. package/packages/client/capability-warnings-contract.mjs +57 -0
  56. package/packages/client/cli-adapter.mjs +548 -0
  57. package/packages/client/cli-environment.mjs +53 -0
  58. package/packages/client/cli-locator.mjs +253 -0
  59. package/packages/client/cli-probe-contract.mjs +47 -0
  60. package/packages/client/client-terms.mjs +60 -0
  61. package/packages/client/deployment-contract.mjs +68 -0
  62. package/packages/client/deployment-data.mjs +483 -0
  63. package/packages/client/deployment-facts.mjs +34 -0
  64. package/packages/client/deployment-label.mjs +76 -0
  65. package/packages/client/deployment-observer.mjs +89 -0
  66. package/packages/client/deployment-panel.mjs +142 -0
  67. package/packages/client/deployment-read-cli.mjs +53 -0
  68. package/packages/client/display-text.mjs +44 -0
  69. package/packages/client/harness-names.mjs +30 -0
  70. package/packages/client/inspect-contract.mjs +62 -0
  71. package/packages/client/instance-acts.mjs +54 -0
  72. package/packages/client/instance-admission.mjs +45 -0
  73. package/packages/client/instance-events-contract.mjs +74 -0
  74. package/packages/client/instance-git-contract.mjs +80 -0
  75. package/packages/client/instance-presentation.mjs +22 -0
  76. package/packages/client/instance-tree.mjs +453 -0
  77. package/packages/client/kernel-environment.mjs +11 -0
  78. package/packages/client/launch-contract.mjs +51 -0
  79. package/packages/client/launch-prompt-outcome.mjs +165 -0
  80. package/packages/client/lifecycle-cli.mjs +61 -0
  81. package/packages/client/lifecycle-contract.mjs +372 -0
  82. package/packages/client/liveness-main.mjs +10 -0
  83. package/packages/client/liveness.mjs +35 -0
  84. package/packages/client/machine-contract.mjs +123 -0
  85. package/packages/client/own-environment.mjs +22 -0
  86. package/packages/client/panel-views.mjs +286 -0
  87. package/packages/client/readiness-contract.mjs +172 -0
  88. package/packages/client/refresh-loop.mjs +52 -0
  89. package/packages/client/remote-address.mjs +126 -0
  90. package/packages/client/remote-roster.mjs +67 -0
  91. package/packages/client/roster-sections.mjs +80 -0
  92. package/packages/client/spawn-apply-cli.mjs +104 -0
  93. package/packages/client/spawn-apply-contract.mjs +183 -0
  94. package/packages/client/spawn-decision.mjs +46 -0
  95. package/packages/client/spawn-messages.mjs +119 -0
  96. package/packages/client/spawn-preview-cli.mjs +32 -0
  97. package/packages/client/spawn-preview-contract.mjs +314 -0
  98. package/packages/client/team-members.mjs +41 -0
  99. package/packages/client/team-rows.mjs +45 -0
  100. package/packages/client/terminal-contract.mjs +57 -0
  101. package/packages/client/tmux-status.mjs +66 -0
  102. package/packages/client/waiting-on-you.mjs +88 -0
  103. package/packages/client/workspace-admission.mjs +45 -0
  104. package/packages/client/workspace-cli.mjs +142 -0
  105. package/packages/client/workspace-views.mjs +147 -0
  106. package/packages/tui/README.md +46 -0
  107. package/packages/tui/bin/tui.mjs +7 -0
  108. package/packages/tui/lib/actions.mjs +29 -0
  109. package/packages/tui/lib/client.mjs +4 -0
  110. package/packages/tui/lib/main.mjs +105 -0
  111. package/packages/tui/lib/term/keys.mjs +323 -0
  112. package/packages/tui/lib/term/screen.mjs +122 -0
  113. package/packages/tui/lib/term/style.mjs +43 -0
  114. package/packages/tui/lib/term/text.mjs +49 -0
  115. package/packages/tui/lib/term/tty.mjs +168 -0
  116. package/packages/tui/lib/term/width.mjs +124 -0
  117. package/packages/tui/lib/views/frame.mjs +62 -0
  118. package/packages/tui/lib/views/help.mjs +28 -0
  119. package/packages/tui/package.json +8 -0
  120. package/skills/oats-getting-started/SKILL.md +29 -22
  121. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  122. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  123. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  124. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  127. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  128. package/lib/launch-prompt-policy.mjs +0 -87
@@ -0,0 +1,933 @@
1
+ # OATS 0.52.0
2
+
3
+ 2026-10-12
4
+
5
+ ## Upgrade
6
+
7
+ Steps 1 to 3 each stop a spawn that worked on 0.51, so do them on each host
8
+ before upgrading, in this order:
9
+
10
+ 1. **Establish folder trust first**: `oats harness trust --plan`, then
11
+ `oats harness trust`. On 0.51 a Claude start on a host without it reported a
12
+ launched instance waiting at the trust prompt. On 0.52 every start with the
13
+ development-channel flag is observed, so the same start ends as
14
+ `E_SPAWN_INCOMPLETE`, `blocked: unexpected prompt`, with the pane retained.
15
+ That is the loud miss working as designed, and it is new for every home that
16
+ was never on the old `launchPromptAnswers` list.
17
+ 2. **A host with several launch configurations for one harness** marks one
18
+ `default: true` or names one in `souls.launch`. Until then, scheduled jobs,
19
+ triggers and agents' own spawns that name no configuration are refused
20
+ (`E_LAUNCH_CONFIG_AMBIGUOUS`).
21
+ 3. **Remove `launchPromptAnswers`** from `oats-local.yaml`: a home entry
22
+ `awebDevelopmentChannel: false` stops the deployment from loading.
23
+
24
+ Then upgrade, in this order, with no lifecycle command (a stop or a retire) in
25
+ flight on the deployment:
26
+
27
+ 4. **Upgrade aw to 1.36.33 or later on every host**, then restart every
28
+ resident custody service and the host wake daemon. A custody that is
29
+ already running keeps its old operations until it is restarted.
30
+ 5. **Upgrade the OATS CLI and the Desktop together.** A 0.51.0 Desktop refuses
31
+ a 0.52.0 CLI.
32
+ 6. **Pin oats.aweb 1.27.0**, then run `oats sync`. It needs OATS 0.52.0: an
33
+ older kernel refuses it with `E_CAPABILITY_INCOMPATIBLE`. The catalog's
34
+ other versions in this release are oats.okf 5.0.2 and oats.framework 1.9.3.
35
+ 7. **After upgrading, on every host that runs schedules**, run
36
+ `oats schedule host install` again, from the operator's own shell (not from
37
+ an instance home): an installed timer is not rewritten by upgrading OATS.
38
+ `oats schedule host status` reports `unit-outdated` until you do.
39
+
40
+ A host or launch configuration that opts out of Claude Code's telemetry
41
+ (`DISABLE_TELEMETRY`, `DO_NOT_TRACK` or
42
+ `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`) gets no channel delivery on the
43
+ default `delivery: channel`, and every start now says so: see Changed.
44
+
45
+ ## Added
46
+
47
+ - **`oats tui` (preview): a terminal client (#855).** `oats tui` is a
48
+ full-screen, keyboard-only client for people who work in terminals and on
49
+ machines with no display. It ships inside the `oats` package: there is
50
+ nothing else to install. **It is a preview, and this version draws the
51
+ frame only**: it shows the frame, answers `?` (help) and `q` (quit), and
52
+ reads nothing from the kernel yet. The views arrive in later releases, and
53
+ while it is a preview its screens may change without notice. It leaves
54
+ preview when the readers it shares with the Desktop are in their shared
55
+ home, a person has used it for a working day and both maintainers agree.
56
+ **So far it has been run in tmux only:** not in a terminal emulator
57
+ without tmux, and not over ssh. If it leaves your terminal wrong, run
58
+ `reset` and report it with the terminal's name and `TERM`.
59
+ - **What it does to your terminal** is a closed list, restored on every way
60
+ out a process can handle (quit, an internal error, SIGINT, SIGTERM,
61
+ SIGHUP, SIGQUIT) and across `Ctrl+Z` and `fg`: raw mode, the alternate
62
+ screen, the cursor hidden, autowrap off and bracketed paste on. It
63
+ switches on no mouse or focus reporting and no keyboard protocol, writes
64
+ no title, clipboard sequence or bell, and uses only your terminal's own
65
+ sixteen colours (`NO_COLOR` is honoured). After SIGKILL no process can
66
+ restore a terminal: `reset` is needed (inside tmux, `tput rmcup` too), and
67
+ nothing is left in tmux.
68
+ - **Text it did not write never reaches the terminal raw.** The screen
69
+ draws only the TUI's own words and text that passed the display filter it
70
+ shares with the Desktop, so a name or a message cannot write a control
71
+ sequence.
72
+ - **Without a terminal** on stdin and stdout, or with `TERM` unset or
73
+ `dumb`, it exits 1 with one line on stderr naming `E_NO_TERMINAL` and
74
+ draws nothing. `oats tui --json` is refused with `E_BAD_ARGS`: it is
75
+ interactive, and `oats status --json` is the machine view.
76
+ - `oats pane` still refuses, and its message now names `oats tui` beside
77
+ the Desktop.
78
+ - No JSON answer, configuration key, hook or lock changes, and
79
+ `oats version --json` lists no new feature: nothing gates on this word.
80
+ See [OATS TUI](../tui.md).
81
+
82
+ ## Changed
83
+
84
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.53.0`.** The compatibility band
85
+ admits 0.52. Upgrade the CLI and the Desktop together: a 0.51.0 Desktop
86
+ refuses a 0.52.0 CLI. No new gate on the band. The Desktop reads two of this
87
+ release's features where the answering kernel names them, and makes the
88
+ weaker claim for a kernel that does not: `lifecycle-claim-stop` (who holds
89
+ the claim, on `E_LIFECYCLE_BUSY`) and `lifecycle-kernel-codes` (a failed stop
90
+ row's `stillRunning: []` says the harness exited).
91
+
92
+ - **OATS confirms Claude's development-channel prompt on every start that
93
+ launches Claude with the development-channel flag**
94
+ ([#886](https://github.com/awebai/oats/issues/886)). When a spawn,
95
+ `oats session start` or `session restart` (by hand or by an agent) starts
96
+ Claude with `--dangerously-load-development-channels
97
+ plugin:aweb-channel@awebai-marketplace`, the launcher confirms Claude's
98
+ confirmation once, with one Enter, in the pane it created. Launching with the
99
+ flag is the decision. There is **no consent setting and no list of homes**:
100
+ every Claude home the messaging provider starts in development mode (the
101
+ default `delivery: channel`, `claudeChannelMode: development`) is covered,
102
+ existing homes included at their next start. This reverses the rule that no
103
+ existing home is enabled automatically. To keep the prompt for a person, stop
104
+ launching with the flag: `settings.oats.aweb.delivery: session` or
105
+ `settings.oats.aweb.claudeChannelMode: approved`, then respawn the home. Each
106
+ start that engages it says so in its warnings (`launch-config preview`, the
107
+ spawn's warnings, `session start|restart`). `spawn --preview` does not yet:
108
+ the argv comes from the provider's spawn hook, which a preview does not run (a
109
+ kernel follow-up runs preview-aware launch hooks there).
110
+ See [the development-channel confirmation](../configuration.md#the-development-channel-confirmation).
111
+
112
+ - **Accounts where Claude Code offers no channels, on the default
113
+ `delivery: channel`: every start now says the instance gets no channel
114
+ delivery.** Claude Code disables channels when telemetry is opted out (`DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`): a host or launch configuration that sets any of
115
+ them is affected the same way, and oats.aweb's readiness warning names the
116
+ three variables that do it. For such an account Claude 2.1.296 ignores
117
+ `--dangerously-load-development-channels`, shows no confirmation, and starts
118
+ the session with the notice `--dangerously-load-development-channels ignored
119
+ (plugin:aweb-channel@awebai-marketplace) Channels are not currently
120
+ available`. Before 0.52 that start reported launched and said nothing, and mail
121
+ and chat never woke the instance. Now, when that notice block equals the new
122
+ `flag-ignored` tolerance entry (which takes no input), OATS sends no key, the
123
+ start succeeds, and the home records `launchPrompts: {status: "flag-ignored",
124
+ reason: "channels-unavailable", signatureId, startId, at}`. The start's
125
+ warnings replace the statement that OATS confirms the prompt with one that
126
+ says what was seen and the causes to check, in order (next entry). It says so
127
+ at every start until the cause is removed or delivery changes. The provider's readiness reports it; the kernel's
128
+ `launch-prompt` readiness item does not. A notice in a wording no entry holds
129
+ still ends `blocked`, like any unknown screen. **Known limit, on a first spawn:** a fresh Claude configuration can show
130
+ another notice (auto mode becoming the default) and keep this one behind
131
+ `1 more notice hidden`. OATS cannot see it, so that spawn ends
132
+ `E_SPAWN_INCOMPLETE`, `blocked: unexpected prompt`, with the session running in
133
+ the retained pane. The error and the readiness remedy then say Claude may have
134
+ ignored the flag: look at the pane and, if the session is running, restart the
135
+ instance; the restart sees the notice and records `flag-ignored`.
136
+
137
+ - **The flag-ignored words say what was seen, and a spawn's answer carries
138
+ `launchPrompts`.** The start's warning reads `Claude reported that channels are not currently available and ignored the development-channel flag, so this instance gets no channel delivery: mail and chat will not wake it. Check first for a telemetry opt-out in the launch environment (DISABLE_TELEMETRY, DO_NOT_TRACK or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: Claude Code disables channels when one is set), then whether this Claude account offers channels; otherwise change the messaging provider's delivery (its readiness warning says where the setting is). See docs/configuration.md#the-development-channel-confirmation.` The hidden-notice hint in the
139
+ error and the readiness remedy names the same causes in the same order. Neither
140
+ states that the account lacks channels, since a telemetry opt-out is the
141
+ other cause, and neither names a provider setting. A successful `oats spawn
142
+ --json` answer now carries `launchPrompts` exactly as a start's answer does
143
+ (`completed`, `not-engaged` or `flag-ignored`), so a client learns a
144
+ spawn's outcome from the answer, as it does a start's.
145
+
146
+ - **The match no longer depends on the Claude binary, platform or pane size.**
147
+ The executable-hash pin, the platform gate and the 110×35 geometry pin are
148
+ removed; the launcher never resizes a pane. The screen, with box-drawing rows
149
+ dropped and whitespace collapsed (nothing else), must **equal** an entry of
150
+ the tolerance list `lib/launch-prompt-fixtures/dev-channel-confirmation.json`:
151
+ the confirmation's text, exactly one channel, the affirmative option selected,
152
+ nothing else. One entry covers Claude 2.1.289 and 2.1.296 on macOS and Linux
153
+ (captures and provenance in `test/fixtures/launch-prompts/`). Claude 2.1.288
154
+ on linux-x64 at 194×50 and 80×24 is reported coverage, not a committed
155
+ capture: the release review matched it on its own host
156
+ ([review 5481510495](https://github.com/awebai/oats/pull/917#pullrequestreview-5481510495)).
157
+ A new Claude wording is a new entry in a reviewed change. A screen still
158
+ being painted is waited for, and so is a transient frame Claude paints while
159
+ starting: an unknown screen blocks only once it has held unchanged for the
160
+ settle window (`SETTLE`, 2 s), `blocked: unexpected prompt`, with no key, and
161
+ the receipt says what `differed` from the nearest entry. A screen still
162
+ changing at the 30 s bound never settled: `blocked: observation timeout`,
163
+ with what differed kept, and an error and readiness remedy that say no prompt
164
+ was established. A pane too narrow
165
+ for Claude to wrap at word boundaries (about 40 columns) does not match.
166
+
167
+ - **Completion after the Enter is version-tolerant.** `SETTLE` (2 s) of
168
+ consecutive clean captures (non-blank, no question marker, no entry; the screen
169
+ free to change) completes. A question marker inside the window, or the
170
+ confirmation coming back, blocks. A blank capture restarts the window. No
171
+ complete window by the 30 s bound is `blocked: observation timeout`, and the
172
+ error says the one Enter was sent. A question first painted more than 2 s
173
+ after the session is working is the session's own, not a launch prompt. The footer-structure
174
+ rule and the exact banner frames are gone, and so is their 110×35 condition.
175
+ Private evidence is kept for every miss and every completion (recognition
176
+ `stable-screen`). See [launch completion](../launch-prompt-completion.md).
177
+
178
+ - **The record always describes the last start.** A start that does not engage
179
+ the confirmation writes `instance.json` `launchPrompts: {status:
180
+ "not-engaged", startId, at}` and removes `launchPromptTarget`. A home whose last
181
+ start was `blocked` shows a `launch-prompt` readiness warning with what
182
+ differed and both remedies (add a tolerance entry, or press Enter after
183
+ reading the prompt); a later start clears it.
184
+
185
+ - **Contract changes for readers.** Previews no longer carry
186
+ `launchPromptAnswers`; `launch-prompt` events no longer carry `consentSource`
187
+ and add `claudeVersion` and `claudeVersionSource` (read from the executable's
188
+ real path, never by running it; `unknown` when Claude is started through a
189
+ wrapper, whose path carries no version) and, on a miss, `differed`. A blocked
190
+ `launchPrompts` carries `differed`, and `claudeSessionShown: true` when the
191
+ blocked screen was Claude's running session. `launchPrompts.status` and the
192
+ `launch-prompt` event add the value `flag-ignored`. After the Enter, a
193
+ `blocked: observation timeout` error and readiness remedy now say the one
194
+ Enter was sent. `oats version --json` lists the feature
195
+ `launch-prompt-dev-channel`.
196
+
197
+ - **Folder trust for every configuration file a launch reads**
198
+ ([#886](https://github.com/awebai/oats/issues/886)). `oats harness trust`
199
+ writes the deployment-root trust entry into the ambient file (the operator's
200
+ `CLAUDE_CONFIG_DIR` or `CODEX_HOME`, else the default) and into the file of
201
+ each launch configuration whose `env` sets `CLAUDE_CONFIG_DIR` (claude) or
202
+ `CODEX_HOME` (codex), as a literal or a `{fromEnv}` reference; files sharing a
203
+ directory count once. `--plan` lists every file, which launch configurations
204
+ use it and what it will write. A launch configuration whose directory is
205
+ missing, whose reference is unset or whose path is relative is a named problem
206
+ that refuses the command before any write. OATS never creates a harness
207
+ configuration directory: a missing ambient one (a harness that has not run as
208
+ this user) is `skipped` under `--harness all` and a problem when that harness is
209
+ named; it used to be created.
210
+ Spawn, `session start|restart`, `launch-config preview`, readiness and Codex's
211
+ per-launch home trust read trust from the file the launch's own environment
212
+ selects; before, they always read the ambient file. The spawn warning and the
213
+ `harness-trust` readiness item say `<harness> folder trust is not established
214
+ in <file>: oats harness trust --dir <deployment>`, because a missing entry does
215
+ not prove that the harness will prompt; readiness also reports a passing item
216
+ naming the file. OATS never answers a folder-trust prompt.
217
+ See [harness trust](../harness-trust.md).
218
+
219
+ - **A spawn with an ambiguous launch configuration is refused**
220
+ ([#886](https://github.com/awebai/oats/issues/886)). When the harness a spawn
221
+ resolves to has more than one launch configuration in `oats-local.yaml`, none
222
+ of them `default: true`, and the spawn names none, `oats spawn --preview` and
223
+ the spawn refuse with `E_LAUNCH_CONFIG_AMBIGUOUS` (`details: {harness,
224
+ configurations, fix}`) instead of starting the bare harness. Name one with
225
+ `--launch-config <name>`, `--launch-config none` (the bare harness) or a
226
+ `souls.launch` name, or mark one `default: true`. An inline `souls.launch`
227
+ preference, the soul's own `launch:` and `--harness` alone do not count. A
228
+ single configuration for the harness is not refused. `oats souls`, `oats
229
+ inspect --soul` and readiness show it as the launch's `problem`. Known gap:
230
+ `session start|restart` of an existing home, including `--harness` and
231
+ `--reselect-launch`, keeps its behaviour and is not refused.
232
+
233
+ - <a id="lifecycle-claim-stop-changed"></a>**Stop and retire: the answers
234
+ that changed with the claim a stop now holds (#866, #890, #895).** What
235
+ changed, and what it fixes, is under
236
+ [Fixed](#lifecycle-claim-stop). These answers are not what they were in
237
+ 0.51.0:
238
+ - **A stop now needs to write its claim.** A stop whose claim cannot be
239
+ written (a full disk is the likely case) is refused before anything is
240
+ signalled: `E_LIFECYCLE_FAILED`, `the claim <lock> could not be taken
241
+ (<the system's error>); nothing was done`, and the session runs as
242
+ before. In 0.51.0 a stop took no claim: it signalled the harness
243
+ whether or not it could write its marker, so it could fail afterwards,
244
+ writing its own record, with the signal already sent. The way out:
245
+ free space and stop again, or end the session by hand. See
246
+ [A stop needs to write its claim](../desktop-cli-api.md#stop-claim-write).
247
+ - A guarded retire whose extra trees no longer read as its plan said,
248
+ found after the hooks, answers `E_WORK_PRESERVATION_FAILED`; it answered
249
+ `E_PLAN_STALE`, which says that nothing happened (#895). The home and
250
+ its work are kept, as before.
251
+ - A retire that cannot end the worktree hook process group an interrupted
252
+ spawn left (it survives SIGTERM and SIGKILL) answers
253
+ `E_RUNTIME_QUIESCE_FAILED`, naming the group; it answered
254
+ `E_LIFECYCLE_BUSY`, "nothing was retired", after two signals.
255
+ - `oats instance stop --apply` with a `--grace-ms` that is not 1–300000
256
+ answers `E_BAD_ARGS` as an error, before the plan is read and before the
257
+ key is used. It answered a receipt with one `E_BAD_ARGS` row per target,
258
+ stored under the key: a caller that read the receipt's rows for this
259
+ now gets an error.
260
+ - A recorded child whose claim is held when its parent is retired (a stop
261
+ or a retire of that child is running) is a row of `childrenStopped`
262
+ with `E_LIFECYCLE_BUSY` or `E_INSTANCE_RETIRING`, and the retire answers
263
+ `E_CHILDREN_RUNNING`, as for any child that did not stop.
264
+ - The message of `E_CHILDREN_RUNNING` says `still running after a bounded
265
+ stop` only of a child whose processes were found running (its row's
266
+ `stillRunning` lists them); of any other child that did not stop it
267
+ says `<child> could not be stopped (<its row's code>)`. It said "still
268
+ running" of every one. The code, `childrenStopped`, the exit status and
269
+ the text form's line are as they were.
270
+
271
+ - **Desktop: the kernel readers moved to `packages/client/`.** The modules
272
+ through which the Desktop reads the kernel's JSON (the CLI adapters and the
273
+ contract decoders) now live in `packages/client/`, where a second client can
274
+ import them. The Desktop behaves as before. In the installed app they are in
275
+ `client/` beside `app.asar`, not inside it: `Contents/Resources/client/` in
276
+ the macOS bundle, covered by its signature, and `resources/client/` on
277
+ Linux. Installer CI now launches the packaged window on the Linux leg.
278
+ - **Desktop: the instance menu is built from one shared decision.** Which
279
+ acts a roster row offers (inspect, start or restart, stop, retire) and why
280
+ one is unavailable is now decided in `packages/client/`, where a second
281
+ client can import it, with the roster's tree and its sections; the Desktop
282
+ draws its menu from that answer. One thing differs: a remote row whose
283
+ server does not report it as reachable has a menu with no items. That menu
284
+ could not be opened before either (its button is disabled and says why), so
285
+ the items it held were never reachable. A root test,
286
+ `test/client-boundary.test.mjs`, pins what `packages/client/` may import
287
+ and which of its modules and exports a second client may take.
288
+ - **Desktop: the panel is put together in `packages/client/`.** What the
289
+ Desktop's backend makes of one deployment's observation (its rows, the
290
+ answer when terminal status cannot be read, what a failed read becomes)
291
+ and the workspace views over its deployments are now functions in
292
+ `packages/client/` that keep nothing, where a second client can call them.
293
+ The Desktop answers as before, apart from the two entries that follow. A
294
+ test now holds that the window's page loads no module that needs Node.
295
+ - **Desktop: a row whose spawn is still setting up its worktree says that it
296
+ can't be used until the spawn finishes.** It no longer says that it opens
297
+ then, which was true only for a spawn started from this window.
298
+ - **Desktop: a local instance whose state OATS could not establish is shown
299
+ as state unknown, with the reason, and no longer as stopped with a Start
300
+ that is then refused.** Its Session card shows a tmux session only when
301
+ OATS recorded one. A kernel read that failed once leaves the row unknown
302
+ until the next roster read.
303
+ - **Desktop: Stop and Retire word the kernel's lifecycle answers from their
304
+ data (#866).** **In 0.51.0 the Desktop's headline promised that waiting
305
+ ends a busy answer also where nothing was running; from this release it
306
+ words the answer by who holds the claim.** The 0.51.0 notes say that the
307
+ Desktop "already words `E_LIFECYCLE_BUSY`, the answer a second retire of
308
+ an instance now gets". That holds for a second retire. The same release
309
+ answers the code where no command runs (a process whose start cannot be
310
+ read, a home that changed while its claim was taken), and there the
311
+ headline told the person to wait for another stop or retire to finish. The
312
+ new wording needs a kernel that says who holds the claim (feature
313
+ `lifecycle-claim-stop`, this release): against an older kernel the headline
314
+ is unchanged, because that kernel does not say.
315
+
316
+ Each sentence below is decided from fields of the answer and from the
317
+ features of the kernel that gave it (for a routed command, the host's own
318
+ list; a host whose list is not known counts as without the feature). No
319
+ kernel message is parsed.
320
+ - **A stop whose session stopped, and whose record failed, reads as stopped
321
+ and not recorded.** With a kernel that lists `lifecycle-kernel-codes`, a
322
+ failed row with `stillRunning: []`, in a stop's result or in a refused
323
+ retire's child list, says that the harness exited and that what failed
324
+ came after. Its line now reads "<name>: Stopped, but OATS couldn't record
325
+ it" where it read "<name>: Didn't stop". When every failed row is such a
326
+ row, the sentence above the rows says so. A stop: "<name> stopped, but
327
+ OATS couldn't record it." for one target and "Every session stopped, but
328
+ OATS couldn't record all of them:" for several, under the title "Stopped,
329
+ but not recorded", where it read "Not every session stopped". A retire
330
+ refused with `E_CHILDREN_RUNNING`: "The child instances stopped, but OATS
331
+ couldn't record it for all of them, so nothing was retired." where it read
332
+ "A child instance wouldn't stop, so nothing was retired. Other children
333
+ may already have stopped." It is still a result that did not succeed: no
334
+ check mark, and **Review again** is offered. Rows of mixed kinds keep the
335
+ sentences they had. With a kernel that does not list the feature the
336
+ Desktop shows what it showed before for every answer: there `[]` does not
337
+ say stopped, and `/api/instance-lifecycle` carries it as `null`.
338
+ - **A child that another command holds reads "Not stopped", with why.** In a
339
+ refused retire's child list, and in a stop's result, a row the kernel
340
+ answers `E_INSTANCE_RETIRING` now reads "<name>: Not stopped: it is being
341
+ retired", and a row it answers `E_LIFECYCLE_BUSY` reads "<name>: Not
342
+ stopped: OATS couldn't lock its home", with the kernel's own sentence for
343
+ that row under it, shown as one line through the display filter. Both read
344
+ "<name>: Didn't stop" before, which says that a stop was tried and failed.
345
+ The kernel answers both codes only before any effect, so for that row
346
+ nothing was tried. The two lines are keyed on the row's code and apply
347
+ with every kernel: a kernel before 0.52.0 already answers an
348
+ `E_INSTANCE_RETIRING` row for a child with a scheduled self-retire. The
349
+ sentence above the rows is unchanged.
350
+ - **`E_LIFECYCLE_BUSY` is worded by who holds the claim.** With a kernel
351
+ that lists `lifecycle-claim-stop`, the kernel's busy answer to a stop, a
352
+ retire or a plan read is read by its `error.details.holder`, and only
353
+ `running` tells the person to wait:
354
+ - `running`: "Another OATS command is already running. Wait for it to
355
+ finish, then review again." (it no longer says "stop or retire": the
356
+ holder can be a spawn), with the kernel's sentence in Details, as before;
357
+ - `unknown`: "Nothing was done. OATS can't tell whether another command is
358
+ still running." then "It says what to check:" and the kernel's sentence;
359
+ - `none`: "Nothing was done, and there is no other command to wait for."
360
+ then "OATS says what to do:" and the kernel's sentence;
361
+ - the field absent, or a value outside that list: "Nothing was done: OATS
362
+ refused this as busy." then "It says:" and the kernel's sentence.
363
+
364
+ For the last three the kernel's sentence names the step that ends the
365
+ refusal, so it is the main text under the headline, as one line through
366
+ the display filter, and a screen reader gets it with the headline. When
367
+ the filter withholds it, the introducing words are left out and Details
368
+ shows that a detail was withheld. When a recursive stop is refused for the
369
+ claim of a child, one line names it: "This is about <name>, which is in
370
+ this plan." The name is the plan's own. With that feature the Desktop's
371
+ own sentence for a home a spawn left ("… then retire it from the CLI with
372
+ --force.") is no longer shown: the kernel's sentence names the check and
373
+ the command where it offers one. Without the feature, or for a host whose
374
+ features are not known, every busy answer reads as before, that sentence
375
+ included, and the busy the Desktop raises itself keeps its sentence.
376
+ - **An answer the kernel gave never reads "OATS couldn't be run for
377
+ this."** That sentence was shown for every code the Desktop has no
378
+ sentence for, with no kernel message. Two things change. A kernel error
379
+ whose code the Desktop does not describe now keeps its own code and reads
380
+ "OATS answered with an error that Desktop has no description for.", with
381
+ the code and the kernel's message in Details, for a local answer and a
382
+ routed one. And `E_RUNTIME_QUIESCE_FAILED` has its own sentence, "OATS
383
+ tried to end a session or a process and couldn't confirm that it ended.",
384
+ shown as the cause under "OATS didn't confirm the result. Check again
385
+ before assuming nothing happened.", with the kernel's message in Details.
386
+ Neither changes what is offered: which answers are a refusal and which an
387
+ unknown outcome is decided as before. "OATS couldn't be run for this."
388
+ stays for what it says: a command that could not be run, and a system
389
+ code (`ENOENT`) from a kernel before 0.52.0.
390
+ - **Desktop: a Stop or a Retire of a home OATS cannot work from reads as a
391
+ refusal (#866).** `E_UNIDENTIFIED_INSTANCE_HOME` is the kernel's answer for
392
+ a home it cannot work from: its `instance.json` is there and cannot be
393
+ read, its rollback marker cannot drive a retry, or it has neither a record
394
+ nor a cleanup descriptor. In 0.51.0 the Desktop read that answer as "OATS
395
+ couldn't be run for this.", with no kernel message, and an apply answered
396
+ with it was an unknown outcome. It now reads "OATS couldn't find or read
397
+ what it needs in this instance's home folder, so nothing was done.", with
398
+ the code and the kernel's message in Details, for a local answer and a
399
+ routed one. An apply answered with it is now a refusal: the kernel answers
400
+ the code only before any effect, and the code joins the Desktop's list of
401
+ the codes it reads so. "Nothing was done" is about the instance: its
402
+ sessions and its home.
403
+ - **Desktop: the launch-prompt answers of this release are read and shown
404
+ (#917).** The Desktop follows the contract above with every kernel it
405
+ accepts. Each new field is read when the answer carries it: nothing is
406
+ gated on `launch-prompt-dev-channel`, and no reader of a field that a 0.44
407
+ to 0.51 kernel sends is removed, because a routed host can run one and a
408
+ home keeps what an older kernel recorded. Against this release's kernel the
409
+ Spawn dialog shows no "Launch prompts" note: a preview carries no
410
+ `launchPromptAnswers`, and `oats spawn --preview` cannot report the
411
+ confirmation (#912). What a person reads differently:
412
+ - **When OATS could not keep its own evidence of a launch, the outcome
413
+ shows its reason instead of "Launch requires inspection".** Four reasons
414
+ the kernel writes join the Desktop's set: `private launch evidence
415
+ retention failed`, alone and as the suffix of three blocked reasons.
416
+ - **When OATS stops at a screen that is not the confirmation it answers,
417
+ Desktop shows what OATS expected and what the terminal showed.** In the
418
+ Spawn dialog, the Start dialog and the Activity row of the event. The
419
+ terminal's text is shown as a quote with its speaker named, through the
420
+ display filter, and is never compared or acted on. The notice of a
421
+ background spawn says that Activity shows it.
422
+ - **A launch-prompt row in Activity shows the Claude version and the
423
+ screen OATS recognised.** "Consent source" stays on the rows an older
424
+ kernel wrote.
425
+ - **Readiness names the configuration file of the folder-trust check, also
426
+ when it passes.** The reason of the new `launch-prompt` warning, which
427
+ quotes a terminal, is shown through the display filter.
428
+ - **When a machine has several launch configurations for a harness and no
429
+ default, the Spawn dialog says so and points to the choice, instead of
430
+ "OATS couldn't work out this soul's defaults".** While that refusal
431
+ stands, the first entry of Launch configuration reads "No default: choose
432
+ one" and Spawn stays disabled.
433
+ - **A Start or Restart that stops at a launch prompt says what happened
434
+ and what OATS saw, instead of showing the command-line message.** The
435
+ dialog says that OATS could not confirm the instance finished starting,
436
+ with the kernel's reason, whether an answer was submitted, and that the
437
+ session was kept; the kernel's own message follows under "OATS says:".
438
+ - **A slow Start or Restart waits for OATS's own answer, up to 70 seconds,
439
+ instead of showing a timeout after 20 seconds while the start was still
440
+ going on.** Giving up never ends a start: the server awaits the command
441
+ whatever becomes of the request.
442
+ - **When a Start or Restart works but Claude Code ignores the channel
443
+ option, Desktop says after the start that mail and chat will not wake the
444
+ instance, with what OATS reported.** The start is not shown as a failure:
445
+ the dialog closes and the terminal opens. The notice is shown after a
446
+ Start and a Restart only. After a spawn the Desktop of this release
447
+ shows none: it does not yet read the spawn's answer for it.
448
+
449
+ ## Fixed
450
+
451
+ - **Schedules: an instance whose tmux server is gone reads `stopped`, with
452
+ what to do (#921).** After a reboot, scheduled spawn jobs whose instances
453
+ are gone from tmux show `stopped`, with the command to resume or retire
454
+ them, instead of a silent "still running". Before, a scheduled instance
455
+ whose recorded tmux server was gone (a reboot, a crash) read `unknown`. Its
456
+ spawn job kept its slot and skipped every due minute as `still running`,
457
+ forever, with nothing saying why. Such an instance now reads `stopped`
458
+ with the note `its tmux server is gone`. Its job still keeps its slot and is
459
+ skipped with `previous instance stopped: retire it (oats retire
460
+ <instance>) or start it again (oats session start --home <home>)`, and
461
+ `oats schedule run-now` refuses with the same words (`E_SCHEDULE_RUNNING`,
462
+ which used to say "is still running"). These words apply to every stopped
463
+ instance, one whose harness exited included, not only one whose tmux
464
+ server is gone. Gone is judged as `oats session start` and `stop` judge
465
+ it: no server listens on the socket, or the socket file is missing and no
466
+ process works in the home.
467
+ When a process still works there, the instance stays `unknown`, with that
468
+ reason. See [Schedules](../schedules.md#what-a-run-reports).
469
+
470
+ - **Schedules: wake jobs after a reboot (#921).** A wake job whose
471
+ instance's tmux server is gone now starts that instance's session at its
472
+ next due minute. Before, it waited forever, skipped as unable to observe
473
+ the session. When a process still works in the home, nothing is started.
474
+ See [Schedules](../schedules.md#what-a-run-reports).
475
+
476
+ - **A lifecycle command never answers with a code that is not a kernel code
477
+ (#892, #874 item 3; the raw inner code of #891).** `oats retire`, `oats
478
+ instance stop`, `oats session` and `oats worktree add|remove` answered any
479
+ error that had a `code` with that code, so a file the system refused to
480
+ read, an entry removed while a retire walked the home, a claim directory
481
+ that could not be made or a home removed under a stop came back as `EACCES`,
482
+ `ENOENT`, `EEXIST` or `ENOTEMPTY`, with no statement of what the command had
483
+ done. Such an error is now answered with a documented kernel code
484
+ (`E_WORK_INSPECTION_FAILED` for an entry a retire's inspection cannot read
485
+ or no longer finds; `E_LIFECYCLE_FAILED` for the rest; `E_SESSION_FAILED`
486
+ for `oats session`; `E_SESSION_STOP_FAILED` inside a stop receipt and a
487
+ retire's `childrenStopped`), with the system's own code in the new
488
+ `error.details.cause` (`{code, syscall}`; or `{name}` for a defect of the
489
+ kernel, a `TypeError` and its like, whose stack goes to stderr). A refusal
490
+ the kernel words without a code, and a `tmux` or `git` command that fails,
491
+ are answered as before: the command's general code and the message alone.
492
+ `unsafe-config-key` and `unsafe-config-value` keep their own names. A
493
+ retire's message ends with
494
+ what it had done when it failed, and every error of a retire apply says the
495
+ same as data in the new `error.details.reached`: `{phase,
496
+ sessionStopAttempted, hooksStarted, home, recovery}`. A removal that fails
497
+ after a complete recovery names that recovery. One value of an existing
498
+ field changes: in a failed row of a stop's `results` and of a retire's
499
+ `childrenStopped`, `stillRunning` is `[]` only when the harness exited. A
500
+ stop whose signalled processes are all gone while the session still does
501
+ not read as idle (`… is still running after <n> ms; nothing was escalated`)
502
+ answered `[]` there and now answers `null`: nothing is established, and a
503
+ reader that takes `[]` as "stopped" no longer does so for it. The stop
504
+ receipt file a kernel with the feature stores says that its rows follow
505
+ these rules (`lifecycleKernelCodes: true`, in the file alone); the replay
506
+ of a file without it answers `null` for a failed row's `[]`, and a kernel
507
+ code for a system's. No existing kernel code
508
+ changes its meaning, no exit status changes, and no receipt or plan a
509
+ command answers gains a field. `oats version --json` lists the feature `lifecycle-kernel-codes`
510
+ for all of this: the rule about codes, `details.cause`, `details.reached`
511
+ and what its absence means. A client that matched on a system error's name
512
+ in one of these answers reads `details.cause.code` instead when the probe
513
+ lists the feature, and keeps its guard for a system code when it does not.
514
+ See
515
+ [The envelope](../desktop-cli-api.md#kernel-codes) and
516
+ [`error.details.reached`](../desktop-cli-api.md#retire-reached).
517
+ - **A claim no longer refuses for ever, or spins, about a holder that will
518
+ never act again (#870, #874 items 1 and 2).** The claim is the file that
519
+ lets one `oats retire` of a home, and one `oats worktree add|remove` of a
520
+ purpose, run at a time. Three of its edges are closed:
521
+ - **A holder that has exited or was killed and that its parent has not
522
+ reaped (a zombie) is gone.** It was read as running, so the command
523
+ answered `E_LIFECYCLE_BUSY` "… is already running … wait for it to
524
+ finish" until the parent reaped it, which a parent that never waits does
525
+ not do. Its claim is now taken over as any dead holder's is. The same
526
+ holds for the three other records that name a command by pid and start
527
+ time: a tree record in state `creating` (the next `add` or `remove`
528
+ recovers it), a self-retire's pending marker (the next retire does what
529
+ the completion owed), and a spawn's `inProgress` marker. **A changed
530
+ answer of `oats status --json`:** a spawn whose process is a zombie
531
+ reads as `rollbackIncomplete`, no longer as `spawnInProgress: true`, and
532
+ `oats retire` completes it. A process group that a killed command left
533
+ is still proven by its leader while that leader is a zombie, and its
534
+ members are still ended. The start token a record names (`proc:<ticks>`,
535
+ `ps:<lstart>`) is unchanged, so a claim or a marker written by an older
536
+ kernel still names its live holder.
537
+ - **A path that exists and never reads as a claim is refused, not
538
+ retried without end.** A dangling symbolic link where the claim belongs
539
+ made `oats retire` and `oats worktree add|remove` loop without a pause
540
+ and without an end. Every attempt now pauses, and the command answers
541
+ `E_LIFECYCLE_BUSY` "`<file>` is not a readable claim; inspect it and
542
+ remove it …; nothing was done": a retire, which does not wait, after
543
+ five retries (a quarter of a second); a worktree command, and a
544
+ self-retire's completion, the same five retries after its 3 s wait.
545
+ - **A gone holder whose claim cannot be taken over is said to be gone.**
546
+ A claim file whose holder is gone and whose `nonce` is not the 32
547
+ hexadecimal digits a claim carries (written or damaged by hand) was
548
+ answered as a live holder, to wait for. It, and the claim at the end of
549
+ a chain of dead takeovers too long for the file system to name one
550
+ more (answered until now as `E_LIFECYCLE_FAILED` with `ENAMETOOLONG`
551
+ about a file that does not exist), now answer `E_LIFECYCLE_BUSY` "the
552
+ process that held `<file>` (pid `<pid>`) is gone, and this file is not a
553
+ claim this kernel can take over (`<why>`); nothing was done — inspect
554
+ `<file>` and remove it if no oats retire holds it, then retry".
555
+ `E_LIFECYCLE_BUSY` keeps its meaning (refused before any effect) and no
556
+ JSON shape changes: what changes is when it is answered and, in the two
557
+ cases above, its message. `details.lock` of a worktree command's "not a
558
+ readable claim" and "this process's start time cannot be read" refusals
559
+ now names the file the message names, as a retire's does; it was always
560
+ the purpose's claim, which differs only for the claim of a takeover
561
+ (`<purpose>.lock.reclaim-<nonce>`).
562
+ **One changed answer in a rare race, `oats worktree` only:** a command
563
+ whose takeover ended a dead command's git step and that was then refused
564
+ the claim (another command took it first) answered `E_LIFECYCLE_BUSY`
565
+ "… nothing was done". It now answers `E_LIFECYCLE_FAILED`, naming the git
566
+ group it ended first and then the refusal, with "nothing else was done";
567
+ `details` are the refusal's. The same holds when the system refuses to
568
+ remove that dead command's claim: "… was ended, and the claim it left is
569
+ kept; nothing else was done", where the answer said that nothing was done.
570
+ See
571
+ [`oats worktree`](../desktop-cli-api.md#oats-worktree) and
572
+ [One retire of a home at a time](../desktop-cli-api.md#retire-one-at-a-time).
573
+ - **One instance home whose record cannot be read no longer breaks the others
574
+ (#896, first half).** A home whose `instance.json` was there and could not
575
+ be read as a JSON object (a write cut off, a file kept from the user, JSON
576
+ that is not an object) made `oats status` end with a stack and no answer,
577
+ and made every other instance's stop and retire fail, because the listing
578
+ read every record without a guard. Now that home decides only for itself.
579
+ `oats status` lists every instance, and that home's row has the fields of a
580
+ home with no `instance.json`, with `running: null`, `runtimeState:
581
+ "unreachable"` and `runtimeError: "E_UNIDENTIFIED_INSTANCE_HOME:
582
+ <home>/instance.json cannot be read (<reason>)"`. Every command about
583
+ another instance answers as if that home were not there. The home's own
584
+ `oats retire` (`--plan` and `--force` included), `oats instance stop` and
585
+ `oats session start|restart` are refused with
586
+ `E_UNIDENTIFIED_INSTANCE_HOME` before anything is read, stopped, run or
587
+ removed; a stop and a session start did not answer that code before.
588
+ Restoring the file from a copy makes the home usable again. A home whose
589
+ `instance.json` is there and cannot be read cannot be removed through OATS
590
+ yet, `--force` included. A parent whose record cannot be read has no
591
+ recorded children for a stop or a retire: they are listed and act on their
592
+ own. **What an operator should know:** a home whose record cannot be read
593
+ is never stopped as anyone's child. Its session may go on running under a
594
+ parent that was stopped or retired, and the stop's or the retire's answer
595
+ does not name it; `oats status` is where it shows. A spawn that names such
596
+ a home as its parent or anchor is refused (`E_SPAWN_FAILED`); before, a
597
+ parent record holding `null` let the spawn through as if no child-spawn
598
+ policy were recorded. **One new value in a field the Desktop reads:** a
599
+ stop or retire plan of a home the kernel cannot look into (the directory
600
+ itself kept from the user) says `work: {observed: false, reason:
601
+ "E_WORK_INSPECTION_FAILED"}`, where it said `"no-worktree"`. A home with no
602
+ `instance.json` answers as before, and so does every command when every
603
+ record can be read; no answer gains a field, and there is no new feature
604
+ name. See
605
+ [A home whose `instance.json` cannot be read](../desktop-cli-api.md#unreadable-record).
606
+
607
+ - **Linux: a tmux server first started from inside a systemd service runs in
608
+ its own scope and survives the service** (#915). A tmux server lives in the
609
+ cgroup of the process that started it. When the schedule tick, whose
610
+ oneshot service ends after every tick, was the first to start the OATS tmux
611
+ server, the server and every agent in it died with the tick within a second.
612
+ The run was then recorded `unknown`, and the job was skipped as "still
613
+ running" from then on. The same held for a Desktop run as a user service:
614
+ the next restart of that unit (every Desktop upgrade) took the server and
615
+ every agent with it. Now, on Linux, a creator inside a systemd service starts
616
+ the server with the system's
617
+ `systemd-run --user --scope --collect --quiet --unit oats-tmux-<hash>-<random>`, with
618
+ the same tmux command and environment as before, less any `INVOCATION_ID`
619
+ (the scope's own is removed with the system's `env -u`, so no pane gets it). The server is a sibling of
620
+ the service and outlives it. When `systemd-run` is missing or fails (no user
621
+ bus), the server starts as before, and the spawn or session start answer,
622
+ and the tick's record of that run (feature `schedule-run-warnings`), say
623
+ that it lives inside that unit. macOS, an operator's shell, an agent's pane
624
+ and a server that already runs are unchanged. Nothing has to be reinstalled.
625
+ See [Execution targets](../execution-targets.md#a-server-started-from-inside-a-systemd-service).
626
+
627
+ - <a id="lifecycle-claim-stop"></a>**A stop and a retire of one instance
628
+ no longer run together, and a killed stop no longer strands the stops
629
+ after it (#866, #890, #895).** Feature
630
+ `lifecycle-claim-stop`. `oats instance stop <instance> --apply` now takes
631
+ the claim that orders the retires of a home
632
+ (`<instances>/.oats-retirement/claims/<instance>.lock`, beside the homes),
633
+ for the instance and for every recorded child it would stop, before it
634
+ stops the first one, and holds them until it has written its receipt.
635
+ - **A stop beside a retire in flight is refused** with
636
+ `E_INSTANCE_RETIRING`, "nothing was stopped", and **a retire beside a
637
+ stop** with `E_LIFECYCLE_BUSY`, "nothing was done": at once, before any
638
+ effect. Before, neither saw the other: the stop wrote its marker, its
639
+ event and its receipt into a home the retire was inspecting or
640
+ removing, which could fail the retire closed or leave a directory that
641
+ no command removed. A stop of a parent is refused whole when any of its
642
+ targets is held; two overlapping stops of one parent: one stops
643
+ everything, the other is refused whole. `oats worktree add` in a home
644
+ whose retire is running is refused too (`E_INSTANCE_RETIRING`, "no tree
645
+ was made"): it reads the claim and takes nothing.
646
+ - **A stop that was killed** (SIGKILL, SIGTERM, SIGINT or SIGHUP) left
647
+ `<home>/.oats-stop-pending.json`, a file that named no holder, and every
648
+ later stop of that instance answered `E_LIFECYCLE_BUSY` until someone
649
+ removed it. The file is no longer written or read. A killed stop leaves
650
+ its claim, which the next stop or retire takes over. The name stays
651
+ reserved: a file an older OATS left refuses nothing, does not make a
652
+ plan's `stopPending` true, and is removed by the next stop apply of
653
+ that home.
654
+ - **A holder is answered before a stale plan.** A stop apply compares the
655
+ revision it was sent once, under its claims, as a guarded retire does:
656
+ beside a retire or a stop in flight the answer is that one is running,
657
+ whatever the plan would read by then. `stopPending` and `retiring` stay
658
+ booleans on every target of a stop plan and are now read from the claim
659
+ (`retiring` also from a scheduled self-retire's marker, as before).
660
+ - **`error.details.action`**, the holder's verb (`"retire"`, `"stop"`), on
661
+ these refusals, beside `lock`, `pid` and `since`; a claim without a verb
662
+ (an older kernel's) reads as `"retire"`. `details.instance` and
663
+ `details.home` are of the home whose claim refused: in a recursive stop
664
+ that may be a child of the instance asked for.
665
+ - **`error.details.holder` on every `E_LIFECYCLE_BUSY`** of `oats retire`,
666
+ `oats instance stop` and `oats worktree add|remove`: `"running"` (a
667
+ process with the recorded pid and start time is alive: waiting ends it
668
+ when that process is the `oats` command its file names), `"unknown"`
669
+ (whether one runs cannot be read) or `"none"` (nobody is running: do
670
+ what the message says). A reader treats an unknown value, or the field's absence, as "do
671
+ not promise that waiting ends it". For `"unknown"` and `"none"` the
672
+ message names the step that ends it; four refusals gained one or were
673
+ reworded for it (a claim file that cannot be read, a command whose own
674
+ start time cannot be read, an interrupted add's rollback that could not
675
+ be completed, a tree record written at the same moment).
676
+ **`"running"` is a live process, not a verified command:** a file that
677
+ names any live process reads as `running`, whoever wrote it. So the
678
+ three sentences of a claim whose holder runs now also name the check
679
+ for a holder that does not end, in the words the `unknown` refusal
680
+ already had: `a retire of <name> is already running (pid <pid>, since
681
+ <at>); nothing was done — wait for it to finish; if it does not end,
682
+ check that pid by hand, and if it is not an oats retire, remove <lock>,
683
+ then retry`; `another oats worktree add or remove of purpose <purpose>
684
+ is running (pid <pid> holds <lock>); nothing was done — retry when it
685
+ has finished; if it does not end, …`; and `<name> is being retired (pid
686
+ <pid>, since <at>); nothing was stopped — if it does not end, …`, which
687
+ does not say to wait. The codes and `details` are as they were.
688
+ - **The codes a stop and a retire answer only before any effect are one
689
+ list in the kernel**, by verb, and the docs table is checked against it:
690
+ `E_BAD_ARGS`, `E_PLAN_STALE`, `E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY`,
691
+ `E_HOME_MISMATCH`, `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
692
+ `E_UNIDENTIFIED_INSTANCE_HOME`, and the router's `E_REMOTE_INCOMPATIBLE`,
693
+ `E_AMBIGUOUS` and `E_SNAPSHOT_UNKNOWN`. A listed code that a stop or a
694
+ retire would answer after its first effect is a defect of the kernel,
695
+ answered as one (`E_LIFECYCLE_FAILED`, its stack on stderr), never as
696
+ "nothing happened".
697
+ - **A claim that is taken again and again by commands that die ends in a
698
+ refusal of its own.** A retire, a stop or a worktree command takes over
699
+ the claim of a holder that is gone and tries again. Once its wait is
700
+ over, when it has found the claim without a live holder five times and
701
+ each time found it taken again, the last time by a process that is
702
+ gone, it answers `E_LIFECYCLE_BUSY`, `holder: "none"`: `the claim <file>
703
+ was found without a live holder 5 times and was taken again each time,
704
+ the last time by a process that is gone (pid <pid>); nothing was done —
705
+ run the command again` (a stop says `nothing was stopped`). Nothing is
706
+ wrong with that file, and the next run takes it over. It is not the
707
+ refusal of a file that cannot be taken over, which says to inspect the
708
+ file and remove it.
709
+ - **Text of a claim file is never part of an answer.** A claim is read
710
+ back as whatever is in its file, and the claims of a deployment's homes
711
+ are in a directory that every instance of it can write: an instance
712
+ could put a sentence in `action`, `at`, `pid` or `processStart` and
713
+ have it shown to whoever ran a stop or a retire. A refusal now names
714
+ the holder's pid, its recorded start and the time it took the claim
715
+ only when each has the shape the kernel writes; otherwise the message
716
+ says `?` (`none` for the start), and `details.pid` and `details.since`
717
+ are `null`. `details.action` is `"retire"` or `"stop"`, and anything
718
+ else in the file reads as `"retire"`. The same for the claim of a
719
+ purpose (`oats worktree add|remove`, whose refusal then has no
720
+ `details.pid`), and for the recorded start of a process group whose
721
+ leader cannot be read (a claim's git step, a tree record's or an
722
+ interrupted spawn's hook group): `recorded start none`, and
723
+ `details.gitStart: null`. No answer changes for a file the kernel
724
+ wrote. See
725
+ [`error.details` of a claim's refusal](../desktop-cli-api.md#claim-file-text).
726
+ **The answers that changed** are under
727
+ [Changed](#lifecycle-claim-stop-changed).
728
+ Two kernel versions acting on one deployment at once are not covered: an
729
+ older kernel takes no claim for a stop. Upgrade with no lifecycle command
730
+ in flight. See
731
+ [Commands that meet on one home](../desktop-cli-api.md#lifecycle-pairs),
732
+ [the list](../desktop-cli-api.md#before-effect-codes) and
733
+ [`details.holder`](../desktop-cli-api.md#busy-holder).
734
+
735
+ - **The schedule host timer fires at second 0 of every minute, and the tick
736
+ evaluates the minute it was fired for** (#902). The launchd unit used
737
+ `StartInterval 60`, and the systemd timer `OnUnitActiveSec=60`: both drift
738
+ away from the minute boundary, so a tick fired at 13:59:59 that read the clock
739
+ at 14:00:11 never evaluated 13:59. The units are now calendar timers
740
+ (`StartCalendarInterval`; `OnCalendar=*-*-* *:*:00`, `AccuracySec=1s`,
741
+ `Persistent=false`). The tick takes its minute from its own process start,
742
+ before any work. `startedAt`, `lastTick` and the trigger poll deadline keep
743
+ the real clock. The host state's `minute` only moves forward. Minutes missed
744
+ while the machine slept are still skipped.
745
+ - **The launchd timer runs at the standard process class, not the background
746
+ one** (#902). Under load, a `ProcessType Background` job's node started up to
747
+ about 90 s after launchd fired it, so its minute was evaluated late or lost.
748
+ It is now `ProcessType Standard`. Unverified: work the tick started before
749
+ this change (a tmux server it created, and the agents in it) may have
750
+ inherited the background throttling. If that matters on a host, stop and
751
+ start the OATS tmux server once after reinstalling the unit.
752
+ - **The limit that remains:** the tick evaluates the minute launchd or systemd
753
+ fired it for as long as it starts within that minute. A tick still running
754
+ when the next minute fires loses that minute's fire, on both platforms.
755
+ The bounded catch-up of #902, a separate change, is what recovers it.
756
+ - **The unit no longer carries instance paths or a versioned Homebrew keg**
757
+ (#902). Its `PATH` is the installer's `PATH` without entries inside an OATS
758
+ instance home, inside `…/Cellar/<formula>/<version>/`, or relative and
759
+ empty ones. Its node is the keg's `opt` link, or the same node found on
760
+ `PATH`. Homebrew's `opt` link is what survives an upgrade, so a `brew
761
+ upgrade` does not stop the timer. With a version manager (mise, nvm, asdf,
762
+ fnm) the unit records that version's own path, and `host status` reports
763
+ `node-missing` once that version is removed. When neither exists, `install`
764
+ warns that the node path is not stable.
765
+ - **`oats schedule host status` says when the unit is stale** (#902).
766
+ `scheduler.problems` (always an array, in every list's `scheduler` too) names
767
+ `node-missing`, `oats-bin-missing`, `path-entry-missing` and `unit-outdated`,
768
+ each with its fix. It is read from the unit alone.
769
+ - **`oats schedule host install --print [--os darwin|linux]`** writes to stdout
770
+ what `install` would write and changes nothing. See
771
+ [Schedules](../schedules.md#the-host-timers-unit).
772
+
773
+ ## Removed
774
+
775
+ - **`launchPromptAnswers` decides nothing.** In `oats-local.yaml`, a block
776
+ with only `awebDevelopmentChannel: true` entries, an empty block, or
777
+ `workspaceTrust`, is ignored with one warning per command saying to remove it.
778
+ A home entry `awebDevelopmentChannel: false` is an operator's refusal this
779
+ kernel cannot honour, so it is refused (`E_WORKSPACE_SCHEMA`, reason
780
+ `removed-key`, at that entry), naming the two settings that keep the prompt
781
+ unanswered. Remove the block.
782
+
783
+ ## Provider updates
784
+
785
+ - **oats.aweb 1.27.0 (with 1.25.0, 1.25.1, 1.26.0, 1.26.1 and 1.26.2): OATS
786
+ confirms Claude's development-channel prompt; `oats aweb resident create`;
787
+ grant seats never expire by default; aw floor 1.36.33; OATS floor 0.52.0**
788
+ ([oats-aweb#109](https://github.com/awebai/oats-aweb/pull/109),
789
+ [#107](https://github.com/awebai/oats-aweb/pull/107),
790
+ [#104](https://github.com/awebai/oats-aweb/pull/104),
791
+ [#101](https://github.com/awebai/oats-aweb/pull/101),
792
+ [#99](https://github.com/awebai/oats-aweb/pull/99),
793
+ [#100](https://github.com/awebai/oats-aweb/pull/100),
794
+ [#80](https://github.com/awebai/oats-aweb/issues/80),
795
+ [#58](https://github.com/awebai/oats-aweb/issues/58);
796
+ [#886](https://github.com/awebai/oats/issues/886)). The official catalog,
797
+ reference workspace and generated `mirrors/oats-aweb` take published
798
+ `v1.27.0` at `e47569159d3714448c85945d2fa95d29913ed61b`.
799
+ For operators, from the six versions:
800
+ - **The minimum provider for this release; kernel first** (1.27.0).
801
+ Pin oats.aweb 1.27.0 with OATS 0.52.0: it reads the kernel's record of
802
+ the development-channel confirmation. It needs OATS 0.52.0 or later
803
+ (`compatibility.oats >=0.52.0`), so upgrade OATS first, then `oats sync`.
804
+ An older kernel refuses oats.aweb 1.27.0 with `E_CAPABILITY_INCOMPATIBLE`
805
+ and stays on 1.26.2.
806
+ - **OATS confirms Claude's development-channel prompt** (1.27.0). A Claude
807
+ home in development mode (`claudeChannelMode: development`, the default,
808
+ under `delivery: channel`) no longer stops at the prompt: the kernel
809
+ confirms it once at launch. Spawn apply, start, restart and the start
810
+ preview say so in the `channel-dev-confirmation` warning:
811
+ `settings.oats.aweb.delivery: session` or
812
+ `settings.oats.aweb.claudeChannelMode: approved` stop the prompt
813
+ altogether. Readiness reads the kernel's record of the last start
814
+ (`instance.json` `launchPrompts.status`): `completed` is quiet,
815
+ `flag-ignored` gives `claude-channels-unavailable` (below), and any other
816
+ status, or none, gives that warning. The skill's exact-home
817
+ `launchPromptAnswers` consent is gone; the kernel no longer reads it.
818
+ - **`claude-channels-unavailable`** (1.27.0). When Claude ignored the
819
+ development-channel flag (`launchPrompts.status: flag-ignored`), readiness
820
+ says the home has no channel delivery. Claude Code disables channels when
821
+ its launch environment opts out of telemetry (`DISABLE_TELEMETRY`,
822
+ `DO_NOT_TRACK` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`) or when the
823
+ account or organization has no channels. The remedy is to remove the
824
+ variable, use an account with channels, or set
825
+ `settings.oats.aweb.delivery: session`. The provider never reads or
826
+ changes these variables.
827
+ - **aw floor 1.36.33, hosts first.** Upgrade aw to 1.36.33 or later,
828
+ restart every resident custody service and the host wake daemon, then
829
+ `oats sync`. An already-running custody keeps its old operations until it
830
+ is restarted, so in the other order a grant seat's readiness and spawn
831
+ fail after the sync. A wake daemon below the floor is a warning, not a
832
+ problem.
833
+ - **`oats aweb resident create <name>`** makes a GLOBAL resident identity in
834
+ an existing hosted team from the aweb dashboard's line,
835
+ `AWEB_API_KEY=<key> AWEB_URL=<url> oats aweb resident create <name>`, run
836
+ in the deployment. It runs `aw init --global` once in
837
+ `<deployment>/.aweb-residents/<name>` with the key in that child's
838
+ environment only, verifies the identity, serves it from a per-user custody
839
+ unit (`ai.aweb.custody.<namespace>.<name>`: a launchd agent on macOS, a
840
+ systemd --user unit on Linux), records
841
+ `settings.oats.aweb.residents.<name>` and prints the seat's
842
+ `oats spawn` step. A rerun continues a partial init with the same identity,
843
+ and after success only verifies. `--plan` changes nothing. A custody
844
+ already running for that identity but not from this command's unit is
845
+ refused (`E_RESIDENT_CUSTODY_RUNNING`). No flag takes a key. See the
846
+ provider's `docs/resident-create.md`.
847
+ - **The resident's team is mapped, and the printed next step works**
848
+ (1.26.1). Without `--team-label`, the team is mapped under its name. It
849
+ becomes the default team only where the deployment has none. An existing
850
+ default is never changed: the output then prints
851
+ `oats teams default <label>` as its own first step, saying that it moves
852
+ the whole deployment's default, and that running it is the operator's
853
+ decision. A derived label that already maps to another team is refused
854
+ after `aw init`, naming what is in place and the `--team-label` rerun.
855
+ Mapping needs OATS 0.48.0 or later (`teams-conditional-default`), and
856
+ older kernels are refused before any effect. In 1.26.0, `--team-label`
857
+ could replace a workspace's default team; that is fixed.
858
+ - **A seat verifies senders at its resident's registry** (1.26.1). A grant
859
+ seat on a resident whose recorded AWID registry is not aw's default gets
860
+ `AWID_REGISTRY_URL` from that resident's identity, never from the
861
+ operator's environment. The manifest declares `AWID_REGISTRY_URL` and the
862
+ `AWID_` namespace, so `oats sync`'s trust review shows them.
863
+ - **A resident's seat is ready without a minting root** (1.26.2). In a
864
+ deployment that holds only residents, as `resident create` makes it, a
865
+ seat with `identity.mode: global` and an `identity.resident` no longer
866
+ reports `no messaging root` at readiness. Local mode still needs its
867
+ minting root.
868
+ - **New grant seats never expire.** `identity.ttl` is the one setting that
869
+ keeps a duration (for example `identity: { ttl: 720h }`), and a seat spawned
870
+ earlier keeps its duration at renewal. What bounds a grant now is its
871
+ scopes, revocation at retire and revocation by the resident's owner.
872
+ - **`joined-team-receive` is gone from readiness** (awebai/oats#881): a joined
873
+ team that receives live needs no action. Its receive mode stays in the spawn
874
+ brief and `oats aweb teams --json`.
875
+
876
+ Every grant carries a per-seat label, so a grant left by a crash or a failed
877
+ revoke is found and revoked at the next start or at retire, and a retire exits
878
+ nonzero while any grant stays valid, naming it and its revoke command. Grant
879
+ seats require custody operations `mail_reply_continuation.v1` (E2EE seats)
880
+ and `grant_never_ttl.v1` (never seats). A start waits at most 10 s to check
881
+ for orphaned grants, and an aw call that never exits is reported as timed out.
882
+ Old homes keep their copied modules until respawn.
883
+
884
+ - **oats.okf 5.0.2 is the catalog's version.** The mirror, the catalog and
885
+ this repository's workspace pin move from 5.0.1 to 5.0.2
886
+ (`compatibility.oats >=0.29.0`, unchanged). Instruction text only: an
887
+ instance that captures knowledge, the harvester and the knowledge maintainer
888
+ are told to keep personal data about people outside the team out of notes,
889
+ proposals and concepts, and out of what a harvest publishes (the commit
890
+ message, the pull request and the names in its provenance). It is an
891
+ instruction, not a check in code. A deployment takes it by pinning
892
+ `oats.okf: v5.0.2` and running `oats sync`; a running instance keeps the
893
+ text it was spawned with until it is respawned.
894
+
895
+ - **oats.framework 1.9.3: oats.core 2.5.2, oats.setup 2.5.1,
896
+ oats.knowledge-theory 1.1.1.** Instruction
897
+ text only; no kernel, schema or provider contract changes, and the
898
+ capability floors are unchanged.
899
+ - `oats-operate` (oats.core) says that from OATS 0.52.0 one stop or retire
900
+ of an instance runs at a time, which code each refusal answers
901
+ (`E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY`) and what to do after each
902
+ (#866).
903
+ - `oats-onboarding` (oats.setup) follows oats.aweb 1.26 and oats.okf 5.x:
904
+ `oats aweb resident create` for a GLOBAL resident, and harvest as
905
+ proposals with the soul's own opt-out in place of the removed host
906
+ setting (#901, #904).
907
+ - `oats-workspace-config` (oats.setup) says that from OATS 0.52.0 OATS
908
+ itself confirms development mode's prompt, and lists
909
+ `E_LAUNCH_CONFIG_AMBIGUOUS` with its remedy (#886).
910
+ - The three reference pages of `knowledge-capability-authoring`
911
+ (oats.knowledge-theory) name personal data about people outside the team
912
+ among what is never promoted, as oats.okf 5.0.2 does (#968).
913
+ A deployment takes it at the tag `oats-framework/v1.9.3`; a running
914
+ instance keeps the text it was spawned with until it is respawned. The tag
915
+ `oats-framework/v1.9.2` holds the first three changes without the fourth;
916
+ the catalog goes from 1.9.1 to 1.9.3.
917
+
918
+ ## Documentation
919
+
920
+ - **`/oats-onboarding` names `oats aweb resident create` for a GLOBAL
921
+ resident (oats.framework).** The "Fresh/reused GLOBAL resident and grant
922
+ seat" route points at the one command from oats.aweb 1.26.0
923
+ (aw >= 1.36.33), run with the dashboard's line, `--plan` first. Card 7's
924
+ GLOBAL options are the exact `--provider oats.aweb identity.mode=global
925
+ --provider oats.aweb identity.resident=<name>` that command prints.
926
+ - **`/oats-onboarding` describes oats.okf 5.x harvest (#901).** The skill
927
+ pins `oats.okf` v5.0.2 and states the 5.x model. Souls propose at
928
+ checkpoints and the harvester opens one pull request per proposal. There is
929
+ no host or spawn switch. The one control enforced in code is the soul's own
930
+ `knowledge: { harvest: off }`, per soul, and the exclusions (personal data
931
+ included) are instructions only. The section also gives the move from 4.x:
932
+ settle first, `oats okf setup --remove-legacy-settings` with `--plan`
933
+ first, and respawn 4.x homes.