@awebai/oats 0.69.4 → 0.69.6

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 (74) hide show
  1. package/bin/oats.mjs +141 -364
  2. package/docs/configuration.md +12 -0
  3. package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
  4. package/docs/design/2026-10-29-warm-reader.md +261 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +258 -13
  7. package/docs/execution-targets.md +36 -5
  8. package/docs/implementation.md +34 -9
  9. package/docs/integrations.md +2 -2
  10. package/docs/knowledge.md +18 -8
  11. package/docs/named-test-runs.md +4 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-notes/v0.69.5.md +146 -0
  15. package/docs/release-notes/v0.69.6.md +165 -0
  16. package/docs/schedules.md +8 -1
  17. package/docs/tui.md +23 -5
  18. package/docs/upgrading.md +20 -5
  19. package/docs/workspaces.md +2 -2
  20. package/lib/agents-root.mjs +51 -0
  21. package/lib/argv.mjs +41 -0
  22. package/lib/automation-api.mjs +7 -0
  23. package/lib/automation-scope.mjs +37 -0
  24. package/lib/automations.mjs +63 -12
  25. package/lib/captured-context.mjs +12 -0
  26. package/lib/compile-cache.mjs +36 -0
  27. package/lib/core.mjs +39 -1348
  28. package/lib/deployment-path.mjs +127 -0
  29. package/lib/deployments.mjs +2 -2
  30. package/lib/drift.mjs +95 -0
  31. package/lib/hot-reads.mjs +137 -0
  32. package/lib/install-stamp.mjs +61 -0
  33. package/lib/instance-address.mjs +21 -0
  34. package/lib/instance-events.mjs +8 -6
  35. package/lib/instance-lifecycle.mjs +4 -16
  36. package/lib/instance-listing.mjs +738 -0
  37. package/lib/instance-resolution.mjs +5 -166
  38. package/lib/kernel-features.mjs +10 -0
  39. package/lib/local-edit.mjs +1 -1
  40. package/lib/local-inputs.mjs +3 -0
  41. package/lib/materialize.mjs +2 -87
  42. package/lib/member-clone.mjs +192 -0
  43. package/lib/package-catalog.mjs +93 -0
  44. package/lib/packages.mjs +4 -24
  45. package/lib/read-call.mjs +143 -0
  46. package/lib/reader.mjs +203 -0
  47. package/lib/remote.mjs +47 -6
  48. package/lib/reserved-launch-env.mjs +20 -0
  49. package/lib/resolved-deployment.mjs +13 -5
  50. package/lib/roster-read.mjs +199 -0
  51. package/lib/schedule.mjs +5 -29
  52. package/lib/semver.mjs +12 -0
  53. package/lib/servers.mjs +10 -12
  54. package/lib/session-end.mjs +3 -2
  55. package/lib/session-input.mjs +35 -11
  56. package/lib/session-inspect.mjs +219 -0
  57. package/lib/soul-listing.mjs +216 -0
  58. package/lib/status-words.mjs +30 -0
  59. package/lib/version.mjs +9 -0
  60. package/lib/workspace-read.mjs +160 -0
  61. package/lib/write-file-atomic.mjs +28 -0
  62. package/package-catalog.json +4 -4
  63. package/package.json +1 -1
  64. package/packages/client/cli-locator.mjs +1 -0
  65. package/packages/client/cli-probe-contract.mjs +4 -2
  66. package/packages/client/deployment-observer.mjs +8 -3
  67. package/packages/client/deployment-panel.mjs +17 -1
  68. package/packages/client/deployment-read-cli.mjs +48 -27
  69. package/packages/client/own-codes.mjs +3 -0
  70. package/packages/client/warm-reader.mjs +241 -0
  71. package/packages/tui/lib/client.mjs +2 -1
  72. package/packages/tui/lib/read.mjs +59 -11
  73. package/packages/tui/lib/store.mjs +7 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
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.5.0** (OATS **>=0.49.0**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.7.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.5.0
28
+ oats.okf: v5.7.0
29
29
  defaults:
30
30
  knowledge: { oats.okf: { from: package } }
31
31
  stores:
@@ -50,10 +50,11 @@ settings:
50
50
 
51
51
  Upgrading from 4.x requires the ordered
52
52
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
53
- just editing a version line. For 5.5.0, OATS >=0.49.0 remains required:
54
- that kernel first supports the public source-event lookup after retirement.
53
+ just editing a version line. From 5.6.0 it requires OATS >=0.69.2: its
54
+ `knowledge-harvester` and `knowledge-maintainer` souls say `background: true`,
55
+ which an older kernel refuses. Upgrade OATS first, then the package.
55
56
 
56
- **Upgrade:** pin `oats.okf: v5.5.0` and run `oats sync`. Only new spawns get
57
+ **Upgrade:** pin `oats.okf: v5.7.0` and run `oats sync`. Only new spawns get
57
58
  the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
59
  homes keep their copied provider even after a session restart; from 5.4.0, a
59
60
  stopped 5.x home can move with `oats instance upgrade` (OATS 0.68.0 and
@@ -65,7 +66,11 @@ remain. From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the
65
66
  checkpoint line in `log.md`, drops the available-memory gate, and has the
66
67
  proposer name each harvester (`--name`, below). 5.5.0 adds the incarnation to
67
68
  the proposal's `Source:` line (below): a harvester on 5.4.0 or older refuses
68
- that line, so run `oats sync` to 5.5.0 before instances on 5.5.0 propose.
69
+ that line, so run `oats sync` to 5.5.0 or later before instances on 5.5.0
70
+ propose. 5.6.0 lists new harvesters and knowledge maintainers under the
71
+ clients' Background section; existing ones do not move. 5.7.0 stops parking
72
+ harvest PRs under `okf-needs-human` (step 4 of [the flow](#the-flow)); PRs an
73
+ older maintainer parked are re-reviewed by the steps in okf's CHANGELOG.
69
74
 
70
75
  ### Bindings document
71
76
 
@@ -277,8 +282,13 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
277
282
  for a labelled PR. A gh error can leave remote effects, so partial or
278
283
  uncertain publication is not completion or permission to clean up.
279
284
  4. **Review.** A separate `oats.okf/knowledge-maintainer` reviews the PR.
280
- Human-accepted decisions are not silently superseded; the review path
281
- keeps its human gate. A PR is not accepted knowledge until merged.
285
+ A PR is not accepted knowledge until merged. Human-accepted decisions are
286
+ not silently superseded. Before oats.okf 5.7.0 the maintainer labels a PR
287
+ that would supersede one `okf-needs-human` and leaves it to a human. From
288
+ 5.7.0 the review never parks a PR: such a supersession merges only with the
289
+ human's acceptance cited (checked when the record is on GitHub, otherwise
290
+ recorded as source-reported), and is closed without it
291
+ ([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)).
282
292
 
283
293
  The promotion test belongs to
284
294
  [What deserves to become knowledge](knowledge-theory.md#what-deserves-to-become-knowledge),
@@ -187,6 +187,10 @@ leaves out the request's two variables, the runner's command files
187
187
  (`GITHUB_ENV`, `GITHUB_OUTPUT`, `GITHUB_PATH`, `GITHUB_STATE`,
188
188
  `GITHUB_STEP_SUMMARY`) and node's nested-run marker. So `GITHUB_WORKFLOW` and
189
189
  `GITHUB_EVENT_NAME` reach the test, and on Linux so does `XDG_RUNTIME_DIR`.
190
+ It puts the tested tree's `node_modules/.bin` first on `PATH`, as `npm test`
191
+ does in pull-request CI and the release workflow: a test that starts a
192
+ fixture instance finds there the `pi` that the workflow's `npm ci` installs
193
+ in the tested tree.
190
194
 
191
195
  A guard is a switch, not a proof. Anyone can set these variables on their own
192
196
  machine, and a guarded test that runs there drives that machine's real
@@ -9,12 +9,12 @@ 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.16.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.5.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.32.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
12
+ | `oats.framework` | `oats-framework/v1.16.4` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.7.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.32.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
15
  | `oats.engineering` | `v1.17.2` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
- | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
17
+ | `oats.cloning` | `v1.1.0` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
19
19
  | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
20
20
  | `oats.apps` | `v1.0.0` | `oats.folio`, `oats.library` | |
@@ -30,7 +30,7 @@ no lock and adds nothing to an existing workspace.
30
30
  ## Find and use packages
31
31
 
32
32
  - A workspace pins an official package by **bare version** in its
33
- `packages:` map (`oats.okf: v5.5.0`); `oats sync` resolves it through the
33
+ `packages:` map (`oats.okf: v5.7.0`); `oats sync` resolves it through the
34
34
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
35
35
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
36
36
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v5.5.0 # bare version → the official catalog
47
+ oats.okf: v5.7.0 # bare version → the official catalog
48
48
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
49
  ```
50
50
 
51
- - **Bare version** (`v5.5.0`, `5.5.0`, `1.0.0-rc.1`): the id is looked up in
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.5.0` or `oats-framework/v1.16.2`) and the payload path. An id
54
+ convention (`v5.7.0` or `oats-framework/v1.16.4`) 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.16.2
78
- oats.okf: v5.5.0
79
- oats.aweb: v1.32.0
77
+ oats.framework: v1.16.4
78
+ oats.okf: v5.7.0
79
+ oats.aweb: v1.32.1
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -105,7 +105,7 @@ decision recorded in the lock.
105
105
  $ oats sync
106
106
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
107
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.5.0 ✓ (@ 4817c74e)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.7.0 ✓ (@ 56dbc167)
109
109
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
110
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
111
  teams platform (shared) · this deployment's: oats teams
@@ -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.32.0 # a catalog version
137
+ oats package add oats.aweb v1.32.1 # 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
  ```
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
160
160
  "source": "catalog:oats.okf",
161
161
  "url": "https://github.com/awebai/oats-okf.git",
162
162
  "path": "oats-package",
163
- "version": "5.5.0",
164
- "commit": "4817c74ede1e1b578e5a78759862964ea077ded1",
163
+ "version": "5.7.0",
164
+ "commit": "56dbc167394bbc13cc900bd8af0c64b74fecae54",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
352
352
  {
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.5.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.2", "path": "oats-package" }
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.16.4", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.16.2`
362
- resolves to tag `oats-framework/v1.16.2`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.16.4`
362
+ resolves to tag `oats-framework/v1.16.4`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,146 @@
1
+ # OATS 0.69.5
2
+
3
+ Unreleased
4
+
5
+ 0.69.5 makes the commands OATS runs most often start faster, and it shows a
6
+ lost session as `LOST` in `oats status` and `oats server roster`. A restart
7
+ whose relaunch fails no longer comes back on the next resume. The catalog
8
+ moves to oats.okf 5.6.0 and oats.cloning 1.1.0, whose one-shot service souls
9
+ are listed under Background, and to oats.aweb 1.32.1 and oats.framework
10
+ 1.16.3. This workspace stops pinning oats.cloning.
11
+
12
+ ## Upgrade
13
+
14
+ - **Install the Desktop first and the CLI second,** as
15
+ [Upgrading](../upgrading.md) says. The 0.69.5 Desktop accepts OATS CLIs
16
+ `>=0.26.0 <0.70.0`.
17
+ - **OATS 0.69.2 or later on every host that shares a workspace, before any of
18
+ them syncs:** oats.okf 5.6.0 and oats.cloning 1.1.0 require it. On an older
19
+ kernel, `oats sync` still locks them, but their souls are dropped and new
20
+ spawns that compose them are refused (`E_CAPABILITY_INCOMPATIBLE`, naming
21
+ the re-pin) (Provider updates, below). Where oats.okf is the workspace's
22
+ default knowledge slot, that is nearly every new spawn.
23
+ - **Package moves:** the official catalog pins oats.okf 5.6.0, oats.cloning
24
+ 1.1.0, oats.aweb 1.32.1 and oats.framework 1.16.3. A deployment takes them
25
+ with `oats sync`. Running instances keep the modules they were spawned
26
+ with: new spawns get the new ones, and a stopped home moves with
27
+ `oats instance upgrade`.
28
+ - **A new cache directory:** every `oats` command keeps Node's compile cache
29
+ in `~/.oats/compile-cache` (Changed, below). It is safe to delete.
30
+
31
+ ## Changed
32
+
33
+ - **`oats` commands start faster: the CLI keeps Node's compile cache.** Node
34
+ no longer recompiles the kernel on every command: each command starts
35
+ faster, by about a quarter for a cheap read such as `oats version`, and the
36
+ status polls the Desktop and the TUI make cost less. The cache is a new
37
+ directory, `~/.oats/compile-cache` (`$OATS_HOME_DIR/compile-cache`),
38
+ created mode 0700. It is safe to delete at any time. `NODE_COMPILE_CACHE`
39
+ moves it, and `NODE_DISABLE_COMPILE_CACHE=1` turns it off
40
+ ([configuration](../configuration.md#the-compile-cache)). Nothing a command
41
+ prints changes.
42
+
43
+ - **The reads OATS makes most often load only what they use.** `oats version`,
44
+ `session inspect`, `status`, `workspace status`, `instance events` and
45
+ `instance waiting clear` no longer load the whole kernel. `oats version` takes
46
+ less than half its time and `session inspect` about half; `status` takes about
47
+ an eighth less and `workspace status` about a fifth less; `instance events` and
48
+ the waiting hook a Claude instance runs every turn take about a quarter less.
49
+ Nothing a command prints changes.
50
+
51
+ ## Fixed
52
+
53
+ - **A restart whose relaunch fails no longer reads `lost`, so a resume does not bring back the session you were restarting.** `oats session restart` stopped the running harness and then relaunched it, without recording the stop. When the relaunch failed, or the restart died between the two, the home read `sessionEnd: "lost"`, and the next resume sweep (OATS Desktop or `oats tui` opening) started the old launch again. A restart now records the stop before it asks the harness to end, as a retire does, so such a home reads `stopped` and stays down; a successful relaunch records a new start, which reads as before. A restart whose stop is refused keeps that record, so its harness, should it die later, reads `stopped` rather than `lost` ([awebai/oats#1601](https://github.com/awebai/oats/issues/1601); [Resume after a shutdown](../execution-targets.md#resume-after-a-shutdown)).
54
+
55
+ - **`oats tui` no longer replaces the answer to what you did with its own line.** When the add of the deployment a run started in to this computer's list fails, the line that says so waits again until a line answering your own act has gone, as it did before 0.69.2. The add answers in the run's first moments, so this shows only when you act before it does: a correctness restore, rarely visible ([awebai/oats#1603](https://github.com/awebai/oats/issues/1603); [Start it](../tui.md#start-it)).
56
+
57
+ - **The pi bridge loads the kernel that launched its instance first**
58
+ ([#1604](https://github.com/awebai/oats/issues/1604)). Pi instances were
59
+ never affected: each home's own `oats` link is first on the PATH pi
60
+ launches with, so the bridge found the launching kernel with no global
61
+ install. Now the bridge reads that link directly, after `OATS_PKG_ROOT`
62
+ and before any PATH or global lookup, so a home loads its own kernel
63
+ whatever PATH pi has. A pi started outside any instance, on a host with no
64
+ global install and an `oats` that is a script rather than a link to the
65
+ kernel, failed with "the pi adapter needs the oats CLI installed
66
+ globally". It now says "OATS kernel not found" and names the three ways
67
+ out: `npm install -g @awebai/oats`, an `oats` on PATH that links to the
68
+ kernel's `bin/oats.mjs` (`npm link` in a checkout), or `OATS_PKG_ROOT`
69
+ ([the bridge's README](../../packages/pi/README.md)).
70
+
71
+ - **`oats status` printed a lost session as `idle`**
72
+ ([#1617](https://github.com/awebai/oats/issues/1617)). The text views of
73
+ `oats status` and `oats status --server <id>` printed every row that does
74
+ not run as `idle`, so a session lost to a reboot or a dead tmux server read
75
+ the same as one stopped on purpose. A row whose `sessionEnd` is `lost` now
76
+ prints `LOST`, with one line under it naming the way back: `oats session
77
+ start --resume --home <home>`, or the next `oats session resume` (run when
78
+ OATS Desktop or `oats tui` opens) when it can vouch for the loss. A
79
+ `--server` row names the host to run them on. A stopped, exited or
80
+ never-launched row, and a row from a host whose kernel reports no
81
+ `sessionEnd`, still print `idle`.
82
+ The JSON is unchanged
83
+ ([How a session's end is read](../execution-targets.md#how-a-sessions-end-is-read)).
84
+
85
+ - **`oats server roster` printed a lost session as `idle`**
86
+ ([#1628](https://github.com/awebai/oats/issues/1628)). Its rows did not
87
+ relay the host's `sessionEnd`, so the roster could not tell a session lost
88
+ to a reboot or a dead tmux server from one stopped on purpose. A roster row
89
+ of `server roster --json` now carries `sessionEnd` when the host's row has
90
+ it, with the host's value: `lost`, `stopped` or `exited`. A host whose
91
+ kernel reports no `sessionEnd` gives rows as before. The roster line prints
92
+ a lost row as `LOST`, with one line under it naming the way back on that
93
+ host, as `oats status --server <id>` does
94
+ ([`sessionEnd` on a roster row](../desktop-cli-api.md#the-remote-roster-oats-server-roster---json)).
95
+
96
+ ## Provider updates
97
+
98
+ - **oats.aweb 1.32.1: recover pi mail lost on an interrupted turn.** The
99
+ catalog and this workspace pin `oats.aweb: v1.32.1`, from 1.32.0. It is
100
+ guidance only, cut from 1.32.0 with this one change: with `@awebai/pi`
101
+ 0.4.0, mail that arrives during a turn can be lost when the human
102
+ interrupts it (awebai/aweb#68). The inject and `/oats-aweb` section 4 now
103
+ have affected pi instances scan `aw mail inbox --show-all --json` after any
104
+ interrupted turn and at task boundaries, and reconcile by message id. The
105
+ workaround goes once a fixed `@awebai/pi` is pinned. OATS >=0.68.0 and the
106
+ aw floor are unchanged.
107
+
108
+ - **oats.cloning 1.1.0: cloners are background instances.** The catalog
109
+ pins oats.cloning `v1.1.0`, from 1.0.1. The `cloner` soul says
110
+ `background: true`, so the Desktop and `oats tui` list a new cloner under
111
+ their Background section (oats-cloning#6, awebai/oats#1579). The clone
112
+ itself is placed as its own soul says.
113
+ - **Upgrade:** 1.1.0 requires **OATS >=0.69.2** (was >=0.34.0): an older
114
+ kernel drops the soul, so `oats cloning request` refuses with
115
+ `E_SOUL_UNKNOWN`. Upgrade OATS first, then `oats sync`.
116
+ - **This workspace no longer pins oats.cloning,** and its souls no longer
117
+ compose it: new instances of them have no `/clone-instance`. Running
118
+ instances keep the copy they were spawned with. A workspace that wants
119
+ cloning pins `oats.cloning: v1.1.0` and composes
120
+ `oats.cloning: { from: package }` in the souls that may request clones.
121
+
122
+ - **oats.framework 1.16.3: oats.setup 2.9.4.** oats.setup's `/oats-onboarding`
123
+ pins `oats.okf: v5.6.0` in its knowledge section and names its kernel floor,
124
+ OATS 0.69.2 (text only). The other capabilities are unchanged.
125
+ - **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
126
+ `oats.framework: v1.16.3`. New spawns get it, and a stopped home moves with
127
+ `oats instance upgrade`.
128
+
129
+ - **oats.okf 5.6.0: knowledge harvesters and knowledge maintainers are
130
+ background instances.** The catalog and this workspace pin
131
+ `oats.okf: v5.6.0`, from 5.5.0. Both package souls say `background: true`,
132
+ so the Desktop and `oats tui` list new harvesters and knowledge maintainers
133
+ under their Background section (oats-okf#113, awebai/oats#1579). Existing
134
+ instances do not move, and harvest and review behave as before.
135
+ - **Upgrade:** 5.6.0 requires **OATS >=0.69.2** (was >=0.49.0): an older
136
+ kernel refuses the `background:` key, so it drops both souls and refuses
137
+ new spawns that compose oats.okf (`E_CAPABILITY_INCOMPATIBLE`, naming the
138
+ re-pin). Upgrade OATS on every host that shares the workspace first, then
139
+ `oats sync`.
140
+
141
+ ## Documentation
142
+
143
+ - **Which losses come back** names one more limit: the 24-hour gap of clause
144
+ 4 does not reach across a reboot, so after a quiet spell of more than a day
145
+ with no OATS read, the first sweep after a restart can bring back a session
146
+ lost during it ([Which losses come back](../execution-targets.md#which-losses-come-back)).
@@ -0,0 +1,165 @@
1
+ # OATS 0.69.6
2
+
3
+ Unreleased
4
+
5
+ 0.69.6 makes the Desktop and `oats tui` refresh without starting a new CLI
6
+ process for every read. Both now read through one warm `oats reader --stdio`,
7
+ and under the new feature `status-liveness` they take each instance's
8
+ liveness from `oats status` instead of running their own terminal probe.
9
+ `oats status` and `oats workspace status` also do less work per read. A
10
+ working instance no longer reads idle when the process scan can't see it.
11
+ The catalog moves to oats.okf 5.7.0, whose knowledge maintainer never parks a
12
+ harvest PR for a human, and to oats.framework 1.16.4.
13
+
14
+ ## Upgrade
15
+
16
+ - **Either order of the Desktop and the CLI works.**
17
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
18
+ installed the CLI first is fine too: the 0.69.6 Desktop accepts OATS CLIs
19
+ `>=0.26.0 <0.70.0`, and so does the 0.69.5 Desktop. The warm reader needs
20
+ both: a Desktop or TUI uses it only with a CLI that lists feature
21
+ `warm-reader`, and otherwise reads through the CLI, as before.
22
+ - **Package moves:** the official catalog pins oats.okf 5.7.0 and
23
+ oats.framework 1.16.4, with no change to their OATS floors. A deployment
24
+ takes them with `oats sync`. Running instances keep the modules they were
25
+ spawned with: new spawns get the new ones, and a stopped home moves with
26
+ `oats instance upgrade`.
27
+ - **Knowledge PRs parked on `okf-needs-human`:** on the review host of the
28
+ workspace's harvest-review trigger, once its lock has oats.okf 5.7.0,
29
+ re-review each one as Provider updates (below) says. A label left in place
30
+ does nothing, and no new review starts on its own.
31
+
32
+ ## Added
33
+
34
+ - The warm reader, `oats reader --stdio` (feature `warm-reader`,
35
+ `readerApi: 1`, #1630). A client starts it as its own child, from the same
36
+ install it runs its CLI reads with, and sends it `oats status --json` and
37
+ `oats workspace status --json` reads over its stdin and stdout, one JSON
38
+ line each way, many times. It answers with the kernel's own read code, kept
39
+ loaded: warm code, not warm data. Every request reads the deployment
40
+ afresh, and each answer's `exit` and `answer` are what the same CLI read
41
+ prints and exits with, with cwd = `--dir`. What it cannot answer that way it
42
+ refuses (`E_READER_BAD_REQUEST`, `E_READER_UNSUPPORTED`), and the client
43
+ runs the CLI. A reader whose install changed under it (an upgrade, a Node
44
+ upgrade) answers nothing more from the old code: it refuses with
45
+ `E_READER_STALE` and exits. It ends when its client closes its stdin or
46
+ dies. Bare `oats reader` is `E_USAGE`. The protocol and the client rules
47
+ are in [The warm reader](../desktop-cli-api.md#the-warm-reader); the
48
+ decisions in [the design record](../design/2026-10-29-warm-reader.md).
49
+ - Feature `status-liveness`: `oats status --json` instance rows' `running`
50
+ and `runtimeState` are the complete local liveness reading, read live at
51
+ every call under the kernel's pane rule, so a client that sees the feature
52
+ in the probe needs no liveness probe of its own beside the roster
53
+ ([The roster](../desktop-cli-api.md#the-roster-oats-status---json)).
54
+
55
+ ## Changed
56
+
57
+ - **OATS Desktop: the poll's reads go through the warm reader** (#1630).
58
+ Where the installed CLI lists `warm-reader` (`readerApi: 1`), the Desktop's
59
+ bundled server starts one `oats reader --stdio` from that CLI. It answers
60
+ the background `oats status` and `oats workspace status` reads of every
61
+ refresh cycle (`--max-age` above 0) with the kernel's read code kept
62
+ loaded, instead of a Node start per read. The answers are the CLI's own and
63
+ are checked the same way. A live read (the first cycle, a refresh after a
64
+ change, Refresh) still runs the CLI. Whenever the reader is absent, refuses,
65
+ times out, stops answering or exits, that read runs the CLI as before.
66
+ After repeated failures the Desktop uses the CLI until the CLI changes. A
67
+ reader whose install was upgraded under it makes the Desktop probe the CLI
68
+ again. The reader dies with the server that started it, also when the app
69
+ or the server is killed. Nothing about it is shown. `/api/cli` reports its
70
+ state as a diagnostic.
71
+ - **OATS Desktop: no liveness child under `status-liveness`.** With a CLI
72
+ that lists `status-liveness`, the refresh cycle no longer starts its
73
+ terminal-liveness child. A local row's running state, reason and tmux
74
+ record are the ones `oats status` reports, and a reason on a local row is
75
+ always the kernel's. As a result, an instance home with no tmux record
76
+ (every spawn records one) has no terminal for the Desktop to open, where
77
+ the child used to fill in the default session. With an older CLI the child
78
+ runs as before.
79
+
80
+ - `oats tui` reads its deployments in the background through one warm
81
+ `oats reader --stdio` of its own kernel, when that kernel lists feature
82
+ `warm-reader`, in place of two kernel commands per deployment each cycle.
83
+ Its answers are the commands' own, and a live read (`r`), every read
84
+ before the reader is ready and every read it does not answer still run
85
+ the commands, as before. Under feature `status-liveness` the TUI no
86
+ longer runs its probe of the terminals: each instance's running state,
87
+ reason and tmux record are the ones `oats status` reports. As a result,
88
+ an instance home with no tmux record (every spawn records one) has no
89
+ terminal for the TUI to open, where the probe used to fill in the default
90
+ session. With an older kernel the probe runs as before (#1630; [What it
91
+ reads, and what it runs](../tui.md#what-it-reads-and-what-it-runs)).
92
+ - The warm reader (`oats reader --stdio`, #1630) starts with only the code
93
+ its reads use: the CLI no longer loads its whole command set for it first.
94
+ On a real deployment its hello comes in about 140–180 ms instead of about
95
+ 300, and it holds about 20 MiB less memory while it answers a poll. Its protocol, its answers
96
+ and its install stamp are unchanged; a client needs no change
97
+ ([The warm reader](../desktop-cli-api.md#the-warm-reader)).
98
+
99
+ - `oats status` and `oats workspace status` do less work per read, with the same answers ([awebai/oats#1630](https://github.com/awebai/oats/issues/1630)). `status` shares each instance home's `instance.json`, as its listing read it, with its legacy-home check and its waiting-claim read instead of each parsing it again, and `workspace status` asks git for a member clone's remotes once, where it verified the clone an automation lives in twice. Nothing is kept between reads, in the CLI or in the warm reader (`oats reader --stdio`).
100
+
101
+ - **`oats workspace status --max-age <s>` reuses the host's `gh` login, for display only** ([awebai/oats#1630](https://github.com/awebai/oats/issues/1630); [Observation reuse](../desktop-cli-api.md#the-gh-login-display-only)). To show where each workspace trigger and schedule runs, `workspace status` asks `gh api user` which account this host acts as: a GitHub API call on every read, which a client polling every few seconds made every few seconds, and most of each read's time. Under `--max-age <s>` it now reuses a login observed at most `<s>` seconds ago, as it reuses remote heads, and counts it in the `observation` block (`reused`, `observedAt`). A login is reused only under the same `gh` context (host, `gh` binary, which token variables are set, `GH_HOST`, the config directory and its `hosts.yml`); no token or digest of one is kept; a failed answer is never reused and ends the reuse of the one before it. Without `--max-age`, or with `0`, it asks every time. What runs does not change: a schedule tick, `oats trigger poll` and every run still ask `gh` live. Within `<s>`, a token revoked on GitHub still shows the login, as a moved head shows unmoved.
102
+ - **A `gh` that hangs costs `oats workspace status` 5 s, not 30.** The display waits at most 5 s for `gh api user` (ticks and runs keep 30 s); a `gh` that does not answer in time reads `owner-mismatch`, as one that is not logged in does.
103
+
104
+
105
+ ## Fixed
106
+
107
+ - **A working instance no longer reads idle when the process scan cannot see it.** tmux names the launch's own shell as a pane's command while the harness runs below it, so `oats status` and `oats session inspect` decide such a pane from the process table. A table that could not establish the fallback prompt still read it: a `ps` that could not see the pane's process (another PID namespace, a pane respawned between the two reads), a process in the pane with no command name, or a line that is not a process each made a running harness read `running: false` (idle) in the Desktop and the TUI. `false` now needs the pane's own shell in the table with no non-shell process below it; anything else reads `running: null` with the reason as `runtimeError` (`session inspect`: `E_SESSION_UNAVAILABLE`), and a lifecycle command refuses rather than taking the pane for a fallback shell. A pane at its fallback prompt still reads `running: false` with `runtimeState: "shell"` ([awebai/oats#1641](https://github.com/awebai/oats/issues/1641); [The roster](../desktop-cli-api.md#the-roster-oats-status---json)).
108
+
109
+ ## Provider updates
110
+
111
+ - **oats.okf 5.7.0: the knowledge maintainer never parks a harvest PR**
112
+ ([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)).
113
+ When a deployment pins oats.okf 5.7.0, a PR that would supersede a
114
+ human-accepted decision is settled at review instead of waiting for a
115
+ human under the `okf-needs-human` label. The OATS floor is unchanged.
116
+ - It is closed when it cites no acceptance (who accepted the change, when
117
+ and where).
118
+ - A cited record on GitHub (an issue or PR comment, or a commit) is
119
+ checked: it must exist at the cited link, under the account the citation
120
+ names, and say the cited thing. Confirmed, the PR merges as an explicit
121
+ supersession with the acceptance recorded as verified at its link, which
122
+ shows the account and the record, not that the human typed it: agents
123
+ may post under their human's account. Otherwise it is closed.
124
+ - A relay on GitHub (a record that presents itself as an agent reporting
125
+ the human's words) is checked the same way: it must exist at the cited
126
+ link and say that the relaying agent reported the human's acceptance of
127
+ this change. Confirmed, the PR merges as an explicit supersession with
128
+ the acceptance recorded as `source-reported (relay at <link>)`, never as
129
+ verified; otherwise it is closed.
130
+ - A cited record the maintainer cannot read (mail, a session, a call) is
131
+ trusted without a check: the PR merges as an explicit supersession with
132
+ the acceptance recorded as source-reported.
133
+ - `oats okf-maintenance review-context` no longer reports `blocked`, and
134
+ `settled` now means only that the PR is not open.
135
+ - **Re-review each parked PR.** A label left in place is inert, but the
136
+ PR is reviewed again only on a new `harvest-review` event. The trigger
137
+ polls: a close it never saw is no reopen. On the trigger's review host,
138
+ once its lock has 5.7.0:
139
+ 1. Retire the knowledge-maintainer instances left from older reviews,
140
+ running or stopped: a retained home holds a concurrency slot (`max`
141
+ 2, `perKey` 1), and one composed from an older package keeps the old
142
+ behaviour.
143
+ 2. Remove `okf-needs-human` from each parked PR, then close it.
144
+ 3. Wait until `oats trigger status <id> --json` shows a `lastPoll`
145
+ after the closes with `ok: true` and `prs` under 100 (every 2m). Only
146
+ such a poll records a close: a failed poll records none (keep
147
+ waiting), and one that fetched 100 open PRs may be truncated (stop
148
+ and report the poll cap; do not reopen). `oats trigger test` does not
149
+ count: it records nothing.
150
+ 4. Reopen each PR, and check that `oats trigger status <id> --json`
151
+ lists a `pending` or `fired` entry with `event: "reopened"` for each
152
+ PR's number. At most two reviews run at once; the rest wait as `held`
153
+ until a maintainer retires.
154
+
155
+ Never clear the trigger's dedup state.
156
+ - [Knowledge operations: the flow](../knowledge.md#the-flow), step 4,
157
+ says what holds before and after 5.7.0.
158
+
159
+ - **oats.framework 1.16.4: oats.setup 2.9.5.** oats.setup's `/oats-onboarding`
160
+ pins `oats.okf: v5.7.0` in its knowledge section (text only), so a new
161
+ deployment sets up knowledge operations whose review never parks a harvest
162
+ PR. The floors and the other capabilities are unchanged.
163
+ - **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
164
+ `oats.framework: v1.16.4`. New spawns get it, and a stopped home moves with
165
+ `oats instance upgrade`.
package/docs/schedules.md CHANGED
@@ -542,7 +542,14 @@ Otherwise the item is listed with a reason: `assigned-elsewhere`,
542
542
  else or not at all), `host-unnamed`, or `untrusted` (placed here but not
543
543
  trusted: it never runs, and `oats workspace status` warns with the exact
544
544
  line to add). Both names come from a commit, so anyone who can commit to a
545
- member could name your host; trust is the operator's own yes. A trust entry
545
+ member could name your host; trust is the operator's own yes.
546
+
547
+ `oats workspace status` shows the same placement. Under `--max-age <s>` it
548
+ may show it with a `gh` login observed up to `<s>` seconds ago, and it waits
549
+ at most 5 s for `gh` (a `gh` that does not answer in time reads
550
+ `owner-mismatch`): [the `gh` login, display only](desktop-cli-api.md#the-gh-login-display-only).
551
+ What runs never depends on that: a tick, `oats trigger poll` and every run
552
+ ask `gh` live and wait up to 30 s. A trust entry
546
553
  that names no workspace automation is a warning (`automation-trust-stale`),
547
554
  not an error: its member may not have synced yet. Your own `oats trigger
548
555
  add` / `oats schedule add` definitions need no trust.
package/docs/tui.md CHANGED
@@ -67,7 +67,8 @@ and is said once, in the line under the list of workspaces, in the kernel's word
67
67
  it comes while the switcher, the help, a confirmation, the palette, the
68
68
  spawn prompt, a detail or a terminal has the screen or the focus, it is said
69
69
  once a view's list has the focus again, so no screen that covers the
70
- sidebar hides it. A deployment opened from the switcher is
70
+ sidebar hides it. It never replaces a line that answers something you did:
71
+ it waits until that line goes. A deployment opened from the switcher is
71
72
  on the list already.
72
73
 
73
74
  **From inside an agent's pane it still reads the deployment you asked
@@ -2365,10 +2366,27 @@ with the Desktop (`packages/client/`).
2365
2366
  deployment, run with **the kernel it shipped with** (the `bin/oats.mjs` of
2366
2367
  the same install, with the Node that runs the TUI), never an `oats` found
2367
2368
  on `PATH`. Each has 30 seconds and 4 MiB.
2368
- - **Then one probe of the terminals**: a small program of the shared readers
2369
- asks tmux which instances have a live pane (`tmux list-panes`, and `ps`
2370
- for what runs in them). It has 30 seconds. An instance the kernel itself
2371
- reported as unknown is not probed and stays unknown.
2369
+ - **The background reads go through one warm reader** when that kernel
2370
+ lists feature `warm-reader`: `oats reader --stdio`, started once by the
2371
+ TUI as it starts every kernel command (`node <bin> reader --stdio`, in a
2372
+ session of its own), answers them from one process with the same answers
2373
+ as the two commands. A live read (`r`, the return from a suspend, a row
2374
+ opened in the switcher), every read before the reader is ready, and every
2375
+ read it does not answer are the two commands, as above: nothing waits for
2376
+ it and nothing shows it. The rules are the Desktop's: the client rules
2377
+ of [The warm reader](desktop-cli-api.md#the-warm-reader). An install that changed
2378
+ under the run leaves the TUI on the two commands until it is started
2379
+ again. The reader ends when the TUI does: the TUI holds its stdin, and
2380
+ closing it, on the way out or by the TUI's death, ends it.
2381
+ - **Then one probe of the terminals**, only for a kernel without feature
2382
+ `status-liveness`: a small program of the shared readers asks tmux which
2383
+ instances have a live pane (`tmux list-panes`, and `ps` for what runs in
2384
+ them). It has 30 seconds. An instance the kernel itself reported as
2385
+ unknown is not probed and stays unknown. A kernel with the feature reads
2386
+ that itself, live, in `oats status`: no probe runs, and each instance is
2387
+ as the kernel reported it, its tmux record included. An instance home
2388
+ with no tmux record (every spawn records one) then has no terminal to
2389
+ open, where the probe fills in the default session.
2372
2390
  - **Every deployment opened in the run is read each time**, at most two at
2373
2391
  a time.
2374
2392
  - **How often:** 5 seconds after the last read ended; 30 seconds once ten
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.4** ([release notes](release-notes/v0.69.4.md)).
10
- The 0.69.4 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.6** ([release notes](release-notes/v0.69.6.md)).
10
+ The 0.69.6 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.4,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.6,** 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.4 first
23
- npm install -g @awebai/oats@0.69.4 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.6 first
23
+ npm install -g @awebai/oats@0.69.6 # 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
  ```
@@ -53,6 +53,12 @@ must be at the same version: a pi session with an older bridge runs old
53
53
  extension code against a new kernel. A host that launches no pi instance has
54
54
  no bridge, and step 2 has nothing to move.
55
55
 
56
+ The bridge loads the kernel that launched its pi instance, so a host that
57
+ runs the CLI from a checkout or a local install needs no global one for its
58
+ instances. A pi started outside any instance looks for a global install, an
59
+ `oats` on PATH that links to the kernel, or `OATS_PKG_ROOT`
60
+ ([the bridge's README](../packages/pi/README.md)).
61
+
56
62
  **A release's own steps are in its notes**, in its `## Upgrade` section.
57
63
  This page is the part that is the same for every release.
58
64
 
@@ -166,6 +172,15 @@ of the Desktop and the CLI, and an optional package pin. A change a script
166
172
  must follow is in its release's Upgrade section whether or not it is listed
167
173
  here.
168
174
 
175
+ - **[0.69.6](release-notes/v0.69.6.md#upgrade):** the catalog pins oats.okf
176
+ 5.7.0 and oats.framework 1.16.4. On the review host of a workspace's
177
+ harvest-review trigger, re-review each knowledge PR parked on
178
+ `okf-needs-human` as its notes say.
179
+ - **[0.69.5](release-notes/v0.69.5.md#upgrade):** the catalog pins oats.okf
180
+ 5.6.0 and oats.cloning 1.1.0, which require OATS >=0.69.2. Every host that
181
+ shares a workspace runs OATS 0.69.2 or later before any of them syncs to
182
+ them; an older kernel drops their souls and refuses new spawns that compose
183
+ them. It also pins oats.aweb 1.32.1 and oats.framework 1.16.3.
169
184
  - **[0.69.2](release-notes/v0.69.2.md#upgrade):** the catalog pins
170
185
  oats.framework 1.16.1 and oats.okf 5.5.0. Sync each deployment before its
171
186
  instances on oats.okf 5.5.0 write proposals: an older harvester refuses
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.16.2 # bare version → resolves through the official catalog
58
- oats.okf: v5.5.0
57
+ oats.framework: v1.16.4 # bare version → resolves through the official catalog
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
 
61
61
  teams: # SHARED teams: the same provider team for everyone