@awebai/oats 0.69.12 → 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 (70) 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 +3 -2
  13. package/docs/knowledge-and-learning.md +72 -0
  14. package/docs/oats-local.schema.json +11 -2
  15. package/docs/official-catalog.md +39 -5
  16. package/docs/packages.md +93 -14
  17. package/docs/release-lane.md +2 -1
  18. package/docs/release-notes/v0.69.13.md +767 -0
  19. package/docs/release-notes/v0.69.14.md +83 -0
  20. package/docs/schedules.md +26 -3
  21. package/docs/servers.md +181 -5
  22. package/docs/souls-and-instances.md +140 -11
  23. package/docs/tui.md +1 -1
  24. package/docs/upgrading.md +24 -5
  25. package/docs/workspaces.md +31 -5
  26. package/lib/claim.mjs +21 -5
  27. package/lib/command-flags.mjs +238 -0
  28. package/lib/core.mjs +791 -563
  29. package/lib/deployments.mjs +4 -3
  30. package/lib/dir-lock.mjs +126 -31
  31. package/lib/errors.mjs +1 -1
  32. package/lib/harness-token.mjs +110 -0
  33. package/lib/hot-reads.mjs +4 -3
  34. package/lib/instance-events.mjs +28 -6
  35. package/lib/instance-git.mjs +138 -13
  36. package/lib/instance-inspect.mjs +6 -1
  37. package/lib/instance-listing.mjs +80 -38
  38. package/lib/instance-resolution.mjs +56 -3
  39. package/lib/instance-upgrade.mjs +16 -20
  40. package/lib/launch-env-exec.sh +7 -0
  41. package/lib/launch-env.mjs +74 -0
  42. package/lib/launch-preference.mjs +19 -12
  43. package/lib/member-clone.mjs +7 -1
  44. package/lib/packages.mjs +74 -2
  45. package/lib/read-call.mjs +3 -0
  46. package/lib/reader.mjs +3 -2
  47. package/lib/refused-text.mjs +3 -2
  48. package/lib/remote.mjs +119 -27
  49. package/lib/retained-after-retire.mjs +2 -7
  50. package/lib/retire-git-forms.mjs +41 -0
  51. package/lib/retire-incomplete.mjs +96 -0
  52. package/lib/schedule.mjs +2 -1
  53. package/lib/servers.mjs +78 -23
  54. package/lib/session-resume.mjs +68 -53
  55. package/lib/session-seen.mjs +54 -5
  56. package/lib/start-env.mjs +13 -7
  57. package/lib/system-tools.mjs +1 -1
  58. package/lib/teams.mjs +11 -4
  59. package/lib/upgrade-state.mjs +13 -2
  60. package/lib/worktree.mjs +56 -7
  61. package/package-catalog.json +1 -1
  62. package/package.json +2 -1
  63. package/packages/client/instance-lifecycle.mjs +1 -1
  64. package/packages/client/lifecycle-contract.mjs +3 -1
  65. package/packages/client/session-resume-cli.mjs +2 -1
  66. package/packages/client/session-start.mjs +10 -7
  67. package/packages/client/workspace-cli.mjs +5 -1
  68. package/share/oats-login-receive +204 -0
  69. package/skills/oats-getting-started/SKILL.md +92 -25
  70. package/lib/tmux-config.mjs +0 -35
@@ -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.22.1` (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.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
13
  | `oats.okf` | `v5.8.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.37.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` |
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,12 +21,46 @@ 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
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
@@ -51,7 +55,7 @@ packages:
51
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.8.0` or `oats-framework/v1.22.1`) 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,7 +78,7 @@ members:
74
78
  - git:github.com/acme/agents
75
79
  - git:github.com/acme/platform
76
80
  packages:
77
- oats.framework: v1.22.1
81
+ oats.framework: v1.23.0
78
82
  oats.okf: v5.8.0
79
83
  oats.aweb: v1.37.0
80
84
  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
 
@@ -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
 
@@ -353,11 +432,11 @@ A soul that names one of the package's capabilities with
353
432
  "policy": "docs/official-catalog.md",
354
433
  "packages": {
355
434
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.8.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.22.1", "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.22.1`
362
- resolves to tag `oats-framework/v1.22.1`. 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