@awebai/oats 0.69.22 → 0.69.24

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 (98) hide show
  1. package/bin/oats.mjs +185 -38
  2. package/docs/capabilities.md +365 -7
  3. package/docs/capability-manifest.schema.json +37 -1
  4. package/docs/configuration.md +27 -7
  5. package/docs/container.md +206 -228
  6. package/docs/design/2026-11-19-sandboxes.md +1352 -0
  7. package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
  8. package/docs/design/README.md +7 -0
  9. package/docs/desktop-cli-api.md +673 -81
  10. package/docs/desktop.md +241 -65
  11. package/docs/execution-targets.md +186 -3
  12. package/docs/first-team.md +11 -0
  13. package/docs/implementation.md +6 -2
  14. package/docs/integrations.md +3 -3
  15. package/docs/knowledge-capability-authoring.md +10 -7
  16. package/docs/knowledge-reference/acceptance.md +21 -19
  17. package/docs/knowledge-reference/adoption.md +18 -4
  18. package/docs/knowledge-reference/model.md +11 -9
  19. package/docs/knowledge-reference/package-craft.md +2 -2
  20. package/docs/knowledge-reference/proposal.md +127 -0
  21. package/docs/knowledge-reference/provider-mapping.md +10 -10
  22. package/docs/knowledge-reference/reader-capture.md +26 -22
  23. package/docs/knowledge-theory.md +1 -1
  24. package/docs/knowledge.md +25 -16
  25. package/docs/official-catalog.md +4 -4
  26. package/docs/packages.md +13 -13
  27. package/docs/release-notes/v0.69.23.md +231 -0
  28. package/docs/release-notes/v0.69.24.md +264 -0
  29. package/docs/servers.md +10 -6
  30. package/docs/souls-and-instances.md +96 -22
  31. package/docs/tui.md +25 -4
  32. package/docs/upgrading.md +19 -5
  33. package/docs/workspaces.md +14 -6
  34. package/lib/argv.mjs +6 -2
  35. package/lib/capability-contract.mjs +2 -2
  36. package/lib/capability-show.mjs +11 -1
  37. package/lib/command-flags.mjs +40 -3
  38. package/lib/compile-cache.mjs +1 -1
  39. package/lib/core.mjs +1201 -195
  40. package/lib/errors.mjs +4 -1
  41. package/lib/hook-env.mjs +106 -0
  42. package/lib/host-run.mjs +11 -3
  43. package/lib/instance-board.mjs +337 -0
  44. package/lib/instance-events.mjs +48 -10
  45. package/lib/instance-inspect.mjs +44 -0
  46. package/lib/instance-lifecycle.mjs +34 -18
  47. package/lib/instance-listing.mjs +113 -16
  48. package/lib/instance-related-work.mjs +143 -0
  49. package/lib/kernel-features.mjs +13 -1
  50. package/lib/node-version.mjs +9 -0
  51. package/lib/provider-call-child.mjs +60 -0
  52. package/lib/provider-resume.mjs +83 -0
  53. package/lib/provider-test-seams.mjs +20 -0
  54. package/lib/read-call.mjs +2 -0
  55. package/lib/reserved-launch-env.mjs +8 -1
  56. package/lib/retire-admission.mjs +5 -1
  57. package/lib/schedule.mjs +14 -4
  58. package/lib/servers.mjs +151 -17
  59. package/lib/session-inspect.mjs +104 -13
  60. package/lib/session-providers.mjs +528 -0
  61. package/lib/session-resume.mjs +68 -15
  62. package/lib/stable-node.mjs +3 -0
  63. package/lib/triggers.mjs +3 -1
  64. package/package-catalog.json +3 -3
  65. package/package.json +2 -1
  66. package/packages/client/capability-list.mjs +21 -0
  67. package/packages/client/cli-adapter.mjs +19 -4
  68. package/packages/client/cli-locator.mjs +5 -1
  69. package/packages/client/deployment-data.mjs +27 -3
  70. package/packages/client/deployment-panel.mjs +27 -4
  71. package/packages/client/home-board.mjs +33 -19
  72. package/packages/client/inspect-boundary.mjs +18 -8
  73. package/packages/client/instance-acts.mjs +30 -3
  74. package/packages/client/instance-board.mjs +206 -0
  75. package/packages/client/instance-presentation.mjs +55 -0
  76. package/packages/client/instance-tree.mjs +34 -4
  77. package/packages/client/keymap.mjs +5 -0
  78. package/packages/client/liveness.mjs +15 -4
  79. package/packages/client/mail-contract.mjs +130 -0
  80. package/packages/client/own-codes.mjs +5 -1
  81. package/packages/client/panel-views.mjs +7 -7
  82. package/packages/client/related-work.mjs +84 -0
  83. package/packages/client/remote-roster.mjs +9 -3
  84. package/packages/client/session-backends.mjs +31 -0
  85. package/packages/client/session-start.mjs +18 -6
  86. package/packages/client/spawn-apply-cli.mjs +5 -3
  87. package/packages/client/spawn-apply-contract.mjs +25 -2
  88. package/packages/client/spawn-apply.mjs +5 -1
  89. package/packages/client/spawn-messages.mjs +3 -0
  90. package/packages/client/terminal-contract.mjs +4 -0
  91. package/packages/client/waiting-on-you.mjs +12 -2
  92. package/packages/client/workspace-cli.mjs +13 -2
  93. package/packages/tui/lib/model.mjs +14 -3
  94. package/packages/tui/lib/store.mjs +12 -3
  95. package/skills/oats-getting-started/SKILL.md +11 -8
  96. package/docs/knowledge-reference/harvester.md +0 -109
  97. package/lib/instance-same-work.mjs +0 -67
  98. package/packages/client/same-work.mjs +0 -49
@@ -66,9 +66,12 @@ see the [official catalog](official-catalog.md) for current pins.
66
66
  with against that kernel's own version, so never finds it above. A
67
67
  `desktopApi` other than 1 is refused (`newerApi` on the candidate when it is
68
68
  a higher one).
69
- - `harnesses` is what `--harness` accepts; `sessionBackends` what `--backend`
70
- accepts: `["tmux"]` since 0.31.0, when Herdr was removed (`--backend herdr`
71
- is refused with `E_HERDR_REMOVED`). A host without the `harness` feature
69
+ - `harnesses` is what `--harness` accepts; `sessionBackends` the kernel's own
70
+ session backends: `["tmux"]` since 0.31.0, when Herdr was removed (`--backend
71
+ herdr` is refused with `E_HERDR_REMOVED`). With the feature
72
+ `session-providers`, `--backend` also takes a session provider's name: a
73
+ backend a capability supplies, never listed here
74
+ ([Session providers](#session-providers-feature-session-providers)). A host without the `harness` feature
72
75
  lists `runtimes` instead.
73
76
  - `remote` is the routed surface: the commands `--server <id>` sends to a
74
77
  registered server, plus `roster`. The Desktop checks the execution host's
@@ -91,6 +94,9 @@ see the [official catalog](official-catalog.md) for current pins.
91
94
  --stdio`, which the reader's hello repeats. Start a reader only where the
92
95
  probe lists both the feature and `readerApi: 1`
93
96
  ([The warm reader](#the-warm-reader)).
97
+ - `boardApi` (feature `instance-board`) is the version of the agent's board:
98
+ the `board` on the rows, `inspect --board` and the board commands' answers
99
+ ([The agent's board](#the-agents-board-oats-instance-board)).
94
100
  - In text mode the command prints `@awebai/oats <version> (desktop API v1)`.
95
101
 
96
102
  ### Features
@@ -167,7 +173,8 @@ see the [official catalog](official-catalog.md) for current pins.
167
173
  | `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
168
174
  | `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
169
175
  | `instance-color` | `oats instance color <instance> (<color> \| --clear)`, local and `--server` ([An instance's colour](#an-instances-colour-oats-instance-color)); `color` on `oats status --json` instance rows, on `oats server roster --json` rows and on `oats inspect --home` `instance` (`null` for none). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows have no `color` | `instanceColorApi: 1` (payload only) |
170
- | `instance-same-work` | `oats instance same-work <instance> on\|off` and `oats spawn … --same-work`, local and `--server` ([Same work as the parent](#same-work-as-the-parent-oats-instance-same-work)); `sameWork: true` on `oats status --json` instance rows and on `oats server roster --json` rows while the instance's flag is bound to its current `parentInstance`, the key absent otherwise ([`sameWork`](#row-same-work)). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows never carry `sameWork`, and it refuses the flag and the verb (`E_BAD_ARGS`) | |
176
+ | `instance-related-work` | `oats instance related-work <instance> on\|off` and `oats spawn … --related-work`, local and `--server` ([Related work](#related-work-oats-instance-related-work)); `relatedWork: true` on `oats status --json` instance rows and on `oats server roster --json` rows while the instance's flag is bound to its current `parentInstance`, or, with no parent, to its current `siblingInstance`, the key absent otherwise ([`relatedWork`](#row-related-work)). It renames `instance-same-work`, still advertised beside it ([below](#feature-instance-same-work)). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows never carry `relatedWork`, and it refuses the flag and the verb (`E_BAD_ARGS`) | |
177
+ | <a id="feature-instance-same-work"></a>`instance-same-work` | the related-work flag by its old name, kept for a release at least ([The deprecated aliases](#the-deprecated-aliases)): `oats spawn … --same-work` and `oats instance same-work <instance> on\|off` work as the new spellings, each use saying so in one line on stderr and never in `--json`; status and roster rows carry `sameWork: true` beside `relatedWork: true` for a parent binding; `.oats-same-work.json` reads as a parent binding while `.oats-related-work.json` is absent. An older kernel advertises it alone: there the flag binds a parent only. Its removal gets its own release-notes entry | |
171
178
  | `deployments-list` | `oats deployments [list]\|add\|remove\|import --json`, this computer's list of its deployments (`~/.oats/config/deployments.json`); `listed` on `oats onboard --json`; a kernel command run in an unlisted deployment lists it ([This computer's deployments](#this-computers-deployments-oats-deployments)). Gate on the probe: there is no fallback scan | `deploymentsApi: 1` |
172
179
  | `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
173
180
  | `instance-suggest-name` | `oats instance suggest-name [--soul <soul>] (--task <t> \| --task-file <f>) [--harness claude\|pi] [--model <m>] [--launch-config <n>] --json`: the name a `--suggest-name` spawn would get, chosen on this machine for a spawn that may land on another, not made unique ([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)). Local only: `--server` is `E_BAD_ARGS`. Gate on the local probe; without it, the spawn goes unnamed (numbered, or named where it lands) | |
@@ -183,7 +190,9 @@ see the [official catalog](official-catalog.md) for current pins.
183
190
  | `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) | |
184
191
  | `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 | |
185
192
  | `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 | |
193
+ | `instance-board` | the agent's board: `oats instance board set\|unset\|ask\|ask --clear`, run by the agent in its own home; `board` on `oats status --json` instance rows and `oats server roster --json` rows; `oats inspect --home <h> --board` for each fact's history and each question's context; the `oats.board` needs-input claim, reason `attention` ([The agent's board](#the-agents-board-oats-instance-board)). Gate on the probe, locally or in the host's `probe.features`: an older kernel refuses `oats instance board` (`E_BAD_ARGS`) and its rows have no `board` | `boardApi: 1` |
186
194
  | `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)) |
195
+ | `session-providers` | session backends a capability supplies ([Session providers](#session-providers-feature-session-providers)): `--backend <provider>` on `oats spawn` (a schedule's `backend`, a trigger's `spawn.backend`); a provider home's `backend`, `session` and `open` on its status row (the endpoint only on its local inspect, spawn and start answers; nothing of it relayed); `backend: "tmux"` on a tmux home's status row; `sessionProviders` in `oats inspect` and `oats capabilities show`; a provider's readiness in `oats readiness`; `backends` on a capability's `requires` row; the codes `E_BACKEND_UNKNOWN`, `E_BACKEND_AMBIGUOUS`, `E_BACKEND_HARNESS`, `E_BACKEND_LAUNCH_ARG`, `E_BACKEND_NOT_READY`, `E_SESSION_NO_TERMINAL`, `E_SESSION_PROMPT_OPEN`, `E_SESSION_INPUT_QUEUED`; `backend` on the sweep's rows of provider homes; `oats session resume --plan --without-provider-inspect`, which is `oats host run`'s own switch for its shutdown listing, not a client's. A routed `--backend <provider>` is sent only to a host that lists it. |
187
196
 
188
197
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
189
198
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -322,23 +331,27 @@ for `--no-recursive`) is never ignored.
322
331
  | Command | Arguments | Flags that take a value | Switches | Refused in their own words | Its own answers |
323
332
  |---|---|---|---|---|---|
324
333
  | `oats retire` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir`, `--server` | `--plan`, `--self`, `--discard-worktree`, `--keep-dir`, `--force`, `--json` | `--delete-branch` | none |
325
- | `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 |
334
+ | `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`, `--related-work`, `--same-work`, `--suggest-name`, `--yolo` | `--instructions-file`, `--def-file`, `--ephemeral` | an unknown flag, an argument after the last |
326
335
  | `oats sync` | none | `--dir` | `--plan`, `--json` | `--approve` | none |
327
336
  | `oats instance stop` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--grace-ms`, `--home`, `--dir`, `--server` | `--plan`, `--apply`, `--no-recursive`, `--json` | none | none |
328
337
  | `oats instance upgrade` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir` | `--undo`, `--plan`, `--json` | `--server` | none |
329
338
  | `oats instance color` | `<instance>` `[<color>]` | `--home`, `--dir`, `--server` | `--clear`, `--json` | none | none |
330
339
  | `oats instance background` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
331
340
  | `oats instance pin` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
341
+ | `oats instance related-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
332
342
  | `oats instance same-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
333
343
  | `oats instance waiting set` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
334
344
  | `oats instance waiting clear` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
335
345
  | `oats instance attention` | none | `--message` | `--clear`, `--json` | `--home`, `--dir`, `--producer`, `--reason` | none |
346
+ | `oats instance board set` | `<key>` | `--label`, `--value`, `--unit`, `--link` | `--json` | `--home`, `--dir`, `--server` | none |
347
+ | `oats instance board unset` | `<key>` | none | `--json` | `--home`, `--dir`, `--server` | none |
348
+ | `oats instance board ask` | `[<question>]` | `--option`, `--id`, `--context-file`, `--clear` | `--json` | `--home`, `--dir`, `--server` | none |
336
349
  | `oats instance suggest-name` | none | `--soul`, `--task`, `--task-file`, `--harness`, `--model`, `--launch-config`, `--dir` | `--json` | `--server` | none |
337
350
  | `oats worktree add` | none | `--purpose`, `--branch`, `--base`, `--repo` | `--preview`, `--json` | `--server`, `--dir`, `--home` | none |
338
351
  | `oats worktree remove` | none | `--purpose` | `--json` | `--server`, `--dir`, `--home` | none |
339
352
  | `oats session start` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json`, `--resume` | `--native-record` | none |
340
353
  | `oats session restart` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server`, `--stop-grace` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json` | `--native-record`, `--resume` | none |
341
- | `oats session resume` | none | `--deployment` | `--plan`, `--json` | `--native-record`, `--server` | none |
354
+ | `oats session resume` | none | `--deployment` | `--plan`, `--without-provider-inspect`, `--json` | `--native-record`, `--server` | none |
342
355
  | `oats session input` | none | `--home`, `--text-file` | `--json` | `--native-record` | none |
343
356
  | `oats session receive` | none | `--home`, `--name` | `--json` | `--native-record` | none |
344
357
  | `oats session upload` | none | `--file`, `--home`, `--instance`, `--server` | `--json` | `--native-record` | none |
@@ -428,6 +441,7 @@ kernel command.
428
441
 
429
442
  | Code | When |
430
443
  |---|---|
444
+ | `E_NODE_UNSUPPORTED` | Node.js is older than 22: before every command, exit 1 with `details: {found: "<process.versions.node>", minimum: "22"}` and message `oats needs Node.js 22 or later; this is Node.js <found>`. With `--json` anywhere in argv, stdout is one failure envelope; otherwise the message is on stderr. This includes the `version --json` probe, whose success shape is not the envelope: on unsupported Node it answers this failure envelope with exit 1. Node 18 and 20 get this refusal; a Node too old to parse the entry can fail with a SyntaxError first |
431
445
  | `E_UNKNOWN_COMMAND` | No kernel command or capability namespace matches; an unknown capability subcommand; a [removed verb](#removed-verbs-and-flags) (`details: {removed, replacement}`) |
432
446
  | `E_CAPABILITY_INACTIVE` | In a home: the namespace's module is not one of the home's recorded capabilities |
433
447
  | `E_CAPABILITY_BLOCKED` | In a home: the manifest claiming the namespace is not a workspace module copy of that home. There is no package trust gate |
@@ -631,7 +645,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
631
645
  ### `oats inspect`
632
646
 
633
647
  ```text
634
- oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
648
+ oats inspect (--home <abs> [--board] | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
635
649
  ```
636
650
 
637
651
  An instance subject, abridged:
@@ -673,7 +687,7 @@ An instance subject, abridged:
673
687
  | `capabilities`, `capabilitiesOff` | the resolved modules (by id) and the ones the soul turned off |
674
688
  | `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
675
689
  | `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
676
- | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order. `color` (feature `instance-color`) is the instance's colour or `null` ([An instance's colour](#an-instances-colour-oats-instance-color)) |
690
+ | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order. `color` (feature `instance-color`) is the instance's colour or `null` ([An instance's colour](#an-instances-colour-oats-instance-color)). `board` (feature `instance-board`) is there only with `--board`, which takes `--home` (`--soul` is `E_BAD_ARGS`): the row's [`board`](#row-board) with each fact's `history` and each question's `context` ([The agent's board](#the-agents-board-oats-instance-board)). Routed with `--server`, `--board` needs the host's feature (`E_REMOTE_INCOMPATIBLE`, nothing sent) |
677
691
  | `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
678
692
  | `problems` | below |
679
693
  | `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
@@ -1001,6 +1015,15 @@ oats operation run <layer>:<name> (--home <abs> | --soul <name> [--dir <d>]) [--
1001
1015
  at the top level; `stderr` appears when the provider wrote any.
1002
1016
  - A `view` operation must answer `{documents: [{label, kind?, path?, text?}]}`
1003
1017
  (`kind` `markdown` or `text`), else `E_OPERATION_RESULT`.
1018
+ - **A view may carry one structured field** beside `documents`, named after
1019
+ its operation and versioned by its own `<name>Api` inside it: `mail` with
1020
+ `mailApi` for `messaging:mail` ([Mail](#mail-mailapi-1)). `documents` stays
1021
+ the plain rendering every view reader can show. The kernel validates
1022
+ `documents` only, and relays the provider's `result` unchanged, locally and
1023
+ through `--server`, where the routing keys (`server`, `route`) sit beside
1024
+ `result`, never inside it. A client reads the structured field only at a
1025
+ `<name>Api` it knows, and falls back to `documents` otherwise. A view carries
1026
+ at most one such field.
1004
1027
  - Errors: `E_OPERATION_UNKNOWN`, `E_OPERATION_UNAVAILABLE` (empty slot, or a
1005
1028
  home operation without `--home`), `E_CAPABILITY_REQUIRES`, `E_BAD_ARGS`
1006
1029
  (undeclared or missing `--arg`), `E_CAPABILITY_BROKEN`. A provider's `ok:
@@ -1019,6 +1042,119 @@ advertises `operations`.
1019
1042
  inspect; the provider's version owns their result shapes. For oats.okf, see
1020
1043
  [knowledge.md](knowledge.md#knowledge-operations).
1021
1044
 
1045
+ **Messaging operations.** The messaging provider's operations are listed by
1046
+ inspect too. One of them is a contract of the messaging layer, whatever the
1047
+ provider: `messaging:mail`, below. oats.aweb is its first provider, from the
1048
+ release that adds it (its `docs/mail-read.md` says how it reads).
1049
+
1050
+ <a id="mail-mailapi-1"></a>
1051
+ #### Mail, `mailApi: 1`
1052
+
1053
+ `messaging:mail` is a read-only view of an instance's own mail, received and
1054
+ sent, newest first. It **never acknowledges** or marks anything read on the
1055
+ agent's behalf. Any messaging provider may answer it.
1056
+
1057
+ ```text
1058
+ oats operation run messaging:mail --home <abs> [--arg limit=50] [--arg cursor=<nextCursor>] [--arg conversation=<id>] [--server <id>] --json
1059
+ ```
1060
+
1061
+ The provider's manifest declares it as a home view operation with three
1062
+ optional args:
1063
+
1064
+ ```json
1065
+ "mail": {"kind": "view", "command": "mail", "context": "home",
1066
+ "description": "Read-only: this instance's mail, received and sent, newest first. Never acknowledges.",
1067
+ "args": [{"name": "limit", "flag": "--limit"}, {"name": "cursor", "flag": "--cursor"}, {"name": "conversation", "flag": "--conversation"}]}
1068
+ ```
1069
+
1070
+ Its `result`:
1071
+
1072
+ ```json
1073
+ {"documents":[{"label":"Mail","kind":"markdown","text":"…plain rendering…"}],
1074
+ "mail":{"mailApi":1,"acknowledges":false,"observedAt":"2026-11-19T12:00:00.000Z",
1075
+ "identities":[{"team":"oats","alias":"dev-1","identity":"<opaque>","primary":true,"error":null},
1076
+ {"team":"alpha","alias":"dev-1","identity":"<opaque>","primary":false,"error":"conversation-unreadable",
1077
+ "unreadableConversations":["<opaque>"]}],
1078
+ "messages":[{"id":"<opaque>","conversationId":"<opaque>","threadTitle":"Review","direction":"received","team":"oats",
1079
+ "from":{"alias":"lead","address":"oats.aweb.ai/lead","identity":"<opaque>"},
1080
+ "to":{"alias":"dev-1","address":"oats.aweb.ai/dev-1","identity":"<opaque>"},
1081
+ "subject":"Review","body":"…","truncated":false,"createdAt":"2026-11-19T11:58:00Z",
1082
+ "readByAgent":false,"encrypted":false,"verification":"verified","priority":"normal"}],
1083
+ "conversations":[{"id":"<opaque>","partial":null}],
1084
+ "hasMore":false,"nextCursor":null}}
1085
+ ```
1086
+
1087
+ - **Opaque values.** `identity` ids, message and conversation ids, `team`
1088
+ labels and `nextCursor` are the provider's strings: a client compares them
1089
+ and passes them back, and never parses them. `from`/`to` `address` may be
1090
+ `null`; `conversationId` is `null` for mail with no conversation.
1091
+ - **Order.** Newest first by `createdAt`, across every identity of the
1092
+ instance (its primary one and each joined team's), merged, each message
1093
+ labelled by the `team` it was read in. `direction` is decided by the
1094
+ sender's identity against the identity read. `identities` lists each
1095
+ identity read, the primary one first.
1096
+ - **Read state.** `readByAgent` reports the server's read state of a received
1097
+ message, and is `true` for a sent one. The read never changes it, and
1098
+ `acknowledges` is always `false`.
1099
+ - **Closed sets.** `direction`: `received` or `sent`. `verification`:
1100
+ `verified`, `unverified`, `failed` or `unknown`. `priority`: `normal`,
1101
+ `high` or `unknown`. `partial`: `null` or `oldest-first-only`. A client
1102
+ shows any other value as unknown.
1103
+ - **Bounds.** Each `body` is at most 16 KiB of UTF-8, cut at a character
1104
+ boundary, with `truncated: true`. The whole `result` is at most 256 KiB;
1105
+ past it the answer stops early, with `hasMore: true` and a `nextCursor`.
1106
+ Where one message alone wouldn't fit, its `subject` and `threadTitle` are
1107
+ cut too, and `truncated: true` marks that as well: `truncated` means the
1108
+ provider shortened the message, whichever of its texts it cut. An answer
1109
+ is never sent oversized, nor as an empty page with `hasMore: true` and no
1110
+ `nextCursor`. `limit` is 1 to 200, default 50 (`E_BAD_ARGS` otherwise).
1111
+ - **Paging.** `nextCursor`, passed back as `--arg cursor=…`, gives the next
1112
+ messages in the same order, with no overlap. What a cursor encodes is the
1113
+ provider's (oats.aweb's: the last message's `createdAt`, id and team). `--arg conversation=<id>`
1114
+ reads one conversation, newest first; its cursor is valid only with the same
1115
+ conversation.
1116
+ - **Partial conversations.** Where the provider can read only the oldest part
1117
+ of a long conversation, the conversation is listed in `conversations` with
1118
+ `partial: "oldest-first-only"`, and its newest messages are missing, never
1119
+ shown as the latest. A client says "older part of a long conversation
1120
+ shown; the newest messages can't be read yet".
1121
+ - **Untrusted text.** `subject`, `threadTitle` and `body` are the sender's
1122
+ plain text: show them as text, attributed to their sender, never as markup.
1123
+ - **Encrypted mail.** End-to-end encrypted bodies are decrypted with the
1124
+ agent's keys, and shown to whoever can run `oats operation run` on that
1125
+ machine (routed reads included): the access that attaching to the agent's
1126
+ terminal already gives, no wider. `encrypted: true` marks them.
1127
+ - **Errors per identity.** In `identities[].error`, a provider's code (such
1128
+ as a grant without mail read). **An identity's `error` doesn't mean it has
1129
+ no messages:** it can come with that identity's messages beside it, and a
1130
+ reader shows both the mail and that some of it couldn't be read. One code
1131
+ is the layer's: `conversation-unreadable`, one or more of that identity's
1132
+ conversations couldn't be read; its other messages are shown, and the row
1133
+ names the missing ones in `unreadableConversations` (conversation ids,
1134
+ present only with that code, the list's tail dropped first if the 256 KiB
1135
+ bound needs it, so it may name fewer than failed, or none).
1136
+ - **Whole failures.** The operation fails whole, with no answer, in two
1137
+ cases: `E_MAIL_UNREADABLE` when no identity can be read
1138
+ (`details.identities` holds the rows), and `E_MAIL_TOO_LARGE` when even an
1139
+ answer with no messages can't fit the 256 KiB bound (its identities alone).
1140
+ - **Cost.** Each read calls the messaging service several times. Read on
1141
+ demand (opening a view, a manual refresh), never on a status poll.
1142
+ - **Older sides.** A home whose provider copy predates the operation answers
1143
+ `E_OPERATION_UNKNOWN` (inspect doesn't list `mail`): the home gets it from
1144
+ `oats instance upgrade` or a new spawn. A home with no messaging slot
1145
+ answers `E_OPERATION_UNAVAILABLE`, and a remote host without `operations`
1146
+ `E_REMOTE_INCOMPATIBLE`. A provider's own refusals are relayed with their
1147
+ code, such as oats.aweb's `E_AW_TOO_OLD` (`details: {version, needs}`) for
1148
+ an aw too old to read mail without acknowledging it.
1149
+ - **The provider's own.** How a provider maps its service's values onto the
1150
+ closed sets, its other identity error codes, what its cursor encodes and how
1151
+ much of a body its `documents` rendering shows are its own, in its docs. For
1152
+ oats.aweb: the "messaging:mail" section of its
1153
+ [README](https://github.com/awebai/oats-aweb/blob/main/README.md#messagingmail-an-instances-mail-read-without-acknowledging-it)
1154
+ and its [docs/mail-read.md](https://github.com/awebai/oats-aweb/blob/main/docs/mail-read.md)
1155
+ (the aw commands it runs, the verification and priority mappings, the
1156
+ cursor, every error code, a 500-character body excerpt in `documents`).
1157
+
1022
1158
  <a id="workspace-model-workspaceapi-2"></a>
1023
1159
  ## Workspace
1024
1160
 
@@ -1720,6 +1856,14 @@ capabilities | package <id>'s capabilities> were not checked …`, never an
1720
1856
  empty list read as "no warning". Older kernels answer no such `warnings` key
1721
1857
  (inspect, readiness, show, doctor) and refuse the capability instead.
1722
1858
 
1859
+ `oats doctor --json` reports the Git version and whether it supports partial
1860
+ caches in an existing `information[]` line starting `git-version:` (text:
1861
+ `INFO: git-version: …`). Git before 2.45 uses the whole-tree fallback; this
1862
+ is information, never a warning or a refusal. A failed version probe reports
1863
+ unknown support. A newer Git supports partial caches, but a remote can
1864
+ require whole-tree fetches and an existing whole-tree cache keeps its mode
1865
+ ([Git version failures](workspaces.md#membership-and-trust)).
1866
+
1723
1867
  `oats doctor --json` also lists what retires left behind in `information[]`:
1724
1868
  one `retained-recovery:` and one `retained-worktree:` line per item, after a
1725
1869
  line that gives each kind's total, and at most 50 items per kind
@@ -3091,7 +3235,9 @@ with `--expect-decision` records the key and decision in `instance.json`.
3091
3235
 
3092
3236
  - Always present: `instance, agent, home, work, branch, base ({ref, oid}
3093
3237
  the new branch started at; `null` without one), launched, warnings
3094
- (array), tmux ({session, window, socket?} | null), backend ("tmux"), repo, harness,
3238
+ (array), tmux ({session, window, socket?} | null), backend ("tmux", or a
3239
+ session provider's name with `session: {provider, endpoint}` after it and
3240
+ `tmux: null`, `attach: null`: [Session providers](#session-providers-feature-session-providers)), repo, harness,
3095
3241
  model, parent,
3096
3242
  sibling, relation, spawnOrigin (operator | instance), attach, launchConfig,
3097
3243
  launch` (the redacted recipe).
@@ -3336,7 +3482,7 @@ kernel stage raised as well.
3336
3482
 
3337
3483
  | Code | Details | When |
3338
3484
  |---|---|---|
3339
- | `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul; `--same-work` for an instance that would record no parent ([Same work as the parent](#same-work-as-the-parent-oats-instance-same-work)) |
3485
+ | `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul; `--related-work` (or its deprecated alias `--same-work`) for an instance that would record no parent or sibling ([Related work](#related-work-oats-instance-related-work)) |
3340
3486
  | `E_LOCAL_MISSING`, `E_NO_DEPLOYMENT` | | no `oats-local.yaml`; no `agents/` root |
3341
3487
  | `E_SOUL_UNKNOWN` | `{name, members, packages, unconfirmed?}` | no such soul, or not at `--agents-root`. `unconfirmed`, only when a member could not be confirmed: `[{key, reason, detail}]`, which the message repeats with what to do |
3342
3488
  | `E_SOUL_AMBIGUOUS` | `{name, repos, qualified}` | several souls answer the bare name; use one of `qualified` |
@@ -3754,6 +3900,62 @@ its absence.
3754
3900
  output, not the exit status, and nothing is printed, whether or not it can
3755
3901
  be read or written. A status routed with `--server` records nothing on this
3756
3902
  machine ([execution-targets.md](execution-targets.md#which-losses-come-back)).
3903
+ - <a id="row-backend-clients"></a>**How the clients read `backend`** (the
3904
+ Desktop and the TUI, `packages/client`). A row whose `backend` is text that
3905
+ is not empty and not `tmux` runs on a session provider, in no terminal (an
3906
+ empty `backend` names none: the kernel never sends one, and the row reads
3907
+ as one with no `backend`):
3908
+ - Its `running`, `runtimeState` and `runtimeError` are shown as the kernel
3909
+ reports them. No client asks tmux about it: with an older kernel, whose
3910
+ rows a client's own terminal check refines, such a row is never passed
3911
+ to that check.
3912
+ - Its acts are the ones of its state: Restart, Stop and Retire while it
3913
+ runs; Start, Stop and Retire stopped; Stop and Retire when the kernel
3914
+ answers `running: null`.
3915
+ - Open is never offered. The clients say where the agent runs ("Runs in a
3916
+ bb thread; open it in bb.") and, when the row carries `open`
3917
+ (`{label, url}`), show it as a link: the Desktop opens it in the system
3918
+ browser from the row's menu, the TUI prints the url. Only an `http` or
3919
+ `https` url with no credentials in it is shown, and only on a row of
3920
+ this machine: another machine's url is that machine's own loopback. No
3921
+ client attaches, splits or restores a terminal for the row.
3922
+ - Its `waitingOnYou` claim is shown unless the row is stopped
3923
+ (`running: false`): while it runs and when the kernel answers
3924
+ `running: null`, since an agent that waits on a person is idle in its
3925
+ provider. A tmux row's claim still needs `running: true` and no
3926
+ `runtimeState` but `running`. A row whose last read failed, or whose
3927
+ server was not reached, shows none, as for any row.
3928
+ - It counts as running (the Desktop's Home, the counts) on `running: true`
3929
+ alone: its `runtimeState` is the provider's word (`unknown` while it
3930
+ runs), never `running`.
3931
+ - A start's or a restart's answer for it carries the provider's name as
3932
+ `backend`, `session: {provider, endpoint?}` and no terminal `target`
3933
+ (the endpoint on a start on this machine, never on a routed one); the
3934
+ clients open no terminal after it.
3935
+ - Its stop and its retire run from the deployment's directory, never from
3936
+ its home. The retire of such a home is refused while any process works in
3937
+ it, the client's own included: start the Desktop or the TUI outside an
3938
+ agent's home.
3939
+ - The Desktop shows the backend and `session.threadId`, when it is text,
3940
+ as `bb · thread thr_…`. Only a status row of this machine carries the
3941
+ thread id: a row relayed from another host (`oats server roster`,
3942
+ `--server`) never does, so a client shows the backend alone there and
3943
+ depends on the id for nothing. The id addresses nothing.
3944
+
3945
+ A row with no `backend` (an older kernel's, or an older routed host's)
3946
+ reads as tmux, as one with `tmux` does: both are read as before. A row recorded
3947
+ on Herdr keeps its own reason (`E_HERDR_REMOVED`) before any of this. On a
3948
+ row of this machine `herdr` is not read as a backend: such a row is known
3949
+ by its `sessionTarget` or its `unsupported` state, and one that only names
3950
+ `herdr` reads as before. A
3951
+ `backend` that is no provider's name (1 to 40 lowercase letters, digits
3952
+ and dashes, the first a letter or a digit; not `tmux` or
3953
+ `session-provider`) still makes the row a provider's, never asked of tmux:
3954
+ the clients then say "Runs outside tmux; it has no terminal to open." and
3955
+ show the value only as display text. `--backend` on a
3956
+ client's spawn is held to the names the kernel lists: `sessionBackends` of
3957
+ `oats version --json` and the session providers `oats inspect --json`
3958
+ reports.
3757
3959
  - **`color`** (feature `instance-color`): the instance's colour, one of
3758
3960
  `sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
3759
3961
  from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
@@ -3768,15 +3970,31 @@ its absence.
3768
3970
  the home holds a valid pin ([Pinned instances](#pinned-instances-oats-instance-pin)),
3769
3971
  absent otherwise; never `false`. A `pinned` in `instance.json` never
3770
3972
  stands in for it. Clients list a pinned row first in its machine's list.
3771
- - <a id="row-same-work"></a>**`sameWork`** (feature `instance-same-work`):
3772
- `true` when the home's same-work flag
3773
- ([Same work as the parent](#same-work-as-the-parent-oats-instance-same-work))
3774
- is bound to the parent the row's `parentInstance` names. Otherwise the key
3775
- is absent, never `false` or `null`: no flag, a flag bound to an earlier
3776
- parent, no `parentInstance`, and a row whose `instance.json` cannot be read.
3777
- A `sameWork` in `instance.json` never stands in for it. Clients draw the
3778
- parent→child line for a row that carries it; a client that does not know
3779
- the key ignores it, and an older kernel never sends it.
3973
+ - <a id="row-board"></a>**`board`** (feature `instance-board`): the agent's
3974
+ board, `{facts: [{key, label, value, unit, link, at}], questions: [{id,
3975
+ question, options, hasContext, since}]}`, or `null` for a home with no board
3976
+ file (or one whose directory can't be read) ([The agent's board](#the-agents-board-oats-instance-board)). Facts come
3977
+ in the order first set, questions in the order asked, and only the questions
3978
+ of the instance's current session. A file that can't be read as a board is an
3979
+ empty board, never an error. The value is at most 8 KiB as UTF-8 JSON on every
3980
+ row. It carries no history and no context: `oats inspect --home <h> --board`
3981
+ does. A `board` in `instance.json` never stands in for it, and an older
3982
+ kernel's rows have no key.
3983
+ - <a id="row-related-work"></a><a id="row-same-work"></a>**`relatedWork`**
3984
+ (feature `instance-related-work`): `true` when the home's related-work
3985
+ flag ([Related work](#related-work-oats-instance-related-work)) is bound
3986
+ to the parent the row's `parentInstance` names, or, on a row with no
3987
+ `parentInstance`, to the sibling its `siblingInstance` names. Otherwise
3988
+ the key is absent, never `false` or `null`: no flag, a flag bound to an
3989
+ earlier relation, neither relation, and a row whose `instance.json`
3990
+ cannot be read. A `relatedWork` or `sameWork` in `instance.json` never
3991
+ stands in for it. **`sameWork`** (feature `instance-same-work`), the
3992
+ flag's old name, stands beside it as `true` when the binding is to the
3993
+ parent, for a client that reads the old key; it is absent for a sibling
3994
+ binding and whenever `relatedWork` is, never `false` or `null`.
3995
+ Clients draw the line between the row and the instance it is bound to; a
3996
+ client that does not know the key ignores it, and an older kernel never
3997
+ sends it.
3780
3998
  - <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
3781
3999
  0.59.0): `{state, since, self, code?, message?}` while a retire of the home
3782
4000
  is running, scheduled or owed; absent otherwise, and from older kernels.
@@ -4050,11 +4268,21 @@ route target:
4050
4268
  has exactly `pinned: true`; any other value (`"true"`, `1`), a host whose
4051
4269
  kernel predates the feature and a saved route the host did not list carry
4052
4270
  none ([`pinned`](#row-pinned)).
4053
- - **`sameWork`** (feature `instance-same-work`) is on a row only when the
4054
- host's row has `sameWork: true`, and is then `true`. Any other value, a host
4055
- whose kernel predates the feature, and a saved route the host did not list
4056
- carry no key ([`sameWork`](#row-same-work)). `oats status --server <id>
4057
- --json` relays the host's answer verbatim, `sameWork` included.
4271
+ - **`board`** (feature `instance-board`) is on a row only when the host's row
4272
+ has the key. It is read by this kernel's own rules: each fact and question
4273
+ within its bounds and the whole within 8 KiB, or else an empty board.
4274
+ `null` stays `null` ([`board`](#row-board)).
4275
+ - **`relatedWork`** (feature `instance-related-work`) is on a row only when
4276
+ the host's row has `relatedWork: true`, and is then `true`. From a host
4277
+ whose features list `instance-same-work` and not `instance-related-work`
4278
+ (an older OATS), its row's `sameWork: true` is relayed as `relatedWork:
4279
+ true`. Any other value, a host whose kernel predates both features, and a
4280
+ saved route the host did not list carry no key
4281
+ ([`relatedWork`](#row-related-work)). `sameWork: true` is relayed beside
4282
+ `relatedWork: true` when the host's row says it (a parent binding), and
4283
+ never on its own. `oats status --server <id> --json` relays the host's
4284
+ answer as it gave it, except for these two keys: each instance row carries
4285
+ them by the same rule (an older host's `sameWork: true` as both).
4058
4286
  - **`sessionEnd`** (feature `session-resume`; relayed from 0.69.5) is on a row only
4059
4287
  when the host's row has the key, with the host's value: a host whose kernel
4060
4288
  predates the feature, a row the host reports without it (one that runs,
@@ -4299,7 +4527,7 @@ instance's own machine: the local command, with `--server <id>` added.
4299
4527
  | `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
4300
4528
  | `oats instance background <name> on\|off --server <id>` | none | `instance-background` |
4301
4529
  | `oats instance pin <name> on\|off --server <id>` | none | `instance-pin` |
4302
- | `oats instance same-work <name> on\|off --server <id>` | none | `instance-same-work` |
4530
+ | `oats instance related-work <name> on\|off --server <id>` | none | `instance-related-work`; a host with only `instance-same-work` is asked by the old name for a parent binding ([Related work](#related-work-oats-instance-related-work)) |
4303
4531
 
4304
4532
  - The flags are the local command's. The instance is addressed like every
4305
4533
  routed instance command ([servers.md](servers.md#run-there)): `--home` as
@@ -4850,7 +5078,13 @@ oats instance attention [--message=<text>] [--clear] --json
4850
5078
 
4851
5079
  - **The row.** A claim is a `waiting` event, `data: {waitingOnYou: true,
4852
5080
  reason, message?}` or `{waitingOnYou: false}`, appended to both logs, with
4853
- `producer` the caller's `--producer`.
5081
+ `producer` the caller's `--producer`. The board's claim (producer
5082
+ `oats.board`, [The agent's board](#the-agents-board-oats-instance-board))
5083
+ also carries `session`, the id of the session it was set in. A row with a
5084
+ `session` counts only while that is still the current session, and only
5085
+ where the read proves it: a session boundary is in the rows read, or the
5086
+ log was read whole (not cut to its last 4 MiB). No verb sets one; a row
5087
+ without `session` counts as before.
4854
5088
  - **`waiting`.** `--producer` matches `^[a-z0-9][a-z0-9._/-]{0,63}$` and is
4855
5089
  not `kernel`. `set` needs `--reason`, one of `permission`, `question`,
4856
5090
  `attention` (closed). `clear` refuses `--reason` and `--message`. The home
@@ -5116,7 +5350,12 @@ oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>]
5116
5350
  `E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
5117
5351
  a home the kernel cannot look into, where whether it has a `work/` cannot
5118
5352
  be told; OATS 0.52.0).
5119
- - `midTask`: `true`, `false` or `"unknown"`.
5353
+ - `midTask`: `true`, `false` or `"unknown"`. A home on a
5354
+ [session provider](execution-targets.md#session-providers) whose session
5355
+ is there reads what its provider reports of it (the `running` of
5356
+ `oats session inspect`, see [Session providers](#session-providers-feature-session-providers)): `true` when it runs a turn,
5357
+ and `"unknown"` when the provider reports no activity (`running: null`),
5358
+ unless its work has changes, which is `true`.
5120
5359
  - `retiring` and `stopPending`, booleans on every target, say who holds the
5121
5360
  target's home when the plan is read (OATS 0.52.0, feature
5122
5361
  `lifecycle-claim-stop`). `retiring`: a self-retire is scheduled for it
@@ -6920,90 +7159,442 @@ when the host's row says exactly `true`), and on `oats inspect --home` as
6920
7159
  `instance.pinned`. Each is absent when not pinned. A client reads `pinned`
6921
7160
  only where the probe lists `instance-pin`.
6922
7161
 
6923
- ## Same work as the parent (`oats instance same-work`)
7162
+ ## The agent's board (`oats instance board`)
6924
7163
 
6925
- Feature `instance-same-work` (awebai/oats#1577).
7164
+ Feature `instance-board`, `boardApi: 1`.
6926
7165
 
6927
7166
  ```text
6928
- oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]
6929
- oats spawn <soul> … --same-work
7167
+ oats instance board set <key> --label <text> --value <text> [--unit <text>] [--link <https-url>] [--json]
7168
+ oats instance board unset <key> [--json]
7169
+ oats instance board ask <question> --option <text> --option <text> [--option <text>]… [--id <id>] [--context-file <f>] [--json]
7170
+ oats instance board ask --clear <id> [--json]
6930
7171
  ```
6931
7172
 
6932
- The flag records that an instance does the same work as its parent. Clients
6933
- draw the parent→child line for an instance that carries it. Nothing else in
6934
- the kernel reads it: it is not identity, it grants nothing and it never
6935
- addresses anything.
7173
+ The board is what an agent tells its person outside its terminal: the
7174
+ **facts** it keeps in view (the PR, the best score, the branch) and the
7175
+ **questions** it needs them to answer, each with 2 to 4 options. A client
7176
+ shows them in the agent's view, above and below the agent's own terminal.
7177
+ The agent reports them, and the kernel infers nothing: it never reads a
7178
+ transcript, and it routes no answer. The word "pin" is never used for facts:
7179
+ [`oats instance pin`](#pinned-instances-oats-instance-pin) pins an instance at
7180
+ the top of the list, which is something else.
7181
+
7182
+ - **Who writes it.** Only the agent, from its own session, as `oats instance
7183
+ attention` does: the home is `$OATS_INSTANCE_HOME`. `--home`, `--dir` and
7184
+ `--server` are refused (`E_BAD_ARGS`), and outside an instance home every
7185
+ form is `E_USAGE`.
7186
+ - **`set`** upserts the fact `<key>`. At most 12 keys: one more is
7187
+ `E_BOARD_FULL`. A set with every field the same changes nothing and writes
7188
+ nothing. The kernel keeps a key's last 20 values with their times (a new
7189
+ value joins it; a new label alone doesn't). `at` is when the fact last
7190
+ changed. **`unset`** removes the key and its history.
7191
+ - **`ask`** opens a question. Its id is `--id`, or `q<n>` by default. `n` is
7192
+ counted per home and never reused while the home lives, so a late answer
7193
+ can't land on a newer question (past `q999999999999999` no default id is
7194
+ left: `E_BOARD_FULL`, ask with `--id`). At most 9 open at once: one more is
7195
+ `E_BOARD_FULL`. Asking a question that is open with the same text, options
7196
+ and context again changes nothing and answers its id, with or without
7197
+ `--id`, so a retry is safe. Anything else under an open id is
7198
+ `E_BAD_ARGS`. **`ask --clear <id>`** closes the
7199
+ question, which the agent does once it has read the answer. Clearing an id
7200
+ that isn't open changes nothing.
7201
+ - **Text.** Key and id match `^[a-z0-9][a-z0-9-]{0,15}$`. Label, value,
7202
+ unit, option and question are one line each, of at most 40, 80, 16, 60
7203
+ and 200 code points, with none of the characters a
7204
+ [waiting message](#waiting-on-you) refuses. A link is an absolute `https:`
7205
+ URL of at most 512 printable ASCII characters. The context comes from a
7206
+ UTF-8 file (`--context-file`), at most 2000 code points once its trailing
7207
+ newlines are trimmed (a file's final newline, such as a heredoc's, isn't
7208
+ content). Newlines (LF) are allowed in it, and every other refused
7209
+ character is not. Anything else is `E_BAD_ARGS`.
7210
+ - **The row bound.** A write that would make the row's `board` larger than
7211
+ 8 KiB as UTF-8 JSON is `E_BOARD_FULL`, with `details.bytes` and
7212
+ `details.max`. Every client can rely on that bound for every row. A
7213
+ refused write writes nothing.
7214
+ - **Per session.** A question records the session it was asked in: the
7215
+ instance's latest kernel session boundary (`launched`, `restarted`,
7216
+ `stopped`: the [waiting claim's rule](#waiting-on-you)). It is live only
7217
+ while that is still the current session. Once a later boundary is written,
7218
+ no row shows it, and the next write drops it. Where the events log's bounded
7219
+ read (its last 4 MiB) holds no boundary, the current session can't be
7220
+ proved: no question is live, and `ask` is `E_BOARD_FAILED` until the next
7221
+ boundary. Facts persist across sessions until they are unset or the home is
7222
+ retired.
7223
+
7224
+ **The needs-input claim.** While any question is open, the home holds the
7225
+ [waiting claim](#waiting-on-you) of producer `oats.board`, reason
7226
+ `attention`. Its message is the oldest open question. The last `--clear`
7227
+ removes it. The claim's row records the session the write read
7228
+ (`session`), and counts only in that session, so a boundary written while a
7229
+ board write runs ends the claim with the question. Reason `attention` holds no scheduled wake
7230
+ ([A held wake](schedules.md#a-held-wake)): a board question leaves the
7231
+ harness at its normal input line. The claim is a producer of its own, so the
7232
+ agent's own `attention` claim can be live beside it, and `waitingOnYou`
7233
+ picks between them by its usual rule. Every board write sets the claim to
7234
+ what the questions say after it. A write whose claim fails is
7235
+ `E_EVENTS_FAILED` after the board was written, with `details.id` (or
7236
+ `details.key`) naming what was written. Running the same command again
7237
+ changes nothing on the board and repairs the claim.
7238
+
7239
+ **How a person answers.** The kernel routes no answer. A client types it as
7240
+ the person's own keystrokes, in the agent's terminal, as `<id>: <text>`
7241
+ (`q2: Yes, one clean commit`), and the person's Enter sends it. An agent reads
7242
+ an answer by its id, then clears the question.
7243
+
7244
+ **The answer** of every form is `{boardApi, instance, home, key | id,
7245
+ changed, board}`, where `board` is the row's value after the write
7246
+ (`null` when the home has no board file and nothing was written):
7247
+
7248
+ ```json
7249
+ {"boardApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","id":"q2","changed":true,
7250
+ "board":{"facts":[{"key":"pr","label":"Pull request","value":"#1990","unit":null,"link":"https://github.com/oats-project/oats/pull/1990","at":"2026-11-19T21:00:00.000Z"}],
7251
+ "questions":[{"id":"q2","question":"Squash before merging?","options":["Yes, one clean commit","No, keep the history"],"hasContext":true,"since":"2026-11-19T21:01:00.000Z"}]}}
7252
+ ```
6936
7253
 
6937
- - **The record** is `<home>/.oats-same-work.json`, `{"sameWorkApi": 1,
6938
- "parent": "<instance>", "at": "<ISO time>"}`, mode 0600, written
6939
- atomically. Present means on; `off` removes it. It is a kernel-owned home
6940
- file: a capability cannot declare it as its own, a retire does not count it
6941
- as work (on its own it never makes a recovery copy), and `oats instance
7254
+ The text answer is one line: `<instance>: fact <key> set` (or `unchanged`,
7255
+ `removed`, `was not set`), or `<instance>: question <id> asked: answers
7256
+ arrive typed as "<id>: <text>"` (or `cleared`, `was not open`).
7257
+
7258
+ | Code | When |
7259
+ |---|---|
7260
+ | `E_USAGE` | Not in an instance session: `$OATS_INSTANCE_HOME` unset, not absolute, or not an instance home under its agents root |
7261
+ | `E_BAD_ARGS` | `--home`, `--dir` or `--server`; a field out of its rules; fewer than 2 or more than 4 options; another question under an open id; a flag given twice (`--option` repeats); `--clear` beside anything else |
7262
+ | `E_BOARD_FULL` | A 13th fact, a 10th open question, a row over 8 KiB, or no default id left; nothing was changed |
7263
+ | `E_BOARD_FAILED` | `ask` where the current session can't be read from the events log (no boundary in its last 4 MiB); nothing was changed. Use `oats instance attention --message` |
7264
+ | `E_BOARD_BUSY` | Another process holds the board's lock past 5 seconds (`details.lock`); nothing was changed |
7265
+ | `E_EVENTS_FAILED` | The board was written (`details.id` or `details.key`), but its claim was not: run the same command again |
7266
+
7267
+ **Where it is read.** [`board` on status rows](#row-board), relayed on
7268
+ [remote roster rows](#the-remote-roster-oats-server-roster---json), and with
7269
+ history and context on `oats inspect --home <h> --board` as
7270
+ `instance.board`: each fact gains `history: [{value, at}]` (oldest first, its
7271
+ current value last) and each question `context` (the text, or `null`). Read
7272
+ it when a view is open, not on every poll. Agent text is untrusted: a client
7273
+ shows it as the agent's attributed words, plain text only, and opens a link
7274
+ only on the person's press, outside the app's window.
7275
+
7276
+ **Storage.** `<home>/.oats-board.json`, mode 0600, written atomically under
7277
+ the lock `<home>/.oats-board.lock`, so parallel writes of one agent lose
7278
+ none. The format is the kernel's own, not part of this contract. A reader
7279
+ takes a regular file of at most 256 KiB, without following a link. A file
7280
+ that isn't a valid board in every part reads as an empty board,
7281
+ `{facts: [], questions: []}`, never as an error. Both names are kernel-owned
7282
+ home files: a capability cannot declare them, and a retire counts neither as
7283
+ work. A start, restart or upgrade keeps them, and a retire removes them with
7284
+ the home.
7285
+
7286
+ ## Related work (`oats instance related-work`)
7287
+
7288
+ <a id="same-work-as-the-parent-oats-instance-same-work"></a>
7289
+ Feature `instance-related-work`. It renames `instance-same-work`
7290
+ (awebai/oats#1577), which the kernel still advertises beside it for the
7291
+ [deprecated aliases](#the-deprecated-aliases) and the old row field.
7292
+
7293
+ ```text
7294
+ oats instance related-work <instance> on|off [--home <abs>] [--dir <d>] [--json]
7295
+ oats spawn <soul> … --related-work
7296
+ ```
7297
+
7298
+ The flag records that an instance does related work with the instance it is
7299
+ bound to: its parent, or, when it has no parent, its sibling. Clients draw a
7300
+ line between the two for an instance that carries it. Nothing else in the
7301
+ kernel reads it: it is not identity, it grants nothing and it never
7302
+ addresses anything. The kernel never sets it on its own, for any relation:
7303
+ only `--related-work` and `on` do.
7304
+
7305
+ - **The binding.** The flag binds the home's recorded `parentInstance` when
7306
+ it has one, else its recorded `siblingInstance`. With neither, it cannot
7307
+ be set. A sibling binding names the sibling the home records. For a
7308
+ sibling of a top-level instance R, that is R. For a sibling of R's
7309
+ sibling S, the home records S, the anchor it was spawned beside, so the
7310
+ binding is to S, not R.
7311
+ - **The record** is `<home>/.oats-related-work.json`, either
7312
+ `{"relatedWorkApi": 1, "parent": "<instance>", "at": "<ISO time>"}` or
7313
+ `{"relatedWorkApi": 1, "sibling": "<instance>", "at": "<ISO time>"}`,
7314
+ exactly one of `parent` and `sibling`, mode 0600, written atomically.
7315
+ Present means on; `off` removes it. It is a kernel-owned home file: a
7316
+ capability cannot declare it as its own, a retire does not count it as
7317
+ work (on its own it never makes a recovery copy), and `oats instance
6942
7318
  upgrade` does not see it as a change to the home.
6943
7319
  - **A reader** takes a regular file only, without following a link, of at
6944
- most 4 KiB, holding JSON with `sameWorkApi: 1` and a non-empty string
6945
- `parent`. Anything else reads as off, never as an error.
6946
- - **Bound to the parent.** The flag is on only while the record's `parent` is
6947
- the home's current recorded `parentInstance`. A reparent leaves the record
6948
- naming the old parent, so the flag reads off: a retire's lineage relink
6949
- (the instances pointing at the retiree re-pointed to its parent) and a
6950
- `--relation parent` spawn re-pointing its anchor. `on` binds it to the
6951
- current parent again.
7320
+ most 4 KiB, holding JSON with `relatedWorkApi: 1` and exactly one of a
7321
+ non-empty string `parent` and `sibling`. Anything else reads as off, never
7322
+ as an error.
7323
+ - **Bound to the relation.** A parent binding is on only while its `parent`
7324
+ is the home's current recorded `parentInstance`. A sibling binding is on
7325
+ only while the home records no parent and its `sibling` is the current
7326
+ `siblingInstance`. A relink that changes the relation leaves the record
7327
+ naming the old instance, so the flag reads off: a retire's lineage relink
7328
+ (the instances pointing at the retiree re-pointed to its parent, or their
7329
+ sibling link moved to its sibling) and a `--relation parent` spawn
7330
+ re-pointing its anchor. `on` binds it to the current relation again.
6952
7331
  - **Lifetime.** It survives `oats session restart`, a stop and a start, a
6953
7332
  resume (`oats session start --resume`) and `oats instance upgrade`. Only
6954
7333
  `off` and retirement clear it.
7334
+ - **The old flag.** A same-work record, `<home>/.oats-same-work.json`
7335
+ (`{"sameWorkApi": 1, "parent": "<instance>", "at": "<ISO time>"}`), reads
7336
+ as a parent binding while nothing stands at the new record's name, by the
7337
+ same reader rules; so an instance flagged before the rename keeps its
7338
+ flag. When both exist, the new record wins, whatever it holds. The write
7339
+ that creates the new record removes the old one, and `off` removes both.
7340
+ `on` for a binding the old record already holds writes nothing. Both names
7341
+ are kernel-owned.
7342
+
7343
+ <a id="the-deprecated-aliases"></a>
7344
+ **The deprecated aliases.** `oats spawn … --same-work` is `--related-work`,
7345
+ and `oats instance same-work <instance> on|off` is `oats instance
7346
+ related-work`, with the same binding rule (the parent, else the sibling),
7347
+ the same refusals and the same answer; spawnInstance's `sameWork` option is
7348
+ `relatedWork`, and each call with it emits one Node `DeprecationWarning`
7349
+ (code `OATS_SAME_WORK`, `sameWork is renamed: use relatedWork`). Each CLI use prints one line on stderr, before the command runs
7350
+ or is sent with `--server`: `oats: --same-work is renamed: use
7351
+ --related-work`, or `oats: oats instance same-work is renamed: use oats
7352
+ instance related-work`. It is never in the `--json` answer: the envelope is
7353
+ the one the new spelling gives, with no `warnings`. The aliases, the
7354
+ feature `instance-same-work` and the [`sameWork`](#row-related-work) row
7355
+ field stay until their removal is decided on its own, with its own
7356
+ release-notes entry.
6955
7357
 
6956
7358
  **The verb.** The instance is addressed as `oats instance color` addresses
6957
7359
  it, and refused with the same answers.
6958
7360
 
6959
- - `on` binds the flag to the instance's recorded `parentInstance`; an
6960
- instance with none is refused. `on` again while the flag is bound to that
6961
- parent writes nothing; `on` after a reparent rebinds it to the current
6962
- parent.
6963
- - `off` removes whatever stands at the record's name (a file, a link, a
6964
- directory). It succeeds whether or not the flag was on and whether or not a
6965
- parent is recorded; `off` again is the same answer.
7361
+ - `on` binds the flag to the instance's recorded `parentInstance`, else to
7362
+ its recorded `siblingInstance`; an instance with neither is refused. `on`
7363
+ again while the flag holds that binding writes nothing; `on` after a
7364
+ relink rebinds it to the current relation.
7365
+ - `off` removes whatever stands at either record's name (a file, a link, a
7366
+ directory). It succeeds whether or not the flag was on and whether or not
7367
+ a relation is recorded; `off` again is the same answer.
6966
7368
 
6967
- The answer, the envelope's `result`, has exactly these two keys:
7369
+ The answer, the envelope's `result`, has exactly these three keys:
6968
7370
 
6969
7371
  ```json
6970
- {"instance":"dev-a","sameWork":true}
7372
+ {"instance":"dev-a","relatedWork":true,"sameWork":true}
6971
7373
  ```
6972
7374
 
6973
- `sameWork` is the binding rule read after the write: `true` after `on`,
6974
- `false` after `off`. The text answer is `dev-a: same work on` (or `off`).
7375
+ `relatedWork` is the binding rule read after the write: `true` after `on`,
7376
+ `false` after `off`. `sameWork` is the old verb's answer: `true` only when
7377
+ the flag holds a parent binding, so `false` for a sibling binding. The text
7378
+ answer is `dev-a: related work on` (or `off`).
6975
7379
 
6976
7380
  | Code | When |
6977
7381
  |---|---|
6978
- | `E_BAD_ARGS` | Neither `on` nor `off`, or more than one word; a `--home` that is not absolute; `on` for an instance with no recorded parent: `<instance> has no parent instance: same work is declared against a recorded parent; the flag was not changed` |
7382
+ | `E_BAD_ARGS` | Neither `on` nor `off`, or more than one word; a `--home` that is not absolute; `on` for an instance with neither a recorded parent nor a recorded sibling: `<instance> would record no parent or sibling instance: related work is declared against a recorded parent or sibling; the flag was not changed` |
6979
7383
  | *(as `oats instance color`)* | Instance resolution: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME` |
6980
7384
  | `E_INSTANCE_RETIRING` | A retire of the home is in flight (its pending marker, or a live retire holding the home's lifecycle claim, which the command reads and never takes), or the home is quarantined. Nothing was written |
6981
7385
  | `E_LIFECYCLE_BUSY` | The home's claim file cannot be read as a claim, or a retire's liveness cannot be read, as for `oats worktree add` |
6982
7386
 
6983
- **At spawn.** `oats spawn … --same-work` sets the flag on the new instance,
6984
- bound to the parent its home records, whichever relation gave it: `--parent
6985
- <instance>` or `--relation child`; `--relation sibling` of an anchor that has
6986
- a parent (the new instance shares it); `--relation parent` of an anchor that
6987
- had a parent (the new instance inherits it); `--work attached` (the owner of
6988
- the tree). The record is written inside the spawn, before the launch, so the
6989
- instance's first status row carries `sameWork: true`; a spawn rolled back
6990
- removes it with the home. When the new instance would record no parent (no
6991
- relation, `--relation unrelated`, a sibling of a root anchor, `--relation
6992
- parent` of a root anchor), the spawn is refused with `E_BAD_ARGS` before
6993
- anything is created, `--preview` included.
7387
+ **At spawn.** `oats spawn … --related-work` sets the flag on the new
7388
+ instance. It is bound to the parent the new home records, whichever
7389
+ relation gave it: `--parent <instance>` or `--relation child`; `--relation
7390
+ sibling` of an anchor that has a parent (the new instance shares it);
7391
+ `--relation parent` of an anchor that had a parent (the new instance
7392
+ inherits it); `--work attached` (the owner of the tree). Else it is bound to
7393
+ the sibling the new home records: `--relation sibling` of an anchor with no
7394
+ parent (the anchor itself), and `--relation parent` of an anchor with a
7395
+ sibling link and no parent (the new instance inherits the link). The record
7396
+ is written inside the spawn, before the launch, so the instance's first
7397
+ status row carries `relatedWork: true`; a spawn rolled back removes it with
7398
+ the home. When the new instance would record neither (no relation,
7399
+ `--relation unrelated`, `--relation parent` of a top-level anchor with no
7400
+ sibling link), the spawn is refused with `E_BAD_ARGS` before anything is
7401
+ created, `--preview` included: `--related-work needs a parent or a sibling:
7402
+ <instance> would record no parent or sibling instance …; nothing was
7403
+ spawned`.
6994
7404
 
6995
7405
  Routed with `--server <id>`, the verb runs on the host
6996
7406
  ([Routed reads and plans](#routed-reads-and-plans)) and `spawn --server …
6997
- --same-work` sends the flag there. A host whose probe does not advertise
6998
- `instance-same-work` is refused with `E_REMOTE_INCOMPATIBLE` for either, and
6999
- nothing is sent.
7000
-
7001
- Where it is read: `sameWork` on [status rows](#row-same-work) and on
7002
- [remote roster rows](#the-remote-roster-oats-server-roster---json) (only
7003
- `true` is relayed).
7407
+ --related-work` sends the flag there. A host that advertises
7408
+ `instance-related-work` is sent the new spellings, the aliases included. A
7409
+ host that advertises only `instance-same-work` (an older OATS), and only
7410
+ that host, is asked by the old spellings when the binding is a parent:
7411
+ `--same-work` and `oats instance same-work`, its answer's `sameWork`
7412
+ returned with `relatedWork` beside it. The binding
7413
+ is read from the spawn's arguments and the host's own roster (the anchor's
7414
+ row for `--relation sibling|parent`, the instance's row for `on`). A sibling
7415
+ binding is refused there with `E_REMOTE_INCOMPATIBLE`, naming the host and
7416
+ the feature it lacks, and nothing is sent; it is never dropped. A host that
7417
+ advertises neither feature is refused with `E_REMOTE_INCOMPATIBLE` for
7418
+ either, and nothing is sent.
7419
+
7420
+ Where it is read: `relatedWork` (and `sameWork` beside it for a parent
7421
+ binding) on [status rows](#row-related-work) and on [remote roster
7422
+ rows](#the-remote-roster-oats-server-roster---json) (only `true` is
7423
+ relayed).
7004
7424
 
7005
7425
  ## Sessions and launch configurations
7006
7426
 
7427
+ ### Session providers (feature `session-providers`)
7428
+
7429
+ A capability can supply a session backend beside the kernel's tmux
7430
+ ([execution-targets.md](execution-targets.md#session-providers); the
7431
+ capability's side is
7432
+ [capabilities.md](capabilities.md#session-providers-sessionproviders)). A
7433
+ home on one is a **provider home**. Everything below is added by the
7434
+ feature; a tmux home's answers are as they were, except its status row's
7435
+ `backend`.
7436
+
7437
+ **Reading the offer.** `oats inspect --soul <soul> --json` and `oats inspect
7438
+ --home <abs> --json` carry `sessionProviders: [{name, capability}]`, the
7439
+ backends `--backend` takes there beside `tmux`, sorted by name (`[]` when the
7440
+ soul has none; a malformed declaration is none). `oats capabilities show
7441
+ <name> --json` carries `sessionProviders` (the manifest's key, exactly as
7442
+ declared) and, only when there is one, `sessionProviderProblems: [{provider,
7443
+ pointer, message}]`.
7444
+
7445
+ **Spawn.** `oats spawn <soul> --backend <name>` (after `--preview`, as for
7446
+ tmux). A preview carries `backend: "<name>"`, `backendStatus: {name,
7447
+ installed: true, started: false}` and `executable: null`. A launched spawn's
7448
+ answer carries `backend: "<name>"`, `session: {provider, endpoint}`, `tmux:
7449
+ null`, `attach: null`, and its `launch.executable` is `null`. While the
7450
+ provider launches, the spawn holds the new home's lifecycle claim: a stop's
7451
+ apply, a start and a retire of it are refused as busy (`E_LIFECYCLE_BUSY`,
7452
+ `E_SESSION_START_BUSY`) until the launch is recorded or undone. Refusals,
7453
+ before anything is created (a preview answers them too):
7454
+
7455
+ | Code | `details` |
7456
+ |---|---|
7457
+ | `E_BACKEND_UNKNOWN` | `{backend, available}`: the names `--backend` takes for this instance, `tmux` first |
7458
+ | `E_BACKEND_AMBIGUOUS` | `{backend, capabilities}`; also from a start or a restart |
7459
+ | `E_BACKEND_HARNESS` | `{backend, capability, harness, harnesses}` |
7460
+ | `E_BACKEND_LAUNCH_ARG` | `{backend, launchConfig, field: "executable"}` |
7461
+ | `E_BACKEND_NOT_READY`, any other `E_BACKEND_*` | the provider's readiness, or its own refusal of the launch: `{backend, capability}`; the spawn is rolled back |
7462
+
7463
+ A launch that fails otherwise is `E_SESSION_START_FAILED`.
7464
+
7465
+ **A status row** (`oats status --json`) of a provider home:
7466
+
7467
+ ```json
7468
+ { "instance": "dev-a", "home": "/abs/home", "launched": true,
7469
+ "backend": "bb",
7470
+ "session": { "provider": "oats.bb", "threadId": "thr_1" },
7471
+ "tmux": null,
7472
+ "open": { "label": "Open in bb", "url": "https://…" },
7473
+ "running": true, "runtimeState": "unknown", "waitingOnYou": null }
7474
+ ```
7475
+
7476
+ - `backend` is the provider's name. A tmux home's row carries `backend:
7477
+ "tmux"`. **A row with no `backend` key reads as tmux**: it comes from a
7478
+ kernel or a routed host without the feature (or is a home whose record
7479
+ cannot be read), never from a provider home.
7480
+ - `session.provider` is the capability. **`session.threadId` is on a local
7481
+ row only**: the thread id of the provider's endpoint, when the endpoint
7482
+ names one, on the host where the home lives, so a tool there can match a
7483
+ session to its instance. It is replaced at a start and a restart, and a
7484
+ home OATS stopped keeps its last. **A relayed row never has it** (`oats
7485
+ server roster`, `oats status --server`): a relayed row's `session` is
7486
+ `{provider}`. A client must not depend on `threadId` beyond the local
7487
+ host.
7488
+ - **The endpoint is never on a row.** `session.endpoint` (the provider's own
7489
+ locator) is on `oats session inspect --home`, a launched spawn's answer
7490
+ and a start's answer, on the host where the home lives; the same answers
7491
+ through `--server` carry `session: {provider}`. Neither the endpoint nor
7492
+ `open` holds a token or a secret.
7493
+ - `tmux` is `null`; `open` is `{label, url}` or `null`: a link a viewer may
7494
+ open instead of a terminal. It is relayed.
7495
+ - `running` is `true`, `false`, or `null` where the provider cannot tell a
7496
+ live idle session from a settled one. `runtimeState` is always set:
7497
+ `unknown` (there), `shell`, `stopped` (OATS stopped it, it was never
7498
+ launched, or it is gone) or `unreachable`, with `runtimeError`, when the
7499
+ provider failed, was slow or answered outside its contract. An unreachable
7500
+ row is never read as stopped.
7501
+ - `sessionEnd` is `stopped` for a home an operator stopped, and `lost` for
7502
+ one stopped with the host or whose session is gone while OATS did not
7503
+ stop it: the sweep resumes a lost one. Absent otherwise.
7504
+ - `waitingOnYou` is the producers' claim, read while the session is there
7505
+ and not in error (`runtimeState: "unknown"`, `running` true or null).
7506
+
7507
+ **Inspect.** `oats session inspect --home <abs> --json` answers `{home,
7508
+ backend, present, state, running, waitingOnYou, wakeHold, session: {provider,
7509
+ endpoint}, open}`: no `paneId`, no `size`. `state` is `unknown`, `shell`,
7510
+ `stopped` or, before the first launch, `not-launched`. For a home OATS
7511
+ stopped it answers `present: false, state: "stopped", running: false, open:
7512
+ null` without asking the provider. A provider that cannot be asked is
7513
+ `E_SESSION_UNAVAILABLE`.
7514
+
7515
+ **Input.** `oats session input --home <abs>` answers `{home, backend,
7516
+ submitted: true, verified}` (no `session`: the endpoint is inspect's, a
7517
+ spawn's and a start's). `E_SESSION_NOT_RUNNING` for a home OATS
7518
+ stopped (nothing was sent, the provider was not called), and for a lost
7519
+ session at its resume cap or with a process of its last run still in the
7520
+ home; `E_SESSION_PROMPT_OPEN` and `E_SESSION_INPUT_QUEUED` from the provider
7521
+ (nothing was sent); `E_SESSION_INPUT_FAILED` for anything else. A stop or a
7522
+ restart that lands while an input is being sent wins, whatever the provider
7523
+ answered to it: `E_SESSION_NOT_RUNNING`, the input not delivered. A delivery
7524
+ is accepted only on `ok: true` with `submitted: true`.
7525
+
7526
+ **Start and restart.** The result has every key a tmux start answers, with
7527
+ `backend: "<name>"`, `session: {provider, endpoint}` and `target: null`:
7528
+ `{instance, agent, home, harness, backend, model, launchConfig, yolo, target,
7529
+ session, startedAt, restartCount, reused: "new", warnings}`, and `stop:
7530
+ {stopped: true, waitedMs}` on a restart. A start of a home whose session is
7531
+ there and that OATS did not stop is `E_SESSION_RUNNING` (it reads `running:
7532
+ true`) or `E_SESSION_UNKNOWN`. `--resume` answers the same keys with `reused:
7533
+ "session"`, `startedAt: null` and `resume: {resumed: true, harness}`: the
7534
+ resume notice went through the provider's input and nothing was launched.
7535
+ Its refusals: `E_RESUME_NOT_LOST` (not a lost session), `E_SESSION_NOT_RUNNING`
7536
+ (the resume cap; `details.resumeCap: {limit, windowMs, nextAttemptAt}`),
7537
+ `E_SESSION_UNKNOWN` (a process of the last run still works in the home, or
7538
+ the session cannot be read), `E_SESSION_PROMPT_OPEN` (a claim or a prompt is
7539
+ open) and `E_SESSION_INPUT_QUEUED`.
7540
+
7541
+ **A launch with no recorded outcome** (the lifecycle's
7542
+ [design record](design/2026-11-20-provider-home-lifecycle.md)). From the
7543
+ moment a spawn or a start sends the provider's launch until its endpoint is
7544
+ recorded, and for good when that command died first, the home's receipt
7545
+ carries `launchSent` and the home is unknown, whether it was launched before
7546
+ or not: `oats session inspect` answers `E_SESSION_UNAVAILABLE`, its status
7547
+ row reads `running: null`, `runtimeState: "unreachable"` with the reason, a
7548
+ `--resume` is `E_SESSION_UNKNOWN`, and `oats session input` is refused with
7549
+ nothing sent (`E_SESSION_NOT_RUNNING` for a home never launched or recorded
7550
+ as stopped, else `E_SESSION_INPUT_FAILED`). A stop, a start, a restart and a
7551
+ retire settle it first, by asking the provider to stop whatever session that
7552
+ launch started: a stop then answers `stopped: true` (never `alreadyIdle`),
7553
+ or `E_SESSION_STOP_FAILED` when the provider does not confirm; a home
7554
+ launched before is left stopped. The row of a never-launched home reads
7555
+ `launched: true` meanwhile.
7556
+
7557
+ **Stop and retire.** The stop's row is `{ok: true, stopped, alreadyIdle,
7558
+ state: "stopped"}`; `E_SESSION_STOP_FAILED` when the provider does not confirm
7559
+ (the home stays recorded as stopped; a second stop asks the provider again). A retire goes on
7560
+ only when no process works in the home after the provider's stop, confirmed
7561
+ or not: otherwise `E_RUNTIME_QUIESCE_FAILED`, naming the processes. When the
7562
+ provider could not confirm the stop, the retire's answer carries a warning.
7563
+
7564
+ **Attach.** `E_SESSION_NO_TERMINAL`, `details: {backend, open}`; its message
7565
+ carries the `open` link when there is one. A client shows that link instead
7566
+ of a terminal.
7567
+
7568
+ **The authority check.** `E_RUNTIME_AUTHORITY_MISMATCH`'s `details.fields`
7569
+ for a provider home are `backend`, `session.provider` and `session.endpoint`
7570
+ (after `launched`).
7571
+
7572
+ **Readiness.** `oats readiness` carries a provider's own readiness, where it
7573
+ declares one, as a `providers` item: `subject: "<capability> session backend
7574
+ <name>"`, `producer: "session provider check"`, `result: {status, problems,
7575
+ warnings}` relayed as given, or `result: null` with `problems` when the
7576
+ provider could not be asked. Required for a home on that backend; not
7577
+ required for a soul.
7578
+
7579
+ **The sweep.** A row of `oats session resume` for a provider home carries
7580
+ `backend`. Its outcomes: `resumed` (a lost session: the notice was sent),
7581
+ `already-running` (a session is there), `refused` with `keeps-getting-lost`
7582
+ (the home's resume cap; `code: "E_SESSION_NOT_RUNNING"`, with
7583
+ `nextAttemptAt`; a `--plan` reads the same count and answers the same) or `start-refused`
7584
+ (the notice was not sent: a prompt or a claim is open, or it was queued),
7585
+ `skipped` with `unknown` (not readable, or a process of the last run still
7586
+ works in the home). A home an operator stopped has no row. `--plan
7587
+ --without-provider-inspect` asks no session provider: every provider home
7588
+ OATS has not stopped is then `skipped`, `unknown`, with its `backend`
7589
+ (`E_BAD_ARGS` without `--plan`). The switch is `oats host run`'s own: it
7590
+ lists with it at shutdown, so that a provider going down with the host cannot
7591
+ hold the listing up. A client has no use for it.
7592
+
7593
+ **Launch preview.** `oats launch-config preview --home <abs> --json` of a
7594
+ provider home answers `command: null`, `argv: null` and `executable.path:
7595
+ null` (its launch is handed to the provider as data), `environment` by name,
7596
+ and a `backend` item in `preflight`.
7597
+
7007
7598
  ### Input
7008
7599
 
7009
7600
  ```text
@@ -7012,7 +7603,8 @@ oats session input --home <abs> [--text-file <path>] --json
7012
7603
 
7013
7604
  Input bytes come from stdin or the named file. The existing version-1 success
7014
7605
  answer is `{schemaVersion: 1, ok: true, result: {home, backend: "tmux",
7015
- present: true, state, paneId, submitted: true, verified}}`. Session input runs
7606
+ present: true, state, paneId, submitted: true, verified}}` (a provider home's
7607
+ is under [Session providers](#session-providers-feature-session-providers)). Session input runs
7016
7608
  on the execution host, including when the wake broker invokes it there;
7017
7609
  `--server` is not supported for input. The adapter sends one literal
7018
7610
  bracketed paste and one Enter after the existing input/authority/target checks.
@@ -7051,7 +7643,7 @@ harness receipt. See [execution targets](execution-targets.md).
7051
7643
  oats session start --home <abs> [--launch-config <name>|none] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--server <id>] --json
7052
7644
  oats session start --resume --home <abs> --json
7053
7645
  oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --json
7054
- oats session resume [--deployment <dir>] [--plan] --json
7646
+ oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] --json
7055
7647
  ```
7056
7648
 
7057
7649
  Features `session-start`, `session-restart`, and `launch-config` for the
@@ -7219,7 +7811,7 @@ answer is the ordinary start answer plus one object:
7219
7811
 
7220
7812
  ### The machine sweep (`oats session resume`)
7221
7813
 
7222
- `oats session resume [--deployment <dir>] [--plan] --json` (feature
7814
+ `oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] --json` (feature
7223
7815
  `session-resume`, OATS 0.69) starts with `--resume` every home of this
7224
7816
  machine's deployments whose session was lost. A client runs it once when it
7225
7817
  opens. It reads this computer's list of deployments without writing it