@awebai/oats 0.69.21 → 0.69.23

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 (73) hide show
  1. package/bin/oats.mjs +131 -23
  2. package/docs/capabilities.md +12 -2
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +290 -5
  5. package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
  6. package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
  7. package/docs/design/2026-11-19-sandboxes.md +878 -0
  8. package/docs/design/README.md +3 -0
  9. package/docs/desktop-cli-api.md +416 -72
  10. package/docs/desktop.md +377 -148
  11. package/docs/implementation.md +15 -2
  12. package/docs/integrations.md +3 -3
  13. package/docs/knowledge-capability-authoring.md +10 -7
  14. package/docs/knowledge-reference/acceptance.md +21 -19
  15. package/docs/knowledge-reference/adoption.md +18 -4
  16. package/docs/knowledge-reference/model.md +11 -9
  17. package/docs/knowledge-reference/package-craft.md +2 -2
  18. package/docs/knowledge-reference/proposal.md +117 -0
  19. package/docs/knowledge-reference/provider-mapping.md +10 -10
  20. package/docs/knowledge-reference/reader-capture.md +26 -22
  21. package/docs/knowledge-theory.md +1 -1
  22. package/docs/knowledge.md +5 -5
  23. package/docs/official-catalog.md +47 -4
  24. package/docs/packages.md +13 -13
  25. package/docs/release-lane.md +8 -6
  26. package/docs/release-notes/v0.69.22.md +221 -0
  27. package/docs/release-notes/v0.69.23.md +231 -0
  28. package/docs/servers.md +10 -6
  29. package/docs/souls-and-instances.md +51 -22
  30. package/docs/tui.md +48 -7
  31. package/docs/upgrading.md +17 -5
  32. package/docs/workspaces.md +2 -2
  33. package/lib/argv.mjs +6 -2
  34. package/lib/capability-contract.mjs +2 -2
  35. package/lib/command-flags.mjs +39 -2
  36. package/lib/core.mjs +25 -14
  37. package/lib/instance-board.mjs +337 -0
  38. package/lib/instance-events.mjs +48 -10
  39. package/lib/instance-lifecycle.mjs +19 -15
  40. package/lib/instance-listing.mjs +18 -10
  41. package/lib/instance-related-work.mjs +143 -0
  42. package/lib/kernel-features.mjs +4 -1
  43. package/lib/servers.mjs +123 -13
  44. package/package-catalog.json +3 -3
  45. package/package.json +1 -1
  46. package/packages/client/above-tested.mjs +3 -2
  47. package/packages/client/capability-list.mjs +69 -0
  48. package/packages/client/capability-origin.mjs +54 -0
  49. package/packages/client/cli-adapter.mjs +9 -1
  50. package/packages/client/deployment-data.mjs +7 -2
  51. package/packages/client/deployment-panel.mjs +4 -1
  52. package/packages/client/home-board.mjs +50 -0
  53. package/packages/client/instance-pin.mjs +28 -0
  54. package/packages/client/instance-record-outcome.mjs +31 -0
  55. package/packages/client/instance-tree.mjs +96 -24
  56. package/packages/client/keymap.mjs +16 -3
  57. package/packages/client/mail-contract.mjs +130 -0
  58. package/packages/client/panel-views.mjs +7 -7
  59. package/packages/client/related-work.mjs +84 -0
  60. package/packages/client/remote-roster.mjs +11 -3
  61. package/packages/client/roster-sections.mjs +10 -7
  62. package/packages/client/soul-role.mjs +44 -0
  63. package/packages/client/waiting-on-you.mjs +10 -0
  64. package/packages/client/workspace-cli.mjs +13 -2
  65. package/packages/tui/lib/actions.mjs +11 -4
  66. package/packages/tui/lib/client.mjs +3 -1
  67. package/packages/tui/lib/main.mjs +16 -2
  68. package/packages/tui/lib/model.mjs +48 -5
  69. package/packages/tui/lib/store.mjs +28 -2
  70. package/skills/oats-getting-started/SKILL.md +97 -24
  71. package/docs/knowledge-reference/harvester.md +0 -109
  72. package/lib/instance-same-work.mjs +0 -67
  73. package/packages/client/same-work.mjs +0 -49
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 6.2.0** (OATS **>=0.69.2**). Provider implementation and
9
+ This is the operator guide for **oats.okf 6.3.0** (OATS **>=0.69.2**). Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
  In 6.0 there is no knowledge harvester: a working instance proposes its own
12
12
  knowledge as a pull request at its checkpoints (`oats okf propose`), and the
@@ -28,7 +28,7 @@ knowledge maintainer gates every merge.
28
28
  ```yaml
29
29
  # oats-workspace.yaml (excerpt)
30
30
  packages:
31
- oats.okf: v6.2.0
31
+ oats.okf: v6.3.0
32
32
  defaults:
33
33
  knowledge: { oats.okf: { from: package } }
34
34
  stores:
@@ -56,9 +56,9 @@ Upgrading from 4.x requires the ordered
56
56
  just editing a version line. The package requires OATS >=0.69.2: its
57
57
  `knowledge-maintainer` soul says `background: true`, which an older kernel
58
58
  refuses. Upgrade OATS first, then the package. Each 5.x step is in
59
- [oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.2.0/CHANGELOG.md).
59
+ [oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.3.0/CHANGELOG.md).
60
60
 
61
- **Upgrade to 6.0:** pin `oats.okf: v6.2.0` and run `oats sync`. Only new
61
+ **Upgrade to 6.0:** pin `oats.okf: v6.3.0` and run `oats sync`. Only new
62
62
  spawns get `oats okf propose`, the 6.0 `okf-propose` skill and the
63
63
  spawn-recorded duty. Existing homes keep their copied provider even after a
64
64
  session restart; a stopped 5.x home can move with `oats instance upgrade`
@@ -67,7 +67,7 @@ remedy to retire and respawn it. Harvester spawns stop: the stub soul
67
67
  `oats.okf/knowledge-harvester`, kept until 7.0, refuses every spawn with
68
68
  `E_REMOVED` and the fix. Harvesters already running keep their 5.x modules
69
69
  and finish, or a person retires them. Then, by hand, from the deployment
70
- (oats.okf's [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.2.0/README.md#upgrading-to-60)
70
+ (oats.okf's [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.3.0/README.md#upgrading-to-60)
71
71
  has each step's commands):
72
72
 
73
73
  1. Delete the harvester's launch preference, if any:
@@ -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.26.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
13
- | `oats.okf` | `v6.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.43.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
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` |
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) | |
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` |
@@ -64,7 +64,7 @@ aliases, a later decision once no workspace we know of pins it.
64
64
  ## Find and use packages
65
65
 
66
66
  - A workspace pins an official package by **bare version** in its
67
- `packages:` map (`oats.okf: v6.2.0`); `oats sync` resolves it through the
67
+ `packages:` map (`oats.okf: v6.3.0`); `oats sync` resolves it through the
68
68
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
69
69
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
70
70
  not join a team or adopt the publisher's workspace. See
@@ -121,3 +121,46 @@ an entry. State the reason, affected releases and supported replacement or hold,
121
121
  and assess existing locks before changing discovery. Preserve immutable
122
122
  release history. A list change is not permission to rewrite a deployment's
123
123
  lock or change what a workspace declares.
124
+
125
+ ## Updating the test mirrors
126
+
127
+ `package-catalog.json` is the source of package release refs. Workspace pins,
128
+ current documentation and skill recommendations are checked against it by
129
+ `scripts/check-catalog-references.mjs`; dated release/design/upgrade records
130
+ retain their historical versions. The clean-room smoke reads the catalog
131
+ rather than repeating its versions.
132
+
133
+ The capability copies in `mirrors/` are test and release material. They stay
134
+ outside `capabilities/` so member discovery cannot offer them a second time,
135
+ and are excluded from npm. Never edit them by hand. For a non-OKF catalog pin:
136
+
137
+ ```bash
138
+ node scripts/check-mirrors.mjs --generate oats.aweb
139
+ node scripts/check-mirrors.mjs --verify
140
+ ```
141
+
142
+ Generation fetches only the catalog tag into ignored disposable scratch under
143
+ `.agents/mirror-source-*`, verifies its published tag object and peeled commit,
144
+ and reads raw Git blobs. Same-filesystem staging uses
145
+ `.agents/mirror-generation-*` there too. These paths are separate from the
146
+ deployment packages/capabilities under `.agents/`; generation does not modify
147
+ those or use modified source-checkout files. Existing destinations can be
148
+ replaced only when the same package's prior manifest owns their exact names;
149
+ OKF inventory paths are reserved for OKF. An optional source
150
+ clone argument uses that clone's immutable objects instead of fetching them;
151
+ its origin and tag must match the catalog and published remote. A moved tag
152
+ at an unchanged pin is refused against the previous inventory. All bytes,
153
+ executable bits, file sets and symlink targets are recorded in
154
+ `scripts/mirror-source-inventory.json`. Root capability exports (`.`) are
155
+ supported; escaping, broken and directory symlinks are refused by the shared
156
+ payload walker before replacement. Git paths that collide under case or Unicode
157
+ normalization are refused before staging writes; symlinks are created only
158
+ after every directory and regular file, so no staging write traverses one.
159
+
160
+ OKF keeps its existing stricter release finalization and wrapper/soul/trigger
161
+ inventory; use [the OKF mirror procedure](release-lane.md#mirroring-a-released-oatsokf)
162
+ to generate that package. The combined checker includes that gate and requires
163
+ its published catalog release. Verification is offline and needs neither Git
164
+ nor sibling clones. It runs explicitly in PR CI and through `npm run validate`.
165
+ A missing, extra or changed entry refuses verification; version equality alone
166
+ is insufficient.
package/docs/packages.md CHANGED
@@ -48,14 +48,14 @@ whole organisation:
48
48
 
49
49
  ```yaml
50
50
  packages:
51
- oats.okf: v6.2.0 # bare version → the official catalog
51
+ oats.okf: v6.3.0 # bare version → the official catalog
52
52
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
53
53
  ```
54
54
 
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.26.0`) and the payload path. An id
58
+ convention (`v5.8.0` or `oats-framework/v1.27.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.26.0
82
- oats.okf: v6.2.0
83
- oats.aweb: v1.43.0
81
+ oats.framework: v1.27.0
82
+ oats.okf: v6.3.0
83
+ oats.aweb: v1.46.0
84
84
  teams:
85
85
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
86
86
  defaults:
@@ -109,7 +109,7 @@ decision recorded in the lock.
109
109
  $ oats sync
110
110
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
111
111
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
112
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 6.2.0 ✓ (@ 92c63060)
112
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 6.3.0 ✓ (@ 29dfd340)
113
113
  changed acme.tools — → 0.4.0 (@ 47f4b816)
114
114
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
115
115
  teams platform (shared) · this deployment's: oats teams
@@ -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.43.0 # a catalog version
158
+ oats package add oats.aweb v1.46.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
  ```
@@ -181,8 +181,8 @@ same workspace commit hold identical locks.
181
181
  "source": "catalog:oats.okf",
182
182
  "url": "https://github.com/awebai/oats-okf.git",
183
183
  "path": "oats-package",
184
- "version": "6.2.0",
185
- "commit": "92c630606db81f55c3e31002cb51d0e603dc7902",
184
+ "version": "6.3.0",
185
+ "commit": "29dfd3403d06ec1f14136f81f4dfae63dafcbd9f",
186
186
  "integrity": "sha256-…",
187
187
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
188
188
  },
@@ -431,12 +431,12 @@ A soul that names one of the package's capabilities with
431
431
  {
432
432
  "policy": "docs/official-catalog.md",
433
433
  "packages": {
434
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.2.0", "path": "oats-package" },
435
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.26.0", "path": "oats-package" }
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" }
436
436
  }
437
437
  }
438
438
  ```
439
439
 
440
- `ref` carries the tag convention: a workspace's `oats.framework: v1.26.0`
441
- resolves to tag `oats-framework/v1.26.0`. Resolving through the catalog never
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
442
442
  advances a lock by itself: `oats sync` does, and says so.
@@ -467,8 +467,9 @@ tagged:
467
467
  ```
468
468
 
469
469
  3. Pin the same version in `package-catalog.json` and `oats-workspace.yaml`,
470
- update the version literals the tests and smoke script carry, and review
471
- the diff as one PR.
470
+ update current documentation/skill recommendations, then run
471
+ `node scripts/check-mirrors.mjs --verify` and `npm run validate`. The
472
+ catalog is the source for smoke/test versions. Review the diff as one PR.
472
473
 
473
474
  `--finalize` stamps `release.status: published` only when every check passes:
474
475
  the tag is exactly `v<package version>` and resolves to the given commit; the
@@ -515,10 +516,11 @@ When the diff is not empty:
515
516
  `oats-framework/v<version>` on its merge commit and push it. No workflow
516
517
  runs on this tag.
517
518
  3. **The pin**, in the kernel release-prep PR: `package-catalog.json`
518
- (`ref`), `oats-workspace.yaml`, and the version literals in
519
- `docs/official-catalog.md`, `docs/packages.md`, `docs/workspaces.md`,
520
- `skills/oats-getting-started/SKILL.md` and
521
- `test/release-packaging.test.mjs`. The pin does not ride the first PR:
519
+ (`ref`) and `oats-workspace.yaml`; update current documentation and skill
520
+ recommendations to match the catalog, then run
521
+ `node scripts/check-mirrors.mjs --verify` and `npm run validate`. Tests
522
+ read the catalog instead of carrying another release literal.
523
+ The pin does not ride the first PR:
522
524
  the tag needs the bumped manifest on `main` first, and CI reads the
523
525
  catalog's ref from the remote. Two tests in
524
526
  `test/hook-events-forward-tolerant.test.mjs` sync a deployment that takes
@@ -0,0 +1,221 @@
1
+ # OATS 0.69.22
2
+
3
+ The Desktop's UI rework continues: Home is where a window opens; Souls, a soul's page, Capabilities, Teams,
4
+ Machines and Setup are calm rows; the command palette is the one place to reach everything, with a status line
5
+ and centred sheets; and the sidebar's chevron and count now come after an agent's name. The Desktop's default
6
+ leader is Ctrl+Space. Instances can be pinned from the Desktop and the Terminal UI. The catalog pins oats.aweb
7
+ 1.45.0. A team container can take read-only inputs and a setgid outbox, and can run an opt-in, experimental bb
8
+ server. The getting-started skill sets up a person's own aweb server on a private AWID registry too.
9
+
10
+ ## Upgrade
11
+
12
+ - **Either order of the Desktop and the CLI works** from a Desktop newer than
13
+ 0.69.17 ([Either order works](../upgrading.md#either-order-works)). A
14
+ Desktop of 0.69.17 or older still goes first.
15
+ - **Package pin:** oats.aweb 1.45.0 (from 1.43.0, through 1.44.0).
16
+ oats.framework stays 1.26.0 and oats.okf 6.2.0. `oats sync` takes it.
17
+ Respawn instances, or move a stopped one with `oats instance upgrade`, to
18
+ take the new module.
19
+ - **oats.aweb 1.44.0's setup changes** (under Changed): `setup --install-aw`
20
+ installs the tested aw by default; bare API-key setup refuses before
21
+ `aw init` in another team's root; `setup --create` and tokenless
22
+ `setup --join` check only their own selected root.
23
+ - **The Desktop's leader is Ctrl+Space by default.** A leader you set is
24
+ kept, and Ctrl+X is one click away on the Keyboard shortcuts sheet. Where
25
+ an input method takes Ctrl+Space (macOS with two input sources or more,
26
+ IBus, Windows CJK IMEs), choose Ctrl+X there. The Terminal UI keeps Ctrl+X.
27
+ - **`oats tui`: `p` is a new default key (pin).** A `tui.json` that binds `p`
28
+ to another action is refused at the start, with a line that names the key
29
+ and both actions. A tui.json that binds p to another action must move that
30
+ action, or bind `pin` to another key (or to none, `"pin": []`). See
31
+ [Pinning](../tui.md#pinning).
32
+
33
+ ## Added
34
+
35
+ - **A team container can run a bb server.** Opt-in: build the derived image
36
+ `container/agent-bb` on a team image, select it with `AGENT_IMAGE` and
37
+ include `container/agent/compose.agent.bb.yaml`. The supervisor then starts
38
+ one [bb](https://github.com/get-bb/bb) server on the container's loopback,
39
+ after the wake broker and before sshd and `oats host run`, restarts it if
40
+ it ends, and stops it after host run has stopped the agents. The service
41
+ still publishes no port; the operator reaches bb over the SSH route with
42
+ `container/agent-bb/relay.mjs`. A container that does not opt in runs as
43
+ before, and the team image holds no bb. The server is unused until agents
44
+ are spawned with the bb session provider, which arrives with a later
45
+ kernel. This is experimental: the bb image, `compose.agent.bb.yaml` and
46
+ the relay will move to the bb package repository once it exists, with no
47
+ compatibility promise on those paths, on `AGENT_BB` or on the image's
48
+ recipe, so that move will not be a breaking change. See
49
+ [A bb server for the team](../container.md#a-bb-server-for-the-team).
50
+
51
+ - Team-agent containers can mount one operator-provisioned input directory
52
+ read-only at `/inputs`, using `TEAM_INPUT_DIR` and the optional
53
+ `compose.agent.inputs.yaml` fragment. Acceptance checks the running mount,
54
+ readability and write refusal; CI also checks the base has no input folder
55
+ and missing sources fail without host-path creation. An optional
56
+ `compose.agent.outbox.yaml` fragment adds a writable export queue with a
57
+ dedicated supplementary group and setgid ownership. Acceptance checks group
58
+ inheritance and private state. Every agent can read the inputs and read/write
59
+ the queue; the publisher, its ledger and credentials stay outside OATS. See [agent team container](../container.md).
60
+
61
+ - **Home in the Desktop.** A workspace now opens on Home, the first pinned row in the sidebar, which answers what needs you and what you have on one page:
62
+ - **The board.** Agents that need you, each with its message, then the running ones, newest first. A group with nobody in it isn't shown, and stopped agents aren't listed.
63
+ - **The overview.** Agents, Souls, Capabilities, Teams, Machines and Graph, each saying how many you have. Enter opens that part of the Workspace page, and Esc comes back to Home.
64
+ - **Home › Agents.** Every agent, running or stopped, with its soul, machine and state, and who started it.
65
+ - **A new workspace** shows what OATS does in two lines and three keys.
66
+
67
+ The palette's **Home** (among its sections) opens Home; it has no key of its own yet. The roster's order doesn't change: urgency is sorted on Home only.
68
+
69
+ - **Pinned instances in the Desktop and the TUI** (feature `instance-pin`).
70
+ A pinned instance is listed at the top of its machine's list, in the
71
+ Desktop's sidebar, the TUI's list and the command palettes' rows you have
72
+ not focused. Pinned instances come first at every level of the tree. An
73
+ instance counts as pinned when it or one below it is, so pinning a child
74
+ lifts its whole group and the path down to it. Among pinned instances the
75
+ order is spawn time, newest first, as for the rest.
76
+ - The Desktop: a row's context menu offers **Pin to top**, or **Unpin** on
77
+ a pinned instance, and the command palette offers **Agent: Pin to
78
+ top** / **Agent: Unpin** for the instance the leader keys act on. A
79
+ pinned row shows a pin after its name, which a screen reader hears as
80
+ "Pinned". A group that holds a pinned instance, its top instance
81
+ included, doesn't start collapsed, so the pin is seen with its group;
82
+ closed by hand, it stays closed.
83
+ - The TUI: `p` pins or unpins the selected instance at once, and the line
84
+ under the sidebar's title says what it did, or why it did nothing.
85
+ - Both run `oats instance pin <name> on|off`. The pin is the instance's
86
+ home's, so everyone who views that machine sees the same pins. Without
87
+ `instance-pin` on this computer, or on an instance's server, the order
88
+ and the menus stay as they were.
89
+
90
+ See [Pinned instances](../desktop.md#pinned-instances) and
91
+ [Pinning](../tui.md#pinning).
92
+
93
+ ## Changed
94
+
95
+ - **The getting-started skill sets up a workspace on the person's own aweb
96
+ server on a private AWID registry too** (#1966). Step 1 no longer stops
97
+ there: it asks the registry's origin, and tells the person that their
98
+ namespace's `_awid` DNS record must name that registry
99
+ (`aw id namespace prepare-controller --domain <domain> --registry <origin>`
100
+ makes one that does). Step 9 records it first, before any other
101
+ `oats aweb` command, with `oats aweb setup --soul <soul> --registry
102
+ <origin>`, the host setting `settings.oats.aweb.registry` that admits a
103
+ private registry. The skill still never sets `AWID_REGISTRY_URL`. That
104
+ branch needs oats.aweb 1.43.0 or later, the first release with
105
+ `--registry`; the public registry keeps 1.42.1. On a private registry,
106
+ when the setup expert needs the host wake broker, the skill first checks
107
+ the install read-only (`oats aweb wake install --plan`) and goes on only
108
+ when it passes, since
109
+ `oats aweb wake status` can't tell which registry a running broker
110
+ serves. On any refusal it stops and leaves the fix to the person: for
111
+ example a broker for another registry (`E_WAKE_REGISTRY_CONFLICT`), or
112
+ one started by hand (`E_WAKE_RUNNING_UNSUPERVISED`). On a machine with
113
+ no service manager, where a plain `aw wake run` would not carry the
114
+ registry, it offers a Claude or pi setup expert instead.
115
+
116
+ - **OATS pins oats.aweb 1.44.0** (from 1.43.0). Floors are unchanged: OATS >=0.68.0, aw >=1.36.33, tested aw 1.36.58. What a deployment must change:
117
+ - **`oats aweb setup --install-aw` installs the tested aw (1.36.58) by default,** where it installed the newest aw 1.x. Pass `--aw-version <v>` to keep another.
118
+ - **Bare API-key setup refuses before `aw init`** in an existing root that belongs to another team, or that lists memberships while no team is configured. Point `settings.oats.aweb.roots[<team>]` at the intended team's root, or at a fresh `.aweb-roots/<label>` directory, or configure the team first, then retry. A root with confirmed empty membership still bootstraps.
119
+ - **`oats aweb setup --create` and `setup --join` without a token check only their own selected root.** An unreadable default root no longer blocks them, which reverses 1.43.0's interim refusal. They now refuse when their selected root's membership is unreadable or belongs to another team. Invited `setup --join` still reads the default root.
120
+
121
+ Setup also names the source of the root it uses. Registry admission stays explicit through command formatting and retire cleanup. aw JSON answers with trailing stdout text are refused. Running instances keep the module they were spawned with: respawn them, or move a stopped one with `oats instance upgrade`, to take 1.44.0.
122
+
123
+ - **OATS pins oats.aweb 1.45.0** (from 1.44.0). Floors are unchanged: OATS >=0.68.0, aw >=1.36.33, tested aw 1.36.58. A launch on a session provider (an `OATS_BACKEND` other than `tmux` or unset) is delivered by the host wake broker, whatever `delivery` and the runtime say. It is inert until the kernel launches homes on a session provider. Homes on tmux behave as before, and nothing changes for them. A host that runs a session provider's homes under `delivery: channel` keeps `aweb-channel` at 1.7.9 or later and `@awebai/pi` at 0.3.10 or later. Running instances keep the module they were spawned with: respawn them, or move a stopped one with `oats instance upgrade`, to take 1.45.0.
124
+
125
+ - **A team container's bb server refuses a damaged token file.** With the bb
126
+ fragment, a `claude-token` file whose token has whitespace inside it (a
127
+ space, a tab, a line break) now fails the container start, before any child, with one line
128
+ naming the file's rule. Before, bb started and reported ready while every
129
+ model call failed. The docs also say to spawn bb agents with `--yolo` in a
130
+ team container, where bb's sandboxed modes cannot start. See
131
+ [A bb server for the team](../container.md#a-bb-server-for-the-team).
132
+
133
+ - **Desktop: the workspace's catalogue pages read as calm rows** (the Desktop UI rework, slice 3b).
134
+ - **Capabilities** is one list. Core capabilities (knowledge, messaging, tasks) come first with a
135
+ dim **core** tag, then the rest by name. Each row has the capability's name and who made it: a
136
+ ✓ for an official one ("Official: in the OATS catalog" for a package pinned from the catalog,
137
+ "Official: from the OATS repository" for a capability of the OATS repository), else **by** its
138
+ source. The mark is the Desktop's rule over workspace status, not a trust claim (a kernel fact
139
+ is [#1981](https://github.com/oats-project/oats/issues/1981)). It also has one line of what it does, and a
140
+ **default** tag on the workspace's defaults. One sentence above the list says what defaults are
141
+ for. The sections, repository pills, colour tiles and two-letter marks are gone. A package's
142
+ name and version are in Setup's Packages box.
143
+ - **A soul's page** lists its capabilities with the same row: the same mark or **by** its source
144
+ (the workspace's own repository is named too), core first, and no **default** tag.
145
+ - **A capability's page** reads top to bottom: what it does, then its **Skills**. Enter on a
146
+ skill opens the whole skill in the pane, and Esc returns. Commands, Settings, Triggers, Hooks,
147
+ Used by, Comes from and Files are folded underneath. Nothing the page showed before is gone.
148
+ - **Teams** names its two sections **Workspace teams** and **This computer's teams** (the teams
149
+ in this computer's `oats-local.yaml`). Each says what it holds in one sentence, and its lists
150
+ count your agents.
151
+ - **Machines** opens on the list of the computers the workspace runs on. Each row says whether
152
+ the computer is reachable and its OATS version. Enter opens
153
+ a machine, with Check and Remove. Its **Map** is the earlier Machines view.
154
+ - **Setup** is its list only; its graph is gone. A member's **Details** (or **Why?**) opens its
155
+ membership under its row.
156
+ - **Connections** says what the GitHub connection is for.
157
+
158
+ - **The sidebar's chevron comes after the name.** An agent with agents under it shows its chevron and their count right after its name, not before it, so every name at a level starts at the same place. A click on the chevron still opens or closes the group, and a click anywhere else on the row still opens its terminal.
159
+
160
+ - **The sidebar's roster heading reads "Agents"**, and the Workspace page no longer has a pinned row of its own: Home opens it, and Home's row stays selected while it shows. ⌘2 / Ctrl+2 and **View: Workspace overview** still open it.
161
+ - **A live agent is "running" on Home.** OATS doesn't report working or idle yet, and the Desktop doesn't guess. There is no "New" group for agents that stopped since you last looked either, because nothing records that yet.
162
+
163
+ - The command palette is the one place to reach everything: the agents that need you, your recent agents, the sections, the commands, and a **New agent: <soul>** row per soul. Quick Open's separate overlay is gone: ⌘P / Alt+P opens the palette on its souls (`+`).
164
+ - A status line along the bottom of the window shows the three most useful keys for where you are, says why a key could not act, and says what was just done. Stop, Start and Restart keep their dialogs.
165
+ - Stop and Retire are centred sheets; after a retire, a dim ✕ row stays where the agent was for ten seconds.
166
+ - Pressing the leader shows a small help sheet with the keys it takes; the leader then `?` pins it until Esc, and the Keyboard shortcuts sheet can turn it off.
167
+ - **Appearance** is one sheet for the theme (System, Dark, Light, more), the terminals' font and their size. **Choose…** sets a terminal font family by name in the sheet; the palette's **Terminal: set font family…**, which did nothing in the Desktop before (it used a prompt Electron doesn't support), opens that field, and choosing a named font clears a family chosen by name, which used to win over it. The window's text is always the system font: Omarchy's font now applies to the terminals only. "White" is now Light and "This computer" is System, with the same behaviour.
168
+ - The keyboard shortcuts editor is a sheet, with a **Leader** choice and the help sheet's setting at its top.
169
+ - **Keys:** the leader is now **Ctrl+Space** in the Desktop (Ctrl+X stays one click away on the Keyboard shortcuts sheet; a leader you set yourself is kept). Pressed twice it sends Ctrl+Space (NUL) to the program in a terminal. If your input method takes Ctrl+Space (fcitx or IBus with two input methods, macOS input sources), choose Ctrl+X. New: **Alt+N** opens New agent; the leader then **h** / **v** split right / down and **b** hides or shows the sidebar (also in `oats tui`, where `b` hides or gives back the list); **Delete** on a roster row retires (the sheet), beside `D`. Every other key is unchanged; the TUI's leader stays Ctrl+X for now.
170
+ - Status-line messages also say when the terminal in front loses its server and when it is back (the pane's countdown and **Reconnect now** are unchanged).
171
+
172
+ - **Desktop: Souls, and a soul's page, read calmly** (the Desktop UI rework, slice 3a).
173
+ - **Workspace › Souls** groups souls by where they come from (the workspace's
174
+ repository first, then its other members, then each package) and lists each
175
+ group in kind order: maintainers, experts, developers, operations, then the
176
+ rest. The kind is read from the soul's name (`-maintainer`, `-expert`,
177
+ `-developer`; a `setup`, `operator`, `admin` or `ops` word is operations):
178
+ OATS reports no role of its own yet.
179
+ - A card shows what the soul does, how many of its agents run and its kind.
180
+ **v** (or **Grid** | **Table**) shows the same souls as a table: name, what
181
+ it does, kind, agents running, harness · model, and whether it is ready
182
+ here. Each window remembers its choice.
183
+ - The card's **Spawn** button, **Group by Team** and **About souls** are gone.
184
+ Start a new agent of a soul from its page (**New agent**), Quick Open or the
185
+ palette.
186
+ - A soul's page is one column: its harness and model, its teams (the editable
187
+ list on this computer folds out under them), its knowledge, and **Ready**,
188
+ or the one thing that stops a spawn here, with the detail and the soul's
189
+ readiness checks under **Details**. Then its capabilities as one list of
190
+ rows, core ones first with a dim **core** tag, each with where it comes from
191
+ and one line of what it does. Then its two prompts as two tabs, **Soul
192
+ instructions** and **Composed instructions**, each with its sections listed
193
+ beside it, and its skills folded under **Skills**. The page no longer lists
194
+ the soul's agents: the Souls grid and table count them.
195
+
196
+ - The kernel test runner fails when a `real aw` regression skips, naming the
197
+ missing coverage. Three normally skipped provider-owned opt-ins were
198
+ removed; container auth checks now execute acceptance orchestration against
199
+ a strict subprocess boundary. [Test ownership](../design/2026-11-18-kernel-test-ownership.md)
200
+ records the source checks removed or replaced and the documented guidance
201
+ checks retained.
202
+
203
+ ## Fixed
204
+
205
+ - Every official package mirror is now generated from its catalog-pinned Git
206
+ tag and checked for complete file sets, bytes, executable modes and symlink
207
+ targets in pull-request CI. Workspace and current documentation/skill pins
208
+ are checked against the catalog; the packed-artifact smoke reads its pins
209
+ from the same source. See [the mirror procedure](../official-catalog.md#updating-the-test-mirrors).
210
+
211
+ ## Removed
212
+
213
+ - Retire three version-named kernel copies of oats.aweb hook tests after
214
+ pinning oats.aweb 1.44.0, which includes the transferred provider regressions.
215
+ Keep hook-1-12-1 until its current token-hygiene menu assertions have released
216
+ package coverage. The [retirement record](../design/2026-11-19-aweb-suite-retirement.md)
217
+ lists every disposition and this hold. The kernel retire-hook contract test
218
+ is unchanged, and a focused test preserves the real mirror answer's coupling
219
+ to the kernel cleanup classifier.
220
+
221
+ - **The packaged sidebar brand image** (`sidebar-48.png`). Nothing has drawn it since the brand mark left the sidebar's foot.