@awebai/oats 0.69.12 → 0.69.15

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 (92) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +254 -201
  3. package/docs/capabilities.md +58 -13
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +291 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +590 -55
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +84 -9
  11. package/docs/first-team.md +4 -3
  12. package/docs/implementation.md +99 -32
  13. package/docs/integrations.md +3 -2
  14. package/docs/knowledge-and-learning.md +72 -0
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +39 -5
  17. package/docs/packages.md +93 -14
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.13.md +767 -0
  20. package/docs/release-notes/v0.69.14.md +83 -0
  21. package/docs/release-notes/v0.69.15.md +444 -0
  22. package/docs/schedules.md +159 -5
  23. package/docs/servers.md +241 -7
  24. package/docs/souls-and-instances.md +223 -14
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +36 -5
  27. package/docs/workspaces.md +31 -5
  28. package/lib/claim.mjs +20 -5
  29. package/lib/command-flags.mjs +240 -0
  30. package/lib/core.mjs +1004 -633
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +145 -33
  33. package/lib/errors.mjs +3 -2
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/host-run.mjs +218 -0
  36. package/lib/host-stop-child.mjs +21 -0
  37. package/lib/hot-reads.mjs +4 -3
  38. package/lib/instance-events.mjs +28 -6
  39. package/lib/instance-git.mjs +165 -14
  40. package/lib/instance-inspect.mjs +6 -1
  41. package/lib/instance-lifecycle.mjs +4 -3
  42. package/lib/instance-listing.mjs +114 -43
  43. package/lib/instance-resolution.mjs +56 -3
  44. package/lib/instance-upgrade.mjs +16 -20
  45. package/lib/kernel-features.mjs +4 -1
  46. package/lib/launch-env-exec.sh +7 -0
  47. package/lib/launch-env.mjs +74 -0
  48. package/lib/launch-preference.mjs +19 -12
  49. package/lib/member-clone.mjs +7 -1
  50. package/lib/packages.mjs +74 -2
  51. package/lib/read-call.mjs +4 -1
  52. package/lib/reader.mjs +3 -2
  53. package/lib/refused-text.mjs +3 -2
  54. package/lib/remote.mjs +126 -31
  55. package/lib/retained-after-retire.mjs +2 -7
  56. package/lib/retire-git-forms.mjs +41 -0
  57. package/lib/retire-incomplete.mjs +96 -0
  58. package/lib/schedule.mjs +239 -21
  59. package/lib/servers.mjs +161 -28
  60. package/lib/session-end.mjs +28 -8
  61. package/lib/session-resume.mjs +63 -56
  62. package/lib/session-seen.mjs +3 -14
  63. package/lib/start-env.mjs +13 -7
  64. package/lib/status-words.mjs +11 -4
  65. package/lib/system-tools.mjs +1 -36
  66. package/lib/teams.mjs +11 -4
  67. package/lib/upgrade-state.mjs +13 -2
  68. package/lib/worktree-hooks.mjs +6 -175
  69. package/lib/worktree.mjs +68 -10
  70. package/package-catalog.json +1 -1
  71. package/package.json +5 -1
  72. package/packages/client/instance-lifecycle.mjs +1 -1
  73. package/packages/client/lifecycle-contract.mjs +3 -1
  74. package/packages/client/session-resume-cli.mjs +2 -1
  75. package/packages/client/session-start.mjs +10 -7
  76. package/packages/client/workspace-cli.mjs +5 -1
  77. package/packages/record/README.md +56 -21
  78. package/packages/record/docs/capture-service.md +8 -5
  79. package/packages/record/docs/turn-record-sot.md +9 -0
  80. package/packages/record/lib/capture-health.mjs +6 -4
  81. package/packages/record/lib/capture-lock.mjs +31 -27
  82. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  83. package/packages/record/lib/capture-scratch.mjs +2 -1
  84. package/packages/record/lib/derived-state.mjs +4 -2
  85. package/packages/record/lib/index-db.mjs +4 -2
  86. package/packages/record/lib/lock-holder.mjs +21 -0
  87. package/packages/record/lib/private-files.mjs +18 -0
  88. package/packages/record/lib/process-identity.mjs +310 -0
  89. package/packages/record/lib/store.mjs +31 -25
  90. package/share/oats-login-receive +204 -0
  91. package/skills/oats-getting-started/SKILL.md +93 -26
  92. package/lib/tmux-config.mjs +0 -35
@@ -171,6 +171,8 @@ see the [official catalog](official-catalog.md) for current pins.
171
171
  | `spawn-attribution` | the kernel validates who spawned an instance: `spawnedBy` (`{instance, home}` or `null`) in `instance.json`, on the `spawned` event and on `oats status --json` rows and remote rows, and `OATS_SPAWNER_HOME` for spawn hooks ([Spawned by](#spawned-by)); `attributedHuman` on `oats status --json` rows and on remote rows ([Attributed human](#attributed-human)). Absent: no `spawnedBy` and no `attributedHuman`, and a capability must not read a missing `OATS_SPAWNER_HOME` as a person's spawn | |
172
172
  | `workspace-tasks-payload` | oats-workspace.yaml may carry a top-level `tasks:` payload, merged for the capability that fills the tasks slot exactly as `messaging:` is for the messaging one; its leaves' `settingsOrigins` are `{kind: "workspace", at: "oats-workspace.yaml#/tasks"}` ([Provider payloads have three homes](workspaces.md#provider-payloads-have-three-homes)). A kernel without it refuses a workspace file that carries `tasks:` (unknown property) | |
173
173
  | `settings-committed-only` | a manifest `settings.<key>.committedOnly: true` is enforced: that key in oats-local.yaml `settings.<cap>` or a `--provider <cap>` flag is refused `E_WORKSPACE_SCHEMA` reason `committed-only-key`, with `details.layer`, `details.at` and `details.allowed` ([Commands and hooks](capabilities.md#commands-and-hooks)). A kernel without it ignores the flag and merges the key | |
174
+ | `schedule-host-register-only` | `oats schedule host install --register-only`: the scope is recorded in the host schedule registry and no timer is installed ([`oats schedule`](#oats-schedule)). Routed with `--server`, the option is sent only to a host that lists this and `schedule`; otherwise it is refused here with `E_REMOTE_INCOMPATIBLE` before anything is sent, since a host without it ignores the option and installs a timer | |
175
+ | `spawn-task-stdin` | `oats spawn <soul> --task-file -` reads the task from standard input. A spawn routed with `--server` sends its `--task` or `--task-file` text that way, to the preview and to the apply, to a host that lists this, and not as an argument; a host that does not list it gets the text as an argument, and the answer's `warnings` gains one line that says it was readable in both machines' process lists ([servers.md](servers.md#a-routed-spawns-task)) |
174
176
 
175
177
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
176
178
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -296,6 +298,120 @@ accepted, and its value is only ever the message. A capability command's own fla
296
298
  typed; the kernel reads only its dispatch flag (`--soul`). There is no feature
297
299
  string for this: to support older kernels, use the spaced form.
298
300
 
301
+ <a id="command-flags"></a>
302
+ ### The flags a command defines
303
+
304
+ These commands change state (and `oats teams`, `oats server check`,
305
+ `oats trigger poll` and `test`, which sit beside them), and each refuses a
306
+ flag it does not define before anything happens: before a plan is read, a
307
+ file is written, a process is stopped or started, and before a `--server`
308
+ command is sent to its host. A typo of a protective flag (`--no-recursve`
309
+ for `--no-recursive`) is never ignored.
310
+
311
+ | Command | Arguments | Flags that take a value | Switches | Refused in their own words | Its own answers |
312
+ |---|---|---|---|---|---|
313
+ | `oats retire` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir`, `--server` | `--plan`, `--self`, `--discard-worktree`, `--keep-dir`, `--force`, `--json` | `--delete-branch` | none |
314
+ | `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 |
315
+ | `oats sync` | none | `--dir` | `--plan`, `--json` | `--approve` | none |
316
+ | `oats instance stop` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--grace-ms`, `--home`, `--dir`, `--server` | `--plan`, `--apply`, `--no-recursive`, `--json` | none | none |
317
+ | `oats instance upgrade` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir` | `--undo`, `--plan`, `--json` | `--server` | none |
318
+ | `oats instance color` | `<instance>` `[<color>]` | `--home`, `--dir`, `--server` | `--clear`, `--json` | none | none |
319
+ | `oats instance background` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
320
+ | `oats instance same-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
321
+ | `oats instance waiting set` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
322
+ | `oats instance waiting clear` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
323
+ | `oats instance attention` | none | `--message` | `--clear`, `--json` | `--home`, `--dir`, `--producer`, `--reason` | none |
324
+ | `oats instance suggest-name` | none | `--soul`, `--task`, `--task-file`, `--harness`, `--model`, `--launch-config`, `--dir` | `--json` | `--server` | none |
325
+ | `oats worktree add` | none | `--purpose`, `--branch`, `--base`, `--repo` | `--preview`, `--json` | `--server`, `--dir`, `--home` | none |
326
+ | `oats worktree remove` | none | `--purpose` | `--json` | `--server`, `--dir`, `--home` | none |
327
+ | `oats session start` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json`, `--resume` | `--native-record` | none |
328
+ | `oats session restart` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server`, `--stop-grace` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json` | `--native-record`, `--resume` | none |
329
+ | `oats session resume` | none | `--deployment` | `--plan`, `--json` | `--native-record`, `--server` | none |
330
+ | `oats session input` | none | `--home`, `--text-file` | `--json` | `--native-record` | none |
331
+ | `oats session receive` | none | `--home`, `--name` | `--json` | `--native-record` | none |
332
+ | `oats session upload` | none | `--file`, `--home`, `--instance`, `--server` | `--json` | `--native-record` | none |
333
+ | `oats session attach` | none | `--detach-key`, `--home`, `--instance`, `--server` | `--no-status-line`, `--print`, `--json` | `--native-record` | none |
334
+ | `oats schedule add` | `[<id>]` | `--file`, `--spec-json`, `--description`, `--workspace`, `--runs-on`, `--owner`, `--dir`, `--server` | `--json` | none | none |
335
+ | `oats schedule update` | `<id>` | `--file`, `--spec-json`, `--description`, `--dir`, `--server` | `--json` | none | none |
336
+ | `oats schedule remove` | `<id>` | `--dir`, `--server` | `--force`, `--json` | none | none |
337
+ | `oats schedule run` | `<id>` | `--dir`, `--server` | `--force`, `--json` | none | none |
338
+ | `oats schedule enable` | `<id>` | `--dir`, `--server` | `--json` | none | none |
339
+ | `oats schedule disable` | `<id>` | `--dir`, `--server` | `--json` | none | none |
340
+ | `oats schedule reconcile` | `<id>` | `--dir`, `--server` | `--clear`, `--json` | none | none |
341
+ | `oats schedule tick` | none | `--dir`, `--server` | `--dry-run`, `--host`, `--json` | none | none |
342
+ | `oats schedule host install` | none | `--max-concurrent`, `--triggers-max-concurrent`, `--os`, `--dir`, `--server` | `--register-only`, `--print`, `--json` | none | none |
343
+ | `oats schedule host uninstall` | none | `--dir`, `--server` | `--json` | none | none |
344
+ | `oats host run` | none | `--stop-grace` | `--plan`, `--json` | none | none |
345
+ | `oats trigger add` | none | `--file`, `--from`, `--set`, `--id`, `--description`, `--workspace`, `--runs-on`, `--owner`, `--dir` | `--json` | none | none |
346
+ | `oats trigger poll` | `<id>` | `--dir`, `--max-age` | `--run-source`, `--json` | none | none |
347
+ | `oats trigger test` | `<id>` | `--dir` | `--run-source`, `--json` | none | none |
348
+ | `oats trigger remove` | `<id>` | `--dir` | `--json` | none | none |
349
+ | `oats trigger enable` | `<id>` | `--dir` | `--json` | none | none |
350
+ | `oats trigger disable` | `<id>` | `--dir` | `--json` | none | none |
351
+ | `oats teams` | none | `--dir`, `--max-age` | `--json` | none | an unknown flag, an argument after the last |
352
+ | `oats teams add` | `<label>` | `--dir`, `--team`, `--description` | `--no-default`, `--json` | none | an unknown flag |
353
+ | `oats teams remove` | `<label>` | `--dir` | `--json` | none | an unknown flag |
354
+ | `oats teams default` | `<label>` | `--dir`, `--expect` | `--if-absent`, `--json` | none | an unknown flag |
355
+ | `oats soul launch set` | `<soul>` | `--dir`, `--launch-config`, `--harness`, `--model` | `--plan`, `--json` | none | an unknown flag, an argument after the last |
356
+ | `oats soul launch remove` | `<soul or key>` | `--dir` | `--plan`, `--json` | none | an unknown flag, an argument after the last |
357
+ | `oats server check` | `<id>` | none | `--json` | none | none |
358
+ | `oats server remove` | `<id>` | none | `--json` | none | none |
359
+ | `oats server forget` | `<id>` | `--instance` | `--json` | none | none |
360
+ | `oats package add` | `<id>` `<version>` | `--dir` | `--json` | none | none |
361
+ | `oats package remove` | `<id>` | `--dir` | `--json` | none | none |
362
+ | `oats launch-config set` | `<name>` | `--file`, `--dir`, `--server` | `--keep-env`, `--json` | `--home`, `--soul` | none |
363
+ | `oats launch-config remove` | `<name>` | `--dir`, `--server` | `--json` | `--home`, `--soul` | none |
364
+ | `oats automations refresh` | none | `--dir` | `--json` | none | none |
365
+ | `oats update` | none | `--dir` | `--check`, `--yes`, `--json` | `--to` | an argument after the last |
366
+
367
+ An argument in brackets (`[<color>]`) is one the command may go without.
368
+ A flag marked with a number of words (`--provider`, two: `--provider
369
+ <capability> key=value`) takes that many.
370
+
371
+ The refusal is `E_BAD_ARGS`, with the command's usage line after the
372
+ message, and comes from the first problem from the left:
373
+
374
+ - a flag the command does not define: `oats <command>: unknown flag
375
+ <flag>`, `error.details: {flag}`;
376
+ - a value on a switch: `oats <command>: <flag> takes no value (got
377
+ <flag>=<value>)`, `error.details: {flag}`;
378
+ - an argument after the last one the command takes: `oats <command>:
379
+ unexpected argument "<word>" after the <name> "<value>": <command> takes
380
+ one <name>`, or `<command> takes no argument`, `error.details: {argument}`;
381
+ - a flag refused in its own words: that message (for example
382
+ `--delete-branch` on retire, `--server` on `oats instance upgrade`),
383
+ `error.details: {flag}`.
384
+
385
+ A command whose last column names an answer gives that one in its own words:
386
+
387
+ - `oats spawn`: `oats spawn: unknown flag <flag>`, and `oats spawn:
388
+ unexpected argument "<word>" after the soul "<soul>": spawn takes one
389
+ soul` (for a `key=value` word, `a capability setting is given as
390
+ --provider <capability> key=value`), `E_BAD_ARGS` with no usage line and
391
+ no `details`;
392
+ - `oats teams` and its forms, `oats soul launch set` and `remove`: the
393
+ flag is `E_USAGE {flag}` in their words ([`oats teams`](#oats-teams),
394
+ [`oats soul launch`](#oats-soul-launch)); a word where `oats teams`
395
+ takes a form is `E_USAGE` with its usage; a second soul of `oats soul
396
+ launch` is `E_BAD_ARGS`, `takes one soul, and got <n>: …`, naming
397
+ every one;
398
+ - `oats update <word>`: ``oats update takes no package: pin package
399
+ versions in oats-workspace.yaml (`oats package add <id> <version>`), then
400
+ `oats sync`; …``, `E_BAD_ARGS`, `error.details: {argument}`.
401
+
402
+ Then, for a command given `--server`, a missing argument it requires is
403
+ `E_USAGE`, with the usage line as `error.message` and no `details`, and
404
+ nothing is sent. On this machine each command answers a missing argument
405
+ itself, as before (`oats retire` with no instance is `E_USAGE` too).
406
+
407
+ A flag that takes a value takes the next word (its number of words) unless
408
+ it starts with `--`; a value after `=` is its first. A value flag given
409
+ none (no word, or one that starts with `--`) ends the check there: it is
410
+ that flag's own refusal, by the command, before any flag after it. `--` is a flag like any other, and none of
411
+ these commands defines it. `--runtime` is the pre-0.27 name of
412
+ `--harness`. `--help` and `-h` print the usage first, as for every
413
+ kernel command.
414
+
299
415
  ### Dispatch errors
300
416
 
301
417
  | Code | When |
@@ -320,6 +436,11 @@ failure as `E_SSH`, message `ssh to <host> failed: …`:
320
436
  retrying cannot help.
321
437
  - No `details`: ssh ran and the link failed (unreachable host, refused key,
322
438
  lost connection, timeout); a retry may succeed.
439
+ - `error.details` is `{decision, idempotencyKey, fix}` when the link failed
440
+ under the apply of a routed spawn the route bound itself
441
+ ([Idempotency](#spawn-idempotency-routed)): the host may have started the
442
+ spawn, and the same spawn with `--expect-decision <decision.revision>
443
+ --idempotency-key <idempotencyKey>` answers that one instance.
323
444
 
324
445
  (0.31.0; before it `E_SSH` never carried details.)
325
446
 
@@ -803,7 +924,13 @@ and ships the soul at the locked commit, and the soul's copy is intact: for
803
924
  `--home`, the home's copy matches the digest it recorded, and a lock still
804
925
  at that commit records the same digest. The copy is digested on every read.
805
926
  It fails otherwise, with `code: "E_PACKAGE_INTEGRITY"` on a digest mismatch
806
- and the remedy naming `oats sync` or a fresh spawn.
927
+ and the remedy naming `oats sync` or a fresh spawn. When the package is no
928
+ longer locked, readiness cannot tell a deliberate drop from an accidental
929
+ unpin or a pending sync, so the `--home` remedy names both, the respawn
930
+ first: if the workspace dropped the package on purpose, spawn a new instance
931
+ from a soul the workspace offers, then retire this one; otherwise declare the
932
+ package in `packages:` and `oats sync`. For `--soul` it is declaring the
933
+ package and `oats sync`.
807
934
 
808
935
  **`providers`** (producer `provider binding check`): for each module whose
809
936
  manifest declares `binding`, the kernel runs its `binding.check` and relays
@@ -1180,6 +1307,13 @@ applies: gate `sync --plan` on `version` 0.44.0 or later, never by trying.
1180
1307
  - Errors: `E_LOCAL_MISSING`, `E_WORKSPACE_SCHEMA {path, problems}`,
1181
1308
  `E_REMOTE_UNREADABLE`, `E_LOCK_SCHEMA`, `E_PACKAGE_MISSING`,
1182
1309
  `E_PACKAGE_INTEGRITY`, `E_PACKAGE_MANIFEST`, `E_REPO_REF`, `E_BAD_ARGS`.
1310
+ `E_PACKAGE_INTEGRITY` names its case in `details.why`: `branch`,
1311
+ `package-id`, and `capabilities` or `souls` for an edited lock; a tag or
1312
+ content that moved carries none
1313
+ ([`oats sync`](packages.md#oats-sync--the-one-command-for-the-common-path)).
1314
+ The Desktop's sync sheet words the refusal per `why`, and gives no `why`, or
1315
+ one it doesn't know, the code's general meaning; its Details show the
1316
+ kernel's message.
1183
1317
 
1184
1318
  ### `oats package add` and `remove`
1185
1319
 
@@ -1578,6 +1712,45 @@ line that gives each kind's total, and at most 50 items per kind
1578
1712
  ([After a retire](souls-and-instances.md#after-a-retire-inspect-restore-dispose)).
1579
1713
  Each element is one line of text with no newline. The answer has no new key.
1580
1714
 
1715
+ `oats doctor --json` lists each retirement left open as one
1716
+ `retire-incomplete` problem in `problems[]`, `{code, message, remedy}`
1717
+ (oats-project/oats#1747). Text prints it as `! retire-incomplete: <message>`
1718
+ with the remedy on the next line. A retirement is open when the home reads
1719
+ quarantined (`rollbackIncomplete`), when its self-retire is `failed` or
1720
+ `interrupted`, or when a failed self-retire left its outcome beside a home
1721
+ that is still there. A home whose retire is `running` or `unknown`, a spawn
1722
+ in progress, and an outcome whose home is gone are not listed. The message
1723
+ names the instance, the home, what is open and since when. The remedy is
1724
+ `oats retire <name> --home <home>`, each word quoted for a shell, and names
1725
+ the capability whose retire hook failed last, or says that none is recorded.
1726
+ Doctor reads this as `oats status` does, offline and read-only. Its exit
1727
+ status does not change: doctor exits 0 with problems. A deployment with no
1728
+ open retirement sees no change.
1729
+
1730
+ `oats doctor --json` lists this machine's session resume lock, when it needs a
1731
+ person, as one `resume-lock-stuck` problem in `problems[]`, `{code, message,
1732
+ remedy}` ([The machine sweep](#the-machine-sweep-oats-session-resume),
1733
+ `E_RESUME_LOCK_STUCK`). It is the machine's, the same from every deployment.
1734
+
1735
+ `oats doctor --json` lists each schedule slot whose record cannot be read, in
1736
+ the deployment and the others the host ticks, as one `schedule-slot-unreadable`
1737
+ problem in `problems[]`, `{code, severity: "warning", scope, id, message,
1738
+ remedy}` (text: `! schedule-slot-unreadable: <message>`, the remedy on the
1739
+ next line). The remedy is to check `oats schedule show <id>`, then run `oats
1740
+ schedule reconcile <id> --clear` ([Schedules](schedules.md#files)); for a
1741
+ workspace schedule this host does not run, or cannot tell it runs, the
1742
+ message says why and the remedy is to remove the slot by hand, at the path it
1743
+ names, once `oats status` shows no run of it here. A slot
1744
+ whose schedule is gone (a local one not in `oats-schedules.json`, a workspace
1745
+ one not in the saved snapshot, whose time it names), readable or not, is one
1746
+ `schedule-slot-orphaned` problem of the same shape, naming the run and the
1747
+ instance its record names; its remedy is to check `oats status`, then run
1748
+ `oats schedule reconcile <id> --clear`. A workspace schedule absent from the
1749
+ snapshot that cannot be shown gone (its member is not in it, or has a schedule
1750
+ file that could not be read) is the same problem, with the step that applies:
1751
+ remove the slot by hand at the path it names, or fix that file and run `oats
1752
+ automations refresh`.
1753
+
1581
1754
  ### Desktop facts
1582
1755
 
1583
1756
  Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
@@ -1848,9 +2021,14 @@ oats teams default <label> [--if-absent | --expect <label>] --json
1848
2021
  Among concurrent `oats teams` writers on one deployment, a conditional write
1849
2022
  therefore never overwrites a default another of them set: when two race, the
1850
2023
  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
2024
+ `E_TEAM_DEFAULT_MISMATCH`. The lock is a file that names the process
2025
+ holding it: one left by a command that was killed is taken over by the next
2026
+ command. A lock whose holder is still running after 5 s is `E_LOCAL_BUSY
2027
+ {path, lock}`, and so is one that cannot be judged: a record that is
2028
+ unreadable, a holder that cannot be told to be running or gone, or a lock
2029
+ directory written by an earlier kernel. The message says which was found and
2030
+ names the path to remove when no oats process is editing; nothing was
2031
+ written. The limits: a person or tool editing
1854
2032
  `oats-local.yaml` directly does not take the lock (the content compare still
1855
2033
  catches most such edits, but not one landing between the compare and the
1856
2034
  rename), and changes to the committed `oats-workspace.yaml` (a pull, a
@@ -2009,7 +2187,7 @@ problem's own keys.
2009
2187
  | `default-team-changed` | warning | `recorded`, `current` | `--home` with live teams: the default changed since the spawn |
2010
2188
  | `E_TEAM_UNKNOWN` | failure | `label`, `at` | a local default no file declares |
2011
2189
  | `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) |
2190
+ | `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
2191
 
2014
2192
  `E_TEAM_UNKNOWN` and local-teams-closed are also spawn, preview and inspect
2015
2193
  refusals (local-teams-closed as `E_WORKSPACE_SCHEMA` with details `{reason,
@@ -2128,7 +2306,7 @@ Every object shape here is closed.
2128
2306
  souls:
2129
2307
  launch:
2130
2308
  "*": opus # every soul on this machine
2131
- oats-expert: opus # a launch configuration
2309
+ oats-engineering-expert: opus # a launch configuration
2132
2310
  oats.engineering/code-reviewer: {harness: codex} # an inline preference
2133
2311
  ```
2134
2312
  - **Migration.** 0.29.x refuses an unknown soul.yaml key, and members are read
@@ -2269,6 +2447,39 @@ shows the drift as `launch-changed`.
2269
2447
  home, `--reselect-launch` included, is never refused this way.
2270
2448
  - `E_WORKSPACE_SCHEMA`: a malformed `launch` or `souls.launch`, path named.
2271
2449
 
2450
+ **A `souls.disabled` entry that names no soul** (oats-project/oats#1772) keeps
2451
+ no soul off this machine, and spawn does not refuse because of it: a stale
2452
+ entry fails open, where a stale `souls.launch` key fails closed. `oats doctor`
2453
+ reports it with the launch check's discipline, offline, from the same read of
2454
+ this machine's cache:
2455
+ - An entry matches when spawn's own rule (`E_SOUL_DISABLED`) holds for a soul
2456
+ the workspace offers: its bare name, or its qualified name (`<package>/<soul>`
2457
+ or `<member>/<soul>`). A disabled soul is still offered. Spawn's rule is
2458
+ exact: `<member>/<soul>` for a soul that only another member offers does not
2459
+ match.
2460
+ - `problems[]` gains `{code: "disabled-soul-unmatched", entry, at,
2461
+ suggestions, message, remedy}` per entry that matches nothing, in file
2462
+ order (text: `! disabled-soul-unmatched: <message>`, then the remedy). `at`
2463
+ is `oats-local.yaml#/souls/disabled/<index>`. `suggestions` holds at most
2464
+ three qualified names of offered souls, ranked as the launch rows rank
2465
+ theirs: the same bare name first, then a bare name within two edits. The
2466
+ message says that it speaks about this machine's last read and that a spawn
2467
+ reads the workspace itself and is the authority. The remedy is the hand
2468
+ edit, replace the entry with the soul it was meant for or remove it: no
2469
+ command writes `souls.disabled`.
2470
+ - An entry is *not checked*, and gets an `information[]` line that starts
2471
+ `disabled-soul-unchecked:` instead of a row, when the source that could
2472
+ hold its soul was not read, for the reasons of the launch check: an entry
2473
+ under a package that is declared and not locked, or one of whose souls was
2474
+ skipped; any entry not under the package of an offered package soul while
2475
+ a member is not confirmed or a member's or an external soul was skipped (a
2476
+ bare name, `<member>/<soul>`, or a prefix that may be a member's name);
2477
+ every entry in the standalone view of a workspace whose host cannot be
2478
+ read, or a read that kept no record of what it skipped. When the cache
2479
+ cannot answer at all, one such line names the entries.
2480
+ - Doctor still exits 0. With no `souls.disabled`, or an empty list, nothing is
2481
+ added. Spawn, `oats souls`, readiness and inspect do not change.
2482
+
2272
2483
  ### The launch report (`Launch`)
2273
2484
 
2274
2485
  ```json
@@ -2777,6 +2988,40 @@ Feature `spawn-apply-2`, `spawnApplyApi: 1`. The Desktop gates on
2777
2988
  Without `--expect-decision` the flag is `E_BAD_ARGS`
2778
2989
  ([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311)).
2779
2990
 
2991
+ <a id="spawn-caller-gone"></a>**A caller that goes away.** A spawn does not
2992
+ depend on its caller to finish: once it has made the home it ends with the
2993
+ home complete or with the home rolled back, whether or not anyone still
2994
+ reads it or its session is still there.
2995
+ - A reader that closes stdout or stderr (an ssh session that ended, a
2996
+ Desktop that quit) only stops reading: the spawn runs to its end, what it
2997
+ could not print is dropped, and its exit status is the spawn's own, `0`
2998
+ for a spawn that completed, as for [`oats worktree add`](#oats-worktree).
2999
+ The answer nobody read is the home's record, and a spawn that brought
3000
+ `--expect-decision` and `--idempotency-key` answers it again when it is
3001
+ repeated (below).
3002
+ - The same holds for the verbs that act under a home's
3003
+ [lifecycle claim](#lifecycle-pairs): `oats retire`, `oats session start`,
3004
+ `oats session restart` and `oats instance stop --apply`. With no reader
3005
+ the act completes, a line it writes on stderr while it acts (a start
3006
+ that starts the OATS tmux server writes one) is dropped with the answer,
3007
+ and the exit status is the act's own, never the `1` of an unhandled
3008
+ `EPIPE`. What was done is on disk: the home is gone, the session runs, or
3009
+ the stop's receipt is stored, and a stop or a guarded retire repeated
3010
+ with its `--idempotency-key` answers the receipt again. Their plans
3011
+ (`--plan`) and every reading command are as before: a reader that goes
3012
+ away ends them.
3013
+ - SIGINT, SIGTERM or SIGHUP never ends the process with a home that has no
3014
+ record. While the capabilities are copied into the new home, and while
3015
+ its `worktree` hooks run, the signal is held and the spawn is rolled back:
3016
+ `E_INTERRUPTED`, exit 128 + the signal number
3017
+ ([Spawn errors](#spawn-errors)). At any other moment the signal reaches
3018
+ the process once the spawn has returned: the home is complete, the answer
3019
+ is written, and the process then exits 128 + the signal number. This is
3020
+ the spawn's rule alone: a retire, a start, a restart and a stop apply
3021
+ hold no signal, and one that is signalled ends where it stands, its claim
3022
+ left for the next command of that home to
3023
+ [take over](#lifecycle-pairs).
3024
+
2780
3025
  **Idempotency** (feature `spawn-idempotency-2`): `--idempotency-key <key>`
2781
3026
  with `--expect-decision` records the key and decision in `instance.json`.
2782
3027
  - Recovery runs right after naming, before placement or preflight. A retry
@@ -2790,6 +3035,23 @@ with `--expect-decision` records the key and decision in `instance.json`.
2790
3035
  for that intent's retries.
2791
3036
  - `wake: {requested, saved, error}` is recorded and replayed; `saved: null`
2792
3037
  means the outcome was not recorded.
3038
+ - A replay answers `attach` as the first apply did; its `launch` is `null`
3039
+ (nothing runs again).
3040
+ - <a id="spawn-idempotency-routed"></a>**Routed (`--server`).** A spawn that
3041
+ brings neither `--expect-decision` nor `--idempotency-key` is bound by the
3042
+ route: it asks the host for its preview, then applies with that decision
3043
+ and a key it makes for the request, and relays the host's keyed answer
3044
+ (`decision`, `replayed: false`, `wake`). A link that fails under that apply
3045
+ is `E_SSH` with `error.details: {decision, idempotencyKey, fix}`: `decision`
3046
+ is the previewed decision, `idempotencyKey` the key the apply carried and
3047
+ `fix` the sentence naming the two flags (and `--name <decision.instance>`
3048
+ in place of `--suggest-name`). The same spawn with them is forwarded as
3049
+ given and answers the one instance. A spawn that brings either flag is
3050
+ forwarded as given. A host without `spawn-preview-2`, `spawn-apply-2` and
3051
+ `spawn-idempotency-2` (and, for `--suggest-name`, `spawn-suggest-name` and
3052
+ `spawn-name`) gets one unbound spawn, and the answer's `warnings` say that
3053
+ a dropped link cannot be retried safely there
3054
+ ([servers.md](servers.md#run-there)).
2793
3055
 
2794
3056
  **Result** (`oats spawn <soul> … --json`):
2795
3057
 
@@ -3061,6 +3323,7 @@ kernel stage raised as well.
3061
3323
  | `E_NOT_A_MEMBER`, `E_MEMBERSHIP_UNCONFIRMED` | | the soul's repository is not a confirmed member |
3062
3324
  | `E_CAPABILITY_MISSING`, `E_CAPABILITY_PRIVATE`, `E_CAPABILITY_INCOMPATIBLE`, `E_COMPATIBILITY` | | a capability cannot be resolved |
3063
3325
  | `E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY`, `E_LOCK_SCHEMA` | | the lock does not provide it (standalone: `{…, standalone: true, reason: "no-catalog", catalog}`) |
3326
+ | `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
3327
  | `E_SLOT_CONFLICT`, `E_SKILL_DUPLICATE` | | the composition conflicts |
3065
3328
  | `E_WORKSPACE_SCHEMA` | `{path, key, reason}` | a removed key or invalid payload |
3066
3329
  | `E_CLONE_MISSING`, `E_CLONE_MISMATCH` | | the member's clone is missing or wrong |
@@ -3075,10 +3338,11 @@ kernel stage raised as well.
3075
3338
  | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
3076
3339
  | `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
3340
  | `E_CLAUDE_CONFIG_REMOVED` | `{file, executable, fix}` | a new claude launch with an `oats-claude-config` in reach ([configuration.md](configuration.md)) |
3341
+ | `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
3342
  | `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
3343
  | `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
3080
3344
  | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
3081
- | `E_INTERRUPTED` | `{signal, hooks}` | SIGINT, SIGTERM or SIGHUP while the spawn's `worktree` hooks ran (feature `worktree-event`): the running hook's process group is ended, the spawn is rolled back as for a required hook failure, and the process exits 128 + the signal number |
3345
+ | `E_INTERRUPTED` | `{signal, hooks}` | SIGINT, SIGTERM or SIGHUP while the spawn's `worktree` hooks ran (feature `worktree-event`): the running hook's process group is ended, the spawn is rolled back as for a required hook failure, and the process exits 128 + the signal number. Also while the capabilities were copied into the new home, before any hook: the signal is held until the copy ends, the home is removed, `hooks` is `[]`, and the exit status is the same ([a caller that goes away](#spawn-caller-gone)) |
3082
3346
  | `E_REQUIRED_HOOK_FAILED` | `{hooks}`, plus `unconfirmed: true` when compensation cannot finish | a required `spawn` or `worktree` hook failed or timed out; the spawn is rolled back. `hooks` holds the receipt of the event that failed: one entry per hook that ran, `{capability, ok, required, log, exitCode?, signal?, timedOut?, contract?}`, paths only. `log` is `null` for a spawn hook (it keeps no log) and once the rollback removed the home; a retained home keeps a `worktree` hook's log path. Never `home`. Before 0.49.0 a required spawn hook's failure answered `E_SPAWN_FAILED` |
3083
3347
  | `E_HOOK_ENVIRONMENT_CONTRACT` | the same as `E_REQUIRED_HOOK_FAILED`, the failed entry with `contract: "environment"` | a `spawn` hook answered an `env` its manifest does not allow, or a `worktree` hook answered `env` at all |
3084
3348
  | `E_RUNTIME_ENDPOINT_UNKNOWN` | | the session cannot be established: the OATS tmux server cannot be read at an apply (before any effect, or after the home, the work and the hooks), or the pane's `PATH`, `HOME` or harness folder cannot be read for the harness package check ([the checks read the pane](execution-targets.md#the-checks-read-the-pane)), before anything is probed or created, or at the apply's second check after the hooks, as for `E_HARNESS_RESOURCE_MISSING`. Once the home exists the spawn is rolled back, with `details.unconfirmed` when that cannot finish. A start and a restart answer the same code |
@@ -3241,16 +3505,16 @@ A failed `add` reports the same facts about its rollback in `details`:
3241
3505
  | `E_CLONE_MISSING` | the repository is not found, or is not a Git repository |
3242
3506
  | `E_CLONE_MISMATCH` | the path is a linked worktree, or the clone has no `origin` |
3243
3507
  | `E_BRANCH_EXISTS` | the branch exists in the clone (before the tree is made, or made by another `add` at the same moment); `details.remedy` is `<instance>/<branch>` |
3244
- | `E_GIT_FAILED` | a Git step failed on its own (`git worktree add`, or `git switch` while the branch does not exist), with Git's message: `git <sub> failed in <dir>: …`; the tree is removed |
3508
+ | `E_GIT_FAILED` | a Git step failed on its own (`git worktree add`, or `git switch` while the branch does not exist), with Git's message: `git <sub> failed in <dir>: …`; or a checkout was not run because the repository's configuration defines a filter driver whose name cannot be overridden ([a checkout runs no filter driver](souls-and-instances.md#checkout-filter-drivers)); the tree is removed |
3245
3509
  | `E_PLACEMENT_TAKEN` | a `ready` record with another clone, branch or base (`details.differ`); `.work-<p>` with no record, or a file or symbolic link there; an unreadable record |
3246
3510
  | `E_LIFECYCLE_BUSY` | an add of that purpose is still running (pid and start time verified); another add or remove of that purpose holds its claim (`details.lock`); a file at the claim's path is no claim this kernel can read or take over (`details.lock`); the claim was taken again, the last time by a process that is gone, each of the five times the command found it without a live holder (`run the command again`); an interrupted add's rollback could not be completed (`details.owed`; the message says what to deal with and to run `oats worktree remove --purpose <purpose>`, which finishes the rollback); or, `add` only (OATS 0.52.0), the home's claim is held by a retire whose liveness cannot be read, or is a file that is no readable claim (`no tree was made`; [Commands that meet on one home](#lifecycle-pairs)). Every one carries [`details.holder`](#busy-holder) |
3247
3511
  | `E_REMOTE_UNREADABLE` | the fetch of `<base>` from `origin` failed; the tree is removed |
3248
3512
  | `E_BASE_UNKNOWN` | the new HEAD is not the fetched commit; the message names both |
3249
3513
  | `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
3514
  | `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 |
3515
+ | `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
3516
  | `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) |
3517
+ | `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
3518
  | `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
3519
 
3256
3520
  A rollback that cannot finish keeps the record and says so in the message
@@ -3413,8 +3677,10 @@ its absence.
3413
3677
  and no `runtimeState`. What the lifecycle commands answer for such a home:
3414
3678
  [below](#unreadable-record).
3415
3679
  - **`spawnInProgress`** (feature `worktree-event`, OATS 0.49.0): `true` only
3416
- while a spawn that is running its `worktree` hooks is verifiably alive (its
3417
- pid runs with the recorded start time). Such a home holds the quarantine marker
3680
+ while a spawn that wrote its in-progress marker is verifiably alive (its
3681
+ pid runs with the recorded start time): one running its `worktree` hooks,
3682
+ or one that has reached its spawn hooks and not yet written its record,
3683
+ when a capability with a spawn hook has a retire hook. Such a home holds the quarantine marker
3418
3684
  with an `inProgress` field ([capabilities.md](capabilities.md#manifest)),
3419
3685
  and its row carries `spawnInProgress: true` and **no**
3420
3686
  `rollbackIncomplete`: a live spawn, not a failed one. Once that process is
@@ -3440,8 +3706,9 @@ its absence.
3440
3706
  reading `null` unless a harness runs there.
3441
3707
  - <a id="row-session-end"></a>**`sessionEnd`** (feature `session-resume`, OATS
3442
3708
  0.69): how the last session of a launched home that does not run ended:
3443
- `lost` (the host went down, its tmux server died, or the harness was killed
3444
- by a signal: the sweep brings it back when it can vouch for the loss,
3709
+ `lost` (the host went down, its tmux server died, the harness was killed
3710
+ by a signal, or `oats host run` stopped it because the host was stopping:
3711
+ the sweep brings it back when it can vouch for the loss,
3445
3712
  [Which losses come back](execution-targets.md#which-losses-come-back)), `stopped` (stopped with OATS:
3446
3713
  `oats instance stop`, Desktop's Stop, or an `oats session restart` whose
3447
3714
  relaunch did not happen) or `exited` (the harness ended by
@@ -3499,7 +3766,7 @@ its absence.
3499
3766
  | the marker, and the result file `.oats-retired-<instance>.json` with `ok: false` | `failed`, with `code` and `message` | `true` | the result's `completedAt`, else the marker's `requestedAt` |
3500
3767
  | the marker, no failed result, its completion process alive | `running` | `true` | the marker's `requestedAt` |
3501
3768
  | the marker, no failed result, the completion's liveness cannot be read, or the marker names no completion process | `unknown` | `true` | the marker's `requestedAt` |
3502
- | the marker, no failed result, its completion process gone | `interrupted` | `true` | the marker's `requestedAt` |
3769
+ | the marker, no failed result, its completion process gone (it ended, its pid runs with another start, or the marker's `completionBoot` is another boot) | `interrupted` | `true` | the marker's `requestedAt` |
3503
3770
  | a marker that cannot be read as an object | `unknown` | `true` | the marker file's modification time |
3504
3771
  | no marker; the home's claim held by a retire whose holder is alive | `running` | `false` | the claim's `since` |
3505
3772
  | no marker; the same, the holder's liveness cannot be read | `unknown` | `false` | the claim's `since` |
@@ -3879,16 +4146,19 @@ oats server check <id> --json
3879
4146
  ```
3880
4147
 
3881
4148
  `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
4149
+ the registration (`id`, `sshHost`, `workspace`, and `operatorSshHost`,
4150
+ `oatsPath`, `path`, `label` when set) plus `workspaceKey` (`null` when not known
4151
+ yet), `target` and `snapshots`. `operatorSshHost` is the optional `--operator-ssh` alias,
4152
+ joined from `~/.oats/server-operator-routes.json`; it is absent from `servers.json`.
4153
+ Older kernels never read the separate file;
4154
+ existing routing and `target` use only `sshHost`. With `--workspace-ref <ref>`,
4155
+ `servers` holds only the rows whose `workspaceKey` is the canonical key of `<ref>` (`parseRepoRef`; any
3886
4156
  spelling of the repository), and `result.unknownWorkspace` lists the ids
3887
4157
  whose key is not known; an unparsable ref is `E_REPO_REF`.
3888
4158
 
3889
4159
  ```json
3890
4160
  {"file":"/Users/me/.oats/servers.json",
3891
- "servers":[{"id":"altair-aweb","sshHost":"altair","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"altair",
4161
+ "servers":[{"id":"altair-aweb","sshHost":"altair","operatorSshHost":"altair-operator","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"altair",
3892
4162
  "workspaceKey":"github.com/awebai/ac",
3893
4163
  "target":{"sshHost":"altair","workspace":"/Users/me/acme","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
3894
4164
  "unknownWorkspace":["build"]}
@@ -3909,7 +4179,7 @@ contradicts fails the check with `E_SERVER_WORKSPACE_MISMATCH`, `details:
3909
4179
 
3910
4180
  ```text
3911
4181
  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
4182
+ [--operator-ssh <alias> | --no-operator-ssh] [--oats <path>] [--path <dirs>] [--label <text>] [--install-oats] [--replace] --json
3913
4183
  ```
3914
4184
 
3915
4185
  An envelope, `ok: true` whenever no step failed, human steps included
@@ -3941,10 +4211,13 @@ An envelope, `ok: true` whenever no step failed, human steps included
3941
4211
  some codes, `details`. `skipped` steps say `waits for <step>`.
3942
4212
  - `registration` is the registration as written or found (`sshHost`,
3943
4213
  `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
4214
+ `workspaceKey`; optional `operatorSshHost` joined from the separate operator-route file; and
4215
+ `oatsPath`, `path`, `label` when set, given or, without `--path`, read from the host user's
3946
4216
  [login shell](servers.md#the-hosts-login-shell-path)), `null` until the
3947
4217
  `register` step has run.
4218
+ With `--replace`, an existing operator route is kept unless `--operator-ssh`
4219
+ sets it again or `--no-operator-ssh` clears it. `server remove` deletes the
4220
+ separate route too. Both files are updated under `servers.lock`.
3948
4221
  - `human` lists the remedies of the `needs-human` steps, in order. A
3949
4222
  `readiness` step that needs a human has one line per problem
3950
4223
  (`<souls>: <subject>: <reason>[ → <remedy>]`, plus `readiness not checked
@@ -4294,6 +4567,39 @@ readOnly: {helpers: "disabled", optionalLocks: "off", objectsWritten: 0}}`.
4294
4567
  (`readOnly`). An object a partial clone lacks is not fetched: the read
4295
4568
  fails with `E_GIT_FAILED` (with Git 2.44 or later; an older Git ignores
4296
4569
  `GIT_NO_LAZY_FETCH`).
4570
+ - **Filter drivers are not run.** Git runs a `filter.<name>.clean` or
4571
+ `.process` command when a status or a diff compares a work-tree file that
4572
+ carries the `filter` attribute, and it has no switch that turns filters
4573
+ off. Before the Git commands that read a work-tree file, `oats instance
4574
+ git` and `oats instance diff` read the configuration Git would use (`git config --list`, which runs
4575
+ nothing and follows `include.path` and `includeIf`) and override every
4576
+ filter driver it defines to no command (`clean`, `smudge`, `process`) and
4577
+ not required. An observation makes that read once, before its status, for
4578
+ its status and its line counts; each command of a diff is preceded by its
4579
+ own.
4580
+ - A file such a filter applies to (a Git LFS file, for one) is compared as
4581
+ its bytes are in the work tree, not as the filter would store them. An
4582
+ untouched file still reads as unchanged, by its recorded size and times.
4583
+ One that was rewritten, or whose times Git cannot tell from the index's,
4584
+ reads as `changed` even when its filtered form is what is stored; its
4585
+ line counts and its diff are the stored form (an LFS pointer) against the
4586
+ work tree's bytes. The observation then carries a note that the
4587
+ repository's configuration defines a filter driver.
4588
+ - A driver whose name cannot be passed on Git's command line (it holds `=`
4589
+ or is not UTF-8) cannot be overridden: Git is not run, and the read fails
4590
+ with `E_GIT_FAILED`.
4591
+ - Not covered: a driver written into the configuration between that read
4592
+ and a Git command it covers (for an observation, up to its line counts,
4593
+ which follow its status and its reads of HEAD, the index and the refs),
4594
+ and a filter a **submodule's own**
4595
+ configuration defines. Git runs inside each populated submodule to learn
4596
+ whether it is dirty, and the overrides name the repository's drivers, not
4597
+ the submodule's. A dirty submodule stays visible in the status for that
4598
+ reason. Where the agent and the reader of its worktree are one system
4599
+ user, which is the usual arrangement, such a filter runs nothing the agent
4600
+ could not run itself. Where they are separate users, it runs the agent's
4601
+ command as the reader's user: do not read a worktree with populated
4602
+ submodules across users.
4297
4603
  - If HEAD or the index moved, the id is not in the current observation, or
4298
4604
  anything moved during the read: `E_STALE_OBSERVATION` with
4299
4605
  `details.observation`. Re-observe; never render a diff of another tree.
@@ -4337,6 +4643,12 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
4337
4643
  `branch-deleted` (not written since 0.41.0: no retire deletes a branch;
4338
4644
  older logs hold it), `child-spawn-refused`, `launch-warning` (0.30: a
4339
4645
  `launch` hook's warning at session start/restart, `data: {message}`),
4646
+ `retire-warning` (a retire hook's warning, `data: {message}`: one row per
4647
+ entry of the retire hooks' `warnings`, a hook's own `warning` and the
4648
+ kernel's lines about those hooks alike, in their order; written to the
4649
+ workspace log only, as soon as the hooks return, so a retire that then
4650
+ refuses or ends quarantined keeps them, and each run of the hooks, a retry
4651
+ among them, adds its own; older clients read it as an unknown kind),
4340
4652
  `recomposed` (from earlier kernels), `waiting` (0.40: a producer's claim,
4341
4653
  [Waiting on you](#waiting-on-you)), `wake-held` (feature `wake-hold`: a
4342
4654
  scheduled wake began to hold, one row per hold, `data: {schedule, since,
@@ -4349,6 +4661,12 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
4349
4661
  credentials, `member` a key or `null`, `hooks` the `worktree` hooks'
4350
4662
  receipt). `producer` is `kernel`, a capability id,
4351
4663
  or another producer id (`agent`). Older rows may carry `eventsApi: 1`.
4664
+ The `message` of a `launch-warning` or `retire-warning` row is the
4665
+ warning's text as stored: control, bidi and hidden characters replaced
4666
+ with U+FFFD, cut to 2048 UTF-16 code units ending in `…` (never through a
4667
+ surrogate pair); a warning that is not a string is stored as its JSON.
4668
+ Clients show it as plain text. The answer that carried the warning
4669
+ (`warnings`) keeps it as it was said.
4352
4670
  `launched` is written by spawn and, since 0.40, once per session start or
4353
4671
  restart, as soon as the session exists (`data: {harness, backend,
4354
4672
  launchConfig, phase, startId}`; spawn's row has neither `phase` nor
@@ -4363,7 +4681,8 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
4363
4681
  - `retired` (`data: {agent, keepDir, self, quarantine, workRecovery, hooks,
4364
4682
  reason?}`) is written to the workspace log only,
4365
4683
  `<deployment>/.agents/events/<agent>--<instance>.jsonl`, which outlives the
4366
- home. `reason` is present only when
4684
+ home. What its hooks warned is not in it: those are the `retire-warning`
4685
+ rows written before it. `reason` is present only when
4367
4686
  the retire completed a self-retire an older OATS recorded with
4368
4687
  `--delete-branch` (since 0.41.0: `this self-retire was requested with
4369
4688
  --delete-branch by an older OATS; retirement no longer deletes branches, so
@@ -4488,8 +4807,8 @@ before whether or not a claim is set. `attention` never marks a screen an Enter
4488
4807
  answers: a producer that wants one uses `question`, and review catches that.
4489
4808
 
4490
4809
  ```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
4810
+ oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] --json
4811
+ oats instance attention [--message=<text>] [--clear] --json
4493
4812
  ```
4494
4813
 
4495
4814
  ```json
@@ -4769,8 +5088,15 @@ oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>]
4769
5088
  - `retiring` and `stopPending`, booleans on every target, say who holds the
4770
5089
  target's home when the plan is read (OATS 0.52.0, feature
4771
5090
  `lifecycle-claim-stop`). `retiring`: a self-retire is scheduled for it
4772
- (its pending marker is there), or a retire holds its
4773
- [claim](#retire-one-at-a-time). From 0.53.0 the marker outlasts a
5091
+ (its pending marker is there, and the completion the marker names is not
5092
+ gone: it lives, its liveness cannot be read, or the marker names none),
5093
+ or a retire holds its
5094
+ [claim](#retire-one-at-a-time). A marker whose completion is gone (it
5095
+ ended, its pid runs with another start, or the marker was written in
5096
+ another boot) is `retiring: false`, and the apply stops the target: the
5097
+ home is owed its retire and nothing carries it out
5098
+ ([a completion that was killed](souls-and-instances.md#self-retire-interrupted)).
5099
+ From 0.53.0 the marker outlasts a
4774
5100
  completion that did not complete only when a retire hook was started or
4775
5101
  the removal of the home began
4776
5102
  ([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
@@ -4833,7 +5159,8 @@ this order:
4833
5159
  retired since the plan was shown answers `E_SESSION_UNKNOWN`; one whose
4834
5160
  `instance.json` can no longer be read, `E_UNIDENTIFIED_INSTANCE_HOME`; a
4835
5161
  child in that state is no longer a target, which is a changed plan.
4836
- 6. It refuses a target for which a self-retire is scheduled
5162
+ 6. It refuses a target for which a self-retire is scheduled, unless the
5163
+ completion its marker names is gone
4837
5164
  (`E_INSTANCE_RETIRING`, with `details.plan`).
4838
5165
  7. It stops each target, writes the receipt and releases the claims.
4839
5166
 
@@ -5116,12 +5443,21 @@ The sweep reports each of these `skipped`, `lifecycle-busy`
5116
5443
  apply refuses a home that is not stopped, so it stops nothing: beside a
5117
5444
  resume that is still starting, it meets the claim.
5118
5445
 
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
5446
+ Upgrade requires a stopped session. It also keeps a file at the home's
5447
+ `.oats-start.lock` until its final invocation receipt is persisted. A start
5448
+ makes nothing at that path and reads it only once it holds the claim, so
5449
+ beside an upgrade that runs it is refused at the claim (`E_LIFECYCLE_BUSY`);
5450
+ the file answers (`E_SESSION_START_BUSY`, naming the same-key retry) only
5451
+ when an upgrade that died left it. A directory at that path is the start lock
5452
+ of an earlier OATS: a start refuses it with `E_SESSION_START_LOCK_STUCK`,
5453
+ `<path> is the start lock directory of an earlier OATS; nothing was stopped
5454
+ or started. Once no earlier oats is running, remove that directory and
5455
+ retry`, and never removes it. Anything else there is refused with the same
5456
+ code: `<path> is neither a package upgrade's file nor an earlier OATS's start
5457
+ lock directory; nothing was stopped or started. Remove it and retry`. An
5458
+ upgrade apply that meets such a directory answers `E_SESSION_RUNNING`, `<name>:
5459
+ <path> is a start lock left by an earlier OATS; upgrade never removes it.
5460
+ Once no earlier oats is running, remove that directory and retry`. A partial receipt refuses starts through the remaining
5125
5461
  finalization (`E_UPGRADE_PARTIAL`): the CLI checks it first, before it reads
5126
5462
  the home's live teams, except while an upgrade holds the claim, which then
5127
5463
  answers. The following stop/retire notes describe the original table.
@@ -5138,7 +5474,9 @@ answers. The following stop/retire notes describe the original table.
5138
5474
  ([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
5139
5475
  A retire reads the marker under the claim, while
5140
5476
  the completion lives (`E_LIFECYCLE_BUSY`, [below](#retire-one-at-a-time)).
5141
- A stop apply reads it in the plan it makes under its claims: a plan that
5477
+ A stop apply reads it in the plan it makes under its claims, and it holds
5478
+ the home against a stop while its completion is not gone
5479
+ ([`retiring`](#stop-claim)): a plan that
5142
5480
  showed `retiring: true` is answered `E_INSTANCE_RETIRING`, and an apply
5143
5481
  whose plan was shown before the retire was scheduled is answered
5144
5482
  `E_PLAN_STALE` first, with the fresh plan.
@@ -5305,6 +5643,7 @@ had begun.
5305
5643
  | Code | `oats instance stop` | `oats retire` |
5306
5644
  |---|---|---|
5307
5645
  | `E_BAD_ARGS` | yes | yes |
5646
+ | `E_USAGE` | yes | yes |
5308
5647
  | `E_PLAN_STALE` | yes | yes |
5309
5648
  | `E_INSTANCE_RETIRING` | yes | yes |
5310
5649
  | `E_LIFECYCLE_BUSY` | yes | yes |
@@ -5763,6 +6102,18 @@ extra tree that is not clean is moved the same way; a clean one is removed.
5763
6102
  oats retire <instance> [--plan-revision <rev> --idempotency-key <key>] [--discard-worktree] [--home <abs>] --json
5764
6103
  ```
5765
6104
 
6105
+ A flag retire does not read, or an argument after the instance, is refused
6106
+ with `E_BAD_ARGS` before any effect, `--plan` and `--server` included:
6107
+ `oats retire: unknown flag <flag>` with `error.details.flag`, or `oats retire:
6108
+ unexpected argument "<word>" after the instance "<instance>": retire takes one
6109
+ instance` with `error.details.argument`, each followed by the usage line. The
6110
+ flags are `--plan`, `--plan-revision`, `--idempotency-key`, `--home`, `--dir`,
6111
+ `--server`, `--self`, `--discard-worktree`, `--keep-dir`, `--force` and
6112
+ `--json` ([souls-and-instances.md](souls-and-instances.md#retire)).
6113
+ A retire with no instance is `E_USAGE`, with the usage line as
6114
+ `error.message`: one envelope under `--json`, the usage line on stderr
6115
+ without it. An unknown flag before the instance is still `E_BAD_ARGS`.
6116
+
5766
6117
  A first retire prints the **raw receipt**, not an envelope:
5767
6118
 
5768
6119
  ```json
@@ -6030,7 +6381,19 @@ zombie) has died: its claim is taken over without waiting for that reap
6030
6381
  (0.52.0, #870; before, the retire was refused as running until the reap). The
6031
6382
  claim does not end what the killed retire left running: one of its retire
6032
6383
  hooks may still be running when the next retire takes the claim over and
6033
- runs the hooks again (#865). Until
6384
+ runs that hook again (#865). <a id="retire-hooks-in-claim"></a>The retire
6385
+ that takes over does not run again a retire hook the killed one had
6386
+ finished: a retire records each hook that ended in its claim, as
6387
+ `retireHooks: [{capability, meta?}]` (the `meta` that hook answered) with
6388
+ `retireHooksFor`, the home's `createdAt`, and the next holder skips those
6389
+ hooks and judges the cleanup, and writes its `retired` row, with their
6390
+ `meta` as if it had run them. A hook that had not ended is run again. Only
6391
+ a take-over reads the list: a retire that returns removes its claim, so
6392
+ the retry of a quarantined home, and each retry a self-retire's completion
6393
+ makes of a cleanup its hooks left incomplete, runs every hook again. A
6394
+ claim without the list, or whose list names another incarnation, skips
6395
+ nothing, and of a list only the entries that name a capability of this
6396
+ home with a retire hook count. Until
6034
6397
  that name is retired again its claim file stays where it is, and it is safe
6035
6398
  to remove once its pid is gone. A retire that ends removes its claim file;
6036
6399
  the `claims/` directory itself stays, empty.
@@ -6099,8 +6462,9 @@ line and says that nothing was done:
6099
6462
  Then the command again.
6100
6463
 
6101
6464
  A scheduled self-retire counts from the moment it is scheduled. Its pending
6102
- marker (`pendingMarker`) records the completion process as `completionPid`
6103
- and `completionStart` (`null` when the start could not be read). While that
6465
+ marker (`pendingMarker`) records the completion process as `completionPid`,
6466
+ `completionStart` and `completionBoot`, the boot it runs in (each of the two
6467
+ `null` when it could not be read). While that
6104
6468
  process lives, every other retire of the instance is refused the same way,
6105
6469
  `--self --keep-dir` included: `a retire of <name> is already scheduled (its
6106
6470
  completion, pid <pid>, requested at <requestedAt>); nothing was done — wait
@@ -6114,7 +6478,10 @@ claim, it is refused the claim and answers `E_LIFECYCLE_BUSY` like any other
6114
6478
  retire, where it answered `alreadyScheduled: true` before 0.51.0. The marker refuses nothing once its completion has
6115
6479
  left its outcome at `resultPath` (it failed) or is gone (it died; a
6116
6480
  completion that is a zombie, not reaped by its parent, has died: 0.52.0,
6117
- #870), nor when
6481
+ #870; one whose marker names another boot than this one is gone whatever
6482
+ its pid reads as, since a boot ends every process and a pid and a start can
6483
+ both come again in the next; a marker that names no boot is judged by its
6484
+ process alone), nor when
6118
6485
  it names no completion (a marker written before 0.51.0): `oats retire
6119
6486
  <instance>` then retries the retirement, as before. The completion does not
6120
6487
  start its retire while the retire that scheduled it holds the claim: it
@@ -6183,14 +6550,17 @@ Git reads as the top level of a `work/` whose `core.worktree` names another
6183
6550
  one),
6184
6551
  `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
6185
6552
  `E_UNIDENTIFIED_INSTANCE_HOME` (a home with no `instance.json` and no cleanup
6186
- descriptor, or a rollback marker that cannot drive a retry, until `--force`;
6553
+ descriptor, or a rollback marker that cannot drive a retry, or an
6554
+ `instance.json` that names no repository and does not show that no capability
6555
+ has a retire hook, what a spawn killed before its record leaves
6556
+ ([capabilities.md](capabilities.md#manifest)), until `--force`;
6187
6557
  a home whose `instance.json` [cannot be read](#unreadable-record), `--plan`
6188
6558
  and `--force` included),
6189
6559
  `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
6190
6560
  home is running or scheduled, or a stop of it is running, `--force`
6191
6561
  included: one retire or stop of a home at a time, above; or, feature
6192
- `worktree-event`: the home is a spawn still running its `worktree` hooks, a
6193
- row with `spawnInProgress: true`, `--force` included; or one whose start time
6562
+ `worktree-event`: the home is a spawn still running its spawn or `worktree`
6563
+ hooks, a row with `spawnInProgress: true`, `--force` included; or one whose start time
6194
6564
  cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
6195
6565
  group whose leader's start cannot be read, until `--force`; every one is
6196
6566
  answered before any effect and carries [`details.holder`](#busy-holder)). The
@@ -6569,6 +6939,11 @@ results with package drift include `drift:[{capability, recorded:{version,commit
6569
6939
  locked:{version,commit}}]` for package modules behind the deployment lock,
6570
6940
  and omit the field when none are behind. Text prints one line after the start:
6571
6941
  `<n> package module(s) behind the lock (<cap> <version> @ <shortcommit> → <version> @ <shortcommit>); to move them: oats instance stop <instance>; oats instance upgrade <instance> --plan`.
6942
+ `drift` lists only modules an upgrade moves in place. Package modules an
6943
+ upgrade keeps, because their package is no longer locked or no longer
6944
+ provides the capability, add one string to `warnings`, printed as a
6945
+ `WARNING:` line:
6946
+ `<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
6947
  Restart has no upgrade flag. A partial upgrade receipt refuses a start with
6573
6948
  `E_UPGRADE_PARTIAL`, naming the retry with the original idempotency key.
6574
6949
  A committed receipt with `steps.cleaned: false` permits start and adds one
@@ -6628,13 +7003,20 @@ warning naming the same-key cleanup retry.
6628
7003
  `E_UNIDENTIFIED_INSTANCE_HOME` (the home's `instance.json`
6629
7004
  [cannot be read](#unreadable-record): nothing was started, `start` and
6630
7005
  `restart`),
6631
- `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY` (feature
7006
+ `E_SESSION_START_BUSY`, `E_SESSION_START_LOCK_STUCK` (a start lock
7007
+ directory an earlier OATS left at `<home>/.oats-start.lock`, or anything
7008
+ else there that is not a package upgrade's file; the message names it and
7009
+ what to remove; nothing was started or stopped:
7010
+ [Commands that meet on one home](#lifecycle-pairs)),
7011
+ `E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY` (feature
6632
7012
  `lifecycle-claim-start`: a stop or an upgrade of the home holds its
6633
7013
  lifecycle claim, or the claim cannot be read or taken; `details.holder`,
6634
7014
  `details.action`; nothing was started or stopped:
6635
7015
  [Commands that meet on one home](#lifecycle-pairs)), `E_LAUNCH_*` (among them
6636
7016
  `E_LAUNCH_SHIM`: the home's `oats` link cannot be written, nothing was
6637
7017
  started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`,
7018
+ `E_CLAUDE_LOGIN_CREDENTIAL` (the effective Claude config has a `/login`
7019
+ credential file alongside an OATS-set token; other harnesses are unaffected),
6638
7020
  `E_HARNESS_RESOURCE_MISSING` (a harness package an active capability
6639
7021
  requires is not installed, disabled, or cannot be verified: nothing was
6640
7022
  started; `E_HARNESS_PACKAGE` before 0.56.0), `E_SESSION_FAILED`
@@ -6693,10 +7075,10 @@ answer is the ordinary start answer plus one object:
6693
7075
  - Refused `E_RESUME_NOT_LOST` when the home did not lose its session
6694
7076
  (`stopped`, `exited`, never launched), read under the claim and the start
6695
7077
  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
7078
+ - Refused `E_LAUNCH_ENV_CHANGED` when a reference value (`fromEnv` or
7079
+ `fromFile`) differs from the one the start it brings back ran with (checked after `E_LAUNCH_ENV_MISSING`):
7080
+ the message names the sources (an environment name or `file:<path>`),
7081
+ sorted, never a value; nothing was started. A home with no record of its last start's values (last started
6700
7082
  by an earlier kernel, or a record that does not read) is resumed, and
6701
7083
  `warnings` carries once `<instance>'s launch environment could not be
6702
7084
  verified this once (it was last started before OATS recorded it); its
@@ -6801,12 +7183,94 @@ whatever the rows say:
6801
7183
  launched something: `resumed`, `fresh`, `blocked`) are kernel-private,
6802
7184
  not a contract. Without a boot id (neither Linux nor macOS) nothing is
6803
7185
  noted or counted.
6804
- - Errors: `E_RESUME_BUSY`; `E_BAD_ARGS` (`--deployment` that is not a
7186
+ - **A lock that needs a person.** `E_RESUME_LOCK_STUCK`, through the same
7187
+ envelope at exit 1, when the sweep's lock cannot be taken and no sweep is
7188
+ known to run; nothing was started, and no sweep starts anything on this
7189
+ machine until it can be. `error.details` is `{lock, found}`: `lock` is
7190
+ the lock's absolute path, and `found` is one of
7191
+
7192
+ | `found` | what is at the lock's path | what to do |
7193
+ |---|---|---|
7194
+ | `unreadable` | a record that cannot be read | remove the file once no sweep runs |
7195
+ | `unknown` | a holder that cannot be told to be running or gone | remove the file once no sweep runs |
7196
+ | `cannot-take-over` | a gone holder's record that cannot be taken over | remove the file |
7197
+ | `held-again` | a lock that was taken again each time the sweep found it free | run the sweep again |
7198
+ | `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 |
7199
+ | `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 |
7200
+
7201
+ The message says the same in words, with what to do
7202
+ ([The sweep](execution-targets.md#the-sweep)). It is never
7203
+ `E_RESUME_BUSY`: that code is a sweep that runs. `readResumeSweep` reads
7204
+ it as `failed` with the code. `oats doctor --json` lists the same states
7205
+ as one `resume-lock-stuck` problem in `problems[]`, `{code, message,
7206
+ remedy}` (text: `! resume-lock-stuck: <message>`, the remedy on the next
7207
+ line), read without taking the lock; a free lock, a sweep that runs and a
7208
+ lock a gone sweep left are not listed, and doctor's exit status does not
7209
+ change.
7210
+ - Errors: `E_RESUME_BUSY`; `E_RESUME_LOCK_STUCK`; `E_BAD_ARGS` (`--deployment` that is not a
6805
7211
  deployment directory, `--server`, an unknown flag or an argument); without
6806
7212
  `--deployment`, the list's own errors (`E_DEPLOYMENTS_INVALID`,
6807
7213
  `E_DEPLOYMENTS_VERSION`). A home's start failure is a row, never the
6808
7214
  sweep's failure.
6809
7215
 
7216
+ ### The host run (`oats host run`)
7217
+
7218
+ `oats host run [--stop-grace <seconds>] [--plan] [--json]` runs
7219
+ the kernel's periodic work in one foreground process, for a host where no
7220
+ timer can ([container.md](container.md#the-kernels-periodic-work)). It is
7221
+ this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
7222
+
7223
+ - **Refused before any effect**, through the standard failure envelope, exit 1:
7224
+ - `E_USAGE`: `OATS_INSTANCE_HOME` is set (it runs as the host, never inside
7225
+ an instance session);
7226
+ - `E_HOST_RUN_TIMER_ACTIVE`: the host timer is active, so two tickers would
7227
+ run; `error.details` `{unit}`. Unit files that are installed and not
7228
+ active are a warning, not a refusal;
7229
+ - `E_HOST_RUN_BUSY`: another `oats host run` holds this machine's lock
7230
+ (`<OATS_HOME_DIR>/host-run/lock`, a kernel-private file), or the lock
7231
+ cannot be judged; `error.details` `{lock, found}`, `found` as
7232
+ `E_RESUME_LOCK_STUCK` names it, and `running` for a host run that runs.
7233
+ A lock whose holder is gone, or that was taken in another boot (in a
7234
+ container, another run), is taken over;
7235
+ - `E_BAD_ARGS`: a flag it does not define, an argument, a `--stop-grace`
7236
+ that is not 1 to 300 seconds, a verb other than `run`.
7237
+
7238
+ Any other failure of the run itself is `E_HOST_RUN_FAILED`, which says
7239
+ nothing of how far it got. A child that ended without an answer is
7240
+ reported under that code too, in `sweep.error` or on stderr, and does not
7241
+ end the run.
7242
+ - **What it runs, in order.** The resume sweep once (`oats session resume`).
7243
+ Then at second 0 of every minute: `oats schedule tick --host` when the
7244
+ host schedule registry lists a scope, and a listing of every deployment's
7245
+ instances, which records what runs for the next start's sweep. Each is a
7246
+ child process. A minute whose tick still runs is skipped; a minute missed
7247
+ is never replayed. With no scope registered it ticks nothing and says so.
7248
+ - **On SIGTERM or SIGINT.** No further minute starts; a tick or a sweep that
7249
+ runs is waited for; it lists once; then it stops every running home, side
7250
+ by side, each with the stop `oats session restart` uses: SIGTERM to the
7251
+ harness, a wait of `--stop-grace` seconds (default 20), never escalated.
7252
+ Each home's stop record is written before its harness is signalled and
7253
+ says `"resume": true, "reason": "host-stop"`, so the home reads
7254
+ `sessionEnd: "lost"` and the next start's sweep resumes it. It exits 0.
7255
+ - **Progress** is one line per event on stderr (`oats host run: …`), in both
7256
+ modes. **The answer** is written once, when the run ends:
7257
+ `result` `{schemaVersion: 1, plan: false, signal, warnings, sweep, ticks, stopped}`.
7258
+ `signal` is `"SIGTERM"` or `"SIGINT"`; `warnings` an array of strings;
7259
+ `sweep` the sweep's own `result`
7260
+ ([The machine sweep](#the-machine-sweep-oats-session-resume)), or
7261
+ `{error: {code, message}}` when it failed (the run goes on); `ticks`
7262
+ `{run, skipped, failed, noScope}`, minutes counted; `stopped` one row per
7263
+ home that ran when it stopped: `{ok: true, home, stopped, alreadyIdle, state}`
7264
+ or `{ok: false, home, code, message, stillRunning}` (`stillRunning`: the
7265
+ pids the stop established as alive, or `null`). A home that did not stop is
7266
+ a row, never the run's failure.
7267
+ - **`--plan`** starts nothing, takes no lock and writes nothing: `result`
7268
+ `{schemaVersion: 1, plan: true, refusals, warnings, scopes, sweep}`.
7269
+ `refusals` is every refusal a run would meet now, in a run's order, each
7270
+ `{code, message, details?}`; `scopes` the registered scopes it would tick;
7271
+ `sweep` the sweep's `--plan` result. It exits 0 also when `refusals` is not
7272
+ empty.
7273
+
6810
7274
  ### Upload
6811
7275
 
6812
7276
  ```text
@@ -6900,7 +7364,7 @@ reading asks it for a live read, and every other reading for nothing
6900
7364
  passes its own exec must keep those three properties: detached, file-backed,
6901
7365
  and never signalling the child.
6902
7366
  - 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
7367
+ envelope whatever the exit (`E_RESUME_BUSY` and `E_RESUME_LOCK_STUCK` exit 1). Otherwise it answers
6904
7368
  a code of its own, with no message: `E_CLI_OUTPUT_LIMIT` (more than 4 MiB),
6905
7369
  `E_CLI_PROTOCOL` (no envelope), `E_CLI_FAILED` (a nonzero exit without an
6906
7370
  `ok:false` envelope, or an exec that throws). No stderr and no exception text
@@ -6937,15 +7401,17 @@ accept `--server <id>`.
6937
7401
  ```json
6938
7402
  {"context":"/w","level":"/w","file":"/w/oats-local.yaml","selected":null,
6939
7403
  "configurations":[{"name":"reviewers","harness":"claude","executable":null,"args":["--permission-mode","plan"],
6940
- "env":{"ANTHROPIC_API_KEY":{"fromEnv":"REVIEW_KEY"},"REVIEW_MODE":{"redacted":true}},
7404
+ "env":{"ANTHROPIC_API_KEY":{"fromEnv":"REVIEW_KEY"},"CLAUDE_CODE_OAUTH_TOKEN":{"fromFile":"/etc/agent-login/claude-token"},"REVIEW_MODE":{"redacted":true}},
6941
7405
  "model":"opus","yolo":null,"default":false,"source":"/w/oats-local.yaml","shadows":[]}]}
6942
7406
  ```
6943
7407
 
6944
7408
  - **list**: `selected` is `null`, `{home, instance}` or `{soul, agentsRoot}`;
6945
7409
  `level` and `file` are `null` without an `oats-local.yaml` (the set is then
6946
7410
  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
7411
+ `{fromEnv: NAME}` or `{fromFile: /absolute/path}`; resolved values are never
7412
+ returned. File references hold credential values; directory selectors require
7413
+ a literal or `fromEnv` ([configuration.md](configuration.md)). `default`
7414
+ (0.32, feature `launch-config-default`) is always a boolean: `true` marks this host's
6949
7415
  default for the configuration's harness.
6950
7416
  - **set**/**remove**: `{name, action, level, file, before, after,
6951
7417
  effective}`. `set --file` takes `{harness, executable?, args?, env?, model?,
@@ -6981,8 +7447,8 @@ accept `--server <id>`.
6981
7447
  - **preview** (read-only) answers `{context, selected, selection: {source,
6982
7448
  launchConfig, harness, model, yolo}, harness, model, modelSource, yolo,
6983
7449
  launchConfig, launchConfigSource, launchConfigDefault, executable: {path,
6984
- declared, resolvedFrom}, argv, environment: [{name, fromEnv} | {name, redacted:
6985
- true} | {name, reference: true}], command (redacted), prompt, hooks,
7450
+ declared, resolvedFrom}, argv, environment: [{name, fromEnv} | {name, fromFile}
7451
+ | {name, redacted: true} | {name, reference: true}], command (redacted), prompt, hooks,
6986
7452
  preflight: [{check, ok, detail, code?}], ok}`. A failed check carries the
6987
7453
  code a start would refuse with; the `harness-packages` check's is the
6988
7454
  gate's own, `E_HARNESS_RESOURCE_MISSING` (`E_HARNESS_PACKAGE` before
@@ -7069,6 +7535,27 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
7069
7535
  `command` or `operation` attempt with `exited: true` (0.40.0) holds no host
7070
7536
  slot (`running: false`) but still blocks its own job; show it as needing
7071
7537
  `oats schedule reconcile <id>` (or `--clear`) either way.
7538
+ - **A slot whose record cannot be read** keeps `running: true`. The tick
7539
+ reports its job `invalid` (`E_SCHEDULE_INVALID`) and runs the scope's
7540
+ other jobs; `reconcile <id>` answers `{reconciled: "unknown", remedy}`
7541
+ and `reconcile <id> --clear` releases the slot (`reconciled: "cleared"`).
7542
+ `oats doctor --json` lists it as a `schedule-slot-unreadable` problem,
7543
+ `{code, severity, scope, id, message, remedy}`
7544
+ ([Schedules](schedules.md#files)).
7545
+ - **A slot whose schedule is gone** (a local one not in
7546
+ `oats-schedules.json`; a workspace one not in the saved snapshot, decided
7547
+ without refreshing it), readable or not, is counted by every tick until it
7548
+ is released. `reconcile <id>` answers `{schedule: null, reconciled:
7549
+ "unknown", remedy}` naming the run its record names, and `reconcile <id>
7550
+ --clear` releases it, resolves a retained attempt as cleared and removes
7551
+ the job's state: `{schedule: null, reconciled: "cleared", cleared}`,
7552
+ `cleared` listing `"slot"`, `"attempt"` and `"state"` as each was there;
7553
+ a gone schedule with retained state and no slot is reconciled the same
7554
+ way (`cleared: ["attempt", "state"]`).
7555
+ A workspace schedule that is disabled, untrusted or placed elsewhere is
7556
+ not gone (`E_AUTOMATION_NOT_HERE`). `oats doctor --json` lists the slot as
7557
+ a `schedule-slot-orphaned` problem of the same shape
7558
+ ([Schedules](schedules.md#files)).
7072
7559
  - **Schedule IDs**: local and workspace schedule definition names permit 1–100
7073
7560
  lowercase letters, digits and dashes; trigger names retain their 40-character
7074
7561
  limit. Desktop accepts these schedule names for creation, editing and row
@@ -7123,6 +7610,13 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
7123
7610
  `disable` → `{schedule}`. `run [--force]`, `remove [--force]`, `reconcile
7124
7611
  [--clear]` → the action's receipt. `tick [--dry-run] [--host]` →
7125
7612
  `{tickedAt, considered, scheduler}`; `host install` → `{scheduler, warnings}`;
7613
+ `host install --register-only` → the same answer, the scope recorded in the
7614
+ host registry and no unit installed (`scheduler.registered: true`,
7615
+ `installed: false`, `warnings: []`), for a host whose ticker is
7616
+ [`oats host run`](#the-host-run-oats-host-run); it does not go with
7617
+ `--print` (`E_BAD_ARGS`), and with `--server` the host must advertise
7618
+ `schedule` and `schedule-host-register-only` (`E_REMOTE_INCOMPATIBLE`
7619
+ otherwise, before anything is sent: nothing is installed there);
7126
7620
  `host uninstall | status` → `{scheduler}`; `host install --print [--os
7127
7621
  darwin|linux]` → `{kind, files: {<path>: <content>}, warnings}`, writing
7128
7622
  nothing.
@@ -7439,6 +7933,47 @@ One warning per command, however many old spellings it read:
7439
7933
  The `--server` routes translate for a host without the `harness` feature:
7440
7934
  they send `--runtime` and `runtime` keys and read its `runtimes` list.
7441
7935
 
7936
+ <a id="harness-token"></a>
7937
+ ### `harness token`
7938
+
7939
+ `oats harness token set|status|remove <harness> --server <id> [--name <team>] [--stdin] [--debug] --json`
7940
+ runs on the operator's machine. Its `--server` selects that registration's
7941
+ separate operator route, never a remote invocation of this CLI. The harness
7942
+ is `claude`, `codex`, `pi` or `opencode`; the name defaults to a valid
7943
+ server label and otherwise is required. The ordinary schemaVersion 1 envelope's
7944
+ result is:
7945
+
7946
+ ```json
7947
+ {"server":"build","action":"status","harness":"claude","name":"team","fingerprint":"sha256:0123456789abcdef","replacedAt":"2026-11-10T00:00:00Z","warnings":[]}
7948
+ ```
7949
+
7950
+ For `remove`, `action` is `remove` and `fingerprint` is `null`.
7951
+ `set --stdin` returns `action: "set"` and also `staleInstances`, an array
7952
+ of `{instance, agent, home, startedAt}` from that server's status rows, with
7953
+ the same harness and a last-start time before or during the second named by
7954
+ `replacedAt`. The receiver records whole seconds, so starts during that second
7955
+ are included conservatively: they may still use the previous credential. If
7956
+ that roster cannot be read, `staleInstances` is `null` and `warnings` holds
7957
+ a plain explanation; the installation remains successful. No automatic
7958
+ restart is performed. Only `set` accepts stdin, as bounded credential bytes;
7959
+ there is no credential argument, result field, event or file on the client.
7960
+ The receiver's single JSON line and exit status must agree, name the requested
7961
+ harness and team, and carry valid metadata. Malformed or oversized replies fail
7962
+ closed as unexpected replies. Text-mode refusal messages escape remote control
7963
+ characters for the terminal. C0 controls and DEL in refusal reasons become
7964
+ spaces in both modes; JSON retains the remaining characters without terminal escaping.
7965
+ The submitted credential is redacted in both modes.
7966
+ Refusals: `E_BAD_ARGS` for unsupported arguments or names,
7967
+ `E_SERVER_UNKNOWN` for a server id without a registration, even with an orphan operator route,
7968
+ `E_HARNESS_TOKEN_ROUTE` for a missing operator alias,
7969
+ `E_HARNESS_TOKEN_INPUT` for invalid, too-large or terminal stdin,
7970
+ `E_HARNESS_TOKEN_UNSUPPORTED` for unavailable interactive capture or a
7971
+ refreshing sign-in, and
7972
+ `E_HARNESS_TOKEN_DELIVERY` for connection failure, receiver refusal or an
7973
+ unexpected reply. Public errors do not forward raw SSH or malformed receiver
7974
+ output. `--debug` adds transport facts on stderr, never stdin or raw receiver
7975
+ output that might echo it. See [servers](servers.md#harness-credentials).
7976
+
7442
7977
  ### `harness trust`
7443
7978
 
7444
7979
  `oats harness trust [--dir <deployment>] [--harness claude|codex|all] [--plan] [--json]`