@awebai/oats 0.51.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 (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
package/docs/schedules.md CHANGED
@@ -21,8 +21,10 @@ inside the deployment, including from an instance home, sees the same
21
21
  definitions.
22
22
 
23
23
  There is no daemon. One host timer (a launchd user agent on macOS, a systemd
24
- user timer on Linux) runs `oats schedule tick --host` once a minute. The tick
25
- evaluates only the current minute, launches what is due through the same
24
+ user timer on Linux) runs `oats schedule tick --host` at second 0 of every
25
+ minute. The tick evaluates only the minute it was fired for (read from the
26
+ process's own start, before any other work, so a tick that is slow to start
27
+ still evaluates its minute), launches what is due through the same
26
28
  `spawn`, `session start` and `session input` paths you use by hand, polls the
27
29
  triggers that are due, records what it observed, and exits. Minutes missed
28
30
  while the machine slept are skipped, never replayed; there are no retries and
@@ -110,7 +112,8 @@ refuses the key on a trigger.
110
112
  scheduler keeps the unknown attempt and its slot until reconciliation.
111
113
  - **wake** `{…, home, message}` — every due minute inspects the instance at
112
114
  `home`. Running: `message` is delivered once as terminal input (bracketed
113
- paste plus Enter), never an interrupt. Not running: the home is started with
115
+ paste plus Enter), never an interrupt. Not running (its harness exited, or
116
+ its tmux server is gone after a reboot): the home is started with
114
117
  `session start` and the message becomes the job's one pending delivery,
115
118
  completed on a later tick once the session is active; the home is started
116
119
  again only at due minutes, so a harness that keeps exiting is not restarted
@@ -547,6 +550,10 @@ add` / `oats schedule add` definitions need no trust.
547
550
  **Opting out on one host.** `oats trigger disable <member>/<id>` writes
548
551
  `triggers.disabled`, and `oats schedule disable <member>/<id>` writes
549
552
  `schedules.disabled`, in `oats-local.yaml`; `enable` removes the entry. The
553
+ write changes that list and no other entry, and takes the lock every kernel
554
+ command that rewrites `oats-local.yaml` holds, so it never drops another
555
+ command's change (`E_LOCAL_BUSY` when the lock stays held, `E_LOCAL_CHANGED`
556
+ when the file kept changing: run it again). The
550
557
  schedule part of a qualified ID accepts up to 100 characters in both
551
558
  `schedules.disabled` and named `automations.trust` entries. Trigger definitions
552
559
  and `triggers.disabled` keep their 40-character limit; the shared trust list
@@ -585,6 +592,7 @@ oats schedule reconcile <id> [--clear] # resolve an attempt whose result was n
585
592
  oats schedule host install # register this deployment and install the one host timer (idempotent)
586
593
  oats schedule host install --max-concurrent 3 --triggers-max-concurrent 2
587
594
  oats schedule host install --max-concurrent default --triggers-max-concurrent none
595
+ oats schedule host install --print [--os darwin|linux] # what install would write; changes nothing
588
596
  oats schedule host status | uninstall
589
597
  oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?" # or --wake-file spec.json
590
598
  ```
@@ -638,6 +646,76 @@ five. Correct it with `oats schedule host install --max-concurrent N` (or
638
646
  An absent value still means five. Set caps through the CLI; do not edit the
639
647
  registry by hand.
640
648
 
649
+ ### The host timer's unit
650
+
651
+ The unit is a launchd user agent (`~/Library/LaunchAgents/ai.oats.schedule-tick.plist`,
652
+ `StartCalendarInterval` with an empty dict) or a systemd user timer and service
653
+ (`oats-schedule-tick.timer`, `OnCalendar=*-*-* *:*:00`, `AccuracySec=1s`,
654
+ `Persistent=false`). Both fire at second 0 of every minute; the launchd job is
655
+ `ProcessType Standard`, not `Background`, whose throttling delayed its start
656
+ under load. The tick evaluates the minute it was fired for as long as it starts
657
+ within that minute. A tick still running when the next minute fires loses that
658
+ minute's fire, on both platforms: launchd and systemd do not start a job that is
659
+ still running, and nothing replays the minute (#902's bounded catch-up, a
660
+ separate change, is what recovers it). `install` renders it
661
+ from **the environment of the shell it runs in**, so run it from the operator's
662
+ own shell, not from an instance home:
663
+
664
+ - **PATH**: the directory of the node the unit runs, then the installer's
665
+ `PATH`, then `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`,
666
+ `/usr/sbin` and `/sbin`. Three kinds of entry are dropped from the
667
+ installer's `PATH`: entries inside an OATS instance home (an instance's
668
+ `.oats/bin`, or anything under `$OATS_INSTANCE_HOME`), entries inside a
669
+ versioned Homebrew keg (`…/Cellar/<formula>/<version>/…`), and relative or
670
+ empty entries. An entry that does not exist yet is kept. This is the
671
+ `PATH` the tick itself runs with. A harness the tick launches is looked up
672
+ where its pane will look it up
673
+ ([execution targets](execution-targets.md#the-servers-start-environment)):
674
+ a launch configuration's own `PATH` when it sets one, else the running OATS
675
+ tmux server's `PATH`, or, when the tick is what starts the server, the
676
+ `PATH` of the login environment the server is created with. The
677
+ unit's `PATH` is that lookup's fallback, when the login environment cannot
678
+ be read.
679
+ - **node**: the keg's `<prefix>/opt/<formula>/bin/node` when it is the node
680
+ running `install`, else the first `node` on the filtered `PATH` that is that
681
+ same file. When neither exists, `install` keeps the node's own path and its
682
+ answer carries a warning that the path is not stable. Only Homebrew's `opt`
683
+ link survives an upgrade. With a version manager (mise, nvm, asdf, fnm) the
684
+ node on `PATH` is that version's own install, so the unit records that
685
+ version's path, and `host status` reports `node-missing` once that version
686
+ is removed. The same rule answers `OATS_NODE_BIN`, the node a
687
+ capability writes down
688
+ ([capabilities](capabilities.md#the-node-a-hook-writes-down)).
689
+ - **oats**: the `oats.mjs` of the oats that runs `install`. When that is inside
690
+ `$OATS_INSTANCE_HOME` or its `work` (a clone in an instance's work tree,
691
+ an attached instance's included), `install` and
692
+ `--print` warn: the timer would stop when that instance retires. Run
693
+ `install` with the operator's installed oats.
694
+
695
+ An installed unit changes only when `install` runs again. `install` rewrites a
696
+ unit whose bytes differ, so running it again after an upgrade migrates the
697
+ unit. `oats schedule host install --print` writes to stdout exactly what
698
+ `install` would write, each file under a `==> <path> <==` line, and changes
699
+ nothing: no registry, no unit file, no log directory, no `launchctl` or
700
+ `systemctl` call. `--os darwin|linux` renders another platform's unit. With
701
+ `--json` it answers `{kind, files: {<path>: <content>}, warnings}`.
702
+
703
+ `host status` (and the `scheduler` of every list) carries `problems`, warnings
704
+ that never change `installed` or `active`. Each is `{code, message, fix}`, read
705
+ from the installed unit alone, so every caller gets the same answer:
706
+
707
+ | Code | When |
708
+ | --- | --- |
709
+ | `node-missing` | the node the unit runs does not exist |
710
+ | `oats-bin-missing` | the `oats.mjs` the unit runs does not exist |
711
+ | `path-entry-missing` | an entry of the unit's `PATH` does not exist (one problem per entry; the fixed prefixes above are not checked, nor the missing node's own directory) |
712
+ | `unit-outdated` | the unit fires on an interval (`StartInterval`, `OnUnitActiveSec`), or differs from what this oats renders for the same node, oats, `PATH` and `OATS_HOME_DIR` |
713
+
714
+ Each problem's `fix` says what to do. For `path-entry-missing`, restore the
715
+ entry, or remove it from the operator's `PATH` and run `oats schedule host
716
+ install` again; for the others, run `oats schedule host install` again from
717
+ the operator's shell.
718
+
641
719
  `oats schedule list --json` answers:
642
720
 
643
721
  ```text
@@ -647,7 +725,7 @@ registry by hand.
647
725
  schedules: [ <row> ],
648
726
  triggers: { count, command: "oats trigger list" },
649
727
  snapshot: { takenAt, problems } | null,
650
- scheduler: { installed, active, unit?, lastTick, maxConcurrent, triggersMaxConcurrent, tickIntervalSec,
728
+ scheduler: { installed, active, unit?, problems, lastTick, maxConcurrent, triggersMaxConcurrent, tickIntervalSec,
651
729
  workspace, registered, workspaces, live } }
652
730
  ```
653
731
 
@@ -668,6 +746,21 @@ home whose retirement is pending still counts), `ended` (its home is gone),
668
746
  you), `launch-failed`, `unknown`, and for wake jobs `delivered`, `started` or
669
747
  `skipped`. The kernel never claims a task succeeded.
670
748
 
749
+ A home whose recorded tmux server is gone, after a reboot or a crash, is
750
+ `stopped` too, with the note `its tmux server is gone`. Gone means that no
751
+ server listens on its socket, or that its socket file is missing and no
752
+ process works in the home. When a process still works there, the home stays
753
+ `unknown`, with that reason
754
+ ([missing socket](execution-targets.md#missing-socket)). A spawn job keeps
755
+ its slot while its instance's home exists, a stopped one included (its harness
756
+ exited, or its tmux server is gone), so its due minutes are skipped with
757
+ `previous instance stopped: retire it (oats retire <instance>) or start it
758
+ again (oats session start --home <home>)`, and
759
+ `oats schedule run-now` refuses with the same words (`E_SCHEDULE_RUNNING`).
760
+ While the instance runs, they are skipped as `still running`. After a reboot, a wake job
761
+ starts its instance's session at its next due minute, and a spawn job shows
762
+ `stopped` with the command to retire or start its instance.
763
+
671
764
  `unknown` means the launch's side effects are unconfirmed: a command timed out
672
765
  or answered no envelope, or an attempt was never recorded. A job with a
673
766
  persisted attempt is skipped until `oats schedule reconcile <id>` (an
@@ -218,20 +218,25 @@ instructions and pins model/provider settings; it excludes nothing.
218
218
  Claude Code and Codex ask before they work in a folder they have not seen, and
219
219
  every instance home is new. A launch stopped at that prompt waits for a human,
220
220
  so the operator trusts the **deployment directory** (where `oats-local.yaml`
221
- is) once per harness. Launches only read native configuration. The explicit
222
- `oats harness trust --dir D --harness all --plan` previews the entry; the same
223
- command without `--plan` applies it with a deployment audit. See
224
- [native trust](harness-trust.md) for safe operation and partial-failure recovery.
221
+ is) once per harness configuration file. Launches only read native
222
+ configuration. The explicit `oats harness trust --dir D --plan` previews the
223
+ entry in every file a launch reads: the ambient one and each launch
224
+ configuration's `CLAUDE_CONFIG_DIR` / `CODEX_HOME`. The same command without
225
+ `--plan` applies it with a deployment audit; it never creates a launch
226
+ configuration's directory. See [native trust](harness-trust.md) for safe
227
+ operation and partial-failure recovery.
225
228
 
226
229
  - **Claude Code** looks for an accepted entry for its folder or an ancestor, up
227
230
  to a Git root. An intervening repository can prevent deployment-root inheritance;
228
231
  the command does not automatically trust another root. The native field is
229
232
  `projects["<deployment>"].hasTrustDialogAccepted` in `~/.claude.json`
230
- (`$CLAUDE_CONFIG_DIR/.claude.json` when that is set).
233
+ (`$CLAUDE_CONFIG_DIR/.claude.json` when the launch's environment, host or
234
+ launch configuration, sets it).
231
235
  - **Codex** applies only an exact entry: a trusted parent does not cover the
232
236
  folders below it. The explicit deployment-root command records
233
237
  `[projects."<deployment>"] trust_level = "trusted"` in
234
- `~/.codex/config.toml` (`$CODEX_HOME/config.toml`). With that entry, or one
238
+ `~/.codex/config.toml` (`$CODEX_HOME/config.toml`, from the launch's
239
+ environment as for Claude). With that entry, or one
235
240
  for an ancestor of the deployment, each codex launch trusts its own new home
236
241
  for that session (`-c 'projects={"<home>"={trust_level="trusted"}}'`) and
237
242
  leaves the config file unchanged. A yolo launch always does this. The plan
@@ -239,14 +244,16 @@ command without `--plan` applies it with a deployment audit. See
239
244
  - Every codex launch also passes `-c check_for_update_on_startup=false`, so
240
245
  Codex's "Update available" choice cannot block it.
241
246
 
242
- When a claude or codex home is not covered, the spawn says so (text and
243
- `--json` `warnings`): `the <harness> session will stop at its folder-trust
244
- prompt: trust <deployment> once (<the step>)`. `oats readiness` reports the
245
- same in `checks.configured` (code `harness-trust`, not required).
247
+ When the file a claude or codex launch reads does not trust the deployment,
248
+ the spawn says so (text and `--json` `warnings`): `<harness> folder trust is
249
+ not established in <file>: oats harness trust --dir <deployment>`. A missing
250
+ entry does not prove a prompt, so it does not say the session will stop.
251
+ `oats readiness` reports the same in `checks.configured` (code
252
+ `harness-trust`, not required), and a passing item naming the file when trust
253
+ is established.
246
254
 
247
- Exact-home [aweb development-channel consent](configuration.md#exact-home-launch-prompt-consent)
248
- does not cover folder-trust prompts. It neither writes trust settings nor
249
- enables existing homes automatically.
255
+ [The development-channel confirmation](configuration.md#the-development-channel-confirmation)
256
+ does not cover folder-trust prompts, and never writes trust settings.
250
257
  A blocked or incomplete prompt outcome preserves the home and process even
251
258
  though its metadata says `launched:false`; inspect that endpoint before any
252
259
  recovery. See [launch prompt outcomes](execution-targets.md#launch-prompt-outcomes).
@@ -441,27 +448,53 @@ beside the homes, which names its holder by pid and start time. Any other
441
448
  retire of that instance (plain, guarded or `--self`, `--force` included) is
442
449
  refused at once with `E_LIFECYCLE_BUSY`, before it stops anything, copies
443
450
  anything or runs a hook: a retire hook releases things that exist once, such
444
- as a messaging identity or a scheduled job. A self-retire's completion is
445
- refused the same way, after it has waited up to 3 s for the retire that
446
- scheduled it to release the claim. A self-retire that is scheduled counts from the moment it is scheduled,
451
+ as a messaging identity or a scheduled job. A self-retire's completion
452
+ waits for the retire that scheduled it to release the claim, for up to ten
453
+ minutes (OATS 0.53.0; before, it gave up after 3 s). Beside any other
454
+ holder it is refused the same way, after it has waited up to 3 s. A self-retire that is scheduled counts from the moment it is scheduled,
447
455
  while its completion lives. A retire killed while it holds the claim leaves
448
456
  the file behind until that name is retired again: the next retire takes the
449
457
  claim over, because its holder is verifiably gone, and the file is safe to
450
- remove by hand once its pid is gone. The claim does not end what the killed
458
+ remove by hand once its pid is gone. A holder that was killed and that its
459
+ parent has not reaped (a zombie) is gone too: nothing waits for that reap. The claim does not end what the killed
451
460
  retire left running: one of its retire hooks may still be running when the
452
461
  next retire takes the claim over and runs the hooks again (#865). A holder whose start time cannot be
453
462
  read is never taken for gone; the refusal names the pid, the file and the
454
- way out. The claim orders retires only: `oats instance stop`, `oats session
455
- start` and `oats worktree add` do not take it, and `oats status` does not
456
- show it (#866). The refusals are in
457
- [desktop-cli-api.md](desktop-cli-api.md#retire).
463
+ way out.
464
+
465
+ A stop holds the same claim (OATS 0.52.0, #866, #890). `oats instance stop
466
+ <instance> --apply` takes the claim of the instance and of every recorded
467
+ child it would stop before it stops the first one, and holds them until it
468
+ has written its receipt. So a stop and a retire of one instance never run
469
+ together: a stop that meets a retire is refused with `E_INSTANCE_RETIRING`, a
470
+ retire or a stop that meets a stop with `E_LIFECYCLE_BUSY`, at once and
471
+ before anything is stopped, run, copied or written. A stop that is killed
472
+ leaves its claim files, and they refuse nothing: the next stop or retire
473
+ takes them over. Before 0.52.0 a stop marked the home with a file inside it,
474
+ `.oats-stop-pending.json`, that named no holder: a killed stop left every
475
+ later stop of that instance refused until the file was removed by hand, and
476
+ a stop wrote into a home that a retire was inspecting or removing. That
477
+ name stays reserved: a file an older OATS left there refuses nothing and is
478
+ removed by the next stop. A retire does not hold the claims of its recorded
479
+ children: it stops each one, and that stop takes the child's claim for as
480
+ long as it lasts; a child held by someone else's stop or retire is a child
481
+ that did not stop (below). `oats worktree add` reads the claim and is
482
+ refused while a retire of the home runs (`E_INSTANCE_RETIRING`). `oats
483
+ session start` and `restart` do not read it yet, and `oats status` does not
484
+ show it. Who answers what to whom is one table in
485
+ [desktop-cli-api.md](desktop-cli-api.md#lifecycle-pairs); the refusals of a
486
+ retire are in [desktop-cli-api.md](desktop-cli-api.md#retire).
458
487
 
459
488
  Recorded children (the instances whose recorded parent chain reaches this
460
489
  one) are stopped first, never escalated, and kept: their homes stay. If one is
461
490
  still running after the grace, or its stop cannot be established, retire
462
491
  refuses with `E_CHILDREN_RUNNING` and retires nothing; `--force` does not
463
492
  bypass it. This holds for plain, guarded and `--self` retires alike
464
- ([desktop-cli-api.md](desktop-cli-api.md)).
493
+ ([desktop-cli-api.md](desktop-cli-api.md)). Who is a child is read from each
494
+ home's `instance.json`: a home whose record cannot be read is never stopped
495
+ as anyone's child, by a retire or by `oats instance stop`. Its session may go
496
+ on running after its parent is retired, and the retire's answer does not name
497
+ it; `oats status` is where it shows.
465
498
 
466
499
  Before any retire hook runs, retire preserves the instance's uncommitted and
467
500
  unmerged work: a verified recovery under `.oats-retirement/recovery/`, named in
@@ -651,7 +684,7 @@ holds of each kind:
651
684
 
652
685
  | Of the nested repository | The copy holds |
653
686
  |---|---|
654
- | `HEAD` | on the same branch, or detached at the same commit when the source's is detached (or on a ref that is not a branch, or on a branch whose name is not UTF-8) |
687
+ | `HEAD` | on the same branch, or detached at the same commit when the source's is detached (or on a ref that is not a branch, or on a branch whose name is not UTF-8); on the same branch with no commit when the source's has none ([below](#nested-no-commit)) |
655
688
  | every local branch | the branch under its name, at its commit |
656
689
  | the reflogs of `HEAD` and of each branch | branch and `HEAD` reflogs are carried, with every commit they name |
657
690
  | tags | the tags and what they name |
@@ -687,6 +720,54 @@ cannot carry at all (an entry that is not a file, a directory or a symbolic
687
720
  link, or a nested repository whose path is not valid UTF-8) refuses the copy,
688
721
  here as anywhere.
689
722
 
723
+ <a id="copied-as-one-file"></a>
724
+ **What the copy takes as one file must be a regular file.** The index,
725
+ `info/attributes`, the stash's log and a nested repository's reflogs are each
726
+ copied as one file. A link at such a path is followed, as Git follows it: the
727
+ recovery holds a plain file with what Git reads through the link. A path
728
+ that is not there, or a link that leads nowhere, is left out of the copy, as
729
+ Git reads nothing there. Anything else at such a path (a directory, empty or
730
+ not, a FIFO, an entry that cannot be read) refuses the copy with
731
+ `E_WORK_PRESERVATION_FAILED`, naming the path and what is there. The retire
732
+ looks before it copies, so the answer is the same on every file system.
733
+
734
+ For the index this refusal is not reached. Git reads the index before the
735
+ copy takes it, and Git fails where a directory, or a file that is not an
736
+ index, stands at it. The retire then refuses with Git's message: for the
737
+ instance's own tree at the inspection (`E_WORK_INSPECTION_FAILED`, before
738
+ anything is stopped, run or removed), for a nested repository when its state
739
+ is read for the copy (`E_WORK_PRESERVATION_FAILED`, the home and the work
740
+ kept). An index that cannot be read refuses at the inspection in both,
741
+ unless it is a nested repository's and a link leads to it: the retire then
742
+ refuses when that repository's state is read, as for a directory there.
743
+
744
+ <a id="no-index-file"></a>
745
+ **A tree with no index file is copied with none.** A work tree made by
746
+ `git worktree add --no-checkout`, or one whose index file was removed, has no
747
+ index file, and Git reads it as a tree whose index lists nothing: every
748
+ committed file is a staged deletion, and every file in the tree is
749
+ untracked. A retire copies it as it copies any tree that holds work, and
750
+ the recovery's `repo/` then has no index file either: Git reads it as it
751
+ read the tree. The same holds for a nested repository that has a commit and
752
+ no index file.
753
+ `git reset` in the recovery makes an index from `HEAD`: the committed files
754
+ are tracked again, and a file that was changed in the tree shows as changed.
755
+
756
+ <a id="nested-no-commit"></a>
757
+ **A nested repository with no commit at its `HEAD` is copied as one.** After
758
+ `git init` and no commit, or after `git switch --orphan` in a repository that
759
+ has commits, a repository's `HEAD` names a branch nobody has committed on.
760
+ The recovery rebuilds it as it rebuilds any nested repository: its `HEAD` is
761
+ on the same branch and has no commit, its other branches are there with
762
+ their commits and their logs, and its index, what is staged in it and its
763
+ files are the source's. One with no index file either (`git init` and
764
+ nothing added) has none in the recovery. A `HEAD` with no commit that names
765
+ no local branch (a ref outside `refs/heads/`, or a branch whose name is not
766
+ UTF-8) is refused with `E_WORK_PRESERVATION_FAILED`, naming the repository,
767
+ the home and the work kept: there is no commit to detach the copy at and no
768
+ branch to put it on. A commit in that repository, or `git switch -c
769
+ <branch>` there, makes the work tree retirable.
770
+
690
771
  **A worktree that cannot be proven unchanged.** Two things make a worktree
691
772
  not provable:
692
773
 
@@ -786,10 +867,12 @@ clean. Such an entry refuses the retire, at one of three points:
786
867
  again in the same home with `oats session start --home <abs>`. A
787
868
  self-retire (`--self`) is completed by its detached completion, which stops
788
869
  the session and refuses in the same way; the refusal is recorded beside the
789
- home, as described below. After a refused self-retire only `oats retire
790
- <instance>` continues: `oats session start` refuses while the self-retire's
791
- pending marker is there, and a retire clears it. Of the refusals at this
792
- point, only that of `--self --keep-dir`, which stays in the calling
870
+ home, as described [below](#self-retire-not-completed). No hook has run at
871
+ this point, so from OATS 0.53.0 the completion removes the self-retire's
872
+ pending marker: the instance is a stopped instance like any other, and
873
+ both `oats retire <instance>` and `oats session start` continue. Before
874
+ 0.53.0 the marker stayed, and only a retire continued. Of the refusals at
875
+ this point, only that of `--self --keep-dir`, which stays in the calling
793
876
  process, comes with the session still running;
794
877
  - **after the hooks**, when a retire hook left the entry behind: the hooks
795
878
  have run, and the home, the work and the recovery written before the hooks
@@ -818,6 +901,40 @@ a file over 2 GiB it gives the size, and `find <work> -type f -size
818
901
  or make it readable, then run `oats retire <instance>` again. With nothing to
819
902
  preserve, the files are not read and the retire goes through.
820
903
 
904
+ **A home whose `instance.json` cannot be read.** The record is what
905
+ identifies a home: its soul, its work mode, its session, its lineage. One
906
+ that is there and gives no JSON object (a write cut off, an empty file, a
907
+ file kept from the user, a directory or a dangling link in its place, JSON
908
+ that is not an object) decides only for that home. `oats status` lists the
909
+ home with `unknown` and `E_UNIDENTIFIED_INSTANCE_HOME: <home>/instance.json
910
+ cannot be read (<reason>)`, and every other instance is listed, stopped,
911
+ started and retired as if that home were not there. The home's own retire
912
+ (`--plan` and `--force` included), its stop and its session start are refused
913
+ with `E_UNIDENTIFIED_INSTANCE_HOME` before anything is read, stopped, run or
914
+ removed. `--force` removes a home that has no `instance.json`; it does not
915
+ remove one whose record cannot be read, which may be a whole instance with
916
+ work. Restoring the file from a copy makes the home usable again; removing
917
+ such a home through OATS is not possible yet. A parent whose record cannot be
918
+ read has no recorded children for a stop or a retire: the lineage is read
919
+ from records, so its children are listed and act on their own. In the other
920
+ direction, such a home is never stopped as anyone's child: stop it, once its
921
+ record is restored, on its own. The answers are in
922
+ [desktop-cli-api.md](desktop-cli-api.md#unreadable-record).
923
+
924
+ **An entry of the home that cannot be read, or that is gone when it is
925
+ read.** Each inspection walks the home: it lists a directory, then reads each
926
+ entry. A file or a directory without permission, and an entry that another
927
+ process removed or renamed between the listing and the read, refuse the
928
+ retire with `E_WORK_INSPECTION_FAILED` at the inspection that met it. The
929
+ message names the entry and the system's reason, and ends with what the
930
+ retire had done by then, as the other refusals at that point do: nothing was
931
+ stopped, run or removed at the first inspection; no hook has run and nothing
932
+ was deleted at the one before the hooks; the hooks have run, and the home, its
933
+ work and the pre-hook recovery are kept at the one after them. The home is
934
+ kept in each case. Make the entry readable, or let the process that writes in
935
+ the home end, then run `oats retire <instance>` again. The answer says the
936
+ same as data: [`error.details.reached`](desktop-cli-api.md#retire-reached).
937
+
821
938
  The home is not copied again because the work is, and the work is not copied
822
939
  again because the home is. The home's comparison after the hooks holds every
823
940
  entry the home copy carries, as its bytes and permission bits, the kernel's
@@ -966,10 +1083,73 @@ status before its tmux window dies a few seconds later. The completion then
966
1083
  retires the instance exactly as an external `oats retire` would: quiesce the
967
1084
  harness, preserve uncommitted work, run retire hooks, repair lineage, remove
968
1085
  the worktree and the home. Success leaves nothing behind: the home and the
969
- marker are gone. A failure writes `.oats-retired-<instance>.json` beside the
970
- retained home (plus the usual quarantine marker when hooks reported incomplete
971
- cleanup), shows in `oats status` and the Desktop as a failed deferred
972
- retirement, and is retried and cleared with `oats retire <instance>`.
1086
+ marker are gone.
1087
+
1088
+ <a id="self-retire-not-completed"></a>A completion that does not complete,
1089
+ because the retire was refused or failed part way, answers nobody. It
1090
+ leaves what happened on disk (OATS 0.53.0):
1091
+
1092
+ - **Its outcome, always.** `.oats-retired-<instance>.json` beside the home
1093
+ holds `ok: false`, the code and the sentence the retire answered, and
1094
+ `retry`, the command that retries it. Its log is
1095
+ `.oats-retired-<instance>.log`. `oats status` and the Desktop show the
1096
+ outcome as a failed deferred retirement until a retire of the instance
1097
+ completes. No other command clears it: to drop it without retiring the
1098
+ instance, remove those two files by hand.
1099
+ - **Its pending marker, only when the home is owed a retire:** when a retire
1100
+ hook was started or the removal of the home began. The usual quarantine
1101
+ marker is there too when hooks reported incomplete cleanup. The instance
1102
+ then reads as retiring: `oats instance stop --apply` and `oats session
1103
+ start` answer `E_INSTANCE_RETIRING`, and `oats retire <instance>`
1104
+ continues. In every other case the completion removes its marker.
1105
+ Nothing of the home was changed, so the instance is a stopped or a
1106
+ running instance like any other: a start works, and a wake schedule may
1107
+ start it. A session or a child that the completion stopped on its way
1108
+ does not keep the marker.
1109
+ - **One event,** `retire-refused`, which says which of the two it was
1110
+ ([Events](desktop-cli-api.md#retire-refused-event)).
1111
+
1112
+ Nothing retries by itself: `oats retire <instance>` does. A completion
1113
+ removes only the marker of its own scheduling, so the marker of a later
1114
+ `--self` is left for that one's completion.
1115
+
1116
+ A completion does not start its retire while its scheduling still holds
1117
+ the home's claim (OATS 0.53.0). A scheduling that the host holds up
1118
+ therefore delays the retire and does not fail it. The completion waits for
1119
+ that one command only, which it knows by the pid and the start time it was
1120
+ given when it was started: a holder that has died, one whose liveness
1121
+ cannot be read, and any other holder are not waited for here, and the
1122
+ retire answers for them as every retire does.
1123
+
1124
+ While a completion waits, the instance reads as live in `oats status`
1125
+ until the scheduling has written its marker, which is the last thing it
1126
+ does before it releases the claim; from then on it reads `RETIRING`, as
1127
+ every scheduled self-retire does. Throughout, the scheduling is a retire
1128
+ that runs, so a stop plan shows `retiring: true`, and a stop apply
1129
+ (`E_INSTANCE_RETIRING`) and another retire (`E_LIFECYCLE_BUSY`) are refused
1130
+ with its pid. The wait ends
1131
+ when that command returns, fails or dies; ending it by hand lets the
1132
+ completion go on and retire the instance, which is what the instance asked
1133
+ for. It also ends after ten minutes (`SCHEDULING_WAIT_MS`): the completion
1134
+ then goes on to its retire, which is refused by the holder that is still
1135
+ there like any retire, and a scheduling that comes back afterwards answers
1136
+ `E_SELF_RETIRE_SCHEDULE_FAILED`, having found its completion's outcome.
1137
+
1138
+ A `--self` whose completion has already ended when the scheduling writes
1139
+ its marker answers `E_SELF_RETIRE_SCHEDULE_FAILED`, and nothing is
1140
+ scheduled: the completion left its outcome, or it is gone and left none
1141
+ (it was killed, for one). The scheduling removes the marker it wrote, with
1142
+ the completion's outcome and log if there are any, and the instance is
1143
+ still live.
1144
+
1145
+ **A home that a refused completion left stuck under 0.52.0 or earlier**
1146
+ still has its marker, and reads as retiring although nothing of it was
1147
+ changed. To retire it after all, run `oats retire <instance>`. To keep it,
1148
+ no command does this. Check that the completion the marker names is gone
1149
+ (its pid is `completionPid` in the marker), then remove by hand
1150
+ `.oats-retire-pending-<instance>.json`, `.oats-retired-<instance>.json` and
1151
+ `.oats-retired-<instance>.log` beside the home. The kernel does not do this
1152
+ for such a home, because it cannot date a refusal that it did not record.
973
1153
 
974
1154
  When a retire hook reports incomplete cleanup, the home is quarantined before
975
1155
  any worktree step: the worktree, its git admin entry and the branch stay
@@ -1040,6 +1220,87 @@ attached children in one note that covers both cases. Only the link changes:
1040
1220
  the child's `instance.json` is not rewritten, and its AGENTS.md and TASK.md
1041
1221
  still name the old path.
1042
1222
 
1223
+ #### What `work/` is at retire
1224
+
1225
+ The retire and its plan read what is at `<home>/work` once, by one rule
1226
+ (0.53.0, #962), and the plan says what the retire will do.
1227
+
1228
+ - **The instance's own tree.** When the spawn's receipt says the instance
1229
+ was given a tree, a real directory at `work/` is that tree. A home without a valid receipt
1230
+ goes by its record: `worktree` is the own tree, and a record with no work
1231
+ mode (or one the kernel does not know) has it when Git confirms that
1232
+ `work/` is a registered linked worktree whose top level it is, by the test
1233
+ of an extra tree below. The retire re-homes it, or removes it through Git
1234
+ with `--discard-worktree`, after copying what is uncommitted to recovery.
1235
+ When the record names no repository, the retire uses the one Git names for
1236
+ the tree and does not write it into the record; the plan's note and the
1237
+ receipt's `warnings` name it. An own tree for which there is no repository
1238
+ at all, recorded or read, is never removed with the home: the retire
1239
+ refuses with `E_WORK_PRESERVATION_FAILED` before it stops, runs or removes
1240
+ anything, `--force` included, and says to move the directory out or delete
1241
+ it by hand.
1242
+ - **A directory of the home.** A real directory at `work/` that is not the
1243
+ instance's own tree: one found where the work mode has a link (an
1244
+ attached, a checkout or a workspace instance, or a record with no work
1245
+ mode), or under a valid receipt that says no tree was given, whatever the
1246
+ record says now. The home's recovery leaves `work/` out, so when the
1247
+ directory holds anything the retire copies it to recovery on its own
1248
+ (`workRecovery.path/work`, class `directory work bytes`), checks the copy
1249
+ against what it inspected, and removes the directory with the home, as it
1250
+ does a directory instance's work. Whatever it holds goes into the copy, a
1251
+ `.git` directory included.
1252
+ It is never read as a tree to move, never removed through Git, and
1253
+ `--discard-worktree` and `--force` change none of this. An entry the copy
1254
+ cannot take (a FIFO, a socket, a device node) refuses the retire with
1255
+ `E_WORK_INSPECTION_FAILED` before anything is stopped, run or removed:
1256
+ remove or move that entry, then retire again. When Git confirms that the
1257
+ directory is a registered worktree of a repository, its entry stays in
1258
+ that repository until a prune; the receipt's `warnings` name the
1259
+ repository and give the command (`git -C <repository> worktree prune`).
1260
+ Its branch and its commits are not touched.
1261
+ - **A link** is never the instance's own tree, whatever the record says
1262
+ (0.53.0, #973). It goes with the home, and what it leads to is not
1263
+ touched: not copied, not moved, not removed, not read through Git, and no
1264
+ branch is deleted, with `--discard-worktree` and `--force` as without
1265
+ them. The record is a file the instance can write; what a link leads to
1266
+ is not the instance's. For a link under a record that says `worktree`
1267
+ (the instance's registered worktree moved elsewhere with a link left in
1268
+ its place, for example) the plan says so in a note and in its `defaults:`
1269
+ line, and the receipt's `warnings` say where the link led: the path the
1270
+ system resolved it to just before the home was removed, or that it led
1271
+ nowhere that could be read. (The receipt holds the path as it is; the
1272
+ retire's text spells a control character or a bidi override in any
1273
+ warning as `\u{<hex>}`.) The tree stays registered in its repository.
1274
+ A retry of a failed spawn's cleanup over a link verifies no Git debt
1275
+ through it: the debt stays outstanding, and `--force` removes the home
1276
+ alone. A link that is no longer a link when the retire inspects the home
1277
+ again (a retire hook put a directory or a file in its place) refuses the
1278
+ retire (`E_WORK_INSPECTION_FAILED`) and keeps the home, since removing
1279
+ the home would take what replaced the link, uncopied. The message says
1280
+ what is there now and how it ends. For a directory it points to the
1281
+ retire plan and says to run the retire again, which reads the home as it
1282
+ is then, by its record as it is then and the spawn's receipt: a directory
1283
+ that is a directory of the home (the first case above) is copied to
1284
+ recovery and removed with the home; a directory under a `worktree` record
1285
+ and a worktree's receipt is kept with the home until a person moves it
1286
+ out. For a file, or an entry that is neither a link, a directory nor a
1287
+ file, it says that no retire removes it and to move it out of the home or
1288
+ remove it, then run the retire again; it does not point to the plan. The
1289
+ next retires keep such an entry with the home and say so each time (under
1290
+ a `worktree` record after the retire hooks have run again, under an
1291
+ `attached`, `checkout` or `workspace` record before anything runs). For
1292
+ an entry that cannot be read it says that the retire reads it again when
1293
+ it is run again. [The retire plan](desktop-cli-api.md#retire) has each
1294
+ case.
1295
+ - **A directory instance's `work/`** is held against the spawn's receipt as
1296
+ before: a record that says `directory` where the receipt does not, or the
1297
+ other way round, refuses the retire.
1298
+
1299
+ Before 0.53.0 a real directory in the second case was read as a worktree.
1300
+ Most retires of such a home were refused, and one shape was not: under a
1301
+ record that named no repository, the directory was removed with the home
1302
+ and nothing of it was copied.
1303
+
1043
1304
  #### Extra trees at retire
1044
1305
 
1045
1306
  An instance can hold [extra trees](#extra-trees) in its home beside `work/`.
@@ -1069,8 +1330,8 @@ It runs after the retire hooks and before the `work/` step, so a refusal
1069
1330
  leaves `work/` untouched. For each tree:
1070
1331
 
1071
1332
  - **A clean tree is removed.** Clean means that `git status`, ignored and
1072
- untracked files included, is empty; no merge, rebase, cherry-pick, revert,
1073
- bisect or sequencer operation is in progress; and its HEAD commit is
1333
+ untracked files included, is empty; no Git operation is in progress
1334
+ ([what counts](#git-operation-in-progress)); and its HEAD commit is
1074
1335
  reached by a ref of its repository (the tree's own HEAD, reflog and
1075
1336
  `refs/worktree/` refs do not count: they go with its admin entry). The retire runs `git worktree remove` (without
1076
1337
  `--force`) and `git worktree prune`, and verifies that the tree is gone from
@@ -1114,12 +1375,39 @@ the new path.
1114
1375
  with each, and they are part of the plan's revision: a tree created, removed,
1115
1376
  dirtied or cleaned between the plan and a guarded apply, or a new target for
1116
1377
  it, refuses the apply with `E_PLAN_STALE` before anything runs. The retire
1117
- checks the trees again at the step itself and refuses with `E_PLAN_STALE`,
1118
- keeping the home, rather than move or remove a tree in a way the plan did
1119
- not say. The retire hooks have run by then, and no tree was moved or
1120
- removed. The fields are in
1378
+ checks the trees again at the step itself and refuses with
1379
+ `E_WORK_PRESERVATION_FAILED`, keeping the home, rather than move or remove a
1380
+ tree in a way the plan did not say. The retire hooks have run by then, and
1381
+ no tree was moved or removed; that is why the code is not `E_PLAN_STALE`,
1382
+ which says that nothing happened (it was, before OATS 0.52.0). The fields are in
1121
1383
  [the CLI API](desktop-cli-api.md#retire).
1122
1384
 
1385
+ <a id="git-operation-in-progress"></a>
1386
+ **What counts as a Git operation in progress.** The retire reads what `git
1387
+ status` reads, in the tree's own Git directory: a rebase or a `git am`
1388
+ (`rebase-merge`, `rebase-apply`), a merge (`MERGE_HEAD`), a cherry-pick or a
1389
+ revert (`CHERRY_PICK_HEAD`, `REVERT_HEAD`, or a `sequencer/todo` between two
1390
+ commits of several) and a bisect (`BISECT_LOG`). What an operation leaves
1391
+ behind when it has ended does not count: `REBASE_HEAD` after a rebase that
1392
+ stopped on a conflict and was continued, `AUTO_MERGE` and `MERGE_MSG` after a
1393
+ cherry-pick or a revert, `BISECT_START` and `BISECT_NAMES` without a
1394
+ `BISECT_LOG`, a `sequencer` directory without a `todo`. A tree that holds
1395
+ only such files is clean. The retire does not remove them: they are Git's.
1396
+
1397
+ The check keeps work, so it errs towards "in progress": an entry counts when
1398
+ it is there, whatever it is, and one that cannot be looked at (no permission,
1399
+ for example) counts too. In a repository that stores its refs in the reftable
1400
+ format, `CHERRY_PICK_HEAD` and `REVERT_HEAD` are not files; there, and only
1401
+ there, the retire asks Git for the two (`git rev-parse -q --verify`, in the
1402
+ tree), and any answer but Git's plain "not there" counts: a failure, a
1403
+ timeout, no Git.
1404
+
1405
+ The same answer decides two more things. An instance's own worktree with no
1406
+ change of its own, in a home that changed, gets a recovery of the home only
1407
+ unless an operation is in progress in it; then the recovery holds the
1408
+ worktree too, with the operation's state. And `oats doctor` says `an
1409
+ operation in progress` of a retained worktree by it.
1410
+
1123
1411
  #### After a retire: inspect, restore, dispose
1124
1412
 
1125
1413
  A retire can leave two things behind outside the removed home: a recovery
@@ -1146,7 +1434,8 @@ link. A fact doctor can't read is said on its line.
1146
1434
  - A retained worktree line gives the path, the repository, the branch (or
1147
1435
  `detached at <commit>`), and `clean` or `not clean; uncommitted: <classes>`
1148
1436
  (staged or unstaged changes, conflicts, untracked or ignored files, an
1149
- operation in progress). Doctor doesn't ask Git for the status of a
1437
+ operation in progress, [as a retire reads it](#git-operation-in-progress)).
1438
+ Doctor doesn't ask Git for the status of a
1150
1439
  repository whose configuration names a content filter (`filter.<driver>.clean`
1151
1440
  or `.process`), because the status would run it: the line says `clean:
1152
1441
  unknown` and names the filter. The status never enters a submodule: it
@@ -1442,7 +1731,8 @@ and hooks, and fetches and writes nothing.
1442
1731
  A process is "still running" when its pid runs with the recorded start
1443
1732
  time. It counts as gone only when its pid does not run (the operating
1444
1733
  system says no such process: `kill -0` fails with ESRCH), or runs with another
1445
- start. When the start cannot be read (for example where `ps` fails), the
1734
+ start, or is a zombie: it has exited or was killed, and its parent has not
1735
+ reaped it. When the start cannot be read (for example where `ps` fails), the
1446
1736
  process is never taken for gone. `add` and `remove` refuse with
1447
1737
  `E_LIFECYCLE_BUSY`, naming the pid and the exact file to remove by hand once
1448
1738
  you have checked it: the record `.oats/trees/<p>.json`, or the claim
@@ -1463,7 +1753,9 @@ A claim left by a command that was killed is taken over by the next one,
1463
1753
  once its holder (pid and start time) is verified gone. Any git step the
1464
1754
  killed command left running is ended first, so it cannot finish late on
1465
1755
  the new tree. A quarantined
1466
- home or one being retired is refused (`E_INSTANCE_RETIRING`).
1756
+ home or one being retired is refused (`E_INSTANCE_RETIRING`): one for which
1757
+ a self-retire is scheduled, and, from OATS 0.52.0, one whose retire is
1758
+ running (the add reads the home's claim and takes nothing).
1467
1759
 
1468
1760
  **`remove`** runs `git worktree remove` (without `--force`) and `git worktree
1469
1761
  prune` on a tree `add` recorded, then drops the record. It keeps the branch