@awebai/oats 0.52.0 → 0.54.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.
- package/README.md +2 -1
- package/bin/oats.mjs +314 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
- package/docs/desktop-cli-api.md +696 -60
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +184 -12
- package/docs/integrations.md +6 -3
- package/docs/knowledge.md +2 -2
- package/docs/macos-test-runs.md +246 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +210 -6
- package/docs/release-notes/v0.53.0.md +1288 -0
- package/docs/release-notes/v0.54.0.md +142 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +239 -16
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +310 -0
- package/docs/workspaces.md +123 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +93 -4
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +569 -121
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +5 -6
- package/lib/instance-lifecycle.mjs +145 -18
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +226 -15
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +18 -5
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +404 -60
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +6 -35
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/workspace.mjs +75 -27
- package/package-catalog.json +4 -4
- package/package.json +2 -1
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/cli-adapter.mjs +16 -3
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-contract.mjs +4 -0
- package/packages/client/deployment-facts.mjs +71 -10
- package/packages/client/deployment-panel.mjs +49 -11
- package/packages/client/deployment-read-cli.mjs +7 -3
- package/packages/client/display-text.mjs +8 -2
- package/packages/client/instance-acts.mjs +46 -10
- package/packages/client/instance-events-contract.mjs +4 -2
- package/packages/client/instance-presentation.mjs +66 -2
- package/packages/client/instance-tree.mjs +23 -14
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-prompt-outcome.mjs +51 -16
- package/packages/client/lifecycle-contract.mjs +45 -4
- package/packages/client/liveness.mjs +14 -1
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/panel-views.mjs +18 -11
- package/packages/client/readiness-contract.mjs +3 -1
- package/packages/client/remote-address.mjs +34 -9
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +92 -6
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-contract.mjs +16 -4
- package/packages/client/spawn-messages.mjs +26 -3
- package/packages/client/spawn-preview-cli.mjs +8 -2
- package/packages/client/spawn-preview-contract.mjs +5 -1
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-views.mjs +39 -3
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +30 -12
- package/packages/tui/lib/actions.mjs +16 -1
- package/packages/tui/lib/client.mjs +32 -1
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +117 -46
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +44 -0
- package/packages/tui/lib/term/screen.mjs +16 -4
- package/packages/tui/lib/term/text.mjs +60 -0
- package/packages/tui/lib/term/tty.mjs +13 -3
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +230 -36
- package/packages/tui/lib/views/help.mjs +125 -13
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/skills/oats-getting-started/SKILL.md +8 -2
|
@@ -0,0 +1,310 @@
|
|
|
1
|
+
# Upgrading OATS on a host
|
|
2
|
+
|
|
3
|
+
Upgrading OATS means three things, in this order, on each host, and one
|
|
4
|
+
before them where the Desktop is installed:
|
|
5
|
+
|
|
6
|
+
0. **The Desktop**, where it is installed: the new version's, before the CLI.
|
|
7
|
+
1. **The CLI** (`@awebai/oats`, the kernel).
|
|
8
|
+
2. **The pi bridge** (`@awebai/oats-pi`), in every pi folder the host's
|
|
9
|
+
deployments launch pi with: `oats update`, in each deployment.
|
|
10
|
+
3. **A check of each deployment**: `oats doctor`.
|
|
11
|
+
|
|
12
|
+
The kernel and the bridge are published together, from one version tag, and
|
|
13
|
+
must be at the same version: a pi session with an older bridge runs old
|
|
14
|
+
extension code against a new kernel. A host that launches no pi instance has
|
|
15
|
+
no bridge, and step 2 has nothing to move.
|
|
16
|
+
|
|
17
|
+
**A release's own steps are in its notes.** Read the `## Upgrade` section of
|
|
18
|
+
every version between yours and the new one in the
|
|
19
|
+
[release notes](release-notes/) first: it says what to do before the CLI
|
|
20
|
+
changes, and what else must change with it (the Desktop, another tool, a
|
|
21
|
+
package pin). This page is the part that is the same for every release.
|
|
22
|
+
|
|
23
|
+
**Why the Desktop goes first.** A Desktop accepts a CLI up to its own minor
|
|
24
|
+
version and refuses a newer one: with the CLI moved first, the Desktop that
|
|
25
|
+
is still running lists no instance until it is replaced. The new Desktop
|
|
26
|
+
accepts the older CLI in the meantime. The CLI can move by two commands, the
|
|
27
|
+
`npm install` below and an `oats update` whose plan installs it: step 0 comes
|
|
28
|
+
before either.
|
|
29
|
+
|
|
30
|
+
**Package versions are a different thing.** `oats update` moves the CLI and
|
|
31
|
+
the bridge, never a package. A deployment's capabilities come from the
|
|
32
|
+
packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
|
|
33
|
+
([Packages](packages.md)).
|
|
34
|
+
|
|
35
|
+
## The steps
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
# 0. where the Desktop is installed: the new version's Desktop first
|
|
39
|
+
npm install -g @awebai/oats # 1. the CLI
|
|
40
|
+
oats update # 2. in a deployment: the plan, then it asks before it runs
|
|
41
|
+
oats doctor # 3. in the same deployment
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Run steps 2 and 3 in every deployment on the host, or name one from anywhere
|
|
45
|
+
with `oats update --dir <deployment>`. Then restart the pi sessions that were
|
|
46
|
+
running: a session keeps the bridge it loaded when it started.
|
|
47
|
+
|
|
48
|
+
In a terminal, `oats update` shows its plan and asks before it runs anything.
|
|
49
|
+
Without a terminal (a script, an agent's shell) it runs only with `--yes`.
|
|
50
|
+
`oats update --check` shows the plan and runs nothing.
|
|
51
|
+
|
|
52
|
+
`oats update` also does step 1: when npm lists a newer `@awebai/oats`, its
|
|
53
|
+
plan starts with that install, and the bridges move to that same version in
|
|
54
|
+
the same run. So where the Desktop is installed, step 0 comes before such an
|
|
55
|
+
`oats update` too: `oats update --check` shows whether the plan holds that
|
|
56
|
+
install, and runs nothing.
|
|
57
|
+
|
|
58
|
+
**`oats update` only moves forward.** It never installs an older CLI or an
|
|
59
|
+
older bridge than the one in place:
|
|
60
|
+
|
|
61
|
+
- **The CLI** is installed only when the version npm lists is newer than the
|
|
62
|
+
installed one. When the installed CLI is ahead of it (a checkout, a build
|
|
63
|
+
that is not published yet), the plan says so in one line and holds no step
|
|
64
|
+
for the CLI.
|
|
65
|
+
- **The bridges** are brought to the version the CLI has after the run: the
|
|
66
|
+
one npm lists when the CLI moves to it, the installed one otherwise. A
|
|
67
|
+
bridge ahead of that version is left alone.
|
|
68
|
+
|
|
69
|
+
Versions are compared as semver, so a prerelease is below its release:
|
|
70
|
+
`0.53.0-rc.1` is ahead of `0.52.0` and behind `0.53.0`. Build metadata makes
|
|
71
|
+
no other version: a local build `0.53.0+build.1` is `0.53.0`, and nothing is
|
|
72
|
+
installed over it.
|
|
73
|
+
|
|
74
|
+
## Which pi folders
|
|
75
|
+
|
|
76
|
+
pi keeps its packages in one folder: `~/.pi/agent`, or the folder
|
|
77
|
+
`PI_CODING_AGENT_DIR` names. A deployment can launch pi with several folders,
|
|
78
|
+
so `oats update` and `oats doctor` look at each of these:
|
|
79
|
+
|
|
80
|
+
- **the default**, `~/.pi/agent`;
|
|
81
|
+
- **this shell's**, when `PI_CODING_AGENT_DIR` is set where the command runs;
|
|
82
|
+
- **each launch configuration's**: the `PI_CODING_AGENT_DIR` in the `env` of
|
|
83
|
+
every `launch-configs` entry of the deployment's `oats-local.yaml` whose
|
|
84
|
+
harness is `pi` ([Configuration](configuration.md#launch-configurations)).
|
|
85
|
+
The value is a path, or a `{fromEnv: NAME}` reference read from the
|
|
86
|
+
environment the command runs in. A leading `~` is your home.
|
|
87
|
+
|
|
88
|
+
Two names for one folder (two configurations, a configuration that names the
|
|
89
|
+
default, a symbolic link) are one folder, listed once with every reason it is
|
|
90
|
+
looked at.
|
|
91
|
+
|
|
92
|
+
The bridge of a folder is read from
|
|
93
|
+
`<folder>/npm/node_modules/@awebai/oats-pi/package.json`, where pi installs
|
|
94
|
+
it.
|
|
95
|
+
|
|
96
|
+
**The deployment** is the one at or above the directory the command runs in,
|
|
97
|
+
or the one `--dir` names. With no deployment there, `oats update` still moves
|
|
98
|
+
the default folder and this shell's, and says, in the plan and again as its
|
|
99
|
+
last line, that no launch configuration was looked at. It says the same about
|
|
100
|
+
a deployment whose `oats-local.yaml` it cannot load; `oats doctor` reports
|
|
101
|
+
what is wrong with that file. An explicit `--dir` with no deployment at or
|
|
102
|
+
above it is refused.
|
|
103
|
+
|
|
104
|
+
**Folders that are not looked at.** Only the deployment's current
|
|
105
|
+
`launch-configs` are read. An instance home records the launch it was created
|
|
106
|
+
with, and keeps it when the configuration is later changed or removed; a
|
|
107
|
+
folder named only by such a record is not in the list. Move its bridge with
|
|
108
|
+
the command under [By hand](#by-hand).
|
|
109
|
+
|
|
110
|
+
## What `oats update` does in each folder
|
|
111
|
+
|
|
112
|
+
The plan lists every folder with the bridge found in it and one of these:
|
|
113
|
+
|
|
114
|
+
| The plan says | When | What happens |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| `move to <version>` | the bridge is at an older version | `pi install` runs there |
|
|
117
|
+
| `left alone, already at <version>` | the bridge is at that version | nothing |
|
|
118
|
+
| `left alone, ahead of <version>` | the bridge is at a newer version | nothing: a bridge is never moved back |
|
|
119
|
+
| `no bridge` | the folder does not exist, or holds no bridge | nothing |
|
|
120
|
+
| `not touched`, with a reason | see below | nothing; the plan prints the command to run there |
|
|
121
|
+
|
|
122
|
+
`oats update` moves a bridge. It never creates a folder and never installs a
|
|
123
|
+
first bridge: a spawn's own package check says when a capability needs one
|
|
124
|
+
that is missing.
|
|
125
|
+
|
|
126
|
+
A folder is **not touched** when:
|
|
127
|
+
|
|
128
|
+
- **it does not resolve**: a `{fromEnv: NAME}` whose variable is not set where
|
|
129
|
+
the command runs, or a path that is not absolute. Run `oats update` again
|
|
130
|
+
where the variable is set, or the printed command.
|
|
131
|
+
- **its bridge cannot be read** (a `package.json` that does not parse).
|
|
132
|
+
- **only launch configurations with their own `executable` name it.** A
|
|
133
|
+
wrapper is your program: `oats update` never runs one. The plan prints the
|
|
134
|
+
install command with that executable; when the configurations name several
|
|
135
|
+
executables, one command for each, with the configurations it is for. A
|
|
136
|
+
folder that the default, this shell or a configuration without an
|
|
137
|
+
`executable` also names is moved with the plain `pi`.
|
|
138
|
+
|
|
139
|
+
For a folder it moves, `oats update` runs the `pi` found on `PATH`, with
|
|
140
|
+
`PI_CODING_AGENT_DIR` set to that folder:
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
PI_CODING_AGENT_DIR=<folder> npm_config_prefer_online=true pi install npm:@awebai/oats-pi@<version>
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
For the default folder the variable is left out, unless this shell sets one.
|
|
147
|
+
|
|
148
|
+
## Nothing is removed before its replacement is known to install
|
|
149
|
+
|
|
150
|
+
The move is one `pi install` over the installed bridge. pi replaces the
|
|
151
|
+
settings entry and the files of a package it already holds, and an install
|
|
152
|
+
that fails leaves the old ones in place. There is no `pi uninstall`.
|
|
153
|
+
|
|
154
|
+
Before any step runs, the CLI's own install included, `oats update` asks the
|
|
155
|
+
registry for the bridge's exact version, with npm told to revalidate its
|
|
156
|
+
cache (`npm view @awebai/oats-pi@<version> version --prefer-online`). A new
|
|
157
|
+
version is listed a few minutes after it is published, and the kernel's
|
|
158
|
+
listing says nothing about the bridge's. If the version does not resolve,
|
|
159
|
+
the update stops with nothing changed and every bridge in place: run it again
|
|
160
|
+
in a few minutes. The same setting goes to pi's own npm for the install
|
|
161
|
+
(`npm_config_prefer_online=true`). `--check` does not make this lookup: it
|
|
162
|
+
shows what would run, and the run looks again.
|
|
163
|
+
|
|
164
|
+
When the installed CLI is ahead of the registry, the version asked for is
|
|
165
|
+
the installed one, and it may not be published at all. The plan does not
|
|
166
|
+
know: it makes no lookup. So when it lists a move to that version, it says
|
|
167
|
+
under the folders what the move depends on:
|
|
168
|
+
|
|
169
|
+
```text
|
|
170
|
+
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.
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
When the run's lookup then does not find the version, the message says that
|
|
174
|
+
the installed kernel is ahead of the registry, instead of telling you to wait
|
|
175
|
+
a few minutes.
|
|
176
|
+
|
|
177
|
+
**What npm answers is checked before it is used.** Both lookups must answer
|
|
178
|
+
one version and nothing else: three numbers and an optional prerelease, on
|
|
179
|
+
one line. Any other answer (nothing, several lines, a list, text around the
|
|
180
|
+
version) stops the update before any step, with nothing changed. The message
|
|
181
|
+
names the lookup and shows the answer cut to 80 characters, with its control
|
|
182
|
+
characters shown as escapes or replaced. Run `oats update` again.
|
|
183
|
+
|
|
184
|
+
npm's own error output of a lookup is not passed to your terminal either.
|
|
185
|
+
When the first lookup fails, the message says how it ended (`exit 1`) and
|
|
186
|
+
then what npm said, cut to 300 characters and made safe the same way.
|
|
187
|
+
|
|
188
|
+
The update stops at the first step that fails. Its message names the folder
|
|
189
|
+
and the exact step to run again, says what that folder holds now (the old
|
|
190
|
+
bridge still, or no bridge), and lists the folders it did not reach. A step
|
|
191
|
+
that ends without an error but leaves another version in the folder is a
|
|
192
|
+
failure too. Run the printed step, then `oats update` again: folders already
|
|
193
|
+
at the version are left alone.
|
|
194
|
+
|
|
195
|
+
## What `oats doctor` reports
|
|
196
|
+
|
|
197
|
+
`oats doctor` prints one warning per folder whose bridge is not the kernel's
|
|
198
|
+
version, naming the folder and why it is looked at:
|
|
199
|
+
|
|
200
|
+
```text
|
|
201
|
+
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)
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
A bridge ahead of the kernel is a skew too. `oats update` moves no bridge
|
|
205
|
+
back, and `oats doctor` does not ask the registry, so the warning says what
|
|
206
|
+
ends the skew:
|
|
207
|
+
|
|
208
|
+
```text
|
|
209
|
+
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")
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
It also warns about a folder it could not look at (one that does not
|
|
213
|
+
resolve, or a bridge that cannot be read). A folder that does not exist or
|
|
214
|
+
holds no bridge is not a skew, and it says nothing about it. The warnings are
|
|
215
|
+
in the text output only; `oats doctor --json` does not carry them.
|
|
216
|
+
|
|
217
|
+
## After a change of Node version
|
|
218
|
+
|
|
219
|
+
Two paths are written into things that outlive a command: the kernel's, and
|
|
220
|
+
the `node` that runs it. A new Node version can leave either behind.
|
|
221
|
+
|
|
222
|
+
**The kernel's path.** The CLI is an npm global package: it is installed
|
|
223
|
+
under npm's global prefix (`npm prefix -g`).
|
|
224
|
+
|
|
225
|
+
- **The prefix is outside the Node install.** The kernel's path does not
|
|
226
|
+
change with the Node version: the CLI needs no reinstall.
|
|
227
|
+
- **The prefix is the Node version's own directory**, the usual layout of a
|
|
228
|
+
version manager (mise, nvm, asdf, fnm). Every Node version then has its own
|
|
229
|
+
global packages: a new version has no `oats`, and removing the old version
|
|
230
|
+
removes the kernel with it. Four things name that kernel by its path: each
|
|
231
|
+
instance home's own `oats` (`<home>/.oats/bin/oats`), the Claude Code hooks
|
|
232
|
+
of a Claude instance, the host timer's unit, and what `oats setup` installs
|
|
233
|
+
(the turn record's capture hooks and its watcher, which name the capture
|
|
234
|
+
script inside the kernel). OATS cannot make a path inside a Node version
|
|
235
|
+
outlast that version.
|
|
236
|
+
|
|
237
|
+
Both layouts can exist on one host: check the prefix in the shell that
|
|
238
|
+
installs the CLI.
|
|
239
|
+
|
|
240
|
+
**The `node`'s path**, whatever the prefix. The Claude Code hooks of a
|
|
241
|
+
Claude instance, the host timer's unit and what `oats setup` installs also
|
|
242
|
+
record the `node` that runs them, by one rule
|
|
243
|
+
([the node a hook writes down](capabilities.md#the-node-a-hook-writes-down)):
|
|
244
|
+
|
|
245
|
+
- **On Homebrew**, the `opt` link (`<prefix>/opt/node/bin/node`) when it is
|
|
246
|
+
the `node` running the kernel. `brew upgrade node` repoints it, so the
|
|
247
|
+
recorded path outlasts the upgrade: the hooks, the timer and the capture
|
|
248
|
+
watcher need nothing done.
|
|
249
|
+
- **Otherwise**, a `node` on `PATH` that is the same file as the one running
|
|
250
|
+
the kernel. With mise that is the version's own install, which does not
|
|
251
|
+
outlast the version (other version managers were not measured).
|
|
252
|
+
- **When there is neither**, the path of the `node` as it is. A spawn, a
|
|
253
|
+
start, `oats schedule host install` and `oats setup` then warn that it is
|
|
254
|
+
not stable.
|
|
255
|
+
|
|
256
|
+
**What `oats setup` records is in your own files, not in an instance home:**
|
|
257
|
+
the capture hooks (`Stop` and `SessionEnd`) in every `~/.claude*/settings.json`
|
|
258
|
+
of the user who ran it, and the capture watcher's unit
|
|
259
|
+
(`~/Library/LaunchAgents/ai.aweb.turn-record-capture.plist` on macOS,
|
|
260
|
+
`~/.config/systemd/user/turn-record-capture.service` on Linux). No spawn,
|
|
261
|
+
start or restart writes them: only `oats setup` run again does, and it
|
|
262
|
+
replaces its own hooks and unit, it does not add a second one.
|
|
263
|
+
|
|
264
|
+
Once the recorded `node` no longer exists (an old version removed under a
|
|
265
|
+
version manager, for example), the hooks fail without a message, so the
|
|
266
|
+
instance stops reporting that it waits on you, and
|
|
267
|
+
`oats schedule host status` reports `node-missing`. The capture hooks then
|
|
268
|
+
fail at every stop of every Claude Code session of that user, and launchd or
|
|
269
|
+
systemd keeps restarting a watcher that cannot start.
|
|
270
|
+
|
|
271
|
+
**A home spawned with an oats.core that does not read `OATS_NODE_BIN`** does
|
|
272
|
+
not follow the rule. Its hooks record the path of the `node` its hook ran
|
|
273
|
+
under, which on Homebrew is the versioned keg
|
|
274
|
+
(`…/Cellar/node/<version>/bin/node`), and a start writes that again, because
|
|
275
|
+
a start runs the copy of oats.core in the home. `brew upgrade node` removes
|
|
276
|
+
the keg at once, so such a home needs the restart of step 2 after every Node
|
|
277
|
+
upgrade, until it is respawned.
|
|
278
|
+
|
|
279
|
+
So after moving to another Node version, and before removing the old one,
|
|
280
|
+
wherever a recorded path does not outlast it:
|
|
281
|
+
|
|
282
|
+
1. Where the prefix is the version's own directory, install the CLI in the
|
|
283
|
+
new version: `npm install -g @awebai/oats`.
|
|
284
|
+
2. Restart the instances, from a shell on the new version
|
|
285
|
+
(`oats session restart --home <home>`). A start writes the home's `oats`
|
|
286
|
+
and its Claude Code hooks again
|
|
287
|
+
([Configuration](configuration.md#launch-configurations)).
|
|
288
|
+
3. On a host that runs schedules, run `oats schedule host install` again,
|
|
289
|
+
from your own shell, not from an instance home. Without it,
|
|
290
|
+
`oats schedule host status` reports `oats-bin-missing` or `node-missing`
|
|
291
|
+
once the old version is removed
|
|
292
|
+
([Schedules](schedules.md#the-host-timers-unit)).
|
|
293
|
+
4. On a host where `oats setup` was run, run `oats setup` again, as the same
|
|
294
|
+
user and from your own shell. `oats setup --dry-run` prints the `node` it
|
|
295
|
+
would record and changes nothing.
|
|
296
|
+
|
|
297
|
+
Until the old version is removed, the instances and the timer keep running
|
|
298
|
+
what it holds.
|
|
299
|
+
|
|
300
|
+
## By hand
|
|
301
|
+
|
|
302
|
+
In any pi folder, with the `pi` that is launched with it:
|
|
303
|
+
|
|
304
|
+
```sh
|
|
305
|
+
PI_CODING_AGENT_DIR=<folder> pi install npm:@awebai/oats-pi@<the CLI's version>
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
`oats version` prints the CLI's version. For the default folder, leave the
|
|
309
|
+
assignment out only when your shell does not set `PI_CODING_AGENT_DIR`;
|
|
310
|
+
when it does, name the folder: `PI_CODING_AGENT_DIR="$HOME/.pi/agent"`.
|
package/docs/workspaces.md
CHANGED
|
@@ -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.
|
|
58
|
-
oats.okf: v5.0.
|
|
57
|
+
oats.framework: v1.10.0 # 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
|
|
@@ -159,6 +159,116 @@ facts for automations, and launch configurations. The full reference is
|
|
|
159
159
|
Written by `oats sync`; the only persisted state at the deployment besides
|
|
160
160
|
`oats-local.yaml`. See [packages.md](packages.md).
|
|
161
161
|
|
|
162
|
+
## Repository references in diagnostics
|
|
163
|
+
|
|
164
|
+
Selected repository references in diagnostics are display values. A selected
|
|
165
|
+
original refused reference is shown verbatim when it is 1–256 characters long
|
|
166
|
+
and contains only ASCII letters, digits, spaces, `.`, `_`, `/`, `+`, `-` and
|
|
167
|
+
`:`. This bounded plain-value rule tests the whole original string: no trimming,
|
|
168
|
+
decoding, control-character removal or truncation makes a value eligible.
|
|
169
|
+
Plain-reference recognition is not a secret detector: credential-like text
|
|
170
|
+
that meets this alphabet remains visible. Otherwise, display is constructed
|
|
171
|
+
from recognised components.
|
|
172
|
+
An unambiguous scheme or scp-style reference supplies only its scheme, host,
|
|
173
|
+
supported port and path, using the repository parser's character rules. User
|
|
174
|
+
information is never a display component: `ssh://git@host/org/repo` and
|
|
175
|
+
`git@host:org/repo` both display as `ssh://host/org/repo`. Display recognition
|
|
176
|
+
can also remove user information from a well-formed HTTP(S) URL that the
|
|
177
|
+
repository parser refuses; it does not admit that URL for use by Git.
|
|
178
|
+
|
|
179
|
+
**The fixed withheld display is `[repository reference withheld]`.** It replaces
|
|
180
|
+
the whole selected value when neither the bounded plain-value rule nor
|
|
181
|
+
unambiguous component construction applies, including malformed or mixed
|
|
182
|
+
references outside the plain rule. Harmless host or path text in that value
|
|
183
|
+
is withheld too. A literal input equal to the fixed display looks the same;
|
|
184
|
+
the display is not an identifier or a value to pass back to a command.
|
|
185
|
+
Standalone `file:` references and filesystem paths retain their path meanings.
|
|
186
|
+
|
|
187
|
+
A diagnostic field that explicitly carries a pinned source uses the same
|
|
188
|
+
constructor with pinned-source context: a recognised reference followed by `@`
|
|
189
|
+
and a validated 40-hex-character commit can retain that commit in its display.
|
|
190
|
+
If either part cannot be recognised, the whole source is withheld: pinned
|
|
191
|
+
sources have no bounded plain-value fallback. Rendering an already constructed
|
|
192
|
+
pinned source does not change it. This context does not change default
|
|
193
|
+
reference rendering or admit a new source form. Local/file reference semantics
|
|
194
|
+
and operational external-source values remain unchanged.
|
|
195
|
+
|
|
196
|
+
The same decision applies to the selected reference in error messages,
|
|
197
|
+
`details.ref`, `details.url`, `details.value`, `provenance.value`, nested
|
|
198
|
+
reference keys and values, and reference-bearing workspace and soul schema
|
|
199
|
+
problems. Discovery problem rows' `source` is also a diagnostic display.
|
|
200
|
+
Seven explicitly rejected argument fields have a separate context in the same
|
|
201
|
+
renderer: `transport`, `commit`, `at`, `path`, `depth`, `limit` and `destDir`.
|
|
202
|
+
A rejected string is preserved only when the whole original string satisfies
|
|
203
|
+
the same bounded plain-value rule above, including its space and colon
|
|
204
|
+
characters. No trimming, decoding, control handling or truncation is applied
|
|
205
|
+
to establish eligibility.
|
|
206
|
+
**The fixed rejected-value display is `[value withheld]`, and its neutral explanation is “(the value was withheld)”.**
|
|
207
|
+
Every other rejected string uses that display in the quoted message value and
|
|
208
|
+
matching details/provenance. Existing nonstring and container handling is
|
|
209
|
+
unchanged; nested strings use this same context. The renderer owns the
|
|
210
|
+
explanation once per originating refusal. This is a bounded display rule, not
|
|
211
|
+
a secret detector: a plain token made only of the permitted characters is not
|
|
212
|
+
protected. Selection belongs to the particular rejection; a field's name
|
|
213
|
+
alone never selects it. Valid argument values and other operational values
|
|
214
|
+
remain exact; pinned-source, schema and Git-line contexts keep their own rules.
|
|
215
|
+
Quoted or JSON-escaped copies and host/path fragments derived from a withheld
|
|
216
|
+
value cannot reveal its remainder. A raw host/path fragment can use the plain
|
|
217
|
+
exception only when its original selected source qualifies for that exception;
|
|
218
|
+
a fragment from a nonplain original never becomes eligible merely
|
|
219
|
+
because the fragment looks plain. Unrelated schema values and opaque provider
|
|
220
|
+
payloads are not scanned. Query and fragment contents are not searched for
|
|
221
|
+
individual secret values; a selected remote reference with an unrecognised
|
|
222
|
+
suffix outside the plain rule is withheld as a whole.
|
|
223
|
+
|
|
224
|
+
A refusal retains its code and reason. When the whole reference is withheld,
|
|
225
|
+
the kernel message explains that once per originating refusal. When a
|
|
226
|
+
constructed display omits user information, the refusal carries the neutral
|
|
227
|
+
clause “(its user information is not shown)”. An HTTP(S) userinfo refusal keeps
|
|
228
|
+
its specific cause and advice to give credentials to Git through a credential
|
|
229
|
+
helper, rather than in the URL; package refusals keep their own reason.
|
|
230
|
+
Workspace and membership message slots carry an existing refusal's explanation
|
|
231
|
+
when they forward it, including schema `problems[].message`, without adding
|
|
232
|
+
another copy. Pattern-only schema problems use the same selected-value display
|
|
233
|
+
without inventing a parser refusal. Known declaration files and key locations
|
|
234
|
+
remain available beside the safe diagnostic value; APIs that do not know a
|
|
235
|
+
location do not invent one.
|
|
236
|
+
|
|
237
|
+
Git's own diagnostic text has a whole-line disclosure rule. A line may be
|
|
238
|
+
shown only when every original operation reference is known and unchanged by
|
|
239
|
+
the display constructor, and the original line contains no literal `@`.
|
|
240
|
+
Missing original-reference evidence fails that check. Check the original text
|
|
241
|
+
before removing control characters or shortening the line; formatting must not
|
|
242
|
+
hide a reason to withhold it. A permitted line keeps the existing control
|
|
243
|
+
handling and length bound.
|
|
244
|
+
|
|
245
|
+
For an unknown Git failure, the last-line diagnostic comes only from stderr.
|
|
246
|
+
Empty or whitespace-only stderr leaves the message at the failure reason;
|
|
247
|
+
there is no error-message fallback on this route. An output overflow without a stderr line uses a
|
|
248
|
+
kernel-owned budget notice. Other diagnostic routes that already use an error
|
|
249
|
+
message fallback keep their behavior and the whole-line disclosure rule.
|
|
250
|
+
|
|
251
|
+
**The fixed Git notice is “Git's diagnostic was withheld; run the same Git operation by hand to see Git's own words.”**
|
|
252
|
+
Every other Git line is replaced by that notice. No substring or token is
|
|
253
|
+
recovered from a withheld line. This replaces the quoted-line disclosure rule
|
|
254
|
+
shipped with the unknown-failure diagnostic: a bounded, scrubbed fragment alone
|
|
255
|
+
is no longer enough to display Git's words. Classification still reads Git's
|
|
256
|
+
result, so the failure code and reason remain useful when its text is withheld.
|
|
257
|
+
Kernel-owned messages and schema problem prose keep their selected-reference
|
|
258
|
+
rendering; they are not Git lines. Transport failures do not gain a
|
|
259
|
+
repository-refusal clause.
|
|
260
|
+
|
|
261
|
+
These diagnostic fields are for people. Accepted parser results, repository
|
|
262
|
+
identity keys and other values consumed by commands remain exact, including
|
|
263
|
+
operational `from` values and external rows' `source`; so does the original
|
|
264
|
+
reference handed to Git. Diagnostic rendering changes neither the
|
|
265
|
+
accepted syntax nor transport. A client may extract a host from a constructed
|
|
266
|
+
display; it must also handle the fixed withheld display without a host.
|
|
267
|
+
Desktop's external-soul view still displays the operational external `source`
|
|
268
|
+
value directly; that separate output route is tracked in
|
|
269
|
+
[#1111](https://github.com/awebai/oats/issues/1111). The diagnostic display rule
|
|
270
|
+
does not make that raw consumer safe.
|
|
271
|
+
|
|
162
272
|
## Membership and trust
|
|
163
273
|
|
|
164
274
|
**Reciprocal membership is a hard gate.** A repo is a member only when
|
|
@@ -198,7 +308,7 @@ as `confirmed` or the reason it is not:
|
|
|
198
308
|
| `not-listed` | the workspace does not list the repo |
|
|
199
309
|
| `no-backlink` | no (or invalid) `oats-membership.yaml` at the member's default branch |
|
|
200
310
|
| `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) |
|
|
311
|
+
| `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
312
|
|
|
203
313
|
An unconfirmed member contributes nothing but its row: its souls are invisible,
|
|
204
314
|
its capabilities unresolvable (`E_NOT_A_MEMBER` / `E_MEMBERSHIP_UNCONFIRMED`).
|
|
@@ -486,6 +596,16 @@ URL — with the operator's own git configuration (`GIT_TERMINAL_PROMPT=0`, ssh
|
|
|
486
596
|
BatchMode: nothing ever prompts). Neither the repo that defines a capability nor
|
|
487
597
|
the repo that hosts the workspace needs to be cloned.
|
|
488
598
|
|
|
599
|
+
`oats souls` and `oats capabilities` print every catalog discovery problem
|
|
600
|
+
below their tables on stdout, in the same order as `--json` `problems`.
|
|
601
|
+
`oats souls` adds unmatched `souls.launch` keys after discovery problems.
|
|
602
|
+
Each line preserves `! <code>: <message>`. When the problem has an owner,
|
|
603
|
+
a bracket identifies its path and, where present, repository key or package;
|
|
604
|
+
external problems show their [diagnostic source display](#repository-references-in-diagnostics)
|
|
605
|
+
and declaration path, while operational external sources remain exact. These listings still exit 0
|
|
606
|
+
when some items cannot be read. A diagnostic can also describe an item that
|
|
607
|
+
remains listed; inspect its code and message.
|
|
608
|
+
|
|
489
609
|
**The only thing that needs a clone is a soul's work target** (`work:
|
|
490
610
|
worktree | checkout`). The kernel finds it, first hit wins: (1) `oats spawn
|
|
491
611
|
… --repo <abs path>`; (2) `oats-local.yaml` `clones: { <repo key>: <abs
|
package/lib/automations.mjs
CHANGED
|
@@ -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`),
|
|
365
|
-
*
|
|
366
|
-
|
|
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
|
-
|
|
369
|
-
const
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
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
|