@awebai/oats 0.69.17 → 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.
Files changed (61) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +14 -13
  3. package/docs/capabilities.md +8 -1
  4. package/docs/container.md +345 -18
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
  6. package/docs/design/2026-09-27-team-model-v2.md +2 -2
  7. package/docs/design/2026-09-28-automations-trust.md +1 -1
  8. package/docs/desktop-cli-api.md +100 -53
  9. package/docs/desktop.md +53 -24
  10. package/docs/execution-targets.md +66 -48
  11. package/docs/implementation.md +8 -7
  12. package/docs/integrations.md +2 -2
  13. package/docs/knowledge.md +5 -5
  14. package/docs/official-catalog.md +7 -7
  15. package/docs/packages.md +13 -13
  16. package/docs/release-lane.md +30 -23
  17. package/docs/release-notes/v0.69.18.md +358 -0
  18. package/docs/release-notes/v0.69.19.md +172 -0
  19. package/docs/servers.md +5 -3
  20. package/docs/souls-and-instances.md +51 -27
  21. package/docs/trust-model.md +119 -0
  22. package/docs/tui.md +8 -8
  23. package/docs/upgrading.md +45 -19
  24. package/docs/workspaces.md +3 -3
  25. package/injects/work-directory.md +27 -2
  26. package/injects/work-workspace.md +32 -6
  27. package/lib/command-flags.mjs +1 -1
  28. package/lib/core.mjs +26 -11
  29. package/lib/errors.mjs +1 -1
  30. package/lib/home-owner.mjs +25 -0
  31. package/lib/host-run-admission.mjs +21 -0
  32. package/lib/host-run-child.mjs +31 -0
  33. package/lib/host-run-work.mjs +150 -0
  34. package/lib/host-run.mjs +43 -29
  35. package/lib/instance-naming.mjs +26 -44
  36. package/lib/packages.mjs +0 -43
  37. package/lib/pi-bridge.mjs +18 -6
  38. package/lib/schedule.mjs +5 -3
  39. package/lib/servers.mjs +4 -3
  40. package/lib/session-end.mjs +9 -0
  41. package/lib/session-resume-contract.mjs +1 -1
  42. package/lib/session-resume.mjs +144 -51
  43. package/lib/session-seen.mjs +16 -11
  44. package/lib/triggers.mjs +3 -1
  45. package/lib/worktree.mjs +5 -2
  46. package/package-catalog.json +3 -3
  47. package/package.json +4 -2
  48. package/packages/client/above-tested-notice.mjs +30 -0
  49. package/packages/client/above-tested.mjs +225 -0
  50. package/packages/client/cli-locator.mjs +67 -52
  51. package/packages/client/deployment-label.mjs +4 -4
  52. package/packages/client/instance-name.mjs +5 -29
  53. package/packages/client/instance-presentation.mjs +2 -2
  54. package/packages/client/instance-tree.mjs +18 -7
  55. package/packages/client/session-start.mjs +31 -3
  56. package/packages/client/workspace-choices.mjs +1 -1
  57. package/packages/client/workspace-views.mjs +1 -1
  58. package/packages/record/README.md +10 -8
  59. package/packages/record/lib/process-identity.mjs +14 -36
  60. package/packages/tui/lib/read.mjs +19 -3
  61. package/skills/oats-getting-started/SKILL.md +33 -4
@@ -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` | |
@@ -2156,7 +2166,7 @@ The messaging provider's `teams` operation (`messaging:teams`) is produced by
2156
2166
  the provider (oats.aweb 1.17 or later), not the kernel:
2157
2167
 
2158
2168
  ```json
2159
- {"defaultTeam":{"label":"antares","team":"antares:ana.aweb.ai","from":"deployment"},
2169
+ {"defaultTeam":{"label":"builder","team":"builder:ana.aweb.ai","from":"deployment"},
2160
2170
  "eligible":[{"label":"oats","team":"oats:oats.aweb.ai","joined":true}],
2161
2171
  "joined":[{"label":"oats","team":"oats:oats.aweb.ai","identityHome":"/w/agents/oe/instances/oe-1/.aw-teams/oats","receive":"live","since":"2026-09-28T09:00:00.000Z"}],
2162
2172
  "left":[{"label":"reviewers","team":"reviewers:acme.aweb.ai","at":"2026-09-28T09:30:00.000Z","reason":"no-longer-eligible"}],
@@ -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 |
@@ -4158,9 +4177,9 @@ whose key is not known; an unparsable ref is `E_REPO_REF`.
4158
4177
 
4159
4178
  ```json
4160
4179
  {"file":"/Users/me/.oats/servers.json",
4161
- "servers":[{"id":"altair-aweb","sshHost":"altair","operatorSshHost":"altair-operator","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"altair",
4162
- "workspaceKey":"github.com/awebai/ac",
4163
- "target":{"sshHost":"altair","workspace":"/Users/me/acme","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
4180
+ "servers":[{"id":"devbox-aweb","sshHost":"devbox","operatorSshHost":"devbox-operator","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"devbox",
4181
+ "workspaceKey":"github.com/example/app",
4182
+ "target":{"sshHost":"devbox","workspace":"/Users/me/acme","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
4164
4183
  "unknownWorkspace":["build"]}
4165
4184
  ```
4166
4185
 
@@ -4186,18 +4205,18 @@ An envelope, `ok: true` whenever no step failed, human steps included
4186
4205
  ([servers.md](servers.md#connect-a-machine) has what each step does):
4187
4206
 
4188
4207
  ```json
4189
- {"id":"altair-aweb","ready":false,
4208
+ {"id":"devbox-aweb","ready":false,
4190
4209
  "registration":null,
4191
4210
  "steps":[{"step":"ssh","status":"ok"},
4192
4211
  {"step":"oats","status":"done","detail":"installed @awebai/oats 0.39.0 (was missing)"},
4193
4212
  {"step":"git","status":"needs-human","code":"E_REMOTE_UNREADABLE",
4194
- "detail":"cannot read remote https://github.com/awebai/ac (auth): on macOS a session without a terminal …",
4195
- "remedy":"on altair: on macOS a session without a terminal … (`gh auth login --insecure-storage`, then `gh auth setup-git`), or use an SSH key the session can reach: …",
4213
+ "detail":"cannot read remote https://github.com/example/app (auth): on macOS a session without a terminal …",
4214
+ "remedy":"on devbox: on macOS a session without a terminal … (`gh auth login --insecure-storage`, then `gh auth setup-git`), or use an SSH key the session can reach: …",
4196
4215
  "hint":"keychain-non-interactive"},
4197
4216
  {"step":"deployment","status":"skipped","detail":"waits for git"},
4198
4217
  {"step":"register","status":"skipped","detail":"waits for git"},
4199
4218
  {"step":"readiness","status":"skipped","detail":"waits for git"}],
4200
- "human":["on altair: on macOS a session without a terminal … or the desktop login's ssh-agent (point SSH_AUTH_SOCK at it in the shell's startup file)"]}
4219
+ "human":["on devbox: on macOS a session without a terminal … or the desktop login's ssh-agent (point SSH_AUTH_SOCK at it in the shell's startup file)"]}
4201
4220
  ```
4202
4221
 
4203
4222
  - `steps` is always the six steps `ssh`, `oats`, `git`, `deployment`,
@@ -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
@@ -7146,7 +7175,7 @@ whatever the rows say:
7146
7175
  | `already-running` | none |
7147
7176
  | `skipped` | `not-seen-recently` (the sweep cannot vouch for this loss: OATS never saw the home running for its current start, an earlier sweep already answered the loss, the loss was first seen 24 hours ago or more, or, within one boot, it was first seen 24 hours or more after the last running look; with a `message` that says which, nothing started: [Which losses come back](execution-targets.md#which-losses-come-back)), `unknown` (running reads `null`, or the start could not establish it: `code` `E_SESSION_UNKNOWN`), `start-busy` (`E_SESSION_START_BUSY`: a concurrent start), `not-lost` (`E_RESUME_NOT_LOST` or `E_SESSION_RUNNING`, or any refusal of a home that is gone: it stopped, started or was removed between the read and the start), `lifecycle-busy` (OATS 0.69.2: OATS is stopping, upgrading or retiring the home, or its retire is owed; read from its row, with a `message`, or answered by its start, with the start's `code`, `E_INSTANCE_RETIRING` or `E_LIFECYCLE_BUSY`, and `message`; nothing started) |
7148
7177
  | `blocked` | `resume-confirmation` (Claude's resume-cost dialog: the session runs and waits for its human), `launch-prompt` (`code` `E_SPAWN_INCOMPLETE`, with `launchPrompts`: the session is kept) |
7149
- | `refused` | `start-refused` (`code` and `message`: the start's own refusal), `refused-this-boot` (an earlier sweep in this boot was refused for this home and start, and its answer to the loss was lost: reported again with that `code` and `message`, nothing started; a refused loss is never retried automatically, after a reboot either), `keeps-getting-lost` (sweeps started this home 3 times in this boot and it was lost again each time: nothing started, no `code`, a `message` that says so; no sweep starts this loss again, after a reboot either: a person starts it by hand) |
7178
+ | `refused` | `start-refused` (`code` and `message`: the start's own refusal, and `nextAttemptAt`: a refused start launched nothing, so it does not answer the loss, and a sweep tries it again no sooner than that time), `start-refused-retrying` (an earlier sweep in this boot was refused for this home and start and its delay has not run: reported again with that `code`, `message` and `nextAttemptAt`, nothing started; the delay is 1 minute after the first refusal and doubles at each further one, up to 15 minutes, and the retries end when the loss is `not-seen-recently`), `keeps-getting-lost` (sweeps started this home 3 times in the last hour and it was lost again each time: nothing started, no `code`, a `message` that says so and `nextAttemptAt`, when the oldest of those starts is an hour old and a sweep starts the home again; a home that used up its starts 3 hours in a row is given up: the row has no `nextAttemptAt`, its `message` says a person starts it, and the loss is answered) |
7150
7179
 
7151
7180
  The kernel defines every `sessionEnd`, `resume` and row name in one
7152
7181
  module, `lib/session-resume-contract.mjs`; a change to one is a contract
@@ -7159,11 +7188,15 @@ whatever the rows say:
7159
7188
  runs in the OATS tmux server's cgroup, not a scope of its own, and why).
7160
7189
  Each start still records it in its own home's events. `--plan` has none.
7161
7190
  - A lost home is answered with the first that applies: `lifecycle-busy`,
7162
- `not-seen-recently`, `refused-this-boot`, `keeps-getting-lost`, then its
7163
- start. A sweep that is not a plan answers each lost home once: a later
7164
- sweep answers that loss `not-seen-recently`. A `lifecycle-busy` row does
7165
- not answer it: whatever OATS was doing to the home decides what it is
7166
- next, and a later sweep reads it again.
7191
+ `not-seen-recently`, `start-refused-retrying`, `keeps-getting-lost`, then
7192
+ its start. A sweep that is not a plan answers each lost home it started
7193
+ once: a later sweep answers that loss `not-seen-recently`. Four rows do
7194
+ not answer the loss, and a later sweep reads the home again:
7195
+ `lifecycle-busy` (whatever OATS was doing to the home decides what it is
7196
+ next), `start-refused` and `start-refused-retrying` (nothing was
7197
+ launched), and `keeps-getting-lost` (until its hour has passed; one
7198
+ without `nextAttemptAt` does answer it). The counts and the delays are
7199
+ one boot's: a reboot starts them again.
7167
7200
  - A home whose self-retire is scheduled or owed reads no `sessionEnd`; a
7168
7201
  launched one that does not run is listed `skipped`, `lifecycle-busy`, as
7169
7202
  a lost one is.
@@ -7182,7 +7215,12 @@ whatever the rows say:
7182
7215
  the per-boot note (refusals, and each home's count of sweep starts that
7183
7216
  launched something: `resumed`, `fresh`, `blocked`) are kernel-private,
7184
7217
  not a contract. Without a boot id (neither Linux nor macOS) nothing is
7185
- noted or counted.
7218
+ noted or counted. A validated current-start host-stop receipt excludes
7219
+ downtime from the in-boot eligibility gap and exempts a successful restore
7220
+ from the crash ceiling and count; it preserves prior failure counts and
7221
+ refusals. Blocked restores still count. See
7222
+ [Which losses come back](execution-targets.md#which-losses-come-back)
7223
+ for receipt validation and the independent loss-age and judgement guards.
7186
7224
  - **A lock that needs a person.** `E_RESUME_LOCK_STUCK`, through the same
7187
7225
  envelope at exit 1, when the sweep's lock cannot be taken and no sweep is
7188
7226
  known to run; nothing was started, and no sweep starts anything on this
@@ -7230,8 +7268,10 @@ this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
7230
7268
  (`<OATS_HOME_DIR>/host-run/lock`, a kernel-private file), or the lock
7231
7269
  cannot be judged; `error.details` `{lock, found}`, `found` as
7232
7270
  `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;
7271
+ A lock whose holder is gone, or that was taken in another kernel boot,
7272
+ is taken over. A container restart on the same kernel is judged by the
7273
+ holder's pid and process start; old qualified Linux boot IDs compare
7274
+ as their kernel UUID, so an upgrade cannot reclaim a live holder;
7235
7275
  - `E_BAD_ARGS`: a flag it does not define, an argument, a `--stop-grace`
7236
7276
  that is not 1 to 300 seconds, a verb other than `run`.
7237
7277
 
@@ -7239,14 +7279,21 @@ this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
7239
7279
  nothing of how far it got. A child that ended without an answer is
7240
7280
  reported under that code too, in `sweep.error` or on stderr, and does not
7241
7281
  end the run.
7242
- - **What it runs, in order.** The resume sweep once (`oats session resume`).
7282
+ - **What it runs, in order.** The resume sweep (`oats session resume`).
7243
7283
  Then at second 0 of every minute: `oats schedule tick --host` when the
7244
- host schedule registry lists a scope, and a listing of every deployment's
7245
- instances, which records what runs for the next start's sweep. Each is a
7246
- child process. A minute whose tick still runs is skipped; a minute missed
7247
- is never replayed. With no scope registered it ticks nothing and says so.
7284
+ host schedule registry lists a scope, and the resume sweep again, which
7285
+ starts a home lost while the host runs, within the sweep's own bounds, and
7286
+ records what runs for a later sweep. Each is a child process. A minute
7287
+ whose tick still runs is skipped, and a sweep that still runs is not run
7288
+ beside itself; a minute missed is never replayed. With no scope registered
7289
+ it ticks nothing and says so. A sweep is said on stderr when its outcomes
7290
+ differ from those of the sweep before.
7248
7291
  - **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
7292
+ runs gets 10 seconds to finish naturally, then a private admission fence
7293
+ stops further launches and owned child groups get a further 5-second
7294
+ cancellation phase. Interrupted attempts keep their unknown/reconcile
7295
+ accounting. It performs a final listing with a 3-second read budget; then
7296
+ it stops every running home, side
7250
7297
  by side, each with the stop `oats session restart` uses: SIGTERM to the
7251
7298
  harness, a wait of `--stop-grace` seconds (default 20), never escalated.
7252
7299
  Each home's stop record is written before its harness is signalled and
@@ -7256,7 +7303,7 @@ this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
7256
7303
  modes. **The answer** is written once, when the run ends:
7257
7304
  `result` `{schemaVersion: 1, plan: false, signal, warnings, sweep, ticks, stopped}`.
7258
7305
  `signal` is `"SIGTERM"` or `"SIGINT"`; `warnings` an array of strings;
7259
- `sweep` the sweep's own `result`
7306
+ `sweep` the first sweep's own `result`
7260
7307
  ([The machine sweep](#the-machine-sweep-oats-session-resume)), or
7261
7308
  `{error: {code, message}}` when it failed (the run goes on); `ticks`
7262
7309
  `{run, skipped, failed, noScope}`, minutes counted; `stopped` one row per
package/docs/desktop.md CHANGED
@@ -86,9 +86,13 @@ the one with **this Desktop's own version** — the app's degradation card
86
86
  shows that exact `npm install -g @awebai/oats@<version>` command, and
87
87
  copying it from the card is the reliable route.
88
88
 
89
- Each Desktop accepts a band of released CLI versions around its own
90
- (prereleases never), and a feature may need a higher floor; the app states
91
- both, so this guide does not repeat the numbers. The contract is
89
+ Each Desktop accepts released CLI versions from a floor up (prereleases
90
+ never), and a feature may need a higher floor; the app states both, so this
91
+ guide does not repeat the numbers. A CLI newer than the Desktop's own minor
92
+ version is accepted with only reads, terminals, Spawn, Start, Restart, the
93
+ colour and the background on: one line in the card's place says that every
94
+ other change is off until you install the OATS Desktop of that CLI's version,
95
+ and links its release. A Desktop of 0.69.17 or older refuses such a CLI. The contract is
92
96
  [desktop-cli-api.md](desktop-cli-api.md). The app discovers the CLI automatically
93
97
  (your PATH, the npm global prefix, a login shell) and re-probes on launch,
94
98
  app focus, and Retry. Until a compatible CLI is verified, the Soul roster's
@@ -166,8 +170,9 @@ recently added workspaces there, once.
166
170
  opened, or your home directory when there is none (never ~/Downloads);
167
171
  **Choose oats…** opens in the directory of the chosen or discovered CLI.
168
172
 
169
- Launch flags for scripted use: `--dir <workspace>`, `--instance <name>` and
170
- `OATS_DESKTOP_PORT`.
173
+ Launch flags for scripted use: `--dir <workspace>` and `--instance <name>`.
174
+ The app always starts its own backend server, on a private socket (below); it
175
+ never uses a server it did not start.
171
176
 
172
177
  ### Opening on an instance
173
178
 
@@ -554,12 +559,11 @@ scroll down with the fields to read it.
554
559
 
555
560
  The dialog's last field before **Developer settings** is **Name · optional**.
556
561
  Left empty, the kernel numbers the new instance (`<soul>-<n>`). A name you type
557
- is used in lowercase and gets the soul's role, the last word of the soul's
558
- name, as its suffix:
559
- `desktop-improvements` for `oats-desktop-expert` becomes
560
- `desktop-improvements-expert`. A name that already ends in the role, or is
561
- the role, stays as typed. The line under the field shows the final name, and a
562
- name that is too long, invalid or already taken is explained there. A spawn
562
+ is used in lowercase, as typed: nothing is appended to it, and the soul is
563
+ shown beside the instance. What to name it is
564
+ [oats.core's naming rule](../oats-package/capabilities/oats-core/skills/oats-souls/SKILL.md#name-the-instance)
565
+ (oats-souls, "Name the instance"). The line under the field shows the name,
566
+ and a name that is too long, invalid or already taken is explained there. A spawn
563
567
  on a server takes the exact name the same way when that machine's OATS can
564
568
  take one (feature `spawn-name`, read from its last roster answer), and its
565
569
  name is explained there too when that machine refuses it. With an OATS older
@@ -571,8 +575,9 @@ instance is named `<soul>-<purpose>`, and the field shows that prefix.
571
575
  `spawn-suggest-name`), the help under an empty Name reads "Left empty, the
572
576
  instance is named from its task." Once the Opening instruction holds at
573
577
  least seven words, the Desktop asks OATS for a name as you type. The soul's
574
- own harness reads the instruction and replies with a short name for the work,
575
- and the role is added as its suffix. The name shows as the field's
578
+ own harness reads the instruction and replies with a short name: a few words
579
+ for the work, then the instance's role as the instruction gives it. The name
580
+ shows as the field's
576
581
  placeholder ("release-notes-manager"), on the line under the field ("(from
577
582
  the task)") and in **What will be created**. It belongs to the instruction it
578
583
  was made for: when you change the instruction it goes, and the Desktop asks
@@ -681,10 +686,10 @@ feature (OATS 0.36.0); without it each deployment has its own entry.
681
686
  One sentence above them says what a machine is: "Each machine runs this
682
687
  workspace in a folder of its own. The instances under a machine run on
683
688
  that machine." **All** stacks one section per deployment, each headed by
684
- its machine and folder ("This Mac · ~/acme", "altair · ~/northwind"),
685
- with "Instances on this machine" or "Instances on altair" under it. Then
686
- each deployment has a tab of its own, named by its machine ("altair";
687
- "This Mac · oats-v2" when this Mac holds two). A workspace with one
689
+ its machine and folder ("This Mac · ~/acme", "devbox · ~/northwind"),
690
+ with "Instances on this machine" or "Instances on devbox" under it. Then
691
+ each deployment has a tab of its own, named by its machine ("devbox";
692
+ "This Mac · acme-2" when this Mac holds two). A workspace with one
688
693
  deployment shows just that deployment's tab, its tree under the same
689
694
  heading. The tab you chose is
690
695
  remembered per workspace. With two or more deployments, the sidebar's
@@ -707,7 +712,7 @@ heading. The tab you chose is
707
712
  can't read other machines. A server that can't be reached stays under the
708
713
  workspace it last reported, marked "remembered".
709
714
  - **The list of workspaces.** Each workspace names its machines on one line ("This Mac ·
710
- altair"), with a mark when one of them isn't live.
715
+ devbox"), with a mark when one of them isn't live.
711
716
  - **Not matched to a workspace.** A deployment that can't be matched is
712
717
  listed on its own under that heading in the list, with its machine and
713
718
  a short reason; choosing it opens its tab on the Machines tab. When this
@@ -968,13 +973,20 @@ right of its parent, and related instances are grouped together. Siblings are
968
973
  joined by a dotted line through their dots. A parent's line to its children
969
974
  runs just to the right of the dotted line, so the two never merge.
970
975
 
976
+ The newest instance is on top: the tree is in spawn order, newest first, at
977
+ every level. A group of related instances sits where its first instance's
978
+ spawn time puts it, so spawning a child doesn't move the group, and starting
979
+ or stopping an instance moves nothing. Instances spawned at the same moment
980
+ are in name order, and an instance whose spawn time can't be read comes after
981
+ every one whose time can.
982
+
971
983
  A parent's line joins only the children that do its work. When the instances'
972
984
  OATS has the `instance-same-work` feature, a child the kernel reports as doing
973
985
  its parent's work (`sameWork: true` in its row, set with `oats spawn …
974
986
  --same-work` or `oats instance same-work <instance> on`) is joined to its
975
987
  parent, and any other child keeps its place and its indent with no line to its
976
988
  parent. Under one parent the joined children are listed first, then the others,
977
- each part in name order, so the parent's line ends at its last joined child and
989
+ each part newest first, so the parent's line ends at its last joined child and
978
990
  never passes one it doesn't join. Nothing else marks the flag: no label, no
979
991
  tag, and nothing for a screen reader, which still hears each child "under" its
980
992
  parent in the command palette. The command palette draws the same lines, in
@@ -1112,9 +1124,24 @@ unknown or unreported harness shows "?". Sources and licences are in
1112
1124
 
1113
1125
  ## Security posture
1114
1126
 
1115
- - The bundled backend binds **127.0.0.1 only** and guards against DNS
1116
- rebinding (loopback Host on every request, loopback Origin on POSTs).
1117
- Do not expose it: it can type into your agent terminals.
1127
+ - The bundled backend listens on a **private socket only the app's main
1128
+ process can reach**: a Unix domain socket in a directory of its own, owned
1129
+ by you and closed to group and others (under `$XDG_RUNTIME_DIR` on Linux
1130
+ when it is private, else the system temporary directory). It opens no TCP
1131
+ port. The renderer reaches it only through main.
1132
+ - **Every request carries the per-launch credential** main hands its server
1133
+ over a private pipe when it starts it: 32 random bytes, fresh for each
1134
+ server, never on a command line, in an environment, a URL, a log or the
1135
+ renderer. A request without it is refused (401) before anything else
1136
+ happens, and no reply carries it: a reply that would (a file, a skill or
1137
+ a Git diff holding it) is refused (403) with no content. The Host guard (a loopback Host on every request) and the Origin
1138
+ guard (a loopback Origin on POSTs) stay. Main only ever talks to the
1139
+ server it started, and discards a reply from a server it has since
1140
+ replaced. Do not expose the socket: the server can type into your agent
1141
+ terminals.
1142
+ - **The CLI binary is chosen only through the app's own file dialog**
1143
+ (**Choose oats…**): main saves the pick, and the server reads it at each
1144
+ probe. No request to the server names a binary.
1118
1145
  - The app never imports framework code from a checkout and accepts no
1119
1146
  framework-root environment override; deployments are read with an
1120
1147
  app-owned read-only reader. Lifecycle actions run the installed `oats` CLI
@@ -1135,12 +1162,14 @@ unknown or unreported harness shows "?". Sources and licences are in
1135
1162
  | Symptom | Cause / fix |
1136
1163
  | --- | --- |
1137
1164
  | "Compatible oats CLI required" card | No CLI, or a version outside the range the card itself states. Copy the card's install command, or **Choose oats…** to point at the right binary; **Retry** re-probes. Spawn is disabled until a compatible CLI is verified. |
1138
- | "This Desktop is older than the installed oats CLI" card | The CLI found is a released version above the range this Desktop works with, usually because the CLI was updated first. Install OATS Desktop of the version the card names; the card offers no npm command, since installing the CLI this Desktop pins would downgrade it. Reads and terminals keep working meanwhile; **Choose oats…** points at another, compatible CLI and **Retry** re-probes. |
1165
+ | "This Desktop was tested with oats CLIs up to …" line, and most changes off | The CLI is of a later minor or major version than this Desktop, usually because the CLI was updated first. Reads, terminals, Spawn, Start, Restart, the colour and the background keep working; every other change is off until you install OATS Desktop of the version the line names, from the release it links. There is no npm command, since installing the CLI this Desktop pins would downgrade it; **Choose oats…** points at another CLI and **Retry** re-probes. |
1166
+ | "This Desktop is older than the installed oats CLI" card | The CLI found speaks a newer desktop API than this Desktop. Install OATS Desktop of the version the card names; the card offers no npm command. Reads and terminals keep working meanwhile; **Choose oats…** points at another, compatible CLI and **Retry** re-probes. |
1139
1167
  | Spawn disabled, no card | The probe hasn't settled yet (transient, resolves in ms). If it persists, the backend is unreachable — restart the app. |
1140
1168
  | Terminals fail to open ("could not attach") | tmux missing, or no live session for that instance. Install tmux (`tmux -V`); check `tmux -L oats ls` (the OATS tmux server, where instances run) and `tmux ls` (your default server, where an instance started by an earlier kernel may still be). |
1141
1169
  | Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: scroll back first (wheel up, Shift+PgUp or Ctrl+B then `[`) for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
1142
1170
  | macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
1143
- | Log says `server on 4820 — this app's server at version X (this app is Y), not started by this app — left running — starting a dedicated one on 4821` | Another OATS Desktop server holds the default port: another installed version or a dev checkout that is running, or one an earlier Desktop left running. The app serves from the port it names and never stops a server it did not start. From 0.49.0 a server the app starts exits when the app ends, however it ends (quit, crash or kill). A server left by an earlier Desktop (seen on Linux, where it outlived the app in its own `app-…scope`) must be stopped once by hand: find it with `ss -ltnp 'sport = :4820'` (or `lsof -iTCP:4820 -sTCP:LISTEN` on macOS) and stop that pid, or its scope (`systemctl --user stop <scope>`), then restart the app. |
1171
+ | Log says `the backend server's socket path is N bytes, over the limit of 103` | The directory for the server's private socket is too deep for a Unix socket path. On Linux it is `$XDG_RUNTIME_DIR` when that is a private directory of yours, else `$TMPDIR` (on macOS always `$TMPDIR`). Start the app with that variable set to a shorter directory of your own, or on Linux with `XDG_RUNTIME_DIR` unset and a short `TMPDIR`. The app never falls back to a TCP port. |
1172
+ | A backend server of an earlier Desktop is still running | From 0.49.0 a server the app starts exits when the app ends, however it ends (quit, crash or kill), and the app never uses a server it did not start. A server left by a Desktop older than 0.49.0 (seen on Linux, where it outlived the app in its own `app-…scope`) is harmless to a newer app but may be stopped once by hand: find it with `ss -ltnp 'sport = :4820'` (or `lsof -iTCP:4820 -sTCP:LISTEN` on macOS) and stop that pid, or its scope (`systemctl --user stop <scope>`). |
1144
1173
  | Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use **Add local workspace…** (the **+** at the top of the sidebar) to select the right folder. |
1145
1174
 
1146
1175
  For bugs, attach the terminal output of the app (`OATS Desktop` prints