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