@awebai/oats 0.66.0 → 0.68.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.
Files changed (81) hide show
  1. package/bin/oats.mjs +166 -17
  2. package/docs/capabilities.md +58 -9
  3. package/docs/capability-manifest.schema.json +5 -1
  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 +463 -13
  7. package/docs/desktop.md +363 -67
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +46 -6
  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-lane.md +16 -0
  16. package/docs/release-notes/v0.67.0.md +366 -0
  17. package/docs/release-notes/v0.67.1.md +64 -0
  18. package/docs/release-notes/v0.68.0.md +504 -0
  19. package/docs/servers.md +8 -2
  20. package/docs/souls-and-instances.md +58 -6
  21. package/docs/tui.md +1033 -237
  22. package/docs/upgrading.md +164 -26
  23. package/docs/workspaces.md +2 -2
  24. package/lib/capability-contract.mjs +8 -7
  25. package/lib/core.mjs +331 -75
  26. package/lib/instance-color.mjs +58 -0
  27. package/lib/instance-events.mjs +1 -1
  28. package/lib/instance-inspect.mjs +107 -23
  29. package/lib/instance-lifecycle.mjs +21 -1
  30. package/lib/instance-naming.mjs +187 -0
  31. package/lib/instance-resolution.mjs +10 -6
  32. package/lib/instance-upgrade.mjs +1445 -0
  33. package/lib/materialize.mjs +287 -89
  34. package/lib/servers.mjs +24 -11
  35. package/lib/soul-composition.mjs +7 -3
  36. package/lib/upgrade-state.mjs +101 -0
  37. package/lib/workspace.mjs +4 -1
  38. package/lib/worktree.mjs +103 -12
  39. package/package-catalog.json +5 -4
  40. package/package.json +1 -1
  41. package/packages/client/cli-adapter.mjs +52 -6
  42. package/packages/client/cli-locator.mjs +2 -2
  43. package/packages/client/composed-gate.mjs +10 -2
  44. package/packages/client/deployment-data.mjs +5 -0
  45. package/packages/client/deployment-identity.mjs +40 -0
  46. package/packages/client/deployment-panel.mjs +9 -3
  47. package/packages/client/inspect-boundary.mjs +11 -7
  48. package/packages/client/inspect-cache.mjs +2 -2
  49. package/packages/client/instance-name.mjs +28 -0
  50. package/packages/client/instance-presentation.mjs +11 -0
  51. package/packages/client/keymap.mjs +133 -28
  52. package/packages/client/keys-file.mjs +126 -0
  53. package/packages/client/own-codes.mjs +4 -2
  54. package/packages/client/panel-views.mjs +78 -12
  55. package/packages/client/spawn-naming.mjs +32 -0
  56. package/packages/client/spawn-preview-cli.mjs +58 -7
  57. package/packages/client/spawn-preview-contract.mjs +59 -0
  58. package/packages/client/spawn-preview-facts.mjs +8 -4
  59. package/packages/client/spawn-preview.mjs +81 -3
  60. package/packages/client/team-members.mjs +4 -1
  61. package/packages/client/workspace-step.mjs +25 -0
  62. package/packages/tui/README.md +7 -7
  63. package/packages/tui/lib/actions.mjs +92 -25
  64. package/packages/tui/lib/client.mjs +9 -4
  65. package/packages/tui/lib/config.mjs +50 -9
  66. package/packages/tui/lib/main.mjs +65 -24
  67. package/packages/tui/lib/model.mjs +292 -75
  68. package/packages/tui/lib/read.mjs +53 -1
  69. package/packages/tui/lib/store.mjs +469 -100
  70. package/packages/tui/lib/term/keys.mjs +22 -6
  71. package/packages/tui/lib/term/kitty.mjs +54 -11
  72. package/packages/tui/lib/term/screen.mjs +15 -6
  73. package/packages/tui/lib/term/through.mjs +66 -28
  74. package/packages/tui/lib/views/frame.mjs +223 -165
  75. package/packages/tui/lib/views/help.mjs +134 -29
  76. package/packages/tui/lib/views/instances.mjs +63 -22
  77. package/packages/tui/lib/views/palette.mjs +14 -4
  78. package/packages/tui/lib/views/souls.mjs +2 -2
  79. package/packages/tui/lib/views/switcher.mjs +6 -1
  80. package/packages/tui/lib/views/workspaces.mjs +55 -0
  81. package/skills/oats-getting-started/SKILL.md +96 -42
@@ -0,0 +1,192 @@
1
+ # Upgrading an existing home's package modules (#1450)
2
+
3
+ Status: decided 2026-10-22 (Pepe, option (b) on #1450, with the five conditions of the lane:release view). This supersedes workspace model v2 items 10–11 **for package modules only**: "a package pin being bumped affects only new spawns" and "the refresh is a new spawn, never an in-place recompose". The soul body still stays at its spawn commit. Member modules still change only through a respawn.
4
+
5
+ ## Why
6
+
7
+ A home keeps the modules it was spawned with, and `oats session restart` starts that copy again. So a provider fix never reaches a live seat short of a respawn.
8
+
9
+ On 2026-10-22 a seat spawned on oats.aweb 1.17.1 was restarted. Its renewal revoked the old grant without re-registering the wake broker, a bug fixed in 1.17.3. Mail stopped arriving, and readiness, which also ran from the frozen 1.17.1 copy, stayed green. Respawning a long-lived coordinator to pick up a fix is not an acceptable remedy.
10
+
11
+ ## The act
12
+
13
+ ```
14
+ oats instance upgrade <instance> --plan [--json]
15
+ oats instance upgrade <instance> --plan-revision <rev> --idempotency-key <key> [--json]
16
+ oats instance upgrade <instance> --undo --plan [--json]
17
+ oats instance upgrade <instance> --undo --plan-revision <rev> --idempotency-key <key> [--json]
18
+ ```
19
+
20
+ It runs from the deployment, or from a parent's home, with the same instance resolution as `oats retire`.
21
+
22
+ **What moves.** Every recorded module whose `from.kind` is `package` and whose recorded commit differs from the deployment lock's commit for that package moves to the locked package version. That is exactly the set that `driftOf` reports as "package moved since".
23
+ - Modules move whole: copy, skills, inject and hooks together (condition 1).
24
+ - A module of a package the lock no longer holds is not moved. The plan lists it as `kept: package no longer locked`.
25
+ - Member modules and the soul body are never moved. The plan lists member drift as information.
26
+
27
+ **Preconditions (all checked at plan and again at apply, under the instance's lifecycle claim):**
28
+ - **The session is stopped.** If it is running, or its state can't be read, the act refuses with `E_SESSION_RUNNING` and the remedy `oats instance stop <instance>`, then upgrade, then `oats session start`. Nothing changes under a running harness.
29
+ - **No retire or other lifecycle act is in flight.** Use the existing claim.
30
+ - Upgrade also holds the existing `.oats-start.lock` mutex until its final
31
+ invocation receipt is persisted; start/restart do not take the lifecycle
32
+ claim. Start acquires this path with `mkdir`; upgrade creates an exclusive
33
+ regular file with `wx`, so either kind refuses an occupied path. Upgrade
34
+ takes the lifecycle claim first and may reclaim only a regular-file mutex,
35
+ including an empty file left by a killed opener. It never reclaims a
36
+ directory. Start never reclaims the mutex and its busy message names the
37
+ same-key upgrade retry. A partial receipt refuses starts until finalization
38
+ completes.
39
+ - **The previous-state directory has no stray entries.** Check it before any
40
+ provider plan or apply hook runs.
41
+ - **The lock's package commit and integrity verify,** just as at spawn (`moduleSource`).
42
+
43
+ ## Plan (condition 3)
44
+
45
+ The plan is read-only. It returns:
46
+ - `homeChangedSinceSpawn`, whether retirement must preserve home changes;
47
+ - a revision, sha256 over the package-move facts (member drift and home-change reporting are informational), the same `planRevision` pattern as stop and retire;
48
+ - per moving module: `{capability, from:{version,commit,digest}, to:{version,commit,integrity}, skills:{added,removed,changed}, inject:changed?, hooks:changed?, provider:{decision, reason}}`;
49
+ - kept modules, with the reason;
50
+ - member drift, for information.
51
+
52
+ The plan writes nothing into the home, because the retire baseline compares home bytes. Like stop and retire plans, it touches nothing there. It stages the new copies in a temporary directory outside the home (`mkdtemp` under the OS temp dir) and removes that directory when it finishes.
53
+
54
+ **Provider adoption (condition 2).** For each moving module, the kernel needs to know whether the *new* version can take over the state the old version laid out. The kernel never guesses.
55
+ - **New lifecycle event `upgrade`.** It is approved in `lib/capability-contract.mjs` and `docs/capability-manifest.schema.json`. It must not be `required`. The kernel runs it from the **staged new copy**, with the usual `lifecycleHookEnv` plus:
56
+ - `OATS_UPGRADE_PHASE=plan|apply`;
57
+ - `OATS_META` (the recorded `capabilityMeta[cap]`, i.e. the old version's state);
58
+ - `OATS_UPGRADE_FROM` (JSON: the recorded `from`, commit, digest);
59
+ - `OATS_UPGRADE_TO` (JSON: the locked entry).
60
+ - **In `plan`** the hook is read-only and prints one of:
61
+ - `{"adopt": true}`;
62
+ - `{"adopt": false, "reason": "...", "remedy": "..."}`, for example naming the respawn.
63
+ - **In `apply`** it may change only provider state inside the home or provider-owned host registrations. One example is oats.aweb re-registering the wake broker against the recorded `grant.home`. It prints `{meta, warning?}` and exits 0, or exits non-zero to refuse.
64
+ A hook that exits non-zero must leave no effects of its own, by atomicity or
65
+ compensation. The kernel treats a failed hook as having made no changes;
66
+ its rollback covers composed home bytes, not provider-owned host effects.
67
+ Errors retain a bounded provider `warning` or stderr diagnosis, identify a
68
+ hook that reported failure, and state that host effects are the provider's responsibility.
69
+ - **Rules:**
70
+ - A moving module with recorded `capabilityMeta`, or one whose old or new manifest declares `spawn` or `launch` hooks, must declare `upgrade`. Otherwise its plan decision is `refuse: <cap> does not declare an upgrade hook; respawn the instance to change it`.
71
+ - A module with neither (skills/inject only) is adopted without a hook.
72
+ - One refusing module refuses the whole upgrade. There are no partial upgrades.
73
+ - **Older kernels.** An older kernel already treats an unknown non-required event as a warning (`capability-contract.mjs:52`), so a provider can declare `upgrade` before every host has the new kernel.
74
+
75
+ ## Apply
76
+
77
+ Apply runs under the claim, with the plan revision re-checked. A stale plan refuses with `E_PLAN_STALE` and attaches a fresh plan. Apply is idempotent per `--idempotency-key`, with a receipt like retire's, and does the following in order:
78
+
79
+ 1. **Stage.** Stage the new module copies in `<home>/.oats/.staging-upgrade-<receipt>`, on the same filesystem so the renames are atomic, and recompose the derived files there. Use the **same code as spawn**: refactor `materialize()` so that composing a home from a resolution can target an existing home. Do not write a second composer. The derived files are:
80
+ - `.agents/skills`;
81
+ - `AGENTS.md`: the soul body at the **recorded soul commit**, the kernel blocks, then each module's inject. If the soul body at that commit can't be read, refuse;
82
+ - in `instance.json`: `modules`, `capabilities[]`, `capabilityRuntime[]` (the absolute hook commands that retire runs), `skills[]`, `instructions[]`, `composition`, `launch.hooks.contributions`, `resolutionRevision`.
83
+ Read the soul body through discovery's path rule at that recorded commit:
84
+ a member soul uses `souls/<agent>/AGENTS.md`; a package soul uses its
85
+ manifest's explicit path. Upgrade never runs launch hooks. If a moved
86
+ module's new manifest has no launch hook, remove its recorded launch and
87
+ environment contribution inside the same journaled metadata swap. If it
88
+ still declares a launch hook, keep the contribution, with settings and trust
89
+ updated from the rebuilt capability, until the next start replaces it
90
+ wholesale through the standard launch refresh. Undo restores the recorded
91
+ contribution from the backed-up `instance.json`. No pending dropped-hook
92
+ state or `unsetEnv` JSON field is introduced; consecutive upgrades without
93
+ a start do not depend on an older previous manifest.
94
+ 2. **Keep the previous state.** This happens before anything outside staging changes. Copy `.oats/modules/<cap>` for each moving module, and the current `instance.json` and `AGENTS.md`, to `<home>/.oats/previous/<receipt>/` with `copyTreeSafe`, then verify the copy. This is not the retirement recovery root, so it is not mistaken for a retained retire.
95
+ 3. **Provider hooks.** Run each moving module's `upgrade` hook (`apply`) from the staged copy, in the plan's module order. `OATS_UPGRADE_MODULE_DIR` names its final `<home>/.oats/modules/<cap>` path: host registrations must use that path, never staging. Hooks must be idempotent in `apply`, because a retry runs them again.
96
+ Before spawning a hook, persist `step: "hook <capability>"` and
97
+ `hooks.inFlight: <capability>`. If execution is interrupted while that
98
+ outcome is unknown, resume must durably record `uncertain: [<capability>]`
99
+ before any retry work. The act then remains forward-only even when
100
+ `steps.hooks` contains no recorded success. A kill between that marker and
101
+ spawn also counts as uncertain unless not-started can be proved.
102
+ 4. **Swap.** Swap in place using materialize's rollback journal. Each moved module gets `modules.<cap>.previous = {from, commit, digest, materializedAt, receipt}` (one level, the latest move). `capabilityMeta[cap]` becomes the hook's `meta`.
103
+ 5. **Baseline.** Under the lifecycle claim, before staging, previous copies or
104
+ provider apply hooks change the home, compare it against the existing
105
+ retirement baseline with the same exclusions and comparison as retirement.
106
+ The plan shows `homeChangedSinceSpawn: true|false`. If the home is clean,
107
+ replace only `homeFingerprint` after the move, atomically. If it is dirty,
108
+ leave the entire baseline file byte-identical. Its old fingerprint keeps
109
+ classing the home as "changed instance-home bytes", including for older
110
+ kernels, which would ignore a new dirty-marker field. Later upgrades keep
111
+ that same dirty baseline; retirement writes its ordinary recovery copy.
112
+ An upgrade never re-takes `generatedWorkFingerprint` or changes the recorded
113
+ `digestVersion`: all work-tree changes remain compared against spawn.
114
+ Existing runtime authority and exclusions remain as recorded. No baseline
115
+ field, format migration or new recovery mechanism is introduced.
116
+ Upgrade receipts (the exact `upgrade-receipt.<key>.json` naming pattern)
117
+ and `.oats/.staging-upgrade-*` remain excluded. `.oats/previous/` is ordinary
118
+ home content. The comparison and clean replacement project out only the
119
+ upgrade's existing regular-file `.oats-start.lock`, using the exact-path
120
+ `transientHomePaths` validation. Future retire fingerprints still hash any
121
+ mutex left behind. A change made before the move is still a change at retire.
122
+ 6. **Commit.** After swap and baseline, record receipt `status: complete`
123
+ with `steps.cleaned: false`. This is the commit boundary: no success event
124
+ may be written before it, so rollback cannot leave a `modules-upgraded` row.
125
+ 7. **Event, then cleanup.** Append `modules-upgraded` with
126
+ `{receipt, modules:[{capability, from, to}]}`, deduplicated by receipt on
127
+ retry. The event kind is documented in the Desktop API and has a Desktop
128
+ label. Then clean staging and record `steps.cleaned: true`. A post-commit
129
+ failure leaves a committed upgrade: the same-key retry completes event
130
+ publication and cleanup without hooks or copies. Start remains allowed
131
+ with one warning naming that retry. A new upgrade or undo plan refuses
132
+ until finalization finishes, so staging cannot mix with another move.
133
+ Retirement keeps its existing behavior: staging is excluded and previous
134
+ copies remain ordinary home content.
135
+
136
+ **When a step fails before the commit boundary.** The rule is set by whether any provider hook's `apply` has succeeded or has an uncertain outcome. A hook can change host state (oats.aweb's wake re-register, for example), and restoring old modules under host state the new version adopted is the same mismatch #1450 is about.
137
+ - **No hook has succeeded or has an uncertain outcome:** roll back fully after a failure in steps 1–2. For a hook, only an explicit non-zero result observed and recorded in the same invocation, with no prior success or uncertainty, permits full rollback. Discard the staging and `<home>/.oats/previous/<receipt>`, change nothing in the home, and record a refusal event that names the step or module.
138
+ - **A hook has succeeded or has an uncertain outcome:** the act only finishes forward. The receipt records `partial` with the steps and modules already done. The error names what is pending, and says to retry with the same `--idempotency-key`. That retry re-runs pending work, including an uncertain idempotent hook, and finishes the swap, baseline and event. If the retried hook fails, the act stays `partial`; it never restores old modules. If the act can't be finished, the remedy named is a respawn. The home is never put back by hand under adopted or possibly adopted host state.
139
+ - **The session start** refuses while a `partial` receipt for the home exists (`E_UPGRADE_PARTIAL`, naming the retry).
140
+
141
+ **`--undo`** plans and applies the reverse move to `modules.<cap>.previous`, with the same steps and hooks; it is the `upgrade` hook of the version being restored. It works only for the latest move, and only while `<home>/.oats/previous/<receipt>` exists and verifies. The same adoption rule applies, so undo works only toward a version that declares `upgrade`. A move from a version without the hook, such as the motivating oats.aweb 1.17.1, cannot be undone through the act: its `.oats/previous/<receipt>` stays for inspection by hand, and the remedy for a bad move is a respawn.
142
+
143
+ **Lifetime of `.oats/previous/`.** Each home keeps one previous state, which the next move replaces. Retire carries it in its recovery copy like any other home content.
144
+
145
+ ## Restart and start (condition 4)
146
+
147
+ - `oats session start` and `oats session restart` never move modules.
148
+ - When a home has package drift, both print one line after the start, and the JSON gets `drift:[{capability, recorded, locked}]`: `<n> package module(s) behind the lock (<cap> <recorded> → <locked>); to move them: oats instance stop <i>; oats instance upgrade <i> --plan`.
149
+ `recorded` and `locked` are each `{version, commit}`. The text renders each
150
+ as `<version> @ <shortcommit>`, so a moved commit is visible even when the
151
+ version string is unchanged. Homes without package drift omit this field and
152
+ preserve the existing start/restart answer shape. If the lock cannot be read
153
+ (including malformed JSON or an unsupported lock version), start/restart
154
+ proceed, omit `drift`, and print one warning naming the lock and the reason.
155
+ - No flag on restart runs the upgrade.
156
+
157
+ ## Kernel stays runtime-neutral (condition 5)
158
+
159
+ The kernel knows modules, hooks, plans and receipts only. Anything aweb-specific lives in the provider's `upgrade` hook, such as grant-home adoption, the wake re-register, or refusing a 1.17.x meta shape it cannot adopt.
160
+
161
+ ## Surfaces
162
+
163
+ - **CLI:** `oats instance upgrade` with help text, in `bin/oats.mjs`.
164
+ - **Docs:**
165
+ - `docs/souls-and-instances.md:200` and `docs/first-team.md:166`: the invariant now reads "a running instance never changes under itself; a stopped one can be moved to the locked package versions with `oats instance upgrade`".
166
+ - `docs/desktop-cli-api.md`: the command, the event, `modules.<cap>.previous`, the start/restart `drift`.
167
+ - `docs/upgrading.md`: the deploy step after a package bump.
168
+ - The oats-operate skill.
169
+ - A release note.
170
+ - **`oats status`:** no change. Drift clears by itself after a move.
171
+ - **Desktop:** `modules.<cap>.previous` is a new field in JSON the Desktop reads. The implementation PR names lane:lfx as that reader and includes a test that the Desktop tolerates the field.
172
+
173
+ ## Out of scope
174
+
175
+ - Member modules and the soul body (still a respawn).
176
+ - Remote homes (`--server`).
177
+ - Moving several homes in one call (a deploy loops over instances).
178
+ - Desktop UI beyond the event label.
179
+ - Automatic upgrades.
180
+ - oats.aweb's `upgrade` hook, which is a separate provider spec and PR and ships after this kernel release with a kernel floor.
181
+
182
+ ## Acceptance
183
+
184
+ - Real-fixture tests:
185
+ - a stopped home on an older package version moves to the locked one. Afterwards its skills, AGENTS.md inject, hook commands, `modules` and `previous` match a fresh spawn on the locked version, apart from identity and timestamps;
186
+ - a running home refuses;
187
+ - a provider refusal changes nothing;
188
+ - a stale plan refuses;
189
+ - an idempotency replay works;
190
+ - `--undo` restores the previous bytes;
191
+ - retire after a move sees no unexplained home change.
192
+ - A live check on a scratch seat, after the provider's hook ships: a global-grant session seat spawned on an old oats.aweb is upgraded and restarted, then a signed mail is presented in the resumed session.
@@ -22,6 +22,10 @@ successor, with a link to its full text.
22
22
  - [Team model 3](2026-10-02-team-model-3.md): the teams a soul may join, and
23
23
  its default, are committed in the workspace; local teams only where the
24
24
  workspace allows them.
25
+ - [Module upgrade](2026-10-22-module-upgrade.md): `oats instance upgrade` moves
26
+ a stopped home's package modules to the locked versions, with plan, apply,
27
+ provider adoption and undo (supersedes workspace model v2 items 10–11 for
28
+ package modules).
25
29
 
26
30
  The Desktop's design brief for designers is in
27
31
  [packages/desktop/docs](../../packages/desktop/docs/design-brief.md).