@awebai/oats 0.69.10 → 0.69.11

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.
@@ -419,8 +419,8 @@ the workspace's slot default. Teams compose nothing, so a soul's composition
419
419
  is the same for every person and machine. A resolved capability whose manifest says `layer: X` fills slot X; two for one slot are
420
420
  `E_SLOT_CONFLICT`. Provider settings start from the manifest's own declared
421
421
  defaults (`settings.<key>.default`, the lowest layer), then take the workspace's
422
- `messaging` payload for the messaging slot, the soul's
423
- slot payload, `oats-local.yaml` `settings.<cap>`, and `oats spawn --provider`,
422
+ `messaging` payload for the messaging slot or its `tasks` payload for the tasks
423
+ slot, the soul's slot payload, `oats-local.yaml` `settings.<cap>`, and `oats spawn --provider`,
424
424
  deep-merged in that order. There are no agent types, no `global`, no
425
425
  per-deployment activation or exclusion maps.
426
426
 
@@ -805,6 +805,25 @@ resolver accepts it only from the deployment's own `oats-local.yaml`
805
805
  Declare it for any key whose value points at something a committed file must
806
806
  never be able to choose.
807
807
 
808
+ The mirror is `committedOnly: true`: a key that must be the same for every
809
+ deployment of the workspace, such as which shared list a tasks provider uses.
810
+ The resolver accepts it only from committed, reviewed files, and refuses it in
811
+ the deployment's `oats-local.yaml` `settings.<capability>` and in a
812
+ `--provider` flag (`E_WORKSPACE_SCHEMA`, reason `committed-only-key`). It is a
813
+ refusal, not a warning, and the key's presence is enough, even with the
814
+ committed value. Where it may be set follows the capability's layer: for a
815
+ messaging or tasks capability, `oats-workspace.yaml` under `messaging:` or
816
+ `tasks:`, or a soul's slot payload; for a knowledge capability, a soul's
817
+ `knowledge:` payload; for a capability with no layer, only its manifest
818
+ default. The refusal names the key, where it was set (`details.layer` `host` or
819
+ `spawn`, `details.at`), where it may be set (`details.allowed`) and the fix. A
820
+ key marked both `hostOnly` and `committedOnly` could be set by nothing but its
821
+ default, so the resolver refuses the manifest (`E_PACKAGE_MANIFEST` for a
822
+ package capability, `E_CAPABILITY_MISSING` for a member one, `details.why`
823
+ `settings-flag-conflict`). The kernel does not validate manifests against the
824
+ schema, so a kernel without the feature `settings-committed-only` ignores the
825
+ flag and merges the key from any layer.
826
+
808
827
  A hook may return only names in its manifest's exact `environment` declaration.
809
828
  For package capabilities that declaration is part of the integrity-locked tree
810
829
  the workspace declared; for member capabilities it is part of what membership
@@ -335,8 +335,16 @@
335
335
  "hostOnly": {
336
336
  "type": "boolean",
337
337
  "description": "When true, this key is a host fact (a custody path, a state directory): the resolver accepts it only from the deployment's oats-local.yaml settings.<capability> and refuses it in the workspace file, a soul's slot payload and --provider flags (E_WORKSPACE_SCHEMA reason host-only-key). Decision 27."
338
+ },
339
+ "committedOnly": {
340
+ "type": "boolean",
341
+ "description": "When true, this key must be the same for every deployment (the mirror of hostOnly): the resolver accepts it only from committed, reviewed files (the manifest default, oats-workspace.yaml's messaging: or tasks: payload for a capability of that slot, a soul's slot payload) and refuses it in oats-local.yaml settings.<capability> and --provider flags (E_WORKSPACE_SCHEMA reason committed-only-key). Never true together with hostOnly. Kernels without the settings-committed-only feature ignore it."
338
342
  }
339
343
  },
344
+ "not": {
345
+ "required": ["hostOnly", "committedOnly"],
346
+ "properties": { "hostOnly": { "const": true }, "committedOnly": { "const": true } }
347
+ },
340
348
  "additionalProperties": false
341
349
  }
342
350
  },
@@ -169,6 +169,8 @@ see the [official catalog](official-catalog.md) for current pins.
169
169
  | `wake-hold` | a scheduled wake sends no key while the home has a live `permission`, `question` or unknown-reason claim, or a claims read that can't be trusted: the run is `skipped`, `reason: "waiting-on-you"`, `pending: true`, with `held` ([A held wake](schedules.md#a-held-wake)); the `wake-held` event ([the event kinds](#events)); `wakeHold` on every successful `session inspect --json` ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)), from the hook answer `dialogClaims` ([Commands and hooks](capabilities.md#commands-and-hooks)). Gate on the feature, then on `wakeHold`: the feature says this kernel holds, `wakeHold` whether this home's dialogs become claims, and `unknown` is not covered | |
170
170
  | `lifecycle-claim-start` | every `oats session start` and `oats session restart`, and a scheduled start, holds the home's lifecycle claim for the whole start (#1602), as `details.action: "start"`: a retire, a stop apply or an upgrade apply that arrives while it runs is refused `E_LIFECYCLE_BUSY` with `details.action: "start"`; the start or restart is refused `E_INSTANCE_RETIRING` beside a retire and `E_LIFECYCLE_BUSY` (with `details.holder` and `details.action`) beside a stop or an upgrade, before any effect; two starts still answer `E_SESSION_START_BUSY` ([Commands that meet on one home](#lifecycle-pairs)). A restart holds one claim across its stop and its launch. A kernel without it takes no claim for these, and reads a `start` holder as a retire | |
171
171
  | `spawn-attribution` | the kernel validates who spawned an instance: `spawnedBy` (`{instance, home}` or `null`) in `instance.json`, on the `spawned` event and on `oats status --json` rows and remote rows, and `OATS_SPAWNER_HOME` for spawn hooks ([Spawned by](#spawned-by)); `attributedHuman` on `oats status --json` rows and on remote rows ([Attributed human](#attributed-human)). Absent: no `spawnedBy` and no `attributedHuman`, and a capability must not read a missing `OATS_SPAWNER_HOME` as a person's spawn | |
172
+ | `workspace-tasks-payload` | oats-workspace.yaml may carry a top-level `tasks:` payload, merged for the capability that fills the tasks slot exactly as `messaging:` is for the messaging one; its leaves' `settingsOrigins` are `{kind: "workspace", at: "oats-workspace.yaml#/tasks"}` ([Provider payloads have three homes](workspaces.md#provider-payloads-have-three-homes)). A kernel without it refuses a workspace file that carries `tasks:` (unknown property) | |
173
+ | `settings-committed-only` | a manifest `settings.<key>.committedOnly: true` is enforced: that key in oats-local.yaml `settings.<cap>` or a `--provider <cap>` flag is refused `E_WORKSPACE_SCHEMA` reason `committed-only-key`, with `details.layer`, `details.at` and `details.allowed` ([Commands and hooks](capabilities.md#commands-and-hooks)). A kernel without it ignores the flag and merges the key | |
172
174
 
173
175
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
174
176
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -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: v5.7.0
44
- oats.aweb: v1.34.0
44
+ oats.aweb: v1.35.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -156,6 +156,12 @@ Building an integration is implementing a contract. The framework's
156
156
  `oats-local.yaml` `settings.<cap>` and refuses it elsewhere
157
157
  (`E_WORKSPACE_SCHEMA`, reason `host-only-key`). The provider cannot enforce
158
158
  this itself: it receives one merged payload without provenance.
159
+ - A setting every deployment must share (which shared task list to use) is
160
+ declared `committedOnly: true`, the mirror: the resolver refuses it from
161
+ `oats-local.yaml` `settings.<cap>` and `--provider` (`E_WORKSPACE_SCHEMA`,
162
+ reason `committed-only-key`), so it comes only from the workspace's
163
+ `messaging:` or `tasks:`, a soul's slot payload or the manifest default.
164
+ Kernels without the feature `settings-committed-only` ignore the flag.
159
165
  - A slot provider that declares `binding` answers `oats readiness` through
160
166
  its `binding.check` command
161
167
  ([capabilities.md](capabilities.md#readiness-check-bindingcheck)).
@@ -52,6 +52,10 @@
52
52
  "type": "object",
53
53
  "description": "Opaque provider payload consumed by the messaging core capability. A team's provider id is teams.<label>.team."
54
54
  },
55
+ "tasks": {
56
+ "type": "object",
57
+ "description": "Opaque provider payload consumed by the capability that fills the tasks slot, merged at the same layer as messaging: (above the manifest's defaults, below a soul's tasks: payload). Kernels before the workspace-tasks-payload feature refuse this key."
58
+ },
55
59
  "external": {
56
60
  "type": "array",
57
61
  "items": { "$ref": "#/$defs/external" },
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.20.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert`, `oats-setup-expert` |
12
+ | `oats.framework` | `oats-framework/v1.21.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert`, `oats-setup-expert` |
13
13
  | `oats.okf` | `v5.7.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.34.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
14
+ | `oats.aweb` | `v1.35.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
15
  | `oats.engineering` | `v1.18.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.1.0` | `oats.cloning` | `cloner` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.7.0`, `5.7.0`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.7.0` or `oats-framework/v1.20.0`) and the payload path. An id
54
+ convention (`v5.7.0` or `oats-framework/v1.21.0`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,9 +74,9 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.20.0
77
+ oats.framework: v1.21.0
78
78
  oats.okf: v5.7.0
79
- oats.aweb: v1.34.0
79
+ oats.aweb: v1.35.0
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
134
134
  ## `oats package add | remove`
135
135
 
136
136
  ```bash
137
- oats package add oats.aweb v1.34.0 # a catalog version
137
+ oats package add oats.aweb v1.35.0 # a catalog version
138
138
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
139
139
  oats package remove acme.tools
140
140
  ```
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.7.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.20.0", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.21.0", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.20.0`
362
- resolves to tag `oats-framework/v1.20.0`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.21.0`
362
+ resolves to tag `oats-framework/v1.21.0`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,107 @@
1
+ # OATS 0.69.11
2
+
3
+ 0.69.11 lets a workspace give the tasks provider one shared setting in
4
+ `oats-workspace.yaml` (`tasks:`), and lets a capability mark a setting
5
+ `committedOnly`, so no deployment can override it locally. It moves the official
6
+ catalog to `oats.framework` 1.21.0 (`/oats-host-delivery` installs the pi
7
+ extension without its bundled skills, and `/oats-upgrade` covers a first Desktop
8
+ install) and `oats.aweb` 1.35.0 (`oats.aweb-tasks` gains a shared `team`
9
+ setting and a readiness check, and pi homes get a warning while the extension
10
+ still loads its skills). Getting started takes fixes from a second round of
11
+ newcomer runs on fresh machines.
12
+
13
+ ## Upgrade
14
+
15
+ - **Either order of the Desktop and the CLI works.**
16
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
17
+ installed the CLI first is fine too: the 0.69.11 Desktop accepts OATS CLIs
18
+ `>=0.26.0 <0.70.0`, as the 0.69.10 and 0.69.9 Desktops do.
19
+ - **Package moves:** the official catalog pins oats.framework 1.21.0 and
20
+ oats.aweb 1.35.0, with no change to their OATS floors (oats.aweb keeps aw
21
+ >=1.36.33, and is tested with 1.36.53). A deployment takes each by raising
22
+ its own pin (`/oats-package-pins`), then `oats sync`. Running instances keep
23
+ the modules they were spawned with: new spawns get the new ones, and a
24
+ stopped home moves with `oats instance upgrade`.
25
+ - **A pi home may warn `pi-extension-skills-loaded`** (oats.aweb 1.35.0) when
26
+ its pi folder's `settings.json` lists `npm:@awebai/pi` without
27
+ `"skills": []`. The warning names the file and the one entry to change; the
28
+ extension still loads, and `pi install` and `pi update` keep the filter.
29
+ - **Where `oats.aweb-tasks` is composed, readiness gains one provider item.**
30
+ With no `team` setting it passes and reads nothing.
31
+ - **Since oats.aweb 1.33.2 (pinned from 0.69.10 on), spawn and readiness warn
32
+ `aw-newer-than-tested`** when the aw on PATH is newer than the aw the
33
+ provider is tested with and the home's team root names a service other than
34
+ the aweb Cloud: a server on an older aweb may refuse it. The fix it names
35
+ first is upgrading that server's aweb. Cloud homes never warn, and it is
36
+ never a refusal. (0.69.10's notes left this out.)
37
+ - **A workspace sets `tasks:` only once every deployment that reads it runs a
38
+ kernel listing `workspace-tasks-payload`** (`oats version --json`
39
+ features). An older kernel refuses the whole file, so every resolve and spawn
40
+ on that deployment stops. A file without `tasks:` resolves exactly as before.
41
+ - **A capability's `committedOnly` setting is enforced only by kernels with
42
+ `settings-committed-only`.** An older kernel ignores the flag and still merges
43
+ the key from oats-local.yaml and `--provider`. A provider that relies on it
44
+ sets its kernel range to this release or later.
45
+
46
+ ## Added
47
+
48
+ - **A workspace `tasks:` payload** (feature `workspace-tasks-payload`). The
49
+ workspace file may carry a top-level `tasks:`, an opaque payload for whichever
50
+ capability fills the tasks slot, merged at the same layer as `messaging:`:
51
+ the manifest's defaults, then the workspace's `messaging:` or `tasks:`, the
52
+ soul's slot payload, oats-local.yaml `settings.<cap>`, then `--provider`. Its
53
+ leaves' origin is `{kind: "workspace", at: "oats-workspace.yaml#/tasks"}`. A
54
+ `hostOnly` key or `byTeam` in it is refused, as in `messaging:`. There is no
55
+ workspace `knowledge:` payload
56
+ ([Provider payloads have three homes](../workspaces.md#provider-payloads-have-three-homes),
57
+ [awebai/oats#1719](https://github.com/awebai/oats/issues/1719)).
58
+ - **`committedOnly` settings** (feature `settings-committed-only`), the mirror
59
+ of `hostOnly`. A manifest's `settings.<key>.committedOnly: true` makes the
60
+ resolver refuse that key in oats-local.yaml `settings.<cap>` and in
61
+ `--provider <cap>` with `E_WORKSPACE_SCHEMA`, reason `committed-only-key`. The
62
+ key's presence is refused, even with the committed value. The refusal names
63
+ the key, where it was set, where it may be set (`details.allowed`) and the
64
+ fix. For a messaging or tasks capability, that is oats-workspace.yaml under
65
+ `messaging:` or `tasks:`, or a soul's slot payload. A key marked both
66
+ `hostOnly` and `committedOnly` is a manifest fault, `details.why`
67
+ `settings-flag-conflict`
68
+ ([Commands and hooks](../capabilities.md#commands-and-hooks)).
69
+ - **An unknown top-level key in oats-workspace.yaml says the workspace may be
70
+ newer than the kernel.** Beside "unknown property", the problem adds "if this
71
+ is not a typo, the workspace uses a feature newer than this kernel (OATS
72
+ <version>): upgrade OATS", with reason `unknown-root-key`. Nested unknown keys
73
+ are unchanged.
74
+
75
+ ## Changed
76
+
77
+ - **`oats.framework` 1.21.0 ships two setup steps.** `oats.setup` 2.12.0's `/oats-host-delivery` gains the pi step of channel delivery: install `@awebai/pi`, then set its entry in the pi folder's `settings.json` to `{"source": "npm:@awebai/pi", "skills": []}`, so pi loads the extension without the skills it bundles (#1722). Its `/oats-upgrade` now covers a first Desktop install: on a host without the Desktop it asks whether the person wants it, and installs that release's Desktop (#1724). No command they name needs a newer OATS than `oats.setup` already admits ([awebai/oats#1665](https://github.com/awebai/oats/issues/1665)).
78
+ - **`oats.aweb` 1.35.0: one tasks team for every deployment; pi without its
79
+ bundled skills.** `oats.aweb-tasks` gains `team: <label>`, the aweb team
80
+ whose task list every deployment shares. It is set only in the workspace's
81
+ or a soul's `tasks:` payload, and marked `committedOnly`. Its new readiness
82
+ check refuses a home that has not joined the team, naming
83
+ `oats aweb join --labels <label>` or `tasks: none`. Both pi `install` texts
84
+ install `@awebai/pi` with `"skills": []`, and readiness warns
85
+ `pi-extension-skills-loaded` where it still loads them. A joined team that has
86
+ become the default is kept, with a warning, until the home is respawned
87
+ ([awebai/oats-aweb#188](https://github.com/awebai/oats-aweb/pull/188)-[#191](https://github.com/awebai/oats-aweb/pull/191)).
88
+ - **Getting started: the steward's global address waits for a release that
89
+ carries its route.** The skill named oats.aweb 1.35.0 as the first release
90
+ with the resident root route, but 1.35.0 ships without it
91
+ ([awebai/oats-aweb#147](https://github.com/awebai/oats-aweb/pull/147) is not
92
+ merged). It now names no version and always takes the fallback, a local team
93
+ identity, until a release carries the route. That was already the outcome on
94
+ 1.35.0, because the plan fell back; only the stated version changes.
95
+ - **Getting started: fixes from a second round of newcomer runs on fresh machines.** In `oats-getting-started`:
96
+ - **The whole file:** its description and its first line tell the agent to download it whole with `curl -fsSL` and follow it as written; a summary of it, from a web fetch that summarises, is not the procedure.
97
+ - **One change per command:** each change step 1's yes named runs as its own command, never batched with others, so a permission check that reads the conversation sees it by name. A refused command is never split into pieces or re-run in parts, `sudo` included: the agent asks the person once, naming the change, and retries once on their yes.
98
+ - **The time budget:** the setup takes a few minutes and seconds of the person's time. The agent waits about a minute for the Desktop's background download once the CLI is installed; when it hasn't verified by then, it goes on without the Desktop and records that in the hand-over; the person can install it later with the setup expert, through `/oats-upgrade`. `/oats-upgrade` (oats.setup) now covers that first install: on a host without the Desktop it asks whether the person wants it, and its Desktop step installs that release's Desktop.
99
+ - **A terminal window on Linux** that `systemd-run --user` can't open (no user session bus) is started directly and detached (`setsid -f xdg-terminal-exec` or `setsid -f x-terminal-emulator`, with the display variables the agent already has, never guessed) before the person is given a command to type.
100
+ - **GitHub:** the skill always checks the login, even right after it installed `gh`, before starting a device login.
101
+ - **A monorepo host:** step 1's one yes names the two setup files pushed straight to its default branch (which runs its automatic checks or deploys), and step 7 pushes them without asking again. A repository others can push to, a protected default branch or a refused push takes a pull request instead, and the hand-over records the skeleton as pushed or merged.
102
+ - **The hand-off** names no versions, package sources or internal flags or codes, and the setup expert, when named as the Desktop lists it, only by its display form; anything the person may want later goes in the hand-over file.
103
+ - **pi's skills filter** matches `npm:@awebai/pi` alone or with a version, never another `@awebai/pi-…` package. The skill now says that Claude's aweb channel plugin still carries one skill of its own until aweb ships it without one, a known gap ([awebai/oats#1665](https://github.com/awebai/oats/issues/1665)).
104
+
105
+ ## Documentation
106
+
107
+ - **`/oats-host-delivery` installs the pi extension without its skills.** `oats.framework`'s host-delivery skill gains the pi step of channel delivery: the setup expert runs `pi install npm:@awebai/pi`, then makes the extension's entry in the pi folder's `settings.json` `{"source": "npm:@awebai/pi", "skills": []}`, so pi loads the extension and none of the skills `@awebai/pi` bundles. A home gets its skills through its OATS capabilities only. The filter is interim, until aweb publishes the extension without skills; oats.aweb's readiness warns `pi-extension-skills-loaded` while it is missing.
@@ -187,7 +187,8 @@ For current settings and the respawn/cleanup sequence, see [knowledge.md](knowle
187
187
  digest. `oats status` compares these with the workspace's current state and
188
188
  shows `moved` / `missing` per module (drift is shown, not prevented).
189
189
  - `providers.<cap>`: the merged provider payload the capability was bound with
190
- (soul ⊕ machine settings ⊕ `--provider`), so a later inspection can tell
190
+ (manifest defaults ⊕ the workspace's `messaging:` or `tasks:` ⊕ soul ⊕
191
+ machine settings ⊕ `--provider`), so a later inspection can tell
191
192
  which instance holds a retained seat or a one-off state root. `spawn
192
193
  --preview` shows the same map before anything exists, as `settings.<cap>`,
193
194
  beside `providers` (the `--provider` flags as given).
package/docs/upgrading.md CHANGED
@@ -6,11 +6,11 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.10** ([release notes](release-notes/v0.69.10.md)).
10
- The 0.69.10 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.11** ([release notes](release-notes/v0.69.11.md)).
10
+ The 0.69.11 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
11
11
 
12
12
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.69.10,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.11,** in the [release notes](release-notes/): it says what to do before
14
14
  the CLI changes, and what else must change with it (the Desktop, another
15
15
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
16
  names the releases that ask for more than the steps below. `oats version`
@@ -19,8 +19,8 @@ prints the version you have.
19
19
  Then, on each host:
20
20
 
21
21
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.69.10 first
23
- npm install -g @awebai/oats@0.69.10 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.11 first
23
+ npm install -g @awebai/oats@0.69.11 # 1. the CLI
24
24
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
25
  oats doctor # 3. in the same deployment
26
26
  ```
@@ -202,6 +202,11 @@ of the Desktop and the CLI, and an optional package pin. A change a script
202
202
  must follow is in its release's Upgrade section whether or not it is listed
203
203
  here.
204
204
 
205
+ - **[0.69.11](release-notes/v0.69.11.md#upgrade):** the catalog pins
206
+ oats.framework 1.21.0 and oats.aweb 1.35.0. Upgrade every deployment of a
207
+ workspace before its shared `oats-workspace.yaml` sets `tasks:` (an older
208
+ kernel refuses the file). A pi home may warn `pi-extension-skills-loaded`
209
+ until its pi extension entry carries `"skills": []`.
205
210
  - **[0.69.10](release-notes/v0.69.10.md#upgrade):** the catalog pins
206
211
  oats.framework 1.20.0 and oats.aweb 1.34.0. With oats.aweb 1.34.0, a
207
212
  deployment that uses aweb tasks composes `oats.aweb-tasks`. Upgrade every
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.20.0 # bare version → resolves through the official catalog
57
+ oats.framework: v1.21.0 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.7.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
 
@@ -78,6 +78,8 @@ stores: # knowledge stores, declared once
78
78
 
79
79
  messaging: # an opaque provider payload for the messaging slot
80
80
  private: per-human
81
+ tasks: # the same, for whichever capability fills the tasks slot
82
+ team: engineering # (ignored while the slot is empty, as here unless a soul fills it)
81
83
 
82
84
  external: # souls borrowed from NON-members; revision REQUIRED
83
85
  - source: git:github.com/oss-collective/experts@9c4e1f2a9c4e1f2a9c4e1f2a9c4e1f2a9c4e1f2a
@@ -625,10 +627,23 @@ Why it is shaped this way: [team model 3](design/2026-10-02-team-model-3.md).
625
627
  | A fact about this machine | `oats-local.yaml` → `settings.<cap>.<key>` (absolute paths are refused in the workspace file) | `settings.oats.okf.state-dir: /Users/ana/.oats/okf` |
626
628
  | A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` |
627
629
 
628
- The merged payload is `workspace.messaging` (messaging slot only) ⊕ soul slot
629
- payload ⊕ `local.settings[cap]` ⊕ `spawn.providers[cap]` — objects deep-merge,
630
- later wins on scalars and arrays. The provider's own `binding` contract
631
- (its readiness check) runs over the merged payload. Teams are **not** settings:
630
+ The merged payload is the manifest's setting defaults ⊕ the workspace's
631
+ `messaging:` (for the messaging-slot capability only) or `tasks:` (for the
632
+ tasks-slot capability only) ⊕ soul slot payload ⊕ `local.settings[cap]` ⊕
633
+ `spawn.providers[cap]` — objects deep-merge, later wins on scalars and arrays.
634
+ There is no workspace `knowledge:` payload. A workspace `tasks:` needs a kernel
635
+ with the feature `workspace-tasks-payload`: an older one refuses the file
636
+ (unknown property). The provider's own `binding` contract (its readiness
637
+ check) runs over the merged payload.
638
+
639
+ A capability's manifest may pin a setting to one of these layers. A key it
640
+ marks `hostOnly` comes only from `oats-local.yaml`; a key it marks
641
+ `committedOnly` never comes from `oats-local.yaml` or `--provider`: it is set
642
+ in the workspace's `messaging:` or `tasks:`, a soul's slot payload, or left at
643
+ the manifest default, so every deployment shares one value. Either one set in
644
+ the wrong layer is refused (`E_WORKSPACE_SCHEMA`, reason `host-only-key` or
645
+ `committed-only-key`), naming the key, where it was set and where it may be set
646
+ ([Commands and hooks](capabilities.md#commands-and-hooks)). Teams are **not** settings:
632
647
  they reach the provider beside them, in its environment ([Teams](#teams)).
633
648
  Where a provider keeps its own state (for oats.aweb, its identity roots) is the
634
649
  provider's concern; see its documentation.
@@ -5,6 +5,6 @@
5
5
  * (test/cli-json-contract.test.mjs). Kernel-private, not exported from `./core`. Dependency-free. */
6
6
  import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
7
7
 
8
- export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution"]);
8
+ export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only"]);
9
9
  /** The warm reader's protocol (`oats reader --stdio`, lib/reader.mjs): `readerApi` in the probe and in the reader's hello. */
10
10
  export const READER_API = 1;
package/lib/resolve.mjs CHANGED
@@ -44,8 +44,10 @@
44
44
  * everything, while a preview can say WHAT changed since the previous instance (declarations | payload | both).
45
45
  *
46
46
  * Payloads (decision 14), later wins on scalars/arrays, objects deep-merge:
47
- * workspace.messaging (messaging slot only)
47
+ * manifest defaults ⊕ workspace.<slot> (messaging and tasks slots only: WORKSPACE_PAYLOAD_SLOTS)
48
48
  * ⊕ soul.<slot> ⊕ local.settings[cap] ⊕ spawn.providers[cap]
49
+ * A manifest settings key marked hostOnly comes only from local.settings[cap]; one marked committedOnly
50
+ * never comes from local.settings[cap] or spawn.providers[cap] (#1719).
49
51
  *
50
52
  * This module shells out to nothing. Remote access is injected (`remote`, default
51
53
  * lib/remote.mjs; `remoteOptions` threaded into every call). `resolveSoul` is
@@ -65,6 +67,8 @@ import { currentRepoKey, sameRepo } from "./repo-moves.mjs";
65
67
 
66
68
  export const RESOLUTION_API = 1;
67
69
  export const SLOTS = Object.freeze(["knowledge", "messaging", "tasks"]);
70
+ /** The slots whose payload oats-workspace.yaml may carry at its root (`messaging:`, `tasks:` since #1719). */
71
+ const WORKSPACE_PAYLOAD_SLOTS = Object.freeze(["messaging", "tasks"]);
68
72
  const CONTRACT_DOC = "docs/design/2026-09-23-workspace-module-contracts.md";
69
73
 
70
74
  /* ───────────────────────────── helpers ────────────────────────────────── */
@@ -179,6 +183,34 @@ function assertNoHostOnlyKey(value, path, hostOnly, capability) {
179
183
  }
180
184
  }
181
185
 
186
+ /** Settings keys a manifest marks `committedOnly: true` (#1719): the mirror of hostOnly. */
187
+ export function committedOnlyKeys(manifest) {
188
+ const out = new Set();
189
+ const decl = isObject(manifest?.settings) ? manifest.settings : {};
190
+ for (const [key, spec] of Object.entries(decl)) if (isObject(spec) && spec.committedOnly === true) out.add(key);
191
+ return out;
192
+ }
193
+ /** Where a committedOnly key of a capability with this layer may be set: the committed payload layers the
194
+ * resolver merges for it (`at` strings, as payloadOrigins names them), and the words for the refusal. */
195
+ function committedOnlyHomes(layer, key) {
196
+ if (WORKSPACE_PAYLOAD_SLOTS.includes(layer)) {
197
+ return { allowed: [`oats-workspace.yaml#/${layer}`, `soul.yaml#/${layer}`], where: `oats-workspace.yaml under ${layer}: or a soul's ${layer}: payload`, fix: `Set it in oats-workspace.yaml under ${layer}:, or remove it` };
198
+ }
199
+ if (layer) return { allowed: [`soul.yaml#/${layer}`], where: `a soul's ${layer}: payload`, fix: `Set it in the soul's ${layer}: payload, or remove it` };
200
+ return { allowed: [`oats.json#/settings/${key.replace(/~/g, "~0").replace(/\//g, "~1")}/default`], where: "its manifest default (the capability has no layer, so no committed payload reaches it)", fix: "Remove it" };
201
+ }
202
+ /** Refuse a committedOnly key in the host or spawn layer: only committed, reviewed files may set it (#1719). */
203
+ function assertNoCommittedOnlyKey(value, { path, layer, at, committedOnly, capability, capabilityLayer }) {
204
+ if (!committedOnly.size || !isObject(value)) return;
205
+ for (const key of committedOnly) {
206
+ if (!Object.hasOwn(value, key)) continue;
207
+ const homes = committedOnlyHomes(capabilityLayer, key);
208
+ const setIn = layer === "host" ? `oats-local.yaml settings.${capability}` : `--provider ${capability}`;
209
+ throw fail("E_WORKSPACE_SCHEMA", `${path}/${key}: ${show(key)} is a committed-only setting of ${capability} (its manifest marks it committedOnly): it was set in ${setIn}, and may be set only in a committed file — ${homes.where}. ${homes.fix} from ${setIn}`,
210
+ { path: `${path}/${key}`, key, capability, reason: "committed-only-key", layer, at, allowed: homes.allowed });
211
+ }
212
+ }
213
+
182
214
  /** Canonical JSON: object keys sorted (recursively), arrays in order, no whitespace. */
183
215
  export function canonicalJson(value) {
184
216
  if (value === undefined) return "null";
@@ -737,7 +769,7 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
737
769
  seenSkills.set(s.name, s);
738
770
  }
739
771
 
740
- // Payloads (decision 14; addendum 5): manifest defaults ⊕ workspace.messaging (messaging slot) ⊕ soul.<slot>
772
+ // Payloads (decision 14; addendum 5): manifest defaults ⊕ workspace.<slot> (messaging and tasks slots) ⊕ soul.<slot>
741
773
  // ⊕ local.settings[cap] ⊕ spawn.providers[cap], each leaf's origin kept in payloadOrigins.
742
774
  const settings = isObject(local?.settings) ? local.settings : {};
743
775
  const providers = isObject(spawn.providers) ? spawn.providers : {};
@@ -767,15 +799,26 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
767
799
  // provider receives one merged payload without provenance and cannot enforce this itself.
768
800
  const hostOnly = hostOnlyKeys(m.manifest);
769
801
  const committed = (payload, path, origin) => { assertNoHostOnlyKey(payload, path, hostOnly, m.name); add(payload, origin); };
770
- // The provider's settings are base ⊕ soul ⊕ host ⊕ spawn. Teams are not settings: they reach the
802
+ // #1719: the mirror — a key marked `committedOnly` must be the same for every deployment (a shared
803
+ // task list), so the host layer and --provider are refused with it present, BEFORE the merge, for the
804
+ // same reason. Marked both, no layer but the manifest default could set it: a fault of the manifest.
805
+ const committedOnly = committedOnlyKeys(m.manifest);
806
+ for (const key of committedOnly) {
807
+ if (hostOnly.has(key)) throw fail(m.from.kind === "package" ? "E_PACKAGE_MANIFEST" : "E_CAPABILITY_MISSING", `${m.name} marks setting ${show(key)} both hostOnly and committedOnly, so no layer but its manifest default could set it — drop one of the two flags`, { capability: m.name, key, why: "settings-flag-conflict" });
808
+ }
809
+ const notCommitted = (payload, path, layer, at) => assertNoCommittedOnlyKey(payload, { path, layer, at, committedOnly, capability: m.name, capabilityLayer: m.layer });
810
+ // The provider's settings are base ⊕ workspace ⊕ soul ⊕ host ⊕ spawn. Teams are not settings: they reach the
771
811
  // provider beside them (OATS_DEFAULT_TEAM*, OATS_TEAMS).
772
- if (m.layer === "messaging" && isObject(workspace?.messaging)) {
773
- assertNoReservedKey(workspace.messaging, "/messaging");
774
- committed(workspace.messaging, "/messaging", { kind: "workspace", at: "oats-workspace.yaml#/messaging" });
812
+ if (WORKSPACE_PAYLOAD_SLOTS.includes(m.layer) && isObject(workspace?.[m.layer])) {
813
+ assertNoReservedKey(workspace[m.layer], `/${m.layer}`);
814
+ committed(workspace[m.layer], `/${m.layer}`, { kind: "workspace", at: `oats-workspace.yaml#/${m.layer}` });
775
815
  }
776
816
  if (m.layer && isObject(definition[m.layer])) { assertNoReservedKey(definition[m.layer], `/${m.layer}`); committed(definition[m.layer], `/${m.layer}`, { kind: "soul", at: `soul.yaml#/${m.layer}` }); }
777
- if (Object.hasOwn(settings, m.name) && isObject(settings[m.name])) { assertNoReservedKey(settings[m.name], `/settings/${m.name}`); add(settings[m.name], { kind: "host", at: `oats-local.yaml#/settings/${m.name}` }); } // the host layer: hostOnly keys are legal here
778
- if (Object.hasOwn(providers, m.name) && isObject(providers[m.name])) committed(providers[m.name], `/spawn/providers/${m.name}`, { kind: "spawn", at: `--provider ${m.name}` });
817
+ if (Object.hasOwn(settings, m.name) && isObject(settings[m.name])) { assertNoReservedKey(settings[m.name], `/settings/${m.name}`); notCommitted(settings[m.name], `/settings/${m.name}`, "host", `oats-local.yaml#/settings/${m.name}`); add(settings[m.name], { kind: "host", at: `oats-local.yaml#/settings/${m.name}` }); } // the host layer: hostOnly keys are legal here, committedOnly ones are not
818
+ if (Object.hasOwn(providers, m.name) && isObject(providers[m.name])) {
819
+ notCommitted(providers[m.name], `/spawn/providers/${m.name}`, "spawn", `--provider ${m.name}`);
820
+ committed(providers[m.name], `/spawn/providers/${m.name}`, { kind: "spawn", at: `--provider ${m.name}` });
821
+ }
779
822
  payloads[m.name] = mergePayload(...layers);
780
823
  origins[m.name] = payloadOrigins(sourced);
781
824
  // A value outside the manifest's `settings.<key>.values` is refused where it was set: a
package/lib/workspace.mjs CHANGED
@@ -223,7 +223,7 @@ function keyOrProblem(remote, ref, path, problems) {
223
223
  /** Schema + domain problems for an oats-workspace.yaml value. Refs are parsed with `remote`
224
224
  * (default lib/remote.mjs) so duplicate members and malformed refs are always caught. */
225
225
  export function validateWorkspace(value, { remote = defaultRemote } = {}) {
226
- const problems = validateAgainst(schemaFor("workspace"), value);
226
+ const problems = validateAgainst(schemaFor("workspace"), value).map(newerRootKeyHint);
227
227
  if (!isObject(value)) return problems;
228
228
  if (value.schemaVersion !== 2) return referenceProblems(problems, refFields(value));
229
229
  // Absolute-path refusal applies to REF/PATH fields only (L2): never to descriptions or the provider payload.
@@ -250,6 +250,7 @@ export function validateWorkspace(value, { remote = defaultRemote } = {}) {
250
250
  if (isObject(value.messaging) && Object.hasOwn(value.messaging, "byTeam")) {
251
251
  problems.push({ path: "/messaging/byTeam", reason: "removed-key", message: "messaging.byTeam was removed in 0.30: a team's provider id is teams.<label>.team (committed, shared) or oats-local.yaml teams.<label>.team (local)" });
252
252
  }
253
+ if (isObject(value.tasks)) reservedKeyProblems(value.tasks, "/tasks", problems);
253
254
  if (Array.isArray(value.external)) value.external.forEach((entry, i) => {
254
255
  if (!isObject(entry)) return;
255
256
  if (typeof entry.source === "string") {
@@ -264,6 +265,14 @@ export function validateWorkspace(value, { remote = defaultRemote } = {}) {
264
265
  sharedLabelProblems(value, problems);
265
266
  return referenceProblems(withRemovedKeys(problems, value, REMOVED_KEYS.workspace), refFields(value));
266
267
  }
268
+ /** An unknown key at the workspace file's root is most often one a newer kernel added (a slot payload, a
269
+ * new section): the problem says so, beside the schema's own "unknown property" text. Nested keys keep it
270
+ * bare, and a removed key's own message (withRemovedKeys) replaces it. */
271
+ const KERNEL = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
272
+ function newerRootKeyHint(problem) {
273
+ if (!/^\/[^/]+$/.test(problem.path) || !problem.message.startsWith("unknown property ")) return problem;
274
+ return { ...problem, reason: "unknown-root-key", message: `${problem.message} — if this is not a typo, the workspace uses a feature newer than this kernel (OATS ${KERNEL}): upgrade OATS` };
275
+ }
267
276
  /** Team model 3: every label `defaultTeam` and `souls:` name is a shared team of this same file, so an
268
277
  * unknown label is refused when the file is read, never at a spawn on someone else's machine. */
269
278
  function sharedLabelProblems(value, problems) {
@@ -8,7 +8,7 @@
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.34.0",
11
+ "ref": "v1.35.0",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -48,7 +48,7 @@
48
48
  },
49
49
  "oats.framework": {
50
50
  "url": "https://github.com/awebai/oats.git",
51
- "ref": "oats-framework/v1.20.0",
51
+ "ref": "oats-framework/v1.21.0",
52
52
  "path": "oats-package"
53
53
  }
54
54
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.69.10",
3
+ "version": "0.69.11",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -10,9 +10,16 @@ description: >-
10
10
  Desktop on it. Offers the TUI.
11
11
  Use for "get started with OATS", "set up / install / adopt OATS", "set up
12
12
  OATS for this project", "join our OATS workspace", or when someone gives
13
- you this file or its URL.
13
+ you this file or its URL. Download this file whole (`curl -fsSL
14
+ https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md`)
15
+ and follow it as written: a summary of it is not the procedure.
14
16
  ---
15
17
 
18
+ **Read this whole file, never a summary of it.** If you only have a summary
19
+ (a web fetch that summarises, say), download it whole with
20
+ `curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md`
21
+ and follow it as written.
22
+
16
23
  # Getting started with OATS
17
24
 
18
25
  You are the person's own coding agent. This skill takes them from nothing to
@@ -44,6 +51,12 @@ stop instead: the person answers nothing after step 1.
44
51
  - **Ask first, then run.** Ask everything in one round (step 1), then run the
45
52
  steps yourself and read back what each did. Touch nothing you were not
46
53
  asked to (see "Never").
54
+ - **The time budget.** The whole setup should take a few minutes, and only
55
+ seconds of the person's time: their answers, a login to approve, a secret
56
+ to type. Don't wait more than about a minute for the Desktop's background
57
+ download once the CLI is installed: if it hasn't verified by then, go on
58
+ without the Desktop and record that in the hand-over (the person can
59
+ install it later with the setup expert, through `/oats-upgrade`).
47
60
  - **Talk to a newcomer, in everyday words.** They may not know what a
48
61
  repository, Git, a terminal or a command is. Talk about their projects,
49
62
  code and folders: "your agents' shared setup" (the workspace), "the setup
@@ -72,16 +85,23 @@ stop instead: the person answers nothing after step 1.
72
85
  missing, with what it is for, Git told to use their GitHub login (`gh auth
73
86
  setup-git`, in `~/.gitconfig`), on Linux npm's per-user folder (in
74
87
  `~/.npmrc`), and, for a new workspace whose host step 6 creates, the
75
- private repository `<owner>/<repo>` on GitHub.
88
+ private repository `<owner>/<repo>` on GitHub, or, when the host is an
89
+ existing repository (a monorepo), the two setup files committed and
90
+ pushed straight to `<owner>/<repo>`'s default branch, which runs its
91
+ automatic checks or deploys if it has any (or a pull request, step 7).
76
92
  Name each change by what and where, not by kind: a permission check that
77
93
  reads the conversation lets a step through only when their yes named it.
94
+ Run each change on the list as its own command, never batched with other
95
+ changes, so that check sees it by the name their yes gave it (a fenced
96
+ block below that makes one change on the list counts as one).
78
97
  Never run `sudo` for something that was not on that list, even where no
79
98
  password is asked; if they say no to a system package, tell them what will
80
99
  not work without it.
81
100
  - **When your harness's permission check stops a step on the list** and
82
101
  asks the person to approve, tell them it is one of the changes they said
83
102
  yes to. If it refuses the step outright, never run it another way
84
- (another shell, a script, a window you open): ask the person once, naming
103
+ (another shell, a script, a window you open), and never split it into
104
+ pieces or re-run its parts, `sudo` included: ask the person once, naming
85
105
  the change, whether you may make it, and try again once on their yes.
86
106
  Still refused: tell them in one sentence which change is missing and what
87
107
  won't work without it, and go on where you can. Never ask them to type a
@@ -111,7 +131,14 @@ stop instead: the person answers nothing after step 1.
111
131
  - **Linux:** `systemd-run --user --collect --quiet -p KillMode=process -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY xdg-terminal-exec sh "F"`,
112
132
  or `x-terminal-emulator -e sh "F"` in place of `xdg-terminal-exec` where
113
133
  only that exists. Through `systemd-run` the window gets their desktop
114
- session's environment, not yours.
134
+ session's environment, not yours. If `systemd-run` fails (for example
135
+ "Failed to connect to bus", when there is no user session bus), start
136
+ the terminal directly, detached, before you give them a command to type:
137
+ `setsid -f xdg-terminal-exec sh "F" </dev/null >/dev/null 2>&1`, or
138
+ `setsid -f x-terminal-emulator -e sh "F" </dev/null >/dev/null 2>&1`.
139
+ It uses the `DISPLAY`, `WAYLAND_DISPLAY`, `XAUTHORITY` and
140
+ `XDG_RUNTIME_DIR` your environment already has; when they are unset,
141
+ don't guess them: take "When no window opens".
115
142
 
116
143
  Tell them what to type there, and ask whether the window opened (a
117
144
  command that started is no proof of one). Check the result with a
@@ -369,7 +396,9 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g;
369
396
 
370
397
  ## 3. Log in to GitHub
371
398
 
372
- Check first:
399
+ Always run this check, even when step 2 just installed gh (an existing gh
400
+ config or `GH_TOKEN` may already log it in), and start the device login
401
+ below only if it says gh is not logged in.
373
402
 
374
403
  ```bash
375
404
  gh auth status
@@ -456,7 +485,7 @@ installed CLI's catalog:
456
485
  node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
457
486
  ```
458
487
 
459
- It prints the two refs, for example `oats-framework/v1.20.0 v1.34.0`. If the
488
+ It prints the two refs, for example `oats-framework/v1.21.0 v1.35.0`. If the
460
489
  framework's version (after the `/`) is below `1.19.0`, or with aweb
461
490
  `oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
462
491
  skill: stop, and tell the person to wait for the next OATS
@@ -466,12 +495,16 @@ release. Never write a setup soul into the workspace in its place.
466
495
  wakes an agent when mail arrives (skip this without messaging): Claude
467
496
  `claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
468
497
  pi `pi install npm:@awebai/pi`, then its entry in pi's `settings.json` set
469
- to load none of the skills it bundles (OATS puts no machine-wide skills on
470
- a computer; each agent gets its own); Codex nothing (the setup expert sets
471
- up its wake). The pi entry, which prints it so you can check `"skills":[]`:
498
+ to load none of the skills it bundles (pi's extension is installed without
499
+ its skills, so it puts none on the computer; each agent gets its own);
500
+ Codex nothing (the setup expert sets up its wake). Claude's aweb channel
501
+ plugin still carries one skill of its own, until aweb ships it without
502
+ (a known gap). The pi entry, which matches `npm:@awebai/pi` alone or with
503
+ `@` and a version, never another `@awebai/pi-…` package, and prints it so
504
+ you can check `"skills":[]`:
472
505
 
473
506
  ```bash
474
- node -e 'const fs=require("fs"),path=require("path"),os=require("os");const f=path.join(process.env.PI_CODING_AGENT_DIR||path.join(os.homedir(),".pi","agent"),"settings.json");const s=JSON.parse(fs.readFileSync(f,"utf8"));const ours=(e)=>(typeof e==="string"?e:e&&e.source||"").startsWith("npm:@awebai/pi");s.packages=(s.packages||[]).map((e)=>ours(e)?{...(typeof e==="object"?e:{}),source:typeof e==="string"?e:e.source,skills:[]}:e);fs.writeFileSync(f,JSON.stringify(s,null,2)+"\n");console.log(JSON.stringify(s.packages.filter(ours)))'
507
+ node -e 'const fs=require("fs"),path=require("path"),os=require("os");const f=path.join(process.env.PI_CODING_AGENT_DIR||path.join(os.homedir(),".pi","agent"),"settings.json");const s=JSON.parse(fs.readFileSync(f,"utf8"));const ours=(e)=>/^npm:@awebai\/pi(@|$)/.test(typeof e==="string"?e:e&&e.source||"");s.packages=(s.packages||[]).map((e)=>ours(e)?{...(typeof e==="object"?e:{}),source:typeof e==="string"?e:e.source,skills:[]}:e);fs.writeFileSync(f,JSON.stringify(s,null,2)+"\n");console.log(JSON.stringify(s.packages.filter(ours)))'
475
508
  ```
476
509
 
477
510
  ```bash
@@ -481,8 +514,8 @@ npm install -g @awebai/aw && aw version
481
514
  `aw` must be 1.36.33 or later.
482
515
 
483
516
  **Then the Desktop. Every step verifies before it installs.** Wait for step
484
- 3's download, then read its log. Each run waits up to a minute; run it
485
- again, up to five times, while the log has no `DONE` line:
517
+ 3's download, then read its log. Run this once: it waits up to a minute
518
+ for a `DONE` line ("How to work", the time budget):
486
519
 
487
520
  ```bash
488
521
  for i in $(seq 60); do grep -qx DONE "<W>.log" && break; sleep 1; done; tail -n 5 "<W>.log"
@@ -490,7 +523,9 @@ for i in $(seq 60); do grep -qx DONE "<W>.log" && break; sleep 1; done; tail -n
490
523
 
491
524
  Install the Desktop only when the log has a `VERIFIED` line. If a download or
492
525
  a check failed (its assets can lag the npm package), or it still has not
493
- finished, skip the Desktop and say so. Never skip a check to
526
+ finished, go on without the Desktop, say so, and record it in the
527
+ hand-over: the person can install it later with the setup expert, through
528
+ `/oats-upgrade`. Never skip a check to
494
529
  make it install, and never install or open this download before its
495
530
  attestation has passed. A Desktop installed before this run stays as it is.
496
531
 
@@ -682,8 +717,8 @@ name: acme
682
717
  members:
683
718
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
684
719
  packages:
685
- oats.framework: v1.20.0 # the installed CLI's catalog versions (below)
686
- oats.aweb: v1.34.0 # messaging: agent identities, mail and chat
720
+ oats.framework: v1.21.0 # the installed CLI's catalog versions (below)
721
+ oats.aweb: v1.35.0 # messaging: agent identities, mail and chat
687
722
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
688
723
  defaults:
689
724
  capabilities:
@@ -720,10 +755,13 @@ workspace: git:github.com/acme/acme-oats
720
755
  **Commit and push.**
721
756
  - **A repository created in step 6:** straight to its default branch (it
722
757
  is the person's own, just created).
723
- - **A monorepo:** show the person the two files first, and commit to its
724
- default branch only on their yes. If the push is refused (a protected
725
- branch, say), push a branch, open a pull request, tell them, and stop until
726
- it is merged.
758
+ - **A monorepo:** push the commit to its default branch on step 1's yes,
759
+ which named it, without asking again; show the person the files only if
760
+ they ask. When others can push to the repository (`gh api
761
+ repos/<owner>/<repo>/collaborators --jq length` prints more than 1, or
762
+ fails), its default branch is protected, or the push is refused: push a
763
+ branch instead, open a pull request, tell them, and stop until it is
764
+ merged.
727
765
  - If `git config user.name` or `git config user.email` prints nothing in
728
766
  `D/<repo>`, commit with the name step 1's yes covered:
729
767
  `-c user.name="<their name>" -c user.email="<their noreply address>"`,
@@ -889,8 +927,10 @@ with no API key and nothing for the person to type. Without messaging, skip
889
927
  this. It needs all of these; when one fails, take the fallback below:
890
928
  - a new workspace: a root that joined by invite (items 3 and 4) does not own
891
929
  the namespace, so aweb would refuse the create;
892
- - `oats.aweb` 1.35.0 or later: the `oats.aweb` row of the
893
- `oats inspect` you read above, `result.capabilities[].version`;
930
+ - an `oats.aweb` release that carries the root route
931
+ ([awebai/oats-aweb#147](https://github.com/awebai/oats-aweb/pull/147)).
932
+ None is released yet: until one is, take the fallback below, whatever
933
+ `oats.aweb` version the `oats inspect` you read above reports;
894
934
  - aw 1.36.48 or later: `aw.version` in the check (item 1).
895
935
 
896
936
  Plan, then create, both from `D` and with no `AWEB_API_KEY`:
@@ -941,8 +981,8 @@ are cloned, knowledge tools, messaging wanted or not>
941
981
  ## Done by the getting-started skill
942
982
  - Installed: OATS <V> (oats version), OATS Desktop <V> | not installed (why)
943
983
  - GitHub: gh logged in over https as <login>; no SSH key or signing set up
944
- - New workspace only: host <owner>/<repo>, skeleton committed (pushed | in
945
- pull request <url>)
984
+ - New workspace only: host <owner>/<repo>, skeleton committed (pushed |
985
+ merged from <url>)
946
986
  - Messaging: <capability>, aw <version>, <harness> channel installed;
947
987
  team T on aweb account N, created for the workspace, not yet attached to
948
988
  the person (new workspace), or T owned by aweb account <handle>
@@ -955,6 +995,8 @@ are cloned, knowledge tools, messaging wanted or not>
955
995
  <GitHub issues in <repo> | <tracker the person named> | ticket keys
956
996
  <PREFIX>-n>, for you to connect with the person; aweb's task list stays
957
997
  empty
998
+ - For the person, later: <what they may want to know but the hand-off
999
+ message leaves out, such as a version, a skipped step and why>
958
1000
 
959
1001
  ## Left to you
960
1002
  Everything else, starting with /oats-setup-expert.
@@ -1089,8 +1131,12 @@ and say yes to it in the hand-over below.
1089
1131
  opts your whole group in to it. To use aweb's task list instead, ask the
1090
1132
  setup assistant."
1091
1133
 
1092
- Don't list homes, paths, versions or commands in this message. You are
1093
- done.
1134
+ Keep this message in plain words. Don't list homes, paths or commands, and
1135
+ name no versions (Git's, OATS's or any other), no package sources (a PPA,
1136
+ say) and no internal flags or codes (a "development-channel flag", a
1137
+ "channel-not-connected", say). When you name the setup expert as the
1138
+ Desktop lists it, use its display form, never its instance name. Anything they may want to know later goes in the hand-over file, for
1139
+ the setup expert, not in this message. You are done.
1094
1140
 
1095
1141
  ## Never
1096
1142