@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
@@ -328,23 +328,25 @@ oats spawn release-manager --provider oats.aweb identity.source=/abs/path/to/ret
328
328
  ```
329
329
 
330
330
  An instance is named exactly `--name <slug>`, or `<soul>-<purpose>` with
331
- `--purpose`; with neither, the kernel numbers it. The convention for a name a
332
- person or an agent chooses is `<descriptive>-<role>` through `--name`: a few
333
- words for the instance's work, then the soul's role, the last word of the
334
- soul's name after any package qualifier (`--name desktop-improvements-expert`
335
- for an `oats-desktop-expert`). `--purpose` derives the name from the soul, for
331
+ `--purpose`; with neither, the kernel numbers it. A typed `--name` is used
332
+ exactly as given. How a person or an agent chooses one is the oats.core
333
+ skill oats-souls, "Name the instance"
334
+ ([its rule](../oats-package/capabilities/oats-core/skills/oats-souls/SKILL.md#name-the-instance)).
335
+ `--purpose` derives the name from the soul, for
336
336
  automations and scripts that know only the soul and a purpose.
337
337
  Names are unique per deployment (a workspace-model deployment has one agents
338
338
  root): a derived name in use gets `-2`, `-3`…; an explicit `--name` in use is
339
- refused (`E_INSTANCE_NAME_TAKEN`). The Desktop's spawn dialog adds the role to
340
- a typed name.
339
+ refused (`E_INSTANCE_NAME_TAKEN`). The Desktop's spawn dialog sends a typed
340
+ name as typed, lowercased.
341
341
  `oats spawn <soul> --preview --suggest-name --task-file <f>` asks the soul's
342
- own harness for the descriptive words, from the task, in one call that starts
342
+ own harness for the whole name, `<work>-<role>` with the role as the task
343
+ gives it, from the task, in one call that starts
343
344
  none of the user's MCP servers, hooks, plugins or extensions. Claude Code's
344
345
  built-in plugins, the host's managed-policy hooks and pi's credential commands
345
346
  are the stated exceptions; a claude login through `apiKeyHelper` is not read,
346
347
  so that user's name stays numbered (`harness-failed`). The preview then answers for
347
- `--name <descriptive>-<role>`, de-duplicated the same way. On claude and pi
348
+ `--name <that name>`, de-duplicated the same way; nothing appends the soul's
349
+ role. On claude and pi
348
350
  only; any other harness, and any failure of the call, leaves the name numbered
349
351
  and says why
350
352
  ([The suggested name](desktop-cli-api.md#the-suggested-name-feature-spawn-suggest-name)).
@@ -355,16 +357,16 @@ at spawn (`.oats-background.json`), so a later soul edit moves no existing
355
357
  instance; `oats instance background <instance> on|off` does. Both flags
356
358
  together are `E_BAD_ARGS`.
357
359
  An apply takes `--suggest-name` too (without `--name` or `--purpose`): the
358
- machine that spawns makes the same call, names the instance
359
- `<descriptive>-<role>`, de-duplicated the same way, and numbers it on any
360
+ machine that spawns makes the same call, names the instance with the reply's
361
+ name, de-duplicated the same way, and numbers it on any
360
362
  failure; the result's `naming` says which, and the apply may take up to 20 s
361
363
  longer ([On an apply](desktop-cli-api.md#on-an-apply-feature-spawn-apply-suggest-name)).
362
364
  Without the flag an apply is numbered, as before.
363
- `oats instance suggest-name --soul <soul> --task-file <f>` asks for the same
364
- words on this machine for a spawn that will land on another (the Desktop's
365
- dialog, spawning through `--server`): the soul only gives the role and needn't
366
- exist here, nothing is written or reserved, and the name is not made unique,
367
- which the landing host does
365
+ `oats instance suggest-name --task-file <f>` asks for the same name on this
366
+ machine for a spawn that will land on another (the Desktop's dialog, spawning
367
+ through `--server`): nothing is written or reserved, and the name is not made
368
+ unique, which the landing host does. `--soul <soul>` is optional: when given it
369
+ is checked as a soul name's shape and does not change the name
368
370
  ([A name for a spawn elsewhere](desktop-cli-api.md#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)).
369
371
 
370
372
  From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
@@ -1839,8 +1841,9 @@ after the capability injects (`injects/instance-boundary.md`):
1839
1841
  target another one deliberately).
1840
1842
  - `<instance-home>/work` — the repository or workspace view — is where
1841
1843
  repository reading, editing, building, testing, git and commits happen, to the
1842
- extent the mode below permits. In `worktree` and `checkout` mode, the
1843
- instance's [extra trees](#extra-trees) in the home serve the same purpose.
1844
+ extent the mode below permits. In `worktree`, `checkout`, `workspace` and
1845
+ `directory` mode, the instance's [extra trees](#extra-trees) in the home
1846
+ serve the same purpose.
1844
1847
  - The home has no soul link: the composed `AGENTS.md` already carries the
1845
1848
  soul's instructions, and `instance.json` `soulDir` records the (read-only,
1846
1849
  per-commit) soul directory every hook and dispatched command receives as
@@ -2012,6 +2015,14 @@ without Git. `repo` (or `--repo`) supplies context only and may be an ordinary
2012
2015
  directory; without it, the deployment directory (where `oats-local.yaml` is) is
2013
2016
  used. No implicit fallback changes the other modes.
2014
2017
 
2018
+ Repository work that needs a branch — a change the instance's role and task
2019
+ call for, or a repository at the remote's current state — goes in an
2020
+ [extra tree](#extra-trees) of the instance's own, never in `work/` (which
2021
+ never becomes a repository) and never in the `repo` directory. An extra tree
2022
+ always names its repository (`--repo`): the recorded `repo` is context only,
2023
+ the deployment directory by default, so `oats worktree add` without `--repo`
2024
+ is refused when it is not a clone (`E_CLONE_MISSING`).
2025
+
2015
2026
  `--work-dir` and `--branch` are rejected. Canonical instructions, skill
2016
2027
  composition, provider trust and harness preflight still apply. Retirement preserves nonempty work in verified recovery storage beside the
2017
2028
  home (`workRecovery.path/work`) before deleting it, including files created by
@@ -2046,21 +2057,34 @@ where it works are decoupled.
2046
2057
 
2047
2058
  Rules:
2048
2059
 
2049
- - Read freely across member repos; **never edit or commit inside them** —
2050
- route changes to the owning repo's agents or the human.
2051
- - No git state operations in any member repo.
2060
+ - Read freely across member repos through `work/`; **never edit or commit
2061
+ inside the member clones** — others use them.
2062
+ - No Git state operations in any member clone (no branch switches, resets,
2063
+ pulls, stashes, or `git worktree` run by hand).
2064
+ - Work that needs a branch of a member — a change the instance's role and
2065
+ task call for, or a member at the remote's current state — goes in an
2066
+ [extra tree](#extra-trees) of the instance's own, which `oats worktree add`
2067
+ makes without moving any of the clone's refs. Otherwise route the change to
2068
+ the owning repo's agents or the human. The mode says where work happens;
2069
+ what work the instance takes on is its role's and its task's call.
2052
2070
  - Knowledge promotion follows the knowledge capability's own protocol, never
2053
2071
  direct edits through the workspace view.
2054
2072
 
2055
- The instance records no branch: the workspace is not a Git tree.
2073
+ The instance records no branch: the workspace is not a Git tree. For the same
2074
+ reason an extra tree always names its repository (`--repo`): the instance's
2075
+ recorded repository is the deployment directory.
2056
2076
 
2057
2077
  ### Extra trees
2058
2078
 
2059
- An instance in `worktree` or `checkout` mode can create extra trees: linked
2060
- Git worktrees in its home, beside `work/`. It does so when the work needs
2061
- another branch, or another repository of the deployment (one task that
2062
- touches several repositories). The `worktree` and `checkout` briefings teach
2063
- it; the `workspace`, `directory` and `attached` briefings do not.
2079
+ An instance in `worktree`, `checkout`, `workspace` or `directory` mode can
2080
+ create extra trees: linked Git worktrees in its home, beside `work/`. It does
2081
+ so when the work needs another branch, or another repository of the deployment
2082
+ (one task that touches several repositories); in `workspace` mode, whenever
2083
+ work needs a branch of a member, since `work/` is read-only; in `directory`
2084
+ mode, whenever work needs a branch at all, since `work/` is not a Git tree.
2085
+ The `worktree`, `checkout`, `workspace` and `directory` briefings teach it
2086
+ (the `workspace` and `directory` ones with `--repo` always, in one shared
2087
+ section); the `attached` briefing does not.
2064
2088
 
2065
2089
  ```text
2066
2090
  oats worktree add --purpose <p> --branch <b> --base <remote-branch>
@@ -0,0 +1,119 @@
1
+ # Trust model
2
+
3
+ Everything that runs as one operating-system user is one trust group, the
4
+ kernel included. OATS draws no line inside a user, and must never run with
5
+ more authority than the agents whose homes it reads.
6
+
7
+ ## The parties
8
+
9
+ - The **operator**: the person, or the control plane acting for them, who
10
+ decides which agents exist and with what configuration.
11
+ - The **kernel**: `oats` commands and `oats host run`. It has no authority of
12
+ its own. It runs as whoever started it.
13
+ - An **agent**: a harness process and everything it starts. It can write its
14
+ own home, and anything else its user can write.
15
+ - A **capability**: code copied into an agent's home at spawn, which the
16
+ kernel runs as hooks and commands.
17
+
18
+ ## The line
19
+
20
+ The line is the user boundary and, for a hosted team, the container around
21
+ it ([container.md](container.md)). Inside it nothing protects one agent from
22
+ another, or the kernel's own state from an agent: an agent can read and write
23
+ what the kernel reads and writes.
24
+
25
+ 1. **A trust group is the unit of compromise.** If one agent in it is
26
+ subverted, treat every agent, seat and credential in it as subverted.
27
+ 2. **One team, one trust group.** Agents that must not be able to read each
28
+ other's identities or affect each other's work do not share a container or
29
+ a user. Nothing in OATS makes that safe. A container holds one team, never
30
+ several.
31
+ 3. **The kernel takes no authority across the line.** It is never run as
32
+ root, as a different user, or on another machine against a home that an
33
+ agent on the far side of the line could write. A command given
34
+ `--server` runs `oats` on the home's side
35
+ ([servers.md](servers.md)); the Desktop and the TUI start the local `oats`
36
+ and run no kernel code of their own on what a remote home contains.
37
+ The kernel holds itself to this: a start, a resume, a stop, a retire or
38
+ an upgrade of a home that the user running it does not own is refused
39
+ with `E_HOME_NOT_OWNED` before anything is written, root included.
40
+ One piece of the package does run as root, and it is outside this rule:
41
+ the harness-credential receiver `share/oats-login-receive`
42
+ ([servers.md](servers.md#harness-credentials)). It runs under a forced
43
+ command, reads only its standard input, writes only the credential file
44
+ its root-owned configuration names and touches no home, so it is not the
45
+ kernel acting on a home.
46
+ 4. **An agent's home is untrusted as data, and trusted as code only inside
47
+ its own group.** The kernel executes what it finds there, such as
48
+ lifecycle hooks and a module's commands, because doing so gives the agent
49
+ nothing it does not already have. What it finds there decides nothing
50
+ about another group.
51
+ 5. **Inside a group OATS protects the agents' work, not the group's
52
+ secrets.** Locks, claims, recovery copies and the Git hardening at
53
+ retirement exist so that a kill, a race or a hostile repository
54
+ configuration does not lose or corrupt work. They are robustness, not
55
+ access control.
56
+
57
+ ## What OATS does not promise
58
+
59
+ Inside one trust group, none of these hold:
60
+
61
+ - That an agent cannot read another agent's seat key, the team's Claude
62
+ token, the launch configurations, the schedule registry or sshd's host
63
+ keys.
64
+ - That an agent cannot stop sshd, `oats host run`, the wake broker or its
65
+ supervisor.
66
+ - That a capability is confined to the outputs it declares.
67
+ - That a command which reads is one which runs nothing.
68
+ `oats readiness --home <home>` executes the home's module commands, and
69
+ today it gives them the environment of whoever runs the read, without that
70
+ caller's `OATS_`, `OAS_` and `PI_` identity variables. Run it for a home of
71
+ another trust group only from an environment that holds nothing the home's
72
+ agent should not have.
73
+ - That a capability the kernel reports as trusted has been judged.
74
+ [Trust is the workspace's declaration](capabilities.md#mental-model) of a
75
+ member repo or a package. The kernel then checks that what it is about to
76
+ run is the copy made at spawn. That copy is in the agent's home, so the
77
+ check is no defence against the agent.
78
+ - That a harness's sandbox is a boundary. OATS counts none as one and relies
79
+ on none. Where a harness restricts what its agent can write, that is the
80
+ harness's property and not a promise of OATS.
81
+
82
+ ## Code from outside the group
83
+
84
+ What an agent's home runs comes from the workspace: packages, pinned by the
85
+ deployment's lock, and member repositories, which are not pinned. A member's
86
+ souls and capabilities are used at the member's latest commit, trusted by
87
+ membership ([capabilities.md](capabilities.md#mental-model)).
88
+
89
+ So the default branch of the workspace host and of every member is outside
90
+ every agent group, and it is the operator's to keep there. A commit on it
91
+ becomes the hooks and commands of the next spawn of every soul that composes
92
+ that member, in every deployment of the workspace, and of the next capability
93
+ command an operator runs on their own machine.
94
+
95
+ OATS does not enforce this. An agent holds whatever Git credential its
96
+ deployment gives it. If that credential can push to a member's default
97
+ branch, one subverted agent reaches every other team and the operator, and
98
+ rule 1 no longer bounds the loss. Give agents a credential that cannot:
99
+ branch protection that requires another identity's approval, or a repository
100
+ that is not a member of the workspace.
101
+
102
+ ## Keys outside the group
103
+
104
+ One part of the line is enforced by something other than OATS: where a
105
+ team's keys are kept. A hosted aweb team's controller key is kept by the
106
+ service, outside every agent group, and no agent can read it. That holds
107
+ today.
108
+
109
+ The aweb human-assurance design goes further. In it, the keys of a human, of
110
+ a namespace and of a team's controller will be held by a protected signer
111
+ outside every agent group. The deployment root's agent key will stay inside
112
+ the group by design, and what it can do will be bounded by its admission
113
+ policy, so that its loss is the loss of that group and of nothing above it.
114
+ The signer is not shipped.
115
+
116
+ No deployment that brings its own team has this yet. Each still holds its
117
+ team keys under the agents' user, in `~/.awid/team-keys` and `.aweb-roots`.
118
+ Under rule 1 those keys are compromised along with any agent in that group,
119
+ until they are moved to the signer.
package/docs/tui.md CHANGED
@@ -176,12 +176,12 @@ while a terminal is open); under 80 columns it has the whole width.
176
176
  kernel reported that were withheld (a home outside its soul's directory,
177
177
  or one reported twice), `2 withheld`, when there are any.
178
178
  - **The list** is the roster the Desktop draws: the same groups in the same
179
- order, from the same code. It is in name order, by each group's top
180
- instance, so starting or stopping an instance moves nothing. An instance
179
+ order, from the same code. It is in spawn order, newest first, by each
180
+ group's top instance, so starting or stopping an instance moves nothing. An instance
181
181
  that others were spawned from has them indented under it, and keeps its
182
182
  place when it gains or loses one. Under one parent, the instances that do
183
183
  its work (the kernel's `sameWork`, from an OATS with `instance-same-work`)
184
- come first, then the others, each part in name order, as the Desktop lists
184
+ come first, then the others, each part newest first, as the Desktop lists
185
185
  them. An empty row stands between each run
186
186
  of instances related to no other and the group before or after it. The
187
187
  indent alone says which instance is under which: no mark is drawn for
@@ -974,7 +974,7 @@ selected.
974
974
  ```
975
975
  acme-platform │ dev
976
976
  acme-billing ● │ soul dev
977
- lfx │ state running
977
+ lab │ state running
978
978
  garnet │ harness claude, claude-opus-5-5 (so…
979
979
  +2 │ work worktree, agents/dev
980
980
  │ team eng
@@ -983,7 +983,7 @@ selected.
983
983
 
984
984
  The sidebar's first rows list the workspaces this run can show, one row a
985
985
  workspace, whatever machines it is on, in [the switcher](#the-switcher)'s
986
- order: `lfx` is one row however many machines hold it, and a machine the
986
+ order: `lab` is one row however many machines hold it, and a machine the
987
987
  rules shared with the Desktop matched to no workspace is a row by its own
988
988
  name, in the same flat list. A row is one line: the name. With one
989
989
  workspace the list is its row.
@@ -1028,7 +1028,7 @@ workspace the list is its row.
1028
1028
  that list fills the sidebar, which then has no such row, does the line
1029
1029
  take a row, the list giving up its last. With the list's focus (`w`) the
1030
1030
  focus stays there, the cursor where it was. A workspace with a deployment of this
1031
- machine not opened yet (lfx, with `~/Work/lfx` on this computer's list)
1031
+ machine not opened yet (lab, with `~/Work/lab` on this computer's list)
1032
1032
  opens it first, as the switcher's `Enter` does. What the workspace left
1033
1033
  had open is kept for it, as for a switch from the
1034
1034
  switcher ([Tabs](#tabs)), and from a terminal's focus the focus is kept
@@ -1068,9 +1068,9 @@ switcher covers the whole screen.
1068
1068
  workspaces │ > * acme-platform
1069
1069
  │ This machine
1070
1070
  Instances 1 │ garnet
1071
- Souls 2 │ lfx
1071
+ Souls 2 │ lab
1072
1072
  Capabilities 3 │ This machine · not opened
1073
- ────────────────────────────────────────────────│ athenea (lfx)
1073
+ ────────────────────────────────────────────────│ builder (lab)
1074
1074
  Ctrl+X commands │ Not matched to a workspace
1075
1075
  Ctrl+K palette │ basalt ssh needs a prompt
1076
1076
  Enter open │ On this machine, not opened
package/docs/upgrading.md CHANGED
@@ -6,11 +6,12 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.17** ([release notes](release-notes/v0.69.17.md)).
10
- The 0.69.17 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.19** ([release notes](release-notes/v0.69.19.md)).
10
+ The 0.69.19 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
11
+ Desktop and the CLI can be upgraded [in either order](#either-order-works).
11
12
 
12
13
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.69.17,** in the [release notes](release-notes/): it says what to do before
14
+ 0.69.19,** in the [release notes](release-notes/): it says what to do before
14
15
  the CLI changes, and what else must change with it (the Desktop, another
15
16
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
17
  names the releases that ask for more than the steps below. `oats version`
@@ -19,14 +20,14 @@ prints the version you have.
19
20
  Then, on each host:
20
21
 
21
22
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.69.17 first
23
- npm install -g @awebai/oats@0.69.17 # 1. the CLI
23
+ # 0. where the Desktop is installed: Desktop 0.69.19, in either order
24
+ npm install -g @awebai/oats@0.69.19 # 1. the CLI
24
25
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
26
  oats doctor # 3. in the same deployment
26
27
  ```
27
28
 
28
29
  The Desktop's installers are the assets of the
29
- [GitHub Release](https://github.com/awebai/oats/releases) of that version
30
+ [GitHub Release](https://github.com/oats-project/oats/releases) of that version
30
31
  ([OATS Desktop](desktop.md#install)). Then restart the pi sessions that were
31
32
  running: a session keeps the bridge it loaded when it started.
32
33
  [The steps](#the-steps) says what each step does and why they come in this
@@ -40,9 +41,12 @@ the version you are upgrading from.
40
41
  ## The steps
41
42
 
42
43
  Upgrading OATS means three things, in this order, on each host, and one
43
- before them where the Desktop is installed:
44
+ more where the Desktop is installed:
44
45
 
45
- 0. **The Desktop**, where it is installed: the new version's, before the CLI.
46
+ 0. **The Desktop**, where it is installed: the new version's. Install it
47
+ before the CLI where the Desktop is 0.69.17 or older
48
+ ([which goes first](#either-order-works)); with a newer one, either order
49
+ works.
46
50
  1. **The CLI** (`@awebai/oats`, the kernel).
47
51
  2. **The pi bridge** (`@awebai/oats-pi`), in every pi folder the host's
48
52
  deployments launch pi with: `oats update`, in each deployment.
@@ -62,12 +66,21 @@ instances. A pi started outside any instance looks for a global install, an
62
66
  **A release's own steps are in its notes**, in its `## Upgrade` section.
63
67
  This page is the part that is the same for every release.
64
68
 
65
- **Why the Desktop goes first.** A Desktop accepts a CLI up to its own minor
66
- version and refuses a newer one: with the CLI moved first, the Desktop that
67
- is still running lists no instance until it is replaced. The new Desktop
68
- accepts the older CLI in the meantime. The CLI can move by two commands, the
69
- `npm install` and an `oats update` whose plan installs it: step 0 comes
70
- before either.
69
+ <a id="either-order-works"></a>**Either order works**, with a Desktop newer than 0.69.17. Such a Desktop was
70
+ tested with the CLIs of its own minor version, and accepts a newer minor or
71
+ major one: reads, terminals, Spawn, Start, Restart, the colour and the
72
+ background keep working with it, and every other change is held back until
73
+ the Desktop of that version is installed. It says so in one line, in the
74
+ place of the CLI card:
75
+ `This Desktop was tested with oats CLIs up to <X.Y>; the installed CLI is <version>. Stop, Remove, schedules, triggers and every other change except Spawn, Start, Restart, colour and background are off until you install OATS Desktop <version>.`
76
+ A Desktop accepts an older CLI too, down to its floor, so installing it first
77
+ holds nothing back.
78
+
79
+ **A Desktop of 0.69.17 or older still refuses a CLI newer than its own minor
80
+ version:** with the CLI moved first, it lists no instance until it is
81
+ replaced. Where one is installed, step 0 comes first. The CLI can move by two
82
+ commands, the `npm install` and an `oats update` whose plan installs it:
83
+ step 0 comes before either.
71
84
 
72
85
  **Package versions are a different thing.** `oats update` moves the CLI and
73
86
  the bridge, never a package. A deployment's capabilities come from the
@@ -84,12 +97,12 @@ Without a terminal (a script, an agent's shell) it runs only with `--yes`.
84
97
 
85
98
  `oats update` also does step 1: when npm lists a newer `@awebai/oats`, its
86
99
  plan starts with that install, and the bridges move to that same version in
87
- the same run. So where the Desktop is installed, step 0 comes before such an
88
- `oats update` too: `oats update --check` shows whether the plan holds that
89
- install, and runs nothing. When that install is of another minor or major
100
+ the same run. So where a Desktop of 0.69.17 or older is installed, step 0
101
+ comes before such an `oats update` too: `oats update --check` shows whether
102
+ the plan holds that install, and runs nothing. When that install is of another minor or major
90
103
  version, the plan says so in one line under its steps, whether or not a
91
- Desktop is installed: `OATS Desktop refuses a CLI newer than its own minor
92
- version: if you use it, install OATS Desktop <version> first.`
104
+ Desktop is installed: `An OATS Desktop older than <X.Y> holds actions back with this CLI. Stop, Remove, schedules, triggers and every other change except Spawn, Start, Restart, colour and background are off until you install OATS Desktop <version>. (An OATS Desktop of 0.69.17 or older refuses this CLI until then.)`
105
+ Its second sentence is the Desktop's own notice, word for word.
93
106
 
94
107
  **`oats update` only moves forward.** It never installs an older CLI or an
95
108
  older bridge than the one in place:
@@ -204,6 +217,19 @@ of the Desktop and the CLI, and an optional package pin. A change a script
204
217
  must follow is in its release's Upgrade section whether or not it is listed
205
218
  here.
206
219
 
220
+ - **[0.69.19](release-notes/v0.69.19.md#upgrade):** the catalog pins
221
+ oats.aweb 1.42.1 and oats.framework 1.25.2. A retained seat that relied on
222
+ `OATS_AWEB_URL` records its server with `aw workspace connect` and unsets the
223
+ variable; a non-boolean `identity.e2ee` or `identity.takeOver` is set to
224
+ `true` or `false`. Respawn instances to take the shorter aweb text and the
225
+ workspace and directory modes' extra trees.
226
+ - **[0.69.18](release-notes/v0.69.18.md#upgrade):** from this Desktop on,
227
+ the Desktop and the CLI go in either order (a Desktop of 0.69.17 or older
228
+ still goes first); the catalog pins oats.aweb 1.41.0, oats.okf 6.0.3 and
229
+ oats.framework 1.25.0. Start the host's wake broker before a Codex or
230
+ `delivery: session` home's next start: oats.aweb 1.40.0 and later refuse
231
+ such a home while none runs. Respawn instances to take the new naming and model
232
+ floor texts.
207
233
  - **[0.69.17](release-notes/v0.69.17.md#upgrade):** the catalog pins
208
234
  oats.okf 6.0.2 and oats.framework 1.24.1; respawn each running
209
235
  `oats-engineering-expert` and `oats-product-expert` once after `oats sync`,
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.24.1 # bare version → resolves through the official catalog
58
- oats.okf: v6.0.2
57
+ oats.framework: v1.25.2 # bare version → resolves through the official catalog
58
+ oats.okf: v6.0.3
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone
@@ -425,7 +425,7 @@ member soul that is the expert in that capability (`oats-okf-expert`,
425
425
  **OATS's coordination is a member copy of the engineering template.** The
426
426
  `oats` repository keeps its own copy of
427
427
  [oats-project/oats-engineering-coordination](https://github.com/oats-project/oats-engineering-coordination)
428
- at template-v3.0.1, adapted to OATS: `oats.engineering-expert`,
428
+ at template-v3.1.3, adapted to OATS: `oats.engineering-expert`,
429
429
  `oats.developer`, `oats.build`, `oats.code-review`, `oats.maintainer`,
430
430
  `oats.landing-rules` and `oats.dispatcher`, in `capabilities/oats-<name>/`.
431
431
  `capabilities/TEMPLATE-RELEASE` records the release, its commit and what was copied, and
@@ -4,9 +4,34 @@ Your `./work` is an **instance-owned execution directory**, not a Git worktree,
4
4
  checkout or link. The `repo` recorded for you supplies configuration only; it
5
5
  grants no permission to edit the `repo` directory.
6
6
 
7
- - Work inside `./work`. **Never initialize a fake repository**; a containing
8
- repository Git discovers is not yours.
7
+ - Work inside `./work`, apart from your extra trees. **Never initialize a
8
+ fake repository**; a containing repository Git discovers is not yours.
9
+ - **Repository work that needs a branch goes in an extra tree of your own**
10
+ (below): a change your role and task call for, or a repository at the
11
+ remote's current state. What work you take on stays your role's and your
12
+ task's call.
9
13
  - Use external inputs and destinations only as your task and capabilities
10
14
  explicitly authorize.
11
15
  - Deliver results through your task's own protocol before you finish: the
12
16
  recovery copy kept at retirement is not publication.
17
+
18
+ ### Extra trees
19
+
20
+ For a branch of a member repository, from your home (`--preview` first;
21
+ `<repo>`: the member key or clone path, always, since your own `./work` is
22
+ not a Git tree; `<base>`: the remote branch to start from, or the one you
23
+ rework):
24
+
25
+ oats worktree add --purpose <purpose> --branch <branch> --base <base> --repo <repo>
26
+
27
+ It moves none of the clone's refs. A tree is yours alone: build, test and
28
+ commit there.
29
+
30
+ - Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
31
+ (if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
32
+ - `add` may take minutes: use a long timeout; if killed, rerun it.
33
+ - Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
34
+ - Before you finish, merge each tree into your PR branch, or push it and name
35
+ it in your hand-back; then `oats worktree remove --purpose <purpose>`.
36
+ Retirement may keep a tree with uncommitted work; don't rely on it.
37
+ Details: `oats worktree --help`, and `/oats-operate` if you have it.
@@ -1,11 +1,37 @@
1
1
  ## Work mode: workspace
2
2
 
3
- Your `./work` is the **whole workspace**, not one repository. You route,
4
- analyse and coordinate; you do not change code.
3
+ Your `./work` is the **whole workspace**, not one repository: every member
4
+ clone, read through it. What work you take on is your role's and your task's
5
+ call; this block says where it happens.
5
6
 
6
- - **Read freely across member repositories; never edit or commit inside them,
7
- and NEVER change their Git state** (no branch switches, resets, pulls,
8
- stashes or worktrees). Route a repository change to that repository's agents
9
- or to your human.
7
+ - **Read freely across member repositories through `./work`; never edit or
8
+ commit there, and NEVER change a member clone's Git state** (no branch
9
+ switches, resets, pulls, stashes, or `git worktree` run by hand). Others
10
+ use those clones.
11
+ - **Work that needs a branch goes in an extra tree of your own** (below): a
12
+ change your role and task call for, or a member at the remote's current
13
+ state. Otherwise route a repository change to that repository's agents or
14
+ to your human.
10
15
  - A capability that delivers updates into a repository follows its own
11
16
  instructions; that is not an exception you take yourself.
17
+
18
+ ### Extra trees
19
+
20
+ For a branch of a member repository, from your home (`--preview` first;
21
+ `<repo>`: the member key or clone path, always, since your own `./work` is
22
+ not a Git tree; `<base>`: the remote branch to start from, or the one you
23
+ rework):
24
+
25
+ oats worktree add --purpose <purpose> --branch <branch> --base <base> --repo <repo>
26
+
27
+ It moves none of the clone's refs. A tree is yours alone: build, test and
28
+ commit there.
29
+
30
+ - Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
31
+ (if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
32
+ - `add` may take minutes: use a long timeout; if killed, rerun it.
33
+ - Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
34
+ - Before you finish, merge each tree into your PR branch, or push it and name
35
+ it in your hand-back; then `oats worktree remove --purpose <purpose>`.
36
+ Retirement may keep a tree with uncommitted work; don't rely on it.
37
+ Details: `oats worktree --help`, and `/oats-operate` if you have it.
@@ -109,7 +109,7 @@ export const COMMAND_FLAGS = Object.freeze([
109
109
  refused: Object.fromEntries(["--home", "--dir", "--producer", "--reason"].map((f) => [f, attentionHasNo(f)])), usage: ATTENTION_USAGE },
110
110
  { command: "instance suggest-name", operands: [], values: ["--soul", "--task", "--task-file", "--harness", "--model", "--launch-config", "--dir"], switches: ["--json"],
111
111
  refused: { "--server": "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)" },
112
- usage: "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]" },
112
+ usage: "usage: oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]" },
113
113
  { command: "worktree add", operands: [], values: ["--purpose", "--branch", "--base", "--repo"], switches: ["--preview", "--json"], refused: WORKTREE_REFUSED,
114
114
  usage: "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json]" },
115
115
  { command: "worktree remove", operands: [], values: ["--purpose"], switches: ["--json"], refused: WORKTREE_REFUSED,