@awebai/oats 0.69.20 → 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 (53) hide show
  1. package/bin/oats.mjs +26 -3
  2. package/docs/capabilities.md +1 -1
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +311 -4
  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/desktop-cli-api.md +80 -0
  8. package/docs/desktop.md +404 -177
  9. package/docs/implementation.md +15 -2
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge-capability-authoring.md +1 -1
  12. package/docs/official-catalog.md +44 -1
  13. package/docs/packages.md +2 -2
  14. package/docs/release-lane.md +8 -6
  15. package/docs/release-notes/v0.69.21.md +155 -0
  16. package/docs/release-notes/v0.69.22.md +221 -0
  17. package/docs/servers.md +5 -1
  18. package/docs/souls-and-instances.md +11 -0
  19. package/docs/tui.md +44 -4
  20. package/docs/upgrading.md +16 -5
  21. package/lib/capability-contract.mjs +2 -2
  22. package/lib/command-flags.mjs +1 -0
  23. package/lib/core.mjs +5 -3
  24. package/lib/instance-inspect.mjs +3 -0
  25. package/lib/instance-lifecycle.mjs +16 -0
  26. package/lib/instance-listing.mjs +8 -4
  27. package/lib/instance-pin.mjs +59 -0
  28. package/lib/kernel-features.mjs +1 -1
  29. package/lib/servers.mjs +8 -3
  30. package/package-catalog.json +1 -1
  31. package/package.json +1 -1
  32. package/packages/client/above-tested.mjs +3 -2
  33. package/packages/client/capability-list.mjs +69 -0
  34. package/packages/client/capability-origin.mjs +54 -0
  35. package/packages/client/cli-adapter.mjs +9 -1
  36. package/packages/client/deployment-data.mjs +3 -0
  37. package/packages/client/deployment-panel.mjs +2 -0
  38. package/packages/client/home-board.mjs +50 -0
  39. package/packages/client/instance-pin.mjs +28 -0
  40. package/packages/client/instance-record-outcome.mjs +31 -0
  41. package/packages/client/instance-tree.mjs +62 -20
  42. package/packages/client/keymap.mjs +11 -3
  43. package/packages/client/remote-roster.mjs +8 -1
  44. package/packages/client/roster-row-facts.mjs +50 -0
  45. package/packages/client/roster-sections.mjs +10 -7
  46. package/packages/client/soul-role.mjs +44 -0
  47. package/packages/client/waiting-on-you.mjs +10 -0
  48. package/packages/tui/lib/actions.mjs +11 -4
  49. package/packages/tui/lib/client.mjs +3 -1
  50. package/packages/tui/lib/main.mjs +16 -2
  51. package/packages/tui/lib/model.mjs +48 -5
  52. package/packages/tui/lib/store.mjs +28 -2
  53. package/skills/oats-getting-started/SKILL.md +283 -30
@@ -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 |
@@ -136,7 +136,7 @@ and the rules its tests pin.
136
136
  | `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
137
137
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
138
138
  | `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
139
- | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through; `instance-background.mjs` is the same for whether an instance is background: its home record, read by the rows, inspect and the command, and written by spawn and the command; `instance-same-work.mjs` is an instance's same-work flag, its home record bound to a parent, and `sameWorkOf`, the one rule of whether it is on, which status rows, spawn and `oats instance same-work` go through |
139
+ | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through; `instance-background.mjs` is the same for whether an instance is background: its home record, read by the rows, inspect and the command, and written by spawn and the command; `instance-pin.mjs` is the same for whether an instance is pinned at the top of its machine's list: its home record, read by the rows and inspect, and written only by `oats instance pin`; `instance-same-work.mjs` is an instance's same-work flag, its home record bound to a parent, and `sameWorkOf`, the one rule of whether it is on, which status rows, spawn and `oats instance same-work` go through |
140
140
  | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, the rollback of an interrupted add, and completion of Git's partial removal. An unregistered residue with a dangling `.git` file is compared with the recorded branch through a private temporary index (`read-tree`, refresh, `diff-files` allowing deletions, and `ls-files --others --exclude-standard`) before permissions or files change; the clone's index is never used. Only clean residue is made writable, without following symlinks, and deleted |
141
141
  | `errors.mjs` | `oatsError`, and the door of the lifecycle verbs: `isKernelCode` (the shape of a kernel code, `^E_[A-Z0-9_]+$`, never a list of codes), `kernelCode`, `asKernelError` and `errorCause`. An answer of `oats retire`, `oats instance stop`, `oats session` and `oats worktree` carries a kernel code, or one of the two names every command answers as they are (`OWN_NAME_FAILURES`: `unsafe-config-key`, `unsafe-config-value`), and no other: `isAnswerCode` is what the door and its wrappers keep, `isKernelCode` stays the test of the shape. An error of the system's or of Node's, a refusal written as a plain `Error` without a code, and a defect (`isDefect`: a `TypeError` and its like without a code, or a thrown value that is no `Error`), is wrapped at the boundary (`bin/oats.mjs` `lifecycleFail`; in a retire, `core.mjs` `retireClaimed`, which also says what the retire had done by then) and its own code goes to `details.cause` (a defect's name does; a plain `Error` without a code has no cause, and is answered with the general code and its message alone, which is what an ordinary refusal of `tmux`, `git` or the kernel itself must read as). New code that answers an error tests the shape with these, never `e.code \|\| "E_…"`: a system error has a `code` too. Whoever ends an error's way up prints the stack of a defect with `reportDefect`: the door, and any code that turns a caught error into a row of results (a stop's `results[]`, a retire's `childrenStopped[]`), after which nobody else can. Two more rules of the lifecycle verbs live here. **`lifecycleBusy(holder, said, remedy, details)` is the only way `E_LIFECYCLE_BUSY` is made** (`test/lifecycle-busy-holder.test.mjs` scans `lib/` and `bin/` for any other): it sets `details.holder` (`BUSY_HOLDERS`: `"running"` only where the kernel established that the other command is alive, `"unknown"`, `"none"`) and refuses to build an `"unknown"` or `"none"` answer without the step that ends it. **`BEFORE_EFFECT_CODES` lists, per verb, the codes that verb answers only before any effect**; `afterFirstEffect` turns a listed code raised after a verb's first effect into a defect (`E_LIFECYCLE_FAILED`, `cause.name: "LateRefusal"`), and is called at the one place of each verb that knows how far it got (`core.mjs` `retireFailure`, from `at.phase`; `instance-lifecycle.mjs` `applyStop`, from whether a target's stop began). A code may join the list only when every place that raises it in that verb is before the first effect; a place found after it gets a code of its own, never the net |
142
142
  | `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire`, `oats instance stop --apply`, `oats instance upgrade`, `oats session start --resume` (verb `resume`) and every other session start and restart, a scheduled start included (verb `start`, #1602; `core.mjs` `startClaimed`, the only exclusion of one start by another: two starts are answered `E_SESSION_START_BUSY` from the claim, `startPair`; a path with no record it can read takes no claim (`readHomeRecord`, as every lifecycle verb reads its record first); the start runs on the home's path on disk, and a home given through a link first answers what a start of the path as given answered before any guard (`startRefusals`, in their order; a partial upgrade is left to the claim while an upgrade holds it, `upgradeHoldsClaim`, as the CLI's pre-check does), then is held to its own authority on the path as given, `sessionDirectoryGuard`, then again with every check of the start's roots; an owned directory home must resolve to the home its own receipt records, bound by the receipt's paths, not by a second read of the disk: `requestedHomeGuard`) (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too A holder may add to its record as it goes (`recordInClaim`), and the next holder reads what a gone one left: a worktree add its running Git step; a retire the retire hooks that ended, `retireHooks: [{capability, meta?}]` with `retireHooksFor` (the home's `createdAt`: the list is bound to the incarnation it ran for, so a claim left by a retire that is gone never skips hooks for another home of the same name), which the retire that takes the claim over does not run again (`core.mjs` `finishedRetireHooks`; `claimHomeFor` hands the gone holder's record over as `tookOver`). A record without them skips nothing. |
@@ -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.42.1
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.42.1` | `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.42.1
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.42.1 # 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,155 @@
1
+ # OATS 0.69.21
2
+
3
+ The official catalog pins oats.aweb 1.43.0: a private aw registry is admitted
4
+ by one host setting, aw children no longer take exported selectors, and grant
5
+ seats stay in their recorded team. Instances can be pinned to the top of their
6
+ machine's list (`oats instance pin`). The Desktop's sidebar is reworked: two-line
7
+ rows, groups that start collapsed, no lineage lines, and a new foot. The
8
+ getting-started skill sets up a workspace on the person's own aweb server.
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.43.0 (from 1.42.1). oats.framework stays
16
+ 1.26.0 and oats.okf 6.2.0. `oats sync` takes it.
17
+
18
+ What a deployment must change, from oats.aweb's 1.43.0 entry:
19
+
20
+
21
+ - **On a non-public aw registry:**
22
+ 1. Run `oats aweb setup --registry <origin>` in the deployment.
23
+ 2. Rerun `oats aweb resident create <name>` for each resident.
24
+ 3. Run `oats aweb wake install` from your own shell.
25
+ 4. Restart the homes.
26
+
27
+ Until then, setup, spawn, join, launch and readiness refuse with
28
+ `registry-setting-required`. A deployment on the public registry changes
29
+ nothing.
30
+ - **Exported aw selectors no longer reach aw:** `AWEB_IDENTITY_HOME`,
31
+ `AWEB_URL`, `AWEB_API_KEY`, `AWEB_ROLE_NAME`, `AWEB_ROLE`,
32
+ `AWID_REGISTRY_URL`. If you exported them for ordinary lifecycle commands,
33
+ record the service in the selected aw home instead, and a private registry
34
+ in the setting above.
35
+ - **Grant seats:**
36
+ - A grant seat with `.oats-aweb/seat.json` whose `identity.resident` or
37
+ default team has changed refuses start: respawn it.
38
+ - A home that an earlier release renewed into another team needs the
39
+ printed manual revoke, then `oats retire <instance> --force`.
40
+ - **Retained seats:** a symlinked `identity.source`, or a link or special
41
+ file in the copied authority, now refuses. Point it at the real directory.
42
+ - **Scripts:**
43
+ - `oats aweb setup --check-only --json` answers `member:null` with a nonzero
44
+ exit when the membership can't be read.
45
+ - `join --plan` fails with `E_SETUP_MEMBERSHIP` for an unreadable root.
46
+ - `setup --create`, and `setup --join` without a token, refuse while the
47
+ default root's membership can't be read.
48
+ - An unavailable username fails as `E_SETUP_USERNAME_UNAVAILABLE`, where it
49
+ was `E_SETUP_NATIVE`.
50
+
51
+ **Respawn instances** to take the new oats.aweb module, or move a stopped
52
+ home with `oats instance upgrade`. A running instance keeps the module it was
53
+ composed with.
54
+
55
+ ## Added
56
+
57
+ - **The `oats-getting-started` skill sets up a new workspace on the
58
+ person's own aweb server** (#1774, #1775). Step 1's messaging line names
59
+ hosted aweb as the default, "unless you run your own aweb server". The
60
+ own-server answer collects
61
+ three things, none of them secret: the namespace domain the person
62
+ controls, the server's public URL, and whether the server uses the public
63
+ AWID registry. A server on a private registry is not set up yet: the
64
+ branch stops before writing anything, says it needs `oats.aweb` with
65
+ `oats aweb setup --registry` (awebai/oats-aweb#284), and offers hosted
66
+ aweb. It also names the prerequisites, which stay on the person's side:
67
+ the namespace's controller key on this computer, its `_awid` DNS record,
68
+ and the server reachable. Then:
69
+ - The skill reads the version `oats.aweb` was tested with (`tested` in
70
+ its `aw-compat.json`, read at the catalog's exact `oats.aweb` ref, never
71
+ `main`) and compares the installed `aw` with it, in `oats.aweb`'s own
72
+ version order. A missing or older `aw` is replaced by `tested`: the skill
73
+ checks the version `aw` prints, and that the program `file` reports is
74
+ for this machine's architecture. A newer `aw` is kept, since another
75
+ deployment may need it, and the hand-over says "aw X is newer than the
76
+ tested Y; kept". On an OATS release whose `oats.aweb` is older than
77
+ `v1.42.1`, the branch stops and offers hosted aweb.
78
+ - The workspace commits the team `<workspace>:<namespace>` as its only
79
+ team and its default. It writes no hosted `default:…aweb.ai` team and no
80
+ `localTeams`.
81
+ - Step 9 checks the DNS record read-only
82
+ (`aw id namespace check-txt`), then creates the team with
83
+ `oats aweb setup --create <workspace> --namespace <domain> --name <workspace>-root`,
84
+ registered with the person's server. It reports where the team key
85
+ lives (the path, never the key), and checks membership before the
86
+ spawn.
87
+
88
+ The skill never makes the namespace's controller key, and never asks for
89
+ `AWEB_API_KEY`. Hosted aweb is unchanged: it installs the latest `aw` and
90
+ records its version. The join of an existing workspace and the machine
91
+ found-list are unchanged, and don't offer the own-server branch.
92
+
93
+ - **Pin an instance at the top of its machine's list** (feature `instance-pin`).
94
+ `oats instance pin <instance> on|off` records or removes the pin, locally or
95
+ with `--server`. Its answer is `{ instancePinApi: 1, instance, home, pinned,
96
+ changed }`; `home` names the home it resolved, so a routed or `--home` pin
97
+ says which one it pinned.
98
+ - The pin is shared. It is kept in the instance's home, so everyone who views
99
+ that machine sees it: the Desktop, the TUI and another machine's routed
100
+ view. There is no per-viewer pin. In 0.69.21 the pin is set and read with
101
+ the CLI only: the Desktop and the TUI show pins, and set them, from the
102
+ next release.
103
+ - The home keeps it in `.oats-pinned.json` through restart, stop, resume and
104
+ `oats instance upgrade`, and a retire removes it with the home. Retire never
105
+ counts the file as work, and a capability cannot declare it.
106
+ - `pinned: true` appears on `oats status --json` rows, on `oats server roster
107
+ --json` rows (only when the host's row says exactly `true`) and on
108
+ `oats inspect --home`. The key is absent when the instance is not pinned.
109
+ - No spawn flag or `soul.yaml` key pins an instance: a pin is a person's
110
+ choice about the view. A routed pin needs a host that lists `instance-pin`.
111
+
112
+ See
113
+ [Pinned instances](../desktop-cli-api.md#pinned-instances-oats-instance-pin).
114
+
115
+ ## Changed
116
+
117
+ - **Getting started names an unavailable aweb username.** With an oats.aweb
118
+ that answers `E_SETUP_USERNAME_UNAVAILABLE` (awebai/oats-aweb#286), the
119
+ `oats-getting-started` skill's signup step knows that nothing was created:
120
+ it asks the person for another `N`, or, on a machine found-list, tells
121
+ them why and stops. `E_SETUP_NATIVE` no longer reads as "most likely
122
+ taken"; on an older oats.aweb a taken `N` still fails that way.
123
+
124
+ - **The catalog pins oats.aweb 1.43.0** (awebai/oats-aweb, tag `v1.43.0`), up
125
+ from 1.42.1. It still requires OATS >=0.68.0; the aw floor stays 1.36.33 and
126
+ the tested aw 1.36.58.
127
+ - **Registry admission is one host setting.** A private aw registry is
128
+ admitted only by `settings.oats.aweb.registry`, which
129
+ `oats aweb setup --registry <origin>` records in `oats-local.yaml`. A saved
130
+ `registry_url` and an exported `AWID_REGISTRY_URL` are locators only.
131
+ - **aw children ignore exported selectors.** Each takes only what a call
132
+ passes by name. A malformed `OATS_SETTINGS` refuses instead of using
133
+ defaults.
134
+ - **A grant seat's calls stay in its recorded team,** and its
135
+ `.oats-aweb/seat.json` owns that team. An empty grant seat now completes
136
+ retire with the documented `nothing-to-delete` outcome.
137
+ - **Membership and custody reads fail closed.** An unreadable read is
138
+ unknown, never "not a member".
139
+ - **Setup** names an unavailable username, and points a new account at
140
+ `claim-human`. `--invite-stdin` reads the token without echo on a
141
+ terminal, and `oats aweb invite --out <file>` writes it to a new
142
+ owner-only file.
143
+
144
+ - **The Desktop's sidebar reads more calmly.** An agent's row is two lines: its name, then its soul and the machine it runs on ("oats-expert · falcon": this computer's own rows by its `host.name` in `oats-local.yaml`, else "This Mac"), in a 44px row with its dot centred. The repository, branch, pull request and harness badge are no longer on the row, and the row has no hover card and no tools on hover: the instance panel shows the repository, branch, harness and model, and a new **Needs input** section with the reason an agent waits, how long it has waited and its message; the row's context menu (right-click, Shift+F10 or the Menu key) opens its pull request (**Open pull request…**) and starts a stopped agent (**Start…**). Until the panel serves an agent whose terminal isn't open, the row's tooltip says its repository, branch, harness and model; with the keyboard alone those show once its terminal is open. The roster draws no lines between agents any more: a child is indented under its parent, a little space separates each group from the next, and a screen reader hears "under <parent>" (with "same work" for a child doing its parent's work) and "sibling of <name>". The order and the needs-input marks are unchanged, and the command palette keeps its lines. **Workspace overview** and **Automations** are pinned rows under the list of workspaces, and **Automations** shows a red dot, which a screen reader hears as "a run failed", while a schedule's last run failed. The foot shows **N need you** (it takes you to the first agent that needs you), **New agent** and **?** (the keyboard shortcuts). An empty roster says "No agents yet" and the key that starts one. The CLI and the docs still say "instance". See [the sidebar](../desktop.md#workspaces) and [its instance tree](../desktop.md#the-sidebars-instance-tree).
145
+
146
+ - **The Desktop's sidebar shows the top-level instances only until you open one.** An instance with children has a chevron before its name, with the number of instances under it. Click the chevron to show or hide its group; a click elsewhere on the row still opens its terminal, and Right and Left still open and close the focused row. Every instance at the top of the tree starts collapsed in each new window (except one still being set up or retired, or whose retire failed, which stays open), and an instance inside a group starts open. A collapsed instance still shows "! N below" for the hidden instances that need input. **Show in roster**, `--instance` and a spawn from the Desktop open the rows above the instance they show. The TUI's list is unchanged and still shows every instance open ([The sidebar's instance tree](../desktop.md#the-sidebars-instance-tree)).
147
+
148
+ ## Fixed
149
+
150
+ - **The getting-started skill reads a failed join from what ran.** Its last messaging check (step 9, item 5) no longer says a run left the root outside the team when no root was made. After the signup or the labelled join it says no root was made or recorded, and a team create that recorded no root is rerun unchanged. Before the person's join window opens, the agent lists the per-team roots and compares the list afterwards, so a root from an earlier join is not read as this one. It compares the team's label as the provider writes the folder name: lowercase, `_` and `.` as `-`. When the window shows no `E_SETUP_` code, the agent asks for the window's last line. The agent still never sees the join's output, never reruns it, and asks for no secret ([#1746](https://github.com/oats-project/oats/issues/1746)).
151
+
152
+ ## Removed
153
+
154
+ - **Show only the current workspace.** The list of workspaces always shows every workspace: the toggle, its ⌥⇧⌘O / Ctrl+Alt+Shift+O (which reaches a terminal's program again) and its palette command are gone, and a choice saved for it is ignored.
155
+ - **The sidebar's settings cog, its Hide sidebar button and its brand mark.** Theme, font and keyboard shortcuts are in the command palette (**Theme: choose…**, **Font: choose…**, **Shortcuts: edit keyboard shortcuts…**) and on the foot's **?**; the sidebar still hides with ⌘B / Ctrl+Shift+B, the palette's **Sidebar: toggle (hide/show)** and **Show sidebar**.
@@ -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/servers.md CHANGED
@@ -478,6 +478,7 @@ schedule's spec still travel as arguments.
478
478
  | `instance stop --plan\|--apply`, `retire --plan`, `retire --plan-revision … --idempotency-key …` | the instance's home | `lifecycle-plans` (`lifecycleApi: 1`) |
479
479
  | `instance color` | the instance's home | `instance-color` |
480
480
  | `instance background` | the instance's home | `instance-background` |
481
+ | `instance pin` | the instance's home | `instance-pin` |
481
482
  | `instance same-work` | the instance's home | `instance-same-work` |
482
483
 
483
484
  `instance suggest-name` and `instance upgrade` are never routed: `--server` is
@@ -648,7 +649,10 @@ way, through the kernel's own read of it, and a value that read refuses is
648
649
  dropped ([`retire`](desktop-cli-api.md#row-retire)). `sameWork` (feature
649
650
  `instance-same-work`, the instance does the same work as its parent) is
650
651
  relayed only when the host's row has `sameWork: true`, and is absent
651
- otherwise ([`sameWork`](desktop-cli-api.md#row-same-work)). A removed or edited registration keeps
652
+ otherwise ([`sameWork`](desktop-cli-api.md#row-same-work)). `pinned` (feature
653
+ `instance-pin`, the instance is pinned at the top of its machine's list) is
654
+ relayed only when the host's row has exactly `pinned: true`, and is absent
655
+ otherwise ([`pinned`](desktop-cli-api.md#row-pinned)). A removed or edited registration keeps
652
656
  its group from the saved routes. State is pulled on every call, from every
653
657
  group at once: each probe has its own deadline, `--per-target` (default 20 s)
654
658
  capped by `--budget` (default 45 s, the deadline of the whole answer), and a
@@ -483,6 +483,17 @@ instance with the flag on carries `sameWork: true` on its `oats status
483
483
  remote relay are in
484
484
  [desktop-cli-api.md](desktop-cli-api.md#same-work-as-the-parent-oats-instance-same-work).
485
485
 
486
+ `oats instance pin <instance> on|off` (feature `instance-pin`) pins an
487
+ instance at the top of its machine's list, or removes the pin, addressed as
488
+ `oats instance background` addresses it and routed with `--server`. The pin
489
+ is the home's own file, `.oats-pinned.json`, so it is shared: every client of
490
+ that machine (the Desktop, the TUI, another machine's routed view) reads it
491
+ from the `pinned: true` on the instance's row and lists it first. It survives
492
+ a restart, a stop and a start, a resume and `oats instance upgrade`, and a
493
+ retire removes it with the home. No spawn flag or `soul.yaml` key sets it.
494
+ The answer and the errors are in
495
+ [desktop-cli-api.md](desktop-cli-api.md#pinned-instances-oats-instance-pin).
496
+
486
497
  `spawnOrigin` records the caller independently of these links. For new spawns
487
498
  from OATS 0.64.0, it is `instance` when the caller's `OATS_INSTANCE` and/or
488
499
  `OATS_INSTANCE_HOME` resolve consistently to an extant home in this deployment;