@awebai/oats 0.69.23 → 0.70.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 (88) hide show
  1. package/bin/oats.mjs +112 -20
  2. package/docs/capabilities.md +697 -11
  3. package/docs/capability-manifest.schema.json +66 -0
  4. package/docs/configuration.md +27 -7
  5. package/docs/design/2026-11-19-sandboxes.md +595 -121
  6. package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +330 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +210 -4
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +24 -3
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge-capability-authoring.md +1 -1
  15. package/docs/knowledge-reference/proposal.md +10 -0
  16. package/docs/knowledge.md +20 -11
  17. package/docs/official-catalog.md +2 -2
  18. package/docs/packages.md +7 -7
  19. package/docs/release-notes/v0.69.24.md +264 -0
  20. package/docs/release-notes/v0.70.0.md +155 -0
  21. package/docs/souls-and-instances.md +57 -0
  22. package/docs/trust-model.md +8 -1
  23. package/docs/tui.md +21 -1
  24. package/docs/upgrading.md +19 -5
  25. package/docs/workspaces.md +13 -5
  26. package/lib/automation-scope.mjs +1 -1
  27. package/lib/capability-show.mjs +20 -1
  28. package/lib/command-flags.mjs +2 -2
  29. package/lib/compile-cache.mjs +1 -1
  30. package/lib/core.mjs +1455 -203
  31. package/lib/errors.mjs +4 -1
  32. package/lib/home-integrity.mjs +329 -0
  33. package/lib/hook-env.mjs +107 -0
  34. package/lib/host-run.mjs +11 -3
  35. package/lib/instance-events.mjs +32 -5
  36. package/lib/instance-git.mjs +9 -0
  37. package/lib/instance-inspect.mjs +107 -9
  38. package/lib/instance-lifecycle.mjs +15 -3
  39. package/lib/instance-listing.mjs +101 -8
  40. package/lib/instance-resolution.mjs +85 -2
  41. package/lib/instance-upgrade.mjs +170 -14
  42. package/lib/kernel-features.mjs +10 -1
  43. package/lib/node-version.mjs +9 -0
  44. package/lib/provider-call-child.mjs +60 -0
  45. package/lib/provider-resume.mjs +83 -0
  46. package/lib/provider-test-seams.mjs +20 -0
  47. package/lib/read-call.mjs +2 -0
  48. package/lib/remote.mjs +33 -1
  49. package/lib/reserved-launch-env.mjs +8 -1
  50. package/lib/retire-admission.mjs +12 -1
  51. package/lib/sandbox-allowances.mjs +329 -0
  52. package/lib/schedule.mjs +14 -4
  53. package/lib/servers.mjs +38 -5
  54. package/lib/session-inspect.mjs +123 -87
  55. package/lib/session-providers.mjs +575 -0
  56. package/lib/session-receipt.mjs +93 -0
  57. package/lib/session-resume.mjs +68 -15
  58. package/lib/stable-node.mjs +3 -0
  59. package/lib/triggers.mjs +3 -1
  60. package/lib/upgrade-state.mjs +6 -1
  61. package/lib/worktree-hooks.mjs +18 -2
  62. package/lib/worktree.mjs +21 -7
  63. package/package-catalog.json +2 -2
  64. package/package.json +2 -1
  65. package/packages/client/capability-list.mjs +21 -0
  66. package/packages/client/cli-adapter.mjs +19 -4
  67. package/packages/client/cli-locator.mjs +5 -1
  68. package/packages/client/deployment-data.mjs +23 -1
  69. package/packages/client/deployment-panel.mjs +25 -3
  70. package/packages/client/home-board.mjs +33 -19
  71. package/packages/client/inspect-boundary.mjs +18 -8
  72. package/packages/client/instance-acts.mjs +30 -3
  73. package/packages/client/instance-board.mjs +206 -0
  74. package/packages/client/instance-presentation.mjs +55 -0
  75. package/packages/client/liveness.mjs +15 -4
  76. package/packages/client/own-codes.mjs +5 -1
  77. package/packages/client/remote-roster.mjs +6 -1
  78. package/packages/client/session-backends.mjs +31 -0
  79. package/packages/client/session-start.mjs +18 -6
  80. package/packages/client/spawn-apply-cli.mjs +5 -3
  81. package/packages/client/spawn-apply-contract.mjs +25 -2
  82. package/packages/client/spawn-apply.mjs +5 -1
  83. package/packages/client/spawn-messages.mjs +3 -0
  84. package/packages/client/terminal-contract.mjs +4 -0
  85. package/packages/client/waiting-on-you.mjs +12 -2
  86. package/packages/tui/lib/model.mjs +14 -3
  87. package/packages/tui/lib/store.mjs +12 -3
  88. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -0,0 +1,155 @@
1
+ # OATS 0.70.0
2
+
3
+ Unreleased
4
+
5
+ The kernel side of session providers is complete. A provider that sandboxes
6
+ its harness is handed the sandbox allowances the instance needs, its trees and
7
+ the kernel's own state to protect. For a provider home, the kernel runs only
8
+ its own copy of the home's modules, kept outside the home, so nothing the
9
+ agent writes in its home changes what the kernel runs. The session-provider
10
+ wire is version 1.3. tmux homes are unchanged, except that every event-log
11
+ write now refuses a log that is a link or a FIFO.
12
+
13
+ ## Upgrade
14
+
15
+ - **The Desktop and the CLI:** a Desktop of 0.69.18 to 0.69.24 accepts the
16
+ 0.70.0 CLI as above its tested bound. It then runs only its reads,
17
+ terminals, Spawn, Start, Restart, the colour and the background, and says
18
+ so, until Desktop 0.70.0 is installed. A Desktop of 0.69.17 or older
19
+ refuses the 0.70.0 CLI until then. Upgrade both.
20
+ - **A provider home spawned by an earlier kernel must be respawned.** Its
21
+ receipt has no `composition`, so this kernel runs none of its
22
+ capabilities: its session reads unavailable, and every verb's message
23
+ says to retire it and spawn it again. `oats retire <name> --force` removes
24
+ it (its retire hooks are not run, and the retire says which). The
25
+ session-provider wire has been experimental so far, and no released
26
+ provider exists; tmux homes are not affected.
27
+ - **For a capability's author:** in a provider home your hooks and commands
28
+ run from the kernel's copy of your capability, not from
29
+ `<home>/.oats/modules/<capability>/`. Find the home by
30
+ `OATS_INSTANCE_HOME`, never by your own location, and never write beside
31
+ your own code.
32
+ - **For a provider's author:** if your provider sandboxes its harness, keep
33
+ `<instances>/.oats-retirement/` unwritable from the session (the kernel's
34
+ copies of the modules and the receipts are there) and leave it readable,
35
+ and its `modules/` executable, at the same path (a hook hands the harness
36
+ scripts there); the launch input names it in `protected`, and deny writes to the Git pointer, configuration and hooks
37
+ of each path in `trees`. Nothing in this release makes a provider's
38
+ sandboxed mode a security boundary between an agent and the operator's
39
+ account.
40
+
41
+ ## Added
42
+
43
+ - **The kernel runs its own copy of a provider home's modules, never the
44
+ home's.** A session provider may run its harness in a sandbox that still
45
+ lets the agent write its own home, and the kernel that runs the home's
46
+ hooks and the provider's commands runs outside any sandbox, while that
47
+ agent runs. For a home on a session provider the kernel now runs nothing
48
+ that is in the home
49
+ ([What the kernel trusts in a provider home](../capabilities.md#what-the-kernel-trusts-in-a-provider-home)):
50
+ - The kernel keeps its own copy of the home's modules outside the home,
51
+ at `<instances>/.oats-retirement/modules/<hash of the home>/<store>/`,
52
+ made once by the spawn, before the provider is asked anything and
53
+ before any hook of the spawn runs. Every
54
+ lifecycle hook and worktree hook, every command of the provider, every
55
+ capability's readiness check and every command or operation dispatched
56
+ in the home runs from it, and the home's manifests are read there. The
57
+ copies in the home stay, for the agent and its harness.
58
+ - The home's receipt records its `composition`: which store holds those
59
+ copies, which modules the home has and where each came from, and the
60
+ capability rows the spawn resolved (settings, their origins, hook
61
+ commands, levels). `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS` and the hook
62
+ commands of such a home come from the receipt, never from
63
+ `instance.json`.
64
+ - A retire removes the kernel's copy with the home. `oats instance
65
+ upgrade` makes the copies for the upgraded home in a new store and then
66
+ writes the receipt once, naming the new store and the new rows together:
67
+ an upgrade that fails or is killed before that write leaves the old copy
68
+ and the old rows, and `--undo` names them again.
69
+ - A provider home's status row, its remote roster row and a start's
70
+ answer gain an optional key beside `modules`, `moduleCopy: {runs:
71
+ "kernel-copy", homeCopy: "same" | "differs", differs}`: which copy the
72
+ kernel runs, and whether the home's own record of its modules is the
73
+ kernel's (records only, nothing hashed). `oats readiness --home` of a
74
+ provider home gains `kernelCopies: {store, differing}`, which compares
75
+ the files. `modules` is unchanged.
76
+ - Nothing is hashed at a call, so a read of a provider home costs no more
77
+ than before. The cost is disk: a provider home's modules are kept twice
78
+ (about 1.3 MB for a home with the usual capabilities).
79
+ - **The launch input and the check's planned launch carry `trees`**: the
80
+ home's `work/`, then every extra tree Git itself lists for the home, as
81
+ absolute paths. A provider that sandboxes keeps each tree's Git pointer,
82
+ configuration and hooks unwritable. Additive; the wire stays 1.3.
83
+ - **The launch input and the check's planned launch carry `protected`**:
84
+ the kernel's own state for the home, today `<instances>/.oats-retirement/`:
85
+ paths a sandboxed agent must never write, and that a provider must not
86
+ block reading or executing. The kernel makes each directory before the
87
+ launch. Additive; the wire stays 1.3.
88
+ - **`OATS_PREVIOUS_BACKEND`** for launch hooks: the backend the home was
89
+ last launched on, as its receipt records it (`tmux` or a provider's
90
+ name); absent at a first launch. A capability that keeps files of its own
91
+ in a home for one backend removes them only when this names that backend.
92
+
93
+ - **Sandbox allowances for session providers.** A session provider that runs
94
+ its harness in a sandbox is handed, with every launch, what the instance
95
+ needs from outside it: `sandbox: {domains, write, missing}` in the launch
96
+ input. The kernel builds the list from the deployment's configuration and
97
+ nothing else adds to it.
98
+ - A capability that fills an instance's messaging, knowledge or tasks slot
99
+ may declare `sandboxDomains` in its manifest: `{"setting": "<key>"}`
100
+ (the setting's value is a URL, a bare host, or a map from team id to
101
+ one, of which the instance's own teams' entries are taken; `"optional":
102
+ true` where the session works without the host) or `{"settingFile":
103
+ "<key>", "urls": "<JSON pointer>"}` (the hosts in a JSON file of the
104
+ deployment). On any other capability a provider launch is refused,
105
+ `E_BACKEND_SANDBOX_HOST`; so is a value that gives no plain host, and a
106
+ file that is not the deployment's own.
107
+ - `write` is the deployment's events directory, which the kernel creates
108
+ before the launch.
109
+ - Values come from the deployment's configuration as a spawn preview
110
+ resolves it, never from an instance home. A start and a restart resolve
111
+ it again, for the deployment and the soul the home's path names (its
112
+ `instance.json` decides neither), without reaching any remote: the
113
+ workspace as this host last read it, and `oats-local.yaml` as it is now; when that cannot be done the launch input says `sandbox:
114
+ {unavailable}`, and the provider refuses a launch it would sandbox.
115
+ - A provider's `check` is handed the planned launch (`launch: {harness,
116
+ yolo, args, sandbox}`) before every launch, and before any hook runs:
117
+ a spawn its backend refuses runs no hook and leaves no home, and a
118
+ refused start runs no hook and stops nothing. `args` are the launch
119
+ configuration's own; a hook's arguments reach the launch input only.
120
+ - A read of a home while it is being spawned (`oats session inspect`, a
121
+ status row) answers `E_SESSION_UNAVAILABLE`, "is being spawned", where
122
+ it answered that the home's records disagree. For a tmux home too.
123
+ - `oats spawn --preview`, a start's answer and `oats readiness --home`
124
+ list each host with who asked for it and each path with its reason;
125
+ `oats capabilities show` lists `sandboxDomains` and its problems.
126
+ - **One wire version.** A session provider declares the wire it speaks
127
+ (`sessionProviders.<name>.wire`, `"1.3"`), and every request carries the
128
+ kernel's. A provider that declares another, or none, is refused
129
+ `E_BACKEND_WIRE`, naming both.
130
+ - What the kernel runs of a provider home is its own copy of the home's
131
+ modules, kept outside the home: see "The kernel runs its own copy of a
132
+ provider home's modules" in these notes.
133
+ - tmux launches are unchanged: no `sandbox`, and `sandboxDomains` is not
134
+ read. A kernel from before session providers ignores the key.
135
+
136
+ ## Changed
137
+
138
+ - **Every Git the kernel runs over a provider home's trees runs with the
139
+ repository's hooks and its file monitor off**: now also a spawn's `git
140
+ worktree add` and its rollback, and `oats worktree add` and `remove` (the
141
+ reads and a retire already did, for every home). A tmux home's Git is
142
+ unchanged.
143
+ - **An append to an instance's event log never writes through a link.** The
144
+ home's log and the deployment's are opened without following a symbolic
145
+ link, and written only when they are a regular file with one name: a
146
+ symbolic link, a hard link and a FIFO at a log's name are refused, as the
147
+ reader already refuses them. The other log still gets its row.
148
+ - **`oats instance upgrade` of a provider home** takes its module set and
149
+ each module's source from the receipt (a module only the home's record
150
+ names refuses it), runs each upgrade hook from the kernel's copy, and
151
+ keeps the pair it replaced, so that `--undo` names the kernel's previous
152
+ copies and rows again in one write. It is not resumed after an
153
+ interruption (`E_UPGRADE_PARTIAL`): the journal it would resume from is
154
+ in the home. The kernel's side is whole either way; such a home is
155
+ retired and spawned again.
@@ -209,6 +209,18 @@ the locked package versions with `oats instance upgrade`. Member modules and
209
209
  the soul body still require a new spawn. See
210
210
  [upgrading package modules](upgrading.md#moving-existing-homes-to-locked-package-versions).
211
211
 
212
+ For a home on a session provider the kernel keeps its own copy of the
213
+ home's modules outside the home, beside the home's receipt, and the receipt
214
+ records the home's capability rows (its `composition`). The kernel runs such
215
+ a home's hooks and commands from its own copy and reads their settings from
216
+ the receipt, never from the home's copies or its `instance.json`. A retire
217
+ removes that copy with the home, and `oats instance upgrade` exchanges it
218
+ and rewrites the rows in one write of the receipt, so that a failed upgrade
219
+ leaves the old copy and the old rows together, and `--undo` names the
220
+ previous pair again. An interrupted upgrade of such a home is not resumed:
221
+ its journal is in the home. See
222
+ [What the kernel trusts in a provider home](capabilities.md#what-the-kernel-trusts-in-a-provider-home).
223
+
212
224
  ### The harness starts normally
213
225
 
214
226
  OATS is a skill contributor, not a skill sandbox. The harness (pi, Claude Code,
@@ -1550,6 +1562,51 @@ still name the old path. A child attached to one of the home's extra trees
1550
1562
  is handled the same way, tree by tree
1551
1563
  ([extra trees at retire](#extra-trees-at-retire)).
1552
1564
 
1565
+ #### Retiring a home on a session provider
1566
+
1567
+ A home whose session runs on a
1568
+ [session provider](execution-targets.md#session-providers) (its
1569
+ `instance.json` records `backend` and `session`) is retired by a kernel that
1570
+ lists the feature `session-providers`, in this order:
1571
+
1572
+ 1. **The stop is recorded** (`stoppedAt` in the home's receipt): from then on
1573
+ inspect answers stopped and every input to the home is refused
1574
+ `E_SESSION_NOT_RUNNING`, so nothing restarts its session.
1575
+ 2. **Inputs that were being sent are waited for.** An input already on its
1576
+ way when the stop was recorded can have the provider restart the session,
1577
+ and once the home is gone nothing could stop it. The retire waits for
1578
+ those inputs to end (at most an input's timeout and 5 s). An input still
1579
+ being sent after that does not hold the retire: its provider command is
1580
+ ended, and the retire goes on, with a warning that names that input's
1581
+ process. An input whose `oats` command was killed is not waited for: its
1582
+ provider command is ended at once. (Every stop of a provider home waits
1583
+ so, a plain `oats instance stop` too.)
1584
+ 3. **The provider is asked to stop the session**, with the usual grace,
1585
+ never escalated. A launch that was sent and never recorded (a command
1586
+ killed while it launched) is settled the same way: the provider is asked
1587
+ to stop whatever it runs for the home.
1588
+ 4. **No process may work in the home**, whatever the provider answered: a
1589
+ stop it confirms can still leave one behind (a harness that outlives its
1590
+ server for a while), and there is no window whose absence would say
1591
+ otherwise. With a process working in the home, or when that cannot be
1592
+ told, the retire refuses `E_RUNTIME_QUIESCE_FAILED` at once, names the
1593
+ processes and keeps the home; its stop stays recorded. A shell whose
1594
+ working directory is in the home counts too, and one named in the
1595
+ refusal may be your own: leaving the home's directory clears it.
1596
+ 5. The retire hooks run (the provider's own archives its session there), the
1597
+ work is preserved as for any home, and the home is removed.
1598
+
1599
+ **When the provider cannot confirm the stop** (it fails, it does not answer,
1600
+ or its capability is no longer among the home's modules after an upgrade),
1601
+ the retire does not strand the home. It goes on when step 4 finds no
1602
+ process in the home, and its answer then carries a warning that the session
1603
+ was not stopped through its backend: archive or remove that session with the
1604
+ provider's own tooling.
1605
+
1606
+ A retire's plan (`oats retire <instance> --plan`) reads the session through
1607
+ the provider, as `oats session inspect` does. A kernel without the feature
1608
+ refuses to retire such a home (`E_RUNTIME_ENDPOINT_UNKNOWN`) and keeps it.
1609
+
1553
1610
  #### What `work/` is at retire
1554
1611
 
1555
1612
  The retire and its plan read what is at `<home>/work` once, by one rule
@@ -74,7 +74,14 @@ Inside one trust group, none of these hold:
74
74
  [Trust is the workspace's declaration](capabilities.md#mental-model) of a
75
75
  member repo or a package. The kernel then checks that what it is about to
76
76
  run is the copy made at spawn. That copy is in the agent's home, so the
77
- check is no defence against the agent.
77
+ check is no defence against the agent. For a home on a session provider
78
+ the kernel does not run the home's copy at all: it runs its own copy of
79
+ the home's modules, kept outside the home and made at the spawn, and
80
+ takes the capability settings and hook commands from the home's receipt,
81
+ kept there too
82
+ ([What the kernel trusts in a provider home](capabilities.md#what-the-kernel-trusts-in-a-provider-home)).
83
+ That holds against an agent that cannot write outside its home, which is
84
+ the provider's sandbox to ensure, not OATS's.
78
85
  - That a harness's sandbox is a boundary. OATS counts none as one and relies
79
86
  on none. Where a harness restricts what its agent can write, that is the
80
87
  harness's property and not a promise of OATS.
package/docs/tui.md CHANGED
@@ -267,6 +267,25 @@ while a terminal is open); under 80 columns it has the whole width.
267
267
  - **Opening an agent.** `Enter` on an instance that runs opens its terminal
268
268
  beside the sidebar, where the detail was, as a tab: see
269
269
  [Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
270
+ - **An agent that runs on a session provider** (a capability's session
271
+ backend, such as bb) has no terminal. The list shows it in the state OATS
272
+ reports (the detail says `running` or `stopped` when OATS says which, else
273
+ the provider's own word), and `S`, `R`, `X` and `D` act on it as on any agent. `Enter` opens
274
+ nothing: the line says where it runs ("Runs in a bb thread; open it in
275
+ bb.") and, when the provider offers a link, prints it under that
276
+ (`"Open in bb: http://…"`) for you to open. The palette does not
277
+ list it among the agents to open, the agent steps pass over it, and a
278
+ workspace's remembered tabs never open it. Its `!` mark shows whenever
279
+ OATS reports that it waits on you and it is not stopped
280
+ ([how the clients read `backend`](desktop-cli-api.md#row-backend-clients)).
281
+ Start the TUI outside an agent's home: OATS refuses to retire a home while
282
+ a process works in it, the TUI's own included, and names that process.
283
+ A known limit: when another machine's agent moves to a session provider
284
+ while the TUI is opening it, a check of its terminal that fails says
285
+ OATS's failure ("The session is no longer running on …") and not where
286
+ it runs, and an agent OATS holds by then (a retire that began) may have a
287
+ viewer started for it, which OATS refuses (`E_SESSION_NO_TERMINAL`).
288
+ Neither reaches another agent.
270
289
 
271
290
  **A view of more than one deployment** (this machine and another, or two
272
291
  deployments on one machine) is one list, grouped as the Desktop groups it:
@@ -704,7 +723,8 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
704
723
  as the workspace was left. The shown tab is the most recent for
705
724
  [the palette](#the-palette).
706
725
  - A tab whose instance is gone or cannot be opened now (retired,
707
- stopped) is dropped, and nothing is said of it. A group the drops
726
+ stopped, or now running on a session provider, which has no terminal)
727
+ is dropped, and nothing is said of it. A group the drops
708
728
  leave with no tab goes, as when its last tab is closed; a group that
709
729
  was empty when the workspace was left is empty again. A shown tab
710
730
  dropped gives its place to the next, else the one before.
package/docs/upgrading.md CHANGED
@@ -6,12 +6,12 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.23** ([release notes](release-notes/v0.69.23.md)).
10
- The 0.69.23 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
9
+ The latest version is **OATS 0.70.0** ([release notes](release-notes/v0.70.0.md)).
10
+ The 0.70.0 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.70: the
11
11
  Desktop and the CLI can be upgraded [in either order](#either-order-works).
12
12
 
13
13
  **First, read the `## Upgrade` section of every release after yours, up to
14
- 0.69.23,** in the [release notes](release-notes/): it says what to do before
14
+ 0.70.0,** in the [release notes](release-notes/): it says what to do before
15
15
  the CLI changes, and what else must change with it (the Desktop, another
16
16
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
17
17
  names the releases that ask for more than the steps below. `oats version`
@@ -20,8 +20,8 @@ prints the version you have.
20
20
  Then, on each host:
21
21
 
22
22
  ```sh
23
- # 0. where the Desktop is installed: Desktop 0.69.23, in either order
24
- npm install -g @awebai/oats@0.69.23 # 1. the CLI
23
+ # 0. where the Desktop is installed: Desktop 0.70.0, in either order
24
+ npm install -g @awebai/oats@0.70.0 # 1. the CLI
25
25
  oats update # 2. in each deployment: the plan, then it asks before it runs
26
26
  oats doctor # 3. in the same deployment
27
27
  ```
@@ -217,6 +217,20 @@ of the Desktop and the CLI, and an optional package pin. A change a script
217
217
  must follow is in its release's Upgrade section whether or not it is listed
218
218
  here.
219
219
 
220
+ - **[0.70.0](release-notes/v0.70.0.md#upgrade):** upgrade the Desktop with
221
+ the CLI: a Desktop of 0.69.18 to 0.69.24 runs the 0.70.0 CLI in its
222
+ reduced, above-tested mode until Desktop 0.70.0 is installed; a Desktop of
223
+ 0.69.17 or older refuses it until then. A session-provider home spawned by
224
+ an earlier kernel is retired with `--force` and spawned again (no released
225
+ provider exists). Capability authors: in a provider home, hooks run from
226
+ the kernel's copy of the capability; find the home by `OATS_INSTANCE_HOME`.
227
+ - **[0.69.24](release-notes/v0.69.24.md#upgrade):** OATS needs Node.js 22.5
228
+ or later: Node 18 and 20 now refuse every command (`E_NODE_UNSUPPORTED`).
229
+ The catalog pins oats.framework 1.28.0 and oats.aweb 1.47.0. Respawn an
230
+ instance of `oats-maintainer` or `oats-setup-admin` once (okf.json version
231
+ 2), and respawn or move other instances with `oats instance upgrade` to take
232
+ oats.core 2.16.0. A legacy oats.aweb grant seat (1.12–1.24) fills its seat
233
+ record at its next start, or refuses with the respawn remedy.
220
234
  - **[0.69.23](release-notes/v0.69.23.md#upgrade):** the catalog pins
221
235
  oats.framework 1.27.0, oats.aweb 1.46.0 and oats.okf 6.3.0. Respawn
222
236
  instances, or move stopped ones with `oats instance upgrade`, to take the
@@ -54,7 +54,7 @@ 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.27.0 # bare version → resolves through the official catalog
57
+ oats.framework: v1.28.0 # bare version → resolves through the official catalog
58
58
  oats.okf: v6.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
 
@@ -62,7 +62,7 @@ teams: # SHARED teams: the same provider tea
62
62
  engineering: { description: Platform and release automation, team: "engineering:acme.aweb.ai" }
63
63
  reviewers: { description: Code review } # declared, not created yet (no `team` id): readiness team-unmapped
64
64
  defaultTeam: engineering # the workspace's default team; see Teams below
65
- souls: # which teams each soul may join besides its default
65
+ souls: # each soul's team: its default, and the others it may join
66
66
  platform/*: { teams: [reviewers] }
67
67
 
68
68
  defaults:
@@ -541,13 +541,21 @@ teams: # SHARED teams: the same provider team
541
541
  docs: { description: Docs rota } # declared, not created yet: team-unmapped
542
542
  defaultTeam: engineering # the workspace's fallback default team (a shared label)
543
543
  localTeams: false # may deployments declare their own teams? (absent: false)
544
- souls: # per soul pattern: its default team and the other teams it may join
544
+ souls: # the one declaration of each soul's team, per soul or pattern
545
545
  "*": { teams: [] } # unlisted souls: default only (also what no entry means)
546
546
  security-souls/*: { default: security, teams: [engineering] }
547
547
  security-souls/incident-responder: { default: security, teams: [engineering, docs] }
548
548
  oats.engineering/*: { teams: any } # any: every shared team of this file
549
549
  ```
550
550
 
551
+ - **`souls:` is the one declaration of which team a soul belongs to.** An entry's
552
+ `default` is the team that soul's instances join; its `teams` are the others they
553
+ may join. A pattern entry (`<member>/*`, `*`) sets them for a set of souls, and a
554
+ named entry overrides it for one. Nothing else assigns a soul a team: not the
555
+ soul's own files, and not where it runs. A deployment's local `defaultTeam` is only
556
+ a fallback for a soul no entry gives a default (below). The sandboxes design
557
+ ([design record](design/2026-11-19-sandboxes.md), not built yet) places souls in
558
+ sandboxes without touching this declaration.
551
559
  - **Shared teams** (`teams.<label> = { description?, team? }`): a shared team
552
560
  without `team` is declared but not created yet (readiness `team-unmapped`):
553
561
  its owner creates it with the messaging provider, then commits the id.
@@ -587,8 +595,8 @@ souls: # per soul pattern: its default team an
587
595
 
588
596
  The default, in order:
589
597
 
590
- 1. the soul's `default` from `souls:` (the most specific matching key that
591
- sets one);
598
+ 1. the soul's `default` from `souls:`, the team its instances join (the most
599
+ specific matching key that sets one);
592
600
  2. else the deployment's `oats-local.yaml` `defaultTeam`, only when
593
601
  `localTeams: true`;
594
602
  3. else the workspace's `defaultTeam`;
@@ -17,7 +17,7 @@ export function childEnv() {
17
17
  for (const key of [...RESERVED_LAUNCH_ENV,
18
18
  "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
19
19
  "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
20
- "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
20
+ "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_BACKEND", "OATS_PREVIOUS_BACKEND", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
21
21
  "OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_TEAMS", "OATS_TEAMS_SOURCE", "OATS_TRIGGER_EVENT_FILE",
22
22
  "OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN",
23
23
  ]) delete env[key];
@@ -32,6 +32,8 @@ import { capabilitySkills, lockedCapability, lockedPackageCapabilities, manifest
32
32
  import { memberRowByKey } from "./workspace.mjs";
33
33
  import { sameRepo } from "./repo-moves.mjs";
34
34
  import { triggerSourcesOf } from "./trigger-sources.mjs";
35
+ import { sessionProvidersOf } from "./session-providers.mjs";
36
+ import { sandboxDomainsOf } from "./sandbox-allowances.mjs";
35
37
 
36
38
  export const CAPABILITY_SHOW_API = 1;
37
39
  /** A text is cut to at most this many UTF-8 bytes; binary detection examines this many + 3. */
@@ -194,6 +196,23 @@ function triggerSourceKeys(manifest) {
194
196
  return { triggerSources: manifest.triggerSources, ...(problems.length ? { triggerSourceProblems: problems } : {}) };
195
197
  }
196
198
 
199
+ /** `sandboxDomains` (lib/sandbox-allowances.mjs), as declared, and what is wrong with it: added keys,
200
+ * each only when there is something to say. A malformed declaration is shown here, and refuses a
201
+ * session-provider launch of an instance that composes the capability. */
202
+ function sandboxDomainKeys(manifest) {
203
+ if (manifest?.sandboxDomains === undefined) return {};
204
+ const { problems } = sandboxDomainsOf(manifest);
205
+ return { sandboxDomains: manifest.sandboxDomains, ...(problems.length ? { sandboxDomainProblems: problems } : {}) };
206
+ }
207
+ /** The session providers a manifest declares (lib/session-providers.mjs), as declared, and the problems a
208
+ * `--backend` naming them would get: added keys, each only when there is something to say. A malformed
209
+ * declaration is shown, never refused. */
210
+ function sessionProviderKeys(manifest) {
211
+ if (manifest?.sessionProviders === undefined) return {};
212
+ const { problems } = sessionProvidersOf(manifest);
213
+ return { sessionProviders: manifest.sessionProviders, ...(problems.length ? { sessionProviderProblems: problems } : {}) };
214
+ }
215
+
197
216
  /** The show answer (capabilityShowApi 1): the inject with its text, each skill with its description and files. */
198
217
  export async function capabilityShow(source, { remote, remoteOptions }) {
199
218
  const r = bindRemote(remote, remoteOptions);
@@ -220,7 +239,7 @@ export async function capabilityShow(source, { remote, remoteOptions }) {
220
239
  skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
221
240
  }
222
241
  }
223
- return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems, warnings: contractWarnings(source), ...triggerSourceKeys(source.manifest) };
242
+ return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems, warnings: contractWarnings(source), ...triggerSourceKeys(source.manifest), ...sessionProviderKeys(source.manifest), ...sandboxDomainKeys(source.manifest) };
224
243
  }
225
244
 
226
245
  /** The `--file` answer: one file the show lists (the inject, or a listed skill file), at the row's commit.
@@ -27,7 +27,7 @@ export function sameWorkDeprecation(argv) {
27
27
  return undefined;
28
28
  }
29
29
  export const RETIRE_USAGE = "usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--dir <d>] [--server <id>] [--self] [--discard-worktree] [--keep-dir] [--force] [--json]";
30
- export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--related-work|--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
30
+ export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--related-work|--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux|<session provider>] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
31
31
  export const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
32
32
  export const APPROVAL_REMOVED = "package approval was removed; declaring a package in packages: is the trust decision";
33
33
  export const TEAMS_USAGE = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
@@ -158,7 +158,7 @@ export const COMMAND_FLAGS = Object.freeze([
158
158
  refused: { ...NATIVE_RECORD_GONE, "--resume": "--resume exists on session start only: it brings back a session that was lost" },
159
159
  usage: "usage: oats session restart (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--launch-config <name>|none | --reselect-launch] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--stop-grace <seconds>] [--json]" },
160
160
  { command: "session resume", operands: [], values: ["--deployment"],
161
- refused: { ...NATIVE_RECORD_GONE, "--server": RESUME_LOCAL_ONLY }, switches: ["--plan", "--json"], usage: "usage: oats session resume [--deployment <dir>] [--plan] [--json]" },
161
+ refused: { ...NATIVE_RECORD_GONE, "--server": RESUME_LOCAL_ONLY }, switches: ["--plan", "--without-provider-inspect", "--json"], usage: "usage: oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] [--json]" },
162
162
  { command: "session input", operands: [], refused: NATIVE_RECORD_GONE, values: ["--home", "--text-file"], switches: ["--json"], usage: "usage: oats session input --home <abs> [--text-file <path>] [--json]" },
163
163
  { command: "session receive", operands: [], refused: NATIVE_RECORD_GONE, values: ["--home", "--name"], switches: ["--json"], usage: "usage: oats session receive --home <abs> --name <file name> [--json]" },
164
164
  { command: "session upload", operands: [], refused: NATIVE_RECORD_GONE, values: ["--file", ...SESSION_ADDRESS], switches: ["--json"],
@@ -1,7 +1,7 @@
1
1
  /** Node's compile cache for the CLI (awebai/oats#1630): V8 keeps the code it compiled for the
2
2
  * kernel's modules, so a command does not recompile them all on every run. Kernel-private, not
3
3
  * exported from `./core` and not a contract: `bin/oats.mjs` calls enableCliCompileCache before it
4
- * imports the kernel (only the dependency-free lib/hot-reads.mjs is parsed before), and in-process
4
+ * imports the kernel (only dependency-free startup helpers are parsed before), and in-process
5
5
  * consumers never call it (they run in their own processes).
6
6
  *
7
7
  * - The cache is `$OATS_HOME_DIR/compile-cache` (`~/.oats/compile-cache`), made 0700 here: Node's