@awebai/oats 0.53.0 → 0.55.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 (42) hide show
  1. package/bin/oats.mjs +17 -7
  2. package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
  3. package/docs/desktop-cli-api.md +44 -12
  4. package/docs/implementation.md +12 -4
  5. package/docs/integrations.md +2 -2
  6. package/docs/knowledge.md +14 -2
  7. package/docs/official-catalog.md +5 -5
  8. package/docs/packages.md +14 -14
  9. package/docs/release-notes/v0.53.0.md +14 -0
  10. package/docs/release-notes/v0.54.0.md +142 -0
  11. package/docs/release-notes/v0.55.0.md +158 -0
  12. package/docs/servers.md +13 -3
  13. package/docs/souls-and-instances.md +2 -1
  14. package/docs/upgrading.md +14 -2
  15. package/docs/workspaces.md +122 -2
  16. package/lib/packages.mjs +5 -1
  17. package/lib/remote.mjs +255 -76
  18. package/lib/servers.mjs +82 -34
  19. package/lib/workspace.mjs +27 -9
  20. package/package-catalog.json +4 -4
  21. package/package.json +1 -1
  22. package/packages/client/cli-locator.mjs +2 -2
  23. package/packages/client/workspace-views.mjs +4 -3
  24. package/packages/record/README.md +54 -13
  25. package/packages/record/bin/capture.mjs +107 -53
  26. package/packages/record/docs/capture-service.md +193 -0
  27. package/packages/record/docs/capture-status.schema.json +100 -0
  28. package/packages/record/lib/capture-aw.mjs +96 -94
  29. package/packages/record/lib/capture-cc.mjs +109 -187
  30. package/packages/record/lib/capture-db-reader.mjs +39 -0
  31. package/packages/record/lib/capture-issues.mjs +64 -0
  32. package/packages/record/lib/capture-scratch.mjs +111 -0
  33. package/packages/record/lib/capture-state.mjs +105 -0
  34. package/packages/record/lib/derived-state.mjs +60 -0
  35. package/packages/record/lib/formats.mjs +31 -31
  36. package/packages/record/lib/index-db.mjs +74 -34
  37. package/packages/record/lib/receipt-summary.mjs +62 -0
  38. package/packages/record/lib/session-snapshot.mjs +56 -1
  39. package/packages/record/lib/sqlite-rows.mjs +14 -0
  40. package/packages/record/lib/store.mjs +122 -43
  41. package/packages/record/lib/transcript-prefix.mjs +40 -0
  42. package/skills/oats-getting-started/SKILL.md +8 -2
@@ -0,0 +1,158 @@
1
+ # OATS 0.55.0
2
+
3
+ 2026-10-14
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.54.0 Desktop refuses a 0.55.0 CLI.
9
+
10
+ - **The first capture after the upgrade takes longer.** It reconciles the
11
+ existing journals, resets the search index and rebuilds it from them, in
12
+ one synchronous pass that can take minutes on a large record; later passes
13
+ read only what is new. See Fixed
14
+ ([#1108](https://github.com/awebai/oats/issues/1108)).
15
+
16
+ - **A script that reads `oats server roster --json`** no longer sees
17
+ `E_ROSTER_BUDGET` or `bounds.skipped`: every server is probed, and one
18
+ that does not answer reports its own `E_SSH` timeout. See Removed
19
+ ([#1117](https://github.com/awebai/oats/issues/1117)).
20
+
21
+ - **The official catalog's versions in this release** are oats.framework
22
+ 1.10.0, oats.okf 5.0.5, oats.aweb 1.27.2 and oats.engineering 1.10.0: see
23
+ Provider updates. Pin what your workspace uses, then run `oats sync`.
24
+ Running instances keep what they were spawned with; new spawns get the new
25
+ versions, so a standing maintainer gets oats.engineering 1.10.0's lane
26
+ rules only by being re-spawned. The same holds for oats.okf 5.0.5: an
27
+ instance spawned before the pin keeps its old frozen-remote guard (and
28
+ still fails with `E_OWNER` on a host that rewrites Git URLs) and its old
29
+ proposal brief until it is re-spawned.
30
+
31
+ ## Changed
32
+
33
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.56.0`.** The compatibility band
34
+ admits 0.55. Upgrade the CLI and the Desktop together: a 0.54.0 Desktop
35
+ refuses a 0.55.0 CLI. No new gate on the band. `oats tui` runs the kernel it
36
+ ships with and is held to the same band.
37
+
38
+ ## Fixed
39
+
40
+ - Capture streams transcript content, stores per-input cursors and journal IDs on
41
+ disk, and indexes only new journal bytes in bounded transactions ([#1108](https://github.com/awebai/oats/issues/1108)).
42
+ Background input logs share an append-only assumption: an edit to an old
43
+ aweb-log line is no longer picked up merely because the log grows. Use
44
+ `capture --reset-cursors [--source aw|cc|pi|codex]` to request reprocessing.
45
+ Detected native-transcript prefix changes are set aside before appending, to
46
+ preserve v0.53.0 downgrade/re-upgrade compatibility. Restore the prefix and
47
+ use `capture --retry-set-aside`, or exclude the source through the existing
48
+ ignore list (which also excludes its later turns). `capture --health` reports
49
+ these inputs. This changes capture algorithms; it introduces no service
50
+ schedule, record-size policy, or bounded-runner guarantee. Content buffers and
51
+ caches are bounded apart from the largest record; sorted path/root metadata
52
+ and explicit receipt inventories can still grow with input counts. The first
53
+ capture after upgrade reconciles existing journals and rebuilds the index,
54
+ with substantial per-input/per-stream synchronous commit cost still unresolved.
55
+ Refused aweb entries are counted and consumed; reset source cursors to retry
56
+ them. Snapshot and receipt scratch stays on the record-root volume, with
57
+ conservative cleanup of proven abandoned allocations under the capture lock.
58
+
59
+ - Capture health reads current set-aside issues, including direct library calls,
60
+ while command snapshots retain their historical run fields. Reading an existing
61
+ capture database requires read-only SQLite support (Node 22.12+/23.2+; prefer
62
+ 22.13+ on 22.x without an experimental flag). Unsupported runtimes, schemas,
63
+ WAL databases and unavailable readers fail closed; normal capture's runtime
64
+ floor is unchanged.
65
+
66
+ - **A server that can't be reached no longer hides the others.** The remote
67
+ roster (`oats server roster`, the Desktop's view of other machines) probes
68
+ every registered server at once, each within its own deadline. A server
69
+ that is switched off now costs only its own entry, which shows that it
70
+ timed out (`E_SSH`, `ssh to <host> timed out: no answer within <n> s`), and
71
+ the servers registered after it are read as usual. Before, the probes ran
72
+ one after another against one 45 s budget. Four registrations on one
73
+ offline host could use the budget up, and the servers after them were
74
+ never asked ([#1117](https://github.com/awebai/oats/issues/1117)).
75
+ - **Retry on a remote window reads the servers again.** In the Desktop, the
76
+ roster's **Retry** on a window with a deployment on another machine now
77
+ reads the servers at once, or waits for the read already running, before it
78
+ shows the roster. Before, it showed the last read's result until the next
79
+ background read, 10 s later
80
+ ([#1117](https://github.com/awebai/oats/issues/1117)).
81
+
82
+ ## Removed
83
+
84
+ - **`E_ROSTER_BUDGET` and `bounds.skipped`** in `oats server roster --json`.
85
+ Every group is probed, so no group is reported as not reached any more, and
86
+ `bounds` is `{budgetMs, perTargetTimeoutMs, elapsedMs}`. `--budget` stays,
87
+ as the deadline of the whole answer, which caps each probe's `--per-target`
88
+ allowance
89
+ ([the roster](../desktop-cli-api.md#the-remote-roster-oats-server-roster---json)).
90
+
91
+ ## Provider updates
92
+
93
+ - **oats.okf 5.0.5** (from 5.0.3; 5.0.4 is included).
94
+ - **A host's Git URL rewriting no longer breaks Git bases**
95
+ ([oats-okf#76](https://github.com/awebai/oats-okf/issues/76), 5.0.4). A
96
+ host whose global or system Git config routes a bound repository through
97
+ `url.<base>.insteadOf` or `pushInsteadOf` (a deploy key on an ssh alias,
98
+ for example) failed every okf call with `E_OWNER`. The frozen-remote
99
+ guard now resolves the binding's `repository` with the host's own
100
+ rewrites and compares that with the clone's fetch and push URLs; the
101
+ binding stays as written. A rewrite in the clone's own config, a changed
102
+ origin or a `pushurl` is still refused, and URLs compare byte for byte.
103
+ - **One harvester at a time** (5.0.5). A working instance writes one
104
+ proposal per checkpoint, with claims only for the nodes its soul owns,
105
+ and spawns one knowledge harvester at a time, none while `oats status`
106
+ still lists its last one ([the flow](../knowledge.md)). Instruction text
107
+ only; it reaches instances spawned after the pin.
108
+ - The official catalog, the reference workspace and the generated mirrors
109
+ take published `v5.0.5` at `73b85020e52b8584cb15f153a39712f900e69918`.
110
+ Compatibility remains OATS 0.29.0 or later.
111
+ - **oats.aweb 1.27.2:** the `/oats-aweb` skill's etiquette points to
112
+ `/oats-token-saving` (oats.core 2.6.0, in OATS 0.54.0) for whether to send,
113
+ to whom and how long, and keeps how to send
114
+ ([#1103](https://github.com/awebai/oats/issues/1103)). Instruction text
115
+ only; both floors are unchanged (OATS 0.52.0, aw 1.36.33). The catalog,
116
+ the reference workspace and `mirrors/oats-aweb` take published `v1.27.2`
117
+ at `f82cebe299562b38188f3373fa09a89b50d5f868`; the mirror's tree equals
118
+ the tag's.
119
+ - **oats.engineering 1.10.0: maintainers work in lanes**
120
+ ([#1103](https://github.com/awebai/oats/issues/1103),
121
+ [oats-engineering#14](https://github.com/awebai/oats-engineering/pull/14)).
122
+ The official catalog, the reference workspace and the generated mirrors
123
+ (`mirrors/oats-developer`, `mirrors/oats-code-review`,
124
+ `mirrors/oats-engineering-expert`, `mirrors/oats-maintainer`) take published
125
+ `v1.10.0` at `944470be71a96299ae4a1cfb7df0fba94a592899`; each mirror's tree
126
+ equals the tag's. Instruction text only: no skill is added or removed, and
127
+ the requirement is unchanged (OATS 0.30.0 or later). `oats.maintainer` and
128
+ `oats.engineering-expert` change; the other two capabilities only change
129
+ version. What changes:
130
+ - **Each maintainer holds a lane.** The peers' agreement becomes a written
131
+ lane map: what each lane covers, its maintainer and its second reader,
132
+ the label a PR shows its lane with, the hold label, and who owns the next
133
+ release. A maintainer's state file holds its own lane only; the forge is
134
+ the one copy of a PR's state.
135
+ - **Every PR gets one second reader, asked once,** at the head the lane's
136
+ maintainer approved. This replaces every peer reviewing every PR and
137
+ re-binding its verdict at every head.
138
+ - **Intake no longer sweeps on every wake:** a full sweep at session start,
139
+ after a compaction and at least weekly; on a wake, the event alone.
140
+ - **Peers message each other for five things** (a second read, a hold that
141
+ must stop work in flight, the release plan, a lane changing hands, a
142
+ request that belongs to the peer's lane), and send no notice before or
143
+ after a merge or a tag. A hold is a label on the forge, and the merge step
144
+ reads it.
145
+ - **The merging maintainer brings a branch up to date itself;** the verdicts
146
+ carry when the PR's own change is unchanged and CI is green. When the
147
+ default branch moved since CI ran, it runs the affected test files on a
148
+ trial merge first.
149
+ - **Experts hand over to one maintainer,** the one whose lane the work is
150
+ in, and leave the branch alone after the hand-over.
151
+ - **To adopt it:** peer maintainers rewrite their agreement as a lane map
152
+ (`/cross-review-peer`), create the lane labels and the hold label, and
153
+ drop each other's PRs from their state files. A maintainer alone has
154
+ nothing to do. Pin `oats.engineering: v1.10.0` and run `oats sync`.
155
+ Running instances keep what they were spawned with; new spawns pick
156
+ 1.10.0 up after `oats sync`. A standing maintainer gets the new rules
157
+ only by being re-spawned, not by a sync or a session restart: hand its
158
+ lane over first (`/cross-review-peer`, "A lane changes hands").
package/docs/servers.md CHANGED
@@ -156,6 +156,12 @@ Every routed ssh call carries these options, before `--` and the host:
156
156
  | `ServerAliveInterval=15`, `ServerAliveCountMax=3` | a link that died without a reset ends the call, an attached viewer included, within about 60 s |
157
157
  | `ControlMaster=auto`, `ControlPath=~/.oats/ssh/%C`, `ControlPersist=60` | every call to one host (the probe, the command, a viewer, concurrent Desktop reads) shares one authenticated connection, kept 60 s after its last client |
158
158
 
159
+ - Concurrent first calls to a host with no master yet (the roster probes
160
+ every registration at once, so two registrations of one host do) race to
161
+ create it. ssh lets the one that loses run over a connection of its own
162
+ ("ControlSocket … already exists, disabling multiplexing"): the call still
163
+ succeeds, and later calls share the master. A dead host's registrations
164
+ each wait out the connect timeout, side by side.
159
165
  - Options given with `-o` override `~/.ssh/config`, so these replace any
160
166
  `ControlMaster`, `ControlPath` or `ControlPersist` set there for the host.
161
167
  Everything else in your ssh config (users, keys, `ProxyJump`, host
@@ -326,9 +332,13 @@ the host's own facts from its `status --json`: `identity`,
326
332
  (an older host, or a saved route the host no longer lists). A row also
327
333
  carries `waitingOnYou` (needs input) when the host's kernel reports it, and
328
334
  only then: an older host's row has no such key. A removed or edited registration keeps
329
- its group from the saved routes. State is pulled on every call within
330
- `--per-target` (default 20 s) of a total `--budget` (default 45 s); a group
331
- not reached is reported with `E_ROSTER_BUDGET`. `--server <id>` narrows it.
335
+ its group from the saved routes. State is pulled on every call, from every
336
+ group at once: each probe has its own deadline, `--per-target` (default 20 s)
337
+ capped by `--budget` (default 45 s, the deadline of the whole answer), and a
338
+ group that fails or does not answer in time reports its own `E_SSH`, so a
339
+ host that is switched off never hides the others. The groups keep their
340
+ registration order whatever order their probes finish in. `--server <id>`
341
+ narrows it.
332
342
 
333
343
  The group's `probe` also relays the host's kernel features (0.49.0,
334
344
  `probe.features`): the top-level `features` of the same `status --json`
@@ -98,7 +98,8 @@ is a code change, reviewed in its repo.
98
98
  ### OATS operational knowledge is a capability
99
99
 
100
100
  An agent's knowledge of OATS itself (status, spawn, retire, finding other
101
- souls) is ordinary capability content: **`oats.core`** (package
101
+ souls, and keeping its messages to other instances few and short:
102
+ `/oats-token-saving`) is ordinary capability content: **`oats.core`** (package
102
103
  `oats.framework`). Workspaces give it to every soul through
103
104
  `defaults.capabilities: { oats.core: { from: package } }`; a soul may say
104
105
  `oats.core: off`. **`oats.setup`** (same package) carries the whole-architecture
package/docs/upgrading.md CHANGED
@@ -1,7 +1,9 @@
1
1
  # Upgrading OATS on a host
2
2
 
3
- Upgrading OATS means three things, in this order, on each host:
3
+ Upgrading OATS means three things, in this order, on each host, and one
4
+ before them where the Desktop is installed:
4
5
 
6
+ 0. **The Desktop**, where it is installed: the new version's, before the CLI.
5
7
  1. **The CLI** (`@awebai/oats`, the kernel).
6
8
  2. **The pi bridge** (`@awebai/oats-pi`), in every pi folder the host's
7
9
  deployments launch pi with: `oats update`, in each deployment.
@@ -18,6 +20,13 @@ every version between yours and the new one in the
18
20
  changes, and what else must change with it (the Desktop, another tool, a
19
21
  package pin). This page is the part that is the same for every release.
20
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
+
21
30
  **Package versions are a different thing.** `oats update` moves the CLI and
22
31
  the bridge, never a package. A deployment's capabilities come from the
23
32
  packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
@@ -26,6 +35,7 @@ packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
26
35
  ## The steps
27
36
 
28
37
  ```sh
38
+ # 0. where the Desktop is installed: the new version's Desktop first
29
39
  npm install -g @awebai/oats # 1. the CLI
30
40
  oats update # 2. in a deployment: the plan, then it asks before it runs
31
41
  oats doctor # 3. in the same deployment
@@ -41,7 +51,9 @@ Without a terminal (a script, an agent's shell) it runs only with `--yes`.
41
51
 
42
52
  `oats update` also does step 1: when npm lists a newer `@awebai/oats`, its
43
53
  plan starts with that install, and the bridges move to that same version in
44
- the same run.
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.
45
57
 
46
58
  **`oats update` only moves forward.** It never installs an older CLI or an
47
59
  older bridge than the one in place:
@@ -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.4 # bare version → resolves through the official catalog
58
- oats.okf: v5.0.3
57
+ oats.framework: v1.10.0 # bare version → resolves through the official catalog
58
+ oats.okf: v5.0.5
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
@@ -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/packages.mjs CHANGED
@@ -290,7 +290,11 @@ export function parsePackageRequest(id, value, catalog) {
290
290
  const c = classifyPackageValue(value);
291
291
  if (c.problem) {
292
292
  const code = typeof value === "string" && value.trim().startsWith("git:") ? "E_REPO_REF" : "E_WORKSPACE_SCHEMA";
293
- throw oatsError(code, `packages.${id}: ${c.problem}, got ${JSON.stringify(value)}`, { id, value, path: `/packages/${id}`, problems: [c.problem] });
293
+ const safe = { id, value: defaultRemote.redactUrl(value, null, { reference: true }), path: `/packages/${id}`,
294
+ problems: [defaultRemote.redactUrl(c.problem, value, { known: false })] };
295
+ const message = defaultRemote.redactUrl(`packages.${safe.id}: ${safe.problems[0]}, got ${JSON.stringify(safe.value)}`,
296
+ value, { known: false, refusal: true });
297
+ throw oatsError(code, message, safe);
294
298
  }
295
299
  if (c.kind === "git") return { kind: "git", remoteRef: c.repo, at: c.at, path: DEFAULT_PACKAGE_PATH };
296
300
  const text = value.trim();