@awebai/oats 0.65.0 → 0.67.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 (75) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +74 -20
  3. package/docs/capabilities.md +4 -4
  4. package/docs/capability-manifest.schema.json +1 -1
  5. package/docs/desktop-cli-api.md +222 -10
  6. package/docs/desktop.md +101 -22
  7. package/docs/implementation.md +16 -6
  8. package/docs/integrations.md +1 -1
  9. package/docs/official-catalog.md +2 -2
  10. package/docs/packages.md +7 -7
  11. package/docs/release-lane.md +16 -0
  12. package/docs/release-notes/v0.66.0.md +183 -0
  13. package/docs/release-notes/v0.67.0.md +366 -0
  14. package/docs/release-notes/v0.67.1.md +64 -0
  15. package/docs/servers.md +5 -4
  16. package/docs/souls-and-instances.md +20 -3
  17. package/docs/tui.md +658 -143
  18. package/docs/upgrading.md +107 -25
  19. package/docs/workspaces.md +9 -2
  20. package/lib/capability-contract.mjs +2 -2
  21. package/lib/core.mjs +126 -54
  22. package/lib/deployments.mjs +21 -5
  23. package/lib/instance-color.mjs +58 -0
  24. package/lib/instance-inspect.mjs +107 -23
  25. package/lib/instance-lifecycle.mjs +21 -1
  26. package/lib/instance-naming.mjs +187 -0
  27. package/lib/instance-resolution.mjs +5 -1
  28. package/lib/materialize.mjs +62 -11
  29. package/lib/servers.mjs +15 -6
  30. package/lib/soul-composition.mjs +7 -3
  31. package/package-catalog.json +2 -2
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +37 -5
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/composed-gate.mjs +10 -2
  36. package/packages/client/deployment-data.mjs +5 -0
  37. package/packages/client/deployment-identity.mjs +40 -0
  38. package/packages/client/deployment-panel.mjs +3 -1
  39. package/packages/client/inspect-boundary.mjs +11 -7
  40. package/packages/client/inspect-cache.mjs +2 -2
  41. package/packages/client/instance-name.mjs +28 -0
  42. package/packages/client/instance-presentation.mjs +11 -0
  43. package/packages/client/keymap.mjs +99 -11
  44. package/packages/client/keys-file.mjs +122 -0
  45. package/packages/client/machine-contract.mjs +1 -5
  46. package/packages/client/own-codes.mjs +4 -2
  47. package/packages/client/panel-views.mjs +62 -9
  48. package/packages/client/spawn-naming.mjs +31 -0
  49. package/packages/client/spawn-preview-cli.mjs +22 -7
  50. package/packages/client/spawn-preview-contract.mjs +24 -0
  51. package/packages/client/spawn-preview-facts.mjs +8 -4
  52. package/packages/client/spawn-preview.mjs +47 -2
  53. package/packages/record/bin/setup.mjs +10 -2
  54. package/packages/record/docs/capture-service.md +45 -6
  55. package/packages/record/lib/capture-service-install.mjs +6 -95
  56. package/packages/record/lib/capture-setup-write.mjs +233 -0
  57. package/packages/tui/README.md +9 -8
  58. package/packages/tui/lib/actions.mjs +108 -64
  59. package/packages/tui/lib/client.mjs +8 -3
  60. package/packages/tui/lib/config.mjs +208 -26
  61. package/packages/tui/lib/main.mjs +91 -20
  62. package/packages/tui/lib/model.mjs +167 -61
  63. package/packages/tui/lib/read.mjs +53 -1
  64. package/packages/tui/lib/store.mjs +156 -47
  65. package/packages/tui/lib/term/keys.mjs +150 -34
  66. package/packages/tui/lib/term/kitty.mjs +223 -0
  67. package/packages/tui/lib/term/through.mjs +174 -27
  68. package/packages/tui/lib/term/tty.mjs +43 -12
  69. package/packages/tui/lib/views/frame.mjs +158 -79
  70. package/packages/tui/lib/views/help.mjs +143 -21
  71. package/packages/tui/lib/views/instances.mjs +59 -20
  72. package/packages/tui/lib/views/palette.mjs +14 -4
  73. package/packages/tui/lib/views/souls.mjs +2 -2
  74. package/packages/tui/lib/views/switcher.mjs +6 -1
  75. package/skills/oats-getting-started/SKILL.md +107 -34
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.2.1`, `5.2.1`, `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.2.1` or `oats-framework/v1.13.3`) and the payload path. An id
54
+ convention (`v5.2.1` or `oats-framework/v1.13.5`) 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.13.3
77
+ oats.framework: v1.13.5
78
78
  oats.okf: v5.2.1
79
- oats.aweb: v1.29.0
79
+ oats.aweb: v1.30.0
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -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.29.0 # a catalog version
137
+ oats package add oats.aweb v1.30.0 # 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
  ```
@@ -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.2.1", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.3", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.5", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.13.3`
362
- resolves to tag `oats-framework/v1.13.3`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.13.5`
362
+ resolves to tag `oats-framework/v1.13.5`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -357,6 +357,22 @@ node scripts/assemble-release-notes.mjs --tag v0.54.0
357
357
 
358
358
  No entry file writes this line: only the tag owner knows the release's
359
359
  version when the notes are assembled.
360
+ - **The same pull request updates "Upgrading to the latest version"**, the
361
+ section [Upgrading](upgrading.md) opens with: the version being tagged in
362
+ each place the section names it (the latest version, its notes, the
363
+ Desktop and the CLI install), and the CLIs that version's Desktop accepts,
364
+ up to its next minor (`ACCEPT_RANGE` in `packages/client/cli-locator.mjs`
365
+ once the release plan has moved it). The page
366
+ states only this band; the earlier ones stay in their notes. When the
367
+ release's Upgrade section asks for more than the page's steps, the order
368
+ of the Desktop and the CLI and an optional package pin, the pull request
369
+ also adds the release's entry at the top of "Coming from an older
370
+ version", one line that links its notes.
371
+ `test/release-packaging.test.mjs` checks that the section names the
372
+ version the manifests carry and no other, and that the page's only band
373
+ is that version's Desktop's. The oats.setup skill `oats-upgrade` reads
374
+ this page at the release's tag, so what the tag carries is what an upgrade
375
+ follows.
360
376
  - **A tag is refused while anything is under `docs/release-notes/next/`:** by
361
377
  the `build-and-test` job of `release.yml` and by `release-lane.mjs build`,
362
378
  each right after its notes-file gate and before anything is built. Each
@@ -0,0 +1,183 @@
1
+ # OATS 0.66.0
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.65 Desktop refuses a 0.66.0 CLI. The
9
+ 0.66.0 Desktop accepts OATS CLIs `>=0.26.0 <0.67.0`.
10
+
11
+ - **Two package moves:** the official catalog pins oats.framework 1.13.4 and
12
+ oats.aweb 1.30.0 (Provider updates, below). A deployment that pins them
13
+ takes them with `oats sync`, and only new spawns use them. Neither floor
14
+ changes.
15
+
16
+ - **`oats tui` moves its key file** to `~/.oats/config/tui.json` the first
17
+ time it starts (Changed, below). If you keep the file in a dotfiles
18
+ manager, point it at the new path first.
19
+
20
+ - **Coming from 0.61 or earlier:** do 0.62.0's Upgrade steps too (the capture
21
+ service's `oats setup`, once per user on each host, from that user's shell).
22
+
23
+ - **`oats server connect` needs `--dir`, inside a deployment too**
24
+ ([#1390](https://github.com/awebai/oats/issues/1390);
25
+ [Connect a machine](../servers.md#connect-a-machine)). The folder on the
26
+ host no longer defaults to `~/Agents/<this deployment's directory name>`:
27
+ only you know where the deployment goes there. A script that ran `connect`
28
+ without it now gets `E_BAD_ARGS` "--dir <path on the host> is required:
29
+ the folder on `<host>` for this deployment (absolute, or ~/… resolved
30
+ there)" before anything runs; add `--dir`. `--workspace-ref` still
31
+ defaults from the deployment, and existing registrations are unchanged.
32
+
33
+ ## Added
34
+
35
+ - **`oats tui` takes the OATS Desktop's Ctrl+Shift chords, where your
36
+ terminal lets them through** ([Chords](../tui.md#chords)): `Ctrl+Shift+K`
37
+ the palette, `Ctrl+Shift+P` a spawn, `Ctrl+Tab` and `Ctrl+Shift+Tab` the
38
+ next and previous tab, `Ctrl+Shift+W` close the terminal, `Ctrl+Shift+F`
39
+ the filter, `Ctrl+Shift+E` and `Ctrl+Shift+O` the splits. Each does what
40
+ the leader then a key does, from every focus, an agent's terminal too,
41
+ and never reaches the agent. They are extras: the leader stays the key
42
+ that always works, and the cheat sheet does not name them.
43
+ - **Only where the terminal says it can.** At start the TUI asks for the
44
+ kitty keyboard protocol (flags 1 and 4) and asks the terminal which flags
45
+ it has. Only when the terminal answers does it take the chords and list
46
+ them in the help, with the keys your terminal may take first (foot's
47
+ Ctrl+Shift+C, V, R, N, O, U, Z, X and Q). Without an answer everything
48
+ is as before. foot, Ghostty, kitty, Alacritty and WezTerm answer; VTE
49
+ terminals and Terminal.app do not. On macOS only `Ctrl+Tab` and
50
+ `Ctrl+Shift+Tab` are chords: the Desktop's hold ⌘, which a terminal
51
+ never passes on.
52
+ - **`Alt+O` and `Esc` then `o` are told apart exactly** under the
53
+ protocol, with no timing.
54
+ - **An agent gets the same bytes as before:** every key typed into its
55
+ terminal is turned back into the bytes it sends without the protocol,
56
+ and no tmux setting is changed. With a terminal that confirms flag 1
57
+ but not flag 4, Shift with Alt or Ctrl on a key that is not a letter
58
+ is typed as the US layout makes it.
59
+ - **The protocol is popped on every way out** and at a suspend, beside the
60
+ terminal modes the TUI already restores.
61
+
62
+ ## Changed
63
+
64
+ - **OATS Desktop's Add a machine dialog no longer suggests a folder**
65
+ ([#1390](https://github.com/awebai/oats/issues/1390)). **Folder on that
66
+ machine** starts empty and you have to fill it in. Its hint reads "A path on
67
+ that machine, starting with / or ~/". If you click **Add machine** with the
68
+ folder empty, the dialog says so beside the field and runs nothing. It used
69
+ to fill in `~/Agents/<deployment folder name>`. The Name default
70
+ (`<host>-<deployment folder name>`) is unchanged.
71
+
72
+ - **`oats deployments add` walks up to a regular `oats-local.yaml` only**
73
+ ([#1397](https://github.com/awebai/oats/issues/1397);
74
+ [This computer's deployments](../workspaces.md#this-computers-deployments)).
75
+ A directory or a link of that name is passed over, as a client passes it
76
+ over when it admits a deployment, instead of being listed and then shown
77
+ as `not-a-deployment`.
78
+ - **A deployment under a temporary directory is no longer listed
79
+ automatically** ([#1397](https://github.com/awebai/oats/issues/1397)). A
80
+ kernel command run in one (`os.tmpdir()`, `/tmp`, `/private/tmp` or
81
+ `/var/folders`, compared after realpath) leaves the list alone, so test
82
+ fixtures no longer fill it with rows that turn `missing`. Such a
83
+ deployment stays reachable: `oats deployments add`, `oats onboard` and a
84
+ client opening it still list it.
85
+
86
+ - **`oats tui` reads its key file from `~/.oats/config/tui.json`**
87
+ ([#1390](https://github.com/awebai/oats/issues/1390)), beside the kernel's
88
+ own files: `$OATS_HOME_DIR/config/tui.json` when `OATS_HOME_DIR` is set.
89
+ `XDG_CONFIG_HOME` is no longer read for it.
90
+ - **An existing file is moved for you** the first time the TUI starts: it
91
+ copies `~/.config/oats/tui.json` (or `$XDG_CONFIG_HOME/oats/tui.json`)
92
+ to the new path and renames the old file `tui.json.migrated`, beside
93
+ it. Nothing else changes.
94
+ - **If both files are there, the TUI refuses to start** with
95
+ `E_TUI_CONFIG`, naming both: copy what you need into
96
+ `~/.oats/config/tui.json`, then remove the old file.
97
+ - **If you keep `tui.json` in a dotfiles manager,** point it at
98
+ `~/.oats/config/tui.json`. A manager that puts the old file back makes
99
+ both files present, and the TUI refuses until you remove it.
100
+ - When the move can't be made (the old file is a link to nothing,
101
+ `tui.json.migrated` is already there, the file system has no hard links,
102
+ or a step fails), the TUI says why and stops: move the file yourself.
103
+ See [OATS TUI](../tui.md#the-move-from-configoats).
104
+
105
+ - **OATS Desktop accepts an `oats` CLI 0.66.x.** Its band is now
106
+ `>=0.26.0 <0.67.0`. 0.66 adds no new gate on the band: the Desktop's Add a
107
+ machine already passes the `--dir` that `oats server connect` now requires.
108
+
109
+ - **A new workspace gets messaging, a team and a first developer in its first
110
+ commit, with no pull requests and no API key.** The `oats-getting-started`
111
+ skill asks for an aweb username in its one round of questions, writes the
112
+ workspace with `oats.aweb`, a team `default:<username>.aweb.ai`,
113
+ `defaultTeam` and a developer soul beside the setup expert, then signs up
114
+ the account with `oats aweb setup --username` before the spawn. Later
115
+ changes follow oats.setup's push rule (the next entry). The skill also runs `gh auth setup-git` when gh is
116
+ already logged in, so the first push and `oats onboard` no longer fail with
117
+ "could not read Username". The README's Start here tells a coding agent
118
+ exactly what to download and follow.
119
+
120
+ - **The setup soul that the `oats-getting-started` skill writes leaves when
121
+ to push to `oats.setup`.** Its `AGENTS.md` states no push rule of its own.
122
+ From `oats.setup` 2.8.3 (oats.framework 1.13.4), the setup expert checks
123
+ before each push (`/oats-workspace-config`, "Change a shared file"): it
124
+ pushes straight to the default branch only where nobody else can push and
125
+ nothing guards that branch, and to a member repository only on the
126
+ person's yes; otherwise it opens a pull request. An older `oats.setup`
127
+ always opens one ([#1314](https://github.com/awebai/oats/issues/1314)).
128
+
129
+ ## Fixed
130
+
131
+ - Capture setup now shares one checked publisher for hooks, service definitions
132
+ and pending activation markers: it syncs file contents before rename, then
133
+ the containing directory, and syncs newly created parent entries in order.
134
+ Required sync failures exit nonzero; failures after publication name the
135
+ affected target and stage without claiming rollback or established durability.
136
+
137
+ ## Provider updates
138
+
139
+ - **oats.framework 1.13.4: oats.setup 2.8.3.** Text only: its floor
140
+ (`compatibility.oats`) does not change.
141
+ - **Straight pushes to a repository only the person can push to.** The
142
+ briefing's rule for shared files was "only by pull request".
143
+ `/oats-workspace-config`'s "Change a shared file" now has two routes. A
144
+ commit goes straight to a repository's default branch, the workspace's
145
+ host or a member repository alike, only when checks right before the
146
+ push show that the person alone can push to it and nothing guards the
147
+ branch:
148
+ - they are its admin and its only collaborator with push access; for an
149
+ organization's repository, an active member and its only owner;
150
+ - no deploy key can write;
151
+ - no branch protection or ruleset guards the default branch (a plan
152
+ without rulesets counts as unguarded).
153
+
154
+ For the host, the setup expert then pushes and tells them what changed.
155
+ For a member repository, it first shows them the commit and says that
156
+ the push runs that repository's push-triggered CI and deploys, and it
157
+ pushes only on their yes. Otherwise the change is a pull request, and a
158
+ refused push never takes another route. The briefing,
159
+ `/oats-setup-expert`, `/oats-package-pins`, `/oats-teams`,
160
+ `/oats-automations` and `/oats-setup-model` follow it
161
+ ([#1314](https://github.com/awebai/oats/issues/1314)).
162
+ - **`/oats-setup-model` on a capture setup that failed after
163
+ publication.** When the setup summary says that publication may have
164
+ occurred but durability was not established, inspect the named target
165
+ and stage before rerunning, and keep that evidence. A sync or close
166
+ failure after the rename does not mean that the old file was restored
167
+ ([#1340](https://github.com/awebai/oats/issues/1340)).
168
+
169
+ - **oats.aweb 1.30.0: Codex readiness from the kernel's launch record.** The
170
+ catalog and this workspace pin `oats.aweb: v1.30.0`
171
+ ([#1345](https://github.com/awebai/oats/issues/1345)).
172
+ - Readiness takes a home's runtime from the kernel's recorded
173
+ `instance.json` `launch.harness` (or top-level `harness`), not from
174
+ provider metadata. A home recorded as Codex needs the host wake broker:
175
+ a missing Codex target or primary stream reports `wake-stream-missing`.
176
+ Malformed or inconsistent kernel fields report
177
+ `receive-record-unavailable`.
178
+ - A malformed `status.updated_at` from `aw wake status` reports
179
+ `wake-status-timestamp-unknown`, naming the aw client and daemon
180
+ versions, instead of `wake-status-stale`.
181
+ - The floors are unchanged (OATS >=0.52.0, aw >=1.36.33). A deployment
182
+ gets it by pinning `oats.aweb: v1.30.0` and running `oats sync`; only
183
+ new spawns use it.
@@ -0,0 +1,366 @@
1
+ # OATS 0.67.0
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.66 Desktop refuses a 0.67.0 CLI. The
9
+ 0.67.0 Desktop accepts OATS CLIs `>=0.26.0 <0.68.0`.
10
+
11
+ - **Coming from 0.65 or earlier:** do 0.66.0's Upgrade steps too (`oats
12
+ tui`'s key file moves to `~/.oats/config/tui.json`, and `oats server
13
+ connect` needs `--dir`), and 0.62.0's when coming from 0.61 or earlier.
14
+
15
+ - **One package move:** the official catalog pins oats.framework 1.13.5
16
+ (Provider updates, below). A deployment that pins it takes it with `oats
17
+ sync`, and only new spawns use it. No floor changes.
18
+
19
+ - **The leader moves to Ctrl+X** in OATS Desktop and in `oats tui`, on every
20
+ platform (Changed, below). A Desktop rebind of the leader and an
21
+ `open.detachKey` in `tui.json` are kept. To keep Alt+O or ⌃\, bind it
22
+ again: `"open": {"detachKey": "M-o"}` (or `"C-\\"`) in `tui.json`, the
23
+ shortcuts editor in the Desktop. **A `tui.json` that gives `ctrl+x` to an
24
+ action and names no leader stops `oats tui` from starting:** its line on
25
+ stderr names the action; give that action another key, or name a leader
26
+ in `open.detachKey` ([Change the keys](../tui.md#change-the-keys-tuijson)).
27
+
28
+ - **The shortcuts move on Linux and Windows** (Changed, below): the shared
29
+ chords are Ctrl+Alt now, not Ctrl+Shift, in OATS Desktop as in `oats tui`.
30
+ A shortcut you rebound in 0.66 is kept. If your terminal passes Ctrl+Shift
31
+ apart from Ctrl (foot, Alacritty), choose the Ctrl+Shift option instead
32
+ (Added, below). The Alt+Shift arrows no longer reach an agent in its
33
+ terminal.
34
+
35
+ ## Added
36
+
37
+ - **An instance has a colour** (feature `instance-color`, awebai/oats#1421).
38
+ `oats instance color <instance> (<colour> | --clear)` sets or clears it,
39
+ from the palette `sand`, `sage`, `slate`, `mauve`, `clay`, `olive`; it is
40
+ addressed as `oats instance stop` addresses an instance, and routed with
41
+ `--server`. The colour is presentation only: anyone may change it, and it
42
+ is never an address. It is kept in the home's own record,
43
+ `.oats-color.json`, which a start or restart never rewrites and a retire
44
+ does not count as a change to the home. `oats status --json` rows,
45
+ `oats server roster --json` rows and `oats inspect --home` carry `color`
46
+ ([An instance's colour](../desktop-cli-api.md#an-instances-colour-oats-instance-color)).
47
+
48
+ - **`oats inspect --soul <soul> --composed-skills` lists every skill a spawn
49
+ of the soul gives its instance** (feature `soul-composed-skills`,
50
+ awebai/oats#1421): its own skills and each capability's, each with its
51
+ `source` (`soul` or `module:<capability>`) and each file's text, from the
52
+ same scratch composition as `--instructions`. A collision a spawn would
53
+ refuse makes the field `null` with spawn's own message. It is opt-in, takes
54
+ `--soul` only, and a routed host without the feature refuses it
55
+ ([`oats inspect`](../desktop-cli-api.md#oats-inspect---home-----soul----dir----json--operationsapi-2)).
56
+
57
+ - **`oats spawn <soul> --preview --suggest-name` names the instance from its
58
+ task** (feature `spawn-suggest-name`, awebai/oats#1421). The soul's own
59
+ harness gives a few descriptive words in one call, and the preview answers
60
+ for `--name <descriptive>-<role>`, with the same decision an apply with
61
+ `--expect-decision` matches. The call starts none of the user's MCP
62
+ servers, hooks, plugins or extensions, and no tool on either harness: the
63
+ prompt goes on stdin, from an empty temporary directory, in its own process
64
+ group, within the preview's 20 s preflight budget, after its harness checks.
65
+ - **Supported harnesses: claude (model `haiku`) and pi (the instance's
66
+ model)**, proven on Linux with claude 2.1.288 and pi 1.3.0
67
+ (`scripts/naming-isolation-proof.mjs`).
68
+ - **Three stated exceptions:** Claude Code's own built-in plugins
69
+ (`cc-plugin-*@builtin`) load as they always do, `--bare` included; hooks
70
+ in the host's managed policy still apply; and pi runs its own credential
71
+ commands (`!command` keys and headers in models.json), as every pi launch
72
+ does. A claude login through `apiKeyHelper` is not read, so such a user
73
+ gets `harness-failed` and a numbered name.
74
+ - **codex is not supported yet:** a codex soul's preview is numbered, with
75
+ `naming.reason: "unsupported-harness"`.
76
+ - **A failure is never an error.** The preview numbers the instance as
77
+ before and says why in `naming.reason`: `no-task`, `unsupported-harness`,
78
+ `timeout`, `harness-failed` or `invalid-reply`.
79
+ - Routed with `--server`, the host must advertise the feature
80
+ ([The suggested name](../desktop-cli-api.md#the-suggested-name-feature-spawn-suggest-name)).
81
+
82
+ - **One chord for each everyday action, the same in `oats tui` and OATS
83
+ Desktop, from every focus, an agent's terminal too, with no leader first**
84
+ ([Chords](../tui.md#chords);
85
+ [desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
86
+ On Linux and Windows:
87
+ - `Ctrl+Alt+O` opens the switcher.
88
+ - `Alt+Shift+Up` and `Alt+Shift+Down` open the terminal of the previous
89
+ or next instance.
90
+ - `Ctrl+Alt+1` to `Ctrl+Alt+8` show the first to eighth tab, and
91
+ `Ctrl+Alt+9` the last one.
92
+ - `Ctrl+Alt+Z` zooms the shown terminal.
93
+ - `Ctrl+Alt+A` goes to the other split group.
94
+
95
+ The Desktop's macOS chords are `⌘⌥O`, `⌘⌥↑`, `⌘⌥↓`, `⌘⌥1` to `⌘⌥9`, `⌘⌥Z`
96
+ and `⌘⌥A`. Help, the views, and stop, restart, start and retire stay on
97
+ the leader, which still works everywhere.
98
+ - **In `oats tui` the Ctrl+Alt chords need the kitty keyboard protocol,**
99
+ as the 0.66 chords did. The Alt+Shift arrows work in every terminal on
100
+ Linux and Windows, GNOME Terminal included. On macOS `oats tui` has no
101
+ chords: the leader does it all there.
102
+ - **While the terminal confirms the protocol, the help and the cheat sheet
103
+ lead with the chords,** each with its leader key beside it. The leader
104
+ keeps its own section.
105
+ - **A character typed with AltGr stays a character.** On Windows `AltGr`
106
+ is `Ctrl+Alt`: where it types a character (Spanish `€`, `@` and `#`,
107
+ Polish `ą`, `ę`, `ó` and `ż`), that key types it in both clients, and
108
+ the leader does what the chord would.
109
+ - **Windows Terminal takes `Ctrl+Alt+1` to `Ctrl+Alt+9`** for its own tabs,
110
+ and the Alt+Shift arrows while its panes are split.
111
+ [The matrix](../tui.md#which-terminals-let-the-chords-through) lists
112
+ what each terminal takes.
113
+
114
+ - **A Ctrl+Shift option for the shared chords, in `oats tui` and OATS
115
+ Desktop at once,** on Linux and Windows
116
+ ([Switch to Ctrl+Shift](../tui.md#switch-to-ctrlshift);
117
+ [desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
118
+ It is for a terminal that lets Ctrl+Shift letters through to `oats tui`:
119
+ foot and Alacritty
120
+ ([Which family for my terminal](../tui.md#which-family-for-my-terminal)).
121
+ Ctrl+Alt stays the default.
122
+ - **Seven chords move:** `Ctrl+Shift+K` the palette, `Ctrl+Shift+P` a
123
+ spawn (the Desktop's Quick Open), `Ctrl+Shift+S` the switcher,
124
+ `Ctrl+Shift+M` zoom, `Ctrl+Shift+W` close the tab, `Ctrl+Shift+E` split
125
+ right and `Ctrl+Shift+D` split down.
126
+ - **The others keep their keys:** `Ctrl+Alt+A` the other group,
127
+ `Ctrl+Alt+F` the filter, the Alt+Shift arrows, `Ctrl+Alt+1` to
128
+ `Ctrl+Alt+9`, and in the Desktop `Ctrl+Alt+R`, an instance's name and
129
+ colour.
130
+ - **To switch,** choose **Ctrl+Shift (foot, Alacritty)** under
131
+ **Shortcut family, shared with oats tui** on the Desktop's Shortcuts page, or write
132
+ `{ "chords": "ctrl+shift" }` to `~/.oats/config/keys.json`
133
+ (`$OATS_HOME_DIR/config/keys.json` when that is set). The Desktop
134
+ switches at once; `oats tui` reads the file at its next start. A
135
+ missing or broken file means Ctrl+Alt, and the help says why.
136
+ - **The help names the family in force:** `?` in `oats tui`, the
137
+ Shortcuts page in the Desktop.
138
+ - **Your own keys still win, row by row:** `tui.json`'s `keys`, and the
139
+ Desktop's shortcuts editor, which shows a clash with a key the option
140
+ takes.
141
+ - **In `oats tui` it needs the kitty keyboard protocol;** the leader
142
+ works without it. With the option on, the seven are taken from an
143
+ agent's terminal too: pi's `Ctrl+Shift+P` (previous model) spawns
144
+ instead.
145
+ - macOS has no option.
146
+
147
+ - **Jump to the next or previous group in the palette,** in `oats tui` and
148
+ OATS Desktop ([The palette](../tui.md#the-palette);
149
+ [desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
150
+ While the palette is open, `Alt+Shift+Down` moves the selection to the
151
+ first row of the next group, and `Alt+Shift+Up` to the previous one's;
152
+ both wrap. On macOS the Desktop's keys are `⌘N` and `⌥⌘N` (`⌘⇧N` stays
153
+ File → New Window).
154
+ - **The keys are the palette's while it is open.** There `⌘N` doesn't
155
+ choose a soul, and the Alt+Shift arrows don't open the next or previous
156
+ instance. With the palette closed, they do what they did before.
157
+ - **`oats tui`'s palette now groups its instances** as the sidebar and the
158
+ Desktop's palette do: by relation, with the group last used first. A dim
159
+ label names each group, and the selection skips it. The souls,
160
+ capabilities, views, acts and commands after them are a group each.
161
+ - Both palettes name the keys: the Desktop's in a line under the list,
162
+ `oats tui`'s in its cheat sheet. On macOS `oats tui` has no group key:
163
+ a terminal never passes ⌘.
164
+
165
+ - **Desktop: the soul page lists every skill an instance gets.** With OATS
166
+ 0.67.0 or later, **Composed for an instance › Skills** lists the soul's own
167
+ skills and the ones its capabilities add, each saying where it comes from
168
+ (**From this soul** or **From** the capability), and the "newer OATS" note
169
+ goes. A capability's skill file opens under its place in the instance home,
170
+ with **Open capability** above it. For a soul on a server, the server's OATS
171
+ must list them too. ([Desktop](../desktop.md))
172
+
173
+ - **Desktop: an instance's colour.** Each instance's dot (the sidebar, its
174
+ terminal tab, the command palette, the overview) shows the colour set for
175
+ it: filled while running, a ring while stopped. **Instance: name and
176
+ colour…** in the command palette, or Ctrl+Alt+R (⌥⌘R on macOS), opens a
177
+ small dialog for the focused instance: its name, and **None** plus the six
178
+ palette colours, applied at once through `oats instance color`. Needs OATS
179
+ 0.67.0 or later here, and on a server for its instances. The TUI leaves
180
+ Ctrl+Alt+R to the agent. ([Desktop](../desktop.md))
181
+
182
+ - **Desktop: an instance named from its task.** With an OATS that suggests
183
+ names (`spawn-suggest-name`), the spawn dialog asks for a name once the
184
+ Opening instruction holds three words and you pause typing. The soul's
185
+ harness replies with a short name for the work, and the role is added as
186
+ its suffix. It shows as the empty Name field's placeholder, "will be named
187
+ release-notes-manager", and in **What will be created**, and Spawn uses
188
+ it. Typing a name replaces it and stops suggestions for that dialog.
189
+ Spawning with Name empty and no suggestion yet shows **Naming…** and asks
190
+ once. When the instance can't be named from its task, it is numbered, and
191
+ a notification says why ("Named oats-desktop-expert-3: naming took longer
192
+ than 20 seconds."). Nothing is asked before you type, nor on a timer.
193
+ Spawns on a server keep their purpose. ([Desktop](../desktop.md))
194
+
195
+ - **The TUI draws an instance's mark in its colour**, its shape still saying
196
+ its state ([tui.md](../tui.md#what-it-shows)).
197
+
198
+ ## Changed
199
+
200
+ - **The leader is Ctrl+X in both clients and on every platform**
201
+ (awebai/oats#1433), as Emacs' prefix key: it was Alt+O on Linux and
202
+ Windows and ⌃\ on macOS. The keys after it do not change. Without the
203
+ kitty keyboard protocol Ctrl+X is one byte, 0x18, in every terminal, so it
204
+ needs no protocol and no timing; under the protocol `oats tui` reads it
205
+ too, and Ctrl+Shift+X and Ctrl+Alt+X are not the leader
206
+ ([The leader](../tui.md#the-leader)).
207
+ - **Ctrl+X twice sends Ctrl+X to the program,** as the leader twice
208
+ always has. The shell's Ctrl+X Ctrl+E is now Ctrl+X twice, then Ctrl+E,
209
+ and nano exits with Ctrl+X twice.
210
+ - **In the Desktop, Cut keeps Ctrl+X** in a text field (an input, a text
211
+ area, an editable region) that is not a terminal, on Linux and Windows.
212
+ On macOS Cut is ⌘X, so the leader works there too
213
+ ([desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md#the-leader)).
214
+ - **Alt+O and ⌃\ go back to the programs:** on Linux and Windows an agent
215
+ gets Alt+O as Esc then `o` (on macOS Option+O types its character, `ø`
216
+ on a US layout, unless the terminal sends Option as Meta), and ⌃\ as it
217
+ is typed, unless you bind either as the leader again.
218
+
219
+ - **The shared chords move from Ctrl+Shift to Ctrl+Alt on Linux and
220
+ Windows,** in both clients. kitty, Ghostty, WezTerm, Konsole and Windows
221
+ Terminal take most Ctrl+Shift chords for themselves, so in `oats tui`
222
+ most of 0.66's chords never arrived. Old → new:
223
+
224
+ | Action | Was | Now |
225
+ |---|---|---|
226
+ | the palette | `Ctrl+Shift+K` | `Ctrl+Alt+K` |
227
+ | Quick Open in the Desktop, a spawn in `oats tui` | `Ctrl+Shift+P` | `Ctrl+Alt+P` |
228
+ | close the tab | `Ctrl+Shift+W` | `Ctrl+Alt+W` |
229
+ | the filter | `Ctrl+Shift+F` | `Ctrl+Alt+F` |
230
+ | split right | `Ctrl+Shift+E` | `Ctrl+Alt+E` |
231
+ | split down | `Ctrl+Shift+O` | `Ctrl+Alt+Shift+E` |
232
+ | next and previous tab in `oats tui` | `Ctrl+Tab`, `Ctrl+Shift+Tab` | `Alt+Shift+Right`, `Alt+Shift+Left` |
233
+ | the Desktop's second next and previous tab chords | `Ctrl+PgDn`, `Ctrl+PgUp` (outside a terminal) | `Alt+Shift+Right`, `Alt+Shift+Left` (everywhere) |
234
+ | the Desktop's go to tab 1–9 | `Alt+1` to `Alt+9` (outside a terminal) | `Ctrl+Alt+1` to `Ctrl+Alt+9` (everywhere) |
235
+
236
+ - **The Alt+Shift arrows no longer reach the agent in its terminal:** in
237
+ both clients they are the chords, there as everywhere else.
238
+ - The Desktop keeps `Ctrl+Tab` and `Ctrl+Shift+Tab`, and its other
239
+ Ctrl+Shift chords (sidebar, instance panel, spawn, theme picker, copy).
240
+ - On macOS the Desktop gains `⌘⌥→` and `⌘⌥←` for the next and previous
241
+ tab, beside `⌃Tab`.
242
+ - A binding you set yourself in the Desktop's shortcuts editor is kept,
243
+ a macOS ⌘⌥ one that 0.66 saved by the character ⌥ typed (`⌥⌘Ø`) too.
244
+ When it is a chord a default now takes, the editor shows the clash.
245
+
246
+ - **In OATS Desktop, a key you bound yourself now wins over a default on
247
+ every key two actions share,** not only on the seven keys of the
248
+ Ctrl+Shift option
249
+ ([desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md)).
250
+ Before, a default of a narrower context (the tabs, the sidebar, a stage)
251
+ could win over a global key of yours. The shortcuts editor lists every
252
+ such clash, and now says which of the two runs: "Ctrl+Shift+K runs
253
+ “Sidebar: show or hide” (yours) where both apply; “Command palette” has
254
+ it by default."
255
+
256
+ - **`.oats-color` is a kernel-owned home name**: a capability's
257
+ `retirement.disposable.home` cannot declare it
258
+ ([capabilities.md](../capabilities.md)).
259
+
260
+ - **Desktop: the soul page's Instructions has two sections.** **Defined in
261
+ this soul** holds the soul's own `AGENTS.md` and its skills. **Composed for
262
+ an instance** holds the composed `AGENTS.md` and the skills an instance
263
+ gets, each saying where it comes from (**From this soul**). Until OATS lists
264
+ the skills that capabilities add, a note says a newer OATS lists them. The
265
+ boundary is a named group for assistive technology too, and the tree is
266
+ still one tab stop. ([Desktop](../desktop.md))
267
+
268
+ - **Desktop: the spawn dialog's name is optional and its last field.**
269
+ **Name · optional** now comes last, before **Developer settings**. The soul-name
270
+ prefix and its **Prefix with the soul name** switch are gone. Left empty,
271
+ the kernel numbers the instance. The Desktop's spawn dialog adds the role
272
+ to a typed name (the last word of the soul's name) and uses the name in
273
+ lowercase: `desktop-improvements` for `oats-desktop-expert` spawns as
274
+ `desktop-improvements-expert`, and a name that already ends in the role
275
+ gets no second one. On a CLI without
276
+ `spawn-name`, and for a spawn on a server, a typed name is still a purpose
277
+ named `<soul>-<purpose>`. The dialog opens on the Opening instruction;
278
+ Ctrl+1 / ⌘1 still goes to Name. ([Desktop](../desktop.md),
279
+ [souls and instances](../souls-and-instances.md))
280
+
281
+ - **Desktop: the spawn dialog starts with the Opening instruction.** It is the
282
+ form's first field, and the dialog opens with the cursor in it, after a
283
+ restored instruction's text. In a narrow window, **What will be created** now comes after the form's last
284
+ field instead of above the form. ([Desktop](../desktop.md))
285
+
286
+ - **Desktop: the sidebar's footer no longer has a "commands" button.** The
287
+ leader's chord works as before. The keyboard shortcuts editor lists the
288
+ keys that follow it: open it from the footer's shortcuts button, with
289
+ Ctrl+, / ⌘, or from the palette.
290
+
291
+ - **Desktop: "Needs input" shows on an instance's second line.** The name
292
+ line keeps the whole name. The mark, or "N below" on a collapsed parent,
293
+ replaces the repository, pull request and branch, which stay in the hover
294
+ card. A home that is being retired or set up keeps its state on that line.
295
+
296
+ - **Desktop: the sidebar's dotted sibling links sit a little further from
297
+ the lines to children.**
298
+
299
+ - **`oats tui`'s switcher lists one row per workspace, whichever machines
300
+ it is on.** A deployment on this computer's list that the run has not
301
+ opened is read for its workspace (`oats status --dir <path> --json`, one at
302
+ a time, 30 seconds each and 60 in all, at the start and when the switcher
303
+ opens or is refreshed). It then joins its workspace's row instead of
304
+ standing apart under `On this machine, not opened`. Under each workspace a
305
+ dim line per deployment names its machine and, when it is not live, its
306
+ state (`not opened`, `not observed`, `not reached`, ...). `Enter` on a
307
+ workspace opens its deployments of this machine too, so the view holds
308
+ them and the other machines' at once. A read that fails or times out
309
+ leaves the deployment as its own row, saying why. The cheat sheet of the
310
+ list of instances names `w workspaces`.
311
+ ([The switcher](../tui.md#the-switcher))
312
+
313
+ - **`oats tui`'s terminal panel has a tab bar like a terminal's.** Its top
314
+ row is always the tab bar, with one tab or many. Each tab is the agent's
315
+ name, with `· <machine>` for another machine's agent, and tabs are divided
316
+ by `│` (`|` in ASCII). The shown tab is bracketed, `[name]`, and bold, in
317
+ reverse video while the terminal has the focus. The other tabs are dim.
318
+ ([Tabs](../tui.md#tabs))
319
+
320
+ - **`oats tui` marks a row that needs input with a tag in words.** Where it
321
+ drew a bare `!` at the right of the row, it now draws the Desktop's words
322
+ in reverse video in the waiting colour: `Needs input`, and on a folded row
323
+ with waiting instances under it, `3 below` (`99+ below` past 99). On the
324
+ selected row the tag is the waiting colour not reversed, so it stands
325
+ apart from the selection's bar, and under `NO_COLOR` the reverse video
326
+ alone carries it. On a row too narrow for the whole name beside the
327
+ words, the tag shrinks to `!` or the count alone, still reversed, and the
328
+ name keeps every cell it had. ([What it shows](../tui.md#what-it-shows))
329
+
330
+ - **The `oats-getting-started` skill covers two Linux snags from a rehearsal.**
331
+ With NodeSource's Node under `/usr`, it sets a per-user npm prefix and now
332
+ also puts `~/.local/bin` on PATH for its own later commands and asks the
333
+ person to add it to their shell's startup file. Without FUSE (Ubuntu 22.04
334
+ and later), it names `libfuse2` (`libfuse2t64` on Ubuntu 24.04) as the
335
+ install, beside the `--appimage-extract-and-run` fallback.
336
+
337
+ ## Fixed
338
+
339
+ - **`oats spawn --preview` names each capability skill as the spawn copies
340
+ it.** A manifest whose `skills` entry is a directory of skills (the
341
+ documented `"skills": ["skills"]`) showed as one skill named `skills`, and
342
+ a manifest with no `skills` showed none of the `skills/` directories the
343
+ spawn copies. The preview now lists each of them, as `--composed-skills`
344
+ does ([The preview](../desktop-cli-api.md#the-preview)).
345
+
346
+ ## Provider updates
347
+
348
+ - **oats.framework 1.13.5: oats.core 2.6.6, oats.support 1.0.1.** Text
349
+ only: neither floor (`compatibility.oats`) changes.
350
+ - **Instances are named for their work, with the soul's role last.**
351
+ `/oats-operate` and `/oats-souls` (oats.core) teach
352
+ `--name <descriptive>-<role>`, the role being the last word of the soul's
353
+ name: `--name desktop-improvements-expert` for an `oats-desktop-expert`,
354
+ not `oats-desktop-expert-desktop-improvements`. `--purpose` still derives
355
+ `<soul>-<purpose>`, for automations and scripts that know only the soul.
356
+ [Souls and instances](../souls-and-instances.md) states the convention
357
+ ([#1421](https://github.com/awebai/oats/issues/1421)).
358
+ - **Agents set needs-input whenever they need anything from a human.** The
359
+ oats.core inject and `/oats-operate` make `oats instance attention`
360
+ mandatory, under an IMPORTANT lead, for any question, decision,
361
+ approval, credential or other input an instance waits on, not only when
362
+ it cannot go on without the answer, so the wait shows on `oats status`
363
+ and in the Desktop. It stays out of FYIs and progress reports.
364
+ oats.support's hand-off skill says the same, and `/oats-operate` says
365
+ which questions the Claude Code emitter already reports
366
+ ([oats.core: needs input](../capabilities.md#oatscore-needs-input)).