@awebai/oats 0.51.0 → 0.53.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 (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  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/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
@@ -43,14 +43,16 @@ see the [official catalog](official-catalog.md) for current pins.
43
43
  "preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
44
44
  "workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
45
45
  "automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
46
- "server-probe-features","worktree-event","session-attach-detach-key"],
46
+ "server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
47
+ "lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
48
+ "soul-launch","retire-plan-own-worktree"],
47
49
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
48
50
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
49
51
  "capabilityShowApi":1}
50
52
  ```
51
53
 
52
54
  - The Desktop accepts `desktopApi === 1` and a released `version` inside
53
- `ACCEPT_RANGE` (`packages/desktop/cli-locator.mjs`); a prerelease is never
55
+ `ACCEPT_RANGE` (`packages/client/cli-locator.mjs`); a prerelease is never
54
56
  accepted. The real gate is the feature list; its minimum is
55
57
  `packages-no-approval`.
56
58
  - `harnesses` is what `--harness` accepts; `sessionBackends` what `--backend`
@@ -120,10 +122,17 @@ see the [official catalog](official-catalog.md) for current pins.
120
122
  | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
121
123
  | `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
122
124
  | `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
125
+ | `lifecycle-kernel-codes` | `oats retire`, `oats instance stop`, `oats session …` and `oats worktree add\|remove` answer kernel codes only (`^E_[A-Z0-9_]+$`), in `error.code` and in the codes inside their results, with one exception: a document with an unsafe mapping key or value is refused under its own name, `unsafe-config-key` or `unsafe-config-value`, by these commands as by every other; `error.details.cause` on an error that has a code which is not a kernel code (`{code, syscall}`) and on a defect of the kernel (`{name}`), and none on a refusal that has no code, which is answered with the command's general code and its message alone ([The envelope](#kernel-codes)); `error.details.reached` on every error of a retire apply once the retire of the home has begun, and its absence before that ([`error.details.reached`](#retire-reached)), OATS 0.52.0. Gate on the probe: a kernel without it can answer one of these commands with a system code (`ENOENT`, `EACCES`), and an absent `reached` there says nothing | |
126
+ | `schedule-run-warnings` | a schedule run's record (`lastRun`, `recentRuns[]`) and a trigger fire's record and `lastRun` carry `warnings?`, the launch answer's warnings, when it had some; OATS 0.52.0 ([schedules and triggers](#schedules-and-triggers)) | |
127
+ | `lifecycle-claim-stop` | `oats instance stop --apply` holds the claim of every target (the file one retire of a home at a time is ordered by), so a stop is refused beside a retire in flight (`E_INSTANCE_RETIRING`) or another stop (`E_LIFECYCLE_BUSY`), a retire beside a stop (`E_LIFECYCLE_BUSY`), and `oats worktree add` beside a retire (`E_INSTANCE_RETIRING`), each before any effect ([Commands that meet on one home](#lifecycle-pairs)); a stop that was killed refuses nothing afterwards, and `<home>/.oats-stop-pending.json` is no longer written or read: a client's own handling of a stale stop marker is not needed for a kernel that lists this; `error.details.action` (the holder's verb) on those refusals, and `error.details.holder` on every `E_LIFECYCLE_BUSY` ([`details.holder`](#busy-holder)); the codes a stop and a retire answer only before any effect, as one list ([the list](#before-effect-codes)), with two retire answers that came after an effect given codes outside it (`E_WORK_PRESERVATION_FAILED`, `E_RUNTIME_QUIESCE_FAILED`), OATS 0.52.0. Gate on the probe; routed with `--server`, on the host's list | |
128
+ | `launch-prompt-dev-channel` | the kernel confirms Claude's development-channel prompt whenever it launches Claude with `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`, with no consent setting; `launchPromptAnswers` gone from previews; `consentSource` gone from `launch-prompt` events, which carry `claudeVersion`, `claudeVersionSource` and, on a miss, `differed`; `launchPrompts.status: "not-engaged"` and `"flag-ignored"`; `launchPrompts` in a launched spawn's answer; the `launch-prompt` readiness warning, OATS 0.52.0 ([Launch prompt results](#launch-prompt-results)) | |
129
+ | `soul-launch` | `oats soul launch set\|remove`, the writer of `oats-local.yaml` `souls.launch`, and `E_LAUNCH_PREFERENCE_UNKNOWN`, OATS 0.53.0 ([`oats soul launch`](#oats-soul-launch)). Gate on the probe: a kernel without it answers `E_USAGE` | `soulLaunchApi: 1` (payload only) |
130
+ | `retire-plan-own-worktree` | a retire plan carries `facts.ownWorktree`, a boolean: whether `work/` is the instance's own work tree, the one the retire retains or removes; in `oats retire --plan` and in the fresh plan (`details.plan`) of `E_PLAN_STALE` and `E_CHILDREN_RUNNING`; a stop plan does not carry it; OATS 0.53.0 ([the retire plan](#retire)) | |
123
131
 
124
132
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
125
133
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
126
- `soulsApi: 1`, `teamsApi: 1`, `soulTeamsApi: 1`, `triggerApi: 1`.
134
+ `soulsApi: 1`, `teamsApi: 1`, `soulTeamsApi: 1`, `triggerApi: 1`,
135
+ `soulLaunchApi: 1`.
127
136
 
128
137
  **Gate on the probe, never by trying.** An older kernel can ignore an unknown
129
138
  flag and act: without `lifecycle-plans`, `retire --plan` retires.
@@ -143,6 +152,54 @@ stdout (progress goes to stderr):
143
152
 
144
153
  - Success exits 0, failure nonzero. `error.details` is present only when the
145
154
  command has details.
155
+ - <a id="kernel-codes"></a>**The lifecycle commands answer kernel codes only**
156
+ (`oats retire`, `oats instance stop`, `oats session …`, `oats worktree
157
+ add|remove`; feature `lifecycle-kernel-codes`, OATS 0.52.0). A kernel
158
+ whose probe does not list the feature can answer one of these commands with
159
+ the system's own code (`ENOENT`, `EACCES`, `ENOTEMPTY`) and has no
160
+ `details.cause`: a client keeps its guard for such a code there. Routed
161
+ with `--server`, one of these commands is answered by the host's kernel:
162
+ gate on that host's list (`probe.features` of
163
+ [`oats server roster --json`](#the-remote-roster-oats-server-roster---json)).
164
+ A kernel code is `E_` followed by upper-case letters, digits
165
+ and underscores (`^E_[A-Z0-9_]+$`). The kernel tests that shape, not a list
166
+ of known codes, and the shape is enough: no dependency of the kernel gives
167
+ an error whose code has that shape, and neither does the system (`ENOENT`)
168
+ or Node (`ERR_…`).
169
+ An error that is not the kernel's is answered with the command's general
170
+ code (`E_LIFECYCLE_FAILED`, `E_SESSION_FAILED`, or the one its section
171
+ names). What the answer adds depends on the error:
172
+ - **One that has a code which is not a kernel code** gets
173
+ **`error.details.cause`**, beside the command's other details:
174
+ `{code, syscall}`. `code` is the system's (`ENOENT`), Node's (`ERR_…`),
175
+ or one of the kernel's own lower-case names, which these commands wrap
176
+ like the rest (`invalid-declaration`, `resource-limit`,
177
+ `integrity-drift`, `invalid-source`); `syscall` only when the error has
178
+ one.
179
+ - **A defect of the kernel** gets `details.cause: {name}`, and its stack
180
+ goes to stderr, in JSON and in text mode. A defect is an error without a
181
+ code that is one of the language's own kinds, whose `name` is not
182
+ `"Error"` (`TypeError`, `ReferenceError`, `RangeError`, `SyntaxError`, …),
183
+ or a thrown value that is no error at all (`name` is then `"Error"`; it
184
+ has no stack, and one line on stderr shows the value instead). It is
185
+ answered as one envelope like the rest. One defect has a name of the
186
+ kernel's own, `LateRefusal`: a stop or a retire met, after its first
187
+ effect, an error whose code says that nothing happened
188
+ ([the list](#before-effect-codes)).
189
+ - **A refusal without a code** (the kernel words some of its refusals that
190
+ way, and a `tmux` or `git` command that fails is reported that way) gets
191
+ neither: the general code and its message alone, no `details.cause`, no
192
+ stack. Text mode prints `oats: <message>`, as a kernel without the
193
+ feature does.
194
+
195
+ `cause` holds nothing else: no message, no path, no stack. The same rule
196
+ holds for a `code` inside a result of these commands (a stop receipt's
197
+ `results[].code`, a retire's `childrenStopped[].code`, a plan's
198
+ `session.reason` and `work.reason`). **The one exception:** an OATS
199
+ document with an unsafe mapping key or value is refused under its own name,
200
+ `unsafe-config-key` or `unsafe-config-value`, by these commands as by every
201
+ other; neither is wrapped. Elsewhere an `error.code` may still be the
202
+ system's.
146
203
  - Either envelope may carry `warnings: [ … ]`, only when there is something
147
204
  to say. The one warning is `deprecated-runtime-name`
148
205
  ([Harness input spellings](#the-harness-rename-feature-harness-oats-0270));
@@ -619,6 +676,14 @@ Feature `workspace-v2`, `workspaceApi: 2`. Model: [workspaces.md](workspaces.md)
619
676
  never prompting: `E_REMOTE_UNREADABLE {url, reason: "auth" | "not-found" |
620
677
  "network" | "timeout" | "killed" | "cache" | "unknown"}`. `killed` (the
621
678
  system killed git, for example out of memory) also carries `signal`.
679
+ `network` is what Git's own text shows to be the network (a host that does
680
+ not resolve, a connection refused, reset or closed, a transport that could
681
+ not reach the remote). A failure whose text shows nothing the kernel
682
+ recognises is `unknown` (0.53.0; it read `network` before), and its message
683
+ then ends with Git's own last line: `cannot read remote <url> (unknown):
684
+ <line>`. The line is one line of at most 300 characters, with control
685
+ characters and the user information of any URL removed; when Git said
686
+ nothing, the message ends at `(unknown)`.
622
687
  `cache` (OATS 0.33.0) is local: the
623
688
  remote cache on this machine could not be written (a git lock still held,
624
689
  another oats process still writing it, or a lock file one left when it
@@ -632,7 +697,8 @@ Feature `workspace-v2`, `workspaceApi: 2`. Model: [workspaces.md](workspaces.md)
632
697
  `cacheDir` or other detail field crosses to the renderer. It keys only on
633
698
  `code` + `details.reason`: `cache` words the roster "OATS cache
634
699
  problem" with the message in full; `network` / `timeout` read "Couldn't
635
- reach <host>"; any other reason keeps the generic wording. When the
700
+ reach <host>"; any other reason, `unknown` among them, keeps the generic
701
+ wording with the message in full. When the
636
702
  deployment was observed before, the failed read keeps that observation:
637
703
  `/api/panel` serves it with `error` (the message) and `errorCause {code,
638
704
  reason, host?}`, and the roster shows it stale instead of empty.
@@ -904,6 +970,16 @@ problem`, (feature `souls-capabilities`) `capabilities`, and (feature
904
970
  share a bare name share one entry (spawning that name is
905
971
  `E_SOUL_AMBIGUOUS`).
906
972
  - `launch` is a [Launch](#the-launch-report-launch).
973
+ - **`problems` rows for `souls.launch`** (0.53). `oats souls` adds, after the
974
+ read's own rows, one row per key of `souls.launch` that names no soul:
975
+ `{code: "E_LAUNCH_PREFERENCE_UNMATCHED", path, message, key, value,
976
+ suggestions}`, sorted by key. `path` is where the key is
977
+ (`oats-local.yaml#/souls/launch/<key>`), `key`, `value` and `suggestions`
978
+ as in the refusal's `details.keys`. `message` is at most 1024 characters
979
+ and ends with the two commands, in their order. Each soul a spawn would
980
+ refuse carries the refusal as `launch.problem`: the souls with no entry of
981
+ their own. Text mode prints each row under the table as `! <code>:
982
+ <message>`.
907
983
  - `teams` and `defaultTeam` (feature `team-model-3`) are a
908
984
  [TeamRow](#the-team-row-teamrow) list and a
909
985
  [DefaultTeam](#the-default-defaultteam); both `null` when the soul's teams
@@ -1387,18 +1463,35 @@ oats teams default <label> [--if-absent | --expect <label>] --json
1387
1463
  form `--max-age` (on a write form, `--max-age` is the kernel's own
1388
1464
  `E_BAD_ARGS`, as for every write verb). `--help` is the kernel's usage
1389
1465
  answer, as for every command.
1466
+ - **Rendering** (0.53.0). The file is written without folding lines: a value
1467
+ past 80 columns stays on its line. Before, a write re-wrapped such a line
1468
+ (the same value, over two lines). A file written as JSON (it opens with
1469
+ `{`, and the kernel reads it as strict JSON) is written back as JSON: it
1470
+ keeps the order of its keys and its final newline, or the absence of one,
1471
+ and its indentation becomes two spaces. Before, a write to such a file
1472
+ failed with no answer. A rewrite the kernel could not read back is
1473
+ `E_WORKSPACE_SCHEMA`, and nothing is written.
1390
1474
  - A write that would introduce an unknown reference is refused with that
1391
1475
  code; an invalid result is `E_WORKSPACE_SCHEMA`.
1392
1476
  - **Writes** edit `oats-local.yaml` in place and touch only the entries that
1393
1477
  change: comments and styles elsewhere, including inline comments on sibling
1394
- entries, are kept. Each verb re-reads the file and judges its refusals on it
1395
- as it is now, and writes only if the file did not change meanwhile (else it
1396
- redoes the edit on the new content). A file that keeps changing is
1478
+ entries, are kept. The file is replaced whole, by a rename, and the new
1479
+ file keeps the permission bits of the old one. An `oats-local.yaml` that
1480
+ is a symbolic link is replaced by a regular file with its target's bits,
1481
+ and the target is not written. Each verb re-reads the file and judges its
1482
+ refusals on it as it is now, and writes only if the file did not change
1483
+ meanwhile (else it redoes the edit on the new content). A file that keeps
1484
+ changing is
1397
1485
  `E_LOCAL_CHANGED {path}`; nothing was written. The condition of `--if-absent`
1398
1486
  and `--expect` is judged the same way, on the file as it is now and again on
1399
1487
  every redo.
1400
1488
  - **Concurrency.** Every `add`, `remove` and `default` holds
1401
1489
  `<deployment>/.agents/locks/local.lock` for its whole read-compare-write.
1490
+ Every other kernel command that rewrites `oats-local.yaml` holds the same
1491
+ lock and answers the same two codes: [`oats soul launch
1492
+ set|remove`](#oats-soul-launch), [`oats launch-config
1493
+ set|remove`](#launch-configurations) and [`oats schedule|trigger
1494
+ enable|disable`](#schedules-and-triggers) of a workspace item.
1402
1495
  Among concurrent `oats teams` writers on one deployment, a conditional write
1403
1496
  therefore never overwrites a default another of them set: when two race, the
1404
1497
  later one sees the earlier result and refuses with
@@ -1437,6 +1530,95 @@ oats soul teams <soul>|'*' [--dir <d>] [--max-age <s>] --json
1437
1530
  oats-workspace.yaml (a PR to the workspace file)"}`, before anything else
1438
1531
  is judged.
1439
1532
 
1533
+ <a id="oats-soul-launch"></a>
1534
+ ### `oats soul launch`
1535
+
1536
+ Feature `soul-launch` (OATS 0.53.0). The supported writer of
1537
+ `oats-local.yaml` `souls.launch`, a soul's
1538
+ [launch preference](#launch-preferences) on this machine.
1539
+
1540
+ ```text
1541
+ oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <d>] --json
1542
+ oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <d>] --json
1543
+ ```
1544
+
1545
+ ```json
1546
+ {"soulLaunchApi":1,"action":"set","plan":false,
1547
+ "key":"example.pkg/reviewer","souls":["example.pkg/reviewer"],
1548
+ "level":"/abs/deployment","file":"/abs/deployment/oats-local.yaml",
1549
+ "before":null,"after":"private","changed":true,
1550
+ "launch":{"declared":null,"effective":{"harness":"claude","model":null,"launchConfig":"private"},
1551
+ "from":"local","at":"oats-local.yaml#/souls/launch/example.pkg~1reviewer","problem":null},
1552
+ "unmatched":[],"unread":null}
1553
+ ```
1554
+
1555
+ One closed answer for `set`, `remove` and their plans.
1556
+
1557
+ - **`set`** names the soul as a spawn does (`E_SOUL_UNKNOWN`,
1558
+ `E_SOUL_AMBIGUOUS`) and writes the key that soul has: its bare name, or
1559
+ `<package>/<soul>`. `'*'` is the machine default. Exactly one of
1560
+ `--launch-config` and `--harness`; `--model` only with `--harness`
1561
+ (`E_BAD_ARGS`). Each of them is given once and with a value, and the
1562
+ command takes one name: a flag repeated, a flag with no value at any
1563
+ occurrence, and a second name are `E_BAD_ARGS`, on `remove` too.
1564
+ `--launch-config <name>` writes the name (`none` too) and
1565
+ `--harness` the inline `{harness, model?}`. A harness that is not installed
1566
+ is not refused: `launch.problem` says what a spawn would refuse.
1567
+ - **`remove`** tries its argument **first as the exact text of a key in
1568
+ `souls.launch`**, with no read of the workspace; otherwise it names a soul,
1569
+ as for `set`, and removes that soul's key. Removing the last entry removes
1570
+ `souls.launch`, and `souls` when that leaves it empty.
1571
+ - **`--plan`** runs every check and writes nothing. Its answer is the
1572
+ apply's with `plan: true`, and a state that refuses the apply refuses the
1573
+ plan with the same code. It takes no lock, so it never answers
1574
+ `E_LOCAL_BUSY`.
1575
+ - **The read.** Both forms read the workspace live: `--max-age` is refused
1576
+ (`E_BAD_ARGS`) with and without `--plan`, as for every write verb, and the
1577
+ answer never carries `observation`.
1578
+
1579
+ | Field | Meaning |
1580
+ |---|---|
1581
+ | `action` | `"set"` or `"remove"` |
1582
+ | `plan` | `true`: nothing was written |
1583
+ | `key` | the `souls.launch` key written or removed, exactly as in the file; `"*"` for the machine default |
1584
+ | `souls` | the qualified names of the offered souls that key applies to, sorted. More than one when two members offer a soul of that name: the entry pins all of them. `[]` for a key that is the key of no soul; `null` for `"*"` |
1585
+ | `level`, `file` | the deployment and its `oats-local.yaml` |
1586
+ | `before`, `after` | the entry: `null` (none), a string (a launch configuration's name, or `none`), or `{harness, model}` with `model` `null` when it has none |
1587
+ | `changed` | `false` when the file already said it: nothing was written |
1588
+ | `launch` | the [`Launch`](#the-launch-report-launch) report a spawn with no flags would decide for the named soul, with the file as it is after this change (as it would be, under `--plan`). After a `remove` it shows what the soul falls through to. For a key given by its exact text, the soul is the first of `souls`. `null` for `"*"` and for a key that is the key of no soul |
1589
+ | `unmatched` | the keys of `souls.launch` that are the key of no offered soul after this change, sorted by key: `[{key, at, value, suggestions}]`. `at` is `oats-local.yaml#/souls/launch/<key>` (JSON-pointer escaped), `value` the entry as in `before`, `suggestions` at most three offered soul keys: those with the key's bare name (the part after the last `/`) first, then those within two edits of it. `"*"` is never listed, and neither is a key the read could not check (a member unconfirmed, a soul skipped with a problem, a package declared and not locked). `[]`: no key is known to name no soul |
1590
+ | `unread` | `null`, or `{code, message}` when a `remove` by exact text ran although the workspace's souls could not be read |
1591
+
1592
+ - **Read `unread` first.** When it is not `null`, the answer says nothing
1593
+ about souls: `souls`, `launch` and `unmatched` are `null` for that reason
1594
+ and no other. In every other answer `unmatched` is a list, and `souls` and
1595
+ `launch` are `null` only as the table says.
1596
+ - **The write** is the one `oats teams` makes (above): one entry set or
1597
+ deleted in the parsed document, under
1598
+ `<deployment>/.agents/locks/local.lock`, from the file as it is now, redone
1599
+ when the file changed under it. The file is rewritten, and every other
1600
+ entry keeps its value and its comments. Before the rename the rewritten
1601
+ text is validated against the local schema and read back: it must equal
1602
+ the old value everywhere but the one entry.
1603
+ - **Refusals**, all before a byte of the file changes: `E_USAGE` (no `set` or
1604
+ `remove`; a flag the form does not take, `--home` and `--soul` among them,
1605
+ with `details: {flag}`), `E_BAD_ARGS`, `E_LOCAL_MISSING`, `E_SOUL_UNKNOWN`,
1606
+ `E_SOUL_AMBIGUOUS`, `E_LAUNCH_CONFIG_UNKNOWN {name, from, at}` (a
1607
+ `--launch-config` name this file does not declare: the fact a spawn would
1608
+ report, said before the file holds it), `E_LAUNCH_PREFERENCE_UNKNOWN {key,
1609
+ keys}` (a `remove` of an entry the file does not have; `keys` are the
1610
+ entries it has), `E_LOCAL_BUSY {path, lock}`, `E_LOCAL_CHANGED {path}`,
1611
+ `E_WORKSPACE_SCHEMA` (the rewritten file would be invalid, or the kernel
1612
+ would not decode it, `details: {problems}`; or it would not read back as
1613
+ this one edit, `details: {path,
1614
+ reason: "read-back", differs}` with `differs` the JSON pointers that
1615
+ differ, never their values), and whatever the read of the workspace
1616
+ answers when `set`, or a `remove` that names a soul, cannot read the souls.
1617
+ - Text mode says the same in lines: what was set or removed and in which
1618
+ file; the souls the entry applies to, when more than one; what the next
1619
+ spawn of that soul selects; and each key that still names no soul, with
1620
+ the command that removes it.
1621
+
1440
1622
  ### The messaging provider's teams document
1441
1623
 
1442
1624
  The messaging provider's `teams` operation (`messaging:teams`) is produced by
@@ -1586,7 +1768,9 @@ Every object shape here is closed.
1586
1768
  - **The machine** may override it in `oats-local.yaml` `souls.launch`. A key is
1587
1769
  a soul key (as for `souls.teams`: `"*"`, a bare soul name, or
1588
1770
  `<package>/<soul>`). A value is a `launch-configs` name in the same file, or
1589
- an inline `{harness, model?}` with the soul's rules.
1771
+ an inline `{harness, model?}` with the soul's rules. From OATS 0.53.0 the
1772
+ key is written by [`oats soul launch set|remove`](#oats-soul-launch)
1773
+ (feature `soul-launch`).
1590
1774
  ```yaml
1591
1775
  souls:
1592
1776
  launch:
@@ -1625,14 +1809,111 @@ a running or existing home until `--reselect-launch` or a respawn.** Readiness
1625
1809
  shows the drift as `launch-changed`.
1626
1810
 
1627
1811
  **Refusals** (spawn, preview, and a reselecting start):
1812
+ - `E_LAUNCH_PREFERENCE_UNMATCHED {soul, from, at, keys, fix}` (0.53): the
1813
+ launch names none (no `--launch-config`, no `--harness`; `--model` alone
1814
+ names none), its soul has no `souls.launch` entry of its own, and
1815
+ `souls.launch` holds a key that is the key of no soul the workspace offers.
1816
+ The kernel cannot tell which soul that key was meant to pin, so the launch
1817
+ the fall-through would decide is refused. It is checked before the three
1818
+ refusals below, which describe that fall-through launch. Refused: `oats
1819
+ spawn`, preview and apply, with the same code and `details`, and `session
1820
+ start|restart --reselect-launch`, before anything is created, stopped or
1821
+ started. A soul with its own entry, a launch named by a flag, and a plain
1822
+ start or restart go on.
1823
+ - `soul`: the soul key of the launch refused. `from`, `at`: the layer that
1824
+ would have decided it (`"local-default"`, `"soul"` or `"host"`; `at` as
1825
+ in the `Launch` report, `null` for the host).
1826
+ - `keys`: every such key, sorted by key, `[{key, at, value,
1827
+ suggestions}]`, the rows of `unmatched` in
1828
+ [`oats soul launch`](#oats-soul-launch). A client builds the two
1829
+ commands from `key` and `value`; it does not parse the sentence.
1830
+ - `fix`: "pin the soul each key was meant for (oats soul launch set), then
1831
+ remove the key (oats soul launch remove <key>); or name this launch with
1832
+ --launch-config <name> or --harness <h>". The order is `set`, then
1833
+ `remove`: removing first ends the refusal and leaves the soul on the
1834
+ fall-through.
1835
+ - The message names at most three keys, then "and K more", and it and
1836
+ `fix` are at most 1024 characters each, with no line break, whatever the
1837
+ file holds. `keys` is complete.
1838
+ - No text of a launch answer holds a character the kernel never prints (a
1839
+ control character, a line or paragraph separator, a bidi control, an
1840
+ invisible hider, a tag character): a refusal's `message` and `fix`, a
1841
+ report's `problem`, a problems row. The schema of `oats-local.yaml`
1842
+ admits no key with one, so the file brings none. Were one handed to an
1843
+ answer all the same, the sentence names it with each such character
1844
+ replaced by U+FFFD and gives no command for it: it says the key is
1845
+ deleted from `souls.launch` in the file by hand. `keys[].key` is always
1846
+ the exact key.
1847
+ - **Unmatched, or not checked.** A key other than `"*"` matches when an
1848
+ offered soul has that soul key (a soul in `souls.disabled` included).
1849
+ A key that matches nothing is *not checked*, and refuses nothing, when
1850
+ the source that could hold its soul was not read: a bare key while a
1851
+ member is not confirmed or a member's or an external soul was skipped
1852
+ with a problem; `<package>/…` while that package is declared and not
1853
+ locked, or one of its souls was skipped; every key in the standalone
1854
+ view of a workspace whose host cannot be read. What a read did not
1855
+ record, it did not establish: a read that carries no record of what it
1856
+ skipped leaves every key not checked, and a member whose listing carries
1857
+ none counts as one with a soul skipped. Every other key that
1858
+ matches nothing is unmatched, `<member>/<soul>` among them (a member's
1859
+ soul is keyed by its bare name). When the workspace cannot be read at
1860
+ all, the answer is that read's own error. `"*"` is never reported.
1861
+ - **Where else it is said.** `oats souls` and `inspect --soul`: `launch.problem`
1862
+ on each soul a spawn would refuse, and `oats souls` `problems` gains one
1863
+ row per key (below). `oats doctor`, offline, from this machine's cache:
1864
+ `problems[]` gains `{code, key, at, value, suggestions, message,
1865
+ remedy}` per key (text: `! <code>: <message>`, then the remedy), whose
1866
+ message says that it speaks about this machine's last read of the souls
1867
+ and that a spawn reads the workspace itself and is the authority. For a
1868
+ key that read could not check, and when the cache cannot answer, doctor
1869
+ adds an `information[]` line that starts `launch-preference-unchecked:`.
1870
+ The line is information: it changes no exit status and refuses nothing.
1871
+ `inspect --home` `launchCurrent` and readiness `launch-changed` make no
1872
+ read of the workspace and do not carry this problem; the
1873
+ `--reselect-launch` they point to refuses.
1628
1874
  - `E_HARNESS_UNAVAILABLE {harness, from, at, fix}`: the chosen harness has no
1629
1875
  executable on this machine. There is no fallback to another harness. `fix`
1630
- is "install <harness>, or override it on this machine in oats-local.yaml
1631
- souls.launch" (from the soul or the host), "install <harness>, or change
1632
- oats-local.yaml souls.launch" (from local layers), or "install <harness>, or
1633
- choose another --harness / --launch-config" (from a flag).
1876
+ names the command that pins the soul (0.53), by the layer that chose the
1877
+ harness:
1878
+ - the soul's own `launch:` or the host default: "install <harness>, or pin
1879
+ this soul on this machine (oats soul launch set <soul> --launch-config
1880
+ <name> | --harness <h>)";
1881
+ - the soul's own entry of `souls.launch`: "install <harness>, or pin this
1882
+ soul to another launch (oats soul launch set <soul> --launch-config <name>
1883
+ | --harness <h>)";
1884
+ - `souls.launch."*"`: "install <harness>, name another launch for every soul
1885
+ without an entry (oats soul launch set '*' --launch-config <name> |
1886
+ --harness <h>), or pin this soul to its own (oats soul launch set <soul>
1887
+ --launch-config <name> | --harness <h>)";
1888
+ - a flag: "install <harness>, or choose another --harness / --launch-config".
1889
+
1890
+ The message says why, names the layer's location (`at`) and ends with the
1891
+ `fix`. It stays within 1024 characters: a location too long for that gives
1892
+ way to the layer in words ("the soul's own launch", for example), and
1893
+ `details.at` keeps it.
1634
1894
  - `E_LAUNCH_CONFIG_UNKNOWN {name, from, at}`: `souls.launch` names a launch
1635
- configuration this `oats-local.yaml` does not declare.
1895
+ configuration this `oats-local.yaml` does not declare. As a `Launch`
1896
+ report's `problem`, its `fix` is "declare launch configuration <name> (oats
1897
+ launch-config set), or pin the soul to another (oats soul launch set <soul>
1898
+ --launch-config <name>)"; where `souls.launch."*"` named it, "declare launch
1899
+ configuration <name> (oats launch-config set), name another for every soul
1900
+ without an entry (oats soul launch set '*' --launch-config <name>), or pin
1901
+ the soul to one (oats soul launch set <soul> --launch-config <name>)".
1902
+ - `E_LAUNCH_CONFIG_AMBIGUOUS {harness, configurations, fix}` (spawn and its
1903
+ preview only, 0.52): the chosen harness has more than one launch
1904
+ configuration here (`configurations`, all their names, sorted; the message
1905
+ names the first 10, then "and K more", and fewer where it would otherwise
1906
+ pass 1024 characters),
1907
+ none is
1908
+ `default: true`, and the spawn named none. Named means `--launch-config
1909
+ <name>`, `--launch-config none`, or a `souls.launch` string; an inline or
1910
+ soul preference and `--harness` alone are not. `fix` is "name one with
1911
+ --launch-config <name>, pin the soul to one (oats soul launch set <soul>
1912
+ --launch-config <name>), or mark one default: true (oats launch-config
1913
+ set)"; where `souls.launch."*"` chose the harness it also says, before the
1914
+ soul's own pin, "name one for every soul without an entry (oats soul launch
1915
+ set '*' --launch-config <name>)". A start or restart of an existing
1916
+ home, `--reselect-launch` included, is never refused this way.
1636
1917
  - `E_WORKSPACE_SCHEMA`: a malformed `launch` or `souls.launch`, path named.
1637
1918
 
1638
1919
  ### The launch report (`Launch`)
@@ -1656,9 +1937,18 @@ shows the drift as `launch-changed`.
1656
1937
  `"oats-local.yaml#/souls/launch/*"`, `"<repoKey>:<path>/soul.yaml#/launch"`,
1657
1938
  or `"package:<id>:<path>/soul.yaml#/launch"`.
1658
1939
  - `problem`: `null`, or `{code, message, fix}` when a spawn would refuse
1659
- (`E_HARNESS_UNAVAILABLE`, `E_LAUNCH_CONFIG_UNKNOWN`, or `E_LAUNCH_EXECUTABLE`
1660
- for a configuration whose own executable is missing). Only reports carry it;
1661
- spawn and preview refuse instead. With `E_LAUNCH_CONFIG_UNKNOWN`,
1940
+ (`E_LAUNCH_PREFERENCE_UNMATCHED`, before any other, with `effective` the
1941
+ launch the fall-through would have given; `E_HARNESS_UNAVAILABLE`,
1942
+ `E_LAUNCH_CONFIG_UNKNOWN`,
1943
+ `E_LAUNCH_CONFIG_AMBIGUOUS` with `effective.launchConfig` `null`, or
1944
+ `E_LAUNCH_EXECUTABLE` for a configuration whose own executable is missing). Only reports carry it;
1945
+ spawn and preview refuse instead. A `fix`, here and in a refusal's
1946
+ `details`, is a sentence for a person: its wording may change between
1947
+ releases, so a client shows it and never parses it. A report states a
1948
+ condition, where a refusal states what was refused: for
1949
+ `E_LAUNCH_PREFERENCE_UNMATCHED` the report's `message` names the keys and
1950
+ the layer that would decide, and ends "it would be refused."; it does not
1951
+ repeat the remedy, which is its `fix` (the refusal's `details.fix`). With `E_LAUNCH_CONFIG_UNKNOWN`,
1662
1952
  `effective` is the host default (`pi`, `null`, `null`): the named
1663
1953
  configuration launches nothing here.
1664
1954
  - In listings (`oats souls`, `inspect --soul`, `launchCurrent`) `model` is the
@@ -1708,47 +1998,90 @@ the result with `oats inspect --soul <name> --json`.
1708
1998
 
1709
1999
  ## Launch prompt results
1710
2000
 
1711
- Spawn preview adds `launchPromptAnswers` with the strict effective boolean
1712
- `awebDevelopmentChannel` and `consentSource` (a config-file
1713
- JSON pointer or `null`). This is a policy report, not a terminal observation
1714
- or readiness assertion. Only the aweb development-channel confirmation is
1715
- covered, restricted to the qualified Claude executable digest, platform and
1716
- geometry documented under [launch consent](configuration.md#exact-home-launch-prompt-consent).
1717
- Folder-trust prompts remain unexpected and blocked.
2001
+ A launch engages the development-channel confirmation exactly when it starts
2002
+ Claude with `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`
2003
+ in its argv ([configuration](configuration.md#the-development-channel-confirmation)).
2004
+ There is no policy field: no preview carries `launchPromptAnswers`. Instead,
2005
+ `launch-config preview`, the spawn apply's `warnings` and `session start|restart`'s
2006
+ `warnings` carry one statement, a fixed string beginning `This start passes
2007
+ --dangerously-load-development-channels`, when the start engages it. `spawn
2008
+ --preview` does not: the argv comes from the provider's spawn hook, which a
2009
+ preview does not run. Folder-trust prompts remain unexpected and blocked.
2010
+
2011
+ The home's `instance.json` `launchPrompts` always describes the last start
2012
+ (spawn, start or restart):
2013
+
2014
+ - `{status: "not-engaged", startId, at}` for a start that did not engage it, with
2015
+ no `launchPromptTarget`;
2016
+ - `{status: "flag-ignored", reason: "channels-unavailable", signatureId, startId,
2017
+ at}` for a start where Claude ignored the flag: a notice block on its screen
2018
+ equalled the `flag-ignored` tolerance entry `signatureId`, Claude showed no
2019
+ confirmation and no key was sent. No screen text is recorded. The start
2020
+ succeeds (`launched: true`) and its `warnings` carry, in place of the statement
2021
+ beginning `This start passes`, a fixed string beginning `Claude reported
2022
+ that channels are not currently available and ignored the development-channel
2023
+ flag`. `launchPromptTarget` is the pane. Claude Code disables channels when telemetry is opted out (`DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`), so a launch
2024
+ environment with any of them set gets this status too;
2025
+ - otherwise the observed result `{status, answers, reason, receipt}`, `status`
2026
+ one of `completed`, `blocked`, `incomplete`. After the Enter, no complete
2027
+ clean `SETTLE` window within the 30 s bound is `status: "blocked"` with
2028
+ `reason: "blocked: observation timeout"` and the submitted Enter in `answers`;
2029
+ `incomplete` means an audit, input or evidence failure. A
2030
+ `blocked` result also carries
2031
+ `differed: {nearest, firstDifference: {index, expected, found}}` (the nearest
2032
+ tolerance entry and at most 40 characters of each normalized text at the first
2033
+ difference) and, when the blocked screen before any Enter started with Claude's
2034
+ running-session banner, `claudeSessionShown: true` (the error and the readiness
2035
+ remedy then add that Claude may have ignored the flag with its notice hidden).
2036
+ `launchPromptTarget` is the pane.
2037
+
2038
+ A `--no-launch` spawn records no `launchPrompts`. Readers must treat
2039
+ `not-engaged` and `flag-ignored` like an absent value: retire and replay act only
2040
+ on `blocked` and `incomplete`.
1718
2041
 
1719
- An observed launch has `launchPrompts: {status, answers, reason, receipt}`.
1720
2042
  `receipt` carries the actual checked launch-prompt event-write results,
1721
2043
  including partial log availability; it is not a receive-readiness receipt.
1722
- The `launch-prompt` event records the launch start and pane/PID identity,
1723
- consent provenance, signature identifier/digest, action and outcome. Intent is
1724
- durable before input; submission (`submitted`, `failed`, `uncertain`) and an
1725
- observed screen transition are distinct. Unexpected raw screen text is never
1726
- included in the receipt.
2044
+ The `launch-prompt` event records the launch start and pane/PID identity, the
2045
+ Claude version read from the executable's real path (`claudeVersion`, a semver
2046
+ or `"unknown"`; `claudeVersionSource`, `"executable-path"` or `"unknown"`; it is
2047
+ `"unknown"` when Claude is started through a wrapper, whose path carries no
2048
+ version), the matched entry (`signatureId`) and digest, action and outcome; a miss adds
2049
+ `differed` (and `claudeSessionShown` as above); a start where Claude ignored the
2050
+ flag is one row, `status: "flag-ignored"`, `reason: "channels-unavailable"`, with
2051
+ the `flag-ignored` entry as `signatureId` and no `key`. It carries no `consentSource`. Intent is durable before input;
2052
+ submission (`submitted`, `failed`, `uncertain`) and an observed screen
2053
+ transition are distinct. Beyond `differed`'s bounded snippets, raw screen text
2054
+ is never included in the receipt.
1727
2055
 
1728
2056
  Spawn and start both reuse `E_SPAWN_INCOMPLETE` for retained prompt outcomes,
1729
2057
  with `launchPrompts.status` set to `blocked` or `incomplete`. Error details
1730
2058
  preserve `instance`, `home`, `launched:"unknown"`, `unconfirmed:true` and add
1731
2059
  `retained:true`, `target`,
1732
2060
  `parentLineageCommitted`, and `launchPrompts`. Unknown prompts report
1733
- `blocked: unexpected prompt`. An incomplete audit can follow a possible key;
1734
- clients must not offer automatic key retry. `launched:false` in retained
1735
- metadata does not mean there is no process or that another harness may be
1736
- allocated. Use runtime inspection and the existing start/restart lifecycle.
1737
- Same-key spawn replay cannot convert a blocked outcome to successful spawn.
2061
+ `blocked: unexpected prompt`. A start whose answer was submitted but that showed no
2062
+ complete clean `SETTLE` window (2 s) within the bound reports `blocked` with
2063
+ reason `blocked: observation timeout`, its `answers` holding the submitted Enter. An incomplete audit can follow a
2064
+ possible key; clients must not offer automatic key retry. `launched:false` in
2065
+ retained metadata does not mean there is no process or that another harness
2066
+ may be allocated. Use runtime inspection and the existing start/restart
2067
+ lifecycle. Same-key spawn replay cannot convert a blocked outcome to successful
2068
+ spawn.
1738
2069
 
1739
2070
  `answers` can contain a `submitted` answer even when the final status is
1740
- `blocked`: even after exact or structural completion recognition is qualified,
1741
- unsupported input/footer shapes and known question markers can block after Enter
1742
- while the actual pane is active. Consumers must preserve that submitted receipt
1743
- and never translate this outcome into “nothing started” or automatic retry.
1744
- The [completion limitation](configuration.md#exact-home-launch-prompt-consent)
1745
- is part of the shipping contract. Structural completion closes observation only;
1746
- unknown dialogs retaining the recognized composer/footer can be misclassified.
1747
- Mandatory structural evidence-save failure reports checked `incomplete` with the
1748
- same answer and target preserved. Private receipt v2 adds no public DTO fields.
1749
-
1750
- Strict Desktop/pi readers must accept these additive fields and the new event
1751
- kind before a writer containing them ships. For operator recovery, see
2071
+ `blocked`: a known question marker after the Enter, or the confirmation coming
2072
+ back, blocks while the actual pane is active. Consumers must preserve that
2073
+ submitted receipt and never translate this outcome into “nothing started” or
2074
+ automatic retry. The [completion rule](launch-prompt-completion.md) closes
2075
+ observation only; an unknown dialog without a marker can be reported completed.
2076
+ A private evidence-save failure on completion reports checked `incomplete` with
2077
+ the same answer and target preserved. Private receipt v2 adds no public DTO fields.
2078
+
2079
+ Readiness of a home whose last start recorded `blocked` carries a `launch-prompt`
2080
+ warning (`required: false`, `producer: "launch prompt"`) naming what differed and
2081
+ both remedies; it clears when a later start records anything else.
2082
+
2083
+ Strict Desktop/pi readers must accept these additive fields before a writer
2084
+ containing them ships. For operator recovery, see
1752
2085
  [launch prompt outcomes](execution-targets.md#launch-prompt-outcomes).
1753
2086
 
1754
2087
  ## Spawn
@@ -1813,7 +2146,7 @@ it to a temporary copy (`soulFetched: true`).
1813
2146
  none` ([the worktree event](capabilities.md#the-worktree-event)).
1814
2147
  - `subject` echoes `{soul, agentsRoot, dir}` byte-exact.
1815
2148
  - `warnings`, present only when there is one, is an array of strings: the
1816
- launch-prompt notice, and (0.49.0) the message of each
2149
+ `launchPromptAnswers` notice when the host file still has that key, and (0.49.0) the message of each
1817
2150
  [capability warning](#capability-warnings-hook-event-unsupported-oats-0490)
1818
2151
  of the resolved modules. The apply's `warnings` carries the same messages.
1819
2152
 
@@ -1949,6 +2282,19 @@ with `--expect-decision` records the key and decision in `instance.json`.
1949
2282
  model, parent,
1950
2283
  sibling, relation, spawnOrigin (operator | instance), attach, launchConfig,
1951
2284
  launch` (the redacted recipe).
2285
+ - `launchPrompts` (0.52.0), on a launched spawn: the value its start recorded in
2286
+ `instance.json`, in exactly the shape a start's answer carries it (see `oats
2287
+ session start`'s result below and [Launch prompt results](#launch-prompt-results)):
2288
+ `{status: "not-engaged", startId, at}`, `{status: "flag-ignored", reason:
2289
+ "channels-unavailable", signatureId, startId, at}`, or the observed
2290
+ `{status: "completed", answers, reason, receipt}`. A `blocked` or
2291
+ `incomplete` outcome is `E_SPAWN_INCOMPLETE` instead. A `--no-launch` spawn
2292
+ has none. A replay (`replayed: true`) carries the value the home holds when
2293
+ it is asked, which is the last start's and not always this spawn's. Its
2294
+ `warnings` are the capability contract warnings alone: the warnings of the
2295
+ launch itself (that OATS confirms the prompt, or that Claude ignored the
2296
+ flag) are not repeated, and `launchPrompts.status` is where a replay says
2297
+ it.
1952
2298
  - `tmux.socket` is the absolute socket of the tmux server the window was
1953
2299
  created on; a launched spawn has it, a `--no-launch` one does not. It is
1954
2300
  the OATS tmux server's
@@ -2084,9 +2430,50 @@ Every `add` or `remove` that reads a record it may act on holds the
2084
2430
  purpose's claim, `<home>/.oats/trees/<purpose>.lock`. The claim is a file
2085
2431
  that names its holder by pid and start time. A second command waits up to
2086
2432
  3 s for a live holder, then answers `E_LIFECYCLE_BUSY` (`details.lock`,
2087
- `details.pid`). A claim whose holder has died, for example one killed in the
2433
+ `details.pid`, and [`details.holder`](#busy-holder) on this and on every
2434
+ other `E_LIFECYCLE_BUSY` of these commands: OATS 0.52.0): `another oats
2435
+ worktree add or remove of purpose <purpose> is running (pid <pid> holds
2436
+ <lock>); nothing was done — retry when it has finished; if it does not end,
2437
+ check that pid by hand, and if it is not an oats worktree command, remove
2438
+ <lock>, then retry` ([a live process](#busy-holder-running), not a verified
2439
+ command). A claim whose holder has died, for example one killed in the
2088
2440
  middle of a recovery, is taken over by the next command. So a killed `add`
2089
- or `remove` can always be run again.
2441
+ or `remove` can always be run again. A holder that has exited or was killed
2442
+ and that its parent has not reaped (a zombie) has died: its claim is taken
2443
+ over, and a `creating` record whose adder is a zombie is recovered, without
2444
+ waiting for that reap (0.52.0, #870).
2445
+
2446
+ Two files at the claim's path are never taken over and never removed
2447
+ (0.52.0, #874). The command answers `E_LIFECYCLE_BUSY`, in one line that
2448
+ names the file, says that nothing was done and never says that a command is
2449
+ running: at once for a file it has read, and for a path that exists and
2450
+ reads as absent after its 3 s wait and five more attempts, 50 ms apart; `details.lock` is the file the
2451
+ message names (for the claim of a takeover, `<lock>.reclaim-<nonce>`):
2452
+
2453
+ - A path that is no readable claim: a file that does not parse, a directory,
2454
+ or a path that exists and cannot be read, such as a dangling symbolic link.
2455
+ `<file> is not a readable claim; nothing was done — inspect it and remove
2456
+ it if no oats worktree command holds it, then retry`.
2457
+ - A claim whose holder is gone and that this kernel cannot take over: its
2458
+ `nonce` is not the 32 hexadecimal digits a claim carries (a file written
2459
+ or damaged by hand); or it is the claim of a takeover that died, at the
2460
+ end of a chain of them so long that the system will not name the claim of
2461
+ one more (each adds 41 bytes to the file's name: four or five on a file
2462
+ system whose names are 255 bytes at most). `the process that held <file>
2463
+ (pid <pid>) is gone, and this file is not a claim this kernel can take
2464
+ over (<why>); nothing was done — inspect <file> and remove it if no oats
2465
+ worktree command holds it, then retry`. Removing that one file lets the
2466
+ next command take the rest over.
2467
+
2468
+ A claim that is taken again and again by commands that die is neither of
2469
+ those (0.52.0). A command takes over the claim of a holder that is gone and
2470
+ tries again. Once its 3 s are over, when it has found the claim without a
2471
+ live holder five times and each time found it taken again, the last time by
2472
+ a process that is gone, it answers `E_LIFECYCLE_BUSY` with `holder: "none"`:
2473
+ `the claim <file> was found without a live holder 5 times and was taken
2474
+ again each time, the last time by a process that is gone (pid <pid>);
2475
+ nothing was done — run the command again`. Nothing is wrong with that file
2476
+ and nothing is to be removed: the next run takes it over.
2090
2477
 
2091
2478
  A killed parent does not take its running git with it. So every git step
2092
2479
  that changes a tree, a ref or the worktree list runs in its own process
@@ -2100,6 +2487,16 @@ step that times out is cleared from the record only once its whole process
2100
2487
  group is gone. A git step that cannot be ended keeps the claim, or the
2101
2488
  record, and the command answers `E_LIFECYCLE_BUSY`.
2102
2489
 
2490
+ `E_LIFECYCLE_BUSY` says that nothing was done, so it is never answered once
2491
+ a takeover has ended a dead command's git step (0.52.0). A command that
2492
+ ends such a step and is then refused the claim (another command took it
2493
+ first, it is held again by a process that is gone, or the system refuses
2494
+ it) answers `E_LIFECYCLE_FAILED`. Its message names the group it ended
2495
+ first, then the refusal it met, with "nothing else was done": `git process
2496
+ group <pgid>, left running by a killed oats worktree command, was ended;
2497
+ after that: <the refusal>`. `details` are that refusal's own. Run the
2498
+ command again: nothing of that step is left to end.
2499
+
2103
2500
  A recorded hook group or git step that still has members while its leader's
2104
2501
  start cannot be read (where `ps` fails) is never signalled and never passed
2105
2502
  over: the leader may still be that hook or git step. The command answers
@@ -2116,19 +2513,20 @@ A failed `add` reports the same facts about its rollback in `details`:
2116
2513
  | Code | When |
2117
2514
  |---|---|
2118
2515
  | `E_BAD_ARGS` | not run from an instance home; `--dir`, `--home` or `--server`; a missing value; a value starting with `-`; an invalid purpose, branch or base; `remove` of a purpose with no record (a tree made with raw Git is removed with `git worktree remove`) |
2119
- | `E_INSTANCE_RETIRING` | `add` in a quarantined home, or one being retired |
2516
+ | `E_INSTANCE_RETIRING` | `add` in a quarantined home; in one for which a self-retire is scheduled; or in one whose retire is running (OATS 0.52.0: `add` reads the home's claim and takes nothing; `<instance> is being retired (pid <pid>, since <at>); no tree was made — if it does not end, check that pid by hand, and if it is not an oats retire, remove <lock>, then retry`, `details: {instance, home, lock, pid, since, action: "retire"}`; [Commands that meet on one home](#lifecycle-pairs)) |
2120
2517
  | `E_CLONE_MISSING` | the repository is not found, or is not a Git repository |
2121
2518
  | `E_CLONE_MISMATCH` | the path is a linked worktree, or the clone has no `origin` |
2122
2519
  | `E_BRANCH_EXISTS` | the branch exists in the clone (before the tree is made, or made by another `add` at the same moment); `details.remedy` is `<instance>/<branch>` |
2123
2520
  | `E_GIT_FAILED` | a Git step failed on its own (`git worktree add`, or `git switch` while the branch does not exist), with Git's message: `git <sub> failed in <dir>: …`; the tree is removed |
2124
2521
  | `E_PLACEMENT_TAKEN` | a `ready` record with another clone, branch or base (`details.differ`); `.work-<p>` with no record, or a file or symbolic link there; an unreadable record |
2125
- | `E_LIFECYCLE_BUSY` | an add of that purpose is still running (pid and start time verified); another add or remove of that purpose holds its claim (`details.lock`); or an interrupted add's rollback could not be completed (`details.owed`) |
2522
+ | `E_LIFECYCLE_BUSY` | an add of that purpose is still running (pid and start time verified); another add or remove of that purpose holds its claim (`details.lock`); a file at the claim's path is no claim this kernel can read or take over (`details.lock`); the claim was taken again, the last time by a process that is gone, each of the five times the command found it without a live holder (`run the command again`); an interrupted add's rollback could not be completed (`details.owed`; the message says what to deal with and to run `oats worktree remove --purpose <purpose>`, which finishes the rollback); or, `add` only (OATS 0.52.0), the home's claim is held by a retire whose liveness cannot be read, or is a file that is no readable claim (`no tree was made`; [Commands that meet on one home](#lifecycle-pairs)). Every one carries [`details.holder`](#busy-holder) |
2126
2523
  | `E_REMOTE_UNREADABLE` | the fetch of `<base>` from `origin` failed; the tree is removed |
2127
2524
  | `E_BASE_UNKNOWN` | the new HEAD is not the fetched commit; the message names both |
2128
2525
  | `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT` | a required `worktree` hook failed or timed out, or a hook answered `env`; the tree is removed (`details.hooks`, `details.rolledBack`) |
2129
2526
  | `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
2130
2527
  | `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message); the record is kept. Commit and push, or discard, then retry |
2131
2528
  | `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or the tree is still there; the record is kept |
2529
+ | `E_LIFECYCLE_FAILED` | an error that is not the kernel's; with [`details.cause`](#kernel-codes) when it has a code of its own or is a defect, and without it when it is a refusal without a code. When it is the purpose's claim that could not be taken (`<home>/.oats/trees` cannot be made, the claim's file cannot be written), the message is `the claim <path> could not be taken (…); nothing was done`. Also a command that was refused the claim after its takeover had ended a dead command's git step: the message names the group it ended first, then the refusal, and `details` are that refusal's (a refusal of the kernel's has no `details.cause`; anything else has it by the same rule) |
2132
2530
 
2133
2531
  A rollback that cannot finish keeps the record and says so in the message
2134
2532
  (`details.rolledBack: false`, `details.owed`); the next `add` or `remove` of
@@ -2232,6 +2630,10 @@ its absence.
2232
2630
  `soulSource` (`{repoKey, commit, path, current?, status?}`, `current` or
2233
2631
  `moved`) for a workspace soul; `retireFailures[]` (`{instance, completedAt,
2234
2632
  error, incomplete, retry, resultPath}`) when a deferred self-retire failed.
2633
+ An entry stays until a retire of the instance completes or its result
2634
+ file is removed by hand, whether or not the instance's row still has
2635
+ `retirePending`
2636
+ ([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
2235
2637
  A capability agent's row is `{name, kind: "capability", capability,
2236
2638
  description, dir, instances}`.
2237
2639
  - **Instance rows**: the home's `instance.json` (launch recipe and command
@@ -2249,6 +2651,20 @@ its absence.
2249
2651
  in the row),
2250
2652
  `identity` when a provider recorded one, `rollbackIncomplete` and
2251
2653
  `retirePending` when present, and the Desktop facts below.
2654
+ - <a id="unreadable-record-row"></a>**A home whose `instance.json` cannot be
2655
+ read** (OATS 0.52.0) is listed like every other, and one such home never
2656
+ fails the listing. Its row has the fields of a home with no `instance.json`
2657
+ and nothing from the record: `instance`, `home`, the Desktop facts
2658
+ (`startedAt`, `identityAddress`, `modelFrom`, each `null`), `waitingOnYou:
2659
+ null`, `rollbackIncomplete` and `retirePending` when present, and `running:
2660
+ null` with `runtimeState: "unreachable"` and `runtimeError:
2661
+ "E_UNIDENTIFIED_INSTANCE_HOME: <home>/instance.json cannot be read
2662
+ (<reason>)"`. The reason is the system's (`EACCES: permission denied`), the
2663
+ parser's (a file cut off, or empty), or what the file is instead: a
2664
+ directory, a symbolic link to nothing, JSON that is not an object. A home
2665
+ with no `instance.json` keeps its row: the same fields, `running: false`
2666
+ and no `runtimeState`. What the lifecycle commands answer for such a home:
2667
+ [below](#unreadable-record).
2252
2668
  - **`spawnInProgress`** (feature `worktree-event`, OATS 0.49.0): `true` only
2253
2669
  while a spawn that is running its `worktree` hooks is verifiably alive (its
2254
2670
  pid runs with the recorded start time). Such a home holds the quarantine marker
@@ -2258,7 +2674,11 @@ its absence.
2258
2674
  gone, or when its start time cannot be read (where `ps` fails), the row
2259
2675
  carries `rollbackIncomplete` as for any quarantine, its `inProgress` naming
2260
2676
  the pid; retire still refuses an unreadable one with `E_LIFECYCLE_BUSY`
2261
- until `--force`. Absent otherwise, and from older kernels.
2677
+ until `--force`. A spawn whose process has exited or was killed and that
2678
+ its parent has not reaped (a zombie) is gone (0.52.0, #870): its row
2679
+ carries `rollbackIncomplete`, where before it read `spawnInProgress: true`
2680
+ until the reap, and retire completes it. Absent otherwise, and from older
2681
+ kernels.
2262
2682
  - **`waitingOnYou`** (feature `waiting-on-you`): `{since, producer, reason,
2263
2683
  message}` when the row is `running: true` and a producer holds a live claim
2264
2684
  that the instance needs input from a human, else `null` (unknown, not "not
@@ -2600,6 +3020,19 @@ that name: `E_AMBIGUOUS_INSTANCE {candidates: [{root, agent, home}]}` (pass
2600
3020
  `--home`; a wrong one is `E_HOME_MISMATCH`). Unknown: `E_SESSION_UNKNOWN`. No
2601
3021
  tree: `E_NO_WORKTREE`.
2602
3022
 
3023
+ `E_NO_WORKTREE` is answered when nothing is at `<home>/work`, when it is not
3024
+ inside a Git work tree, and (0.53.0, #962) when it is a real directory that
3025
+ is not the top level Git names for it. Git answers for any directory inside
3026
+ a work tree, so a plain `work/` in a home whose deployment directory is a
3027
+ Git checkout was read as that checkout before: its branch and its files,
3028
+ none of them the instance's. The rule is the path, in every work mode: a
3029
+ `directory` instance in such a deployment has no work tree, and one whose
3030
+ `work/` is the top level of a repository of its own is observed as before.
3031
+ A `work/` that is a link is read as what it leads to, wherever that is: a
3032
+ `workspace` instance's leads to the deployment directory, which is above its
3033
+ home, and is observed as before. A [stop plan](#stop)'s and a
3034
+ [retire plan](#retire)'s `work` read the same way, with the code as `reason`.
3035
+
2603
3036
  ```json
2604
3037
  {"instanceGitApi":1,"instance":"dev-1","agent":"dev","home":"/w/agents/dev/instances/dev-1","workMode":"worktree",
2605
3038
  "observation":{"revision":"46c20668…","indexRevision":"3147fef2…","at":"2026-09-26T18:15:26.487Z","worktree":"/w/agents/dev/instances/dev-1/work",
@@ -2684,7 +3117,8 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2684
3117
  bytes}`. Only a regular file is opened (no symlinks, same device and inode
2685
3118
  after open), and at most its last 4 MiB is read (`"tail"`).
2686
3119
  - **Kinds:** `spawned`, `launched`, `restarted`, `stopped`, `stop-refused`,
2687
- `retire-planned`, `retired`, `worktree-retained`, `worktree-removed`,
3120
+ `retire-planned`, `retired`, `retire-refused` (0.53.0,
3121
+ [below](#retire-refused-event)), `worktree-retained`, `worktree-removed`,
2688
3122
  `branch-deleted` (not written since 0.41.0: no retire deletes a branch;
2689
3123
  older logs hold it), `child-spawn-refused`, `launch-warning` (0.30: a
2690
3124
  `launch` hook's warning at session start/restart, `data: {message}`),
@@ -2714,6 +3148,34 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2714
3148
  `--delete-branch` (since 0.41.0: `this self-retire was requested with
2715
3149
  --delete-branch by an older OATS; retirement no longer deletes branches, so
2716
3150
  the branch and the worktree were left`).
3151
+ - <a id="retire-refused-event"></a>`retire-refused` (0.53.0; `data: {code,
3152
+ homeChanged, reason}`) is written once by the completion of a scheduled
3153
+ self-retire (`oats retire <instance> --self`) that did not complete, and
3154
+ by nothing else. A retire that a person runs answers that person and
3155
+ writes none. No feature names the kind: a client that does not know it
3156
+ reads the row as it reads any unknown kind.
3157
+ - `code` is a kernel code, or `null`. It is the code the retire answered.
3158
+ It is `null` for the one outcome that is a result and not an error: a
3159
+ cleanup that did not finish, with the home retained in quarantine.
3160
+ `null` means that outcome, never "unknown".
3161
+ - `homeChanged` is `false` when no retire hook was started and nothing of
3162
+ the home was removed, and `true` otherwise. It is always `true` for the
3163
+ incomplete cleanup. A session or a child that was stopped on the way
3164
+ does not count.
3165
+ - `reason` is the sentence the retire answered, on one line and at most
3166
+ 2048 UTF-16 code units. A longer sentence is cut and ends with `…`,
3167
+ which is counted in the 2048. The bound is the Desktop events reader's,
3168
+ which refuses a whole read that holds a longer detail. For the
3169
+ incomplete cleanup it is a sentence of the kernel's own that names no
3170
+ item; the items are in the completion's result file.
3171
+ - The row is in the workspace's log only, and carries the incarnation
3172
+ the home had before the retire ran. The completion holds no claim when
3173
+ it writes, so it writes nothing into a home.
3174
+ - With `homeChanged: false` the self-retire's pending marker is gone as
3175
+ well, and with `true` it stays
3176
+ ([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
3177
+ - `stop-refused` and `retire-refused` each cover two cases: a verb that was
3178
+ refused, and one that failed after it began.
2717
3179
  - `worktree-retained` (`data: {movedTo, branch, recordedBranch}`) and
2718
3180
  `worktree-removed` (`data: {branch}`) are written to the workspace log only,
2719
3181
  by the retire's worktree step. Since 0.42.1 the retire also writes one per
@@ -2896,7 +3358,57 @@ reality moved it refuses `E_PLAN_STALE` with the fresh `details.plan`. An
2896
3358
  idempotency key (`^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`) makes a retried apply
2897
3359
  return the first receipt. Recorded parentage (`parentInstance`) is the only
2898
3360
  relation followed; a child whose parent name matches several homes is listed
2899
- under `ambiguous` and never acted on.
3361
+ under `ambiguous` and never acted on. Parentage is read from each home's
3362
+ `instance.json`: a home whose record cannot be read is never stopped as
3363
+ anyone's child. It is in no plan's `targets`, `children` or `ambiguous`, and
3364
+ no stop or retire of its parent names it, so its session may go on running
3365
+ under a parent that was stopped or retired. `oats status` is where it shows
3366
+ ([its row](#unreadable-record-row)).
3367
+
3368
+ <a id="unreadable-record"></a>
3369
+ **A home whose `instance.json` is there and cannot be read** as a JSON object
3370
+ (cut off, empty, kept from the user, a directory, a link to nothing, JSON
3371
+ that is not an object; OATS 0.52.0) decides only for itself.
3372
+
3373
+ - Every command about another instance answers as if that home were not
3374
+ there: its stop and retire plans and applies, `oats session`, `oats
3375
+ instance events`, a spawn, the roster.
3376
+ - Every lifecycle command about that home is refused with
3377
+ `E_UNIDENTIFIED_INSTANCE_HOME` before it takes a claim, reads the home or
3378
+ touches anything: `oats retire` (plain, `--plan`, guarded, `--self`), `oats
3379
+ instance stop --plan` and `--apply`, `oats session start` and `restart`.
3380
+ The answer has no `details`, and the message is `<home>/instance.json
3381
+ cannot be read (<reason>); nothing was done. Restoring the file from a copy
3382
+ makes the home usable again; removing such a home through OATS is not
3383
+ possible yet.`
3384
+ - `oats retire --force` is refused the same way. `--force` removes a home
3385
+ that has no `instance.json`; a home whose record is there and cannot be
3386
+ read may be a whole instance with work, and is never removed blind.
3387
+ - The lineage is read from records. A parent whose record cannot be read has
3388
+ no recorded children for a stop or a retire: they are listed, and each is
3389
+ stopped and retired on its own. A home whose record cannot be read is never
3390
+ stopped as anyone's child: it is not a target of its parent's stop or
3391
+ retire, no plan and no answer of either names it, and a retire does not
3392
+ repair its lineage. Its session may go on running under a parent that was
3393
+ retired; `oats status` is where it shows.
3394
+ - A spawn that names such a home as its parent or anchor is refused
3395
+ (`E_SPAWN_FAILED`, the same sentence with `nothing was spawned`): the
3396
+ parent's child-spawn policy and the lineage are in that record.
3397
+ - `oats session inspect`, `input` and `attach` on that home answer
3398
+ `E_RUNTIME_ENDPOINT_UNKNOWN`, and `oats instance events` still reads its
3399
+ logs.
3400
+
3401
+ `E_UNIDENTIFIED_INSTANCE_HOME` for a record that cannot be read is answered
3402
+ only before any effect: nothing was signalled, run, copied or removed. A
3403
+ record that becomes unreadable after a retire has taken the home's claim is
3404
+ refused with the same sentence, before the retire's first signal (the end of
3405
+ the hook group an interrupted spawn left); in a guarded apply, with
3406
+ [its plan's `retire-planned` event](#guarded-apply-plan-event) already
3407
+ appended to the workspace log. That answer alone carries
3408
+ [`details.reached`](#retire-reached), untouched: `{phase: "before-effects",
3409
+ sessionStopAttempted: false, hooksStarted: false, home: "kept", recovery:
3410
+ null}`. A plan refuses the same way when the record became unreadable after
3411
+ the home was resolved.
2900
3412
 
2901
3413
  ### Stop
2902
3414
 
@@ -2922,10 +3434,34 @@ oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>]
2922
3434
  `not-launched` are idle; `unknown` is a running process tmux cannot name
2923
3435
  (the normal state of a harness). Not established: `{state:
2924
3436
  "unestablished", present: null, backend: null, established: false,
2925
- reason}`; render it as unknown, never idle.
3437
+ reason}`; render it as unknown, never idle. `reason` is the kernel code of
3438
+ what failed (`E_SESSION_UNAVAILABLE` for an error that has none).
2926
3439
  - `work` is the Git observation summarized (`changed` counts changed,
2927
- renamed, copied and unmerged rows), or `{observed: false, reason}`.
3440
+ renamed, copied and unmerged rows), or `{observed: false, reason}`:
3441
+ `"no-worktree"` when nothing is at `work/`, or the kernel code of what
3442
+ failed (`E_NO_WORKTREE` for a `work/` that is no work tree of the
3443
+ instance's, as [`oats instance git`](#git-and-diff) answers it;
3444
+ `E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
3445
+ a home the kernel cannot look into, where whether it has a `work/` cannot
3446
+ be told; OATS 0.52.0).
2928
3447
  - `midTask`: `true`, `false` or `"unknown"`.
3448
+ - `retiring` and `stopPending`, booleans on every target, say who holds the
3449
+ target's home when the plan is read (OATS 0.52.0, feature
3450
+ `lifecycle-claim-stop`). `retiring`: a self-retire is scheduled for it
3451
+ (its pending marker is there), or a retire holds its
3452
+ [claim](#retire-one-at-a-time). From 0.53.0 the marker outlasts a
3453
+ completion that did not complete only when a retire hook was started or
3454
+ the removal of the home began
3455
+ ([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
3456
+ `stopPending`: a stop apply holds its
3457
+ claim. A holder counts while it is not known to be gone: alive, or of a
3458
+ liveness that cannot be read. `retiring` is one of the facts
3459
+ `planRevision` is hashed from, as it was; `stopPending` is not. The
3460
+ plan's `notes` say in a line that an apply will refuse either: a note is
3461
+ a sentence for a person, and no client keys on its text (`retiring` and
3462
+ `stopPending` are the data). Before
3463
+ 0.52.0 `retiring` read the pending marker alone and `stopPending` read a
3464
+ file inside the home ([below](#stop-claim)).
2929
3465
 
2930
3466
  ```text
2931
3467
  oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key> [--no-recursive] [--grace-ms <n>] [--home <abs>] --json
@@ -2936,6 +3472,179 @@ Children first: SIGTERM to the harness processes and a bounded wait
2936
3472
  transcript and launch configuration are kept; `oats session restart` brings
2937
3473
  the instance back.
2938
3474
 
3475
+ <a id="stop-claim"></a>
3476
+ **A stop holds the claim of every target** (OATS 0.52.0, feature
3477
+ `lifecycle-claim-stop`; #866, #890). It is the file that orders the retires
3478
+ of a home ([One retire of a home at a time](#retire-one-at-a-time)):
3479
+ `<instances>/.oats-retirement/claims/<instance>.lock`, beside the homes, its
3480
+ record naming the holder by pid and start time and by its verb (`action:
3481
+ "stop"`). With `--server` it is taken on the host. An apply does this, in
3482
+ this order:
3483
+
3484
+ 1. It refuses bad arguments (`E_BAD_ARGS`), `--grace-ms` among them.
3485
+ 2. It reads the plan, for its targets.
3486
+ 3. It replays a receipt stored under the same key (below). No claim is
3487
+ taken for that.
3488
+ 4. It takes the claim of every target, in one fixed order (by the claim's
3489
+ path), so that two overlapping stops never each hold half: one takes the
3490
+ first file both want, and the other is refused at once and releases what
3491
+ it took. **A holder is answered here, before a stale plan**, as a guarded
3492
+ retire answers it: `E_INSTANCE_RETIRING` beside a retire,
3493
+ `E_LIFECYCLE_BUSY` beside another stop
3494
+ ([Commands that meet on one home](#lifecycle-pairs)). A stop never waits
3495
+ for a holder. A claim that cannot be written is
3496
+ [read in its place](#stop-claim-write) (OATS 0.53.0): whoever holds it
3497
+ is answered the same way, here.
3498
+ 5. It reads the plan again, under the claims: this is the plan it acts on.
3499
+ **It holds the claim of every target of this plan before it does
3500
+ anything.** A target it does not hold yet (a child recorded, or readable
3501
+ again, since step 2) sends it back to step 4 with this plan's targets,
3502
+ every claim released first so that the order of step 4 holds. A target
3503
+ whose claim was only read counts as held for this, and its claim is
3504
+ read once more now, before the comparison below: a holder that came
3505
+ since is answered as in step 4. A stop
3506
+ whose targets are others under each of three such reads (a constant of
3507
+ the kernel: there is no setting for it) gives up:
3508
+ `E_LIFECYCLE_BUSY`, `holder: "none"`, `… nothing was stopped — run the
3509
+ command again`. It then compares the plan's revision with the one sent,
3510
+ once: `E_PLAN_STALE` with the fresh `details.plan` (the claims this
3511
+ apply holds are not reported in it as `stopPending`). A home that was
3512
+ retired since the plan was shown answers `E_SESSION_UNKNOWN`; one whose
3513
+ `instance.json` can no longer be read, `E_UNIDENTIFIED_INSTANCE_HOME`; a
3514
+ child in that state is no longer a target, which is a changed plan.
3515
+ 6. It refuses a target for which a self-retire is scheduled
3516
+ (`E_INSTANCE_RETIRING`, with `details.plan`).
3517
+ 7. It stops each target, writes the receipt and releases the claims.
3518
+
3519
+ Everything through step 6 is before any effect: nothing was signalled, and
3520
+ nothing was written into a home. From step 7 on a target's failure is a row
3521
+ of the receipt, and no answer of the apply carries a code of
3522
+ [the list](#before-effect-codes). A target that was never launched, or is
3523
+ idle, is claimed and released like any other; its row says `alreadyIdle`.
3524
+
3525
+ A stop that is killed (SIGKILL, SIGTERM, SIGINT or SIGHUP) leaves its claim
3526
+ files, and they refuse nothing: the next stop or retire of that home takes
3527
+ over the claim of a holder that is gone. Before 0.52.0 a stop marked each
3528
+ target with `<home>/.oats-stop-pending.json`, a file that named no holder,
3529
+ so a killed stop left every later stop of that instance refused
3530
+ (`E_LIFECYCLE_BUSY`) until someone removed the file (#890).
3531
+ **`.oats-stop-pending.json` stays a reserved name.** This kernel neither
3532
+ writes nor reads it. One that an older kernel left refuses nothing, does not
3533
+ make `stopPending` true, and is removed by the next stop apply of that home
3534
+ once it holds the claim; a removal that fails is a warning on stderr (`oats:
3535
+ warning: …`, in both modes) and the stop goes on.
3536
+
3537
+ <a id="stop-claim-write"></a>
3538
+ **A stop whose claim cannot be written reads it instead** (OATS 0.53.0;
3539
+ #946). Stop is what a person reaches for when a disk is full, and a stop
3540
+ that leaves a session running because it could not write a file protects
3541
+ nobody. So `oats instance stop --apply`, and it alone, reads a claim it
3542
+ cannot write, for a reason that stops every other writer of this user as
3543
+ well, and goes on when nobody holds it. It holds nothing for that target,
3544
+ and says so on stderr. A retire, and a retire's stop of a recorded child,
3545
+ need their claim as before.
3546
+
3547
+ The reasons are five codes of the system's, met at one of the claim's
3548
+ writes (its directory, its file, and the same two of a takeover's own
3549
+ claim):
3550
+
3551
+ | The system's code | It means |
3552
+ |---|---|
3553
+ | `ENOSPC` | the file system is full |
3554
+ | `EDQUOT` | this user's quota is spent |
3555
+ | `EROFS` | the file system is read-only |
3556
+ | `EACCES`, `EPERM` | the claims directory is not writable by this user |
3557
+
3558
+ Each is in the list for one reason: what stops this stop from writing a
3559
+ claim in that directory stops a retire or another stop of the same user as
3560
+ well, so a claim that reads as held by nobody is held by nobody. `EACCES`
3561
+ and `EPERM` are there because every instance of a deployment can change the
3562
+ claims directory, and one that takes write permission from it must not take
3563
+ Stop from the operator. On a shared deployment that is the likely case of a
3564
+ warning below, and its cure is to fix the directory's permissions, not to
3565
+ live with the warning. Any other code (`EIO`, `EMFILE`, `EEXIST` from a
3566
+ file where the directory belongs) says nothing about who else could write
3567
+ there, and is refused as in 0.52.0: `E_LIFECYCLE_FAILED`, `the claim <lock>
3568
+ could not be taken (<the system's error>); nothing was done`, with the
3569
+ system's code in [`details.cause`](#kernel-codes) and the plan it read in
3570
+ `details.plan`; nothing was signalled.
3571
+
3572
+ **What the read answers** is what the taking would have answered for what
3573
+ is at the claim's path, with one difference:
3574
+
3575
+ - **Nobody holds it** (no file there; or a holder that is verifiably gone,
3576
+ whose claim a command that can write would take over): the stop goes on.
3577
+ This is the difference: the dead holder's file is left as it is, for the
3578
+ next command that can write to take over.
3579
+ - **A holder that is alive, or whose liveness cannot be read, and a file
3580
+ that is no readable claim:** the cell of
3581
+ [the pair table](#lifecycle-pairs) for an arriving stop, with the same
3582
+ sentence and the same `details`. Nothing was signalled.
3583
+ - **A file of a gone holder that no kernel can take over** (no `nonce` of a
3584
+ claim's shape): `E_LIFECYCLE_BUSY`, `holder: "none"`, as for a stop that
3585
+ can write. Its message says to inspect the file and remove it. On a full
3586
+ disk that removal works; in a directory that is not writable the person
3587
+ has to make it writable first.
3588
+ - **The claim cannot be read either** (its path cannot be reached): the
3589
+ `E_LIFECYCLE_FAILED` of the write, as above. The read is positive or it
3590
+ is nothing.
3591
+
3592
+ The read is made twice: where the claim would have been taken (step 4), and
3593
+ again once the plan has been read under the claims (step 5), before the
3594
+ revision is compared. A holder that came in between is answered there,
3595
+ before a stale plan and before any signal, with the fresh plan in
3596
+ `details.plan`.
3597
+
3598
+ **What it gives up.** Nothing on the home shows this stop: a plan read
3599
+ meanwhile says `stopPending: false`, and a retire or a stop that starts
3600
+ while it runs, and that can write its claim, is not refused. That is space
3601
+ freed a moment later, or a process of another user, for whom the directory
3602
+ is writable. The two commands then work in one home at once, as every stop
3603
+ did before 0.52.0. The warning says it, one line per such target, on stderr
3604
+ in text and in JSON mode:
3605
+
3606
+ ```text
3607
+ oats: warning: <instance>: stopping without its claim: <lock> could not be written (<CODE>), and nobody holds it. A retire or a stop of <instance> that starts while this one runs will not see it.
3608
+ ```
3609
+
3610
+ `<lock>` is the claim's own path and `<CODE>` the system's code, never its
3611
+ message. It is printed only when the apply answers a receipt, also for a
3612
+ target whose row is `alreadyIdle`, and never for a replay, which takes no
3613
+ claim. It is not part of the receipt, whose fields and values are those of
3614
+ any stop. **With `--server` the warning does not reach the caller:** the
3615
+ router keeps a remote command's stderr only when the command fails, as for
3616
+ every warning of a stop (#952).
3617
+
3618
+ **On a full disk the stop cannot write into the home either.** The session
3619
+ is stopped, and the apply answers its receipt (exit 0 in JSON mode) with
3620
+ that target's row `ok: false`, `E_SESSION_STOP_FAILED`, a `message` that
3621
+ ends `its harness was signalled (SIGTERM) and has exited`, and
3622
+ [`stillRunning: []`](#still-running): the row of a stop in a home that
3623
+ cannot be written, as it was. Read `stillRunning`, not `ok`: `[]` says
3624
+ stopped. Text mode prints that row, closes with `the stop did not complete
3625
+ its record; nothing is still running`, and exits 1, as for any target that
3626
+ failed. The receipt cannot be stored either, so **its key cannot be
3627
+ replayed**: the same apply again runs, and is answered `E_PLAN_STALE` with
3628
+ the fresh plan, in which the session is stopped; an apply with that plan's
3629
+ revision answers `alreadyIdle`, and prints the warning again. Such a stop
3630
+ leaves nothing of its own in the home: the private file each of the two
3631
+ writes goes through (`.oats-stop.json.tmp-<pid>`,
3632
+ `.oats-stop-receipt.<key>.json.<pid>.tmp`) is removed when its write or its
3633
+ rename fails. Before 0.53.0 each apply on a full disk left both there,
3634
+ empty.
3635
+
3636
+ In 0.52.0 a stop whose claim could not be written for one of those five
3637
+ codes was refused like the others, before anything was signalled
3638
+ (`E_LIFECYCLE_FAILED`). Before 0.52.0 a stop took no claim: it wrote its
3639
+ marker if it could and signalled the harness either way.
3640
+
3641
+ Two kernel versions acting on one deployment at once are not covered: a
3642
+ kernel before 0.52.0 takes no claim for a stop and does not read a stop's
3643
+ claim. A machine has one installed CLI, and a command routed with `--server`
3644
+ runs with the host's own, so the only overlap is a command of the old
3645
+ version still running across an upgrade: upgrade with no lifecycle command
3646
+ in flight.
3647
+
2939
3648
  - The receipt is `{lifecycleApi: 1, action: "stop", instance, home,
2940
3649
  idempotencyKey, planRevision, at, ok, results, retained: ["home", "work",
2941
3650
  "transcript", "launch"], replayed: false}`. A result is `{instance, home,
@@ -2944,13 +3653,301 @@ the instance back.
2944
3653
  whether the instance runs cannot be established, among them a recorded
2945
3654
  tmux socket file that is missing while a process works in the home
2946
3655
  ([#624](execution-targets.md#missing-socket)): never `alreadyIdle`.
2947
- - `ok: false`: at least one target still runs (text mode exits 1).
3656
+ - `code` is always a [kernel code](#kernel-codes). A stop that fails for a
3657
+ reason of the system's (the home removed under it, a write refused) is
3658
+ `E_SESSION_STOP_FAILED`, as one whose harness still runs after the wait is.
3659
+ Its `message` then holds the system's text and ends with what is true of
3660
+ the harness: `its harness was signalled (SIGTERM) and has exited`, `… and
3661
+ is still running`, `no signal reached its harness, which had already
3662
+ exited` (the stop found it idle, or its processes gone, when it came to
3663
+ signal), `… which was not seen to exit`, `whether its harness was signalled
3664
+ is not known`, or `its harness was not signalled`. <a id="still-running"></a>`stillRunning`
3665
+ is what the stop established of the processes it signalled, one of three
3666
+ values: the pids still alive; `[]` only when the harness exited (its
3667
+ processes are gone and the session read as idle); `null` when it
3668
+ established nothing, which is a stop that has no answer of its signalling
3669
+ step, and one whose signalled processes are all gone while the session
3670
+ still does not read as idle (its message says `is still running after <n>
3671
+ ms; nothing was escalated`): something runs there that the stop cannot
3672
+ name. Only `[]` says stopped. The three values hold from feature
3673
+ `lifecycle-kernel-codes`. A kernel without it answers `[]` in a failed row
3674
+ for that last case only (all signalled processes gone, the session not
3675
+ idle), so there `[]` establishes nothing, and it answers `null` for a
3676
+ harness that exited before something else failed. A stop that
3677
+ fails on a [defect of the kernel](#kernel-codes) is that same row, and the
3678
+ defect's stack is printed on stderr; a stop that fails on a refusal without
3679
+ a code (a `tmux` command that failed) is that row and prints no stack. The
3680
+ same holds for a child's stop in a retire's `childrenStopped`.
3681
+ - `ok: false`: at least one target's row is not `ok` (text mode exits 1).
3682
+ Whether something still runs is each such row's `stillRunning`, and the
3683
+ sentence text mode closes with follows it: `some targets are still
3684
+ running; nothing was escalated` when one of those rows names a process or
3685
+ establishes nothing (`null`, or no `stillRunning` in the row), and `the
3686
+ stop did not complete its record; nothing is still running` when every
3687
+ one of them says `[]` (from 0.53.0; before, the first sentence closed
3688
+ every such answer).
2948
3689
  - A replay is the stored receipt (`<home>/.oats-stop-receipt.<key>.json`)
2949
- with `replayed: true`.
3690
+ with `replayed: true`, and it follows the same rules as a first answer. The
3691
+ file a kernel with feature `lifecycle-kernel-codes` stores says so in a
3692
+ field of its own, `lifecycleKernelCodes: true`, which is part of the file
3693
+ and never of an answer: a replay leaves it out, so a replayed receipt has
3694
+ the fields of the first one. A file without that field was stored by a
3695
+ kernel from before the feature, and its failed rows are answered under the
3696
+ feature's rules: a system's code in `code` becomes `E_SESSION_STOP_FAILED`
3697
+ (the `message` keeps the system's text), and `stillRunning: []` becomes
3698
+ `null`, which is what that kernel's `[]` established. The stored file is
3699
+ never rewritten. A replay takes no claim. The same key sent again while the
3700
+ first apply still holds its claims is refused on the claim
3701
+ (`E_LIFECYCLE_BUSY`): the receipt is not written yet. Once the first apply
3702
+ has ended, the key replays.
2950
3703
  - Refusals: `E_BAD_ARGS` (no `--plan-revision`, a bad key, not exactly one of
2951
- `--plan`/`--apply`), `E_PLAN_STALE`, `E_INSTANCE_RETIRING` and
2952
- `E_LIFECYCLE_BUSY` (each with `details.plan`), `E_SESSION_UNKNOWN`,
2953
- `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_LIFECYCLE_FAILED`.
3704
+ `--plan`/`--apply`, a `--grace-ms` that is not 1–300000: answered before
3705
+ the plan is read and before the key is used. Before 0.52.0 a bad grace was
3706
+ one `E_BAD_ARGS` row per target, in a receipt stored under the key),
3707
+ `E_INSTANCE_RETIRING` and `E_LIFECYCLE_BUSY` (a target's claim is held:
3708
+ the holder's [`details`](#lifecycle-pairs), with `details.plan`, the plan
3709
+ read before the claims), `E_PLAN_STALE` (`details.plan`, the fresh one),
3710
+ `E_INSTANCE_RETIRING` for a scheduled self-retire (`details.plan`),
3711
+ `E_SESSION_UNKNOWN`,
3712
+ `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME`
3713
+ (the home's `instance.json` [cannot be read](#unreadable-record); `--plan`
3714
+ and `--apply`, nothing was done), `E_LIFECYCLE_FAILED` (any error
3715
+ that is not the kernel's; with [`details.cause`](#kernel-codes) when it has
3716
+ a code of its own or is a defect, and without it when it is a refusal
3717
+ without a code; among them a claim that cannot be taken for a reason of
3718
+ the system's other than [the five a stop reads it for](#stop-claim-write):
3719
+ `the claim <path> could not be taken (…); nothing was done`).
3720
+ A stop never answers `E_WORK_INSPECTION_FAILED`.
3721
+
3722
+ <a id="lifecycle-pairs"></a>
3723
+ ### Commands that meet on one home
3724
+
3725
+ Feature `lifecycle-claim-stop`, OATS 0.52.0 (#866). A retire and a stop apply
3726
+ hold the home's claim for their whole run, and `oats worktree add` reads it.
3727
+ Each cell is the answer of the command that **arrives**. It is given at once
3728
+ and before any effect: that command stopped, ran, copied, made and removed
3729
+ nothing, and the command already on the home is not disturbed.
3730
+
3731
+ | On the home ↓ / arrives → | `oats retire` | `oats instance stop --apply` | `oats instance stop --apply` that cannot write its claim | `oats worktree add` |
3732
+ |---|---|---|---|---|
3733
+ | a retire is running | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
3734
+ | a self-retire is scheduled | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
3735
+ | a stop apply is running | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
3736
+ | a retire whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
3737
+ | a stop whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
3738
+ | the claim file is no readable claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
3739
+ | the holder of the claim is gone | not refused | not refused | not refused | not refused |
3740
+
3741
+ - **A holder is answered before a stale plan, by both verbs.** A guarded
3742
+ retire and a stop apply compare the revision they were sent only once
3743
+ they hold the claim, so beside a holder the answer is the cell above
3744
+ whatever the plan would read by then.
3745
+ - **A scheduled self-retire holds no claim** until its completion runs: it
3746
+ is its pending marker. The row lasts as long as the marker does: until
3747
+ the completion has retired the home, or, from 0.53.0, until a completion
3748
+ that did not complete has removed it, which it does unless it started a
3749
+ retire hook or began the removal of the home
3750
+ ([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
3751
+ A retire reads the marker under the claim, while
3752
+ the completion lives (`E_LIFECYCLE_BUSY`, [below](#retire-one-at-a-time)).
3753
+ A stop apply reads it in the plan it makes under its claims: a plan that
3754
+ showed `retiring: true` is answered `E_INSTANCE_RETIRING`, and an apply
3755
+ whose plan was shown before the retire was scheduled is answered
3756
+ `E_PLAN_STALE` first, with the fresh plan.
3757
+ - **A claim file that is no readable claim** is one that does not parse as
3758
+ a claim, a directory, or a path that is there and cannot be read, such as
3759
+ a dangling symbolic link. All three commands read it the same way, and
3760
+ none removes it.
3761
+ - **A holder that is gone** (it exited or was killed, a zombie too) refuses
3762
+ nothing: a retire or a stop takes its claim over and runs, and a `worktree
3763
+ add` takes nothing and runs. One file of a gone holder still refuses the
3764
+ two verbs that must take the claim: one this kernel
3765
+ [cannot take over](#retire-one-at-a-time) (a `nonce` that is not a
3766
+ claim's, written or damaged by hand) answers `E_LIFECYCLE_BUSY`, `holder:
3767
+ "none"`, to a retire and to a stop; a `worktree add` reads the same file
3768
+ as a holder that is gone, and runs. So does a file that parses and names
3769
+ no pid (`{}`, `[]`, a verb alone): a claim
3770
+ [always carries its pid](#retire-one-at-a-time), so no kernel wrote that
3771
+ file as one. And one race refuses them: a claim that was
3772
+ [taken again](#retire-one-at-a-time) by a command that then died, each of
3773
+ the five times the retire or the stop found it without a live holder, is
3774
+ `E_LIFECYCLE_BUSY`, `holder: "none"`, with `run the command again`.
3775
+ - **A stop does not refuse a `worktree add`:** a tree does not depend on the
3776
+ session.
3777
+ - **A stop apply that cannot write its claim**
3778
+ ([it reads it instead](#stop-claim-write), OATS 0.53.0) is answered as
3779
+ the stop that can, cell for cell. Beside a holder that is gone it stops
3780
+ like the other, and leaves that holder's file as it is: it takes nothing
3781
+ over. As a command already on the home it has no row: it holds nothing,
3782
+ so nothing on the home shows it, and no command that arrives is refused
3783
+ by it.
3784
+ - `--plan` of either verb takes no claim and is never refused by one; a
3785
+ stop plan reports the holder (`retiring`, `stopPending`). `oats worktree
3786
+ remove` does not read the home's claim. `oats session start` and `restart`
3787
+ do not read it yet: they are refused only beside a scheduled self-retire
3788
+ (`E_INSTANCE_RETIRING`). `oats status` does not show a held claim.
3789
+
3790
+ Several targets:
3791
+
3792
+ 1. **A stop of a parent whose recorded child is being retired** answers
3793
+ `E_INSTANCE_RETIRING` before the first target is stopped, never after:
3794
+ the claim of every target is taken first, and the claims already taken
3795
+ are released.
3796
+ 2. **Two overlapping stops of one parent:** one stops everything, and the
3797
+ other is refused whole with `E_LIFECYCLE_BUSY`.
3798
+ 3. **A retire whose recorded child is held by someone else.** A retire does
3799
+ not hold its children's claims. It stops each child, and that stop takes
3800
+ the child's claim for its own span. A child whose claim is held is a row
3801
+ of `childrenStopped` with `ok: false`, `stillRunning: null` and the code
3802
+ of the cell above for an arriving stop (`E_LIFECYCLE_BUSY` beside a stop,
3803
+ `E_INSTANCE_RETIRING` beside a retire), and the retire answers
3804
+ **`E_CHILDREN_RUNNING`**, whether or not it had already stopped another
3805
+ child ([`reached.sessionStopAttempted`](#retire-reached) says whether a
3806
+ signal was sent). A stop of a child beside its parent's retire is not
3807
+ refused.
3808
+
3809
+ **`error.details` of a claim's refusal** is `{instance, home, lock, pid,
3810
+ since, action}`, with `holder` on `E_LIFECYCLE_BUSY`:
3811
+
3812
+ - `instance` and `home`: the home whose claim refused. **In a recursive
3813
+ stop this may be a child of the instance asked for.**
3814
+ - `lock`: the file that names the holder. `pid` and `since`: the holder's
3815
+ pid and when it took the claim.
3816
+ - **`action`: the holder's verb**, `"retire"` or `"stop"`. A claim written
3817
+ by a kernel before this feature has no verb and reads as `"retire"`. A
3818
+ reader treats a value it does not know as busy.
3819
+ - <a id="claim-file-text"></a>**Text of a claim file is never part of an
3820
+ answer.** A claim is read back as whatever is in its file, and the claims
3821
+ of a deployment's homes are in a directory that every instance of it can
3822
+ write. A field of the claim that does not have the shape the kernel
3823
+ writes is answered as `null` (`pid`: a positive integer; `since`: an
3824
+ instant as `2026-01-01T00:00:00.000Z`) and printed as `?` (the recorded
3825
+ start: `none`), and an `action` that is not a verb of the list is
3826
+ answered as `"retire"`. The same holds for a purpose's claim
3827
+ ([`oats worktree`](#oats-worktree)), whose refusal then names no `pid`,
3828
+ and for the recorded start of a process group (`details.gitStart`).
3829
+ - A refusal that names no holder has no `pid`, no `since` and no `action`:
3830
+ a claim file that is no readable claim, and a command that cannot read
3831
+ its own start time.
3832
+ - **A scheduled self-retire is no claim.** A retire's refusal beside one
3833
+ has the same keys, with `lock` the pending marker and `pid` the
3834
+ completion's. A stop apply's has `details.plan` alone, and a `worktree
3835
+ add`'s has no `details`; their message is `<instance> is being retired;
3836
+ nothing was stopped` (`no tree was made`), with no pid.
3837
+ - A stop apply's refusal carries `details.plan` beside them: the plan it
3838
+ read before it took the claims.
3839
+ - A holder whose liveness cannot be read: `details.unknown` is the reason,
3840
+ and the message names the recorded verb, the pid, its recorded start and
3841
+ the way out (check that pid by hand; if it is not that command, remove
3842
+ `<lock>`, then retry).
3843
+
3844
+ The messages: `<instance> is being retired (pid <pid>, since <at>); nothing
3845
+ was stopped — if it does not end, check that pid by hand, and if it is not
3846
+ an oats retire, remove <lock>, then retry` (a `worktree add`: `no tree was
3847
+ made`); `a stop of <instance> is already running (pid <pid>, since <at>);
3848
+ nothing was done — wait for it to finish; if it does not end, check that
3849
+ pid by hand, and if it is not an oats instance stop, remove <lock>, then
3850
+ retry` (an arriving stop: `nothing was stopped`). The step for a holder
3851
+ that does not end is [the check of a live process](#busy-holder-running).
3852
+ A client shows the message and never parses it.
3853
+
3854
+ <a id="busy-holder"></a>
3855
+ **`error.details.holder`, on every `E_LIFECYCLE_BUSY`** of `oats retire`,
3856
+ `oats instance stop` and `oats worktree add|remove`, for a claim or for
3857
+ anything else the code is answered for (a tree record, a spawn's marker, a
3858
+ scheduled completion, an owed rollback). It says, as data, whether waiting
3859
+ ends the refusal:
3860
+
3861
+ | `details.holder` | It means | What ends it |
3862
+ |---|---|---|
3863
+ | `"running"` | the kernel established that a process with the recorded pid and start time is alive: the one that the claim, the record or the marker names as an `oats` command (a retire, a stop, a worktree command, a spawn, a scheduled completion). It did not establish that the process is that command | waiting, when it is that command; a claim's refusal also names the check for when it does not end |
3864
+ | `"unknown"` | whether one still runs cannot be read | a person checks what the message names (the process, the file) |
3865
+ | `"none"` | nobody is running: something that a dead command left, or that this host lacks, has to be dealt with | what the message says (a file to inspect and remove, a group to end, a command to run) |
3866
+
3867
+ A reader treats a value it does not know, or the field's absence (a kernel
3868
+ without the feature), as **do not promise that waiting ends it**. For
3869
+ `"unknown"` and `"none"` the message always names the step that ends it,
3870
+ after ` — `.
3871
+
3872
+ <a id="busy-holder-running"></a>
3873
+ **`"running"` is a live process, not a verified command.** A file that
3874
+ names any live process by its pid and start time reads as `running`,
3875
+ whoever wrote it, and waiting for that process ends nothing. So a claim's
3876
+ refusal for a holder that runs names, after the wait, the check that the
3877
+ `unknown` refusal names, in the same words: `… — wait for it to finish; if
3878
+ it does not end, check that pid by hand, and if it is not an oats retire,
3879
+ remove <lock>, then retry` (`an oats instance stop`, `an oats worktree
3880
+ command`). `E_INSTANCE_RETIRING` from a claim names the check alone: the
3881
+ instance is on its way out, so waiting makes neither the stop nor the tree
3882
+ possible. What a client does with each value of `holder` does not change. The field has a meaning only under `E_LIFECYCLE_BUSY`: under
3883
+ any other code a reader ignores it (an `E_LIFECYCLE_FAILED` made after a
3884
+ takeover ended a dead holder's step carries the details of the refusal it
3885
+ then met, `holder` among them).
3886
+
3887
+ <a id="before-effect-codes"></a>
3888
+ **The codes a stop and a retire answer only before any effect.** The kernel
3889
+ holds one list, by verb. A code in it means *refused, nothing happened*: no
3890
+ process was signalled, no hook ran, and nothing of a home was written, copied
3891
+ or removed. For a retire that is `reached.phase: "before-effects"`, or no
3892
+ [`reached`](#retire-reached) at all; for a stop apply, that no target's stop
3893
+ had begun.
3894
+
3895
+ | Code | `oats instance stop` | `oats retire` |
3896
+ |---|---|---|
3897
+ | `E_BAD_ARGS` | yes | yes |
3898
+ | `E_PLAN_STALE` | yes | yes |
3899
+ | `E_INSTANCE_RETIRING` | yes | yes |
3900
+ | `E_LIFECYCLE_BUSY` | yes | yes |
3901
+ | `E_HOME_MISMATCH` | yes | yes |
3902
+ | `E_SESSION_UNKNOWN` | yes | yes |
3903
+ | `E_AMBIGUOUS_INSTANCE` | yes | yes |
3904
+ | `E_UNIDENTIFIED_INSTANCE_HOME` | yes | yes |
3905
+ | `E_REMOTE_INCOMPATIBLE` | yes | yes |
3906
+ | `E_AMBIGUOUS` | yes | yes |
3907
+ | `E_SNAPSHOT_UNKNOWN` | yes | yes |
3908
+
3909
+ The last three are the router's (`--server`): they are answered before the
3910
+ command is sent to the host. The list is about the envelope's `error.code`.
3911
+ A row of a result (a stop receipt's `results[].code`, a retire's
3912
+ `childrenStopped[].code`) says why that one target was not stopped, and
3913
+ other rows may say that theirs was. Every other code may come after an
3914
+ effect: `E_CHILDREN_RUNNING`, `E_SESSION_STOP_FAILED`,
3915
+ `E_RUNTIME_QUIESCE_FAILED`, `E_WORK_PRESERVATION_FAILED`,
3916
+ `E_WORK_INSPECTION_FAILED`, `E_LIFECYCLE_FAILED` and the rest; for a retire
3917
+ `reached` says how far it got.
3918
+
3919
+ <a id="guarded-apply-plan-event"></a>
3920
+ **One thing has already happened when a guarded retire apply answers one of
3921
+ these codes: its plan's append.** A guarded apply reads its plan once it
3922
+ holds the home's claim, and a plan that is answered appends its
3923
+ `retire-planned` event to the workspace log, as [a plan](#retire) always
3924
+ does. Every listed code that the apply answers from there on comes with that
3925
+ event already appended, in the workspace log only: `E_PLAN_STALE` always,
3926
+ since the comparison follows the plan; `E_LIFECYCLE_BUSY` or
3927
+ `E_UNIDENTIFIED_INSTANCE_HOME` when the retire's own first reads then refuse
3928
+ (the instance is still being spawned; its record became unreadable after the
3929
+ plan). Nothing of the home is touched and no signal is sent. A stop's plan
3930
+ appends nothing, and a plain or `--self` retire reads no plan.
3931
+
3932
+ The rule holds by construction. Each verb knows how far it got at one place
3933
+ (a retire: the `phase` it reports in `reached`; a stop apply: whether a
3934
+ target's stop had begun), and an error that would leave that place with a
3935
+ listed code after the first effect is not answered with it. It is a
3936
+ [defect of the kernel](#kernel-codes): `E_LIFECYCLE_FAILED`,
3937
+ `details.cause: {name: "LateRefusal"}`, its other details kept, and its
3938
+ stack on stderr.
3939
+
3940
+ Two answers of a retire that came after an effect had a listed code before
3941
+ 0.52.0 and have another now (#895):
3942
+
3943
+ - A guarded retire whose extra trees no longer read as its plan said, found
3944
+ at the step that moves them, after the hooks: `E_WORK_PRESERVATION_FAILED`
3945
+ (it was `E_PLAN_STALE`). The home and its work are kept.
3946
+ - The worktree hook process group that an interrupted spawn left, when it
3947
+ survives SIGTERM and SIGKILL: `E_RUNTIME_QUIESCE_FAILED`, naming the group
3948
+ (it was `E_LIFECYCLE_BUSY`, "nothing was retired", after two signals).
3949
+ `reached.phase` is `"before-hooks"`; no session was stopped, no retire
3950
+ hook was run and nothing was removed.
2954
3951
 
2955
3952
  <a id="retire"></a>
2956
3953
  ### Retire
@@ -2964,7 +3961,7 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2964
3961
  "facts":{"session":{"state":"shell","present":true,"backend":"tmux","established":true},
2965
3962
  "work":{"observed":true,"revision":"46c20668…","branch":"feat/x","detached":false,"drift":true,"changed":0,"untracked":1,
2966
3963
  "upstream":{"ref":null,"ahead":null,"behind":null},"base":{"ref":null,"ahead":null,"behind":null},"remote":null},
2967
- "workMode":"worktree","repo":"/w/one","recordedBranch":"agents/dev-1",
3964
+ "workMode":"worktree","ownWorktree":true,"repo":"/w/one","recordedBranch":"agents/dev-1",
2968
3965
  "children":[{"instance":"dev-1-child","agent":"dev","home":"/w/agents/dev/instances/dev-1-child","session":{"state":"shell","present":true,"backend":"tmux","established":true}}],
2969
3966
  "ambiguous":[],"pullRequest":"unknown",
2970
3967
  "extraWorktrees":[{"path":"/w/agents/dev/instances/dev-1/.work-docs","repo":"/w/docs","branch":"agents/dev-1-docs","detachedAt":null,
@@ -2973,9 +3970,201 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2973
3970
  "planRevision":"4e5f6a7b8c9d0e1f2a3b4c5d","notes":["the worktree is on feat/x, not the recorded agents/dev-1; …"]}
2974
3971
  ```
2975
3972
 
3973
+ - `facts.session` and `facts.work` read as a [stop plan](#stop)'s
3974
+ `session` and `work`. Work that was not observed is `{observed: false,
3975
+ reason}`: `"no-worktree"`, or the kernel code of what failed
3976
+ (`E_NO_WORKTREE` for a `work/` that is no work tree of the instance's;
3977
+ `E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
3978
+ a home the kernel cannot look into, where whether it has a `work/` cannot be
3979
+ told; OATS 0.52.0). `facts.work` never reads a checkout that encloses the
3980
+ home as the instance's work (0.53.0, #962).
2976
3981
  - The plan changes nothing except appending a `retire-planned` event to the
2977
3982
  workspace log. `pullRequest` is always `"unknown"`. Branch actions use the
2978
3983
  worktree's branch, never `recordedBranch`.
3984
+ - `facts.ownWorktree` (0.53.0, #988, feature `retire-plan-own-worktree`) is
3985
+ a fact: a boolean, `true` exactly when `work/` is the instance's own work
3986
+ tree, the one this retire retains (moved, as described below) or removes
3987
+ (`--discard-worktree`), and `false` for every other home. It is always
3988
+ present and never `null`. It is the answer of the one reading of `work/`
3989
+ that the retire acts on (below), so it is `true` in `worktree` mode with
3990
+ the instance's tree at `work/` (and, by the record, with nothing at
3991
+ `work/`: the retire then finds its tree absent), and for a record with no
3992
+ work mode whose `work/` Git confirms is a registered linked worktree
3993
+ (#962). It is `false` for a directory instance; for an attached, a
3994
+ checkout or a workspace instance, whatever the tree its link leads to is
3995
+ on; for a real directory that is not the instance's own tree (#962) and
3996
+ for a link (#973), under a record that says `worktree` too. It is the
3997
+ reading's answer and not a promise that the retire completes: it is
3998
+ `true` for a file (or any entry that is neither a link nor a directory)
3999
+ at `work/` under a record that says `worktree`, and `false` for one under
4000
+ any other record; and it is `true` for a work directory whose Git admin
4001
+ entry is missing when the spawn's receipt says that a tree was given,
4002
+ whatever the record says but `directory`. No retire removes such an
4003
+ entry: it is kept with the home until a person moves it (#1019). Neither
4004
+ `facts.workMode` (the record's value, which the instance can write) nor
4005
+ `facts.work` (an observation, through any link) says whose tree it is:
4006
+ read this key for that. Gate on the probe: from a kernel that lists the
4007
+ feature the key is present and a boolean; from one that does not it is
4008
+ absent, and its absence says nothing. A stop plan does not carry it. A
4009
+ relayed plan (`--server`) carries it as its host answered it, so it is
4010
+ the host's features that say whether it is there.
4011
+ - `defaults.retainWorktree` is the default of one option of this retire:
4012
+ whether the instance's own work tree is retained or removed
4013
+ (`--discard-worktree`). It follows the fact today: it is `true` when
4014
+ `facts.ownWorktree` is. A default is what the retire would do if nobody
4015
+ chose and a fact is what is there, so a client does not read this key to
4016
+ learn what `work/` is. Where it is `false` the instance has no work tree
4017
+ of its own; it is never `false` because a tree would be removed: there
4018
+ the retire touches no tree it does not own. `work/` of an attached, a
4019
+ checkout or a workspace instance is a link (to its owner's tree, to the
4020
+ shared checkout, to the deployment directory) that goes with the home,
4021
+ and what it links to is not touched. Where a real directory is found at
4022
+ `work/` of such an instance and no link, it is a directory of the home:
4023
+ the retire copies it to recovery when it is not empty and removes it
4024
+ with the home, and the plan says so (0.53.0, #962: the next item).
4025
+ `work/` of a directory instance is the home's own directory: it is
4026
+ copied to recovery when it is not empty, then removed with the home. The
4027
+ plan's text (`oats retire <instance>
4028
+ --plan` without `--json`) prints `retain worktree true` in its `defaults:`
4029
+ line for the instance's own tree only; for the other homes the line says
4030
+ the above (0.53.0, #959). When the reading of `work/` establishes
4031
+ neither an own tree nor a directory of the home, the line says `work mode
4032
+ not recorded` for a record with no work mode, and `work mode not known to
4033
+ this kernel` for one whose work mode the kernel does not know: the value
4034
+ is never printed, and `facts.workMode` holds it. (An own tree under such
4035
+ a record prints `retain worktree true`, and a directory of the home its
4036
+ own sentence.) The text does not print the fact.
4037
+ - What `work/` is comes from one reading, which the plan and the retire
4038
+ share (0.53.0, #962). It is **the instance's own tree** when the spawn's
4039
+ receipt says the instance was given one; for a home without a valid
4040
+ receipt, when the record says `worktree`, or holds no work mode (or one
4041
+ the kernel does not know) and Git confirms that `work/` is a registered
4042
+ linked worktree whose top level it is (the test of an
4043
+ [extra tree](souls-and-instances.md#extra-trees-at-retire)). A real
4044
+ directory at `work/` that is not that is **a directory of the home**: one
4045
+ found where the work mode has a link (an attached, a checkout or a
4046
+ workspace instance, or a record with no work mode), or under a valid
4047
+ receipt that says no tree was given, whatever the record says now. **A
4048
+ link** at `work/` is never the instance's own tree, whatever the record
4049
+ says (0.53.0, #973, below). For a directory of the home the plan has:
4050
+ - `defaults.retainWorktree: false`, and in the text's `defaults:` line `no
4051
+ work tree of its own (work/ is a real directory of the home: copied to
4052
+ recovery when not empty and then removed with the home)`.
4053
+ - the note `work/ is a real directory of the home and not a work tree of
4054
+ the instance's own: the retire copies it to recovery when it is not
4055
+ empty (a .git in it included), checks the copy, and removes it with the
4056
+ home`, and `recovery: work/ is copied there when it is not empty`. The
4057
+ notes that say a worktree is retained, and the drift note, are not said.
4058
+ - when Git confirms that the directory is a registered worktree, the note
4059
+ `work/ is registered as a worktree of <repository>: the retire leaves its
4060
+ entry there until a prune (git -C '<repository>' worktree prune), and does
4061
+ not touch its branch or its commits`.
4062
+ - `facts.work` by the path alone: observed when `work/` is the top level of
4063
+ a repository of its own, else `{observed: false, reason:
4064
+ "E_NO_WORKTREE"}`.
4065
+
4066
+ For an own tree whose record names no repository, the plan has the note
4067
+ `the record names no repository for the work tree: the retire uses the
4068
+ one Git names for it, <repository>, and does not write it into the
4069
+ record`. No key of the plan is new.
4070
+
4071
+ What `work/` is decides what the retire does with it, so it is part of
4072
+ `planRevision` wherever it is not what the work mode alone says: when an
4073
+ own tree became a directory of the home, or the other way round, between
4074
+ the plan and the apply (a record's work mode that changed, a receipt that
4075
+ is gone), or the repository read from Git changed, a guarded apply refuses
4076
+ with `E_PLAN_STALE` before anything runs. Every other home has the
4077
+ revision it had.
4078
+ - A link at `work/` is never the instance's own tree: the retire removes
4079
+ the link with the home and does not touch what it leads to, whatever the
4080
+ record says (0.53.0, #973). The record is a file the instance can write;
4081
+ what the link leads to is not the instance's. So a home whose record says
4082
+ `worktree` and whose `work/` is a symbolic link plans and retires as a
4083
+ home that was given a link. Before 0.53.0 its plan said
4084
+ `defaults.retainWorktree: true` and its retire was refused with
4085
+ `E_WORK_PRESERVATION_FAILED`. Its plan has:
4086
+ - `defaults.retainWorktree: false`, and in the text's `defaults:` line `no
4087
+ work tree of its own (work/ is a link, though the record says worktree:
4088
+ what it leads to is not touched)`. `facts.workMode` is the record's
4089
+ value, as always.
4090
+ - the note `the record says work mode worktree, but work/ is a link and
4091
+ not a work tree of the instance's own: the retire removes the link with
4092
+ the home and does not touch what it leads to, with --discard-worktree as
4093
+ well`. The note names no target. It names the flag because a plan takes
4094
+ no option: `--plan --discard-worktree` answers this same plan, and no
4095
+ worktree step runs for the link with the flag either.
4096
+ - `facts.work` as for every home whose `work/` is a link: an observation
4097
+ of what the link leads to, which says nothing of whose tree it is.
4098
+ - a `planRevision` that binds it, by the rule above: a plan read while
4099
+ `work/` was a link is stale once `work/` is the instance's own tree, and
4100
+ the other way round.
4101
+
4102
+ Its retire completes with the receipt of a home that was given a link
4103
+ (`retention: null`, `worktreeRemoved: false`, no copy of the work in
4104
+ `workRecovery`; with `--discard-worktree` too, since no worktree step
4105
+ runs), with and without `--discard-worktree` and `--force`, and one string
4106
+ in `warnings`: `<home>/work was a link though the record says
4107
+ work mode worktree: nothing was retained or removed as a work tree, and
4108
+ what it led to (<path>) was not touched`. `<path>` is what the system
4109
+ resolves the link to just before the home is removed, never the text
4110
+ stored in the link; nothing acts on it. When the link does not resolve,
4111
+ the string ends `and it led nowhere that could be read`. The receipt holds
4112
+ the path as the system gave it. The retire's text (without `--json`)
4113
+ prints every warning of the receipt on one line and spells each character
4114
+ a terminal would act on, or that hides or reorders text (a control
4115
+ character such as an escape or a newline, a bidi override: the set the
4116
+ kernel never prints in text it did not write), as `\u{<hex>}`, so that a
4117
+ name cannot clear the screen or write a line of its own. The JSON is not
4118
+ changed by that: its strings are what they were. No key of the plan or of
4119
+ the receipt is new.
4120
+ - A link at `work/` that is no longer a link when the retire inspects the
4121
+ home again (a retire hook, or anything else, put a directory or a file in
4122
+ its place) refuses with `E_WORK_INSPECTION_FAILED` and keeps the home, in
4123
+ every work mode (0.53.0, #973): the home's removal would take what is
4124
+ there now, uncopied. The message says what was there and what is there
4125
+ now, that the home is kept and nothing of it was removed, and how it
4126
+ ends, by what is there now:
4127
+ - a directory: that `oats retire <instance> --plan` shows what a retire
4128
+ would do with what is there now, and that running the retire again does
4129
+ that;
4130
+ - a file, or an entry that is neither a link, a directory nor a file:
4131
+ that no retire removes it, and the step (`move it out of the home or
4132
+ remove it, then run the retire again`). It does not point to the plan,
4133
+ which does not say that such an entry stays (#1019);
4134
+ - an entry that cannot be read: that the retire reads it again when it is
4135
+ run again.
4136
+
4137
+ Running the retire again reads the home as it is then, by the reading
4138
+ above: the record as it is then and the spawn's receipt decide, not what
4139
+ the home was given alone.
4140
+ - A directory that the reading answers is a directory of the home (#962:
4141
+ the spawn's receipt says that no tree was given, as an attached, a
4142
+ checkout or a workspace instance's does, and the record says
4143
+ `attached`, `checkout`, `workspace`, `worktree` or holds no work mode):
4144
+ the retire copies it to recovery, checks the copy and removes it with
4145
+ the home.
4146
+ - A directory under a record that says `worktree` whose spawn's receipt
4147
+ says that a tree was given, and a file (or an entry that is none of the
4148
+ three) under a record that says `worktree` whatever the receipt says
4149
+ (an attached instance whose record was changed to `worktree` included):
4150
+ a work directory with no Git admin entry. The retire runs its hooks and keeps the entry and the home as an
4151
+ incomplete item (exit 1; with `--force` it refuses with
4152
+ `E_WORK_PRESERVATION_FAILED` before anything runs) until a person moves
4153
+ the entry out or deletes it; then it completes.
4154
+ - A file, or an entry that is none of the three, under a record that
4155
+ says `attached`, `checkout` or `workspace`: the inspection refuses
4156
+ (`E_WORK_INSPECTION_FAILED`, `--force` included, nothing stopped, run
4157
+ or removed) until a person removes the entry; then it completes.
4158
+ - A record that says `directory` by then is held against the spawn's
4159
+ receipt as always: the retire refuses (`E_WORK_INSPECTION_FAILED`,
4160
+ nothing stopped, run or removed) while the two disagree.
4161
+ - The two notes about a worktree that is retained, `N changed and M
4162
+ untracked file(s) would be retained with the worktree` and `the worktree
4163
+ is on <branch>, not the recorded <branch>`, are given for the instance's
4164
+ own tree alone (0.53.0, #973). `facts.work` of an attached, a checkout or
4165
+ a workspace instance observes the tree its link leads to, and before
4166
+ 0.53.0 its plan gave both notes for that tree, which the retire neither
4167
+ keeps nor moves. `facts.work` is unchanged.
2979
4168
  - A home spawned before 0.25.9 has no session receipt (0.30). Its
2980
4169
  `facts.session` is `{state: "absent", present: false, backend, established:
2981
4170
  true, note}` when the session is observably gone: instance.json records no
@@ -3149,9 +4338,9 @@ A first retire prints the **raw receipt**, not an envelope:
3149
4338
  not removed. The home and the worktree are kept, and so is any recovery the
3150
4339
  retire wrote; retry the retire.`), and a HEAD that cannot be read with
3151
4340
  `E_WORK_INSPECTION_FAILED`. Either may follow earlier effects of the same
3152
- retire (hooks run, a recovery copied), and neither says that one happened:
3153
- an error here is not proof that nothing happened, nor that a recovery
3154
- exists.
4341
+ retire (hooks run, a recovery copied): an error here is not proof that
4342
+ nothing happened, nor that a recovery exists. Read
4343
+ [`error.details.reached`](#retire-reached), which says both.
3155
4344
  - `extraWorktrees` (0.42.1): the extra trees the retire handled, present only
3156
4345
  when it handled at least one. Each row is the plan's row (`{path, repo,
3157
4346
  branch, detachedAt, disposition, movedTo, reason}`) plus `outcome`:
@@ -3165,7 +4354,9 @@ A first retire prints the **raw receipt**, not an envelope:
3165
4354
  stops it at the step, after the hooks. `--force` does not bypass either;
3166
4355
  the home and `work/` are kept, and trees already handled stay handled. A tree
3167
4356
  that no longer matches what the applied plan said refuses with
3168
- `E_PLAN_STALE`, the home kept, rather than be moved or removed unplanned.
4357
+ `E_WORK_PRESERVATION_FAILED`, the home kept, rather than be moved or
4358
+ removed unplanned (OATS 0.52.0; it was `E_PLAN_STALE`, a code that says
4359
+ nothing happened, answered after the hooks: #895).
3169
4360
  The key is additive.
3170
4361
  - `workRecovery`: `{path, classes, bytes, home, outputs?, repoCopy?,
3171
4362
  notCopied?, afterHooks?}`, present when a recovery was written. One retire
@@ -3241,15 +4432,24 @@ A first retire prints the **raw receipt**, not an envelope:
3241
4432
  **Recorded children**, on every apply (plain, guarded and `--self`), as the
3242
4433
  plan says: each child the plan lists is stopped first (bounded SIGTERM,
3243
4434
  never escalated) and kept, once the retire has resolved the home and before
3244
- the instance's own session is stopped. `childrenStopped[]` lists them,
4435
+ the instance's own session is stopped. A home whose `instance.json`
4436
+ [cannot be read](#unreadable-record) is never stopped as anyone's child: the
4437
+ plan does not list it, `childrenStopped[]` does not name it, and its session
4438
+ may go on running after its parent is retired; `oats status` is where it
4439
+ shows. `childrenStopped[]` lists the children stopped,
3245
4440
  deepest first, as `{instance, home, ok: true, stopped, alreadyIdle}` or
3246
- `{instance, home, ok: false, code, message, stillRunning}`. A plain or
4441
+ `{instance, home, ok: false, code, message, stillRunning}`, where
4442
+ `stillRunning` has the three values of [a stop's result](#still-running): the
4443
+ pids still alive, `[]` only when the child's harness exited, `null` when
4444
+ nothing is established. A plain or
3247
4445
  `--self` receipt carries it only when there are children; a guarded receipt
3248
4446
  always does (`[]` when there are none). One child still running after the
3249
4447
  grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
3250
- `E_INSTANCE_RETIRING`, …), refuses everything: nothing is retired, exit 1,
4448
+ `E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY`, …), refuses everything: nothing is retired, exit 1,
3251
4449
  `E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
3252
- `code`). **`--force` does not bypass it**: `--force` covers incomplete
4450
+ `code`, always a [kernel code](#kernel-codes); the message says `still running after a bounded stop`
4451
+ only of a child whose row lists processes in `stillRunning`, and `<child> could not be stopped
4452
+ (<code>)` of any other, OATS 0.52.0). **`--force` does not bypass it**: `--force` covers incomplete
3253
4453
  cleanup, not a running child. A `--self` retirement stops the children
3254
4454
  recorded when it was scheduled that are still instances (a child retired in
3255
4455
  between is skipped), in its detached completion before it stops the caller;
@@ -3269,20 +4469,31 @@ retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
3269
4469
  the plan would read by then: a retire in flight has usually changed it (it
3270
4470
  stops the session of a launched instance before its hooks run). Before the
3271
4471
  claim an apply only replays a used key and resolves the home
3272
- (`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`).
4472
+ (`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`,
4473
+ `E_UNIDENTIFIED_INSTANCE_HOME` for a home whose `instance.json`
4474
+ [cannot be read](#unreadable-record)).
3273
4475
  - The children stopped are those of the revalidated plan, and a refusal
3274
4476
  carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
3275
4477
  - A first guarded retire prints the raw receipt with `planRevision`,
3276
4478
  `idempotencyKey` and `replayed: false`.
3277
4479
 
3278
- **One retire of a home at a time** (0.51.0, #863). Every retire that applies (plain,
4480
+ <a id="retire-one-at-a-time"></a>
4481
+ **One retire of a home at a time** (0.51.0, #863), **and one retire or stop**
4482
+ (0.52.0, #866: a stop apply holds the same claim,
4483
+ [above](#stop-claim)). Every retire that applies (plain,
3279
4484
  guarded, `--self` and its detached completion; with `--server`, on the host)
3280
4485
  holds the home's claim,
3281
4486
  `<instances>/.oats-retirement/claims/<instance>.lock`, from the moment it
3282
4487
  has resolved the home until it ends, by success or by any refusal or failure.
3283
- The claim is a file that names its holder by pid and start time. It lies
4488
+ The claim is a file that names its holder by pid and start time, and by its
4489
+ verb (`action`: `"retire"` or `"stop"`; 0.52.0). It is written whole to a
4490
+ private file and linked into place, so a kernel's claim is never seen
4491
+ without its `pid`: a file there that parses and names no pid was not
4492
+ written by a kernel as a claim, and a kernel that wrote one without it would
4493
+ be changing the lock format, which is a contract decision. It lies
3284
4494
  beside the homes, never inside one: a home's bytes are what its retire
3285
- observes, copies and removes. A second retire of that home does not wait: it
4495
+ observes, copies and removes. A second retire of that home, or a retire that
4496
+ meets a stop of it, does not wait: it
3286
4497
  answers `E_LIFECYCLE_BUSY` at once (exit 1; the text form prints the
3287
4498
  message), before it stops a session or a child, writes a recovery, runs a
3288
4499
  hook or changes a file of the home. **`--force` does not bypass it**, and
@@ -3291,7 +4502,10 @@ before `E_PLAN_STALE`: under the claim the answers come in this order: the
3291
4502
  home is gone (`E_SESSION_UNKNOWN`), a self-retire is scheduled
3292
4503
  (`E_LIFECYCLE_BUSY`), the plan is stale (`E_PLAN_STALE`), then the retire. A claim whose holder has
3293
4504
  died, for example a retire killed while its hooks ran, is taken over by the
3294
- next retire of that name. So a killed retire can always be run again. The
4505
+ next retire of that name. So a killed retire can always be run again. A
4506
+ holder that has exited or was killed and that its parent has not reaped (a
4507
+ zombie) has died: its claim is taken over without waiting for that reap
4508
+ (0.52.0, #870; before, the retire was refused as running until the reap). The
3295
4509
  claim does not end what the killed retire left running: one of its retire
3296
4510
  hooks may still be running when the next retire takes the claim over and
3297
4511
  runs the hooks again (#865). Until
@@ -3299,23 +4513,68 @@ that name is retired again its claim file stays where it is, and it is safe
3299
4513
  to remove once its pid is gone. A retire that ends removes its claim file;
3300
4514
  the `claims/` directory itself stays, empty.
3301
4515
 
3302
- `details` is `{instance, home, lock, pid, since}`: `lock` is the file that
3303
- names the holder, `since` when the holder took it. Every message is one
4516
+ `details` is `{instance, home, lock, pid, since, action, holder}`: `lock` is
4517
+ the file that names the holder, `since` when the holder took it, `action`
4518
+ the holder's verb and [`holder`](#busy-holder) whether waiting ends it (both
4519
+ 0.52.0, feature `lifecycle-claim-stop`;
4520
+ [Commands that meet on one home](#lifecycle-pairs)). Every message is one
3304
4521
  line and says that nothing was done:
3305
4522
 
3306
- - A live holder: `a retire of <name> is already running (pid <pid>, since
3307
- <at>); nothing was done — wait for it to finish`.
4523
+ - A live holder (`holder: "running"`): `a retire of <name> is already
4524
+ running (pid <pid>, since <at>); nothing was done — wait for it to
4525
+ finish; if it does not end, check that pid by hand, and if it is not an
4526
+ oats retire, remove <lock>, then retry`; beside a stop, `a stop of <name>
4527
+ is already running …`, with `action: "stop"` and `an oats instance
4528
+ stop`. Live is what was established
4529
+ [of the process](#busy-holder-running), not that it is that command.
3308
4530
  - A holder whose start time cannot be read (where `ps` fails, or a claim
3309
4531
  that records none) is never taken for gone, and its claim is never taken
3310
- over. `details.unknown` is the reason. The message names the pid, its
3311
- recorded start, the reason and the way out: check that pid by hand, and if
3312
- it is not an `oats retire`, remove `<lock>`, then retry.
3313
- - A claim file that is not a readable claim is never removed. `details` is
3314
- `{instance, home, lock}`; the message names the file and says to inspect
3315
- it and remove it if no `oats retire` holds it.
4532
+ over (`holder: "unknown"`). `details.unknown` is the reason. The message
4533
+ names the holder's verb, the pid, its recorded start, the reason and the
4534
+ way out: check that pid by hand, and if it is not that command (`oats
4535
+ retire`, `oats instance stop`), remove `<lock>`, then retry.
4536
+ - A claim file that is not a readable claim is never removed: a file that
4537
+ does not parse, a directory, or a path that exists and cannot be read, such
4538
+ as a dangling symbolic link (0.52.0, #874: that one made the retire spin
4539
+ without end; it is now refused once its retries are spent, a quarter of a
4540
+ second for a retire, which does not wait).
4541
+ `details` is `{instance, home, lock, holder: "unknown"}`; the message is
4542
+ `<lock> is not a readable claim; nothing was done — inspect it and remove
4543
+ it if no oats retire or oats instance stop holds it, then retry`.
4544
+ - A claim whose holder is gone and that this kernel cannot take over is
4545
+ never removed either: its `nonce` is not the 32 hexadecimal digits a claim
4546
+ carries (a file written or damaged by hand); or it is the claim of a
4547
+ takeover that died (`<lock>.reclaim-<nonce>`), at the end of a chain of
4548
+ them so long that the system will not name the claim of one more (each
4549
+ adds 41 bytes to the file's name: three to five on a file system whose
4550
+ names are 255 bytes at most). `details` is `{instance, home, lock, pid,
4551
+ since, action, holder: "none"}`, `lock` being the file the message names.
4552
+ The message is `the
4553
+ process that held <lock> (pid <pid>) is gone, and this file is not a claim
4554
+ this kernel can take over (<why>); nothing was done — inspect <lock> and
4555
+ remove it if no oats retire or oats instance stop holds it, then retry` (0.52.0, #874; before,
4556
+ the first was answered as a live holder, to wait for, and the second as
4557
+ `E_LIFECYCLE_FAILED` with the system's `ENAMETOOLONG` about a file that
4558
+ does not exist). Removing that one file lets the next retire take the
4559
+ rest over. A retire of a name that has no home leaves a file whose nonce
4560
+ is not a claim's as it is.
4561
+ - A claim that is taken again and again by commands that die is an ordinary
4562
+ claim, and is not refused with that sentence. A retire takes over the
4563
+ claim of a holder that is gone and tries again, five times. When each time
4564
+ it found the claim taken again, the last time by a process that is gone,
4565
+ `details` is `{instance, home, lock, pid, since, action, holder: "none"}`
4566
+ (the last holder's), and the message is `the claim <lock> was found
4567
+ without a live holder 5 times and was taken again each time, the last time
4568
+ by a process that is gone (pid <pid>); nothing was done — run the command
4569
+ again` (a stop: `nothing was stopped`). Nothing is to be inspected or
4570
+ removed: the next retire or stop takes that claim over.
3316
4571
  - The retire's own start time cannot be read, so it could not hold the claim
3317
- verifiably: `details` is `{instance, home, lock}`, and the message gives
3318
- the reader's own reason (the `/proc` read, or what `ps` answered).
4572
+ verifiably: `details` is `{instance, home, lock, holder: "none"}`, and the
4573
+ message gives the reader's own reason (the `/proc` read, or what `ps`
4574
+ answered) and the check to run by hand in a shell on that host: `cat
4575
+ /proc/$$/stat` where there is a `/proc`; elsewhere `PATH=/usr/bin:/bin ps
4576
+ -o lstart= -o stat= -p $$`, which must print a start time and a state.
4577
+ Then the command again.
3319
4578
 
3320
4579
  A scheduled self-retire counts from the moment it is scheduled. Its pending
3321
4580
  marker (`pendingMarker`) records the completion process as `completionPid`
@@ -3331,12 +4590,44 @@ the file to remove being the pending marker. A second `--self` answers
3331
4590
  the first `--self` is still scheduling, or once the completion holds the
3332
4591
  claim, it is refused the claim and answers `E_LIFECYCLE_BUSY` like any other
3333
4592
  retire, where it answered `alreadyScheduled: true` before 0.51.0. The marker refuses nothing once its completion has
3334
- left its outcome at `resultPath` (it failed) or is gone (it died), nor when
4593
+ left its outcome at `resultPath` (it failed) or is gone (it died; a
4594
+ completion that is a zombie, not reaped by its parent, has died: 0.52.0,
4595
+ #870), nor when
3335
4596
  it names no completion (a marker written before 0.51.0): `oats retire
3336
- <instance>` then retries the retirement, as before. The completion waits up
3337
- to 3 s for the retire that scheduled it to release the claim, then takes it
3338
- as any retire does; one that meets another retire still running is refused,
3339
- and records that at `resultPath` like any failed completion.
4597
+ <instance>` then retries the retirement, as before. The completion does not
4598
+ start its retire while the retire that scheduled it holds the claim: it
4599
+ waits for that one command, which it knows by the pid and the start time it
4600
+ was given, for up to ten minutes (`SCHEDULING_WAIT_MS`; 0.53.0; before, for
4601
+ up to 3 s only). Meanwhile the home has no marker until that retire writes
4602
+ it, last, and that retire answers a stop and another retire as any running
4603
+ retire does ([the table](#lifecycle-pairs)). Then it takes the claim as any retire
4604
+ does, waiting up to 3 s for a live holder, the one that scheduled it
4605
+ included when the ten minutes have passed; one that meets another retire still running is refused,
4606
+ and records that at `resultPath` like any failed completion. The `error`
4607
+ recorded there has the code and the message the same failure has as an
4608
+ envelope: a kernel code, and what the retire had done by then. From 0.53.0
4609
+ a completion that does not complete also writes one
4610
+ [`retire-refused` event](#retire-refused-event), and removes its pending
4611
+ marker unless it started a retire hook or began the removal of the home.
4612
+ It removes only the marker of its own scheduling: the same `requestedAt`,
4613
+ and a `completionPid` that is absent, its own, or of a process that is
4614
+ gone.
4615
+
4616
+ A `--self` that cannot finish scheduling (the completion's log cannot be
4617
+ opened, no process is created, the marker cannot be written, or, from
4618
+ 0.53.0, its completion has already ended when the marker is written, with
4619
+ an outcome or without one: the marker is then removed again) answers
4620
+ `E_SELF_RETIRE_SCHEDULE_FAILED`, with `reached.phase: "before-effects"`. That
4621
+ stays true after the answer: a completion this command had started is not
4622
+ running when it answers (it is ended, unless it had gone by itself; a
4623
+ completion does nothing to the instance before it holds the home's claim,
4624
+ which the retire that scheduled it holds until it has answered), and its
4625
+ log and any result it had recorded are removed. One leftover is possible and
4626
+ is not a debt of the instance: a completion that was kept waiting for the
4627
+ claim until it gave up may write its result (`E_LIFECYCLE_BUSY`) at the
4628
+ moment it is ended, after that removal. The next `oats retire` of the
4629
+ instance removes it. The instance is still live and can be retired
4630
+ externally.
3340
4631
 
3341
4632
  The home is resolved again once the claim is held. One that another retire
3342
4633
  removed in between answers `E_SESSION_UNKNOWN`, as a retire of a retired
@@ -3347,29 +4638,130 @@ being taken …; nothing was done — retry`, `details: {instance, home, lock}`)
3347
4638
  A retire of a name that has no home also removes a claim of that name whose
3348
4639
  holder is gone, left by a retire that was killed after it removed the home.
3349
4640
 
3350
- The claim orders retires only. `oats instance stop`, `oats session start`
3351
- and `oats worktree add` do not take it and are not refused by it, and `oats
3352
- status` does not show a held claim (#866).
4641
+ The claim orders the retires and the stops of a home (0.52.0, #866): `oats
4642
+ instance stop --apply` takes it, and `oats worktree add` reads it
4643
+ ([Commands that meet on one home](#lifecycle-pairs)). `oats session start`
4644
+ and `restart` do not read it yet, and `oats status` does not show a held
4645
+ claim. Before 0.52.0 the claim ordered retires only: a stop was not refused
4646
+ beside a retire in flight, and wrote into the home that the retire was
4647
+ inspecting or removing.
3353
4648
 
3354
- Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
4649
+ Refusals (envelopes): `E_PLAN_STALE` (a guarded apply's revision, checked
4650
+ under the claim: before any effect), `E_CHILDREN_RUNNING`,
3355
4651
  `E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
3356
4652
  `--discard-worktree` when it is `work/` that could not be re-homed: it does
3357
- not apply to an extra tree), `E_WORK_INSPECTION_FAILED` (the home is kept; the
4653
+ not apply to an extra tree; also a guarded retire whose extra trees no
4654
+ longer read as its plan said, after the hooks: review the fresh plan and
4655
+ apply again), `E_RUNTIME_QUIESCE_FAILED` (the session's window could not be
4656
+ shown gone; or the worktree hook process group an interrupted spawn left
4657
+ survived SIGTERM and SIGKILL: end that group by hand, then retire again),
4658
+ `E_WORK_INSPECTION_FAILED` (the home is kept; the
3358
4659
  message names the entry or the state that could not be read, or the directory
3359
4660
  Git reads as the top level of a `work/` whose `core.worktree` names another
3360
4661
  one),
3361
4662
  `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
4663
+ `E_UNIDENTIFIED_INSTANCE_HOME` (a home with no `instance.json` and no cleanup
4664
+ descriptor, or a rollback marker that cannot drive a retry, until `--force`;
4665
+ a home whose `instance.json` [cannot be read](#unreadable-record), `--plan`
4666
+ and `--force` included),
3362
4667
  `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
3363
- home is running or scheduled, `--force` included: one retire of a home at a
3364
- time, above; or, feature
4668
+ home is running or scheduled, or a stop of it is running, `--force`
4669
+ included: one retire or stop of a home at a time, above; or, feature
3365
4670
  `worktree-event`: the home is a spawn still running its `worktree` hooks, a
3366
4671
  row with `spawnInProgress: true`, `--force` included; or one whose start time
3367
4672
  cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
3368
- group whose leader's start cannot be read, until `--force`). A recovery whose Git status disagrees with
4673
+ group whose leader's start cannot be read, until `--force`; every one is
4674
+ answered before any effect and carries [`details.holder`](#busy-holder)). The
4675
+ codes a retire answers only before any effect are
4676
+ [one list](#before-effect-codes). A recovery whose Git status disagrees with
3369
4677
  the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
3370
4678
  source, recovery}], total}}` (the first 10 paths). Usage errors are text on
3371
4679
  stderr, not envelopes.
3372
4680
 
4681
+ <a id="retire-reached"></a>
4682
+ **What a failed retire had done: `error.details.reached`** (feature
4683
+ `lifecycle-kernel-codes`, OATS 0.52.0). Every error a
4684
+ retire apply answers once it has resolved the home and holds its claim, a
4685
+ typed refusal or not, carries it beside its other details. A client shows the
4686
+ message and never parses it; this is the same statement as data. Gate on the
4687
+ probe, never on the field: from a kernel that lists the feature an absent
4688
+ `reached` means the error was answered before the retire of the home began
4689
+ and nothing was done (below); from a kernel without it an absent `reached`
4690
+ says nothing.
4691
+
4692
+ ```json
4693
+ {"phase":"after-hooks","sessionStopAttempted":true,"hooksStarted":true,"home":"kept",
4694
+ "recovery":{"path":"/w/agents/dev/instances/.oats-retirement/recovery/dev-1-Ab12Cd","phase":"before-hooks"}}
4695
+ ```
4696
+
4697
+ - `phase`: how far the retire got. `"before-effects"`: nothing of the
4698
+ instance was touched and no process was signalled (the first inspection
4699
+ is usually here).
4700
+ `"before-hooks"`: from the step that stops its recorded children on,
4701
+ whether or not that step had anything to signal (then the stop of its own
4702
+ session, the second inspection, the copy made before the hooks), until the
4703
+ hook runner is called. It begins earlier in one case: a home whose
4704
+ interrupted spawn left a worktree hook process group that the retire can
4705
+ prove is that spawn's has that group ended before the first inspection, and
4706
+ `phase` is `"before-hooks"` from the moment the retire may have signalled
4707
+ it. So `"before-hooks"` says neither that a process was signalled nor that
4708
+ the children step was reached; `"before-effects"` is never answered after
4709
+ a signal. `"after-hooks"`: from
4710
+ the call of the retire hooks on (the third inspection, the copy's
4711
+ conclusion, the extra trees and the worktree). `"removal"`: from the
4712
+ removal of the home on.
4713
+ - **In the other four fields the untouched value is a guarantee, and the
4714
+ other value means only that the retire reached that step, which may not
4715
+ have completed.**
4716
+ - `sessionStopAttempted`: `false` = this retire sent no signal to the
4717
+ instance's session nor to any child's harness. `true` = it began to.
4718
+ - `hooksStarted`: `false` = no retire hook was started. `true` = the hook
4719
+ runner was called.
4720
+ - `home`: `"kept"` = the removal has not begun. Otherwise what is on disk
4721
+ when the error is answered: `"partial"` (the removal began and the
4722
+ directory is still there: it is no longer guaranteed to be a whole
4723
+ instance home) or `"removed"` (it is not there).
4724
+ - `recovery`: `null` = no copy of this retire whose manifest can be read.
4725
+ Otherwise `{path, phase}`: the absolute path of the copy, and the `phase`
4726
+ its `recovery.json` holds on disk when the error is answered
4727
+ (`"before-hooks"` or `"complete"`). A removal that fails after a complete
4728
+ recovery therefore names where the work is.
4729
+ - Four points where a step was reached and its outcome is not established:
4730
+ the hook process group an interrupted spawn left was signalled and did not
4731
+ end (`E_RUNTIME_QUIESCE_FAILED`; `phase: "before-hooks"`, and
4732
+ `sessionStopAttempted: false`: that group is no session);
4733
+ the kill of the session's window was sent and the check that the window is
4734
+ gone failed (`E_RUNTIME_QUIESCE_FAILED`; `sessionStopAttempted: true`, and
4735
+ the harness may still run); a child's stop that signalled its harness and
4736
+ then failed, or failed while signalling (`sessionStopAttempted: true`); the
4737
+ hook runner throwing part-way (`hooksStarted: true`, and some hooks may not
4738
+ have run).
4739
+ - `phase`, `home` and `recovery.phase` are closed lists. A reader treats a
4740
+ value it does not know as "effects may have happened".
4741
+ - It is absent from the answers given before the retire of the home begins,
4742
+ where nothing was done: a name that resolves to no home, to several or to
4743
+ another one, the claim, a scheduled self-retire, a guarded apply's plan
4744
+ (`E_PLAN_STALE` with `details.plan`). It is not part of a plan.
4745
+
4746
+ **An error that is not the kernel's** (a file the system refuses to read, a
4747
+ directory that cannot be removed) is answered with a
4748
+ [kernel code](#kernel-codes), [`details.cause`](#kernel-codes) (when the
4749
+ error has a code of its own or is a defect; a refusal without a code has
4750
+ none), `reached`, and a message that ends with the sentence the typed refusals at that point carry:
4751
+
4752
+ | Where it fails | Code | The message ends with |
4753
+ |---|---|---|
4754
+ | before the home's retire begins (the resolution, the plan a guarded apply reads) | `E_LIFECYCLE_FAILED`, no `reached` | `Nothing was done: <instance> is not retired.` |
4755
+ | the claim cannot be taken (its directory cannot be made, its file cannot be written) | `E_LIFECYCLE_FAILED`, no `reached` | `the claim <path> could not be taken (…); nothing was done` |
4756
+ | an inspection of the home or the work meets an entry it cannot read, or one that is gone when it is read | `E_WORK_INSPECTION_FAILED` | the sentence of its phase: `Nothing was stopped, run or removed.` (or, once it has signalled the hook group an interrupted spawn left, `The worktree hook process group <pgid> that an interrupted spawn left was ended; no session was stopped, no retire hook was run and nothing was removed.`, with `was signalled and may still run` when it is not seen to have ended); `No retire hook has run and nothing was deleted: <instance> is not retired and its home and work are kept; …`; `The retire hooks have run; the home, its work and the pre-hook recovery (if any) are kept; …` |
4757
+ | anything else before the removal | `E_LIFECYCLE_FAILED` | the sentence of its phase; once the retire has begun to remove or re-home trees, `The retire hooks have run; the home is kept, and so is any recovery the retire wrote; …` and what it has already done with them |
4758
+ | the removal of the home (a directory that is written into while it is removed, or that cannot be emptied) | `E_LIFECYCLE_FAILED`, `reached.home: "partial"` | `<instance>: the directory at <home> could not be removed: … The retire hooks have run; its recovery (complete) is at <path>; its retired event is recorded; what is left at <home> may not be a whole instance home; …` |
4759
+
4760
+ `E_WORK_INSPECTION_FAILED` is answered only by a retire, only before the
4761
+ removal begins, and only with the home kept (`reached.home: "kept"`). A
4762
+ typed refusal keeps its code, its details and its own words; the inspections'
4763
+ and the recovery's refusals end with the sentence of their phase, once.
4764
+
3373
4765
  ## Sessions and launch configurations
3374
4766
 
3375
4767
  ### Input
@@ -3420,7 +4812,14 @@ selection flags. See [the start workflow](desktop-instance-start.md).
3420
4812
 
3421
4813
  - The result is `{instance, agent, home, harness, backend, model,
3422
4814
  launchConfig, yolo, target, startedAt, restartCount, reused, warnings}`,
3423
- plus `nativeRecordId` and `stop` (a restart's stop receipt) when they apply.
4815
+ plus `nativeRecordId` and `stop` (a restart's stop receipt) when they apply,
4816
+ and (0.52.0) `launchPrompts`, the value this start recorded in `instance.json`:
4817
+ `{status: "not-engaged", startId, at}` for a start that did not engage the
4818
+ development-channel confirmation, `{status: "flag-ignored", reason:
4819
+ "channels-unavailable", signatureId, startId, at}` for one where Claude ignored
4820
+ the flag (with its warning in `warnings`), or the observed `{status: "completed",
4821
+ answers, reason, receipt}`. A `blocked` or `incomplete` outcome is
4822
+ `E_SPAWN_INCOMPLETE` instead ([Launch prompt results](#launch-prompt-results)).
3424
4823
  - `warnings` (0.30) is always present: an array of strings, the warnings the
3425
4824
  capabilities' `launch` hooks returned for this start (as spawn's
3426
4825
  `warnings`), `[]` when there are none. Each is also appended to the
@@ -3462,9 +4861,15 @@ selection flags. See [the start workflow](desktop-instance-start.md).
3462
4861
  - A lost response does not mean the launch failed: check status before a
3463
4862
  retry. A remote home's saved route names its execution host.
3464
4863
  - Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
4864
+ `E_UNIDENTIFIED_INSTANCE_HOME` (the home's `instance.json`
4865
+ [cannot be read](#unreadable-record): nothing was started, `start` and
4866
+ `restart`),
3465
4867
  `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*` (among them
3466
4868
  `E_LAUNCH_SHIM`: the home's `oats` link cannot be written, nothing was
3467
- started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`.
4869
+ started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`
4870
+ (any error that is not the kernel's; with
4871
+ [`details.cause`](#kernel-codes) when it has a code of its own or is a
4872
+ defect, and without it when it is a refusal without a code).
3468
4873
 
3469
4874
  ### Upload
3470
4875
 
@@ -3522,7 +4927,23 @@ accept `--server <id>`.
3522
4927
  anything is sent (`default: false` is dropped). Errors: `E_LOCAL_MISSING`,
3523
4928
  `E_BAD_ARGS` (including `--home`/`--soul`), `E_LAUNCH_CONFIG_UNKNOWN`,
3524
4929
  `E_LAUNCH_CONFIG_INVALID`, `E_CONFIG_BROKEN`, `E_HOME_UNKNOWN`,
3525
- `E_REMOTE_INCOMPATIBLE`.
4930
+ `E_REMOTE_INCOMPATIBLE`, `E_LOCAL_BUSY {path, lock}`, `E_LOCAL_CHANGED
4931
+ {path}`.
4932
+ - **The write** (`set`, `remove`) replaces the `launch-configs` block and
4933
+ leaves every other byte of the file as it was. It is made under
4934
+ `<deployment>/.agents/locks/local.lock`, the lock of every kernel command
4935
+ that rewrites `oats-local.yaml` ([`oats teams`](#oats-teams) says what it
4936
+ covers), from the file as it is under that lock: whether the name is
4937
+ declared, `before`, the environment `--keep-env` keeps and the one default
4938
+ per harness are all read there, never from the command's start. The
4939
+ definition (`--file`, or stdin) is read and judged before the lock is
4940
+ taken. A lock still held after 5 s is `E_LOCAL_BUSY`, and a file that kept
4941
+ changing while the edit ran is `E_LOCAL_CHANGED`; nothing was written, and
4942
+ the same command can be run again. When the text it would write is the
4943
+ file's text already, nothing is written; the receipt is the same either
4944
+ way. (The same definition set again is such a case only once this command
4945
+ has written the block: a block written by hand in another form is
4946
+ rewritten in this command's.)
3526
4947
  - **preview** (read-only) answers `{context, selected, selection: {source,
3527
4948
  launchConfig, harness, model, yolo}, harness, model, modelSource, yolo,
3528
4949
  launchConfig, launchConfigSource, launchConfigDefault, executable: {path,
@@ -3637,6 +5058,12 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
3637
5058
  - `session` is `{instance, home, incarnation, server, delivery: "launched"
3638
5059
  | "delivered-active" | "none"}`: recorded provenance, not a transcript
3639
5060
  reader.
5061
+ - `warnings?` (feature `schedule-run-warnings`): the launch answer's
5062
+ warnings, strings, present only when it had some (a spawn job's spawn, a
5063
+ wake that started its session). For example, that the OATS tmux server
5064
+ was started inside the tick's systemd service
5065
+ ([execution targets](execution-targets.md#a-server-started-from-inside-a-systemd-service)).
5066
+ A later run of the same record never keeps an earlier run's.
3640
5067
  - `nextDue` is "when it next runs" in every row (`null` when another host
3641
5068
  runs it); a schedule row also keeps `nextRun`.
3642
5069
  - **Integrity.** `oats-schedules.json` and `.agents/schedules/state.json` are
@@ -3652,8 +5079,10 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
3652
5079
  - `add <id> (--file <spec.json> | --spec-json <json>)`, `update`, `enable`,
3653
5080
  `disable` → `{schedule}`. `run [--force]`, `remove [--force]`, `reconcile
3654
5081
  [--clear]` → the action's receipt. `tick [--dry-run] [--host]` →
3655
- `{tickedAt, considered, scheduler}`; `host install | uninstall | status` →
3656
- `{scheduler}`.
5082
+ `{tickedAt, considered, scheduler}`; `host install` → `{scheduler, warnings}`;
5083
+ `host uninstall | status` → `{scheduler}`; `host install --print [--os
5084
+ darwin|linux]` → `{kind, files: {<path>: <content>}, warnings}`, writing
5085
+ nothing.
3657
5086
  - `test <id>` → `{test: {id, qualifiedId, kind, placement: {runsHere, reason,
3658
5087
  reasonDetail?, enabledHere, runsOn, owner, host}, soul: {name, origin,
3659
5088
  resolves, error} | null, nextDue, spawned: false, problems, ok}}`. The soul
@@ -3695,7 +5124,9 @@ capability declares ([schedules.md](schedules.md#capability-sources)).
3695
5124
  distinct labels passed as `--provider <messaging cap> join=<labels>`; a
3696
5125
  soul without messaging refuses `E_TRIGGER_TEAMS {soul, teams}`.
3697
5126
  - `template?`: `{package, version, commit, template}`.
3698
- - `lastRun`: `{at, instance, home, event, number, subject, key}`
5127
+ - `lastRun`: `{at, instance, home, event, number, subject, key, warnings?}`
5128
+ (`warnings?`, feature `schedule-run-warnings`: the fire's spawn answer's
5129
+ warnings, present only when it had some)
3699
5130
  (`subject`, 0.49.0: the event's subject, a PR's number as a string;
3700
5131
  for a run recorded before 0.49.0, its number; a capability source's
3701
5132
  run has `number: null`); `nextDue`: the next poll here, `null` before
@@ -3862,8 +5293,10 @@ Details: [schedules.md](schedules.md#workspace-triggers-and-schedules).
3862
5293
  null}}` (this machine's `host.name` and its `gh` logins, compared with a
3863
5294
  row's `owner`), `snapshot: {takenAt, problems (a count)} | null` (the last
3864
5295
  `oats sync` snapshot), and `scheduler: {installed, active, registered,
3865
- lastTick, maxConcurrent, triggersMaxConcurrent, …}` (nothing runs unless installed, active and
3866
- registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
5296
+ problems, lastTick, maxConcurrent, triggersMaxConcurrent, …}` (nothing runs unless installed, active and
5297
+ registered; `problems` is always an array of `{code, message, fix}` warnings
5298
+ about the installed unit, see [schedules](schedules.md#the-host-timers-unit), and never
5299
+ changes `installed` or `active`). `maxConcurrent` is the effective scheduled-job cap (default 5);
3867
5300
  `triggersMaxConcurrent` is the separate trigger cap, or `null` for no host cap.
3868
5301
 
3869
5302
  **Every row** carries:
@@ -3905,8 +5338,13 @@ registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
3905
5338
 
3906
5339
  **Workspace items:**
3907
5340
  - `enable`/`disable` edit `oats-local.yaml` `triggers.disabled` or
3908
- `schedules.disabled`. `update` and `remove` refuse `E_AUTOMATION_WORKSPACE
3909
- {id, origin}`. `schedule run`/`reconcile` elsewhere refuse
5341
+ `schedules.disabled`: that list and no other entry, under
5342
+ `<deployment>/.agents/locks/local.lock` and from the file as it is under
5343
+ it, as [`oats teams`](#oats-teams) writes that file. A lock still held
5344
+ after 5 s is `E_LOCAL_BUSY {path, lock}`, and a file that kept changing
5345
+ while the edit ran is `E_LOCAL_CHANGED {path}`; nothing was written, and
5346
+ the same command can be run again. `update` and `remove` refuse
5347
+ `E_AUTOMATION_WORKSPACE {id, origin}`. `schedule run`/`reconcile` elsewhere refuse
3910
5348
  `E_AUTOMATION_NOT_HERE {id, reason, runsOn, owner}`.
3911
5349
  - `oats trigger|schedule add … --workspace <member> --runs-on <host> --owner
3912
5350
  <host>/<login> --json` writes the file in the member clone and answers
@@ -3972,6 +5410,7 @@ It uses the existing success/error JSON envelope. Result:
3972
5410
  "root": "/canonical/deployment",
3973
5411
  "entries": [{
3974
5412
  "harness": "claude", "file": "/native/.claude.json",
5413
+ "ambient": true, "launchConfigs": [],
3975
5414
  "key": ["projects", "/canonical/deployment", "hasTrustDialogAccepted"],
3976
5415
  "current": null, "desired": true,
3977
5416
  "beforeDigest": null, "afterDigest": "sha256-hex", "status": "change"
@@ -3981,7 +5420,16 @@ It uses the existing success/error JSON envelope. Result:
3981
5420
  }
3982
5421
  ```
3983
5422
 
3984
- Entry statuses are `change|unchanged|refused|applied|failed|incomplete|not-attempted`.
5423
+ There is one entry per target file: the ambient file of each selected harness,
5424
+ then one per launch configuration whose `env` sets `CLAUDE_CONFIG_DIR` or
5425
+ `CODEX_HOME`, deduplicated by canonical directory. `ambient` says whether the
5426
+ operator's own environment selects the file; `launchConfigs` names the launch
5427
+ configurations that do (sorted). A launch configuration whose directory cannot
5428
+ be resolved (an unset reference, a relative path) or does not exist is a
5429
+ `refused` entry with a `problem` string naming it; `file` is null when the path
5430
+ is unresolved. The directory is never created.
5431
+
5432
+ Entry statuses are `change|unchanged|refused|applied|failed|incomplete|not-attempted|skipped`. `skipped` (with `reason`) is a harness whose ambient configuration directory does not exist under `--harness all`; it is never created.
3985
5433
  `current` contains only the known trust scalar, or null when missing. Codex's key
3986
5434
  ends in `trust_level` and its desired value is `trusted`. Digests are raw-byte
3987
5435
  SHA256 hex; missing files have null beforeDigest. Plan and unattempted entries
@@ -3991,9 +5439,11 @@ unverifiable observations). The intent retains the candidate digest. Apply's aud
3991
5439
  `{path,operationId,status:"recorded"|"incomplete"}`. Override provenance is conveyed
3992
5440
  in warnings, without native configuration contents.
3993
5441
 
3994
- Preflight failures use `E_CONFIG_BROKEN` with the result in details. Apply failures
5442
+ Preflight failures, including any entry `problem`, use `E_CONFIG_BROKEN` with the
5443
+ result in details; the message names each problem. Apply failures
3995
5444
  use `E_HARNESS_TRUST_INCOMPLETE`, details `{...result,reason,mayHaveChanged}`;
3996
- reason is the closed set `locked|changed|audit|write|verify`. Partial writes are
5445
+ reason is the closed set `locked|changed|audit|write|verify`; the message names the
5446
+ failed files. Partial writes are
3997
5447
  retained. No existing instance-event envelope or lifecycle DTO changes.
3998
5448
 
3999
5449
  Audit JSONL rows have `version: 1`, `kind: "harness-trust"`, ISO `at`,