@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.
Files changed (100) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +314 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
  6. package/docs/desktop-cli-api.md +696 -60
  7. package/docs/desktop-instance-start.md +25 -12
  8. package/docs/execution-targets.md +1 -0
  9. package/docs/implementation.md +184 -12
  10. package/docs/integrations.md +6 -3
  11. package/docs/knowledge.md +2 -2
  12. package/docs/macos-test-runs.md +246 -0
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-lane.md +210 -6
  16. package/docs/release-notes/v0.53.0.md +1288 -0
  17. package/docs/release-notes/v0.54.0.md +142 -0
  18. package/docs/schedules.md +7 -1
  19. package/docs/souls-and-instances.md +239 -16
  20. package/docs/tui.md +453 -21
  21. package/docs/upgrading.md +310 -0
  22. package/docs/workspaces.md +123 -3
  23. package/lib/automations.mjs +22 -22
  24. package/lib/claim.mjs +93 -4
  25. package/lib/config-data.mjs +4 -1
  26. package/lib/core.mjs +569 -121
  27. package/lib/instance-events.mjs +19 -1
  28. package/lib/instance-git.mjs +39 -3
  29. package/lib/instance-inspect.mjs +5 -6
  30. package/lib/instance-lifecycle.mjs +145 -18
  31. package/lib/instance-resolution.mjs +59 -6
  32. package/lib/launch-preference.mjs +226 -15
  33. package/lib/local-edit.mjs +118 -0
  34. package/lib/packages.mjs +18 -5
  35. package/lib/pi-bridge.mjs +308 -0
  36. package/lib/refused-text.mjs +11 -0
  37. package/lib/remote.mjs +404 -60
  38. package/lib/resolve.mjs +2 -1
  39. package/lib/retained-after-retire.mjs +2 -2
  40. package/lib/retire-output.mjs +12 -1
  41. package/lib/schedule-host.mjs +6 -35
  42. package/lib/shell-word.mjs +13 -0
  43. package/lib/soul-launch-verbs.mjs +153 -0
  44. package/lib/stable-node.mjs +62 -0
  45. package/lib/teams-verbs.mjs +18 -46
  46. package/lib/workspace.mjs +75 -27
  47. package/package-catalog.json +4 -4
  48. package/package.json +2 -1
  49. package/packages/client/attach-exit.mjs +25 -0
  50. package/packages/client/cli-adapter.mjs +16 -3
  51. package/packages/client/cli-locator.mjs +2 -2
  52. package/packages/client/deployment-contract.mjs +4 -0
  53. package/packages/client/deployment-facts.mjs +71 -10
  54. package/packages/client/deployment-panel.mjs +49 -11
  55. package/packages/client/deployment-read-cli.mjs +7 -3
  56. package/packages/client/display-text.mjs +8 -2
  57. package/packages/client/instance-acts.mjs +46 -10
  58. package/packages/client/instance-events-contract.mjs +4 -2
  59. package/packages/client/instance-presentation.mjs +66 -2
  60. package/packages/client/instance-tree.mjs +23 -14
  61. package/packages/client/kernel-lines.mjs +31 -0
  62. package/packages/client/kernel-made.mjs +23 -0
  63. package/packages/client/launch-prompt-outcome.mjs +51 -16
  64. package/packages/client/lifecycle-contract.mjs +45 -4
  65. package/packages/client/liveness.mjs +14 -1
  66. package/packages/client/own-codes.mjs +31 -0
  67. package/packages/client/panel-views.mjs +18 -11
  68. package/packages/client/readiness-contract.mjs +3 -1
  69. package/packages/client/remote-address.mjs +34 -9
  70. package/packages/client/remote-identity-memory.mjs +94 -0
  71. package/packages/client/remote-roster.mjs +92 -6
  72. package/packages/client/session-attach.mjs +175 -0
  73. package/packages/client/spawn-apply-contract.mjs +16 -4
  74. package/packages/client/spawn-messages.mjs +26 -3
  75. package/packages/client/spawn-preview-cli.mjs +8 -2
  76. package/packages/client/spawn-preview-contract.mjs +5 -1
  77. package/packages/client/terminal-exec.mjs +21 -0
  78. package/packages/client/workspace-choices.mjs +95 -0
  79. package/packages/client/workspace-views.mjs +39 -3
  80. package/packages/record/README.md +21 -0
  81. package/packages/record/bin/setup.mjs +108 -15
  82. package/packages/tui/README.md +30 -12
  83. package/packages/tui/lib/actions.mjs +16 -1
  84. package/packages/tui/lib/client.mjs +32 -1
  85. package/packages/tui/lib/config.mjs +151 -0
  86. package/packages/tui/lib/main.mjs +117 -46
  87. package/packages/tui/lib/model.mjs +392 -0
  88. package/packages/tui/lib/read.mjs +473 -0
  89. package/packages/tui/lib/store.mjs +364 -0
  90. package/packages/tui/lib/term/keys.mjs +44 -0
  91. package/packages/tui/lib/term/screen.mjs +16 -4
  92. package/packages/tui/lib/term/text.mjs +60 -0
  93. package/packages/tui/lib/term/tty.mjs +13 -3
  94. package/packages/tui/lib/views/detail.mjs +46 -0
  95. package/packages/tui/lib/views/frame.mjs +230 -36
  96. package/packages/tui/lib/views/help.mjs +125 -13
  97. package/packages/tui/lib/views/instances.mjs +137 -0
  98. package/packages/tui/lib/views/scroll.mjs +19 -0
  99. package/packages/tui/lib/views/switcher.mjs +97 -0
  100. 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"`.
@@ -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.3 # bare version → resolves through the official catalog
58
- oats.okf: v5.0.2
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
@@ -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