@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.
Files changed (64) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +316 -63
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/release-notes/v0.68.1.md +102 -0
  17. package/docs/servers.md +6 -1
  18. package/docs/souls-and-instances.md +38 -3
  19. package/docs/tui.md +663 -243
  20. package/docs/upgrading.md +66 -6
  21. package/docs/workspaces.md +2 -2
  22. package/lib/capability-contract.mjs +6 -5
  23. package/lib/core.mjs +222 -38
  24. package/lib/instance-events.mjs +1 -1
  25. package/lib/instance-resolution.mjs +5 -5
  26. package/lib/instance-upgrade.mjs +1445 -0
  27. package/lib/materialize.mjs +225 -78
  28. package/lib/servers.mjs +11 -7
  29. package/lib/upgrade-state.mjs +101 -0
  30. package/lib/workspace.mjs +4 -1
  31. package/lib/worktree.mjs +103 -12
  32. package/package-catalog.json +5 -4
  33. package/package.json +1 -1
  34. package/packages/client/cli-adapter.mjs +15 -1
  35. package/packages/client/cli-locator.mjs +2 -2
  36. package/packages/client/deployment-panel.mjs +6 -2
  37. package/packages/client/instance-display-name.mjs +18 -0
  38. package/packages/client/keymap.mjs +89 -45
  39. package/packages/client/keys-file.mjs +9 -5
  40. package/packages/client/panel-views.mjs +16 -3
  41. package/packages/client/spawn-naming.mjs +7 -6
  42. package/packages/client/spawn-preview-cli.mjs +37 -1
  43. package/packages/client/spawn-preview-contract.mjs +35 -0
  44. package/packages/client/spawn-preview.mjs +35 -2
  45. package/packages/client/team-members.mjs +4 -1
  46. package/packages/client/workspace-step.mjs +25 -0
  47. package/packages/tui/README.md +5 -5
  48. package/packages/tui/lib/actions.mjs +51 -27
  49. package/packages/tui/lib/client.mjs +4 -2
  50. package/packages/tui/lib/config.mjs +4 -4
  51. package/packages/tui/lib/main.mjs +27 -13
  52. package/packages/tui/lib/model.mjs +143 -21
  53. package/packages/tui/lib/store.mjs +343 -68
  54. package/packages/tui/lib/term/keys.mjs +5 -3
  55. package/packages/tui/lib/term/kitty.mjs +28 -10
  56. package/packages/tui/lib/term/screen.mjs +15 -6
  57. package/packages/tui/lib/term/through.mjs +33 -28
  58. package/packages/tui/lib/views/capabilities.mjs +6 -6
  59. package/packages/tui/lib/views/frame.mjs +88 -109
  60. package/packages/tui/lib/views/help.mjs +57 -35
  61. package/packages/tui/lib/views/instances.mjs +48 -30
  62. package/packages/tui/lib/views/souls.mjs +9 -8
  63. package/packages/tui/lib/views/workspaces.mjs +55 -0
  64. package/skills/oats-getting-started/SKILL.md +92 -43
@@ -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` without `--preview`, or with `--name` or `--purpose`, is
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 `E_PLACEMENT_TAKEN`.
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); the record is kept. Commit and push, or discard, then retry |
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 the tree is still there; the record is kept |
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 `"stop"`. A claim written
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 stop holds it, then retry`.
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 stop holds it, then retry` (0.52.0, #874; before,
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,