@awebai/oats 0.69.11 → 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 (72) 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 +9 -5
  13. package/docs/knowledge-and-learning.md +72 -0
  14. package/docs/knowledge.md +10 -3
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +42 -8
  17. package/docs/packages.md +101 -22
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.12.md +97 -0
  20. package/docs/release-notes/v0.69.13.md +767 -0
  21. package/docs/release-notes/v0.69.14.md +83 -0
  22. package/docs/schedules.md +26 -3
  23. package/docs/servers.md +181 -5
  24. package/docs/souls-and-instances.md +140 -11
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +30 -5
  27. package/docs/workspaces.md +32 -6
  28. package/lib/claim.mjs +21 -5
  29. package/lib/command-flags.mjs +238 -0
  30. package/lib/core.mjs +791 -563
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +126 -31
  33. package/lib/errors.mjs +1 -1
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/hot-reads.mjs +4 -3
  36. package/lib/instance-events.mjs +28 -6
  37. package/lib/instance-git.mjs +138 -13
  38. package/lib/instance-inspect.mjs +6 -1
  39. package/lib/instance-listing.mjs +80 -38
  40. package/lib/instance-resolution.mjs +56 -3
  41. package/lib/instance-upgrade.mjs +16 -20
  42. package/lib/launch-env-exec.sh +7 -0
  43. package/lib/launch-env.mjs +74 -0
  44. package/lib/launch-preference.mjs +19 -12
  45. package/lib/member-clone.mjs +7 -1
  46. package/lib/packages.mjs +74 -2
  47. package/lib/read-call.mjs +3 -0
  48. package/lib/reader.mjs +3 -2
  49. package/lib/refused-text.mjs +3 -2
  50. package/lib/remote.mjs +119 -27
  51. package/lib/retained-after-retire.mjs +2 -7
  52. package/lib/retire-git-forms.mjs +41 -0
  53. package/lib/retire-incomplete.mjs +96 -0
  54. package/lib/schedule.mjs +2 -1
  55. package/lib/servers.mjs +78 -23
  56. package/lib/session-resume.mjs +68 -53
  57. package/lib/session-seen.mjs +54 -5
  58. package/lib/start-env.mjs +13 -7
  59. package/lib/system-tools.mjs +1 -1
  60. package/lib/teams.mjs +11 -4
  61. package/lib/upgrade-state.mjs +13 -2
  62. package/lib/worktree.mjs +56 -7
  63. package/package-catalog.json +3 -3
  64. package/package.json +2 -1
  65. package/packages/client/instance-lifecycle.mjs +1 -1
  66. package/packages/client/lifecycle-contract.mjs +3 -1
  67. package/packages/client/session-resume-cli.mjs +2 -1
  68. package/packages/client/session-start.mjs +10 -7
  69. package/packages/client/workspace-cli.mjs +5 -1
  70. package/share/oats-login-receive +204 -0
  71. package/skills/oats-getting-started/SKILL.md +180 -49
  72. package/lib/tmux-config.mjs +0 -35
@@ -296,6 +296,119 @@ accepted, and its value is only ever the message. A capability command's own fla
296
296
  typed; the kernel reads only its dispatch flag (`--soul`). There is no feature
297
297
  string for this: to support older kernels, use the spaced form.
298
298
 
299
+ <a id="command-flags"></a>
300
+ ### The flags a command defines
301
+
302
+ These commands change state (and `oats teams`, `oats server check`,
303
+ `oats trigger poll` and `test`, which sit beside them), and each refuses a
304
+ flag it does not define before anything happens: before a plan is read, a
305
+ file is written, a process is stopped or started, and before a `--server`
306
+ command is sent to its host. A typo of a protective flag (`--no-recursve`
307
+ for `--no-recursive`) is never ignored.
308
+
309
+ | Command | Arguments | Flags that take a value | Switches | Refused in their own words | Its own answers |
310
+ |---|---|---|---|---|---|
311
+ | `oats retire` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir`, `--server` | `--plan`, `--self`, `--discard-worktree`, `--keep-dir`, `--force`, `--json` | `--delete-branch` | none |
312
+ | `oats spawn` | `<soul>` | `--agents-root`, `--backend`, `--base`, `--branch`, `--dir`, `--expect-decision`, `--harness`, `--herdr-socket`, `--idempotency-key`, `--instance`, `--launch-config`, `--max-age`, `--model`, `--name`, `--parent`, `--provider` (2 words), `--purpose`, `--relation`, `--relative-root`, `--relative-to`, `--repo`, `--runtime`, `--server`, `--task`, `--task-file`, `--trigger-event`, `--wake-cron`, `--wake-every`, `--wake-file`, `--wake-json`, `--wake-message`, `--wake-message-file`, `--wake-tz`, `--work`, `--work-dir` | `--allow-child-spawns`, `--background`, `--json`, `--no-background`, `--no-child-spawns`, `--no-launch`, `--no-yolo`, `--preview`, `--same-work`, `--suggest-name`, `--yolo` | `--instructions-file`, `--def-file`, `--ephemeral` | an unknown flag, an argument after the last |
313
+ | `oats sync` | none | `--dir` | `--plan`, `--json` | `--approve` | none |
314
+ | `oats instance stop` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--grace-ms`, `--home`, `--dir`, `--server` | `--plan`, `--apply`, `--no-recursive`, `--json` | none | none |
315
+ | `oats instance upgrade` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir` | `--undo`, `--plan`, `--json` | `--server` | none |
316
+ | `oats instance color` | `<instance>` `[<color>]` | `--home`, `--dir`, `--server` | `--clear`, `--json` | none | none |
317
+ | `oats instance background` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
318
+ | `oats instance same-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
319
+ | `oats instance waiting set` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
320
+ | `oats instance waiting clear` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
321
+ | `oats instance attention` | none | `--message` | `--clear`, `--json` | `--home`, `--dir`, `--producer`, `--reason` | none |
322
+ | `oats instance suggest-name` | none | `--soul`, `--task`, `--task-file`, `--harness`, `--model`, `--launch-config`, `--dir` | `--json` | `--server` | none |
323
+ | `oats worktree add` | none | `--purpose`, `--branch`, `--base`, `--repo` | `--preview`, `--json` | `--server`, `--dir`, `--home` | none |
324
+ | `oats worktree remove` | none | `--purpose` | `--json` | `--server`, `--dir`, `--home` | none |
325
+ | `oats session start` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json`, `--resume` | `--native-record` | none |
326
+ | `oats session restart` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server`, `--stop-grace` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json` | `--native-record`, `--resume` | none |
327
+ | `oats session resume` | none | `--deployment` | `--plan`, `--json` | `--native-record`, `--server` | none |
328
+ | `oats session input` | none | `--home`, `--text-file` | `--json` | `--native-record` | none |
329
+ | `oats session receive` | none | `--home`, `--name` | `--json` | `--native-record` | none |
330
+ | `oats session upload` | none | `--file`, `--home`, `--instance`, `--server` | `--json` | `--native-record` | none |
331
+ | `oats session attach` | none | `--detach-key`, `--home`, `--instance`, `--server` | `--no-status-line`, `--print`, `--json` | `--native-record` | none |
332
+ | `oats schedule add` | `[<id>]` | `--file`, `--spec-json`, `--description`, `--workspace`, `--runs-on`, `--owner`, `--dir`, `--server` | `--json` | none | none |
333
+ | `oats schedule update` | `<id>` | `--file`, `--spec-json`, `--description`, `--dir`, `--server` | `--json` | none | none |
334
+ | `oats schedule remove` | `<id>` | `--dir`, `--server` | `--force`, `--json` | none | none |
335
+ | `oats schedule run` | `<id>` | `--dir`, `--server` | `--force`, `--json` | none | none |
336
+ | `oats schedule enable` | `<id>` | `--dir`, `--server` | `--json` | none | none |
337
+ | `oats schedule disable` | `<id>` | `--dir`, `--server` | `--json` | none | none |
338
+ | `oats schedule reconcile` | `<id>` | `--dir`, `--server` | `--clear`, `--json` | none | none |
339
+ | `oats schedule tick` | none | `--dir`, `--server` | `--dry-run`, `--host`, `--json` | none | none |
340
+ | `oats schedule host install` | none | `--max-concurrent`, `--triggers-max-concurrent`, `--os`, `--dir`, `--server` | `--print`, `--json` | none | none |
341
+ | `oats schedule host uninstall` | none | `--dir`, `--server` | `--json` | none | none |
342
+ | `oats trigger add` | none | `--file`, `--from`, `--set`, `--id`, `--description`, `--workspace`, `--runs-on`, `--owner`, `--dir` | `--json` | none | none |
343
+ | `oats trigger poll` | `<id>` | `--dir`, `--max-age` | `--run-source`, `--json` | none | none |
344
+ | `oats trigger test` | `<id>` | `--dir` | `--run-source`, `--json` | none | none |
345
+ | `oats trigger remove` | `<id>` | `--dir` | `--json` | none | none |
346
+ | `oats trigger enable` | `<id>` | `--dir` | `--json` | none | none |
347
+ | `oats trigger disable` | `<id>` | `--dir` | `--json` | none | none |
348
+ | `oats teams` | none | `--dir`, `--max-age` | `--json` | none | an unknown flag, an argument after the last |
349
+ | `oats teams add` | `<label>` | `--dir`, `--team`, `--description` | `--no-default`, `--json` | none | an unknown flag |
350
+ | `oats teams remove` | `<label>` | `--dir` | `--json` | none | an unknown flag |
351
+ | `oats teams default` | `<label>` | `--dir`, `--expect` | `--if-absent`, `--json` | none | an unknown flag |
352
+ | `oats soul launch set` | `<soul>` | `--dir`, `--launch-config`, `--harness`, `--model` | `--plan`, `--json` | none | an unknown flag, an argument after the last |
353
+ | `oats soul launch remove` | `<soul or key>` | `--dir` | `--plan`, `--json` | none | an unknown flag, an argument after the last |
354
+ | `oats server check` | `<id>` | none | `--json` | none | none |
355
+ | `oats server remove` | `<id>` | none | `--json` | none | none |
356
+ | `oats server forget` | `<id>` | `--instance` | `--json` | none | none |
357
+ | `oats package add` | `<id>` `<version>` | `--dir` | `--json` | none | none |
358
+ | `oats package remove` | `<id>` | `--dir` | `--json` | none | none |
359
+ | `oats launch-config set` | `<name>` | `--file`, `--dir`, `--server` | `--keep-env`, `--json` | `--home`, `--soul` | none |
360
+ | `oats launch-config remove` | `<name>` | `--dir`, `--server` | `--json` | `--home`, `--soul` | none |
361
+ | `oats automations refresh` | none | `--dir` | `--json` | none | none |
362
+ | `oats update` | none | `--dir` | `--check`, `--yes`, `--json` | `--to` | an argument after the last |
363
+
364
+ An argument in brackets (`[<color>]`) is one the command may go without.
365
+ A flag marked with a number of words (`--provider`, two: `--provider
366
+ <capability> key=value`) takes that many.
367
+
368
+ The refusal is `E_BAD_ARGS`, with the command's usage line after the
369
+ message, and comes from the first problem from the left:
370
+
371
+ - a flag the command does not define: `oats <command>: unknown flag
372
+ <flag>`, `error.details: {flag}`;
373
+ - a value on a switch: `oats <command>: <flag> takes no value (got
374
+ <flag>=<value>)`, `error.details: {flag}`;
375
+ - an argument after the last one the command takes: `oats <command>:
376
+ unexpected argument "<word>" after the <name> "<value>": <command> takes
377
+ one <name>`, or `<command> takes no argument`, `error.details: {argument}`;
378
+ - a flag refused in its own words: that message (for example
379
+ `--delete-branch` on retire, `--server` on `oats instance upgrade`),
380
+ `error.details: {flag}`.
381
+
382
+ A command whose last column names an answer gives that one in its own words:
383
+
384
+ - `oats spawn`: `oats spawn: unknown flag <flag>`, and `oats spawn:
385
+ unexpected argument "<word>" after the soul "<soul>": spawn takes one
386
+ soul` (for a `key=value` word, `a capability setting is given as
387
+ --provider <capability> key=value`), `E_BAD_ARGS` with no usage line and
388
+ no `details`;
389
+ - `oats teams` and its forms, `oats soul launch set` and `remove`: the
390
+ flag is `E_USAGE {flag}` in their words ([`oats teams`](#oats-teams),
391
+ [`oats soul launch`](#oats-soul-launch)); a word where `oats teams`
392
+ takes a form is `E_USAGE` with its usage; a second soul of `oats soul
393
+ launch` is `E_BAD_ARGS`, `takes one soul, and got <n>: …`, naming
394
+ every one;
395
+ - `oats update <word>`: ``oats update takes no package: pin package
396
+ versions in oats-workspace.yaml (`oats package add <id> <version>`), then
397
+ `oats sync`; …``, `E_BAD_ARGS`, `error.details: {argument}`.
398
+
399
+ Then, for a command given `--server`, a missing argument it requires is
400
+ `E_USAGE`, with the usage line as `error.message` and no `details`, and
401
+ nothing is sent. On this machine each command answers a missing argument
402
+ itself, as before (`oats retire` with no instance is `E_USAGE` too).
403
+
404
+ A flag that takes a value takes the next word (its number of words) unless
405
+ it starts with `--`; a value after `=` is its first. A value flag given
406
+ none (no word, or one that starts with `--`) ends the check there: it is
407
+ that flag's own refusal, by the command, before any flag after it. `--` is a flag like any other, and none of
408
+ these commands defines it. `--runtime` is the pre-0.27 name of
409
+ `--harness`. `--help` and `-h` print the usage first, as for every
410
+ kernel command.
411
+
299
412
  ### Dispatch errors
300
413
 
301
414
  | Code | When |
@@ -803,7 +916,13 @@ and ships the soul at the locked commit, and the soul's copy is intact: for
803
916
  `--home`, the home's copy matches the digest it recorded, and a lock still
804
917
  at that commit records the same digest. The copy is digested on every read.
805
918
  It fails otherwise, with `code: "E_PACKAGE_INTEGRITY"` on a digest mismatch
806
- and the remedy naming `oats sync` or a fresh spawn.
919
+ and the remedy naming `oats sync` or a fresh spawn. When the package is no
920
+ longer locked, readiness cannot tell a deliberate drop from an accidental
921
+ unpin or a pending sync, so the `--home` remedy names both, the respawn
922
+ first: if the workspace dropped the package on purpose, spawn a new instance
923
+ from a soul the workspace offers, then retire this one; otherwise declare the
924
+ package in `packages:` and `oats sync`. For `--soul` it is declaring the
925
+ package and `oats sync`.
807
926
 
808
927
  **`providers`** (producer `provider binding check`): for each module whose
809
928
  manifest declares `binding`, the kernel runs its `binding.check` and relays
@@ -1180,6 +1299,13 @@ applies: gate `sync --plan` on `version` 0.44.0 or later, never by trying.
1180
1299
  - Errors: `E_LOCAL_MISSING`, `E_WORKSPACE_SCHEMA {path, problems}`,
1181
1300
  `E_REMOTE_UNREADABLE`, `E_LOCK_SCHEMA`, `E_PACKAGE_MISSING`,
1182
1301
  `E_PACKAGE_INTEGRITY`, `E_PACKAGE_MANIFEST`, `E_REPO_REF`, `E_BAD_ARGS`.
1302
+ `E_PACKAGE_INTEGRITY` names its case in `details.why`: `branch`,
1303
+ `package-id`, and `capabilities` or `souls` for an edited lock; a tag or
1304
+ content that moved carries none
1305
+ ([`oats sync`](packages.md#oats-sync--the-one-command-for-the-common-path)).
1306
+ The Desktop's sync sheet words the refusal per `why`, and gives no `why`, or
1307
+ one it doesn't know, the code's general meaning; its Details show the
1308
+ kernel's message.
1183
1309
 
1184
1310
  ### `oats package add` and `remove`
1185
1311
 
@@ -1578,6 +1704,26 @@ line that gives each kind's total, and at most 50 items per kind
1578
1704
  ([After a retire](souls-and-instances.md#after-a-retire-inspect-restore-dispose)).
1579
1705
  Each element is one line of text with no newline. The answer has no new key.
1580
1706
 
1707
+ `oats doctor --json` lists each retirement left open as one
1708
+ `retire-incomplete` problem in `problems[]`, `{code, message, remedy}`
1709
+ (oats-project/oats#1747). Text prints it as `! retire-incomplete: <message>`
1710
+ with the remedy on the next line. A retirement is open when the home reads
1711
+ quarantined (`rollbackIncomplete`), when its self-retire is `failed` or
1712
+ `interrupted`, or when a failed self-retire left its outcome beside a home
1713
+ that is still there. A home whose retire is `running` or `unknown`, a spawn
1714
+ in progress, and an outcome whose home is gone are not listed. The message
1715
+ names the instance, the home, what is open and since when. The remedy is
1716
+ `oats retire <name> --home <home>`, each word quoted for a shell, and names
1717
+ the capability whose retire hook failed last, or says that none is recorded.
1718
+ Doctor reads this as `oats status` does, offline and read-only. Its exit
1719
+ status does not change: doctor exits 0 with problems. A deployment with no
1720
+ open retirement sees no change.
1721
+
1722
+ `oats doctor --json` lists this machine's session resume lock, when it needs a
1723
+ person, as one `resume-lock-stuck` problem in `problems[]`, `{code, message,
1724
+ remedy}` ([The machine sweep](#the-machine-sweep-oats-session-resume),
1725
+ `E_RESUME_LOCK_STUCK`). It is the machine's, the same from every deployment.
1726
+
1581
1727
  ### Desktop facts
1582
1728
 
1583
1729
  Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
@@ -1848,9 +1994,14 @@ oats teams default <label> [--if-absent | --expect <label>] --json
1848
1994
  Among concurrent `oats teams` writers on one deployment, a conditional write
1849
1995
  therefore never overwrites a default another of them set: when two race, the
1850
1996
  later one sees the earlier result and refuses with
1851
- `E_TEAM_DEFAULT_MISMATCH`. A lock still held after 5 s is `E_LOCAL_BUSY
1852
- {path, lock}`, naming the directory to remove when no oats process is
1853
- editing; nothing was written. The limits: a person or tool editing
1997
+ `E_TEAM_DEFAULT_MISMATCH`. The lock is a file that names the process
1998
+ holding it: one left by a command that was killed is taken over by the next
1999
+ command. A lock whose holder is still running after 5 s is `E_LOCAL_BUSY
2000
+ {path, lock}`, and so is one that cannot be judged: a record that is
2001
+ unreadable, a holder that cannot be told to be running or gone, or a lock
2002
+ directory written by an earlier kernel. The message says which was found and
2003
+ names the path to remove when no oats process is editing; nothing was
2004
+ written. The limits: a person or tool editing
1854
2005
  `oats-local.yaml` directly does not take the lock (the content compare still
1855
2006
  catches most such edits, but not one landing between the compare and the
1856
2007
  rename), and changes to the committed `oats-workspace.yaml` (a pull, a
@@ -2009,7 +2160,7 @@ problem's own keys.
2009
2160
  | `default-team-changed` | warning | `recorded`, `current` | `--home` with live teams: the default changed since the spawn |
2010
2161
  | `E_TEAM_UNKNOWN` | failure | `label`, `at` | a local default no file declares |
2011
2162
  | `E_WORKSPACE_SCHEMA` | failure | `condition: "local-teams-closed"`, `path`, `keys` | `oats-local.yaml` declares `teams` / `defaultTeam` and the workspace does not allow local teams |
2012
- | `team-soul-unknown` | warning | `key`, `at` | a `souls:` key that is neither `"*"` nor `<name>/*` nor a discovered soul's key (a typo guard) |
2163
+ | `team-soul-unknown` | warning | `key`, `at` | a `souls:` key that is no discovered soul's key, or a `<name>/*` pattern that matches none of them; never `"*"` (a typo guard; a pattern's `message` and `fix` are its own) |
2013
2164
 
2014
2165
  `E_TEAM_UNKNOWN` and local-teams-closed are also spawn, preview and inspect
2015
2166
  refusals (local-teams-closed as `E_WORKSPACE_SCHEMA` with details `{reason,
@@ -2128,7 +2279,7 @@ Every object shape here is closed.
2128
2279
  souls:
2129
2280
  launch:
2130
2281
  "*": opus # every soul on this machine
2131
- oats-expert: opus # a launch configuration
2282
+ oats-engineering-expert: opus # a launch configuration
2132
2283
  oats.engineering/code-reviewer: {harness: codex} # an inline preference
2133
2284
  ```
2134
2285
  - **Migration.** 0.29.x refuses an unknown soul.yaml key, and members are read
@@ -2269,6 +2420,39 @@ shows the drift as `launch-changed`.
2269
2420
  home, `--reselect-launch` included, is never refused this way.
2270
2421
  - `E_WORKSPACE_SCHEMA`: a malformed `launch` or `souls.launch`, path named.
2271
2422
 
2423
+ **A `souls.disabled` entry that names no soul** (oats-project/oats#1772) keeps
2424
+ no soul off this machine, and spawn does not refuse because of it: a stale
2425
+ entry fails open, where a stale `souls.launch` key fails closed. `oats doctor`
2426
+ reports it with the launch check's discipline, offline, from the same read of
2427
+ this machine's cache:
2428
+ - An entry matches when spawn's own rule (`E_SOUL_DISABLED`) holds for a soul
2429
+ the workspace offers: its bare name, or its qualified name (`<package>/<soul>`
2430
+ or `<member>/<soul>`). A disabled soul is still offered. Spawn's rule is
2431
+ exact: `<member>/<soul>` for a soul that only another member offers does not
2432
+ match.
2433
+ - `problems[]` gains `{code: "disabled-soul-unmatched", entry, at,
2434
+ suggestions, message, remedy}` per entry that matches nothing, in file
2435
+ order (text: `! disabled-soul-unmatched: <message>`, then the remedy). `at`
2436
+ is `oats-local.yaml#/souls/disabled/<index>`. `suggestions` holds at most
2437
+ three qualified names of offered souls, ranked as the launch rows rank
2438
+ theirs: the same bare name first, then a bare name within two edits. The
2439
+ message says that it speaks about this machine's last read and that a spawn
2440
+ reads the workspace itself and is the authority. The remedy is the hand
2441
+ edit, replace the entry with the soul it was meant for or remove it: no
2442
+ command writes `souls.disabled`.
2443
+ - An entry is *not checked*, and gets an `information[]` line that starts
2444
+ `disabled-soul-unchecked:` instead of a row, when the source that could
2445
+ hold its soul was not read, for the reasons of the launch check: an entry
2446
+ under a package that is declared and not locked, or one of whose souls was
2447
+ skipped; any entry not under the package of an offered package soul while
2448
+ a member is not confirmed or a member's or an external soul was skipped (a
2449
+ bare name, `<member>/<soul>`, or a prefix that may be a member's name);
2450
+ every entry in the standalone view of a workspace whose host cannot be
2451
+ read, or a read that kept no record of what it skipped. When the cache
2452
+ cannot answer at all, one such line names the entries.
2453
+ - Doctor still exits 0. With no `souls.disabled`, or an empty list, nothing is
2454
+ added. Spawn, `oats souls`, readiness and inspect do not change.
2455
+
2272
2456
  ### The launch report (`Launch`)
2273
2457
 
2274
2458
  ```json
@@ -3061,6 +3245,7 @@ kernel stage raised as well.
3061
3245
  | `E_NOT_A_MEMBER`, `E_MEMBERSHIP_UNCONFIRMED` | | the soul's repository is not a confirmed member |
3062
3246
  | `E_CAPABILITY_MISSING`, `E_CAPABILITY_PRIVATE`, `E_CAPABILITY_INCOMPATIBLE`, `E_COMPATIBILITY` | | a capability cannot be resolved |
3063
3247
  | `E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY`, `E_LOCK_SCHEMA` | | the lock does not provide it (standalone: `{…, standalone: true, reason: "no-catalog", catalog}`) |
3248
+ | `E_PACKAGE_INTEGRITY` | `{package, version, commit, expected, actual}` | a composed package's tree at the locked commit does not digest to the lock's `integrity` (`expected`); `actual` is the digest read. Preview and apply, before anything is written ([The integrity check at spawn](packages.md#the-integrity-check-at-spawn)) |
3064
3249
  | `E_SLOT_CONFLICT`, `E_SKILL_DUPLICATE` | | the composition conflicts |
3065
3250
  | `E_WORKSPACE_SCHEMA` | `{path, key, reason}` | a removed key or invalid payload |
3066
3251
  | `E_CLONE_MISSING`, `E_CLONE_MISMATCH` | | the member's clone is missing or wrong |
@@ -3075,6 +3260,7 @@ kernel stage raised as well.
3075
3260
  | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
3076
3261
  | `E_HARNESS_UNAVAILABLE` | `{harness, from, at, fix}` | the chosen harness has no executable on this machine ([launch preferences](#soul-launch-preferences-feature-launch-preference-oats-0300)) |
3077
3262
  | `E_CLAUDE_CONFIG_REMOVED` | `{file, executable, fix}` | a new claude launch with an `oats-claude-config` in reach ([configuration.md](configuration.md)) |
3263
+ | `E_CLAUDE_LOGIN_CREDENTIAL` | | the effective Claude configuration has a `/login` credential file while OATS sets `CLAUDE_CODE_OAUTH_TOKEN`; remove the login credential and use the token route ([configuration.md](configuration.md)). Spawn preflight checks predictable values before effects, and the actual pane is checked after hooks |
3078
3264
  | `E_HARNESS_RESOURCE_MISSING` | | a harness package a capability requires for the selected harness is not installed, disabled, or cannot be verified ([capabilities.md](capabilities.md)); raised before any home exists, at a preview too, and again by an apply after the home, the work and the hooks when the pane it got differs from the one it checked in a name the probe reads, or selects another program (another creator started the OATS tmux server): then the spawn is rolled back, with `details.unconfirmed` when that cannot finish. A start, a restart and a launch plan's `harness-packages` check answer the same code |
3079
3265
  | `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
3080
3266
  | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
@@ -3248,9 +3434,9 @@ A failed `add` reports the same facts about its rollback in `details`:
3248
3434
  | `E_BASE_UNKNOWN` | the new HEAD is not the fetched commit; the message names both |
3249
3435
  | `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT` | a required `worktree` hook failed or timed out, or a hook answered `env`; the tree is removed (`details.hooks`, `details.rolledBack`) |
3250
3436
  | `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
3251
- | `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message), or an unregistered residue differs from the recorded branch (the message and `details.git` list the modified or nonignored untracked paths). The record is kept. Save the changes, or discard, then retry |
3437
+ | `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message), or an unregistered residue differs from the recorded branch (the message and `details.git` list the modified or nonignored untracked paths). No filter driver the repository's configuration defines is run for either: a file such a filter applies to is compared as its bytes are in the tree. The record is kept. Save the changes, or discard, then retry |
3252
3438
  | `E_CHILDREN_RUNNING` | `remove`: an instance attached to the tree has a session that is running, or that cannot be read. Answered under the purpose's claim, before Git is asked anything: nothing is removed and the record is kept. `details: {purpose, path, children: [{instance, home, session}]}`, `session` being `"running"` or `"unknown"`; only the instances that refuse are listed. The message names each one and what was seen, and the step: `oats instance stop <instance>`, or retire it, then remove again. No flag removes anyway. It is the code [a retire](#retire-children-running) answers, with other `details`: a retire answers it for a child it asked to stop and that did not; `remove` for an attached instance it found running or unread, and it asks nobody to stop, so there is no `childrenStopped` |
3253
- | `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, removal could not be verified, or an unregistered residue could not be checked against its recorded branch or deleted; the record is kept. A failure after Git started removal reports possible partial deletion and the retry, never that nothing was removed. A missing or invalid `.git` marker names the manual step: save any work, remove the directory by hand, then run `remove` again to drop the record. See [extra-tree removal recovery](souls-and-instances.md#extra-trees) |
3439
+ | `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, removal could not be verified, an unregistered residue could not be checked against its recorded branch or deleted, or the repository's configuration defines a filter driver whose name cannot be overridden on Git's command line (it holds `=` or is not UTF-8; Git is not run on the tree, since it would run that filter: [filter drivers](souls-and-instances.md#retire-filter-drivers)); the record is kept. A failure after Git started removal reports possible partial deletion and the retry, never that nothing was removed. A missing or invalid `.git` marker names the manual step: save any work, remove the directory by hand, then run `remove` again to drop the record. See [extra-tree removal recovery](souls-and-instances.md#extra-trees) |
3254
3440
  | `E_LIFECYCLE_FAILED` | an error that is not the kernel's; with [`details.cause`](#kernel-codes) when it has a code of its own or is a defect, and without it when it is a refusal without a code. When it is the purpose's claim that could not be taken (`<home>/.oats/trees` cannot be made, the claim's file cannot be written), the message is `the claim <path> could not be taken (…); nothing was done`. Also a command that was refused the claim after its takeover had ended a dead command's git step: the message names the group it ended first, then the refusal, and `details` are that refusal's (a refusal of the kernel's has no `details.cause`; anything else has it by the same rule) |
3255
3441
 
3256
3442
  A rollback that cannot finish keeps the record and says so in the message
@@ -3879,16 +4065,19 @@ oats server check <id> --json
3879
4065
  ```
3880
4066
 
3881
4067
  `server list` is an envelope whose `result` is `{file, servers}`; each row is
3882
- the registration (`id`, `sshHost`, `workspace`, and `oatsPath`, `path`,
3883
- `label` when set) plus `workspaceKey` (`null` when not known yet), `target`
3884
- and `snapshots`. With `--workspace-ref <ref>`, `servers` holds only the rows
3885
- whose `workspaceKey` is the canonical key of `<ref>` (`parseRepoRef`; any
4068
+ the registration (`id`, `sshHost`, `workspace`, and `operatorSshHost`,
4069
+ `oatsPath`, `path`, `label` when set) plus `workspaceKey` (`null` when not known
4070
+ yet), `target` and `snapshots`. `operatorSshHost` is the optional `--operator-ssh` alias,
4071
+ joined from `~/.oats/server-operator-routes.json`; it is absent from `servers.json`.
4072
+ Older kernels never read the separate file;
4073
+ existing routing and `target` use only `sshHost`. With `--workspace-ref <ref>`,
4074
+ `servers` holds only the rows whose `workspaceKey` is the canonical key of `<ref>` (`parseRepoRef`; any
3886
4075
  spelling of the repository), and `result.unknownWorkspace` lists the ids
3887
4076
  whose key is not known; an unparsable ref is `E_REPO_REF`.
3888
4077
 
3889
4078
  ```json
3890
4079
  {"file":"/Users/me/.oats/servers.json",
3891
- "servers":[{"id":"altair-aweb","sshHost":"altair","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"altair",
4080
+ "servers":[{"id":"altair-aweb","sshHost":"altair","operatorSshHost":"altair-operator","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"altair",
3892
4081
  "workspaceKey":"github.com/awebai/ac",
3893
4082
  "target":{"sshHost":"altair","workspace":"/Users/me/acme","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
3894
4083
  "unknownWorkspace":["build"]}
@@ -3909,7 +4098,7 @@ contradicts fails the check with `E_SERVER_WORKSPACE_MISMATCH`, `details:
3909
4098
 
3910
4099
  ```text
3911
4100
  oats server connect <id> --ssh <host> --dir </abs/path or ~/path on the host> [--workspace-ref <ref>]
3912
- [--oats <path>] [--path <dirs>] [--label <text>] [--install-oats] [--replace] --json
4101
+ [--operator-ssh <alias> | --no-operator-ssh] [--oats <path>] [--path <dirs>] [--label <text>] [--install-oats] [--replace] --json
3913
4102
  ```
3914
4103
 
3915
4104
  An envelope, `ok: true` whenever no step failed, human steps included
@@ -3941,10 +4130,13 @@ An envelope, `ok: true` whenever no step failed, human steps included
3941
4130
  some codes, `details`. `skipped` steps say `waits for <step>`.
3942
4131
  - `registration` is the registration as written or found (`sshHost`,
3943
4132
  `workspace`: the absolute path the host resolved for `--dir`, never `~`;
3944
- `workspaceKey`; and `oatsPath`, `path`,
3945
- `label` when set, given or, without `--path`, read from the host user's
4133
+ `workspaceKey`; optional `operatorSshHost` joined from the separate operator-route file; and
4134
+ `oatsPath`, `path`, `label` when set, given or, without `--path`, read from the host user's
3946
4135
  [login shell](servers.md#the-hosts-login-shell-path)), `null` until the
3947
4136
  `register` step has run.
4137
+ With `--replace`, an existing operator route is kept unless `--operator-ssh`
4138
+ sets it again or `--no-operator-ssh` clears it. `server remove` deletes the
4139
+ separate route too. Both files are updated under `servers.lock`.
3948
4140
  - `human` lists the remedies of the `needs-human` steps, in order. A
3949
4141
  `readiness` step that needs a human has one line per problem
3950
4142
  (`<souls>: <subject>: <reason>[ → <remedy>]`, plus `readiness not checked
@@ -4294,6 +4486,39 @@ readOnly: {helpers: "disabled", optionalLocks: "off", objectsWritten: 0}}`.
4294
4486
  (`readOnly`). An object a partial clone lacks is not fetched: the read
4295
4487
  fails with `E_GIT_FAILED` (with Git 2.44 or later; an older Git ignores
4296
4488
  `GIT_NO_LAZY_FETCH`).
4489
+ - **Filter drivers are not run.** Git runs a `filter.<name>.clean` or
4490
+ `.process` command when a status or a diff compares a work-tree file that
4491
+ carries the `filter` attribute, and it has no switch that turns filters
4492
+ off. Before the Git commands that read a work-tree file, `oats instance
4493
+ git` and `oats instance diff` read the configuration Git would use (`git config --list`, which runs
4494
+ nothing and follows `include.path` and `includeIf`) and override every
4495
+ filter driver it defines to no command (`clean`, `smudge`, `process`) and
4496
+ not required. An observation makes that read once, before its status, for
4497
+ its status and its line counts; each command of a diff is preceded by its
4498
+ own.
4499
+ - A file such a filter applies to (a Git LFS file, for one) is compared as
4500
+ its bytes are in the work tree, not as the filter would store them. An
4501
+ untouched file still reads as unchanged, by its recorded size and times.
4502
+ One that was rewritten, or whose times Git cannot tell from the index's,
4503
+ reads as `changed` even when its filtered form is what is stored; its
4504
+ line counts and its diff are the stored form (an LFS pointer) against the
4505
+ work tree's bytes. The observation then carries a note that the
4506
+ repository's configuration defines a filter driver.
4507
+ - A driver whose name cannot be passed on Git's command line (it holds `=`
4508
+ or is not UTF-8) cannot be overridden: Git is not run, and the read fails
4509
+ with `E_GIT_FAILED`.
4510
+ - Not covered: a driver written into the configuration between that read
4511
+ and a Git command it covers (for an observation, up to its line counts,
4512
+ which follow its status and its reads of HEAD, the index and the refs),
4513
+ and a filter a **submodule's own**
4514
+ configuration defines. Git runs inside each populated submodule to learn
4515
+ whether it is dirty, and the overrides name the repository's drivers, not
4516
+ the submodule's. A dirty submodule stays visible in the status for that
4517
+ reason. Where the agent and the reader of its worktree are one system
4518
+ user, which is the usual arrangement, such a filter runs nothing the agent
4519
+ could not run itself. Where they are separate users, it runs the agent's
4520
+ command as the reader's user: do not read a worktree with populated
4521
+ submodules across users.
4297
4522
  - If HEAD or the index moved, the id is not in the current observation, or
4298
4523
  anything moved during the read: `E_STALE_OBSERVATION` with
4299
4524
  `details.observation`. Re-observe; never render a diff of another tree.
@@ -4337,6 +4562,12 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
4337
4562
  `branch-deleted` (not written since 0.41.0: no retire deletes a branch;
4338
4563
  older logs hold it), `child-spawn-refused`, `launch-warning` (0.30: a
4339
4564
  `launch` hook's warning at session start/restart, `data: {message}`),
4565
+ `retire-warning` (a retire hook's warning, `data: {message}`: one row per
4566
+ entry of the retire hooks' `warnings`, a hook's own `warning` and the
4567
+ kernel's lines about those hooks alike, in their order; written to the
4568
+ workspace log only, as soon as the hooks return, so a retire that then
4569
+ refuses or ends quarantined keeps them, and each run of the hooks, a retry
4570
+ among them, adds its own; older clients read it as an unknown kind),
4340
4571
  `recomposed` (from earlier kernels), `waiting` (0.40: a producer's claim,
4341
4572
  [Waiting on you](#waiting-on-you)), `wake-held` (feature `wake-hold`: a
4342
4573
  scheduled wake began to hold, one row per hold, `data: {schedule, since,
@@ -4349,6 +4580,12 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
4349
4580
  credentials, `member` a key or `null`, `hooks` the `worktree` hooks'
4350
4581
  receipt). `producer` is `kernel`, a capability id,
4351
4582
  or another producer id (`agent`). Older rows may carry `eventsApi: 1`.
4583
+ The `message` of a `launch-warning` or `retire-warning` row is the
4584
+ warning's text as stored: control, bidi and hidden characters replaced
4585
+ with U+FFFD, cut to 2048 UTF-16 code units ending in `…` (never through a
4586
+ surrogate pair); a warning that is not a string is stored as its JSON.
4587
+ Clients show it as plain text. The answer that carried the warning
4588
+ (`warnings`) keeps it as it was said.
4352
4589
  `launched` is written by spawn and, since 0.40, once per session start or
4353
4590
  restart, as soon as the session exists (`data: {harness, backend,
4354
4591
  launchConfig, phase, startId}`; spawn's row has neither `phase` nor
@@ -4363,7 +4600,8 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
4363
4600
  - `retired` (`data: {agent, keepDir, self, quarantine, workRecovery, hooks,
4364
4601
  reason?}`) is written to the workspace log only,
4365
4602
  `<deployment>/.agents/events/<agent>--<instance>.jsonl`, which outlives the
4366
- home. `reason` is present only when
4603
+ home. What its hooks warned is not in it: those are the `retire-warning`
4604
+ rows written before it. `reason` is present only when
4367
4605
  the retire completed a self-retire an older OATS recorded with
4368
4606
  `--delete-branch` (since 0.41.0: `this self-retire was requested with
4369
4607
  --delete-branch by an older OATS; retirement no longer deletes branches, so
@@ -4488,8 +4726,8 @@ before whether or not a claim is set. `attention` never marks a screen an Enter
4488
4726
  answers: a producer that wants one uses `question`, and review catches that.
4489
4727
 
4490
4728
  ```text
4491
- oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] --json
4492
- oats instance attention [--message <text>] [--clear] --json
4729
+ oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] --json
4730
+ oats instance attention [--message=<text>] [--clear] --json
4493
4731
  ```
4494
4732
 
4495
4733
  ```json
@@ -5116,12 +5354,21 @@ The sweep reports each of these `skipped`, `lifecycle-busy`
5116
5354
  apply refuses a home that is not stopped, so it stops nothing: beside a
5117
5355
  resume that is still starting, it meets the claim.
5118
5356
 
5119
- Upgrade requires a stopped session. It also holds the start's
5120
- `.oats-start.lock` mutex until its final invocation receipt is persisted. A
5121
- start reaches that mutex only once it holds the claim, so beside an upgrade
5122
- that runs it is refused at the claim (`E_LIFECYCLE_BUSY`); the mutex answers
5123
- (`E_SESSION_START_BUSY`, naming the same-key retry) only when an upgrade that
5124
- died left it. A partial receipt refuses starts through the remaining
5357
+ Upgrade requires a stopped session. It also keeps a file at the home's
5358
+ `.oats-start.lock` until its final invocation receipt is persisted. A start
5359
+ makes nothing at that path and reads it only once it holds the claim, so
5360
+ beside an upgrade that runs it is refused at the claim (`E_LIFECYCLE_BUSY`);
5361
+ the file answers (`E_SESSION_START_BUSY`, naming the same-key retry) only
5362
+ when an upgrade that died left it. A directory at that path is the start lock
5363
+ of an earlier OATS: a start refuses it with `E_SESSION_START_LOCK_STUCK`,
5364
+ `<path> is the start lock directory of an earlier OATS; nothing was stopped
5365
+ or started. Once no earlier oats is running, remove that directory and
5366
+ retry`, and never removes it. Anything else there is refused with the same
5367
+ code: `<path> is neither a package upgrade's file nor an earlier OATS's start
5368
+ lock directory; nothing was stopped or started. Remove it and retry`. An
5369
+ upgrade apply that meets such a directory answers `E_SESSION_RUNNING`, `<name>:
5370
+ <path> is a start lock left by an earlier OATS; upgrade never removes it.
5371
+ Once no earlier oats is running, remove that directory and retry`. A partial receipt refuses starts through the remaining
5125
5372
  finalization (`E_UPGRADE_PARTIAL`): the CLI checks it first, before it reads
5126
5373
  the home's live teams, except while an upgrade holds the claim, which then
5127
5374
  answers. The following stop/retire notes describe the original table.
@@ -5305,6 +5552,7 @@ had begun.
5305
5552
  | Code | `oats instance stop` | `oats retire` |
5306
5553
  |---|---|---|
5307
5554
  | `E_BAD_ARGS` | yes | yes |
5555
+ | `E_USAGE` | yes | yes |
5308
5556
  | `E_PLAN_STALE` | yes | yes |
5309
5557
  | `E_INSTANCE_RETIRING` | yes | yes |
5310
5558
  | `E_LIFECYCLE_BUSY` | yes | yes |
@@ -5763,6 +6011,18 @@ extra tree that is not clean is moved the same way; a clean one is removed.
5763
6011
  oats retire <instance> [--plan-revision <rev> --idempotency-key <key>] [--discard-worktree] [--home <abs>] --json
5764
6012
  ```
5765
6013
 
6014
+ A flag retire does not read, or an argument after the instance, is refused
6015
+ with `E_BAD_ARGS` before any effect, `--plan` and `--server` included:
6016
+ `oats retire: unknown flag <flag>` with `error.details.flag`, or `oats retire:
6017
+ unexpected argument "<word>" after the instance "<instance>": retire takes one
6018
+ instance` with `error.details.argument`, each followed by the usage line. The
6019
+ flags are `--plan`, `--plan-revision`, `--idempotency-key`, `--home`, `--dir`,
6020
+ `--server`, `--self`, `--discard-worktree`, `--keep-dir`, `--force` and
6021
+ `--json` ([souls-and-instances.md](souls-and-instances.md#retire)).
6022
+ A retire with no instance is `E_USAGE`, with the usage line as
6023
+ `error.message`: one envelope under `--json`, the usage line on stderr
6024
+ without it. An unknown flag before the instance is still `E_BAD_ARGS`.
6025
+
5766
6026
  A first retire prints the **raw receipt**, not an envelope:
5767
6027
 
5768
6028
  ```json
@@ -6569,6 +6829,11 @@ results with package drift include `drift:[{capability, recorded:{version,commit
6569
6829
  locked:{version,commit}}]` for package modules behind the deployment lock,
6570
6830
  and omit the field when none are behind. Text prints one line after the start:
6571
6831
  `<n> package module(s) behind the lock (<cap> <version> @ <shortcommit> → <version> @ <shortcommit>); to move them: oats instance stop <instance>; oats instance upgrade <instance> --plan`.
6832
+ `drift` lists only modules an upgrade moves in place. Package modules an
6833
+ upgrade keeps, because their package is no longer locked or no longer
6834
+ provides the capability, add one string to `warnings`, printed as a
6835
+ `WARNING:` line:
6836
+ `<n> package module(s) cannot move in place (<cap>: package <id> is no longer locked; <cap>: package <id> no longer provides it); an upgrade keeps them as they are, so respawn this instance to move it onto the lock`.
6572
6837
  Restart has no upgrade flag. A partial upgrade receipt refuses a start with
6573
6838
  `E_UPGRADE_PARTIAL`, naming the retry with the original idempotency key.
6574
6839
  A committed receipt with `steps.cleaned: false` permits start and adds one
@@ -6628,13 +6893,20 @@ warning naming the same-key cleanup retry.
6628
6893
  `E_UNIDENTIFIED_INSTANCE_HOME` (the home's `instance.json`
6629
6894
  [cannot be read](#unreadable-record): nothing was started, `start` and
6630
6895
  `restart`),
6631
- `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY` (feature
6896
+ `E_SESSION_START_BUSY`, `E_SESSION_START_LOCK_STUCK` (a start lock
6897
+ directory an earlier OATS left at `<home>/.oats-start.lock`, or anything
6898
+ else there that is not a package upgrade's file; the message names it and
6899
+ what to remove; nothing was started or stopped:
6900
+ [Commands that meet on one home](#lifecycle-pairs)),
6901
+ `E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY` (feature
6632
6902
  `lifecycle-claim-start`: a stop or an upgrade of the home holds its
6633
6903
  lifecycle claim, or the claim cannot be read or taken; `details.holder`,
6634
6904
  `details.action`; nothing was started or stopped:
6635
6905
  [Commands that meet on one home](#lifecycle-pairs)), `E_LAUNCH_*` (among them
6636
6906
  `E_LAUNCH_SHIM`: the home's `oats` link cannot be written, nothing was
6637
6907
  started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`,
6908
+ `E_CLAUDE_LOGIN_CREDENTIAL` (the effective Claude config has a `/login`
6909
+ credential file alongside an OATS-set token; other harnesses are unaffected),
6638
6910
  `E_HARNESS_RESOURCE_MISSING` (a harness package an active capability
6639
6911
  requires is not installed, disabled, or cannot be verified: nothing was
6640
6912
  started; `E_HARNESS_PACKAGE` before 0.56.0), `E_SESSION_FAILED`
@@ -6693,10 +6965,10 @@ answer is the ordinary start answer plus one object:
6693
6965
  - Refused `E_RESUME_NOT_LOST` when the home did not lose its session
6694
6966
  (`stopped`, `exited`, never launched), read under the claim and the start
6695
6967
  lock before any launch hook runs; nothing was started.
6696
- - Refused `E_LAUNCH_ENV_CHANGED` when a `{fromEnv}` value differs from the
6697
- one the start it brings back ran with (checked after `E_LAUNCH_ENV_MISSING`):
6698
- the message names the variables, sorted, never a value; nothing was
6699
- started. A home with no record of its last start's values (last started
6968
+ - Refused `E_LAUNCH_ENV_CHANGED` when a reference value (`fromEnv` or
6969
+ `fromFile`) differs from the one the start it brings back ran with (checked after `E_LAUNCH_ENV_MISSING`):
6970
+ the message names the sources (an environment name or `file:<path>`),
6971
+ sorted, never a value; nothing was started. A home with no record of its last start's values (last started
6700
6972
  by an earlier kernel, or a record that does not read) is resumed, and
6701
6973
  `warnings` carries once `<instance>'s launch environment could not be
6702
6974
  verified this once (it was last started before OATS recorded it); its
@@ -6801,7 +7073,31 @@ whatever the rows say:
6801
7073
  launched something: `resumed`, `fresh`, `blocked`) are kernel-private,
6802
7074
  not a contract. Without a boot id (neither Linux nor macOS) nothing is
6803
7075
  noted or counted.
6804
- - Errors: `E_RESUME_BUSY`; `E_BAD_ARGS` (`--deployment` that is not a
7076
+ - **A lock that needs a person.** `E_RESUME_LOCK_STUCK`, through the same
7077
+ envelope at exit 1, when the sweep's lock cannot be taken and no sweep is
7078
+ known to run; nothing was started, and no sweep starts anything on this
7079
+ machine until it can be. `error.details` is `{lock, found}`: `lock` is
7080
+ the lock's absolute path, and `found` is one of
7081
+
7082
+ | `found` | what is at the lock's path | what to do |
7083
+ |---|---|---|
7084
+ | `unreadable` | a record that cannot be read | remove the file once no sweep runs |
7085
+ | `unknown` | a holder that cannot be told to be running or gone | remove the file once no sweep runs |
7086
+ | `cannot-take-over` | a gone holder's record that cannot be taken over | remove the file |
7087
+ | `held-again` | a lock that was taken again each time the sweep found it free | run the sweep again |
7088
+ | `own-start-unreadable` | nothing in the way: the sweep cannot read its own start time, so it could not hold the lock | run the sweep again; nothing is to be removed |
7089
+ | `directory` | a directory, the lock of an OATS that locked with one; it is never removed for the operator | remove the directory once no earlier `oats` runs |
7090
+
7091
+ The message says the same in words, with what to do
7092
+ ([The sweep](execution-targets.md#the-sweep)). It is never
7093
+ `E_RESUME_BUSY`: that code is a sweep that runs. `readResumeSweep` reads
7094
+ it as `failed` with the code. `oats doctor --json` lists the same states
7095
+ as one `resume-lock-stuck` problem in `problems[]`, `{code, message,
7096
+ remedy}` (text: `! resume-lock-stuck: <message>`, the remedy on the next
7097
+ line), read without taking the lock; a free lock, a sweep that runs and a
7098
+ lock a gone sweep left are not listed, and doctor's exit status does not
7099
+ change.
7100
+ - Errors: `E_RESUME_BUSY`; `E_RESUME_LOCK_STUCK`; `E_BAD_ARGS` (`--deployment` that is not a
6805
7101
  deployment directory, `--server`, an unknown flag or an argument); without
6806
7102
  `--deployment`, the list's own errors (`E_DEPLOYMENTS_INVALID`,
6807
7103
  `E_DEPLOYMENTS_VERSION`). A home's start failure is a row, never the
@@ -6900,7 +7196,7 @@ reading asks it for a live read, and every other reading for nothing
6900
7196
  passes its own exec must keep those three properties: detached, file-backed,
6901
7197
  and never signalling the child.
6902
7198
  - It answers the kernel's envelope: the result at exit 0, and an `ok:false`
6903
- envelope whatever the exit (`E_RESUME_BUSY` exits 1). Otherwise it answers
7199
+ envelope whatever the exit (`E_RESUME_BUSY` and `E_RESUME_LOCK_STUCK` exit 1). Otherwise it answers
6904
7200
  a code of its own, with no message: `E_CLI_OUTPUT_LIMIT` (more than 4 MiB),
6905
7201
  `E_CLI_PROTOCOL` (no envelope), `E_CLI_FAILED` (a nonzero exit without an
6906
7202
  `ok:false` envelope, or an exec that throws). No stderr and no exception text
@@ -6937,15 +7233,17 @@ accept `--server <id>`.
6937
7233
  ```json
6938
7234
  {"context":"/w","level":"/w","file":"/w/oats-local.yaml","selected":null,
6939
7235
  "configurations":[{"name":"reviewers","harness":"claude","executable":null,"args":["--permission-mode","plan"],
6940
- "env":{"ANTHROPIC_API_KEY":{"fromEnv":"REVIEW_KEY"},"REVIEW_MODE":{"redacted":true}},
7236
+ "env":{"ANTHROPIC_API_KEY":{"fromEnv":"REVIEW_KEY"},"CLAUDE_CODE_OAUTH_TOKEN":{"fromFile":"/etc/agent-login/claude-token"},"REVIEW_MODE":{"redacted":true}},
6941
7237
  "model":"opus","yolo":null,"default":false,"source":"/w/oats-local.yaml","shadows":[]}]}
6942
7238
  ```
6943
7239
 
6944
7240
  - **list**: `selected` is `null`, `{home, instance}` or `{soul, agentsRoot}`;
6945
7241
  `level` and `file` are `null` without an `oats-local.yaml` (the set is then
6946
7242
  empty). An environment literal is `{redacted: true}`, a reference
6947
- `{fromEnv}`; values never leave the file. `default` (0.32, feature
6948
- `launch-config-default`) is always a boolean: `true` marks this host's
7243
+ `{fromEnv: NAME}` or `{fromFile: /absolute/path}`; resolved values are never
7244
+ returned. File references hold credential values; directory selectors require
7245
+ a literal or `fromEnv` ([configuration.md](configuration.md)). `default`
7246
+ (0.32, feature `launch-config-default`) is always a boolean: `true` marks this host's
6949
7247
  default for the configuration's harness.
6950
7248
  - **set**/**remove**: `{name, action, level, file, before, after,
6951
7249
  effective}`. `set --file` takes `{harness, executable?, args?, env?, model?,
@@ -6981,8 +7279,8 @@ accept `--server <id>`.
6981
7279
  - **preview** (read-only) answers `{context, selected, selection: {source,
6982
7280
  launchConfig, harness, model, yolo}, harness, model, modelSource, yolo,
6983
7281
  launchConfig, launchConfigSource, launchConfigDefault, executable: {path,
6984
- declared, resolvedFrom}, argv, environment: [{name, fromEnv} | {name, redacted:
6985
- true} | {name, reference: true}], command (redacted), prompt, hooks,
7282
+ declared, resolvedFrom}, argv, environment: [{name, fromEnv} | {name, fromFile}
7283
+ | {name, redacted: true} | {name, reference: true}], command (redacted), prompt, hooks,
6986
7284
  preflight: [{check, ok, detail, code?}], ok}`. A failed check carries the
6987
7285
  code a start would refuse with; the `harness-packages` check's is the
6988
7286
  gate's own, `E_HARNESS_RESOURCE_MISSING` (`E_HARNESS_PACKAGE` before
@@ -7439,6 +7737,47 @@ One warning per command, however many old spellings it read:
7439
7737
  The `--server` routes translate for a host without the `harness` feature:
7440
7738
  they send `--runtime` and `runtime` keys and read its `runtimes` list.
7441
7739
 
7740
+ <a id="harness-token"></a>
7741
+ ### `harness token`
7742
+
7743
+ `oats harness token set|status|remove <harness> --server <id> [--name <team>] [--stdin] [--debug] --json`
7744
+ runs on the operator's machine. Its `--server` selects that registration's
7745
+ separate operator route, never a remote invocation of this CLI. The harness
7746
+ is `claude`, `codex`, `pi` or `opencode`; the name defaults to a valid
7747
+ server label and otherwise is required. The ordinary schemaVersion 1 envelope's
7748
+ result is:
7749
+
7750
+ ```json
7751
+ {"server":"build","action":"status","harness":"claude","name":"team","fingerprint":"sha256:0123456789abcdef","replacedAt":"2026-11-10T00:00:00Z","warnings":[]}
7752
+ ```
7753
+
7754
+ For `remove`, `action` is `remove` and `fingerprint` is `null`.
7755
+ `set --stdin` returns `action: "set"` and also `staleInstances`, an array
7756
+ of `{instance, agent, home, startedAt}` from that server's status rows, with
7757
+ the same harness and a last-start time before or during the second named by
7758
+ `replacedAt`. The receiver records whole seconds, so starts during that second
7759
+ are included conservatively: they may still use the previous credential. If
7760
+ that roster cannot be read, `staleInstances` is `null` and `warnings` holds
7761
+ a plain explanation; the installation remains successful. No automatic
7762
+ restart is performed. Only `set` accepts stdin, as bounded credential bytes;
7763
+ there is no credential argument, result field, event or file on the client.
7764
+ The receiver's single JSON line and exit status must agree, name the requested
7765
+ harness and team, and carry valid metadata. Malformed or oversized replies fail
7766
+ closed as unexpected replies. Text-mode refusal messages escape remote control
7767
+ characters for the terminal. C0 controls and DEL in refusal reasons become
7768
+ spaces in both modes; JSON retains the remaining characters without terminal escaping.
7769
+ The submitted credential is redacted in both modes.
7770
+ Refusals: `E_BAD_ARGS` for unsupported arguments or names,
7771
+ `E_SERVER_UNKNOWN` for a server id without a registration, even with an orphan operator route,
7772
+ `E_HARNESS_TOKEN_ROUTE` for a missing operator alias,
7773
+ `E_HARNESS_TOKEN_INPUT` for invalid, too-large or terminal stdin,
7774
+ `E_HARNESS_TOKEN_UNSUPPORTED` for unavailable interactive capture or a
7775
+ refreshing sign-in, and
7776
+ `E_HARNESS_TOKEN_DELIVERY` for connection failure, receiver refusal or an
7777
+ unexpected reply. Public errors do not forward raw SSH or malformed receiver
7778
+ output. `--debug` adds transport facts on stderr, never stdin or raw receiver
7779
+ output that might echo it. See [servers](servers.md#harness-credentials).
7780
+
7442
7781
  ### `harness trust`
7443
7782
 
7444
7783
  `oats harness trust [--dir <deployment>] [--harness claude|codex|all] [--plan] [--json]`