@awebai/oats 0.69.18 → 0.69.19
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/docs/capabilities.md +1 -1
- package/docs/container.md +198 -25
- package/docs/design/2026-09-27-team-model-v2.md +2 -2
- package/docs/design/2026-09-28-automations-trust.md +1 -1
- package/docs/desktop-cli-api.md +27 -20
- package/docs/desktop.md +13 -6
- package/docs/execution-targets.md +32 -17
- package/docs/implementation.md +2 -2
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-lane.md +6 -4
- package/docs/release-notes/v0.69.19.md +172 -0
- package/docs/servers.md +2 -2
- package/docs/souls-and-instances.md +33 -11
- package/docs/tui.md +8 -8
- package/docs/upgrading.md +11 -5
- package/docs/workspaces.md +1 -1
- package/injects/work-directory.md +27 -2
- package/injects/work-workspace.md +32 -6
- package/lib/core.mjs +2 -2
- package/lib/host-run.mjs +24 -19
- package/lib/session-resume-contract.mjs +1 -1
- package/lib/session-resume.mjs +130 -47
- package/lib/session-seen.mjs +3 -3
- package/package-catalog.json +2 -2
- package/package.json +3 -1
- package/packages/client/instance-presentation.mjs +2 -2
- package/packages/client/instance-tree.mjs +18 -7
- package/skills/oats-getting-started/SKILL.md +3 -3
package/docs/release-lane.md
CHANGED
|
@@ -180,21 +180,23 @@ runs the same installer steps, so it names the same commits. So does
|
|
|
180
180
|
lane's call of 2026-10-27: it runs a branch's code on the release's own
|
|
181
181
|
actions, and its run is that pull request's macOS evidence, so it names them
|
|
182
182
|
at the commits that were read
|
|
183
|
-
([Implementation](implementation.md#the-tuis-tests-on-macos)).
|
|
183
|
+
([Implementation](implementation.md#the-tuis-tests-on-macos)).
|
|
184
|
+
`team-image.yml` also names these commits for
|
|
185
|
+
[image acceptance](container.md#image-ci-and-publication). Every other
|
|
184
186
|
workflow keeps tags (`actions/checkout@v4`): nothing is published from them.
|
|
185
187
|
|
|
186
188
|
`test/workflow-no-cache.test.mjs` holds this. Its table of the actions that
|
|
187
|
-
were read has a row for each action: `action`, `id`, `version`. In
|
|
189
|
+
were read has a row for each action: `action`, `id`, `version`. In these four
|
|
188
190
|
files every `uses:` is a row's id, the same action is the same id in all of
|
|
189
191
|
them, and the comment beside an id is the row's version. In every other
|
|
190
192
|
workflow a `uses:` is the major of a row's version.
|
|
191
193
|
|
|
192
194
|
**An id is moved by a pull request, reviewed like any change to that
|
|
193
|
-
workflow.** It changes these together, and nothing else in
|
|
195
|
+
workflow.** It changes these together, and nothing else in these four workflow
|
|
194
196
|
files:
|
|
195
197
|
|
|
196
198
|
- the id and the version comment, on every `uses:` line of that action in
|
|
197
|
-
`release.yml`, `build-installers.yml` and `
|
|
199
|
+
`release.yml`, `build-installers.yml`, `tui-macos.yml` and `team-image.yml`;
|
|
198
200
|
- the action's row in the table.
|
|
199
201
|
|
|
200
202
|
**The id is read from an exact version tag of the action's own repository**
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# OATS 0.69.19
|
|
2
|
+
|
|
3
|
+
The official catalog pins oats.aweb 1.42.1, which makes retained seats safer
|
|
4
|
+
and shortens the always-loaded messaging instructions, and oats.framework
|
|
5
|
+
1.25.2. Instances in `workspace` and `directory` mode can make extra trees of
|
|
6
|
+
their own for repository work. `oats host run` runs the resume sweep each
|
|
7
|
+
minute, and the sweep retries a refused start and counts a home's starts per
|
|
8
|
+
hour. The Desktop's sidebar lists instances newest first. oats.okf stays
|
|
9
|
+
6.0.3.
|
|
10
|
+
|
|
11
|
+
## Upgrade
|
|
12
|
+
|
|
13
|
+
- **Either order of the Desktop and the CLI works** from a Desktop newer than
|
|
14
|
+
0.69.17 ([Either order works](../upgrading.md#either-order-works)). A
|
|
15
|
+
Desktop of 0.69.17 or older still goes first.
|
|
16
|
+
- **Package pins:** oats.aweb 1.42.1 (from 1.41.0) and oats.framework 1.25.2
|
|
17
|
+
(from 1.25.0). oats.okf stays 6.0.3. `oats sync` takes them; the two oats.aweb
|
|
18
|
+
steps below apply only where they match.
|
|
19
|
+
- **A retained seat reads its aweb service only from its own record.** If
|
|
20
|
+
you set `OATS_AWEB_URL` for a retained seat, record the server in the seat
|
|
21
|
+
with `aw workspace connect --service <server>`, run in the seat's parent
|
|
22
|
+
directory, then unset the variable. A seat whose `workspace.yaml` already
|
|
23
|
+
names its server is unchanged.
|
|
24
|
+
- **A non-boolean `identity.e2ee` or `identity.takeOver` is refused** at spawn
|
|
25
|
+
and start. `true`, `false` and the strings `"true"`/`"false"` are accepted,
|
|
26
|
+
and an empty value reads as unset. Set any other value to `true` or `false`.
|
|
27
|
+
- **Scripts that read `oats session resume --json`:** the row reason
|
|
28
|
+
`refused-this-boot` is gone. A refused start waiting for its next attempt
|
|
29
|
+
is `start-refused-retrying`, and `keeps-getting-lost` now means 3 starts in
|
|
30
|
+
the last hour (details under Changed). The Desktop doesn't depend on these
|
|
31
|
+
reasons.
|
|
32
|
+
- **Respawn instances** to take the shorter aweb text and the extra-trees
|
|
33
|
+
briefing of the `workspace` and `directory` modes: a running instance keeps
|
|
34
|
+
the text it was composed with.
|
|
35
|
+
|
|
36
|
+
## Added
|
|
37
|
+
|
|
38
|
+
- **Team image acceptance in CI.** Pull requests now build the team agent image
|
|
39
|
+
from their exact head commit and run the existing container acceptance script
|
|
40
|
+
on an amd64 runner with a private Compose fixture and no inference credentials.
|
|
41
|
+
Release image publication is prepared after the OATS release, by digest with an
|
|
42
|
+
exact release retention tag. The run and release notes record the immutable
|
|
43
|
+
reference. Publication remains disabled pending the registry decision and
|
|
44
|
+
requires a stable OATS release tag of at least 0.69.18 plus a committed final
|
|
45
|
+
aw image pin of at least 1.36.59.
|
|
46
|
+
|
|
47
|
+
- Manual verification of an image built with its selected commit's own packed
|
|
48
|
+
kernel, with exact installed-file paths, sizes, modes and hashes checked
|
|
49
|
+
against HEAD. A separate proof compares the default installed payload with
|
|
50
|
+
and without the read-only build-context mount. Packed mode remains manual
|
|
51
|
+
until the compatible image baseline lands; publication stays disabled.
|
|
52
|
+
With the committed baseline, the packed job refuses; positive real
|
|
53
|
+
packed-image acceptance is **NOT RUN** until that compatible baseline lands.
|
|
54
|
+
|
|
55
|
+
## Changed
|
|
56
|
+
|
|
57
|
+
- **The catalog pins oats.aweb 1.42.1** (from 1.41.0). 1.42.0 is never
|
|
58
|
+
pinned: a comment in it named the kernel's private module, which the mirror
|
|
59
|
+
check refuses. 1.42.1 requires OATS >=0.68.0, the aw floor stays 1.36.33,
|
|
60
|
+
and the tested aw is 1.36.58. Most of
|
|
61
|
+
the release is about retained seats: an atomic seat lock, a lock held on
|
|
62
|
+
another host refuses with its release, a killed or failed spawn never
|
|
63
|
+
deletes the standing identity's workspace, and a seat with no membership of
|
|
64
|
+
its team is refused before any effect. The captured-execution variables are
|
|
65
|
+
now ignored, with one warning each. The always-loaded messaging
|
|
66
|
+
instructions are shorter, and new spawns get the new text.
|
|
67
|
+
|
|
68
|
+
- **The Desktop's Add machine dialog gives an invented host as its example.**
|
|
69
|
+
The host field's placeholder now reads "ssh host alias, e.g. devbox"; it
|
|
70
|
+
named one deployment's own machine. Nothing else in the dialog changes.
|
|
71
|
+
|
|
72
|
+
- **The `directory` work mode teaches extra trees.** Its briefing granted
|
|
73
|
+
none, while the instance-boundary block says repository work happens "there,
|
|
74
|
+
or in the extra trees your mode block grants", and `oats worktree add`
|
|
75
|
+
already worked from a directory home. `./work` stays an owned directory
|
|
76
|
+
that never becomes a repository; repository work that needs a branch goes in
|
|
77
|
+
an extra tree of the instance's own, with the same "Extra trees" section as
|
|
78
|
+
the `workspace` briefing:
|
|
79
|
+
`oats worktree add --purpose <p> --branch <b> --base <remote-branch> --repo <repo>`.
|
|
80
|
+
`--repo` is always named: the home's recorded repository is configuration
|
|
81
|
+
context, the deployment directory by default, so `add` without it is
|
|
82
|
+
refused there (`E_CLONE_MISSING`). A directory instance's `TASK.md` says the
|
|
83
|
+
same ("Work in ./work; do repository work only in your extra trees.")
|
|
84
|
+
([work modes](../souls-and-instances.md#directory--independent-execution)).
|
|
85
|
+
Existing homes keep the briefing they were composed with; a new spawn picks
|
|
86
|
+
this one up.
|
|
87
|
+
|
|
88
|
+
- **`oats.framework` 1.25.2: `oats.core` 2.13.2** (through 1.25.1).
|
|
89
|
+
`oats.core`'s `/oats-operate` says that `workspace`- and `directory`-mode
|
|
90
|
+
instances can make extra trees too: work that needs a branch goes in an
|
|
91
|
+
extra tree of the instance's own, made with `oats worktree add --repo
|
|
92
|
+
<repo>`. Member clones stay read-only, and a directory instance's `./work`
|
|
93
|
+
never becomes a repository.
|
|
94
|
+
|
|
95
|
+
No capability needs a newer OATS: `oats worktree add --repo` has worked
|
|
96
|
+
from those homes since OATS 0.49.0.
|
|
97
|
+
|
|
98
|
+
- **`oats host run` runs the resume sweep each minute, not only at its
|
|
99
|
+
start.** An agent whose session is lost while the host runs (its harness
|
|
100
|
+
crashed or was killed) is started again by the sweep of the next minute,
|
|
101
|
+
within the sweep's own bounds: at most 3 starts of a home in an hour, a
|
|
102
|
+
refused start retried with backoff, and a home given up after 3 such hours
|
|
103
|
+
in a row. Before, a container that stayed up never started a lost agent
|
|
104
|
+
again; only a restart of the container did.
|
|
105
|
+
|
|
106
|
+
A home the sweep started counts as seen running for that start. A home
|
|
107
|
+
that is lost again within the minute, before any read saw it running, is
|
|
108
|
+
therefore started again and counted, not left as `not-seen-recently`.
|
|
109
|
+
|
|
110
|
+
The sweep replaces the listing `oats host run` ran each minute, and records
|
|
111
|
+
what that listing recorded. A sweep that still runs at the next minute is
|
|
112
|
+
not run beside itself. Progress says a sweep only when its outcomes differ
|
|
113
|
+
from those of the sweep before. The answer's `sweep` is the first sweep's.
|
|
114
|
+
Stopping is unchanged: a sweep that runs gets the same 10 seconds, and the
|
|
115
|
+
admission fence stops its further starts.
|
|
116
|
+
|
|
117
|
+
- **`oats session resume` tries a refused start again, and counts a home's
|
|
118
|
+
starts per hour.** A start the sweep ran and that was refused (a launch
|
|
119
|
+
variable not set, no wake broker running yet) launched nothing and says how
|
|
120
|
+
the host was at that moment. It no longer answers the loss for good: the
|
|
121
|
+
sweep tries that home again no sooner than 1 minute later, doubling to 15
|
|
122
|
+
minutes at most, until the loss is 24 hours old. A home that keeps getting
|
|
123
|
+
lost is still started at most 3 times, now in an hour instead of in a boot,
|
|
124
|
+
and a sweep starts it again when the oldest of those starts is an hour old.
|
|
125
|
+
A home that uses up its starts 3 hours in a row is given up until a person
|
|
126
|
+
starts it.
|
|
127
|
+
Both the count and the delays are kept for one boot. On upgrade, a home's
|
|
128
|
+
count of starts for the current boot begins at zero once: the earlier
|
|
129
|
+
kernel's note holds no start times.
|
|
130
|
+
|
|
131
|
+
**Contract change for clients of `oats session resume --json`**
|
|
132
|
+
([the machine sweep](../desktop-cli-api.md#the-machine-sweep-oats-session-resume)):
|
|
133
|
+
- the row reason `refused-this-boot` is no longer emitted. A refusal that
|
|
134
|
+
is waiting for its next attempt is `start-refused-retrying`, with the
|
|
135
|
+
refusal's `code` and `message`;
|
|
136
|
+
- `start-refused`, `start-refused-retrying` and `keeps-getting-lost` rows
|
|
137
|
+
carry `nextAttemptAt`, an ISO time (not on a host without a boot id,
|
|
138
|
+
where nothing is noted);
|
|
139
|
+
- `keeps-getting-lost` keeps its name and now means 3 starts in the last
|
|
140
|
+
hour, not in this boot. It is final only without `nextAttemptAt`: after
|
|
141
|
+
3 such hours in a row;
|
|
142
|
+
- a refused start and `keeps-getting-lost` no longer make later sweeps
|
|
143
|
+
answer the home `not-seen-recently`.
|
|
144
|
+
|
|
145
|
+
- **The Desktop's sidebar lists instances newest first.** The instance tree
|
|
146
|
+
is in spawn order, newest on top, instead of by name, at every level: a
|
|
147
|
+
group of related instances by its first instance, the children under a
|
|
148
|
+
parent the same way. Spawning a child doesn't move its group, and starting
|
|
149
|
+
or stopping an instance still moves nothing. The TUI's list and the command
|
|
150
|
+
palette's never-focused rows follow the same order.
|
|
151
|
+
|
|
152
|
+
- Release image preparation installs the exact kernel version just published,
|
|
153
|
+
preserves unrelated committed lock entries and retains the generated inputs.
|
|
154
|
+
Acceptance verifies the installed version before registry login. Publication
|
|
155
|
+
remains disabled; its prepared path adds only the exact release retention tag,
|
|
156
|
+
refuses tag conflicts and records an immutable digest receipt with explicit
|
|
157
|
+
build/startup coverage and unrun agent and containment checks.
|
|
158
|
+
|
|
159
|
+
- **The `workspace` work mode teaches extra trees.** Its briefing no longer
|
|
160
|
+
lists worktrees among the Git operations it forbids, which contradicted the
|
|
161
|
+
instance-boundary block ("repository work happens there, or in the extra
|
|
162
|
+
trees your mode block grants"). Member clones stay read-only through
|
|
163
|
+
`./work`; work that needs a member's branch goes in an extra tree of the
|
|
164
|
+
instance's own, made with
|
|
165
|
+
`oats worktree add --purpose <p> --branch <b> --base <remote-branch> --repo <member>`,
|
|
166
|
+
which moves none of the clone's refs. `--repo` is always named in this mode:
|
|
167
|
+
the home's recorded repository is the deployment directory, so `add` without
|
|
168
|
+
it is refused (`E_CLONE_MISSING`). A workspace instance's `TASK.md` says the
|
|
169
|
+
same. What work an instance takes on stays its role's and its task's call
|
|
170
|
+
([work modes](../souls-and-instances.md#workspace--cross-repo-coordinator)).
|
|
171
|
+
Existing homes keep the briefing they were composed with; a new spawn picks
|
|
172
|
+
this one up.
|
package/docs/servers.md
CHANGED
|
@@ -246,7 +246,7 @@ symlinks. Neither the caller's command nor stdin chooses a destination path.
|
|
|
246
246
|
## Connect a machine
|
|
247
247
|
|
|
248
248
|
```bash
|
|
249
|
-
oats server connect
|
|
249
|
+
oats server connect devbox-aweb --ssh devbox --dir '~/acme' --install-oats
|
|
250
250
|
```
|
|
251
251
|
|
|
252
252
|
Run from a deployment, `server connect` puts that deployment's workspace on
|
|
@@ -569,7 +569,7 @@ registration.
|
|
|
569
569
|
**Capability commands.** Any capability command routes with `--server`:
|
|
570
570
|
|
|
571
571
|
```bash
|
|
572
|
-
oats aweb setup --join aweb --invite-stdin --soul dev --server
|
|
572
|
+
oats aweb setup --join aweb --invite-stdin --soul dev --server devbox-aweb < invite.txt
|
|
573
573
|
```
|
|
574
574
|
|
|
575
575
|
The host runs the same argv, minus `--server <id>` (or `--server=<id>`;
|
|
@@ -1841,8 +1841,9 @@ after the capability injects (`injects/instance-boundary.md`):
|
|
|
1841
1841
|
target another one deliberately).
|
|
1842
1842
|
- `<instance-home>/work` — the repository or workspace view — is where
|
|
1843
1843
|
repository reading, editing, building, testing, git and commits happen, to the
|
|
1844
|
-
extent the mode below permits. In `worktree
|
|
1845
|
-
instance's [extra trees](#extra-trees) in the home
|
|
1844
|
+
extent the mode below permits. In `worktree`, `checkout`, `workspace` and
|
|
1845
|
+
`directory` mode, the instance's [extra trees](#extra-trees) in the home
|
|
1846
|
+
serve the same purpose.
|
|
1846
1847
|
- The home has no soul link: the composed `AGENTS.md` already carries the
|
|
1847
1848
|
soul's instructions, and `instance.json` `soulDir` records the (read-only,
|
|
1848
1849
|
per-commit) soul directory every hook and dispatched command receives as
|
|
@@ -2014,6 +2015,14 @@ without Git. `repo` (or `--repo`) supplies context only and may be an ordinary
|
|
|
2014
2015
|
directory; without it, the deployment directory (where `oats-local.yaml` is) is
|
|
2015
2016
|
used. No implicit fallback changes the other modes.
|
|
2016
2017
|
|
|
2018
|
+
Repository work that needs a branch — a change the instance's role and task
|
|
2019
|
+
call for, or a repository at the remote's current state — goes in an
|
|
2020
|
+
[extra tree](#extra-trees) of the instance's own, never in `work/` (which
|
|
2021
|
+
never becomes a repository) and never in the `repo` directory. An extra tree
|
|
2022
|
+
always names its repository (`--repo`): the recorded `repo` is context only,
|
|
2023
|
+
the deployment directory by default, so `oats worktree add` without `--repo`
|
|
2024
|
+
is refused when it is not a clone (`E_CLONE_MISSING`).
|
|
2025
|
+
|
|
2017
2026
|
`--work-dir` and `--branch` are rejected. Canonical instructions, skill
|
|
2018
2027
|
composition, provider trust and harness preflight still apply. Retirement preserves nonempty work in verified recovery storage beside the
|
|
2019
2028
|
home (`workRecovery.path/work`) before deleting it, including files created by
|
|
@@ -2048,21 +2057,34 @@ where it works are decoupled.
|
|
|
2048
2057
|
|
|
2049
2058
|
Rules:
|
|
2050
2059
|
|
|
2051
|
-
- Read freely across member repos
|
|
2052
|
-
|
|
2053
|
-
- No
|
|
2060
|
+
- Read freely across member repos through `work/`; **never edit or commit
|
|
2061
|
+
inside the member clones** — others use them.
|
|
2062
|
+
- No Git state operations in any member clone (no branch switches, resets,
|
|
2063
|
+
pulls, stashes, or `git worktree` run by hand).
|
|
2064
|
+
- Work that needs a branch of a member — a change the instance's role and
|
|
2065
|
+
task call for, or a member at the remote's current state — goes in an
|
|
2066
|
+
[extra tree](#extra-trees) of the instance's own, which `oats worktree add`
|
|
2067
|
+
makes without moving any of the clone's refs. Otherwise route the change to
|
|
2068
|
+
the owning repo's agents or the human. The mode says where work happens;
|
|
2069
|
+
what work the instance takes on is its role's and its task's call.
|
|
2054
2070
|
- Knowledge promotion follows the knowledge capability's own protocol, never
|
|
2055
2071
|
direct edits through the workspace view.
|
|
2056
2072
|
|
|
2057
|
-
The instance records no branch: the workspace is not a Git tree.
|
|
2073
|
+
The instance records no branch: the workspace is not a Git tree. For the same
|
|
2074
|
+
reason an extra tree always names its repository (`--repo`): the instance's
|
|
2075
|
+
recorded repository is the deployment directory.
|
|
2058
2076
|
|
|
2059
2077
|
### Extra trees
|
|
2060
2078
|
|
|
2061
|
-
An instance in `worktree` or `
|
|
2062
|
-
Git worktrees in its home, beside `work/`. It does
|
|
2063
|
-
another branch, or another repository of the deployment
|
|
2064
|
-
touches several repositories)
|
|
2065
|
-
|
|
2079
|
+
An instance in `worktree`, `checkout`, `workspace` or `directory` mode can
|
|
2080
|
+
create extra trees: linked Git worktrees in its home, beside `work/`. It does
|
|
2081
|
+
so when the work needs another branch, or another repository of the deployment
|
|
2082
|
+
(one task that touches several repositories); in `workspace` mode, whenever
|
|
2083
|
+
work needs a branch of a member, since `work/` is read-only; in `directory`
|
|
2084
|
+
mode, whenever work needs a branch at all, since `work/` is not a Git tree.
|
|
2085
|
+
The `worktree`, `checkout`, `workspace` and `directory` briefings teach it
|
|
2086
|
+
(the `workspace` and `directory` ones with `--repo` always, in one shared
|
|
2087
|
+
section); the `attached` briefing does not.
|
|
2066
2088
|
|
|
2067
2089
|
```text
|
|
2068
2090
|
oats worktree add --purpose <p> --branch <b> --base <remote-branch>
|
package/docs/tui.md
CHANGED
|
@@ -176,12 +176,12 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
176
176
|
kernel reported that were withheld (a home outside its soul's directory,
|
|
177
177
|
or one reported twice), `2 withheld`, when there are any.
|
|
178
178
|
- **The list** is the roster the Desktop draws: the same groups in the same
|
|
179
|
-
order, from the same code. It is in
|
|
180
|
-
instance, so starting or stopping an instance moves nothing. An instance
|
|
179
|
+
order, from the same code. It is in spawn order, newest first, by each
|
|
180
|
+
group's top instance, so starting or stopping an instance moves nothing. An instance
|
|
181
181
|
that others were spawned from has them indented under it, and keeps its
|
|
182
182
|
place when it gains or loses one. Under one parent, the instances that do
|
|
183
183
|
its work (the kernel's `sameWork`, from an OATS with `instance-same-work`)
|
|
184
|
-
come first, then the others, each part
|
|
184
|
+
come first, then the others, each part newest first, as the Desktop lists
|
|
185
185
|
them. An empty row stands between each run
|
|
186
186
|
of instances related to no other and the group before or after it. The
|
|
187
187
|
indent alone says which instance is under which: no mark is drawn for
|
|
@@ -974,7 +974,7 @@ selected.
|
|
|
974
974
|
```
|
|
975
975
|
acme-platform │ dev
|
|
976
976
|
acme-billing ● │ soul dev
|
|
977
|
-
|
|
977
|
+
lab │ state running
|
|
978
978
|
garnet │ harness claude, claude-opus-5-5 (so…
|
|
979
979
|
+2 │ work worktree, agents/dev
|
|
980
980
|
│ team eng
|
|
@@ -983,7 +983,7 @@ selected.
|
|
|
983
983
|
|
|
984
984
|
The sidebar's first rows list the workspaces this run can show, one row a
|
|
985
985
|
workspace, whatever machines it is on, in [the switcher](#the-switcher)'s
|
|
986
|
-
order: `
|
|
986
|
+
order: `lab` is one row however many machines hold it, and a machine the
|
|
987
987
|
rules shared with the Desktop matched to no workspace is a row by its own
|
|
988
988
|
name, in the same flat list. A row is one line: the name. With one
|
|
989
989
|
workspace the list is its row.
|
|
@@ -1028,7 +1028,7 @@ workspace the list is its row.
|
|
|
1028
1028
|
that list fills the sidebar, which then has no such row, does the line
|
|
1029
1029
|
take a row, the list giving up its last. With the list's focus (`w`) the
|
|
1030
1030
|
focus stays there, the cursor where it was. A workspace with a deployment of this
|
|
1031
|
-
machine not opened yet (
|
|
1031
|
+
machine not opened yet (lab, with `~/Work/lab` on this computer's list)
|
|
1032
1032
|
opens it first, as the switcher's `Enter` does. What the workspace left
|
|
1033
1033
|
had open is kept for it, as for a switch from the
|
|
1034
1034
|
switcher ([Tabs](#tabs)), and from a terminal's focus the focus is kept
|
|
@@ -1068,9 +1068,9 @@ switcher covers the whole screen.
|
|
|
1068
1068
|
workspaces │ > * acme-platform
|
|
1069
1069
|
│ This machine
|
|
1070
1070
|
Instances 1 │ garnet
|
|
1071
|
-
Souls 2 │
|
|
1071
|
+
Souls 2 │ lab
|
|
1072
1072
|
Capabilities 3 │ This machine · not opened
|
|
1073
|
-
────────────────────────────────────────────────│
|
|
1073
|
+
────────────────────────────────────────────────│ builder (lab)
|
|
1074
1074
|
Ctrl+X commands │ Not matched to a workspace
|
|
1075
1075
|
Ctrl+K palette │ basalt ssh needs a prompt
|
|
1076
1076
|
Enter open │ On this machine, not opened
|
package/docs/upgrading.md
CHANGED
|
@@ -6,12 +6,12 @@ host that comes from it.
|
|
|
6
6
|
|
|
7
7
|
## Upgrading to the latest version
|
|
8
8
|
|
|
9
|
-
The latest version is **OATS 0.69.
|
|
10
|
-
The 0.69.
|
|
9
|
+
The latest version is **OATS 0.69.19** ([release notes](release-notes/v0.69.19.md)).
|
|
10
|
+
The 0.69.19 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
|
|
11
11
|
Desktop and the CLI can be upgraded [in either order](#either-order-works).
|
|
12
12
|
|
|
13
13
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
14
|
-
0.69.
|
|
14
|
+
0.69.19,** in the [release notes](release-notes/): it says what to do before
|
|
15
15
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
16
16
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
17
17
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -20,8 +20,8 @@ prints the version you have.
|
|
|
20
20
|
Then, on each host:
|
|
21
21
|
|
|
22
22
|
```sh
|
|
23
|
-
# 0. where the Desktop is installed: Desktop 0.69.
|
|
24
|
-
npm install -g @awebai/oats@0.69.
|
|
23
|
+
# 0. where the Desktop is installed: Desktop 0.69.19, in either order
|
|
24
|
+
npm install -g @awebai/oats@0.69.19 # 1. the CLI
|
|
25
25
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
26
26
|
oats doctor # 3. in the same deployment
|
|
27
27
|
```
|
|
@@ -217,6 +217,12 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
217
217
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
218
218
|
here.
|
|
219
219
|
|
|
220
|
+
- **[0.69.19](release-notes/v0.69.19.md#upgrade):** the catalog pins
|
|
221
|
+
oats.aweb 1.42.1 and oats.framework 1.25.2. A retained seat that relied on
|
|
222
|
+
`OATS_AWEB_URL` records its server with `aw workspace connect` and unsets the
|
|
223
|
+
variable; a non-boolean `identity.e2ee` or `identity.takeOver` is set to
|
|
224
|
+
`true` or `false`. Respawn instances to take the shorter aweb text and the
|
|
225
|
+
workspace and directory modes' extra trees.
|
|
220
226
|
- **[0.69.18](release-notes/v0.69.18.md#upgrade):** from this Desktop on,
|
|
221
227
|
the Desktop and the CLI go in either order (a Desktop of 0.69.17 or older
|
|
222
228
|
still goes first); the catalog pins oats.aweb 1.41.0, oats.okf 6.0.3 and
|
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.25.
|
|
57
|
+
oats.framework: v1.25.2 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v6.0.3
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
@@ -4,9 +4,34 @@ Your `./work` is an **instance-owned execution directory**, not a Git worktree,
|
|
|
4
4
|
checkout or link. The `repo` recorded for you supplies configuration only; it
|
|
5
5
|
grants no permission to edit the `repo` directory.
|
|
6
6
|
|
|
7
|
-
- Work inside `./work
|
|
8
|
-
repository Git discovers is not yours.
|
|
7
|
+
- Work inside `./work`, apart from your extra trees. **Never initialize a
|
|
8
|
+
fake repository**; a containing repository Git discovers is not yours.
|
|
9
|
+
- **Repository work that needs a branch goes in an extra tree of your own**
|
|
10
|
+
(below): a change your role and task call for, or a repository at the
|
|
11
|
+
remote's current state. What work you take on stays your role's and your
|
|
12
|
+
task's call.
|
|
9
13
|
- Use external inputs and destinations only as your task and capabilities
|
|
10
14
|
explicitly authorize.
|
|
11
15
|
- Deliver results through your task's own protocol before you finish: the
|
|
12
16
|
recovery copy kept at retirement is not publication.
|
|
17
|
+
|
|
18
|
+
### Extra trees
|
|
19
|
+
|
|
20
|
+
For a branch of a member repository, from your home (`--preview` first;
|
|
21
|
+
`<repo>`: the member key or clone path, always, since your own `./work` is
|
|
22
|
+
not a Git tree; `<base>`: the remote branch to start from, or the one you
|
|
23
|
+
rework):
|
|
24
|
+
|
|
25
|
+
oats worktree add --purpose <purpose> --branch <branch> --base <base> --repo <repo>
|
|
26
|
+
|
|
27
|
+
It moves none of the clone's refs. A tree is yours alone: build, test and
|
|
28
|
+
commit there.
|
|
29
|
+
|
|
30
|
+
- Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
|
|
31
|
+
(if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
|
|
32
|
+
- `add` may take minutes: use a long timeout; if killed, rerun it.
|
|
33
|
+
- Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
|
|
34
|
+
- Before you finish, merge each tree into your PR branch, or push it and name
|
|
35
|
+
it in your hand-back; then `oats worktree remove --purpose <purpose>`.
|
|
36
|
+
Retirement may keep a tree with uncommitted work; don't rely on it.
|
|
37
|
+
Details: `oats worktree --help`, and `/oats-operate` if you have it.
|
|
@@ -1,11 +1,37 @@
|
|
|
1
1
|
## Work mode: workspace
|
|
2
2
|
|
|
3
|
-
Your `./work` is the **whole workspace**, not one repository
|
|
4
|
-
|
|
3
|
+
Your `./work` is the **whole workspace**, not one repository: every member
|
|
4
|
+
clone, read through it. What work you take on is your role's and your task's
|
|
5
|
+
call; this block says where it happens.
|
|
5
6
|
|
|
6
|
-
- **Read freely across member repositories
|
|
7
|
-
and NEVER change
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
- **Read freely across member repositories through `./work`; never edit or
|
|
8
|
+
commit there, and NEVER change a member clone's Git state** (no branch
|
|
9
|
+
switches, resets, pulls, stashes, or `git worktree` run by hand). Others
|
|
10
|
+
use those clones.
|
|
11
|
+
- **Work that needs a branch goes in an extra tree of your own** (below): a
|
|
12
|
+
change your role and task call for, or a member at the remote's current
|
|
13
|
+
state. Otherwise route a repository change to that repository's agents or
|
|
14
|
+
to your human.
|
|
10
15
|
- A capability that delivers updates into a repository follows its own
|
|
11
16
|
instructions; that is not an exception you take yourself.
|
|
17
|
+
|
|
18
|
+
### Extra trees
|
|
19
|
+
|
|
20
|
+
For a branch of a member repository, from your home (`--preview` first;
|
|
21
|
+
`<repo>`: the member key or clone path, always, since your own `./work` is
|
|
22
|
+
not a Git tree; `<base>`: the remote branch to start from, or the one you
|
|
23
|
+
rework):
|
|
24
|
+
|
|
25
|
+
oats worktree add --purpose <purpose> --branch <branch> --base <base> --repo <repo>
|
|
26
|
+
|
|
27
|
+
It moves none of the clone's refs. A tree is yours alone: build, test and
|
|
28
|
+
commit there.
|
|
29
|
+
|
|
30
|
+
- Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
|
|
31
|
+
(if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
|
|
32
|
+
- `add` may take minutes: use a long timeout; if killed, rerun it.
|
|
33
|
+
- Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
|
|
34
|
+
- Before you finish, merge each tree into your PR branch, or push it and name
|
|
35
|
+
it in your hand-back; then `oats worktree remove --purpose <purpose>`.
|
|
36
|
+
Retirement may keep a tree with uncommitted work; don't rely on it.
|
|
37
|
+
Details: `oats worktree --help`, and `/oats-operate` if you have it.
|
package/lib/core.mjs
CHANGED
|
@@ -4824,14 +4824,14 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4824
4824
|
: work === "directory"
|
|
4825
4825
|
? `an instance-owned execution directory — not a Git worktree or a link to ${repoAbs}; that path supplies configuration only`
|
|
4826
4826
|
: work === "workspace"
|
|
4827
|
-
? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you
|
|
4827
|
+
? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you never edit member clones there (see your work-mode briefing)`
|
|
4828
4828
|
: `a symlink to the ${repoAbs} checkout — you share it; ${branch ? `work on the currently checked-out branch (${branch})` : `work on what is checked out (${noBranch})`} and do not switch branches without being asked`;
|
|
4829
4829
|
writeFileSync(join(home, "TASK.md"), `# Instance briefing: ${instance}
|
|
4830
4830
|
|
|
4831
4831
|
You are instance "${instance}" of agent "${agent.name}".
|
|
4832
4832
|
- Home: ${home}
|
|
4833
4833
|
- Work tree: ./work — ${workDesc}
|
|
4834
|
-
- Do all repository work inside ./work. Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}${harness === "codex" ? "\n## Harness notification delivery\n\nNative Codex has no built-in messaging channel. Follow the explicit delivery briefing for this instance from your messaging capability, if present; it may arrange notification through this terminal. Shared channel instructions alone do not establish that delivery is configured. Without an instance delivery briefing, check your messaging capability's inbox and pending commands at task boundaries or when the operator asks; do not assume messages will wake this session.\n" : ""}
|
|
4834
|
+
- ${work === "workspace" ? "Read across the workspace in ./work; do repository work only in your extra trees." : work === "directory" ? "Work in ./work; do repository work only in your extra trees." : "Do all repository work inside ./work."} Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}${harness === "codex" ? "\n## Harness notification delivery\n\nNative Codex has no built-in messaging channel. Follow the explicit delivery briefing for this instance from your messaging capability, if present; it may arrange notification through this terminal. Shared channel instructions alone do not establish that delivery is configured. Without an instance delivery briefing, check your messaging capability's inbox and pending commands at task boundaries or when the operator asks; do not assume messages will wake this session.\n" : ""}
|
|
4835
4835
|
${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spawn time — await instructions.\n"}`, { mode: 0o600 }); // human text: the owner's only
|
|
4836
4836
|
// Feature instance-background: the home's record, beside its other files, so the spawn's rollback
|
|
4837
4837
|
// (which removes the home) leaves nothing of it.
|
package/lib/host-run.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/** `oats host run` (oats-project/oats#1789): the kernel's periodic work in one foreground process,
|
|
2
2
|
* for a host where no timer can run it (a container, a machine without launchd or a systemd user
|
|
3
3
|
* manager). Every `oats` command is short-lived and agents sit under a daemonised tmux server, so
|
|
4
|
-
* without it nothing there runs the resume sweep
|
|
4
|
+
* without it nothing there runs the resume sweep or the schedule tick each minute, and
|
|
5
5
|
* nothing stops the agents in order when the host stops.
|
|
6
6
|
*
|
|
7
7
|
* - Refused before any effect: inside an instance session (OATS_INSTANCE_HOME set), E_USAGE; while
|
|
@@ -13,12 +13,12 @@
|
|
|
13
13
|
* holder by pid, process start and boot id. A lock whose holder is gone, or that was taken in
|
|
14
14
|
* another kernel boot, is taken over at once; a holder that runs, and a
|
|
15
15
|
* lock that cannot be judged, are E_HOST_RUN_BUSY, `details` `{ lock, found }`.
|
|
16
|
-
* - A run, in order: the lock; the resume sweep
|
|
16
|
+
* - A run, in order: the lock; the resume sweep (`oats session resume`); then, at second 0 of
|
|
17
17
|
* each minute, `oats schedule tick --host` when the host schedule registry lists a scope (with
|
|
18
|
-
* none it ticks nothing and says so), and
|
|
19
|
-
* records what runs for
|
|
20
|
-
* loop stays free for the signal. A minute whose tick still runs is skipped; a minute
|
|
21
|
-
* never replayed (the host timer's own rule).
|
|
18
|
+
* none it ticks nothing and says so), and the resume sweep again, which starts a home lost
|
|
19
|
+
* while this runs and records what runs for a later sweep. Each is an `oats` child, so this
|
|
20
|
+
* process's loop stays free for the signal. A minute whose tick still runs is skipped; a minute
|
|
21
|
+
* missed is never replayed (the host timer's own rule).
|
|
22
22
|
* - SIGTERM or SIGINT stops it (hostRun): ticking first, then every running home, so that the
|
|
23
23
|
* next start resumes them; then it answers and exits 0.
|
|
24
24
|
* - `plan` says what a run would refuse, the scopes it would tick (the host schedule registry) and
|
|
@@ -99,7 +99,7 @@ function sweepSaid(rows) {
|
|
|
99
99
|
}
|
|
100
100
|
|
|
101
101
|
/** `oats host run`: refuses (above), then runs until SIGTERM or SIGINT →
|
|
102
|
-
* `{ schemaVersion, plan: false, signal, warnings, sweep, ticks, stopped }`: `sweep` the resume
|
|
102
|
+
* `{ schemaVersion, plan: false, signal, warnings, sweep, ticks, stopped }`: `sweep` the first resume
|
|
103
103
|
* sweep's answer, or `{ error: { code, message } }`; `ticks` the minutes counted (`run`,
|
|
104
104
|
* `skipped` while the tick before still ran, `failed`, `noScope` with no scope registered);
|
|
105
105
|
* `stopped` one row per home that ran when it stopped, in the listing's order (stopHome).
|
|
@@ -159,15 +159,23 @@ export async function hostRun({
|
|
|
159
159
|
say(`started (pid ${process.pid}); it holds ${hostRunLockPath()}`);
|
|
160
160
|
for (const warning of warnings) say(`warning: ${warning}`);
|
|
161
161
|
|
|
162
|
-
// The sweep,
|
|
163
|
-
|
|
162
|
+
// The sweep, at the start and then each minute: a home lost while this runs is started again
|
|
163
|
+
// within the sweep's own bounds (lib/session-resume.mjs: its starts per hour, its retries).
|
|
164
|
+
// Each sweep is said when its outcomes differ from those of the sweep before.
|
|
165
|
+
let saidOfSweep;
|
|
166
|
+
const resume = async () => {
|
|
167
|
+
const swept = await execute(["session", "resume", "--json"]);
|
|
168
|
+
const said = swept?.ok === true ? `resume sweep: ${sweepSaid(swept.result?.rows ?? [])}` : `resume sweep failed ${failed(swept)}`;
|
|
169
|
+
if (said !== saidOfSweep) say(saidOfSweep = said);
|
|
170
|
+
return swept;
|
|
171
|
+
};
|
|
172
|
+
const swept = await resume();
|
|
164
173
|
const sweep = swept?.ok === true ? swept.result : { error: { code: swept?.error?.code ?? "E_HOST_RUN_FAILED", message: swept?.error?.message ?? "no answer" } };
|
|
165
|
-
say(swept?.ok === true ? `resume sweep: ${sweepSaid(sweep.rows ?? [])}` : `resume sweep failed ${failed(swept)}`);
|
|
166
174
|
|
|
167
175
|
// The minutes. Each is armed from the clock as it reads then, for second 0 of the next one: a
|
|
168
176
|
// minute missed while this process did not run is never armed again.
|
|
169
177
|
const ticks = { run: 0, skipped: 0, failed: 0, noScope: 0 };
|
|
170
|
-
let ticking = null,
|
|
178
|
+
let ticking = null, sweeping = null, ticked;
|
|
171
179
|
const list = (options) => execute(["session", "resume", "--plan", "--json"], options);
|
|
172
180
|
const arm = () => { disarm = timer(minute, MINUTE - (now() % MINUTE)); };
|
|
173
181
|
const minute = () => {
|
|
@@ -189,13 +197,10 @@ export async function hostRun({
|
|
|
189
197
|
if (answer?.ok !== true) { ticks.failed += 1; say(`tick failed ${failed(answer)}`); }
|
|
190
198
|
});
|
|
191
199
|
}
|
|
192
|
-
// The
|
|
193
|
-
//
|
|
194
|
-
// deployment
|
|
195
|
-
|
|
196
|
-
listing = null;
|
|
197
|
-
if (answer?.ok !== true) say(`listing failed ${failed(answer)}`);
|
|
198
|
-
});
|
|
200
|
+
// The sweep each minute also writes what a later sweep needs: that each running home was
|
|
201
|
+
// seen running (lib/session-seen.mjs recordSeen, by the sweep's own read of every
|
|
202
|
+
// deployment). One that still runs at the next minute is not run beside itself.
|
|
203
|
+
sweeping ??= resume().then(() => { sweeping = null; });
|
|
199
204
|
arm();
|
|
200
205
|
};
|
|
201
206
|
if (!signal) arm();
|
|
@@ -205,7 +210,7 @@ export async function hostRun({
|
|
|
205
210
|
// when it arrived during the initial sweep. No launch may race agent stops.
|
|
206
211
|
say(`${signal}: ticking ended`);
|
|
207
212
|
await draining;
|
|
208
|
-
await Promise.all([ticking,
|
|
213
|
+
await Promise.all([ticking, sweeping]);
|
|
209
214
|
const last = await list({ timeoutMs: 3000 });
|
|
210
215
|
if (last?.ok !== true) say(`listing failed ${failed(last)}: no instance is stopped`);
|
|
211
216
|
const homes = last?.ok === true ? (last.result?.rows ?? []).filter((row) => row.outcome === OUTCOME.ALREADY_RUNNING && typeof row.home === "string").map((row) => row.home) : [];
|
|
@@ -25,7 +25,7 @@ export const OUTCOME = Object.freeze({ RESUMED: "resumed", FRESH: "fresh", ALREA
|
|
|
25
25
|
export const ROW_REASON = Object.freeze({
|
|
26
26
|
UNKNOWN: "unknown", START_BUSY: "start-busy", NOT_LOST: "not-lost", NOT_SEEN_RECENTLY: "not-seen-recently",
|
|
27
27
|
RESUME_CONFIRMATION: RESUME_WAITING.RESUME_CONFIRMATION, LAUNCH_PROMPT: "launch-prompt",
|
|
28
|
-
START_REFUSED: "start-refused",
|
|
28
|
+
START_REFUSED: "start-refused", START_REFUSED_RETRYING: "start-refused-retrying", KEEPS_GETTING_LOST: "keeps-getting-lost",
|
|
29
29
|
LIFECYCLE_BUSY: "lifecycle-busy",
|
|
30
30
|
});
|
|
31
31
|
|