@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
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
@@ -4051,7 +4061,7 @@ async function experimentalCmd() {
4051
4061
  /** `oats server add|list|remove|check`. A registration is where and how:
4052
4062
  * an OpenSSH host alias, the remote workspace, the remote oats path. Keys
4053
4063
  * and passwords never enter it; ssh owns those. */
4054
- function serverCmd() {
4064
+ async function serverCmd() {
4055
4065
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
4056
4066
  const sub = args[1];
4057
4067
  const usage = "usage: oats server add <id> --ssh <host-alias> --workspace </abs/path> [--oats <path>] [--path <dir:dir>] [--label <text>] [--replace] | connect <id> --ssh <host-alias> [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] | list [--workspace-ref <ref>] | remove <id> | check <id> | roster [--server <id>] | forget <id> --instance <name> [--json]";
@@ -4073,12 +4083,12 @@ function serverCmd() {
4073
4083
  }
4074
4084
  if (sub === "roster") {
4075
4085
  // The remote roster for the Desktop and operators: grouped by saved route
4076
- // target, one bounded status pull per target, saved routes as the action
4086
+ // target, one bounded status pull per target, all at once, saved routes as the action
4077
4087
  // authority. --server narrows to one registry id.
4078
4088
  const only = flag("server") === true ? bail("E_BAD_ARGS", "--server needs a registered server id") : flag("server");
4079
4089
  const ms = (name) => { const v = flag(name); if (v === undefined) return undefined; const n = Number(v); if (!Number.isInteger(n) || n < 1000) bail("E_BAD_ARGS", `--${name} takes whole milliseconds, at least 1000`); return n; };
4080
4090
  let out;
4081
- try { out = rosterGroups({ server: only, io: { budgetMs: ms("budget"), perTargetTimeoutMs: ms("per-target") } }); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4091
+ try { out = await rosterGroups({ server: only, io: { budgetMs: ms("budget"), perTargetTimeoutMs: ms("per-target") } }); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4082
4092
  if (JSON_MODE) { jsonOk(out); return; }
4083
4093
  if (!out.groups.length) { console.log("no remote groups: no registrations and no saved routes"); return; }
4084
4094
  for (const g of out.groups) {
@@ -4087,7 +4097,7 @@ function serverCmd() {
4087
4097
  for (const i of g.instances) console.log(` • ${i.instance} ${i.missingRemotely ? "GONE on the host (saved route is stale: oats server forget)" : i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown"}${i.retirePending ? " RETIRING" : ""}${i.rollbackIncomplete ? " QUARANTINED" : ""}${i.savedRoute ? "" : " (observed only, no saved route)"}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4088
4098
  for (const f of g.retireFailures || []) console.log(` ! deferred retirement of ${f.instance} (${f.agent}) FAILED there${f.error?.message ? `: ${f.error.message}` : ""}${f.retry ? ` — retry on the host: ${f.retry}` : ""}`);
4089
4099
  }
4090
- console.log(` bounds: ${out.bounds.perTargetTimeoutMs} ms per target within ${out.bounds.budgetMs} ms, ${out.bounds.elapsedMs} ms used${out.bounds.skipped ? `, ${out.bounds.skipped} target(s) not reached` : ""}`);
4100
+ console.log(` bounds: ${out.bounds.perTargetTimeoutMs} ms per target within ${out.bounds.budgetMs} ms, ${out.bounds.elapsedMs} ms used`);
4091
4101
  return;
4092
4102
  }
4093
4103
  let servers;
@@ -4546,7 +4556,7 @@ else {
4546
4556
  const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
4547
4557
  if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
4548
4558
  if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
4549
- else if (cmd === "server") serverCmd();
4559
+ else if (cmd === "server") await serverCmd();
4550
4560
  else if (cmd === "inspect") await inspectCmd();
4551
4561
  else if (cmd === "operation") await operationCmd();
4552
4562
  else if (cmd === "launch-config") await launchConfigCmd();
@@ -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
@@ -2806,9 +2827,14 @@ route target:
2806
2827
  ```
2807
2828
 
2808
2829
  - **`probe`**: `{ok: true, features}` when the host's `status --json` was
2809
- pulled, else `{ok: false, error: {code, message}}` (ssh failed, the host
2810
- answered `ok: false`, or `E_ROSTER_BUDGET`: the roster's budget ran out
2811
- before this target), with no `features` key.
2830
+ pulled, else `{ok: false, error: {code, message}}` (ssh failed or timed
2831
+ out, `E_SSH`; or the host answered `ok: false`), with no `features` key.
2832
+ Every group is probed at once, each within its own deadline, so a group's
2833
+ `probe` depends only on its own host: one that does not answer in time is
2834
+ `E_SSH` with `ssh to <host> timed out: no answer within <n> s`, and every
2835
+ other group is unaffected. Before 0.55.0 the probes ran one after another
2836
+ against the total budget, and a group the budget did not reach was
2837
+ `E_ROSTER_BUDGET`; that code is no longer answered.
2812
2838
  - **`probe.features`** (feature `server-probe-features`, OATS 0.49.0): the
2813
2839
  host's kernel features, relayed from the top-level `features` of its
2814
2840
  [`status --json`](#the-roster-oats-status---json), never probed: the roster
@@ -2824,7 +2850,7 @@ route target:
2824
2850
  - **`workspace`** (feature `workspace-identity`, OATS 0.36.0): the host's
2825
2851
  own `status --json` [`workspace` object](#workspace-identity-feature-workspace-identity-oats-0360),
2826
2852
  relayed verbatim, or `null` when the host reports none (a deployment
2827
- without `oats-local.yaml`, or a failed or skipped probe). A host before
2853
+ without `oats-local.yaml`, or a failed probe). A host before
2828
2854
  0.36.0 answers the reachability-only object (`{reachable, code?, reason?,
2829
2855
  message?}`) with no identity fields, so the identity is there only when
2830
2856
  the object has a `key` field (which a 0.36.0 host always sends, `null` for
@@ -2863,6 +2889,12 @@ route target:
2863
2889
  - `running` is `null` when unknown; `backend` is `tmux` for a row with a tmux
2864
2890
  target, else `null`; `tmux`, `sessionTarget` (the recorded target of a home
2865
2891
  a Herdr-era kernel opened) and `runtimeError` are as the host reports them.
2892
+ - **`bounds`**: `{budgetMs, perTargetTimeoutMs, elapsedMs}`. Each group's
2893
+ probe may take the smaller of `perTargetTimeoutMs` (`--per-target`,
2894
+ default 20 s) and `budgetMs` (`--budget`, default 45 s, the deadline of the
2895
+ whole answer); `elapsedMs` is what the answer took, about the slowest
2896
+ group's probe. Before 0.55.0 `bounds` also carried `skipped`, the number of
2897
+ groups the budget did not reach; it is gone with `E_ROSTER_BUDGET`.
2866
2898
 
2867
2899
  <a id="servers-per-workspace"></a>
2868
2900
  ### Servers per workspace (feature `servers-per-workspace`)
@@ -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`
@@ -40,8 +40,8 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.0.3
44
- oats.aweb: v1.27.1
43
+ oats.okf: v5.0.5
44
+ oats.aweb: v1.27.2
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 5.0.3**. Provider implementation and
9
+ This is the operator guide for **oats.okf 5.0.5**. Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
 
12
12
  | Surface | What it holds |
@@ -23,7 +23,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
23
23
  ```yaml
24
24
  # oats-workspace.yaml (excerpt)
25
25
  packages:
26
- oats.okf: v5.0.3
26
+ oats.okf: v5.0.5
27
27
  defaults:
28
28
  knowledge: { oats.okf: { from: package } }
29
29
  stores:
@@ -161,6 +161,18 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
161
161
  automatic transcript capture, source registry, worker cursor or retire
162
162
  harvest. An unrelated harvester can outlive its source; this is a
163
163
  lifecycle property, not proof that missing source authority can be ignored.
164
+
165
+ One proposal per checkpoint, each concept a claim of its own in it, and
166
+ claims only for the nodes the source soul owns; a lesson for a node it only
167
+ reads goes in one line in the instance's hand-back, for that node's owner.
168
+ One harvester at a time, per instance (oats.okf 5.0.5): the source notes the
169
+ harvester's instance name and spawns no other while `oats status` still
170
+ lists it, since a harvester retires once it has handed over. What it learns
171
+ meanwhile goes into its next proposal; an instance that hands back with one
172
+ still listed names it and the claims still waiting. A harvester retained
173
+ after a publication failure stays listed, so it holds back its source's
174
+ later proposals: once that failure is dealt with, the operator retires it
175
+ (`oats retire <harvester>`).
164
176
  3. **Judge and submit.** The harvester checks recorded source configuration,
165
177
  accepted knowledge and open/recent harvest PRs. It reads named backing
166
178
  notes, edits only owned nodes in its own Git checkout, validates the
@@ -9,10 +9,10 @@ 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` |
13
- | `oats.okf` | `v5.0.3` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.27.1` | `oats.aweb` (messaging) | |
15
- | `oats.engineering` | `v1.9.1` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
12
+ | `oats.framework` | `oats-framework/v1.10.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.0.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.27.2` | `oats.aweb` (messaging) | |
15
+ | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
29
29
  ## Find and use packages
30
30
 
31
31
  - A workspace pins an official package by **bare version** in its
32
- `packages:` map (`oats.okf: v5.0.3`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.0.5`); `oats sync` resolves it through the
33
33
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
34
34
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
35
35
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v5.0.3 # bare version → the official catalog
47
+ oats.okf: v5.0.5 # bare version → the official catalog
48
48
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
49
  ```
50
50
 
51
- - **Bare version** (`v5.0.3`, `5.0.3`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.0.5`, `5.0.5`, `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.5` 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,9 +74,9 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.9.4
78
- oats.okf: v5.0.3
79
- oats.aweb: v1.27.1
77
+ oats.framework: v1.10.0
78
+ oats.okf: v5.0.5
79
+ oats.aweb: v1.27.2
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -105,7 +105,7 @@ decision recorded in the lock.
105
105
  $ oats sync
106
106
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
107
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.3 ✓ (@ e687a94a)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.5 ✓ (@ 73b85020)
109
109
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
110
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
111
  teams platform (shared) · this deployment's: oats teams
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
134
134
  ## `oats package add | remove`
135
135
 
136
136
  ```bash
137
- oats package add oats.aweb v1.27.1 # a catalog version
137
+ oats package add oats.aweb v1.27.2 # a catalog version
138
138
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
139
139
  oats package remove acme.tools
140
140
  ```
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
160
160
  "source": "catalog:oats.okf",
161
161
  "url": "https://github.com/awebai/oats-okf.git",
162
162
  "path": "oats-package",
163
- "version": "5.0.3",
164
- "commit": "e687a94a40494521a671979dd168e3d62b11bcde",
163
+ "version": "5.0.5",
164
+ "commit": "73b85020e52b8584cb15f153a39712f900e69918",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
352
352
  {
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
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" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.5", "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`.