@awebai/oats 0.69.11 → 0.69.14

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 (72) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +176 -184
  3. package/docs/capabilities.md +4 -1
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +246 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +376 -37
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +69 -6
  11. package/docs/implementation.md +86 -29
  12. package/docs/integrations.md +9 -5
  13. package/docs/knowledge-and-learning.md +72 -0
  14. package/docs/knowledge.md +10 -3
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +42 -8
  17. package/docs/packages.md +101 -22
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.12.md +97 -0
  20. package/docs/release-notes/v0.69.13.md +767 -0
  21. package/docs/release-notes/v0.69.14.md +83 -0
  22. package/docs/schedules.md +26 -3
  23. package/docs/servers.md +181 -5
  24. package/docs/souls-and-instances.md +140 -11
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +30 -5
  27. package/docs/workspaces.md +32 -6
  28. package/lib/claim.mjs +21 -5
  29. package/lib/command-flags.mjs +238 -0
  30. package/lib/core.mjs +791 -563
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +126 -31
  33. package/lib/errors.mjs +1 -1
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/hot-reads.mjs +4 -3
  36. package/lib/instance-events.mjs +28 -6
  37. package/lib/instance-git.mjs +138 -13
  38. package/lib/instance-inspect.mjs +6 -1
  39. package/lib/instance-listing.mjs +80 -38
  40. package/lib/instance-resolution.mjs +56 -3
  41. package/lib/instance-upgrade.mjs +16 -20
  42. package/lib/launch-env-exec.sh +7 -0
  43. package/lib/launch-env.mjs +74 -0
  44. package/lib/launch-preference.mjs +19 -12
  45. package/lib/member-clone.mjs +7 -1
  46. package/lib/packages.mjs +74 -2
  47. package/lib/read-call.mjs +3 -0
  48. package/lib/reader.mjs +3 -2
  49. package/lib/refused-text.mjs +3 -2
  50. package/lib/remote.mjs +119 -27
  51. package/lib/retained-after-retire.mjs +2 -7
  52. package/lib/retire-git-forms.mjs +41 -0
  53. package/lib/retire-incomplete.mjs +96 -0
  54. package/lib/schedule.mjs +2 -1
  55. package/lib/servers.mjs +78 -23
  56. package/lib/session-resume.mjs +68 -53
  57. package/lib/session-seen.mjs +54 -5
  58. package/lib/start-env.mjs +13 -7
  59. package/lib/system-tools.mjs +1 -1
  60. package/lib/teams.mjs +11 -4
  61. package/lib/upgrade-state.mjs +13 -2
  62. package/lib/worktree.mjs +56 -7
  63. package/package-catalog.json +3 -3
  64. package/package.json +2 -1
  65. package/packages/client/instance-lifecycle.mjs +1 -1
  66. package/packages/client/lifecycle-contract.mjs +3 -1
  67. package/packages/client/session-resume-cli.mjs +2 -1
  68. package/packages/client/session-start.mjs +10 -7
  69. package/packages/client/workspace-cli.mjs +5 -1
  70. package/share/oats-login-receive +204 -0
  71. package/skills/oats-getting-started/SKILL.md +180 -49
  72. package/lib/tmux-config.mjs +0 -35
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 5.7.0** (OATS **>=0.69.2**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.8.0** (OATS **>=0.69.2**). Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
 
12
12
  | Surface | What it holds |
@@ -25,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
25
25
  ```yaml
26
26
  # oats-workspace.yaml (excerpt)
27
27
  packages:
28
- oats.okf: v5.7.0
28
+ oats.okf: v5.8.0
29
29
  defaults:
30
30
  knowledge: { oats.okf: { from: package } }
31
31
  stores:
@@ -54,7 +54,7 @@ just editing a version line. From 5.6.0 it requires OATS >=0.69.2: its
54
54
  `knowledge-harvester` and `knowledge-maintainer` souls say `background: true`,
55
55
  which an older kernel refuses. Upgrade OATS first, then the package.
56
56
 
57
- **Upgrade:** pin `oats.okf: v5.7.0` and run `oats sync`. Only new spawns get
57
+ **Upgrade:** pin `oats.okf: v5.8.0` and run `oats sync`. Only new spawns get
58
58
  the capability-owned harvest duty, skill and spawn-recorded policy. Existing
59
59
  homes keep their copied provider even after a session restart; from 5.4.0, a
60
60
  stopped 5.x home can move with `oats instance upgrade` (OATS 0.68.0 and
@@ -71,6 +71,13 @@ propose. 5.6.0 lists new harvesters and knowledge maintainers under the
71
71
  clients' Background section; existing ones do not move. 5.7.0 stops parking
72
72
  harvest PRs under `okf-needs-human` (step 4 of [the flow](#the-flow)); PRs an
73
73
  older maintainer parked are re-reviewed by the steps in okf's CHANGELOG.
74
+ 5.8.0 screens what harvest and maintenance publish (the outgoing history,
75
+ paths, blobs and text) before any push, comment or merge, and reports only
76
+ the location, line and rule; a harvest PR behind the accepted tip is
77
+ rewritten onto it for a fresh exact-head verdict, never merged on an
78
+ approximate squash. Structural validation is unchanged. A harvester or
79
+ knowledge maintainer spawned after the sync uses it; existing homes keep
80
+ their copy until respawned or upgraded.
74
81
 
75
82
  ### Bindings document
76
83
 
@@ -73,10 +73,19 @@
73
73
  "additionalProperties": {
74
74
  "oneOf": [
75
75
  { "type": "string" },
76
- { "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } }
76
+ { "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
77
+ { "type": "object", "additionalProperties": false, "required": ["fromFile"], "properties": { "fromFile": { "type": "string", "pattern": "^/[^\\u0000]*$" } } }
77
78
  ]
78
79
  },
79
- "description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops."
80
+ "allOf": [{ "properties": {
81
+ "HOME": { "not": { "type": "object", "required": ["fromFile"] } },
82
+ "PATH": { "not": { "type": "object", "required": ["fromFile"] } },
83
+ "CLAUDE_CONFIG_DIR": { "not": { "type": "object", "required": ["fromFile"] } },
84
+ "CODEX_HOME": { "not": { "type": "object", "required": ["fromFile"] } },
85
+ "PI_CODING_AGENT_DIR": { "not": { "type": "object", "required": ["fromFile"] } },
86
+ "PI_CODING_AGENT_SESSION_DIR": { "not": { "type": "object", "required": ["fromFile"] } }
87
+ } }],
88
+ "description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops. {fromFile: /absolute/path} reads a regular UTF-8 file of at most 64 KiB (source bytes including a final newline) on the execution host at every start, stripping one trailing LF or CRLF. NUL, missing, unreadable or nonregular files refuse with E_LAUNCH_ENV_MISSING. Both reference kinds are redacted and recorded only as keyed digests. fromFile is for credential values; directory selectors require a literal or fromEnv."
80
89
  },
81
90
  "model": { "type": "string", "minLength": 1, "description": "Model for this configuration's harness; overrides the soul default when this configuration is selected." },
82
91
  "yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." },
@@ -9,10 +9,10 @@ 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.21.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert`, `oats-setup-expert` |
13
- | `oats.okf` | `v5.7.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.35.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
- | `oats.engineering` | `v1.18.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
12
+ | `oats.framework` | `oats-framework/v1.23.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
13
+ | `oats.okf` | `v5.8.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.37.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
+ | `oats.engineering` | `v1.18.0` (frozen: see Coordination templates) | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.1.0` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
@@ -21,16 +21,50 @@ or workspace membership alone does not make a package official.
21
21
  | `oats.machine` | `v0.1.1` | `oats.machine-care` | `steward`, `technician` |
22
22
 
23
23
  Each package lives in its own `awebai/oats-*` repository except
24
- `oats.framework`, whose payload root is `oats-package/` here. A capability id
25
- names the package that supplies it through the catalog's aliases, so
26
- `oats.developer: { from: package }` selects `oats.engineering`. This catalog ships with
24
+ `oats.framework`, whose payload root is `oats-package/` here. A capability
25
+ written `{ from: package }` resolves through the workspace's lock, to the one
26
+ locked package whose capability list holds it: `oats.developer: { from: package }`
27
+ selects `oats.engineering` when that package is pinned and synced. Two locked
28
+ packages providing the same capability are refused with `E_PACKAGE_MISSING`,
29
+ which names both. The catalog's `capabilities` map records which official
30
+ package ships each capability (and a renamed capability's current name:
31
+ `oas.okf` is `oats.okf`); the kernel reads it only to pick a standalone
32
+ deployment's package (the one that ships `oats.core`). This catalog ships with
27
33
  the CLI: an older installed CLI keeps its own copy, and a change here rewrites
28
34
  no lock and adds nothing to an existing workspace.
29
35
 
36
+ ## Coordination templates
37
+
38
+ OATS's coordination ships as templates, not packages: one for each way of
39
+ working, each in its own repository. An installed kernel's
40
+ copy of this catalog carries this section from the next kernel release; the
41
+ onboarding skills name the engineering template directly, so they work on an
42
+ older kernel too. A template is a
43
+ repository that a setup expert copies into a workspace's own capabilities and
44
+ adapts to the organisation by the repository's `ADAPTING.md`
45
+ (`/adapt-to-the-organisation`, in `oats.framework`); nobody pins it. Template
46
+ releases are tagged `template-v<version>`. Each copied capability records the
47
+ release it came from in its description, and the copy records it as a whole in
48
+ `capabilities/TEMPLATE-RELEASE`.
49
+
50
+ | Template | Latest release | Way of working |
51
+ | --- | --- | --- |
52
+ | `oats-project/oats-engineering-coordination` | `template-v3.0.1` | Work that lands as pull requests: a dispatcher, a lead for each effort that builds a change itself or sends developers, whoever builds it iterating with a fresh reviewer each round, and a maintainer where a lane needs one. |
53
+ | `oats-project/oats-research-coordination` | `template-v2.0.0` | Work that ends in a finding or a report: a dispatcher, a research lead for each question that researches a single small angle itself or sends a researcher for each, and a verifier briefed to disprove, which checks the lead's own claims too. A report lands when the person who asked accepts it. |
54
+ | `oats-project/oats-scientific-research-coordination` | `template-v2.0.0` | Studies that end in claims a person is accountable for: a dispatcher, a study lead for each study, an analyst for each arm of a locked protocol, fresh study reviewers for the methods, an independent check, leakage and citations, and a record steward that locks protocols and keeps the study records. A claim lands when the scientist accepts it; one that leaves the group needs a check that isn't LLM judgement. |
55
+
56
+ The package `oats.engineering` is frozen at `v1.18.0`. Its entry and its four
57
+ aliases stay, so existing pins keep resolving, and its repository,
58
+ `oats-project/oats-engineering`, gets no further releases. The engineering
59
+ template that replaces it lives in its own repository, above; a workspace that
60
+ pins the package moves to it by the template's `ADAPTING.md` and the "From
61
+ v1.18.0" steps in its CHANGELOG. Open: retiring the entry and moving the
62
+ aliases, a later decision once no workspace we know of pins it.
63
+
30
64
  ## Find and use packages
31
65
 
32
66
  - A workspace pins an official package by **bare version** in its
33
- `packages:` map (`oats.okf: v5.7.0`); `oats sync` resolves it through the
67
+ `packages:` map (`oats.okf: v5.8.0`); `oats sync` resolves it through the
34
68
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
35
69
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
36
70
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -28,7 +28,11 @@ A Git repository **contains** a package at `oats-package/`:
28
28
  ```
29
29
 
30
30
  `oats-package.json` must declare `package` and `capabilities` (a list of
31
- directories relative to the package root, each holding an `oats.json`). It may
31
+ directories relative to the package root, each holding an `oats.json`). The
32
+ `package` must equal the `packages:` key the package is pinned under: a
33
+ package is locked under its own id, and its souls are named after it
34
+ (`<package>/<soul>`). `sync` refuses a pin whose manifest names another id
35
+ (`E_PACKAGE_INTEGRITY { why: "package-id" }`, see [`oats sync`](#oats-sync--the-one-command-for-the-common-path)). It may
32
36
  also declare `souls`: soul directories the package ships, see
33
37
  [Package souls](#package-souls). A
34
38
  directory entry need not equal the capability's name
@@ -44,14 +48,14 @@ whole organisation:
44
48
 
45
49
  ```yaml
46
50
  packages:
47
- oats.okf: v5.7.0 # bare version → the official catalog
51
+ oats.okf: v5.8.0 # bare version → the official catalog
48
52
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
53
  ```
50
54
 
51
- - **Bare version** (`v5.7.0`, `5.7.0`, `1.0.0-rc.1`): the id is looked up in
55
+ - **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
52
56
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
57
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.7.0` or `oats-framework/v1.21.0`) and the payload path. An id
58
+ convention (`v5.8.0` or `oats-framework/v1.23.0`) and the payload path. An id
55
59
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
60
  a package outside the catalog"). The catalog is the reviewed official list
57
61
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,9 +78,9 @@ members:
74
78
  - git:github.com/acme/agents
75
79
  - git:github.com/acme/platform
76
80
  packages:
77
- oats.framework: v1.21.0
78
- oats.okf: v5.7.0
79
- oats.aweb: v1.35.0
81
+ oats.framework: v1.23.0
82
+ oats.okf: v5.8.0
83
+ oats.aweb: v1.37.0
80
84
  teams:
81
85
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
86
  defaults:
@@ -105,7 +109,7 @@ decision recorded in the lock.
105
109
  $ oats sync
106
110
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
111
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.7.0 ✓ (@ 56dbc167)
112
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.8.0 ✓ (@ cfc595a9)
109
113
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
114
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
115
  teams platform (shared) · this deployment's: oats teams
@@ -117,12 +121,29 @@ lock oats-lock.json
117
121
 
118
122
  1. discovers the workspace over the remotes and confirms every member;
119
123
  2. resolves each `packages:` entry to a commit (`observeRemote`), reads its
120
- manifests, computes the **integrity** (content digest of the package tree)
121
- and records `url`, `path`, `version`, `commit`, `integrity`, `capabilities`;
124
+ manifests, checks that `oats-package.json` names the `packages:` key it is
125
+ pinned under, computes the **integrity** (content digest of the package
126
+ tree) and records `url`, `path`, `version`, `commit`, `integrity`,
127
+ `capabilities`. A manifest naming another package is refused before
128
+ anything is written: `E_PACKAGE_INTEGRITY { why: "package-id", id,
129
+ manifestPackage, commit }`, whose message names the line to write instead:
130
+ - a catalog version whose named package is in the catalog: `<named>: <the
131
+ same version>`;
132
+ - a catalog version whose named package is not: `<named>:
133
+ git:<the catalog entry's repo>@<the resolved tag>` (no line when the
134
+ catalog entry reads another `path` than `oats-package/`, which a `git:`
135
+ pin cannot reach);
136
+ - a `git:` pin: `<named>: <the same git: value>`.
137
+
138
+ The other way out is a version of the key's package whose manifest names
139
+ that key;
122
140
  3. for an entry already locked at the same version/source/path: the commit must
123
141
  be unchanged (else `E_PACKAGE_INTEGRITY` — "the tag moved; a version string
124
- must change when its content does") and the integrity must match
125
- (`E_PACKAGE_INTEGRITY`);
142
+ must change when its content does"), the integrity must match
143
+ (`E_PACKAGE_INTEGRITY`), and the manifest must still name the key
144
+ (`why: "package-id"`, as in step 2: a lock an older kernel wrote under
145
+ another package's id is refused at the next sync; spawns from it keep
146
+ working until then);
126
147
  4. writes `oats-lock.json` and reports the diff. Entries dropped from
127
148
  `packages:` are dropped from the lock.
128
149
 
@@ -134,7 +155,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
134
155
  ## `oats package add | remove`
135
156
 
136
157
  ```bash
137
- oats package add oats.aweb v1.35.0 # a catalog version
158
+ oats package add oats.aweb v1.37.0 # a catalog version
138
159
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
139
160
  oats package remove acme.tools
140
161
  ```
@@ -160,7 +181,7 @@ same workspace commit hold identical locks.
160
181
  "source": "catalog:oats.okf",
161
182
  "url": "https://github.com/awebai/oats-okf.git",
162
183
  "path": "oats-package",
163
- "version": "5.7.0",
184
+ "version": "5.8.0",
164
185
  "commit": "56dbc167394bbc13cc900bd8af0c64b74fecae54",
165
186
  "integrity": "sha256-…",
166
187
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
@@ -202,9 +223,12 @@ Member capabilities are trusted by membership; **a package is trusted by its
202
223
  declaration in the workspace's `packages:`**. People declare a package only
203
224
  when they trust it, so there is no second, per-version approval step. The lock is reproducibility, not approval: it pins
204
225
  the exact commit and the content integrity, a moved tag or drifted content is
205
- `E_PACKAGE_INTEGRITY`, and at spawn the lock's capability list must match what
206
- the package declares at the locked commit (`E_PACKAGE_INTEGRITY { why:
207
- "capabilities" }`).
226
+ `E_PACKAGE_INTEGRITY`, a package pinned under another package's id is
227
+ `E_PACKAGE_INTEGRITY { why: "package-id" }` at sync, and at spawn the lock's
228
+ capability list must match what the package declares at the locked commit
229
+ (`E_PACKAGE_INTEGRITY { why: "capabilities" }`) and the package tree there must
230
+ digest to the lock's `integrity`
231
+ ([The integrity check at spawn](#the-integrity-check-at-spawn)).
208
232
 
209
233
  ## Materialization from a package
210
234
 
@@ -217,6 +241,56 @@ against what the fetch reported; skills are copied to
217
241
  `packages:` and syncing affects **only new spawns**; `oats status` shows a
218
242
  running instance's package module as `moved` once the lock points elsewhere.
219
243
 
244
+ ### The integrity check at spawn
245
+
246
+ A spawn copies a package's capabilities only when the package is the content
247
+ the lock records. For each package the soul composes a capability from, the
248
+ kernel digests the package tree (the lock entry's `path`) at the lock's
249
+ `commit`, as `oats sync` does, and compares the digest with the lock's
250
+ `integrity`.
251
+
252
+ - **When.** After the soul is resolved and before the spawn writes anything:
253
+ no soul copy, no worktree, no instance home. `oats spawn --preview` makes
254
+ the same check. `oats instance upgrade` makes it for each package it moves
255
+ a module to.
256
+ - **The refusal** is `E_PACKAGE_INTEGRITY` with `details: {package, version,
257
+ commit, expected, actual}`: `expected` is the lock's `integrity`, `actual`
258
+ the digest of the tree as this computer reads it. The message names the
259
+ package, the commit and both digests. Two things produce it: a lock whose
260
+ `commit` and `integrity` describe different content (a hand edit, a bad
261
+ merge), which is fixed by restoring the lock; and a copy of the
262
+ package in this computer's remote cache that changed after it was fetched,
263
+ which is fixed by removing the cache (`$OATS_REMOTE_CACHE`, default
264
+ `~/.cache/oats/remotes`).
265
+ - **Once per package version and computer.** A tree that matched is recorded
266
+ under the remote cache, in `.verified/`, one file per (repository key,
267
+ commit, path, integrity). The record also holds the state of the cached
268
+ repository the tree was read from: every file under it, by path, size,
269
+ mode, inode, modification time and status-change time. A later spawn
270
+ believes a record only when each of its fields is the one asked for and the
271
+ cached repository is still in that state, and then digests nothing. Any
272
+ file added, removed, replaced or rewritten there (a later fetch of the same
273
+ repository included) makes the next spawn digest the tree again. Nothing
274
+ is recorded when the cached repository changed while the tree was read (the
275
+ first fetch of the package's files): the next spawn digests it again. With
276
+ a missing or unreadable record the tree is digested, and a cached
277
+ repository that reads objects from outside itself (a symbolic link, an
278
+ alternates file) is digested every time. A record older than 30 days is
279
+ removed when the cache is next pruned. The records are the kernel's own and
280
+ no contract: deleting them only costs the next spawn a digest.
281
+ - **What a record does not see.**
282
+ - A change to the cached repository that leaves every file's size, mode,
283
+ inode and both times as they were. That takes writing to the disk under
284
+ the filesystem, setting the clock back, or, on a filesystem that keeps
285
+ times to the second, rewriting a file in place to the same size within
286
+ the second it was last changed.
287
+ - A record written by whoever changed the cache: both live in the same
288
+ directory, so the cache is as trusted as the account that owns it.
289
+ - What Git reads outside the cached repository: its own configuration and
290
+ environment.
291
+ - A change made between the check and the copy of the modules a moment
292
+ later in the same spawn.
293
+
220
294
  ## Package souls
221
295
 
222
296
  A package may ship **souls** as well as capabilities. One pin in
@@ -273,7 +347,12 @@ oats-package/
273
347
  { id, version, commit, digest, path }` and the soul id `package:<id>#<soul>`;
274
348
  in `oats status` the soul is `moved` once the package pin moves.
275
349
  - **Disabled** by `oats-local.yaml` `souls.disabled` by its qualified or bare
276
- name (`E_SOUL_DISABLED` at spawn).
350
+ name (`E_SOUL_DISABLED` at spawn). An entry is matched by name only, so an
351
+ entry naming a soul that no longer exists fails open: after a pin's removal
352
+ or rename, the soul it was meant to keep off spawns again under its new
353
+ name. After removing or renaming a pin, or a soul it provided, run
354
+ `oats doctor` and fix what it reports, and check `souls.disabled` by hand: an
355
+ older kernel's doctor doesn't report such an entry.
277
356
  - **Trusted** as the package's capabilities are: declaring the package is the
278
357
  trust decision.
279
358
 
@@ -352,12 +431,12 @@ A soul that names one of the package's capabilities with
352
431
  {
353
432
  "policy": "docs/official-catalog.md",
354
433
  "packages": {
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.21.0", "path": "oats-package" }
434
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.8.0", "path": "oats-package" },
435
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.23.0", "path": "oats-package" }
357
436
  }
358
437
  }
359
438
  ```
360
439
 
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
440
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.23.0`
441
+ resolves to tag `oats-framework/v1.23.0`. Resolving through the catalog never
363
442
  advances a lock by itself: `oats sync` does, and says so.
@@ -480,7 +480,8 @@ always records `release.status: pending`.
480
480
  ## Releasing `oats.framework`
481
481
 
482
482
  The distribution package in `oats-package/` (`oats.core`, `oats.setup`,
483
- `oats.onboarding`, `oats.support`, `oats.knowledge-theory`) is not published
483
+ `oats.onboarding`, `oats.coordination-setup`, `oats.support`,
484
+ `oats.knowledge-theory`) is not published
484
485
  by `release.yml` or by this lane. A deployment takes it from this repository at the tag
485
486
  `oats-framework/v<version>`, through the catalog ref or its workspace pin. A
486
487
  skill changed under `oats-package/` therefore reaches deployments only when
@@ -0,0 +1,97 @@
1
+ # OATS 0.69.12
2
+
3
+ 0.69.12 moves the official catalog to `oats.okf` 5.8.0, `oats.aweb` 1.37.0 and
4
+ `oats.framework` 1.22.1. `oats.okf` checks every harvest publication's content
5
+ before it is pushed. `oats.aweb` lets a person join a team by pasting one
6
+ invite, keeps every invite token off the command line, names the cause of a
7
+ refused join, warns when whatever keeps a home's aweb task claims present is
8
+ too old, and on macOS restarts its launchd jobs so they come back after an aw
9
+ upgrade. The setup expert and getting started take a second round of fixes
10
+ from newcomer runs on fresh machines.
11
+
12
+ ## Upgrade
13
+
14
+ - **Either order of the Desktop and the CLI works.**
15
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
16
+ installed the CLI first is fine too: the 0.69.12 Desktop accepts OATS CLIs
17
+ `>=0.26.0 <0.70.0`, as the 0.69.11 and 0.69.10 Desktops do.
18
+ - **Package moves:** the official catalog pins oats.okf 5.8.0 (from 5.7.0),
19
+ oats.aweb 1.37.0 (from 1.35.0, crossing 1.36.0) and oats.framework 1.22.1
20
+ (from 1.21.0, crossing 1.22.0). None changes its OATS floor: oats.okf stays >=0.69.2,
21
+ oats.aweb >=0.68.0 with aw >=1.36.33 (tested with 1.36.53). A deployment
22
+ takes each by raising its own pin (`/oats-package-pins`), then `oats sync`.
23
+ Running instances keep the modules they were spawned with: new spawns get
24
+ the new ones, and a stopped home moves with `oats instance upgrade`. A
25
+ knowledge harvester spawned after the sync publishes through oats.okf
26
+ 5.8.0's content gate.
27
+ - **Where `oats.aweb-tasks` is composed, readiness may warn** (oats.aweb
28
+ 1.37.0) `wake-daemon-outdated` (a home the host wake daemon serves, while
29
+ the daemon runs aw below 1.36.54), `aweb-channel-outdated` (a Claude home,
30
+ below aweb-channel 1.8.2) or `pi-extension-outdated` (a pi home, below
31
+ @awebai/pi 0.4.1). These are warnings, not refusals: an older component
32
+ still delivers, but a claim it doesn't heartbeat can be taken over once it
33
+ goes stale. Messaging-only homes get none of them.
34
+ - **aw 1.36.54 is on npm's `next` tag; `latest` is still 1.36.53.** Install
35
+ it by version, `npm install -g @awebai/aw@1.36.54`: a plain
36
+ `npm install -g @awebai/aw`, and `oats aweb setup --install-aw`, install
37
+ 1.36.53. Then rerun `oats aweb wake install` to restart the host wake
38
+ daemon on it. On macOS that rerun now unloads and reloads the daemon
39
+ (bootout, then bootstrap), because launchd refuses to respawn a job whose
40
+ binary an upgrade replaced; before oats.aweb 1.37.0 it left the daemon
41
+ down. Against a server other than the aweb Cloud, aw 1.36.54 is newer than
42
+ the tested aw, so oats.aweb also warns `aw-newer-than-tested` there.
43
+ - **Known issue (macOS): a running custody job is not restarted for you
44
+ after an aw upgrade.** Reload each one by hand:
45
+ `launchctl bootout gui/$(id -u)/<label>`; wait until
46
+ `launchctl print gui/$(id -u)/<label>` no longer finds it; then
47
+ `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<label>.plist`;
48
+ then rerun `oats aweb resident create <name>` to verify (oats.aweb 1.37.0's
49
+ CHANGELOG).
50
+ - **`oats aweb setup --invite` or `--invite-stdin` without `--join` is no
51
+ longer a usage error** (exit 2, "requires --join <label>"). From oats.aweb
52
+ 1.36.0 it is setup from the invite alone: it needs aw 1.36.53 or later,
53
+ refuses with `E_SETUP_AW_VERSION` on an older one, and refuses every other
54
+ problem before anything is redeemed. `--join <label>` works as before.
55
+ Every invite acceptance now reads the token on stdin, so a malformed token
56
+ fails as an aw usage error (exit 2) before anything is redeemed.
57
+
58
+ ## Changed
59
+
60
+ - **oats.okf 5.8.0: a content-safety gate on every harvest publication.**
61
+ Harvest and maintenance screen what they would publish (the outgoing
62
+ history, paths, blobs and text) before any push, comment or merge, and
63
+ report only the location, line and rule. A harvest PR left behind the
64
+ accepted tip is rewritten onto it for a fresh exact-head verdict, never
65
+ merged on an approximate squash. Structural OKF validation is unchanged
66
+ ([awebai/oats-okf#121](https://github.com/awebai/oats-okf/pull/121)).
67
+ - **oats.aweb 1.36.0: setup from one pasted invite.** `oats aweb setup --soul
68
+ <soul> --invite-stdin --name <alias>`, without `--join`, reads the invite's
69
+ team and service with aw's `team invite inspect` (redeeming nothing),
70
+ derives the label from the team's name, joins into a per-team root, and
71
+ ends with one next step. `oats aweb invite --json` answers that command at
72
+ `result.joinCommand`, with no token in it. A refused `oats aweb join` and a
73
+ failed `aw team invite` name their cause and fix, and new team roots go
74
+ beside the default team's root
75
+ ([awebai/oats-aweb#56](https://github.com/awebai/oats-aweb/issues/56),
76
+ [#52](https://github.com/awebai/oats-aweb/issues/52),
77
+ [#45](https://github.com/awebai/oats-aweb/issues/45)).
78
+ - **oats.aweb 1.37.0: claim floors for aweb tasks, and launchd restarts.**
79
+ oats.aweb-tasks's readiness warns per home on the component that keeps its
80
+ claims present (above). `oats aweb wake install` and
81
+ `oats aweb resident create` restart a loaded launchd job with bootout and
82
+ bootstrap, never `kickstart`
83
+ ([awebai/oats-aweb#196](https://github.com/awebai/oats-aweb/pull/196),
84
+ [#198](https://github.com/awebai/oats-aweb/pull/198)).
85
+ - **`oats.framework` 1.22.0 ships the second round of newcomer fixes to the setup expert.** `oats.setup` 2.13.0's `/oats-setup-expert`, `/oats-setup-model` and `/oats-package-pins`, `oats.onboarding` 1.2.0's `/oats-tailor-workspace`, and the `oats-setup-expert` soul carry them: the hand-over and hand-back, the tasks rule for each case, human attribution, both instance-name forms, and a harness entry for each new soul whose declared harness differs (#1726, #1729). The onboarding round-two entry in these notes describes each fix. The per-soul launch lines say from OATS 0.53.0. Apart from `oats tui` (OATS 0.52.0), which the hand-back leaves unversioned, no other command they name needs a newer OATS than each capability already admits ([awebai/oats#1665](https://github.com/awebai/oats/issues/1665)).
86
+ - **`oats.framework` 1.22.1: `oats.setup` 2.13.1's `/oats-onboarding` names `oats.okf` 5.8.0**, the release the catalog pins, as what knowledge operations need beside kernel 0.69.2 or later, and its workspace example pins `oats.okf: v5.8.0`. No other change.
87
+
88
+ - **Getting started and the setup expert: fixes from further newcomer runs on fresh machines** ([awebai/oats#1665](https://github.com/awebai/oats/issues/1665)).
89
+ - **`oats-getting-started`, the machine's round is always asked:** on a machine found-list, the round's one yes, naming the changes, is asked even when the prompt that started the run says to ask for nothing more. It is the consent the harness's permission check reads; without it, each change (the repository, the aweb signup, the folder trust) was refused on its own and cost the person a round. After it, nothing more is asked.
90
+ - **`oats-getting-started`, the Desktop's system libraries on Linux x64** are checked with step 2's other checks, before step 1's message, so a missing ALSA library goes on the one-yes list as a system package (dropped if the person declines the Desktop) and the Desktop's install needs no second yes.
91
+ - **`oats-getting-started`, the harness for every soul:** the skill records the chosen harness with `oats soul launch set '*' --harness <harness>` (plan first), for every soul on the machine without an entry of its own, in place of the setup soul alone. Package souls the setup expert or the steward spawns later no longer fall back to pi. `'*'` wins over a soul's own `launch:` on that machine, so each soul whose declared harness differs, and is installed and logged in on that machine, gets its own entry with that harness (and its model), by the `key` `oats souls --json` prints, plan first; a declared harness the machine lacks stays under `'*'`, so the soul can run, and the hand-over names it. The setup soul is the exception: it keeps the harness the person chose. Souls added later are covered when they declare no `launch:` of their own; one that declares one gets its own entry from the skill that adds it (`/oats-tailor-workspace`, `/oats-package-pins`) ([Launch preferences](../configuration.md#launch-preferences)).
92
+ - **`/oats-tailor-workspace` (oats.onboarding), tasks, one rule per case:** with aweb's task list by default, it keeps it. Beside a tracker the agents already use (`tasks: none`), the setup expert offers to make a tasks capability of the workspace's own for it, from how the team works (its labels and states, who files and closes issues, what agents may do), holds that conversation itself and builds it with the person (over `gh issue` for GitHub issues, a manifest with `"layer": "tasks"`), and makes it the tasks default on their yes. The getting-started skill's tasks line now says the setup assistant offers to connect the tracker. It never leaves `none` without asking and pins no generic provider in its place ([Official providers](../integrations.md#official-providers)).
93
+ - **`/oats-tailor-workspace`, human attribution:** the step where the person typed a deployment-agent command and a passphrase at a terminal is gone, as #1665 decided. Agents run every command, and the person's one act is a click in their aweb dashboard; agents already running are attached in place, with no respawn. The setup expert first looks for the step in the messaging capability's own skill; until `oats.aweb` ships it, and for a self-custodial key or an account off aweb Cloud, it runs nothing, and its brief says the agents stay unattributed and keep working. A declined or expired request is reported, never re-prompted.
94
+ - **`/oats-setup-expert` (oats.setup):** its list of what the hand-over holds matches the getting-started template (the host and its type, the steward lines, the channel mode, Tasks, and what the person may want later), and step 1 reads the tasks default. Its hand-back names no versions and no commands unless the person asks, and when a session spawned before messaging should be replaced, on the person's yes the setup expert spawns the new one as `<its name>-2`, checks that it runs and is in the team, tells the person its name, asks before its retirement would stop any of the person's agents, writes its state and only then retires itself; if a check fails it keeps its session. The person runs none of it. It describes the workspace's tasks capability as made beside a tracker on the person's yes.
95
+ - **`/oats-setup-model` (oats.setup)** describes the setup expert as `oats.framework`'s package soul `oats-setup-expert`, chosen by `oats onboard` after a workspace's own `<workspace>-oats-setup-expert` and before the first by name, and lists `oats.aweb-tasks` among the tasks providers. It, `/oats-setup-expert` and the `oats-setup-expert` soul's own instructions name both instance-name forms, `<workspace>-oats-setup-expert` and `<workspace>-<machine>-oats-setup-expert`, and the kernel's `<workspace>-oats-setup` when a soul holds the first name.
96
+ - **`oats-getting-started`, a person without a GitHub account:** step 1 asks whether they have one when gh is not logged in. Without one, step 3 opens GitHub's sign-up page in their browser (they create the account there, never in the conversation), then runs the usual device login; gh is installed like any missing tool, on the one yes.
97
+ - **`oats-getting-started`, a join never runs `aw team ensure`:** on a join, `ensure` would silently make a new team of the person's own for the same repository rather than find the teammate's. It stays step 5's, for a new workspace, and a test pins every `ensure` line there.