@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.
- package/bin/oats.mjs +18 -10
- package/docs/configuration.md +17 -27
- package/docs/desktop-cli-api.md +59 -3
- package/docs/desktop.md +25 -4
- package/docs/execution-targets.md +6 -1
- package/docs/implementation.md +106 -5
- package/docs/integrations.md +8 -4
- package/docs/knowledge.md +93 -38
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/release-notes/v0.57.1.md +275 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +18 -0
- package/docs/souls-and-instances.md +126 -15
- package/docs/tui.md +333 -95
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +439 -126
- package/lib/instance-lifecycle.mjs +45 -9
- package/lib/session-viewer.mjs +29 -4
- package/lib/worktree.mjs +23 -2
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -7
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +34 -0
- package/packages/client/inspect-boundary.mjs +157 -0
- package/packages/client/inspect-cache.mjs +86 -0
- package/packages/client/instance-lifecycle.mjs +10 -3
- package/packages/client/keyed-catalog.mjs +132 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/launch-view.mjs +46 -0
- package/packages/client/session-attach.mjs +7 -5
- package/packages/client/soul-catalog.mjs +77 -0
- package/packages/client/soul-colors.mjs +31 -0
- package/packages/client/soul-facts.mjs +85 -0
- package/packages/client/soul-rows.mjs +48 -0
- package/packages/client/spawn-apply-cli.mjs +11 -6
- package/packages/client/spawn-apply.mjs +212 -0
- package/packages/client/spawn-messages.mjs +131 -85
- package/packages/client/spawn-preview-contract.mjs +3 -0
- package/packages/client/spawn-preview-facts.mjs +119 -0
- package/packages/client/spawn-preview.mjs +152 -0
- package/packages/client/spawn-transaction.mjs +136 -0
- package/packages/tui/README.md +43 -13
- package/packages/tui/lib/actions.mjs +18 -2
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/config.mjs +9 -14
- package/packages/tui/lib/main.mjs +241 -55
- package/packages/tui/lib/model.mjs +230 -29
- package/packages/tui/lib/panel.mjs +955 -0
- package/packages/tui/lib/read.mjs +134 -24
- package/packages/tui/lib/store.mjs +184 -31
- package/packages/tui/lib/term/capture.mjs +260 -0
- package/packages/tui/lib/term/screen.mjs +44 -8
- package/packages/tui/lib/term/style.mjs +78 -6
- package/packages/tui/lib/term/text.mjs +24 -4
- package/packages/tui/lib/term/through.mjs +213 -0
- package/packages/tui/lib/term/tty.mjs +7 -60
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +153 -37
- package/packages/tui/lib/views/help.mjs +22 -14
- package/skills/oats-getting-started/SKILL.md +4 -3
- package/packages/tui/lib/open.mjs +0 -45
|
@@ -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/schedules.md
CHANGED
|
@@ -841,9 +841,14 @@ fails, the spawn result still carries the instance receipt, plus
|
|
|
841
841
|
|
|
842
842
|
## Knowledge harvest and review
|
|
843
843
|
|
|
844
|
-
**oats.okf 5.
|
|
845
|
-
|
|
846
|
-
|
|
844
|
+
**oats.okf 5.x does not schedule harvest jobs.** In 5.2 the capability's
|
|
845
|
+
IMPORTANT inject and compulsory `okf-propose` skill give the duty, not TASK.md.
|
|
846
|
+
A working instance keeps its notes current, checks `oats okf status`, and at
|
|
847
|
+
a finished task or PR hand-over proposes only durable, non-duplicate claims.
|
|
848
|
+
At most one proposal per completed unit of work, one harvester at a time,
|
|
849
|
+
and no spawn under memory pressure or below 8 GB available; otherwise defer
|
|
850
|
+
and hand back the pending claims. Most checkpoints propose nothing. When the
|
|
851
|
+
skill's gates pass, the instance directly spawns the package harvester:
|
|
847
852
|
|
|
848
853
|
```sh
|
|
849
854
|
oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
|
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:
|
|
@@ -402,7 +402,9 @@ sugar for `--relative-to <instance> --relation child`):
|
|
|
402
402
|
`oats status --json` (`parentInstance` + `siblingInstance` edges).
|
|
403
403
|
- **unrelated** (default): no link, operator-origin, top-level.
|
|
404
404
|
|
|
405
|
-
Attached-mode spawns are ALWAYS children of the owner of the shared work tree
|
|
405
|
+
Attached-mode spawns are ALWAYS children of the owner of the shared work tree
|
|
406
|
+
(the instance in whose home the tree is, as its `work/` or as one of its
|
|
407
|
+
extra trees: see [`attached`](#attached--another-instances-tree)),
|
|
406
408
|
because an attached agent serves that owner; relation flags other than a
|
|
407
409
|
redundant child-of-owner are rejected. Any other spawn, including one from a
|
|
408
410
|
shell that inherited an agent's environment variables, is operator-origin and
|
|
@@ -554,8 +556,16 @@ parses it, so it copies the files Git reads:
|
|
|
554
556
|
- what the copy takes from the Git directories as files, each with its bytes
|
|
555
557
|
and its permission bits: the state of an operation in progress (a merge, a
|
|
556
558
|
rebase, a cherry-pick, a revert, a bisect), `info/attributes` and the
|
|
557
|
-
stash's log
|
|
558
|
-
|
|
559
|
+
stash's log. A link at one of the operation's entries is copied as the same
|
|
560
|
+
link, also one that leads nowhere;
|
|
561
|
+
- the refs an operation leaves that are not files where the refs are stored
|
|
562
|
+
in the reftable format: `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`
|
|
563
|
+
and `AUTO_MERGE`, each written into the copy through Git at the same object
|
|
564
|
+
id. The copy itself always stores its refs as files, whatever format the
|
|
565
|
+
operator's Git configuration or environment gives a new repository;
|
|
566
|
+
- its tags and its stash. Where the stash's log is not a file (the reftable
|
|
567
|
+
format), its entries are read through Git and stored again in the copy,
|
|
568
|
+
oldest first, each with its message, so `git stash list` reads the same;
|
|
559
569
|
- its exclude rules (`core.excludesFile` with the file the copy reads for it,
|
|
560
570
|
and `info/exclude`) and the settings that change what `git status` reports
|
|
561
571
|
(`core.fileMode`, `core.ignoreCase`, `core.precomposeUnicode`,
|
|
@@ -708,7 +718,11 @@ Git in the recovery. Set by hand in the recovery only what you trust.
|
|
|
708
718
|
**Every object the copy's Git metadata names is in it.** For the worktree's
|
|
709
719
|
copy and for each nested repository's alike, the copier collects what the
|
|
710
720
|
Git metadata it carries names: every commit the stash's log names (the new
|
|
711
|
-
id of each entry, as `git log -g refs/stash` shows them),
|
|
721
|
+
id of each entry, as `git log -g refs/stash` shows them), the commit each of
|
|
722
|
+
`CHERRY_PICK_HEAD`, `REVERT_HEAD` and `REBASE_HEAD` names, every commit
|
|
723
|
+
`MERGE_HEAD` names (one per line), and the tree `AUTO_MERGE` names with the
|
|
724
|
+
trees and blobs under it that the copy lacks (a conflict's files are in no
|
|
725
|
+
commit), whether the copy took the ref as a file or wrote it, for a nested
|
|
712
726
|
repository the commit of each of its local branches (its own `refs/heads`,
|
|
713
727
|
including a branch its configuration hides from a clone) and every commit
|
|
714
728
|
its `HEAD` and branch reflogs name, and every blob
|
|
@@ -719,8 +733,12 @@ the missing blobs by content (a staged blob or a resolved conflict's side
|
|
|
719
733
|
can be in no commit), then checks the whole set again. An object the
|
|
720
734
|
source cannot supply (a partial clone that lacks it: the retire never
|
|
721
735
|
fetches from a promisor remote) refuses the copy with
|
|
722
|
-
`E_WORK_PRESERVATION_FAILED`, naming it.
|
|
723
|
-
|
|
736
|
+
`E_WORK_PRESERVATION_FAILED`, naming it. An operation's ref that names an
|
|
737
|
+
object the source itself lacks is copied as it is and names nothing in the
|
|
738
|
+
copy either; where that ref must be written (the reftable format), Git
|
|
739
|
+
refuses to write it, and so the copy is refused. So `git stash show
|
|
740
|
+
stash@{2}`, `git checkout -m <path>` and `git cherry-pick --continue` work in
|
|
741
|
+
the copy as in the source. What the copier
|
|
724
742
|
cannot carry at all (an entry that is not a file, a directory or a symbolic
|
|
725
743
|
link, or a nested repository whose path is not valid UTF-8) refuses the copy,
|
|
726
744
|
here as anywhere.
|
|
@@ -1220,10 +1238,14 @@ retry. A relink that fails is a warning in the summary and the receipt's
|
|
|
1220
1238
|
`warnings`, with the command to repoint the link by hand; the retire is not
|
|
1221
1239
|
undone. A child that is not attached, whose link leads elsewhere, or that this
|
|
1222
1240
|
retire did not stop is not touched. With `--discard-worktree` the worktree is
|
|
1223
|
-
removed and an attached child's link
|
|
1224
|
-
|
|
1241
|
+
removed and an attached child's link then points at a path that is gone: the
|
|
1242
|
+
summary and the receipt's `warnings` name each such child, the tree and the
|
|
1243
|
+
link. The retire plan names the attached children in one note that covers
|
|
1244
|
+
both cases. Only the link changes:
|
|
1225
1245
|
the child's `instance.json` is not rewritten, and its AGENTS.md and TASK.md
|
|
1226
|
-
still name the old path.
|
|
1246
|
+
still name the old path. A child attached to one of the home's extra trees
|
|
1247
|
+
is handled the same way, tree by tree
|
|
1248
|
+
([extra trees at retire](#extra-trees-at-retire)).
|
|
1227
1249
|
|
|
1228
1250
|
#### What `work/` is at retire
|
|
1229
1251
|
|
|
@@ -1370,6 +1392,38 @@ leaves `work/` untouched. For each tree:
|
|
|
1370
1392
|
handled, and the message says what was done. `--force` does not bypass it:
|
|
1371
1393
|
it forces past hook cleanup, not past local work.
|
|
1372
1394
|
|
|
1395
|
+
An instance can be attached to an extra tree as it can to `work/`
|
|
1396
|
+
([`attached`](#attached--another-instances-tree)). The retire finds the
|
|
1397
|
+
attached children of every tree before it moves or removes any of them, among
|
|
1398
|
+
the recorded children it stopped and by the test it uses for `work/`:
|
|
1399
|
+
|
|
1400
|
+
- **Where the tree is re-homed**, each one's `work` link is repointed to the
|
|
1401
|
+
tree's new path, under the conditions `work/` has (the tree is seen at its
|
|
1402
|
+
new path, nothing is left at the old one, and the child's link is still the
|
|
1403
|
+
one that was found) and with the same warnings when it cannot be done. It
|
|
1404
|
+
is done right after that tree's move, not at the end of the retire: a later
|
|
1405
|
+
step can still refuse and keep the home, and the tree has left it either
|
|
1406
|
+
way.
|
|
1407
|
+
- **Where a clean tree is removed**, it is removed as any other, and the
|
|
1408
|
+
child's link then points at a path that is gone. The receipt's `warnings`
|
|
1409
|
+
and the summary name each such child, the tree and the link.
|
|
1410
|
+
|
|
1411
|
+
The plan's note for a tree names its attached children and says which of the
|
|
1412
|
+
two the retire would do. A retire that refuses after it has handled trees
|
|
1413
|
+
says, with the trees it handled, each warning it has about their attached
|
|
1414
|
+
children.
|
|
1415
|
+
|
|
1416
|
+
All of this is about the recorded children, for `work/` too. An attached
|
|
1417
|
+
instance that the plan lists under `ambiguous` (it records this instance as
|
|
1418
|
+
its parent under a name that is not unique) is not asked to stop, so the
|
|
1419
|
+
retire does not repoint its link, which then points at the path the tree
|
|
1420
|
+
has left. The retire says so. The plan's note for an extra tree names such
|
|
1421
|
+
instances in a clause of its own, and `work/` has a note of its own for
|
|
1422
|
+
them. The receipt's `warnings` name each one for every tree the retire moved
|
|
1423
|
+
or removed, with the command to repoint its link by hand where the tree was
|
|
1424
|
+
re-homed. The receipt of a `--self` retirement does not carry those
|
|
1425
|
+
warnings; its plan's notes are the same.
|
|
1426
|
+
|
|
1373
1427
|
`--discard-worktree` applies to `work/` only: a tree that is not clean is
|
|
1374
1428
|
always re-homed. The retire writes one workspace event per handled tree
|
|
1375
1429
|
(`worktree-removed` or `worktree-retained`, with `extra: true` and the tree's
|
|
@@ -1598,16 +1652,56 @@ Rules:
|
|
|
1598
1652
|
### `attached` — another instance's tree
|
|
1599
1653
|
|
|
1600
1654
|
`work/` points at **another instance's work tree** — same branch, same
|
|
1601
|
-
uncommitted state. Spawning attached requires `workDir` (
|
|
1602
|
-
instance's `<home>/work`
|
|
1603
|
-
|
|
1655
|
+
uncommitted state. Spawning attached requires `workDir` (`--work-dir`): a
|
|
1656
|
+
tree in the owning instance's home, its `<home>/work` or one of its
|
|
1657
|
+
[extra trees](#extra-trees) (`<home>/.work-<purpose>`). It is a spawn-time
|
|
1658
|
+
choice (`--work attached`) for service agents such as reviewers.
|
|
1659
|
+
|
|
1660
|
+
The kernel derives the owner and the repository from the tree named on the
|
|
1661
|
+
command line, so the spawn needs no `--repo` and no relation flag (an extra
|
|
1662
|
+
tree from 0.57.0, #958):
|
|
1663
|
+
|
|
1664
|
+
```text
|
|
1665
|
+
oats spawn <soul> --work attached --work-dir <home>/work
|
|
1666
|
+
oats spawn <soul> --work attached --work-dir <home>/.work-<purpose>
|
|
1667
|
+
```
|
|
1668
|
+
|
|
1669
|
+
- **The owner** is the instance in whose home the tree is, and the new
|
|
1670
|
+
instance is its child. It must be an instance of the deployment the spawn
|
|
1671
|
+
runs in, and its name must resolve back to that home from there: a name
|
|
1672
|
+
that resolves to another instance is refused, since the parent link would
|
|
1673
|
+
be ambiguous. The parent is never read from the caller's environment.
|
|
1674
|
+
- **An attached instance's repository is the repository of the tree it is
|
|
1675
|
+
attached to.** For `<home>/work` that is the repository its owner
|
|
1676
|
+
recorded. For an extra tree it is the repository Git names for that tree,
|
|
1677
|
+
which can be another member repository than the owner's own
|
|
1678
|
+
(`oats worktree add --repo`).
|
|
1679
|
+
- `--parent <owner>` and `--repo <repository>` given explicitly are
|
|
1680
|
+
accepted. A relation that is not "child of the owner" is refused.
|
|
1681
|
+
- An extra tree is one by the kernel's test of it, the same one a retire
|
|
1682
|
+
uses ([extra trees at retire](#extra-trees-at-retire)): a linked worktree
|
|
1683
|
+
in the home that Git confirms is registered in a repository outside the
|
|
1684
|
+
home. The shape of the path decides nothing. A directory named `.work-x`
|
|
1685
|
+
that is not such a tree (a plain directory, a clone of its own, a tree of
|
|
1686
|
+
a repository inside the home, a tree whose registration was pruned) is a
|
|
1687
|
+
tree of no instance, and so is a path inside an extra tree.
|
|
1688
|
+
- **A tree of no known instance** (an integration worktree, for example)
|
|
1689
|
+
has nothing to derive from: the spawn needs `--parent <instance>` and
|
|
1690
|
+
`--repo <repository>`. One refusal (`E_BAD_ARGS`) names every one still
|
|
1691
|
+
missing, so one retry is enough.
|
|
1604
1692
|
|
|
1605
1693
|
Attached agents are guests: never switch branches or rewrite history, touch
|
|
1606
1694
|
only what the briefing names, keep commits small and attributable. Retiring
|
|
1607
1695
|
an attached instance never removes the shared tree. When its owner retires
|
|
1608
|
-
and the tree is re-homed,
|
|
1609
|
-
|
|
1610
|
-
|
|
1696
|
+
and the tree is re-homed, `work/` or an extra tree, the `work` link of an
|
|
1697
|
+
instance attached to it is repointed to the tree's new path
|
|
1698
|
+
([retire](#retire), [extra trees at retire](#extra-trees-at-retire)); its
|
|
1699
|
+
AGENTS.md and TASK.md still name the old one. When the retire removes the
|
|
1700
|
+
tree (a clean extra tree, or `work/` with `--discard-worktree`), the link
|
|
1701
|
+
then points at a path that is gone: the plan says so beforehand and the
|
|
1702
|
+
receipt's `warnings` afterwards, each naming the instance and the tree. The
|
|
1703
|
+
owner's `oats worktree remove` does not remove an extra tree while an
|
|
1704
|
+
instance attached to it is running ([extra trees](#extra-trees)). The packaged
|
|
1611
1705
|
`work-attached` instruction source carries this discipline into each generated instance AGENTS.md.
|
|
1612
1706
|
|
|
1613
1707
|
### `directory` — independent execution
|
|
@@ -1773,6 +1867,23 @@ and nothing is removed. On a `creating` record whose process is gone, `remove`
|
|
|
1773
1867
|
completes the rollback instead. Its answer then says whether the branch was
|
|
1774
1868
|
kept (`branchKept`, `branchKeptReason`).
|
|
1775
1869
|
|
|
1870
|
+
`remove` does not remove a tree under a running session. An instance is
|
|
1871
|
+
attached to the tree when its `instance.json` says `work: "attached"` and its
|
|
1872
|
+
`work` is a link to it ([`attached`](#attached--another-instances-tree)).
|
|
1873
|
+
When such an instance's session is running, or cannot be read, `remove`
|
|
1874
|
+
refuses with `E_CHILDREN_RUNNING` before it asks Git anything: nothing is
|
|
1875
|
+
removed and the record is kept. The message names each such instance and
|
|
1876
|
+
what was seen (an unread session is not called running), and gives the step:
|
|
1877
|
+
stop it (`oats instance stop <instance>`) or retire it, then run `remove`
|
|
1878
|
+
again. `remove` stops nobody, and no flag removes the tree anyway. An
|
|
1879
|
+
attached instance whose session is stopped does not refuse: the tree is
|
|
1880
|
+
removed, and the answer's `warnings` name the instance and its `work` link,
|
|
1881
|
+
which then points at a path that is gone. The instances looked at are the
|
|
1882
|
+
recorded children of the tree's owner, as its retire plan lists them, and
|
|
1883
|
+
those the plan lists as `ambiguous` (they record the owner as their parent
|
|
1884
|
+
under a name that is not unique): the link makes an instance attached, not
|
|
1885
|
+
its lineage. A tree that is already gone from disk is not checked.
|
|
1886
|
+
|
|
1776
1887
|
**Working in the tree.**
|
|
1777
1888
|
|
|
1778
1889
|
- `git switch` needs Git 2.23 or later.
|