@awebai/oats 0.67.1 → 0.68.1
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/bin/oats.mjs +112 -16
- package/docs/capabilities.md +54 -5
- package/docs/capability-manifest.schema.json +4 -0
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +248 -9
- package/docs/desktop.md +316 -63
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +42 -3
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/release-notes/v0.68.1.md +102 -0
- package/docs/servers.md +6 -1
- package/docs/souls-and-instances.md +38 -3
- package/docs/tui.md +663 -243
- package/docs/upgrading.md +66 -6
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +6 -5
- package/lib/core.mjs +222 -38
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-resolution.mjs +5 -5
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +225 -78
- package/lib/servers.mjs +11 -7
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +15 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-panel.mjs +6 -2
- package/packages/client/instance-display-name.mjs +18 -0
- package/packages/client/keymap.mjs +89 -45
- package/packages/client/keys-file.mjs +9 -5
- package/packages/client/panel-views.mjs +16 -3
- package/packages/client/spawn-naming.mjs +7 -6
- package/packages/client/spawn-preview-cli.mjs +37 -1
- package/packages/client/spawn-preview-contract.mjs +35 -0
- package/packages/client/spawn-preview.mjs +35 -2
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +5 -5
- package/packages/tui/lib/actions.mjs +51 -27
- package/packages/tui/lib/client.mjs +4 -2
- package/packages/tui/lib/config.mjs +4 -4
- package/packages/tui/lib/main.mjs +27 -13
- package/packages/tui/lib/model.mjs +143 -21
- package/packages/tui/lib/store.mjs +343 -68
- package/packages/tui/lib/term/keys.mjs +5 -3
- package/packages/tui/lib/term/kitty.mjs +28 -10
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +33 -28
- package/packages/tui/lib/views/capabilities.mjs +6 -6
- package/packages/tui/lib/views/frame.mjs +88 -109
- package/packages/tui/lib/views/help.mjs +57 -35
- package/packages/tui/lib/views/instances.mjs +48 -30
- package/packages/tui/lib/views/souls.mjs +9 -8
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +92 -43
package/docs/desktop-cli-api.md
CHANGED
|
@@ -89,6 +89,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
89
89
|
| `schedule-history`, `schedule-read-2` | run history with identity and provenance (gate on `schedule-read-2`) | `scheduleHistoryApi: 3` |
|
|
90
90
|
| `workspace-v2` | `onboard`, `sync`, `package`, `workspace status`, `capabilities`, `souls` | `workspaceApi: 2` |
|
|
91
91
|
| `instance-modules` | `instance.json` `modules`/`providers`/`workspace`; module drift in status; preview `modules[]` | |
|
|
92
|
+
| `instance-upgrade` | `oats instance upgrade` plan/apply/undo for stopped local homes; optional `upgrade` hook; `modules.<cap>.previous`; `modules-upgraded` event; start/restart package `drift` | |
|
|
92
93
|
| `spawn-provider-payload` | `oats spawn … --provider <cap> <key>=<value>` | |
|
|
93
94
|
| `served-identity` | `decision.effective.providers`; the served `identity` in inspect and status | |
|
|
94
95
|
| `packages-no-approval` | no package approval anywhere | |
|
|
@@ -140,6 +141,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
140
141
|
| `instance-color` | `oats instance color <instance> (<color> \| --clear)`, local and `--server` ([An instance's colour](#an-instances-colour-oats-instance-color)); `color` on `oats status --json` instance rows, on `oats server roster --json` rows and on `oats inspect --home` `instance` (`null` for none). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows have no `color` | `instanceColorApi: 1` (payload only) |
|
|
141
142
|
| `deployments-list` | `oats deployments [list]\|add\|remove\|import --json`, this computer's list of its deployments (`~/.oats/config/deployments.json`); `listed` on `oats onboard --json`; a kernel command run in an unlisted deployment lists it ([This computer's deployments](#this-computers-deployments-oats-deployments)). Gate on the probe: there is no fallback scan | `deploymentsApi: 1` |
|
|
142
143
|
| `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
|
|
144
|
+
| `instance-suggest-name` | `oats instance suggest-name --soul <soul> (--task <t> \| --task-file <f>) [--harness claude\|pi] [--model <m>] [--launch-config <n>] --json`: the name a `--suggest-name` spawn of `<soul>` would get, chosen on this machine for a spawn that may land on another, not made unique ([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)). Local only: `--server` is `E_BAD_ARGS`. Gate on the local probe; without it, the spawn goes unnamed (numbered, or named where it lands) | |
|
|
145
|
+
| `spawn-apply-suggest-name` | `--suggest-name` on a spawn apply, without `--preview`: the apply names the instance as a preview's `--suggest-name` would, on the machine that spawns, and its result carries `naming` ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)). Routed, the host needs the feature (`E_REMOTE_INCOMPATIBLE`, nothing sent): gate on the host's `probe.features` and don't send the flag to a host without it | |
|
|
143
146
|
|
|
144
147
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
145
148
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -2509,8 +2512,9 @@ oats spawn <soul> --preview --suggest-name --task-file <f> [the flags of a real
|
|
|
2509
2512
|
|
|
2510
2513
|
A preview that also chooses the instance's name, from the task (`--task-file`,
|
|
2511
2514
|
or `--task <text>`). Like every preview it writes nothing and runs no hooks.
|
|
2512
|
-
- `--suggest-name`
|
|
2513
|
-
`E_BAD_ARGS`.
|
|
2515
|
+
- `--suggest-name` with `--name`, `--purpose` or `--expect-decision` is
|
|
2516
|
+
`E_BAD_ARGS`. Without `--preview` it names an apply
|
|
2517
|
+
([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)).
|
|
2514
2518
|
- **The call.** The kernel makes one non-interactive call through the
|
|
2515
2519
|
harness, executable and environment the spawn would launch (the launch
|
|
2516
2520
|
configuration's `env`, not its `args`), with this prompt on stdin, never in
|
|
@@ -2597,6 +2601,40 @@ or `--task <text>`). Like every preview it writes nothing and runs no hooks.
|
|
|
2597
2601
|
not advertise `spawn-suggest-name` is refused (`E_REMOTE_INCOMPATIBLE`)
|
|
2598
2602
|
before the spawn is sent.
|
|
2599
2603
|
|
|
2604
|
+
#### On an apply (feature `spawn-apply-suggest-name`)
|
|
2605
|
+
|
|
2606
|
+
```text
|
|
2607
|
+
oats spawn <soul> --suggest-name --task-file <f> [the flags of a real spawn] [--json]
|
|
2608
|
+
```
|
|
2609
|
+
|
|
2610
|
+
An apply with `--suggest-name` and no `--name`, `--purpose` or
|
|
2611
|
+
`--expect-decision` names the instance on the machine that spawns, by the
|
|
2612
|
+
preview's call and rules above, through the soul's harness.
|
|
2613
|
+
- The name is `<descriptive>-<role>`, made unique as a preview's is, and it is
|
|
2614
|
+
placed exactly as `--name <name>` would be.
|
|
2615
|
+
- On any failure the instance is numbered as it is today, and `naming` says
|
|
2616
|
+
why. A failed call is never an error: the spawn goes on.
|
|
2617
|
+
- The call is made before anything is placed, after the executable is
|
|
2618
|
+
resolved and the harness packages probed. An apply has no preflight
|
|
2619
|
+
budget: the call has its own 20 s. Every later bound of the apply (the
|
|
2620
|
+
hooks, the launch) starts after it, so the apply can take up to 20 s longer
|
|
2621
|
+
than without the flag. A caller with its own deadline on the apply allows
|
|
2622
|
+
for that.
|
|
2623
|
+
- The result carries `naming`, in the preview's shape and with its closed
|
|
2624
|
+
`reason` set, whenever `--suggest-name` was given
|
|
2625
|
+
([Apply](#apply), its result). The text answer prints a
|
|
2626
|
+
`name: suggested by …` or `name: numbered (…)` line.
|
|
2627
|
+
- **A race.** Another soul's spawn that takes the name between the naming
|
|
2628
|
+
and the placement makes this apply `E_INSTANCE_NAME_TAKEN`, as for `--name`
|
|
2629
|
+
(nothing was created by this call; spawn again for another name). The same
|
|
2630
|
+
soul's is `E_PLACEMENT_TAKEN`, as for any name.
|
|
2631
|
+
- Without `--suggest-name`, an apply is unchanged: numbered, with no call.
|
|
2632
|
+
- **`--server`:** the call runs on the host, through the routed apply. A host
|
|
2633
|
+
that does not advertise `spawn-apply-suggest-name` is refused
|
|
2634
|
+
(`E_REMOTE_INCOMPATIBLE`) before the spawn is sent; the route never drops
|
|
2635
|
+
the flag. A caller that would rather have the host number the instance
|
|
2636
|
+
checks the host's `probe.features` and does not send the flag.
|
|
2637
|
+
|
|
2600
2638
|
**Provider settings.**
|
|
2601
2639
|
- `providers` is the `--provider` map as typed.
|
|
2602
2640
|
- `settings.<cap>`: the merged payload (manifest defaults, then workspace,
|
|
@@ -2636,7 +2674,8 @@ Feature `spawn-apply-2`, `spawnApplyApi: 1`. The Desktop gates on
|
|
|
2636
2674
|
- The home is reserved with a non-recursive `mkdir`. A concurrent loser
|
|
2637
2675
|
refuses `E_PLACEMENT_TAKEN {instance, home}` having touched nothing. Names
|
|
2638
2676
|
are deployment-wide: a same-name race with another soul ends in
|
|
2639
|
-
`E_INSTANCE_NAME_TAKEN` (for `--name`) or
|
|
2677
|
+
`E_INSTANCE_NAME_TAKEN` (for `--name` and a suggested name) or
|
|
2678
|
+
`E_PLACEMENT_TAKEN`.
|
|
2640
2679
|
- A refused child spawn appends `child-spawn-refused` to the parent's log (on
|
|
2641
2680
|
apply only).
|
|
2642
2681
|
- `--max-age <s>` with `--expect-decision <revision>` (feature
|
|
@@ -2713,7 +2752,9 @@ with `--expect-decision` records the key and decision in `instance.json`.
|
|
|
2713
2752
|
`wakeScheduleError` (a requested wake), `worktreeHooks` (feature
|
|
2714
2753
|
`worktree-event`: only when the spawn ran `worktree` hooks, the receipt
|
|
2715
2754
|
`[{capability, ok, required, log, exitCode, signal?, timedOut?,
|
|
2716
|
-
contract?}]`, `log` being the hook's log file)
|
|
2755
|
+
contract?}]`, `log` being the hook's log file), `naming` (feature
|
|
2756
|
+
`spawn-apply-suggest-name`: only with `--suggest-name`, `{source, reason?,
|
|
2757
|
+
message?, ms, harness?, model?}` as on the preview).
|
|
2717
2758
|
- A spawn that runs `worktree` hooks can take up to 30 minutes per hook
|
|
2718
2759
|
([the worktree event](capabilities.md#the-worktree-event)).
|
|
2719
2760
|
|
|
@@ -2730,9 +2771,90 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2730
2771
|
`E_INSTANCE_NAME_TAKEN {instance, home, session?}`; a typed name never gets
|
|
2731
2772
|
a silent `-2`.
|
|
2732
2773
|
- The name is part of the decision.
|
|
2774
|
+
- Routed (`--server`), `--name` needs a host that advertises `spawn-name`:
|
|
2775
|
+
`E_REMOTE_INCOMPATIBLE` otherwise, with nothing sent. A saved route here
|
|
2776
|
+
under that name is `E_ROUTE_EXISTS`, before the spawn is sent.
|
|
2733
2777
|
- `--preview --suggest-name` (feature `spawn-suggest-name`) chooses a
|
|
2734
2778
|
descriptive name for the task, `<descriptive>-<role>`, which the apply then
|
|
2735
2779
|
passes as `--name` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)).
|
|
2780
|
+
An apply with `--suggest-name` (feature `spawn-apply-suggest-name`) chooses
|
|
2781
|
+
it itself ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)).
|
|
2782
|
+
- `oats instance suggest-name` (feature `instance-suggest-name`) chooses one on
|
|
2783
|
+
this machine for a spawn on another
|
|
2784
|
+
([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)).
|
|
2785
|
+
|
|
2786
|
+
### A name for a spawn elsewhere (`oats instance suggest-name`)
|
|
2787
|
+
|
|
2788
|
+
Feature `instance-suggest-name`.
|
|
2789
|
+
|
|
2790
|
+
```text
|
|
2791
|
+
oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] --json
|
|
2792
|
+
```
|
|
2793
|
+
|
|
2794
|
+
The name a spawn of `<soul>` would get by `--suggest-name`, chosen on the
|
|
2795
|
+
machine that asks (a Desktop's, with the spawn dialog open) for a spawn that
|
|
2796
|
+
may land on another.
|
|
2797
|
+
|
|
2798
|
+
- **What it touches.** It resolves no workspace, writes nothing, records
|
|
2799
|
+
nothing and reserves no name. It reads only this machine's launch
|
|
2800
|
+
configurations (the `oats-local.yaml` in reach of `--dir`, else the working
|
|
2801
|
+
directory) and the OATS tmux server's environment, as a spawn's pane would
|
|
2802
|
+
have it; it resolves no souls, members, lock or remote. The deployment it
|
|
2803
|
+
reads is not added to this computer's deployments list.
|
|
2804
|
+
- **The soul is only a name.** It gives the role (the last word of the name,
|
|
2805
|
+
after any package qualifier) and needn't exist on this machine. It is
|
|
2806
|
+
checked as a soul name's shape (`<soul>`, `<package>/<soul>`,
|
|
2807
|
+
`<package>--<soul>`), never resolved.
|
|
2808
|
+
- **Not made unique.** The words, role and length rules are the preview's
|
|
2809
|
+
([The suggested name](#the-suggested-name-feature-spawn-suggest-name)), but no
|
|
2810
|
+
`-2` is added: the machine the spawn lands on owns uniqueness, and a name
|
|
2811
|
+
taken there is its `E_INSTANCE_NAME_TAKEN` at the apply.
|
|
2812
|
+
- **The harness and model.** The harness is `--harness`, else the
|
|
2813
|
+
configuration's, else claude. Its executable and environment are what a
|
|
2814
|
+
spawn on this machine would launch it with: `--launch-config` if given
|
|
2815
|
+
(`none` for the bare harness), else this machine's default configuration
|
|
2816
|
+
for that harness, else the harness's own executable. The model is
|
|
2817
|
+
`--model`, else the configuration's: `@native-default` is the harness's
|
|
2818
|
+
own, and a preference list names its first entry (no catalogue is
|
|
2819
|
+
probed: the naming call is the only process the command starts). It
|
|
2820
|
+
matters for pi; claude always names with `haiku`. The task text goes to this machine's harness and model, as the
|
|
2821
|
+
preview's naming does.
|
|
2822
|
+
- **The call** is the preview's, with the same prompt, argv and isolation,
|
|
2823
|
+
and its model call is bounded as the preview's is: at most 20 s and 4 KiB
|
|
2824
|
+
of output.
|
|
2825
|
+
- **The answer** is the usual envelope, `ok: true` whether the name was
|
|
2826
|
+
suggested or numbered:
|
|
2827
|
+
|
|
2828
|
+
```json
|
|
2829
|
+
{"schemaVersion": 1, "ok": true, "result": {"name": "fix-flaky-login-developer", "naming": {"source": "suggested", "ms": 2310, "harness": "claude", "model": "haiku"}}}
|
|
2830
|
+
```
|
|
2831
|
+
|
|
2832
|
+
```json
|
|
2833
|
+
{"schemaVersion": 1, "ok": true, "result": {"naming": {"source": "numbered", "reason": "harness-failed", "message": "claude could not be run: claude is not installed on this machine (claude binary not found on PATH)", "ms": 0}}}
|
|
2834
|
+
```
|
|
2835
|
+
|
|
2836
|
+
- `name` is present only when `naming.source` is `"suggested"`.
|
|
2837
|
+
- `naming` has the preview's shape, and `naming.reason` its closed set:
|
|
2838
|
+
`no-task` (`--task ""`, or a blank task file; no call is made),
|
|
2839
|
+
`unsupported-harness` (codex; no call is made), `timeout`,
|
|
2840
|
+
`harness-failed` (a nonzero exit, a signal, or no executable here: no
|
|
2841
|
+
such executable, or a configuration's `{fromEnv}` reference not set
|
|
2842
|
+
here; `message` names the cause, never a value), `invalid-reply`.
|
|
2843
|
+
- A naming failure is not an error: `ok: true` with
|
|
2844
|
+
`naming.source: "numbered"`.
|
|
2845
|
+
- The text answer is the name, or `numbered (<reason>: <message>)`.
|
|
2846
|
+
- **Refusals** (`E_BAD_ARGS` unless named): no `--soul`, or one that is not
|
|
2847
|
+
a soul name's shape; neither or both of `--task` and `--task-file`, or one
|
|
2848
|
+
that cannot be read; a `--harness` other than pi, claude or codex; a
|
|
2849
|
+
`--harness` that is not the named configuration's; a flag or argument it
|
|
2850
|
+
does not take; `--server`. An unknown `--launch-config` is
|
|
2851
|
+
`E_LAUNCH_CONFIG_UNKNOWN`.
|
|
2852
|
+
- **Never routed.** `oats instance` commands route through `--server`, but
|
|
2853
|
+
this one runs where it is asked: a name for another machine is decided
|
|
2854
|
+
here. `--server` is refused before anything is sent.
|
|
2855
|
+
- **When the feature is missing** (an older local kernel), a client spawns
|
|
2856
|
+
without a name: the host numbers the instance, or names it itself if it
|
|
2857
|
+
advertises `spawn-apply-suggest-name` and the client sends `--suggest-name`.
|
|
2736
2858
|
|
|
2737
2859
|
### Spawn origin
|
|
2738
2860
|
|
|
@@ -2982,9 +3104,9 @@ A failed `add` reports the same facts about its rollback in `details`:
|
|
|
2982
3104
|
| `E_BASE_UNKNOWN` | the new HEAD is not the fetched commit; the message names both |
|
|
2983
3105
|
| `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT` | a required `worktree` hook failed or timed out, or a hook answered `env`; the tree is removed (`details.hooks`, `details.rolledBack`) |
|
|
2984
3106
|
| `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
|
|
2985
|
-
| `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message)
|
|
3107
|
+
| `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message), or an unregistered residue differs from the recorded branch (the message and `details.git` list the modified or nonignored untracked paths). The record is kept. Save the changes, or discard, then retry |
|
|
2986
3108
|
| `E_CHILDREN_RUNNING` | `remove`: an instance attached to the tree has a session that is running, or that cannot be read. Answered under the purpose's claim, before Git is asked anything: nothing is removed and the record is kept. `details: {purpose, path, children: [{instance, home, session}]}`, `session` being `"running"` or `"unknown"`; only the instances that refuse are listed. The message names each one and what was seen, and the step: `oats instance stop <instance>`, or retire it, then remove again. No flag removes anyway. It is the code [a retire](#retire-children-running) answers, with other `details`: a retire answers it for a child it asked to stop and that did not; `remove` for an attached instance it found running or unread, and it asks nobody to stop, so there is no `childrenStopped` |
|
|
2987
|
-
| `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or
|
|
3109
|
+
| `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, removal could not be verified, or an unregistered residue could not be checked against its recorded branch or deleted; the record is kept. A failure after Git started removal reports possible partial deletion and the retry, never that nothing was removed. A missing or invalid `.git` marker names the manual step: save any work, remove the directory by hand, then run `remove` again to drop the record. See [extra-tree removal recovery](souls-and-instances.md#extra-trees) |
|
|
2988
3110
|
| `E_LIFECYCLE_FAILED` | an error that is not the kernel's; with [`details.cause`](#kernel-codes) when it has a code of its own or is a defect, and without it when it is a refusal without a code. When it is the purpose's claim that could not be taken (`<home>/.oats/trees` cannot be made, the claim's file cannot be written), the message is `the claim <path> could not be taken (…); nothing was done`. Also a command that was refused the claim after its takeover had ended a dead command's git step: the message names the group it ended first, then the refusal, and `details` are that refusal's (a refusal of the kernel's has no `details.cause`; anything else has it by the same rule) |
|
|
2989
3111
|
|
|
2990
3112
|
A rollback that cannot finish keeps the record and says so in the message
|
|
@@ -3029,6 +3151,11 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
|
|
|
3029
3151
|
the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
|
|
3030
3152
|
`<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
|
|
3031
3153
|
`<home>/.agents/skills/<cap>/<skill>/`).
|
|
3154
|
+
After a package upgrade, the moved row also carries
|
|
3155
|
+
`previous: {from, commit, digest, materializedAt, receipt}`: one level, for
|
|
3156
|
+
its latest move. Readers tolerate this additive field. The verified copy
|
|
3157
|
+
for undo lives at `<home>/.oats/previous/<receipt>/`; each move replaces the
|
|
3158
|
+
previous state, and retirement preserves it in recovery.
|
|
3032
3159
|
- `branch`: for a worktree instance, the branch its worktree was created on.
|
|
3033
3160
|
For an attached or checkout instance, the branch the tree's HEAD named at
|
|
3034
3161
|
the spawn, or `null` when HEAD was detached or named a ref OATS carries no
|
|
@@ -3751,6 +3878,10 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
3751
3878
|
bytes}`. Only a regular file is opened (no symlinks, same device and inode
|
|
3752
3879
|
after open), and at most its last 4 MiB is read (`"tail"`).
|
|
3753
3880
|
- **Kinds:** `spawned`, `launched`, `restarted`, `stopped`, `stop-refused`,
|
|
3881
|
+
`modules-upgraded` (`data: {receipt, modules:[{capability, from, to}]}`,
|
|
3882
|
+
written after the module swap and retirement baseline complete),
|
|
3883
|
+
`upgrade-refused` (a failure with no successful or uncertain apply-hook outcome,
|
|
3884
|
+
naming the failed step or module; older clients tolerate the unknown kind),
|
|
3754
3885
|
`retire-planned`, `retired`, `retire-refused` (0.53.0,
|
|
3755
3886
|
[below](#retire-refused-event)), `worktree-retained`, `worktree-removed`,
|
|
3756
3887
|
`branch-deleted` (not written since 0.41.0: no retire deletes a branch;
|
|
@@ -3983,6 +4114,84 @@ oats instance attention [--message <text>] [--clear] --json
|
|
|
3983
4114
|
readable `instance.json`), `E_HOME_MISMATCH`, `E_EVENTS_FAILED` (the write
|
|
3984
4115
|
failed; nothing else is affected).
|
|
3985
4116
|
|
|
4117
|
+
## Upgrading an instance's package modules
|
|
4118
|
+
|
|
4119
|
+
Requires the `instance-upgrade` feature in `oats version --json` or `oats status --json`.
|
|
4120
|
+
|
|
4121
|
+
```text
|
|
4122
|
+
oats instance upgrade <instance> --plan [--json]
|
|
4123
|
+
oats instance upgrade <instance> --plan-revision <revision> --idempotency-key <key> [--json]
|
|
4124
|
+
oats instance upgrade <instance> --undo --plan [--json]
|
|
4125
|
+
oats instance upgrade <instance> --undo --plan-revision <revision> --idempotency-key <key> [--json]
|
|
4126
|
+
```
|
|
4127
|
+
|
|
4128
|
+
This local act resolves an instance like `oats retire`, from its deployment
|
|
4129
|
+
or a parent's home. It uses the lifecycle claim and requires a stopped,
|
|
4130
|
+
readable session. A running or unreadable session is `E_SESSION_RUNNING`,
|
|
4131
|
+
naming `oats instance stop <instance>`, upgrade, then session start. It does
|
|
4132
|
+
not support `--server` or several homes in one call.
|
|
4133
|
+
|
|
4134
|
+
A read-only plan stages package copies outside the home, verifies the locked
|
|
4135
|
+
commit and integrity as spawn does, then removes that staging. Its revision
|
|
4136
|
+
hashes the facts. Each moving module reports `{capability,
|
|
4137
|
+
from:{version,commit,digest}, to:{version,commit,integrity},
|
|
4138
|
+
skills:{added,removed,changed}, inject, hooks, provider:{decision,reason}}`.
|
|
4139
|
+
`inject` and `hooks` indicate changes. The plan also lists kept modules and
|
|
4140
|
+
member drift and `homeChangedSinceSpawn` (both excluded from `planRevision`).
|
|
4141
|
+
A package no longer in the lock is kept. Member modules and
|
|
4142
|
+
the soul body never move. A provider refusal refuses the whole act.
|
|
4143
|
+
|
|
4144
|
+
Apply rechecks the revision under the lifecycle claim (`E_PLAN_STALE` with
|
|
4145
|
+
a fresh plan on mismatch) and records an idempotency receipt. It stages the
|
|
4146
|
+
whole modules, skills, inject and hook composition through spawn's composer,
|
|
4147
|
+
using the soul at its recorded commit. It saves and verifies the previous
|
|
4148
|
+
state before provider hooks run, swaps the composition, updates only a clean
|
|
4149
|
+
home's retirement `homeFingerprint`, commits the receipt, then appends
|
|
4150
|
+
`modules-upgraded`. A dirty home keeps its baseline file byte-identical, so
|
|
4151
|
+
older kernels also preserve its pre-upgrade edits at retirement. Work-tree
|
|
4152
|
+
fingerprints and digest versions always remain as recorded. The moved module record's `previous`
|
|
4153
|
+
is described under [`instance.json`](#instancejson).
|
|
4154
|
+
Upgrade runs no launch hooks. When a moved module's new manifest has no launch
|
|
4155
|
+
hook, apply removes its recorded launch/environment contribution in the same
|
|
4156
|
+
journaled metadata swap. When it still declares a launch hook, the existing
|
|
4157
|
+
contribution stays with settings and trust refreshed, until the next start
|
|
4158
|
+
replaces it wholesale. Undo restores the recorded contribution from the
|
|
4159
|
+
backed-up `instance.json`. There is no pending dropped-hook state to resolve
|
|
4160
|
+
at start, so consecutive upgrades need no intervening start.
|
|
4161
|
+
Receipts live at `<home>/.oats/upgrade-receipt.<key>.json`. Retirement's baseline
|
|
4162
|
+
excludes only that exact receipt filename pattern and `.oats/.staging-upgrade-*`;
|
|
4163
|
+
`.oats/previous/` is ordinary home content covered by the baseline.
|
|
4164
|
+
|
|
4165
|
+
Before the commit boundary, failure restores composed home bytes and removes
|
|
4166
|
+
staging and the saved previous state only when no provider hook succeeded or
|
|
4167
|
+
has an uncertain outcome. A non-zero hook result must be explicitly observed
|
|
4168
|
+
and recorded in the same invocation to permit this rollback. A hook reporting
|
|
4169
|
+
failure must leave no effects of its own; provider host effects are its
|
|
4170
|
+
responsibility.
|
|
4171
|
+
|
|
4172
|
+
Before spawning a hook, the receipt records `step: "hook <capability>"` and
|
|
4173
|
+
`hooks.inFlight: <capability>`. Resuming an unknown in-flight outcome durably
|
|
4174
|
+
records `uncertain: [<capability>]` before retry work. Even a kill before spawn
|
|
4175
|
+
counts as uncertain if not-started cannot be proved. After any success or
|
|
4176
|
+
uncertainty, failure records `partial`: the error names pending work and asks
|
|
4177
|
+
for the same `--idempotency-key` to finish forward. Retry re-runs pending
|
|
4178
|
+
idempotent hooks, including an uncertain one. A subsequent hook failure stays
|
|
4179
|
+
partial; it cannot authorize rollback. Start refuses with `E_UPGRADE_PARTIAL`
|
|
4180
|
+
while the receipt is partial. If completion is impossible, the remedy is respawn.
|
|
4181
|
+
|
|
4182
|
+
The commit boundary is after swap and baseline: the receipt becomes
|
|
4183
|
+
`status: "complete"` with `steps.cleaned: false` before the success event and staging cleanup.
|
|
4184
|
+
Successful cleanup sets `steps.cleaned: true`. A failure after that boundary
|
|
4185
|
+
leaves the upgrade committed. The same-key retry finishes event publication
|
|
4186
|
+
and cleanup, without
|
|
4187
|
+
hooks or copies. Start is allowed with one warning naming that retry; a new
|
|
4188
|
+
upgrade or undo plan refuses until cleanup finishes. `E_UPGRADE_PARTIAL`
|
|
4189
|
+
applies only before commit. Retirement adds no special cleanup behavior.
|
|
4190
|
+
|
|
4191
|
+
`--undo` uses the latest verified previous state and the restored version's
|
|
4192
|
+
`upgrade` hook, under the same adoption and failure protocol. A version
|
|
4193
|
+
without that hook cannot be restored through this act; respawn instead.
|
|
4194
|
+
|
|
3986
4195
|
## Lifecycle: stop and retire
|
|
3987
4196
|
|
|
3988
4197
|
Feature `lifecycle-plans` (and `retire-retention`), `lifecycleApi: 1`. A
|
|
@@ -4359,6 +4568,7 @@ in flight.
|
|
|
4359
4568
|
|
|
4360
4569
|
Feature `lifecycle-claim-stop`, OATS 0.52.0 (#866). A retire and a stop apply
|
|
4361
4570
|
hold the home's claim for their whole run, and `oats worktree add` reads it.
|
|
4571
|
+
This table covers those three commands; the upgrade pairs follow separately.
|
|
4362
4572
|
Each cell is the answer of the command that **arrives**. It is given at once
|
|
4363
4573
|
and before any effect: that command stopped, ran, copied, made and removed
|
|
4364
4574
|
nothing, and the command already on the home is not disturbed.
|
|
@@ -4373,6 +4583,25 @@ nothing, and the command already on the home is not disturbed.
|
|
|
4373
4583
|
| the claim file is no readable claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
|
|
4374
4584
|
| the holder of the claim is gone | not refused | not refused | not refused | not refused |
|
|
4375
4585
|
|
|
4586
|
+
<a id="upgrade-lifecycle-pairs"></a>
|
|
4587
|
+
The `instance-upgrade` pairs use the same home's lifecycle claim:
|
|
4588
|
+
|
|
4589
|
+
| On the home | Arriving command | Answer |
|
|
4590
|
+
|---|---|---|
|
|
4591
|
+
| a retire is running | `oats instance upgrade` apply | `E_INSTANCE_RETIRING` |
|
|
4592
|
+
| a self-retire is scheduled | `oats instance upgrade` apply | `E_INSTANCE_RETIRING` |
|
|
4593
|
+
| a stop or upgrade apply is running | `oats instance upgrade` apply | `E_LIFECYCLE_BUSY` |
|
|
4594
|
+
| a holder's verb is unknown, its liveness cannot be read, or the claim is unreadable | `oats instance upgrade` apply | `E_LIFECYCLE_BUSY` |
|
|
4595
|
+
| the holder of the claim is gone | `oats instance upgrade` apply | not refused after claim takeover checks |
|
|
4596
|
+
| an upgrade apply is running | `oats retire` or `oats instance stop --apply` | `E_LIFECYCLE_BUSY` |
|
|
4597
|
+
| an upgrade apply is running | `oats worktree add` | not refused |
|
|
4598
|
+
|
|
4599
|
+
Upgrade requires a stopped session. Start and restart do not take or read the
|
|
4600
|
+
lifecycle claim: upgrade instead holds their existing `.oats-start.lock`
|
|
4601
|
+
mutex until its final invocation receipt is persisted. A start blocked by an
|
|
4602
|
+
upgrade mutex names the same-key retry. A partial receipt refuses starts through the remaining
|
|
4603
|
+
finalization. The following stop/retire notes describe the original table.
|
|
4604
|
+
|
|
4376
4605
|
- **A holder is answered before a stale plan, by both verbs.** A guarded
|
|
4377
4606
|
retire and a stop apply compare the revision they were sent only once
|
|
4378
4607
|
they hold the claim, so beside a holder the answer is the cell above
|
|
@@ -4448,7 +4677,7 @@ since, action}`, with `holder` on `E_LIFECYCLE_BUSY`:
|
|
|
4448
4677
|
stop this may be a child of the instance asked for.**
|
|
4449
4678
|
- `lock`: the file that names the holder. `pid` and `since`: the holder's
|
|
4450
4679
|
pid and when it took the claim.
|
|
4451
|
-
- **`action`: the holder's verb**, `"retire"` or `"
|
|
4680
|
+
- **`action`: the holder's verb**, `"retire"`, `"stop"` or `"upgrade"`. A claim written
|
|
4452
4681
|
by a kernel before this feature has no verb and reads as `"retire"`. A
|
|
4453
4682
|
reader treats a value it does not know as busy.
|
|
4454
4683
|
- <a id="claim-file-text"></a>**Text of a claim file is never part of an
|
|
@@ -5287,7 +5516,7 @@ line and says that nothing was done:
|
|
|
5287
5516
|
second for a retire, which does not wait).
|
|
5288
5517
|
`details` is `{instance, home, lock, holder: "unknown"}`; the message is
|
|
5289
5518
|
`<lock> is not a readable claim; nothing was done — inspect it and remove
|
|
5290
|
-
it if no oats retire or oats instance
|
|
5519
|
+
it if no oats retire, oats instance stop or oats instance upgrade holds it, then retry`.
|
|
5291
5520
|
- A claim whose holder is gone and that this kernel cannot take over is
|
|
5292
5521
|
never removed either: its `nonce` is not the 32 hexadecimal digits a claim
|
|
5293
5522
|
carries (a file written or damaged by hand); or it is the claim of a
|
|
@@ -5299,7 +5528,7 @@ line and says that nothing was done:
|
|
|
5299
5528
|
The message is `the
|
|
5300
5529
|
process that held <lock> (pid <pid>) is gone, and this file is not a claim
|
|
5301
5530
|
this kernel can take over (<why>); nothing was done — inspect <lock> and
|
|
5302
|
-
remove it if no oats retire or oats instance
|
|
5531
|
+
remove it if no oats retire, oats instance stop or oats instance upgrade holds it, then retry` (0.52.0, #874; before,
|
|
5303
5532
|
the first was answered as a live holder, to wait for, and the second as
|
|
5304
5533
|
`E_LIFECYCLE_FAILED` with the system's `ENAMETOOLONG` about a file that
|
|
5305
5534
|
does not exist). Removing that one file lets the next retire take the
|
|
@@ -5638,6 +5867,16 @@ oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --
|
|
|
5638
5867
|
Features `session-start`, `session-restart`, and `launch-config` for the
|
|
5639
5868
|
selection flags. See [the start workflow](desktop-instance-start.md).
|
|
5640
5869
|
|
|
5870
|
+
Start and restart keep the home's recorded module copies. Their successful
|
|
5871
|
+
results with package drift include `drift:[{capability, recorded:{version,commit},
|
|
5872
|
+
locked:{version,commit}}]` for package modules behind the deployment lock,
|
|
5873
|
+
and omit the field when none are behind. Text prints one line after the start:
|
|
5874
|
+
`<n> package module(s) behind the lock (<cap> <version> @ <shortcommit> → <version> @ <shortcommit>); to move them: oats instance stop <instance>; oats instance upgrade <instance> --plan`.
|
|
5875
|
+
Restart has no upgrade flag. A partial upgrade receipt refuses a start with
|
|
5876
|
+
`E_UPGRADE_PARTIAL`, naming the retry with the original idempotency key.
|
|
5877
|
+
A committed receipt with `steps.cleaned: false` permits start and adds one
|
|
5878
|
+
warning naming the same-key cleanup retry.
|
|
5879
|
+
|
|
5641
5880
|
- The result is `{instance, agent, home, harness, backend, model,
|
|
5642
5881
|
launchConfig, yolo, target, startedAt, restartCount, reused, warnings}`,
|
|
5643
5882
|
plus `nativeRecordId` and `stop` (a restart's stop receipt) when they apply,
|