@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
package/docs/upgrading.md CHANGED
@@ -1,5 +1,44 @@
1
1
  # Upgrading OATS on a host
2
2
 
3
+ This page opens with the upgrade to the latest version. The steps that are
4
+ the same for every release follow, then what each older release asks of a
5
+ host that comes from it.
6
+
7
+ ## Upgrading to the latest version
8
+
9
+ The latest version is **OATS 0.68.0** ([release notes](release-notes/v0.68.0.md)).
10
+ The 0.68.0 Desktop accepts OATS CLIs `>=0.26.0 <0.69.0`.
11
+
12
+ **First, read the `## Upgrade` section of every release after yours, up to
13
+ 0.68.0,** in the [release notes](release-notes/): it says what to do before
14
+ the CLI changes, and what else must change with it (the Desktop, another
15
+ tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
+ names the releases that ask for more than the steps below. `oats version`
17
+ prints the version you have.
18
+
19
+ Then, on each host:
20
+
21
+ ```sh
22
+ # 0. where the Desktop is installed: Desktop 0.68.0 first
23
+ npm install -g @awebai/oats@0.68.0 # 1. the CLI
24
+ oats update # 2. in each deployment: the plan, then it asks before it runs
25
+ oats doctor # 3. in the same deployment
26
+ ```
27
+
28
+ The Desktop's installers are the assets of the
29
+ [GitHub Release](https://github.com/awebai/oats/releases) of that version
30
+ ([OATS Desktop](desktop.md#install)). Then restart the pi sessions that were
31
+ running: a session keeps the bridge it loaded when it started.
32
+ [The steps](#the-steps) says what each step does and why they come in this
33
+ order.
34
+
35
+ An agent with the oats.setup capability does this with you through its
36
+ `/oats-upgrade` skill. It reads this page and the release notes at the
37
+ latest release's tag, never the copy in the installed CLI, which describes
38
+ the version you are upgrading from.
39
+
40
+ ## The steps
41
+
3
42
  Upgrading OATS means three things, in this order, on each host, and one
4
43
  before them where the Desktop is installed:
5
44
 
@@ -14,36 +53,24 @@ must be at the same version: a pi session with an older bridge runs old
14
53
  extension code against a new kernel. A host that launches no pi instance has
15
54
  no bridge, and step 2 has nothing to move.
16
55
 
17
- **A release's own steps are in its notes.** Read the `## Upgrade` section of
18
- every version between yours and the new one in the
19
- [release notes](release-notes/) first: it says what to do before the CLI
20
- changes, and what else must change with it (the Desktop, another tool, a
21
- package pin). This page is the part that is the same for every release.
56
+ **A release's own steps are in its notes**, in its `## Upgrade` section.
57
+ This page is the part that is the same for every release.
22
58
 
23
59
  **Why the Desktop goes first.** A Desktop accepts a CLI up to its own minor
24
60
  version and refuses a newer one: with the CLI moved first, the Desktop that
25
61
  is still running lists no instance until it is replaced. The new Desktop
26
62
  accepts the older CLI in the meantime. The CLI can move by two commands, the
27
- `npm install` below and an `oats update` whose plan installs it: step 0 comes
63
+ `npm install` and an `oats update` whose plan installs it: step 0 comes
28
64
  before either.
29
65
 
30
66
  **Package versions are a different thing.** `oats update` moves the CLI and
31
67
  the bridge, never a package. A deployment's capabilities come from the
32
68
  packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
33
- ([Packages](packages.md)).
34
-
35
- ## The steps
36
-
37
- ```sh
38
- # 0. where the Desktop is installed: the new version's Desktop first
39
- npm install -g @awebai/oats # 1. the CLI
40
- oats update # 2. in a deployment: the plan, then it asks before it runs
41
- oats doctor # 3. in the same deployment
42
- ```
69
+ ([Packages](packages.md)). To move an existing stopped home to those locked
70
+ versions, follow [the package-module deploy step](#moving-existing-homes-to-locked-package-versions).
43
71
 
44
72
  Run steps 2 and 3 in every deployment on the host, or name one from anywhere
45
- with `oats update --dir <deployment>`. Then restart the pi sessions that were
46
- running: a session keeps the bridge it loaded when it started.
73
+ with `oats update --dir <deployment>`.
47
74
 
48
75
  In a terminal, `oats update` shows its plan and asks before it runs anything.
49
76
  Without a terminal (a script, an agent's shell) it runs only with `--yes`.
@@ -74,7 +101,121 @@ Versions are compared as semver, so a prerelease is below its release:
74
101
  no other version: a local build `0.53.0+build.1` is `0.53.0`, and nothing is
75
102
  installed over it.
76
103
 
77
- ## Capture service release order
104
+ ## Moving existing homes to locked package versions
105
+
106
+ After changing a package pin and running `oats sync`, move each existing home
107
+ explicitly. Run these from its deployment or a parent's home:
108
+
109
+ ```sh
110
+ oats instance stop <instance>
111
+ oats instance upgrade <instance> --plan --json
112
+ oats instance upgrade <instance> --plan-revision <revision> --idempotency-key <key> --json
113
+ oats session start --home <absolute-home>
114
+ ```
115
+
116
+ Read the plan before applying it. It lists every moving package module,
117
+ skill/inject/hook changes and provider adoption decisions, modules kept
118
+ because their package is no longer locked, and member drift for information.
119
+ One provider refusal refuses the whole move. A running or unreadable session
120
+ refuses with `E_SESSION_RUNNING`; stop it first. A stale plan returns
121
+ `E_PLAN_STALE` and a fresh plan to review.
122
+
123
+ Modules move whole, with skills, instructions and hooks recomposed from the
124
+ same sources as spawn. The soul body stays at its recorded commit, and member
125
+ modules stay unchanged. `oats status` drift clears after the move. Start and
126
+ restart keep the recorded copies; when they lag the lock they report drift
127
+ and print the stop/upgrade command.
128
+
129
+ Before commit, a failure restores composed home bytes only when no provider
130
+ apply hook succeeded and no outcome is uncertain. A non-zero result must be
131
+ observed and recorded in the same invocation; a killed or interrupted hook
132
+ can already have adopted host state even when no success was recorded. A hook
133
+ reporting failure is responsible for leaving no provider effects of its own.
134
+ After success or an uncertain outcome, failure records `partial` and moves
135
+ forward only: retry with the same `--idempotency-key` to finish pending work,
136
+ including an uncertain idempotent hook. A refusal on retry stays partial.
137
+ Start refuses with `E_UPGRADE_PARTIAL` until it finishes. If it cannot finish,
138
+ respawn the instance. Do not restore old modules by hand under adopted or
139
+ possibly adopted host registrations.
140
+
141
+ After swap and baseline, the receipt commits before publishing the success
142
+ event and cleaning staging.
143
+ If cleanup fails, the upgrade is complete and the same-key retry cleans up
144
+ only, without hooks or copies. Start is allowed with one warning naming that
145
+ retry. A new upgrade or undo plan refuses until cleanup finishes. Retirement
146
+ keeps its normal behavior; it does not finish upgrade cleanup.
147
+
148
+ The latest previous state is kept in `.oats/previous/<receipt>/`. To request
149
+ the reverse move, use `oats instance upgrade <instance> --undo --plan --json`,
150
+ then apply with `--undo --plan-revision <revision> --idempotency-key <key>`.
151
+ Undo verifies that copy and asks the version being restored to adopt the
152
+ current state through its own `upgrade` hook. A version lacking that hook
153
+ cannot be restored through undo; respawn instead. Each successful move replaces
154
+ the one previous state, and retirement carries it into recovery.
155
+
156
+ This act handles one local home at a time. A deployment loops over its homes;
157
+ it does not upgrade automatically or through `--server`.
158
+
159
+ ## Coming from an older version
160
+
161
+ Read the `## Upgrade` section of every release after yours, up to the
162
+ latest: each release's own steps are there, and only there. This list is a
163
+ guide to them, not a replacement: it names, newest first, the releases whose
164
+ Upgrade section asks a host for more than [the steps](#the-steps), the order
165
+ of the Desktop and the CLI, and an optional package pin. A change a script
166
+ must follow is in its release's Upgrade section whether or not it is listed
167
+ here.
168
+
169
+ - **[0.67.0](release-notes/v0.67.0.md#upgrade), first published as
170
+ 0.67.1:** the leader is Ctrl+X in OATS Desktop and in `oats tui`, on every
171
+ platform; a leader you rebound is kept. A `tui.json` that gives `ctrl+x` to an action and names no leader
172
+ stops `oats tui` from starting: give that action another key, or name a
173
+ leader ([Change the keys](tui.md#change-the-keys-tuijson)). On Linux and
174
+ Windows the shared shortcuts are Ctrl+Alt; a terminal that passes
175
+ Ctrl+Shift apart from Ctrl takes the Ctrl+Shift option.
176
+ - **[0.66.0](release-notes/v0.66.0.md#upgrade):** `oats tui` moves its key
177
+ file to `~/.oats/config/tui.json`; `oats server connect` needs `--dir`.
178
+ - **[0.62.0](release-notes/v0.62.0.md#upgrade):** after the CLI, run
179
+ `oats setup` once per user on each host, from that user's shell: the
180
+ capture service ([Capture service release order](#capture-service-release-order)).
181
+ - **[0.61.0](release-notes/v0.61.0.md#upgrade):** restart a pi instance stuck
182
+ on its opening task once the bridge has moved; `oats onboard`'s
183
+ `next.spawn` names the soul that holds oats.setup.
184
+ - **[0.60.0](release-notes/v0.60.0.md#upgrade):** `running` in
185
+ `oats status --json` means the harness is running.
186
+ - **[0.59.0](release-notes/v0.59.0.md#upgrade):** with oats.aweb 1.28.0, a
187
+ host that needs the wake broker installs it once (`oats aweb wake install`,
188
+ from its own login session); `oats tui`'s back key is pressed twice.
189
+ - **[0.58.0](release-notes/v0.58.0.md#upgrade):** on a Mac, upgrade the CLI
190
+ before the next reboot.
191
+ - **[0.57.1](release-notes/v0.57.1.md#upgrade):** upgrade the hosts a Desktop
192
+ reaches over `--server` too; `oats tui`'s panel needs tmux 3.2 or later.
193
+ - **[0.57.0](release-notes/v0.57.0.md#upgrade):** a retire plan taken before
194
+ the upgrade is refused once (`E_PLAN_STALE`); `oats worktree remove` may
195
+ refuse with `E_CHILDREN_RUNNING`; with oats.okf 5.2.0, new spawns carry the
196
+ harvest duty unless the soul opts out.
197
+ - **[0.56.0](release-notes/v0.56.0.md#upgrade):** new refusal codes for
198
+ scripts; `open-workspace` in `tui.json` is `open`; a launch gets only its
199
+ capabilities' declared environment.
200
+ - **[0.55.1](release-notes/v0.55.1.md#upgrade):** pin oats.aweb 1.27.3 and run
201
+ `oats sync`: on 1.27.2, readiness reports every home the host wake broker
202
+ serves as `unavailable`.
203
+ - **[0.55.0](release-notes/v0.55.0.md#upgrade):** the first capture after the
204
+ upgrade takes longer.
205
+ - **[0.53.0](release-notes/v0.53.0.md#upgrade):** from 0.51 or earlier, do
206
+ 0.52.0's steps first (aw 1.36.33 or later, before `oats sync`); once the
207
+ CLI is 0.53.0, run `oats update` in each deployment that launches pi (an
208
+ older CLI's `oats update` moves the default pi folder only); run
209
+ `oats setup` again where it was run; restart Claude Code instances on a
210
+ Homebrew `node`; rerun `oats aweb resident create` for an existing
211
+ resident custody unit; `oats doctor` names unmatched `souls.launch` keys.
212
+
213
+ **Coming from before 0.53.0:** read the whole notes of every release after
214
+ yours: up to 0.39.0 the section may be called `## Upgrading` or
215
+ `## Upgrading from <version>`, and some releases give their order under
216
+ another heading (0.49.0's oats.okf 5.0 cutover, for one).
217
+
218
+ ### Capture service release order
78
219
 
79
220
  The bounded periodic capture service (service A) is **not shipped in
80
221
  [0.56.0](release-notes/v0.56.0.md) through [0.61.0](release-notes/v0.61.0.md)**
@@ -85,16 +226,13 @@ existing capture watcher, and upgrading to any of them does not install the
85
226
  periodic service. The capture algorithms and recovery commands already
86
227
  released do not prove that migration happened.
87
228
 
88
- For those released versions, follow their own Upgrade sections and the steps
89
- above. In particular, install the target Desktop before the CLI: the 0.61.0
90
- Desktop accepts CLIs `>=0.26.0 <0.62.0`, and a 0.60 Desktop refuses a 0.61.0 CLI.
229
+ For those released versions, follow their own Upgrade sections and
230
+ [the steps](#the-steps), the target Desktop before the CLI.
91
231
 
92
232
  Service A ships in [0.62.0](release-notes/v0.62.0.md) and every later
93
233
  release. Read 0.62.0's Upgrade section and keep this order: install the
94
- Desktop of the release you upgrade to first (the 0.62.0 Desktop accepts CLIs
95
- `>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0`, the 0.64.0
96
- Desktop `>=0.26.0 <0.65.0`, the 0.65.0 Desktop `>=0.26.0 <0.66.0`, the 0.66.0 Desktop `>=0.26.0 <0.67.0`), then that
97
- release's CLI and matching pi bridge. Only **after
234
+ Desktop of the release you upgrade to first (its notes give the CLIs
235
+ it accepts), then that release's CLI and matching pi bridge. Only **after
98
236
  installing that CLI**, run its setup conversion once per user on each host,
99
237
  from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
100
238
  watcher is replaced by the periodic service; foreign or disabled definitions
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.13.4 # bare version → resolves through the official catalog
58
- oats.okf: v5.2.1
57
+ oats.framework: v1.14.1 # bare version → resolves through the official catalog
58
+ oats.okf: v5.3.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone
@@ -11,10 +11,11 @@
11
11
  * inside the capability), and a provider payload's value against the manifest's
12
12
  * `settings.<key>.values`. Dependency-free. */
13
13
 
14
- export const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch", "worktree"]);
14
+ export const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch", "worktree", "upgrade"]);
15
15
  /** The events whose hook may be declared `required: true`: each has a moment
16
16
  * that can fail closed (a spawn's transaction; `oats worktree add`, which
17
- * removes the tree it made). */
17
+ * removes the tree it made). Upgrade instead enforces its own adoption
18
+ * protocol independently of the `required` flag. */
18
19
  export const REQUIRABLE_HOOKS = new Set(["spawn", "worktree"]);
19
20
  export const PORTABLE_ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
20
21
  export const CAPABILITY_ENV_ID_RE = /^[a-z][a-z0-9]*\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
@@ -105,9 +106,9 @@ export function manifestContract(m) {
105
106
  if (isObject(value) && value.required !== undefined && typeof value.required !== "boolean") bad(`${at}/required`, `hook "${event}": "required" must be a boolean`);
106
107
  // An unknown event its author declared essential cannot be skipped.
107
108
  else if (!known && isObject(value) && value.required === true) bad(at, `declares unsupported hook "${event}" (${[...APPROVED_HOOKS].join(", ")})`);
108
- // Only a spawn or worktree hook can fail what it serves; marking others
109
- // required would promise an enforcement that has no defined moment to act.
110
- else if (known && isObject(value) && value.required === true && !REQUIRABLE_HOOKS.has(event)) bad(`${at}/required`, `hook "${event}" cannot be required — only the spawn and worktree hooks are enforced (retire, launch and soul-scaffold run outside a transaction that can fail closed)`);
109
+ // Upgrade has its own adoption protocol; the other events outside spawn
110
+ // and worktree have no transaction where `required` can fail closed.
111
+ else if (known && isObject(value) && value.required === true && !REQUIRABLE_HOOKS.has(event)) bad(`${at}/required`, `hook "${event}" cannot be required — only the spawn and worktree hooks are enforced (upgrade uses its adoption protocol; retire, launch and soul-scaffold run outside a transaction that can fail closed)`);
111
112
  if (hookScriptEscapes(command)) bad(isObject(value) ? `${at}/command` : at, `hook "${event}" script ${JSON.stringify(command.trim().split(/\s+/)[0])} escapes the capability directory; a hook script is a path inside it`);
112
113
  if (!known && problems.length === sound) warnings.push({ code: "hook-event-unsupported", pointer: at, message: `capability ${id} declares hook "${event}", which this kernel does not run; it is ignored (this kernel runs ${[...APPROVED_HOOKS].join(", ")})` });
113
114
  }
@@ -180,13 +181,13 @@ const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
180
181
  * declaration may not cover them: these exact names, and every exact name
181
182
  * starting with one of these prefixes (the events log; the stop, restart and
182
183
  * start receipts and locks; the rollback marker; AGENTS.md backups; the
183
- * attachments directory). This is the one list: a new kernel-written top-level
184
+ * attachments directory; the instance colour, `.oats-color.json`). This is the one list: a new kernel-written top-level
184
185
  * home entry MUST be added here and to the `not` patterns of
185
186
  * `retirement.disposable.home` in docs/capability-manifest.schema.json. A
186
187
  * prefix declaration can reach none of them except through `.oats-`, which is
187
188
  * refused whole; `.oats-<provider>` as an exact name stays declarable. */
188
189
  const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
189
- const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments"];
190
+ const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color"];
190
191
 
191
192
  /** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
192
193
  * name or prefix), "kernel-owned", or undefined when it is sound. */