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