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