@awebai/oats 0.51.0 → 0.53.0

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 (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
@@ -0,0 +1,298 @@
1
+ # Upgrading OATS on a host
2
+
3
+ Upgrading OATS means three things, in this order, on each host:
4
+
5
+ 1. **The CLI** (`@awebai/oats`, the kernel).
6
+ 2. **The pi bridge** (`@awebai/oats-pi`), in every pi folder the host's
7
+ deployments launch pi with: `oats update`, in each deployment.
8
+ 3. **A check of each deployment**: `oats doctor`.
9
+
10
+ The kernel and the bridge are published together, from one version tag, and
11
+ must be at the same version: a pi session with an older bridge runs old
12
+ extension code against a new kernel. A host that launches no pi instance has
13
+ no bridge, and step 2 has nothing to move.
14
+
15
+ **A release's own steps are in its notes.** Read the `## Upgrade` section of
16
+ every version between yours and the new one in the
17
+ [release notes](release-notes/) first: it says what to do before the CLI
18
+ changes, and what else must change with it (the Desktop, another tool, a
19
+ package pin). This page is the part that is the same for every release.
20
+
21
+ **Package versions are a different thing.** `oats update` moves the CLI and
22
+ the bridge, never a package. A deployment's capabilities come from the
23
+ packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
24
+ ([Packages](packages.md)).
25
+
26
+ ## The steps
27
+
28
+ ```sh
29
+ npm install -g @awebai/oats # 1. the CLI
30
+ oats update # 2. in a deployment: the plan, then it asks before it runs
31
+ oats doctor # 3. in the same deployment
32
+ ```
33
+
34
+ Run steps 2 and 3 in every deployment on the host, or name one from anywhere
35
+ with `oats update --dir <deployment>`. Then restart the pi sessions that were
36
+ running: a session keeps the bridge it loaded when it started.
37
+
38
+ In a terminal, `oats update` shows its plan and asks before it runs anything.
39
+ Without a terminal (a script, an agent's shell) it runs only with `--yes`.
40
+ `oats update --check` shows the plan and runs nothing.
41
+
42
+ `oats update` also does step 1: when npm lists a newer `@awebai/oats`, its
43
+ plan starts with that install, and the bridges move to that same version in
44
+ the same run.
45
+
46
+ **`oats update` only moves forward.** It never installs an older CLI or an
47
+ older bridge than the one in place:
48
+
49
+ - **The CLI** is installed only when the version npm lists is newer than the
50
+ installed one. When the installed CLI is ahead of it (a checkout, a build
51
+ that is not published yet), the plan says so in one line and holds no step
52
+ for the CLI.
53
+ - **The bridges** are brought to the version the CLI has after the run: the
54
+ one npm lists when the CLI moves to it, the installed one otherwise. A
55
+ bridge ahead of that version is left alone.
56
+
57
+ Versions are compared as semver, so a prerelease is below its release:
58
+ `0.53.0-rc.1` is ahead of `0.52.0` and behind `0.53.0`. Build metadata makes
59
+ no other version: a local build `0.53.0+build.1` is `0.53.0`, and nothing is
60
+ installed over it.
61
+
62
+ ## Which pi folders
63
+
64
+ pi keeps its packages in one folder: `~/.pi/agent`, or the folder
65
+ `PI_CODING_AGENT_DIR` names. A deployment can launch pi with several folders,
66
+ so `oats update` and `oats doctor` look at each of these:
67
+
68
+ - **the default**, `~/.pi/agent`;
69
+ - **this shell's**, when `PI_CODING_AGENT_DIR` is set where the command runs;
70
+ - **each launch configuration's**: the `PI_CODING_AGENT_DIR` in the `env` of
71
+ every `launch-configs` entry of the deployment's `oats-local.yaml` whose
72
+ harness is `pi` ([Configuration](configuration.md#launch-configurations)).
73
+ The value is a path, or a `{fromEnv: NAME}` reference read from the
74
+ environment the command runs in. A leading `~` is your home.
75
+
76
+ Two names for one folder (two configurations, a configuration that names the
77
+ default, a symbolic link) are one folder, listed once with every reason it is
78
+ looked at.
79
+
80
+ The bridge of a folder is read from
81
+ `<folder>/npm/node_modules/@awebai/oats-pi/package.json`, where pi installs
82
+ it.
83
+
84
+ **The deployment** is the one at or above the directory the command runs in,
85
+ or the one `--dir` names. With no deployment there, `oats update` still moves
86
+ the default folder and this shell's, and says, in the plan and again as its
87
+ last line, that no launch configuration was looked at. It says the same about
88
+ a deployment whose `oats-local.yaml` it cannot load; `oats doctor` reports
89
+ what is wrong with that file. An explicit `--dir` with no deployment at or
90
+ above it is refused.
91
+
92
+ **Folders that are not looked at.** Only the deployment's current
93
+ `launch-configs` are read. An instance home records the launch it was created
94
+ with, and keeps it when the configuration is later changed or removed; a
95
+ folder named only by such a record is not in the list. Move its bridge with
96
+ the command under [By hand](#by-hand).
97
+
98
+ ## What `oats update` does in each folder
99
+
100
+ The plan lists every folder with the bridge found in it and one of these:
101
+
102
+ | The plan says | When | What happens |
103
+ |---|---|---|
104
+ | `move to <version>` | the bridge is at an older version | `pi install` runs there |
105
+ | `left alone, already at <version>` | the bridge is at that version | nothing |
106
+ | `left alone, ahead of <version>` | the bridge is at a newer version | nothing: a bridge is never moved back |
107
+ | `no bridge` | the folder does not exist, or holds no bridge | nothing |
108
+ | `not touched`, with a reason | see below | nothing; the plan prints the command to run there |
109
+
110
+ `oats update` moves a bridge. It never creates a folder and never installs a
111
+ first bridge: a spawn's own package check says when a capability needs one
112
+ that is missing.
113
+
114
+ A folder is **not touched** when:
115
+
116
+ - **it does not resolve**: a `{fromEnv: NAME}` whose variable is not set where
117
+ the command runs, or a path that is not absolute. Run `oats update` again
118
+ where the variable is set, or the printed command.
119
+ - **its bridge cannot be read** (a `package.json` that does not parse).
120
+ - **only launch configurations with their own `executable` name it.** A
121
+ wrapper is your program: `oats update` never runs one. The plan prints the
122
+ install command with that executable; when the configurations name several
123
+ executables, one command for each, with the configurations it is for. A
124
+ folder that the default, this shell or a configuration without an
125
+ `executable` also names is moved with the plain `pi`.
126
+
127
+ For a folder it moves, `oats update` runs the `pi` found on `PATH`, with
128
+ `PI_CODING_AGENT_DIR` set to that folder:
129
+
130
+ ```sh
131
+ PI_CODING_AGENT_DIR=<folder> npm_config_prefer_online=true pi install npm:@awebai/oats-pi@<version>
132
+ ```
133
+
134
+ For the default folder the variable is left out, unless this shell sets one.
135
+
136
+ ## Nothing is removed before its replacement is known to install
137
+
138
+ The move is one `pi install` over the installed bridge. pi replaces the
139
+ settings entry and the files of a package it already holds, and an install
140
+ that fails leaves the old ones in place. There is no `pi uninstall`.
141
+
142
+ Before any step runs, the CLI's own install included, `oats update` asks the
143
+ registry for the bridge's exact version, with npm told to revalidate its
144
+ cache (`npm view @awebai/oats-pi@<version> version --prefer-online`). A new
145
+ version is listed a few minutes after it is published, and the kernel's
146
+ listing says nothing about the bridge's. If the version does not resolve,
147
+ the update stops with nothing changed and every bridge in place: run it again
148
+ in a few minutes. The same setting goes to pi's own npm for the install
149
+ (`npm_config_prefer_online=true`). `--check` does not make this lookup: it
150
+ shows what would run, and the run looks again.
151
+
152
+ When the installed CLI is ahead of the registry, the version asked for is
153
+ the installed one, and it may not be published at all. The plan does not
154
+ know: it makes no lookup. So when it lists a move to that version, it says
155
+ under the folders what the move depends on:
156
+
157
+ ```text
158
+ A bridge moves to 0.53.0 only if @awebai/oats-pi@0.53.0 is published: the installed kernel is ahead of the registry's 0.52.0, and a run checks that before any step.
159
+ ```
160
+
161
+ When the run's lookup then does not find the version, the message says that
162
+ the installed kernel is ahead of the registry, instead of telling you to wait
163
+ a few minutes.
164
+
165
+ **What npm answers is checked before it is used.** Both lookups must answer
166
+ one version and nothing else: three numbers and an optional prerelease, on
167
+ one line. Any other answer (nothing, several lines, a list, text around the
168
+ version) stops the update before any step, with nothing changed. The message
169
+ names the lookup and shows the answer cut to 80 characters, with its control
170
+ characters shown as escapes or replaced. Run `oats update` again.
171
+
172
+ npm's own error output of a lookup is not passed to your terminal either.
173
+ When the first lookup fails, the message says how it ended (`exit 1`) and
174
+ then what npm said, cut to 300 characters and made safe the same way.
175
+
176
+ The update stops at the first step that fails. Its message names the folder
177
+ and the exact step to run again, says what that folder holds now (the old
178
+ bridge still, or no bridge), and lists the folders it did not reach. A step
179
+ that ends without an error but leaves another version in the folder is a
180
+ failure too. Run the printed step, then `oats update` again: folders already
181
+ at the version are left alone.
182
+
183
+ ## What `oats doctor` reports
184
+
185
+ `oats doctor` prints one warning per folder whose bridge is not the kernel's
186
+ version, naming the folder and why it is looked at:
187
+
188
+ ```text
189
+ WARNING: version skew — kernel 0.53.0, pi bridge 0.52.0 in /srv/pi-work (launch configuration work); run `oats update` (they publish in lockstep)
190
+ ```
191
+
192
+ A bridge ahead of the kernel is a skew too. `oats update` moves no bridge
193
+ back, and `oats doctor` does not ask the registry, so the warning says what
194
+ ends the skew:
195
+
196
+ ```text
197
+ WARNING: version skew — kernel 0.52.0, pi bridge 0.53.0 in /srv/pi-work (launch configuration work); the bridge is ahead of the kernel, and `oats update` never moves a bridge back. The skew ends when the kernel is at 0.53.0 (`oats update` moves it once npm lists that version), or when the kernel's bridge is installed there by hand (docs/upgrading.md, "By hand")
198
+ ```
199
+
200
+ It also warns about a folder it could not look at (one that does not
201
+ resolve, or a bridge that cannot be read). A folder that does not exist or
202
+ holds no bridge is not a skew, and it says nothing about it. The warnings are
203
+ in the text output only; `oats doctor --json` does not carry them.
204
+
205
+ ## After a change of Node version
206
+
207
+ Two paths are written into things that outlive a command: the kernel's, and
208
+ the `node` that runs it. A new Node version can leave either behind.
209
+
210
+ **The kernel's path.** The CLI is an npm global package: it is installed
211
+ under npm's global prefix (`npm prefix -g`).
212
+
213
+ - **The prefix is outside the Node install.** The kernel's path does not
214
+ change with the Node version: the CLI needs no reinstall.
215
+ - **The prefix is the Node version's own directory**, the usual layout of a
216
+ version manager (mise, nvm, asdf, fnm). Every Node version then has its own
217
+ global packages: a new version has no `oats`, and removing the old version
218
+ removes the kernel with it. Four things name that kernel by its path: each
219
+ instance home's own `oats` (`<home>/.oats/bin/oats`), the Claude Code hooks
220
+ of a Claude instance, the host timer's unit, and what `oats setup` installs
221
+ (the turn record's capture hooks and its watcher, which name the capture
222
+ script inside the kernel). OATS cannot make a path inside a Node version
223
+ outlast that version.
224
+
225
+ Both layouts can exist on one host: check the prefix in the shell that
226
+ installs the CLI.
227
+
228
+ **The `node`'s path**, whatever the prefix. The Claude Code hooks of a
229
+ Claude instance, the host timer's unit and what `oats setup` installs also
230
+ record the `node` that runs them, by one rule
231
+ ([the node a hook writes down](capabilities.md#the-node-a-hook-writes-down)):
232
+
233
+ - **On Homebrew**, the `opt` link (`<prefix>/opt/node/bin/node`) when it is
234
+ the `node` running the kernel. `brew upgrade node` repoints it, so the
235
+ recorded path outlasts the upgrade: the hooks, the timer and the capture
236
+ watcher need nothing done.
237
+ - **Otherwise**, a `node` on `PATH` that is the same file as the one running
238
+ the kernel. With mise that is the version's own install, which does not
239
+ outlast the version (other version managers were not measured).
240
+ - **When there is neither**, the path of the `node` as it is. A spawn, a
241
+ start, `oats schedule host install` and `oats setup` then warn that it is
242
+ not stable.
243
+
244
+ **What `oats setup` records is in your own files, not in an instance home:**
245
+ the capture hooks (`Stop` and `SessionEnd`) in every `~/.claude*/settings.json`
246
+ of the user who ran it, and the capture watcher's unit
247
+ (`~/Library/LaunchAgents/ai.aweb.turn-record-capture.plist` on macOS,
248
+ `~/.config/systemd/user/turn-record-capture.service` on Linux). No spawn,
249
+ start or restart writes them: only `oats setup` run again does, and it
250
+ replaces its own hooks and unit, it does not add a second one.
251
+
252
+ Once the recorded `node` no longer exists (an old version removed under a
253
+ version manager, for example), the hooks fail without a message, so the
254
+ instance stops reporting that it waits on you, and
255
+ `oats schedule host status` reports `node-missing`. The capture hooks then
256
+ fail at every stop of every Claude Code session of that user, and launchd or
257
+ systemd keeps restarting a watcher that cannot start.
258
+
259
+ **A home spawned with an oats.core that does not read `OATS_NODE_BIN`** does
260
+ not follow the rule. Its hooks record the path of the `node` its hook ran
261
+ under, which on Homebrew is the versioned keg
262
+ (`…/Cellar/node/<version>/bin/node`), and a start writes that again, because
263
+ a start runs the copy of oats.core in the home. `brew upgrade node` removes
264
+ the keg at once, so such a home needs the restart of step 2 after every Node
265
+ upgrade, until it is respawned.
266
+
267
+ So after moving to another Node version, and before removing the old one,
268
+ wherever a recorded path does not outlast it:
269
+
270
+ 1. Where the prefix is the version's own directory, install the CLI in the
271
+ new version: `npm install -g @awebai/oats`.
272
+ 2. Restart the instances, from a shell on the new version
273
+ (`oats session restart --home <home>`). A start writes the home's `oats`
274
+ and its Claude Code hooks again
275
+ ([Configuration](configuration.md#launch-configurations)).
276
+ 3. On a host that runs schedules, run `oats schedule host install` again,
277
+ from your own shell, not from an instance home. Without it,
278
+ `oats schedule host status` reports `oats-bin-missing` or `node-missing`
279
+ once the old version is removed
280
+ ([Schedules](schedules.md#the-host-timers-unit)).
281
+ 4. On a host where `oats setup` was run, run `oats setup` again, as the same
282
+ user and from your own shell. `oats setup --dry-run` prints the `node` it
283
+ would record and changes nothing.
284
+
285
+ Until the old version is removed, the instances and the timer keep running
286
+ what it holds.
287
+
288
+ ## By hand
289
+
290
+ In any pi folder, with the `pi` that is launched with it:
291
+
292
+ ```sh
293
+ PI_CODING_AGENT_DIR=<folder> pi install npm:@awebai/oats-pi@<the CLI's version>
294
+ ```
295
+
296
+ `oats version` prints the CLI's version. For the default folder, leave the
297
+ assignment out only when your shell does not set `PI_CODING_AGENT_DIR`;
298
+ when it does, name the folder: `PI_CODING_AGENT_DIR="$HOME/.pi/agent"`.
@@ -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.9.1 # bare version → resolves through the official catalog
58
- oats.okf: v5.0.1
57
+ oats.framework: v1.9.4 # bare version → resolves through the official catalog
58
+ oats.okf: v5.0.3
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
@@ -198,7 +198,7 @@ as `confirmed` or the reason it is not:
198
198
  | `not-listed` | the workspace does not list the repo |
199
199
  | `no-backlink` | no (or invalid) `oats-membership.yaml` at the member's default branch |
200
200
  | `backlink-elsewhere` | the member names a different workspace (a case-only difference is flagged: repo paths are case-sensitive identities) |
201
- | `cannot-read` | the operator cannot read the member (auth / not-found / network / timeout / killed: the system killed git, e.g. out of memory), or this machine's remote cache could not be written (cache) |
201
+ | `cannot-read` | the operator cannot read the member (auth / not-found / network / timeout / killed: the system killed git, e.g. out of memory / unknown: git failed for a reason the kernel cannot name), or this machine's remote cache could not be written (cache) |
202
202
 
203
203
  An unconfirmed member contributes nothing but its row: its souls are invisible,
204
204
  its capabilities unresolvable (`E_NOT_A_MEMBER` / `E_MEMBERSHIP_UNCONFIRMED`).
@@ -38,6 +38,7 @@ import { dirname, join } from "node:path";
38
38
  import { recordLocalInput } from "./local-inputs.mjs";
39
39
  import YAML from "yaml";
40
40
  import { parseConfigData } from "./config-data.mjs";
41
+ import { editLocal } from "./local-edit.mjs";
41
42
 
42
43
  export const AUTOMATIONS_API = 1;
43
44
  export const SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
@@ -361,29 +362,28 @@ function refreshViaCli(dep, io) {
361
362
  // ------------------------------------------------------------ opting out here
362
363
 
363
364
  /** Add or remove `<member>/<id>` in oats-local.yaml `<kind>s.disabled` (`triggers.disabled` or
364
- * `schedules.disabled`), keeping the rest of the file (comments included) as written.
365
- * `validate(value)` → problems, checked before any write. */
366
- export function setDisabledHere(localPath, kind, qid, disabled, { validate } = {}) {
365
+ * `schedules.disabled`), through the one path that rewrites that file (lib/local-edit.mjs editLocal:
366
+ * the deployment's local lock, the file as it is under it, the local schema, a rename): the rest of the
367
+ * file stays as written, comments included, and no other writer's change is dropped.
368
+ * `ctx`: { deployment, localPath }. → { changed, disabled } (the list now). */
369
+ export function setDisabledHere(ctx, kind, qid, disabled) {
367
370
  const section = `${kind}s`;
368
- const text = readFileSync(localPath, "utf8");
369
- const doc = YAML.parseDocument(text, { keepSourceTokens: true });
370
- if (doc.errors?.length) throw automationError("E_WORKSPACE_SCHEMA", `${localPath}: ${doc.errors[0].message}`);
371
- const current = doc.getIn([section, "disabled"]);
372
- const list = current && typeof current.toJSON === "function" ? current.toJSON() : Array.isArray(current) ? current : [];
373
- const next = disabled ? [...new Set([...list, qid])].sort() : list.filter((x) => x !== qid);
374
- if (JSON.stringify(next) === JSON.stringify(list)) return { changed: false, disabled: list };
375
- if (next.length) doc.setIn([section, "disabled"], next);
376
- else if (doc.hasIn([section, "disabled"])) {
377
- doc.deleteIn([section, "disabled"]);
378
- const rest = doc.get(section);
379
- if (rest && typeof rest.toJSON === "function" && !Object.keys(rest.toJSON() || {}).length) doc.delete(section);
380
- }
381
- const out = doc.toString();
382
- const value = parseConfigData(out, { origin: { kind: "local", path: localPath } }).value;
383
- const problems = validate ? validate(value) : [];
384
- if (problems.length) throw automationError("E_WORKSPACE_SCHEMA", `the rewritten ${localPath} would be invalid (${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}); nothing was written`);
385
- writeFileSync(localPath, out);
386
- return { changed: true, disabled: next };
371
+ let list = [];
372
+ const { changed } = editLocal(ctx, { verb: `oats ${kind} ${disabled ? "disable" : "enable"}` }, ({ doc }) => {
373
+ const current = doc.getIn([section, "disabled"]);
374
+ list = current && typeof current.toJSON === "function" ? current.toJSON() : Array.isArray(current) ? current : [];
375
+ const next = disabled ? [...new Set([...list, qid])].sort() : list.filter((x) => x !== qid);
376
+ if (JSON.stringify(next) === JSON.stringify(list)) return null;
377
+ if (next.length) doc.setIn([section, "disabled"], next);
378
+ else if (doc.hasIn([section, "disabled"])) {
379
+ doc.deleteIn([section, "disabled"]);
380
+ const rest = doc.get(section);
381
+ if (rest && typeof rest.toJSON === "function" && !Object.keys(rest.toJSON() || {}).length) doc.delete(section);
382
+ }
383
+ list = next;
384
+ return {};
385
+ });
386
+ return { changed, disabled: list };
387
387
  }
388
388
 
389
389
  // ------------------------------------------------------------ writing a workspace file