@awebai/oats 0.52.0 → 0.54.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 +2 -1
- package/bin/oats.mjs +314 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
- package/docs/desktop-cli-api.md +696 -60
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +184 -12
- package/docs/integrations.md +6 -3
- package/docs/knowledge.md +2 -2
- package/docs/macos-test-runs.md +246 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +210 -6
- package/docs/release-notes/v0.53.0.md +1288 -0
- package/docs/release-notes/v0.54.0.md +142 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +239 -16
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +310 -0
- package/docs/workspaces.md +123 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +93 -4
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +569 -121
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +5 -6
- package/lib/instance-lifecycle.mjs +145 -18
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +226 -15
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +18 -5
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +404 -60
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +6 -35
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/workspace.mjs +75 -27
- package/package-catalog.json +4 -4
- package/package.json +2 -1
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/cli-adapter.mjs +16 -3
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-contract.mjs +4 -0
- package/packages/client/deployment-facts.mjs +71 -10
- package/packages/client/deployment-panel.mjs +49 -11
- package/packages/client/deployment-read-cli.mjs +7 -3
- package/packages/client/display-text.mjs +8 -2
- package/packages/client/instance-acts.mjs +46 -10
- package/packages/client/instance-events-contract.mjs +4 -2
- package/packages/client/instance-presentation.mjs +66 -2
- package/packages/client/instance-tree.mjs +23 -14
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-prompt-outcome.mjs +51 -16
- package/packages/client/lifecycle-contract.mjs +45 -4
- package/packages/client/liveness.mjs +14 -1
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/panel-views.mjs +18 -11
- package/packages/client/readiness-contract.mjs +3 -1
- package/packages/client/remote-address.mjs +34 -9
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +92 -6
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-contract.mjs +16 -4
- package/packages/client/spawn-messages.mjs +26 -3
- package/packages/client/spawn-preview-cli.mjs +8 -2
- package/packages/client/spawn-preview-contract.mjs +5 -1
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-views.mjs +39 -3
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +30 -12
- package/packages/tui/lib/actions.mjs +16 -1
- package/packages/tui/lib/client.mjs +32 -1
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +117 -46
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +44 -0
- package/packages/tui/lib/term/screen.mjs +16 -4
- package/packages/tui/lib/term/text.mjs +60 -0
- package/packages/tui/lib/term/tty.mjs +13 -3
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +230 -36
- package/packages/tui/lib/views/help.mjs +125 -13
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/skills/oats-getting-started/SKILL.md +8 -2
package/docs/desktop-cli-api.md
CHANGED
|
@@ -44,7 +44,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
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
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
|
+
"lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
|
|
48
|
+
"soul-launch","retire-plan-own-worktree"],
|
|
48
49
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
49
50
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
50
51
|
"capabilityShowApi":1}
|
|
@@ -125,10 +126,13 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
125
126
|
| `schedule-run-warnings` | a schedule run's record (`lastRun`, `recentRuns[]`) and a trigger fire's record and `lastRun` carry `warnings?`, the launch answer's warnings, when it had some; OATS 0.52.0 ([schedules and triggers](#schedules-and-triggers)) | |
|
|
126
127
|
| `lifecycle-claim-stop` | `oats instance stop --apply` holds the claim of every target (the file one retire of a home at a time is ordered by), so a stop is refused beside a retire in flight (`E_INSTANCE_RETIRING`) or another stop (`E_LIFECYCLE_BUSY`), a retire beside a stop (`E_LIFECYCLE_BUSY`), and `oats worktree add` beside a retire (`E_INSTANCE_RETIRING`), each before any effect ([Commands that meet on one home](#lifecycle-pairs)); a stop that was killed refuses nothing afterwards, and `<home>/.oats-stop-pending.json` is no longer written or read: a client's own handling of a stale stop marker is not needed for a kernel that lists this; `error.details.action` (the holder's verb) on those refusals, and `error.details.holder` on every `E_LIFECYCLE_BUSY` ([`details.holder`](#busy-holder)); the codes a stop and a retire answer only before any effect, as one list ([the list](#before-effect-codes)), with two retire answers that came after an effect given codes outside it (`E_WORK_PRESERVATION_FAILED`, `E_RUNTIME_QUIESCE_FAILED`), OATS 0.52.0. Gate on the probe; routed with `--server`, on the host's list | |
|
|
127
128
|
| `launch-prompt-dev-channel` | the kernel confirms Claude's development-channel prompt whenever it launches Claude with `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`, with no consent setting; `launchPromptAnswers` gone from previews; `consentSource` gone from `launch-prompt` events, which carry `claudeVersion`, `claudeVersionSource` and, on a miss, `differed`; `launchPrompts.status: "not-engaged"` and `"flag-ignored"`; `launchPrompts` in a launched spawn's answer; the `launch-prompt` readiness warning, OATS 0.52.0 ([Launch prompt results](#launch-prompt-results)) | |
|
|
129
|
+
| `soul-launch` | `oats soul launch set\|remove`, the writer of `oats-local.yaml` `souls.launch`, and `E_LAUNCH_PREFERENCE_UNKNOWN`, OATS 0.53.0 ([`oats soul launch`](#oats-soul-launch)). Gate on the probe: a kernel without it answers `E_USAGE` | `soulLaunchApi: 1` (payload only) |
|
|
130
|
+
| `retire-plan-own-worktree` | a retire plan carries `facts.ownWorktree`, a boolean: whether `work/` is the instance's own work tree, the one the retire retains or removes; in `oats retire --plan` and in the fresh plan (`details.plan`) of `E_PLAN_STALE` and `E_CHILDREN_RUNNING`; a stop plan does not carry it; OATS 0.53.0 ([the retire plan](#retire)) | |
|
|
128
131
|
|
|
129
132
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
130
133
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
131
|
-
`soulsApi: 1`, `teamsApi: 1`, `soulTeamsApi: 1`, `triggerApi: 1
|
|
134
|
+
`soulsApi: 1`, `teamsApi: 1`, `soulTeamsApi: 1`, `triggerApi: 1`,
|
|
135
|
+
`soulLaunchApi: 1`.
|
|
132
136
|
|
|
133
137
|
**Gate on the probe, never by trying.** An older kernel can ignore an unknown
|
|
134
138
|
flag and act: without `lifecycle-plans`, `retire --plan` retires.
|
|
@@ -672,6 +676,21 @@ Feature `workspace-v2`, `workspaceApi: 2`. Model: [workspaces.md](workspaces.md)
|
|
|
672
676
|
never prompting: `E_REMOTE_UNREADABLE {url, reason: "auth" | "not-found" |
|
|
673
677
|
"network" | "timeout" | "killed" | "cache" | "unknown"}`. `killed` (the
|
|
674
678
|
system killed git, for example out of memory) also carries `signal`.
|
|
679
|
+
`network` is what Git's own text shows to be the network (a host that does
|
|
680
|
+
not resolve, a connection refused, reset or closed, a transport that could
|
|
681
|
+
not reach the remote). A failure whose text shows nothing the kernel
|
|
682
|
+
recognises is `unknown` (0.53.0; it read `network` before), and its message
|
|
683
|
+
then ends with a last-line diagnostic: `cannot read remote <url> (unknown):
|
|
684
|
+
<line>`. Git's words are shown only under the
|
|
685
|
+
[whole-line disclosure rule](workspaces.md#repository-references-in-diagnostics);
|
|
686
|
+
otherwise `<line>` is the contract's fixed Git notice. Permitted text remains
|
|
687
|
+
one line of at most 300 characters with control characters removed. This
|
|
688
|
+
supersedes the earlier rule that a scrubbed Git line was always shown.
|
|
689
|
+
Only stderr supplies this last-line diagnostic. Empty or whitespace-only
|
|
690
|
+
stderr leaves the message at `(unknown)`, without an error-message fallback;
|
|
691
|
+
an output overflow without a stderr line uses a kernel-owned budget notice. Other diagnostic routes'
|
|
692
|
+
existing error-message fallbacks retain the same original-operation context
|
|
693
|
+
and disclosure rule.
|
|
675
694
|
`cache` (OATS 0.33.0) is local: the
|
|
676
695
|
remote cache on this machine could not be written (a git lock still held,
|
|
677
696
|
another oats process still writing it, or a lock file one left when it
|
|
@@ -682,10 +701,14 @@ Feature `workspace-v2`, `workspaceApi: 2`. Model: [workspaces.md](workspaces.md)
|
|
|
682
701
|
`status` / `workspace status`, the Desktop keeps the `message` (shown as
|
|
683
702
|
given) and only a bounded cause: `details.reason` (matching
|
|
684
703
|
`^[a-z][a-z-]{0,31}$`) and the host of `details.url`. No path, pid, lock,
|
|
685
|
-
`cacheDir` or other detail field crosses to the renderer.
|
|
704
|
+
`cacheDir` or other detail field crosses to the renderer. `details.url` is a
|
|
705
|
+
display value under the [repository diagnostic contract](workspaces.md#repository-references-in-diagnostics),
|
|
706
|
+
so it may withhold the reference and supply no host; it is not a transport URL.
|
|
707
|
+
It keys only on
|
|
686
708
|
`code` + `details.reason`: `cache` words the roster "OATS cache
|
|
687
709
|
problem" with the message in full; `network` / `timeout` read "Couldn't
|
|
688
|
-
reach <host>"; any other reason keeps the generic
|
|
710
|
+
reach <host>"; any other reason, `unknown` among them, keeps the generic
|
|
711
|
+
wording with the message in full. When the
|
|
689
712
|
deployment was observed before, the failed read keeps that observation:
|
|
690
713
|
`/api/panel` serves it with `error` (the message) and `errorCause {code,
|
|
691
714
|
reason, host?}`, and the roster shows it stale instead of empty.
|
|
@@ -918,7 +941,19 @@ oats souls [--dir <d>] [--max-age <s>] --json
|
|
|
918
941
|
Every item of every confirmed member, the external souls, and the locked
|
|
919
942
|
packages' capabilities and souls, sorted by name, then origin. Both carry
|
|
920
943
|
`workspace: {name, key, commit}`, `problems` and, on a standalone view,
|
|
921
|
-
`standalone: true`.
|
|
944
|
+
`standalone: true`. Text mode prints every `problems` row on stdout under
|
|
945
|
+
the table, in the same order as JSON: discovery problems, then unmatched
|
|
946
|
+
`souls.launch` keys for `oats souls`. The line is `! <code>: <message>`,
|
|
947
|
+
preserving the kernel code and message. A row with an owner (`repoKey`,
|
|
948
|
+
`package` or `source`) adds ` [<where>]`: its existing `path`, preceded by
|
|
949
|
+
`repoKey: ` or `package: ` when present. A source-owned row shows its diagnostic
|
|
950
|
+
source display followed by its path; the source uses the shared
|
|
951
|
+
[repository-reference display policy](workspaces.md#repository-references-in-diagnostics)
|
|
952
|
+
and may be withheld as a whole. Operational external sources remain exact. Context uses
|
|
953
|
+
the kernel's terminal text escaping. Ownerless rows, including unmatched
|
|
954
|
+
launch keys, have no bracket. Partial listings still exit 0; JSON success
|
|
955
|
+
semantics and fatal refusals are unchanged. A problem does not necessarily
|
|
956
|
+
mean an item is absent from the table.
|
|
922
957
|
|
|
923
958
|
```json
|
|
924
959
|
{"soulsApi":1,"workspace":{"name":"northwind","key":"github.com/nw/agents","commit":"66566512…"},
|
|
@@ -957,6 +992,15 @@ problem`, (feature `souls-capabilities`) `capabilities`, and (feature
|
|
|
957
992
|
share a bare name share one entry (spawning that name is
|
|
958
993
|
`E_SOUL_AMBIGUOUS`).
|
|
959
994
|
- `launch` is a [Launch](#the-launch-report-launch).
|
|
995
|
+
- **`problems` rows for `souls.launch`** (0.53). `oats souls` adds, after the
|
|
996
|
+
read's own rows, one row per key of `souls.launch` that names no soul:
|
|
997
|
+
`{code: "E_LAUNCH_PREFERENCE_UNMATCHED", path, message, key, value,
|
|
998
|
+
suggestions}`, sorted by key. `path` is where the key is
|
|
999
|
+
(`oats-local.yaml#/souls/launch/<key>`), `key`, `value` and `suggestions`
|
|
1000
|
+
as in the refusal's `details.keys`. `message` is at most 1024 characters
|
|
1001
|
+
and ends with the two commands, in their order. Each soul a spawn would
|
|
1002
|
+
refuse carries the refusal as `launch.problem`: the souls with no entry of
|
|
1003
|
+
their own.
|
|
960
1004
|
- `teams` and `defaultTeam` (feature `team-model-3`) are a
|
|
961
1005
|
[TeamRow](#the-team-row-teamrow) list and a
|
|
962
1006
|
[DefaultTeam](#the-default-defaultteam); both `null` when the soul's teams
|
|
@@ -1440,18 +1484,35 @@ oats teams default <label> [--if-absent | --expect <label>] --json
|
|
|
1440
1484
|
form `--max-age` (on a write form, `--max-age` is the kernel's own
|
|
1441
1485
|
`E_BAD_ARGS`, as for every write verb). `--help` is the kernel's usage
|
|
1442
1486
|
answer, as for every command.
|
|
1487
|
+
- **Rendering** (0.53.0). The file is written without folding lines: a value
|
|
1488
|
+
past 80 columns stays on its line. Before, a write re-wrapped such a line
|
|
1489
|
+
(the same value, over two lines). A file written as JSON (it opens with
|
|
1490
|
+
`{`, and the kernel reads it as strict JSON) is written back as JSON: it
|
|
1491
|
+
keeps the order of its keys and its final newline, or the absence of one,
|
|
1492
|
+
and its indentation becomes two spaces. Before, a write to such a file
|
|
1493
|
+
failed with no answer. A rewrite the kernel could not read back is
|
|
1494
|
+
`E_WORKSPACE_SCHEMA`, and nothing is written.
|
|
1443
1495
|
- A write that would introduce an unknown reference is refused with that
|
|
1444
1496
|
code; an invalid result is `E_WORKSPACE_SCHEMA`.
|
|
1445
1497
|
- **Writes** edit `oats-local.yaml` in place and touch only the entries that
|
|
1446
1498
|
change: comments and styles elsewhere, including inline comments on sibling
|
|
1447
|
-
entries, are kept.
|
|
1448
|
-
|
|
1449
|
-
|
|
1499
|
+
entries, are kept. The file is replaced whole, by a rename, and the new
|
|
1500
|
+
file keeps the permission bits of the old one. An `oats-local.yaml` that
|
|
1501
|
+
is a symbolic link is replaced by a regular file with its target's bits,
|
|
1502
|
+
and the target is not written. Each verb re-reads the file and judges its
|
|
1503
|
+
refusals on it as it is now, and writes only if the file did not change
|
|
1504
|
+
meanwhile (else it redoes the edit on the new content). A file that keeps
|
|
1505
|
+
changing is
|
|
1450
1506
|
`E_LOCAL_CHANGED {path}`; nothing was written. The condition of `--if-absent`
|
|
1451
1507
|
and `--expect` is judged the same way, on the file as it is now and again on
|
|
1452
1508
|
every redo.
|
|
1453
1509
|
- **Concurrency.** Every `add`, `remove` and `default` holds
|
|
1454
1510
|
`<deployment>/.agents/locks/local.lock` for its whole read-compare-write.
|
|
1511
|
+
Every other kernel command that rewrites `oats-local.yaml` holds the same
|
|
1512
|
+
lock and answers the same two codes: [`oats soul launch
|
|
1513
|
+
set|remove`](#oats-soul-launch), [`oats launch-config
|
|
1514
|
+
set|remove`](#launch-configurations) and [`oats schedule|trigger
|
|
1515
|
+
enable|disable`](#schedules-and-triggers) of a workspace item.
|
|
1455
1516
|
Among concurrent `oats teams` writers on one deployment, a conditional write
|
|
1456
1517
|
therefore never overwrites a default another of them set: when two race, the
|
|
1457
1518
|
later one sees the earlier result and refuses with
|
|
@@ -1490,6 +1551,95 @@ oats soul teams <soul>|'*' [--dir <d>] [--max-age <s>] --json
|
|
|
1490
1551
|
oats-workspace.yaml (a PR to the workspace file)"}`, before anything else
|
|
1491
1552
|
is judged.
|
|
1492
1553
|
|
|
1554
|
+
<a id="oats-soul-launch"></a>
|
|
1555
|
+
### `oats soul launch`
|
|
1556
|
+
|
|
1557
|
+
Feature `soul-launch` (OATS 0.53.0). The supported writer of
|
|
1558
|
+
`oats-local.yaml` `souls.launch`, a soul's
|
|
1559
|
+
[launch preference](#launch-preferences) on this machine.
|
|
1560
|
+
|
|
1561
|
+
```text
|
|
1562
|
+
oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <d>] --json
|
|
1563
|
+
oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <d>] --json
|
|
1564
|
+
```
|
|
1565
|
+
|
|
1566
|
+
```json
|
|
1567
|
+
{"soulLaunchApi":1,"action":"set","plan":false,
|
|
1568
|
+
"key":"example.pkg/reviewer","souls":["example.pkg/reviewer"],
|
|
1569
|
+
"level":"/abs/deployment","file":"/abs/deployment/oats-local.yaml",
|
|
1570
|
+
"before":null,"after":"private","changed":true,
|
|
1571
|
+
"launch":{"declared":null,"effective":{"harness":"claude","model":null,"launchConfig":"private"},
|
|
1572
|
+
"from":"local","at":"oats-local.yaml#/souls/launch/example.pkg~1reviewer","problem":null},
|
|
1573
|
+
"unmatched":[],"unread":null}
|
|
1574
|
+
```
|
|
1575
|
+
|
|
1576
|
+
One closed answer for `set`, `remove` and their plans.
|
|
1577
|
+
|
|
1578
|
+
- **`set`** names the soul as a spawn does (`E_SOUL_UNKNOWN`,
|
|
1579
|
+
`E_SOUL_AMBIGUOUS`) and writes the key that soul has: its bare name, or
|
|
1580
|
+
`<package>/<soul>`. `'*'` is the machine default. Exactly one of
|
|
1581
|
+
`--launch-config` and `--harness`; `--model` only with `--harness`
|
|
1582
|
+
(`E_BAD_ARGS`). Each of them is given once and with a value, and the
|
|
1583
|
+
command takes one name: a flag repeated, a flag with no value at any
|
|
1584
|
+
occurrence, and a second name are `E_BAD_ARGS`, on `remove` too.
|
|
1585
|
+
`--launch-config <name>` writes the name (`none` too) and
|
|
1586
|
+
`--harness` the inline `{harness, model?}`. A harness that is not installed
|
|
1587
|
+
is not refused: `launch.problem` says what a spawn would refuse.
|
|
1588
|
+
- **`remove`** tries its argument **first as the exact text of a key in
|
|
1589
|
+
`souls.launch`**, with no read of the workspace; otherwise it names a soul,
|
|
1590
|
+
as for `set`, and removes that soul's key. Removing the last entry removes
|
|
1591
|
+
`souls.launch`, and `souls` when that leaves it empty.
|
|
1592
|
+
- **`--plan`** runs every check and writes nothing. Its answer is the
|
|
1593
|
+
apply's with `plan: true`, and a state that refuses the apply refuses the
|
|
1594
|
+
plan with the same code. It takes no lock, so it never answers
|
|
1595
|
+
`E_LOCAL_BUSY`.
|
|
1596
|
+
- **The read.** Both forms read the workspace live: `--max-age` is refused
|
|
1597
|
+
(`E_BAD_ARGS`) with and without `--plan`, as for every write verb, and the
|
|
1598
|
+
answer never carries `observation`.
|
|
1599
|
+
|
|
1600
|
+
| Field | Meaning |
|
|
1601
|
+
|---|---|
|
|
1602
|
+
| `action` | `"set"` or `"remove"` |
|
|
1603
|
+
| `plan` | `true`: nothing was written |
|
|
1604
|
+
| `key` | the `souls.launch` key written or removed, exactly as in the file; `"*"` for the machine default |
|
|
1605
|
+
| `souls` | the qualified names of the offered souls that key applies to, sorted. More than one when two members offer a soul of that name: the entry pins all of them. `[]` for a key that is the key of no soul; `null` for `"*"` |
|
|
1606
|
+
| `level`, `file` | the deployment and its `oats-local.yaml` |
|
|
1607
|
+
| `before`, `after` | the entry: `null` (none), a string (a launch configuration's name, or `none`), or `{harness, model}` with `model` `null` when it has none |
|
|
1608
|
+
| `changed` | `false` when the file already said it: nothing was written |
|
|
1609
|
+
| `launch` | the [`Launch`](#the-launch-report-launch) report a spawn with no flags would decide for the named soul, with the file as it is after this change (as it would be, under `--plan`). After a `remove` it shows what the soul falls through to. For a key given by its exact text, the soul is the first of `souls`. `null` for `"*"` and for a key that is the key of no soul |
|
|
1610
|
+
| `unmatched` | the keys of `souls.launch` that are the key of no offered soul after this change, sorted by key: `[{key, at, value, suggestions}]`. `at` is `oats-local.yaml#/souls/launch/<key>` (JSON-pointer escaped), `value` the entry as in `before`, `suggestions` at most three offered soul keys: those with the key's bare name (the part after the last `/`) first, then those within two edits of it. `"*"` is never listed, and neither is a key the read could not check (a member unconfirmed, a soul skipped with a problem, a package declared and not locked). `[]`: no key is known to name no soul |
|
|
1611
|
+
| `unread` | `null`, or `{code, message}` when a `remove` by exact text ran although the workspace's souls could not be read |
|
|
1612
|
+
|
|
1613
|
+
- **Read `unread` first.** When it is not `null`, the answer says nothing
|
|
1614
|
+
about souls: `souls`, `launch` and `unmatched` are `null` for that reason
|
|
1615
|
+
and no other. In every other answer `unmatched` is a list, and `souls` and
|
|
1616
|
+
`launch` are `null` only as the table says.
|
|
1617
|
+
- **The write** is the one `oats teams` makes (above): one entry set or
|
|
1618
|
+
deleted in the parsed document, under
|
|
1619
|
+
`<deployment>/.agents/locks/local.lock`, from the file as it is now, redone
|
|
1620
|
+
when the file changed under it. The file is rewritten, and every other
|
|
1621
|
+
entry keeps its value and its comments. Before the rename the rewritten
|
|
1622
|
+
text is validated against the local schema and read back: it must equal
|
|
1623
|
+
the old value everywhere but the one entry.
|
|
1624
|
+
- **Refusals**, all before a byte of the file changes: `E_USAGE` (no `set` or
|
|
1625
|
+
`remove`; a flag the form does not take, `--home` and `--soul` among them,
|
|
1626
|
+
with `details: {flag}`), `E_BAD_ARGS`, `E_LOCAL_MISSING`, `E_SOUL_UNKNOWN`,
|
|
1627
|
+
`E_SOUL_AMBIGUOUS`, `E_LAUNCH_CONFIG_UNKNOWN {name, from, at}` (a
|
|
1628
|
+
`--launch-config` name this file does not declare: the fact a spawn would
|
|
1629
|
+
report, said before the file holds it), `E_LAUNCH_PREFERENCE_UNKNOWN {key,
|
|
1630
|
+
keys}` (a `remove` of an entry the file does not have; `keys` are the
|
|
1631
|
+
entries it has), `E_LOCAL_BUSY {path, lock}`, `E_LOCAL_CHANGED {path}`,
|
|
1632
|
+
`E_WORKSPACE_SCHEMA` (the rewritten file would be invalid, or the kernel
|
|
1633
|
+
would not decode it, `details: {problems}`; or it would not read back as
|
|
1634
|
+
this one edit, `details: {path,
|
|
1635
|
+
reason: "read-back", differs}` with `differs` the JSON pointers that
|
|
1636
|
+
differ, never their values), and whatever the read of the workspace
|
|
1637
|
+
answers when `set`, or a `remove` that names a soul, cannot read the souls.
|
|
1638
|
+
- Text mode says the same in lines: what was set or removed and in which
|
|
1639
|
+
file; the souls the entry applies to, when more than one; what the next
|
|
1640
|
+
spawn of that soul selects; and each key that still names no soul, with
|
|
1641
|
+
the command that removes it.
|
|
1642
|
+
|
|
1493
1643
|
### The messaging provider's teams document
|
|
1494
1644
|
|
|
1495
1645
|
The messaging provider's `teams` operation (`messaging:teams`) is produced by
|
|
@@ -1639,7 +1789,9 @@ Every object shape here is closed.
|
|
|
1639
1789
|
- **The machine** may override it in `oats-local.yaml` `souls.launch`. A key is
|
|
1640
1790
|
a soul key (as for `souls.teams`: `"*"`, a bare soul name, or
|
|
1641
1791
|
`<package>/<soul>`). A value is a `launch-configs` name in the same file, or
|
|
1642
|
-
an inline `{harness, model?}` with the soul's rules.
|
|
1792
|
+
an inline `{harness, model?}` with the soul's rules. From OATS 0.53.0 the
|
|
1793
|
+
key is written by [`oats soul launch set|remove`](#oats-soul-launch)
|
|
1794
|
+
(feature `soul-launch`).
|
|
1643
1795
|
```yaml
|
|
1644
1796
|
souls:
|
|
1645
1797
|
launch:
|
|
@@ -1678,24 +1830,110 @@ a running or existing home until `--reselect-launch` or a respawn.** Readiness
|
|
|
1678
1830
|
shows the drift as `launch-changed`.
|
|
1679
1831
|
|
|
1680
1832
|
**Refusals** (spawn, preview, and a reselecting start):
|
|
1833
|
+
- `E_LAUNCH_PREFERENCE_UNMATCHED {soul, from, at, keys, fix}` (0.53): the
|
|
1834
|
+
launch names none (no `--launch-config`, no `--harness`; `--model` alone
|
|
1835
|
+
names none), its soul has no `souls.launch` entry of its own, and
|
|
1836
|
+
`souls.launch` holds a key that is the key of no soul the workspace offers.
|
|
1837
|
+
The kernel cannot tell which soul that key was meant to pin, so the launch
|
|
1838
|
+
the fall-through would decide is refused. It is checked before the three
|
|
1839
|
+
refusals below, which describe that fall-through launch. Refused: `oats
|
|
1840
|
+
spawn`, preview and apply, with the same code and `details`, and `session
|
|
1841
|
+
start|restart --reselect-launch`, before anything is created, stopped or
|
|
1842
|
+
started. A soul with its own entry, a launch named by a flag, and a plain
|
|
1843
|
+
start or restart go on.
|
|
1844
|
+
- `soul`: the soul key of the launch refused. `from`, `at`: the layer that
|
|
1845
|
+
would have decided it (`"local-default"`, `"soul"` or `"host"`; `at` as
|
|
1846
|
+
in the `Launch` report, `null` for the host).
|
|
1847
|
+
- `keys`: every such key, sorted by key, `[{key, at, value,
|
|
1848
|
+
suggestions}]`, the rows of `unmatched` in
|
|
1849
|
+
[`oats soul launch`](#oats-soul-launch). A client builds the two
|
|
1850
|
+
commands from `key` and `value`; it does not parse the sentence.
|
|
1851
|
+
- `fix`: "pin the soul each key was meant for (oats soul launch set), then
|
|
1852
|
+
remove the key (oats soul launch remove <key>); or name this launch with
|
|
1853
|
+
--launch-config <name> or --harness <h>". The order is `set`, then
|
|
1854
|
+
`remove`: removing first ends the refusal and leaves the soul on the
|
|
1855
|
+
fall-through.
|
|
1856
|
+
- The message names at most three keys, then "and K more", and it and
|
|
1857
|
+
`fix` are at most 1024 characters each, with no line break, whatever the
|
|
1858
|
+
file holds. `keys` is complete.
|
|
1859
|
+
- No text of a launch answer holds a character the kernel never prints (a
|
|
1860
|
+
control character, a line or paragraph separator, a bidi control, an
|
|
1861
|
+
invisible hider, a tag character): a refusal's `message` and `fix`, a
|
|
1862
|
+
report's `problem`, a problems row. The schema of `oats-local.yaml`
|
|
1863
|
+
admits no key with one, so the file brings none. Were one handed to an
|
|
1864
|
+
answer all the same, the sentence names it with each such character
|
|
1865
|
+
replaced by U+FFFD and gives no command for it: it says the key is
|
|
1866
|
+
deleted from `souls.launch` in the file by hand. `keys[].key` is always
|
|
1867
|
+
the exact key.
|
|
1868
|
+
- **Unmatched, or not checked.** A key other than `"*"` matches when an
|
|
1869
|
+
offered soul has that soul key (a soul in `souls.disabled` included).
|
|
1870
|
+
A key that matches nothing is *not checked*, and refuses nothing, when
|
|
1871
|
+
the source that could hold its soul was not read: a bare key while a
|
|
1872
|
+
member is not confirmed or a member's or an external soul was skipped
|
|
1873
|
+
with a problem; `<package>/…` while that package is declared and not
|
|
1874
|
+
locked, or one of its souls was skipped; every key in the standalone
|
|
1875
|
+
view of a workspace whose host cannot be read. What a read did not
|
|
1876
|
+
record, it did not establish: a read that carries no record of what it
|
|
1877
|
+
skipped leaves every key not checked, and a member whose listing carries
|
|
1878
|
+
none counts as one with a soul skipped. Every other key that
|
|
1879
|
+
matches nothing is unmatched, `<member>/<soul>` among them (a member's
|
|
1880
|
+
soul is keyed by its bare name). When the workspace cannot be read at
|
|
1881
|
+
all, the answer is that read's own error. `"*"` is never reported.
|
|
1882
|
+
- **Where else it is said.** `oats souls` and `inspect --soul`: `launch.problem`
|
|
1883
|
+
on each soul a spawn would refuse, and `oats souls` `problems` gains one
|
|
1884
|
+
row per key (below). `oats doctor`, offline, from this machine's cache:
|
|
1885
|
+
`problems[]` gains `{code, key, at, value, suggestions, message,
|
|
1886
|
+
remedy}` per key (text: `! <code>: <message>`, then the remedy), whose
|
|
1887
|
+
message says that it speaks about this machine's last read of the souls
|
|
1888
|
+
and that a spawn reads the workspace itself and is the authority. For a
|
|
1889
|
+
key that read could not check, and when the cache cannot answer, doctor
|
|
1890
|
+
adds an `information[]` line that starts `launch-preference-unchecked:`.
|
|
1891
|
+
The line is information: it changes no exit status and refuses nothing.
|
|
1892
|
+
`inspect --home` `launchCurrent` and readiness `launch-changed` make no
|
|
1893
|
+
read of the workspace and do not carry this problem; the
|
|
1894
|
+
`--reselect-launch` they point to refuses.
|
|
1681
1895
|
- `E_HARNESS_UNAVAILABLE {harness, from, at, fix}`: the chosen harness has no
|
|
1682
1896
|
executable on this machine. There is no fallback to another harness. `fix`
|
|
1683
|
-
|
|
1684
|
-
|
|
1685
|
-
|
|
1686
|
-
|
|
1897
|
+
names the command that pins the soul (0.53), by the layer that chose the
|
|
1898
|
+
harness:
|
|
1899
|
+
- the soul's own `launch:` or the host default: "install <harness>, or pin
|
|
1900
|
+
this soul on this machine (oats soul launch set <soul> --launch-config
|
|
1901
|
+
<name> | --harness <h>)";
|
|
1902
|
+
- the soul's own entry of `souls.launch`: "install <harness>, or pin this
|
|
1903
|
+
soul to another launch (oats soul launch set <soul> --launch-config <name>
|
|
1904
|
+
| --harness <h>)";
|
|
1905
|
+
- `souls.launch."*"`: "install <harness>, name another launch for every soul
|
|
1906
|
+
without an entry (oats soul launch set '*' --launch-config <name> |
|
|
1907
|
+
--harness <h>), or pin this soul to its own (oats soul launch set <soul>
|
|
1908
|
+
--launch-config <name> | --harness <h>)";
|
|
1909
|
+
- a flag: "install <harness>, or choose another --harness / --launch-config".
|
|
1910
|
+
|
|
1911
|
+
The message says why, names the layer's location (`at`) and ends with the
|
|
1912
|
+
`fix`. It stays within 1024 characters: a location too long for that gives
|
|
1913
|
+
way to the layer in words ("the soul's own launch", for example), and
|
|
1914
|
+
`details.at` keeps it.
|
|
1687
1915
|
- `E_LAUNCH_CONFIG_UNKNOWN {name, from, at}`: `souls.launch` names a launch
|
|
1688
|
-
configuration this `oats-local.yaml` does not declare.
|
|
1916
|
+
configuration this `oats-local.yaml` does not declare. As a `Launch`
|
|
1917
|
+
report's `problem`, its `fix` is "declare launch configuration <name> (oats
|
|
1918
|
+
launch-config set), or pin the soul to another (oats soul launch set <soul>
|
|
1919
|
+
--launch-config <name>)"; where `souls.launch."*"` named it, "declare launch
|
|
1920
|
+
configuration <name> (oats launch-config set), name another for every soul
|
|
1921
|
+
without an entry (oats soul launch set '*' --launch-config <name>), or pin
|
|
1922
|
+
the soul to one (oats soul launch set <soul> --launch-config <name>)".
|
|
1689
1923
|
- `E_LAUNCH_CONFIG_AMBIGUOUS {harness, configurations, fix}` (spawn and its
|
|
1690
1924
|
preview only, 0.52): the chosen harness has more than one launch
|
|
1691
1925
|
configuration here (`configurations`, all their names, sorted; the message
|
|
1692
|
-
names the first 10, then "and K more",
|
|
1926
|
+
names the first 10, then "and K more", and fewer where it would otherwise
|
|
1927
|
+
pass 1024 characters),
|
|
1693
1928
|
none is
|
|
1694
1929
|
`default: true`, and the spawn named none. Named means `--launch-config
|
|
1695
1930
|
<name>`, `--launch-config none`, or a `souls.launch` string; an inline or
|
|
1696
1931
|
soul preference and `--harness` alone are not. `fix` is "name one with
|
|
1697
|
-
--launch-config <name
|
|
1698
|
-
|
|
1932
|
+
--launch-config <name>, pin the soul to one (oats soul launch set <soul>
|
|
1933
|
+
--launch-config <name>), or mark one default: true (oats launch-config
|
|
1934
|
+
set)"; where `souls.launch."*"` chose the harness it also says, before the
|
|
1935
|
+
soul's own pin, "name one for every soul without an entry (oats soul launch
|
|
1936
|
+
set '*' --launch-config <name>)". A start or restart of an existing
|
|
1699
1937
|
home, `--reselect-launch` included, is never refused this way.
|
|
1700
1938
|
- `E_WORKSPACE_SCHEMA`: a malformed `launch` or `souls.launch`, path named.
|
|
1701
1939
|
|
|
@@ -1720,10 +1958,18 @@ shows the drift as `launch-changed`.
|
|
|
1720
1958
|
`"oats-local.yaml#/souls/launch/*"`, `"<repoKey>:<path>/soul.yaml#/launch"`,
|
|
1721
1959
|
or `"package:<id>:<path>/soul.yaml#/launch"`.
|
|
1722
1960
|
- `problem`: `null`, or `{code, message, fix}` when a spawn would refuse
|
|
1723
|
-
(`
|
|
1961
|
+
(`E_LAUNCH_PREFERENCE_UNMATCHED`, before any other, with `effective` the
|
|
1962
|
+
launch the fall-through would have given; `E_HARNESS_UNAVAILABLE`,
|
|
1963
|
+
`E_LAUNCH_CONFIG_UNKNOWN`,
|
|
1724
1964
|
`E_LAUNCH_CONFIG_AMBIGUOUS` with `effective.launchConfig` `null`, or
|
|
1725
1965
|
`E_LAUNCH_EXECUTABLE` for a configuration whose own executable is missing). Only reports carry it;
|
|
1726
|
-
spawn and preview refuse instead.
|
|
1966
|
+
spawn and preview refuse instead. A `fix`, here and in a refusal's
|
|
1967
|
+
`details`, is a sentence for a person: its wording may change between
|
|
1968
|
+
releases, so a client shows it and never parses it. A report states a
|
|
1969
|
+
condition, where a refusal states what was refused: for
|
|
1970
|
+
`E_LAUNCH_PREFERENCE_UNMATCHED` the report's `message` names the keys and
|
|
1971
|
+
the layer that would decide, and ends "it would be refused."; it does not
|
|
1972
|
+
repeat the remedy, which is its `fix` (the refusal's `details.fix`). With `E_LAUNCH_CONFIG_UNKNOWN`,
|
|
1727
1973
|
`effective` is the host default (`pi`, `null`, `null`): the named
|
|
1728
1974
|
configuration launches nothing here.
|
|
1729
1975
|
- In listings (`oats souls`, `inspect --soul`, `launchCurrent`) `model` is the
|
|
@@ -2405,6 +2651,10 @@ its absence.
|
|
|
2405
2651
|
`soulSource` (`{repoKey, commit, path, current?, status?}`, `current` or
|
|
2406
2652
|
`moved`) for a workspace soul; `retireFailures[]` (`{instance, completedAt,
|
|
2407
2653
|
error, incomplete, retry, resultPath}`) when a deferred self-retire failed.
|
|
2654
|
+
An entry stays until a retire of the instance completes or its result
|
|
2655
|
+
file is removed by hand, whether or not the instance's row still has
|
|
2656
|
+
`retirePending`
|
|
2657
|
+
([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
|
|
2408
2658
|
A capability agent's row is `{name, kind: "capability", capability,
|
|
2409
2659
|
description, dir, instances}`.
|
|
2410
2660
|
- **Instance rows**: the home's `instance.json` (launch recipe and command
|
|
@@ -2791,6 +3041,19 @@ that name: `E_AMBIGUOUS_INSTANCE {candidates: [{root, agent, home}]}` (pass
|
|
|
2791
3041
|
`--home`; a wrong one is `E_HOME_MISMATCH`). Unknown: `E_SESSION_UNKNOWN`. No
|
|
2792
3042
|
tree: `E_NO_WORKTREE`.
|
|
2793
3043
|
|
|
3044
|
+
`E_NO_WORKTREE` is answered when nothing is at `<home>/work`, when it is not
|
|
3045
|
+
inside a Git work tree, and (0.53.0, #962) when it is a real directory that
|
|
3046
|
+
is not the top level Git names for it. Git answers for any directory inside
|
|
3047
|
+
a work tree, so a plain `work/` in a home whose deployment directory is a
|
|
3048
|
+
Git checkout was read as that checkout before: its branch and its files,
|
|
3049
|
+
none of them the instance's. The rule is the path, in every work mode: a
|
|
3050
|
+
`directory` instance in such a deployment has no work tree, and one whose
|
|
3051
|
+
`work/` is the top level of a repository of its own is observed as before.
|
|
3052
|
+
A `work/` that is a link is read as what it leads to, wherever that is: a
|
|
3053
|
+
`workspace` instance's leads to the deployment directory, which is above its
|
|
3054
|
+
home, and is observed as before. A [stop plan](#stop)'s and a
|
|
3055
|
+
[retire plan](#retire)'s `work` read the same way, with the code as `reason`.
|
|
3056
|
+
|
|
2794
3057
|
```json
|
|
2795
3058
|
{"instanceGitApi":1,"instance":"dev-1","agent":"dev","home":"/w/agents/dev/instances/dev-1","workMode":"worktree",
|
|
2796
3059
|
"observation":{"revision":"46c20668…","indexRevision":"3147fef2…","at":"2026-09-26T18:15:26.487Z","worktree":"/w/agents/dev/instances/dev-1/work",
|
|
@@ -2875,7 +3138,8 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
2875
3138
|
bytes}`. Only a regular file is opened (no symlinks, same device and inode
|
|
2876
3139
|
after open), and at most its last 4 MiB is read (`"tail"`).
|
|
2877
3140
|
- **Kinds:** `spawned`, `launched`, `restarted`, `stopped`, `stop-refused`,
|
|
2878
|
-
`retire-planned`, `retired`, `
|
|
3141
|
+
`retire-planned`, `retired`, `retire-refused` (0.53.0,
|
|
3142
|
+
[below](#retire-refused-event)), `worktree-retained`, `worktree-removed`,
|
|
2879
3143
|
`branch-deleted` (not written since 0.41.0: no retire deletes a branch;
|
|
2880
3144
|
older logs hold it), `child-spawn-refused`, `launch-warning` (0.30: a
|
|
2881
3145
|
`launch` hook's warning at session start/restart, `data: {message}`),
|
|
@@ -2905,6 +3169,34 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
2905
3169
|
`--delete-branch` (since 0.41.0: `this self-retire was requested with
|
|
2906
3170
|
--delete-branch by an older OATS; retirement no longer deletes branches, so
|
|
2907
3171
|
the branch and the worktree were left`).
|
|
3172
|
+
- <a id="retire-refused-event"></a>`retire-refused` (0.53.0; `data: {code,
|
|
3173
|
+
homeChanged, reason}`) is written once by the completion of a scheduled
|
|
3174
|
+
self-retire (`oats retire <instance> --self`) that did not complete, and
|
|
3175
|
+
by nothing else. A retire that a person runs answers that person and
|
|
3176
|
+
writes none. No feature names the kind: a client that does not know it
|
|
3177
|
+
reads the row as it reads any unknown kind.
|
|
3178
|
+
- `code` is a kernel code, or `null`. It is the code the retire answered.
|
|
3179
|
+
It is `null` for the one outcome that is a result and not an error: a
|
|
3180
|
+
cleanup that did not finish, with the home retained in quarantine.
|
|
3181
|
+
`null` means that outcome, never "unknown".
|
|
3182
|
+
- `homeChanged` is `false` when no retire hook was started and nothing of
|
|
3183
|
+
the home was removed, and `true` otherwise. It is always `true` for the
|
|
3184
|
+
incomplete cleanup. A session or a child that was stopped on the way
|
|
3185
|
+
does not count.
|
|
3186
|
+
- `reason` is the sentence the retire answered, on one line and at most
|
|
3187
|
+
2048 UTF-16 code units. A longer sentence is cut and ends with `…`,
|
|
3188
|
+
which is counted in the 2048. The bound is the Desktop events reader's,
|
|
3189
|
+
which refuses a whole read that holds a longer detail. For the
|
|
3190
|
+
incomplete cleanup it is a sentence of the kernel's own that names no
|
|
3191
|
+
item; the items are in the completion's result file.
|
|
3192
|
+
- The row is in the workspace's log only, and carries the incarnation
|
|
3193
|
+
the home had before the retire ran. The completion holds no claim when
|
|
3194
|
+
it writes, so it writes nothing into a home.
|
|
3195
|
+
- With `homeChanged: false` the self-retire's pending marker is gone as
|
|
3196
|
+
well, and with `true` it stays
|
|
3197
|
+
([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
|
|
3198
|
+
- `stop-refused` and `retire-refused` each cover two cases: a verb that was
|
|
3199
|
+
refused, and one that failed after it began.
|
|
2908
3200
|
- `worktree-retained` (`data: {movedTo, branch, recordedBranch}`) and
|
|
2909
3201
|
`worktree-removed` (`data: {branch}`) are written to the workspace log only,
|
|
2910
3202
|
by the retire's worktree step. Since 0.42.1 the retire also writes one per
|
|
@@ -3167,16 +3459,22 @@ oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>]
|
|
|
3167
3459
|
what failed (`E_SESSION_UNAVAILABLE` for an error that has none).
|
|
3168
3460
|
- `work` is the Git observation summarized (`changed` counts changed,
|
|
3169
3461
|
renamed, copied and unmerged rows), or `{observed: false, reason}`:
|
|
3170
|
-
`"no-worktree"
|
|
3171
|
-
|
|
3172
|
-
|
|
3173
|
-
|
|
3462
|
+
`"no-worktree"` when nothing is at `work/`, or the kernel code of what
|
|
3463
|
+
failed (`E_NO_WORKTREE` for a `work/` that is no work tree of the
|
|
3464
|
+
instance's, as [`oats instance git`](#git-and-diff) answers it;
|
|
3465
|
+
`E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
|
|
3466
|
+
a home the kernel cannot look into, where whether it has a `work/` cannot
|
|
3467
|
+
be told; OATS 0.52.0).
|
|
3174
3468
|
- `midTask`: `true`, `false` or `"unknown"`.
|
|
3175
3469
|
- `retiring` and `stopPending`, booleans on every target, say who holds the
|
|
3176
3470
|
target's home when the plan is read (OATS 0.52.0, feature
|
|
3177
3471
|
`lifecycle-claim-stop`). `retiring`: a self-retire is scheduled for it
|
|
3178
3472
|
(its pending marker is there), or a retire holds its
|
|
3179
|
-
[claim](#retire-one-at-a-time).
|
|
3473
|
+
[claim](#retire-one-at-a-time). From 0.53.0 the marker outlasts a
|
|
3474
|
+
completion that did not complete only when a retire hook was started or
|
|
3475
|
+
the removal of the home began
|
|
3476
|
+
([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
|
|
3477
|
+
`stopPending`: a stop apply holds its
|
|
3180
3478
|
claim. A holder counts while it is not known to be gone: alive, or of a
|
|
3181
3479
|
liveness that cannot be read. `retiring` is one of the facts
|
|
3182
3480
|
`planRevision` is hashed from, as it was; `stopPending` is not. The
|
|
@@ -3215,12 +3513,17 @@ this order:
|
|
|
3215
3513
|
retire answers it: `E_INSTANCE_RETIRING` beside a retire,
|
|
3216
3514
|
`E_LIFECYCLE_BUSY` beside another stop
|
|
3217
3515
|
([Commands that meet on one home](#lifecycle-pairs)). A stop never waits
|
|
3218
|
-
for a holder.
|
|
3516
|
+
for a holder. A claim that cannot be written is
|
|
3517
|
+
[read in its place](#stop-claim-write) (OATS 0.53.0): whoever holds it
|
|
3518
|
+
is answered the same way, here.
|
|
3219
3519
|
5. It reads the plan again, under the claims: this is the plan it acts on.
|
|
3220
3520
|
**It holds the claim of every target of this plan before it does
|
|
3221
3521
|
anything.** A target it does not hold yet (a child recorded, or readable
|
|
3222
3522
|
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
|
|
3523
|
+
every claim released first so that the order of step 4 holds. A target
|
|
3524
|
+
whose claim was only read counts as held for this, and its claim is
|
|
3525
|
+
read once more now, before the comparison below: a holder that came
|
|
3526
|
+
since is answered as in step 4. A stop
|
|
3224
3527
|
whose targets are others under each of three such reads (a constant of
|
|
3225
3528
|
the kernel: there is no setting for it) gives up:
|
|
3226
3529
|
`E_LIFECYCLE_BUSY`, `holder: "none"`, `… nothing was stopped — run the
|
|
@@ -3253,16 +3556,108 @@ once it holds the claim; a removal that fails is a warning on stderr (`oats:
|
|
|
3253
3556
|
warning: …`, in both modes) and the stop goes on.
|
|
3254
3557
|
|
|
3255
3558
|
<a id="stop-claim-write"></a>
|
|
3256
|
-
**A stop
|
|
3257
|
-
|
|
3258
|
-
|
|
3259
|
-
`
|
|
3260
|
-
|
|
3261
|
-
|
|
3262
|
-
|
|
3263
|
-
|
|
3264
|
-
|
|
3265
|
-
|
|
3559
|
+
**A stop whose claim cannot be written reads it instead** (OATS 0.53.0;
|
|
3560
|
+
#946). Stop is what a person reaches for when a disk is full, and a stop
|
|
3561
|
+
that leaves a session running because it could not write a file protects
|
|
3562
|
+
nobody. So `oats instance stop --apply`, and it alone, reads a claim it
|
|
3563
|
+
cannot write, for a reason that stops every other writer of this user as
|
|
3564
|
+
well, and goes on when nobody holds it. It holds nothing for that target,
|
|
3565
|
+
and says so on stderr. A retire, and a retire's stop of a recorded child,
|
|
3566
|
+
need their claim as before.
|
|
3567
|
+
|
|
3568
|
+
The reasons are five codes of the system's, met at one of the claim's
|
|
3569
|
+
writes (its directory, its file, and the same two of a takeover's own
|
|
3570
|
+
claim):
|
|
3571
|
+
|
|
3572
|
+
| The system's code | It means |
|
|
3573
|
+
|---|---|
|
|
3574
|
+
| `ENOSPC` | the file system is full |
|
|
3575
|
+
| `EDQUOT` | this user's quota is spent |
|
|
3576
|
+
| `EROFS` | the file system is read-only |
|
|
3577
|
+
| `EACCES`, `EPERM` | the claims directory is not writable by this user |
|
|
3578
|
+
|
|
3579
|
+
Each is in the list for one reason: what stops this stop from writing a
|
|
3580
|
+
claim in that directory stops a retire or another stop of the same user as
|
|
3581
|
+
well, so a claim that reads as held by nobody is held by nobody. `EACCES`
|
|
3582
|
+
and `EPERM` are there because every instance of a deployment can change the
|
|
3583
|
+
claims directory, and one that takes write permission from it must not take
|
|
3584
|
+
Stop from the operator. On a shared deployment that is the likely case of a
|
|
3585
|
+
warning below, and its cure is to fix the directory's permissions, not to
|
|
3586
|
+
live with the warning. Any other code (`EIO`, `EMFILE`, `EEXIST` from a
|
|
3587
|
+
file where the directory belongs) says nothing about who else could write
|
|
3588
|
+
there, and is refused as in 0.52.0: `E_LIFECYCLE_FAILED`, `the claim <lock>
|
|
3589
|
+
could not be taken (<the system's error>); nothing was done`, with the
|
|
3590
|
+
system's code in [`details.cause`](#kernel-codes) and the plan it read in
|
|
3591
|
+
`details.plan`; nothing was signalled.
|
|
3592
|
+
|
|
3593
|
+
**What the read answers** is what the taking would have answered for what
|
|
3594
|
+
is at the claim's path, with one difference:
|
|
3595
|
+
|
|
3596
|
+
- **Nobody holds it** (no file there; or a holder that is verifiably gone,
|
|
3597
|
+
whose claim a command that can write would take over): the stop goes on.
|
|
3598
|
+
This is the difference: the dead holder's file is left as it is, for the
|
|
3599
|
+
next command that can write to take over.
|
|
3600
|
+
- **A holder that is alive, or whose liveness cannot be read, and a file
|
|
3601
|
+
that is no readable claim:** the cell of
|
|
3602
|
+
[the pair table](#lifecycle-pairs) for an arriving stop, with the same
|
|
3603
|
+
sentence and the same `details`. Nothing was signalled.
|
|
3604
|
+
- **A file of a gone holder that no kernel can take over** (no `nonce` of a
|
|
3605
|
+
claim's shape): `E_LIFECYCLE_BUSY`, `holder: "none"`, as for a stop that
|
|
3606
|
+
can write. Its message says to inspect the file and remove it. On a full
|
|
3607
|
+
disk that removal works; in a directory that is not writable the person
|
|
3608
|
+
has to make it writable first.
|
|
3609
|
+
- **The claim cannot be read either** (its path cannot be reached): the
|
|
3610
|
+
`E_LIFECYCLE_FAILED` of the write, as above. The read is positive or it
|
|
3611
|
+
is nothing.
|
|
3612
|
+
|
|
3613
|
+
The read is made twice: where the claim would have been taken (step 4), and
|
|
3614
|
+
again once the plan has been read under the claims (step 5), before the
|
|
3615
|
+
revision is compared. A holder that came in between is answered there,
|
|
3616
|
+
before a stale plan and before any signal, with the fresh plan in
|
|
3617
|
+
`details.plan`.
|
|
3618
|
+
|
|
3619
|
+
**What it gives up.** Nothing on the home shows this stop: a plan read
|
|
3620
|
+
meanwhile says `stopPending: false`, and a retire or a stop that starts
|
|
3621
|
+
while it runs, and that can write its claim, is not refused. That is space
|
|
3622
|
+
freed a moment later, or a process of another user, for whom the directory
|
|
3623
|
+
is writable. The two commands then work in one home at once, as every stop
|
|
3624
|
+
did before 0.52.0. The warning says it, one line per such target, on stderr
|
|
3625
|
+
in text and in JSON mode:
|
|
3626
|
+
|
|
3627
|
+
```text
|
|
3628
|
+
oats: warning: <instance>: stopping without its claim: <lock> could not be written (<CODE>), and nobody holds it. A retire or a stop of <instance> that starts while this one runs will not see it.
|
|
3629
|
+
```
|
|
3630
|
+
|
|
3631
|
+
`<lock>` is the claim's own path and `<CODE>` the system's code, never its
|
|
3632
|
+
message. It is printed only when the apply answers a receipt, also for a
|
|
3633
|
+
target whose row is `alreadyIdle`, and never for a replay, which takes no
|
|
3634
|
+
claim. It is not part of the receipt, whose fields and values are those of
|
|
3635
|
+
any stop. **With `--server` the warning does not reach the caller:** the
|
|
3636
|
+
router keeps a remote command's stderr only when the command fails, as for
|
|
3637
|
+
every warning of a stop (#952).
|
|
3638
|
+
|
|
3639
|
+
**On a full disk the stop cannot write into the home either.** The session
|
|
3640
|
+
is stopped, and the apply answers its receipt (exit 0 in JSON mode) with
|
|
3641
|
+
that target's row `ok: false`, `E_SESSION_STOP_FAILED`, a `message` that
|
|
3642
|
+
ends `its harness was signalled (SIGTERM) and has exited`, and
|
|
3643
|
+
[`stillRunning: []`](#still-running): the row of a stop in a home that
|
|
3644
|
+
cannot be written, as it was. Read `stillRunning`, not `ok`: `[]` says
|
|
3645
|
+
stopped. Text mode prints that row, closes with `the stop did not complete
|
|
3646
|
+
its record; nothing is still running`, and exits 1, as for any target that
|
|
3647
|
+
failed. The receipt cannot be stored either, so **its key cannot be
|
|
3648
|
+
replayed**: the same apply again runs, and is answered `E_PLAN_STALE` with
|
|
3649
|
+
the fresh plan, in which the session is stopped; an apply with that plan's
|
|
3650
|
+
revision answers `alreadyIdle`, and prints the warning again. Such a stop
|
|
3651
|
+
leaves nothing of its own in the home: the private file each of the two
|
|
3652
|
+
writes goes through (`.oats-stop.json.tmp-<pid>`,
|
|
3653
|
+
`.oats-stop-receipt.<key>.json.<pid>.tmp`) is removed when its write or its
|
|
3654
|
+
rename fails. Before 0.53.0 each apply on a full disk left both there,
|
|
3655
|
+
empty.
|
|
3656
|
+
|
|
3657
|
+
In 0.52.0 a stop whose claim could not be written for one of those five
|
|
3658
|
+
codes was refused like the others, before anything was signalled
|
|
3659
|
+
(`E_LIFECYCLE_FAILED`). Before 0.52.0 a stop took no claim: it wrote its
|
|
3660
|
+
marker if it could and signalled the harness either way.
|
|
3266
3661
|
|
|
3267
3662
|
Two kernel versions acting on one deployment at once are not covered: a
|
|
3268
3663
|
kernel before 0.52.0 takes no claim for a stop and does not read a stop's
|
|
@@ -3304,7 +3699,14 @@ in flight.
|
|
|
3304
3699
|
defect's stack is printed on stderr; a stop that fails on a refusal without
|
|
3305
3700
|
a code (a `tmux` command that failed) is that row and prints no stack. The
|
|
3306
3701
|
same holds for a child's stop in a retire's `childrenStopped`.
|
|
3307
|
-
- `ok: false`: at least one target
|
|
3702
|
+
- `ok: false`: at least one target's row is not `ok` (text mode exits 1).
|
|
3703
|
+
Whether something still runs is each such row's `stillRunning`, and the
|
|
3704
|
+
sentence text mode closes with follows it: `some targets are still
|
|
3705
|
+
running; nothing was escalated` when one of those rows names a process or
|
|
3706
|
+
establishes nothing (`null`, or no `stillRunning` in the row), and `the
|
|
3707
|
+
stop did not complete its record; nothing is still running` when every
|
|
3708
|
+
one of them says `[]` (from 0.53.0; before, the first sentence closed
|
|
3709
|
+
every such answer).
|
|
3308
3710
|
- A replay is the stored receipt (`<home>/.oats-stop-receipt.<key>.json`)
|
|
3309
3711
|
with `replayed: true`, and it follows the same rules as a first answer. The
|
|
3310
3712
|
file a kernel with feature `lifecycle-kernel-codes` stores says so in a
|
|
@@ -3334,7 +3736,8 @@ in flight.
|
|
|
3334
3736
|
that is not the kernel's; with [`details.cause`](#kernel-codes) when it has
|
|
3335
3737
|
a code of its own or is a defect, and without it when it is a refusal
|
|
3336
3738
|
without a code; among them a claim that cannot be taken for a reason of
|
|
3337
|
-
the system's
|
|
3739
|
+
the system's other than [the five a stop reads it for](#stop-claim-write):
|
|
3740
|
+
`the claim <path> could not be taken (…); nothing was done`).
|
|
3338
3741
|
A stop never answers `E_WORK_INSPECTION_FAILED`.
|
|
3339
3742
|
|
|
3340
3743
|
<a id="lifecycle-pairs"></a>
|
|
@@ -3346,22 +3749,27 @@ Each cell is the answer of the command that **arrives**. It is given at once
|
|
|
3346
3749
|
and before any effect: that command stopped, ran, copied, made and removed
|
|
3347
3750
|
nothing, and the command already on the home is not disturbed.
|
|
3348
3751
|
|
|
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 |
|
|
3752
|
+
| On the home ↓ / arrives → | `oats retire` | `oats instance stop --apply` | `oats instance stop --apply` that cannot write its claim | `oats worktree add` |
|
|
3753
|
+
|---|---|---|---|---|
|
|
3754
|
+
| a retire is running | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
|
|
3755
|
+
| a self-retire is scheduled | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
|
|
3756
|
+
| a stop apply is running | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
|
|
3757
|
+
| a retire whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
|
|
3758
|
+
| a stop whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
|
|
3759
|
+
| the claim file is no readable claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
|
|
3760
|
+
| the holder of the claim is gone | not refused | not refused | not refused | not refused |
|
|
3358
3761
|
|
|
3359
3762
|
- **A holder is answered before a stale plan, by both verbs.** A guarded
|
|
3360
3763
|
retire and a stop apply compare the revision they were sent only once
|
|
3361
3764
|
they hold the claim, so beside a holder the answer is the cell above
|
|
3362
3765
|
whatever the plan would read by then.
|
|
3363
3766
|
- **A scheduled self-retire holds no claim** until its completion runs: it
|
|
3364
|
-
is its pending marker.
|
|
3767
|
+
is its pending marker. The row lasts as long as the marker does: until
|
|
3768
|
+
the completion has retired the home, or, from 0.53.0, until a completion
|
|
3769
|
+
that did not complete has removed it, which it does unless it started a
|
|
3770
|
+
retire hook or began the removal of the home
|
|
3771
|
+
([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
|
|
3772
|
+
A retire reads the marker under the claim, while
|
|
3365
3773
|
the completion lives (`E_LIFECYCLE_BUSY`, [below](#retire-one-at-a-time)).
|
|
3366
3774
|
A stop apply reads it in the plan it makes under its claims: a plan that
|
|
3367
3775
|
showed `retiring: true` is answered `E_INSTANCE_RETIRING`, and an apply
|
|
@@ -3387,6 +3795,13 @@ nothing, and the command already on the home is not disturbed.
|
|
|
3387
3795
|
`E_LIFECYCLE_BUSY`, `holder: "none"`, with `run the command again`.
|
|
3388
3796
|
- **A stop does not refuse a `worktree add`:** a tree does not depend on the
|
|
3389
3797
|
session.
|
|
3798
|
+
- **A stop apply that cannot write its claim**
|
|
3799
|
+
([it reads it instead](#stop-claim-write), OATS 0.53.0) is answered as
|
|
3800
|
+
the stop that can, cell for cell. Beside a holder that is gone it stops
|
|
3801
|
+
like the other, and leaves that holder's file as it is: it takes nothing
|
|
3802
|
+
over. As a command already on the home it has no row: it holds nothing,
|
|
3803
|
+
so nothing on the home shows it, and no command that arrives is refused
|
|
3804
|
+
by it.
|
|
3390
3805
|
- `--plan` of either verb takes no claim and is never refused by one; a
|
|
3391
3806
|
stop plan reports the holder (`retiring`, `stopPending`). `oats worktree
|
|
3392
3807
|
remove` does not read the home's claim. `oats session start` and `restart`
|
|
@@ -3567,7 +3982,7 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
3567
3982
|
"facts":{"session":{"state":"shell","present":true,"backend":"tmux","established":true},
|
|
3568
3983
|
"work":{"observed":true,"revision":"46c20668…","branch":"feat/x","detached":false,"drift":true,"changed":0,"untracked":1,
|
|
3569
3984
|
"upstream":{"ref":null,"ahead":null,"behind":null},"base":{"ref":null,"ahead":null,"behind":null},"remote":null},
|
|
3570
|
-
"workMode":"worktree","repo":"/w/one","recordedBranch":"agents/dev-1",
|
|
3985
|
+
"workMode":"worktree","ownWorktree":true,"repo":"/w/one","recordedBranch":"agents/dev-1",
|
|
3571
3986
|
"children":[{"instance":"dev-1-child","agent":"dev","home":"/w/agents/dev/instances/dev-1-child","session":{"state":"shell","present":true,"backend":"tmux","established":true}}],
|
|
3572
3987
|
"ambiguous":[],"pullRequest":"unknown",
|
|
3573
3988
|
"extraWorktrees":[{"path":"/w/agents/dev/instances/dev-1/.work-docs","repo":"/w/docs","branch":"agents/dev-1-docs","detachedAt":null,
|
|
@@ -3579,12 +3994,198 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
3579
3994
|
- `facts.session` and `facts.work` read as a [stop plan](#stop)'s
|
|
3580
3995
|
`session` and `work`. Work that was not observed is `{observed: false,
|
|
3581
3996
|
reason}`: `"no-worktree"`, or the kernel code of what failed
|
|
3582
|
-
(`
|
|
3997
|
+
(`E_NO_WORKTREE` for a `work/` that is no work tree of the instance's;
|
|
3998
|
+
`E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
|
|
3583
3999
|
a home the kernel cannot look into, where whether it has a `work/` cannot be
|
|
3584
|
-
told; OATS 0.52.0).
|
|
4000
|
+
told; OATS 0.52.0). `facts.work` never reads a checkout that encloses the
|
|
4001
|
+
home as the instance's work (0.53.0, #962).
|
|
3585
4002
|
- The plan changes nothing except appending a `retire-planned` event to the
|
|
3586
4003
|
workspace log. `pullRequest` is always `"unknown"`. Branch actions use the
|
|
3587
4004
|
worktree's branch, never `recordedBranch`.
|
|
4005
|
+
- `facts.ownWorktree` (0.53.0, #988, feature `retire-plan-own-worktree`) is
|
|
4006
|
+
a fact: a boolean, `true` exactly when `work/` is the instance's own work
|
|
4007
|
+
tree, the one this retire retains (moved, as described below) or removes
|
|
4008
|
+
(`--discard-worktree`), and `false` for every other home. It is always
|
|
4009
|
+
present and never `null`. It is the answer of the one reading of `work/`
|
|
4010
|
+
that the retire acts on (below), so it is `true` in `worktree` mode with
|
|
4011
|
+
the instance's tree at `work/` (and, by the record, with nothing at
|
|
4012
|
+
`work/`: the retire then finds its tree absent), and for a record with no
|
|
4013
|
+
work mode whose `work/` Git confirms is a registered linked worktree
|
|
4014
|
+
(#962). It is `false` for a directory instance; for an attached, a
|
|
4015
|
+
checkout or a workspace instance, whatever the tree its link leads to is
|
|
4016
|
+
on; for a real directory that is not the instance's own tree (#962) and
|
|
4017
|
+
for a link (#973), under a record that says `worktree` too. It is the
|
|
4018
|
+
reading's answer and not a promise that the retire completes: it is
|
|
4019
|
+
`true` for a file (or any entry that is neither a link nor a directory)
|
|
4020
|
+
at `work/` under a record that says `worktree`, and `false` for one under
|
|
4021
|
+
any other record; and it is `true` for a work directory whose Git admin
|
|
4022
|
+
entry is missing when the spawn's receipt says that a tree was given,
|
|
4023
|
+
whatever the record says but `directory`. No retire removes such an
|
|
4024
|
+
entry: it is kept with the home until a person moves it (#1019). Neither
|
|
4025
|
+
`facts.workMode` (the record's value, which the instance can write) nor
|
|
4026
|
+
`facts.work` (an observation, through any link) says whose tree it is:
|
|
4027
|
+
read this key for that. Gate on the probe: from a kernel that lists the
|
|
4028
|
+
feature the key is present and a boolean; from one that does not it is
|
|
4029
|
+
absent, and its absence says nothing. A stop plan does not carry it. A
|
|
4030
|
+
relayed plan (`--server`) carries it as its host answered it, so it is
|
|
4031
|
+
the host's features that say whether it is there.
|
|
4032
|
+
- `defaults.retainWorktree` is the default of one option of this retire:
|
|
4033
|
+
whether the instance's own work tree is retained or removed
|
|
4034
|
+
(`--discard-worktree`). It follows the fact today: it is `true` when
|
|
4035
|
+
`facts.ownWorktree` is. A default is what the retire would do if nobody
|
|
4036
|
+
chose and a fact is what is there, so a client does not read this key to
|
|
4037
|
+
learn what `work/` is. Where it is `false` the instance has no work tree
|
|
4038
|
+
of its own; it is never `false` because a tree would be removed: there
|
|
4039
|
+
the retire touches no tree it does not own. `work/` of an attached, a
|
|
4040
|
+
checkout or a workspace instance is a link (to its owner's tree, to the
|
|
4041
|
+
shared checkout, to the deployment directory) that goes with the home,
|
|
4042
|
+
and what it links to is not touched. Where a real directory is found at
|
|
4043
|
+
`work/` of such an instance and no link, it is a directory of the home:
|
|
4044
|
+
the retire copies it to recovery when it is not empty and removes it
|
|
4045
|
+
with the home, and the plan says so (0.53.0, #962: the next item).
|
|
4046
|
+
`work/` of a directory instance is the home's own directory: it is
|
|
4047
|
+
copied to recovery when it is not empty, then removed with the home. The
|
|
4048
|
+
plan's text (`oats retire <instance>
|
|
4049
|
+
--plan` without `--json`) prints `retain worktree true` in its `defaults:`
|
|
4050
|
+
line for the instance's own tree only; for the other homes the line says
|
|
4051
|
+
the above (0.53.0, #959). When the reading of `work/` establishes
|
|
4052
|
+
neither an own tree nor a directory of the home, the line says `work mode
|
|
4053
|
+
not recorded` for a record with no work mode, and `work mode not known to
|
|
4054
|
+
this kernel` for one whose work mode the kernel does not know: the value
|
|
4055
|
+
is never printed, and `facts.workMode` holds it. (An own tree under such
|
|
4056
|
+
a record prints `retain worktree true`, and a directory of the home its
|
|
4057
|
+
own sentence.) The text does not print the fact.
|
|
4058
|
+
- What `work/` is comes from one reading, which the plan and the retire
|
|
4059
|
+
share (0.53.0, #962). It is **the instance's own tree** when the spawn's
|
|
4060
|
+
receipt says the instance was given one; for a home without a valid
|
|
4061
|
+
receipt, when the record says `worktree`, or holds no work mode (or one
|
|
4062
|
+
the kernel does not know) and Git confirms that `work/` is a registered
|
|
4063
|
+
linked worktree whose top level it is (the test of an
|
|
4064
|
+
[extra tree](souls-and-instances.md#extra-trees-at-retire)). A real
|
|
4065
|
+
directory at `work/` that is not that is **a directory of the home**: one
|
|
4066
|
+
found where the work mode has a link (an attached, a checkout or a
|
|
4067
|
+
workspace instance, or a record with no work mode), or under a valid
|
|
4068
|
+
receipt that says no tree was given, whatever the record says now. **A
|
|
4069
|
+
link** at `work/` is never the instance's own tree, whatever the record
|
|
4070
|
+
says (0.53.0, #973, below). For a directory of the home the plan has:
|
|
4071
|
+
- `defaults.retainWorktree: false`, and in the text's `defaults:` line `no
|
|
4072
|
+
work tree of its own (work/ is a real directory of the home: copied to
|
|
4073
|
+
recovery when not empty and then removed with the home)`.
|
|
4074
|
+
- the note `work/ is a real directory of the home and not a work tree of
|
|
4075
|
+
the instance's own: the retire copies it to recovery when it is not
|
|
4076
|
+
empty (a .git in it included), checks the copy, and removes it with the
|
|
4077
|
+
home`, and `recovery: work/ is copied there when it is not empty`. The
|
|
4078
|
+
notes that say a worktree is retained, and the drift note, are not said.
|
|
4079
|
+
- when Git confirms that the directory is a registered worktree, the note
|
|
4080
|
+
`work/ is registered as a worktree of <repository>: the retire leaves its
|
|
4081
|
+
entry there until a prune (git -C '<repository>' worktree prune), and does
|
|
4082
|
+
not touch its branch or its commits`.
|
|
4083
|
+
- `facts.work` by the path alone: observed when `work/` is the top level of
|
|
4084
|
+
a repository of its own, else `{observed: false, reason:
|
|
4085
|
+
"E_NO_WORKTREE"}`.
|
|
4086
|
+
|
|
4087
|
+
For an own tree whose record names no repository, the plan has the note
|
|
4088
|
+
`the record names no repository for the work tree: the retire uses the
|
|
4089
|
+
one Git names for it, <repository>, and does not write it into the
|
|
4090
|
+
record`. No key of the plan is new.
|
|
4091
|
+
|
|
4092
|
+
What `work/` is decides what the retire does with it, so it is part of
|
|
4093
|
+
`planRevision` wherever it is not what the work mode alone says: when an
|
|
4094
|
+
own tree became a directory of the home, or the other way round, between
|
|
4095
|
+
the plan and the apply (a record's work mode that changed, a receipt that
|
|
4096
|
+
is gone), or the repository read from Git changed, a guarded apply refuses
|
|
4097
|
+
with `E_PLAN_STALE` before anything runs. Every other home has the
|
|
4098
|
+
revision it had.
|
|
4099
|
+
- A link at `work/` is never the instance's own tree: the retire removes
|
|
4100
|
+
the link with the home and does not touch what it leads to, whatever the
|
|
4101
|
+
record says (0.53.0, #973). The record is a file the instance can write;
|
|
4102
|
+
what the link leads to is not the instance's. So a home whose record says
|
|
4103
|
+
`worktree` and whose `work/` is a symbolic link plans and retires as a
|
|
4104
|
+
home that was given a link. Before 0.53.0 its plan said
|
|
4105
|
+
`defaults.retainWorktree: true` and its retire was refused with
|
|
4106
|
+
`E_WORK_PRESERVATION_FAILED`. Its plan has:
|
|
4107
|
+
- `defaults.retainWorktree: false`, and in the text's `defaults:` line `no
|
|
4108
|
+
work tree of its own (work/ is a link, though the record says worktree:
|
|
4109
|
+
what it leads to is not touched)`. `facts.workMode` is the record's
|
|
4110
|
+
value, as always.
|
|
4111
|
+
- the note `the record says work mode worktree, but work/ is a link and
|
|
4112
|
+
not a work tree of the instance's own: the retire removes the link with
|
|
4113
|
+
the home and does not touch what it leads to, with --discard-worktree as
|
|
4114
|
+
well`. The note names no target. It names the flag because a plan takes
|
|
4115
|
+
no option: `--plan --discard-worktree` answers this same plan, and no
|
|
4116
|
+
worktree step runs for the link with the flag either.
|
|
4117
|
+
- `facts.work` as for every home whose `work/` is a link: an observation
|
|
4118
|
+
of what the link leads to, which says nothing of whose tree it is.
|
|
4119
|
+
- a `planRevision` that binds it, by the rule above: a plan read while
|
|
4120
|
+
`work/` was a link is stale once `work/` is the instance's own tree, and
|
|
4121
|
+
the other way round.
|
|
4122
|
+
|
|
4123
|
+
Its retire completes with the receipt of a home that was given a link
|
|
4124
|
+
(`retention: null`, `worktreeRemoved: false`, no copy of the work in
|
|
4125
|
+
`workRecovery`; with `--discard-worktree` too, since no worktree step
|
|
4126
|
+
runs), with and without `--discard-worktree` and `--force`, and one string
|
|
4127
|
+
in `warnings`: `<home>/work was a link though the record says
|
|
4128
|
+
work mode worktree: nothing was retained or removed as a work tree, and
|
|
4129
|
+
what it led to (<path>) was not touched`. `<path>` is what the system
|
|
4130
|
+
resolves the link to just before the home is removed, never the text
|
|
4131
|
+
stored in the link; nothing acts on it. When the link does not resolve,
|
|
4132
|
+
the string ends `and it led nowhere that could be read`. The receipt holds
|
|
4133
|
+
the path as the system gave it. The retire's text (without `--json`)
|
|
4134
|
+
prints every warning of the receipt on one line and spells each character
|
|
4135
|
+
a terminal would act on, or that hides or reorders text (a control
|
|
4136
|
+
character such as an escape or a newline, a bidi override: the set the
|
|
4137
|
+
kernel never prints in text it did not write), as `\u{<hex>}`, so that a
|
|
4138
|
+
name cannot clear the screen or write a line of its own. The JSON is not
|
|
4139
|
+
changed by that: its strings are what they were. No key of the plan or of
|
|
4140
|
+
the receipt is new.
|
|
4141
|
+
- A link at `work/` that is no longer a link when the retire inspects the
|
|
4142
|
+
home again (a retire hook, or anything else, put a directory or a file in
|
|
4143
|
+
its place) refuses with `E_WORK_INSPECTION_FAILED` and keeps the home, in
|
|
4144
|
+
every work mode (0.53.0, #973): the home's removal would take what is
|
|
4145
|
+
there now, uncopied. The message says what was there and what is there
|
|
4146
|
+
now, that the home is kept and nothing of it was removed, and how it
|
|
4147
|
+
ends, by what is there now:
|
|
4148
|
+
- a directory: that `oats retire <instance> --plan` shows what a retire
|
|
4149
|
+
would do with what is there now, and that running the retire again does
|
|
4150
|
+
that;
|
|
4151
|
+
- a file, or an entry that is neither a link, a directory nor a file:
|
|
4152
|
+
that no retire removes it, and the step (`move it out of the home or
|
|
4153
|
+
remove it, then run the retire again`). It does not point to the plan,
|
|
4154
|
+
which does not say that such an entry stays (#1019);
|
|
4155
|
+
- an entry that cannot be read: that the retire reads it again when it is
|
|
4156
|
+
run again.
|
|
4157
|
+
|
|
4158
|
+
Running the retire again reads the home as it is then, by the reading
|
|
4159
|
+
above: the record as it is then and the spawn's receipt decide, not what
|
|
4160
|
+
the home was given alone.
|
|
4161
|
+
- A directory that the reading answers is a directory of the home (#962:
|
|
4162
|
+
the spawn's receipt says that no tree was given, as an attached, a
|
|
4163
|
+
checkout or a workspace instance's does, and the record says
|
|
4164
|
+
`attached`, `checkout`, `workspace`, `worktree` or holds no work mode):
|
|
4165
|
+
the retire copies it to recovery, checks the copy and removes it with
|
|
4166
|
+
the home.
|
|
4167
|
+
- A directory under a record that says `worktree` whose spawn's receipt
|
|
4168
|
+
says that a tree was given, and a file (or an entry that is none of the
|
|
4169
|
+
three) under a record that says `worktree` whatever the receipt says
|
|
4170
|
+
(an attached instance whose record was changed to `worktree` included):
|
|
4171
|
+
a work directory with no Git admin entry. The retire runs its hooks and keeps the entry and the home as an
|
|
4172
|
+
incomplete item (exit 1; with `--force` it refuses with
|
|
4173
|
+
`E_WORK_PRESERVATION_FAILED` before anything runs) until a person moves
|
|
4174
|
+
the entry out or deletes it; then it completes.
|
|
4175
|
+
- A file, or an entry that is none of the three, under a record that
|
|
4176
|
+
says `attached`, `checkout` or `workspace`: the inspection refuses
|
|
4177
|
+
(`E_WORK_INSPECTION_FAILED`, `--force` included, nothing stopped, run
|
|
4178
|
+
or removed) until a person removes the entry; then it completes.
|
|
4179
|
+
- A record that says `directory` by then is held against the spawn's
|
|
4180
|
+
receipt as always: the retire refuses (`E_WORK_INSPECTION_FAILED`,
|
|
4181
|
+
nothing stopped, run or removed) while the two disagree.
|
|
4182
|
+
- The two notes about a worktree that is retained, `N changed and M
|
|
4183
|
+
untracked file(s) would be retained with the worktree` and `the worktree
|
|
4184
|
+
is on <branch>, not the recorded <branch>`, are given for the instance's
|
|
4185
|
+
own tree alone (0.53.0, #973). `facts.work` of an attached, a checkout or
|
|
4186
|
+
a workspace instance observes the tree its link leads to, and before
|
|
4187
|
+
0.53.0 its plan gave both notes for that tree, which the retire neither
|
|
4188
|
+
keeps nor moves. `facts.work` is unchanged.
|
|
3588
4189
|
- A home spawned before 0.25.9 has no session receipt (0.30). Its
|
|
3589
4190
|
`facts.session` is `{state: "absent", present: false, backend, established:
|
|
3590
4191
|
true, note}` when the session is observably gone: instance.json records no
|
|
@@ -4014,15 +4615,29 @@ left its outcome at `resultPath` (it failed) or is gone (it died; a
|
|
|
4014
4615
|
completion that is a zombie, not reaped by its parent, has died: 0.52.0,
|
|
4015
4616
|
#870), nor when
|
|
4016
4617
|
it names no completion (a marker written before 0.51.0): `oats retire
|
|
4017
|
-
<instance>` then retries the retirement, as before. The completion
|
|
4018
|
-
|
|
4019
|
-
|
|
4618
|
+
<instance>` then retries the retirement, as before. The completion does not
|
|
4619
|
+
start its retire while the retire that scheduled it holds the claim: it
|
|
4620
|
+
waits for that one command, which it knows by the pid and the start time it
|
|
4621
|
+
was given, for up to ten minutes (`SCHEDULING_WAIT_MS`; 0.53.0; before, for
|
|
4622
|
+
up to 3 s only). Meanwhile the home has no marker until that retire writes
|
|
4623
|
+
it, last, and that retire answers a stop and another retire as any running
|
|
4624
|
+
retire does ([the table](#lifecycle-pairs)). Then it takes the claim as any retire
|
|
4625
|
+
does, waiting up to 3 s for a live holder, the one that scheduled it
|
|
4626
|
+
included when the ten minutes have passed; one that meets another retire still running is refused,
|
|
4020
4627
|
and records that at `resultPath` like any failed completion. The `error`
|
|
4021
4628
|
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.
|
|
4629
|
+
envelope: a kernel code, and what the retire had done by then. From 0.53.0
|
|
4630
|
+
a completion that does not complete also writes one
|
|
4631
|
+
[`retire-refused` event](#retire-refused-event), and removes its pending
|
|
4632
|
+
marker unless it started a retire hook or began the removal of the home.
|
|
4633
|
+
It removes only the marker of its own scheduling: the same `requestedAt`,
|
|
4634
|
+
and a `completionPid` that is absent, its own, or of a process that is
|
|
4635
|
+
gone.
|
|
4023
4636
|
|
|
4024
4637
|
A `--self` that cannot finish scheduling (the completion's log cannot be
|
|
4025
|
-
opened, no process is created, the marker cannot be written
|
|
4638
|
+
opened, no process is created, the marker cannot be written, or, from
|
|
4639
|
+
0.53.0, its completion has already ended when the marker is written, with
|
|
4640
|
+
an outcome or without one: the marker is then removed again) answers
|
|
4026
4641
|
`E_SELF_RETIRE_SCHEDULE_FAILED`, with `reached.phase: "before-effects"`. That
|
|
4027
4642
|
stays true after the answer: a completion this command had started is not
|
|
4028
4643
|
running when it answers (it is ended, unless it had gone by itself; a
|
|
@@ -4333,7 +4948,23 @@ accept `--server <id>`.
|
|
|
4333
4948
|
anything is sent (`default: false` is dropped). Errors: `E_LOCAL_MISSING`,
|
|
4334
4949
|
`E_BAD_ARGS` (including `--home`/`--soul`), `E_LAUNCH_CONFIG_UNKNOWN`,
|
|
4335
4950
|
`E_LAUNCH_CONFIG_INVALID`, `E_CONFIG_BROKEN`, `E_HOME_UNKNOWN`,
|
|
4336
|
-
`E_REMOTE_INCOMPATIBLE
|
|
4951
|
+
`E_REMOTE_INCOMPATIBLE`, `E_LOCAL_BUSY {path, lock}`, `E_LOCAL_CHANGED
|
|
4952
|
+
{path}`.
|
|
4953
|
+
- **The write** (`set`, `remove`) replaces the `launch-configs` block and
|
|
4954
|
+
leaves every other byte of the file as it was. It is made under
|
|
4955
|
+
`<deployment>/.agents/locks/local.lock`, the lock of every kernel command
|
|
4956
|
+
that rewrites `oats-local.yaml` ([`oats teams`](#oats-teams) says what it
|
|
4957
|
+
covers), from the file as it is under that lock: whether the name is
|
|
4958
|
+
declared, `before`, the environment `--keep-env` keeps and the one default
|
|
4959
|
+
per harness are all read there, never from the command's start. The
|
|
4960
|
+
definition (`--file`, or stdin) is read and judged before the lock is
|
|
4961
|
+
taken. A lock still held after 5 s is `E_LOCAL_BUSY`, and a file that kept
|
|
4962
|
+
changing while the edit ran is `E_LOCAL_CHANGED`; nothing was written, and
|
|
4963
|
+
the same command can be run again. When the text it would write is the
|
|
4964
|
+
file's text already, nothing is written; the receipt is the same either
|
|
4965
|
+
way. (The same definition set again is such a case only once this command
|
|
4966
|
+
has written the block: a block written by hand in another form is
|
|
4967
|
+
rewritten in this command's.)
|
|
4337
4968
|
- **preview** (read-only) answers `{context, selected, selection: {source,
|
|
4338
4969
|
launchConfig, harness, model, yolo}, harness, model, modelSource, yolo,
|
|
4339
4970
|
launchConfig, launchConfigSource, launchConfigDefault, executable: {path,
|
|
@@ -4728,8 +5359,13 @@ changes `installed` or `active`). `maxConcurrent` is the effective scheduled-job
|
|
|
4728
5359
|
|
|
4729
5360
|
**Workspace items:**
|
|
4730
5361
|
- `enable`/`disable` edit `oats-local.yaml` `triggers.disabled` or
|
|
4731
|
-
`schedules.disabled
|
|
4732
|
-
|
|
5362
|
+
`schedules.disabled`: that list and no other entry, under
|
|
5363
|
+
`<deployment>/.agents/locks/local.lock` and from the file as it is under
|
|
5364
|
+
it, as [`oats teams`](#oats-teams) writes that file. A lock still held
|
|
5365
|
+
after 5 s is `E_LOCAL_BUSY {path, lock}`, and a file that kept changing
|
|
5366
|
+
while the edit ran is `E_LOCAL_CHANGED {path}`; nothing was written, and
|
|
5367
|
+
the same command can be run again. `update` and `remove` refuse
|
|
5368
|
+
`E_AUTOMATION_WORKSPACE {id, origin}`. `schedule run`/`reconcile` elsewhere refuse
|
|
4733
5369
|
`E_AUTOMATION_NOT_HERE {id, reason, runsOn, owner}`.
|
|
4734
5370
|
- `oats trigger|schedule add … --workspace <member> --runs-on <host> --owner
|
|
4735
5371
|
<host>/<login> --json` writes the file in the member clone and answers
|