@awebai/oats 0.55.1 → 0.57.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/bin/oats.mjs +96 -72
- package/docs/capabilities.md +67 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
- package/docs/desktop-cli-api.md +375 -37
- package/docs/desktop-instance-start.md +105 -12
- package/docs/desktop.md +65 -11
- package/docs/execution-targets.md +184 -9
- package/docs/harness-trust.md +128 -11
- package/docs/implementation.md +153 -11
- package/docs/integrations.md +5 -3
- package/docs/knowledge.md +117 -43
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-lane.md +26 -1
- package/docs/release-notes/v0.56.0.md +699 -0
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +21 -5
- package/docs/souls-and-instances.md +134 -19
- package/docs/tui.md +215 -31
- package/docs/upgrading.md +4 -1
- package/docs/workspaces.md +26 -6
- package/lib/automations.mjs +3 -4
- package/lib/bounded-read.mjs +18 -0
- package/lib/capability-show.mjs +13 -2
- package/lib/claim.mjs +3 -4
- package/lib/core.mjs +919 -278
- package/lib/errors.mjs +39 -0
- package/lib/harness-trust-write.mjs +119 -40
- package/lib/harness-trust.mjs +31 -18
- package/lib/instance-inspect.mjs +160 -11
- package/lib/instance-lifecycle.mjs +90 -37
- package/lib/packages.mjs +8 -5
- package/lib/pi-bridge.mjs +18 -19
- package/lib/remote.mjs +88 -51
- package/lib/retire-output.mjs +9 -4
- package/lib/schedule.mjs +3 -4
- package/lib/servers.mjs +39 -6
- package/lib/session-viewer.mjs +25 -1
- package/lib/triggers.mjs +3 -4
- package/lib/workspace.mjs +6 -6
- package/lib/worktree.mjs +33 -8
- package/lib/write-through-private-file.mjs +26 -0
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +108 -13
- package/packages/client/cli-locator.mjs +16 -14
- package/packages/client/deployment-panel.mjs +4 -3
- package/packages/client/display-text.mjs +2 -1
- package/packages/client/instance-events-contract.mjs +4 -3
- package/packages/client/instance-lifecycle.mjs +235 -0
- package/packages/client/instance-presentation.mjs +9 -0
- package/packages/client/instance-tree.mjs +10 -8
- package/packages/client/kernel-lines.mjs +3 -3
- package/packages/client/launch-contract.mjs +11 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/lifecycle-cli.mjs +12 -6
- package/packages/client/lifecycle-confirmation.mjs +407 -0
- package/packages/client/lifecycle-contract.mjs +6 -2
- package/packages/client/own-codes.mjs +1 -0
- package/packages/client/panel-views.mjs +39 -2
- package/packages/client/readiness-contract.mjs +2 -2
- package/packages/client/remote-roster.mjs +50 -5
- package/packages/client/roster-sections.mjs +3 -3
- package/packages/client/session-start.mjs +98 -0
- package/packages/client/start-gate.mjs +46 -0
- package/packages/client/start-messages.mjs +17 -0
- package/packages/client/workspace-views.mjs +2 -2
- package/packages/tui/README.md +21 -8
- package/packages/tui/lib/actions.mjs +11 -2
- package/packages/tui/lib/client.mjs +9 -2
- package/packages/tui/lib/config.mjs +39 -9
- package/packages/tui/lib/main.mjs +168 -20
- package/packages/tui/lib/model.mjs +315 -13
- package/packages/tui/lib/open.mjs +45 -0
- package/packages/tui/lib/read.mjs +171 -16
- package/packages/tui/lib/store.mjs +171 -10
- package/packages/tui/lib/term/tty.mjs +71 -12
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +145 -33
- package/packages/tui/lib/views/help.mjs +46 -11
- package/skills/oats-getting-started/SKILL.md +6 -3
package/docs/desktop-cli-api.md
CHANGED
|
@@ -45,7 +45,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
45
45
|
"automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
|
|
46
46
|
"server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
|
|
47
47
|
"lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
|
|
48
|
-
"soul-launch","retire-plan-own-worktree"],
|
|
48
|
+
"soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key"],
|
|
49
49
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
50
50
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
51
51
|
"capabilityShowApi":1}
|
|
@@ -117,6 +117,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
117
117
|
| `automation-descriptions` | a `description` on every trigger and schedule row, local or workspace, by one rule; `oats schedule update <id> --description=<text>` (the description only) and `oats trigger update <id> --description=<text>`; `--description=<text>` on `schedule add` and `trigger add`, OATS 0.43.0 ([Shared row fields](#automations-shared-rows)) | |
|
|
118
118
|
| `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
|
|
119
119
|
| `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
120
|
+
| `soul-skills` | `oats inspect --soul <soul> --skills` and its `souls[].skills`: the soul's own skills, the ones a spawn of it copies, with each file's text ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
120
121
|
| `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
|
|
121
122
|
| `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
|
|
122
123
|
| `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) |
|
|
@@ -128,6 +129,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
128
129
|
| `launch-prompt-dev-channel` | the kernel confirms Claude's development-channel prompt whenever it launches Claude with `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`, with no consent setting; `launchPromptAnswers` gone from previews; `consentSource` gone from `launch-prompt` events, which carry `claudeVersion`, `claudeVersionSource` and, on a miss, `differed`; `launchPrompts.status: "not-engaged"` and `"flag-ignored"`; `launchPrompts` in a launched spawn's answer; the `launch-prompt` readiness warning, OATS 0.52.0 ([Launch prompt results](#launch-prompt-results)) | |
|
|
129
130
|
| `soul-launch` | `oats soul launch set\|remove`, the writer of `oats-local.yaml` `souls.launch`, and `E_LAUNCH_PREFERENCE_UNKNOWN`, OATS 0.53.0 ([`oats soul launch`](#oats-soul-launch)). Gate on the probe: a kernel without it answers `E_USAGE` | `soulLaunchApi: 1` (payload only) |
|
|
130
131
|
| `retire-plan-own-worktree` | a retire plan carries `facts.ownWorktree`, a boolean: whether `work/` is the instance's own work tree, the one the retire retains or removes; in `oats retire --plan` and in the fresh plan (`details.plan`) of `E_PLAN_STALE` and `E_CHILDREN_RUNNING`; a stop plan does not carry it; OATS 0.53.0 ([the retire plan](#retire)) | |
|
|
132
|
+
| `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
|
|
133
|
+
| `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
|
|
131
134
|
|
|
132
135
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
133
136
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -137,6 +140,33 @@ Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
|
137
140
|
**Gate on the probe, never by trying.** An older kernel can ignore an unknown
|
|
138
141
|
flag and act: without `lifecycle-plans`, `retire --plan` retires.
|
|
139
142
|
|
|
143
|
+
## Text output
|
|
144
|
+
|
|
145
|
+
A command's text (without `--json`) is for a person and is not part of this
|
|
146
|
+
contract. Some of its lines hold text the kernel did not write: a path as the
|
|
147
|
+
system or Git names it, a branch name, a hook's or a host's own words. In the
|
|
148
|
+
lines below, each character a terminal would act on, or that hides or
|
|
149
|
+
reorders text (a control character such as an escape or a newline, a bidi
|
|
150
|
+
override: the set the kernel never prints in text it did not write), is
|
|
151
|
+
spelled `\u{<hex>}` (OATS 0.53.0 for the local retire's warnings, #973; the
|
|
152
|
+
rest 0.56.0, #1006), so that such a name cannot clear the screen, write a
|
|
153
|
+
line of its own or reverse what follows it:
|
|
154
|
+
|
|
155
|
+
- the `note:` lines of `oats retire --plan`, `oats instance stop --plan`,
|
|
156
|
+
`oats instance git` and `oats readiness`;
|
|
157
|
+
- the `WARNING:` lines of `oats spawn` (its preview, and with `--server`
|
|
158
|
+
too), of the `oats session` commands (a start's or a restart's launch-hook
|
|
159
|
+
warnings, on stderr) and of `oats doctor` (a pi bridge's version skew);
|
|
160
|
+
- the lines of `oats retire`, local and with `--server`, for the recovery it
|
|
161
|
+
wrote, for the extra trees it handled and for the receipt's warnings. A
|
|
162
|
+
retire with `--server` prints the receipt's warnings as a local one does.
|
|
163
|
+
|
|
164
|
+
A newline in such a value is spelled too, so the value stays on its line.
|
|
165
|
+
Text that already holds the characters of a spelling (`\u{1b}` written out)
|
|
166
|
+
prints as it is: a spelling is not meant to be read back. Every other line of
|
|
167
|
+
text output prints what it holds as it is. The JSON is never changed by
|
|
168
|
+
this: its strings are what they are.
|
|
169
|
+
|
|
140
170
|
## The envelope and dispatch errors
|
|
141
171
|
|
|
142
172
|
Every `--json` command except those below prints exactly one JSON object on
|
|
@@ -390,7 +420,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
|
|
|
390
420
|
### `oats inspect`
|
|
391
421
|
|
|
392
422
|
```text
|
|
393
|
-
oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions]) [--max-age <s>] --json
|
|
423
|
+
oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills]) [--max-age <s>] --json
|
|
394
424
|
```
|
|
395
425
|
|
|
396
426
|
An instance subject, abridged:
|
|
@@ -475,6 +505,72 @@ travels to the host; a host whose probe does not advertise
|
|
|
475
505
|
`soul-composed-instructions` is refused with `E_REMOTE_INCOMPATIBLE`, and
|
|
476
506
|
nothing is sent.
|
|
477
507
|
|
|
508
|
+
`skills` (feature `soul-skills`) is present only with `--skills`, which takes
|
|
509
|
+
a soul subject (`--home` is `E_BAD_ARGS`) and combines with `--instructions`;
|
|
510
|
+
without the flag the key is absent and no skill file is read. It lists the
|
|
511
|
+
soul's own skills, exactly the ones a spawn of it copies (not its
|
|
512
|
+
capabilities' skills), read from the same soul copy as `instructions`:
|
|
513
|
+
|
|
514
|
+
```json
|
|
515
|
+
"skills":[{"name":"release-checklist","path":"skills/release-checklist","description":"Cutting a release.",
|
|
516
|
+
"files":[{"path":"skills/release-checklist/SKILL.md","bytes":812,"text":"---\nname: release-checklist\n…","binary":false,"truncated":false},
|
|
517
|
+
{"path":"skills/release-checklist/references/notes.md","bytes":2048,"text":null,"binary":false,"truncated":false,"omitted":true}],
|
|
518
|
+
"filesTruncated":false}]
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
- `skills` is the list sorted by `name` in codepoint order; `[]` when the
|
|
522
|
+
soul has no skills of its own (no `skills/` directory, or none with a
|
|
523
|
+
`SKILL.md`); `null` when they could not be listed, with a problem below,
|
|
524
|
+
including a skill directory whose `SKILL.md` could not be examined.
|
|
525
|
+
It is also `null` when the soul's copy failed, and that copy's problem
|
|
526
|
+
explains it.
|
|
527
|
+
- A skill is a child directory of `skills/` holding a regular-file
|
|
528
|
+
`SKILL.md`, or `skills/` itself when it holds one (`name` is then
|
|
529
|
+
`skills`). `path` is POSIX and relative to the soul directory. Its
|
|
530
|
+
`description` is the `SKILL.md` front matter's `description`, by the same
|
|
531
|
+
function as [`oats capabilities show`](#oats-capabilities-show), which reads
|
|
532
|
+
the file up to 4 MiB: `null` when the file is unreadable, a symbolic link,
|
|
533
|
+
binary or over 4 MiB, or has no such string, and cut to 1024 bytes.
|
|
534
|
+
- `files` is every regular file under the skill directory, recursively,
|
|
535
|
+
sorted by `path` in codepoint order, each `path` relative to the soul
|
|
536
|
+
directory. At most 200 are listed; beyond that `filesTruncated` is `true`.
|
|
537
|
+
`files` is `null` (and `filesTruncated` `false`) when the files could not
|
|
538
|
+
be listed: an entry whose name is not a safe path component (`.git` in any
|
|
539
|
+
case, a backslash, a control character), or a listed file that cannot be
|
|
540
|
+
read safely (unreadable, gone, changed type, or refused as below). Could
|
|
541
|
+
not list never reads as listed nothing.
|
|
542
|
+
- A file is `{path, bytes, text, binary, truncated}`, by `oats capabilities
|
|
543
|
+
show`'s rules: `bytes` is its real size; `binary` (a NUL or invalid UTF-8
|
|
544
|
+
in its first 262,147 bytes) has `text: null` and `truncated: false`;
|
|
545
|
+
otherwise `text` is at most 262,144 bytes, cut on a code point boundary,
|
|
546
|
+
and `truncated` says it was cut.
|
|
547
|
+
- The whole field carries at most 1 MiB (1,048,576 bytes) of `text`, as
|
|
548
|
+
UTF-8, summed over its files in answer order. The file whose text would
|
|
549
|
+
pass that, and every file after it, has `text: null, binary: false,
|
|
550
|
+
truncated: false, omitted: true`; no other file has `omitted`, and a binary
|
|
551
|
+
file costs nothing. So `text` is `null` only with `binary: true` or
|
|
552
|
+
`omitted: true`.
|
|
553
|
+
- No symbolic link is followed. A symlinked file or directory inside a skill
|
|
554
|
+
is not listed, a symlinked skill directory is not a skill, and a symlinked
|
|
555
|
+
`skills/` makes `skills` `null` with a problem. FIFOs, sockets and devices
|
|
556
|
+
are not listed and never opened. A directory is listed, and a file read,
|
|
557
|
+
only once its real path lies inside its skill's, and the skill's inside the
|
|
558
|
+
soul's; one that does not makes the skill's `files` `null`. A file is
|
|
559
|
+
opened without following a symbolic link and must be the regular file the
|
|
560
|
+
listing found. One race remains: a parent directory swapped for a symbolic
|
|
561
|
+
link in the instant between that check and the open can redirect a read.
|
|
562
|
+
Only someone who can write the deployment's `agents/` tree can do that, and
|
|
563
|
+
they already control the soul copy and every instance's `AGENTS.md`.
|
|
564
|
+
- Problems are `{code, message}` in `problems[]`, each message starting
|
|
565
|
+
`skills: `: `soul-skills-unreadable` when the list is `null`, and
|
|
566
|
+
`soul-skill-files-unreadable`, naming the skill's `path`, for a skill whose
|
|
567
|
+
`files` is `null`.
|
|
568
|
+
|
|
569
|
+
Routed with `--server <id>`, `--skills` travels to the host; a host whose
|
|
570
|
+
probe does not advertise `soul-skills` is refused with `E_REMOTE_INCOMPATIBLE`,
|
|
571
|
+
and nothing is sent. Every text is untrusted repository content: render it as
|
|
572
|
+
plain text or through a sanitising renderer.
|
|
573
|
+
|
|
478
574
|
**Layers.** `id` is the capability filling the slot or `null`. `from`
|
|
479
575
|
(feature `layers-from`) is `"soul"` or `"workspace"`, `null` for an empty slot
|
|
480
576
|
or a home spawned before it was recorded.
|
|
@@ -507,10 +603,9 @@ message}`.
|
|
|
507
603
|
|
|
508
604
|
A soul whose resolution is refused is an inspect error with the resolver's
|
|
509
605
|
code and details (`E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY`,
|
|
510
|
-
`E_CAPABILITY_MISSING`, `E_LOCK_SCHEMA`, `
|
|
511
|
-
`
|
|
512
|
-
|
|
513
|
-
as an item. Soul lookup errors are those of [spawn](#spawn-errors).
|
|
606
|
+
`E_CAPABILITY_MISSING`, `E_LOCK_SCHEMA`, `E_TEAM_UNKNOWN`, and
|
|
607
|
+
`E_WORKSPACE_SCHEMA` reason `local-teams-closed`); readiness reports the same
|
|
608
|
+
condition as an item. Soul lookup errors are those of [spawn](#spawn-errors).
|
|
514
609
|
|
|
515
610
|
<a id="oats-readiness---home-----soul----dir----policy---json--readinessapi-2"></a>
|
|
516
611
|
### `oats readiness`
|
|
@@ -2353,6 +2448,16 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2353
2448
|
<a id="spawn-errors"></a>
|
|
2354
2449
|
### Spawn errors
|
|
2355
2450
|
|
|
2451
|
+
A spawn answers the kernel's own code, as raised, whatever stage raised it
|
|
2452
|
+
(feature `spawn-kernel-codes`, OATS 0.56.0). Beyond the codes below that is
|
|
2453
|
+
any code of the kernel a spawn reaches: the deployment's files, where the home
|
|
2454
|
+
may be, the composition written into the home, reading a package or member at
|
|
2455
|
+
its commit, the harness's packages, the session, and the work and what a
|
|
2456
|
+
failed spawn leaves. **A code says nothing about how far the spawn got:**
|
|
2457
|
+
`details.unconfirmed` does. `E_SPAWN_FAILED` is for an error with no kernel
|
|
2458
|
+
code; a kernel without `spawn-kernel-codes` answers it for most codes its
|
|
2459
|
+
kernel stage raised as well.
|
|
2460
|
+
|
|
2356
2461
|
| Code | Details | When |
|
|
2357
2462
|
|---|---|---|
|
|
2358
2463
|
| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul |
|
|
@@ -2368,7 +2473,6 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2368
2473
|
| `E_SLOT_CONFLICT`, `E_SKILL_DUPLICATE` | | the composition conflicts |
|
|
2369
2474
|
| `E_WORKSPACE_SCHEMA` | `{path, key, reason}` | a removed key or invalid payload |
|
|
2370
2475
|
| `E_CLONE_MISSING`, `E_CLONE_MISMATCH` | | the member's clone is missing or wrong |
|
|
2371
|
-
| `E_REQUIREMENT_INACTIVE` | `{soul, capabilities, context, remedy}` | a declared requirement is not active |
|
|
2372
2476
|
| `E_CHILD_SPAWNS_DISABLED` | `{parent, policy}` | the parent's policy is off |
|
|
2373
2477
|
| `E_PARENT_NOT_FOUND`, `E_RELATIVE_NOT_FOUND` | | the anchor name matches no instance |
|
|
2374
2478
|
| `E_RELATIVE_AMBIGUOUS` | | the anchor matches several instances (`--relative-root` picks one) or a same-named instance would shadow the edge |
|
|
@@ -2378,12 +2482,16 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2378
2482
|
| `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
|
|
2379
2483
|
| `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}`; retained launch-prompt outcomes additionally carry `{retained: true, target, parentLineageCommitted, launchPrompts}` | See [launch prompt results](#launch-prompt-results). |
|
|
2380
2484
|
| `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
|
|
2485
|
+
| `E_HARNESS_UNAVAILABLE` | `{harness, from, at, fix}` | the chosen harness has no executable on this machine ([launch preferences](#soul-launch-preferences-feature-launch-preference-oats-0300)) |
|
|
2486
|
+
| `E_CLAUDE_CONFIG_REMOVED` | `{file, executable, fix}` | a new claude launch with an `oats-claude-config` in reach ([configuration.md](configuration.md)) |
|
|
2487
|
+
| `E_HARNESS_RESOURCE_MISSING` | | a harness package a capability requires for the selected harness is not installed, disabled, or cannot be verified ([capabilities.md](capabilities.md)); raised before any home exists, at a preview too, and again by an apply after the home, the work and the hooks when the pane it got differs from the one it checked in a name the probe reads, or selects another program (another creator started the OATS tmux server): then the spawn is rolled back, with `details.unconfirmed` when that cannot finish. A start, a restart and a launch plan's `harness-packages` check answer the same code |
|
|
2381
2488
|
| `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
|
|
2382
2489
|
| `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
|
|
2383
2490
|
| `E_INTERRUPTED` | `{signal, hooks}` | SIGINT, SIGTERM or SIGHUP while the spawn's `worktree` hooks ran (feature `worktree-event`): the running hook's process group is ended, the spawn is rolled back as for a required hook failure, and the process exits 128 + the signal number |
|
|
2384
2491
|
| `E_REQUIRED_HOOK_FAILED` | `{hooks}`, plus `unconfirmed: true` when compensation cannot finish | a required `spawn` or `worktree` hook failed or timed out; the spawn is rolled back. `hooks` holds the receipt of the event that failed: one entry per hook that ran, `{capability, ok, required, log, exitCode?, signal?, timedOut?, contract?}`, paths only. `log` is `null` for a spawn hook (it keeps no log) and once the rollback removed the home; a retained home keeps a `worktree` hook's log path. Never `home`. Before 0.49.0 a required spawn hook's failure answered `E_SPAWN_FAILED` |
|
|
2385
2492
|
| `E_HOOK_ENVIRONMENT_CONTRACT` | the same as `E_REQUIRED_HOOK_FAILED`, the failed entry with `contract: "environment"` | a `spawn` hook answered an `env` its manifest does not allow, or a `worktree` hook answered `env` at all |
|
|
2386
|
-
| `
|
|
2493
|
+
| `E_RUNTIME_ENDPOINT_UNKNOWN` | | the session cannot be established: the OATS tmux server cannot be read at an apply (before any effect, or after the home, the work and the hooks), or the pane's `PATH`, `HOME` or harness folder cannot be read for the harness package check ([the checks read the pane](execution-targets.md#the-checks-read-the-pane)), before anything is probed or created, or at the apply's second check after the hooks, as for `E_HARNESS_RESOURCE_MISSING`. Once the home exists the spawn is rolled back, with `details.unconfirmed` when that cannot finish. A start and a restart answer the same code |
|
|
2494
|
+
| `E_SPAWN_FAILED` | `{unconfirmed: true}` when compensation cannot finish; `cause` for an error with a system code, or a defect | an error with no kernel code |
|
|
2387
2495
|
|
|
2388
2496
|
Spawn failure envelopes carry `error.details.unconfirmed: true` when an existing
|
|
2389
2497
|
keyed spawn is incomplete (`E_SPAWN_INCOMPLETE`) or compensation cannot confirm
|
|
@@ -2434,7 +2542,11 @@ what could not be printed is dropped. Its result:
|
|
|
2434
2542
|
|
|
2435
2543
|
`remove` answers `{purpose, path, removed: true, rolledBack, branch,
|
|
2436
2544
|
branchKept, branchKeptReason?, warnings?}`. After removing a `ready` tree,
|
|
2437
|
-
`rolledBack` is `false` and `branchKept` is `true`. When
|
|
2545
|
+
`rolledBack` is `false` and `branchKept` is `true`. When an instance whose
|
|
2546
|
+
session is stopped was [attached](souls-and-instances.md#extra-trees) to the
|
|
2547
|
+
removed tree, `warnings` carries one string for it: `<instance>: its work
|
|
2548
|
+
was <tree>, which was removed; its work link <home>/work now points at a
|
|
2549
|
+
path that is gone`. With no attached instance the answer is what it was. When it completed an
|
|
2438
2550
|
interrupted add's rollback, `rolledBack` is `true` and `branchKept` says
|
|
2439
2551
|
whether the branch still exists. The rollback deletes the branch only when
|
|
2440
2552
|
that add created it, no worktree has it checked out, and it still points at
|
|
@@ -2546,6 +2658,7 @@ A failed `add` reports the same facts about its rollback in `details`:
|
|
|
2546
2658
|
| `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`) |
|
|
2547
2659
|
| `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
|
|
2548
2660
|
| `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 |
|
|
2661
|
+
| `E_CHILDREN_RUNNING` | `remove`: an instance attached to the tree has a session that is running, or that cannot be read. Answered under the purpose's claim, before Git is asked anything: nothing is removed and the record is kept. `details: {purpose, path, children: [{instance, home, session}]}`, `session` being `"running"` or `"unknown"`; only the instances that refuse are listed. The message names each one and what was seen, and the step: `oats instance stop <instance>`, or retire it, then remove again. No flag removes anyway. It is the code [a retire](#retire-children-running) answers, with other `details`: a retire answers it for a child it asked to stop and that did not; `remove` for an attached instance it found running or unread, and it asks nobody to stop, so there is no `childrenStopped` |
|
|
2549
2662
|
| `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or the tree is still there; the record is kept |
|
|
2550
2663
|
| `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) |
|
|
2551
2664
|
|
|
@@ -2798,7 +2911,7 @@ messaging identity's `address` (else `alias`), or `null`.
|
|
|
2798
2911
|
### The remote roster (`oats server roster --json`)
|
|
2799
2912
|
|
|
2800
2913
|
```text
|
|
2801
|
-
oats server roster [--server <id>] [--per-target <ms>] [--budget <ms>] --json
|
|
2914
|
+
oats server roster [--server <id>] [--workspace-key <key>]... [--per-target <ms>] [--budget <ms>] --json
|
|
2802
2915
|
```
|
|
2803
2916
|
|
|
2804
2917
|
An envelope; `result` is `{groups, bounds}` (remote `roster`,
|
|
@@ -2883,7 +2996,9 @@ route target:
|
|
|
2883
2996
|
name is unique on the host ([addressing](servers.md#run-there); a shared
|
|
2884
2997
|
name is `E_AMBIGUOUS` with `error.details.candidates: [{agent, home}]`). A
|
|
2885
2998
|
saved-route row the host did not list is addressable only while the host's
|
|
2886
|
-
answer is unknown (`missingRemotely: false`).
|
|
2999
|
+
answer is unknown (`missingRemotely: false`). A row the host was reached
|
|
3000
|
+
for and did not list (`missingRemotely: true`) is the one
|
|
3001
|
+
[`server forget`](#forget-a-saved-route-oats-server-forget---json) is for.
|
|
2887
3002
|
- **`savedRoute`**: the instance was spawned from this machine and has a
|
|
2888
3003
|
saved route here. Information only; no action depends on it.
|
|
2889
3004
|
- `running` is `null` when unknown; `backend` is `tmux` for a row with a tmux
|
|
@@ -2896,6 +3011,92 @@ route target:
|
|
|
2896
3011
|
group's probe. Before 0.55.0 `bounds` also carried `skipped`, the number of
|
|
2897
3012
|
groups the budget did not reach; it is gone with `E_ROSTER_BUDGET`.
|
|
2898
3013
|
|
|
3014
|
+
<a id="roster-workspace-key"></a>
|
|
3015
|
+
**`--workspace-key <key>`** (feature `roster-workspace-key`, OATS 0.56.0,
|
|
3016
|
+
#1124) narrows the roster to the groups that can belong to the given
|
|
3017
|
+
workspaces, so a host registered for another workspace, switched off or not,
|
|
3018
|
+
costs a window nothing. The flag is repeatable and every occurrence counts;
|
|
3019
|
+
`--workspace-key=<key>`, one argument per key, is the same (`--workspace-key=`
|
|
3020
|
+
and a value that starts with `--` are `E_BAD_ARGS`).
|
|
3021
|
+
With one or more keys, a group is probed and returned when:
|
|
3022
|
+
|
|
3023
|
+
1. its registration's `workspaceKey` is one of the keys;
|
|
3024
|
+
2. its registration's `workspaceKey` is not known (absent; `oats server
|
|
3025
|
+
check <id>` learns it);
|
|
3026
|
+
3. it has no registration for its target (`registrationPresent: false`:
|
|
3027
|
+
saved routes only, the registration removed or changed to another
|
|
3028
|
+
target). Its workspace is unknown, so it is always probed: it holds the
|
|
3029
|
+
rows the Desktop offers Forget on (#1131), which no window's filter may
|
|
3030
|
+
hide.
|
|
3031
|
+
|
|
3032
|
+
A group whose registration names another workspace is neither probed nor
|
|
3033
|
+
returned, its saved routes under that registration and target with it. A
|
|
3034
|
+
group is judged by its registration when it has one, so a saved route whose
|
|
3035
|
+
target differs from the registration's is a group of its own, kind 3. A key
|
|
3036
|
+
is compared with the registration's `workspaceKey` by exact string equality:
|
|
3037
|
+
it is the canonical key a host's `status --json` reports as `workspace.key`,
|
|
3038
|
+
never parsed as a repository reference. An empty or missing value, or one
|
|
3039
|
+
with whitespace or a control character, is `E_BAD_ARGS`. `--server` and
|
|
3040
|
+
`--workspace-key` both narrow. Without the flag the answer is exactly as
|
|
3041
|
+
above. With it the answer's shape is unchanged (no filter is echoed in it);
|
|
3042
|
+
only which groups appear changes, and a key that matches nothing leaves the
|
|
3043
|
+
kinds 2 and 3. In text mode, keys that leave no group print `no remote groups
|
|
3044
|
+
for the given workspace keys`.
|
|
3045
|
+
|
|
3046
|
+
The Desktop reads one roster for all its windows: it passes the workspace key
|
|
3047
|
+
of every open window's view in one read, member-derived keys included (a
|
|
3048
|
+
registration records the key its host reports, whatever its `keyFrom`). A key
|
|
3049
|
+
that is `null`, or one the kernel would refuse, is no registration's: a view
|
|
3050
|
+
without a usable key adds none. The read is unfiltered when the Desktop has no
|
|
3051
|
+
window set or no roster answer yet, when a window shows the switcher, when a
|
|
3052
|
+
view without a usable key holds another machine's deployment (whose
|
|
3053
|
+
registration cannot then be named), and when no key is usable.
|
|
3054
|
+
|
|
3055
|
+
<a id="forget-a-saved-route-oats-server-forget---json"></a>
|
|
3056
|
+
### Forget a saved route (`oats server forget --json`)
|
|
3057
|
+
|
|
3058
|
+
```text
|
|
3059
|
+
oats server forget <server> --instance <instance> --json
|
|
3060
|
+
```
|
|
3061
|
+
|
|
3062
|
+
It removes this computer's saved route to `<instance>` through `<server>`,
|
|
3063
|
+
the file under `$OATS_HOME_DIR/remote/<server>/`, and nothing else. It runs
|
|
3064
|
+
nothing on the host and does not contact it: the home there, if it still
|
|
3065
|
+
exists, is untouched ([servers.md](servers.md#what-this-machine-keeps)). It
|
|
3066
|
+
shipped in 0.22.3 with the roster's `missingRemotely`, so every kernel that
|
|
3067
|
+
reports a gone row answers it; there is no feature name.
|
|
3068
|
+
|
|
3069
|
+
An envelope; `result` is:
|
|
3070
|
+
|
|
3071
|
+
```json
|
|
3072
|
+
{"server":"build","instance":"dev-a","home":"/srv/team/agents/dev/instances/dev-a",
|
|
3073
|
+
"target":{"sshHost":"build-host","workspace":"/srv/team","oatsPath":"oats"},"forgotten":true}
|
|
3074
|
+
```
|
|
3075
|
+
|
|
3076
|
+
- **`server`** and **`instance`**: the arguments, echoed.
|
|
3077
|
+
- **`home`**: the instance's home on the host, as the route recorded it.
|
|
3078
|
+
- **`target`**: the route's target (`{sshHost, workspace, oatsPath, …}`) as
|
|
3079
|
+
the route file recorded it, less the `herdrPath` a route written before
|
|
3080
|
+
0.31.0 may hold.
|
|
3081
|
+
- **`forgotten`**: always `true` on success.
|
|
3082
|
+
|
|
3083
|
+
A refusal is `ok: false` with `error: {code, message}` only (no `details`,
|
|
3084
|
+
no `fix`), exit 1, and removes nothing:
|
|
3085
|
+
|
|
3086
|
+
- `E_USAGE`: no server id, or no `--instance` value.
|
|
3087
|
+
- `E_SERVER_INVALID`: the server id is not `^[a-z0-9][a-z0-9-]{0,63}$`.
|
|
3088
|
+
- `E_BAD_ARGS`: the instance name is not `^[a-z0-9][a-z0-9-]*$`.
|
|
3089
|
+
- `E_SNAPSHOT_UNKNOWN`: this computer has no saved route for that instance
|
|
3090
|
+
through that server id (a second forget of the same row answers this).
|
|
3091
|
+
- `E_SNAPSHOT_UNREADABLE`: the route file is not valid JSON; the file is
|
|
3092
|
+
kept.
|
|
3093
|
+
|
|
3094
|
+
The Desktop runs it only for a remote roster row with `missingRemotely:
|
|
3095
|
+
true`, after a confirmation, with exactly the row's `server` and `instance`
|
|
3096
|
+
as the arguments. It never shows `home` or `target`, and it reads the remote
|
|
3097
|
+
roster again after every outcome, a refusal and an unknown one included,
|
|
3098
|
+
instead of editing the row.
|
|
3099
|
+
|
|
2899
3100
|
<a id="servers-per-workspace"></a>
|
|
2900
3101
|
### Servers per workspace (feature `servers-per-workspace`)
|
|
2901
3102
|
|
|
@@ -3424,8 +3625,9 @@ that is not an object; OATS 0.52.0) decides only for itself.
|
|
|
3424
3625
|
repair its lineage. Its session may go on running under a parent that was
|
|
3425
3626
|
retired; `oats status` is where it shows.
|
|
3426
3627
|
- A spawn that names such a home as its parent or anchor is refused
|
|
3427
|
-
(`
|
|
3428
|
-
parent's child-spawn policy
|
|
3628
|
+
(`E_UNIDENTIFIED_INSTANCE_HOME`, the same sentence with `nothing was
|
|
3629
|
+
spawned`; `E_SPAWN_FAILED` before 0.56.0): the parent's child-spawn policy
|
|
3630
|
+
and the lineage are in that record.
|
|
3429
3631
|
- `oats session inspect`, `input` and `attach` on that home answer
|
|
3430
3632
|
`E_RUNTIME_ENDPOINT_UNKNOWN`, and `oats instance events` still reads its
|
|
3431
3633
|
logs.
|
|
@@ -4100,13 +4302,78 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4100
4302
|
one Git names for it, <repository>, and does not write it into the
|
|
4101
4303
|
record`. No key of the plan is new.
|
|
4102
4304
|
|
|
4103
|
-
|
|
4104
|
-
|
|
4105
|
-
|
|
4106
|
-
|
|
4107
|
-
|
|
4108
|
-
|
|
4109
|
-
|
|
4305
|
+
<a id="retire-revision-work"></a>**A retire plan's `planRevision` binds
|
|
4306
|
+
everything the plan shows, except the facts that move by themselves**
|
|
4307
|
+
(0.56.0, #1065), which are these:
|
|
4308
|
+
- `at`, the instant of the read;
|
|
4309
|
+
- the counts against the branch's upstream and against the default branch
|
|
4310
|
+
(`facts.work.upstream.ahead` and `.behind`, `facts.work.base.ahead` and
|
|
4311
|
+
`.behind`), and the default branch's name (`facts.work.base.ref`): a
|
|
4312
|
+
fetch by anyone who shares the clone moves the remote's refs, and
|
|
4313
|
+
creates a missing `origin/HEAD`, where that name is read;
|
|
4314
|
+
- a child's session (`facts.children[].session`): a child's process ends
|
|
4315
|
+
when it ends, and a child that will not stop refuses the retire by
|
|
4316
|
+
itself (`E_CHILDREN_RUNNING`).
|
|
4317
|
+
|
|
4318
|
+
Everything else a plan shows is in its revision, in every home:
|
|
4319
|
+
- what the plan reports of the record: its work mode (`facts.workMode`),
|
|
4320
|
+
its repository (`facts.repo`), its branch (`facts.recordedBranch`) and
|
|
4321
|
+
whether it records a launch;
|
|
4322
|
+
- what `work/` is by this reading, with the repository Git names for
|
|
4323
|
+
`work/` wherever it is a registered work tree;
|
|
4324
|
+
- what Git says of `work/`: the commit, the branch and whether `HEAD` is
|
|
4325
|
+
detached, whether that branch is not the one the record names
|
|
4326
|
+
(`facts.work.drift`, as the plan shows it: it comes from a second read
|
|
4327
|
+
of the record, so it is not derived from `facts.recordedBranch`),
|
|
4328
|
+
the counts of changed and untracked files, the branch's upstream by its
|
|
4329
|
+
name (`facts.work.upstream.ref`) and the remote's host and path
|
|
4330
|
+
(`facts.work.remote`); and where Git gives no answer, the reason
|
|
4331
|
+
(`facts.work.reason`);
|
|
4332
|
+
- the session as the plan shows it (`facts.session`, whole: its state,
|
|
4333
|
+
and the `reason` or the `note` of one that is not established), which
|
|
4334
|
+
the record's launch and endpoint decide where the session's receipt
|
|
4335
|
+
does not;
|
|
4336
|
+
- the home's extra trees (`facts.extraWorktrees`, whole);
|
|
4337
|
+
- where a recovery would be written and the declared roots it leaves
|
|
4338
|
+
out, as the spawn's receipt gives them: the roots with their owners,
|
|
4339
|
+
not the note made from them, which is shortened past its budget and
|
|
4340
|
+
then reads alike for two lists of one length. A changed recovery
|
|
4341
|
+
exclusion changes the revision (it did not before 0.56.0);
|
|
4342
|
+
- of other homes: the children as the plan names them (`instance`,
|
|
4343
|
+
`agent`, `home`; a child's agent is the name its soul's file gives),
|
|
4344
|
+
the edges that could not be followed (`facts.ambiguous`, whole) and the
|
|
4345
|
+
instances attached to this home's `work/` and to each of its extra
|
|
4346
|
+
trees, the recorded children and those of a name that is not unique
|
|
4347
|
+
alike: the plan's notes name them (#964).
|
|
4348
|
+
|
|
4349
|
+
A key that is derived is bound through what it is derived from:
|
|
4350
|
+
`facts.ownWorktree` and `defaults.retainWorktree` (the reading), and
|
|
4351
|
+
every note and every line of the plan's text.
|
|
4352
|
+
`lifecycleApi`, `action`, `facts.pullRequest` and the defaults
|
|
4353
|
+
`deleteBranch`, `stopChildren` and `retainChildren` have one value in
|
|
4354
|
+
every plan of a kernel.
|
|
4355
|
+
|
|
4356
|
+
So two plans of one home that differ in anything else they show never
|
|
4357
|
+
share a revision, and a guarded apply after one of those things moved (a
|
|
4358
|
+
record's work mode, repository or branch that was rewritten, a receipt
|
|
4359
|
+
that is gone, an own tree that became a directory of the home, a
|
|
4360
|
+
directory of the home that became a work tree of another repository, a
|
|
4361
|
+
file where nothing was at `work/`, a receipt that declares another root)
|
|
4362
|
+
is refused with `E_PLAN_STALE` and the fresh plan, before anything runs.
|
|
4363
|
+
Two reads of a home that nobody touched give one revision.
|
|
4364
|
+
|
|
4365
|
+
Before 0.56.0 the revision held of the record its launch alone, of the
|
|
4366
|
+
session its state alone, and the reading only where its answer was not
|
|
4367
|
+
the one the record's work mode alone gives, or where the retire took the
|
|
4368
|
+
repository from Git because the record named none (0.53.0): a record
|
|
4369
|
+
rewritten between a plan and its apply could leave the plan's revision
|
|
4370
|
+
as it was.
|
|
4371
|
+
**Every retire plan read under an older kernel is stale under this one,
|
|
4372
|
+
once:** its apply is refused with `E_PLAN_STALE` and the fresh plan, and
|
|
4373
|
+
the person confirms again. A repeated apply with the idempotency key of a
|
|
4374
|
+
retire that did run is answered from its stored receipt as before,
|
|
4375
|
+
whatever revision it carries: the receipt is looked for before any plan
|
|
4376
|
+
is read.
|
|
4110
4377
|
- A link at `work/` is never the instance's own tree: the retire removes
|
|
4111
4378
|
the link with the home and does not touch what it leads to, whatever the
|
|
4112
4379
|
record says (0.53.0, #973). The record is a file the instance can write;
|
|
@@ -4142,13 +4409,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4142
4409
|
stored in the link; nothing acts on it. When the link does not resolve,
|
|
4143
4410
|
the string ends `and it led nowhere that could be read`. The receipt holds
|
|
4144
4411
|
the path as the system gave it. The retire's text (without `--json`)
|
|
4145
|
-
prints every warning of the receipt on one line
|
|
4146
|
-
|
|
4147
|
-
|
|
4148
|
-
kernel never prints in text it did not write), as `\u{<hex>}`, so that a
|
|
4149
|
-
name cannot clear the screen or write a line of its own. The JSON is not
|
|
4150
|
-
changed by that: its strings are what they were. No key of the plan or of
|
|
4151
|
-
the receipt is new.
|
|
4412
|
+
prints every warning of the receipt on one line, spelled as
|
|
4413
|
+
[Text output](#text-output) says. The JSON is not changed by that: its
|
|
4414
|
+
strings are what they were. No key of the plan or of the receipt is new.
|
|
4152
4415
|
- A link at `work/` that is no longer a link when the retire inspects the
|
|
4153
4416
|
home again (a retire hook, or anything else, put a directory or a file in
|
|
4154
4417
|
its place) refuses with `E_WORK_INSPECTION_FAILED` and keeps the home, in
|
|
@@ -4211,7 +4474,7 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4211
4474
|
case. Read an unknown `state` as not idle.
|
|
4212
4475
|
- `notes` says what a retire would copy to recovery (0.42), in up to two
|
|
4213
4476
|
strings read from the home's retirement baseline and the work mode, without
|
|
4214
|
-
hashing
|
|
4477
|
+
hashing a file of the home:
|
|
4215
4478
|
|
|
4216
4479
|
```text
|
|
4217
4480
|
recovery: the home is copied to /w/agents/dev/instances/.oats-retirement/recovery before the home is removed, when it changed since spawn; not copied: .aw, .aweb-identity, .aweb-identity-*, .oats-aweb (oats.aweb)
|
|
@@ -4233,7 +4496,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4233
4496
|
The second is the line above in worktree mode, `recovery: work/ is copied
|
|
4234
4497
|
there when it is not empty` in directory mode, and absent in checkout,
|
|
4235
4498
|
attached and workspace modes. They are strings in `notes`: no other key
|
|
4236
|
-
changes
|
|
4499
|
+
changes. From 0.56.0 the declared roots are part of `planRevision`, as
|
|
4500
|
+
the baseline gives them and not as the note says them (#1065,
|
|
4501
|
+
[the plan's revision](#retire-revision-work)); before it they were not.
|
|
4237
4502
|
- `facts.extraWorktrees` (0.42.1) lists the instance's
|
|
4238
4503
|
[extra trees](souls-and-instances.md#extra-trees-at-retire): linked
|
|
4239
4504
|
worktrees at `<home>/.work-*` that Git confirms. It is an array, empty when
|
|
@@ -4280,6 +4545,32 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4280
4545
|
--discard-worktree the worktree is removed and their work link will
|
|
4281
4546
|
dangle`. It holds for either choice; no other key changes. A relink that
|
|
4282
4547
|
fails is a string in the receipt's `warnings`.
|
|
4548
|
+
- The note of an extra tree that recorded children are attached to (their
|
|
4549
|
+
`work` is a link to that tree) names them and says what the retire leaves
|
|
4550
|
+
them with. For a tree that would be removed it ends `; attached child
|
|
4551
|
+
instance(s) <names> use it as their work, and their work link would then
|
|
4552
|
+
point at a path that is gone`; for one that would be re-homed, `; attached
|
|
4553
|
+
child instance(s) <names> use it as their work, and the retire repoints
|
|
4554
|
+
their work link to it`. A tree the retire refuses is neither moved nor
|
|
4555
|
+
removed, and its note says nothing of them. Names too long for the note
|
|
4556
|
+
give way to `<n> of the recorded children`. They are strings in `notes`: no
|
|
4557
|
+
key changes. Who is attached to each tree is part of `planRevision`
|
|
4558
|
+
([what the revision binds](#retire-revision-work)).
|
|
4559
|
+
- The retire does not act on an instance listed under `ambiguous`, and one
|
|
4560
|
+
that is attached to a tree of this home is named with what that leaves it
|
|
4561
|
+
with. An extra tree's note gains a clause of its own, after the one for
|
|
4562
|
+
the recorded children: `; attached instance(s) <names>, listed under
|
|
4563
|
+
ambiguous, use it as their work: the retire does not stop them, and their
|
|
4564
|
+
work link would then point at a path that is gone` for a tree that would
|
|
4565
|
+
be removed, and `…: the retire neither stops them nor repoints their work
|
|
4566
|
+
link, which would then point at a path that is gone (the tree would be at
|
|
4567
|
+
<movedTo>)` for one that would be re-homed. For `work/` it is a note of
|
|
4568
|
+
its own, in a worktree-mode plan: `attached instance(s) <names>, listed
|
|
4569
|
+
under ambiguous, use this home's work/ as their work: the retire neither
|
|
4570
|
+
stops them nor repoints their work link, which will then point at a path
|
|
4571
|
+
that is gone, whether the worktree is retained (the receipt names where)
|
|
4572
|
+
or removed with --discard-worktree`. The note for the recorded children
|
|
4573
|
+
above is unchanged.
|
|
4283
4574
|
- `facts.recordedBranch` is `null` where the home records the word `"HEAD"`
|
|
4284
4575
|
(a detached checkout or attached spawn before 0.49.0, #641): it is not a
|
|
4285
4576
|
branch name, so `facts.work.drift` is `false` for it as well.
|
|
@@ -4390,6 +4681,29 @@ A first retire prints the **raw receipt**, not an envelope:
|
|
|
4390
4681
|
removed unplanned (OATS 0.52.0; it was `E_PLAN_STALE`, a code that says
|
|
4391
4682
|
nothing happened, answered after the hooks: #895).
|
|
4392
4683
|
The key is additive.
|
|
4684
|
+
- `warnings` also says what the retire left the attached children of a tree
|
|
4685
|
+
it moved or removed with, one string per child, for `work/` and for each
|
|
4686
|
+
extra tree. A child that could not be repointed to a retained tree:
|
|
4687
|
+
`<child>: its work link could not be repointed to the retained worktree
|
|
4688
|
+
<movedTo> (<why>) and still points at <link>; repoint it by hand: ln -sfn
|
|
4689
|
+
…`, or `<child>: its attachment changed during the retire, so its work was
|
|
4690
|
+
left as it is now and not repointed to the retained worktree <movedTo>;
|
|
4691
|
+
inspect <home>/work`. A child of a tree the retire removed (a clean extra
|
|
4692
|
+
tree, or `work/` with `--discard-worktree`): `<child>: its work was
|
|
4693
|
+
<tree>, which this retire removed (<why>); its work link <home>/work now
|
|
4694
|
+
points at a path that is gone`. A child that was repointed has no string:
|
|
4695
|
+
the text summary's `child <name>` line says where its work now links. No
|
|
4696
|
+
key is new.
|
|
4697
|
+
|
|
4698
|
+
An attached instance the plan lists under `ambiguous` is not stopped and
|
|
4699
|
+
not repointed, and has a string for each tree that was moved or removed:
|
|
4700
|
+
the sentence above for a removed tree, followed by ` (it records this
|
|
4701
|
+
instance as its parent under a name that is not unique, so the retire did
|
|
4702
|
+
not stop it)`, or, for a re-homed tree, `<instance>: its work was <tree>,
|
|
4703
|
+
which this retire re-homed to <movedTo>; its work link <home>/work was not
|
|
4704
|
+
repointed and now points at a path that is gone (it records … did not stop
|
|
4705
|
+
it); to repoint it by hand: ln -sfn …`. A `--self` retirement's receipt
|
|
4706
|
+
does not carry these strings.
|
|
4393
4707
|
- `workRecovery`: `{path, classes, bytes, home, outputs?, repoCopy?,
|
|
4394
4708
|
notCopied?, afterHooks?}`, present when a recovery was written. One retire
|
|
4395
4709
|
writes at most one recovery directory, and `path` is that directory.
|
|
@@ -4478,7 +4792,7 @@ nothing is established. A plain or
|
|
|
4478
4792
|
always does (`[]` when there are none). One child still running after the
|
|
4479
4793
|
grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
|
|
4480
4794
|
`E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY`, …), refuses everything: nothing is retired, exit 1,
|
|
4481
|
-
|
|
4795
|
+
<a id="retire-children-running"></a>`E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
|
|
4482
4796
|
`code`, always a [kernel code](#kernel-codes); the message says `still running after a bounded stop`
|
|
4483
4797
|
only of a child whose row lists processes in `stillRunning`, and `<child> could not be stopped
|
|
4484
4798
|
(<code>)` of any other, OATS 0.52.0). **`--force` does not bypass it**: `--force` covers incomplete
|
|
@@ -4898,7 +5212,10 @@ selection flags. See [the start workflow](desktop-instance-start.md).
|
|
|
4898
5212
|
`restart`),
|
|
4899
5213
|
`E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*` (among them
|
|
4900
5214
|
`E_LAUNCH_SHIM`: the home's `oats` link cannot be written, nothing was
|
|
4901
|
-
started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`,
|
|
5215
|
+
started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`,
|
|
5216
|
+
`E_HARNESS_RESOURCE_MISSING` (a harness package an active capability
|
|
5217
|
+
requires is not installed, disabled, or cannot be verified: nothing was
|
|
5218
|
+
started; `E_HARNESS_PACKAGE` before 0.56.0), `E_SESSION_FAILED`
|
|
4902
5219
|
(any error that is not the kernel's; with
|
|
4903
5220
|
[`details.cause`](#kernel-codes) when it has a code of its own or is a
|
|
4904
5221
|
defect, and without it when it is a refusal without a code).
|
|
@@ -4981,7 +5298,11 @@ accept `--server <id>`.
|
|
|
4981
5298
|
launchConfig, launchConfigSource, launchConfigDefault, executable: {path,
|
|
4982
5299
|
declared, resolvedFrom}, argv, environment: [{name, fromEnv} | {name, redacted:
|
|
4983
5300
|
true} | {name, reference: true}], command (redacted), prompt, hooks,
|
|
4984
|
-
preflight: [{check, ok, detail}], ok}`.
|
|
5301
|
+
preflight: [{check, ok, detail, code?}], ok}`. A failed check carries the
|
|
5302
|
+
code a start would refuse with; the `harness-packages` check's is the
|
|
5303
|
+
gate's own, `E_HARNESS_RESOURCE_MISSING` (`E_HARNESS_PACKAGE` before
|
|
5304
|
+
0.56.0). A fault of the gate, which is no verdict on a package, is not a
|
|
5305
|
+
row: the preview fails as a whole.
|
|
4985
5306
|
|
|
4986
5307
|
`launchConfigDefault` (0.32) is `true` when `launchConfig` is this host's
|
|
4987
5308
|
default for the harness rather than a chosen configuration; the spawn preview
|
|
@@ -5454,12 +5775,20 @@ It uses the existing success/error JSON envelope. Result:
|
|
|
5454
5775
|
|
|
5455
5776
|
There is one entry per target file: the ambient file of each selected harness,
|
|
5456
5777
|
then one per launch configuration whose `env` sets `CLAUDE_CONFIG_DIR` or
|
|
5457
|
-
`CODEX_HOME`,
|
|
5458
|
-
|
|
5459
|
-
|
|
5778
|
+
`CODEX_HOME`, or sets `HOME` when its launch has no such variable at all
|
|
5779
|
+
(its default file under that `HOME`), deduplicated by canonical directory. `ambient` says whether the
|
|
5780
|
+
file is the one a launch with no launch configuration reads (by the
|
|
5781
|
+
environment its tmux pane will have, or the operator's own when no OATS tmux
|
|
5782
|
+
server runs, which `warnings` then says:
|
|
5783
|
+
[harness-trust.md](harness-trust.md)); `launchConfigs` names the launch
|
|
5784
|
+
configurations that select it (sorted). A launch configuration whose directory cannot
|
|
5460
5785
|
be resolved (an unset reference, a relative path) or does not exist is a
|
|
5461
5786
|
`refused` entry with a `problem` string naming it; `file` is null when the path
|
|
5462
|
-
is unresolved. The directory is never created.
|
|
5787
|
+
is unresolved. The directory is never created. A file the writer refuses (its
|
|
5788
|
+
type, links, owner, mode bits, `ls` metadata markers, size, encoding or format)
|
|
5789
|
+
is a `refused` entry whose `problem` is the file and the check that refused it,
|
|
5790
|
+
in fixed wording that never includes the file's content; such an entry's
|
|
5791
|
+
`current` and digests do not describe the file's trust.
|
|
5463
5792
|
|
|
5464
5793
|
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.
|
|
5465
5794
|
`current` contains only the known trust scalar, or null when missing. Codex's key
|
|
@@ -5472,7 +5801,16 @@ unverifiable observations). The intent retains the candidate digest. Apply's aud
|
|
|
5472
5801
|
in warnings, without native configuration contents.
|
|
5473
5802
|
|
|
5474
5803
|
Preflight failures, including any entry `problem`, use `E_CONFIG_BROKEN` with the
|
|
5475
|
-
result in details; the message names each problem.
|
|
5804
|
+
result in details; the message names each problem. One case has its own code:
|
|
5805
|
+
when the only refused entries are ambient ones whose file could not be
|
|
5806
|
+
established, because a server runs and the environment of its panes cannot be
|
|
5807
|
+
read, or because tmux could not say whether the server runs (its
|
|
5808
|
+
`list-sessions` refused or cut off; with no tmux on the command's `PATH`
|
|
5809
|
+
no read is made, and the operator's own file is the target, said in
|
|
5810
|
+
`warnings`), the code is `E_RUNTIME_ENDPOINT_UNKNOWN` (`Harness trust targets cannot be
|
|
5811
|
+
established; nothing was written: …`), with the same details: the entry is
|
|
5812
|
+
`refused`, `file` null, with its `problem`. With a refused launch
|
|
5813
|
+
configuration's entry beside it, `E_CONFIG_BROKEN` wins. Apply failures
|
|
5476
5814
|
use `E_HARNESS_TRUST_INCOMPLETE`, details `{...result,reason,mayHaveChanged}`;
|
|
5477
5815
|
reason is the closed set `locked|changed|audit|write|verify`; the message names the
|
|
5478
5816
|
failed files. Partial writes are
|