@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.
- package/bin/oats.mjs +17 -7
- package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
- package/docs/desktop-cli-api.md +44 -12
- package/docs/implementation.md +12 -4
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +14 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.53.0.md +14 -0
- package/docs/release-notes/v0.54.0.md +142 -0
- package/docs/release-notes/v0.55.0.md +158 -0
- package/docs/servers.md +13 -3
- package/docs/souls-and-instances.md +2 -1
- package/docs/upgrading.md +14 -2
- package/docs/workspaces.md +122 -2
- package/lib/packages.mjs +5 -1
- package/lib/remote.mjs +255 -76
- package/lib/servers.mjs +82 -34
- package/lib/workspace.mjs +27 -9
- package/package-catalog.json +4 -4
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/workspace-views.mjs +4 -3
- package/packages/record/README.md +54 -13
- package/packages/record/bin/capture.mjs +107 -53
- package/packages/record/docs/capture-service.md +193 -0
- package/packages/record/docs/capture-status.schema.json +100 -0
- package/packages/record/lib/capture-aw.mjs +96 -94
- package/packages/record/lib/capture-cc.mjs +109 -187
- package/packages/record/lib/capture-db-reader.mjs +39 -0
- package/packages/record/lib/capture-issues.mjs +64 -0
- package/packages/record/lib/capture-scratch.mjs +111 -0
- package/packages/record/lib/capture-state.mjs +105 -0
- package/packages/record/lib/derived-state.mjs +60 -0
- package/packages/record/lib/formats.mjs +31 -31
- package/packages/record/lib/index-db.mjs +74 -34
- package/packages/record/lib/receipt-summary.mjs +62 -0
- package/packages/record/lib/session-snapshot.mjs +56 -1
- package/packages/record/lib/sqlite-rows.mjs +14 -0
- package/packages/record/lib/store.mjs +122 -43
- package/packages/record/lib/transcript-prefix.mjs +40 -0
- 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
|
|
330
|
-
|
|
331
|
-
|
|
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
|
|
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:
|
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.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
|
-
|
|
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();
|