@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
@@ -0,0 +1,142 @@
1
+ # OATS 0.54.0
2
+
3
+ 2026-10-13
4
+
5
+ ## Upgrade
6
+
7
+ - **Nothing is required.** Install the Desktop first and the CLI second, as
8
+ [Upgrading](../upgrading.md) says: a 0.53.0 Desktop refuses a 0.54.0 CLI.
9
+
10
+ - **To get the skill `/oats-token-saving`,** pin `oats.framework: v1.10.0`
11
+ in your workspace and run `oats sync`. Instances already running keep the
12
+ briefing and the skills they were spawned with; new spawns get the new
13
+ ones. See Added and Provider updates.
14
+
15
+ - **A script that reads a refusal about a repository reference** (its
16
+ message, or `details.ref`, `details.url`, `details.value`) now reads a
17
+ display form: user information is never in it; a refused value made only
18
+ of letters, digits, spaces and `._/+-:` is shown as written; any other
19
+ value that cannot be rebuilt from its parts is replaced whole by a fixed
20
+ text. See Changed and Fixed
21
+ ([#1077](https://github.com/awebai/oats/issues/1077)). Codes and field
22
+ shapes are unchanged, and so is the reference Git itself is given.
23
+
24
+ - **The official catalog's versions in this release** are oats.framework
25
+ 1.10.0, oats.okf 5.0.3, oats.aweb 1.27.1 and oats.engineering 1.9.1: see
26
+ Provider updates. Pin what your workspace uses, then run `oats sync`.
27
+
28
+ ## Added
29
+
30
+ - **`oats.core`: the skill `/oats-token-saving`, and three lines of its
31
+ briefing** ([#1103](https://github.com/awebai/oats/issues/1103)). A message
32
+ between instances costs twice: the sender writes it, and the receiver is
33
+ woken, reads it with its whole context and often answers. The skill gives
34
+ one test before sending, "who will do something different because of this,
35
+ and what?", and the rules that follow from it:
36
+ - **to whom:** only the instance that will act on it, with no copies and no
37
+ sending to every holder of a role;
38
+ - **what not to send:** acknowledgements and courtesy, progress and status,
39
+ what a shared record already shows, someone else's words passed along, and
40
+ the story of how the sender got there. A message that needs a confirmation
41
+ says so and gets one line back;
42
+ - **don't ask for what you can read,** and never ask for progress reports or
43
+ set a helper up to send them;
44
+ - **what a message holds:** first what the receiver must do, exact
45
+ references, one topic, one message per task boundary. A spec, a brief or a
46
+ review's findings is the long message, sent once as a file or a link;
47
+ - **what is never cut:** what moves work, what a role owes, and what is owed
48
+ on a record (a verdict on the pull request, a decision on its issue, the
49
+ evidence of a hand-over, the report of a fault or of one's own mistake).
50
+
51
+ The skill is provider-neutral: it names no messaging capability, and how to
52
+ send stays with that capability's own skill. The `oats.core` briefing, which
53
+ every instance with `oats.core` reads, gains the test in three lines, so it
54
+ applies before the skill is loaded. An instance spawned before the release
55
+ that carries this keeps its briefing; new spawns get it
56
+ ([`oats.core`](../souls-and-instances.md)).
57
+
58
+ ## Changed
59
+
60
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.55.0`.** The compatibility band
61
+ admits 0.54. Upgrade the CLI and the Desktop together: a 0.53.0 Desktop
62
+ refuses a 0.54.0 CLI. No new gate on the band. `oats tui` runs the kernel it
63
+ ships with and is held to the same band.
64
+
65
+ - **Diagnostic messages, details, provenance and workspace `cannot-read` values
66
+ now preserve bounded plain refused values, construct displays that omit user
67
+ information (including SSH users), or withhold the reference, while the seven
68
+ rejected argument fields share the bounded plain rule and Git lines are shown
69
+ only for unchanged original operation references
70
+ and no literal `@` in the original line, replacing
71
+ [#1075](https://github.com/awebai/oats/issues/1075)'s scrubbed-line behavior
72
+ ([#1077](https://github.com/awebai/oats/issues/1077)).**
73
+
74
+ ## Fixed
75
+
76
+ - **Repository diagnostics no longer copy user information from selected
77
+ references ([#1077](https://github.com/awebai/oats/issues/1077)).** Messages,
78
+ reference-bearing details and provenance, schema problems and workspace
79
+ `cannot-read` fields use a display constructed from recognised host and path
80
+ components, with a verbatim exception for original refused values of 1–256
81
+ ASCII letters, digits, spaces or `._/+-:` characters. The same predicate
82
+ serves the seven selected rejected arguments; it never trims or decodes an
83
+ input. Malformed or mixed values outside that rule are withheld whole,
84
+ including harmless text, while known declaration files and key locations
85
+ remain available. Raw derived fragments qualify for the plain exception only
86
+ through their original selected source, never from a nonplain source. Plain
87
+ recognition is not a secret detector: credential-like text within the
88
+ permitted alphabet remains visible.
89
+ Git's own line is shown only when all original operation references are
90
+ proved unchanged by display construction and the original line contains no
91
+ `@`; otherwise the whole line becomes a fixed notice directing the operator
92
+ to run the operation by hand. No substring is recovered. This replaces the
93
+ quoted-line disclosure behavior shipped for unknown Git failures.
94
+ See the [diagnostic display contract](../workspaces.md#repository-references-in-diagnostics).
95
+ Standalone file/path meanings, command-consumed values and Git's original
96
+ transport reference are unchanged.
97
+ Explicit pinned-source diagnostics keep a constructed reference and its
98
+ validated commit, or withhold the whole source without a plain fallback.
99
+ Rejected argument values use the contract's bounded plain-value rule and
100
+ neutral withholding notice; valid operational arguments are unchanged. Unknown Git failures quote only
101
+ stderr: empty stderr adds no line unless output overflow needs a kernel budget notice.
102
+
103
+ - **Repository and package refusals explain an omitted reference without
104
+ exposing it ([#1077](https://github.com/awebai/oats/issues/1077)).** The
105
+ originating refusal explains withholding or user-information omission once;
106
+ existing message slots keep the explanation when forwarding it. HTTP(S)
107
+ userinfo refusals keep their specific cause and credential-helper advice,
108
+ and package refusals keep their own reason. Admission, codes and field shapes
109
+ are unchanged.
110
+
111
+ - `oats souls` and `oats capabilities` now show every catalog discovery
112
+ problem below their text tables, including unreadable locked package
113
+ souls. Diagnostics stay on stdout in JSON order, with the kernel's code
114
+ and message; partial listings still exit 0
115
+ ([#1098](https://github.com/awebai/oats/issues/1098)).
116
+
117
+ ## Provider updates
118
+
119
+ - **oats.framework 1.10.0: oats.core 2.6.0.** One new skill and three lines
120
+ of instruction text in oats.core; no hook, command, schema or provider
121
+ contract changes, and the capability floors are unchanged (oats.core
122
+ `>=0.40.0`).
123
+ - oats.core gains the skill `/oats-token-saving` and names it in its
124
+ briefing, as the entry under Added says
125
+ ([#1103](https://github.com/awebai/oats/issues/1103)). The two commands
126
+ the skill tells an instance to read before asking, `oats status` and
127
+ `oats instance events <instance>`, exist in every kernel oats.core
128
+ admits.
129
+ - A deployment gets it by pinning `oats.framework: v1.10.0` and running
130
+ `oats sync`. Instances already running keep the briefing and the skills
131
+ they were spawned with; new spawns get the new ones.
132
+
133
+ ## Documentation
134
+
135
+ - **Upgrading: the Desktop goes before the CLI
136
+ ([#1107](https://github.com/awebai/oats/issues/1107)).**
137
+ [Upgrading OATS on a host](../upgrading.md) now says so, and why: a
138
+ Desktop refuses a CLI of a newer minor version, so with the CLI moved
139
+ first it lists no instance until it is replaced. The Upgrade section of
140
+ the [0.53.0 notes](v0.53.0.md#upgrade) gained that step, and one for a
141
+ host that comes from 0.51 or earlier: 0.52.0's steps first, the aw client
142
+ among them, before `oats sync`.
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
@@ -98,7 +98,8 @@ is a code change, reviewed in its repo.
98
98
  ### OATS operational knowledge is a capability
99
99
 
100
100
  An agent's knowledge of OATS itself (status, spawn, retire, finding other
101
- souls) is ordinary capability content: **`oats.core`** (package
101
+ souls, and keeping its messages to other instances few and short:
102
+ `/oats-token-saving`) is ordinary capability content: **`oats.core`** (package
102
103
  `oats.framework`). Workspaces give it to every soul through
103
104
  `defaults.capabilities: { oats.core: { from: package } }`; a soul may say
104
105
  `oats.core: off`. **`oats.setup`** (same package) carries the whole-architecture
@@ -448,9 +449,10 @@ beside the homes, which names its holder by pid and start time. Any other
448
449
  retire of that instance (plain, guarded or `--self`, `--force` included) is
449
450
  refused at once with `E_LIFECYCLE_BUSY`, before it stops anything, copies
450
451
  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,
452
+ as a messaging identity or a scheduled job. A self-retire's completion
453
+ waits for the retire that scheduled it to release the claim, for up to ten
454
+ minutes (OATS 0.53.0; before, it gave up after 3 s). Beside any other
455
+ 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
456
  while its completion lives. A retire killed while it holds the claim leaves
455
457
  the file behind until that name is retired again: the next retire takes the
456
458
  claim over, because its holder is verifiably gone, and the file is safe to
@@ -683,7 +685,7 @@ holds of each kind:
683
685
 
684
686
  | Of the nested repository | The copy holds |
685
687
  |---|---|
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) |
688
+ | `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
689
  | every local branch | the branch under its name, at its commit |
688
690
  | the reflogs of `HEAD` and of each branch | branch and `HEAD` reflogs are carried, with every commit they name |
689
691
  | tags | the tags and what they name |
@@ -719,6 +721,54 @@ cannot carry at all (an entry that is not a file, a directory or a symbolic
719
721
  link, or a nested repository whose path is not valid UTF-8) refuses the copy,
720
722
  here as anywhere.
721
723
 
724
+ <a id="copied-as-one-file"></a>
725
+ **What the copy takes as one file must be a regular file.** The index,
726
+ `info/attributes`, the stash's log and a nested repository's reflogs are each
727
+ copied as one file. A link at such a path is followed, as Git follows it: the
728
+ recovery holds a plain file with what Git reads through the link. A path
729
+ that is not there, or a link that leads nowhere, is left out of the copy, as
730
+ Git reads nothing there. Anything else at such a path (a directory, empty or
731
+ not, a FIFO, an entry that cannot be read) refuses the copy with
732
+ `E_WORK_PRESERVATION_FAILED`, naming the path and what is there. The retire
733
+ looks before it copies, so the answer is the same on every file system.
734
+
735
+ For the index this refusal is not reached. Git reads the index before the
736
+ copy takes it, and Git fails where a directory, or a file that is not an
737
+ index, stands at it. The retire then refuses with Git's message: for the
738
+ instance's own tree at the inspection (`E_WORK_INSPECTION_FAILED`, before
739
+ anything is stopped, run or removed), for a nested repository when its state
740
+ is read for the copy (`E_WORK_PRESERVATION_FAILED`, the home and the work
741
+ kept). An index that cannot be read refuses at the inspection in both,
742
+ unless it is a nested repository's and a link leads to it: the retire then
743
+ refuses when that repository's state is read, as for a directory there.
744
+
745
+ <a id="no-index-file"></a>
746
+ **A tree with no index file is copied with none.** A work tree made by
747
+ `git worktree add --no-checkout`, or one whose index file was removed, has no
748
+ index file, and Git reads it as a tree whose index lists nothing: every
749
+ committed file is a staged deletion, and every file in the tree is
750
+ untracked. A retire copies it as it copies any tree that holds work, and
751
+ the recovery's `repo/` then has no index file either: Git reads it as it
752
+ read the tree. The same holds for a nested repository that has a commit and
753
+ no index file.
754
+ `git reset` in the recovery makes an index from `HEAD`: the committed files
755
+ are tracked again, and a file that was changed in the tree shows as changed.
756
+
757
+ <a id="nested-no-commit"></a>
758
+ **A nested repository with no commit at its `HEAD` is copied as one.** After
759
+ `git init` and no commit, or after `git switch --orphan` in a repository that
760
+ has commits, a repository's `HEAD` names a branch nobody has committed on.
761
+ The recovery rebuilds it as it rebuilds any nested repository: its `HEAD` is
762
+ on the same branch and has no commit, its other branches are there with
763
+ their commits and their logs, and its index, what is staged in it and its
764
+ files are the source's. One with no index file either (`git init` and
765
+ nothing added) has none in the recovery. A `HEAD` with no commit that names
766
+ no local branch (a ref outside `refs/heads/`, or a branch whose name is not
767
+ UTF-8) is refused with `E_WORK_PRESERVATION_FAILED`, naming the repository,
768
+ the home and the work kept: there is no commit to detach the copy at and no
769
+ branch to put it on. A commit in that repository, or `git switch -c
770
+ <branch>` there, makes the work tree retirable.
771
+
722
772
  **A worktree that cannot be proven unchanged.** Two things make a worktree
723
773
  not provable:
724
774
 
@@ -818,10 +868,12 @@ clean. Such an entry refuses the retire, at one of three points:
818
868
  again in the same home with `oats session start --home <abs>`. A
819
869
  self-retire (`--self`) is completed by its detached completion, which stops
820
870
  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
871
+ home, as described [below](#self-retire-not-completed). No hook has run at
872
+ this point, so from OATS 0.53.0 the completion removes the self-retire's
873
+ pending marker: the instance is a stopped instance like any other, and
874
+ both `oats retire <instance>` and `oats session start` continue. Before
875
+ 0.53.0 the marker stayed, and only a retire continued. Of the refusals at
876
+ this point, only that of `--self --keep-dir`, which stays in the calling
825
877
  process, comes with the session still running;
826
878
  - **after the hooks**, when a retire hook left the entry behind: the hooks
827
879
  have run, and the home, the work and the recovery written before the hooks
@@ -1032,10 +1084,73 @@ status before its tmux window dies a few seconds later. The completion then
1032
1084
  retires the instance exactly as an external `oats retire` would: quiesce the
1033
1085
  harness, preserve uncommitted work, run retire hooks, repair lineage, remove
1034
1086
  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>`.
1087
+ marker are gone.
1088
+
1089
+ <a id="self-retire-not-completed"></a>A completion that does not complete,
1090
+ because the retire was refused or failed part way, answers nobody. It
1091
+ leaves what happened on disk (OATS 0.53.0):
1092
+
1093
+ - **Its outcome, always.** `.oats-retired-<instance>.json` beside the home
1094
+ holds `ok: false`, the code and the sentence the retire answered, and
1095
+ `retry`, the command that retries it. Its log is
1096
+ `.oats-retired-<instance>.log`. `oats status` and the Desktop show the
1097
+ outcome as a failed deferred retirement until a retire of the instance
1098
+ completes. No other command clears it: to drop it without retiring the
1099
+ instance, remove those two files by hand.
1100
+ - **Its pending marker, only when the home is owed a retire:** when a retire
1101
+ hook was started or the removal of the home began. The usual quarantine
1102
+ marker is there too when hooks reported incomplete cleanup. The instance
1103
+ then reads as retiring: `oats instance stop --apply` and `oats session
1104
+ start` answer `E_INSTANCE_RETIRING`, and `oats retire <instance>`
1105
+ continues. In every other case the completion removes its marker.
1106
+ Nothing of the home was changed, so the instance is a stopped or a
1107
+ running instance like any other: a start works, and a wake schedule may
1108
+ start it. A session or a child that the completion stopped on its way
1109
+ does not keep the marker.
1110
+ - **One event,** `retire-refused`, which says which of the two it was
1111
+ ([Events](desktop-cli-api.md#retire-refused-event)).
1112
+
1113
+ Nothing retries by itself: `oats retire <instance>` does. A completion
1114
+ removes only the marker of its own scheduling, so the marker of a later
1115
+ `--self` is left for that one's completion.
1116
+
1117
+ A completion does not start its retire while its scheduling still holds
1118
+ the home's claim (OATS 0.53.0). A scheduling that the host holds up
1119
+ therefore delays the retire and does not fail it. The completion waits for
1120
+ that one command only, which it knows by the pid and the start time it was
1121
+ given when it was started: a holder that has died, one whose liveness
1122
+ cannot be read, and any other holder are not waited for here, and the
1123
+ retire answers for them as every retire does.
1124
+
1125
+ While a completion waits, the instance reads as live in `oats status`
1126
+ until the scheduling has written its marker, which is the last thing it
1127
+ does before it releases the claim; from then on it reads `RETIRING`, as
1128
+ every scheduled self-retire does. Throughout, the scheduling is a retire
1129
+ that runs, so a stop plan shows `retiring: true`, and a stop apply
1130
+ (`E_INSTANCE_RETIRING`) and another retire (`E_LIFECYCLE_BUSY`) are refused
1131
+ with its pid. The wait ends
1132
+ when that command returns, fails or dies; ending it by hand lets the
1133
+ completion go on and retire the instance, which is what the instance asked
1134
+ for. It also ends after ten minutes (`SCHEDULING_WAIT_MS`): the completion
1135
+ then goes on to its retire, which is refused by the holder that is still
1136
+ there like any retire, and a scheduling that comes back afterwards answers
1137
+ `E_SELF_RETIRE_SCHEDULE_FAILED`, having found its completion's outcome.
1138
+
1139
+ A `--self` whose completion has already ended when the scheduling writes
1140
+ its marker answers `E_SELF_RETIRE_SCHEDULE_FAILED`, and nothing is
1141
+ scheduled: the completion left its outcome, or it is gone and left none
1142
+ (it was killed, for one). The scheduling removes the marker it wrote, with
1143
+ the completion's outcome and log if there are any, and the instance is
1144
+ still live.
1145
+
1146
+ **A home that a refused completion left stuck under 0.52.0 or earlier**
1147
+ still has its marker, and reads as retiring although nothing of it was
1148
+ changed. To retire it after all, run `oats retire <instance>`. To keep it,
1149
+ no command does this. Check that the completion the marker names is gone
1150
+ (its pid is `completionPid` in the marker), then remove by hand
1151
+ `.oats-retire-pending-<instance>.json`, `.oats-retired-<instance>.json` and
1152
+ `.oats-retired-<instance>.log` beside the home. The kernel does not do this
1153
+ for such a home, because it cannot date a refusal that it did not record.
1039
1154
 
1040
1155
  When a retire hook reports incomplete cleanup, the home is quarantined before
1041
1156
  any worktree step: the worktree, its git admin entry and the branch stay
@@ -1106,6 +1221,87 @@ attached children in one note that covers both cases. Only the link changes:
1106
1221
  the child's `instance.json` is not rewritten, and its AGENTS.md and TASK.md
1107
1222
  still name the old path.
1108
1223
 
1224
+ #### What `work/` is at retire
1225
+
1226
+ The retire and its plan read what is at `<home>/work` once, by one rule
1227
+ (0.53.0, #962), and the plan says what the retire will do.
1228
+
1229
+ - **The instance's own tree.** When the spawn's receipt says the instance
1230
+ was given a tree, a real directory at `work/` is that tree. A home without a valid receipt
1231
+ goes by its record: `worktree` is the own tree, and a record with no work
1232
+ mode (or one the kernel does not know) has it when Git confirms that
1233
+ `work/` is a registered linked worktree whose top level it is, by the test
1234
+ of an extra tree below. The retire re-homes it, or removes it through Git
1235
+ with `--discard-worktree`, after copying what is uncommitted to recovery.
1236
+ When the record names no repository, the retire uses the one Git names for
1237
+ the tree and does not write it into the record; the plan's note and the
1238
+ receipt's `warnings` name it. An own tree for which there is no repository
1239
+ at all, recorded or read, is never removed with the home: the retire
1240
+ refuses with `E_WORK_PRESERVATION_FAILED` before it stops, runs or removes
1241
+ anything, `--force` included, and says to move the directory out or delete
1242
+ it by hand.
1243
+ - **A directory of the home.** A real directory at `work/` that is not the
1244
+ instance's own tree: one found where the work mode has a link (an
1245
+ attached, a checkout or a workspace instance, or a record with no work
1246
+ mode), or under a valid receipt that says no tree was given, whatever the
1247
+ record says now. The home's recovery leaves `work/` out, so when the
1248
+ directory holds anything the retire copies it to recovery on its own
1249
+ (`workRecovery.path/work`, class `directory work bytes`), checks the copy
1250
+ against what it inspected, and removes the directory with the home, as it
1251
+ does a directory instance's work. Whatever it holds goes into the copy, a
1252
+ `.git` directory included.
1253
+ It is never read as a tree to move, never removed through Git, and
1254
+ `--discard-worktree` and `--force` change none of this. An entry the copy
1255
+ cannot take (a FIFO, a socket, a device node) refuses the retire with
1256
+ `E_WORK_INSPECTION_FAILED` before anything is stopped, run or removed:
1257
+ remove or move that entry, then retire again. When Git confirms that the
1258
+ directory is a registered worktree of a repository, its entry stays in
1259
+ that repository until a prune; the receipt's `warnings` name the
1260
+ repository and give the command (`git -C <repository> worktree prune`).
1261
+ Its branch and its commits are not touched.
1262
+ - **A link** is never the instance's own tree, whatever the record says
1263
+ (0.53.0, #973). It goes with the home, and what it leads to is not
1264
+ touched: not copied, not moved, not removed, not read through Git, and no
1265
+ branch is deleted, with `--discard-worktree` and `--force` as without
1266
+ them. The record is a file the instance can write; what a link leads to
1267
+ is not the instance's. For a link under a record that says `worktree`
1268
+ (the instance's registered worktree moved elsewhere with a link left in
1269
+ its place, for example) the plan says so in a note and in its `defaults:`
1270
+ line, and the receipt's `warnings` say where the link led: the path the
1271
+ system resolved it to just before the home was removed, or that it led
1272
+ nowhere that could be read. (The receipt holds the path as it is; the
1273
+ retire's text spells a control character or a bidi override in any
1274
+ warning as `\u{<hex>}`.) The tree stays registered in its repository.
1275
+ A retry of a failed spawn's cleanup over a link verifies no Git debt
1276
+ through it: the debt stays outstanding, and `--force` removes the home
1277
+ alone. A link that is no longer a link when the retire inspects the home
1278
+ again (a retire hook put a directory or a file in its place) refuses the
1279
+ retire (`E_WORK_INSPECTION_FAILED`) and keeps the home, since removing
1280
+ the home would take what replaced the link, uncopied. The message says
1281
+ what is there now and how it ends. For a directory it points to the
1282
+ retire plan and says to run the retire again, which reads the home as it
1283
+ is then, by its record as it is then and the spawn's receipt: a directory
1284
+ that is a directory of the home (the first case above) is copied to
1285
+ recovery and removed with the home; a directory under a `worktree` record
1286
+ and a worktree's receipt is kept with the home until a person moves it
1287
+ out. For a file, or an entry that is neither a link, a directory nor a
1288
+ file, it says that no retire removes it and to move it out of the home or
1289
+ remove it, then run the retire again; it does not point to the plan. The
1290
+ next retires keep such an entry with the home and say so each time (under
1291
+ a `worktree` record after the retire hooks have run again, under an
1292
+ `attached`, `checkout` or `workspace` record before anything runs). For
1293
+ an entry that cannot be read it says that the retire reads it again when
1294
+ it is run again. [The retire plan](desktop-cli-api.md#retire) has each
1295
+ case.
1296
+ - **A directory instance's `work/`** is held against the spawn's receipt as
1297
+ before: a record that says `directory` where the receipt does not, or the
1298
+ other way round, refuses the retire.
1299
+
1300
+ Before 0.53.0 a real directory in the second case was read as a worktree.
1301
+ Most retires of such a home were refused, and one shape was not: under a
1302
+ record that named no repository, the directory was removed with the home
1303
+ and nothing of it was copied.
1304
+
1109
1305
  #### Extra trees at retire
1110
1306
 
1111
1307
  An instance can hold [extra trees](#extra-trees) in its home beside `work/`.
@@ -1135,8 +1331,8 @@ It runs after the retire hooks and before the `work/` step, so a refusal
1135
1331
  leaves `work/` untouched. For each tree:
1136
1332
 
1137
1333
  - **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
1334
+ untracked files included, is empty; no Git operation is in progress
1335
+ ([what counts](#git-operation-in-progress)); and its HEAD commit is
1140
1336
  reached by a ref of its repository (the tree's own HEAD, reflog and
1141
1337
  `refs/worktree/` refs do not count: they go with its admin entry). The retire runs `git worktree remove` (without
1142
1338
  `--force`) and `git worktree prune`, and verifies that the tree is gone from
@@ -1187,6 +1383,32 @@ no tree was moved or removed; that is why the code is not `E_PLAN_STALE`,
1187
1383
  which says that nothing happened (it was, before OATS 0.52.0). The fields are in
1188
1384
  [the CLI API](desktop-cli-api.md#retire).
1189
1385
 
1386
+ <a id="git-operation-in-progress"></a>
1387
+ **What counts as a Git operation in progress.** The retire reads what `git
1388
+ status` reads, in the tree's own Git directory: a rebase or a `git am`
1389
+ (`rebase-merge`, `rebase-apply`), a merge (`MERGE_HEAD`), a cherry-pick or a
1390
+ revert (`CHERRY_PICK_HEAD`, `REVERT_HEAD`, or a `sequencer/todo` between two
1391
+ commits of several) and a bisect (`BISECT_LOG`). What an operation leaves
1392
+ behind when it has ended does not count: `REBASE_HEAD` after a rebase that
1393
+ stopped on a conflict and was continued, `AUTO_MERGE` and `MERGE_MSG` after a
1394
+ cherry-pick or a revert, `BISECT_START` and `BISECT_NAMES` without a
1395
+ `BISECT_LOG`, a `sequencer` directory without a `todo`. A tree that holds
1396
+ only such files is clean. The retire does not remove them: they are Git's.
1397
+
1398
+ The check keeps work, so it errs towards "in progress": an entry counts when
1399
+ it is there, whatever it is, and one that cannot be looked at (no permission,
1400
+ for example) counts too. In a repository that stores its refs in the reftable
1401
+ format, `CHERRY_PICK_HEAD` and `REVERT_HEAD` are not files; there, and only
1402
+ there, the retire asks Git for the two (`git rev-parse -q --verify`, in the
1403
+ tree), and any answer but Git's plain "not there" counts: a failure, a
1404
+ timeout, no Git.
1405
+
1406
+ The same answer decides two more things. An instance's own worktree with no
1407
+ change of its own, in a home that changed, gets a recovery of the home only
1408
+ unless an operation is in progress in it; then the recovery holds the
1409
+ worktree too, with the operation's state. And `oats doctor` says `an
1410
+ operation in progress` of a retained worktree by it.
1411
+
1190
1412
  #### After a retire: inspect, restore, dispose
1191
1413
 
1192
1414
  A retire can leave two things behind outside the removed home: a recovery
@@ -1213,7 +1435,8 @@ link. A fact doctor can't read is said on its line.
1213
1435
  - A retained worktree line gives the path, the repository, the branch (or
1214
1436
  `detached at <commit>`), and `clean` or `not clean; uncommitted: <classes>`
1215
1437
  (staged or unstaged changes, conflicts, untracked or ignored files, an
1216
- operation in progress). Doctor doesn't ask Git for the status of a
1438
+ operation in progress, [as a retire reads it](#git-operation-in-progress)).
1439
+ Doctor doesn't ask Git for the status of a
1217
1440
  repository whose configuration names a content filter (`filter.<driver>.clean`
1218
1441
  or `.process`), because the status would run it: the line says `clean:
1219
1442
  unknown` and names the filter. The status never enters a submodule: it