@awebai/oats 0.56.0 → 0.57.1

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 (64) hide show
  1. package/bin/oats.mjs +18 -10
  2. package/docs/configuration.md +17 -27
  3. package/docs/desktop-cli-api.md +59 -3
  4. package/docs/desktop.md +25 -4
  5. package/docs/execution-targets.md +6 -1
  6. package/docs/implementation.md +106 -5
  7. package/docs/integrations.md +8 -4
  8. package/docs/knowledge.md +93 -38
  9. package/docs/official-catalog.md +3 -3
  10. package/docs/packages.md +12 -12
  11. package/docs/release-notes/v0.57.0.md +283 -0
  12. package/docs/release-notes/v0.57.1.md +275 -0
  13. package/docs/schedules.md +8 -3
  14. package/docs/servers.md +18 -0
  15. package/docs/souls-and-instances.md +126 -15
  16. package/docs/tui.md +333 -95
  17. package/docs/workspaces.md +2 -2
  18. package/lib/core.mjs +439 -126
  19. package/lib/instance-lifecycle.mjs +45 -9
  20. package/lib/session-viewer.mjs +29 -4
  21. package/lib/worktree.mjs +23 -2
  22. package/package-catalog.json +2 -2
  23. package/package.json +1 -1
  24. package/packages/client/cli-adapter.mjs +9 -7
  25. package/packages/client/cli-locator.mjs +2 -2
  26. package/packages/client/composed-gate.mjs +34 -0
  27. package/packages/client/inspect-boundary.mjs +157 -0
  28. package/packages/client/inspect-cache.mjs +86 -0
  29. package/packages/client/instance-lifecycle.mjs +10 -3
  30. package/packages/client/keyed-catalog.mjs +132 -0
  31. package/packages/client/launch-prompt-outcome.mjs +1 -1
  32. package/packages/client/launch-view.mjs +46 -0
  33. package/packages/client/session-attach.mjs +7 -5
  34. package/packages/client/soul-catalog.mjs +77 -0
  35. package/packages/client/soul-colors.mjs +31 -0
  36. package/packages/client/soul-facts.mjs +85 -0
  37. package/packages/client/soul-rows.mjs +48 -0
  38. package/packages/client/spawn-apply-cli.mjs +11 -6
  39. package/packages/client/spawn-apply.mjs +212 -0
  40. package/packages/client/spawn-messages.mjs +131 -85
  41. package/packages/client/spawn-preview-contract.mjs +3 -0
  42. package/packages/client/spawn-preview-facts.mjs +119 -0
  43. package/packages/client/spawn-preview.mjs +152 -0
  44. package/packages/client/spawn-transaction.mjs +136 -0
  45. package/packages/tui/README.md +43 -13
  46. package/packages/tui/lib/actions.mjs +18 -2
  47. package/packages/tui/lib/client.mjs +4 -0
  48. package/packages/tui/lib/config.mjs +9 -14
  49. package/packages/tui/lib/main.mjs +241 -55
  50. package/packages/tui/lib/model.mjs +230 -29
  51. package/packages/tui/lib/panel.mjs +955 -0
  52. package/packages/tui/lib/read.mjs +134 -24
  53. package/packages/tui/lib/store.mjs +184 -31
  54. package/packages/tui/lib/term/capture.mjs +260 -0
  55. package/packages/tui/lib/term/screen.mjs +44 -8
  56. package/packages/tui/lib/term/style.mjs +78 -6
  57. package/packages/tui/lib/term/text.mjs +24 -4
  58. package/packages/tui/lib/term/through.mjs +213 -0
  59. package/packages/tui/lib/term/tty.mjs +7 -60
  60. package/packages/tui/lib/views/act.mjs +85 -0
  61. package/packages/tui/lib/views/frame.mjs +153 -37
  62. package/packages/tui/lib/views/help.mjs +22 -14
  63. package/skills/oats-getting-started/SKILL.md +4 -3
  64. package/packages/tui/lib/open.mjs +0 -45
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.1.0** (OATS **>=0.49.0**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.2.0** (OATS **>=0.49.0**). 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 |
@@ -14,6 +14,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
14
14
  | Accepted Git or directory bases | Soul knowledge: OKF concepts in owned nodes. |
15
15
  | `souls/<name>/okf.json` | The soul's stable owner and owned/read nodes. |
16
16
  | Instance home: `STATE.md`, `log.md`, `notes/` | The instance's working knowledge. |
17
+ | Instance home: `okf-harvest-policy.json` | Provider-written duty at spawn, exposed by `oats okf status`; not publication authority. |
17
18
  | Harvester home: `harvest-source/` | Private source evidence captured at spawn, not accepted knowledge. |
18
19
  | Bindings file and `stateDir` | Host base locations and consultation/binding state, not a harvest queue. |
19
20
 
@@ -24,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
24
25
  ```yaml
25
26
  # oats-workspace.yaml (excerpt)
26
27
  packages:
27
- oats.okf: v5.1.0
28
+ oats.okf: v5.2.0
28
29
  defaults:
29
30
  knowledge: { oats.okf: { from: package } }
30
31
  stores:
@@ -49,10 +50,15 @@ settings:
49
50
 
50
51
  Upgrading from 4.x requires the ordered
51
52
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
52
- just editing a version line. For 5.1.0, upgrade to OATS >=0.49.0 before moving
53
- the provider pin: that kernel first supports the public source-event lookup
54
- after retirement. Re-spawn harvesters to receive the new capture hook and
55
- instructions; restarting a session keeps its copied provider.
53
+ just editing a version line. For 5.2.0, OATS >=0.49.0 remains required:
54
+ that kernel first supports the public source-event lookup after retirement.
55
+
56
+ **Upgrade:** pin `oats.okf: v5.2.0` and run `oats sync`. Only new spawns get
57
+ the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
+ homes keep their copied provider even after a session restart. Deployments
59
+ whose briefings never mentioned harvesting now get knowledge proposals at
60
+ eligible checkpoints; souls not ready for this must declare
61
+ `knowledge: { harvest: off }`. Consultation and instance-memory upkeep remain.
56
62
 
57
63
  ### Bindings document
58
64
 
@@ -142,9 +148,11 @@ soul's opt-out:
142
148
  knowledge: { harvest: off }
143
149
  ```
144
150
 
145
- That soul keeps consultation and working-memory guidance, receives no
146
- checkpoint-harvest directive, and its material is refused by the
147
- harvester's required spawn hook. Absence gives the normal proposal flow.
151
+ That soul keeps consultation and working-memory guidance but has no harvest
152
+ duty. The shared IMPORTANT block and compulsory skill pointer still ship,
153
+ with an explicit exception; the provider's spawn-recorded answer says `off`.
154
+ Independently, the harvester's required spawn hook refuses that soul's
155
+ material. Absence gives the normal proposal flow.
148
156
  A soul's `harvest: on` is not a replacement switch. Host cleanup never
149
157
  changes the soul declaration. `knowledge: none` removes the layer entirely.
150
158
 
@@ -152,36 +160,66 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
152
160
 
153
161
  ### The flow
154
162
 
155
- 1. **Consult.** Read accepted soul knowledge at task start, after compaction
156
- and before decisions; keep instance `STATE.md`, `log.md` and `notes/`.
157
- Working instances never write accepted knowledge themselves.
158
- 2. **Propose at checkpoints.** When work merits a checkpoint, update notes
159
- and write a self-contained proposal: what to save, why and the backing
160
- notes. It has exactly one line `Source: instance <name>, home <path>, soul
161
- <name>` naming the actual source. From the source home:
163
+ 1. **Consult and keep instance knowledge current.** Read accepted soul
164
+ knowledge at task start, after compaction and before decisions. Keep
165
+ `STATE.md`, `log.md` and `notes/` up to date as work happens. The
166
+ capability's **IMPORTANT** inject block makes this upkeep and eligible
167
+ checkpoint harvesting a duty; reading **okf-propose** is compulsory.
168
+ Neither duty depends on TASK.md. Run `oats okf status` from instance home
169
+ to learn the duty recorded at spawn: `on` means follow the skill, `off`
170
+ means no harvest, and `unknown` or an error means stop and report, never
171
+ infer permission or edit the record. Working instances never write
172
+ accepted knowledge themselves.
173
+ 2. **Propose only at a finished task or PR hand-over.** First update state,
174
+ log and relevant notes. Apply `knowledge-theory` and search accepted
175
+ knowledge (`oats okf search`, then `cat`): already accepted with nothing
176
+ to add means no proposal. Most checkpoints propose nothing. Make at most
177
+ **one proposal for that completed unit of work**; handing over its PR and
178
+ closing the same task are not two opportunities. Never launch per commit,
179
+ per decision, per review round or merely because a PR opened.
180
+
181
+ Write a short self-contained `proposals/<YYYY-MM-DD>-<slug>.md` in instance
182
+ home: What (one claim per concept), Why, Evidence (observations, dates,
183
+ limits and accepted concepts cited), and optional `## Backing notes` with
184
+ one `- notes/<file>.md` entry per note. It has exactly one line
185
+ `Source: instance <name>, home <path>, soul <name>` naming the actual
186
+ source, a pointer to verify rather than authority. Claim only for owned
187
+ nodes; a lesson for a node the soul only reads is named in one line in its
188
+ hand-back for that node's owner.
189
+
190
+ **Before spawning:** one harvester at a time per instance. Record its
191
+ returned name and proposal in log.md, and do not spawn another while
192
+ `oats status` still lists the last one. Check available memory immediately
193
+ before spawning: on Linux, `free -g` must show at least 8 GB available;
194
+ elsewhere use the host's documented check. If availability cannot be
195
+ established, is below the floor, or the host is under memory pressure,
196
+ defer. These are instructions, not a scheduler or a memory reservation.
197
+ Keep deferred proposals/notes and record the reason and waiting claims in
198
+ STATE.md, log.md and the hand-back. Reconsider at a natural task boundary,
199
+ never by polling, sleeping or stopping other instances to make room.
200
+
201
+ From instance home, preview and then apply the skill's command when the
202
+ gates permit it:
162
203
 
163
204
  ```sh
164
205
  oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
165
206
  ```
166
207
 
167
- Never combine `--relation unrelated` with `--relative-to`. There is no
208
+ Never combine `--relation unrelated` with `--relative-to`, or override
209
+ the kernel's harness/model selection. An unrelated harvester can outlive
210
+ its proposer; a child would tie their lifetimes together. There is no
168
211
  automatic transcript capture, source registry, worker cursor or retire
169
- harvest. An unrelated harvester can outlive its source. Proposers need
170
- not stay alive: the harvester can check their recorded retirement recovery.
171
- Keep backing evidence in the source home or that recovery until capture;
172
- never treat missing source authority as permission to invent it.
173
-
174
- One proposal per checkpoint, each concept a claim of its own in it, and
175
- claims only for the nodes the source soul owns; a lesson for a node it only
176
- reads goes in one line in the instance's hand-back, for that node's owner.
177
- One harvester at a time, per instance: the source notes the
178
- harvester's instance name and spawns no other while `oats status` still
179
- lists it, since a harvester retires once it has handed over. What it learns
180
- meanwhile goes into its next proposal; an instance that hands back with one
181
- still listed names it and the claims still waiting. A harvester retained
182
- after a publication failure stays listed, so it holds back its source's
183
- later proposals: once that failure is dealt with, the operator retires it
184
- (`oats retire <harvester>`).
212
+ harvest. Keep backing notes until the harvester retires; the proposer
213
+ itself need not stay alive. Its recorded retirement recovery can supply
214
+ evidence before capture, so do not dispose of it before capture.
215
+ Missing source authority never permits inventing it.
216
+
217
+ A refused or uncertain spawn is reported, not retried in a loop. If the
218
+ last harvester is still listed at hand-back, name it and the claims still
219
+ waiting; do not wait for it or spawn around it. A harvester retained after
220
+ a publication failure stays listed and holds back later proposals. Once
221
+ that failure is dealt with, the operator retires it (`oats retire
222
+ <harvester>`).
185
223
  3. **Capture, judge and submit.** Before the model starts, the required spawn
186
224
  hook checks the source's live record or the completed recovery named by
187
225
  its public retirement event. Source identity, single-incarnation history,
@@ -227,7 +265,7 @@ is historical 4.x context, not instructions for operating 5.0.
227
265
 
228
266
  Secrets, credentials, private paths and verbatim third-party messages are
229
267
  left out. So is personal data, in the same sentence at every place an agent
230
- is told what to leave out (the capturing instance, the proposal brief, the
268
+ is told what to leave out (the capturing instance, the proposing skill, the
231
269
  harvester when it edits and when it reads its diff, and the maintainer's
232
270
  review):
233
271
 
@@ -264,13 +302,14 @@ this provider. See [Knowledge harvest and review](schedules.md#knowledge-harvest
264
302
 
265
303
  | Capability | Composed into | Skills |
266
304
  |---|---|---|
267
- | `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), `knowledge-theory` |
305
+ | `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), [`okf-propose`](../mirrors/oats-okf/skills/okf-propose/SKILL.md), `knowledge-theory` |
268
306
  | `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../mirrors/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` |
269
307
  | `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` | `knowledge-theory`, [`knowledge-review`](../mirrors/oats-okf-maintenance/skills/knowledge-review/SKILL.md), `okf-authoring`, [`okf-trigger-setup`](../mirrors/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md) |
270
308
 
271
- Only the working soul's eligible **spawn brief** gives the proposal-spawn
272
- command. Shared consultation injects/skills also reach opted-out souls and
273
- do not unconditionally direct a harvest.
309
+ The capability's **IMPORTANT** inject block gives the duty and compulsory
310
+ pointer; **okf-propose** holds the procedure. These shared texts also reach
311
+ opted-out souls, with the explicit exception and provider status answer.
312
+ No source TASK brief contains harvest or proposal direction.
274
313
 
275
314
  ## Inspection and operator commands
276
315
 
@@ -304,6 +343,22 @@ are rooted in the base, never outside it. A failed fetch may serve cached
304
343
  accepted bytes marked stale. `read` and `refresh` remain removed: use `cat`
305
344
  and `index`. The consultation skill teaches navigation and citation.
306
345
 
346
+ ### Read the harvest duty
347
+
348
+ ```sh
349
+ oats okf status --json
350
+ ```
351
+
352
+ The provider's answer is `result.harvest: "on"` with `reason: "default"`, or
353
+ `"off"` with `reason: "soul-opt-out"`. It reads only home-local spawn state,
354
+ not the network, bases, TASK.md or a soul file. Missing state is `"unknown"`
355
+ with `reason: "spawn-state-missing"`; malformed or linked state refuses.
356
+ Neither unknown nor failure permits a proposal. Report it and respawn with
357
+ the current provider; never hand-create a policy or reinterpret later
358
+ settings as the spawn decision. `--home PATH` selects an explicit home.
359
+ This answer is instruction state, not publication authority: the harvester
360
+ still independently checks its recorded source's opt-out.
361
+
307
362
  ### Inspect
308
363
 
309
364
  ```sh
@@ -9,8 +9,8 @@ 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.10.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.1.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
12
+ | `oats.framework` | `oats-framework/v1.12.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.27.3` | `oats.aweb` (messaging) | |
15
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` | |
@@ -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.1.0`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.2.0`); `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.1.0 # bare version → the official catalog
47
+ oats.okf: v5.2.0 # 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.1.0`, `5.1.0`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.2.0`, `5.2.0`, `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.1.0` or `oats-framework/v1.10.1`) and the payload path. An id
54
+ convention (`v5.2.0` or `oats-framework/v1.12.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,8 +74,8 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.10.1
78
- oats.okf: v5.1.0
77
+ oats.framework: v1.12.0
78
+ oats.okf: v5.2.0
79
79
  oats.aweb: v1.27.3
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
@@ -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.1.0 ✓ (@ 40265ac7)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.2.0 ✓ (@ 2ac86ccb)
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
@@ -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.1.0",
164
- "commit": "40265ac79eca54a76ae648462dbfc83ac370dbbe",
163
+ "version": "5.2.0",
164
+ "commit": "2ac86ccba6ea3da19acf43274dd6d30ab2037653",
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.1.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.1", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.0", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.0", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.10.1`
362
- resolves to tag `oats-framework/v1.10.1`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.12.0`
362
+ resolves to tag `oats-framework/v1.12.0`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,283 @@
1
+ # OATS 0.57.0
2
+
3
+ 2026-10-15
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.56 Desktop refuses a 0.57.0 CLI. The
9
+ 0.57.0 Desktop accepts OATS CLIs `>=0.26.0 <0.58.0`.
10
+
11
+ - **A script that runs `oats worktree remove`** may now get
12
+ `E_CHILDREN_RUNNING`: the tree is the work of an attached instance whose
13
+ session is running or cannot be read. Nothing is removed, and no flag
14
+ removes anyway: stop that instance (`oats instance stop <instance>`) or
15
+ retire it, then remove again. **A script that attaches a spawn to a tree of
16
+ no known instance** gets one `E_BAD_ARGS` naming every flag still missing,
17
+ where it got a repository refusal and then `E_SPAWN_FAILED` on the retry.
18
+ See Changed ([#958](https://github.com/awebai/oats/issues/958),
19
+ [#964](https://github.com/awebai/oats/issues/964)).
20
+
21
+ - **A retire plan taken before the upgrade** is refused once by the 0.57.0
22
+ kernel with `E_PLAN_STALE` and the fresh plan: the plan's revision now also
23
+ binds the instances attached to each tree. Read the fresh plan and retire
24
+ with it. See Changed ([#964](https://github.com/awebai/oats/issues/964)).
25
+
26
+ - **On Linux and Windows the Desktop's palette is Ctrl+Shift+K,** and
27
+ Ctrl+Shift+P now opens Quick Open, from a focused terminal too. macOS keeps
28
+ ⌘K and ⌘P. See Changed
29
+ ([#1217](https://github.com/awebai/oats/issues/1217)).
30
+
31
+ - **To get the new provider versions,** pin `oats.framework: v1.10.2` and
32
+ `oats.okf: v5.2.0` in your workspace and run `oats sync`. Instances already
33
+ running keep what they were spawned with. See Provider updates.
34
+
35
+ - **Pin `oats.okf: v5.2.0` and run `oats sync`; only new spawns get the
36
+ capability-owned harvest duty.** Existing homes keep their copied provider
37
+ and instructions, including across session restarts. Deployments whose
38
+ task briefings never mentioned harvests now propose eligible knowledge at
39
+ finished tasks or PR hand-overs. Souls not ready for that must declare
40
+ `knowledge: { harvest: off }`; consultation and working-memory upkeep
41
+ remain. OATS >=0.49.0 is still required.
42
+
43
+ - **The official catalog's versions in this release** are oats.framework
44
+ 1.10.2, oats.okf 5.2.0, oats.aweb 1.27.3, oats.engineering 1.10.0,
45
+ oats.cloning 1.0.1, oats.authoring 1.0.3, oats.jira 1.0.1, oats.linear 1.0.1
46
+ and oats.apps 1.0.0.
47
+
48
+ ## Added
49
+
50
+ - **`oats tui` stops, starts, restarts and retires an agent**
51
+ ([#855](https://github.com/awebai/oats/issues/855)). With an instance
52
+ selected, `X` stops it, `D` retires it, `S` starts it and `R` restarts it,
53
+ each after a confirmation that opens with the focus on `Cancel`: the act
54
+ takes a move (`Left`/`Right` or `Tab`) and a press of `Enter`, and pasted
55
+ text never acts. The rules and the words are the Desktop's: a stop or a
56
+ retire shows the kernel's plan first and applies exactly that plan, on
57
+ this machine or on a registered one; a start or a restart uses the launch
58
+ recorded for the agent. An act you sent runs to its end whatever
59
+ `oats tui` does: closing the confirmation, quitting, a suspend or a signal
60
+ never ends it, and when you leave while one runs a line on standard error
61
+ says so. `tui.json` changes the keys (`stop`, `retire`, `start`,
62
+ `restart`). See [the TUI page](../tui.md#stopping-starting-restarting-and-retiring).
63
+
64
+ - **Desktop: each team has its own page, with your instances on it.** Click
65
+ a card under Workspace › Teams, or press Enter on its name, to open it. The
66
+ page shows the team's card at the top (its default, description, who may
67
+ join, address, problems and actions), then **Your instances on this team**:
68
+ how many there are, how many run, how many are stopped or need attention,
69
+ and on how many machines. Below that, each machine gets a card, with a
70
+ table of its instances: the name, the soul, the state, when it was created
71
+ and a Terminal button when it can be opened. A click on the name shows the
72
+ instance in the roster. The page lists only your instances, the ones on
73
+ this computer and on the machines you added to this workspace. Instances
74
+ other people run on the team are not listed. Back or Esc returns to the
75
+ board, on that team's card.
76
+
77
+ ## Changed
78
+
79
+ - **The Desktop accepts OATS CLIs `>=0.26.0 <0.58.0`**
80
+ ([#1211](https://github.com/awebai/oats/issues/1211)). The compatibility band
81
+ admits 0.57; a 0.56 Desktop refuses a 0.57 CLI. No new gate on the band.
82
+ `oats tui` runs the kernel it ships with and is held to the same band.
83
+
84
+ - **Desktop on Linux and Windows: the palette is Ctrl+Shift+K, and Quick Open
85
+ is Ctrl+Shift+P and works from a focused terminal**
86
+ ([#1217](https://github.com/awebai/oats/issues/1217)). Quick Open was
87
+ Ctrl+P, which a focused terminal keeps for the program in it (shell
88
+ history), so it did not open from there. **Ctrl+Shift+P changes meaning:**
89
+ it has opened the palette since 0.30.3 and now opens Quick Open; the
90
+ palette moves to Ctrl+Shift+K. While the palette is open, Ctrl+Shift+K
91
+ moves down its rows and ArrowUp moves up. xterm sends nothing for either
92
+ chord, so plain Ctrl+K and Ctrl+P still reach the program. A shortcut you
93
+ set yourself is kept; when it is one of these two chords, the shortcuts
94
+ editor shows the clash. A Quick Open shortcut you set yourself now works
95
+ from a terminal too: if it is a plain Ctrl+letter, such as Ctrl+P, the
96
+ program no longer gets that key, so choose a Ctrl+Shift chord. macOS is
97
+ unchanged (⌘K, ⌘P). See
98
+ [Desktop keyboard](../../packages/desktop/docs/desktop-keyboard.md).
99
+
100
+ - **An attached spawn on an extra tree derives its owner and its repository
101
+ (#958).** `oats spawn <soul> --work attached --work-dir
102
+ <home>/.work-<purpose>` was refused twice: first for the repository
103
+ (`pass --repo`), then, with that given, for the owner (`--parent
104
+ <instance>`). For `<home>/work` the kernel derived both. An extra tree of
105
+ a home is that home's tree too, so the same command now spawns with
106
+ neither flag: the owner is the instance in whose home the tree is, the new
107
+ instance is its child, and its repository is the repository of the tree
108
+ it is attached to (for an extra tree the one Git names for it, which can
109
+ be another member repository than the owner's own). `--parent <owner>`
110
+ and `--repo` given explicitly still work, so a command that passes both
111
+ runs on this kernel and on earlier ones. The tree is an extra tree by the
112
+ kernel's own test (a registered linked worktree in a home), never by the
113
+ shape of its path. Nothing changes for `<home>/work`, and no flag, key or
114
+ field changes.
115
+
116
+ A tree of no known instance still needs both flags. Its refusal is now
117
+ one, `E_BAD_ARGS`, and names every flag still missing: `attached workDir
118
+ <path> is not a known instance's <home>/work or an extra tree of a known
119
+ instance's home (<home>/.work-<purpose>), so neither its owner nor its
120
+ repository is derived — pass both: --parent <instance> (the owning
121
+ instance) and --repo <repository>`. With one of the two given it names
122
+ the other. Before, the missing repository was refused first (`no
123
+ repository for a attached instance — pass --repo (the work tree's owner
124
+ records none)`), and the missing owner only on the retry, under the code
125
+ `E_SPAWN_FAILED`. See
126
+ [`attached`](../souls-and-instances.md#attached--another-instances-tree).
127
+
128
+ - **A tree that goes away says what it leaves its attached instances with
129
+ (#964).** An instance can be attached to an extra tree of its owner as to
130
+ the owner's `work/` (#958). Four things change for such a tree:
131
+
132
+ - **A retire that re-homes an extra tree repoints its attached children**
133
+ to the tree's new path, as it does for `work/`: only the recorded
134
+ children the retire stopped, only once the tree is seen at its new path
135
+ with nothing left at the old one, and only a link that is still the one
136
+ the retire found. One that cannot be repointed is a warning in the
137
+ receipt, with the command to do it by hand.
138
+ - **A retire that removes a tree names the attached children it leaves
139
+ without one.** A clean extra tree is removed, as before, and so is
140
+ `work/` with `--discard-worktree`. The plan's note for the tree now
141
+ names its attached children and says that their `work` link would then
142
+ point at a path that is gone, and the receipt's `warnings` (and the
143
+ summary) say so afterwards, naming each child, the tree and the link.
144
+ Before, the plan and the receipt said nothing of them.
145
+ - **An attached instance the retire does not act on is named too.** An
146
+ instance that records the owner as its parent under a name that is not
147
+ unique is listed under the plan's `ambiguous` and is never stopped, so
148
+ its link is not repointed either. The plan's note for the tree it is
149
+ attached to (an extra tree, or `work/`) now names it and says that its
150
+ `work` link would then point at a path that is gone, and the receipt's
151
+ `warnings` say so for each tree that was moved or removed, with the
152
+ command to repoint the link by hand where the tree was re-homed. A
153
+ `--self` retirement's receipt does not carry those warnings.
154
+ - **`oats worktree remove` refuses a tree under a running session.** When
155
+ an instance attached to the tree has a session that is running, or that
156
+ cannot be read, the command answers `E_CHILDREN_RUNNING` before Git is
157
+ asked anything: nothing is removed and the record is kept. `details` is
158
+ `{purpose, path, children: [{instance, home, session}]}`, `session` being
159
+ `"running"` or `"unknown"`. The message names each instance and the
160
+ step: stop it (`oats instance stop <instance>`) or retire it, then remove
161
+ again. The command stops nobody, and no flag removes the tree anyway. An
162
+ attached instance whose session is stopped does not refuse: the tree is
163
+ removed and the answer's `warnings` name the instance and its link.
164
+
165
+ The new sentences are strings in arrays the plan and the answers already
166
+ have (`notes`, `warnings`): no key, field or flag is new, and a tree with
167
+ no attached instance is handled as before. `E_CHILDREN_RUNNING` is the code
168
+ a retire already answers, there for a child it asked to stop and that did
169
+ not; `oats worktree remove` answers it with `details` of its own and no
170
+ `childrenStopped`. See
171
+ [extra trees at retire](../souls-and-instances.md#extra-trees-at-retire)
172
+ and [extra trees](../souls-and-instances.md#extra-trees).
173
+
174
+ - **Desktop: the Workspace › Setup tab reads as one column.** The List view
175
+ puts what the workspace shares through Git above what lives only on this
176
+ computer. It shows the same facts as before.
177
+ - **Under the workspace's name**, a summary counts the members (and those
178
+ that need attention), the packages and the state of the lock. The line
179
+ under it says where the workspace is declared, for example "Declared in
180
+ agents's oats-workspace.yaml at 1a2b3c4."
181
+ - **An Overview** says that the host repository defines the workspace: its
182
+ members and its packages. **For developers**, folded, explains the two
183
+ links that make a repository a member: the host's workspace file lists
184
+ it, and its membership file names the workspace back. It also says what
185
+ each member state means. The Graph view shows the Overview too. The
186
+ legend of badges is gone.
187
+ - **Shared through Git** holds Members, Packages and Defaults. Only the
188
+ host's row carries a tag, **Host** with its workspace file; the Member
189
+ tag is gone from every row. A confirmed member shows a check and
190
+ "confirmed". Any other state keeps its warning chip. In a wide enough
191
+ window every row takes one line.
192
+ - **This computer** holds the deployment's folder, settings, lock, lock
193
+ file, CLI, instances and disabled souls, then the member clones, then the
194
+ Machines box. Instances reads "3, 1 running". The Machines box no longer
195
+ carries a "Not shared" tag; the zone says it.
196
+ - **The Graph view** labels read "Shared through Git", "Members, latest"
197
+ and "Packages, pinned", in sentence case.
198
+
199
+ - **Desktop: the Teams board is one calm column.** Shared teams, local teams
200
+ and which teams each soul may join each have a heading and one line saying
201
+ what they are. A team's card no longer lists its instances: it shows the
202
+ team's facts in labelled rows (Default for, May join, Address), any
203
+ warning with its fix, and a summary line at the bottom ("3 of your
204
+ instances, 1 on other machines"). A click anywhere on the card opens the
205
+ team's page, and each card is one Tab stop. Which teams each soul may join
206
+ is now a table: the pattern, its default team, and the other teams it may
207
+ also join. The type is calmer: fewer sizes and styles, no uppercase labels,
208
+ and the facts that matter stand out by size and weight, not by new colours.
209
+
210
+ ## Fixed
211
+
212
+ - **Released in 0.56.0, not noted there: the Desktop's terminals draw again
213
+ after a GPU process restart
214
+ ([#1190](https://github.com/awebai/oats/issues/1190), #1192).** After the GPU
215
+ process restarted, xterm's shared glyph store went stale and terminals
216
+ stopped drawing. They now draw again. A 0.56.0 or later Desktop has the
217
+ fix.
218
+
219
+ - **A retire's recovery of a worktree carries a stopped cherry-pick, revert,
220
+ rebase or merge, and the stash, in both ref formats
221
+ ([#1038](https://github.com/awebai/oats/issues/1038)).** The recovery
222
+ copied an operation's state as files of the Git directory. Three things
223
+ were missing from it, and nothing said so:
224
+ - where the repository stores its refs in the reftable format,
225
+ `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD` and `AUTO_MERGE` are not
226
+ files. The recovery had none of them, and its `git status` no longer said
227
+ a cherry-pick or a revert was in progress. The stash's log is not a file
228
+ there either: the recovery's `git stash list` was empty;
229
+ - in both formats, the commit or tree those refs and `MERGE_HEAD` name is
230
+ often in no branch (a commit reset away, a conflict's tree). The recovery
231
+ named it without holding it, so `git cherry-pick --continue`, `git merge
232
+ --continue` or a diff against `AUTO_MERGE` failed there;
233
+ - a link at one of the copied names was left out when it led nowhere.
234
+
235
+ The recovery now writes those four refs through Git at the same ids and
236
+ holds every object they and `MERGE_HEAD` name. It stores the stash's
237
+ entries again, oldest first, with their messages, so `git stash list`
238
+ reads the same. A link is copied as the same link. A ref the source holds
239
+ in the reftable format without its object cannot be written, and refuses
240
+ the retire with `E_WORK_PRESERVATION_FAILED`, the home kept, as any
241
+ recovery that cannot be made does. Which homes a retire recovers, the
242
+ receipt and every code are unchanged.
243
+
244
+ ## Provider updates
245
+
246
+ - **oats.okf 5.2.0:** the IMPORTANT inject block requires current instance
247
+ knowledge and compulsory reading of `okf-propose`. The skill holds the
248
+ bounded checkpoint procedure, promotion/search checks, proposal format and
249
+ memory/concurrency gates. No harvest or proposal direction remains in the
250
+ working instance's TASK brief. At most one proposal per completed task or
251
+ PR hand-over, one harvester per instance, and no spawn under memory pressure
252
+ or below 8 GB available; most checkpoints propose nothing. An unrelated
253
+ harvester can outlive its proposer. These limits are instructions, not a
254
+ scheduler or resource reservation.
255
+ - `oats okf status` exposes the duty written by the provider at spawn (`on`,
256
+ `off`, or missing-state `unknown`). An unknown answer or failure permits no
257
+ proposal. Shared inject/skill text explicitly exempts opted-out souls, and
258
+ the harvester independently refuses their recorded source material. No
259
+ kernel composition mechanism is added.
260
+
261
+ - **oats.framework 1.10.2: oats.core 2.6.1 and oats.setup 2.5.4.**
262
+ Instruction text in two skills; no hook, command, schema or provider
263
+ contract changes, and the capability floors are unchanged (oats.core
264
+ `>=0.40.0`, oats.setup `>=0.30.0`).
265
+ - `oats-operate` (oats.core) says that from OATS 0.57.0 `oats worktree
266
+ remove` refuses a tree that is the work of an attached instance whose
267
+ session is running or cannot be read (`E_CHILDREN_RUNNING`): stop that
268
+ instance or retire it, then remove again, as the entry under Changed
269
+ says ([#964](https://github.com/awebai/oats/issues/964)).
270
+ - `oats-onboarding` (oats.setup) pins `oats.okf: v5.2.0` in its knowledge
271
+ section and describes the harvest duty that oats.okf 5.2.0 gives every
272
+ working soul: the compulsory `okf-propose` skill, `oats okf status`, and
273
+ the soul's own opt-out, as the oats.okf entry says.
274
+ - A deployment gets it by pinning `oats.framework: v1.10.2` and running
275
+ `oats sync`. Instances already running keep the skills they were spawned
276
+ with; new spawns get the new ones.
277
+
278
+ ## Documentation
279
+
280
+ - [Knowledge operations](../knowledge.md#the-flow) now describes the
281
+ capability-owned flow, opt-out/status answer, narrow checkpoints and
282
+ deferred hand-back. Catalog/workspace pins, package examples, mirrors and
283
+ clean-room composition assertions move together to 5.2.0.