@awebai/oats 0.69.17 → 0.69.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +14 -13
  3. package/docs/capabilities.md +7 -0
  4. package/docs/container.md +172 -18
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
  6. package/docs/desktop-cli-api.md +73 -33
  7. package/docs/desktop.md +40 -18
  8. package/docs/execution-targets.md +36 -33
  9. package/docs/implementation.md +7 -6
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge.md +5 -5
  12. package/docs/official-catalog.md +7 -7
  13. package/docs/packages.md +13 -13
  14. package/docs/release-lane.md +24 -19
  15. package/docs/release-notes/v0.69.18.md +358 -0
  16. package/docs/servers.md +3 -1
  17. package/docs/souls-and-instances.md +18 -16
  18. package/docs/trust-model.md +119 -0
  19. package/docs/upgrading.md +39 -19
  20. package/docs/workspaces.md +3 -3
  21. package/lib/command-flags.mjs +1 -1
  22. package/lib/core.mjs +24 -9
  23. package/lib/errors.mjs +1 -1
  24. package/lib/home-owner.mjs +25 -0
  25. package/lib/host-run-admission.mjs +21 -0
  26. package/lib/host-run-child.mjs +31 -0
  27. package/lib/host-run-work.mjs +150 -0
  28. package/lib/host-run.mjs +20 -11
  29. package/lib/instance-naming.mjs +26 -44
  30. package/lib/packages.mjs +0 -43
  31. package/lib/pi-bridge.mjs +18 -6
  32. package/lib/schedule.mjs +5 -3
  33. package/lib/servers.mjs +4 -3
  34. package/lib/session-end.mjs +9 -0
  35. package/lib/session-resume.mjs +19 -9
  36. package/lib/session-seen.mjs +13 -8
  37. package/lib/triggers.mjs +3 -1
  38. package/lib/worktree.mjs +5 -2
  39. package/package-catalog.json +3 -3
  40. package/package.json +2 -2
  41. package/packages/client/above-tested-notice.mjs +30 -0
  42. package/packages/client/above-tested.mjs +225 -0
  43. package/packages/client/cli-locator.mjs +67 -52
  44. package/packages/client/deployment-label.mjs +4 -4
  45. package/packages/client/instance-name.mjs +5 -29
  46. package/packages/client/session-start.mjs +31 -3
  47. package/packages/client/workspace-choices.mjs +1 -1
  48. package/packages/client/workspace-views.mjs +1 -1
  49. package/packages/record/README.md +10 -8
  50. package/packages/record/lib/process-identity.mjs +14 -36
  51. package/packages/tui/lib/read.mjs +19 -3
  52. package/skills/oats-getting-started/SKILL.md +33 -4
package/README.md CHANGED
@@ -271,7 +271,7 @@ It is optional: agents run, message each other and follow their schedules whethe
271
271
 
272
272
  3. **Answer its questions.** It asks everything in one round and lists the changes it will make to your computer; say yes to them. After that you only approve the GitHub login and type a password or token if one is asked for.
273
273
 
274
- Your agent then installs OATS, OATS Desktop and what they need. It creates a private GitHub repository for your agents' shared setup (the workspace), creates the group your agents message each other in (on [aweb](https://aweb.ai), with no sign-up), and starts the **setup expert**, an agent that adapts the defaults with you. OATS Desktop opens on it. Allow 5 to 10 minutes.
274
+ Your agent then installs OATS and what it needs, and OATS Desktop unless you decline it: the Desktop is optional, and the terminal UI (`oats tui`) or the command line work without it. It creates a private GitHub repository for your agents' shared setup (the workspace), creates the group your agents message each other in (on [aweb](https://aweb.ai), with no sign-up), and starts the **setup expert**, an agent that adapts the defaults with you. OATS Desktop, if you kept it, opens on it. Allow 5 to 10 minutes.
275
275
 
276
276
  **To join a workspace a teammate already runs,** say instead *"Join our OATS workspace at \<its GitHub repository\>, following https://github.com/oats-project/oats"*. Your teammate's agent makes you an invite, which your teammate passes to you privately; your agent tells you when to paste it.
277
277
 
package/bin/oats.mjs CHANGED
@@ -1423,11 +1423,12 @@ async function instanceUpgradeCmd(name, bail) {
1423
1423
  } catch (e) { return lifecycleFail(e, "E_UPGRADE_FAILED", { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) }); }
1424
1424
  }
1425
1425
 
1426
- /** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a spawn
1427
- * of a soul would get by --suggest-name, chosen here for a spawn that may land on another machine
1428
- * (lib/core.mjs suggestSpawnName). Never routed: --server is refused before the route dispatch. */
1426
+ /** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a
1427
+ * --suggest-name spawn would get, chosen here for a spawn that may land on another machine
1428
+ * (lib/core.mjs suggestSpawnName). --soul is optional, shape-checked when given and unused for the
1429
+ * name. Never routed: --server is refused before the route dispatch. */
1429
1430
  async function instanceSuggestNameCmd(bail) {
1430
- const usage = "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]";
1431
+ const usage = "usage: oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]";
1431
1432
  // A flag's value as given, the empty text included (`--task ""` is an empty task, not a missing one).
1432
1433
  const value = (name) => {
1433
1434
  const i = args.indexOf(`--${name}`);
@@ -1437,7 +1438,6 @@ async function instanceSuggestNameCmd(bail) {
1437
1438
  return v;
1438
1439
  };
1439
1440
  const soul = value("soul"), task = value("task"), taskFile = value("task-file");
1440
- if (soul === undefined) return bail("E_BAD_ARGS", `--soul is required; ${usage}`);
1441
1441
  if ((task === undefined) === (taskFile === undefined)) return bail("E_BAD_ARGS", `give the task with one of --task or --task-file; ${usage}`);
1442
1442
  let text = task;
1443
1443
  if (taskFile !== undefined) { try { text = readFileSync(taskFile, "utf8"); } catch (e) { return bail("E_BAD_ARGS", `--task-file ${taskFile} cannot be read (${e.code || "error"})`); } }
@@ -5086,8 +5086,8 @@ Usage:
5086
5086
  includes the decision revision for confirmation
5087
5087
  [--suggest-name] no --name, --purpose or --expect-decision: the
5088
5088
  soul's harness, on the machine that spawns, names
5089
- the instance for its task (<descriptive>-<role>,
5090
- made unique); else it is numbered, and
5089
+ the instance for its task (the model's whole
5090
+ <work>-<role>, made unique); else it is numbered, and
5091
5091
  naming.reason says why (claude and pi); on a
5092
5092
  preview or an apply
5093
5093
  [--expect-decision <rev>] bind apply to the previewed decision; drift refuses
@@ -5249,13 +5249,14 @@ Usage:
5249
5249
  record that this instance does the same work as
5250
5250
  its parent (on needs a recorded parent); clients
5251
5251
  draw the parent line for it; off removes it
5252
- oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi]
5252
+ oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi]
5253
5253
  [--model <m>] [--launch-config <n>] [--dir <d>] [--json]
5254
- a name for a spawn of <soul> (only a name: it gives
5255
- the role) by this machine's harness, as a preview's
5256
- --suggest-name chooses it, not made unique (where it
5257
- lands decides that); else numbered, and naming.reason
5258
- says why. Reads only this machine's launch
5254
+ a name for a spawn by this machine's harness, as a
5255
+ preview's --suggest-name chooses it (the model's whole
5256
+ <work>-<role>), not made unique (where it lands decides
5257
+ that); else numbered, and naming.reason says why.
5258
+ --soul is optional, checked as a soul name's shape and
5259
+ not used for the name. Reads only this machine's launch
5259
5260
  configurations; writes and reserves nothing; no --server
5260
5261
  oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
5261
5262
  [--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
@@ -32,6 +32,13 @@ its skills flat into `<home>/.agents/skills/<skill>/`), and the instance's `AGEN
32
32
  generated without changing the canonical soul. Nothing is installed or
33
33
  activated at a deployment.
34
34
 
35
+ Trust is decided once, where the workspace declares the member or the
36
+ package. When the kernel later reports a capability as trusted, it has
37
+ checked only that what it is about to run is the copy made at spawn and where
38
+ that copy came from. It judges nothing about the code, and the copy is in the
39
+ home its agent can write, so the check is no defence against that agent
40
+ ([trust-model.md](trust-model.md)).
41
+
35
42
  ## Manifest
36
43
 
37
44
  A self-contained package has an `oats.json`:
package/docs/container.md CHANGED
@@ -8,6 +8,26 @@ then runs `oats host run`
8
8
  ([The kernel's periodic work](#the-kernels-periodic-work)). Deployment setup
9
9
  and seat admission belong to the operator.
10
10
 
11
+ ## One team, one trust group
12
+
13
+ The service runs every agent, sshd and `oats host run` as one user, so the
14
+ container is one trust group ([trust-model.md](trust-model.md)):
15
+
16
+ - **It is the unit of compromise.** If one agent in it is subverted, treat
17
+ every agent, seat and credential in it as subverted. Each agent can read
18
+ every seat under `/state/seats`, the Claude token and sshd's host keys,
19
+ rewrite the launch configurations in `/state/deploy` and the schedule
20
+ registry in `/state/home`, rewrite the wake registrations under
21
+ `/state/home/.config/aw/wake`, and stop sshd, `oats host run`, the wake
22
+ broker or its supervisor.
23
+ - **It holds one team, never several.** Agents that must not be able to read
24
+ each other's identities or affect each other's work get separate
25
+ containers. Nothing in OATS makes sharing one safe.
26
+ - **Its Git credentials must not reach the workspace's own code.** A
27
+ workspace member is used at its latest commit, so an agent that can push to
28
+ a member's default branch changes what every deployment of that workspace
29
+ runs ([trust-model.md](trust-model.md#code-from-outside-the-group)).
30
+
11
31
  ## Configuration contract
12
32
 
13
33
  The same inputs apply to a Compose service or a platform's container spec:
@@ -48,7 +68,7 @@ must succeed during the build.
48
68
 
49
69
  `libnss-wrapper` is the extra OS package needed for arbitrary UID support.
50
70
  No credentials or SSH host keys are baked in. The build context allowlist
51
- excludes everything except the image's five inputs.
71
+ excludes everything except the explicitly listed image inputs.
52
72
 
53
73
  A derived image may add reviewed OS tools with `USER root` and `RUN`, then
54
74
  restore `USER agent`. Those build steps use the system passwd/group database.
@@ -184,6 +204,94 @@ Preview runs no provider hook and does not validate a missing seat. Apply
184
204
  only after reviewing it and provisioning its seat; use the same arguments
185
205
  without `--preview`. Keep the team and controller keys outside the container.
186
206
 
207
+ ### Making a seat
208
+
209
+ `identity.source` is the legacy route of `oats.aweb`: the spawn copies an
210
+ existing aweb identity into the new home and connects it. It is the route
211
+ that works in a container today, and it stays labelled legacy until the
212
+ package has a route that admits a seat itself.
213
+
214
+ A seat is the `.aw` directory of one admitted team member. On both routes
215
+ below the seat's signing key is created in the container, over the SSH
216
+ route, so it is on `/state` and never leaves it; the team's controller key
217
+ stays outside. Which route applies depends on who holds that controller key.
218
+
219
+ **A team whose controller key the operator holds** (a self-hosted server, or
220
+ a team the operator brought). The seat asks, the controller admits it, the
221
+ seat fetches its certificate:
222
+
223
+ ```sh
224
+ # 1. In the container, once per seat. Prints the add-member command.
225
+ mkdir -p /state/seats/<alias> && cd /state/seats/<alias>
226
+ aw id team request --create-local-key --team <team>:<domain> --name <alias>
227
+
228
+ # 2. Outside the container, where the team's controller key is: run the
229
+ # printed `aw id team add-member` command. It answers a certificate id.
230
+
231
+ # 3. In the container, in the same directory:
232
+ aw id team fetch-cert --team <team> --namespace <domain> --cert-id <certificate-id>
233
+ aw workspace connect --service <the team's aweb server>
234
+ ```
235
+
236
+ An invite cannot be used here: a token made with the operator's own
237
+ controller key is redeemed only on the machine that holds that key
238
+ (`aw id team accept-invite --help`).
239
+
240
+ **A team hosted by the aweb service.** The service holds the controller key
241
+ and issues an invite token (`aw_inv_…`); the seat redeems it:
242
+
243
+ ```sh
244
+ # In the container, once per seat:
245
+ mkdir -p /state/seats/<alias> && cd /state/seats/<alias>
246
+ aw id team accept-invite <token> --name <alias>
247
+ aw workspace connect --service <the team's aweb server>
248
+ ```
249
+
250
+ The commands are as `aw` 1.36.57 documents them in its own `--help`. The
251
+ sequences have not yet been run in a container.
252
+
253
+ Before it copies anything, the spawn checks three things and refuses the
254
+ seat when one is missing:
255
+
256
+ - `signing.key`, the member's key;
257
+ - the server: `aweb_url` in `workspace.yaml` (`aw workspace connect` writes
258
+ it);
259
+ - the team: the deployment's default team, or else the active team in
260
+ `teams.yaml`.
261
+
262
+ The member's certificate under `team-certs/` is not checked at that point,
263
+ and the seat does not work without it: the spawn copies the seat, fails when
264
+ it connects or reads the identity back, and removes the copy.
265
+
266
+ One seat serves one instance at a time. The spawn writes
267
+ `.aw-retained-seat.json` beside the seat's `.aw` and refuses a second spawn
268
+ while the first instance's home exists; retiring that instance releases the
269
+ seat. Two cases need the operator:
270
+
271
+ - **The holder's home exists and its runtime is known to be dead.** Spawn
272
+ with `identity.takeOver=true`. If that runtime is in fact alive, there are
273
+ then two seats with one key; stop the old one.
274
+ - **The holder's home is gone without a retire** (a home removed by hand, a
275
+ volume restored). Every later spawn is still refused, as "taken by another
276
+ spawn a moment ago", and `identity.takeOver` does not apply. Remove
277
+ `.aw-retained-seat.json` by hand once the home is confirmed gone
278
+ ([awebai/oats-aweb#227](https://github.com/awebai/oats-aweb/issues/227)).
279
+
280
+ Retiring never revokes the member's certificate: on a server that is not the
281
+ hosted service, whoever holds the controller key removes a member
282
+ (`aw id team remove-member`).
283
+
284
+ Known limits of this route, until their fixes are released:
285
+
286
+ - **A restart can lose the seat's identity.** A seat made this way may not
287
+ get `AWEB_IDENTITY_HOME` at a restart
288
+ ([awebai/oats-aweb#226](https://github.com/awebai/oats-aweb/issues/226)).
289
+ Check `aw whoami` in the home after a restart; if it is not the seat, retire
290
+ the instance and spawn it again.
291
+ - **Do not interrupt a seat's spawn.** A spawn killed after it connected can
292
+ delete the standing identity's workspace at the server
293
+ ([awebai/oats-aweb#228](https://github.com/awebai/oats-aweb/issues/228)).
294
+
187
295
  The pinned OATS release supports this file-backed launch configuration:
188
296
 
189
297
  ```yaml
@@ -201,11 +309,50 @@ Select it with `--launch-config team-claude`. The operator provisions only a
201
309
  by every agent in the same trust group; read-only mounting does not hide it
202
310
  or narrow its authority. Never share the mount across trust groups.
203
311
 
312
+ ### After changing a credential
313
+
314
+ A resume starts an agent under the values its last start recorded. When the
315
+ value behind a reference has changed, such as a new token in
316
+ `/etc/agent-login/claude-token`, every resume of that home is refused with
317
+ `E_LAUNCH_ENV_CHANGED`, by the sweep and by hand
318
+ ([execution-targets.md](execution-targets.md#resume-after-a-shutdown)). The
319
+ agents do not come back when the container restarts, and host run's log
320
+ shows them as `refused`.
321
+
322
+ So after replacing a referenced credential, start each agent once yourself.
323
+ An ordinary start does not compare; it uses the new value and records it:
324
+
325
+ ```sh
326
+ # In the container:
327
+ oats session restart --home <abs> # an agent that runs
328
+ oats session start --home <abs> # one that is stopped
329
+ ```
330
+
331
+ An ordinary start begins a new conversation; it does not resume the earlier
332
+ one.
333
+
334
+ ### Where conversations are stored
335
+
336
+ With `CLAUDE_CONFIG_DIR: /state/home/.claude`, Claude Code writes each
337
+ session's transcript under that directory. It holds what the agents read and
338
+ wrote, tool output included: mail they opened, and the results of calls made
339
+ on their behalf.
340
+
341
+ - It is one directory for every agent of the container, and every agent can
342
+ read it ([One team, one trust group](#one-team-one-trust-group)).
343
+ - It is on `/state`, so it outlives the container and is in any copy of the
344
+ volume.
345
+ - OATS neither trims nor deletes it. Retiring an instance removes its home,
346
+ not its transcripts. The operator decides how long they are kept and
347
+ removes them.
348
+
204
349
  ## The kernel's periodic work
205
350
 
206
351
  A container has no launchd and no systemd user manager, so no timer runs
207
- the kernel's periodic work in it. The image's entrypoint does: it starts
208
- sshd in the background and then runs `oats host run`
352
+ the kernel's periodic work in it. After the entrypoint prepares NSS and
353
+ SSH host keys, an image-local Node supervisor starts `aw wake run`. It waits
354
+ for `aw wake status --json` to report `daemon_running: true` and name that
355
+ live child's PID as `daemon_pid`, then starts sshd and `oats host run`
209
356
  ([desktop-cli-api.md](desktop-cli-api.md#the-host-run-oats-host-run)), one
210
357
  foreground process that lasts as long as the container.
211
358
 
@@ -216,31 +363,36 @@ foreground process that lasts as long as the container.
216
363
  deployments the container's host schedule registry lists and lists the
217
364
  instances. With no deployment registered it ticks nothing and says so.
218
365
  - **On the runtime's SIGTERM** (`docker stop`, `docker restart`, a Compose
219
- `down` or a recreate) it starts no further minute, waits for a tick that
220
- is running, and stops every running agent side by side: SIGTERM to the
366
+ `down` or a recreate) it starts no further minute. Active launch work gets
367
+ 10 seconds to finish naturally; then a private admission fence prevents
368
+ further schedule, trigger, wake or resume launches and owned children get
369
+ a 5-second cancellation phase. An interrupted launch stays `unknown` and
370
+ needs reconciliation; a timeout does not prove that nothing ran. Host run
371
+ then lists and stops every running agent side by side: SIGTERM to the
221
372
  harness and a wait of 20 seconds, never escalated. Each home's stop record
222
373
  says it was stopped with the host, so the home reads `lost` and the next
223
- start's sweep resumes it. Then it exits 0 and the container ends.
374
+ start's sweep resumes it. Then it exits 0 and the supervisor stops the
375
+ broker. Work that cannot be killed retains the host-run claim; the runtime's
376
+ final kill is a failed stop, never proof of an ordered shutdown.
224
377
  - **Its progress** is one line per event on standard error, beside sshd's
225
378
  log, in `docker logs`.
226
379
 
227
380
  What the image's files fix for that:
228
381
 
229
- - **`oats host run` is tini's direct child**, the process the runtime's
230
- signal reaches and the container waits for: the entrypoint's last line is
231
- `exec oats host run`, after sshd is started in the background. `tini -g`
232
- signals its child's process group; the OATS tmux server and the harnesses
233
- under it are in sessions of their own, outside that group, so they run
234
- until `oats host run` stops them. Measured in `oats-agent:o1-local` with
235
- tini 0.19.0 and tmux 3.3a: on `docker stop` both members of the group
236
- received the TERM, and two seconds later the tmux server and its pane were
237
- alive and the pane had received nothing.
382
+ - **PID-only tini signals the Node supervisor.** It forwards TERM to host
383
+ run alone and keeps the wake broker alive until host run finishes stopping
384
+ the agents. Then it stops sshd and the broker in parallel. A broker or
385
+ host-run exit is reported and drains the other children before a nonzero
386
+ container exit, so
387
+ the restart policy can restart it. The broker runs as the agent uid; its
388
+ default state directory is `/state/home/.config/aw/wake`, so registrations
389
+ survive container replacement and it starts again even with no spawn.
238
390
  - **`stop_grace_period: 45s`** in the Compose service. Docker's default is
239
391
  10 seconds, shorter than the 20 seconds each harness is given; a container
240
392
  killed at the timeout leaves agents that were not stopped in order. A
241
393
  platform that does not read the Compose file needs the same stop timeout
242
394
  in its container spec.
243
- - **A healthcheck on sshd.** `oats host run` does not supervise sshd: if
395
+ - **A healthcheck on sshd.** The supervisor reports an sshd exit; if
244
396
  sshd ends, the agents and the tick go on and the operator's route is gone.
245
397
  The service's healthcheck opens `127.0.0.1:2222` every 30 seconds (5
246
398
  second timeout, 3 retries, 10 second start period), so the container then
@@ -258,8 +410,10 @@ What the image's files fix for that:
258
410
 
259
411
  `oats host run` refuses to start while another one holds the container's
260
412
  lock (`E_HOST_RUN_BUSY`); the container then exits 1 and the restart policy
261
- starts it again. A lock left by an earlier run of the container is taken
262
- over.
413
+ starts it again. A lock left by an earlier run is taken over when its pid
414
+ is gone or has another process start time. A visible live holder, or a
415
+ holder whose start cannot be read, stays held; see
416
+ [Session recovery](execution-targets.md#which-losses-come-back).
263
417
 
264
418
  The schedule tick covers only registered deployments. Register the
265
419
  deployment once, after `server connect`
@@ -305,8 +305,14 @@ Each entry's manifests, souls and integrity are read at the observed commit →
305
305
  ### 4.3 Trust and removed APIs
306
306
 
307
307
  There is no approval step or record: declaring a package in `packages:` is the trust decision, and the
308
- lock pins commit and integrity. `oats sync --approve` is `E_BAD_ARGS`. Pre-workspace exports remain as
309
- shims that throw `E_REMOVED { name, contract }`, pointing at this record.
308
+ lock pins commit and integrity. `oats sync --approve` is `E_BAD_ARGS`.
309
+
310
+ Pre-workspace package-install, requirement, OAS-migration and config-merge APIs are not
311
+ exported from `lib/packages.mjs`. Named imports fail at module loading; namespace imports do not
312
+ contain those names. Use workspace `packages:`
313
+ plus `oats sync`; capability requirements and configuration belong to their provider, not the
314
+ removed package-install/config-merge APIs. The live `lockedPackageCapabilities` in `lib/resolve.mjs`
315
+ and `packageSpecIdentity` in `lib/core.mjs` are separate APIs and remain available.
310
316
 
311
317
  ---
312
318
 
@@ -52,10 +52,20 @@ see the [official catalog](official-catalog.md) for current pins.
52
52
  "capabilityShowApi":1,"sessionViewer":{"prefixScroll":true},"package":"@awebai/oats"}
53
53
  ```
54
54
 
55
- - The Desktop accepts `desktopApi === 1` and a released `version` inside
56
- `ACCEPT_RANGE` (`packages/client/cli-locator.mjs`); a prerelease is never
57
- accepted. The real gate is the feature list; its minimum is
58
- `packages-no-approval`.
55
+ - The Desktop accepts `desktopApi === 1` and a released `version` at or
56
+ above `ACCEPT_RANGE`'s floor (`packages/client/cli-locator.mjs`); a
57
+ prerelease is never accepted. The real gate is the feature list; its
58
+ minimum is `packages-no-approval`.
59
+ - A version above the Desktop's tested bound, the minor of its own release
60
+ (`testedBound`), is accepted with `aboveTested: true` and `testedThrough`
61
+ (`X.Y`): the Desktop then runs only its reads, terminals, the Spawn preview
62
+ and apply, Start, Restart, the colour and the background, refuses every
63
+ other operation before running the CLI (`cli-above-tested`), and says so in
64
+ one line until the Desktop of that version is installed. A Desktop of
65
+ 0.69.17 or older refuses such a CLI. `oats tui` judges the kernel it ships
66
+ with against that kernel's own version, so never finds it above. A
67
+ `desktopApi` other than 1 is refused (`newerApi` on the candidate when it is
68
+ a higher one).
59
69
  - `harnesses` is what `--harness` accepts; `sessionBackends` what `--backend`
60
70
  accepts: `["tmux"]` since 0.31.0, when Herdr was removed (`--backend herdr`
61
71
  is refused with `E_HERDR_REMOVED`). A host without the `harness` feature
@@ -160,7 +170,7 @@ see the [official catalog](official-catalog.md) for current pins.
160
170
  | `instance-same-work` | `oats instance same-work <instance> on\|off` and `oats spawn … --same-work`, local and `--server` ([Same work as the parent](#same-work-as-the-parent-oats-instance-same-work)); `sameWork: true` on `oats status --json` instance rows and on `oats server roster --json` rows while the instance's flag is bound to its current `parentInstance`, the key absent otherwise ([`sameWork`](#row-same-work)). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows never carry `sameWork`, and it refuses the flag and the verb (`E_BAD_ARGS`) | |
161
171
  | `deployments-list` | `oats deployments [list]\|add\|remove\|import --json`, this computer's list of its deployments (`~/.oats/config/deployments.json`); `listed` on `oats onboard --json`; a kernel command run in an unlisted deployment lists it ([This computer's deployments](#this-computers-deployments-oats-deployments)). Gate on the probe: there is no fallback scan | `deploymentsApi: 1` |
162
172
  | `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
163
- | `instance-suggest-name` | `oats instance suggest-name --soul <soul> (--task <t> \| --task-file <f>) [--harness claude\|pi] [--model <m>] [--launch-config <n>] --json`: the name a `--suggest-name` spawn of `<soul>` would get, chosen on this machine for a spawn that may land on another, not made unique ([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)). Local only: `--server` is `E_BAD_ARGS`. Gate on the local probe; without it, the spawn goes unnamed (numbered, or named where it lands) | |
173
+ | `instance-suggest-name` | `oats instance suggest-name [--soul <soul>] (--task <t> \| --task-file <f>) [--harness claude\|pi] [--model <m>] [--launch-config <n>] --json`: the name a `--suggest-name` spawn would get, chosen on this machine for a spawn that may land on another, not made unique ([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)). Local only: `--server` is `E_BAD_ARGS`. Gate on the local probe; without it, the spawn goes unnamed (numbered, or named where it lands) | |
164
174
  | `spawn-apply-suggest-name` | `--suggest-name` on a spawn apply, without `--preview`: the apply names the instance as a preview's `--suggest-name` would, on the machine that spawns, and its result carries `naming` ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)). Routed, the host needs the feature (`E_REMOTE_INCOMPATIBLE`, nothing sent): gate on the host's `probe.features` and don't send the flag to a host without it | |
165
175
  | `instance-background` | background instances (awebai/oats#1579): `soul.yaml` `background:`; `oats spawn … --background\|--no-background`, whose preview and result carry `background` and `backgroundFrom`; `oats instance background <instance> on\|off`, local and `--server`; `background: true` on `oats status --json` instance rows, `oats server roster --json` rows, `oats inspect --home` `instance` and `oats souls --json` soul rows, absent otherwise ([Background instances](#background-instances-oats-instance-background)). Gate on the probe, locally or in the host's `probe.features`: an older kernel refuses the flags and the verb, and its rows have no `background`. A routed spawn with either flag needs the host's feature (`E_REMOTE_INCOMPATIBLE`, nothing sent) | `instanceBackgroundApi: 1` (payload only) |
166
176
  | `session-resume` | sessions come back after a shutdown, OATS 0.69 (#1559): `sessionEnd` on `oats status --json` instance rows ([`sessionEnd`](#row-session-end)); `oats session start --resume --home <abs>` and its `resume` answer ([Resume a lost session](#resume-a-lost-session---resume)); the machine sweep `oats session resume [--deployment <dir>] [--plan] --json` ([`oats session resume`](#the-machine-sweep-oats-session-resume)); `E_RESUME_BUSY`, `E_RESUME_NOT_LOST`. Local only: `--server` is `E_BAD_ARGS`. Gate a client's resume-on-open on the probe: a kernel without it has no `session resume` | |
@@ -2816,7 +2826,7 @@ or `--task <text>`). Like every preview it writes nothing and runs no hooks.
2816
2826
  configuration's `env`, not its `args`), with this prompt on stdin, never in
2817
2827
  argv:
2818
2828
 
2819
- > Name an agent for this task: 2–4 lowercase words joined by hyphens, describing the work, not the role. Reply with the name only.
2829
+ > Name an agent for this task: <work>-<role>, at most five lowercase words joined by hyphens. First a few words for the work, then, last, one word for the agent's role as the task gives it; if the task gives no role, one word for what the agent does in it. Reply with the name only.
2820
2830
  >
2821
2831
  > Task:
2822
2832
  > <the task text, at most 4000 characters>
@@ -2857,15 +2867,23 @@ or `--task <text>`). Like every preview it writes nothing and runs no hooks.
2857
2867
  --no-context-files --no-approve [--model <m>]`.
2858
2868
  - **codex** is not supported. Its naming call is not proven to start
2859
2869
  nothing, so a codex soul is numbered with `unsupported-harness`.
2860
- - **The name.**
2861
- 1. The reply's first non-empty line, as a slug.
2862
- 2. Without one or more trailing `-<role>`. The role is the last word of the
2863
- soul's name, after any package qualifier.
2864
- 3. At most 4 words, cut at a word boundary to fit
2865
- `64 − 1 − len(role)`.
2866
- 4. Nothing left, or only the role, is `invalid-reply`.
2867
- 5. The name is `<descriptive>-<role>`. A name that is taken (an instance,
2868
- a soul or a live window, as for `--name`) gets `-2`, `-3`, and so on.
2870
+ - **The name** is the model's whole `<work>-<role>`. Nothing appends a
2871
+ role, and nothing reads the soul's name for it.
2872
+ 1. The reply's first non-empty line, as a slug. Its last word is the role,
2873
+ and is always kept.
2874
+ 2. Fewer than two words is `invalid-reply`: one word names no work and
2875
+ role.
2876
+ 3. Over 5 words, the descriptive words nearest the role are dropped
2877
+ (`a-b-c-d-e-lead` → `a-b-c-d-lead`).
2878
+ 4. Over 64 characters, counting any `-<n>` below, the same: descriptive
2879
+ words nearest the role are dropped, and the first word's characters
2880
+ are cut only when it is the one descriptive word left. A role that
2881
+ leaves no room for one character of a first word is `invalid-reply`.
2882
+ 5. A name that is taken (an instance, a soul or a live window, as for
2883
+ `--name`) gets `-2`, `-3`, and so on, at the end.
2884
+
2885
+ A reply that is prose, or a tool-call block, is named by whatever its
2886
+ first non-empty line slugs to: the rules above are the only guard.
2869
2887
  - **The answer** is the full preview, plus `naming`:
2870
2888
 
2871
2889
  ```json
@@ -2906,8 +2924,8 @@ oats spawn <soul> --suggest-name --task-file <f> [the flags of a real spawn] [--
2906
2924
  An apply with `--suggest-name` and no `--name`, `--purpose` or
2907
2925
  `--expect-decision` names the instance on the machine that spawns, by the
2908
2926
  preview's call and rules above, through the soul's harness.
2909
- - The name is `<descriptive>-<role>`, made unique as a preview's is, and it is
2910
- placed exactly as `--name <name>` would be.
2927
+ - The name is the reply's whole name, by the preview's rules, made unique as
2928
+ a preview's is, and it is placed exactly as `--name <name>` would be.
2911
2929
  - On any failure the instance is numbered as it is today, and `naming` says
2912
2930
  why. A failed call is never an error: the spawn goes on.
2913
2931
  - The call is made before anything is placed, after the executable is
@@ -3129,7 +3147,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
3129
3147
  `E_REMOTE_INCOMPATIBLE` otherwise, with nothing sent. A saved route here
3130
3148
  under that name is `E_ROUTE_EXISTS`, before the spawn is sent.
3131
3149
  - `--preview --suggest-name` (feature `spawn-suggest-name`) chooses a
3132
- descriptive name for the task, `<descriptive>-<role>`, which the apply then
3150
+ name for the task, the model's whole `<work>-<role>`, which the apply then
3133
3151
  passes as `--name` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)).
3134
3152
  An apply with `--suggest-name` (feature `spawn-apply-suggest-name`) chooses
3135
3153
  it itself ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)).
@@ -3142,10 +3160,10 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
3142
3160
  Feature `instance-suggest-name`.
3143
3161
 
3144
3162
  ```text
3145
- oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] --json
3163
+ oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] --json
3146
3164
  ```
3147
3165
 
3148
- The name a spawn of `<soul>` would get by `--suggest-name`, chosen on the
3166
+ The name a spawn would get by `--suggest-name`, chosen on the
3149
3167
  machine that asks (a Desktop's, with the spawn dialog open) for a spawn that
3150
3168
  may land on another.
3151
3169
 
@@ -3155,11 +3173,12 @@ may land on another.
3155
3173
  directory) and the OATS tmux server's environment, as a spawn's pane would
3156
3174
  have it; it resolves no souls, members, lock or remote. The deployment it
3157
3175
  reads is not added to this computer's deployments list.
3158
- - **The soul is only a name.** It gives the role (the last word of the name,
3159
- after any package qualifier) and needn't exist on this machine. It is
3160
- checked as a soul name's shape (`<soul>`, `<package>/<soul>`,
3161
- `<package>--<soul>`), never resolved.
3162
- - **Not made unique.** The words, role and length rules are the preview's
3176
+ - **`--soul` is optional, and not used for the name.** Installed Desktops
3177
+ send it, so when given it is still checked as a soul name's shape
3178
+ (`<soul>`, `<package>/<soul>`, `<package>--<soul>`, else `E_BAD_ARGS`),
3179
+ never resolved, and needn't exist on this machine. Two souls with the same
3180
+ reply get the same name.
3181
+ - **Not made unique.** The word and length rules are the preview's
3163
3182
  ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)), but no
3164
3183
  `-2` is added: the machine the spawn lands on owns uniqueness, and a name
3165
3184
  taken there is its `E_INSTANCE_NAME_TAKEN` at the apply.
@@ -3197,8 +3216,8 @@ may land on another.
3197
3216
  - A naming failure is not an error: `ok: true` with
3198
3217
  `naming.source: "numbered"`.
3199
3218
  - The text answer is the name, or `numbered (<reason>: <message>)`.
3200
- - **Refusals** (`E_BAD_ARGS` unless named): no `--soul`, or one that is not
3201
- a soul name's shape; neither or both of `--task` and `--task-file`, or one
3219
+ - **Refusals** (`E_BAD_ARGS` unless named): a `--soul` that is not a soul
3220
+ name's shape; neither or both of `--task` and `--task-file`, or one
3202
3221
  that cannot be read; a `--harness` other than pi, claude or codex; a
3203
3222
  `--harness` that is not the named configuration's; a flag or argument it
3204
3223
  does not take; `--server`. An unknown `--launch-config` is
@@ -3504,8 +3523,8 @@ A failed `add` reports the same facts about its rollback in `details`:
3504
3523
  | `E_INSTANCE_RETIRING` | `add` in a quarantined home; in one for which a self-retire is scheduled; or in one whose retire is running (OATS 0.52.0: `add` reads the home's claim and takes nothing; `<instance> is being retired (pid <pid>, since <at>); no tree was made — if it does not end, check that pid by hand, and if it is not an oats retire, remove <lock>, then retry`, `details: {instance, home, lock, pid, since, action: "retire"}`; [Commands that meet on one home](#lifecycle-pairs)) |
3505
3524
  | `E_CLONE_MISSING` | the repository is not found, or is not a Git repository |
3506
3525
  | `E_CLONE_MISMATCH` | the path is a linked worktree, or the clone has no `origin` |
3507
- | `E_BRANCH_EXISTS` | the branch exists in the clone (before the tree is made, or made by another `add` at the same moment); `details.remedy` is `<instance>/<branch>` |
3508
- | `E_GIT_FAILED` | a Git step failed on its own (`git worktree add`, or `git switch` while the branch does not exist), with Git's message: `git <sub> failed in <dir>: …`; or a checkout was not run because the repository's configuration defines a filter driver whose name cannot be overridden ([a checkout runs no filter driver](souls-and-instances.md#checkout-filter-drivers)); the tree is removed |
3526
+ | `E_BRANCH_EXISTS` | the branch exists in the clone: before the tree is made, or made by another `add` or another git at the same moment, between that check and this add's `git switch -c` (the tree is removed, and that branch kept). Either way `details` carries `branch`, `clone` and `remedy`, which is `<instance>/<branch>`. A racing `add` can end in this code or in `E_GIT_FAILED` (next row) |
3527
+ | `E_GIT_FAILED` | a Git step failed on its own (`git worktree add`, or `git switch` while the branch does not exist), with Git's message: `git <sub> failed in <dir>: …`; or a checkout was not run because the repository's configuration defines a filter driver whose name cannot be overridden ([a checkout runs no filter driver](souls-and-instances.md#checkout-filter-drivers)); the tree is removed. A `git switch` that meets the branch's ref lock while another git holds it (`cannot lock ref …`), as a racing `add` can, is this code: the branch does not exist yet, and a lock left by a git that crashed looks the same. A caller that retries once the other git has made the branch gets `E_BRANCH_EXISTS` from the check before the tree is made, with its remedy |
3509
3528
  | `E_PLACEMENT_TAKEN` | a `ready` record with another clone, branch or base (`details.differ`); `.work-<p>` with no record, or a file or symbolic link there; an unreadable record |
3510
3529
  | `E_LIFECYCLE_BUSY` | an add of that purpose is still running (pid and start time verified); another add or remove of that purpose holds its claim (`details.lock`); a file at the claim's path is no claim this kernel can read or take over (`details.lock`); the claim was taken again, the last time by a process that is gone, each of the five times the command found it without a live holder (`run the command again`); an interrupted add's rollback could not be completed (`details.owed`; the message says what to deal with and to run `oats worktree remove --purpose <purpose>`, which finishes the rollback); or, `add` only (OATS 0.52.0), the home's claim is held by a retire whose liveness cannot be read, or is a file that is no readable claim (`no tree was made`; [Commands that meet on one home](#lifecycle-pairs)). Every one carries [`details.holder`](#busy-holder) |
3511
3530
  | `E_REMOTE_UNREADABLE` | the fetch of `<base>` from `origin` failed; the tree is removed |
@@ -5648,6 +5667,7 @@ had begun.
5648
5667
  | `E_INSTANCE_RETIRING` | yes | yes |
5649
5668
  | `E_LIFECYCLE_BUSY` | yes | yes |
5650
5669
  | `E_HOME_MISMATCH` | yes | yes |
5670
+ | `E_HOME_NOT_OWNED` | yes | yes |
5651
5671
  | `E_SESSION_UNKNOWN` | yes | yes |
5652
5672
  | `E_AMBIGUOUS_INSTANCE` | yes | yes |
5653
5673
  | `E_UNIDENTIFIED_INSTANCE_HOME` | yes | yes |
@@ -5655,6 +5675,15 @@ had begun.
5655
5675
  | `E_AMBIGUOUS` | yes | yes |
5656
5676
  | `E_SNAPSHOT_UNKNOWN` | yes | yes |
5657
5677
 
5678
+ `E_HOME_NOT_OWNED` is the answer of every command that takes a home's
5679
+ lifecycle claim (a start, a resume, a stop, a retire, an upgrade) when the
5680
+ user it runs as does not own the home. It is answered before the claim is
5681
+ written, root is refused like any other user, and `details` carries
5682
+ `instance`, `home`, `owner` and `user` (the two uids). The fix is to run the
5683
+ same command as the home's owner, with that user's `HOME`
5684
+ (`sudo -H -u '#<owner>' oats …`): OATS keeps its own state under it
5685
+ ([trust model](trust-model.md#the-line), rule 3).
5686
+
5658
5687
  The last three are the router's (`--server`): they are answered before the
5659
5688
  command is sent to the host. The list is about the envelope's `error.code`.
5660
5689
  A row of a result (a stop receipt's `results[].code`, a retire's
@@ -7182,7 +7211,12 @@ whatever the rows say:
7182
7211
  the per-boot note (refusals, and each home's count of sweep starts that
7183
7212
  launched something: `resumed`, `fresh`, `blocked`) are kernel-private,
7184
7213
  not a contract. Without a boot id (neither Linux nor macOS) nothing is
7185
- noted or counted.
7214
+ noted or counted. A validated current-start host-stop receipt excludes
7215
+ downtime from the in-boot eligibility gap and exempts a successful restore
7216
+ from the crash ceiling and count; it preserves prior failure counts and
7217
+ refusals. Blocked restores still count. See
7218
+ [Which losses come back](execution-targets.md#which-losses-come-back)
7219
+ for receipt validation and the independent loss-age and judgement guards.
7186
7220
  - **A lock that needs a person.** `E_RESUME_LOCK_STUCK`, through the same
7187
7221
  envelope at exit 1, when the sweep's lock cannot be taken and no sweep is
7188
7222
  known to run; nothing was started, and no sweep starts anything on this
@@ -7230,8 +7264,10 @@ this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
7230
7264
  (`<OATS_HOME_DIR>/host-run/lock`, a kernel-private file), or the lock
7231
7265
  cannot be judged; `error.details` `{lock, found}`, `found` as
7232
7266
  `E_RESUME_LOCK_STUCK` names it, and `running` for a host run that runs.
7233
- A lock whose holder is gone, or that was taken in another boot (in a
7234
- container, another run), is taken over;
7267
+ A lock whose holder is gone, or that was taken in another kernel boot,
7268
+ is taken over. A container restart on the same kernel is judged by the
7269
+ holder's pid and process start; old qualified Linux boot IDs compare
7270
+ as their kernel UUID, so an upgrade cannot reclaim a live holder;
7235
7271
  - `E_BAD_ARGS`: a flag it does not define, an argument, a `--stop-grace`
7236
7272
  that is not 1 to 300 seconds, a verb other than `run`.
7237
7273
 
@@ -7246,7 +7282,11 @@ this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
7246
7282
  child process. A minute whose tick still runs is skipped; a minute missed
7247
7283
  is never replayed. With no scope registered it ticks nothing and says so.
7248
7284
  - **On SIGTERM or SIGINT.** No further minute starts; a tick or a sweep that
7249
- runs is waited for; it lists once; then it stops every running home, side
7285
+ runs gets 10 seconds to finish naturally, then a private admission fence
7286
+ stops further launches and owned child groups get a further 5-second
7287
+ cancellation phase. Interrupted attempts keep their unknown/reconcile
7288
+ accounting. It performs a final listing with a 3-second read budget; then
7289
+ it stops every running home, side
7250
7290
  by side, each with the stop `oats session restart` uses: SIGTERM to the
7251
7291
  harness, a wait of `--stop-grace` seconds (default 20), never escalated.
7252
7292
  Each home's stop record is written before its harness is signalled and