@awebai/oats 0.69.3 → 0.69.5

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 (50) hide show
  1. package/bin/oats.mjs +68 -49
  2. package/docs/configuration.md +12 -0
  3. package/docs/desktop-cli-api.md +8 -1
  4. package/docs/execution-targets.md +25 -3
  5. package/docs/implementation.md +42 -3
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge.md +9 -6
  8. package/docs/named-test-runs.md +4 -2
  9. package/docs/official-catalog.md +6 -6
  10. package/docs/packages.md +14 -14
  11. package/docs/release-lane.md +25 -18
  12. package/docs/release-notes/v0.69.4.md +73 -0
  13. package/docs/release-notes/v0.69.5.md +146 -0
  14. package/docs/souls-and-instances.md +2 -2
  15. package/docs/tui.md +2 -1
  16. package/docs/upgrading.md +16 -5
  17. package/docs/workspaces.md +2 -2
  18. package/lib/agents-root.mjs +51 -0
  19. package/lib/automation-api.mjs +7 -0
  20. package/lib/automation-scope.mjs +35 -0
  21. package/lib/automations.mjs +2 -1
  22. package/lib/compile-cache.mjs +36 -0
  23. package/lib/core.mjs +39 -1348
  24. package/lib/deployment-path.mjs +127 -0
  25. package/lib/deployments.mjs +2 -2
  26. package/lib/drift.mjs +95 -0
  27. package/lib/hot-reads.mjs +131 -0
  28. package/lib/instance-address.mjs +21 -0
  29. package/lib/instance-lifecycle.mjs +4 -16
  30. package/lib/instance-listing.mjs +730 -0
  31. package/lib/instance-resolution.mjs +5 -166
  32. package/lib/materialize.mjs +2 -87
  33. package/lib/member-clone.mjs +188 -0
  34. package/lib/package-catalog.mjs +93 -0
  35. package/lib/packages.mjs +4 -24
  36. package/lib/reserved-launch-env.mjs +20 -0
  37. package/lib/resolved-deployment.mjs +1 -1
  38. package/lib/schedule.mjs +5 -29
  39. package/lib/semver.mjs +12 -0
  40. package/lib/servers.mjs +10 -12
  41. package/lib/session-end.mjs +3 -2
  42. package/lib/session-inspect.mjs +219 -0
  43. package/lib/soul-listing.mjs +216 -0
  44. package/lib/status-words.mjs +30 -0
  45. package/lib/version.mjs +9 -0
  46. package/lib/write-file-atomic.mjs +28 -0
  47. package/package-catalog.json +5 -5
  48. package/package.json +1 -1
  49. package/packages/tui/lib/store.mjs +7 -3
  50. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -170,21 +170,26 @@ by a full commit id, with the exact version in a comment beside it:
170
170
 
171
171
  A tag is the action owner's to move, and a commit is not: the code that runs
172
172
  with the publishing rights is the code that was read. `build-installers.yml`
173
- runs the same installer steps, so it names the same commits. Every other
173
+ runs the same installer steps, so it names the same commits. So does
174
+ `tui-macos.yml`, the TUI's tests on macOS at pull-request time, by the release
175
+ lane's call of 2026-10-27: it runs a branch's code on the release's own
176
+ actions, and its run is that pull request's macOS evidence, so it names them
177
+ at the commits that were read
178
+ ([Implementation](implementation.md#the-tuis-tests-on-macos)). Every other
174
179
  workflow keeps tags (`actions/checkout@v4`): nothing is published from them.
175
180
 
176
181
  `test/workflow-no-cache.test.mjs` holds this. Its table of the actions that
177
- were read has a row for each action: `action`, `id`, `version`. In the two files
178
- every `uses:` is a row's id, the same action is the same id in both, and the
179
- comment beside an id is the row's version. In every other workflow a `uses:`
180
- is the major of a row's version.
182
+ were read has a row for each action: `action`, `id`, `version`. In the three
183
+ files every `uses:` is a row's id, the same action is the same id in all of
184
+ them, and the comment beside an id is the row's version. In every other
185
+ workflow a `uses:` is the major of a row's version.
181
186
 
182
187
  **An id is moved by a pull request, reviewed like any change to that
183
- workflow.** It changes these together, and nothing else in the two workflow
188
+ workflow.** It changes these together, and nothing else in the three workflow
184
189
  files:
185
190
 
186
191
  - the id and the version comment, on every `uses:` line of that action in
187
- `release.yml` and `build-installers.yml`;
192
+ `release.yml`, `build-installers.yml` and `tui-macos.yml`;
188
193
  - the action's row in the table.
189
194
 
190
195
  **The id is read from an exact version tag of the action's own repository**
@@ -216,21 +221,23 @@ and packages it depends on, and what its entry points call of a cache.
216
221
  needs `package-manager-cache: false` on every step. The test takes the
217
222
  version of an id from the row, so it refuses a step without it.
218
223
 
219
- **The two files name their runners by version too** (`ubuntu-24.04`, as they
220
- name `macos-14`), never by a label that GitHub moves to another system by
221
- itself (`ubuntu-latest`). The Linux installers are built on that runner, and
222
- what they need of a system follows the system that built them.
224
+ **`release.yml` and `build-installers.yml` name their runners by version
225
+ too** (`ubuntu-24.04`, as they name `macos-14`), never by a label that GitHub
226
+ moves to another system by itself (`ubuntu-latest`). The Linux installers are
227
+ built on that runner, and what they need of a system follows the system that
228
+ built them.
223
229
  `pull-request.yml` keeps `ubuntu-latest` on purpose: when the label moves, a
224
230
  break on the new system shows in pull-request CI first and not at a release.
225
231
 
226
- The labels the two files may name are a list beside the table of actions in
227
- `test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and `macos-14`. Every job
228
- of the two files runs on a label of that list, and both files build on the
229
- same Linux. A label is added to the list by whoever decides the runner, as an
230
- action's row is by whoever read it.
232
+ The labels `release.yml` and `build-installers.yml` may name are a list beside
233
+ the table of actions in `test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and
234
+ `macos-14`. Every job of the two runs on a label of that list, and both build
235
+ on the same Linux. A label is added to the list by whoever decides the runner,
236
+ as an action's row is by whoever read it.
231
237
 
232
- **Moving the runner is a pull request** that changes the label in the two
233
- files and in the list together, and says what the installers then need.
238
+ **Moving the runner is a pull request** that changes the label in
239
+ `release.yml`, `build-installers.yml` and the list together, and says what the
240
+ installers then need.
234
241
 
235
242
  **What the Linux installer needs today**, to compare with at the next move.
236
243
  Read from `oats-desktop-0.52.0-linux-amd64.deb`, built on `ubuntu-24.04`
@@ -0,0 +1,73 @@
1
+ # OATS 0.69.4
2
+
3
+ Unreleased
4
+
5
+ 0.69.4 ships the new coordination skills. Finished instances retire
6
+ automatically, coordinated between agents without a human
7
+ (oats.engineering 1.17.2). An overrun maintainer gets an overflow seat. And
8
+ oats.core says a soul's capabilities can call for a spawn (oats.framework
9
+ 1.16.2). There is no kernel or Desktop change beyond the version.
10
+
11
+ ## Upgrade
12
+
13
+ - **Install the Desktop first and the CLI second,** as
14
+ [Upgrading](../upgrading.md) says. The 0.69.4 Desktop accepts OATS CLIs
15
+ `>=0.26.0 <0.70.0`.
16
+ - **Package moves:** the official catalog pins oats.framework 1.16.2 and
17
+ oats.engineering 1.17.2 (Provider updates, below). A deployment takes them
18
+ with `oats sync`.
19
+ - **Running instances keep the skills they were spawned with.** New spawns
20
+ get the new skills. A running instance is stopped first, moved with
21
+ `oats instance upgrade`, then started again (`oats session start`).
22
+
23
+ ## Changed
24
+
25
+ - **oats.core: spawning a child your capabilities call for needs no human.**
26
+ `/oats-operate` and `/oats-souls` said to spawn only when your task or your
27
+ human asks (or a documented workflow requires it), and to ask your human
28
+ when a relation is unclear. They now also admit your soul's capabilities, as
29
+ the "You run on OATS" block already does (a developer spawning its
30
+ reviewer, an expert its developers), and send a question about an unclear
31
+ relation to your parent or the agent that gave you the task, and to your
32
+ human only when no agent can say. A capability that spawns its own helpers
33
+ no longer reads as needing a human for it.
34
+
35
+ ## Provider updates
36
+
37
+ - **oats.engineering 1.17.2: finished instances retire automatically, and an
38
+ overrun maintainer gets an overflow seat.** The catalog and this workspace
39
+ pin `oats.engineering: v1.17.2`. The floor is unchanged.
40
+ - **Automatic retirement** (oats-engineering#28). An instance is finished
41
+ when three things hold:
42
+ - its PRs are merged and green, or closed (handed back is not landed);
43
+ - nothing waits on it;
44
+ - its final harvest is launched.
45
+
46
+ It then sends its parent a done line, and its parent retires it after
47
+ checking that the work tree is clean and pushed and that nothing is
48
+ attached, without asking or telling a human. A developer retires its
49
+ reviewer, an expert its developers, a maintainer the leads it spawned. An
50
+ instance with no OATS parent retires itself. Maintainers are standing
51
+ seats and are never retired this way.
52
+ - **Overflow seat** (oats-engineering#29). A maintainer with more than 5
53
+ efforts of its own in flight spawns one overflow seat as its child. The
54
+ seat drives the new intake up to hand-back. It holds no entry on the lane
55
+ map, and merges, second reads and sign-offs stay with its parent.
56
+ - 1.17.1 and 1.17.2 fix two lines of 1.17.0. An instance with no parent
57
+ retires itself with `oats retire "$OATS_INSTANCE" --self`, because the
58
+ kernel requires the name. The harvest condition names no knowledge-layer
59
+ command: your knowledge layer says whether you have a harvest duty.
60
+ - **Upgrade:** `oats sync` locks it. New spawns get it, and a stopped home
61
+ moves to it with `oats instance upgrade`.
62
+
63
+ - **oats.framework 1.16.2: oats.core 2.9.1.** oats.core's `/oats-operate`
64
+ and `/oats-souls` now state spawning authority the way its "You run on
65
+ OATS" inject already does. You spawn when your task, your human or your
66
+ soul's capabilities say so, so a developer spawning its reviewer, or an
67
+ expert its developers, needs no human. When a relation is unclear, ask
68
+ your parent or the agent that gave you the task first, and your human
69
+ only when no agent can say (#1621). This is text only. The floors are
70
+ unchanged, and the other capabilities are unchanged.
71
+ - **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
72
+ `oats.framework: v1.16.2`. New spawns get it, and a stopped home moves with
73
+ `oats instance upgrade`, from OATS 0.68.0.
@@ -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)).
@@ -420,8 +420,8 @@ proposes promotions by pull request. See [knowledge](knowledge.md).
420
420
 
421
421
  ### Spawning and coordinating with other agents
422
422
 
423
- OATS agents can run `oats spawn` when their instructions or the
424
- human ask them to create another expert instance. The spawned agent is another
423
+ OATS agents can run `oats spawn` when their task, their human or their
424
+ soul's capabilities call for another instance. The spawned agent is another
425
425
  full OATS instance, with its own soul, home, worktree, and lifecycle.
426
426
 
427
427
  Spawn lineage is **explicit** and relation-based:
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
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.3** ([release notes](release-notes/v0.69.3.md)).
10
- The 0.69.3 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.5** ([release notes](release-notes/v0.69.5.md)).
10
+ The 0.69.5 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.3,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.5,** 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.3 first
23
- npm install -g @awebai/oats@0.69.3 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.5 first
23
+ npm install -g @awebai/oats@0.69.5 # 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,11 @@ 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.5](release-notes/v0.69.5.md#upgrade):** the catalog pins oats.okf
176
+ 5.6.0 and oats.cloning 1.1.0, which require OATS >=0.69.2. Every host that
177
+ shares a workspace runs OATS 0.69.2 or later before any of them syncs to
178
+ them; an older kernel drops their souls and refuses new spawns that compose
179
+ them. It also pins oats.aweb 1.32.1 and oats.framework 1.16.3.
169
180
  - **[0.69.2](release-notes/v0.69.2.md#upgrade):** the catalog pins
170
181
  oats.framework 1.16.1 and oats.okf 5.5.0. Sync each deployment before its
171
182
  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.1 # bare version → resolves through the official catalog
58
- oats.okf: v5.5.0
57
+ oats.framework: v1.16.3 # bare version → resolves through the official catalog
58
+ oats.okf: v5.6.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
@@ -0,0 +1,51 @@
1
+ /** The agents root a command works in: found by walking up from a directory (findRoot), or checked
2
+ * where one is named (ensureRoot), and its canonical spelling. A leaf (awebai/oats#1630): the hot reads
3
+ * resolve their scope without loading core.mjs, which re-exports these. */
4
+ import { existsSync, lstatSync } from "node:fs";
5
+ import { resolve, dirname, join, basename } from "node:path";
6
+ import { resolvedDeployment } from "./resolved-deployment.mjs";
7
+ import { oatsError } from "./errors.mjs";
8
+ import { canonicalDeploymentPath } from "./deployment-path.mjs";
9
+
10
+ // ---------- root discovery ----------
11
+ /** Closest agents/ walking up from `cwd`. A deployment whose agents/ was never
12
+ * created has no root here; ensureRoot names the remedy. */
13
+ export function findRoot(cwd = process.cwd()) {
14
+ if (process.env.PI_AGENTS_ROOT) return resolve(process.env.PI_AGENTS_ROOT);
15
+ let d = resolve(cwd);
16
+ while (true) {
17
+ if (basename(d) === "agents" && lstatSync(d).isDirectory()) return d;
18
+ const candidate = join(d, "agents");
19
+ if (existsSync(candidate) && lstatSync(candidate).isDirectory()) return candidate;
20
+ const parent = dirname(d);
21
+ if (parent === d) return undefined;
22
+ d = parent;
23
+ }
24
+ }
25
+
26
+ /** The canonical deployment root — where instance homes belong. */
27
+ export function canonicalAgentsRoot(root) { return canonicalDeploymentPath(root); }
28
+ export function ensureRoot(cwd) {
29
+ const root = findRoot(cwd);
30
+ if (!root) {
31
+ const from = resolve(cwd ?? process.cwd());
32
+ // Workspace model: an oats-local.yaml above `from` IS a deployment whose instance
33
+ // root (<deployment>/agents/) was never created — name that remedy, not a v1 verb.
34
+ let localDeployment = null;
35
+ for (let d = from; ; d = dirname(d)) { if (existsSync(join(d, "oats-local.yaml"))) { localDeployment = d; break; } if (dirname(d) === d) break; }
36
+ if (localDeployment) {
37
+ throw oatsError("E_NO_DEPLOYMENT",
38
+ `no instance root walking up from ${from}: ${join(localDeployment, "oats-local.yaml")} names this deployment but ${join(localDeployment, "agents")} does not exist — mkdir ${join(localDeployment, "agents")} (or run \`oats sync --dir ${localDeployment}\`, which creates it)`,
39
+ { from, looked: ["agents/"], deployment: localDeployment, local: join(localDeployment, "oats-local.yaml"), remedy: `mkdir ${join(localDeployment, "agents")} (or run oats sync)` });
40
+ }
41
+ throw oatsError("E_NO_DEPLOYMENT",
42
+ `no deployment found walking up from ${from}: no agents/ directory — run from the deployment (where oats-local.yaml lives; \`oats onboard\` creates one), or set PI_AGENTS_ROOT`,
43
+ { from, looked: ["agents/"] });
44
+ }
45
+ // Deployment root ≠ invocation CWD: homes always land in the primary checkout.
46
+ const canonical = canonicalAgentsRoot(root);
47
+ resolvedDeployment(dirname(canonical), { canonical: true });
48
+ return canonical;
49
+ }
50
+
51
+ export function workspaceOf(root) { return dirname(root); }
@@ -0,0 +1,7 @@
1
+ /** The API versions of the automation answers (`scheduleApi` and `automationsApi` in `version --json`).
2
+ * A leaf (awebai/oats#1630): `oats version` reads them without loading schedule.mjs or automations.mjs,
3
+ * which re-export them. */
4
+
5
+ export const SCHEDULE_API = 2;
6
+
7
+ export const AUTOMATIONS_API = 1;
@@ -0,0 +1,35 @@
1
+ /** scopeAutomations: the triggers and schedules a deployment declares, read with the clone each one
2
+ * needs, and childEnv, the environment a scheduled job runs with. A leaf (awebai/oats#1630):
3
+ * `oats workspace status` reads the automation scope without loading schedule.mjs and core.mjs;
4
+ * schedule.mjs imports both and re-exports them. */
5
+ import { loadLocal } from "./workspace.mjs";
6
+ import { resolveMemberClone } from "./member-clone.mjs";
7
+ import { automationContext } from "./automations.mjs";
8
+ import { RESERVED_LAUNCH_ENV } from "./reserved-launch-env.mjs";
9
+
10
+ /** The environment a scheduler-launched oats child runs with: the caller's
11
+ * frozen instance identity and capability snapshot removed (a tick or run-now
12
+ * may be invoked from inside an unrelated instance; dispatch belongs to the
13
+ * job's cwd and explicit selectors, never to that caller), host configuration
14
+ * such as OATS_HOME_DIR and credentials kept. Shared by command and spawn jobs. */
15
+ export function childEnv() {
16
+ const env = { ...process.env };
17
+ for (const key of [...RESERVED_LAUNCH_ENV,
18
+ "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
19
+ "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
20
+ "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
21
+ "OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_TEAMS", "OATS_TEAMS_SOURCE", "OATS_TRIGGER_EVENT_FILE",
22
+ "OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN",
23
+ ]) delete env[key];
24
+ return env;
25
+ }
26
+
27
+ /** One scope's automations context (lib/automations.mjs automationContext) with its oats-local.yaml;
28
+ * an unreadable oats-local.yaml means no workspace automations (the local jobs still run). */
29
+ export function scopeAutomations(ws, { io, now = new Date(), refresh = false, cache = new Map() } = {}) {
30
+ let local = null;
31
+ try { local = loadLocal(ws).local; } catch { local = null; }
32
+ const clonePathOf = (repoKey) => resolveMemberClone({ deployment: ws, soulEntry: { repoKey }, local });
33
+ const ctx = automationContext(ws, { local, io: { ...(io || {}), childEnv }, now, refresh, cache, clonePathOf });
34
+ return Object.assign(ctx, { ws, local });
35
+ }
@@ -40,8 +40,9 @@ import YAML from "yaml";
40
40
  import { parseConfigData } from "./config-data.mjs";
41
41
  import { editLocal } from "./local-edit.mjs";
42
42
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
43
+ import { AUTOMATIONS_API } from "./automation-api.mjs";
44
+ export { AUTOMATIONS_API } from "./automation-api.mjs";
43
45
 
44
- export const AUTOMATIONS_API = 1;
45
46
  export const SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
46
47
  export const PLACEMENT_REASONS = Object.freeze(["host-unnamed", "assigned-elsewhere", "owner-mismatch", "untrusted"]);
47
48
  /** The kinds, in the order the snapshot keeps them (`triggers`, `schedules`). */
@@ -0,0 +1,36 @@
1
+ /** Node's compile cache for the CLI (awebai/oats#1630): V8 keeps the code it compiled for the
2
+ * kernel's modules, so a command does not recompile them all on every run. Kernel-private, not
3
+ * exported from `./core` and not a contract: `bin/oats.mjs` calls enableCliCompileCache before it
4
+ * imports the kernel (only the dependency-free lib/hot-reads.mjs is parsed before), and in-process
5
+ * consumers never call it (they run in their own processes).
6
+ *
7
+ * - The cache is `$OATS_HOME_DIR/compile-cache` (`~/.oats/compile-cache`), made 0700 here: Node's
8
+ * default, `os.tmpdir()/node-compile-cache`, is shared by every user of the computer, and Node
9
+ * would make the directory 0755. Node keeps one subdirectory per Node version under it; the whole
10
+ * directory is safe to delete at any time.
11
+ * - The caller's choice wins, and Node applies it before any of this runs: with NODE_COMPILE_CACHE
12
+ * (another place) or NODE_DISABLE_COMPILE_CACHE (none) set, nothing is made or written under
13
+ * OATS_HOME_DIR. There is no OATS variable for it.
14
+ * - Never in the way: a Node without enableCompileCache (22.0), a directory that cannot be made or
15
+ * written, any throw, is simply no cache, with nothing printed. NODE_COMPILE_CACHE is never set in
16
+ * the environment, so hooks and other children inherit only what the caller gave.
17
+ * Node built-ins only, so that it parses nothing of the kernel. */
18
+ import { mkdirSync } from "node:fs";
19
+ import module from "node:module";
20
+ import { homedir } from "node:os";
21
+ import { join } from "node:path";
22
+
23
+ export function enableCliCompileCache() {
24
+ // A named import would be a link-time SyntaxError on a Node that lacks it.
25
+ if (typeof module.enableCompileCache !== "function") return;
26
+ // As Node reads them: any NODE_DISABLE_COMPILE_CACHE disables, even "" or "0"; an empty
27
+ // NODE_COMPILE_CACHE is none.
28
+ if (process.env.NODE_COMPILE_CACHE || process.env.NODE_DISABLE_COMPILE_CACHE !== undefined) return;
29
+ try {
30
+ const dir = join(process.env.OATS_HOME_DIR || join(homedir(), ".oats"), "compile-cache");
31
+ // Made here first, also because Node 22 never returns from a directory it cannot make.
32
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
33
+ // The string form: Node 22 takes no options object.
34
+ module.enableCompileCache(dir);
35
+ } catch { /* no cache */ }
36
+ }