@awebai/oats 0.50.0 → 0.52.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +153 -51
  3. package/docs/capabilities.md +11 -3
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +994 -71
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +230 -59
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +73 -8
  12. package/docs/integrations.md +9 -8
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +43 -7
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/oats-local.schema.json +4 -3
  20. package/docs/official-catalog.md +4 -4
  21. package/docs/packages.md +14 -14
  22. package/docs/release-lane.md +15 -5
  23. package/docs/release-notes/v0.44.0.md +1 -1
  24. package/docs/release-notes/v0.51.0.md +156 -0
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/schedules.md +91 -4
  27. package/docs/servers.md +21 -2
  28. package/docs/souls-and-instances.md +113 -21
  29. package/docs/tui.md +152 -0
  30. package/docs/workspaces.md +2 -2
  31. package/lib/claim.mjs +266 -0
  32. package/lib/core.mjs +845 -166
  33. package/lib/errors.mjs +170 -0
  34. package/lib/harness-trust-write.mjs +68 -27
  35. package/lib/harness-trust.mjs +34 -16
  36. package/lib/instance-inspect.mjs +40 -11
  37. package/lib/instance-lifecycle.mjs +169 -47
  38. package/lib/launch-preference.mjs +16 -0
  39. package/lib/launch-prompt-completion.mjs +7 -43
  40. package/lib/launch-prompt-evidence.mjs +14 -7
  41. package/lib/launch-prompt-fixtures/README.md +86 -152
  42. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  43. package/lib/launch-prompt-fixtures.mjs +122 -109
  44. package/lib/launch-prompt-transport.mjs +2 -56
  45. package/lib/launch-prompts.mjs +102 -100
  46. package/lib/schedule-host.mjs +154 -22
  47. package/lib/schedule.mjs +73 -24
  48. package/lib/servers.mjs +20 -4
  49. package/lib/session-viewer.mjs +87 -10
  50. package/lib/system-tools.mjs +39 -0
  51. package/lib/tmux-server-scope.mjs +62 -0
  52. package/lib/triggers.mjs +4 -4
  53. package/lib/workspace.mjs +5 -11
  54. package/lib/worktree-hooks.mjs +116 -23
  55. package/lib/worktree.mjs +89 -102
  56. package/package-catalog.json +3 -3
  57. package/package.json +7 -2
  58. package/packages/client/capability-show-contract.mjs +230 -0
  59. package/packages/client/capability-warnings-contract.mjs +57 -0
  60. package/packages/client/cli-adapter.mjs +548 -0
  61. package/packages/client/cli-environment.mjs +53 -0
  62. package/packages/client/cli-locator.mjs +253 -0
  63. package/packages/client/cli-probe-contract.mjs +47 -0
  64. package/packages/client/client-terms.mjs +60 -0
  65. package/packages/client/deployment-contract.mjs +68 -0
  66. package/packages/client/deployment-data.mjs +483 -0
  67. package/packages/client/deployment-facts.mjs +34 -0
  68. package/packages/client/deployment-label.mjs +76 -0
  69. package/packages/client/deployment-observer.mjs +89 -0
  70. package/packages/client/deployment-panel.mjs +142 -0
  71. package/packages/client/deployment-read-cli.mjs +53 -0
  72. package/packages/client/display-text.mjs +44 -0
  73. package/packages/client/harness-names.mjs +30 -0
  74. package/packages/client/inspect-contract.mjs +62 -0
  75. package/packages/client/instance-acts.mjs +54 -0
  76. package/packages/client/instance-admission.mjs +45 -0
  77. package/packages/client/instance-events-contract.mjs +74 -0
  78. package/packages/client/instance-git-contract.mjs +80 -0
  79. package/packages/client/instance-presentation.mjs +22 -0
  80. package/packages/client/instance-tree.mjs +453 -0
  81. package/packages/client/kernel-environment.mjs +11 -0
  82. package/packages/client/launch-contract.mjs +51 -0
  83. package/packages/client/launch-prompt-outcome.mjs +165 -0
  84. package/packages/client/lifecycle-cli.mjs +61 -0
  85. package/packages/client/lifecycle-contract.mjs +372 -0
  86. package/packages/client/liveness-main.mjs +10 -0
  87. package/packages/client/liveness.mjs +35 -0
  88. package/packages/client/machine-contract.mjs +123 -0
  89. package/packages/client/own-environment.mjs +22 -0
  90. package/packages/client/panel-views.mjs +286 -0
  91. package/packages/client/readiness-contract.mjs +172 -0
  92. package/packages/client/refresh-loop.mjs +52 -0
  93. package/packages/client/remote-address.mjs +126 -0
  94. package/packages/client/remote-roster.mjs +67 -0
  95. package/packages/client/roster-sections.mjs +80 -0
  96. package/packages/client/spawn-apply-cli.mjs +104 -0
  97. package/packages/client/spawn-apply-contract.mjs +183 -0
  98. package/packages/client/spawn-decision.mjs +46 -0
  99. package/packages/client/spawn-messages.mjs +119 -0
  100. package/packages/client/spawn-preview-cli.mjs +32 -0
  101. package/packages/client/spawn-preview-contract.mjs +314 -0
  102. package/packages/client/team-members.mjs +41 -0
  103. package/packages/client/team-rows.mjs +45 -0
  104. package/packages/client/terminal-contract.mjs +57 -0
  105. package/packages/client/tmux-status.mjs +66 -0
  106. package/packages/client/waiting-on-you.mjs +88 -0
  107. package/packages/client/workspace-admission.mjs +45 -0
  108. package/packages/client/workspace-cli.mjs +142 -0
  109. package/packages/client/workspace-views.mjs +147 -0
  110. package/packages/tui/README.md +46 -0
  111. package/packages/tui/bin/tui.mjs +7 -0
  112. package/packages/tui/lib/actions.mjs +29 -0
  113. package/packages/tui/lib/client.mjs +4 -0
  114. package/packages/tui/lib/main.mjs +105 -0
  115. package/packages/tui/lib/term/keys.mjs +323 -0
  116. package/packages/tui/lib/term/screen.mjs +122 -0
  117. package/packages/tui/lib/term/style.mjs +43 -0
  118. package/packages/tui/lib/term/text.mjs +49 -0
  119. package/packages/tui/lib/term/tty.mjs +168 -0
  120. package/packages/tui/lib/term/width.mjs +124 -0
  121. package/packages/tui/lib/views/frame.mjs +62 -0
  122. package/packages/tui/lib/views/help.mjs +28 -0
  123. package/packages/tui/package.json +8 -0
  124. package/skills/oats-getting-started/SKILL.md +29 -22
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  127. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  128. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  129. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  130. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  131. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  132. package/lib/launch-prompt-policy.mjs +0 -87
@@ -43,14 +43,15 @@ 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"],
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"],
47
48
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
48
49
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
49
50
  "capabilityShowApi":1}
50
51
  ```
51
52
 
52
53
  - The Desktop accepts `desktopApi === 1` and a released `version` inside
53
- `ACCEPT_RANGE` (`packages/desktop/cli-locator.mjs`); a prerelease is never
54
+ `ACCEPT_RANGE` (`packages/client/cli-locator.mjs`); a prerelease is never
54
55
  accepted. The real gate is the feature list; its minimum is
55
56
  `packages-no-approval`.
56
57
  - `harnesses` is what `--harness` accepts; `sessionBackends` what `--backend`
@@ -119,6 +120,11 @@ see the [official catalog](official-catalog.md) for current pins.
119
120
  | `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
120
121
  | `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
122
  | `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)) | |
123
+ | `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"}`) | |
124
+ | `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 | |
125
+ | `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)) | |
126
+ | `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 | |
127
+ | `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)) | |
122
128
 
123
129
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
124
130
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -142,6 +148,54 @@ stdout (progress goes to stderr):
142
148
 
143
149
  - Success exits 0, failure nonzero. `error.details` is present only when the
144
150
  command has details.
151
+ - <a id="kernel-codes"></a>**The lifecycle commands answer kernel codes only**
152
+ (`oats retire`, `oats instance stop`, `oats session …`, `oats worktree
153
+ add|remove`; feature `lifecycle-kernel-codes`, OATS 0.52.0). A kernel
154
+ whose probe does not list the feature can answer one of these commands with
155
+ the system's own code (`ENOENT`, `EACCES`, `ENOTEMPTY`) and has no
156
+ `details.cause`: a client keeps its guard for such a code there. Routed
157
+ with `--server`, one of these commands is answered by the host's kernel:
158
+ gate on that host's list (`probe.features` of
159
+ [`oats server roster --json`](#the-remote-roster-oats-server-roster---json)).
160
+ A kernel code is `E_` followed by upper-case letters, digits
161
+ and underscores (`^E_[A-Z0-9_]+$`). The kernel tests that shape, not a list
162
+ of known codes, and the shape is enough: no dependency of the kernel gives
163
+ an error whose code has that shape, and neither does the system (`ENOENT`)
164
+ or Node (`ERR_…`).
165
+ An error that is not the kernel's is answered with the command's general
166
+ code (`E_LIFECYCLE_FAILED`, `E_SESSION_FAILED`, or the one its section
167
+ names). What the answer adds depends on the error:
168
+ - **One that has a code which is not a kernel code** gets
169
+ **`error.details.cause`**, beside the command's other details:
170
+ `{code, syscall}`. `code` is the system's (`ENOENT`), Node's (`ERR_…`),
171
+ or one of the kernel's own lower-case names, which these commands wrap
172
+ like the rest (`invalid-declaration`, `resource-limit`,
173
+ `integrity-drift`, `invalid-source`); `syscall` only when the error has
174
+ one.
175
+ - **A defect of the kernel** gets `details.cause: {name}`, and its stack
176
+ goes to stderr, in JSON and in text mode. A defect is an error without a
177
+ code that is one of the language's own kinds, whose `name` is not
178
+ `"Error"` (`TypeError`, `ReferenceError`, `RangeError`, `SyntaxError`, …),
179
+ or a thrown value that is no error at all (`name` is then `"Error"`; it
180
+ has no stack, and one line on stderr shows the value instead). It is
181
+ answered as one envelope like the rest. One defect has a name of the
182
+ kernel's own, `LateRefusal`: a stop or a retire met, after its first
183
+ effect, an error whose code says that nothing happened
184
+ ([the list](#before-effect-codes)).
185
+ - **A refusal without a code** (the kernel words some of its refusals that
186
+ way, and a `tmux` or `git` command that fails is reported that way) gets
187
+ neither: the general code and its message alone, no `details.cause`, no
188
+ stack. Text mode prints `oats: <message>`, as a kernel without the
189
+ feature does.
190
+
191
+ `cause` holds nothing else: no message, no path, no stack. The same rule
192
+ holds for a `code` inside a result of these commands (a stop receipt's
193
+ `results[].code`, a retire's `childrenStopped[].code`, a plan's
194
+ `session.reason` and `work.reason`). **The one exception:** an OATS
195
+ document with an unsafe mapping key or value is refused under its own name,
196
+ `unsafe-config-key` or `unsafe-config-value`, by these commands as by every
197
+ other; neither is wrapped. Elsewhere an `error.code` may still be the
198
+ system's.
145
199
  - Either envelope may carry `warnings: [ … ]`, only when there is something
146
200
  to say. The one warning is `deprecated-runtime-name`
147
201
  ([Harness input spellings](#the-harness-rename-feature-harness-oats-0270));
@@ -1632,6 +1686,17 @@ shows the drift as `launch-changed`.
1632
1686
  choose another --harness / --launch-config" (from a flag).
1633
1687
  - `E_LAUNCH_CONFIG_UNKNOWN {name, from, at}`: `souls.launch` names a launch
1634
1688
  configuration this `oats-local.yaml` does not declare.
1689
+ - `E_LAUNCH_CONFIG_AMBIGUOUS {harness, configurations, fix}` (spawn and its
1690
+ preview only, 0.52): the chosen harness has more than one launch
1691
+ configuration here (`configurations`, all their names, sorted; the message
1692
+ names the first 10, then "and K more", so it stays within 1024 characters),
1693
+ none is
1694
+ `default: true`, and the spawn named none. Named means `--launch-config
1695
+ <name>`, `--launch-config none`, or a `souls.launch` string; an inline or
1696
+ soul preference and `--harness` alone are not. `fix` is "name one with
1697
+ --launch-config <name> (or souls.launch in oats-local.yaml), or mark one
1698
+ default: true (oats launch-config set)". A start or restart of an existing
1699
+ home, `--reselect-launch` included, is never refused this way.
1635
1700
  - `E_WORKSPACE_SCHEMA`: a malformed `launch` or `souls.launch`, path named.
1636
1701
 
1637
1702
  ### The launch report (`Launch`)
@@ -1655,8 +1720,9 @@ shows the drift as `launch-changed`.
1655
1720
  `"oats-local.yaml#/souls/launch/*"`, `"<repoKey>:<path>/soul.yaml#/launch"`,
1656
1721
  or `"package:<id>:<path>/soul.yaml#/launch"`.
1657
1722
  - `problem`: `null`, or `{code, message, fix}` when a spawn would refuse
1658
- (`E_HARNESS_UNAVAILABLE`, `E_LAUNCH_CONFIG_UNKNOWN`, or `E_LAUNCH_EXECUTABLE`
1659
- for a configuration whose own executable is missing). Only reports carry it;
1723
+ (`E_HARNESS_UNAVAILABLE`, `E_LAUNCH_CONFIG_UNKNOWN`,
1724
+ `E_LAUNCH_CONFIG_AMBIGUOUS` with `effective.launchConfig` `null`, or
1725
+ `E_LAUNCH_EXECUTABLE` for a configuration whose own executable is missing). Only reports carry it;
1660
1726
  spawn and preview refuse instead. With `E_LAUNCH_CONFIG_UNKNOWN`,
1661
1727
  `effective` is the host default (`pi`, `null`, `null`): the named
1662
1728
  configuration launches nothing here.
@@ -1707,47 +1773,90 @@ the result with `oats inspect --soul <name> --json`.
1707
1773
 
1708
1774
  ## Launch prompt results
1709
1775
 
1710
- Spawn preview adds `launchPromptAnswers` with the strict effective boolean
1711
- `awebDevelopmentChannel` and `consentSource` (a config-file
1712
- JSON pointer or `null`). This is a policy report, not a terminal observation
1713
- or readiness assertion. Only the aweb development-channel confirmation is
1714
- covered, restricted to the qualified Claude executable digest, platform and
1715
- geometry documented under [launch consent](configuration.md#exact-home-launch-prompt-consent).
1716
- Folder-trust prompts remain unexpected and blocked.
1776
+ A launch engages the development-channel confirmation exactly when it starts
1777
+ Claude with `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`
1778
+ in its argv ([configuration](configuration.md#the-development-channel-confirmation)).
1779
+ There is no policy field: no preview carries `launchPromptAnswers`. Instead,
1780
+ `launch-config preview`, the spawn apply's `warnings` and `session start|restart`'s
1781
+ `warnings` carry one statement, a fixed string beginning `This start passes
1782
+ --dangerously-load-development-channels`, when the start engages it. `spawn
1783
+ --preview` does not: the argv comes from the provider's spawn hook, which a
1784
+ preview does not run. Folder-trust prompts remain unexpected and blocked.
1785
+
1786
+ The home's `instance.json` `launchPrompts` always describes the last start
1787
+ (spawn, start or restart):
1788
+
1789
+ - `{status: "not-engaged", startId, at}` for a start that did not engage it, with
1790
+ no `launchPromptTarget`;
1791
+ - `{status: "flag-ignored", reason: "channels-unavailable", signatureId, startId,
1792
+ at}` for a start where Claude ignored the flag: a notice block on its screen
1793
+ equalled the `flag-ignored` tolerance entry `signatureId`, Claude showed no
1794
+ confirmation and no key was sent. No screen text is recorded. The start
1795
+ succeeds (`launched: true`) and its `warnings` carry, in place of the statement
1796
+ beginning `This start passes`, a fixed string beginning `Claude reported
1797
+ that channels are not currently available and ignored the development-channel
1798
+ 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
1799
+ environment with any of them set gets this status too;
1800
+ - otherwise the observed result `{status, answers, reason, receipt}`, `status`
1801
+ one of `completed`, `blocked`, `incomplete`. After the Enter, no complete
1802
+ clean `SETTLE` window within the 30 s bound is `status: "blocked"` with
1803
+ `reason: "blocked: observation timeout"` and the submitted Enter in `answers`;
1804
+ `incomplete` means an audit, input or evidence failure. A
1805
+ `blocked` result also carries
1806
+ `differed: {nearest, firstDifference: {index, expected, found}}` (the nearest
1807
+ tolerance entry and at most 40 characters of each normalized text at the first
1808
+ difference) and, when the blocked screen before any Enter started with Claude's
1809
+ running-session banner, `claudeSessionShown: true` (the error and the readiness
1810
+ remedy then add that Claude may have ignored the flag with its notice hidden).
1811
+ `launchPromptTarget` is the pane.
1812
+
1813
+ A `--no-launch` spawn records no `launchPrompts`. Readers must treat
1814
+ `not-engaged` and `flag-ignored` like an absent value: retire and replay act only
1815
+ on `blocked` and `incomplete`.
1717
1816
 
1718
- An observed launch has `launchPrompts: {status, answers, reason, receipt}`.
1719
1817
  `receipt` carries the actual checked launch-prompt event-write results,
1720
1818
  including partial log availability; it is not a receive-readiness receipt.
1721
- The `launch-prompt` event records the launch start and pane/PID identity,
1722
- consent provenance, signature identifier/digest, action and outcome. Intent is
1723
- durable before input; submission (`submitted`, `failed`, `uncertain`) and an
1724
- observed screen transition are distinct. Unexpected raw screen text is never
1725
- included in the receipt.
1819
+ The `launch-prompt` event records the launch start and pane/PID identity, the
1820
+ Claude version read from the executable's real path (`claudeVersion`, a semver
1821
+ or `"unknown"`; `claudeVersionSource`, `"executable-path"` or `"unknown"`; it is
1822
+ `"unknown"` when Claude is started through a wrapper, whose path carries no
1823
+ version), the matched entry (`signatureId`) and digest, action and outcome; a miss adds
1824
+ `differed` (and `claudeSessionShown` as above); a start where Claude ignored the
1825
+ flag is one row, `status: "flag-ignored"`, `reason: "channels-unavailable"`, with
1826
+ the `flag-ignored` entry as `signatureId` and no `key`. It carries no `consentSource`. Intent is durable before input;
1827
+ submission (`submitted`, `failed`, `uncertain`) and an observed screen
1828
+ transition are distinct. Beyond `differed`'s bounded snippets, raw screen text
1829
+ is never included in the receipt.
1726
1830
 
1727
1831
  Spawn and start both reuse `E_SPAWN_INCOMPLETE` for retained prompt outcomes,
1728
1832
  with `launchPrompts.status` set to `blocked` or `incomplete`. Error details
1729
1833
  preserve `instance`, `home`, `launched:"unknown"`, `unconfirmed:true` and add
1730
1834
  `retained:true`, `target`,
1731
1835
  `parentLineageCommitted`, and `launchPrompts`. Unknown prompts report
1732
- `blocked: unexpected prompt`. An incomplete audit can follow a possible key;
1733
- clients must not offer automatic key retry. `launched:false` in retained
1734
- metadata does not mean there is no process or that another harness may be
1735
- allocated. Use runtime inspection and the existing start/restart lifecycle.
1736
- Same-key spawn replay cannot convert a blocked outcome to successful spawn.
1836
+ `blocked: unexpected prompt`. A start whose answer was submitted but that showed no
1837
+ complete clean `SETTLE` window (2 s) within the bound reports `blocked` with
1838
+ reason `blocked: observation timeout`, its `answers` holding the submitted Enter. An incomplete audit can follow a
1839
+ possible key; clients must not offer automatic key retry. `launched:false` in
1840
+ retained metadata does not mean there is no process or that another harness
1841
+ may be allocated. Use runtime inspection and the existing start/restart
1842
+ lifecycle. Same-key spawn replay cannot convert a blocked outcome to successful
1843
+ spawn.
1737
1844
 
1738
1845
  `answers` can contain a `submitted` answer even when the final status is
1739
- `blocked`: even after exact or structural completion recognition is qualified,
1740
- unsupported input/footer shapes and known question markers can block after Enter
1741
- while the actual pane is active. Consumers must preserve that submitted receipt
1742
- and never translate this outcome into “nothing started” or automatic retry.
1743
- The [completion limitation](configuration.md#exact-home-launch-prompt-consent)
1744
- is part of the shipping contract. Structural completion closes observation only;
1745
- unknown dialogs retaining the recognized composer/footer can be misclassified.
1746
- Mandatory structural evidence-save failure reports checked `incomplete` with the
1747
- same answer and target preserved. Private receipt v2 adds no public DTO fields.
1748
-
1749
- Strict Desktop/pi readers must accept these additive fields and the new event
1750
- kind before a writer containing them ships. For operator recovery, see
1846
+ `blocked`: a known question marker after the Enter, or the confirmation coming
1847
+ back, blocks while the actual pane is active. Consumers must preserve that
1848
+ submitted receipt and never translate this outcome into “nothing started” or
1849
+ automatic retry. The [completion rule](launch-prompt-completion.md) closes
1850
+ observation only; an unknown dialog without a marker can be reported completed.
1851
+ A private evidence-save failure on completion reports checked `incomplete` with
1852
+ the same answer and target preserved. Private receipt v2 adds no public DTO fields.
1853
+
1854
+ Readiness of a home whose last start recorded `blocked` carries a `launch-prompt`
1855
+ warning (`required: false`, `producer: "launch prompt"`) naming what differed and
1856
+ both remedies; it clears when a later start records anything else.
1857
+
1858
+ Strict Desktop/pi readers must accept these additive fields before a writer
1859
+ containing them ships. For operator recovery, see
1751
1860
  [launch prompt outcomes](execution-targets.md#launch-prompt-outcomes).
1752
1861
 
1753
1862
  ## Spawn
@@ -1812,7 +1921,7 @@ it to a temporary copy (`soulFetched: true`).
1812
1921
  none` ([the worktree event](capabilities.md#the-worktree-event)).
1813
1922
  - `subject` echoes `{soul, agentsRoot, dir}` byte-exact.
1814
1923
  - `warnings`, present only when there is one, is an array of strings: the
1815
- launch-prompt notice, and (0.49.0) the message of each
1924
+ `launchPromptAnswers` notice when the host file still has that key, and (0.49.0) the message of each
1816
1925
  [capability warning](#capability-warnings-hook-event-unsupported-oats-0490)
1817
1926
  of the resolved modules. The apply's `warnings` carries the same messages.
1818
1927
 
@@ -1948,6 +2057,19 @@ with `--expect-decision` records the key and decision in `instance.json`.
1948
2057
  model, parent,
1949
2058
  sibling, relation, spawnOrigin (operator | instance), attach, launchConfig,
1950
2059
  launch` (the redacted recipe).
2060
+ - `launchPrompts` (0.52.0), on a launched spawn: the value its start recorded in
2061
+ `instance.json`, in exactly the shape a start's answer carries it (see `oats
2062
+ session start`'s result below and [Launch prompt results](#launch-prompt-results)):
2063
+ `{status: "not-engaged", startId, at}`, `{status: "flag-ignored", reason:
2064
+ "channels-unavailable", signatureId, startId, at}`, or the observed
2065
+ `{status: "completed", answers, reason, receipt}`. A `blocked` or
2066
+ `incomplete` outcome is `E_SPAWN_INCOMPLETE` instead. A `--no-launch` spawn
2067
+ has none. A replay (`replayed: true`) carries the value the home holds when
2068
+ it is asked, which is the last start's and not always this spawn's. Its
2069
+ `warnings` are the capability contract warnings alone: the warnings of the
2070
+ launch itself (that OATS confirms the prompt, or that Claude ignored the
2071
+ flag) are not repeated, and `launchPrompts.status` is where a replay says
2072
+ it.
1951
2073
  - `tmux.socket` is the absolute socket of the tmux server the window was
1952
2074
  created on; a launched spawn has it, a `--no-launch` one does not. It is
1953
2075
  the OATS tmux server's
@@ -2083,9 +2205,50 @@ Every `add` or `remove` that reads a record it may act on holds the
2083
2205
  purpose's claim, `<home>/.oats/trees/<purpose>.lock`. The claim is a file
2084
2206
  that names its holder by pid and start time. A second command waits up to
2085
2207
  3 s for a live holder, then answers `E_LIFECYCLE_BUSY` (`details.lock`,
2086
- `details.pid`). A claim whose holder has died, for example one killed in the
2208
+ `details.pid`, and [`details.holder`](#busy-holder) on this and on every
2209
+ other `E_LIFECYCLE_BUSY` of these commands: OATS 0.52.0): `another oats
2210
+ worktree add or remove of purpose <purpose> is running (pid <pid> holds
2211
+ <lock>); nothing was done — retry when it has finished; if it does not end,
2212
+ check that pid by hand, and if it is not an oats worktree command, remove
2213
+ <lock>, then retry` ([a live process](#busy-holder-running), not a verified
2214
+ command). A claim whose holder has died, for example one killed in the
2087
2215
  middle of a recovery, is taken over by the next command. So a killed `add`
2088
- or `remove` can always be run again.
2216
+ or `remove` can always be run again. A holder that has exited or was killed
2217
+ and that its parent has not reaped (a zombie) has died: its claim is taken
2218
+ over, and a `creating` record whose adder is a zombie is recovered, without
2219
+ waiting for that reap (0.52.0, #870).
2220
+
2221
+ Two files at the claim's path are never taken over and never removed
2222
+ (0.52.0, #874). The command answers `E_LIFECYCLE_BUSY`, in one line that
2223
+ names the file, says that nothing was done and never says that a command is
2224
+ running: at once for a file it has read, and for a path that exists and
2225
+ reads as absent after its 3 s wait and five more attempts, 50 ms apart; `details.lock` is the file the
2226
+ message names (for the claim of a takeover, `<lock>.reclaim-<nonce>`):
2227
+
2228
+ - A path that is no readable claim: a file that does not parse, a directory,
2229
+ or a path that exists and cannot be read, such as a dangling symbolic link.
2230
+ `<file> is not a readable claim; nothing was done — inspect it and remove
2231
+ it if no oats worktree command holds it, then retry`.
2232
+ - A claim whose holder is gone and that this kernel cannot take over: its
2233
+ `nonce` is not the 32 hexadecimal digits a claim carries (a file written
2234
+ or damaged by hand); or it is the claim of a takeover that died, at the
2235
+ end of a chain of them so long that the system will not name the claim of
2236
+ one more (each adds 41 bytes to the file's name: four or five on a file
2237
+ system whose names are 255 bytes at most). `the process that held <file>
2238
+ (pid <pid>) is gone, and this file is not a claim this kernel can take
2239
+ over (<why>); nothing was done — inspect <file> and remove it if no oats
2240
+ worktree command holds it, then retry`. Removing that one file lets the
2241
+ next command take the rest over.
2242
+
2243
+ A claim that is taken again and again by commands that die is neither of
2244
+ those (0.52.0). A command takes over the claim of a holder that is gone and
2245
+ tries again. Once its 3 s are over, when it has found the claim without a
2246
+ live holder five times and each time found it taken again, the last time by
2247
+ a process that is gone, it answers `E_LIFECYCLE_BUSY` with `holder: "none"`:
2248
+ `the claim <file> was found without a live holder 5 times and was taken
2249
+ again each time, the last time by a process that is gone (pid <pid>);
2250
+ nothing was done — run the command again`. Nothing is wrong with that file
2251
+ and nothing is to be removed: the next run takes it over.
2089
2252
 
2090
2253
  A killed parent does not take its running git with it. So every git step
2091
2254
  that changes a tree, a ref or the worktree list runs in its own process
@@ -2099,6 +2262,16 @@ step that times out is cleared from the record only once its whole process
2099
2262
  group is gone. A git step that cannot be ended keeps the claim, or the
2100
2263
  record, and the command answers `E_LIFECYCLE_BUSY`.
2101
2264
 
2265
+ `E_LIFECYCLE_BUSY` says that nothing was done, so it is never answered once
2266
+ a takeover has ended a dead command's git step (0.52.0). A command that
2267
+ ends such a step and is then refused the claim (another command took it
2268
+ first, it is held again by a process that is gone, or the system refuses
2269
+ it) answers `E_LIFECYCLE_FAILED`. Its message names the group it ended
2270
+ first, then the refusal it met, with "nothing else was done": `git process
2271
+ group <pgid>, left running by a killed oats worktree command, was ended;
2272
+ after that: <the refusal>`. `details` are that refusal's own. Run the
2273
+ command again: nothing of that step is left to end.
2274
+
2102
2275
  A recorded hook group or git step that still has members while its leader's
2103
2276
  start cannot be read (where `ps` fails) is never signalled and never passed
2104
2277
  over: the leader may still be that hook or git step. The command answers
@@ -2115,19 +2288,20 @@ A failed `add` reports the same facts about its rollback in `details`:
2115
2288
  | Code | When |
2116
2289
  |---|---|
2117
2290
  | `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`) |
2118
- | `E_INSTANCE_RETIRING` | `add` in a quarantined home, or one being retired |
2291
+ | `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)) |
2119
2292
  | `E_CLONE_MISSING` | the repository is not found, or is not a Git repository |
2120
2293
  | `E_CLONE_MISMATCH` | the path is a linked worktree, or the clone has no `origin` |
2121
2294
  | `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>` |
2122
2295
  | `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 |
2123
2296
  | `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 |
2124
- | `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`) |
2297
+ | `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) |
2125
2298
  | `E_REMOTE_UNREADABLE` | the fetch of `<base>` from `origin` failed; the tree is removed |
2126
2299
  | `E_BASE_UNKNOWN` | the new HEAD is not the fetched commit; the message names both |
2127
2300
  | `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`) |
2128
2301
  | `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
2129
2302
  | `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 |
2130
2303
  | `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or the tree is still there; the record is kept |
2304
+ | `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) |
2131
2305
 
2132
2306
  A rollback that cannot finish keeps the record and says so in the message
2133
2307
  (`details.rolledBack: false`, `details.owed`); the next `add` or `remove` of
@@ -2248,6 +2422,20 @@ its absence.
2248
2422
  in the row),
2249
2423
  `identity` when a provider recorded one, `rollbackIncomplete` and
2250
2424
  `retirePending` when present, and the Desktop facts below.
2425
+ - <a id="unreadable-record-row"></a>**A home whose `instance.json` cannot be
2426
+ read** (OATS 0.52.0) is listed like every other, and one such home never
2427
+ fails the listing. Its row has the fields of a home with no `instance.json`
2428
+ and nothing from the record: `instance`, `home`, the Desktop facts
2429
+ (`startedAt`, `identityAddress`, `modelFrom`, each `null`), `waitingOnYou:
2430
+ null`, `rollbackIncomplete` and `retirePending` when present, and `running:
2431
+ null` with `runtimeState: "unreachable"` and `runtimeError:
2432
+ "E_UNIDENTIFIED_INSTANCE_HOME: <home>/instance.json cannot be read
2433
+ (<reason>)"`. The reason is the system's (`EACCES: permission denied`), the
2434
+ parser's (a file cut off, or empty), or what the file is instead: a
2435
+ directory, a symbolic link to nothing, JSON that is not an object. A home
2436
+ with no `instance.json` keeps its row: the same fields, `running: false`
2437
+ and no `runtimeState`. What the lifecycle commands answer for such a home:
2438
+ [below](#unreadable-record).
2251
2439
  - **`spawnInProgress`** (feature `worktree-event`, OATS 0.49.0): `true` only
2252
2440
  while a spawn that is running its `worktree` hooks is verifiably alive (its
2253
2441
  pid runs with the recorded start time). Such a home holds the quarantine marker
@@ -2257,7 +2445,11 @@ its absence.
2257
2445
  gone, or when its start time cannot be read (where `ps` fails), the row
2258
2446
  carries `rollbackIncomplete` as for any quarantine, its `inProgress` naming
2259
2447
  the pid; retire still refuses an unreadable one with `E_LIFECYCLE_BUSY`
2260
- until `--force`. Absent otherwise, and from older kernels.
2448
+ until `--force`. A spawn whose process has exited or was killed and that
2449
+ its parent has not reaped (a zombie) is gone (0.52.0, #870): its row
2450
+ carries `rollbackIncomplete`, where before it read `spawnInProgress: true`
2451
+ until the reap, and retire completes it. Absent otherwise, and from older
2452
+ kernels.
2261
2453
  - **`waitingOnYou`** (feature `waiting-on-you`): `{since, producer, reason,
2262
2454
  message}` when the row is `running: true` and a producer holds a live claim
2263
2455
  that the instance needs input from a human, else `null` (unknown, not "not
@@ -2895,7 +3087,57 @@ reality moved it refuses `E_PLAN_STALE` with the fresh `details.plan`. An
2895
3087
  idempotency key (`^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`) makes a retried apply
2896
3088
  return the first receipt. Recorded parentage (`parentInstance`) is the only
2897
3089
  relation followed; a child whose parent name matches several homes is listed
2898
- under `ambiguous` and never acted on.
3090
+ under `ambiguous` and never acted on. Parentage is read from each home's
3091
+ `instance.json`: a home whose record cannot be read is never stopped as
3092
+ anyone's child. It is in no plan's `targets`, `children` or `ambiguous`, and
3093
+ no stop or retire of its parent names it, so its session may go on running
3094
+ under a parent that was stopped or retired. `oats status` is where it shows
3095
+ ([its row](#unreadable-record-row)).
3096
+
3097
+ <a id="unreadable-record"></a>
3098
+ **A home whose `instance.json` is there and cannot be read** as a JSON object
3099
+ (cut off, empty, kept from the user, a directory, a link to nothing, JSON
3100
+ that is not an object; OATS 0.52.0) decides only for itself.
3101
+
3102
+ - Every command about another instance answers as if that home were not
3103
+ there: its stop and retire plans and applies, `oats session`, `oats
3104
+ instance events`, a spawn, the roster.
3105
+ - Every lifecycle command about that home is refused with
3106
+ `E_UNIDENTIFIED_INSTANCE_HOME` before it takes a claim, reads the home or
3107
+ touches anything: `oats retire` (plain, `--plan`, guarded, `--self`), `oats
3108
+ instance stop --plan` and `--apply`, `oats session start` and `restart`.
3109
+ The answer has no `details`, and the message is `<home>/instance.json
3110
+ cannot be read (<reason>); nothing was done. Restoring the file from a copy
3111
+ makes the home usable again; removing such a home through OATS is not
3112
+ possible yet.`
3113
+ - `oats retire --force` is refused the same way. `--force` removes a home
3114
+ that has no `instance.json`; a home whose record is there and cannot be
3115
+ read may be a whole instance with work, and is never removed blind.
3116
+ - The lineage is read from records. A parent whose record cannot be read has
3117
+ no recorded children for a stop or a retire: they are listed, and each is
3118
+ stopped and retired on its own. A home whose record cannot be read is never
3119
+ stopped as anyone's child: it is not a target of its parent's stop or
3120
+ retire, no plan and no answer of either names it, and a retire does not
3121
+ repair its lineage. Its session may go on running under a parent that was
3122
+ retired; `oats status` is where it shows.
3123
+ - A spawn that names such a home as its parent or anchor is refused
3124
+ (`E_SPAWN_FAILED`, the same sentence with `nothing was spawned`): the
3125
+ parent's child-spawn policy and the lineage are in that record.
3126
+ - `oats session inspect`, `input` and `attach` on that home answer
3127
+ `E_RUNTIME_ENDPOINT_UNKNOWN`, and `oats instance events` still reads its
3128
+ logs.
3129
+
3130
+ `E_UNIDENTIFIED_INSTANCE_HOME` for a record that cannot be read is answered
3131
+ only before any effect: nothing was signalled, run, copied or removed. A
3132
+ record that becomes unreadable after a retire has taken the home's claim is
3133
+ refused with the same sentence, before the retire's first signal (the end of
3134
+ the hook group an interrupted spawn left); in a guarded apply, with
3135
+ [its plan's `retire-planned` event](#guarded-apply-plan-event) already
3136
+ appended to the workspace log. That answer alone carries
3137
+ [`details.reached`](#retire-reached), untouched: `{phase: "before-effects",
3138
+ sessionStopAttempted: false, hooksStarted: false, home: "kept", recovery:
3139
+ null}`. A plan refuses the same way when the record became unreadable after
3140
+ the home was resolved.
2899
3141
 
2900
3142
  ### Stop
2901
3143
 
@@ -2921,10 +3163,28 @@ oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>]
2921
3163
  `not-launched` are idle; `unknown` is a running process tmux cannot name
2922
3164
  (the normal state of a harness). Not established: `{state:
2923
3165
  "unestablished", present: null, backend: null, established: false,
2924
- reason}`; render it as unknown, never idle.
3166
+ reason}`; render it as unknown, never idle. `reason` is the kernel code of
3167
+ what failed (`E_SESSION_UNAVAILABLE` for an error that has none).
2925
3168
  - `work` is the Git observation summarized (`changed` counts changed,
2926
- renamed, copied and unmerged rows), or `{observed: false, reason}`.
3169
+ renamed, copied and unmerged rows), or `{observed: false, reason}`:
3170
+ `"no-worktree"`, or the kernel code of what failed (`E_GIT_FAILED` for an
3171
+ error that has none; `E_WORK_INSPECTION_FAILED` for a home the kernel
3172
+ cannot look into, where whether it has a `work/` cannot be told; OATS
3173
+ 0.52.0).
2927
3174
  - `midTask`: `true`, `false` or `"unknown"`.
3175
+ - `retiring` and `stopPending`, booleans on every target, say who holds the
3176
+ target's home when the plan is read (OATS 0.52.0, feature
3177
+ `lifecycle-claim-stop`). `retiring`: a self-retire is scheduled for it
3178
+ (its pending marker is there), or a retire holds its
3179
+ [claim](#retire-one-at-a-time). `stopPending`: a stop apply holds its
3180
+ claim. A holder counts while it is not known to be gone: alive, or of a
3181
+ liveness that cannot be read. `retiring` is one of the facts
3182
+ `planRevision` is hashed from, as it was; `stopPending` is not. The
3183
+ plan's `notes` say in a line that an apply will refuse either: a note is
3184
+ a sentence for a person, and no client keys on its text (`retiring` and
3185
+ `stopPending` are the data). Before
3186
+ 0.52.0 `retiring` read the pending marker alone and `stopPending` read a
3187
+ file inside the home ([below](#stop-claim)).
2928
3188
 
2929
3189
  ```text
2930
3190
  oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key> [--no-recursive] [--grace-ms <n>] [--home <abs>] --json
@@ -2935,6 +3195,82 @@ Children first: SIGTERM to the harness processes and a bounded wait
2935
3195
  transcript and launch configuration are kept; `oats session restart` brings
2936
3196
  the instance back.
2937
3197
 
3198
+ <a id="stop-claim"></a>
3199
+ **A stop holds the claim of every target** (OATS 0.52.0, feature
3200
+ `lifecycle-claim-stop`; #866, #890). It is the file that orders the retires
3201
+ of a home ([One retire of a home at a time](#retire-one-at-a-time)):
3202
+ `<instances>/.oats-retirement/claims/<instance>.lock`, beside the homes, its
3203
+ record naming the holder by pid and start time and by its verb (`action:
3204
+ "stop"`). With `--server` it is taken on the host. An apply does this, in
3205
+ this order:
3206
+
3207
+ 1. It refuses bad arguments (`E_BAD_ARGS`), `--grace-ms` among them.
3208
+ 2. It reads the plan, for its targets.
3209
+ 3. It replays a receipt stored under the same key (below). No claim is
3210
+ taken for that.
3211
+ 4. It takes the claim of every target, in one fixed order (by the claim's
3212
+ path), so that two overlapping stops never each hold half: one takes the
3213
+ first file both want, and the other is refused at once and releases what
3214
+ it took. **A holder is answered here, before a stale plan**, as a guarded
3215
+ retire answers it: `E_INSTANCE_RETIRING` beside a retire,
3216
+ `E_LIFECYCLE_BUSY` beside another stop
3217
+ ([Commands that meet on one home](#lifecycle-pairs)). A stop never waits
3218
+ for a holder.
3219
+ 5. It reads the plan again, under the claims: this is the plan it acts on.
3220
+ **It holds the claim of every target of this plan before it does
3221
+ anything.** A target it does not hold yet (a child recorded, or readable
3222
+ again, since step 2) sends it back to step 4 with this plan's targets,
3223
+ every claim released first so that the order of step 4 holds. A stop
3224
+ whose targets are others under each of three such reads (a constant of
3225
+ the kernel: there is no setting for it) gives up:
3226
+ `E_LIFECYCLE_BUSY`, `holder: "none"`, `… nothing was stopped — run the
3227
+ command again`. It then compares the plan's revision with the one sent,
3228
+ once: `E_PLAN_STALE` with the fresh `details.plan` (the claims this
3229
+ apply holds are not reported in it as `stopPending`). A home that was
3230
+ retired since the plan was shown answers `E_SESSION_UNKNOWN`; one whose
3231
+ `instance.json` can no longer be read, `E_UNIDENTIFIED_INSTANCE_HOME`; a
3232
+ child in that state is no longer a target, which is a changed plan.
3233
+ 6. It refuses a target for which a self-retire is scheduled
3234
+ (`E_INSTANCE_RETIRING`, with `details.plan`).
3235
+ 7. It stops each target, writes the receipt and releases the claims.
3236
+
3237
+ Everything through step 6 is before any effect: nothing was signalled, and
3238
+ nothing was written into a home. From step 7 on a target's failure is a row
3239
+ of the receipt, and no answer of the apply carries a code of
3240
+ [the list](#before-effect-codes). A target that was never launched, or is
3241
+ idle, is claimed and released like any other; its row says `alreadyIdle`.
3242
+
3243
+ A stop that is killed (SIGKILL, SIGTERM, SIGINT or SIGHUP) leaves its claim
3244
+ files, and they refuse nothing: the next stop or retire of that home takes
3245
+ over the claim of a holder that is gone. Before 0.52.0 a stop marked each
3246
+ target with `<home>/.oats-stop-pending.json`, a file that named no holder,
3247
+ so a killed stop left every later stop of that instance refused
3248
+ (`E_LIFECYCLE_BUSY`) until someone removed the file (#890).
3249
+ **`.oats-stop-pending.json` stays a reserved name.** This kernel neither
3250
+ writes nor reads it. One that an older kernel left refuses nothing, does not
3251
+ make `stopPending` true, and is removed by the next stop apply of that home
3252
+ once it holds the claim; a removal that fails is a warning on stderr (`oats:
3253
+ warning: …`, in both modes) and the stop goes on.
3254
+
3255
+ <a id="stop-claim-write"></a>
3256
+ **A stop needs to write its claim.** A stop whose claim cannot be written
3257
+ (a full disk is the likely case; a claims directory that cannot be made or
3258
+ written) is refused before anything is signalled: `E_LIFECYCLE_FAILED`,
3259
+ `the claim <lock> could not be taken (<the system's error>); nothing was
3260
+ done`, with the system's code in [`details.cause`](#kernel-codes) and the
3261
+ plan it read in `details.plan`. The session runs as before. The way out:
3262
+ free space and stop again, or end the session by hand. Before 0.52.0 a stop
3263
+ took no claim: it wrote its marker if it could and signalled the harness
3264
+ either way, so it could fail afterwards, writing its own record, with the
3265
+ signal already sent.
3266
+
3267
+ Two kernel versions acting on one deployment at once are not covered: a
3268
+ kernel before 0.52.0 takes no claim for a stop and does not read a stop's
3269
+ claim. A machine has one installed CLI, and a command routed with `--server`
3270
+ runs with the host's own, so the only overlap is a command of the old
3271
+ version still running across an upgrade: upgrade with no lifecycle command
3272
+ in flight.
3273
+
2938
3274
  - The receipt is `{lifecycleApi: 1, action: "stop", instance, home,
2939
3275
  idempotencyKey, planRevision, at, ok, results, retained: ["home", "work",
2940
3276
  "transcript", "launch"], replayed: false}`. A result is `{instance, home,
@@ -2943,13 +3279,281 @@ the instance back.
2943
3279
  whether the instance runs cannot be established, among them a recorded
2944
3280
  tmux socket file that is missing while a process works in the home
2945
3281
  ([#624](execution-targets.md#missing-socket)): never `alreadyIdle`.
3282
+ - `code` is always a [kernel code](#kernel-codes). A stop that fails for a
3283
+ reason of the system's (the home removed under it, a write refused) is
3284
+ `E_SESSION_STOP_FAILED`, as one whose harness still runs after the wait is.
3285
+ Its `message` then holds the system's text and ends with what is true of
3286
+ the harness: `its harness was signalled (SIGTERM) and has exited`, `… and
3287
+ is still running`, `no signal reached its harness, which had already
3288
+ exited` (the stop found it idle, or its processes gone, when it came to
3289
+ signal), `… which was not seen to exit`, `whether its harness was signalled
3290
+ is not known`, or `its harness was not signalled`. <a id="still-running"></a>`stillRunning`
3291
+ is what the stop established of the processes it signalled, one of three
3292
+ values: the pids still alive; `[]` only when the harness exited (its
3293
+ processes are gone and the session read as idle); `null` when it
3294
+ established nothing, which is a stop that has no answer of its signalling
3295
+ step, and one whose signalled processes are all gone while the session
3296
+ still does not read as idle (its message says `is still running after <n>
3297
+ ms; nothing was escalated`): something runs there that the stop cannot
3298
+ name. Only `[]` says stopped. The three values hold from feature
3299
+ `lifecycle-kernel-codes`. A kernel without it answers `[]` in a failed row
3300
+ for that last case only (all signalled processes gone, the session not
3301
+ idle), so there `[]` establishes nothing, and it answers `null` for a
3302
+ harness that exited before something else failed. A stop that
3303
+ fails on a [defect of the kernel](#kernel-codes) is that same row, and the
3304
+ defect's stack is printed on stderr; a stop that fails on a refusal without
3305
+ a code (a `tmux` command that failed) is that row and prints no stack. The
3306
+ same holds for a child's stop in a retire's `childrenStopped`.
2946
3307
  - `ok: false`: at least one target still runs (text mode exits 1).
2947
3308
  - A replay is the stored receipt (`<home>/.oats-stop-receipt.<key>.json`)
2948
- with `replayed: true`.
3309
+ with `replayed: true`, and it follows the same rules as a first answer. The
3310
+ file a kernel with feature `lifecycle-kernel-codes` stores says so in a
3311
+ field of its own, `lifecycleKernelCodes: true`, which is part of the file
3312
+ and never of an answer: a replay leaves it out, so a replayed receipt has
3313
+ the fields of the first one. A file without that field was stored by a
3314
+ kernel from before the feature, and its failed rows are answered under the
3315
+ feature's rules: a system's code in `code` becomes `E_SESSION_STOP_FAILED`
3316
+ (the `message` keeps the system's text), and `stillRunning: []` becomes
3317
+ `null`, which is what that kernel's `[]` established. The stored file is
3318
+ never rewritten. A replay takes no claim. The same key sent again while the
3319
+ first apply still holds its claims is refused on the claim
3320
+ (`E_LIFECYCLE_BUSY`): the receipt is not written yet. Once the first apply
3321
+ has ended, the key replays.
2949
3322
  - Refusals: `E_BAD_ARGS` (no `--plan-revision`, a bad key, not exactly one of
2950
- `--plan`/`--apply`), `E_PLAN_STALE`, `E_INSTANCE_RETIRING` and
2951
- `E_LIFECYCLE_BUSY` (each with `details.plan`), `E_SESSION_UNKNOWN`,
2952
- `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_LIFECYCLE_FAILED`.
3323
+ `--plan`/`--apply`, a `--grace-ms` that is not 1–300000: answered before
3324
+ the plan is read and before the key is used. Before 0.52.0 a bad grace was
3325
+ one `E_BAD_ARGS` row per target, in a receipt stored under the key),
3326
+ `E_INSTANCE_RETIRING` and `E_LIFECYCLE_BUSY` (a target's claim is held:
3327
+ the holder's [`details`](#lifecycle-pairs), with `details.plan`, the plan
3328
+ read before the claims), `E_PLAN_STALE` (`details.plan`, the fresh one),
3329
+ `E_INSTANCE_RETIRING` for a scheduled self-retire (`details.plan`),
3330
+ `E_SESSION_UNKNOWN`,
3331
+ `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME`
3332
+ (the home's `instance.json` [cannot be read](#unreadable-record); `--plan`
3333
+ and `--apply`, nothing was done), `E_LIFECYCLE_FAILED` (any error
3334
+ that is not the kernel's; with [`details.cause`](#kernel-codes) when it has
3335
+ a code of its own or is a defect, and without it when it is a refusal
3336
+ without a code; among them a claim that cannot be taken for a reason of
3337
+ the system's: `the claim <path> could not be taken (…); nothing was done`).
3338
+ A stop never answers `E_WORK_INSPECTION_FAILED`.
3339
+
3340
+ <a id="lifecycle-pairs"></a>
3341
+ ### Commands that meet on one home
3342
+
3343
+ Feature `lifecycle-claim-stop`, OATS 0.52.0 (#866). A retire and a stop apply
3344
+ hold the home's claim for their whole run, and `oats worktree add` reads it.
3345
+ Each cell is the answer of the command that **arrives**. It is given at once
3346
+ and before any effect: that command stopped, ran, copied, made and removed
3347
+ nothing, and the command already on the home is not disturbed.
3348
+
3349
+ | On the home ↓ / arrives → | `oats retire` | `oats instance stop --apply` | `oats worktree add` |
3350
+ |---|---|---|---|
3351
+ | a retire is running | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
3352
+ | a self-retire is scheduled | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
3353
+ | a stop apply is running | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
3354
+ | a retire whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
3355
+ | a stop whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
3356
+ | the claim file is no readable claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
3357
+ | the holder of the claim is gone | not refused | not refused | not refused |
3358
+
3359
+ - **A holder is answered before a stale plan, by both verbs.** A guarded
3360
+ retire and a stop apply compare the revision they were sent only once
3361
+ they hold the claim, so beside a holder the answer is the cell above
3362
+ whatever the plan would read by then.
3363
+ - **A scheduled self-retire holds no claim** until its completion runs: it
3364
+ is its pending marker. A retire reads the marker under the claim, while
3365
+ the completion lives (`E_LIFECYCLE_BUSY`, [below](#retire-one-at-a-time)).
3366
+ A stop apply reads it in the plan it makes under its claims: a plan that
3367
+ showed `retiring: true` is answered `E_INSTANCE_RETIRING`, and an apply
3368
+ whose plan was shown before the retire was scheduled is answered
3369
+ `E_PLAN_STALE` first, with the fresh plan.
3370
+ - **A claim file that is no readable claim** is one that does not parse as
3371
+ a claim, a directory, or a path that is there and cannot be read, such as
3372
+ a dangling symbolic link. All three commands read it the same way, and
3373
+ none removes it.
3374
+ - **A holder that is gone** (it exited or was killed, a zombie too) refuses
3375
+ nothing: a retire or a stop takes its claim over and runs, and a `worktree
3376
+ add` takes nothing and runs. One file of a gone holder still refuses the
3377
+ two verbs that must take the claim: one this kernel
3378
+ [cannot take over](#retire-one-at-a-time) (a `nonce` that is not a
3379
+ claim's, written or damaged by hand) answers `E_LIFECYCLE_BUSY`, `holder:
3380
+ "none"`, to a retire and to a stop; a `worktree add` reads the same file
3381
+ as a holder that is gone, and runs. So does a file that parses and names
3382
+ no pid (`{}`, `[]`, a verb alone): a claim
3383
+ [always carries its pid](#retire-one-at-a-time), so no kernel wrote that
3384
+ file as one. And one race refuses them: a claim that was
3385
+ [taken again](#retire-one-at-a-time) by a command that then died, each of
3386
+ the five times the retire or the stop found it without a live holder, is
3387
+ `E_LIFECYCLE_BUSY`, `holder: "none"`, with `run the command again`.
3388
+ - **A stop does not refuse a `worktree add`:** a tree does not depend on the
3389
+ session.
3390
+ - `--plan` of either verb takes no claim and is never refused by one; a
3391
+ stop plan reports the holder (`retiring`, `stopPending`). `oats worktree
3392
+ remove` does not read the home's claim. `oats session start` and `restart`
3393
+ do not read it yet: they are refused only beside a scheduled self-retire
3394
+ (`E_INSTANCE_RETIRING`). `oats status` does not show a held claim.
3395
+
3396
+ Several targets:
3397
+
3398
+ 1. **A stop of a parent whose recorded child is being retired** answers
3399
+ `E_INSTANCE_RETIRING` before the first target is stopped, never after:
3400
+ the claim of every target is taken first, and the claims already taken
3401
+ are released.
3402
+ 2. **Two overlapping stops of one parent:** one stops everything, and the
3403
+ other is refused whole with `E_LIFECYCLE_BUSY`.
3404
+ 3. **A retire whose recorded child is held by someone else.** A retire does
3405
+ not hold its children's claims. It stops each child, and that stop takes
3406
+ the child's claim for its own span. A child whose claim is held is a row
3407
+ of `childrenStopped` with `ok: false`, `stillRunning: null` and the code
3408
+ of the cell above for an arriving stop (`E_LIFECYCLE_BUSY` beside a stop,
3409
+ `E_INSTANCE_RETIRING` beside a retire), and the retire answers
3410
+ **`E_CHILDREN_RUNNING`**, whether or not it had already stopped another
3411
+ child ([`reached.sessionStopAttempted`](#retire-reached) says whether a
3412
+ signal was sent). A stop of a child beside its parent's retire is not
3413
+ refused.
3414
+
3415
+ **`error.details` of a claim's refusal** is `{instance, home, lock, pid,
3416
+ since, action}`, with `holder` on `E_LIFECYCLE_BUSY`:
3417
+
3418
+ - `instance` and `home`: the home whose claim refused. **In a recursive
3419
+ stop this may be a child of the instance asked for.**
3420
+ - `lock`: the file that names the holder. `pid` and `since`: the holder's
3421
+ pid and when it took the claim.
3422
+ - **`action`: the holder's verb**, `"retire"` or `"stop"`. A claim written
3423
+ by a kernel before this feature has no verb and reads as `"retire"`. A
3424
+ reader treats a value it does not know as busy.
3425
+ - <a id="claim-file-text"></a>**Text of a claim file is never part of an
3426
+ answer.** A claim is read back as whatever is in its file, and the claims
3427
+ of a deployment's homes are in a directory that every instance of it can
3428
+ write. A field of the claim that does not have the shape the kernel
3429
+ writes is answered as `null` (`pid`: a positive integer; `since`: an
3430
+ instant as `2026-01-01T00:00:00.000Z`) and printed as `?` (the recorded
3431
+ start: `none`), and an `action` that is not a verb of the list is
3432
+ answered as `"retire"`. The same holds for a purpose's claim
3433
+ ([`oats worktree`](#oats-worktree)), whose refusal then names no `pid`,
3434
+ and for the recorded start of a process group (`details.gitStart`).
3435
+ - A refusal that names no holder has no `pid`, no `since` and no `action`:
3436
+ a claim file that is no readable claim, and a command that cannot read
3437
+ its own start time.
3438
+ - **A scheduled self-retire is no claim.** A retire's refusal beside one
3439
+ has the same keys, with `lock` the pending marker and `pid` the
3440
+ completion's. A stop apply's has `details.plan` alone, and a `worktree
3441
+ add`'s has no `details`; their message is `<instance> is being retired;
3442
+ nothing was stopped` (`no tree was made`), with no pid.
3443
+ - A stop apply's refusal carries `details.plan` beside them: the plan it
3444
+ read before it took the claims.
3445
+ - A holder whose liveness cannot be read: `details.unknown` is the reason,
3446
+ and the message names the recorded verb, the pid, its recorded start and
3447
+ the way out (check that pid by hand; if it is not that command, remove
3448
+ `<lock>`, then retry).
3449
+
3450
+ The messages: `<instance> is being retired (pid <pid>, since <at>); nothing
3451
+ was stopped — if it does not end, check that pid by hand, and if it is not
3452
+ an oats retire, remove <lock>, then retry` (a `worktree add`: `no tree was
3453
+ made`); `a stop of <instance> is already running (pid <pid>, since <at>);
3454
+ nothing was done — wait for it to finish; if it does not end, check that
3455
+ pid by hand, and if it is not an oats instance stop, remove <lock>, then
3456
+ retry` (an arriving stop: `nothing was stopped`). The step for a holder
3457
+ that does not end is [the check of a live process](#busy-holder-running).
3458
+ A client shows the message and never parses it.
3459
+
3460
+ <a id="busy-holder"></a>
3461
+ **`error.details.holder`, on every `E_LIFECYCLE_BUSY`** of `oats retire`,
3462
+ `oats instance stop` and `oats worktree add|remove`, for a claim or for
3463
+ anything else the code is answered for (a tree record, a spawn's marker, a
3464
+ scheduled completion, an owed rollback). It says, as data, whether waiting
3465
+ ends the refusal:
3466
+
3467
+ | `details.holder` | It means | What ends it |
3468
+ |---|---|---|
3469
+ | `"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 |
3470
+ | `"unknown"` | whether one still runs cannot be read | a person checks what the message names (the process, the file) |
3471
+ | `"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) |
3472
+
3473
+ A reader treats a value it does not know, or the field's absence (a kernel
3474
+ without the feature), as **do not promise that waiting ends it**. For
3475
+ `"unknown"` and `"none"` the message always names the step that ends it,
3476
+ after ` — `.
3477
+
3478
+ <a id="busy-holder-running"></a>
3479
+ **`"running"` is a live process, not a verified command.** A file that
3480
+ names any live process by its pid and start time reads as `running`,
3481
+ whoever wrote it, and waiting for that process ends nothing. So a claim's
3482
+ refusal for a holder that runs names, after the wait, the check that the
3483
+ `unknown` refusal names, in the same words: `… — wait for it to finish; if
3484
+ it does not end, check that pid by hand, and if it is not an oats retire,
3485
+ remove <lock>, then retry` (`an oats instance stop`, `an oats worktree
3486
+ command`). `E_INSTANCE_RETIRING` from a claim names the check alone: the
3487
+ instance is on its way out, so waiting makes neither the stop nor the tree
3488
+ possible. What a client does with each value of `holder` does not change. The field has a meaning only under `E_LIFECYCLE_BUSY`: under
3489
+ any other code a reader ignores it (an `E_LIFECYCLE_FAILED` made after a
3490
+ takeover ended a dead holder's step carries the details of the refusal it
3491
+ then met, `holder` among them).
3492
+
3493
+ <a id="before-effect-codes"></a>
3494
+ **The codes a stop and a retire answer only before any effect.** The kernel
3495
+ holds one list, by verb. A code in it means *refused, nothing happened*: no
3496
+ process was signalled, no hook ran, and nothing of a home was written, copied
3497
+ or removed. For a retire that is `reached.phase: "before-effects"`, or no
3498
+ [`reached`](#retire-reached) at all; for a stop apply, that no target's stop
3499
+ had begun.
3500
+
3501
+ | Code | `oats instance stop` | `oats retire` |
3502
+ |---|---|---|
3503
+ | `E_BAD_ARGS` | yes | yes |
3504
+ | `E_PLAN_STALE` | yes | yes |
3505
+ | `E_INSTANCE_RETIRING` | yes | yes |
3506
+ | `E_LIFECYCLE_BUSY` | yes | yes |
3507
+ | `E_HOME_MISMATCH` | yes | yes |
3508
+ | `E_SESSION_UNKNOWN` | yes | yes |
3509
+ | `E_AMBIGUOUS_INSTANCE` | yes | yes |
3510
+ | `E_UNIDENTIFIED_INSTANCE_HOME` | yes | yes |
3511
+ | `E_REMOTE_INCOMPATIBLE` | yes | yes |
3512
+ | `E_AMBIGUOUS` | yes | yes |
3513
+ | `E_SNAPSHOT_UNKNOWN` | yes | yes |
3514
+
3515
+ The last three are the router's (`--server`): they are answered before the
3516
+ command is sent to the host. The list is about the envelope's `error.code`.
3517
+ A row of a result (a stop receipt's `results[].code`, a retire's
3518
+ `childrenStopped[].code`) says why that one target was not stopped, and
3519
+ other rows may say that theirs was. Every other code may come after an
3520
+ effect: `E_CHILDREN_RUNNING`, `E_SESSION_STOP_FAILED`,
3521
+ `E_RUNTIME_QUIESCE_FAILED`, `E_WORK_PRESERVATION_FAILED`,
3522
+ `E_WORK_INSPECTION_FAILED`, `E_LIFECYCLE_FAILED` and the rest; for a retire
3523
+ `reached` says how far it got.
3524
+
3525
+ <a id="guarded-apply-plan-event"></a>
3526
+ **One thing has already happened when a guarded retire apply answers one of
3527
+ these codes: its plan's append.** A guarded apply reads its plan once it
3528
+ holds the home's claim, and a plan that is answered appends its
3529
+ `retire-planned` event to the workspace log, as [a plan](#retire) always
3530
+ does. Every listed code that the apply answers from there on comes with that
3531
+ event already appended, in the workspace log only: `E_PLAN_STALE` always,
3532
+ since the comparison follows the plan; `E_LIFECYCLE_BUSY` or
3533
+ `E_UNIDENTIFIED_INSTANCE_HOME` when the retire's own first reads then refuse
3534
+ (the instance is still being spawned; its record became unreadable after the
3535
+ plan). Nothing of the home is touched and no signal is sent. A stop's plan
3536
+ appends nothing, and a plain or `--self` retire reads no plan.
3537
+
3538
+ The rule holds by construction. Each verb knows how far it got at one place
3539
+ (a retire: the `phase` it reports in `reached`; a stop apply: whether a
3540
+ target's stop had begun), and an error that would leave that place with a
3541
+ listed code after the first effect is not answered with it. It is a
3542
+ [defect of the kernel](#kernel-codes): `E_LIFECYCLE_FAILED`,
3543
+ `details.cause: {name: "LateRefusal"}`, its other details kept, and its
3544
+ stack on stderr.
3545
+
3546
+ Two answers of a retire that came after an effect had a listed code before
3547
+ 0.52.0 and have another now (#895):
3548
+
3549
+ - A guarded retire whose extra trees no longer read as its plan said, found
3550
+ at the step that moves them, after the hooks: `E_WORK_PRESERVATION_FAILED`
3551
+ (it was `E_PLAN_STALE`). The home and its work are kept.
3552
+ - The worktree hook process group that an interrupted spawn left, when it
3553
+ survives SIGTERM and SIGKILL: `E_RUNTIME_QUIESCE_FAILED`, naming the group
3554
+ (it was `E_LIFECYCLE_BUSY`, "nothing was retired", after two signals).
3555
+ `reached.phase` is `"before-hooks"`; no session was stopped, no retire
3556
+ hook was run and nothing was removed.
2953
3557
 
2954
3558
  <a id="retire"></a>
2955
3559
  ### Retire
@@ -2972,6 +3576,12 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2972
3576
  "planRevision":"4e5f6a7b8c9d0e1f2a3b4c5d","notes":["the worktree is on feat/x, not the recorded agents/dev-1; …"]}
2973
3577
  ```
2974
3578
 
3579
+ - `facts.session` and `facts.work` read as a [stop plan](#stop)'s
3580
+ `session` and `work`. Work that was not observed is `{observed: false,
3581
+ reason}`: `"no-worktree"`, or the kernel code of what failed
3582
+ (`E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
3583
+ a home the kernel cannot look into, where whether it has a `work/` cannot be
3584
+ told; OATS 0.52.0).
2975
3585
  - The plan changes nothing except appending a `retire-planned` event to the
2976
3586
  workspace log. `pullRequest` is always `"unknown"`. Branch actions use the
2977
3587
  worktree's branch, never `recordedBranch`.
@@ -3148,9 +3758,9 @@ A first retire prints the **raw receipt**, not an envelope:
3148
3758
  not removed. The home and the worktree are kept, and so is any recovery the
3149
3759
  retire wrote; retry the retire.`), and a HEAD that cannot be read with
3150
3760
  `E_WORK_INSPECTION_FAILED`. Either may follow earlier effects of the same
3151
- retire (hooks run, a recovery copied), and neither says that one happened:
3152
- an error here is not proof that nothing happened, nor that a recovery
3153
- exists.
3761
+ retire (hooks run, a recovery copied): an error here is not proof that
3762
+ nothing happened, nor that a recovery exists. Read
3763
+ [`error.details.reached`](#retire-reached), which says both.
3154
3764
  - `extraWorktrees` (0.42.1): the extra trees the retire handled, present only
3155
3765
  when it handled at least one. Each row is the plan's row (`{path, repo,
3156
3766
  branch, detachedAt, disposition, movedTo, reason}`) plus `outcome`:
@@ -3164,7 +3774,9 @@ A first retire prints the **raw receipt**, not an envelope:
3164
3774
  stops it at the step, after the hooks. `--force` does not bypass either;
3165
3775
  the home and `work/` are kept, and trees already handled stay handled. A tree
3166
3776
  that no longer matches what the applied plan said refuses with
3167
- `E_PLAN_STALE`, the home kept, rather than be moved or removed unplanned.
3777
+ `E_WORK_PRESERVATION_FAILED`, the home kept, rather than be moved or
3778
+ removed unplanned (OATS 0.52.0; it was `E_PLAN_STALE`, a code that says
3779
+ nothing happened, answered after the hooks: #895).
3168
3780
  The key is additive.
3169
3781
  - `workRecovery`: `{path, classes, bytes, home, outputs?, repoCopy?,
3170
3782
  notCopied?, afterHooks?}`, present when a recovery was written. One retire
@@ -3234,20 +3846,30 @@ A first retire prints the **raw receipt**, not an envelope:
3234
3846
  `capabilityMeta`, `warnings`, `wakeSchedulesRemoved`.
3235
3847
  - A deferred self-retire (`--self`) prints `{retired, agent, deferred: true,
3236
3848
  pendingMarker, resultPath, logPath, completesInSec, completionPid}`, or
3237
- `{…, alreadyScheduled: true, requestedAt}`.
3849
+ `{…, alreadyScheduled: true, requestedAt}` while one is scheduled and its
3850
+ completion has not started (below).
3238
3851
 
3239
3852
  **Recorded children**, on every apply (plain, guarded and `--self`), as the
3240
3853
  plan says: each child the plan lists is stopped first (bounded SIGTERM,
3241
3854
  never escalated) and kept, once the retire has resolved the home and before
3242
- the instance's own session is stopped. `childrenStopped[]` lists them,
3855
+ the instance's own session is stopped. A home whose `instance.json`
3856
+ [cannot be read](#unreadable-record) is never stopped as anyone's child: the
3857
+ plan does not list it, `childrenStopped[]` does not name it, and its session
3858
+ may go on running after its parent is retired; `oats status` is where it
3859
+ shows. `childrenStopped[]` lists the children stopped,
3243
3860
  deepest first, as `{instance, home, ok: true, stopped, alreadyIdle}` or
3244
- `{instance, home, ok: false, code, message, stillRunning}`. A plain or
3861
+ `{instance, home, ok: false, code, message, stillRunning}`, where
3862
+ `stillRunning` has the three values of [a stop's result](#still-running): the
3863
+ pids still alive, `[]` only when the child's harness exited, `null` when
3864
+ nothing is established. A plain or
3245
3865
  `--self` receipt carries it only when there are children; a guarded receipt
3246
3866
  always does (`[]` when there are none). One child still running after the
3247
3867
  grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
3248
- `E_INSTANCE_RETIRING`, …), refuses everything: nothing is retired, exit 1,
3868
+ `E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY`, …), refuses everything: nothing is retired, exit 1,
3249
3869
  `E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
3250
- `code`). **`--force` does not bypass it**: `--force` covers incomplete
3870
+ `code`, always a [kernel code](#kernel-codes); the message says `still running after a bounded stop`
3871
+ only of a child whose row lists processes in `stillRunning`, and `<child> could not be stopped
3872
+ (<code>)` of any other, OATS 0.52.0). **`--force` does not bypass it**: `--force` covers incomplete
3251
3873
  cleanup, not a running child. A `--self` retirement stops the children
3252
3874
  recorded when it was scheduled that are still instances (a child retired in
3253
3875
  between is skipped), in its detached completion before it stops the caller;
@@ -3259,29 +3881,293 @@ retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
3259
3881
  `--idempotency-key` together.
3260
3882
  - A used key replays its receipt as an **envelope** with `replayed: true`
3261
3883
  (receipts live beside the instances directory and outlive the home).
3262
- - The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`.
3884
+ - The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`. That
3885
+ plan is read once, when the retire holds the home's claim (below): it is
3886
+ the state the retire starts from, and one apply appends one
3887
+ `retire-planned` event. Against a retire in flight or a scheduled
3888
+ self-retire the answer is `E_LIFECYCLE_BUSY` and no plan is read, whatever
3889
+ the plan would read by then: a retire in flight has usually changed it (it
3890
+ stops the session of a launched instance before its hooks run). Before the
3891
+ claim an apply only replays a used key and resolves the home
3892
+ (`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`,
3893
+ `E_UNIDENTIFIED_INSTANCE_HOME` for a home whose `instance.json`
3894
+ [cannot be read](#unreadable-record)).
3263
3895
  - The children stopped are those of the revalidated plan, and a refusal
3264
3896
  carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
3265
3897
  - A first guarded retire prints the raw receipt with `planRevision`,
3266
3898
  `idempotencyKey` and `replayed: false`.
3267
3899
 
3268
- Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
3900
+ <a id="retire-one-at-a-time"></a>
3901
+ **One retire of a home at a time** (0.51.0, #863), **and one retire or stop**
3902
+ (0.52.0, #866: a stop apply holds the same claim,
3903
+ [above](#stop-claim)). Every retire that applies (plain,
3904
+ guarded, `--self` and its detached completion; with `--server`, on the host)
3905
+ holds the home's claim,
3906
+ `<instances>/.oats-retirement/claims/<instance>.lock`, from the moment it
3907
+ has resolved the home until it ends, by success or by any refusal or failure.
3908
+ The claim is a file that names its holder by pid and start time, and by its
3909
+ verb (`action`: `"retire"` or `"stop"`; 0.52.0). It is written whole to a
3910
+ private file and linked into place, so a kernel's claim is never seen
3911
+ without its `pid`: a file there that parses and names no pid was not
3912
+ written by a kernel as a claim, and a kernel that wrote one without it would
3913
+ be changing the lock format, which is a contract decision. It lies
3914
+ beside the homes, never inside one: a home's bytes are what its retire
3915
+ observes, copies and removes. A second retire of that home, or a retire that
3916
+ meets a stop of it, does not wait: it
3917
+ answers `E_LIFECYCLE_BUSY` at once (exit 1; the text form prints the
3918
+ message), before it stops a session or a child, writes a recovery, runs a
3919
+ hook or changes a file of the home. **`--force` does not bypass it**, and
3920
+ `--plan` takes no claim and refuses nothing new. A guarded apply answers it
3921
+ before `E_PLAN_STALE`: under the claim the answers come in this order: the
3922
+ home is gone (`E_SESSION_UNKNOWN`), a self-retire is scheduled
3923
+ (`E_LIFECYCLE_BUSY`), the plan is stale (`E_PLAN_STALE`), then the retire. A claim whose holder has
3924
+ died, for example a retire killed while its hooks ran, is taken over by the
3925
+ next retire of that name. So a killed retire can always be run again. A
3926
+ holder that has exited or was killed and that its parent has not reaped (a
3927
+ zombie) has died: its claim is taken over without waiting for that reap
3928
+ (0.52.0, #870; before, the retire was refused as running until the reap). The
3929
+ claim does not end what the killed retire left running: one of its retire
3930
+ hooks may still be running when the next retire takes the claim over and
3931
+ runs the hooks again (#865). Until
3932
+ that name is retired again its claim file stays where it is, and it is safe
3933
+ to remove once its pid is gone. A retire that ends removes its claim file;
3934
+ the `claims/` directory itself stays, empty.
3935
+
3936
+ `details` is `{instance, home, lock, pid, since, action, holder}`: `lock` is
3937
+ the file that names the holder, `since` when the holder took it, `action`
3938
+ the holder's verb and [`holder`](#busy-holder) whether waiting ends it (both
3939
+ 0.52.0, feature `lifecycle-claim-stop`;
3940
+ [Commands that meet on one home](#lifecycle-pairs)). Every message is one
3941
+ line and says that nothing was done:
3942
+
3943
+ - A live holder (`holder: "running"`): `a retire of <name> is already
3944
+ running (pid <pid>, since <at>); nothing was done — wait for it to
3945
+ finish; if it does not end, check that pid by hand, and if it is not an
3946
+ oats retire, remove <lock>, then retry`; beside a stop, `a stop of <name>
3947
+ is already running …`, with `action: "stop"` and `an oats instance
3948
+ stop`. Live is what was established
3949
+ [of the process](#busy-holder-running), not that it is that command.
3950
+ - A holder whose start time cannot be read (where `ps` fails, or a claim
3951
+ that records none) is never taken for gone, and its claim is never taken
3952
+ over (`holder: "unknown"`). `details.unknown` is the reason. The message
3953
+ names the holder's verb, the pid, its recorded start, the reason and the
3954
+ way out: check that pid by hand, and if it is not that command (`oats
3955
+ retire`, `oats instance stop`), remove `<lock>`, then retry.
3956
+ - A claim file that is not a readable claim is never removed: a file that
3957
+ does not parse, a directory, or a path that exists and cannot be read, such
3958
+ as a dangling symbolic link (0.52.0, #874: that one made the retire spin
3959
+ without end; it is now refused once its retries are spent, a quarter of a
3960
+ second for a retire, which does not wait).
3961
+ `details` is `{instance, home, lock, holder: "unknown"}`; the message is
3962
+ `<lock> is not a readable claim; nothing was done — inspect it and remove
3963
+ it if no oats retire or oats instance stop holds it, then retry`.
3964
+ - A claim whose holder is gone and that this kernel cannot take over is
3965
+ never removed either: its `nonce` is not the 32 hexadecimal digits a claim
3966
+ carries (a file written or damaged by hand); or it is the claim of a
3967
+ takeover that died (`<lock>.reclaim-<nonce>`), at the end of a chain of
3968
+ them so long that the system will not name the claim of one more (each
3969
+ adds 41 bytes to the file's name: three to five on a file system whose
3970
+ names are 255 bytes at most). `details` is `{instance, home, lock, pid,
3971
+ since, action, holder: "none"}`, `lock` being the file the message names.
3972
+ The message is `the
3973
+ process that held <lock> (pid <pid>) is gone, and this file is not a claim
3974
+ this kernel can take over (<why>); nothing was done — inspect <lock> and
3975
+ remove it if no oats retire or oats instance stop holds it, then retry` (0.52.0, #874; before,
3976
+ the first was answered as a live holder, to wait for, and the second as
3977
+ `E_LIFECYCLE_FAILED` with the system's `ENAMETOOLONG` about a file that
3978
+ does not exist). Removing that one file lets the next retire take the
3979
+ rest over. A retire of a name that has no home leaves a file whose nonce
3980
+ is not a claim's as it is.
3981
+ - A claim that is taken again and again by commands that die is an ordinary
3982
+ claim, and is not refused with that sentence. A retire takes over the
3983
+ claim of a holder that is gone and tries again, five times. When each time
3984
+ it found the claim taken again, the last time by a process that is gone,
3985
+ `details` is `{instance, home, lock, pid, since, action, holder: "none"}`
3986
+ (the last holder's), and the message is `the claim <lock> was found
3987
+ without a live holder 5 times and was taken again each time, the last time
3988
+ by a process that is gone (pid <pid>); nothing was done — run the command
3989
+ again` (a stop: `nothing was stopped`). Nothing is to be inspected or
3990
+ removed: the next retire or stop takes that claim over.
3991
+ - The retire's own start time cannot be read, so it could not hold the claim
3992
+ verifiably: `details` is `{instance, home, lock, holder: "none"}`, and the
3993
+ message gives the reader's own reason (the `/proc` read, or what `ps`
3994
+ answered) and the check to run by hand in a shell on that host: `cat
3995
+ /proc/$$/stat` where there is a `/proc`; elsewhere `PATH=/usr/bin:/bin ps
3996
+ -o lstart= -o stat= -p $$`, which must print a start time and a state.
3997
+ Then the command again.
3998
+
3999
+ A scheduled self-retire counts from the moment it is scheduled. Its pending
4000
+ marker (`pendingMarker`) records the completion process as `completionPid`
4001
+ and `completionStart` (`null` when the start could not be read). While that
4002
+ process lives, every other retire of the instance is refused the same way,
4003
+ `--self --keep-dir` included: `a retire of <name> is already scheduled (its
4004
+ completion, pid <pid>, requested at <requestedAt>); nothing was done — wait
4005
+ for it to finish`, with `details.lock` the pending marker, `details.pid` the
4006
+ completion and `details.since` the marker's `requestedAt`. A completion
4007
+ whose start cannot be read is refused as a holder's is (`details.unknown`),
4008
+ the file to remove being the pending marker. A second `--self` answers
4009
+ `alreadyScheduled: true` only while the completion has not started. While
4010
+ the first `--self` is still scheduling, or once the completion holds the
4011
+ claim, it is refused the claim and answers `E_LIFECYCLE_BUSY` like any other
4012
+ retire, where it answered `alreadyScheduled: true` before 0.51.0. The marker refuses nothing once its completion has
4013
+ left its outcome at `resultPath` (it failed) or is gone (it died; a
4014
+ completion that is a zombie, not reaped by its parent, has died: 0.52.0,
4015
+ #870), nor when
4016
+ it names no completion (a marker written before 0.51.0): `oats retire
4017
+ <instance>` then retries the retirement, as before. The completion waits up
4018
+ to 3 s for the retire that scheduled it to release the claim, then takes it
4019
+ as any retire does; one that meets another retire still running is refused,
4020
+ and records that at `resultPath` like any failed completion. The `error`
4021
+ recorded there has the code and the message the same failure has as an
4022
+ envelope: a kernel code, and what the retire had done by then.
4023
+
4024
+ A `--self` that cannot finish scheduling (the completion's log cannot be
4025
+ opened, no process is created, the marker cannot be written) answers
4026
+ `E_SELF_RETIRE_SCHEDULE_FAILED`, with `reached.phase: "before-effects"`. That
4027
+ stays true after the answer: a completion this command had started is not
4028
+ running when it answers (it is ended, unless it had gone by itself; a
4029
+ completion does nothing to the instance before it holds the home's claim,
4030
+ which the retire that scheduled it holds until it has answered), and its
4031
+ log and any result it had recorded are removed. One leftover is possible and
4032
+ is not a debt of the instance: a completion that was kept waiting for the
4033
+ claim until it gave up may write its result (`E_LIFECYCLE_BUSY`) at the
4034
+ moment it is ended, after that removal. The next `oats retire` of the
4035
+ instance removes it. The instance is still live and can be retired
4036
+ externally.
4037
+
4038
+ The home is resolved again once the claim is held. One that another retire
4039
+ removed in between answers `E_SESSION_UNKNOWN`, as a retire of a retired
4040
+ instance does. If the name is by then the home of another agent, the retire
4041
+ starts over on that home, under that home's claim; after two such changes it
4042
+ answers `E_LIFECYCLE_BUSY` (`the home of <name> changed while its claim was
4043
+ being taken …; nothing was done — retry`, `details: {instance, home, lock}`).
4044
+ A retire of a name that has no home also removes a claim of that name whose
4045
+ holder is gone, left by a retire that was killed after it removed the home.
4046
+
4047
+ The claim orders the retires and the stops of a home (0.52.0, #866): `oats
4048
+ instance stop --apply` takes it, and `oats worktree add` reads it
4049
+ ([Commands that meet on one home](#lifecycle-pairs)). `oats session start`
4050
+ and `restart` do not read it yet, and `oats status` does not show a held
4051
+ claim. Before 0.52.0 the claim ordered retires only: a stop was not refused
4052
+ beside a retire in flight, and wrote into the home that the retire was
4053
+ inspecting or removing.
4054
+
4055
+ Refusals (envelopes): `E_PLAN_STALE` (a guarded apply's revision, checked
4056
+ under the claim: before any effect), `E_CHILDREN_RUNNING`,
3269
4057
  `E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
3270
4058
  `--discard-worktree` when it is `work/` that could not be re-homed: it does
3271
- not apply to an extra tree), `E_WORK_INSPECTION_FAILED` (the home is kept; the
4059
+ not apply to an extra tree; also a guarded retire whose extra trees no
4060
+ longer read as its plan said, after the hooks: review the fresh plan and
4061
+ apply again), `E_RUNTIME_QUIESCE_FAILED` (the session's window could not be
4062
+ shown gone; or the worktree hook process group an interrupted spawn left
4063
+ survived SIGTERM and SIGKILL: end that group by hand, then retire again),
4064
+ `E_WORK_INSPECTION_FAILED` (the home is kept; the
3272
4065
  message names the entry or the state that could not be read, or the directory
3273
4066
  Git reads as the top level of a `work/` whose `core.worktree` names another
3274
4067
  one),
3275
4068
  `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
3276
- `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (feature
4069
+ `E_UNIDENTIFIED_INSTANCE_HOME` (a home with no `instance.json` and no cleanup
4070
+ descriptor, or a rollback marker that cannot drive a retry, until `--force`;
4071
+ a home whose `instance.json` [cannot be read](#unreadable-record), `--plan`
4072
+ and `--force` included),
4073
+ `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
4074
+ home is running or scheduled, or a stop of it is running, `--force`
4075
+ included: one retire or stop of a home at a time, above; or, feature
3277
4076
  `worktree-event`: the home is a spawn still running its `worktree` hooks, a
3278
4077
  row with `spawnInProgress: true`, `--force` included; or one whose start time
3279
4078
  cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
3280
- group whose leader's start cannot be read, until `--force`). A recovery whose Git status disagrees with
4079
+ group whose leader's start cannot be read, until `--force`; every one is
4080
+ answered before any effect and carries [`details.holder`](#busy-holder)). The
4081
+ codes a retire answers only before any effect are
4082
+ [one list](#before-effect-codes). A recovery whose Git status disagrees with
3281
4083
  the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
3282
4084
  source, recovery}], total}}` (the first 10 paths). Usage errors are text on
3283
4085
  stderr, not envelopes.
3284
4086
 
4087
+ <a id="retire-reached"></a>
4088
+ **What a failed retire had done: `error.details.reached`** (feature
4089
+ `lifecycle-kernel-codes`, OATS 0.52.0). Every error a
4090
+ retire apply answers once it has resolved the home and holds its claim, a
4091
+ typed refusal or not, carries it beside its other details. A client shows the
4092
+ message and never parses it; this is the same statement as data. Gate on the
4093
+ probe, never on the field: from a kernel that lists the feature an absent
4094
+ `reached` means the error was answered before the retire of the home began
4095
+ and nothing was done (below); from a kernel without it an absent `reached`
4096
+ says nothing.
4097
+
4098
+ ```json
4099
+ {"phase":"after-hooks","sessionStopAttempted":true,"hooksStarted":true,"home":"kept",
4100
+ "recovery":{"path":"/w/agents/dev/instances/.oats-retirement/recovery/dev-1-Ab12Cd","phase":"before-hooks"}}
4101
+ ```
4102
+
4103
+ - `phase`: how far the retire got. `"before-effects"`: nothing of the
4104
+ instance was touched and no process was signalled (the first inspection
4105
+ is usually here).
4106
+ `"before-hooks"`: from the step that stops its recorded children on,
4107
+ whether or not that step had anything to signal (then the stop of its own
4108
+ session, the second inspection, the copy made before the hooks), until the
4109
+ hook runner is called. It begins earlier in one case: a home whose
4110
+ interrupted spawn left a worktree hook process group that the retire can
4111
+ prove is that spawn's has that group ended before the first inspection, and
4112
+ `phase` is `"before-hooks"` from the moment the retire may have signalled
4113
+ it. So `"before-hooks"` says neither that a process was signalled nor that
4114
+ the children step was reached; `"before-effects"` is never answered after
4115
+ a signal. `"after-hooks"`: from
4116
+ the call of the retire hooks on (the third inspection, the copy's
4117
+ conclusion, the extra trees and the worktree). `"removal"`: from the
4118
+ removal of the home on.
4119
+ - **In the other four fields the untouched value is a guarantee, and the
4120
+ other value means only that the retire reached that step, which may not
4121
+ have completed.**
4122
+ - `sessionStopAttempted`: `false` = this retire sent no signal to the
4123
+ instance's session nor to any child's harness. `true` = it began to.
4124
+ - `hooksStarted`: `false` = no retire hook was started. `true` = the hook
4125
+ runner was called.
4126
+ - `home`: `"kept"` = the removal has not begun. Otherwise what is on disk
4127
+ when the error is answered: `"partial"` (the removal began and the
4128
+ directory is still there: it is no longer guaranteed to be a whole
4129
+ instance home) or `"removed"` (it is not there).
4130
+ - `recovery`: `null` = no copy of this retire whose manifest can be read.
4131
+ Otherwise `{path, phase}`: the absolute path of the copy, and the `phase`
4132
+ its `recovery.json` holds on disk when the error is answered
4133
+ (`"before-hooks"` or `"complete"`). A removal that fails after a complete
4134
+ recovery therefore names where the work is.
4135
+ - Four points where a step was reached and its outcome is not established:
4136
+ the hook process group an interrupted spawn left was signalled and did not
4137
+ end (`E_RUNTIME_QUIESCE_FAILED`; `phase: "before-hooks"`, and
4138
+ `sessionStopAttempted: false`: that group is no session);
4139
+ the kill of the session's window was sent and the check that the window is
4140
+ gone failed (`E_RUNTIME_QUIESCE_FAILED`; `sessionStopAttempted: true`, and
4141
+ the harness may still run); a child's stop that signalled its harness and
4142
+ then failed, or failed while signalling (`sessionStopAttempted: true`); the
4143
+ hook runner throwing part-way (`hooksStarted: true`, and some hooks may not
4144
+ have run).
4145
+ - `phase`, `home` and `recovery.phase` are closed lists. A reader treats a
4146
+ value it does not know as "effects may have happened".
4147
+ - It is absent from the answers given before the retire of the home begins,
4148
+ where nothing was done: a name that resolves to no home, to several or to
4149
+ another one, the claim, a scheduled self-retire, a guarded apply's plan
4150
+ (`E_PLAN_STALE` with `details.plan`). It is not part of a plan.
4151
+
4152
+ **An error that is not the kernel's** (a file the system refuses to read, a
4153
+ directory that cannot be removed) is answered with a
4154
+ [kernel code](#kernel-codes), [`details.cause`](#kernel-codes) (when the
4155
+ error has a code of its own or is a defect; a refusal without a code has
4156
+ none), `reached`, and a message that ends with the sentence the typed refusals at that point carry:
4157
+
4158
+ | Where it fails | Code | The message ends with |
4159
+ |---|---|---|
4160
+ | 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.` |
4161
+ | 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` |
4162
+ | 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; …` |
4163
+ | 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 |
4164
+ | 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; …` |
4165
+
4166
+ `E_WORK_INSPECTION_FAILED` is answered only by a retire, only before the
4167
+ removal begins, and only with the home kept (`reached.home: "kept"`). A
4168
+ typed refusal keeps its code, its details and its own words; the inspections'
4169
+ and the recovery's refusals end with the sentence of their phase, once.
4170
+
3285
4171
  ## Sessions and launch configurations
3286
4172
 
3287
4173
  ### Input
@@ -3332,7 +4218,14 @@ selection flags. See [the start workflow](desktop-instance-start.md).
3332
4218
 
3333
4219
  - The result is `{instance, agent, home, harness, backend, model,
3334
4220
  launchConfig, yolo, target, startedAt, restartCount, reused, warnings}`,
3335
- plus `nativeRecordId` and `stop` (a restart's stop receipt) when they apply.
4221
+ plus `nativeRecordId` and `stop` (a restart's stop receipt) when they apply,
4222
+ and (0.52.0) `launchPrompts`, the value this start recorded in `instance.json`:
4223
+ `{status: "not-engaged", startId, at}` for a start that did not engage the
4224
+ development-channel confirmation, `{status: "flag-ignored", reason:
4225
+ "channels-unavailable", signatureId, startId, at}` for one where Claude ignored
4226
+ the flag (with its warning in `warnings`), or the observed `{status: "completed",
4227
+ answers, reason, receipt}`. A `blocked` or `incomplete` outcome is
4228
+ `E_SPAWN_INCOMPLETE` instead ([Launch prompt results](#launch-prompt-results)).
3336
4229
  - `warnings` (0.30) is always present: an array of strings, the warnings the
3337
4230
  capabilities' `launch` hooks returned for this start (as spawn's
3338
4231
  `warnings`), `[]` when there are none. Each is also appended to the
@@ -3374,9 +4267,15 @@ selection flags. See [the start workflow](desktop-instance-start.md).
3374
4267
  - A lost response does not mean the launch failed: check status before a
3375
4268
  retry. A remote home's saved route names its execution host.
3376
4269
  - Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
4270
+ `E_UNIDENTIFIED_INSTANCE_HOME` (the home's `instance.json`
4271
+ [cannot be read](#unreadable-record): nothing was started, `start` and
4272
+ `restart`),
3377
4273
  `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*` (among them
3378
4274
  `E_LAUNCH_SHIM`: the home's `oats` link cannot be written, nothing was
3379
- started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`.
4275
+ started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`
4276
+ (any error that is not the kernel's; with
4277
+ [`details.cause`](#kernel-codes) when it has a code of its own or is a
4278
+ defect, and without it when it is a refusal without a code).
3380
4279
 
3381
4280
  ### Upload
3382
4281
 
@@ -3549,6 +4448,12 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
3549
4448
  - `session` is `{instance, home, incarnation, server, delivery: "launched"
3550
4449
  | "delivered-active" | "none"}`: recorded provenance, not a transcript
3551
4450
  reader.
4451
+ - `warnings?` (feature `schedule-run-warnings`): the launch answer's
4452
+ warnings, strings, present only when it had some (a spawn job's spawn, a
4453
+ wake that started its session). For example, that the OATS tmux server
4454
+ was started inside the tick's systemd service
4455
+ ([execution targets](execution-targets.md#a-server-started-from-inside-a-systemd-service)).
4456
+ A later run of the same record never keeps an earlier run's.
3552
4457
  - `nextDue` is "when it next runs" in every row (`null` when another host
3553
4458
  runs it); a schedule row also keeps `nextRun`.
3554
4459
  - **Integrity.** `oats-schedules.json` and `.agents/schedules/state.json` are
@@ -3564,8 +4469,10 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
3564
4469
  - `add <id> (--file <spec.json> | --spec-json <json>)`, `update`, `enable`,
3565
4470
  `disable` → `{schedule}`. `run [--force]`, `remove [--force]`, `reconcile
3566
4471
  [--clear]` → the action's receipt. `tick [--dry-run] [--host]` →
3567
- `{tickedAt, considered, scheduler}`; `host install | uninstall | status` →
3568
- `{scheduler}`.
4472
+ `{tickedAt, considered, scheduler}`; `host install` → `{scheduler, warnings}`;
4473
+ `host uninstall | status` → `{scheduler}`; `host install --print [--os
4474
+ darwin|linux]` → `{kind, files: {<path>: <content>}, warnings}`, writing
4475
+ nothing.
3569
4476
  - `test <id>` → `{test: {id, qualifiedId, kind, placement: {runsHere, reason,
3570
4477
  reasonDetail?, enabledHere, runsOn, owner, host}, soul: {name, origin,
3571
4478
  resolves, error} | null, nextDue, spawned: false, problems, ok}}`. The soul
@@ -3607,7 +4514,9 @@ capability declares ([schedules.md](schedules.md#capability-sources)).
3607
4514
  distinct labels passed as `--provider <messaging cap> join=<labels>`; a
3608
4515
  soul without messaging refuses `E_TRIGGER_TEAMS {soul, teams}`.
3609
4516
  - `template?`: `{package, version, commit, template}`.
3610
- - `lastRun`: `{at, instance, home, event, number, subject, key}`
4517
+ - `lastRun`: `{at, instance, home, event, number, subject, key, warnings?}`
4518
+ (`warnings?`, feature `schedule-run-warnings`: the fire's spawn answer's
4519
+ warnings, present only when it had some)
3611
4520
  (`subject`, 0.49.0: the event's subject, a PR's number as a string;
3612
4521
  for a run recorded before 0.49.0, its number; a capability source's
3613
4522
  run has `number: null`); `nextDue`: the next poll here, `null` before
@@ -3774,8 +4683,10 @@ Details: [schedules.md](schedules.md#workspace-triggers-and-schedules).
3774
4683
  null}}` (this machine's `host.name` and its `gh` logins, compared with a
3775
4684
  row's `owner`), `snapshot: {takenAt, problems (a count)} | null` (the last
3776
4685
  `oats sync` snapshot), and `scheduler: {installed, active, registered,
3777
- lastTick, maxConcurrent, triggersMaxConcurrent, …}` (nothing runs unless installed, active and
3778
- registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
4686
+ problems, lastTick, maxConcurrent, triggersMaxConcurrent, …}` (nothing runs unless installed, active and
4687
+ registered; `problems` is always an array of `{code, message, fix}` warnings
4688
+ about the installed unit, see [schedules](schedules.md#the-host-timers-unit), and never
4689
+ changes `installed` or `active`). `maxConcurrent` is the effective scheduled-job cap (default 5);
3779
4690
  `triggersMaxConcurrent` is the separate trigger cap, or `null` for no host cap.
3780
4691
 
3781
4692
  **Every row** carries:
@@ -3884,6 +4795,7 @@ It uses the existing success/error JSON envelope. Result:
3884
4795
  "root": "/canonical/deployment",
3885
4796
  "entries": [{
3886
4797
  "harness": "claude", "file": "/native/.claude.json",
4798
+ "ambient": true, "launchConfigs": [],
3887
4799
  "key": ["projects", "/canonical/deployment", "hasTrustDialogAccepted"],
3888
4800
  "current": null, "desired": true,
3889
4801
  "beforeDigest": null, "afterDigest": "sha256-hex", "status": "change"
@@ -3893,7 +4805,16 @@ It uses the existing success/error JSON envelope. Result:
3893
4805
  }
3894
4806
  ```
3895
4807
 
3896
- Entry statuses are `change|unchanged|refused|applied|failed|incomplete|not-attempted`.
4808
+ There is one entry per target file: the ambient file of each selected harness,
4809
+ then one per launch configuration whose `env` sets `CLAUDE_CONFIG_DIR` or
4810
+ `CODEX_HOME`, deduplicated by canonical directory. `ambient` says whether the
4811
+ operator's own environment selects the file; `launchConfigs` names the launch
4812
+ configurations that do (sorted). A launch configuration whose directory cannot
4813
+ be resolved (an unset reference, a relative path) or does not exist is a
4814
+ `refused` entry with a `problem` string naming it; `file` is null when the path
4815
+ is unresolved. The directory is never created.
4816
+
4817
+ 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.
3897
4818
  `current` contains only the known trust scalar, or null when missing. Codex's key
3898
4819
  ends in `trust_level` and its desired value is `trusted`. Digests are raw-byte
3899
4820
  SHA256 hex; missing files have null beforeDigest. Plan and unattempted entries
@@ -3903,9 +4824,11 @@ unverifiable observations). The intent retains the candidate digest. Apply's aud
3903
4824
  `{path,operationId,status:"recorded"|"incomplete"}`. Override provenance is conveyed
3904
4825
  in warnings, without native configuration contents.
3905
4826
 
3906
- Preflight failures use `E_CONFIG_BROKEN` with the result in details. Apply failures
4827
+ Preflight failures, including any entry `problem`, use `E_CONFIG_BROKEN` with the
4828
+ result in details; the message names each problem. Apply failures
3907
4829
  use `E_HARNESS_TRUST_INCOMPLETE`, details `{...result,reason,mayHaveChanged}`;
3908
- reason is the closed set `locked|changed|audit|write|verify`. Partial writes are
4830
+ reason is the closed set `locked|changed|audit|write|verify`; the message names the
4831
+ failed files. Partial writes are
3909
4832
  retained. No existing instance-event envelope or lifecycle DTO changes.
3910
4833
 
3911
4834
  Audit JSONL rows have `version: 1`, `kind: "harness-trust"`, ISO `at`,