@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.
- package/README.md +2 -1
- package/bin/oats.mjs +304 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/desktop-cli-api.md +673 -58
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +175 -11
- package/docs/integrations.md +6 -3
- package/docs/knowledge.md +2 -2
- package/docs/macos-test-runs.md +246 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +210 -6
- package/docs/release-notes/v0.53.0.md +1274 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +237 -15
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +93 -4
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +569 -121
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +5 -6
- package/lib/instance-lifecycle.mjs +145 -18
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +226 -15
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +6 -35
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/workspace.mjs +49 -19
- package/package-catalog.json +4 -4
- package/package.json +2 -1
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/cli-adapter.mjs +16 -3
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-contract.mjs +4 -0
- package/packages/client/deployment-facts.mjs +71 -10
- package/packages/client/deployment-panel.mjs +49 -11
- package/packages/client/deployment-read-cli.mjs +7 -3
- package/packages/client/display-text.mjs +8 -2
- package/packages/client/instance-acts.mjs +46 -10
- package/packages/client/instance-events-contract.mjs +4 -2
- package/packages/client/instance-presentation.mjs +66 -2
- package/packages/client/instance-tree.mjs +23 -14
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-prompt-outcome.mjs +51 -16
- package/packages/client/lifecycle-contract.mjs +45 -4
- package/packages/client/liveness.mjs +14 -1
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/panel-views.mjs +18 -11
- package/packages/client/readiness-contract.mjs +3 -1
- package/packages/client/remote-address.mjs +34 -9
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +92 -6
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-contract.mjs +16 -4
- package/packages/client/spawn-messages.mjs +26 -3
- package/packages/client/spawn-preview-cli.mjs +8 -2
- package/packages/client/spawn-preview-contract.mjs +5 -1
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-views.mjs +39 -3
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +30 -12
- package/packages/tui/lib/actions.mjs +16 -1
- package/packages/tui/lib/client.mjs +32 -1
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +117 -46
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +44 -0
- package/packages/tui/lib/term/screen.mjs +16 -4
- package/packages/tui/lib/term/text.mjs +60 -0
- package/packages/tui/lib/term/tty.mjs +13 -3
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +230 -36
- package/packages/tui/lib/views/help.mjs +125 -13
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- 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
|
|
452
|
-
|
|
453
|
-
|
|
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.
|
|
822
|
-
|
|
823
|
-
pending marker
|
|
824
|
-
|
|
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.
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
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
|
|
1139
|
-
|
|
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
|
|
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
|