@awebai/oats 0.57.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 (50) hide show
  1. package/docs/configuration.md +17 -27
  2. package/docs/desktop.md +14 -0
  3. package/docs/execution-targets.md +6 -1
  4. package/docs/implementation.md +7 -1
  5. package/docs/integrations.md +3 -1
  6. package/docs/official-catalog.md +1 -1
  7. package/docs/packages.md +5 -5
  8. package/docs/release-notes/v0.57.1.md +275 -0
  9. package/docs/servers.md +18 -0
  10. package/docs/tui.md +214 -87
  11. package/docs/workspaces.md +1 -1
  12. package/lib/session-viewer.mjs +29 -4
  13. package/package-catalog.json +1 -1
  14. package/package.json +1 -1
  15. package/packages/client/cli-adapter.mjs +9 -7
  16. package/packages/client/composed-gate.mjs +34 -0
  17. package/packages/client/inspect-boundary.mjs +157 -0
  18. package/packages/client/inspect-cache.mjs +86 -0
  19. package/packages/client/keyed-catalog.mjs +132 -0
  20. package/packages/client/launch-view.mjs +46 -0
  21. package/packages/client/session-attach.mjs +7 -5
  22. package/packages/client/soul-catalog.mjs +77 -0
  23. package/packages/client/soul-colors.mjs +31 -0
  24. package/packages/client/soul-facts.mjs +85 -0
  25. package/packages/client/soul-rows.mjs +48 -0
  26. package/packages/client/spawn-apply-cli.mjs +11 -6
  27. package/packages/client/spawn-apply.mjs +212 -0
  28. package/packages/client/spawn-messages.mjs +131 -85
  29. package/packages/client/spawn-preview-contract.mjs +3 -0
  30. package/packages/client/spawn-preview-facts.mjs +119 -0
  31. package/packages/client/spawn-preview.mjs +152 -0
  32. package/packages/client/spawn-transaction.mjs +136 -0
  33. package/packages/tui/README.md +32 -11
  34. package/packages/tui/lib/actions.mjs +10 -1
  35. package/packages/tui/lib/config.mjs +9 -14
  36. package/packages/tui/lib/main.mjs +165 -57
  37. package/packages/tui/lib/model.mjs +28 -24
  38. package/packages/tui/lib/panel.mjs +955 -0
  39. package/packages/tui/lib/read.mjs +5 -14
  40. package/packages/tui/lib/store.mjs +77 -30
  41. package/packages/tui/lib/term/capture.mjs +260 -0
  42. package/packages/tui/lib/term/screen.mjs +44 -8
  43. package/packages/tui/lib/term/style.mjs +78 -6
  44. package/packages/tui/lib/term/text.mjs +24 -4
  45. package/packages/tui/lib/term/through.mjs +213 -0
  46. package/packages/tui/lib/term/tty.mjs +7 -60
  47. package/packages/tui/lib/views/frame.mjs +126 -40
  48. package/packages/tui/lib/views/help.mjs +12 -10
  49. package/skills/oats-getting-started/SKILL.md +3 -2
  50. package/packages/tui/lib/open.mjs +0 -45
@@ -87,9 +87,14 @@ Loading development channels” prompt through the **approved route**: the
87
87
  development prompt. Claude admits the plugin when a root-owned machine
88
88
  managed-settings file lists it. The route does not depend on the Claude
89
89
  version and needs no OATS mechanism beyond these settings. The operator's
90
- ordered procedure is the `oats.setup` host step “Claude channel delivery
91
- (approved route)” in `/oats-workspace-config`, which `/oats-onboarding` card 4
92
- calls; the provider's side is `/oats-aweb` §4.
90
+ ordered procedure is the `oats.setup` skill `/oats-host-delivery`, whose
91
+ Choice 1 is this route and whose Choice 2 is the host wake broker;
92
+ `/oats-onboarding` card 4 makes both choices and card 8 checks them. The provider's side is
93
+ `/oats-aweb` §4.
94
+
95
+ An unset `claudeChannelMode` is development mode, so a host that never makes
96
+ the choice runs every Claude home with the development prompt. Set the key
97
+ explicitly, to `approved` or, as a recorded fallback, `development`.
93
98
 
94
99
  **The managed-settings file** is a host change made by a human admin with
95
100
  sudo. OATS never writes it.
@@ -127,7 +132,11 @@ settings:
127
132
  ```
128
133
 
129
134
  With channel delivery, pi uses its `@awebai/pi` extension and Codex always
130
- uses the host broker.
135
+ uses the host broker. The broker (`aw wake run`, one per host user) also wakes
136
+ every joined team and every `delivery: session` home. Without it, joined teams
137
+ are poll-only. It runs as a per-user launchd or systemd service that the
138
+ operator installs, with `AW_WAKE_OATS_BIN` and a `PATH` that reaches `oats`,
139
+ `node` and `tmux`. That procedure is Choice 2 of `/oats-host-delivery`.
131
140
 
132
141
  **The plugin.** `aweb-channel` must be installed from the marketplace named
133
142
  `awebai-marketplace` (GitHub `awebai/claude-plugins`) and enabled, in the
@@ -142,29 +151,10 @@ without the operator's word.
142
151
  confirm: [the development-channel confirmation](#the-development-channel-confirmation)
143
152
  applies only to a launch with the development-channel flag.
144
153
 
145
- **Verify:**
146
-
147
- 1. `oats spawn <soul> --preview` shows `settings.oats.aweb.claudeChannelMode:
148
- approved` and `delivery: channel`.
149
- 2. The started session shows no development prompt, and its banner shows
150
- “Channels (experimental) messages from plugin:aweb-channel@awebai-marketplace
151
- inject directly in this session”, followed by “restart without --channels
152
- to stop”. At normal terminal widths the banner wraps over two rows: look
153
- for each part, not for one string.
154
- 3. The banner says none of `not on the approved channels allowlist`,
155
- `not on your org's approved channels list`, `blocked by org policy` or
156
- `plugin not installed`.
157
- 4. Receive is proven only by the `/oats-aweb` nonce exchange.
158
-
159
- **Failure banners**, their cause and remedy:
160
-
161
- | What the session shows | Cause | Remedy |
162
- |---|---|---|
163
- | `not on the approved channels allowlist` | the effective managed policy has no `allowedChannelPlugins` (no file, the file not read, or the key missing), so Anthropic's default list applied | write or fix the file |
164
- | `not on your org's approved channels list` | the effective policy has an `allowedChannelPlugins` without this plugin and marketplace pair: the names in the file are wrong, or a higher source (server-managed settings or MDM) supplies its own list | fix the entry, or have the organization admin add it |
165
- | `blocked by org policy` (then “Inbound messages will be silently dropped”) | the effective policy lacks `channelsEnabled: true`, which Team/Enterprise subscribers need, and API-key use whenever any managed policy exists | add the key, or have the organization admin set it |
166
- | `plugin:aweb-channel@awebai-marketplace · plugin not installed` | the plugin is not installed in the launch's Claude config directory | install and enable it there |
167
- | the development prompt still appears | the home started in development mode, not approved: the host setting is missing, or the home was spawned before the change | set `claudeChannelMode: approved`, then respawn the home |
154
+ **Verify** with the success list and the failure-banner table of
155
+ `/oats-host-delivery`, Choice 1: the preview's mode, the admitted banner
156
+ with no failure banner, then the `/oats-aweb` nonce exchange, which alone
157
+ proves receive.
168
158
 
169
159
  **Limits.** Channels are an Anthropic research preview. Anthropic's
170
160
  account-level feature flag gates channels on every route. The allowlist
package/docs/desktop.md CHANGED
@@ -166,6 +166,16 @@ workspace on a server: `name — server`).
166
166
  - Tabs belong to their window: a workspace's terminals and tabs stay in the
167
167
  window they were opened in, and switching that window back to the
168
168
  workspace brings them back.
169
+ - A tab's terminal ends ("session ended") when its instance's tmux window
170
+ goes, whatever your tmux `detach-on-destroy` setting: a tab never shows
171
+ another instance's terminal. Stopping an instance leaves its tab open.
172
+ - When a roster read shows an instance retired, from the Desktop, the CLI,
173
+ another agent or another machine, every tab of that instance closes, in
174
+ every split. In each split the next tab (or else the previous one) becomes
175
+ active, and the focus moves to it only if it was in a closed tab. A
176
+ workspace that isn't shown closes them the next time its roster is read.
177
+ An instance respawned under the same name is a new instance: opening it
178
+ opens a new tab.
169
179
 
170
180
  ## Capabilities and spawning
171
181
 
@@ -442,6 +452,10 @@ any other exit code. Closing the tab ends the reconnecting. Reconnecting
442
452
  never stops or restarts the agent on the server: only the local ssh viewer
443
453
  ends.
444
454
 
455
+ A remote instance's tabs close only when its server answers without it
456
+ (retired there, or gone from it), never because the server can't be reached
457
+ or its roster read is out of date.
458
+
445
459
  ## Copy from a terminal
446
460
 
447
461
  Drag over an agent's output to select it, as in any terminal. The selection
@@ -1076,7 +1076,12 @@ oats session attach --home /abs/home --detach-key 'C-\'
1076
1076
  acceptance evidence remain separate contracts.
1077
1077
  - **attach** is interactive and takes no `--json`. It opens a temporary tmux
1078
1078
  session linked to the agent's window alone.
1079
- Closing the viewer leaves the agent running.
1079
+ Closing the viewer leaves the agent running. When the agent's window ends
1080
+ (for example, the instance is stopped or retired), the viewer ends too: it
1081
+ sets tmux's `detach-on-destroy on` for its own session, so a server
1082
+ configured with `detach-on-destroy off` never moves the viewer's client to
1083
+ another session, another agent's terminal. Your own sessions keep your
1084
+ setting.
1080
1085
 
1081
1086
  On tmux 3.2 and later the viewer's tmux client asks for synchronized
1082
1087
  output (`tmux -T sync`, for that client alone): tmux wraps each redraw in
@@ -665,7 +665,13 @@ and acts on every existing session through its recorded socket
665
665
  (`test/session-attach-detach-key.test.mjs`). A mouse report is sent as the
666
666
  bytes a terminal sends (`send-keys -l`). A pane program that must show the
667
667
  keys it reads puts its terminal in raw mode first: in cooked mode a control
668
- byte is a signal or an edit, not input.
668
+ byte is a signal or an edit, not input. A signal to the command's process
669
+ group (what a pty hang-up or a C-c delivers) needs the command to be a group
670
+ of its own: the pane's script starts `trap : INT; set -m`, so the shell
671
+ survives to record the status (bash would otherwise end itself after a job
672
+ that INT ended). A `tmux` first on the command's `PATH` times the signal
673
+ against one of the command's tmux calls; it finds the group with
674
+ `ps -o pgid= -p $PPID`.
669
675
  - A test of a full-screen program (`oats tui`) uses a pane of a private
670
676
  server as its terminal (`test/tui-terminal.test.mjs`): the real CLI is typed
671
677
  at an interactive shell in the pane, keys go in with `send-keys`, the screen
@@ -100,7 +100,9 @@ operations in full.
100
100
  becomes quiet after the kernel records a completed confirmation. If Claude
101
101
  ignored the flag, readiness reports `claude-channels-unavailable`.
102
102
  `settings.oats.aweb.delivery: session` or
103
- `settings.oats.aweb.claudeChannelMode: approved` stop the prompt. `oats aweb roster` lists the team:
103
+ `settings.oats.aweb.claudeChannelMode: approved` stop the prompt. Which one a
104
+ host uses, and its host wake broker, are the operator's choices in
105
+ oats.setup's `/oats-host-delivery`. `oats aweb roster` lists the team:
104
106
  its membership certificates and workspaces, one entry per alias with its
105
107
  sources, status and kind (global identities first), and says when either
106
108
  source is incomplete. After `oats server connect`, `oats aweb connect
@@ -9,7 +9,7 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.10.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.12.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
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` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
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.2.0` or `oats-framework/v1.10.2`) 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,7 +74,7 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.10.2
77
+ oats.framework: v1.12.0
78
78
  oats.okf: v5.2.0
79
79
  oats.aweb: v1.27.3
80
80
  teams:
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.2", "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.2`
362
- resolves to tag `oats-framework/v1.10.2`. 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,275 @@
1
+ # OATS 0.57.1
2
+
3
+ 2026-10-15
4
+
5
+ ## Upgrade
6
+
7
+ - **Either order of Desktop and CLI works:** a 0.57.0 Desktop accepts a
8
+ 0.57.1 CLI, and the other way round. The 0.57.1 Desktop accepts OATS CLIs
9
+ `>=0.26.0 <0.58.0`.
10
+
11
+ - **Upgrade the hosts a Desktop reaches over `--server`, too.** A routed
12
+ attach runs its viewer on the host, so the viewer fixes (it ends with the
13
+ agent's window under `detach-on-destroy off`, and a late hang-up no longer
14
+ leaves an `oatsview-*` session behind) hold for a remote terminal only once
15
+ that host runs 0.57.1. See Fixed
16
+ ([#1237](https://github.com/awebai/oats/issues/1237),
17
+ [#1243](https://github.com/awebai/oats/issues/1243)).
18
+
19
+ - **`oats tui`: the whole-screen open is gone.** `Enter` opens an agent's
20
+ terminal in a panel beside the list; `z` gives it the whole body. The panel
21
+ needs tmux 3.2 or later. `open.detachKey` in `tui.json` keeps its name and
22
+ the keys it accepts, and now means the back key to the list; a key outside
23
+ them is refused when `tui.json` is read. See Changed
24
+ ([#855](https://github.com/awebai/oats/issues/855)).
25
+
26
+ - **pi homes: run `oats update`** to move the `@awebai/oats-pi` bridge in
27
+ your pi folders to this release (by hand: see [Upgrading](../upgrading.md));
28
+ the kernel alone doesn't change it. A freshly spawned pi home then no
29
+ longer starts by "continuing" from an empty `STATE.md`. See Fixed
30
+ ([#1251](https://github.com/awebai/oats/issues/1251)).
31
+
32
+ - **To get the new framework skills,** pin `oats.framework: v1.12.0` in your
33
+ workspace and run `oats sync`: `/oats-host-delivery` and `/oats-git-setup`
34
+ in oats.setup 2.7.0. Instances already running keep what they were spawned
35
+ with. See Provider updates.
36
+
37
+ - **The official catalog's versions in this release** are oats.framework
38
+ 1.12.0, oats.okf 5.2.0, oats.aweb 1.27.3, oats.engineering 1.10.0,
39
+ oats.cloning 1.0.1, oats.authoring 1.0.3, oats.jira 1.0.1, oats.linear 1.0.1
40
+ and oats.apps 1.0.0.
41
+
42
+ ## Changed
43
+
44
+ - **A spawn runs in a process session of its own.** The `oats spawn` child of
45
+ a confirmed spawn now runs in a process session of its own, so a hang-up or
46
+ a Ctrl-C in the terminal that started the client does not reach a spawn
47
+ while its worktree hooks run. The deadline the confirmed preview implies
48
+ still interrupts it, and the kernel rolls it back.
49
+
50
+ - **`oats tui` opens an agent's terminal in a panel beside the list**
51
+ ([#855](https://github.com/awebai/oats/issues/855)). `Enter` on an
52
+ instance that runs shows its terminal where the detail was, with the list
53
+ still on screen and the focus in the terminal: everything you type goes to
54
+ the agent but the back key (`Ctrl+\`, or `open.detachKey` in `tui.json`),
55
+ which gives the focus to the list while the terminal stays open and live.
56
+ From the list, `Enter` on its row goes back to it, `z` gives it the whole
57
+ body and `c` closes it; `Enter` on another instance opens that one
58
+ instead. A terminal whose viewer ends closes with a line that says why,
59
+ and is never opened again by itself. **The whole-screen open of the
60
+ previous version is gone**: `z` replaces it. The viewer now runs in a tmux
61
+ server private to the run (tmux 3.2 or later), ended on every way out, a
62
+ `kill -9` of `oats tui` included; a later run removes what a killed one
63
+ left. `open.detachKey` keeps its name
64
+ and the keys it accepts, and now means the back key; a key outside them is
65
+ refused when `tui.json` is read, and an older OATS on another machine is
66
+ opened like a newer one. See [the TUI page](../tui.md#open-an-agents-terminal).
67
+ - **The header's second row reads as navigation:** `Instances Souls
68
+ Capabilities`, the open view in reverse video and the views not built yet
69
+ dim. The keys `1`, `2` and `3` are in the help, not beside the names, and
70
+ the footer names them as one hint, `1-3 views`; `2` and `3` say what to
71
+ run instead. Every frame is now one
72
+ synchronized update (`CSI ?2026h` … `CSI ?2026l`).
73
+
74
+ ## Fixed
75
+
76
+ - **Desktop: a team card's warning can be copied.** On the Teams board, the
77
+ text of a team's warning or blocking problem, with its fix, can be
78
+ selected and copied, and a click on that box no longer opens the team's
79
+ page. A click anywhere else on the card still opens it, and the card is
80
+ still one Tab stop.
81
+ - **Desktop: a Make default confirmation closes with the team's page.** A
82
+ confirmation opened on a team's page no longer stays open after Back, Esc,
83
+ a tab change or the team going away, and the Teams board updates again
84
+ when your instances change.
85
+ - **Desktop: a failed read shows on an open team page.** When the teams on
86
+ this computer can't be read, the open team's page says so in its card, in
87
+ the board's words, instead of showing facts that may be out of date.
88
+
89
+ - **Desktop: a retired instance's tabs close**
90
+ ([#1237](https://github.com/awebai/oats/issues/1237)). When a roster read
91
+ shows an instance retired, whether the Desktop, the CLI, another agent or
92
+ another machine retired it, every tab of that instance closes, in every
93
+ split. The next tab becomes active, and the focus moves only if it was in
94
+ a closed tab. A remote instance's tabs close only when its server answers
95
+ without it, never because the server can't be reached. Stopping an
96
+ instance still leaves its tab open, and an instance respawned under the
97
+ same name opens a new tab.
98
+ - **Desktop: a tab no longer shows another instance's terminal**
99
+ ([#1237](https://github.com/awebai/oats/issues/1237)). With tmux's
100
+ `detach-on-destroy off` in your configuration, retiring an instance moved
101
+ its tab to another session, often another tab's agent: the tab kept its
102
+ name, and what you typed went to that agent. The tab's terminal now ends
103
+ ("session ended") when its instance's window goes. Only the Desktop's own
104
+ viewer sessions are set this way; your global option and your own
105
+ sessions are untouched.
106
+
107
+ - **`oats session attach`: the viewer ends with the agent's window, even under
108
+ `detach-on-destroy off`**
109
+ ([#1237](https://github.com/awebai/oats/issues/1237)). When an attached
110
+ instance was retired, a tmux configured with `set -g detach-on-destroy off`
111
+ moved the viewer's client to another session, so the terminal went on
112
+ showing, and typing into, another agent. The viewer session now sets
113
+ `detach-on-destroy on` for itself alone, and the viewer ends as it does
114
+ under tmux's default. Your own sessions keep your setting. A routed attach
115
+ (`--server`) runs the viewer on the host, so this holds there once the host
116
+ runs this release. Remote Desktop terminals use that viewer.
117
+
118
+ - **`oats session attach`: a late hang-up no longer leaves the viewer session
119
+ behind** ([#1243](https://github.com/awebai/oats/issues/1243)). A hang-up,
120
+ termination or interrupt can reach `oats session attach` late, for example
121
+ under a wrapping shell or a terminal profile, where it arrives once the
122
+ wrapper has died and goes to the whole process group. If it arrived just
123
+ after the viewer's client had exited, or while the viewer was still being
124
+ prepared, it could end `oats` before its cleanup, or kill the cleanup's
125
+ tmux call, and leave the `oatsview-*` session (and a keyed viewer's key
126
+ table) on the agents' tmux server. `oats` now handles these signals from
127
+ before it creates the viewer until its cleanup has finished, and runs its
128
+ tmux calls outside its own process group, so the viewer is always removed.
129
+ Exit statuses are unchanged. A routed attach (`--server`) runs the viewer on
130
+ the host, so this holds there once the host runs this release.
131
+
132
+ - **pi: a freshly spawned home no longer starts by "continuing" from an empty
133
+ `STATE.md`**
134
+ ([#1251](https://github.com/awebai/oats/issues/1251)). At session start the
135
+ `@awebai/oats-pi` bridge sends the nudge "Read ./STATE.md … then continue
136
+ from STATE.md's Next section". It held the nudge back only while `STATE.md`
137
+ still held template text that no package writes any more, so every fresh
138
+ home got it, ahead of its opening task. A startup now gets the nudge only
139
+ when pi kept an earlier session of the home (pi keeps one once it holds a
140
+ message) and
141
+ `STATE.md` exists, whatever a knowledge capability seeded into it. Sessions
142
+ of an earlier instance with the same name, at the same path, don't count.
143
+ The bridge writes nothing in the home to tell. Run `oats update` to move
144
+ the bridge in your pi folders to this release (by hand: see
145
+ [Upgrading](../upgrading.md)); the kernel alone doesn't change it.
146
+
147
+ ## Provider updates
148
+
149
+ - **oats.framework 1.11.0: oats.setup 2.6.0. Onboarding now makes a host's two
150
+ delivery choices and checks them**
151
+ ([#1224](https://github.com/awebai/oats/issues/1224)).
152
+ - **Why.** A host could finish onboarding with `oats doctor` clean and still
153
+ have two problems nobody had chosen:
154
+ - its Claude homes ran in development channel mode, because
155
+ `claudeChannelMode` was unset;
156
+ - no host wake broker ran, so every joined team was poll-only, and Codex
157
+ and `delivery: session` homes were not woken at all.
158
+ - **A new skill, `/oats-host-delivery`,** is the one place that teaches both
159
+ choices. `/oats-workspace-config` now points to it, instead of holding
160
+ the approved-route steps itself:
161
+ - **Choice 1, Claude channel delivery:** the approved route (the
162
+ managed-settings file, `claudeChannelMode: approved`, the plugin in the
163
+ launch's `CLAUDE_CONFIG_DIR`, respawning homes, the banner check) as the
164
+ default for unattended hosts. The development fallback is written
165
+ explicitly, with its costs stated. Session delivery is the third
166
+ option.
167
+ - **Choice 2, the host wake broker:** when a host needs it (a joined
168
+ team, Codex, `delivery: session`); how the operator installs `aw wake
169
+ run` as a per-user systemd or launchd service, with `AW_WAKE_OATS_BIN`
170
+ and a `PATH` that reaches `oats`, `node` and `tmux`; the restart after an aw upgrade; the check (`aw wake status
171
+ --json`, and readiness free of `wake-daemon-*` and
172
+ `joined-team-poll-only`); and the false `wake-status-stale` of oats.aweb
173
+ 1.27.2 ([oats-aweb#116](https://github.com/awebai/oats-aweb/issues/116),
174
+ fixed in 1.27.3).
175
+ - **`/oats-onboarding`:**
176
+ - card 4 requires both choices to be made and recorded: the broker is
177
+ installed once aw meets its floor, before the first spawn;
178
+ - card 8 checks each recorded choice, and the hand-back records both;
179
+ - card 4 also requires Git that works without a terminal on a macOS
180
+ host that another machine drives, linking
181
+ [Git on a macOS host](../servers.md#git-on-a-macos-host).
182
+ - **`/oats-setup-model`** names both host facts and answers “why didn't my
183
+ agent wake”. `/oats-teams` reopens Choice 2 at a host's first joined
184
+ team.
185
+ - Instruction text and one new skill: there is no hook, command, schema or
186
+ provider contract change, and the capability floors are unchanged
187
+ (oats.setup `>=0.30.0`).
188
+ - A deployment gets it by pinning `oats.framework: v1.11.0` and running
189
+ `oats sync`. Instances already running keep the skills they were spawned
190
+ with.
191
+
192
+ - **oats.framework 1.11.1, oats.setup 2.6.1: `/oats-host-delivery` teaches
193
+ `oats aweb wake install` (oats.aweb 1.28.0)**
194
+ ([#1224](https://github.com/awebai/oats/issues/1224)).
195
+ - Choice 2 now leads with the oats.aweb 1.28.0 command: `--plan`,
196
+ `install`, `status`, `uninstall`, and rerunning `install` after an aw
197
+ upgrade.
198
+ - The hand-written systemd and launchd units remain as the fallback, for
199
+ older providers or an operator's own unit.
200
+ - It names the migration from the hand-written `ai.aweb.wake` unit that
201
+ oats.setup 2.6.0 taught: that unit carries no install marker, so `install`
202
+ refuses it with `E_WAKE_UNIT_CONFLICT`. Retire it with the printed steps,
203
+ then rerun.
204
+ - On macOS, `install` runs at the desktop login. Over ssh, `launchctl
205
+ bootstrap` can fail after the plist is written (`E_WAKE_UNIT`); rerun it
206
+ at the desktop.
207
+ - The broker is installed before onboarding card 6. From oats.aweb 1.28.0,
208
+ card 6's readiness fails without it for a soul with `delivery: session` or
209
+ a join.
210
+ - Choice 1 and the checks name the new readiness warning
211
+ `claude-channel-mode-default`, and the soul-scope broker check.
212
+ - Instruction text only; the floors are unchanged.
213
+ - A deployment gets it by pinning `oats.framework: v1.11.1` and running
214
+ `oats sync`. Instances already running keep the skills they were spawned
215
+ with.
216
+
217
+ - **oats.framework 1.12.0: oats.setup 2.7.0. A guided Git and GitHub setup
218
+ for a person who isn't a developer**
219
+ ([#1233](https://github.com/awebai/oats/issues/1233)).
220
+ - **Why.** OATS reads its workspace with Git, and agents commit as the
221
+ person who runs them, but nothing taught that person to set Git up. The
222
+ kernel never prompts: it reads `git:` references over `https://` with
223
+ the credential helper and runs ssh in batch mode. A host could reach
224
+ onboarding with no GitHub credentials for Git, no known `github.com`
225
+ host key, or commits that GitHub shows as Unverified.
226
+ - **A new skill, `/oats-git-setup`,** walks through it on macOS and
227
+ Linux. Each step says what to run, what you should see, and what to do
228
+ when you see something else:
229
+ - installing `git` and `gh`, and checking that `gh` has the flags the
230
+ steps use;
231
+ - one SSH key, registered on GitHub both as an authentication key and as
232
+ a signing key, with the admin scopes removed from gh's token again
233
+ afterwards;
234
+ - `gh auth setup-git` for `https://` remotes, and the first `ssh -T
235
+ git@github.com` checked against GitHub's published fingerprint;
236
+ - the identity, with an email verified on GitHub, and SSH commit signing;
237
+ - a DCO sign-off on every commit through a global `core.hooksPath` hook
238
+ that still runs each repository's own hooks;
239
+ - a check: SSH auth, a signed and signed-off commit that GitHub's API
240
+ reports as `verified: true`, and `gh auth status`.
241
+ - **The macOS credential helper.** On macOS, a Git process run without
242
+ `HOME` skips `~/.gitconfig` and uses the system file, where Homebrew's
243
+ Git sets `credential.helper osxkeychain`. That raised repeated keychain
244
+ popups on one host. The skill leaves credentials to gh and SSH, checks
245
+ which helper a Git without `HOME` would use, and says why it matters.
246
+ - **`/oats-onboarding`:** card 2, which makes the first Git reads, starts
247
+ with `/oats-git-setup` when the person's Git and GitHub setup is missing
248
+ or unchecked. `/oats-setup-model` and
249
+ `/oats-workspace-config` name where these facts live.
250
+ - Instruction text and one new skill: there is no hook, command, schema or
251
+ provider contract change, and the capability floors are unchanged
252
+ (oats.setup `>=0.30.0`).
253
+ - A deployment gets it by pinning `oats.framework: v1.12.0` and running
254
+ `oats sync`. Instances already running keep the skills they were spawned
255
+ with.
256
+
257
+ ## Documentation
258
+
259
+ - [Configuration](../configuration.md), “Claude channel delivery: the approved
260
+ route”:
261
+ - an unset `claudeChannelMode` is development mode, so set it explicitly;
262
+ - the host wake broker is the other host delivery choice;
263
+ - the operator's procedure for both is oats.setup's `/oats-host-delivery`
264
+ ([#1224](https://github.com/awebai/oats/issues/1224)).
265
+ - [Servers](../servers.md), “Git on a macOS host”, adds four things:
266
+ - which remedy applies to an `https://` remote and which to a
267
+ `git@github.com:` one;
268
+ - that SSH commit signing has the same requirement;
269
+ - the `--insecure-storage` trade-off;
270
+ - when to set it up, and how to verify it from a session without a
271
+ terminal ([#1224](https://github.com/awebai/oats/issues/1224)).
272
+
273
+ - [Servers](../servers.md), “Git on a macOS host”, points to `/oats-git-setup`
274
+ for the person's whole Git and GitHub setup
275
+ ([#1233](https://github.com/awebai/oats/issues/1233)).
package/docs/servers.md CHANGED
@@ -146,6 +146,24 @@ login agent in the shell's startup file (for zsh, `~/.zshenv`, which
146
146
  non-interactive sessions read). OATS never reads or changes credentials
147
147
  itself; the hint is about where Git ran, not a probe of the keychain.
148
148
 
149
+ - **Which remedy applies depends on the remote.**
150
+ - An `https://` remote is read through the credential helper: gh's token.
151
+ - A `git@github.com:` remote is read through the SSH key. Its
152
+ `UseKeychain yes` works only in the desktop session.
153
+ - SSH commit signing (`gpg.format=ssh`) reaches its key the same way, so it
154
+ has the same requirement.
155
+ - **The trade-off.** `--insecure-storage` keeps gh's token in gh's own
156
+ configuration file, protected by file permissions instead of the keychain.
157
+ The machine's operator makes that choice.
158
+ - **When to set it up.** At onboarding (`/oats-onboarding` card 4), on a Mac
159
+ that another machine will drive (`oats server add`), or that runs Git from
160
+ background jobs. The person's whole Git and GitHub setup, including the
161
+ system `osxkeychain` helper a Git without `HOME` falls back to, is
162
+ oats.setup's `/oats-git-setup`.
163
+ - **Verify** from a session without a terminal: `ssh <host> git ls-remote
164
+ <workspace remote> HEAD`, or `oats server check <id>` from the driving
165
+ machine.
166
+
149
167
  ## Connections
150
168
 
151
169
  Every routed ssh call carries these options, before `--` and the host: