@awebai/oats 0.69.23 → 0.69.24

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 (74) hide show
  1. package/bin/oats.mjs +56 -17
  2. package/docs/capabilities.md +353 -5
  3. package/docs/capability-manifest.schema.json +36 -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 +320 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +257 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +186 -3
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +5 -1
  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/souls-and-instances.md +45 -0
  21. package/docs/tui.md +21 -1
  22. package/docs/upgrading.md +12 -5
  23. package/docs/workspaces.md +13 -5
  24. package/lib/capability-show.mjs +11 -1
  25. package/lib/command-flags.mjs +2 -2
  26. package/lib/compile-cache.mjs +1 -1
  27. package/lib/core.mjs +1176 -181
  28. package/lib/errors.mjs +4 -1
  29. package/lib/hook-env.mjs +106 -0
  30. package/lib/host-run.mjs +11 -3
  31. package/lib/instance-inspect.mjs +44 -0
  32. package/lib/instance-lifecycle.mjs +15 -3
  33. package/lib/instance-listing.mjs +97 -8
  34. package/lib/kernel-features.mjs +10 -1
  35. package/lib/node-version.mjs +9 -0
  36. package/lib/provider-call-child.mjs +60 -0
  37. package/lib/provider-resume.mjs +83 -0
  38. package/lib/provider-test-seams.mjs +20 -0
  39. package/lib/read-call.mjs +2 -0
  40. package/lib/reserved-launch-env.mjs +8 -1
  41. package/lib/retire-admission.mjs +5 -1
  42. package/lib/schedule.mjs +14 -4
  43. package/lib/servers.mjs +28 -4
  44. package/lib/session-inspect.mjs +104 -13
  45. package/lib/session-providers.mjs +528 -0
  46. package/lib/session-resume.mjs +68 -15
  47. package/lib/stable-node.mjs +3 -0
  48. package/lib/triggers.mjs +3 -1
  49. package/package-catalog.json +2 -2
  50. package/package.json +2 -1
  51. package/packages/client/capability-list.mjs +21 -0
  52. package/packages/client/cli-adapter.mjs +19 -4
  53. package/packages/client/cli-locator.mjs +5 -1
  54. package/packages/client/deployment-data.mjs +23 -1
  55. package/packages/client/deployment-panel.mjs +25 -3
  56. package/packages/client/home-board.mjs +33 -19
  57. package/packages/client/inspect-boundary.mjs +18 -8
  58. package/packages/client/instance-acts.mjs +30 -3
  59. package/packages/client/instance-board.mjs +206 -0
  60. package/packages/client/instance-presentation.mjs +55 -0
  61. package/packages/client/liveness.mjs +15 -4
  62. package/packages/client/own-codes.mjs +5 -1
  63. package/packages/client/remote-roster.mjs +6 -1
  64. package/packages/client/session-backends.mjs +31 -0
  65. package/packages/client/session-start.mjs +18 -6
  66. package/packages/client/spawn-apply-cli.mjs +5 -3
  67. package/packages/client/spawn-apply-contract.mjs +25 -2
  68. package/packages/client/spawn-apply.mjs +5 -1
  69. package/packages/client/spawn-messages.mjs +3 -0
  70. package/packages/client/terminal-contract.mjs +4 -0
  71. package/packages/client/waiting-on-you.mjs +12 -2
  72. package/packages/tui/lib/model.mjs +14 -3
  73. package/packages/tui/lib/store.mjs +12 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -29,7 +29,7 @@ an author soul:
29
29
  ```yaml
30
30
  # oats-workspace.yaml
31
31
  packages:
32
- oats.framework: v1.27.0 # provides oats.core, oats.setup, oats.knowledge-theory
32
+ oats.framework: v1.28.0 # provides oats.core, oats.setup, oats.knowledge-theory
33
33
 
34
34
  # souls/<author-soul>/soul.yaml
35
35
  capabilities:
@@ -51,6 +51,16 @@ so there is no queue, no background worker and no watermark to keep.
51
51
  record the checkpoint and its exact outcome in the instance's own record. A
52
52
  partial edit or an opened process is not a delivered proposal.
53
53
 
54
+ **Steps 2 and 5 may move to the reviewer.** A capability may keep the
55
+ proposer's consultation to a quick search and leave duplicates, the canonical
56
+ home and the destination node or subject to the reviewer. A proposal may then
57
+ name a node or subject the proposer does not own, flagged for the reviewer
58
+ rather than refused. `oats.okf` 6.3 works this way: its proposals carry such
59
+ findings as warnings the knowledge maintainer resolves before merging. Say in
60
+ the capability which side settles each of these, and make what the reviewer
61
+ must settle visible on the proposal. The exclusions and the screen before
62
+ delivery stay with the proposer: they protect what leaves the host.
63
+
54
64
  Never promote secrets, credentials, personal data about people outside the team
55
65
  (clients, correspondents, any other third party), third-party messages
56
66
  verbatim, tool noise, readily re-derived code descriptions or task-only plans.
package/docs/knowledge.md CHANGED
@@ -231,14 +231,15 @@ other than `off`, or a soul `knowledge.propose` key, refuses the spawn
231
231
  head of the same PR and each decision made while working are not
232
232
  checkpoints: those are captured in `notes/`, and the next checkpoint
233
233
  carries them. First update state, log and relevant notes. Apply
234
- `knowledge-theory` and search accepted knowledge (`oats okf search`, then
235
- `cat`): already accepted with nothing to add means no proposal. Make **one
236
- proposal per checkpoint, carrying only what no earlier proposal carried**,
237
- and record every checkpoint in `log.md`, either with its proposal's PR
238
- URLs or with `nothing to propose` and the reason. Claim only for owned
239
- nodes (or, for a version-2 soul, in `claims/` on its subjects); a lesson
240
- for a node the soul only reads is named in one line in its hand-back for
241
- that node's owner.
234
+ `knowledge-theory` and run a quick `oats okf search` for each claim: when
235
+ in doubt, propose, because duplicates, the canonical home and the subject
236
+ are the knowledge maintainer's to settle. Make **one proposal per
237
+ checkpoint, carrying only what no earlier proposal carried**, and record
238
+ every checkpoint in `log.md`, either with its proposal's PR URLs or with
239
+ `nothing to propose` and the reason. A claim goes in the owned nodes (or,
240
+ for a version-2 soul, in `claims/` on its subjects); a lesson that belongs
241
+ in a node the soul only reads may be proposed there too, and the check
242
+ flags it for the maintainer, who chooses its home.
242
243
 
243
244
  The instance proposes itself, from its home, in three steps:
244
245
 
@@ -259,6 +260,13 @@ other than `off`, or a soul `knowledge.propose` key, refuses the spawn
259
260
  that would leave the host and prints the complete outgoing diff, the
260
261
  commit text, the PR body with its provenance block and a digest; nothing
261
262
  remote changes, and the instance reads that diff once as a reviewer would.
263
+ It refuses only what protects against real harm (for example an unsafe
264
+ file, a non-Markdown file where Markdown is required, `okf-base.json`, an
265
+ invalid base or the content screen's findings);
266
+ a path outside the write surface, a claim with no subject, a broken link
267
+ or an unfilled `proposal.md` is a `W_*` warning, listed under
268
+ `## Check warnings` in the PR body, which the maintainer resolves before
269
+ merging.
262
270
  `--apply` with that digest commits, pushes a new
263
271
  `okf-proposal/<date>-<uuid>` branch (create-only, never the accepted
264
272
  branch), labels it `okf-proposal` and opens one PR per changed base. One
@@ -321,9 +329,10 @@ names but does not judge its content. A bounded content screen runs over
321
329
  everything that would leave the host before every push, comment and merge,
322
330
  and the host's `screen-terms-file` can add terms to it; a clean screen is not
323
331
  proof. The proposer reads its outgoing diff before the push; the maintainer,
324
- the second reader, reads the already-pushed pull request. The write surface,
325
- the provenance checks and the soul's opt-out are enforced in code; none is a
326
- privacy guarantee. The opt-out ([The soul's opt-out](#the-souls-opt-out)) is
332
+ the second reader, reads the already-pushed pull request. The refusals of
333
+ `--check`, the provenance checks and the soul's opt-out are enforced in code;
334
+ a path outside the write surface is only a warning the maintainer resolves.
335
+ None is a privacy guarantee. The opt-out ([The soul's opt-out](#the-souls-opt-out)) is
327
336
  per soul and covers that soul's own proposals, not what its instances write
328
337
  to other seats. A soul whose work is reading third-party correspondence
329
338
  should opt out.
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.27.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
12
+ | `oats.framework` | `oats-framework/v1.28.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
13
13
  | `oats.okf` | `v6.3.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.46.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
14
+ | `oats.aweb` | `v1.47.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
15
  | `oats.engineering` | `v1.18.0` (frozen: see Coordination templates) | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.1.0` | `oats.cloning` | `cloner` |
package/docs/packages.md CHANGED
@@ -55,7 +55,7 @@ packages:
55
55
  - **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
56
56
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
57
57
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
58
- convention (`v5.8.0` or `oats-framework/v1.27.0`) and the payload path. An id
58
+ convention (`v5.8.0` or `oats-framework/v1.28.0`) and the payload path. An id
59
59
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
60
60
  a package outside the catalog"). The catalog is the reviewed official list
61
61
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -78,9 +78,9 @@ members:
78
78
  - git:github.com/acme/agents
79
79
  - git:github.com/acme/platform
80
80
  packages:
81
- oats.framework: v1.27.0
81
+ oats.framework: v1.28.0
82
82
  oats.okf: v6.3.0
83
- oats.aweb: v1.46.0
83
+ oats.aweb: v1.47.0
84
84
  teams:
85
85
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
86
86
  defaults:
@@ -155,7 +155,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
155
155
  ## `oats package add | remove`
156
156
 
157
157
  ```bash
158
- oats package add oats.aweb v1.46.0 # a catalog version
158
+ oats package add oats.aweb v1.47.0 # a catalog version
159
159
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
160
160
  oats package remove acme.tools
161
161
  ```
@@ -432,11 +432,11 @@ A soul that names one of the package's capabilities with
432
432
  "policy": "docs/official-catalog.md",
433
433
  "packages": {
434
434
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.3.0", "path": "oats-package" },
435
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.27.0", "path": "oats-package" }
435
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.28.0", "path": "oats-package" }
436
436
  }
437
437
  }
438
438
  ```
439
439
 
440
- `ref` carries the tag convention: a workspace's `oats.framework: v1.27.0`
441
- resolves to tag `oats-framework/v1.27.0`. Resolving through the catalog never
440
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.28.0`
441
+ resolves to tag `oats-framework/v1.28.0`. Resolving through the catalog never
442
442
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,264 @@
1
+ # OATS 0.69.24
2
+
3
+ Unreleased
4
+
5
+ The kernel can run an agent on a session backend a capability supplies, beside
6
+ tmux (session providers, experimental until the follow-up change). The Desktop
7
+ shows an agent's board around its terminal: its facts, and its questions
8
+ answered by number. OATS now refuses to start on Node.js older than 22.
9
+ oats.framework 1.28.0 and oats.aweb 1.47.0 are pinned.
10
+
11
+ ## Upgrade
12
+
13
+ - **The catalog pins oats.framework 1.28.0 and oats.aweb 1.47.0**; oats.okf
14
+ stays 6.3.0. `oats sync` takes them. Existing homes take oats.core 2.16.0
15
+ (the `tui` default) through `oats instance upgrade` or a respawn.
16
+ - **A legacy oats.aweb grant seat** (one spawned with oats.aweb 1.12–1.24)
17
+ fills its `.oats-aweb/seat.json` once at its next start, from facts that
18
+ must agree; otherwise its start refuses with the respawn remedy. Such a
19
+ seat no longer follows a changed default team: respawn it to move it.
20
+
21
+ - **What users must do: move to Node.js 22.5 or later.** OATS now stops before
22
+ every command on Node below 22, including `version`, the reader and
23
+ capability commands. If you run OATS on Node 20 today, upgrade Node before continuing.
24
+ Node 18 and 20 receive `E_NODE_UNSUPPORTED` with exit 1, as one failure
25
+ envelope on stdout with `--json`, or a message on stderr without it. Remote
26
+ probes and Desktop discovery retain the host's refusal message. The npm
27
+ package retains its Node 22.5.0 floor so installation warns about it.
28
+
29
+ - **Respawn an instance of `oats-maintainer` or `oats-setup-admin` once**
30
+ after `oats sync`. An instance keeps the `okf.json` its spawn recorded, so
31
+ one started before this release still reads and proposes to its old node; a
32
+ new spawn reads the soul's subjects. The soul needs a knowledge base bound
33
+ with the subject layout: on a base that is not bridged, its spawn refuses
34
+ with `E_CONFIG` naming the base
35
+ ([okf.json version 2](../knowledge.md#the-souls-okfjson)).
36
+
37
+ ## Added
38
+
39
+ - **Doctor reports Git's cache support.** Text and JSON doctor output name
40
+ the Git version and whether it supports partial caches or uses the
41
+ whole-tree fallback. This uses the existing `information[]` field, adds no
42
+ warning and refuses nothing. Git 2.45 or later is recommended for partial
43
+ caches; an older Git works with whole-tree fetches.
44
+
45
+ - **The Desktop and the TUI show an agent that runs on a session provider
46
+ as OATS reports it.** A session provider is a session backend a capability
47
+ supplies, in place of tmux; this release's kernel reports them (session
48
+ providers, below), and no released provider exists yet. For such an agent:
49
+ - its state is the one OATS reports, and no client asks tmux about it;
50
+ - Start, Restart, Stop and Retire are offered by its state, as for any
51
+ agent;
52
+ - it shows as needing input whenever OATS reports that it waits on you
53
+ and it is not stopped, and the Desktop's Home lists it under Running
54
+ while it runs;
55
+ - there is no terminal to open. The clients say where it runs ("Runs in a
56
+ bb thread; open it in bb.") and show the link the provider offers: the
57
+ Desktop in the row's context menu, opened in your browser, and the TUI
58
+ printed under the line after `Enter`. Neither opens, splits or restores
59
+ a terminal tab for it;
60
+ - the row's tooltip in the Desktop names the backend and the provider's
61
+ thread id.
62
+
63
+ An agent in tmux, and one recorded on Herdr, read as before
64
+ ([how the clients read `backend`](../desktop-cli-api.md#row-backend-clients)).
65
+
66
+ - **The agent view in the Desktop.** With an OATS that reports the agent's board (feature `instance-board`), an agent's terminal tab shows what the agent keeps in your view and what it asks you:
67
+ - **Facts** above the terminal: `label · value unit`, "updated <time>", at most three shown and the rest folded, a sparkline once the view has read the history, and links shown as attributed text: a press shows the whole address, and Open in browser opens it. In a short pane the facts give way so the terminal keeps its room. × or u hides a fact on this computer only, until its value changes.
68
+ - **Questions** under the terminal, one at a time, with "question n of N", ‹ › and the dots, and a context fold (c opens it from the keyboard).
69
+ - **Answering:** The questions and the facts are F6 regions (Ctrl+Shift+F6 from the terminal reaches the questions), and the palette's Agent: questions and facts (focus) moves through them; no chord takes Alt+T, Claude Code's extended thinking. A number puts `<id>: <option>` on the agent's input line, unsent, and your Enter in the terminal sends it. No bare digit is ever typed, and nothing is typed into a terminal that isn't on screen, or into one in its scrollback or one it can't check. A question's card stays until the agent clears it. On an agent on another machine the numbers are disabled and the zone says to type the answer in its terminal. While the agent's terminal shows a harness prompt (a live `permission` or `question` claim), the numbers are disabled and the zone says to answer the prompt there first.
70
+
71
+ Without the feature the terminal tab and its waiting row are as before.
72
+
73
+ - **Session providers: a capability can supply a session backend** (feature
74
+ `session-providers`). tmux stays the kernel's own backend and the default,
75
+ and tmux homes are unchanged. A capability declares `sessionProviders` in
76
+ its manifest, four of its own commands (`launch`, `inspect`, `input`,
77
+ `stop`, and optionally `inspectMany` and `check`), and `oats spawn <soul>
78
+ --backend <name>` (a schedule's `backend`, a trigger's `spawn.backend`)
79
+ runs the instance there. OATS keeps the home, the records, the lifecycle
80
+ and the answers.
81
+ - **The session-provider wire is experimental**: it is not stable until
82
+ the follow-up change (sandbox allowances and wire 1.3), and no released
83
+ provider speaks it.
84
+ - A provider home records `backend` and `session: {provider, endpoint}`.
85
+ Its status row carries `backend`, `session: {provider}` and `open` (a
86
+ link to show instead of a terminal), and on its own host the endpoint's
87
+ thread id; the endpoint is on its local inspect, spawn and start answers
88
+ only, and nothing of it is relayed to another machine. `oats inspect` and
89
+ `oats capabilities show` list `sessionProviders`.
90
+ - A spawn holds its new home's lifecycle claim while the provider
91
+ launches, and the home's receipt records that a launch was sent until
92
+ its outcome is recorded (`runtime.launchSent`): a spawn or a start
93
+ killed mid-launch leaves a home that reads as unknown, whose next stop,
94
+ start or retire first asks the provider to stop what it started.
95
+ - Each command of a provider runs in a process group of its own, ended
96
+ whole at its timeout. A `launch`, an `input` or a `stop` whose `oats`
97
+ command was killed is ended, with its group, by the next stop, start,
98
+ input or retire of the home, before the provider is called again: it
99
+ starts no session that OATS has no record of. A stop of a provider home
100
+ waits for an input that is being sent (up to its timeout) before it
101
+ asks the provider. A provider's command runs its helpers
102
+ inside that group.
103
+ - A stop made with OATS stays stopped: inspect answers stopped and every
104
+ input is refused `E_SESSION_NOT_RUNNING` until the home is started,
105
+ without asking the provider.
106
+ - Only a lost session is resumed, in its own conversation: one stopped by
107
+ `oats host run`'s shutdown, or one that is gone while OATS did not stop
108
+ it. `oats session resume` sends it one notice through the provider's
109
+ input, under a cap of 3 resumes of one home in an hour; any input to a
110
+ lost session counts as one.
111
+ - A provider's readiness (`check`) is asked right before every launch
112
+ (`E_BACKEND_NOT_READY`), and `oats readiness` relays it.
113
+ - New codes: `E_BACKEND_UNKNOWN`, `E_BACKEND_AMBIGUOUS`,
114
+ `E_BACKEND_HARNESS`, `E_BACKEND_LAUNCH_ARG`, `E_BACKEND_NOT_READY`,
115
+ `E_SESSION_NO_TERMINAL` (attach), `E_SESSION_PROMPT_OPEN` and
116
+ `E_SESSION_INPUT_QUEUED` (input).
117
+ - A routed `--backend <provider>` is sent only to a host that lists the
118
+ feature. A kernel without it that meets a provider home only refuses.
119
+
120
+ See [Session providers](../execution-targets.md#session-providers) and, for
121
+ a capability's author,
122
+ [Session providers (`sessionProviders`)](../capabilities.md#session-providers-sessionproviders).
123
+ - **A harness-package requirement can name its backends.** A `requires` row
124
+ of a capability manifest takes `backends: ["tmux"]`, `["session-provider"]`
125
+ or both; without it the row applies to every launch. A kernel without
126
+ `session-providers` applies such a row to every launch, so a package that
127
+ uses the key raises its OATS floor.
128
+
129
+ ## Changed
130
+
131
+ - **Desktop: Home shows what needs you, and the Workspace page has its own row and a way back.**
132
+ ([Workspaces](../desktop.md#workspaces))
133
+ - **Home is one centred column.** **Needs you** comes first: each agent waiting on you, with its
134
+ soul, its machine and its message, newest first. Eight show at most, then **Show all N**. With
135
+ none, "Nothing needs you."
136
+ - **One summary line** counts the rest: "24 agents · 21 running · 3 need you · 0 stopped".
137
+ - **The workspace is one row of tiles**, each a button with its count: Agents, Souls,
138
+ Capabilities, Teams, Machines and Automations (with the red dot while a run failed). They show
139
+ without scrolling, even with eight agents waiting on you. The Graph tile is gone; Machines keeps
140
+ its List and Map.
141
+ - **Running**, under the tiles, shows five running agents, then **Show all N running**. No row
142
+ says "running" any more: the heading does.
143
+ - **The sidebar's pinned rows are Home, Workspace and Automations.** Opening any Workspace page
144
+ (from a tile, the command palette, ⌘2 / Ctrl+2, or a soul's or capability's page) marks the
145
+ Workspace row, no longer Home's. Its palette command is now **View: Workspace**.
146
+ - **Every Workspace page says where you are, and the way back:** **Home › Workspace › Souls**
147
+ above the tabs, and **Home › Workspace › Souls › dev** on a soul's page, each part a link. Esc
148
+ goes up one level: twice from a soul's page reaches Home.
149
+ - **Capabilities shows the Workspace defaults again**, above the list: the Core slots (Knowledge,
150
+ Messaging, Tasks) and the Additional defaults, each as the list's own row.
151
+ - **Soul cards read more clearly:** the name larger and bolder, what the soul does in muted body
152
+ text, its agents and kind on a smaller line.
153
+
154
+ - **Desktop: the Workspace pages look like the prototype.** ([Capabilities and spawning](../desktop.md#capabilities-and-spawning))
155
+ - **The Dark theme takes Tokyo Night's blues and greys** in the window: backgrounds, raised surfaces, ink, the blue
156
+ accent, green, amber and red. Every text colour still meets WCAG AA; the terminals keep their own colours, and their
157
+ cells their size. Light and Solarized keep their colours.
158
+ - **Souls**: **Grid** | **Table** sits beside the page's title. The first line counts the souls and those with
159
+ agents running ("You have 10 souls, 4 with agents running, …"). Group headings are small capitals with their count.
160
+ The grid has three columns at most; a card is a calmer tile, its name in semibold, what it does on two lines, then
161
+ one meta line, and a refused spawn says so in one quiet line.
162
+ - **Capabilities**: a first line says what a capability is, how many there are and how many are official, and what
163
+ ✓, **core** and **default** mean. The rows sit on the page with a thin rule under each, the ✓ or **by** right after
164
+ the name, **core** and **default** as small pills. **Workspace defaults** stays above **All capabilities**, styled the
165
+ same way.
166
+ - **A soul's page and a capability's page** use the same type and spacing: a smaller title, section titles in small
167
+ capitals, the capability and skill rows as Capabilities' rows, quieter tabs and folds.
168
+ - **The status line shows the page's keys** on these pages: "↑↓ move · Enter open · v table · Esc Home" on Souls,
169
+ and "Esc back" on a soul's or a capability's page.
170
+
171
+ - **oats.framework 1.28.0** (`oats.core` 2.16.0, `oats.coordination-setup`
172
+ 1.1.1, `oats.knowledge-theory` 1.1.3, `oats.onboarding` 1.3.1, `oats.setup`
173
+ 2.16.2).
174
+ - `oats.core` adds `tui: "default"` to an agent's Claude settings when the
175
+ key is absent, so Claude's fullscreen-renderer offer no longer takes a
176
+ wake; a value already there stays (#1692). `/oats-operate` names the Node
177
+ floor and doctor's `git-version:` line, from OATS 0.69.24.
178
+ - `oats.coordination-setup` and `oats.onboarding` teach related work: a
179
+ lead's children and its sibling leads, with `--related-work` from OATS
180
+ 0.69.23 (#2022).
181
+ - `oats.knowledge-theory`'s proposal reference names `oats.okf` 6.3's
182
+ division of work as an option (#2030).
183
+ - `oats.setup`'s `oats-agent-permissions` skill explains why launch
184
+ `args` are refused where a capability requires a harness package, and
185
+ how to choose auto mode through the launch configuration's `env` (#1692).
186
+ - Guidance text, plus the one `tui` default. Nothing changes for a
187
+ deployment beyond `oats sync` taking the new tag; existing homes take
188
+ oats.core 2.16.0 through `oats instance upgrade` or a new spawn.
189
+
190
+ - **The framework's coordination guidance teaches related work.**
191
+ `oats.coordination-setup`'s `/coordination-best-practices` and
192
+ `/adapt-to-the-organisation`, and `oats.onboarding`'s
193
+ `/oats-tailor-workspace`, say that a lead's children are spawned with
194
+ related work, and that a lead for a related effort, the first lead's
195
+ sibling, gets it too. The flag is `--related-work` from OATS 0.69.23 and
196
+ `--same-work` before, which binds a child only. Guidance text only: no
197
+ floor moves. See [Related work](../desktop-cli-api.md#related-work-oats-instance-related-work).
198
+
199
+ - **`oats-maintainer` and `oats-setup-admin` read by subject** (`okf.json`
200
+ version 2). The maintainer's subjects are `workstream/oats-direction`,
201
+ `workstream/coordination`, `system/oats-kernel`, `system/oats-desktop`,
202
+ `workstream/provider-integration`, `workstream/operations`,
203
+ `workstream/positioning` and `workstream/workspace-administration`: the
204
+ subjects that absorb the nodes it owned and read. The setup admin's are
205
+ `workstream/workspace-administration`, `workstream/operations`,
206
+ `workstream/oats-direction`, `workstream/coordination` and
207
+ `system/oats-kernel`. Their texts say each proposed claim names the subjects
208
+ it is about.
209
+
210
+ - **OATS's own coordination capabilities teach related work.** The
211
+ engineering expert's, the build and the maintainer's skills spawn with
212
+ `--related-work` where they passed `--same-work`. A lead's children
213
+ (specialists, helpers, probes, developers and reviewers) get it, as before,
214
+ and now so does a sibling lead started for an effort that arises from the
215
+ lead's own (`--relation sibling --relative-to <lead> --related-work`). An
216
+ independent lead, and a lead a maintainer launches, still don't. The kernel
217
+ and its injects set no default. An OATS before 0.69.23 refuses
218
+ `--related-work`: hosts that run these capabilities need 0.69.23 or later.
219
+ See [Related work](../desktop-cli-api.md#related-work-oats-instance-related-work).
220
+
221
+ - **Capability hooks get `OATS_BACKEND`.** Every spawn hook and launch hook
222
+ is given the session backend the instance launches on: `tmux`, or a session
223
+ provider's name.
224
+ - **A tmux home's row of `oats status --json` carries `backend: "tmux"`.** A
225
+ row with no `backend` key comes from a kernel without `session-providers`,
226
+ and reads as a tmux home's.
227
+
228
+ ## Fixed
229
+
230
+ - **Claude agent panes skip the fullscreen-renderer offer.** At spawn and
231
+ every launch, oats.core 2.16.0 adds `"tui": "default"` to a Claude home's
232
+ `.claude/settings.json` if no `tui` key is present. Any existing value is
233
+ kept. Agent panes use Claude's classic renderer even where Claude now
234
+ defaults to fullscreen, and even over a user-level `"tui": "fullscreen"`;
235
+ this keeps tmux scrollback and the renderer used by the launch-prompt
236
+ captures. An existing project `tui` still wins. If oats.core stops adding
237
+ the key, existing homes keep it until respawn. See
238
+ [oats.core](../capabilities.md#oatscore-needs-input).
239
+
240
+ ## Documentation
241
+
242
+ - **Launch args guidance matches the package-probe refusal.** Any non-empty
243
+ launch-configuration `args` is refused at spawn with
244
+ `E_LAUNCH_PROBE_UNSUPPORTED` while an active capability requires a package
245
+ for that harness; with oats.aweb, every Claude launch has such a requirement.
246
+ `claude plugin list --json` cannot carry those args, and `--settings` can
247
+ change which plugins load. The supported routes are user `settings.json`
248
+ in the Claude config selected by `CLAUDE_CONFIG_DIR` through `env`, which
249
+ the probe carries, or a wrapper executable. `/oats-agent-permissions` now
250
+ teaches `permissions.defaultMode: "auto"` in that user file, replacing its
251
+ launch-args advice. See [launch configurations](../configuration.md#launch-configurations).
252
+
253
+ - **Knowledge proposals as oats.okf 6.3 runs them.** The
254
+ [operator guide](../knowledge.md#the-flow) still said a claim
255
+ goes only in the soul's owned nodes, that the proposer settles duplicates
256
+ before proposing, and that the write surface is enforced. With 6.3 a quick
257
+ search is enough, duplicates, the canonical home and the subject are the
258
+ knowledge maintainer's, and a path outside the write surface is a `W_*`
259
+ warning under `## Check warnings` in the PR body, which the maintainer
260
+ resolves before merging. The authors' guide's
261
+ [judgment and proposal](../knowledge-reference/proposal.md#judgment-procedure)
262
+ page now says a capability may divide the work that way; the exclusions and
263
+ the screen before delivery stay with the proposer. The
264
+ `oats.knowledge-theory` copy changes with it.
@@ -1550,6 +1550,51 @@ still name the old path. A child attached to one of the home's extra trees
1550
1550
  is handled the same way, tree by tree
1551
1551
  ([extra trees at retire](#extra-trees-at-retire)).
1552
1552
 
1553
+ #### Retiring a home on a session provider
1554
+
1555
+ A home whose session runs on a
1556
+ [session provider](execution-targets.md#session-providers) (its
1557
+ `instance.json` records `backend` and `session`) is retired by a kernel that
1558
+ lists the feature `session-providers`, in this order:
1559
+
1560
+ 1. **The stop is recorded** (`stoppedAt` in the home's receipt): from then on
1561
+ inspect answers stopped and every input to the home is refused
1562
+ `E_SESSION_NOT_RUNNING`, so nothing restarts its session.
1563
+ 2. **Inputs that were being sent are waited for.** An input already on its
1564
+ way when the stop was recorded can have the provider restart the session,
1565
+ and once the home is gone nothing could stop it. The retire waits for
1566
+ those inputs to end (at most an input's timeout and 5 s). An input still
1567
+ being sent after that does not hold the retire: its provider command is
1568
+ ended, and the retire goes on, with a warning that names that input's
1569
+ process. An input whose `oats` command was killed is not waited for: its
1570
+ provider command is ended at once. (Every stop of a provider home waits
1571
+ so, a plain `oats instance stop` too.)
1572
+ 3. **The provider is asked to stop the session**, with the usual grace,
1573
+ never escalated. A launch that was sent and never recorded (a command
1574
+ killed while it launched) is settled the same way: the provider is asked
1575
+ to stop whatever it runs for the home.
1576
+ 4. **No process may work in the home**, whatever the provider answered: a
1577
+ stop it confirms can still leave one behind (a harness that outlives its
1578
+ server for a while), and there is no window whose absence would say
1579
+ otherwise. With a process working in the home, or when that cannot be
1580
+ told, the retire refuses `E_RUNTIME_QUIESCE_FAILED` at once, names the
1581
+ processes and keeps the home; its stop stays recorded. A shell whose
1582
+ working directory is in the home counts too, and one named in the
1583
+ refusal may be your own: leaving the home's directory clears it.
1584
+ 5. The retire hooks run (the provider's own archives its session there), the
1585
+ work is preserved as for any home, and the home is removed.
1586
+
1587
+ **When the provider cannot confirm the stop** (it fails, it does not answer,
1588
+ or its capability is no longer among the home's modules after an upgrade),
1589
+ the retire does not strand the home. It goes on when step 4 finds no
1590
+ process in the home, and its answer then carries a warning that the session
1591
+ was not stopped through its backend: archive or remove that session with the
1592
+ provider's own tooling.
1593
+
1594
+ A retire's plan (`oats retire <instance> --plan`) reads the session through
1595
+ the provider, as `oats session inspect` does. A kernel without the feature
1596
+ refuses to retire such a home (`E_RUNTIME_ENDPOINT_UNKNOWN`) and keeps it.
1597
+
1553
1598
  #### What `work/` is at retire
1554
1599
 
1555
1600
  The retire and its plan read what is at `<home>/work` once, by one rule
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.69.24** ([release notes](release-notes/v0.69.24.md)).
10
+ The 0.69.24 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: 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.69.24,** 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.69.24, in either order
24
+ npm install -g @awebai/oats@0.69.24 # 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,13 @@ 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.69.24](release-notes/v0.69.24.md#upgrade):** OATS needs Node.js 22.5
221
+ or later: Node 18 and 20 now refuse every command (`E_NODE_UNSUPPORTED`).
222
+ The catalog pins oats.framework 1.28.0 and oats.aweb 1.47.0. Respawn an
223
+ instance of `oats-maintainer` or `oats-setup-admin` once (okf.json version
224
+ 2), and respawn or move other instances with `oats instance upgrade` to take
225
+ oats.core 2.16.0. A legacy oats.aweb grant seat (1.12–1.24) fills its seat
226
+ record at its next start, or refuses with the respawn remedy.
220
227
  - **[0.69.23](release-notes/v0.69.23.md#upgrade):** the catalog pins
221
228
  oats.framework 1.27.0, oats.aweb 1.46.0 and oats.okf 6.3.0. Respawn
222
229
  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`;
@@ -32,6 +32,7 @@ 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";
35
36
 
36
37
  export const CAPABILITY_SHOW_API = 1;
37
38
  /** A text is cut to at most this many UTF-8 bytes; binary detection examines this many + 3. */
@@ -194,6 +195,15 @@ function triggerSourceKeys(manifest) {
194
195
  return { triggerSources: manifest.triggerSources, ...(problems.length ? { triggerSourceProblems: problems } : {}) };
195
196
  }
196
197
 
198
+ /** The session providers a manifest declares (lib/session-providers.mjs), as declared, and the problems a
199
+ * `--backend` naming them would get: added keys, each only when there is something to say. A malformed
200
+ * declaration is shown, never refused. */
201
+ function sessionProviderKeys(manifest) {
202
+ if (manifest?.sessionProviders === undefined) return {};
203
+ const { problems } = sessionProvidersOf(manifest);
204
+ return { sessionProviders: manifest.sessionProviders, ...(problems.length ? { sessionProviderProblems: problems } : {}) };
205
+ }
206
+
197
207
  /** The show answer (capabilityShowApi 1): the inject with its text, each skill with its description and files. */
198
208
  export async function capabilityShow(source, { remote, remoteOptions }) {
199
209
  const r = bindRemote(remote, remoteOptions);
@@ -220,7 +230,7 @@ export async function capabilityShow(source, { remote, remoteOptions }) {
220
230
  skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
221
231
  }
222
232
  }
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) };
233
+ 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) };
224
234
  }
225
235
 
226
236
  /** The `--file` answer: one file the show lists (the inject, or a listed skill file), at the row's commit.