@awebai/oats 0.69.12 → 0.69.14

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 (70) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +176 -184
  3. package/docs/capabilities.md +4 -1
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +246 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +376 -37
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +69 -6
  11. package/docs/implementation.md +86 -29
  12. package/docs/integrations.md +3 -2
  13. package/docs/knowledge-and-learning.md +72 -0
  14. package/docs/oats-local.schema.json +11 -2
  15. package/docs/official-catalog.md +39 -5
  16. package/docs/packages.md +93 -14
  17. package/docs/release-lane.md +2 -1
  18. package/docs/release-notes/v0.69.13.md +767 -0
  19. package/docs/release-notes/v0.69.14.md +83 -0
  20. package/docs/schedules.md +26 -3
  21. package/docs/servers.md +181 -5
  22. package/docs/souls-and-instances.md +140 -11
  23. package/docs/tui.md +1 -1
  24. package/docs/upgrading.md +24 -5
  25. package/docs/workspaces.md +31 -5
  26. package/lib/claim.mjs +21 -5
  27. package/lib/command-flags.mjs +238 -0
  28. package/lib/core.mjs +791 -563
  29. package/lib/deployments.mjs +4 -3
  30. package/lib/dir-lock.mjs +126 -31
  31. package/lib/errors.mjs +1 -1
  32. package/lib/harness-token.mjs +110 -0
  33. package/lib/hot-reads.mjs +4 -3
  34. package/lib/instance-events.mjs +28 -6
  35. package/lib/instance-git.mjs +138 -13
  36. package/lib/instance-inspect.mjs +6 -1
  37. package/lib/instance-listing.mjs +80 -38
  38. package/lib/instance-resolution.mjs +56 -3
  39. package/lib/instance-upgrade.mjs +16 -20
  40. package/lib/launch-env-exec.sh +7 -0
  41. package/lib/launch-env.mjs +74 -0
  42. package/lib/launch-preference.mjs +19 -12
  43. package/lib/member-clone.mjs +7 -1
  44. package/lib/packages.mjs +74 -2
  45. package/lib/read-call.mjs +3 -0
  46. package/lib/reader.mjs +3 -2
  47. package/lib/refused-text.mjs +3 -2
  48. package/lib/remote.mjs +119 -27
  49. package/lib/retained-after-retire.mjs +2 -7
  50. package/lib/retire-git-forms.mjs +41 -0
  51. package/lib/retire-incomplete.mjs +96 -0
  52. package/lib/schedule.mjs +2 -1
  53. package/lib/servers.mjs +78 -23
  54. package/lib/session-resume.mjs +68 -53
  55. package/lib/session-seen.mjs +54 -5
  56. package/lib/start-env.mjs +13 -7
  57. package/lib/system-tools.mjs +1 -1
  58. package/lib/teams.mjs +11 -4
  59. package/lib/upgrade-state.mjs +13 -2
  60. package/lib/worktree.mjs +56 -7
  61. package/package-catalog.json +1 -1
  62. package/package.json +2 -1
  63. package/packages/client/instance-lifecycle.mjs +1 -1
  64. package/packages/client/lifecycle-contract.mjs +3 -1
  65. package/packages/client/session-resume-cli.mjs +2 -1
  66. package/packages/client/session-start.mjs +10 -7
  67. package/packages/client/workspace-cli.mjs +5 -1
  68. package/share/oats-login-receive +204 -0
  69. package/skills/oats-getting-started/SKILL.md +92 -25
  70. package/lib/tmux-config.mjs +0 -35
@@ -0,0 +1,83 @@
1
+ # OATS 0.69.14
2
+
3
+ 0.69.14 publishes what 0.69.13 carried: the tag v0.69.13 was cut, but its
4
+ release workflow stopped before publication (the Desktop's Linux launch
5
+ check lacked the root dependencies), so no 0.69.13 reached npm or GitHub
6
+ Releases. Everything in the [0.69.13 notes](v0.69.13.md) ships here, with
7
+ the workflow fixed and the rest of the state-changing commands refusing a
8
+ flag they do not define.
9
+
10
+ ## Upgrade
11
+
12
+ - **Read the [0.69.13 Upgrade section](v0.69.13.md#upgrade) first:** its
13
+ steps are this release's too, since 0.69.13 was never published.
14
+ - **Either order of the Desktop and the CLI works.**
15
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
16
+ installed the CLI first is fine too: the 0.69.14 Desktop accepts OATS CLIs
17
+ `>=0.26.0 <0.70.0`, as the 0.69.12 and 0.69.11 Desktops do.
18
+ - **Package pins** are 0.69.13's: oats.framework 1.23.0, oats.okf 5.8.0 and
19
+ oats.aweb 1.37.0.
20
+
21
+ - **A flag these commands never defined is now refused, where it was
22
+ ignored** (oats-project/oats#1824). A typo of a real flag is now refused
23
+ before anything happens: `oats schedule host install --prnt` installed the
24
+ host timer and `oats schedule tick --dry-rn` ran the tick; both are now
25
+ refused with `E_BAD_ARGS`. Check scripts and schedules that call `oats
26
+ instance`, `oats schedule`, `oats trigger`, `oats session`, `oats server
27
+ check` or `oats update`: what is now refused is listed under Fixed below,
28
+ and the flags each command defines in
29
+ [The flags a command defines](../desktop-cli-api.md#command-flags).
30
+
31
+ ## Fixed
32
+
33
+ - **The rest of the commands that change state refuse a flag they do not
34
+ define** (oats-project/oats#1791, after #1813). These read the flags they
35
+ knew and ignored every other one: `oats instance color`, `background`,
36
+ `same-work`, `waiting set|clear` and `attention`; `oats schedule add`,
37
+ `update`, `tick` and `host install`; `oats trigger add`, `poll` and
38
+ `test`; `oats session input`, `receive`, `upload` and `attach`; `oats
39
+ server check`; and `oats update`. A typo of one of their flags did the
40
+ thing without it: `oats schedule host install --prnt` installed the host
41
+ timer where `--print` only prints its files, and `oats schedule tick
42
+ --dry-rn` ran the tick.
43
+ - Each of them now refuses, with `E_BAD_ARGS` and before anything
44
+ happens, a flag it does not define, a value given with `=` to one of its
45
+ switches, and an argument after the last one it takes, with the same
46
+ words as the commands of #1813 (`oats schedule tick: unknown flag
47
+ --dry-rn` and the usage line; `error.details.flag` or
48
+ `error.details.argument`). A routed one (`--server`) missing an argument
49
+ it requires is `E_USAGE` here, and nothing is sent.
50
+ - A script that passes one of these commands a flag it never defined gets
51
+ the refusal where the flag was ignored: remove the flag. Among them:
52
+ `--dir` on `oats session input`, `receive`, `upload` and `attach` (they
53
+ take `--home`), `--server` on `oats trigger add`, `poll` and `test`
54
+ (which have no route), `--clear` on `oats instance waiting` (it is
55
+ `oats instance attention`'s), and anything after `oats update`'s own
56
+ flags. `--server` on `oats instance waiting`, `oats instance attention`,
57
+ `oats session input` and `oats session receive`, which have no route, is
58
+ `E_BAD_ARGS`, unknown flag, where it was `E_USAGE` from the router. The flags each command defines
59
+ are listed in
60
+ [The flags a command defines](../desktop-cli-api.md#command-flags).
61
+ - **The commands that already refused a flag they do not read check it in
62
+ the same place**: `oats spawn`, `oats sync`, `oats session resume`, `oats
63
+ instance suggest-name`, `oats teams` and `oats soul launch set|remove`.
64
+ Their answers keep their words: `oats teams` and `oats soul launch` still
65
+ answer `E_USAGE {flag}`, `oats spawn` its own `unknown flag` and
66
+ capability-setting words. What changed:
67
+ - `oats spawn --instructions-file`, `--def-file` and `--ephemeral` are
68
+ refused in their own words on a `--server` spawn too, where they were an
69
+ unknown flag, and carry `error.details.flag`. `oats spawn <soul> -x` is
70
+ `oats spawn: unknown flag -x`, where it was an unexpected argument.
71
+ - `oats instance suggest-name` says `unknown flag <flag>` with the usage
72
+ line and `error.details.flag`, where it said `unexpected flag "<flag>"`;
73
+ `oats session resume`'s refusal carries `error.details.flag` or
74
+ `error.details.argument`, and an argument is `unexpected argument
75
+ "<word>": session resume takes no argument`. `oats sync <word>` is
76
+ `sync takes no argument`, where it said `sync takes no positional`.
77
+ - `oats teams add|remove|default <label> <word>` refuses the second word,
78
+ which it ignored; `oats teams --dir <d> add <label>` (a flag before the
79
+ form) is refused with the forms' usage, where it listed the teams.
80
+ - `oats instance background|same-work <instance> on off` is `unexpected
81
+ argument "off" after the state "on"`, where it said `give on or off`.
82
+
83
+ - **The release workflow installs the root dependencies before the Desktop's Linux launch check.** The packaged-window launch phase (#1757) onboards a fixture deployment with this repository's kernel. `release.yml`'s Desktop job installed only `packages/desktop`'s dependencies, so on the v0.69.13 tag the Linux leg failed (`Cannot find package 'yaml'`) and nothing was published. The pull-request workflow, `build-installers.yml`, already installed both. The release now installs them on the Linux leg after packaging, just before the launch, so the Desktop suite and packaging still run with the Desktop's dependencies alone. `test/release-workflow.test.mjs` requires each workflow to install the root dependencies before the launch, and `test/continuous-integration.test.mjs` allows that one root install and no other.
package/docs/schedules.md CHANGED
@@ -44,9 +44,32 @@ The design is in the
44
44
  | `<deployment>/.agents/schedules/` | Run state: `state.json` (last minute and recent runs per job), `triggers.json` (polls, pending events, fired keys) and one lock directory per running job. |
45
45
  | `~/.oats/schedules/registry.json` | The deployments this host ticks, `maxConcurrent` (absent: default 5 running scheduled jobs) and `triggersMaxConcurrent` (absent: no host cap on trigger-spawned live instances). The two caps are separate. |
46
46
 
47
- One host lock serializes ticks, run-now, reconcile and remove. It is never
48
- reclaimed by another process: a lock whose owner is gone is reported with the
49
- directory to remove.
47
+ One host lock, `~/.oats/schedules/host.lock`, serializes ticks, run-now,
48
+ reconcile and remove. Changes to the registry hold
49
+ `~/.oats/schedules/registry.lock`, and changes to a deployment's definitions
50
+ and state hold `<deployment>/.agents/schedules/scope.lock`. Each is a file that
51
+ names the process holding it, by its pid and the time it started.
52
+
53
+ **A lock left by a command that was killed is taken over by the next
54
+ command.** A tick that is killed, or lost in a reboot, while it holds the host
55
+ lock therefore does not stop the scheduler: the next tick finds that the
56
+ process the file names is gone, takes the lock and runs. A holder that is
57
+ still running is never taken over: the command answers `E_SCHEDULER_BUSY`
58
+ (`pid <n> holds it`), and nothing was changed.
59
+
60
+ Three cases are left to the operator. Each is `E_SCHEDULER_BUSY`, the message
61
+ says which it is and names the path, and nothing at that path is removed for
62
+ you:
63
+
64
+ | The message says | What is there | What to do |
65
+ |---|---|---|
66
+ | `the record at <path> is unreadable` | a file that is not a lock's record | remove that file once no `oats schedule` process is running |
67
+ | `whether pid <n>, which holds it, still runs cannot be established` | a record whose process cannot be told from another with the same pid (the record has no start time, or this host cannot read one) | check pid `<n>` by hand; if it is not an `oats schedule` process, remove the lock file |
68
+ | `<path> is a lock directory written by an earlier kernel` | a directory, the lock of an oats older than this one | if an older oats is still running a schedule command, wait for it; otherwise remove the directory |
69
+
70
+ A lock whose holder is gone and whose record cannot be taken over (a record
71
+ without the identifier a takeover needs) is reported the same way, with the
72
+ file that must be removed.
50
73
 
51
74
  ## Kinds
52
75
 
package/docs/servers.md CHANGED
@@ -18,6 +18,39 @@ oats server remove build
18
18
  To put a workspace on a machine that has no deployment yet, use
19
19
  [`oats server connect`](#connect-a-machine) instead of `server add`.
20
20
 
21
+ `server add` and `server connect` also accept `--operator-ssh <alias>`.
22
+ It records the optional operator route separately in
23
+ `~/.oats/server-operator-routes.json`:
24
+
25
+ ```json
26
+ { "build": { "operatorSshHost": "build-operator" } }
27
+ ```
28
+
29
+ `server list` (text and JSON) and connect's `registration` join that route
30
+ with the server registration. The alias follows the same rules as `--ssh`:
31
+ letters, digits, dot, underscore and dash, beginning with a letter or digit;
32
+ no `user@host`, spaces or SSH options. Put the user and forced-command key in
33
+ OpenSSH configuration under that alias. Registrations without it remain valid.
34
+ Older kernels never read this separate file; `servers.json` retains the field
35
+ set they accept.
36
+
37
+ The operator alias is reserved for credential provisioning. Registering it
38
+ runs no operator command: every existing remote operation continues to use
39
+ `sshHost`, and saved instance targets contain no operator route. To change an
40
+ existing registration, pass `--replace`; connect keeps an existing value
41
+ without it. With `--replace`, the operator route is kept unless you give
42
+ `--operator-ssh <alias>` to change it or `--no-operator-ssh` to clear it.
43
+ The two flags cannot be combined. `server remove` deletes the operator route
44
+ too. Both files are changed under the same `~/.oats/servers.lock`.
45
+ A fresh add or connect starts with no operator route unless `--operator-ssh`
46
+ is given; a route left behind by an older kernel is discarded for that new
47
+ registration.
48
+ For example:
49
+
50
+ ```bash
51
+ oats server add build --ssh build-host --operator-ssh build-operator --workspace /srv/team
52
+ ```
53
+
21
54
  - `--ssh` is an OpenSSH host alias or host name, never `user@host` or an
22
55
  option. Users, keys and host verification belong in `~/.ssh/config`.
23
56
  Connections are non-interactive (`BatchMode=yes`): a prompt fails fast.
@@ -36,10 +69,14 @@ To put a workspace on a machine that has no deployment yet, use
36
69
  - Registrations live in `~/.oats/servers.json` on this machine, never in a
37
70
  repository. Every change to the file (add, remove, a learned workspace key,
38
71
  connect) is a short read-modify-write of the file as it is then, under the
39
- lock directory `~/.oats/servers.lock`, so concurrent commands never lose each
40
- other's registrations. A lock still held after 5 s, or left by a process
41
- that died, is refused with `E_SERVERS_BUSY`, naming the directory to remove
42
- once no oats process is changing the registry.
72
+ lock `~/.oats/servers.lock`, so concurrent commands never lose each
73
+ other's registrations. The lock is a file that names the process holding it.
74
+ One left by a command that was killed is taken over by the next command. One
75
+ whose holder is still running after 5 s is refused with `E_SERVERS_BUSY`. So
76
+ are a lock file whose record is unreadable, a holder that cannot be told to
77
+ be running or gone, and a lock directory written by an earlier kernel: the
78
+ message says which it found and names the path to remove once no oats
79
+ process is changing the registry.
43
80
 
44
81
  **Which workspace a server serves.** A registration records `workspaceKey`:
45
82
  the canonical key of the workspace its host deployment realizes, as the
@@ -54,7 +91,8 @@ never typed:
54
91
  - A key is recorded only on the registration that was asked: if the
55
92
  registration is removed or pointed elsewhere while the host is being asked,
56
93
  the answer is dropped (`server add` warns), never written onto the new
57
- entry or used to bring a removed one back.
94
+ entry or used to bring a removed one back. The add result reports no
95
+ workspace key when the registration changed during the request.
58
96
  - A host reporting a different key than the recorded one is
59
97
  `E_SERVER_WORKSPACE_MISMATCH` (`details: {recorded, reported}`) and the
60
98
  registration is not rewritten. If the host now serves another workspace,
@@ -68,6 +106,143 @@ never typed:
68
106
  (`workspaceReadable`; the host's [`onboard --check`](#what-connect-runs-on-the-host)),
69
107
  which is where a [macOS keychain](#git-on-a-macos-host) problem shows up.
70
108
 
109
+ ## Harness credentials
110
+
111
+ Install, inspect or remove a harness credential through the operator route:
112
+
113
+ ```bash
114
+ credential-source | oats harness token set claude --server build --name team --stdin
115
+ oats harness token status claude --server build --name team
116
+ oats harness token remove claude --server build --name team
117
+ ```
118
+
119
+ Here `credential-source` stands for a command that supplies an existing
120
+ credential on stdout without putting it in arguments, files or terminal
121
+ output elsewhere. OATS never accepts the credential as an argument or writes
122
+ it on this machine. `--stdin` refuses a terminal, whose normal echo would
123
+ show the value.
124
+
125
+ The harness is `claude`, `codex`, `pi` or `opencode`. `--name` is the
126
+ receiver's configured team name: lowercase letters, digits and dashes,
127
+ starting with a letter or digit, at most 63 characters. When omitted, the
128
+ server label is used only if it already matches that grammar; otherwise
129
+ give `--name`. OATS never guesses a slug from a display label.
130
+
131
+ These commands use the separate operator SSH alias and its forced-command
132
+ receiver, with the usual noninteractive SSH options and `ControlPath=none`.
133
+ They never reuse the agent connection or fall back to the agent alias.
134
+ An unknown server id refuses before SSH, even if an orphan operator route exists.
135
+ Without an operator route, OATS refuses with `E_HARNESS_TOKEN_ROUTE` and
136
+ prints a complete `oats server add <id> --ssh <agent-alias> --workspace <path>
137
+ --operator-ssh <alias> --replace` remedy, preserving the registration's
138
+ existing `--label`, `--oats` and `--path` values. Replace `<alias>` with the
139
+ operator alias; `oats server list --json` shows the current registration.
140
+ The receiver answers only a fingerprint and replacement time; it never
141
+ returns a credential. Removal deletes the delivered credential file; revoke
142
+ the original credential with its provider too.
143
+
144
+ The forced command is `oats-login-receive`, installed root-owned
145
+ and bound to a dedicated key. It accepts `install|status|remove <harness> <name>`
146
+ through `SSH_ORIGINAL_COMMAND`; the destination is the receiver's root-owned
147
+ configuration, never a client-supplied path. See the
148
+ [CLI JSON contract](desktop-cli-api.md#harness-token) and
149
+ [receiver installation](#install-the-credential-receiver).
150
+
151
+ `set` maps to the receiver's `install`, with the credential on stdin. The
152
+ receiver writes atomically to its configured root-owned file, normally
153
+ `/srv/oats-team/<name>/login/<harness>-token`, readable by the agent group
154
+ and not writable by it. OATS validates the returned fingerprint against the
155
+ bytes it sent. Re-running `set` rotates the file; sessions keep their
156
+ current credential until their next start. The output lists instances of the
157
+ same harness on that server whose last start predates or falls within the
158
+ reported replacement second. The receiver records whole seconds, so sessions
159
+ started during that second may still have read the previous credential.
160
+ It never restarts them. If listing fails after installation, the command
161
+ still succeeds, with a warning and an unknown older-session list.
162
+
163
+ Input is at most 65,536 bytes of strict UTF-8. Leading and trailing ASCII
164
+ whitespace is stripped as the receiver strips it; the result must be one
165
+ non-empty line, contain no NUL, and fit in 65,535 bytes so the installed final
166
+ newline fits the 64 KiB file-reference cap. Claude tokens must begin
167
+ `sk-ant-oat` and fit in 512 bytes, matching the receiver's check. Other
168
+ harness inputs are opaque provider API keys.
169
+
170
+ | Harness | Credential supplied through stdin | Agent launch binding | Login and revocation |
171
+ |---|---|---|---|
172
+ | Claude | inference-only setup-token | `CLAUDE_CODE_OAUTH_TOKEN` with `fromFile` | Created on the person's machine; revoke by signing the session out in claude.ai settings |
173
+ | Codex | non-refreshing OpenAI API key | `OPENAI_API_KEY` with `fromFile` | Obtain and revoke on the provider's key page |
174
+ | pi | non-refreshing provider API key | the provider's env variable, such as `ANTHROPIC_API_KEY`, with `fromFile` | Provider-specific key page |
175
+ | opencode | opaque provider API key | provider binding must be configured separately; OATS does not choose one | Provider-specific key page |
176
+
177
+ OATS runs no harness login for this stdin path. Claude interactive capture
178
+ is unavailable. Codex ChatGPT sign-in and pi OAuth are refused: their credentials
179
+ refresh on the agent host and rewrite an auth file, which does not fit a
180
+ read-only operator-delivered credential. No interactive opencode adapter is
181
+ available. For pi, `--name` is the team, not a provider selection. Configure
182
+ the provider's launch environment yourself; these commands never edit launch
183
+ configurations. See [file references](configuration.md#launch-configurations).
184
+
185
+ `--debug` prints SSH exit and known transport error codes on stderr.
186
+ It never forwards receiver stdout or raw diagnostics: an unexpected peer
187
+ could echo all or part of its stdin. Public failures distinguish an unreachable
188
+ server, a receiver refusal and an unexpected reply without exposing a value.
189
+
190
+ ### Install the credential receiver
191
+
192
+ The npm package ships `share/oats-login-receive`. On the receiving server,
193
+ its installed path is
194
+ `$(npm root -g)/@awebai/oats/share/oats-login-receive`. The receiver requires
195
+ Python 3 at `/usr/bin/python3`; its shebang runs Python in isolated mode (`-I`).
196
+ After installing OATS on that server, install the receiver as root, mode 0755:
197
+
198
+ ```bash
199
+ sudo install -d -o root -g root -m 0755 /usr/local/sbin /etc/oats-login
200
+ sudo install -o root -g root -m 0755 \
201
+ "$(npm root -g)/@awebai/oats/share/oats-login-receive" \
202
+ /usr/local/sbin/oats-login-receive
203
+ sudoedit /etc/oats-login/receiver.json
204
+ ```
205
+
206
+ The root-owned `/etc/oats-login/receiver.json` selects the allowed teams,
207
+ read groups, harnesses and destinations. This is the format from the
208
+ receiver's docstring, with a concrete team and group:
209
+
210
+ ```json
211
+ {
212
+ "teams": {
213
+ "team": {
214
+ "group": "oats-team",
215
+ "harnesses": ["claude", "codex", "pi", "opencode"],
216
+ "path": "/srv/oats-team/{name}/login/{harness}-token"
217
+ }
218
+ }
219
+ }
220
+ ```
221
+
222
+ Replace `team` and `oats-team` with the receiver's configured team name and
223
+ an existing group whose members may read its credentials. `path` is optional;
224
+ the default is `/srv/oats-team/{name}/login/{harness}-token`. Keep both the
225
+ configuration file and `/etc/oats-login` root-owned and not writable by group
226
+ or others:
227
+
228
+ ```bash
229
+ sudo chown root:root /etc/oats-login/receiver.json
230
+ sudo chmod 0644 /etc/oats-login/receiver.json
231
+ ```
232
+
233
+ Add the dedicated operator public key to root's `authorized_keys` with this
234
+ forced command, replacing `<key>` with that public key:
235
+
236
+ ```text
237
+ restrict,command="/usr/local/sbin/oats-login-receive" <key>
238
+ ```
239
+
240
+ The operator SSH alias selects that key and the root account. The agent SSH
241
+ alias uses its separate account and key. The receiver creates credential
242
+ files root-owned, group-readable and mode 0440; the login directory is mode
243
+ 0750, and its parents must be root-owned, not writable by others and not
244
+ symlinks. Neither the caller's command nor stdin chooses a destination path.
245
+
71
246
  ## Connect a machine
72
247
 
73
248
  ```bash
@@ -84,6 +259,7 @@ missing, so after a human step you run the same command again.
84
259
  | `--dir <path>` | none, inside a deployment too: the folder on the host for this deployment, absolute or `~/…` (resolved by the host). Without it: `E_BAD_ARGS` "--dir <path on the host> is required: the folder on `<host>` for this deployment (absolute, or ~/… resolved there)". A registration made before it was required is unchanged |
85
260
  | `--workspace-ref <ref>` | this deployment's `oats-local.yaml` `workspace:` |
86
261
  | `--oats <path>`, `--path <dirs>`, `--label <text>` | as for `server add`; `--path` is where the host finds `npm`, `oats` and the harnesses. Without it, connect uses the PATH of the host user's [login shell](#the-hosts-login-shell-path) |
262
+ | `--operator-ssh <alias>`, `--no-operator-ssh` | set or clear the separate operator route; with `--replace`, omitting both keeps it. Same alias validation as `--ssh` |
87
263
  | `--install-oats` | off: a missing or older OATS is a human step |
88
264
  | `--replace` | off: an id registered for another host or directory is refused |
89
265
 
@@ -107,7 +107,9 @@ souls, and keeping its messages to other instances few and short:
107
107
  `oats.core: off`. **`oats.setup`** (same package) carries the whole-architecture
108
108
  knowledge an onboarding expert needs, **`oats.onboarding`** (same package)
109
109
  is how the package soul `oats-setup-expert` tailors a new workspace to its use
110
- case, and **`oats.support`** (same package)
110
+ case, **`oats.coordination-setup`** (same package) is how it shapes OATS's
111
+ coordination practices to that organisation, and **`oats.support`** (same
112
+ package)
111
113
  is the support desk role: a publicly reachable soul that tickets requests and
112
114
  hands them to a support maintainer. None of them is kernel magic; the kernel still
113
115
  composes its own instance-boundary and work-mode briefings, and the "You run
@@ -531,6 +533,20 @@ takes a final capture of notes and the session record into durable custody; an
531
533
  incomplete capture keeps the home for a retry. Retirement never waits for a
532
534
  model or GitHub: processing continues after the home is gone.
533
535
 
536
+ A retire hook's warning, such as an action someone must still take, is in the
537
+ retire's `warnings` and stays readable after the home is gone: each one is a
538
+ `retire-warning` event in the instance's workspace log, read with
539
+ `oats instance events <instance>` ([Events](desktop-cli-api.md#events)).
540
+
541
+ `oats retire <instance>` reads these flags: `--plan`, `--plan-revision <rev>`
542
+ with `--idempotency-key <key>`, `--home <path>`, `--dir <d>`, `--server <id>`,
543
+ `--self`, `--discard-worktree`, `--keep-dir`, `--force` and `--json`. Any
544
+ other flag, and any argument after the instance, is refused with `E_BAD_ARGS`
545
+ before anything happens: before a plan is read, a child is stopped, a hook
546
+ runs, or a routed retire is sent to its server. The refusal names the flag
547
+ (`oats retire: unknown flag --keep-dirs`) and prints the usage, so a mistyped
548
+ `--keep-dir` never removes the home.
549
+
534
550
  One retire of an instance runs at a time. A retire holds the instance's claim
535
551
  from the moment it has resolved the home until it ends: the file
536
552
  `.oats-retirement/claims/<instance>.lock` in the agent's instances directory,
@@ -700,9 +716,60 @@ them, and without them a status can read differently (a global
700
716
  `core.excludesFile`, `core.autocrlf`, a filter), which would add a copy
701
717
  attempt to every existing instance's retire. They are the operator's own;
702
718
  what the retire guards against is configuration the retired agent could
703
- write. One limit remains: a filter driver that the repository's own
704
- configuration names and its `.gitattributes` select can still run during
705
- `git status`. Turning it off would change what status reports.
719
+ write.
720
+
721
+ <a id="retire-filter-drivers"></a>
722
+ **Filter drivers of the repository are not run.** Git runs a
723
+ `filter.<name>.clean` or `.process` command when a status compares a
724
+ work-tree file that carries the `filter` attribute (`.gitattributes`, or
725
+ `info/attributes` in the Git directory), and it has no switch that turns
726
+ filters off. Before each `git status` of the worktree, of a repository under
727
+ it and of a recovery, and before a recovery's `git checkout`, the retire
728
+ reads the repository's own configuration (`git config --list`, which runs
729
+ nothing and follows `include.path` and `includeIf`) and overrides every
730
+ filter driver it defines to no command (`clean`, `smudge`, `process`) and
731
+ not required. The status the spawn baseline is taken from is read the same
732
+ way.
733
+
734
+ - A file such a filter applies to is compared as its bytes are in the work
735
+ tree, not as the filter would store them. An untouched file still reads as
736
+ unchanged, by the size and times the index recorded for it. One that was
737
+ rewritten, or whose times Git cannot tell from the index's, reads as
738
+ changed even when its filtered form is what is stored: it is work to
739
+ preserve, the retire copies it, and a worktree holding it is not removed
740
+ as a clean one.
741
+ - A driver whose name cannot be passed on Git's command line (it holds `=`
742
+ or is not UTF-8) cannot be overridden. Git is not run, and the status has
743
+ failed: the retire refuses with `E_WORK_INSPECTION_FAILED` at its first
744
+ inspection, as for any [status that fails](#retire-status-fails), with
745
+ `--discard-worktree` and `--force` too. A spawn into a worktree of such a
746
+ repository is refused the same way and rolled back. Remove or rename the
747
+ driver in the repository's configuration, then retry.
748
+ - A driver that the operator's global or system configuration defines is
749
+ the operator's own and runs with the operator's command, in the worktree
750
+ and in the recovery alike. That holds when the repository's configuration
751
+ defines a driver of the same name too (`git lfs install --local` beside
752
+ `git lfs install`): the repository's values for it are replaced by the
753
+ operator's, so a command the repository gives that name never runs. The
754
+ operator's configuration is the human's; the repository's is the agent's
755
+ to write.
756
+ - The recovery has no local configuration, so it has none of the
757
+ repository's drivers. Its status must still be the worktree's, and for a
758
+ file such a filter applies to it can differ: the worktree reads an
759
+ untouched file as unchanged by the size and times its index recorded,
760
+ while the copy, whose files are written anew, compares its bytes with the
761
+ stored form. The copy then cannot be verified: the retire refuses with
762
+ `E_WORK_PRESERVATION_FAILED` and removes nothing. This is so only for a
763
+ driver the repository alone defines.
764
+ - Not covered: a driver written into the configuration between that read
765
+ and the Git command that follows it, and a filter a **submodule's own**
766
+ configuration defines. Git runs inside each populated submodule to learn
767
+ whether it is dirty, and the overrides name the repository's drivers, not
768
+ the submodule's. Where the agent and whoever retires it are one system
769
+ user, which is the usual arrangement, such a filter runs nothing the agent
770
+ could not run itself. Where they are separate users, it runs the agent's
771
+ command as the retiring user: do not retire a worktree with populated
772
+ submodules across users.
706
773
 
707
774
  **A worktree whose top level is another directory.** A worktree's
708
775
  per-worktree configuration can set `core.worktree` to a directory other
@@ -961,6 +1028,7 @@ That changes no digest and no error, and it is bounded: at most four files
961
1028
  are read at once, each through a 1 MiB buffer, and never more than 64 MiB or
962
1029
  4096 files ahead of the digest.
963
1030
 
1031
+ <a id="retire-status-fails"></a>
964
1032
  A worktree whose `git status` fails refuses the retire with
965
1033
  `E_WORK_INSPECTION_FAILED` at the first inspection: no recovery was written,
966
1034
  nothing was deleted, and the retire has not stopped the instance's session.
@@ -1245,9 +1313,48 @@ leaves what happened on disk (OATS 0.53.0):
1245
1313
  - **One event,** `retire-refused`, which says which of the two it was
1246
1314
  ([Events](desktop-cli-api.md#retire-refused-event)).
1247
1315
 
1248
- Nothing retries by itself: `oats retire <instance>` does. A completion
1249
- removes only the marker of its own scheduling, so the marker of a later
1250
- `--self` is left for that one's completion.
1316
+ <a id="self-retire-hook-retry"></a>**A completion retries a cleanup that only
1317
+ retire hooks left incomplete** (oats-project/oats#1747), because a provider's
1318
+ failure is often transient. When the retire ends with the home quarantined,
1319
+ and what it owes is retire hooks and nothing else, the completion runs the
1320
+ same retire again: up to three times, about 1, 5 and 15 minutes after each
1321
+ failed attempt. Every attempt is an ordinary retire of the home, under its
1322
+ claim. Its quarantine retry clears only once the owed hooks are shown to have
1323
+ run.
1324
+
1325
+ - **A retry whose hooks pass ends as a first success does.** The home is
1326
+ removed and nothing is left beside it.
1327
+ - **After the last failed attempt** the completion leaves what it leaves
1328
+ today: the outcome, the pending marker, the quarantine and one
1329
+ `retire-refused` event. The outcome adds `attempts`, the number of attempts
1330
+ that ran.
1331
+ - **Every attempt has its own `retired` event** with its `hooks` list, so
1332
+ `oats instance events <instance>` shows each one and how its hooks ended.
1333
+ - **What is never retried.** A quarantine that also owes a Git step,
1334
+ directory preservation or an orphaned work directory, or whose descriptor
1335
+ could not be stored in the home. A capability that declares no retire
1336
+ hook, or hooks that cannot be rerun. The retries also stop at an attempt
1337
+ that answers an error, and at one whose debt is no longer hooks alone. No
1338
+ retry starts once the home is gone or the pending marker is no longer this
1339
+ completion's: the retry checks that after its wait and again under the
1340
+ home's claim, and leaves a later scheduling's marker as it is.
1341
+ - **While the completion waits**, `oats status` reads the retire as
1342
+ `running`. Any other retire of the home is refused with `E_LIFECYCLE_BUSY`,
1343
+ for up to about 21 minutes after a hook failure. The refusal names the next
1344
+ attempt and the earliest time the last one starts. The time is only a lower
1345
+ bound: how long each attempt runs cannot be known in advance. The completion
1346
+ keeps this in a file of its own beside the home,
1347
+ `.oats-retire-retry-<instance>.json`, kernel-internal. It is removed on
1348
+ every way out, and by any retire that removes the home.
1349
+ - **A completion killed while it waits** leaves the instance `interrupted`,
1350
+ as before.
1351
+
1352
+ After that, nothing retries by itself: `oats retire <instance>` does, and
1353
+ `oats doctor` lists every retirement left open as a `retire-incomplete`
1354
+ problem, with that command and the capability whose hook failed last
1355
+ ([doctor](desktop-cli-api.md)). A completion removes only the marker of its
1356
+ own scheduling, so the marker of a later `--self` is left for that one's
1357
+ completion. Plain retires are not retried: their caller gets the answer.
1251
1358
 
1252
1359
  A completion does not start its retire while its scheduling still holds
1253
1360
  the home's claim (OATS 0.53.0). A scheduling that the host holds up
@@ -1904,10 +2011,17 @@ option.
1904
2011
  rework an existing one).
1905
2012
  - `--repo`: the instance's repository by default. A member key is looked up
1906
2013
  as a spawn looks up a clone (`oats-local.yaml` `clones:`, then
1907
- `<deployment>/<member name>`; `E_CLONE_MISSING` when there is none). A path
1908
- (absolute, or starting with `.` or `~`) is used as given. It must be a
1909
- clone, not a linked worktree (`E_CLONE_MISMATCH`), and have an `origin`
1910
- remote (`E_CLONE_MISMATCH`). Not a Git repository: `E_CLONE_MISSING`.
2014
+ `<deployment>/<member name>`; `E_CLONE_MISSING` when there is none). A name
2015
+ that isn't a repository key (`oats`, `awebai/oats`, `oats.git`) names no
2016
+ member and is refused as before: `E_CLONE_MISMATCH` when a clone is at its
2017
+ convention path or `clones:` names one for it, `E_CLONE_MISSING` when there
2018
+ is none. When that clone has a remote of that name (its key is the name or ends
2019
+ in `/<name>`), the refusal names the key to pass, `--repo <key>`, and the
2020
+ clone's path as the other spelling that works. It never suggests repointing
2021
+ the clone. A path (absolute, or starting with `.` or `~`) is used as given.
2022
+ It must be a clone, not a linked worktree (`E_CLONE_MISMATCH`), and have an
2023
+ `origin` remote (`E_CLONE_MISMATCH`). Not a Git repository:
2024
+ `E_CLONE_MISSING`.
1911
2025
 
1912
2026
  **What `add` does.** It writes a record, `<home>/.oats/trees/<p>.json`, in
1913
2027
  state `creating`, with its own pid and start time. Then it runs, as argument
@@ -2005,6 +2119,21 @@ output. This never changes the clone's index. Cleanup grants directories
2005
2119
  owner read, write and search access, and keeps `.git` until all other entries
2006
2120
  are deleted, so a failed deletion can be retried.
2007
2121
  An unreadable branch or a failed inspection keeps the tree and record.
2122
+
2123
+ `remove` runs no filter driver the repository's configuration defines
2124
+ (`filter.<name>.clean`, `.process`): its own status of the tree, the clean
2125
+ check inside `git worktree remove` and the comparison of an unregistered
2126
+ tree's surviving files are each preceded by one read of that configuration,
2127
+ and every driver it defines is overridden to no command, [as a retire does
2128
+ it](#retire-filter-drivers). A file such a filter applies to is compared as
2129
+ its bytes are in the tree, so one that was rewritten is uncommitted work
2130
+ (`E_WORKTREE_DIRTY`)
2131
+ even when its filtered form is what the branch stores. A driver whose name
2132
+ cannot be passed on Git's command line (it holds `=` or is not UTF-8)
2133
+ refuses the removal with `E_WORK_PRESERVATION_FAILED` before Git is run on
2134
+ the tree: no files were removed, and the record is kept. The same limits
2135
+ hold: a driver written between that read and the Git command, and a
2136
+ submodule's own configuration.
2008
2137
  Failures after Git started removing files say that removal may be partial
2009
2138
  and name the retry. If Git already removed `.git` too, automatic comparison
2010
2139
  is refused: save any work and remove the directory by hand, then run
package/docs/tui.md CHANGED
@@ -1296,7 +1296,7 @@ The exit status never depends on it.
1296
1296
  - An `oats tui` started again knows nothing of the acts an earlier one
1297
1297
  sent: `Check again` there answers that the plan expired, the list shows
1298
1298
  what the kernel reports, and against an earlier one's start still running
1299
- the kernel's start lock is the only guard.
1299
+ the home's lifecycle claim is the only guard.
1300
1300
  - An agent on a machine whose OATS is older than 0.52.0: a stop interrupted
1301
1301
  there can leave `.oats-stop-pending.json` in the agent's home, and then
1302
1302
  the agent can be started but not stopped while that file exists.
package/docs/upgrading.md CHANGED
@@ -6,11 +6,11 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.12** ([release notes](release-notes/v0.69.12.md)).
10
- The 0.69.12 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.14** ([release notes](release-notes/v0.69.14.md)).
10
+ The 0.69.14 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
11
11
 
12
12
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.69.12,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.14,** in the [release notes](release-notes/): it says what to do before
14
14
  the CLI changes, and what else must change with it (the Desktop, another
15
15
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
16
  names the releases that ask for more than the steps below. `oats version`
@@ -19,8 +19,8 @@ prints the version you have.
19
19
  Then, on each host:
20
20
 
21
21
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.69.12 first
23
- npm install -g @awebai/oats@0.69.12 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.14 first
23
+ npm install -g @awebai/oats@0.69.14 # 1. the CLI
24
24
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
25
  oats doctor # 3. in the same deployment
26
26
  ```
@@ -122,6 +122,8 @@ oats session start --home <absolute-home>
122
122
  Read the plan before applying it. It lists every moving package module,
123
123
  skill/inject/hook changes and provider adoption decisions, modules kept
124
124
  because their package is no longer locked, and member drift for information.
125
+ A kept package module moves only by a respawn; `oats session start` and
126
+ `restart` say so in one warning that names each one.
125
127
  One provider refusal refuses the whole move. A running or unreadable session
126
128
  refuses with `E_SESSION_RUNNING`; stop it first. A stale plan returns
127
129
  `E_PLAN_STALE` and a fresh plan to review.
@@ -202,6 +204,15 @@ of the Desktop and the CLI, and an optional package pin. A change a script
202
204
  must follow is in its release's Upgrade section whether or not it is listed
203
205
  here.
204
206
 
207
+ - **[0.69.14](release-notes/v0.69.14.md#upgrade):** 0.69.13 was tagged but
208
+ never published, so its steps (below) are this release's; the remaining
209
+ state-changing commands refuse a flag they do not define.
210
+ - **[0.69.13](release-notes/v0.69.13.md#upgrade):** the catalog pins
211
+ oats.framework 1.23.0. Remove a sweep lock (`~/.oats/session-resume/lock`)
212
+ or a home's start lock (`<home>/.oats-start.lock`) an earlier OATS left;
213
+ check each `git:` package pin names its own id; a deployment of OATS's
214
+ own workspace takes the four hand steps for the reviewer soul's new name,
215
+ then respawns its homes onto the new souls and starts a dispatcher.
205
216
  - **[0.69.12](release-notes/v0.69.12.md#upgrade):** the catalog pins
206
217
  oats.okf 5.8.0, oats.aweb 1.37.0 and oats.framework 1.22.1. Where
207
218
  `oats.aweb-tasks` is composed, readiness warns until the host wake daemon
@@ -552,6 +563,14 @@ resolve, or a bridge that cannot be read). A folder that does not exist or
552
563
  holds no bridge is not a skew, and it says nothing about it. The warnings are
553
564
  in the text output only; `oats doctor --json` does not carry them.
554
565
 
566
+ `oats doctor` also reports this machine's session resume lock when it needs a
567
+ person, as a `resume-lock-stuck` problem with the path and what to do: after
568
+ an upgrade that is a lock directory left by the earlier OATS
569
+ (`~/.oats/session-resume/lock/`), which `oats session resume` refuses with
570
+ `E_RESUME_LOCK_STUCK` and never removes. Remove the directory once no earlier
571
+ `oats` is running on the machine
572
+ ([The sweep](execution-targets.md#the-sweep)).
573
+
555
574
  ## After a change of Node version
556
575
 
557
576
  Two paths are written into things that outlive a command: the kernel's, and