@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.
- package/README.md +2 -1
- package/bin/oats.mjs +314 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
- package/docs/desktop-cli-api.md +696 -60
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +184 -12
- 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 +1288 -0
- package/docs/release-notes/v0.54.0.md +142 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +239 -16
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +310 -0
- package/docs/workspaces.md +123 -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 +18 -5
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +404 -60
- 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 +75 -27
- 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 +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
|
|
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
|
|
452
|
-
|
|
453
|
-
|
|
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.
|
|
822
|
-
|
|
823
|
-
pending marker
|
|
824
|
-
|
|
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.
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
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
|
|
1139
|
-
|
|
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
|
|
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
|