@awebai/oats 0.52.0 → 0.53.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/bin/oats.mjs +304 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/desktop-cli-api.md +673 -58
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +175 -11
- 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 +1274 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +237 -15
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -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 +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +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 +49 -19
- 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 +2 -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,14 @@ 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 Git's own last line: `cannot read remote <url> (unknown):
|
|
684
|
+
<line>`. The line is one line of at most 300 characters, with control
|
|
685
|
+
characters and the user information of any URL removed; when Git said
|
|
686
|
+
nothing, the message ends at `(unknown)`.
|
|
675
687
|
`cache` (OATS 0.33.0) is local: the
|
|
676
688
|
remote cache on this machine could not be written (a git lock still held,
|
|
677
689
|
another oats process still writing it, or a lock file one left when it
|
|
@@ -685,7 +697,8 @@ Feature `workspace-v2`, `workspaceApi: 2`. Model: [workspaces.md](workspaces.md)
|
|
|
685
697
|
`cacheDir` or other detail field crosses to the renderer. It keys only on
|
|
686
698
|
`code` + `details.reason`: `cache` words the roster "OATS cache
|
|
687
699
|
problem" with the message in full; `network` / `timeout` read "Couldn't
|
|
688
|
-
reach <host>"; any other reason keeps the generic
|
|
700
|
+
reach <host>"; any other reason, `unknown` among them, keeps the generic
|
|
701
|
+
wording with the message in full. When the
|
|
689
702
|
deployment was observed before, the failed read keeps that observation:
|
|
690
703
|
`/api/panel` serves it with `error` (the message) and `errorCause {code,
|
|
691
704
|
reason, host?}`, and the roster shows it stale instead of empty.
|
|
@@ -957,6 +970,16 @@ problem`, (feature `souls-capabilities`) `capabilities`, and (feature
|
|
|
957
970
|
share a bare name share one entry (spawning that name is
|
|
958
971
|
`E_SOUL_AMBIGUOUS`).
|
|
959
972
|
- `launch` is a [Launch](#the-launch-report-launch).
|
|
973
|
+
- **`problems` rows for `souls.launch`** (0.53). `oats souls` adds, after the
|
|
974
|
+
read's own rows, one row per key of `souls.launch` that names no soul:
|
|
975
|
+
`{code: "E_LAUNCH_PREFERENCE_UNMATCHED", path, message, key, value,
|
|
976
|
+
suggestions}`, sorted by key. `path` is where the key is
|
|
977
|
+
(`oats-local.yaml#/souls/launch/<key>`), `key`, `value` and `suggestions`
|
|
978
|
+
as in the refusal's `details.keys`. `message` is at most 1024 characters
|
|
979
|
+
and ends with the two commands, in their order. Each soul a spawn would
|
|
980
|
+
refuse carries the refusal as `launch.problem`: the souls with no entry of
|
|
981
|
+
their own. Text mode prints each row under the table as `! <code>:
|
|
982
|
+
<message>`.
|
|
960
983
|
- `teams` and `defaultTeam` (feature `team-model-3`) are a
|
|
961
984
|
[TeamRow](#the-team-row-teamrow) list and a
|
|
962
985
|
[DefaultTeam](#the-default-defaultteam); both `null` when the soul's teams
|
|
@@ -1440,18 +1463,35 @@ oats teams default <label> [--if-absent | --expect <label>] --json
|
|
|
1440
1463
|
form `--max-age` (on a write form, `--max-age` is the kernel's own
|
|
1441
1464
|
`E_BAD_ARGS`, as for every write verb). `--help` is the kernel's usage
|
|
1442
1465
|
answer, as for every command.
|
|
1466
|
+
- **Rendering** (0.53.0). The file is written without folding lines: a value
|
|
1467
|
+
past 80 columns stays on its line. Before, a write re-wrapped such a line
|
|
1468
|
+
(the same value, over two lines). A file written as JSON (it opens with
|
|
1469
|
+
`{`, and the kernel reads it as strict JSON) is written back as JSON: it
|
|
1470
|
+
keeps the order of its keys and its final newline, or the absence of one,
|
|
1471
|
+
and its indentation becomes two spaces. Before, a write to such a file
|
|
1472
|
+
failed with no answer. A rewrite the kernel could not read back is
|
|
1473
|
+
`E_WORKSPACE_SCHEMA`, and nothing is written.
|
|
1443
1474
|
- A write that would introduce an unknown reference is refused with that
|
|
1444
1475
|
code; an invalid result is `E_WORKSPACE_SCHEMA`.
|
|
1445
1476
|
- **Writes** edit `oats-local.yaml` in place and touch only the entries that
|
|
1446
1477
|
change: comments and styles elsewhere, including inline comments on sibling
|
|
1447
|
-
entries, are kept.
|
|
1448
|
-
|
|
1449
|
-
|
|
1478
|
+
entries, are kept. The file is replaced whole, by a rename, and the new
|
|
1479
|
+
file keeps the permission bits of the old one. An `oats-local.yaml` that
|
|
1480
|
+
is a symbolic link is replaced by a regular file with its target's bits,
|
|
1481
|
+
and the target is not written. Each verb re-reads the file and judges its
|
|
1482
|
+
refusals on it as it is now, and writes only if the file did not change
|
|
1483
|
+
meanwhile (else it redoes the edit on the new content). A file that keeps
|
|
1484
|
+
changing is
|
|
1450
1485
|
`E_LOCAL_CHANGED {path}`; nothing was written. The condition of `--if-absent`
|
|
1451
1486
|
and `--expect` is judged the same way, on the file as it is now and again on
|
|
1452
1487
|
every redo.
|
|
1453
1488
|
- **Concurrency.** Every `add`, `remove` and `default` holds
|
|
1454
1489
|
`<deployment>/.agents/locks/local.lock` for its whole read-compare-write.
|
|
1490
|
+
Every other kernel command that rewrites `oats-local.yaml` holds the same
|
|
1491
|
+
lock and answers the same two codes: [`oats soul launch
|
|
1492
|
+
set|remove`](#oats-soul-launch), [`oats launch-config
|
|
1493
|
+
set|remove`](#launch-configurations) and [`oats schedule|trigger
|
|
1494
|
+
enable|disable`](#schedules-and-triggers) of a workspace item.
|
|
1455
1495
|
Among concurrent `oats teams` writers on one deployment, a conditional write
|
|
1456
1496
|
therefore never overwrites a default another of them set: when two race, the
|
|
1457
1497
|
later one sees the earlier result and refuses with
|
|
@@ -1490,6 +1530,95 @@ oats soul teams <soul>|'*' [--dir <d>] [--max-age <s>] --json
|
|
|
1490
1530
|
oats-workspace.yaml (a PR to the workspace file)"}`, before anything else
|
|
1491
1531
|
is judged.
|
|
1492
1532
|
|
|
1533
|
+
<a id="oats-soul-launch"></a>
|
|
1534
|
+
### `oats soul launch`
|
|
1535
|
+
|
|
1536
|
+
Feature `soul-launch` (OATS 0.53.0). The supported writer of
|
|
1537
|
+
`oats-local.yaml` `souls.launch`, a soul's
|
|
1538
|
+
[launch preference](#launch-preferences) on this machine.
|
|
1539
|
+
|
|
1540
|
+
```text
|
|
1541
|
+
oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <d>] --json
|
|
1542
|
+
oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <d>] --json
|
|
1543
|
+
```
|
|
1544
|
+
|
|
1545
|
+
```json
|
|
1546
|
+
{"soulLaunchApi":1,"action":"set","plan":false,
|
|
1547
|
+
"key":"example.pkg/reviewer","souls":["example.pkg/reviewer"],
|
|
1548
|
+
"level":"/abs/deployment","file":"/abs/deployment/oats-local.yaml",
|
|
1549
|
+
"before":null,"after":"private","changed":true,
|
|
1550
|
+
"launch":{"declared":null,"effective":{"harness":"claude","model":null,"launchConfig":"private"},
|
|
1551
|
+
"from":"local","at":"oats-local.yaml#/souls/launch/example.pkg~1reviewer","problem":null},
|
|
1552
|
+
"unmatched":[],"unread":null}
|
|
1553
|
+
```
|
|
1554
|
+
|
|
1555
|
+
One closed answer for `set`, `remove` and their plans.
|
|
1556
|
+
|
|
1557
|
+
- **`set`** names the soul as a spawn does (`E_SOUL_UNKNOWN`,
|
|
1558
|
+
`E_SOUL_AMBIGUOUS`) and writes the key that soul has: its bare name, or
|
|
1559
|
+
`<package>/<soul>`. `'*'` is the machine default. Exactly one of
|
|
1560
|
+
`--launch-config` and `--harness`; `--model` only with `--harness`
|
|
1561
|
+
(`E_BAD_ARGS`). Each of them is given once and with a value, and the
|
|
1562
|
+
command takes one name: a flag repeated, a flag with no value at any
|
|
1563
|
+
occurrence, and a second name are `E_BAD_ARGS`, on `remove` too.
|
|
1564
|
+
`--launch-config <name>` writes the name (`none` too) and
|
|
1565
|
+
`--harness` the inline `{harness, model?}`. A harness that is not installed
|
|
1566
|
+
is not refused: `launch.problem` says what a spawn would refuse.
|
|
1567
|
+
- **`remove`** tries its argument **first as the exact text of a key in
|
|
1568
|
+
`souls.launch`**, with no read of the workspace; otherwise it names a soul,
|
|
1569
|
+
as for `set`, and removes that soul's key. Removing the last entry removes
|
|
1570
|
+
`souls.launch`, and `souls` when that leaves it empty.
|
|
1571
|
+
- **`--plan`** runs every check and writes nothing. Its answer is the
|
|
1572
|
+
apply's with `plan: true`, and a state that refuses the apply refuses the
|
|
1573
|
+
plan with the same code. It takes no lock, so it never answers
|
|
1574
|
+
`E_LOCAL_BUSY`.
|
|
1575
|
+
- **The read.** Both forms read the workspace live: `--max-age` is refused
|
|
1576
|
+
(`E_BAD_ARGS`) with and without `--plan`, as for every write verb, and the
|
|
1577
|
+
answer never carries `observation`.
|
|
1578
|
+
|
|
1579
|
+
| Field | Meaning |
|
|
1580
|
+
|---|---|
|
|
1581
|
+
| `action` | `"set"` or `"remove"` |
|
|
1582
|
+
| `plan` | `true`: nothing was written |
|
|
1583
|
+
| `key` | the `souls.launch` key written or removed, exactly as in the file; `"*"` for the machine default |
|
|
1584
|
+
| `souls` | the qualified names of the offered souls that key applies to, sorted. More than one when two members offer a soul of that name: the entry pins all of them. `[]` for a key that is the key of no soul; `null` for `"*"` |
|
|
1585
|
+
| `level`, `file` | the deployment and its `oats-local.yaml` |
|
|
1586
|
+
| `before`, `after` | the entry: `null` (none), a string (a launch configuration's name, or `none`), or `{harness, model}` with `model` `null` when it has none |
|
|
1587
|
+
| `changed` | `false` when the file already said it: nothing was written |
|
|
1588
|
+
| `launch` | the [`Launch`](#the-launch-report-launch) report a spawn with no flags would decide for the named soul, with the file as it is after this change (as it would be, under `--plan`). After a `remove` it shows what the soul falls through to. For a key given by its exact text, the soul is the first of `souls`. `null` for `"*"` and for a key that is the key of no soul |
|
|
1589
|
+
| `unmatched` | the keys of `souls.launch` that are the key of no offered soul after this change, sorted by key: `[{key, at, value, suggestions}]`. `at` is `oats-local.yaml#/souls/launch/<key>` (JSON-pointer escaped), `value` the entry as in `before`, `suggestions` at most three offered soul keys: those with the key's bare name (the part after the last `/`) first, then those within two edits of it. `"*"` is never listed, and neither is a key the read could not check (a member unconfirmed, a soul skipped with a problem, a package declared and not locked). `[]`: no key is known to name no soul |
|
|
1590
|
+
| `unread` | `null`, or `{code, message}` when a `remove` by exact text ran although the workspace's souls could not be read |
|
|
1591
|
+
|
|
1592
|
+
- **Read `unread` first.** When it is not `null`, the answer says nothing
|
|
1593
|
+
about souls: `souls`, `launch` and `unmatched` are `null` for that reason
|
|
1594
|
+
and no other. In every other answer `unmatched` is a list, and `souls` and
|
|
1595
|
+
`launch` are `null` only as the table says.
|
|
1596
|
+
- **The write** is the one `oats teams` makes (above): one entry set or
|
|
1597
|
+
deleted in the parsed document, under
|
|
1598
|
+
`<deployment>/.agents/locks/local.lock`, from the file as it is now, redone
|
|
1599
|
+
when the file changed under it. The file is rewritten, and every other
|
|
1600
|
+
entry keeps its value and its comments. Before the rename the rewritten
|
|
1601
|
+
text is validated against the local schema and read back: it must equal
|
|
1602
|
+
the old value everywhere but the one entry.
|
|
1603
|
+
- **Refusals**, all before a byte of the file changes: `E_USAGE` (no `set` or
|
|
1604
|
+
`remove`; a flag the form does not take, `--home` and `--soul` among them,
|
|
1605
|
+
with `details: {flag}`), `E_BAD_ARGS`, `E_LOCAL_MISSING`, `E_SOUL_UNKNOWN`,
|
|
1606
|
+
`E_SOUL_AMBIGUOUS`, `E_LAUNCH_CONFIG_UNKNOWN {name, from, at}` (a
|
|
1607
|
+
`--launch-config` name this file does not declare: the fact a spawn would
|
|
1608
|
+
report, said before the file holds it), `E_LAUNCH_PREFERENCE_UNKNOWN {key,
|
|
1609
|
+
keys}` (a `remove` of an entry the file does not have; `keys` are the
|
|
1610
|
+
entries it has), `E_LOCAL_BUSY {path, lock}`, `E_LOCAL_CHANGED {path}`,
|
|
1611
|
+
`E_WORKSPACE_SCHEMA` (the rewritten file would be invalid, or the kernel
|
|
1612
|
+
would not decode it, `details: {problems}`; or it would not read back as
|
|
1613
|
+
this one edit, `details: {path,
|
|
1614
|
+
reason: "read-back", differs}` with `differs` the JSON pointers that
|
|
1615
|
+
differ, never their values), and whatever the read of the workspace
|
|
1616
|
+
answers when `set`, or a `remove` that names a soul, cannot read the souls.
|
|
1617
|
+
- Text mode says the same in lines: what was set or removed and in which
|
|
1618
|
+
file; the souls the entry applies to, when more than one; what the next
|
|
1619
|
+
spawn of that soul selects; and each key that still names no soul, with
|
|
1620
|
+
the command that removes it.
|
|
1621
|
+
|
|
1493
1622
|
### The messaging provider's teams document
|
|
1494
1623
|
|
|
1495
1624
|
The messaging provider's `teams` operation (`messaging:teams`) is produced by
|
|
@@ -1639,7 +1768,9 @@ Every object shape here is closed.
|
|
|
1639
1768
|
- **The machine** may override it in `oats-local.yaml` `souls.launch`. A key is
|
|
1640
1769
|
a soul key (as for `souls.teams`: `"*"`, a bare soul name, or
|
|
1641
1770
|
`<package>/<soul>`). A value is a `launch-configs` name in the same file, or
|
|
1642
|
-
an inline `{harness, model?}` with the soul's rules.
|
|
1771
|
+
an inline `{harness, model?}` with the soul's rules. From OATS 0.53.0 the
|
|
1772
|
+
key is written by [`oats soul launch set|remove`](#oats-soul-launch)
|
|
1773
|
+
(feature `soul-launch`).
|
|
1643
1774
|
```yaml
|
|
1644
1775
|
souls:
|
|
1645
1776
|
launch:
|
|
@@ -1678,24 +1809,110 @@ a running or existing home until `--reselect-launch` or a respawn.** Readiness
|
|
|
1678
1809
|
shows the drift as `launch-changed`.
|
|
1679
1810
|
|
|
1680
1811
|
**Refusals** (spawn, preview, and a reselecting start):
|
|
1812
|
+
- `E_LAUNCH_PREFERENCE_UNMATCHED {soul, from, at, keys, fix}` (0.53): the
|
|
1813
|
+
launch names none (no `--launch-config`, no `--harness`; `--model` alone
|
|
1814
|
+
names none), its soul has no `souls.launch` entry of its own, and
|
|
1815
|
+
`souls.launch` holds a key that is the key of no soul the workspace offers.
|
|
1816
|
+
The kernel cannot tell which soul that key was meant to pin, so the launch
|
|
1817
|
+
the fall-through would decide is refused. It is checked before the three
|
|
1818
|
+
refusals below, which describe that fall-through launch. Refused: `oats
|
|
1819
|
+
spawn`, preview and apply, with the same code and `details`, and `session
|
|
1820
|
+
start|restart --reselect-launch`, before anything is created, stopped or
|
|
1821
|
+
started. A soul with its own entry, a launch named by a flag, and a plain
|
|
1822
|
+
start or restart go on.
|
|
1823
|
+
- `soul`: the soul key of the launch refused. `from`, `at`: the layer that
|
|
1824
|
+
would have decided it (`"local-default"`, `"soul"` or `"host"`; `at` as
|
|
1825
|
+
in the `Launch` report, `null` for the host).
|
|
1826
|
+
- `keys`: every such key, sorted by key, `[{key, at, value,
|
|
1827
|
+
suggestions}]`, the rows of `unmatched` in
|
|
1828
|
+
[`oats soul launch`](#oats-soul-launch). A client builds the two
|
|
1829
|
+
commands from `key` and `value`; it does not parse the sentence.
|
|
1830
|
+
- `fix`: "pin the soul each key was meant for (oats soul launch set), then
|
|
1831
|
+
remove the key (oats soul launch remove <key>); or name this launch with
|
|
1832
|
+
--launch-config <name> or --harness <h>". The order is `set`, then
|
|
1833
|
+
`remove`: removing first ends the refusal and leaves the soul on the
|
|
1834
|
+
fall-through.
|
|
1835
|
+
- The message names at most three keys, then "and K more", and it and
|
|
1836
|
+
`fix` are at most 1024 characters each, with no line break, whatever the
|
|
1837
|
+
file holds. `keys` is complete.
|
|
1838
|
+
- No text of a launch answer holds a character the kernel never prints (a
|
|
1839
|
+
control character, a line or paragraph separator, a bidi control, an
|
|
1840
|
+
invisible hider, a tag character): a refusal's `message` and `fix`, a
|
|
1841
|
+
report's `problem`, a problems row. The schema of `oats-local.yaml`
|
|
1842
|
+
admits no key with one, so the file brings none. Were one handed to an
|
|
1843
|
+
answer all the same, the sentence names it with each such character
|
|
1844
|
+
replaced by U+FFFD and gives no command for it: it says the key is
|
|
1845
|
+
deleted from `souls.launch` in the file by hand. `keys[].key` is always
|
|
1846
|
+
the exact key.
|
|
1847
|
+
- **Unmatched, or not checked.** A key other than `"*"` matches when an
|
|
1848
|
+
offered soul has that soul key (a soul in `souls.disabled` included).
|
|
1849
|
+
A key that matches nothing is *not checked*, and refuses nothing, when
|
|
1850
|
+
the source that could hold its soul was not read: a bare key while a
|
|
1851
|
+
member is not confirmed or a member's or an external soul was skipped
|
|
1852
|
+
with a problem; `<package>/…` while that package is declared and not
|
|
1853
|
+
locked, or one of its souls was skipped; every key in the standalone
|
|
1854
|
+
view of a workspace whose host cannot be read. What a read did not
|
|
1855
|
+
record, it did not establish: a read that carries no record of what it
|
|
1856
|
+
skipped leaves every key not checked, and a member whose listing carries
|
|
1857
|
+
none counts as one with a soul skipped. Every other key that
|
|
1858
|
+
matches nothing is unmatched, `<member>/<soul>` among them (a member's
|
|
1859
|
+
soul is keyed by its bare name). When the workspace cannot be read at
|
|
1860
|
+
all, the answer is that read's own error. `"*"` is never reported.
|
|
1861
|
+
- **Where else it is said.** `oats souls` and `inspect --soul`: `launch.problem`
|
|
1862
|
+
on each soul a spawn would refuse, and `oats souls` `problems` gains one
|
|
1863
|
+
row per key (below). `oats doctor`, offline, from this machine's cache:
|
|
1864
|
+
`problems[]` gains `{code, key, at, value, suggestions, message,
|
|
1865
|
+
remedy}` per key (text: `! <code>: <message>`, then the remedy), whose
|
|
1866
|
+
message says that it speaks about this machine's last read of the souls
|
|
1867
|
+
and that a spawn reads the workspace itself and is the authority. For a
|
|
1868
|
+
key that read could not check, and when the cache cannot answer, doctor
|
|
1869
|
+
adds an `information[]` line that starts `launch-preference-unchecked:`.
|
|
1870
|
+
The line is information: it changes no exit status and refuses nothing.
|
|
1871
|
+
`inspect --home` `launchCurrent` and readiness `launch-changed` make no
|
|
1872
|
+
read of the workspace and do not carry this problem; the
|
|
1873
|
+
`--reselect-launch` they point to refuses.
|
|
1681
1874
|
- `E_HARNESS_UNAVAILABLE {harness, from, at, fix}`: the chosen harness has no
|
|
1682
1875
|
executable on this machine. There is no fallback to another harness. `fix`
|
|
1683
|
-
|
|
1684
|
-
|
|
1685
|
-
|
|
1686
|
-
|
|
1876
|
+
names the command that pins the soul (0.53), by the layer that chose the
|
|
1877
|
+
harness:
|
|
1878
|
+
- the soul's own `launch:` or the host default: "install <harness>, or pin
|
|
1879
|
+
this soul on this machine (oats soul launch set <soul> --launch-config
|
|
1880
|
+
<name> | --harness <h>)";
|
|
1881
|
+
- the soul's own entry of `souls.launch`: "install <harness>, or pin this
|
|
1882
|
+
soul to another launch (oats soul launch set <soul> --launch-config <name>
|
|
1883
|
+
| --harness <h>)";
|
|
1884
|
+
- `souls.launch."*"`: "install <harness>, name another launch for every soul
|
|
1885
|
+
without an entry (oats soul launch set '*' --launch-config <name> |
|
|
1886
|
+
--harness <h>), or pin this soul to its own (oats soul launch set <soul>
|
|
1887
|
+
--launch-config <name> | --harness <h>)";
|
|
1888
|
+
- a flag: "install <harness>, or choose another --harness / --launch-config".
|
|
1889
|
+
|
|
1890
|
+
The message says why, names the layer's location (`at`) and ends with the
|
|
1891
|
+
`fix`. It stays within 1024 characters: a location too long for that gives
|
|
1892
|
+
way to the layer in words ("the soul's own launch", for example), and
|
|
1893
|
+
`details.at` keeps it.
|
|
1687
1894
|
- `E_LAUNCH_CONFIG_UNKNOWN {name, from, at}`: `souls.launch` names a launch
|
|
1688
|
-
configuration this `oats-local.yaml` does not declare.
|
|
1895
|
+
configuration this `oats-local.yaml` does not declare. As a `Launch`
|
|
1896
|
+
report's `problem`, its `fix` is "declare launch configuration <name> (oats
|
|
1897
|
+
launch-config set), or pin the soul to another (oats soul launch set <soul>
|
|
1898
|
+
--launch-config <name>)"; where `souls.launch."*"` named it, "declare launch
|
|
1899
|
+
configuration <name> (oats launch-config set), name another for every soul
|
|
1900
|
+
without an entry (oats soul launch set '*' --launch-config <name>), or pin
|
|
1901
|
+
the soul to one (oats soul launch set <soul> --launch-config <name>)".
|
|
1689
1902
|
- `E_LAUNCH_CONFIG_AMBIGUOUS {harness, configurations, fix}` (spawn and its
|
|
1690
1903
|
preview only, 0.52): the chosen harness has more than one launch
|
|
1691
1904
|
configuration here (`configurations`, all their names, sorted; the message
|
|
1692
|
-
names the first 10, then "and K more",
|
|
1905
|
+
names the first 10, then "and K more", and fewer where it would otherwise
|
|
1906
|
+
pass 1024 characters),
|
|
1693
1907
|
none is
|
|
1694
1908
|
`default: true`, and the spawn named none. Named means `--launch-config
|
|
1695
1909
|
<name>`, `--launch-config none`, or a `souls.launch` string; an inline or
|
|
1696
1910
|
soul preference and `--harness` alone are not. `fix` is "name one with
|
|
1697
|
-
--launch-config <name
|
|
1698
|
-
|
|
1911
|
+
--launch-config <name>, pin the soul to one (oats soul launch set <soul>
|
|
1912
|
+
--launch-config <name>), or mark one default: true (oats launch-config
|
|
1913
|
+
set)"; where `souls.launch."*"` chose the harness it also says, before the
|
|
1914
|
+
soul's own pin, "name one for every soul without an entry (oats soul launch
|
|
1915
|
+
set '*' --launch-config <name>)". A start or restart of an existing
|
|
1699
1916
|
home, `--reselect-launch` included, is never refused this way.
|
|
1700
1917
|
- `E_WORKSPACE_SCHEMA`: a malformed `launch` or `souls.launch`, path named.
|
|
1701
1918
|
|
|
@@ -1720,10 +1937,18 @@ shows the drift as `launch-changed`.
|
|
|
1720
1937
|
`"oats-local.yaml#/souls/launch/*"`, `"<repoKey>:<path>/soul.yaml#/launch"`,
|
|
1721
1938
|
or `"package:<id>:<path>/soul.yaml#/launch"`.
|
|
1722
1939
|
- `problem`: `null`, or `{code, message, fix}` when a spawn would refuse
|
|
1723
|
-
(`
|
|
1940
|
+
(`E_LAUNCH_PREFERENCE_UNMATCHED`, before any other, with `effective` the
|
|
1941
|
+
launch the fall-through would have given; `E_HARNESS_UNAVAILABLE`,
|
|
1942
|
+
`E_LAUNCH_CONFIG_UNKNOWN`,
|
|
1724
1943
|
`E_LAUNCH_CONFIG_AMBIGUOUS` with `effective.launchConfig` `null`, or
|
|
1725
1944
|
`E_LAUNCH_EXECUTABLE` for a configuration whose own executable is missing). Only reports carry it;
|
|
1726
|
-
spawn and preview refuse instead.
|
|
1945
|
+
spawn and preview refuse instead. A `fix`, here and in a refusal's
|
|
1946
|
+
`details`, is a sentence for a person: its wording may change between
|
|
1947
|
+
releases, so a client shows it and never parses it. A report states a
|
|
1948
|
+
condition, where a refusal states what was refused: for
|
|
1949
|
+
`E_LAUNCH_PREFERENCE_UNMATCHED` the report's `message` names the keys and
|
|
1950
|
+
the layer that would decide, and ends "it would be refused."; it does not
|
|
1951
|
+
repeat the remedy, which is its `fix` (the refusal's `details.fix`). With `E_LAUNCH_CONFIG_UNKNOWN`,
|
|
1727
1952
|
`effective` is the host default (`pi`, `null`, `null`): the named
|
|
1728
1953
|
configuration launches nothing here.
|
|
1729
1954
|
- In listings (`oats souls`, `inspect --soul`, `launchCurrent`) `model` is the
|
|
@@ -2405,6 +2630,10 @@ its absence.
|
|
|
2405
2630
|
`soulSource` (`{repoKey, commit, path, current?, status?}`, `current` or
|
|
2406
2631
|
`moved`) for a workspace soul; `retireFailures[]` (`{instance, completedAt,
|
|
2407
2632
|
error, incomplete, retry, resultPath}`) when a deferred self-retire failed.
|
|
2633
|
+
An entry stays until a retire of the instance completes or its result
|
|
2634
|
+
file is removed by hand, whether or not the instance's row still has
|
|
2635
|
+
`retirePending`
|
|
2636
|
+
([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
|
|
2408
2637
|
A capability agent's row is `{name, kind: "capability", capability,
|
|
2409
2638
|
description, dir, instances}`.
|
|
2410
2639
|
- **Instance rows**: the home's `instance.json` (launch recipe and command
|
|
@@ -2791,6 +3020,19 @@ that name: `E_AMBIGUOUS_INSTANCE {candidates: [{root, agent, home}]}` (pass
|
|
|
2791
3020
|
`--home`; a wrong one is `E_HOME_MISMATCH`). Unknown: `E_SESSION_UNKNOWN`. No
|
|
2792
3021
|
tree: `E_NO_WORKTREE`.
|
|
2793
3022
|
|
|
3023
|
+
`E_NO_WORKTREE` is answered when nothing is at `<home>/work`, when it is not
|
|
3024
|
+
inside a Git work tree, and (0.53.0, #962) when it is a real directory that
|
|
3025
|
+
is not the top level Git names for it. Git answers for any directory inside
|
|
3026
|
+
a work tree, so a plain `work/` in a home whose deployment directory is a
|
|
3027
|
+
Git checkout was read as that checkout before: its branch and its files,
|
|
3028
|
+
none of them the instance's. The rule is the path, in every work mode: a
|
|
3029
|
+
`directory` instance in such a deployment has no work tree, and one whose
|
|
3030
|
+
`work/` is the top level of a repository of its own is observed as before.
|
|
3031
|
+
A `work/` that is a link is read as what it leads to, wherever that is: a
|
|
3032
|
+
`workspace` instance's leads to the deployment directory, which is above its
|
|
3033
|
+
home, and is observed as before. A [stop plan](#stop)'s and a
|
|
3034
|
+
[retire plan](#retire)'s `work` read the same way, with the code as `reason`.
|
|
3035
|
+
|
|
2794
3036
|
```json
|
|
2795
3037
|
{"instanceGitApi":1,"instance":"dev-1","agent":"dev","home":"/w/agents/dev/instances/dev-1","workMode":"worktree",
|
|
2796
3038
|
"observation":{"revision":"46c20668…","indexRevision":"3147fef2…","at":"2026-09-26T18:15:26.487Z","worktree":"/w/agents/dev/instances/dev-1/work",
|
|
@@ -2875,7 +3117,8 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
2875
3117
|
bytes}`. Only a regular file is opened (no symlinks, same device and inode
|
|
2876
3118
|
after open), and at most its last 4 MiB is read (`"tail"`).
|
|
2877
3119
|
- **Kinds:** `spawned`, `launched`, `restarted`, `stopped`, `stop-refused`,
|
|
2878
|
-
`retire-planned`, `retired`, `
|
|
3120
|
+
`retire-planned`, `retired`, `retire-refused` (0.53.0,
|
|
3121
|
+
[below](#retire-refused-event)), `worktree-retained`, `worktree-removed`,
|
|
2879
3122
|
`branch-deleted` (not written since 0.41.0: no retire deletes a branch;
|
|
2880
3123
|
older logs hold it), `child-spawn-refused`, `launch-warning` (0.30: a
|
|
2881
3124
|
`launch` hook's warning at session start/restart, `data: {message}`),
|
|
@@ -2905,6 +3148,34 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
2905
3148
|
`--delete-branch` (since 0.41.0: `this self-retire was requested with
|
|
2906
3149
|
--delete-branch by an older OATS; retirement no longer deletes branches, so
|
|
2907
3150
|
the branch and the worktree were left`).
|
|
3151
|
+
- <a id="retire-refused-event"></a>`retire-refused` (0.53.0; `data: {code,
|
|
3152
|
+
homeChanged, reason}`) is written once by the completion of a scheduled
|
|
3153
|
+
self-retire (`oats retire <instance> --self`) that did not complete, and
|
|
3154
|
+
by nothing else. A retire that a person runs answers that person and
|
|
3155
|
+
writes none. No feature names the kind: a client that does not know it
|
|
3156
|
+
reads the row as it reads any unknown kind.
|
|
3157
|
+
- `code` is a kernel code, or `null`. It is the code the retire answered.
|
|
3158
|
+
It is `null` for the one outcome that is a result and not an error: a
|
|
3159
|
+
cleanup that did not finish, with the home retained in quarantine.
|
|
3160
|
+
`null` means that outcome, never "unknown".
|
|
3161
|
+
- `homeChanged` is `false` when no retire hook was started and nothing of
|
|
3162
|
+
the home was removed, and `true` otherwise. It is always `true` for the
|
|
3163
|
+
incomplete cleanup. A session or a child that was stopped on the way
|
|
3164
|
+
does not count.
|
|
3165
|
+
- `reason` is the sentence the retire answered, on one line and at most
|
|
3166
|
+
2048 UTF-16 code units. A longer sentence is cut and ends with `…`,
|
|
3167
|
+
which is counted in the 2048. The bound is the Desktop events reader's,
|
|
3168
|
+
which refuses a whole read that holds a longer detail. For the
|
|
3169
|
+
incomplete cleanup it is a sentence of the kernel's own that names no
|
|
3170
|
+
item; the items are in the completion's result file.
|
|
3171
|
+
- The row is in the workspace's log only, and carries the incarnation
|
|
3172
|
+
the home had before the retire ran. The completion holds no claim when
|
|
3173
|
+
it writes, so it writes nothing into a home.
|
|
3174
|
+
- With `homeChanged: false` the self-retire's pending marker is gone as
|
|
3175
|
+
well, and with `true` it stays
|
|
3176
|
+
([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
|
|
3177
|
+
- `stop-refused` and `retire-refused` each cover two cases: a verb that was
|
|
3178
|
+
refused, and one that failed after it began.
|
|
2908
3179
|
- `worktree-retained` (`data: {movedTo, branch, recordedBranch}`) and
|
|
2909
3180
|
`worktree-removed` (`data: {branch}`) are written to the workspace log only,
|
|
2910
3181
|
by the retire's worktree step. Since 0.42.1 the retire also writes one per
|
|
@@ -3167,16 +3438,22 @@ oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>]
|
|
|
3167
3438
|
what failed (`E_SESSION_UNAVAILABLE` for an error that has none).
|
|
3168
3439
|
- `work` is the Git observation summarized (`changed` counts changed,
|
|
3169
3440
|
renamed, copied and unmerged rows), or `{observed: false, reason}`:
|
|
3170
|
-
`"no-worktree"
|
|
3171
|
-
|
|
3172
|
-
|
|
3173
|
-
|
|
3441
|
+
`"no-worktree"` when nothing is at `work/`, or the kernel code of what
|
|
3442
|
+
failed (`E_NO_WORKTREE` for a `work/` that is no work tree of the
|
|
3443
|
+
instance's, as [`oats instance git`](#git-and-diff) answers it;
|
|
3444
|
+
`E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
|
|
3445
|
+
a home the kernel cannot look into, where whether it has a `work/` cannot
|
|
3446
|
+
be told; OATS 0.52.0).
|
|
3174
3447
|
- `midTask`: `true`, `false` or `"unknown"`.
|
|
3175
3448
|
- `retiring` and `stopPending`, booleans on every target, say who holds the
|
|
3176
3449
|
target's home when the plan is read (OATS 0.52.0, feature
|
|
3177
3450
|
`lifecycle-claim-stop`). `retiring`: a self-retire is scheduled for it
|
|
3178
3451
|
(its pending marker is there), or a retire holds its
|
|
3179
|
-
[claim](#retire-one-at-a-time).
|
|
3452
|
+
[claim](#retire-one-at-a-time). From 0.53.0 the marker outlasts a
|
|
3453
|
+
completion that did not complete only when a retire hook was started or
|
|
3454
|
+
the removal of the home began
|
|
3455
|
+
([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
|
|
3456
|
+
`stopPending`: a stop apply holds its
|
|
3180
3457
|
claim. A holder counts while it is not known to be gone: alive, or of a
|
|
3181
3458
|
liveness that cannot be read. `retiring` is one of the facts
|
|
3182
3459
|
`planRevision` is hashed from, as it was; `stopPending` is not. The
|
|
@@ -3215,12 +3492,17 @@ this order:
|
|
|
3215
3492
|
retire answers it: `E_INSTANCE_RETIRING` beside a retire,
|
|
3216
3493
|
`E_LIFECYCLE_BUSY` beside another stop
|
|
3217
3494
|
([Commands that meet on one home](#lifecycle-pairs)). A stop never waits
|
|
3218
|
-
for a holder.
|
|
3495
|
+
for a holder. A claim that cannot be written is
|
|
3496
|
+
[read in its place](#stop-claim-write) (OATS 0.53.0): whoever holds it
|
|
3497
|
+
is answered the same way, here.
|
|
3219
3498
|
5. It reads the plan again, under the claims: this is the plan it acts on.
|
|
3220
3499
|
**It holds the claim of every target of this plan before it does
|
|
3221
3500
|
anything.** A target it does not hold yet (a child recorded, or readable
|
|
3222
3501
|
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
|
|
3502
|
+
every claim released first so that the order of step 4 holds. A target
|
|
3503
|
+
whose claim was only read counts as held for this, and its claim is
|
|
3504
|
+
read once more now, before the comparison below: a holder that came
|
|
3505
|
+
since is answered as in step 4. A stop
|
|
3224
3506
|
whose targets are others under each of three such reads (a constant of
|
|
3225
3507
|
the kernel: there is no setting for it) gives up:
|
|
3226
3508
|
`E_LIFECYCLE_BUSY`, `holder: "none"`, `… nothing was stopped — run the
|
|
@@ -3253,16 +3535,108 @@ once it holds the claim; a removal that fails is a warning on stderr (`oats:
|
|
|
3253
3535
|
warning: …`, in both modes) and the stop goes on.
|
|
3254
3536
|
|
|
3255
3537
|
<a id="stop-claim-write"></a>
|
|
3256
|
-
**A stop
|
|
3257
|
-
|
|
3258
|
-
|
|
3259
|
-
`
|
|
3260
|
-
|
|
3261
|
-
|
|
3262
|
-
|
|
3263
|
-
|
|
3264
|
-
|
|
3265
|
-
|
|
3538
|
+
**A stop whose claim cannot be written reads it instead** (OATS 0.53.0;
|
|
3539
|
+
#946). Stop is what a person reaches for when a disk is full, and a stop
|
|
3540
|
+
that leaves a session running because it could not write a file protects
|
|
3541
|
+
nobody. So `oats instance stop --apply`, and it alone, reads a claim it
|
|
3542
|
+
cannot write, for a reason that stops every other writer of this user as
|
|
3543
|
+
well, and goes on when nobody holds it. It holds nothing for that target,
|
|
3544
|
+
and says so on stderr. A retire, and a retire's stop of a recorded child,
|
|
3545
|
+
need their claim as before.
|
|
3546
|
+
|
|
3547
|
+
The reasons are five codes of the system's, met at one of the claim's
|
|
3548
|
+
writes (its directory, its file, and the same two of a takeover's own
|
|
3549
|
+
claim):
|
|
3550
|
+
|
|
3551
|
+
| The system's code | It means |
|
|
3552
|
+
|---|---|
|
|
3553
|
+
| `ENOSPC` | the file system is full |
|
|
3554
|
+
| `EDQUOT` | this user's quota is spent |
|
|
3555
|
+
| `EROFS` | the file system is read-only |
|
|
3556
|
+
| `EACCES`, `EPERM` | the claims directory is not writable by this user |
|
|
3557
|
+
|
|
3558
|
+
Each is in the list for one reason: what stops this stop from writing a
|
|
3559
|
+
claim in that directory stops a retire or another stop of the same user as
|
|
3560
|
+
well, so a claim that reads as held by nobody is held by nobody. `EACCES`
|
|
3561
|
+
and `EPERM` are there because every instance of a deployment can change the
|
|
3562
|
+
claims directory, and one that takes write permission from it must not take
|
|
3563
|
+
Stop from the operator. On a shared deployment that is the likely case of a
|
|
3564
|
+
warning below, and its cure is to fix the directory's permissions, not to
|
|
3565
|
+
live with the warning. Any other code (`EIO`, `EMFILE`, `EEXIST` from a
|
|
3566
|
+
file where the directory belongs) says nothing about who else could write
|
|
3567
|
+
there, and is refused as in 0.52.0: `E_LIFECYCLE_FAILED`, `the claim <lock>
|
|
3568
|
+
could not be taken (<the system's error>); nothing was done`, with the
|
|
3569
|
+
system's code in [`details.cause`](#kernel-codes) and the plan it read in
|
|
3570
|
+
`details.plan`; nothing was signalled.
|
|
3571
|
+
|
|
3572
|
+
**What the read answers** is what the taking would have answered for what
|
|
3573
|
+
is at the claim's path, with one difference:
|
|
3574
|
+
|
|
3575
|
+
- **Nobody holds it** (no file there; or a holder that is verifiably gone,
|
|
3576
|
+
whose claim a command that can write would take over): the stop goes on.
|
|
3577
|
+
This is the difference: the dead holder's file is left as it is, for the
|
|
3578
|
+
next command that can write to take over.
|
|
3579
|
+
- **A holder that is alive, or whose liveness cannot be read, and a file
|
|
3580
|
+
that is no readable claim:** the cell of
|
|
3581
|
+
[the pair table](#lifecycle-pairs) for an arriving stop, with the same
|
|
3582
|
+
sentence and the same `details`. Nothing was signalled.
|
|
3583
|
+
- **A file of a gone holder that no kernel can take over** (no `nonce` of a
|
|
3584
|
+
claim's shape): `E_LIFECYCLE_BUSY`, `holder: "none"`, as for a stop that
|
|
3585
|
+
can write. Its message says to inspect the file and remove it. On a full
|
|
3586
|
+
disk that removal works; in a directory that is not writable the person
|
|
3587
|
+
has to make it writable first.
|
|
3588
|
+
- **The claim cannot be read either** (its path cannot be reached): the
|
|
3589
|
+
`E_LIFECYCLE_FAILED` of the write, as above. The read is positive or it
|
|
3590
|
+
is nothing.
|
|
3591
|
+
|
|
3592
|
+
The read is made twice: where the claim would have been taken (step 4), and
|
|
3593
|
+
again once the plan has been read under the claims (step 5), before the
|
|
3594
|
+
revision is compared. A holder that came in between is answered there,
|
|
3595
|
+
before a stale plan and before any signal, with the fresh plan in
|
|
3596
|
+
`details.plan`.
|
|
3597
|
+
|
|
3598
|
+
**What it gives up.** Nothing on the home shows this stop: a plan read
|
|
3599
|
+
meanwhile says `stopPending: false`, and a retire or a stop that starts
|
|
3600
|
+
while it runs, and that can write its claim, is not refused. That is space
|
|
3601
|
+
freed a moment later, or a process of another user, for whom the directory
|
|
3602
|
+
is writable. The two commands then work in one home at once, as every stop
|
|
3603
|
+
did before 0.52.0. The warning says it, one line per such target, on stderr
|
|
3604
|
+
in text and in JSON mode:
|
|
3605
|
+
|
|
3606
|
+
```text
|
|
3607
|
+
oats: warning: <instance>: stopping without its claim: <lock> could not be written (<CODE>), and nobody holds it. A retire or a stop of <instance> that starts while this one runs will not see it.
|
|
3608
|
+
```
|
|
3609
|
+
|
|
3610
|
+
`<lock>` is the claim's own path and `<CODE>` the system's code, never its
|
|
3611
|
+
message. It is printed only when the apply answers a receipt, also for a
|
|
3612
|
+
target whose row is `alreadyIdle`, and never for a replay, which takes no
|
|
3613
|
+
claim. It is not part of the receipt, whose fields and values are those of
|
|
3614
|
+
any stop. **With `--server` the warning does not reach the caller:** the
|
|
3615
|
+
router keeps a remote command's stderr only when the command fails, as for
|
|
3616
|
+
every warning of a stop (#952).
|
|
3617
|
+
|
|
3618
|
+
**On a full disk the stop cannot write into the home either.** The session
|
|
3619
|
+
is stopped, and the apply answers its receipt (exit 0 in JSON mode) with
|
|
3620
|
+
that target's row `ok: false`, `E_SESSION_STOP_FAILED`, a `message` that
|
|
3621
|
+
ends `its harness was signalled (SIGTERM) and has exited`, and
|
|
3622
|
+
[`stillRunning: []`](#still-running): the row of a stop in a home that
|
|
3623
|
+
cannot be written, as it was. Read `stillRunning`, not `ok`: `[]` says
|
|
3624
|
+
stopped. Text mode prints that row, closes with `the stop did not complete
|
|
3625
|
+
its record; nothing is still running`, and exits 1, as for any target that
|
|
3626
|
+
failed. The receipt cannot be stored either, so **its key cannot be
|
|
3627
|
+
replayed**: the same apply again runs, and is answered `E_PLAN_STALE` with
|
|
3628
|
+
the fresh plan, in which the session is stopped; an apply with that plan's
|
|
3629
|
+
revision answers `alreadyIdle`, and prints the warning again. Such a stop
|
|
3630
|
+
leaves nothing of its own in the home: the private file each of the two
|
|
3631
|
+
writes goes through (`.oats-stop.json.tmp-<pid>`,
|
|
3632
|
+
`.oats-stop-receipt.<key>.json.<pid>.tmp`) is removed when its write or its
|
|
3633
|
+
rename fails. Before 0.53.0 each apply on a full disk left both there,
|
|
3634
|
+
empty.
|
|
3635
|
+
|
|
3636
|
+
In 0.52.0 a stop whose claim could not be written for one of those five
|
|
3637
|
+
codes was refused like the others, before anything was signalled
|
|
3638
|
+
(`E_LIFECYCLE_FAILED`). Before 0.52.0 a stop took no claim: it wrote its
|
|
3639
|
+
marker if it could and signalled the harness either way.
|
|
3266
3640
|
|
|
3267
3641
|
Two kernel versions acting on one deployment at once are not covered: a
|
|
3268
3642
|
kernel before 0.52.0 takes no claim for a stop and does not read a stop's
|
|
@@ -3304,7 +3678,14 @@ in flight.
|
|
|
3304
3678
|
defect's stack is printed on stderr; a stop that fails on a refusal without
|
|
3305
3679
|
a code (a `tmux` command that failed) is that row and prints no stack. The
|
|
3306
3680
|
same holds for a child's stop in a retire's `childrenStopped`.
|
|
3307
|
-
- `ok: false`: at least one target
|
|
3681
|
+
- `ok: false`: at least one target's row is not `ok` (text mode exits 1).
|
|
3682
|
+
Whether something still runs is each such row's `stillRunning`, and the
|
|
3683
|
+
sentence text mode closes with follows it: `some targets are still
|
|
3684
|
+
running; nothing was escalated` when one of those rows names a process or
|
|
3685
|
+
establishes nothing (`null`, or no `stillRunning` in the row), and `the
|
|
3686
|
+
stop did not complete its record; nothing is still running` when every
|
|
3687
|
+
one of them says `[]` (from 0.53.0; before, the first sentence closed
|
|
3688
|
+
every such answer).
|
|
3308
3689
|
- A replay is the stored receipt (`<home>/.oats-stop-receipt.<key>.json`)
|
|
3309
3690
|
with `replayed: true`, and it follows the same rules as a first answer. The
|
|
3310
3691
|
file a kernel with feature `lifecycle-kernel-codes` stores says so in a
|
|
@@ -3334,7 +3715,8 @@ in flight.
|
|
|
3334
3715
|
that is not the kernel's; with [`details.cause`](#kernel-codes) when it has
|
|
3335
3716
|
a code of its own or is a defect, and without it when it is a refusal
|
|
3336
3717
|
without a code; among them a claim that cannot be taken for a reason of
|
|
3337
|
-
the system's
|
|
3718
|
+
the system's other than [the five a stop reads it for](#stop-claim-write):
|
|
3719
|
+
`the claim <path> could not be taken (…); nothing was done`).
|
|
3338
3720
|
A stop never answers `E_WORK_INSPECTION_FAILED`.
|
|
3339
3721
|
|
|
3340
3722
|
<a id="lifecycle-pairs"></a>
|
|
@@ -3346,22 +3728,27 @@ Each cell is the answer of the command that **arrives**. It is given at once
|
|
|
3346
3728
|
and before any effect: that command stopped, ran, copied, made and removed
|
|
3347
3729
|
nothing, and the command already on the home is not disturbed.
|
|
3348
3730
|
|
|
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 |
|
|
3731
|
+
| On the home ↓ / arrives → | `oats retire` | `oats instance stop --apply` | `oats instance stop --apply` that cannot write its claim | `oats worktree add` |
|
|
3732
|
+
|---|---|---|---|---|
|
|
3733
|
+
| a retire is running | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
|
|
3734
|
+
| a self-retire is scheduled | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
|
|
3735
|
+
| a stop apply is running | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
|
|
3736
|
+
| a retire whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
|
|
3737
|
+
| a stop whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
|
|
3738
|
+
| the claim file is no readable claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
|
|
3739
|
+
| the holder of the claim is gone | not refused | not refused | not refused | not refused |
|
|
3358
3740
|
|
|
3359
3741
|
- **A holder is answered before a stale plan, by both verbs.** A guarded
|
|
3360
3742
|
retire and a stop apply compare the revision they were sent only once
|
|
3361
3743
|
they hold the claim, so beside a holder the answer is the cell above
|
|
3362
3744
|
whatever the plan would read by then.
|
|
3363
3745
|
- **A scheduled self-retire holds no claim** until its completion runs: it
|
|
3364
|
-
is its pending marker.
|
|
3746
|
+
is its pending marker. The row lasts as long as the marker does: until
|
|
3747
|
+
the completion has retired the home, or, from 0.53.0, until a completion
|
|
3748
|
+
that did not complete has removed it, which it does unless it started a
|
|
3749
|
+
retire hook or began the removal of the home
|
|
3750
|
+
([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
|
|
3751
|
+
A retire reads the marker under the claim, while
|
|
3365
3752
|
the completion lives (`E_LIFECYCLE_BUSY`, [below](#retire-one-at-a-time)).
|
|
3366
3753
|
A stop apply reads it in the plan it makes under its claims: a plan that
|
|
3367
3754
|
showed `retiring: true` is answered `E_INSTANCE_RETIRING`, and an apply
|
|
@@ -3387,6 +3774,13 @@ nothing, and the command already on the home is not disturbed.
|
|
|
3387
3774
|
`E_LIFECYCLE_BUSY`, `holder: "none"`, with `run the command again`.
|
|
3388
3775
|
- **A stop does not refuse a `worktree add`:** a tree does not depend on the
|
|
3389
3776
|
session.
|
|
3777
|
+
- **A stop apply that cannot write its claim**
|
|
3778
|
+
([it reads it instead](#stop-claim-write), OATS 0.53.0) is answered as
|
|
3779
|
+
the stop that can, cell for cell. Beside a holder that is gone it stops
|
|
3780
|
+
like the other, and leaves that holder's file as it is: it takes nothing
|
|
3781
|
+
over. As a command already on the home it has no row: it holds nothing,
|
|
3782
|
+
so nothing on the home shows it, and no command that arrives is refused
|
|
3783
|
+
by it.
|
|
3390
3784
|
- `--plan` of either verb takes no claim and is never refused by one; a
|
|
3391
3785
|
stop plan reports the holder (`retiring`, `stopPending`). `oats worktree
|
|
3392
3786
|
remove` does not read the home's claim. `oats session start` and `restart`
|
|
@@ -3567,7 +3961,7 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
3567
3961
|
"facts":{"session":{"state":"shell","present":true,"backend":"tmux","established":true},
|
|
3568
3962
|
"work":{"observed":true,"revision":"46c20668…","branch":"feat/x","detached":false,"drift":true,"changed":0,"untracked":1,
|
|
3569
3963
|
"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",
|
|
3964
|
+
"workMode":"worktree","ownWorktree":true,"repo":"/w/one","recordedBranch":"agents/dev-1",
|
|
3571
3965
|
"children":[{"instance":"dev-1-child","agent":"dev","home":"/w/agents/dev/instances/dev-1-child","session":{"state":"shell","present":true,"backend":"tmux","established":true}}],
|
|
3572
3966
|
"ambiguous":[],"pullRequest":"unknown",
|
|
3573
3967
|
"extraWorktrees":[{"path":"/w/agents/dev/instances/dev-1/.work-docs","repo":"/w/docs","branch":"agents/dev-1-docs","detachedAt":null,
|
|
@@ -3579,12 +3973,198 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
3579
3973
|
- `facts.session` and `facts.work` read as a [stop plan](#stop)'s
|
|
3580
3974
|
`session` and `work`. Work that was not observed is `{observed: false,
|
|
3581
3975
|
reason}`: `"no-worktree"`, or the kernel code of what failed
|
|
3582
|
-
(`
|
|
3976
|
+
(`E_NO_WORKTREE` for a `work/` that is no work tree of the instance's;
|
|
3977
|
+
`E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
|
|
3583
3978
|
a home the kernel cannot look into, where whether it has a `work/` cannot be
|
|
3584
|
-
told; OATS 0.52.0).
|
|
3979
|
+
told; OATS 0.52.0). `facts.work` never reads a checkout that encloses the
|
|
3980
|
+
home as the instance's work (0.53.0, #962).
|
|
3585
3981
|
- The plan changes nothing except appending a `retire-planned` event to the
|
|
3586
3982
|
workspace log. `pullRequest` is always `"unknown"`. Branch actions use the
|
|
3587
3983
|
worktree's branch, never `recordedBranch`.
|
|
3984
|
+
- `facts.ownWorktree` (0.53.0, #988, feature `retire-plan-own-worktree`) is
|
|
3985
|
+
a fact: a boolean, `true` exactly when `work/` is the instance's own work
|
|
3986
|
+
tree, the one this retire retains (moved, as described below) or removes
|
|
3987
|
+
(`--discard-worktree`), and `false` for every other home. It is always
|
|
3988
|
+
present and never `null`. It is the answer of the one reading of `work/`
|
|
3989
|
+
that the retire acts on (below), so it is `true` in `worktree` mode with
|
|
3990
|
+
the instance's tree at `work/` (and, by the record, with nothing at
|
|
3991
|
+
`work/`: the retire then finds its tree absent), and for a record with no
|
|
3992
|
+
work mode whose `work/` Git confirms is a registered linked worktree
|
|
3993
|
+
(#962). It is `false` for a directory instance; for an attached, a
|
|
3994
|
+
checkout or a workspace instance, whatever the tree its link leads to is
|
|
3995
|
+
on; for a real directory that is not the instance's own tree (#962) and
|
|
3996
|
+
for a link (#973), under a record that says `worktree` too. It is the
|
|
3997
|
+
reading's answer and not a promise that the retire completes: it is
|
|
3998
|
+
`true` for a file (or any entry that is neither a link nor a directory)
|
|
3999
|
+
at `work/` under a record that says `worktree`, and `false` for one under
|
|
4000
|
+
any other record; and it is `true` for a work directory whose Git admin
|
|
4001
|
+
entry is missing when the spawn's receipt says that a tree was given,
|
|
4002
|
+
whatever the record says but `directory`. No retire removes such an
|
|
4003
|
+
entry: it is kept with the home until a person moves it (#1019). Neither
|
|
4004
|
+
`facts.workMode` (the record's value, which the instance can write) nor
|
|
4005
|
+
`facts.work` (an observation, through any link) says whose tree it is:
|
|
4006
|
+
read this key for that. Gate on the probe: from a kernel that lists the
|
|
4007
|
+
feature the key is present and a boolean; from one that does not it is
|
|
4008
|
+
absent, and its absence says nothing. A stop plan does not carry it. A
|
|
4009
|
+
relayed plan (`--server`) carries it as its host answered it, so it is
|
|
4010
|
+
the host's features that say whether it is there.
|
|
4011
|
+
- `defaults.retainWorktree` is the default of one option of this retire:
|
|
4012
|
+
whether the instance's own work tree is retained or removed
|
|
4013
|
+
(`--discard-worktree`). It follows the fact today: it is `true` when
|
|
4014
|
+
`facts.ownWorktree` is. A default is what the retire would do if nobody
|
|
4015
|
+
chose and a fact is what is there, so a client does not read this key to
|
|
4016
|
+
learn what `work/` is. Where it is `false` the instance has no work tree
|
|
4017
|
+
of its own; it is never `false` because a tree would be removed: there
|
|
4018
|
+
the retire touches no tree it does not own. `work/` of an attached, a
|
|
4019
|
+
checkout or a workspace instance is a link (to its owner's tree, to the
|
|
4020
|
+
shared checkout, to the deployment directory) that goes with the home,
|
|
4021
|
+
and what it links to is not touched. Where a real directory is found at
|
|
4022
|
+
`work/` of such an instance and no link, it is a directory of the home:
|
|
4023
|
+
the retire copies it to recovery when it is not empty and removes it
|
|
4024
|
+
with the home, and the plan says so (0.53.0, #962: the next item).
|
|
4025
|
+
`work/` of a directory instance is the home's own directory: it is
|
|
4026
|
+
copied to recovery when it is not empty, then removed with the home. The
|
|
4027
|
+
plan's text (`oats retire <instance>
|
|
4028
|
+
--plan` without `--json`) prints `retain worktree true` in its `defaults:`
|
|
4029
|
+
line for the instance's own tree only; for the other homes the line says
|
|
4030
|
+
the above (0.53.0, #959). When the reading of `work/` establishes
|
|
4031
|
+
neither an own tree nor a directory of the home, the line says `work mode
|
|
4032
|
+
not recorded` for a record with no work mode, and `work mode not known to
|
|
4033
|
+
this kernel` for one whose work mode the kernel does not know: the value
|
|
4034
|
+
is never printed, and `facts.workMode` holds it. (An own tree under such
|
|
4035
|
+
a record prints `retain worktree true`, and a directory of the home its
|
|
4036
|
+
own sentence.) The text does not print the fact.
|
|
4037
|
+
- What `work/` is comes from one reading, which the plan and the retire
|
|
4038
|
+
share (0.53.0, #962). It is **the instance's own tree** when the spawn's
|
|
4039
|
+
receipt says the instance was given one; for a home without a valid
|
|
4040
|
+
receipt, when the record says `worktree`, or holds no work mode (or one
|
|
4041
|
+
the kernel does not know) and Git confirms that `work/` is a registered
|
|
4042
|
+
linked worktree whose top level it is (the test of an
|
|
4043
|
+
[extra tree](souls-and-instances.md#extra-trees-at-retire)). A real
|
|
4044
|
+
directory at `work/` that is not that is **a directory of the home**: one
|
|
4045
|
+
found where the work mode has a link (an attached, a checkout or a
|
|
4046
|
+
workspace instance, or a record with no work mode), or under a valid
|
|
4047
|
+
receipt that says no tree was given, whatever the record says now. **A
|
|
4048
|
+
link** at `work/` is never the instance's own tree, whatever the record
|
|
4049
|
+
says (0.53.0, #973, below). For a directory of the home the plan has:
|
|
4050
|
+
- `defaults.retainWorktree: false`, and in the text's `defaults:` line `no
|
|
4051
|
+
work tree of its own (work/ is a real directory of the home: copied to
|
|
4052
|
+
recovery when not empty and then removed with the home)`.
|
|
4053
|
+
- the note `work/ is a real directory of the home and not a work tree of
|
|
4054
|
+
the instance's own: the retire copies it to recovery when it is not
|
|
4055
|
+
empty (a .git in it included), checks the copy, and removes it with the
|
|
4056
|
+
home`, and `recovery: work/ is copied there when it is not empty`. The
|
|
4057
|
+
notes that say a worktree is retained, and the drift note, are not said.
|
|
4058
|
+
- when Git confirms that the directory is a registered worktree, the note
|
|
4059
|
+
`work/ is registered as a worktree of <repository>: the retire leaves its
|
|
4060
|
+
entry there until a prune (git -C '<repository>' worktree prune), and does
|
|
4061
|
+
not touch its branch or its commits`.
|
|
4062
|
+
- `facts.work` by the path alone: observed when `work/` is the top level of
|
|
4063
|
+
a repository of its own, else `{observed: false, reason:
|
|
4064
|
+
"E_NO_WORKTREE"}`.
|
|
4065
|
+
|
|
4066
|
+
For an own tree whose record names no repository, the plan has the note
|
|
4067
|
+
`the record names no repository for the work tree: the retire uses the
|
|
4068
|
+
one Git names for it, <repository>, and does not write it into the
|
|
4069
|
+
record`. No key of the plan is new.
|
|
4070
|
+
|
|
4071
|
+
What `work/` is decides what the retire does with it, so it is part of
|
|
4072
|
+
`planRevision` wherever it is not what the work mode alone says: when an
|
|
4073
|
+
own tree became a directory of the home, or the other way round, between
|
|
4074
|
+
the plan and the apply (a record's work mode that changed, a receipt that
|
|
4075
|
+
is gone), or the repository read from Git changed, a guarded apply refuses
|
|
4076
|
+
with `E_PLAN_STALE` before anything runs. Every other home has the
|
|
4077
|
+
revision it had.
|
|
4078
|
+
- A link at `work/` is never the instance's own tree: the retire removes
|
|
4079
|
+
the link with the home and does not touch what it leads to, whatever the
|
|
4080
|
+
record says (0.53.0, #973). The record is a file the instance can write;
|
|
4081
|
+
what the link leads to is not the instance's. So a home whose record says
|
|
4082
|
+
`worktree` and whose `work/` is a symbolic link plans and retires as a
|
|
4083
|
+
home that was given a link. Before 0.53.0 its plan said
|
|
4084
|
+
`defaults.retainWorktree: true` and its retire was refused with
|
|
4085
|
+
`E_WORK_PRESERVATION_FAILED`. Its plan has:
|
|
4086
|
+
- `defaults.retainWorktree: false`, and in the text's `defaults:` line `no
|
|
4087
|
+
work tree of its own (work/ is a link, though the record says worktree:
|
|
4088
|
+
what it leads to is not touched)`. `facts.workMode` is the record's
|
|
4089
|
+
value, as always.
|
|
4090
|
+
- the note `the record says work mode worktree, but work/ is a link and
|
|
4091
|
+
not a work tree of the instance's own: the retire removes the link with
|
|
4092
|
+
the home and does not touch what it leads to, with --discard-worktree as
|
|
4093
|
+
well`. The note names no target. It names the flag because a plan takes
|
|
4094
|
+
no option: `--plan --discard-worktree` answers this same plan, and no
|
|
4095
|
+
worktree step runs for the link with the flag either.
|
|
4096
|
+
- `facts.work` as for every home whose `work/` is a link: an observation
|
|
4097
|
+
of what the link leads to, which says nothing of whose tree it is.
|
|
4098
|
+
- a `planRevision` that binds it, by the rule above: a plan read while
|
|
4099
|
+
`work/` was a link is stale once `work/` is the instance's own tree, and
|
|
4100
|
+
the other way round.
|
|
4101
|
+
|
|
4102
|
+
Its retire completes with the receipt of a home that was given a link
|
|
4103
|
+
(`retention: null`, `worktreeRemoved: false`, no copy of the work in
|
|
4104
|
+
`workRecovery`; with `--discard-worktree` too, since no worktree step
|
|
4105
|
+
runs), with and without `--discard-worktree` and `--force`, and one string
|
|
4106
|
+
in `warnings`: `<home>/work was a link though the record says
|
|
4107
|
+
work mode worktree: nothing was retained or removed as a work tree, and
|
|
4108
|
+
what it led to (<path>) was not touched`. `<path>` is what the system
|
|
4109
|
+
resolves the link to just before the home is removed, never the text
|
|
4110
|
+
stored in the link; nothing acts on it. When the link does not resolve,
|
|
4111
|
+
the string ends `and it led nowhere that could be read`. The receipt holds
|
|
4112
|
+
the path as the system gave it. The retire's text (without `--json`)
|
|
4113
|
+
prints every warning of the receipt on one line and spells each character
|
|
4114
|
+
a terminal would act on, or that hides or reorders text (a control
|
|
4115
|
+
character such as an escape or a newline, a bidi override: the set the
|
|
4116
|
+
kernel never prints in text it did not write), as `\u{<hex>}`, so that a
|
|
4117
|
+
name cannot clear the screen or write a line of its own. The JSON is not
|
|
4118
|
+
changed by that: its strings are what they were. No key of the plan or of
|
|
4119
|
+
the receipt is new.
|
|
4120
|
+
- A link at `work/` that is no longer a link when the retire inspects the
|
|
4121
|
+
home again (a retire hook, or anything else, put a directory or a file in
|
|
4122
|
+
its place) refuses with `E_WORK_INSPECTION_FAILED` and keeps the home, in
|
|
4123
|
+
every work mode (0.53.0, #973): the home's removal would take what is
|
|
4124
|
+
there now, uncopied. The message says what was there and what is there
|
|
4125
|
+
now, that the home is kept and nothing of it was removed, and how it
|
|
4126
|
+
ends, by what is there now:
|
|
4127
|
+
- a directory: that `oats retire <instance> --plan` shows what a retire
|
|
4128
|
+
would do with what is there now, and that running the retire again does
|
|
4129
|
+
that;
|
|
4130
|
+
- a file, or an entry that is neither a link, a directory nor a file:
|
|
4131
|
+
that no retire removes it, and the step (`move it out of the home or
|
|
4132
|
+
remove it, then run the retire again`). It does not point to the plan,
|
|
4133
|
+
which does not say that such an entry stays (#1019);
|
|
4134
|
+
- an entry that cannot be read: that the retire reads it again when it is
|
|
4135
|
+
run again.
|
|
4136
|
+
|
|
4137
|
+
Running the retire again reads the home as it is then, by the reading
|
|
4138
|
+
above: the record as it is then and the spawn's receipt decide, not what
|
|
4139
|
+
the home was given alone.
|
|
4140
|
+
- A directory that the reading answers is a directory of the home (#962:
|
|
4141
|
+
the spawn's receipt says that no tree was given, as an attached, a
|
|
4142
|
+
checkout or a workspace instance's does, and the record says
|
|
4143
|
+
`attached`, `checkout`, `workspace`, `worktree` or holds no work mode):
|
|
4144
|
+
the retire copies it to recovery, checks the copy and removes it with
|
|
4145
|
+
the home.
|
|
4146
|
+
- A directory under a record that says `worktree` whose spawn's receipt
|
|
4147
|
+
says that a tree was given, and a file (or an entry that is none of the
|
|
4148
|
+
three) under a record that says `worktree` whatever the receipt says
|
|
4149
|
+
(an attached instance whose record was changed to `worktree` included):
|
|
4150
|
+
a work directory with no Git admin entry. The retire runs its hooks and keeps the entry and the home as an
|
|
4151
|
+
incomplete item (exit 1; with `--force` it refuses with
|
|
4152
|
+
`E_WORK_PRESERVATION_FAILED` before anything runs) until a person moves
|
|
4153
|
+
the entry out or deletes it; then it completes.
|
|
4154
|
+
- A file, or an entry that is none of the three, under a record that
|
|
4155
|
+
says `attached`, `checkout` or `workspace`: the inspection refuses
|
|
4156
|
+
(`E_WORK_INSPECTION_FAILED`, `--force` included, nothing stopped, run
|
|
4157
|
+
or removed) until a person removes the entry; then it completes.
|
|
4158
|
+
- A record that says `directory` by then is held against the spawn's
|
|
4159
|
+
receipt as always: the retire refuses (`E_WORK_INSPECTION_FAILED`,
|
|
4160
|
+
nothing stopped, run or removed) while the two disagree.
|
|
4161
|
+
- The two notes about a worktree that is retained, `N changed and M
|
|
4162
|
+
untracked file(s) would be retained with the worktree` and `the worktree
|
|
4163
|
+
is on <branch>, not the recorded <branch>`, are given for the instance's
|
|
4164
|
+
own tree alone (0.53.0, #973). `facts.work` of an attached, a checkout or
|
|
4165
|
+
a workspace instance observes the tree its link leads to, and before
|
|
4166
|
+
0.53.0 its plan gave both notes for that tree, which the retire neither
|
|
4167
|
+
keeps nor moves. `facts.work` is unchanged.
|
|
3588
4168
|
- A home spawned before 0.25.9 has no session receipt (0.30). Its
|
|
3589
4169
|
`facts.session` is `{state: "absent", present: false, backend, established:
|
|
3590
4170
|
true, note}` when the session is observably gone: instance.json records no
|
|
@@ -4014,15 +4594,29 @@ left its outcome at `resultPath` (it failed) or is gone (it died; a
|
|
|
4014
4594
|
completion that is a zombie, not reaped by its parent, has died: 0.52.0,
|
|
4015
4595
|
#870), nor when
|
|
4016
4596
|
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
|
-
|
|
4597
|
+
<instance>` then retries the retirement, as before. The completion does not
|
|
4598
|
+
start its retire while the retire that scheduled it holds the claim: it
|
|
4599
|
+
waits for that one command, which it knows by the pid and the start time it
|
|
4600
|
+
was given, for up to ten minutes (`SCHEDULING_WAIT_MS`; 0.53.0; before, for
|
|
4601
|
+
up to 3 s only). Meanwhile the home has no marker until that retire writes
|
|
4602
|
+
it, last, and that retire answers a stop and another retire as any running
|
|
4603
|
+
retire does ([the table](#lifecycle-pairs)). Then it takes the claim as any retire
|
|
4604
|
+
does, waiting up to 3 s for a live holder, the one that scheduled it
|
|
4605
|
+
included when the ten minutes have passed; one that meets another retire still running is refused,
|
|
4020
4606
|
and records that at `resultPath` like any failed completion. The `error`
|
|
4021
4607
|
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.
|
|
4608
|
+
envelope: a kernel code, and what the retire had done by then. From 0.53.0
|
|
4609
|
+
a completion that does not complete also writes one
|
|
4610
|
+
[`retire-refused` event](#retire-refused-event), and removes its pending
|
|
4611
|
+
marker unless it started a retire hook or began the removal of the home.
|
|
4612
|
+
It removes only the marker of its own scheduling: the same `requestedAt`,
|
|
4613
|
+
and a `completionPid` that is absent, its own, or of a process that is
|
|
4614
|
+
gone.
|
|
4023
4615
|
|
|
4024
4616
|
A `--self` that cannot finish scheduling (the completion's log cannot be
|
|
4025
|
-
opened, no process is created, the marker cannot be written
|
|
4617
|
+
opened, no process is created, the marker cannot be written, or, from
|
|
4618
|
+
0.53.0, its completion has already ended when the marker is written, with
|
|
4619
|
+
an outcome or without one: the marker is then removed again) answers
|
|
4026
4620
|
`E_SELF_RETIRE_SCHEDULE_FAILED`, with `reached.phase: "before-effects"`. That
|
|
4027
4621
|
stays true after the answer: a completion this command had started is not
|
|
4028
4622
|
running when it answers (it is ended, unless it had gone by itself; a
|
|
@@ -4333,7 +4927,23 @@ accept `--server <id>`.
|
|
|
4333
4927
|
anything is sent (`default: false` is dropped). Errors: `E_LOCAL_MISSING`,
|
|
4334
4928
|
`E_BAD_ARGS` (including `--home`/`--soul`), `E_LAUNCH_CONFIG_UNKNOWN`,
|
|
4335
4929
|
`E_LAUNCH_CONFIG_INVALID`, `E_CONFIG_BROKEN`, `E_HOME_UNKNOWN`,
|
|
4336
|
-
`E_REMOTE_INCOMPATIBLE
|
|
4930
|
+
`E_REMOTE_INCOMPATIBLE`, `E_LOCAL_BUSY {path, lock}`, `E_LOCAL_CHANGED
|
|
4931
|
+
{path}`.
|
|
4932
|
+
- **The write** (`set`, `remove`) replaces the `launch-configs` block and
|
|
4933
|
+
leaves every other byte of the file as it was. It is made under
|
|
4934
|
+
`<deployment>/.agents/locks/local.lock`, the lock of every kernel command
|
|
4935
|
+
that rewrites `oats-local.yaml` ([`oats teams`](#oats-teams) says what it
|
|
4936
|
+
covers), from the file as it is under that lock: whether the name is
|
|
4937
|
+
declared, `before`, the environment `--keep-env` keeps and the one default
|
|
4938
|
+
per harness are all read there, never from the command's start. The
|
|
4939
|
+
definition (`--file`, or stdin) is read and judged before the lock is
|
|
4940
|
+
taken. A lock still held after 5 s is `E_LOCAL_BUSY`, and a file that kept
|
|
4941
|
+
changing while the edit ran is `E_LOCAL_CHANGED`; nothing was written, and
|
|
4942
|
+
the same command can be run again. When the text it would write is the
|
|
4943
|
+
file's text already, nothing is written; the receipt is the same either
|
|
4944
|
+
way. (The same definition set again is such a case only once this command
|
|
4945
|
+
has written the block: a block written by hand in another form is
|
|
4946
|
+
rewritten in this command's.)
|
|
4337
4947
|
- **preview** (read-only) answers `{context, selected, selection: {source,
|
|
4338
4948
|
launchConfig, harness, model, yolo}, harness, model, modelSource, yolo,
|
|
4339
4949
|
launchConfig, launchConfigSource, launchConfigDefault, executable: {path,
|
|
@@ -4728,8 +5338,13 @@ changes `installed` or `active`). `maxConcurrent` is the effective scheduled-job
|
|
|
4728
5338
|
|
|
4729
5339
|
**Workspace items:**
|
|
4730
5340
|
- `enable`/`disable` edit `oats-local.yaml` `triggers.disabled` or
|
|
4731
|
-
`schedules.disabled
|
|
4732
|
-
|
|
5341
|
+
`schedules.disabled`: that list and no other entry, under
|
|
5342
|
+
`<deployment>/.agents/locks/local.lock` and from the file as it is under
|
|
5343
|
+
it, as [`oats teams`](#oats-teams) writes that file. A lock still held
|
|
5344
|
+
after 5 s is `E_LOCAL_BUSY {path, lock}`, and a file that kept changing
|
|
5345
|
+
while the edit ran is `E_LOCAL_CHANGED {path}`; nothing was written, and
|
|
5346
|
+
the same command can be run again. `update` and `remove` refuse
|
|
5347
|
+
`E_AUTOMATION_WORKSPACE {id, origin}`. `schedule run`/`reconcile` elsewhere refuse
|
|
4733
5348
|
`E_AUTOMATION_NOT_HERE {id, reason, runsOn, owner}`.
|
|
4734
5349
|
- `oats trigger|schedule add … --workspace <member> --runs-on <host> --owner
|
|
4735
5350
|
<host>/<login> --json` writes the file in the member clone and answers
|