@awebai/oats 0.69.21 → 0.69.22

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 (36) hide show
  1. package/docs/container.md +311 -4
  2. package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
  3. package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
  4. package/docs/desktop.md +316 -130
  5. package/docs/implementation.md +14 -1
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge-capability-authoring.md +1 -1
  8. package/docs/official-catalog.md +44 -1
  9. package/docs/packages.md +2 -2
  10. package/docs/release-lane.md +8 -6
  11. package/docs/release-notes/v0.69.22.md +221 -0
  12. package/docs/tui.md +44 -4
  13. package/docs/upgrading.md +10 -5
  14. package/package-catalog.json +1 -1
  15. package/package.json +1 -1
  16. package/packages/client/above-tested.mjs +3 -2
  17. package/packages/client/capability-list.mjs +69 -0
  18. package/packages/client/capability-origin.mjs +54 -0
  19. package/packages/client/cli-adapter.mjs +9 -1
  20. package/packages/client/deployment-data.mjs +3 -0
  21. package/packages/client/deployment-panel.mjs +2 -0
  22. package/packages/client/home-board.mjs +50 -0
  23. package/packages/client/instance-pin.mjs +28 -0
  24. package/packages/client/instance-record-outcome.mjs +31 -0
  25. package/packages/client/instance-tree.mjs +62 -20
  26. package/packages/client/keymap.mjs +11 -3
  27. package/packages/client/remote-roster.mjs +8 -1
  28. package/packages/client/roster-sections.mjs +10 -7
  29. package/packages/client/soul-role.mjs +44 -0
  30. package/packages/client/waiting-on-you.mjs +10 -0
  31. package/packages/tui/lib/actions.mjs +11 -4
  32. package/packages/tui/lib/client.mjs +3 -1
  33. package/packages/tui/lib/main.mjs +16 -2
  34. package/packages/tui/lib/model.mjs +48 -5
  35. package/packages/tui/lib/store.mjs +28 -2
  36. package/skills/oats-getting-started/SKILL.md +88 -18
@@ -85,7 +85,7 @@ and the rules its tests pin.
85
85
  | `injects/` | the kernel and work-mode instruction blocks composed into every instance |
86
86
  | `skills/` | bootstrap skills shipped with the kernel |
87
87
  | `capabilities/` | this repository's own member capabilities, discovered at the member's latest state: `oats-desktop-ui`, `oats-workspace-experts`, and the copy of the engineering template (`oats-dispatcher`, `oats-engineering-expert`, `oats-developer`, `oats-build`, `oats-code-review`, `oats-maintainer`, `oats-landing-rules`; the release it came from in `TEMPLATE-RELEASE`, its MIT notice in `TEMPLATE-LICENSE`, the notices of the sources its build skill and its quality floor adapt in `THIRD-PARTY-NOTICES.md`) that the framework's own souls compose |
88
- | `mirrors/` | copies of the official packages' capabilities at their pinned tags: release-lane and test material, kept out of `capabilities/` so member discovery does not list them a second time; not shipped in the npm package. The three OKF mirrors (`oats-okf*`) are generated by `scripts/check-okf-mirror.mjs` and checked byte for byte against `scripts/okf-source-inventory.json`; the other seven (`oats-aweb`, `oats-aweb-tasks`, `oats-folio`, `oats-library`, `oats-jira`, `oats-linear`, `oats-authoring`) are copied from their tags by hand and checked for their version only, until every mirror has that check (oats-project/oats#1848) |
88
+ | `mirrors/` | generated copies of official packages' capabilities at the catalog-pinned tags; never authored here or shipped in npm. `scripts/check-mirrors.mjs` verifies every file, mode and symlink against the generated inventories in PR CI and local validation. The workspace pins determine which package inventories must exist, so deleting a record together with its mirrors cannot disable verification. The framework stays in `oats-package/`. OKF retains its stricter published-release, wrapper and soul/trigger inventory. See [updating mirrors](official-catalog.md#updating-the-test-mirrors). |
89
89
  | `oats-package/` | the `oats.framework` package |
90
90
  | `souls/` | this repository's own souls (a workspace member) |
91
91
  | `docs/` | the reference pages, schemas, design records and release notes |
@@ -590,6 +590,19 @@ scaling by call count.
590
590
 
591
591
  ## Tests and gates
592
592
 
593
+ Native `aw` test titles start with `real aw` (or `real-aw`). Put that prefix
594
+ on every skippable native suite as well, for example
595
+ `describe("real aw custody", { skip: reason }, ...)`: Node does not register
596
+ children of a skipped `describe`, so an unprefixed skipped parent hides
597
+ its child titles from reporters. The prefix must be on the skipped node.
598
+ The root runner's
599
+ reporter counts any skipped test with that prefix, prints its file and title,
600
+ and fails the run. An absent binary or fixture is missing evidence; platform
601
+ skips outside that group keep their normal meaning. Provider-owned optional
602
+ native tests are not retained in the kernel as normally skipped duplicates.
603
+ The [test ownership record](design/2026-11-18-kernel-test-ownership.md) lists
604
+ the removed opt-ins and source checks, with their reasons.
605
+
593
606
  | command | what it checks |
594
607
  |---|---|
595
608
  | `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs`, which also fails the run when an `oats: warning:` line is left in a test file's output, or a test file leaves something in its temporary directory |
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v6.2.0
44
- oats.aweb: v1.43.0
44
+ oats.aweb: v1.45.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -97,7 +97,7 @@ operations in full.
97
97
  - **`oats.aweb-tasks`** (in the `oats.aweb` package from 1.31.0) fills the
98
98
  tasks slot with aweb tasks, acting as the instance's own `oats.aweb`
99
99
  identity in its default team. **An existing workspace opts in** by pinning
100
- `oats.aweb: v1.31.0` (or later), adding
100
+ `oats.aweb: v1.45.0` (the feature needs 1.31.0 or later), adding
101
101
  `tasks: { oats.aweb-tasks: { from: package } }` to `defaults`, and running
102
102
  `oats sync`. Only new spawns get it. A soul that names its own tasks
103
103
  provider in `capabilities:` (`oats.jira`, `oats.linear`) then holds two and
@@ -29,7 +29,7 @@ an author soul:
29
29
  ```yaml
30
30
  # oats-workspace.yaml
31
31
  packages:
32
- oats.framework: v1.4.1 # provides oats.core, oats.setup, oats.knowledge-theory
32
+ oats.framework: v1.26.0 # provides oats.core, oats.setup, oats.knowledge-theory
33
33
 
34
34
  # souls/<author-soul>/soul.yaml
35
35
  capabilities:
@@ -11,7 +11,7 @@ or workspace membership alone does not make a package official.
11
11
  |---|---|---|---|
12
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
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) | |
14
+ | `oats.aweb` | `v1.45.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` |
@@ -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
@@ -80,7 +80,7 @@ members:
80
80
  packages:
81
81
  oats.framework: v1.26.0
82
82
  oats.okf: v6.2.0
83
- oats.aweb: v1.43.0
83
+ oats.aweb: v1.45.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.43.0 # a catalog version
158
+ oats package add oats.aweb v1.45.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
  ```
@@ -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.
package/docs/tui.md CHANGED
@@ -182,7 +182,9 @@ while a terminal is open); under 80 columns it has the whole width.
182
182
  place when it gains or loses one. Under one parent, the instances that do
183
183
  its work (the kernel's `sameWork`, from an OATS with `instance-same-work`)
184
184
  come first, then the others, each part newest first, as the Desktop lists
185
- them. An empty row stands between each run
185
+ them. Pinned instances come before all of these, at every level, and an
186
+ instance with a pinned one below it counts as pinned
187
+ ([Pinning](#pinning)). An empty row stands between each run
186
188
  of instances related to no other and the group before or after it. The
187
189
  indent alone says which instance is under which: no mark is drawn for
188
190
  it. A row whose instances are folded away (`h`) says how many after its
@@ -744,9 +746,14 @@ The panel can be split in two **groups**, side by side or one above the
744
746
  other. Each group is a panel of [tabs](#tabs) of its own: a tab bar, a shown
745
747
  tab and the marks of its hidden ones.
746
748
 
747
- - **Splitting.** The leader then `|` splits the panel side by side, and the
748
- leader then `-` one above the other; in the Instances view `|` and `-`
749
- do the same without the leader. The tabs open stay in the first group
749
+ - **The list out of the way.** The leader then `b` gives the shown terminal the
750
+ whole screen with the focus, and again gives the list back with the focus (the
751
+ Desktop's `b` hides its sidebar; the list is the TUI's). With no terminal shown
752
+ it does nothing.
753
+ - **Splitting.** The leader then `|` (or `h`) splits the panel side by side, and the
754
+ leader then `-` (or `v`) one above the other; in the Instances view `|` and `-`
755
+ do the same without the leader. (`h` and `v` are Herdr's letters, shared with the
756
+ Desktop since its UI rework.) The tabs open stay in the first group
750
757
  (left, or top). The second group starts empty and is the focused group.
751
758
  - A split needs a tab open, and none starting.
752
759
  - **There are at most two groups.** With two, the split keys do nothing,
@@ -1301,6 +1308,38 @@ The exit status never depends on it.
1301
1308
  there can leave `.oats-stop-pending.json` in the agent's home, and then
1302
1309
  the agent can be started but not stopped while that file exists.
1303
1310
 
1311
+ ## Pinning
1312
+
1313
+ `p` pins the selected instance to the top of its machine's list, or unpins a
1314
+ pinned one. It runs `oats instance pin <name> on|off` at once, with no
1315
+ confirmation: a pin changes only the order, and `p` again undoes it. The line
1316
+ under the sidebar's title says `Pinning <name>…`, then the result, and the
1317
+ list is read again, so the row moves.
1318
+
1319
+ - **The order** is the Desktop's, from the same code. Pinned instances come
1320
+ first at every level: the groups of a machine's list, the instances of a
1321
+ group, and the children of one parent. An instance counts as pinned when
1322
+ it or any instance below it is, so pinning a child lifts its whole group,
1323
+ and the path down to it rises among its siblings. Among pinned instances,
1324
+ and among the others, the order is spawn time, newest first. Under one
1325
+ parent, the instances that do its work still come first. A pinned
1326
+ background instance leads the Background section. A filter never
1327
+ reorders the list. The palette lists the instances you opened most
1328
+ recently first, as before, and the others in this order.
1329
+ - **Shared.** The pin is kept in the instance's home, so everyone who views
1330
+ that machine sees it, in the TUI, the Desktop and another machine's view.
1331
+ There is no pin of your own.
1332
+ - **When `p` does nothing**, the line says why: this OATS doesn't list the
1333
+ `instance-pin` feature (then `oats instance pin <name> on|off` needs a
1334
+ newer OATS too), the instance is held by a spawn or a retire, or its pin
1335
+ is still changing. For an instance on another machine whose OATS doesn't
1336
+ list the feature, the kernel refuses before it sends anything, and the
1337
+ line gives its words.
1338
+ - **The key.** `p` is a default key from this version on. A `tui.json` that
1339
+ gives `p` to another action is refused at the start, with a line that
1340
+ names the key and both actions: move that action to another key, or give
1341
+ `pin` another key (or none) in `tui.json`.
1342
+
1304
1343
  ## Resuming lost sessions
1305
1344
 
1306
1345
  After a shutdown, a reboot or a crash, the instances that were running have
@@ -1472,6 +1511,7 @@ that kind.
1472
1511
  | close the empty group | – | – | – | – | – | `x` |
1473
1512
  | stop, restart, start, retire | `X`, `R`, `S`, `D` | – | – | – | – | `X`, `R`, `S`, `D` |
1474
1513
  | spawn another of the soul | `N` | – | – | – | – | `N` |
1514
+ | pin or unpin (`oats tui` only; the Desktop's is in the row's menu) | `p` | – | – | – | – | – |
1475
1515
  | the Instances, Souls, Capabilities views | `1`, `2`, `3` | – | – | – | – | `1`, `2`, `3` |
1476
1516
  | the help | `?` | – | – | – | – | `?` |
1477
1517
  | the list | `Esc` | – | – | – | – | `Esc` |
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.21** ([release notes](release-notes/v0.69.21.md)).
10
- The 0.69.21 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
9
+ The latest version is **OATS 0.69.22** ([release notes](release-notes/v0.69.22.md)).
10
+ The 0.69.22 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.21,** in the [release notes](release-notes/): it says what to do before
14
+ 0.69.22,** 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.21, in either order
24
- npm install -g @awebai/oats@0.69.21 # 1. the CLI
23
+ # 0. where the Desktop is installed: Desktop 0.69.22, in either order
24
+ npm install -g @awebai/oats@0.69.22 # 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,11 @@ 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.22](release-notes/v0.69.22.md#upgrade):** the catalog pins
221
+ oats.aweb 1.45.0; `setup --install-aw` installs the tested aw by default.
222
+ The Desktop's leader is Ctrl+Space (Ctrl+X a click away; a leader you set is
223
+ kept). A `tui.json` that binds `p` to another action moves it. Respawn
224
+ instances to take the new module.
220
225
  - **[0.69.21](release-notes/v0.69.21.md#upgrade):** the catalog pins
221
226
  oats.aweb 1.43.0. A deployment on a non-public aw registry runs
222
227
  `oats aweb setup --registry <origin>`, reruns `oats aweb resident create`,
@@ -8,7 +8,7 @@
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.43.0",
11
+ "ref": "v1.45.0",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.69.21",
3
+ "version": "0.69.22",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -9,8 +9,8 @@
9
9
  Why these and not others: the four traced cases on #1879 (schedule edit at 0.40, Remove at 0.49 and
10
10
  0.53, the Stop outcome at 0.52) all sit where the Desktop words a consequence itself or writes a whole
11
11
  definition. What stays on is a read, a terminal, or a change fenced by the kernel's own answer: Spawn
12
- applies only the decision its preview showed (`--expect-decision`), and Start, Restart, colour and
13
- background report only an answer the Desktop reads in full (each fails closed on a shape it does not
12
+ applies only the decision its preview showed (`--expect-decision`), and Start, Restart, colour,
13
+ background and pin report only an answer the Desktop reads in full (each fails closed on a shape it does not
14
14
  know).
15
15
 
16
16
  Enforcement is not the renderer's. Every place an operation enters the backend asks
@@ -65,6 +65,7 @@ export const OPERATIONS = Object.freeze({
65
65
  // ── An instance's own record.
66
66
  'POST /api/instance-color': allowed("colour: one field of the instance's own record, the answer read in full"),
67
67
  'POST /api/instance-background': allowed("background: one field of the instance's own record, the answer read in full"),
68
+ 'POST /api/instance-pin': allowed("pin: one field of the instance's own record, the answer read in full"),
68
69
  // ── Reads.
69
70
  'POST /api/instance-git git': read('git'),
70
71
  'POST /api/instance-git diff': read('git'),
@@ -0,0 +1,69 @@
1
+ /** The workspace's capabilities as one flat list, as both clients draw it (the Desktop UI rework, slice 3b: "show
2
+ * core and other ones as really the same"). Core capabilities (a knowledge, messaging or tasks `layer`) come first
3
+ * in that order, then every other one by name. Each entry carries what its row says: its core slot, whether it
4
+ * is one of the workspace's defaults (`oats workspace status` `defaults`), and who made it (capability-origin.mjs).
5
+ * Nothing is inferred: a default is matched to a row only by the name and the source the kernel reports, and
6
+ * with no reported `defaults` no row is called a default. Pure and DOM-free. */
7
+ import { sameRepo } from './repo-moves.mjs';
8
+ import { memberNames, hostKeyOf, matchCapabilities } from './capability-rows.mjs';
9
+ import { capabilityOrigin } from './capability-origin.mjs';
10
+
11
+ /** The core slots, in the one order every surface shows them. */
12
+ export const CORE_LAYERS = Object.freeze(['knowledge', 'messaging', 'tasks']);
13
+
14
+ const record = v => !!v && typeof v === 'object' && !Array.isArray(v);
15
+ const text = v => typeof v === 'string' && v ? v : null;
16
+ const list = v => Array.isArray(v) ? v : [];
17
+
18
+ /** Whether a declared default (`{ name, from }`: `from` is "package", "here" or a member key) names this row. */
19
+ export function defaultNames(entry, row, hostKey = null) {
20
+ if (!record(entry) || entry.name !== row?.name) return false;
21
+ if (entry.from === 'package') return row.kind === 'package';
22
+ if (entry.from === 'here') return row.kind === 'member' && !!text(hostKey) && sameRepo(row.repoKey, hostKey);
23
+ if (text(entry.from)) return row.kind === 'member' && sameRepo(row.repoKey, entry.from);
24
+ return false;
25
+ }
26
+ /** The row's place in the workspace's defaults: 'on' (every soul starts with it), 'off' (the workspace turns it
27
+ * off), or null (not a default, or no defaults reported). A turned-off entry reports no source: it is matched by
28
+ * name. A slot default fills its core slot (`defaults.slots.<layer>`). */
29
+ export function defaultState(status, row) {
30
+ const defaults = status?.defaults;
31
+ if (!record(defaults) || !row) return null;
32
+ const hostKey = hostKeyOf(status);
33
+ for (const cap of list(defaults.capabilities)) {
34
+ if (!record(cap) || cap.name !== row.name) continue;
35
+ if (cap.off === true) return 'off';
36
+ if (defaultNames(cap, row, hostKey)) return 'on';
37
+ }
38
+ const slot = text(row.layer) && record(defaults.slots) ? defaults.slots[row.layer] : null;
39
+ return record(slot) && defaultNames(slot, row, hostKey) ? 'on' : null;
40
+ }
41
+ /** The rank of a row in the list: a core slot's index, else after every core one. */
42
+ const rank = row => { const at = CORE_LAYERS.indexOf(row?.layer); return at < 0 ? CORE_LAYERS.length : at; };
43
+
44
+ /** The list's entries, in drawn order: `{ row, core, default, origin }`. `core`: the row's core slot or null;
45
+ * `default`: defaultState; `origin`: capabilityOrigin. `query` narrows by name (matchCapabilities). */
46
+ export function capabilityList(rows, status, { query = '' } = {}) {
47
+ const names = memberNames(status);
48
+ return matchCapabilities(list(rows), query)
49
+ .map(row => ({ row, core: CORE_LAYERS.includes(row.layer) ? row.layer : null, default: defaultState(status, row), origin: capabilityOrigin(row, status, names) }))
50
+ .sort((a, b) => rank(a.row) - rank(b.row) || String(a.row.name).localeCompare(String(b.row.name)) || a.origin.by.localeCompare(b.origin.by));
51
+ }
52
+
53
+ /** What the list's lead sentence needs, from the reported defaults: null when the kernel reports none (no claim).
54
+ * `empty`: the workspace sets no default at all. `emptySlots`: the core slots no default fills (by a slot or a
55
+ * named capability of that layer), in CORE_LAYERS order. `unlisted`: the declared defaults no catalog row
56
+ * matches (`{ name, off }`), so the list cannot show them as rows; a turned-off one is unlisted when no row has
57
+ * its name. */
58
+ export function defaultsSummary(status, rows) {
59
+ const defaults = status?.defaults;
60
+ if (!record(defaults)) return null;
61
+ const hostKey = hostKeyOf(status), all = list(rows);
62
+ const slots = CORE_LAYERS.map(layer => [layer, record(defaults.slots) && record(defaults.slots[layer]) && text(defaults.slots[layer].name) ? defaults.slots[layer] : null]);
63
+ const caps = list(defaults.capabilities).filter(cap => record(cap) && text(cap.name));
64
+ const listed = entry => entry.off === true ? all.some(row => row?.name === entry.name) : all.some(row => defaultNames(entry, row, hostKey));
65
+ const filled = new Set(slots.filter(([, value]) => value).map(([layer]) => layer));
66
+ for (const cap of caps) if (cap.off !== true) for (const row of all) if (defaultNames(cap, row, hostKey) && CORE_LAYERS.includes(row.layer)) filled.add(row.layer);
67
+ const unlisted = [...slots.filter(([, value]) => value).map(([, value]) => value), ...caps].filter(entry => !listed(entry)).map(entry => ({ name: entry.name, off: entry.off === true }));
68
+ return { empty: !filled.size && !caps.length, emptySlots: CORE_LAYERS.filter(layer => !filled.has(layer)), unlisted };
69
+ }