@awebai/oats 0.52.0 → 0.54.0

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