@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.
@@ -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)). Every other
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 the three
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 the three workflow
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 `tui-macos.yml`;
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 altair-aweb --ssh altair --dir '~/acme' --install-oats
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 altair-aweb < invite.txt
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` and `checkout` mode, the
1845
- instance's [extra trees](#extra-trees) in the home serve the same purpose.
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; **never edit or commit inside them** —
2052
- route changes to the owning repo's agents or the human.
2053
- - No git state operations in any member repo.
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 `checkout` mode can create extra trees: linked
2062
- Git worktrees in its home, beside `work/`. It does so when the work needs
2063
- another branch, or another repository of the deployment (one task that
2064
- touches several repositories). The `worktree` and `checkout` briefings teach
2065
- it; the `workspace`, `directory` and `attached` briefings do not.
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 name order, by each group's top
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 in name order, as the Desktop lists
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
- lfx │ state running
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: `lfx` is one row however many machines hold it, and a machine the
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 (lfx, with `~/Work/lfx` on this computer's list)
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 │ lfx
1071
+ Souls 2 │ lab
1072
1072
  Capabilities 3 │ This machine · not opened
1073
- ────────────────────────────────────────────────│ athenea (lfx)
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.18** ([release notes](release-notes/v0.69.18.md)).
10
- The 0.69.18 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
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.18,** in the [release notes](release-notes/): it says what to do before
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.18, in either order
24
- npm install -g @awebai/oats@0.69.18 # 1. the CLI
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
@@ -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.0 # bare version → resolves through the official catalog
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`. **Never initialize a fake repository**; a containing
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. You route,
4
- analyse and coordinate; you do not change code.
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; never edit or commit inside them,
7
- and NEVER change their Git state** (no branch switches, resets, pulls,
8
- stashes or worktrees). Route a repository change to that repository's agents
9
- or to your human.
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 coordinate, you do not edit member repos (see your work-mode briefing)`
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 at start or the schedule tick each minute, and
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 once (`oats session resume`); then, at second 0 of
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 a listing of every deployment's instances, which
19
- * records what runs for the next start's sweep. Each is an `oats` child, so this process's
20
- * loop stays free for the signal. A minute whose tick still runs is skipped; a minute missed is
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, once: a home lost while this runs is a crash, and the sweep's bound is per boot.
163
- const swept = await execute(["session", "resume", "--json"]);
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, listing = null, ticked;
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 listing each minute writes what the sweep of the next start needs: that each running
193
- // home was seen running (lib/session-seen.mjs recordSeen, by the sweep's own read of every
194
- // deployment, which its plan does and nothing else).
195
- listing ??= list().then((answer) => {
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, listing]);
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", REFUSED_THIS_BOOT: "refused-this-boot", KEEPS_GETTING_LOST: "keeps-getting-lost",
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