@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.
Files changed (98) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +304 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/desktop-cli-api.md +673 -58
  6. package/docs/desktop-instance-start.md +25 -12
  7. package/docs/execution-targets.md +1 -0
  8. package/docs/implementation.md +175 -11
  9. package/docs/integrations.md +6 -3
  10. package/docs/knowledge.md +2 -2
  11. package/docs/macos-test-runs.md +246 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-lane.md +210 -6
  15. package/docs/release-notes/v0.53.0.md +1274 -0
  16. package/docs/schedules.md +7 -1
  17. package/docs/souls-and-instances.md +237 -15
  18. package/docs/tui.md +453 -21
  19. package/docs/upgrading.md +298 -0
  20. package/docs/workspaces.md +3 -3
  21. package/lib/automations.mjs +22 -22
  22. package/lib/claim.mjs +93 -4
  23. package/lib/config-data.mjs +4 -1
  24. package/lib/core.mjs +569 -121
  25. package/lib/instance-events.mjs +19 -1
  26. package/lib/instance-git.mjs +39 -3
  27. package/lib/instance-inspect.mjs +5 -6
  28. package/lib/instance-lifecycle.mjs +145 -18
  29. package/lib/instance-resolution.mjs +59 -6
  30. package/lib/launch-preference.mjs +226 -15
  31. package/lib/local-edit.mjs +118 -0
  32. package/lib/packages.mjs +13 -4
  33. package/lib/pi-bridge.mjs +308 -0
  34. package/lib/refused-text.mjs +11 -0
  35. package/lib/remote.mjs +190 -25
  36. package/lib/resolve.mjs +2 -1
  37. package/lib/retained-after-retire.mjs +2 -2
  38. package/lib/retire-output.mjs +12 -1
  39. package/lib/schedule-host.mjs +6 -35
  40. package/lib/shell-word.mjs +13 -0
  41. package/lib/soul-launch-verbs.mjs +153 -0
  42. package/lib/stable-node.mjs +62 -0
  43. package/lib/teams-verbs.mjs +18 -46
  44. package/lib/workspace.mjs +49 -19
  45. package/package-catalog.json +4 -4
  46. package/package.json +2 -1
  47. package/packages/client/attach-exit.mjs +25 -0
  48. package/packages/client/cli-adapter.mjs +16 -3
  49. package/packages/client/cli-locator.mjs +2 -2
  50. package/packages/client/deployment-contract.mjs +4 -0
  51. package/packages/client/deployment-facts.mjs +71 -10
  52. package/packages/client/deployment-panel.mjs +49 -11
  53. package/packages/client/deployment-read-cli.mjs +7 -3
  54. package/packages/client/display-text.mjs +8 -2
  55. package/packages/client/instance-acts.mjs +46 -10
  56. package/packages/client/instance-events-contract.mjs +4 -2
  57. package/packages/client/instance-presentation.mjs +66 -2
  58. package/packages/client/instance-tree.mjs +23 -14
  59. package/packages/client/kernel-lines.mjs +31 -0
  60. package/packages/client/kernel-made.mjs +23 -0
  61. package/packages/client/launch-prompt-outcome.mjs +51 -16
  62. package/packages/client/lifecycle-contract.mjs +45 -4
  63. package/packages/client/liveness.mjs +14 -1
  64. package/packages/client/own-codes.mjs +31 -0
  65. package/packages/client/panel-views.mjs +18 -11
  66. package/packages/client/readiness-contract.mjs +3 -1
  67. package/packages/client/remote-address.mjs +34 -9
  68. package/packages/client/remote-identity-memory.mjs +94 -0
  69. package/packages/client/remote-roster.mjs +92 -6
  70. package/packages/client/session-attach.mjs +175 -0
  71. package/packages/client/spawn-apply-contract.mjs +16 -4
  72. package/packages/client/spawn-messages.mjs +26 -3
  73. package/packages/client/spawn-preview-cli.mjs +8 -2
  74. package/packages/client/spawn-preview-contract.mjs +5 -1
  75. package/packages/client/terminal-exec.mjs +21 -0
  76. package/packages/client/workspace-choices.mjs +95 -0
  77. package/packages/client/workspace-views.mjs +39 -3
  78. package/packages/record/README.md +21 -0
  79. package/packages/record/bin/setup.mjs +108 -15
  80. package/packages/tui/README.md +30 -12
  81. package/packages/tui/lib/actions.mjs +16 -1
  82. package/packages/tui/lib/client.mjs +32 -1
  83. package/packages/tui/lib/config.mjs +151 -0
  84. package/packages/tui/lib/main.mjs +117 -46
  85. package/packages/tui/lib/model.mjs +392 -0
  86. package/packages/tui/lib/read.mjs +473 -0
  87. package/packages/tui/lib/store.mjs +364 -0
  88. package/packages/tui/lib/term/keys.mjs +44 -0
  89. package/packages/tui/lib/term/screen.mjs +16 -4
  90. package/packages/tui/lib/term/text.mjs +60 -0
  91. package/packages/tui/lib/term/tty.mjs +13 -3
  92. package/packages/tui/lib/views/detail.mjs +46 -0
  93. package/packages/tui/lib/views/frame.mjs +230 -36
  94. package/packages/tui/lib/views/help.mjs +125 -13
  95. package/packages/tui/lib/views/instances.mjs +137 -0
  96. package/packages/tui/lib/views/scroll.mjs +19 -0
  97. package/packages/tui/lib/views/switcher.mjs +97 -0
  98. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -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 wording. When the
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. Each verb re-reads the file and judges its refusals on it
1448
- as it is now, and writes only if the file did not change meanwhile (else it
1449
- redoes the edit on the new content). A file that keeps changing is
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
- is "install <harness>, or override it on this machine in oats-local.yaml
1684
- souls.launch" (from the soul or the host), "install <harness>, or change
1685
- oats-local.yaml souls.launch" (from local layers), or "install <harness>, or
1686
- choose another --harness / --launch-config" (from a flag).
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", so it stays within 1024 characters),
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> (or souls.launch in oats-local.yaml), or mark one
1698
- default: true (oats launch-config set)". A start or restart of an existing
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
- (`E_HARNESS_UNAVAILABLE`, `E_LAUNCH_CONFIG_UNKNOWN`,
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. With `E_LAUNCH_CONFIG_UNKNOWN`,
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`, `worktree-retained`, `worktree-removed`,
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"`, or the kernel code of what failed (`E_GIT_FAILED` for an
3171
- error that has none; `E_WORK_INSPECTION_FAILED` for a home the kernel
3172
- cannot look into, where whether it has a `work/` cannot be told; OATS
3173
- 0.52.0).
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). `stopPending`: a stop apply holds its
3452
+ [claim](#retire-one-at-a-time). From 0.53.0 the marker outlasts a
3453
+ completion that did not complete only when a retire hook was started or
3454
+ the removal of the home began
3455
+ ([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
3456
+ `stopPending`: a stop apply holds its
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 stop
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 needs to write its claim.** A stop whose claim cannot be written
3257
- (a full disk is the likely case; a claims directory that cannot be made or
3258
- written) is refused before anything is signalled: `E_LIFECYCLE_FAILED`,
3259
- `the claim <lock> could not be taken (<the system's error>); nothing was
3260
- done`, with the system's code in [`details.cause`](#kernel-codes) and the
3261
- plan it read in `details.plan`. The session runs as before. The way out:
3262
- free space and stop again, or end the session by hand. Before 0.52.0 a stop
3263
- took no claim: it wrote its marker if it could and signalled the harness
3264
- either way, so it could fail afterwards, writing its own record, with the
3265
- signal already sent.
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 still runs (text mode exits 1).
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: `the claim <path> could not be taken (…); nothing was done`).
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. A retire reads the marker under the claim, while
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
- (`E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
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 waits up
4018
- to 3 s for the retire that scheduled it to release the claim, then takes it
4019
- as any retire does; one that meets another retire still running is refused,
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) answers
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`. `update` and `remove` refuse `E_AUTOMATION_WORKSPACE
4732
- {id, origin}`. `schedule run`/`reconcile` elsewhere refuse
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