@awebai/oats 0.63.0 → 0.65.0

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 (47) hide show
  1. package/README.md +14 -1
  2. package/bin/oats.mjs +158 -26
  3. package/docs/desktop-cli-api.md +127 -3
  4. package/docs/desktop.md +14 -5
  5. package/docs/execution-targets.md +9 -5
  6. package/docs/first-team.md +6 -0
  7. package/docs/implementation.md +17 -3
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-notes/v0.64.0.md +105 -0
  11. package/docs/release-notes/v0.65.0.md +187 -0
  12. package/docs/souls-and-instances.md +26 -6
  13. package/docs/tui.md +416 -238
  14. package/docs/upgrading.md +2 -1
  15. package/docs/workspaces.md +125 -1
  16. package/lib/core.mjs +43 -11
  17. package/lib/deployments.mjs +325 -0
  18. package/lib/resolved-deployment.mjs +37 -0
  19. package/lib/session-input.mjs +12 -2
  20. package/lib/workspace.mjs +2 -0
  21. package/package-catalog.json +1 -1
  22. package/package.json +1 -1
  23. package/packages/client/cli-locator.mjs +2 -2
  24. package/packages/client/deployment-label.mjs +2 -2
  25. package/packages/client/deployment-list-cli.mjs +98 -0
  26. package/packages/client/deployment-list.mjs +91 -0
  27. package/packages/client/instance-tree.mjs +53 -3
  28. package/packages/client/keymap.mjs +106 -0
  29. package/packages/client/own-codes.mjs +2 -0
  30. package/packages/client/panel-views.mjs +1 -1
  31. package/packages/client/roster-sections.mjs +22 -6
  32. package/packages/client/workspace-admission.mjs +2 -1
  33. package/packages/tui/README.md +4 -4
  34. package/packages/tui/lib/actions.mjs +29 -5
  35. package/packages/tui/lib/client.mjs +3 -1
  36. package/packages/tui/lib/config.mjs +21 -14
  37. package/packages/tui/lib/main.mjs +108 -31
  38. package/packages/tui/lib/model.mjs +71 -41
  39. package/packages/tui/lib/read.mjs +15 -45
  40. package/packages/tui/lib/store.mjs +158 -39
  41. package/packages/tui/lib/term/through.mjs +40 -18
  42. package/packages/tui/lib/views/act.mjs +17 -13
  43. package/packages/tui/lib/views/frame.mjs +418 -421
  44. package/packages/tui/lib/views/help.mjs +41 -19
  45. package/packages/tui/lib/views/instances.mjs +38 -9
  46. package/packages/tui/lib/views/switcher.mjs +65 -21
  47. package/skills/oats-getting-started/SKILL.md +440 -170
@@ -9,7 +9,7 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.13.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.13.3` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.29.0` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.2.1`, `5.2.1`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.2.1` or `oats-framework/v1.13.2`) and the payload path. An id
54
+ convention (`v5.2.1` or `oats-framework/v1.13.3`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,7 +74,7 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.13.2
77
+ oats.framework: v1.13.3
78
78
  oats.okf: v5.2.1
79
79
  oats.aweb: v1.29.0
80
80
  teams:
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.1", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.2", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.3", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.13.2`
362
- resolves to tag `oats-framework/v1.13.2`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.13.3`
362
+ resolves to tag `oats-framework/v1.13.3`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,105 @@
1
+ # OATS 0.64.0
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.63 Desktop refuses a 0.64.0 CLI. The
9
+ 0.64.0 Desktop accepts OATS CLIs `>=0.26.0 <0.65.0`.
10
+
11
+ - **The official catalog moves oats.framework 1.13.2 → 1.13.3** (oats.core
12
+ 2.6.5 and oats.setup 2.8.2, see Provider updates). The other packages are
13
+ unchanged. A deployment takes it by moving its `oats.framework` pin and
14
+ running `oats sync`. Only new spawns use it.
15
+
16
+ - **Coming from 0.61 or earlier:** do 0.62.0's Upgrade steps too (the capture
17
+ service's `oats setup`, once per user on each host, from that user's shell).
18
+
19
+ ## Changed
20
+
21
+ - **One way in: the README's "Start here" points to the
22
+ `oats-getting-started` skill**, which a person's own coding agent
23
+ downloads verbatim and follows ([#1314](https://github.com/awebai/oats/issues/1314)).
24
+ - **The skill is rewritten.** It asks one round of questions: the use case,
25
+ the existing repositories, the knowledge tools, new or existing
26
+ workspace, messaging, harness and deployment directory.
27
+ - **It installs what is missing,** then OATS Desktop and the CLI at the
28
+ same version (with the pi bridge, `@awebai/oats-pi`, when the harness is
29
+ pi). The Desktop comes from the release asset, downloaded with
30
+ `gh` and checked against `SHA256SUMS.txt` and its attestation; on Linux it
31
+ installs per user and shows in the app launcher.
32
+ - **The GitHub login** is gh's device flow, which the agent starts and the
33
+ person approves in their browser.
34
+ - **A new workspace** becomes a private repository holding the workspace
35
+ file, its membership and one thin soul,
36
+ `<workspace>-oats-setup-expert`, which holds `oats.setup` and has no
37
+ knowledge of its own, so it spawns on a machine before knowledge is set
38
+ up there. It takes the workspace's messaging, so it stays the
39
+ workspace's operator. **An existing workspace** is onboarded as it is;
40
+ when it has messaging, the skill sets it up on the machine before the
41
+ spawn, with an invite token the person types in their own terminal.
42
+ - **Then** the skill spawns the setup expert with the person's answers as
43
+ its task, and the expert does the rest (`/oats-setup-expert`,
44
+ oats.framework 1.13.0). An existing workspace without a setup soul gets
45
+ one first, from its owner, by pull request.
46
+ - The Desktop is started on the new deployment, and the TUI is offered.
47
+ - The person types only passwords, logins and tokens, and no secret passes through
48
+ the agent.
49
+
50
+ - `spawnOrigin` now describes the caller independently of lineage: valid
51
+ instance context in this deployment records `instance`; otherwise `operator`,
52
+ including operator spawns with `--parent`. Existing instances keep their
53
+ recorded values, whose older meaning followed the relation. Attribution is
54
+ informational and does not change permissions (#1371).
55
+
56
+ - Desktop: the command palette (⌘K / Ctrl+Shift+K) now shows the sidebar's
57
+ tree, with the sidebar's lines and state dots, ordered by the instance you
58
+ focused most recently. A group or a parent moves up when you focus any
59
+ instance under it, and a child stays under its parent. This replaces the
60
+ flat Recent group. The palette still opens on the agent you were on before,
61
+ and the sidebar keeps its own name order (#1383).
62
+
63
+ - **OATS Desktop accepts an `oats` CLI 0.64.x.** Its band is now
64
+ `>=0.26.0 <0.65.0`. 0.64 adds no new gate on the band: `spawnOrigin` keeps
65
+ its `instance`/`operator` values, which the Desktop passes through without
66
+ reading, and the Desktop already shows a fallback shell as `shell` (#1387).
67
+
68
+ ## Fixed
69
+
70
+ - Shared spawn help now lists the existing `--base <ref>` flag beside `--branch`
71
+ and explains its worktree-only scope and default to the soul commit observed
72
+ by spawn (#1370, #445).
73
+
74
+ - `oats spawn --help` and `oats help` now list the full existing spawn flag
75
+ inventory, including decision replay, scope, launch, child policy and wake
76
+ options, with compatibility and internal inputs labelled. Flag behavior is
77
+ unchanged (#1373).
78
+
79
+ - Status and session inspection now recognize a fallback shell when tmux
80
+ reports an empty or `unset` pane command, so a stopped harness no longer
81
+ appears to be running in that case (#1381).
82
+
83
+ ## Provider updates
84
+
85
+ - **oats.framework 1.13.3: oats.core 2.6.5 and oats.setup 2.8.2.** Text
86
+ only: neither capability's floor (`compatibility.oats`) changes.
87
+ - **`/oats-operate`** says what `spawnOrigin` records from OATS 0.64.0: the
88
+ caller's context (`instance` from a valid instance environment in this
89
+ deployment, otherwise `operator`), independent of the relation. It is
90
+ attribution, not a permission check, and a remote spawn records the
91
+ host side. The skill also says how `--branch` and `--base` choose a
92
+ worktree's branch and start point
93
+ ([#1371](https://github.com/awebai/oats/issues/1371),
94
+ [#1370](https://github.com/awebai/oats/issues/1370)).
95
+ - **oats.setup names the right OATS version for the getting-started entry
96
+ path.** `/oats-setup-expert`, `/oats-setup-model` and the oats.setup
97
+ briefing said the `oats-getting-started` skill writes the setup expert's
98
+ hand-over and creates its soul from OATS 0.62.0. That skill first ships
99
+ in 0.64.0, and they now say so
100
+ ([#1314](https://github.com/awebai/oats/issues/1314)).
101
+
102
+ ## Documentation
103
+
104
+ - `docs/first-team.md` opens with the getting-started skill as the quick
105
+ way; the page remains the manual path.
@@ -0,0 +1,187 @@
1
+ # OATS 0.65.0
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.64 Desktop refuses a 0.65.0 CLI. The
9
+ 0.65.0 Desktop accepts OATS CLIs `>=0.26.0 <0.66.0`. With an older CLI its
10
+ switcher shows the saved workspaces only and says "Update oats".
11
+
12
+ - **No package moves.** The official catalog keeps oats.framework 1.13.3; no
13
+ `oats sync` is needed for this release.
14
+
15
+ - **This computer's deployments list fills itself.** Nothing to run: the
16
+ first kernel command in a deployment lists it, `oats onboard` lists what it
17
+ creates, the first command that touches the list imports `~/Agents` once,
18
+ and the 0.65.0 Desktop's first launch imports its own saved and recent
19
+ workspaces. The Desktop and `oats tui` both read it, and no longer look
20
+ inside `~/Agents`. `oats deployments` shows the list, and
21
+ `oats deployments remove` takes off a row you don't want.
22
+
23
+ - **Coming from 0.61 or earlier:** do 0.62.0's Upgrade steps too (the capture
24
+ service's `oats setup`, once per user on each host, from that user's shell).
25
+
26
+ ## Added
27
+
28
+ - **One list of this computer's deployments, `~/.oats/config/deployments.json`,
29
+ and `oats deployments`** to read and change it
30
+ ([#1390](https://github.com/awebai/oats/issues/1390);
31
+ [This computer's deployments](../workspaces.md#this-computers-deployments)).
32
+ The clients read it to offer the deployments that are not open. It holds
33
+ this computer's deployments only; other machines stay in the server
34
+ registry.
35
+ - **`oats deployments [list] [--json]`** shows each deployment's path, its
36
+ state (`ok`, `missing`, `not-a-deployment` or `unreadable`, from
37
+ existence checks only) and how it was listed. `add [<dir>]` lists the
38
+ deployment at or above `<dir>`; `remove <path>` takes a row off the list
39
+ and touches nothing on disk; `import --from desktop <path>...` is the
40
+ Desktop's one-time import of its own lists. The JSON is in the
41
+ [Desktop CLI API](../desktop-cli-api.md#this-computers-deployments-oats-deployments),
42
+ under the feature `deployments-list`.
43
+ - **The list fills itself.** `oats onboard` lists what it creates (`listed`
44
+ in its result; a failed add never fails the onboard). Any kernel command
45
+ that resolves a deployment that is not listed yet (`status`, `spawn`,
46
+ `sync`, `doctor` and the others that read a deployment) lists it,
47
+ silently. A deployment inside a linked Git worktree or submodule is
48
+ listed by the first command that resolves its instance root (`status`,
49
+ `spawn`, `session` and the like), not by `sync`, `doctor` and the other
50
+ configuration commands. Once it is listed, a command reads the list and
51
+ nothing more: no lock, no write, no process (at most about
52
+ 0.5 ms a command); another spelling of it, a link for example, adds
53
+ one realpath. A busy lock never delays a command, and a command routed
54
+ with `--server` lists nothing.
55
+ - **A removed deployment stays removed.** Nothing automatic lists a path
56
+ `oats deployments remove` took out; `oats deployments add` or
57
+ `oats onboard` brings it back.
58
+ - **`~/Agents` is imported once.** The first command that touches the list
59
+ lists the deployments directly inside `~/Agents` (at most 200 entries, no
60
+ link followed) and records that it did. Nothing reads `~/Agents` again.
61
+ - **Five new codes:** `E_DEPLOYMENTS_INVALID`, `E_DEPLOYMENTS_VERSION`,
62
+ `E_DEPLOYMENTS_BUSY`, `E_DEPLOYMENTS_WRITE` and `E_DEPLOYMENTS_IMPORT`
63
+ (`~/Agents` cannot be read for the first-use import), each saying what
64
+ to do.
65
+
66
+ - Desktop: the TUI's leader. Alt+O on Linux and Windows, ⌃\ on macOS, then
67
+ one key from the TUI's own table: `k` or Space the command palette, `1` `2`
68
+ `3` Instances, Souls and Capabilities, ↑/↓ the terminal of the roster row
69
+ before or after, ←/→ the tabs, `z` focus mode, `w` close the tab, `|` `-`
70
+ the splits, Tab and `x` the split's groups, `X` `R` `S` `D` Stop, Restart,
71
+ Start and Retire, `n` `N` spawn, `/` the filter, `o` the workspace
72
+ switcher, `?` the shortcuts and Esc the instance roster. It works from a
73
+ terminal too: there the leader pressed twice sends the program what the
74
+ chord sends (Alt+O is ESC o, ⌃\ is 0x1c). While it waits, a panel at the
75
+ bottom of the main area lists the keys that apply now. `m` (move a tab to
76
+ the other group) has nothing to act on in the Desktop and is left out. A
77
+ test holds the Desktop's table to the TUI's, so the two cannot drift apart
78
+ ([Desktop keyboard](../../packages/desktop/docs/desktop-keyboard.md#the-leader)).
79
+ - Desktop: the TUI's plain keys in the sidebar. With focus in the sidebar,
80
+ `1` `2` `3`, `w`, `/`, `r`, `z`, `c`, `[` `]`, `|` `-`, `X` `D` `S` `R`,
81
+ `n` `N` and `?` do what they do in the TUI, each rebindable in the
82
+ shortcuts editor; on a roster row `k` `j` `g` `G` `h` `l` and
83
+ PageUp/PageDown move through the tree
84
+ ([Sidebar keys](../../packages/desktop/docs/desktop-keyboard.md#sidebar-keys)).
85
+ - Desktop: help leads with the leader. The shortcuts editor opens on a
86
+ Leader group, the leader's chord and then one row per key after it, which
87
+ its search finds (`alt+o k`), then the sidebar keys. The sidebar footer
88
+ starts with the leader's chord and "commands", a button that starts it.
89
+
90
+ ## Changed
91
+
92
+ - **The Desktop's switcher lists this computer's deployments from the
93
+ kernel's list,** `oats deployments`
94
+ ([#1390](https://github.com/awebai/oats/issues/1390)), and no longer looks
95
+ inside `~/Agents`.
96
+ - **Under "On this computer"** a window with no workspace shows the
97
+ deployments on that list that are not open, beside the saved ones.
98
+ - **A row that can't be opened says why:** missing (the folder is gone, or
99
+ its volume isn't mounted), not a deployment any more, or can't be checked.
100
+ - **Remove** beside a row takes it off the list, and off the Desktop's saved
101
+ workspaces when it is one. Nothing on disk changes. From the keyboard:
102
+ Right Arrow, then Enter.
103
+ - **Every deployment the Desktop opens is listed:** an add, an onboarding,
104
+ and the deployment it was launched on. A failure is a notification, and
105
+ the deployment stays open.
106
+ - **Once, at the first launch,** the Desktop moves its own list of recently
107
+ added workspaces and its saved workspaces onto the list, then renames
108
+ `workspace-recents.json` to `workspace-recents.imported.json`. It reads
109
+ recents for nothing else.
110
+ - **With an older oats,** which has no such list, the switcher shows the
111
+ saved workspaces and says "This oats can't list this computer's
112
+ deployments. Update oats." See [OATS Desktop](../desktop.md#opening-a-workspace).
113
+
114
+ - **`oats tui`'s switcher lists this computer's deployments from the
115
+ kernel's list,** `oats deployments`
116
+ ([#1390](https://github.com/awebai/oats/issues/1390)), and no longer looks
117
+ inside `~/Agents`.
118
+ - **Started outside every deployment** with no `--dir`, it reads the list
119
+ and starts with the switcher when the list holds a row. With none, it
120
+ exits with `E_NO_DEPLOYMENT`, and the line says how to open one
121
+ (`oats tui --dir <path>`) or create one (`oats onboard`). A list that
122
+ can't be read exits with the kernel's own code and message.
123
+ - **Opening a deployment lists it:** the deployment a run starts in, from
124
+ where you are or with `--dir`, is added to the list once. A failure is
125
+ said once, under the sidebar's title, and opens nothing less.
126
+ - **Under "On this machine, not opened"** stand the list's deployments the
127
+ run hasn't opened. A row that can't be opened says why: `Not found.`,
128
+ `Not an OATS deployment any more.` or `Can't be read.`
129
+ - **`Delete` on such a row asks, then removes it from the list,** with
130
+ `Enter`; nothing on disk changes. `tui.json` can give `remove` another
131
+ key. `r` reads the list again.
132
+ - The `More folders than are listed here.` row is gone. See
133
+ [OATS TUI](../tui.md#the-switcher).
134
+
135
+ - **The `oats-getting-started` skill suggests no deployment directory.** It
136
+ asks for `D` and no longer suggests `~/Agents/<workspace>`: from this
137
+ release `oats onboard` lists `D` in this computer's list of deployments, so
138
+ the Desktop and the TUI find it wherever it is
139
+ ([#1390](https://github.com/awebai/oats/issues/1390)). On Linux, the person
140
+ picks `D` in the Desktop's switcher, where it is listed; when it isn't
141
+ (an older Desktop, or a list that could not be written), they add it with
142
+ **Add local workspace… → Browse**.
143
+
144
+ - **OATS Desktop accepts an `oats` CLI 0.65.x.** Its band is now
145
+ `>=0.26.0 <0.66.0`. 0.65 adds no new gate on the band: the Desktop reads
146
+ `oats deployments` only behind its feature `deployments-list`, and does not
147
+ read `listed` on `oats onboard --json`.
148
+
149
+ - Desktop: the command palette (⌘K / Ctrl+Shift+K) now opens on its first
150
+ row, the top of the list, which its last-focus order makes the most recently
151
+ focused path. With a query it opens on the first match. It no longer opens on
152
+ the agent you were on before, which was often a row in the middle of the
153
+ list (#1391).
154
+
155
+ - Desktop: none of the existing default shortcuts changes. A shortcut you set
156
+ yourself that now shares its chord with the leader or a sidebar key is kept
157
+ as it is, and the shortcuts editor shows the clash until you rebind or reset
158
+ one side.
159
+
160
+ - **`oats tui` is one sidebar and the main area, with no header and no
161
+ footer.** An agent's open terminal now spans every row, and zoomed (`z`)
162
+ it has the whole screen. The sidebar starts with the workspace's name and
163
+ what the view holds of other machines. A deployment's state and reason,
164
+ the note of a one-deployment view and the line after an open stand under
165
+ it. The three views follow as an accordion, each with its key: the open
166
+ one's heading with its list under it, and with no instances
167
+ `No agents yet: n spawns one`. A short cheat sheet comes last: the
168
+ leader, the palette, what `Enter` does now, spawn, help and quit; the
169
+ leader's hint, the palette and the help name the other keys. On a narrow
170
+ sidebar a row's name keeps its cells ahead of its word. The filter field
171
+ and a kept filter stand on the open view's heading. The counts and the
172
+ time of the read have left the screen. The help shows that time at its top, with how many rows were
173
+ withheld. From 80 columns the switcher, the palette, the spawn prompt, the
174
+ help and the confirmations cover the main area, and the sidebar stays
175
+ beside them. Under 80 columns they cover the whole screen, with their keys
176
+ on their first row, as the detail does
177
+ ([docs/tui.md](../tui.md#what-it-shows)).
178
+
179
+ - **The leader is `Alt+O` on Linux and Windows.** `Ctrl+\` was a stretch on
180
+ most keyboards and needs AltGr on many layouts. macOS keeps `Ctrl+\` for
181
+ now. `open.detachKey` in `tui.json` still names another key, `C-\`
182
+ among them. `Alt+O` counts as the leader only when it arrives as one
183
+ keypress: an `Esc` then `o` typed as two keys reaches the agent unchanged.
184
+ The leader pressed twice now types it into the terminal that has the
185
+ focus, and the leader then `Esc` gives the list the focus. The cheat
186
+ sheet and the help name keys as people read them: `Alt+O`, `Ctrl+K`,
187
+ `Enter` ([docs/tui.md](../tui.md#the-leader)).
@@ -306,6 +306,12 @@ soul would, run it from the deployment with `OATS_INSTANCE_HOME` and
306
306
 
307
307
  ### Spawn
308
308
 
309
+ `oats spawn --help` lists the existing spawn flags and their conditions; the
310
+ spawn section of `oats help` contains the same inventory. Both work outside a
311
+ deployment. Compatibility and internal inputs are labelled, including the
312
+ locally refused legacy instance selector. For preview confirmation and receipt
313
+ replay, see the [spawn decision and apply contract](desktop-cli-api.md#the-decision).
314
+
309
315
  ```bash
310
316
  oats spawn release-manager --purpose cut-3.2 --task "…" # a soul of a confirmed member
311
317
  oats spawn release-manager --preview --json # decide everything, create nothing
@@ -384,8 +390,7 @@ Spawn lineage is **explicit** and relation-based:
384
390
  declares what the new instance IS to an existing one (`--parent <instance>` is
385
391
  sugar for `--relative-to <instance> --relation child`):
386
392
 
387
- - **child**: nests under the anchor: `parentInstance` = anchor,
388
- `spawnOrigin: instance`.
393
+ - **child**: nests under the anchor: `parentInstance` = anchor.
389
394
  - **parent**: the NEW instance becomes the anchor's parent: it inherits the
390
395
  anchor's old lineage slot, and the anchor's `instance.json` is re-pointed so
391
396
  its `parentInstance` is the new instance (a reviewer/maintainer of your work
@@ -400,15 +405,27 @@ sugar for `--relative-to <instance> --relation child`):
400
405
  when one exists; when the anchor is a root, the new instance records an
401
406
  explicit `siblingInstance` link so the cluster is still derivable from
402
407
  `oats status --json` (`parentInstance` + `siblingInstance` edges).
403
- - **unrelated** (default): no link, operator-origin, top-level.
408
+ - **unrelated** (default): no link, top-level.
404
409
 
405
410
  Attached-mode spawns are ALWAYS children of the owner of the shared work tree
406
411
  (the instance in whose home the tree is, as its `work/` or as one of its
407
412
  extra trees: see [`attached`](#attached--another-instances-tree)),
408
413
  because an attached agent serves that owner; relation flags other than a
409
- redundant child-of-owner are rejected. Any other spawn, including one from a
410
- shell that inherited an agent's environment variables, is operator-origin and
411
- appears top-level.
414
+ redundant child-of-owner are rejected.
415
+
416
+ `spawnOrigin` records the caller independently of these links. For new spawns
417
+ from OATS 0.64.0, it is `instance` when the caller's `OATS_INSTANCE` and/or
418
+ `OATS_INSTANCE_HOME` resolve consistently to an extant home in this deployment;
419
+ otherwise it is `operator`. A stopped home counts. A shell, Desktop or console
420
+ caller without that context records `operator` even with `--parent`; an instance
421
+ caller records `instance` even without a relation. A shell inheriting valid
422
+ instance context also records `instance`. This is informational attribution,
423
+ not a security boundary or a permission check. Existing instances keep their
424
+ recorded value, including the relation-based meaning recorded by older kernels.
425
+ For a remote spawn (`--server`), attribution uses the host-side caller context;
426
+ caller identity is not forwarded, so the origin is normally `operator`.
427
+ See [the caller resolution rules](desktop-cli-api.md#spawn-origin).
428
+
412
429
  Agents spawning sub-agents should pass `--parent "$OATS_INSTANCE"` (or the
413
430
  relation that fits).
414
431
 
@@ -1623,6 +1640,9 @@ as `--repo`, then `oats-local.yaml` `clones:`, then `<deployment>/<member name>`
1623
1640
  (`E_CLONE_MISSING` / `E_CLONE_MISMATCH` otherwise — see
1624
1641
  [configuration.md](configuration.md)).
1625
1642
 
1643
+ `--branch <b>` overrides the branch name; `--base <ref>` overrides its start
1644
+ point. These options apply to worktree mode.
1645
+
1626
1646
  The branch starts at the commit of the soul's repository that the spawn
1627
1647
  observed (the one it resolved the soul at), not at what the clone has checked
1628
1648
  out: the clone may be a human's checkout or a shared reference, far behind.