@awebai/oats 0.53.0 → 0.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/oats.mjs CHANGED
@@ -42,6 +42,7 @@ import { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBrid
42
42
  import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
43
43
  import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
44
44
  import { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } from "../lib/launch-preference.mjs";
45
+ import { terminalText } from "../lib/refused-text.mjs";
45
46
  import { soulsOffered } from "../lib/instance-resolution.mjs";
46
47
  import { parseConfigData } from "../lib/config-data.mjs";
47
48
  import * as remoteModule from "../lib/remote.mjs";
@@ -2270,14 +2271,23 @@ async function itemsCmd(kind) {
2270
2271
  // `oats souls` reads souls.launch for every soul it lists: a key that names none of them is a problem
2271
2272
  // of this read, one row per key (the souls a spawn would refuse carry it as launch.problem).
2272
2273
  const unmatched = kind === "souls" ? launchKeysUnmatched({ local: ctx.local, offered: soulsOffered(discovery) }).unmatched.map(unmatchedProblemRow) : [];
2273
- if (JSON_MODE) { jsonOk(withObservation({ [`${kind}Api`]: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, commit: discovery.commit }, [kind]: items, problems: [...discovery.problems, ...unmatched] })); return; }
2274
+ const problems = [...discovery.problems, ...unmatched];
2275
+ if (JSON_MODE) { jsonOk(withObservation({ [`${kind}Api`]: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, commit: discovery.commit }, [kind]: items, problems })); return; }
2274
2276
  console.log(`${kind} of workspace ${workspaceName(discovery)} (${discovery.key} @ ${short(discovery.commit)})${standalone ? ` — ${standaloneNote(discovery)}` : ""}\n`);
2275
2277
  if (!items.length) console.log(" (none)");
2276
2278
  else if (kind === "souls") printTable(["name", "origin", "teams here", "work"], items.map((s) => [s.name, s.origin, s.teams === null ? "(invalid: oats teams)" : s.teams.map((t) => (t.default ? `${t.label}*` : t.label)).join(",") || "—", s.work ?? "—"]));
2277
2279
  else printTable(["name", "origin", "layer"], items.map((c) => [c.private ? `${c.name} (repo-owned)` : c.name, c.origin, c.layer ?? "—"]));
2278
2280
  const unsynced = Object.keys(discovery.workspace?.packages || {}).filter((id) => !lock.packages[id]);
2279
2281
  if (kind === "capabilities" && unsynced.length) console.log(`\n package capabilities of ${unsynced.join(", ")} appear after \`oats sync\``);
2280
- for (const p of unmatched) console.log(`\n! ${p.code}: ${p.message}`);
2282
+ for (const p of problems) console.log(`\n${catalogProblemLine(p)}`);
2283
+ }
2284
+
2285
+ /** Owner fields decide context, never message text. A problem source is display data;
2286
+ * render that projection without changing the operational external source. */
2287
+ function catalogProblemLine(p) {
2288
+ const owner = p.repoKey || p.package || (p.source ? remoteModule.redactUrl(p.source, null, { pinned: true }) : null);
2289
+ const where = owner ? ` [${terminalText(`${owner}: ${p.path}`)}]` : "";
2290
+ return `! ${p.code}: ${p.message}${where}`;
2281
2291
  }
2282
2292
 
2283
2293
  /** A key of souls.launch that names no soul (lib/launch-preference.mjs launchKeysUnmatched's row) as a
@@ -62,6 +62,9 @@ symlink enters as `symlink:<target>`; empty directories and a top-level `.git/`
62
62
  The cache may be wiped at any time. Operations on one cache repo are serialized.
63
63
  - Failures: `E_REMOTE_UNREADABLE { url, key, reason }`, `reason` ∈ `auth`, `not-found`, `network`,
64
64
  `timeout`, `unknown`. Nothing half-succeeds.
65
+ - Reference-bearing diagnostics use `redactUrl`, including parser refusals, package and
66
+ workspace validation errors, and quoted Git text; the [display rule](../workspaces.md#repository-references-in-diagnostics)
67
+ removes user information without changing the reference used for transport.
65
68
 
66
69
  ---
67
70
 
@@ -680,10 +680,17 @@ Feature `workspace-v2`, `workspaceApi: 2`. Model: [workspaces.md](workspaces.md)
680
680
  not resolve, a connection refused, reset or closed, a transport that could
681
681
  not reach the remote). A failure whose text shows nothing the kernel
682
682
  recognises is `unknown` (0.53.0; it read `network` before), and its message
683
- then ends with Git's own last line: `cannot read remote <url> (unknown):
684
- <line>`. The line is one line of at most 300 characters, with control
685
- characters and the user information of any URL removed; when Git said
686
- nothing, the message ends at `(unknown)`.
683
+ then ends with a last-line diagnostic: `cannot read remote <url> (unknown):
684
+ <line>`. Git's words are shown only under the
685
+ [whole-line disclosure rule](workspaces.md#repository-references-in-diagnostics);
686
+ otherwise `<line>` is the contract's fixed Git notice. Permitted text remains
687
+ one line of at most 300 characters with control characters removed. This
688
+ supersedes the earlier rule that a scrubbed Git line was always shown.
689
+ Only stderr supplies this last-line diagnostic. Empty or whitespace-only
690
+ stderr leaves the message at `(unknown)`, without an error-message fallback;
691
+ an output overflow without a stderr line uses a kernel-owned budget notice. Other diagnostic routes'
692
+ existing error-message fallbacks retain the same original-operation context
693
+ and disclosure rule.
687
694
  `cache` (OATS 0.33.0) is local: the
688
695
  remote cache on this machine could not be written (a git lock still held,
689
696
  another oats process still writing it, or a lock file one left when it
@@ -694,7 +701,10 @@ Feature `workspace-v2`, `workspaceApi: 2`. Model: [workspaces.md](workspaces.md)
694
701
  `status` / `workspace status`, the Desktop keeps the `message` (shown as
695
702
  given) and only a bounded cause: `details.reason` (matching
696
703
  `^[a-z][a-z-]{0,31}$`) and the host of `details.url`. No path, pid, lock,
697
- `cacheDir` or other detail field crosses to the renderer. It keys only on
704
+ `cacheDir` or other detail field crosses to the renderer. `details.url` is a
705
+ display value under the [repository diagnostic contract](workspaces.md#repository-references-in-diagnostics),
706
+ so it may withhold the reference and supply no host; it is not a transport URL.
707
+ It keys only on
698
708
  `code` + `details.reason`: `cache` words the roster "OATS cache
699
709
  problem" with the message in full; `network` / `timeout` read "Couldn't
700
710
  reach <host>"; any other reason, `unknown` among them, keeps the generic
@@ -931,7 +941,19 @@ oats souls [--dir <d>] [--max-age <s>] --json
931
941
  Every item of every confirmed member, the external souls, and the locked
932
942
  packages' capabilities and souls, sorted by name, then origin. Both carry
933
943
  `workspace: {name, key, commit}`, `problems` and, on a standalone view,
934
- `standalone: true`.
944
+ `standalone: true`. Text mode prints every `problems` row on stdout under
945
+ the table, in the same order as JSON: discovery problems, then unmatched
946
+ `souls.launch` keys for `oats souls`. The line is `! <code>: <message>`,
947
+ preserving the kernel code and message. A row with an owner (`repoKey`,
948
+ `package` or `source`) adds ` [<where>]`: its existing `path`, preceded by
949
+ `repoKey: ` or `package: ` when present. A source-owned row shows its diagnostic
950
+ source display followed by its path; the source uses the shared
951
+ [repository-reference display policy](workspaces.md#repository-references-in-diagnostics)
952
+ and may be withheld as a whole. Operational external sources remain exact. Context uses
953
+ the kernel's terminal text escaping. Ownerless rows, including unmatched
954
+ launch keys, have no bracket. Partial listings still exit 0; JSON success
955
+ semantics and fatal refusals are unchanged. A problem does not necessarily
956
+ mean an item is absent from the table.
935
957
 
936
958
  ```json
937
959
  {"soulsApi":1,"workspace":{"name":"northwind","key":"github.com/nw/agents","commit":"66566512…"},
@@ -978,8 +1000,7 @@ problem`, (feature `souls-capabilities`) `capabilities`, and (feature
978
1000
  as in the refusal's `details.keys`. `message` is at most 1024 characters
979
1001
  and ends with the two commands, in their order. Each soul a spawn would
980
1002
  refuse carries the refusal as `launch.problem`: the souls with no entry of
981
- their own. Text mode prints each row under the table as `! <code>:
982
- <message>`.
1003
+ their own.
983
1004
  - `teams` and `defaultTeam` (feature `team-model-3`) are a
984
1005
  [TeamRow](#the-team-row-teamrow) list and a
985
1006
  [DefaultTeam](#the-default-defaultteam); both `null` when the soul's teams
@@ -86,7 +86,7 @@ and the rules its tests pin.
86
86
 
87
87
  | module | owns |
88
88
  |---|---|
89
- | `remote.mjs` | repo refs, reading Git remotes, content digests |
89
+ | `remote.mjs` | repo refs, reading Git remotes, content digests; `redactUrl` owns [reference display construction and withholding](workspaces.md#repository-references-in-diagnostics). Selected original refused references first use the contract's bounded plain-value rule; other values supply only validated scheme/SCP, host, supported port and path components, or are withheld whole. Raw host/path fragments inherit plain eligibility only from the original selected source, never from the fragment alone; nonplain originals cannot use that exception. Plain-reference recognition is not a secret detector: credential-like text within the permitted alphabet stays visible. Display recognition shares the parser's character rules without calling its error path, and never changes admission or transport. Explicit pinned-source context retains only a constructed reference plus a validated 40-hex commit, remains idempotent, and has no plain fallback; the default context does not infer pins. Each rejection boundary explicitly names its rejected-input fields; the seven selected argument fields use the same bounded plain-value predicate through the renderer, including spaces and colons and without trimming or decoding, never a global field-name rule. Rejected-input messages quote the rendered fields through a formatter at that boundary, so rejected words cannot replace identical words in the fixed reason. Valid operational values are untouched. Refusal context owns the explanation once; forwarding preserves it. `scrubGitLine` delegates the linked whole-Git-line disclosure rule to the renderer before control/length formatting: only proven unchanged original operation refs plus an original line without `@` permit disclosure; all other lines become the fixed notice, with no substring recovery. Construction tests audit raw Git error-text access and quoting routes; generated invariants cover selected diagnostic routes |
90
90
  | `local-inputs.mjs` | the local configuration a command read, for `observation.localRevision` |
91
91
  | `workspace.mjs` | workspace, membership and soul files; discovery |
92
92
  | `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
@@ -332,9 +332,17 @@ A failed git call is classified from what it shows (`classifyRemoteFailure`):
332
332
  our own timer's kill is `timeout`, another signal `killed`, a failed write of
333
333
  the cache `cache`, and otherwise git's text decides, read without the object
334
334
  ids it names. A text that shows nothing the kernel recognises is `unknown`,
335
- never `network`, and the message of an `unknown` failure carries git's own
336
- line through one scrub (`scrubGitLine`): one line, bounded, with no control
337
- character and no URL's user information.
335
+ never `network`. `gitLastLine` reads only stderr for an `unknown` failure:
336
+ empty or whitespace-only stderr supplies no line; an output overflow without
337
+ a stderr line supplies a kernel-owned budget notice. It does not substitute an error message; other
338
+ routes' existing error-message fallbacks are unchanged. A stderr line passes
339
+ through `scrubGitLine`, which delegates the
340
+ [whole-line disclosure rule](workspaces.md#repository-references-in-diagnostics)
341
+ to the renderer with the original line and original operation references before
342
+ formatting.
343
+ When disclosure is not proved safe, it returns the contract's fixed Git notice;
344
+ it does not try to recover a safe fragment. Classification and kernel-owned
345
+ reason text do not depend on whether Git's words can be shown.
338
346
 
339
347
  Every write to a cache repo (its `git init`, config, fetches and pins) holds
340
348
  the repo's cross-process write lock, `<cache>/.locks/<repo>.lock`
@@ -9,7 +9,7 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.9.4` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.10.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v5.0.3` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.27.1` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.9.1` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.0.3`, `5.0.3`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.0.3` or `oats-framework/v1.9.4`) and the payload path. An id
54
+ convention (`v5.0.3` or `oats-framework/v1.10.0`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,7 +74,7 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.9.4
77
+ oats.framework: v1.10.0
78
78
  oats.okf: v5.0.3
79
79
  oats.aweb: v1.27.1
80
80
  teams:
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.3", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.4", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.0", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.9.4`
362
- resolves to tag `oats-framework/v1.9.4`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.10.0`
362
+ resolves to tag `oats-framework/v1.10.0`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -11,6 +11,20 @@ to do on a host, and what: restart the instances and, where schedules run,
11
11
  install the host timer again; before that, install the CLI again where it is
12
12
  installed inside the Node version.
13
13
 
14
+ - **Where the Desktop is installed, install Desktop 0.53.0 before the CLI
15
+ ([#1107](https://github.com/awebai/oats/issues/1107)).** A 0.52.0 Desktop
16
+ refuses a 0.53.0 CLI and lists no instance until it is replaced. Desktop
17
+ 0.53.0 accepts the older CLI in the meantime. This includes an
18
+ `oats update` whose plan installs the CLI.
19
+
20
+ - **A host that comes from 0.51 or earlier does 0.52.0's
21
+ [Upgrade steps](v0.52.0.md#upgrade) first, in their order.** One of them is
22
+ easy to miss because it is a host tool and not OATS: aw 1.36.33 or later,
23
+ before `oats sync`. The sync to this release's catalog locks oats.aweb
24
+ 1.27.1, which refuses every new spawn below that version. After the sync,
25
+ `oats readiness --soul <name>` shows it as a failed provider check, with
26
+ the install that cures it.
27
+
14
28
  - **Once the CLI is 0.53.0, run `oats update` in each deployment that
15
29
  launches pi instances.** It now moves the pi bridge in every pi folder that
16
30
  deployment's launch configurations name, and `oats doctor` warns about each
@@ -0,0 +1,142 @@
1
+ # OATS 0.54.0
2
+
3
+ 2026-10-13
4
+
5
+ ## Upgrade
6
+
7
+ - **Nothing is required.** Install the Desktop first and the CLI second, as
8
+ [Upgrading](../upgrading.md) says: a 0.53.0 Desktop refuses a 0.54.0 CLI.
9
+
10
+ - **To get the skill `/oats-token-saving`,** pin `oats.framework: v1.10.0`
11
+ in your workspace and run `oats sync`. Instances already running keep the
12
+ briefing and the skills they were spawned with; new spawns get the new
13
+ ones. See Added and Provider updates.
14
+
15
+ - **A script that reads a refusal about a repository reference** (its
16
+ message, or `details.ref`, `details.url`, `details.value`) now reads a
17
+ display form: user information is never in it; a refused value made only
18
+ of letters, digits, spaces and `._/+-:` is shown as written; any other
19
+ value that cannot be rebuilt from its parts is replaced whole by a fixed
20
+ text. See Changed and Fixed
21
+ ([#1077](https://github.com/awebai/oats/issues/1077)). Codes and field
22
+ shapes are unchanged, and so is the reference Git itself is given.
23
+
24
+ - **The official catalog's versions in this release** are oats.framework
25
+ 1.10.0, oats.okf 5.0.3, oats.aweb 1.27.1 and oats.engineering 1.9.1: see
26
+ Provider updates. Pin what your workspace uses, then run `oats sync`.
27
+
28
+ ## Added
29
+
30
+ - **`oats.core`: the skill `/oats-token-saving`, and three lines of its
31
+ briefing** ([#1103](https://github.com/awebai/oats/issues/1103)). A message
32
+ between instances costs twice: the sender writes it, and the receiver is
33
+ woken, reads it with its whole context and often answers. The skill gives
34
+ one test before sending, "who will do something different because of this,
35
+ and what?", and the rules that follow from it:
36
+ - **to whom:** only the instance that will act on it, with no copies and no
37
+ sending to every holder of a role;
38
+ - **what not to send:** acknowledgements and courtesy, progress and status,
39
+ what a shared record already shows, someone else's words passed along, and
40
+ the story of how the sender got there. A message that needs a confirmation
41
+ says so and gets one line back;
42
+ - **don't ask for what you can read,** and never ask for progress reports or
43
+ set a helper up to send them;
44
+ - **what a message holds:** first what the receiver must do, exact
45
+ references, one topic, one message per task boundary. A spec, a brief or a
46
+ review's findings is the long message, sent once as a file or a link;
47
+ - **what is never cut:** what moves work, what a role owes, and what is owed
48
+ on a record (a verdict on the pull request, a decision on its issue, the
49
+ evidence of a hand-over, the report of a fault or of one's own mistake).
50
+
51
+ The skill is provider-neutral: it names no messaging capability, and how to
52
+ send stays with that capability's own skill. The `oats.core` briefing, which
53
+ every instance with `oats.core` reads, gains the test in three lines, so it
54
+ applies before the skill is loaded. An instance spawned before the release
55
+ that carries this keeps its briefing; new spawns get it
56
+ ([`oats.core`](../souls-and-instances.md)).
57
+
58
+ ## Changed
59
+
60
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.55.0`.** The compatibility band
61
+ admits 0.54. Upgrade the CLI and the Desktop together: a 0.53.0 Desktop
62
+ refuses a 0.54.0 CLI. No new gate on the band. `oats tui` runs the kernel it
63
+ ships with and is held to the same band.
64
+
65
+ - **Diagnostic messages, details, provenance and workspace `cannot-read` values
66
+ now preserve bounded plain refused values, construct displays that omit user
67
+ information (including SSH users), or withhold the reference, while the seven
68
+ rejected argument fields share the bounded plain rule and Git lines are shown
69
+ only for unchanged original operation references
70
+ and no literal `@` in the original line, replacing
71
+ [#1075](https://github.com/awebai/oats/issues/1075)'s scrubbed-line behavior
72
+ ([#1077](https://github.com/awebai/oats/issues/1077)).**
73
+
74
+ ## Fixed
75
+
76
+ - **Repository diagnostics no longer copy user information from selected
77
+ references ([#1077](https://github.com/awebai/oats/issues/1077)).** Messages,
78
+ reference-bearing details and provenance, schema problems and workspace
79
+ `cannot-read` fields use a display constructed from recognised host and path
80
+ components, with a verbatim exception for original refused values of 1–256
81
+ ASCII letters, digits, spaces or `._/+-:` characters. The same predicate
82
+ serves the seven selected rejected arguments; it never trims or decodes an
83
+ input. Malformed or mixed values outside that rule are withheld whole,
84
+ including harmless text, while known declaration files and key locations
85
+ remain available. Raw derived fragments qualify for the plain exception only
86
+ through their original selected source, never from a nonplain source. Plain
87
+ recognition is not a secret detector: credential-like text within the
88
+ permitted alphabet remains visible.
89
+ Git's own line is shown only when all original operation references are
90
+ proved unchanged by display construction and the original line contains no
91
+ `@`; otherwise the whole line becomes a fixed notice directing the operator
92
+ to run the operation by hand. No substring is recovered. This replaces the
93
+ quoted-line disclosure behavior shipped for unknown Git failures.
94
+ See the [diagnostic display contract](../workspaces.md#repository-references-in-diagnostics).
95
+ Standalone file/path meanings, command-consumed values and Git's original
96
+ transport reference are unchanged.
97
+ Explicit pinned-source diagnostics keep a constructed reference and its
98
+ validated commit, or withhold the whole source without a plain fallback.
99
+ Rejected argument values use the contract's bounded plain-value rule and
100
+ neutral withholding notice; valid operational arguments are unchanged. Unknown Git failures quote only
101
+ stderr: empty stderr adds no line unless output overflow needs a kernel budget notice.
102
+
103
+ - **Repository and package refusals explain an omitted reference without
104
+ exposing it ([#1077](https://github.com/awebai/oats/issues/1077)).** The
105
+ originating refusal explains withholding or user-information omission once;
106
+ existing message slots keep the explanation when forwarding it. HTTP(S)
107
+ userinfo refusals keep their specific cause and credential-helper advice,
108
+ and package refusals keep their own reason. Admission, codes and field shapes
109
+ are unchanged.
110
+
111
+ - `oats souls` and `oats capabilities` now show every catalog discovery
112
+ problem below their text tables, including unreadable locked package
113
+ souls. Diagnostics stay on stdout in JSON order, with the kernel's code
114
+ and message; partial listings still exit 0
115
+ ([#1098](https://github.com/awebai/oats/issues/1098)).
116
+
117
+ ## Provider updates
118
+
119
+ - **oats.framework 1.10.0: oats.core 2.6.0.** One new skill and three lines
120
+ of instruction text in oats.core; no hook, command, schema or provider
121
+ contract changes, and the capability floors are unchanged (oats.core
122
+ `>=0.40.0`).
123
+ - oats.core gains the skill `/oats-token-saving` and names it in its
124
+ briefing, as the entry under Added says
125
+ ([#1103](https://github.com/awebai/oats/issues/1103)). The two commands
126
+ the skill tells an instance to read before asking, `oats status` and
127
+ `oats instance events <instance>`, exist in every kernel oats.core
128
+ admits.
129
+ - A deployment gets it by pinning `oats.framework: v1.10.0` and running
130
+ `oats sync`. Instances already running keep the briefing and the skills
131
+ they were spawned with; new spawns get the new ones.
132
+
133
+ ## Documentation
134
+
135
+ - **Upgrading: the Desktop goes before the CLI
136
+ ([#1107](https://github.com/awebai/oats/issues/1107)).**
137
+ [Upgrading OATS on a host](../upgrading.md) now says so, and why: a
138
+ Desktop refuses a CLI of a newer minor version, so with the CLI moved
139
+ first it lists no instance until it is replaced. The Upgrade section of
140
+ the [0.53.0 notes](v0.53.0.md#upgrade) gained that step, and one for a
141
+ host that comes from 0.51 or earlier: 0.52.0's steps first, the aw client
142
+ among them, before `oats sync`.
@@ -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,7 +54,7 @@ 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
57
+ oats.framework: v1.10.0 # bare version → resolves through the official catalog
58
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
 
@@ -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();