@awebai/oats 0.69.19 → 0.69.20

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 (38) hide show
  1. package/bin/oats.mjs +2 -2
  2. package/docs/capabilities.md +26 -13
  3. package/docs/container.md +218 -18
  4. package/docs/desktop-cli-api.md +25 -11
  5. package/docs/desktop.md +16 -0
  6. package/docs/implementation.md +2 -1
  7. package/docs/integrations.md +1 -1
  8. package/docs/knowledge.md +5 -5
  9. package/docs/official-catalog.md +4 -4
  10. package/docs/packages.md +11 -11
  11. package/docs/release-notes/v0.69.20.md +325 -0
  12. package/docs/servers.md +4 -2
  13. package/docs/souls-and-instances.md +4 -2
  14. package/docs/upgrading.md +11 -5
  15. package/docs/workspaces.md +13 -7
  16. package/lib/core.mjs +31 -195
  17. package/lib/hook-outcome.mjs +6 -0
  18. package/lib/instance-lifecycle.mjs +3 -1
  19. package/lib/instance-listing.mjs +3 -2
  20. package/lib/launch-prompt-fixtures/README.md +6 -0
  21. package/lib/retire-admission.mjs +215 -0
  22. package/lib/servers.mjs +3 -0
  23. package/package-catalog.json +2 -2
  24. package/package.json +1 -1
  25. package/packages/client/attributed-human.mjs +13 -0
  26. package/packages/client/deployment-data.mjs +4 -0
  27. package/packages/client/deployment-panel.mjs +2 -0
  28. package/packages/client/instance-lifecycle.mjs +6 -4
  29. package/packages/client/lifecycle-confirmation.mjs +4 -2
  30. package/packages/client/lifecycle-contract.mjs +11 -6
  31. package/packages/client/remote-roster.mjs +4 -0
  32. package/packages/record/README.md +15 -2
  33. package/packages/record/docs/capture-service.md +14 -0
  34. package/packages/record/lib/canonical.mjs +2 -70
  35. package/packages/record/lib/capture-aw-unit.mjs +14 -3
  36. package/packages/record/lib/capture-aw.mjs +11 -5
  37. package/packages/record/lib/capture-health.mjs +16 -5
  38. package/skills/oats-getting-started/SKILL.md +2 -2
package/docs/packages.md CHANGED
@@ -48,14 +48,14 @@ whole organisation:
48
48
 
49
49
  ```yaml
50
50
  packages:
51
- oats.okf: v6.0.3 # bare version → the official catalog
51
+ oats.okf: v6.2.0 # bare version → the official catalog
52
52
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
53
53
  ```
54
54
 
55
55
  - **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
56
56
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
57
57
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
58
- convention (`v5.8.0` or `oats-framework/v1.25.2`) and the payload path. An id
58
+ convention (`v5.8.0` or `oats-framework/v1.26.0`) and the payload path. An id
59
59
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
60
60
  a package outside the catalog"). The catalog is the reviewed official list
61
61
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -78,8 +78,8 @@ members:
78
78
  - git:github.com/acme/agents
79
79
  - git:github.com/acme/platform
80
80
  packages:
81
- oats.framework: v1.25.2
82
- oats.okf: v6.0.3
81
+ oats.framework: v1.26.0
82
+ oats.okf: v6.2.0
83
83
  oats.aweb: v1.42.1
84
84
  teams:
85
85
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
@@ -109,7 +109,7 @@ decision recorded in the lock.
109
109
  $ oats sync
110
110
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
111
111
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
112
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 6.0.3 ✓ (@ fa13ca0b)
112
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 6.2.0 ✓ (@ 92c63060)
113
113
  changed acme.tools — → 0.4.0 (@ 47f4b816)
114
114
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
115
115
  teams platform (shared) · this deployment's: oats teams
@@ -181,8 +181,8 @@ same workspace commit hold identical locks.
181
181
  "source": "catalog:oats.okf",
182
182
  "url": "https://github.com/awebai/oats-okf.git",
183
183
  "path": "oats-package",
184
- "version": "6.0.3",
185
- "commit": "fa13ca0b026995fe5a278f7fb922ecd4eb09d6a9",
184
+ "version": "6.2.0",
185
+ "commit": "92c630606db81f55c3e31002cb51d0e603dc7902",
186
186
  "integrity": "sha256-…",
187
187
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
188
188
  },
@@ -431,12 +431,12 @@ A soul that names one of the package's capabilities with
431
431
  {
432
432
  "policy": "docs/official-catalog.md",
433
433
  "packages": {
434
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.0.3", "path": "oats-package" },
435
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.25.2", "path": "oats-package" }
434
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.2.0", "path": "oats-package" },
435
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.26.0", "path": "oats-package" }
436
436
  }
437
437
  }
438
438
  ```
439
439
 
440
- `ref` carries the tag convention: a workspace's `oats.framework: v1.25.2`
441
- resolves to tag `oats-framework/v1.25.2`. Resolving through the catalog never
440
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.26.0`
441
+ resolves to tag `oats-framework/v1.26.0`. Resolving through the catalog never
442
442
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,325 @@
1
+ # OATS 0.69.20
2
+
3
+ The official catalog pins oats.okf 6.2.0 and oats.framework 1.26.0. oats.aweb
4
+ stays 1.42.1. Retiring an old home whose recorded cleanup hooks cannot run is
5
+ now refused before anything stops, with `--force` as the named way out, and
6
+ the Desktop's Remove explains why. The team container gains an egress
7
+ component that routes only the services an agent needs. The Desktop shows an
8
+ instance's owning human. OATS's own copy of the engineering template moves to
9
+ template-v4.0.2.
10
+
11
+ ## Upgrade
12
+
13
+ - **Either order of the Desktop and the CLI works** from a Desktop newer than
14
+ 0.69.17 ([Either order works](../upgrading.md#either-order-works)). A
15
+ Desktop of 0.69.17 or older still goes first.
16
+ - **Package pins:** oats.okf 6.2.0 (from 6.0.3) and oats.framework 1.26.0
17
+ (from 1.25.2). oats.aweb stays 1.42.1. `oats sync` takes them.
18
+ - **Retiring an old home can now be refused.** A home spawned before
19
+ `capabilityRuntime`, or captured before 0.26, whose recorded retire hooks
20
+ cannot run is refused with `E_UNIDENTIFIED_INSTANCE_HOME`, unless its record
21
+ proves that no cleanup is owed. Clean up its external identities and
22
+ memberships with the provider's tooling, then run
23
+ `oats retire <instance> --force` (details under Changed).
24
+ - **Team-container deployments:**
25
+ - After pulling the updated team agent image, recreate existing agent
26
+ containers to apply the 50-second stop timeout. Acceptance refuses the
27
+ previous 45-second timeout.
28
+ - Deployment bundles default `team.registryRoute` to `external`. Existing
29
+ deployments with a registry Compose service must set
30
+ `team.registryRoute: local` before upgrading. External mode refuses a
31
+ local registry service or an owned destination, and local mode must refuse
32
+ a URL the local service does not serve.
33
+ - **Respawn instances** to take the new framework skills and this workspace's
34
+ template-v4.0.2 texts. A running instance keeps the texts it was composed
35
+ with.
36
+
37
+ ## Added
38
+
39
+ - The Desktop's instance panel shows an instance's **Owning human** in its
40
+ Lineage section when OATS reports a human its messaging identity is
41
+ attributed to (`attributedHuman` on its status row, local or on a server).
42
+ Instances keep their own names as their labels everywhere, and an instance
43
+ with no human attributed looks as before
44
+ ([An instance's owning human](../desktop.md#an-instances-owning-human)).
45
+
46
+ - The Compose egress boundary probe accepts `--json` for `{passed,receipts,error?}`
47
+ output and an optional derived `namePrefix` for every temporary container.
48
+ Receipts identify the name, image, network, confirmed creation and verified
49
+ absence; stderr includes receipts and unverified names in either mode.
50
+
51
+ - Agent egress policies can declare a nonempty subset of aweb, logs, registry,
52
+ secrets and signer. Targets and probe paths must match exactly. Namespace
53
+ authority TXT records are required with registry and refused without registry,
54
+ including messaging-only sets; the human origin is required with signer and
55
+ refused without signer. Omission keeps
56
+ the existing five-service compilation. The minimal Compose wrapper includes
57
+ explicit IPAM and a read-only preflight that refuses failed observations and
58
+ overlaps. Every subset retains the universal boundary controls; team-image CI
59
+ builds and probes the full set and two messaging subsets. See the
60
+ [container reference](../container.md#egress-component).
61
+
62
+ - The team-container deployment can build a non-root DNS/TLS egress image and
63
+ extend its Compose service. It routes only the named aweb, Secrets, Logs, signer
64
+ request and registry hosts, using pinned upstream addresses and profile-derived
65
+ public namespace TXT records. There is no recursive DNS or mounted service key.
66
+
67
+ - The agent Compose fragment requires `AGENT_TMP_SIZE`, in positive integer bytes
68
+ from the shared `agents.tmpSize` input, and applies it to the `/tmp` tmpfs. Its
69
+ acceptance check refuses a missing or different limit.
70
+
71
+ - Optional fragments add a public CA file with two fixed trust settings, or
72
+ operator-maintained bare Git mirrors at read-only `/mirrors`. Acceptance checks
73
+ their exact mounts and refuses writable-state aliases, multiply linked CA files
74
+ and arbitrary environment changes. The fixed public trust reaches the supervisor,
75
+ broker, direct SSH commands and login-captured tmux panes while retaining normal
76
+ public roots. No service credential or TLS verification bypass is added.
77
+
78
+ - Runtime acceptance proves the agent's own on-link gateway denial with live
79
+ controls and a plain-versus-isolated bridge regression. The ingress probe checks
80
+ every policy route over HTTP/1.1 and HTTP/2, with required full-policy inputs
81
+ and valid 200 service controls. Owned routes require separate common-path log
82
+ coverage before/after negatives and non-delivery for forbidden human authorities;
83
+ known-name refusals require completed TLS. Partial signer-only CLI calls cannot
84
+ emit the admission token.
85
+ Both checks must pass before agents launch. Readiness and rendered policy alone do not establish
86
+ isolation. See the [component contract](../../container/agent/egress/README.md).
87
+
88
+ - The egress component can enable two fixed external roles: Git HTTPS at
89
+ `github.com` and model HTTPS at `api.anthropic.com`. Operator-selected public
90
+ IPv4 DNS resolvers are required, with no default. Agent DNS still points only
91
+ at the proxy. Each external connection rejects unsafe or deployment addresses
92
+ and connects to a validated IP without resolving it again.
93
+ - External enforcement is exact SNI plus a public destination; it does not filter
94
+ HTTP authorities, paths, methods or repositories, or prove non-delivery at a
95
+ public backend. The five pinned service routes and owned-backend audit remain
96
+ separate. Runtime checks add verified-TLS external controls and refused-name
97
+ logging. Claude launch settings suppress ancillary traffic, whose actual host
98
+ requirements still need a real authorized start and turn.
99
+
100
+ ## Changed
101
+
102
+ - **`oats.framework` 1.26.0: `oats.core` 2.14.0, `oats.setup` 2.16.0,
103
+ `oats.coordination-setup` 1.1.0.**
104
+ - `oats.core`'s `/oats-operate` says that, from OATS 0.69.20, retiring a
105
+ home whose recorded retire hooks cannot run is refused with
106
+ `E_UNIDENTIFIED_INSTANCE_HOME` before anything stops, and that
107
+ `oats retire <instance> --force` then removes the home, warning that the
108
+ skipped hooks revoked nothing (#1953).
109
+ - `oats.setup`'s `/oats-onboarding` pins `oats.okf` 6.2.0 for knowledge
110
+ operations (#1945).
111
+ - `oats.setup`'s `/oats-agent-permissions` example asks a person before
112
+ `aw` runs with `--identity-home`, `--human` or `--team`, and no longer
113
+ allows a bare `aw mail ack` (#1952).
114
+ - `oats.coordination-setup` follows engineering-coordination template v4
115
+ (#1943). A maintainer's green light is an option per lane, off by
116
+ default. The landing rules list the lanes and their owners, and a lane's
117
+ maintainer is found by its instance name, `<person>-<lane>-maintainer`.
118
+ `VERIFIED at <head>` comes from whoever specified the work.
119
+
120
+ No capability needs a newer OATS. The retire refusal is the kernel's own,
121
+ and the skill names the version it starts in.
122
+
123
+ - The team agent image pins the released OATS 0.69.19 dependency closure,
124
+ removing the unused pi extension subtree from the image lock. The other
125
+ committed CLI packages and their integrity pins remain unchanged.
126
+
127
+ - The agent supervisor lets the wake broker finish its five-second channel
128
+ delivery drain before escalation. Broker cleanup allows six seconds and
129
+ sshd cleanup keeps three seconds; container acceptance requires a 50-second
130
+ stop grace for the kernel and supervisor phases. The runtime deadline is a
131
+ final failure boundary for stuck OS work; wake delivery and model activity
132
+ require separate evidence.
133
+
134
+ - **The official catalog pins oats.okf 6.2.0** (from 6.0.3, taking 6.1.0's
135
+ changes with it), and OATS's own workspace takes it. A knowledge change
136
+ names the agent that proposed it in Git trailers on its commit, and
137
+ `oats okf propose --apply` checks `gh` before it pushes anything,
138
+ refusing `E_GH_UNAVAILABLE` with the fix (6.1.0). New in 6.2.0: an
139
+ optional, host-only setting `settings.oats.okf.github-token-file` (in
140
+ `oats-local.yaml` only) gives every remote `git` and `gh` call of oats.okf
141
+ the token in that file, for knowledge writes from a container; with it, a
142
+ publication refuses `E_HOST_CREDENTIAL` while the host could answer GitHub
143
+ in the token's place. `oats okf setup --check --soul <soul>` says whether a
144
+ deployment is provisioned for knowledge and names each fix
145
+ ([Bringing up a deployment's knowledge store](https://github.com/oats-project/oats-okf/blob/v6.2.0/README.md#bringing-up-a-deployments-knowledge-store)).
146
+ Without `github-token-file` nothing changes, apart from the `gh` check
147
+ before a push. Three things are not yet proven in a live run: a proposal
148
+ opened through `github-token-file` on a real private repository; GitHub
149
+ refusing that write-role-only credential a direct push and a merge under
150
+ the example ruleset; and what GitHub reports for such a token, which
151
+ `setup --check` reads. A container deployment that relies on
152
+ `github-token-file` waits for that run. The generated mirror under
153
+ `mirrors/oats-okf*` is finalized from the v6.2.0 tag
154
+ ([oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.2.0/CHANGELOG.md)).
155
+
156
+ - The shared ingress probe accepts an explicitly external registry with a harmless
157
+ verified-TLS 200 control at every pinned address over HTTP/1.1 and HTTP/2. It
158
+ reports positive connectivity only, without third-party refusal or backend-log
159
+ claims. The other four service routes and signer/human authority refusal keep
160
+ their full owned-backend audit. External registry addresses must not overlap
161
+ deployment destinations; no new route or forwarding policy is added.
162
+
163
+ - Retiring homes spawned by a kernel from before `capabilityRuntime`, and
164
+ captured homes from before 0.26, now refuses with
165
+ `E_UNIDENTIFIED_INSTANCE_HOME` if their hooks cannot run and the record
166
+ does not prove no cleanup is owed. Both `--plan` (including Desktop Remove)
167
+ and apply refuse before anything is stopped, run or removed, children included.
168
+ Inspect the home, clean up external identities/memberships using the provider's
169
+ tooling, then run `oats retire <instance> --force`. Force keeps the warnings
170
+ that hooks did not run and state was not revoked; it can leave external state
171
+ active after deleting the local credential. Captured homes need positive
172
+ evidence that no capability's spawn hook ran to retire without force.
173
+ Forced self-retirement keeps the force choice in its deferred completion.
174
+
175
+ - Retire plans for a home that cannot be entered (mode 000), or an
176
+ interrupted spawn's stub without recorded hook bindings, now refuse with
177
+ the same cleanup admission as apply. This is the before-effects plan/apply
178
+ rule; a refusal returns no plan claiming that work is absent. The stub's
179
+ refusal now names missing `capabilityRuntime` and retains the `--force`
180
+ remedy. Homes lacking workspace modules alone are not newly refused:
181
+ the cleanup rule depends on their recorded hook bindings.
182
+
183
+ - Retire hooks now run in the repository Git identifies for an instance's
184
+ own worktree when its record names no `repo`. Previously that home ran no
185
+ retire hook and warned that there was no context repository. Retirement
186
+ now performs the recorded cleanup in the Git-derived context without
187
+ rewriting the instance record.
188
+
189
+ - **OATS's own copy of the engineering template moves to template-v4.0.0,
190
+ taken up whole.** The template recomposed every text, so the copy is
191
+ template-v4.0.0's text with OATS's answers and its marked adaptations
192
+ written back in. This changes the texts this workspace's own souls are
193
+ composed from, not the kernel or any package contract.
194
+ - **One agent is the default,** and every expert instance holds one seat,
195
+ named on a `Seat:` line in its task: root lead, specialist, or helper or
196
+ probe. A lead sizes the tree to the work: alone, with short-lived probes
197
+ and helpers, or with one long-lived specialist per area for a large
198
+ effort or one across several areas.
199
+ - **Skills renamed or folded in.** `oats.engineering-expert` has five
200
+ skills: `/plan-and-spec`, `/orchestrate-agents` (was `/send-a-helper`),
201
+ `/coordinate-developers` (takes in `/verify-developer-work`),
202
+ `/hand-off-and-ask` (takes in `/hand-off`, `/ask-a-person`,
203
+ `/findings-and-blocks` and `/across-people`) and `/land-on-agreement`
204
+ (takes in `/find-the-maintainer`). `oats.build` has three:
205
+ `/build-in-the-repository` (new), `/run-the-review-loop` and
206
+ `/work-the-reviews`; `/test-first`, `/diagnose-before-fixing`,
207
+ `/design-while-writing`, `/execution-strategy`, `/prove-it-works`,
208
+ `/maintain-dev-docs` and `/worktrees` are gone. `oats.developer` folds
209
+ `/understand-the-spec` into its briefing. `oats.maintainer` has
210
+ `/keep-the-lane` (from `/maintainer-intake`, `/keep-it-clean` and
211
+ `/cross-review-peer`), `/plan-and-ship-release` (from `/plan-release`
212
+ and `/ship-release`), `/pr-review`, `/direction-gate` and
213
+ `/launch-work`; it still drops `/support-maintainer`. `oats.landing-rules`
214
+ gains `/landing-rules-detail` and `/wait-and-retire`, which every
215
+ coordinating soul now has. The souls' own texts name the new skills.
216
+ - **A lane maintainer's green light.** In the template it is an option a
217
+ lane chooses. Every OATS lane asks for it: the maintainer's read of a PR
218
+ from an effort is now its verdict at the exact head, `GREEN LIGHT`,
219
+ `RETURN` or `ESCALATE`, on direction, contracts, coherence, scope and
220
+ evidence. Each lane's agreements are as before: the PR's second reader,
221
+ the release lane's sign-off where the lane asks, and the merge where the
222
+ lane's arrangement puts it. A PR with no lead still gets the four gates.
223
+ - **Both maintainer reads look at the code and judge direction, roadmap
224
+ and product fit.** The lane maintainer's green light adds its own read
225
+ of the whole diff, from its own checkout, to the five checks: a defect
226
+ it finds there blocks, and it runs no review rounds of its own. The
227
+ release lane's sign-off keeps the four gates (direction, roadmap and
228
+ product fit; correctness over the whole diff; security; mergeability)
229
+ on every PR it signs off, at the exact head being merged, as the final
230
+ gate on main.
231
+ - **What carries to a new head.** A review carries as before, except that a
232
+ fix to a minor is read by the review bot where one runs, otherwise by a
233
+ fresh reviewer briefed with the delta, not by the round's reviewer. A `VERIFIED` note and a green light carry only
234
+ through an unchanged rebase or update; at any other head, whoever gave
235
+ one reads the delta and gives it again.
236
+ - **Every finished instance retires itself,** its children first
237
+ (`oats retire <name> --self`), and its parent checks that it is gone and
238
+ retires one still listed. A reviewer retires itself once its report is
239
+ sent: one reviewer, one report.
240
+ - **OATS keeps its lane map.** The template drops it; OATS's landing rules
241
+ still point at the pinned issue "Lane map for awebai/oats" for its lanes,
242
+ their owners and arrangements, and a lane's maintainer is found by its
243
+ `active` entry there. Maintainers keep their instance names.
244
+ - The model floor, the hosts rule and CI as the test run are stated once,
245
+ in the landing rules' house rules.
246
+
247
+ A running instance keeps the texts it was spawned with: composition is
248
+ frozen at spawn, so no running instance changes, and a new spawn takes
249
+ these. `capabilities/TEMPLATE-RELEASE` records the release and its commit.
250
+ The catalog's row for the engineering template moves to template-v4.0.0.
251
+ - **`oats.framework`'s setup expert teaches the green light as an option.**
252
+ `/set-landing-rules` offers a lane maintainer's green light per lane, off by
253
+ default: recommended for a large project (several lanes or maintainers,
254
+ several people), left out for a small personal project. Its carry rule
255
+ follows template-v4.0.0. `/adapt-to-the-organisation` and
256
+ `/design-the-roster` write no lane map: the landing rules list the lanes and
257
+ their owners, and a maintainer is found by its instance name,
258
+ `<person>-<lane>-maintainer`.
259
+
260
+ - **OATS's own copy of the engineering template moves to template-v4.0.2.**
261
+ The two patch releases fix how a lane's maintainer is found and started.
262
+ The copy takes them in, adapted to the lane map, where a lane's maintainer
263
+ is still its `active` entry. This changes the texts this workspace's own
264
+ souls are composed from, not the kernel or any package contract.
265
+ - **A refused spawn means the seat is held.** When `oats spawn` refuses a
266
+ maintainer's name because it is taken, a holder is running or stopped.
267
+ The dispatcher, the expert and the maintainer each find it and start
268
+ none under another name.
269
+ - **A new maintainer gets a name no instance has had.** The kernel accepts
270
+ a retired instance's name. So before starting one, the dispatcher and
271
+ the expert check each name of the family in turn with
272
+ `oats instance events <name>`, and the maintainer's launch-work says to
273
+ do the same. A name the roster still lists counts as used.
274
+ - **A maintainer named only on the roster is asked about first.** Such a
275
+ name may be retired or running elsewhere. The dispatcher, the expert and
276
+ the maintainer ask their person before starting another.
277
+ - **The dispatcher handles the expert's other cases too.** In another
278
+ person's lane, it asks their dispatcher, or that person. Where the
279
+ workspace has no maintainer soul, or it can't tell the lane or its
280
+ owner, it asks its person. In each case it starts none.
281
+ - **The maintainer soul's OATS review skill agrees with `pr-review`.** It
282
+ names the four gates for the release lane's sign-off as well as for a PR
283
+ with no lead, and the green light's read of the whole diff.
284
+ - **The official catalog** lists template-v4.0.2 as the engineering
285
+ template's latest release.
286
+
287
+ ## Fixed
288
+
289
+ - Canary and TCP-control cleanup checks exact-name absence, including after Docker
290
+ timeouts, and removes a container only when its per-attempt ownership label
291
+ matches. Name collisions and failed observations refuse admission without
292
+ removing another caller's container. Diagnostics distinguish confirmed leftovers
293
+ from unowned or unverified names, including collisions. The host-side helpers remain outside the
294
+ egress image build context.
295
+
296
+ - The egress ingress routine names its signer-role requirement before sending
297
+ controls when given a policy without signer. Runtime boundary controls now
298
+ share the compiler's canonical role order, including in emitted probe
299
+ programs. The packaged CLI keeps its values-withheld refusal diagnostic.
300
+
301
+ - Desktop's Remove refusal now explains when OATS cannot tell what a home's
302
+ capabilities created or cannot run their cleanup. The headline says
303
+ nothing was removed and points to Details for the kernel's cause and
304
+ remedy. It never suggests forcing an unreadable record: that case needs
305
+ the file restored. Force commands appear only in Details where the
306
+ kernel offers them. Stop keeps its existing refusal text.
307
+
308
+ - Conversation capture stops before sealed aw client-log entries, preserves
309
+ the cursor, and reports them as sealed instead of failed projections.
310
+ Command capture sets the input aside as “sealed, not readable by this recorder”.
311
+
312
+ - Capability commands routed with `--server` refuse `--invite <token>` and
313
+ `--invite=<token>` before ssh starts. Use `--invite-stdin` and a pipe instead.
314
+ - The agent-permissions setup example asks before `aw` selects another identity,
315
+ human principal or team, and leaves mail acknowledgement to the classifier.
316
+
317
+ ## Removed
318
+
319
+ - Removed the recorder's unused signature-verification helpers
320
+ `base58Decode`, `publicKeyFromDidKey`, `base64DecodeLoose`,
321
+ `verifyDidKeySignature` and `verifyTurnSig` from the `@awebai/turn-record/canonical` export.
322
+ `@awebai/turn-record` lives in this repository and is not published to npm.
323
+ An importer of a local copy must remove those imports or use a
324
+ signature-verification library. No in-repository production callers used
325
+ them. Source signatures are still preserved.
package/docs/servers.md CHANGED
@@ -576,8 +576,10 @@ The host runs the same argv, minus `--server <id>` (or `--server=<id>`;
576
576
  after a `--` the argv is the provider's and is never read), as `oats <namespace>
577
577
  <command> …` from the registered workspace directory: the kernel's
578
578
  capability dispatch finds the deployment from its working directory, so no
579
- `--dir` is added to the provider's argv. `--soul` and every other flag go
580
- through untouched. Stdin is forwarded as is and never read or logged here;
579
+ `--dir` is added to the provider's argv. `--soul` and other flags go
580
+ through untouched, except `--invite <token>` and `--invite=<token>`: routed
581
+ commands refuse both with `E_BAD_ARGS` before ssh runs. Use `--invite-stdin`
582
+ and pipe the token on stdin to avoid exposing it in process arguments. Stdin is forwarded as is and never read or logged here;
581
583
  when stdin is a terminal nothing is forwarded and the host's stdin is
582
584
  closed. The host's stdout, stderr and exit status are relayed; with
583
585
  `--json` its envelope is relayed verbatim, and when nothing comes back this
@@ -2348,5 +2348,7 @@ member repository's `souls/<name>` (`soul.yaml` + `AGENTS.md`) and run
2348
2348
 
2349
2349
  Homes left by mechanisms earlier releases removed are reported once by
2350
2350
  `oats status` and `oats doctor`: `legacy-local-agents` (a `local-agents/`
2351
- directory) and `legacy-captured-home`. Retire such instances and re-spawn the
2352
- soul from the deployment.
2351
+ directory) and `legacy-captured-home`. Follow the reported cleanup remedy,
2352
+ then re-spawn the soul from the deployment. For captured homes, inspect and
2353
+ clean up external state first; without positive proof that no spawn hook
2354
+ ran, retirement needs `oats retire <instance> --force`.
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.19** ([release notes](release-notes/v0.69.19.md)).
10
- The 0.69.19 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
9
+ The latest version is **OATS 0.69.20** ([release notes](release-notes/v0.69.20.md)).
10
+ The 0.69.20 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.19,** in the [release notes](release-notes/): it says what to do before
14
+ 0.69.20,** 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.19, in either order
24
- npm install -g @awebai/oats@0.69.19 # 1. the CLI
23
+ # 0. where the Desktop is installed: Desktop 0.69.20, in either order
24
+ npm install -g @awebai/oats@0.69.20 # 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,12 @@ 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.20](release-notes/v0.69.20.md#upgrade):** the catalog pins
221
+ oats.okf 6.2.0 and oats.framework 1.26.0. Retiring an old home whose
222
+ recorded cleanup hooks cannot run is refused; clean up its external state,
223
+ then run `oats retire --force`. Team-container deployments
224
+ recreate their agent containers, and those with a local registry service set
225
+ `team.registryRoute: local`. Respawn instances to take the new texts.
220
226
  - **[0.69.19](release-notes/v0.69.19.md#upgrade):** the catalog pins
221
227
  oats.aweb 1.42.1 and oats.framework 1.25.2. A retained seat that relied on
222
228
  `OATS_AWEB_URL` records its server with `aw workspace connect` and unsets the
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.25.2 # bare version → resolves through the official catalog
58
- oats.okf: v6.0.3
57
+ oats.framework: v1.26.0 # bare version → resolves through the official catalog
58
+ oats.okf: v6.2.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone
@@ -425,15 +425,21 @@ member soul that is the expert in that capability (`oats-okf-expert`,
425
425
  **OATS's coordination is a member copy of the engineering template.** The
426
426
  `oats` repository keeps its own copy of
427
427
  [oats-project/oats-engineering-coordination](https://github.com/oats-project/oats-engineering-coordination)
428
- at template-v3.1.3, adapted to OATS: `oats.engineering-expert`,
428
+ at template-v4.0.2, adapted to OATS: `oats.engineering-expert`,
429
429
  `oats.developer`, `oats.build`, `oats.code-review`, `oats.maintainer`,
430
430
  `oats.landing-rules` and `oats.dispatcher`, in `capabilities/oats-<name>/`.
431
431
  `capabilities/TEMPLATE-RELEASE` records the release, its commit and what was copied, and
432
- `capabilities/THIRD-PARTY-NOTICES.md` the sources four of the build skills and the
433
- developer's quality floor adapt. `oats.build` holds the build skills, and every soul that
432
+ `capabilities/THIRD-PARTY-NOTICES.md` the sources that three rules of the build skill and
433
+ the quality floor adapt. `oats.build` holds the build skills, and every soul that
434
434
  builds composes it: the developers, and the engineering experts that build their own
435
- specs. The framework's own souls compose them `from: here`, never the `oats.engineering` package's copies; the
436
- landing rules point at the lane map, which stays the one home of OATS's lanes.
435
+ specs. The framework's own souls compose them `from: here`, never the `oats.engineering` package's copies. The
436
+ template drops the lane map, but OATS keeps it: the landing rules point at the lane map,
437
+ which stays the one home of OATS's lanes and their owners, and a lane's maintainer is
438
+ found by its entry there. Every lane asks for its maintainer's green light on every PR of
439
+ an effort, before its second reader and the release lane's sign-off where the lane asks.
440
+ Both maintainer reads look at the code and judge direction, roadmap and product fit: the
441
+ lane maintainer by the five checks of its green light plus its own read of the whole
442
+ diff, the release lane by the four gates, at the exact head being merged.
437
443
  The reviewer is the template's `code-reviewer` soul, in `souls/`. The workspace
438
444
  doesn't pin the `oats.engineering` package, frozen at v1.18.0
439
445
  ([official catalog](official-catalog.md#coordination-templates)), so each of