@awebai/oats 0.52.0 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +304 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/desktop-cli-api.md +673 -58
  6. package/docs/desktop-instance-start.md +25 -12
  7. package/docs/execution-targets.md +1 -0
  8. package/docs/implementation.md +175 -11
  9. package/docs/integrations.md +6 -3
  10. package/docs/knowledge.md +2 -2
  11. package/docs/macos-test-runs.md +246 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-lane.md +210 -6
  15. package/docs/release-notes/v0.53.0.md +1274 -0
  16. package/docs/schedules.md +7 -1
  17. package/docs/souls-and-instances.md +237 -15
  18. package/docs/tui.md +453 -21
  19. package/docs/upgrading.md +298 -0
  20. package/docs/workspaces.md +3 -3
  21. package/lib/automations.mjs +22 -22
  22. package/lib/claim.mjs +93 -4
  23. package/lib/config-data.mjs +4 -1
  24. package/lib/core.mjs +569 -121
  25. package/lib/instance-events.mjs +19 -1
  26. package/lib/instance-git.mjs +39 -3
  27. package/lib/instance-inspect.mjs +5 -6
  28. package/lib/instance-lifecycle.mjs +145 -18
  29. package/lib/instance-resolution.mjs +59 -6
  30. package/lib/launch-preference.mjs +226 -15
  31. package/lib/local-edit.mjs +118 -0
  32. package/lib/packages.mjs +13 -4
  33. package/lib/pi-bridge.mjs +308 -0
  34. package/lib/refused-text.mjs +11 -0
  35. package/lib/remote.mjs +190 -25
  36. package/lib/resolve.mjs +2 -1
  37. package/lib/retained-after-retire.mjs +2 -2
  38. package/lib/retire-output.mjs +12 -1
  39. package/lib/schedule-host.mjs +6 -35
  40. package/lib/shell-word.mjs +13 -0
  41. package/lib/soul-launch-verbs.mjs +153 -0
  42. package/lib/stable-node.mjs +62 -0
  43. package/lib/teams-verbs.mjs +18 -46
  44. package/lib/workspace.mjs +49 -19
  45. package/package-catalog.json +4 -4
  46. package/package.json +2 -1
  47. package/packages/client/attach-exit.mjs +25 -0
  48. package/packages/client/cli-adapter.mjs +16 -3
  49. package/packages/client/cli-locator.mjs +2 -2
  50. package/packages/client/deployment-contract.mjs +4 -0
  51. package/packages/client/deployment-facts.mjs +71 -10
  52. package/packages/client/deployment-panel.mjs +49 -11
  53. package/packages/client/deployment-read-cli.mjs +7 -3
  54. package/packages/client/display-text.mjs +8 -2
  55. package/packages/client/instance-acts.mjs +46 -10
  56. package/packages/client/instance-events-contract.mjs +4 -2
  57. package/packages/client/instance-presentation.mjs +66 -2
  58. package/packages/client/instance-tree.mjs +23 -14
  59. package/packages/client/kernel-lines.mjs +31 -0
  60. package/packages/client/kernel-made.mjs +23 -0
  61. package/packages/client/launch-prompt-outcome.mjs +51 -16
  62. package/packages/client/lifecycle-contract.mjs +45 -4
  63. package/packages/client/liveness.mjs +14 -1
  64. package/packages/client/own-codes.mjs +31 -0
  65. package/packages/client/panel-views.mjs +18 -11
  66. package/packages/client/readiness-contract.mjs +3 -1
  67. package/packages/client/remote-address.mjs +34 -9
  68. package/packages/client/remote-identity-memory.mjs +94 -0
  69. package/packages/client/remote-roster.mjs +92 -6
  70. package/packages/client/session-attach.mjs +175 -0
  71. package/packages/client/spawn-apply-contract.mjs +16 -4
  72. package/packages/client/spawn-messages.mjs +26 -3
  73. package/packages/client/spawn-preview-cli.mjs +8 -2
  74. package/packages/client/spawn-preview-contract.mjs +5 -1
  75. package/packages/client/terminal-exec.mjs +21 -0
  76. package/packages/client/workspace-choices.mjs +95 -0
  77. package/packages/client/workspace-views.mjs +39 -3
  78. package/packages/record/README.md +21 -0
  79. package/packages/record/bin/setup.mjs +108 -15
  80. package/packages/tui/README.md +30 -12
  81. package/packages/tui/lib/actions.mjs +16 -1
  82. package/packages/tui/lib/client.mjs +32 -1
  83. package/packages/tui/lib/config.mjs +151 -0
  84. package/packages/tui/lib/main.mjs +117 -46
  85. package/packages/tui/lib/model.mjs +392 -0
  86. package/packages/tui/lib/read.mjs +473 -0
  87. package/packages/tui/lib/store.mjs +364 -0
  88. package/packages/tui/lib/term/keys.mjs +44 -0
  89. package/packages/tui/lib/term/screen.mjs +16 -4
  90. package/packages/tui/lib/term/text.mjs +60 -0
  91. package/packages/tui/lib/term/tty.mjs +13 -3
  92. package/packages/tui/lib/views/detail.mjs +46 -0
  93. package/packages/tui/lib/views/frame.mjs +230 -36
  94. package/packages/tui/lib/views/help.mjs +125 -13
  95. package/packages/tui/lib/views/instances.mjs +137 -0
  96. package/packages/tui/lib/views/scroll.mjs +19 -0
  97. package/packages/tui/lib/views/switcher.mjs +97 -0
  98. package/skills/oats-getting-started/SKILL.md +2 -2
package/docs/schedules.md CHANGED
@@ -550,6 +550,10 @@ add` / `oats schedule add` definitions need no trust.
550
550
  **Opting out on one host.** `oats trigger disable <member>/<id>` writes
551
551
  `triggers.disabled`, and `oats schedule disable <member>/<id>` writes
552
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
553
557
  schedule part of a qualified ID accepts up to 100 characters in both
554
558
  `schedules.disabled` and named `automations.trust` entries. Trigger definitions
555
559
  and `triggers.disabled` keep their 40-character limit; the shared trust list
@@ -679,7 +683,9 @@ own shell, not from an instance home:
679
683
  link survives an upgrade. With a version manager (mise, nvm, asdf, fnm) the
680
684
  node on `PATH` is that version's own install, so the unit records that
681
685
  version's path, and `host status` reports `node-missing` once that version
682
- is removed.
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)).
683
689
  - **oats**: the `oats.mjs` of the oats that runs `install`. When that is inside
684
690
  `$OATS_INSTANCE_HOME` or its `work` (a clone in an instance's work tree,
685
691
  an attached instance's included), `install` and
@@ -448,9 +448,10 @@ beside the homes, which names its holder by pid and start time. Any other
448
448
  retire of that instance (plain, guarded or `--self`, `--force` included) is
449
449
  refused at once with `E_LIFECYCLE_BUSY`, before it stops anything, copies
450
450
  anything or runs a hook: a retire hook releases things that exist once, such
451
- as a messaging identity or a scheduled job. A self-retire's completion is
452
- refused the same way, after it has waited up to 3 s for the retire that
453
- 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,
454
455
  while its completion lives. A retire killed while it holds the claim leaves
455
456
  the file behind until that name is retired again: the next retire takes the
456
457
  claim over, because its holder is verifiably gone, and the file is safe to
@@ -683,7 +684,7 @@ holds of each kind:
683
684
 
684
685
  | Of the nested repository | The copy holds |
685
686
  |---|---|
686
- | `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)) |
687
688
  | every local branch | the branch under its name, at its commit |
688
689
  | the reflogs of `HEAD` and of each branch | branch and `HEAD` reflogs are carried, with every commit they name |
689
690
  | tags | the tags and what they name |
@@ -719,6 +720,54 @@ cannot carry at all (an entry that is not a file, a directory or a symbolic
719
720
  link, or a nested repository whose path is not valid UTF-8) refuses the copy,
720
721
  here as anywhere.
721
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
+
722
771
  **A worktree that cannot be proven unchanged.** Two things make a worktree
723
772
  not provable:
724
773
 
@@ -818,10 +867,12 @@ clean. Such an entry refuses the retire, at one of three points:
818
867
  again in the same home with `oats session start --home <abs>`. A
819
868
  self-retire (`--self`) is completed by its detached completion, which stops
820
869
  the session and refuses in the same way; the refusal is recorded beside the
821
- home, as described below. After a refused self-retire only `oats retire
822
- <instance>` continues: `oats session start` refuses while the self-retire's
823
- pending marker is there, and a retire clears it. Of the refusals at this
824
- 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
825
876
  process, comes with the session still running;
826
877
  - **after the hooks**, when a retire hook left the entry behind: the hooks
827
878
  have run, and the home, the work and the recovery written before the hooks
@@ -1032,10 +1083,73 @@ status before its tmux window dies a few seconds later. The completion then
1032
1083
  retires the instance exactly as an external `oats retire` would: quiesce the
1033
1084
  harness, preserve uncommitted work, run retire hooks, repair lineage, remove
1034
1085
  the worktree and the home. Success leaves nothing behind: the home and the
1035
- marker are gone. A failure writes `.oats-retired-<instance>.json` beside the
1036
- retained home (plus the usual quarantine marker when hooks reported incomplete
1037
- cleanup), shows in `oats status` and the Desktop as a failed deferred
1038
- 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.
1039
1153
 
1040
1154
  When a retire hook reports incomplete cleanup, the home is quarantined before
1041
1155
  any worktree step: the worktree, its git admin entry and the branch stay
@@ -1106,6 +1220,87 @@ attached children in one note that covers both cases. Only the link changes:
1106
1220
  the child's `instance.json` is not rewritten, and its AGENTS.md and TASK.md
1107
1221
  still name the old path.
1108
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
+
1109
1304
  #### Extra trees at retire
1110
1305
 
1111
1306
  An instance can hold [extra trees](#extra-trees) in its home beside `work/`.
@@ -1135,8 +1330,8 @@ It runs after the retire hooks and before the `work/` step, so a refusal
1135
1330
  leaves `work/` untouched. For each tree:
1136
1331
 
1137
1332
  - **A clean tree is removed.** Clean means that `git status`, ignored and
1138
- untracked files included, is empty; no merge, rebase, cherry-pick, revert,
1139
- 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
1140
1335
  reached by a ref of its repository (the tree's own HEAD, reflog and
1141
1336
  `refs/worktree/` refs do not count: they go with its admin entry). The retire runs `git worktree remove` (without
1142
1337
  `--force`) and `git worktree prune`, and verifies that the tree is gone from
@@ -1187,6 +1382,32 @@ no tree was moved or removed; that is why the code is not `E_PLAN_STALE`,
1187
1382
  which says that nothing happened (it was, before OATS 0.52.0). The fields are in
1188
1383
  [the CLI API](desktop-cli-api.md#retire).
1189
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
+
1190
1411
  #### After a retire: inspect, restore, dispose
1191
1412
 
1192
1413
  A retire can leave two things behind outside the removed home: a recovery
@@ -1213,7 +1434,8 @@ link. A fact doctor can't read is said on its line.
1213
1434
  - A retained worktree line gives the path, the repository, the branch (or
1214
1435
  `detached at <commit>`), and `clean` or `not clean; uncommitted: <classes>`
1215
1436
  (staged or unstaged changes, conflicts, untracked or ignored files, an
1216
- 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
1217
1439
  repository whose configuration names a content filter (`filter.<driver>.clean`
1218
1440
  or `.process`), because the status would run it: the line says `clean:
1219
1441
  unknown` and names the filter. The status never enters a submodule: it