@awebai/oats 0.69.22 → 0.69.23

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 (54) hide show
  1. package/bin/oats.mjs +131 -23
  2. package/docs/capabilities.md +12 -2
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +206 -228
  5. package/docs/design/2026-11-19-sandboxes.md +878 -0
  6. package/docs/design/README.md +3 -0
  7. package/docs/desktop-cli-api.md +416 -72
  8. package/docs/desktop.md +60 -17
  9. package/docs/implementation.md +1 -1
  10. package/docs/integrations.md +3 -3
  11. package/docs/knowledge-capability-authoring.md +10 -7
  12. package/docs/knowledge-reference/acceptance.md +21 -19
  13. package/docs/knowledge-reference/adoption.md +18 -4
  14. package/docs/knowledge-reference/model.md +11 -9
  15. package/docs/knowledge-reference/package-craft.md +2 -2
  16. package/docs/knowledge-reference/proposal.md +117 -0
  17. package/docs/knowledge-reference/provider-mapping.md +10 -10
  18. package/docs/knowledge-reference/reader-capture.md +26 -22
  19. package/docs/knowledge-theory.md +1 -1
  20. package/docs/knowledge.md +5 -5
  21. package/docs/official-catalog.md +4 -4
  22. package/docs/packages.md +13 -13
  23. package/docs/release-notes/v0.69.23.md +231 -0
  24. package/docs/servers.md +10 -6
  25. package/docs/souls-and-instances.md +51 -22
  26. package/docs/tui.md +4 -3
  27. package/docs/upgrading.md +12 -5
  28. package/docs/workspaces.md +2 -2
  29. package/lib/argv.mjs +6 -2
  30. package/lib/capability-contract.mjs +2 -2
  31. package/lib/command-flags.mjs +39 -2
  32. package/lib/core.mjs +25 -14
  33. package/lib/instance-board.mjs +337 -0
  34. package/lib/instance-events.mjs +48 -10
  35. package/lib/instance-lifecycle.mjs +19 -15
  36. package/lib/instance-listing.mjs +18 -10
  37. package/lib/instance-related-work.mjs +143 -0
  38. package/lib/kernel-features.mjs +4 -1
  39. package/lib/servers.mjs +123 -13
  40. package/package-catalog.json +3 -3
  41. package/package.json +1 -1
  42. package/packages/client/deployment-data.mjs +4 -2
  43. package/packages/client/deployment-panel.mjs +2 -1
  44. package/packages/client/instance-tree.mjs +34 -4
  45. package/packages/client/keymap.mjs +5 -0
  46. package/packages/client/mail-contract.mjs +130 -0
  47. package/packages/client/panel-views.mjs +7 -7
  48. package/packages/client/related-work.mjs +84 -0
  49. package/packages/client/remote-roster.mjs +4 -3
  50. package/packages/client/workspace-cli.mjs +13 -2
  51. package/skills/oats-getting-started/SKILL.md +11 -8
  52. package/docs/knowledge-reference/harvester.md +0 -109
  53. package/lib/instance-same-work.mjs +0 -67
  54. package/packages/client/same-work.mjs +0 -49
@@ -91,6 +91,9 @@ see the [official catalog](official-catalog.md) for current pins.
91
91
  --stdio`, which the reader's hello repeats. Start a reader only where the
92
92
  probe lists both the feature and `readerApi: 1`
93
93
  ([The warm reader](#the-warm-reader)).
94
+ - `boardApi` (feature `instance-board`) is the version of the agent's board:
95
+ the `board` on the rows, `inspect --board` and the board commands' answers
96
+ ([The agent's board](#the-agents-board-oats-instance-board)).
94
97
  - In text mode the command prints `@awebai/oats <version> (desktop API v1)`.
95
98
 
96
99
  ### Features
@@ -167,7 +170,8 @@ see the [official catalog](official-catalog.md) for current pins.
167
170
  | `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
171
  | `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
172
  | `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`) | |
173
+ | `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`) | |
174
+ | <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
175
  | `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
176
  | `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
177
  | `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,6 +187,7 @@ see the [official catalog](official-catalog.md) for current pins.
183
187
  | `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
188
  | `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
189
  | `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 | |
190
+ | `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
191
  | `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)) |
187
192
 
188
193
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
@@ -322,17 +327,21 @@ for `--no-recursive`) is never ignored.
322
327
  | Command | Arguments | Flags that take a value | Switches | Refused in their own words | Its own answers |
323
328
  |---|---|---|---|---|---|
324
329
  | `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 |
330
+ | `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
331
  | `oats sync` | none | `--dir` | `--plan`, `--json` | `--approve` | none |
327
332
  | `oats instance stop` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--grace-ms`, `--home`, `--dir`, `--server` | `--plan`, `--apply`, `--no-recursive`, `--json` | none | none |
328
333
  | `oats instance upgrade` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir` | `--undo`, `--plan`, `--json` | `--server` | none |
329
334
  | `oats instance color` | `<instance>` `[<color>]` | `--home`, `--dir`, `--server` | `--clear`, `--json` | none | none |
330
335
  | `oats instance background` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
331
336
  | `oats instance pin` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
337
+ | `oats instance related-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
332
338
  | `oats instance same-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
333
339
  | `oats instance waiting set` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
334
340
  | `oats instance waiting clear` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
335
341
  | `oats instance attention` | none | `--message` | `--clear`, `--json` | `--home`, `--dir`, `--producer`, `--reason` | none |
342
+ | `oats instance board set` | `<key>` | `--label`, `--value`, `--unit`, `--link` | `--json` | `--home`, `--dir`, `--server` | none |
343
+ | `oats instance board unset` | `<key>` | none | `--json` | `--home`, `--dir`, `--server` | none |
344
+ | `oats instance board ask` | `[<question>]` | `--option`, `--id`, `--context-file`, `--clear` | `--json` | `--home`, `--dir`, `--server` | none |
336
345
  | `oats instance suggest-name` | none | `--soul`, `--task`, `--task-file`, `--harness`, `--model`, `--launch-config`, `--dir` | `--json` | `--server` | none |
337
346
  | `oats worktree add` | none | `--purpose`, `--branch`, `--base`, `--repo` | `--preview`, `--json` | `--server`, `--dir`, `--home` | none |
338
347
  | `oats worktree remove` | none | `--purpose` | `--json` | `--server`, `--dir`, `--home` | none |
@@ -631,7 +640,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
631
640
  ### `oats inspect`
632
641
 
633
642
  ```text
634
- oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
643
+ oats inspect (--home <abs> [--board] | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
635
644
  ```
636
645
 
637
646
  An instance subject, abridged:
@@ -673,7 +682,7 @@ An instance subject, abridged:
673
682
  | `capabilities`, `capabilitiesOff` | the resolved modules (by id) and the ones the soul turned off |
674
683
  | `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
675
684
  | `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)) |
685
+ | `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
686
  | `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
687
  | `problems` | below |
679
688
  | `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
@@ -1001,6 +1010,15 @@ oats operation run <layer>:<name> (--home <abs> | --soul <name> [--dir <d>]) [--
1001
1010
  at the top level; `stderr` appears when the provider wrote any.
1002
1011
  - A `view` operation must answer `{documents: [{label, kind?, path?, text?}]}`
1003
1012
  (`kind` `markdown` or `text`), else `E_OPERATION_RESULT`.
1013
+ - **A view may carry one structured field** beside `documents`, named after
1014
+ its operation and versioned by its own `<name>Api` inside it: `mail` with
1015
+ `mailApi` for `messaging:mail` ([Mail](#mail-mailapi-1)). `documents` stays
1016
+ the plain rendering every view reader can show. The kernel validates
1017
+ `documents` only, and relays the provider's `result` unchanged, locally and
1018
+ through `--server`, where the routing keys (`server`, `route`) sit beside
1019
+ `result`, never inside it. A client reads the structured field only at a
1020
+ `<name>Api` it knows, and falls back to `documents` otherwise. A view carries
1021
+ at most one such field.
1004
1022
  - Errors: `E_OPERATION_UNKNOWN`, `E_OPERATION_UNAVAILABLE` (empty slot, or a
1005
1023
  home operation without `--home`), `E_CAPABILITY_REQUIRES`, `E_BAD_ARGS`
1006
1024
  (undeclared or missing `--arg`), `E_CAPABILITY_BROKEN`. A provider's `ok:
@@ -1019,6 +1037,119 @@ advertises `operations`.
1019
1037
  inspect; the provider's version owns their result shapes. For oats.okf, see
1020
1038
  [knowledge.md](knowledge.md#knowledge-operations).
1021
1039
 
1040
+ **Messaging operations.** The messaging provider's operations are listed by
1041
+ inspect too. One of them is a contract of the messaging layer, whatever the
1042
+ provider: `messaging:mail`, below. oats.aweb is its first provider, from the
1043
+ release that adds it (its `docs/mail-read.md` says how it reads).
1044
+
1045
+ <a id="mail-mailapi-1"></a>
1046
+ #### Mail, `mailApi: 1`
1047
+
1048
+ `messaging:mail` is a read-only view of an instance's own mail, received and
1049
+ sent, newest first. It **never acknowledges** or marks anything read on the
1050
+ agent's behalf. Any messaging provider may answer it.
1051
+
1052
+ ```text
1053
+ oats operation run messaging:mail --home <abs> [--arg limit=50] [--arg cursor=<nextCursor>] [--arg conversation=<id>] [--server <id>] --json
1054
+ ```
1055
+
1056
+ The provider's manifest declares it as a home view operation with three
1057
+ optional args:
1058
+
1059
+ ```json
1060
+ "mail": {"kind": "view", "command": "mail", "context": "home",
1061
+ "description": "Read-only: this instance's mail, received and sent, newest first. Never acknowledges.",
1062
+ "args": [{"name": "limit", "flag": "--limit"}, {"name": "cursor", "flag": "--cursor"}, {"name": "conversation", "flag": "--conversation"}]}
1063
+ ```
1064
+
1065
+ Its `result`:
1066
+
1067
+ ```json
1068
+ {"documents":[{"label":"Mail","kind":"markdown","text":"…plain rendering…"}],
1069
+ "mail":{"mailApi":1,"acknowledges":false,"observedAt":"2026-11-19T12:00:00.000Z",
1070
+ "identities":[{"team":"oats","alias":"dev-1","identity":"<opaque>","primary":true,"error":null},
1071
+ {"team":"alpha","alias":"dev-1","identity":"<opaque>","primary":false,"error":"conversation-unreadable",
1072
+ "unreadableConversations":["<opaque>"]}],
1073
+ "messages":[{"id":"<opaque>","conversationId":"<opaque>","threadTitle":"Review","direction":"received","team":"oats",
1074
+ "from":{"alias":"lead","address":"oats.aweb.ai/lead","identity":"<opaque>"},
1075
+ "to":{"alias":"dev-1","address":"oats.aweb.ai/dev-1","identity":"<opaque>"},
1076
+ "subject":"Review","body":"…","truncated":false,"createdAt":"2026-11-19T11:58:00Z",
1077
+ "readByAgent":false,"encrypted":false,"verification":"verified","priority":"normal"}],
1078
+ "conversations":[{"id":"<opaque>","partial":null}],
1079
+ "hasMore":false,"nextCursor":null}}
1080
+ ```
1081
+
1082
+ - **Opaque values.** `identity` ids, message and conversation ids, `team`
1083
+ labels and `nextCursor` are the provider's strings: a client compares them
1084
+ and passes them back, and never parses them. `from`/`to` `address` may be
1085
+ `null`; `conversationId` is `null` for mail with no conversation.
1086
+ - **Order.** Newest first by `createdAt`, across every identity of the
1087
+ instance (its primary one and each joined team's), merged, each message
1088
+ labelled by the `team` it was read in. `direction` is decided by the
1089
+ sender's identity against the identity read. `identities` lists each
1090
+ identity read, the primary one first.
1091
+ - **Read state.** `readByAgent` reports the server's read state of a received
1092
+ message, and is `true` for a sent one. The read never changes it, and
1093
+ `acknowledges` is always `false`.
1094
+ - **Closed sets.** `direction`: `received` or `sent`. `verification`:
1095
+ `verified`, `unverified`, `failed` or `unknown`. `priority`: `normal`,
1096
+ `high` or `unknown`. `partial`: `null` or `oldest-first-only`. A client
1097
+ shows any other value as unknown.
1098
+ - **Bounds.** Each `body` is at most 16 KiB of UTF-8, cut at a character
1099
+ boundary, with `truncated: true`. The whole `result` is at most 256 KiB;
1100
+ past it the answer stops early, with `hasMore: true` and a `nextCursor`.
1101
+ Where one message alone wouldn't fit, its `subject` and `threadTitle` are
1102
+ cut too, and `truncated: true` marks that as well: `truncated` means the
1103
+ provider shortened the message, whichever of its texts it cut. An answer
1104
+ is never sent oversized, nor as an empty page with `hasMore: true` and no
1105
+ `nextCursor`. `limit` is 1 to 200, default 50 (`E_BAD_ARGS` otherwise).
1106
+ - **Paging.** `nextCursor`, passed back as `--arg cursor=…`, gives the next
1107
+ messages in the same order, with no overlap. What a cursor encodes is the
1108
+ provider's (oats.aweb's: the last message's `createdAt`, id and team). `--arg conversation=<id>`
1109
+ reads one conversation, newest first; its cursor is valid only with the same
1110
+ conversation.
1111
+ - **Partial conversations.** Where the provider can read only the oldest part
1112
+ of a long conversation, the conversation is listed in `conversations` with
1113
+ `partial: "oldest-first-only"`, and its newest messages are missing, never
1114
+ shown as the latest. A client says "older part of a long conversation
1115
+ shown; the newest messages can't be read yet".
1116
+ - **Untrusted text.** `subject`, `threadTitle` and `body` are the sender's
1117
+ plain text: show them as text, attributed to their sender, never as markup.
1118
+ - **Encrypted mail.** End-to-end encrypted bodies are decrypted with the
1119
+ agent's keys, and shown to whoever can run `oats operation run` on that
1120
+ machine (routed reads included): the access that attaching to the agent's
1121
+ terminal already gives, no wider. `encrypted: true` marks them.
1122
+ - **Errors per identity.** In `identities[].error`, a provider's code (such
1123
+ as a grant without mail read). **An identity's `error` doesn't mean it has
1124
+ no messages:** it can come with that identity's messages beside it, and a
1125
+ reader shows both the mail and that some of it couldn't be read. One code
1126
+ is the layer's: `conversation-unreadable`, one or more of that identity's
1127
+ conversations couldn't be read; its other messages are shown, and the row
1128
+ names the missing ones in `unreadableConversations` (conversation ids,
1129
+ present only with that code, the list's tail dropped first if the 256 KiB
1130
+ bound needs it, so it may name fewer than failed, or none).
1131
+ - **Whole failures.** The operation fails whole, with no answer, in two
1132
+ cases: `E_MAIL_UNREADABLE` when no identity can be read
1133
+ (`details.identities` holds the rows), and `E_MAIL_TOO_LARGE` when even an
1134
+ answer with no messages can't fit the 256 KiB bound (its identities alone).
1135
+ - **Cost.** Each read calls the messaging service several times. Read on
1136
+ demand (opening a view, a manual refresh), never on a status poll.
1137
+ - **Older sides.** A home whose provider copy predates the operation answers
1138
+ `E_OPERATION_UNKNOWN` (inspect doesn't list `mail`): the home gets it from
1139
+ `oats instance upgrade` or a new spawn. A home with no messaging slot
1140
+ answers `E_OPERATION_UNAVAILABLE`, and a remote host without `operations`
1141
+ `E_REMOTE_INCOMPATIBLE`. A provider's own refusals are relayed with their
1142
+ code, such as oats.aweb's `E_AW_TOO_OLD` (`details: {version, needs}`) for
1143
+ an aw too old to read mail without acknowledging it.
1144
+ - **The provider's own.** How a provider maps its service's values onto the
1145
+ closed sets, its other identity error codes, what its cursor encodes and how
1146
+ much of a body its `documents` rendering shows are its own, in its docs. For
1147
+ oats.aweb: the "messaging:mail" section of its
1148
+ [README](https://github.com/awebai/oats-aweb/blob/main/README.md#messagingmail-an-instances-mail-read-without-acknowledging-it)
1149
+ and its [docs/mail-read.md](https://github.com/awebai/oats-aweb/blob/main/docs/mail-read.md)
1150
+ (the aw commands it runs, the verification and priority mappings, the
1151
+ cursor, every error code, a 500-character body excerpt in `documents`).
1152
+
1022
1153
  <a id="workspace-model-workspaceapi-2"></a>
1023
1154
  ## Workspace
1024
1155
 
@@ -3336,7 +3467,7 @@ kernel stage raised as well.
3336
3467
 
3337
3468
  | Code | Details | When |
3338
3469
  |---|---|---|
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)) |
3470
+ | `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
3471
  | `E_LOCAL_MISSING`, `E_NO_DEPLOYMENT` | | no `oats-local.yaml`; no `agents/` root |
3341
3472
  | `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
3473
  | `E_SOUL_AMBIGUOUS` | `{name, repos, qualified}` | several souls answer the bare name; use one of `qualified` |
@@ -3768,15 +3899,31 @@ its absence.
3768
3899
  the home holds a valid pin ([Pinned instances](#pinned-instances-oats-instance-pin)),
3769
3900
  absent otherwise; never `false`. A `pinned` in `instance.json` never
3770
3901
  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.
3902
+ - <a id="row-board"></a>**`board`** (feature `instance-board`): the agent's
3903
+ board, `{facts: [{key, label, value, unit, link, at}], questions: [{id,
3904
+ question, options, hasContext, since}]}`, or `null` for a home with no board
3905
+ file (or one whose directory can't be read) ([The agent's board](#the-agents-board-oats-instance-board)). Facts come
3906
+ in the order first set, questions in the order asked, and only the questions
3907
+ of the instance's current session. A file that can't be read as a board is an
3908
+ empty board, never an error. The value is at most 8 KiB as UTF-8 JSON on every
3909
+ row. It carries no history and no context: `oats inspect --home <h> --board`
3910
+ does. A `board` in `instance.json` never stands in for it, and an older
3911
+ kernel's rows have no key.
3912
+ - <a id="row-related-work"></a><a id="row-same-work"></a>**`relatedWork`**
3913
+ (feature `instance-related-work`): `true` when the home's related-work
3914
+ flag ([Related work](#related-work-oats-instance-related-work)) is bound
3915
+ to the parent the row's `parentInstance` names, or, on a row with no
3916
+ `parentInstance`, to the sibling its `siblingInstance` names. Otherwise
3917
+ the key is absent, never `false` or `null`: no flag, a flag bound to an
3918
+ earlier relation, neither relation, and a row whose `instance.json`
3919
+ cannot be read. A `relatedWork` or `sameWork` in `instance.json` never
3920
+ stands in for it. **`sameWork`** (feature `instance-same-work`), the
3921
+ flag's old name, stands beside it as `true` when the binding is to the
3922
+ parent, for a client that reads the old key; it is absent for a sibling
3923
+ binding and whenever `relatedWork` is, never `false` or `null`.
3924
+ Clients draw the line between the row and the instance it is bound to; a
3925
+ client that does not know the key ignores it, and an older kernel never
3926
+ sends it.
3780
3927
  - <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
3781
3928
  0.59.0): `{state, since, self, code?, message?}` while a retire of the home
3782
3929
  is running, scheduled or owed; absent otherwise, and from older kernels.
@@ -4050,11 +4197,21 @@ route target:
4050
4197
  has exactly `pinned: true`; any other value (`"true"`, `1`), a host whose
4051
4198
  kernel predates the feature and a saved route the host did not list carry
4052
4199
  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.
4200
+ - **`board`** (feature `instance-board`) is on a row only when the host's row
4201
+ has the key. It is read by this kernel's own rules: each fact and question
4202
+ within its bounds and the whole within 8 KiB, or else an empty board.
4203
+ `null` stays `null` ([`board`](#row-board)).
4204
+ - **`relatedWork`** (feature `instance-related-work`) is on a row only when
4205
+ the host's row has `relatedWork: true`, and is then `true`. From a host
4206
+ whose features list `instance-same-work` and not `instance-related-work`
4207
+ (an older OATS), its row's `sameWork: true` is relayed as `relatedWork:
4208
+ true`. Any other value, a host whose kernel predates both features, and a
4209
+ saved route the host did not list carry no key
4210
+ ([`relatedWork`](#row-related-work)). `sameWork: true` is relayed beside
4211
+ `relatedWork: true` when the host's row says it (a parent binding), and
4212
+ never on its own. `oats status --server <id> --json` relays the host's
4213
+ answer as it gave it, except for these two keys: each instance row carries
4214
+ them by the same rule (an older host's `sameWork: true` as both).
4058
4215
  - **`sessionEnd`** (feature `session-resume`; relayed from 0.69.5) is on a row only
4059
4216
  when the host's row has the key, with the host's value: a host whose kernel
4060
4217
  predates the feature, a row the host reports without it (one that runs,
@@ -4299,7 +4456,7 @@ instance's own machine: the local command, with `--server <id>` added.
4299
4456
  | `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
4300
4457
  | `oats instance background <name> on\|off --server <id>` | none | `instance-background` |
4301
4458
  | `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` |
4459
+ | `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
4460
 
4304
4461
  - The flags are the local command's. The instance is addressed like every
4305
4462
  routed instance command ([servers.md](servers.md#run-there)): `--home` as
@@ -4850,7 +5007,13 @@ oats instance attention [--message=<text>] [--clear] --json
4850
5007
 
4851
5008
  - **The row.** A claim is a `waiting` event, `data: {waitingOnYou: true,
4852
5009
  reason, message?}` or `{waitingOnYou: false}`, appended to both logs, with
4853
- `producer` the caller's `--producer`.
5010
+ `producer` the caller's `--producer`. The board's claim (producer
5011
+ `oats.board`, [The agent's board](#the-agents-board-oats-instance-board))
5012
+ also carries `session`, the id of the session it was set in. A row with a
5013
+ `session` counts only while that is still the current session, and only
5014
+ where the read proves it: a session boundary is in the rows read, or the
5015
+ log was read whole (not cut to its last 4 MiB). No verb sets one; a row
5016
+ without `session` counts as before.
4854
5017
  - **`waiting`.** `--producer` matches `^[a-z0-9][a-z0-9._/-]{0,63}$` and is
4855
5018
  not `kernel`. `set` needs `--reason`, one of `permission`, `question`,
4856
5019
  `attention` (closed). `clear` refuses `--reason` and `--message`. The home
@@ -6920,87 +7083,268 @@ when the host's row says exactly `true`), and on `oats inspect --home` as
6920
7083
  `instance.pinned`. Each is absent when not pinned. A client reads `pinned`
6921
7084
  only where the probe lists `instance-pin`.
6922
7085
 
6923
- ## Same work as the parent (`oats instance same-work`)
7086
+ ## The agent's board (`oats instance board`)
6924
7087
 
6925
- Feature `instance-same-work` (awebai/oats#1577).
7088
+ Feature `instance-board`, `boardApi: 1`.
6926
7089
 
6927
7090
  ```text
6928
- oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]
6929
- oats spawn <soul> … --same-work
7091
+ oats instance board set <key> --label <text> --value <text> [--unit <text>] [--link <https-url>] [--json]
7092
+ oats instance board unset <key> [--json]
7093
+ oats instance board ask <question> --option <text> --option <text> [--option <text>]… [--id <id>] [--context-file <f>] [--json]
7094
+ oats instance board ask --clear <id> [--json]
6930
7095
  ```
6931
7096
 
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.
7097
+ The board is what an agent tells its person outside its terminal: the
7098
+ **facts** it keeps in view (the PR, the best score, the branch) and the
7099
+ **questions** it needs them to answer, each with 2 to 4 options. A client
7100
+ shows them in the agent's view, above and below the agent's own terminal.
7101
+ The agent reports them, and the kernel infers nothing: it never reads a
7102
+ transcript, and it routes no answer. The word "pin" is never used for facts:
7103
+ [`oats instance pin`](#pinned-instances-oats-instance-pin) pins an instance at
7104
+ the top of the list, which is something else.
7105
+
7106
+ - **Who writes it.** Only the agent, from its own session, as `oats instance
7107
+ attention` does: the home is `$OATS_INSTANCE_HOME`. `--home`, `--dir` and
7108
+ `--server` are refused (`E_BAD_ARGS`), and outside an instance home every
7109
+ form is `E_USAGE`.
7110
+ - **`set`** upserts the fact `<key>`. At most 12 keys: one more is
7111
+ `E_BOARD_FULL`. A set with every field the same changes nothing and writes
7112
+ nothing. The kernel keeps a key's last 20 values with their times (a new
7113
+ value joins it; a new label alone doesn't). `at` is when the fact last
7114
+ changed. **`unset`** removes the key and its history.
7115
+ - **`ask`** opens a question. Its id is `--id`, or `q<n>` by default. `n` is
7116
+ counted per home and never reused while the home lives, so a late answer
7117
+ can't land on a newer question (past `q999999999999999` no default id is
7118
+ left: `E_BOARD_FULL`, ask with `--id`). At most 9 open at once: one more is
7119
+ `E_BOARD_FULL`. Asking a question that is open with the same text, options
7120
+ and context again changes nothing and answers its id, with or without
7121
+ `--id`, so a retry is safe. Anything else under an open id is
7122
+ `E_BAD_ARGS`. **`ask --clear <id>`** closes the
7123
+ question, which the agent does once it has read the answer. Clearing an id
7124
+ that isn't open changes nothing.
7125
+ - **Text.** Key and id match `^[a-z0-9][a-z0-9-]{0,15}$`. Label, value,
7126
+ unit, option and question are one line each, of at most 40, 80, 16, 60
7127
+ and 200 code points, with none of the characters a
7128
+ [waiting message](#waiting-on-you) refuses. A link is an absolute `https:`
7129
+ URL of at most 512 printable ASCII characters. The context comes from a
7130
+ UTF-8 file (`--context-file`), at most 2000 code points once its trailing
7131
+ newlines are trimmed (a file's final newline, such as a heredoc's, isn't
7132
+ content). Newlines (LF) are allowed in it, and every other refused
7133
+ character is not. Anything else is `E_BAD_ARGS`.
7134
+ - **The row bound.** A write that would make the row's `board` larger than
7135
+ 8 KiB as UTF-8 JSON is `E_BOARD_FULL`, with `details.bytes` and
7136
+ `details.max`. Every client can rely on that bound for every row. A
7137
+ refused write writes nothing.
7138
+ - **Per session.** A question records the session it was asked in: the
7139
+ instance's latest kernel session boundary (`launched`, `restarted`,
7140
+ `stopped`: the [waiting claim's rule](#waiting-on-you)). It is live only
7141
+ while that is still the current session. Once a later boundary is written,
7142
+ no row shows it, and the next write drops it. Where the events log's bounded
7143
+ read (its last 4 MiB) holds no boundary, the current session can't be
7144
+ proved: no question is live, and `ask` is `E_BOARD_FAILED` until the next
7145
+ boundary. Facts persist across sessions until they are unset or the home is
7146
+ retired.
7147
+
7148
+ **The needs-input claim.** While any question is open, the home holds the
7149
+ [waiting claim](#waiting-on-you) of producer `oats.board`, reason
7150
+ `attention`. Its message is the oldest open question. The last `--clear`
7151
+ removes it. The claim's row records the session the write read
7152
+ (`session`), and counts only in that session, so a boundary written while a
7153
+ board write runs ends the claim with the question. Reason `attention` holds no scheduled wake
7154
+ ([A held wake](schedules.md#a-held-wake)): a board question leaves the
7155
+ harness at its normal input line. The claim is a producer of its own, so the
7156
+ agent's own `attention` claim can be live beside it, and `waitingOnYou`
7157
+ picks between them by its usual rule. Every board write sets the claim to
7158
+ what the questions say after it. A write whose claim fails is
7159
+ `E_EVENTS_FAILED` after the board was written, with `details.id` (or
7160
+ `details.key`) naming what was written. Running the same command again
7161
+ changes nothing on the board and repairs the claim.
7162
+
7163
+ **How a person answers.** The kernel routes no answer. A client types it as
7164
+ the person's own keystrokes, in the agent's terminal, as `<id>: <text>`
7165
+ (`q2: Yes, one clean commit`), and the person's Enter sends it. An agent reads
7166
+ an answer by its id, then clears the question.
7167
+
7168
+ **The answer** of every form is `{boardApi, instance, home, key | id,
7169
+ changed, board}`, where `board` is the row's value after the write
7170
+ (`null` when the home has no board file and nothing was written):
7171
+
7172
+ ```json
7173
+ {"boardApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","id":"q2","changed":true,
7174
+ "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"}],
7175
+ "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"}]}}
7176
+ ```
7177
+
7178
+ The text answer is one line: `<instance>: fact <key> set` (or `unchanged`,
7179
+ `removed`, `was not set`), or `<instance>: question <id> asked: answers
7180
+ arrive typed as "<id>: <text>"` (or `cleared`, `was not open`).
7181
+
7182
+ | Code | When |
7183
+ |---|---|
7184
+ | `E_USAGE` | Not in an instance session: `$OATS_INSTANCE_HOME` unset, not absolute, or not an instance home under its agents root |
7185
+ | `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 |
7186
+ | `E_BOARD_FULL` | A 13th fact, a 10th open question, a row over 8 KiB, or no default id left; nothing was changed |
7187
+ | `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` |
7188
+ | `E_BOARD_BUSY` | Another process holds the board's lock past 5 seconds (`details.lock`); nothing was changed |
7189
+ | `E_EVENTS_FAILED` | The board was written (`details.id` or `details.key`), but its claim was not: run the same command again |
7190
+
7191
+ **Where it is read.** [`board` on status rows](#row-board), relayed on
7192
+ [remote roster rows](#the-remote-roster-oats-server-roster---json), and with
7193
+ history and context on `oats inspect --home <h> --board` as
7194
+ `instance.board`: each fact gains `history: [{value, at}]` (oldest first, its
7195
+ current value last) and each question `context` (the text, or `null`). Read
7196
+ it when a view is open, not on every poll. Agent text is untrusted: a client
7197
+ shows it as the agent's attributed words, plain text only, and opens a link
7198
+ only on the person's press, outside the app's window.
7199
+
7200
+ **Storage.** `<home>/.oats-board.json`, mode 0600, written atomically under
7201
+ the lock `<home>/.oats-board.lock`, so parallel writes of one agent lose
7202
+ none. The format is the kernel's own, not part of this contract. A reader
7203
+ takes a regular file of at most 256 KiB, without following a link. A file
7204
+ that isn't a valid board in every part reads as an empty board,
7205
+ `{facts: [], questions: []}`, never as an error. Both names are kernel-owned
7206
+ home files: a capability cannot declare them, and a retire counts neither as
7207
+ work. A start, restart or upgrade keeps them, and a retire removes them with
7208
+ the home.
7209
+
7210
+ ## Related work (`oats instance related-work`)
7211
+
7212
+ <a id="same-work-as-the-parent-oats-instance-same-work"></a>
7213
+ Feature `instance-related-work`. It renames `instance-same-work`
7214
+ (awebai/oats#1577), which the kernel still advertises beside it for the
7215
+ [deprecated aliases](#the-deprecated-aliases) and the old row field.
7216
+
7217
+ ```text
7218
+ oats instance related-work <instance> on|off [--home <abs>] [--dir <d>] [--json]
7219
+ oats spawn <soul> … --related-work
7220
+ ```
6936
7221
 
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
7222
+ The flag records that an instance does related work with the instance it is
7223
+ bound to: its parent, or, when it has no parent, its sibling. Clients draw a
7224
+ line between the two for an instance that carries it. Nothing else in the
7225
+ kernel reads it: it is not identity, it grants nothing and it never
7226
+ addresses anything. The kernel never sets it on its own, for any relation:
7227
+ only `--related-work` and `on` do.
7228
+
7229
+ - **The binding.** The flag binds the home's recorded `parentInstance` when
7230
+ it has one, else its recorded `siblingInstance`. With neither, it cannot
7231
+ be set. A sibling binding names the sibling the home records. For a
7232
+ sibling of a top-level instance R, that is R. For a sibling of R's
7233
+ sibling S, the home records S, the anchor it was spawned beside, so the
7234
+ binding is to S, not R.
7235
+ - **The record** is `<home>/.oats-related-work.json`, either
7236
+ `{"relatedWorkApi": 1, "parent": "<instance>", "at": "<ISO time>"}` or
7237
+ `{"relatedWorkApi": 1, "sibling": "<instance>", "at": "<ISO time>"}`,
7238
+ exactly one of `parent` and `sibling`, mode 0600, written atomically.
7239
+ Present means on; `off` removes it. It is a kernel-owned home file: a
7240
+ capability cannot declare it as its own, a retire does not count it as
7241
+ work (on its own it never makes a recovery copy), and `oats instance
6942
7242
  upgrade` does not see it as a change to the home.
6943
7243
  - **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.
7244
+ most 4 KiB, holding JSON with `relatedWorkApi: 1` and exactly one of a
7245
+ non-empty string `parent` and `sibling`. Anything else reads as off, never
7246
+ as an error.
7247
+ - **Bound to the relation.** A parent binding is on only while its `parent`
7248
+ is the home's current recorded `parentInstance`. A sibling binding is on
7249
+ only while the home records no parent and its `sibling` is the current
7250
+ `siblingInstance`. A relink that changes the relation leaves the record
7251
+ naming the old instance, so the flag reads off: a retire's lineage relink
7252
+ (the instances pointing at the retiree re-pointed to its parent, or their
7253
+ sibling link moved to its sibling) and a `--relation parent` spawn
7254
+ re-pointing its anchor. `on` binds it to the current relation again.
6952
7255
  - **Lifetime.** It survives `oats session restart`, a stop and a start, a
6953
7256
  resume (`oats session start --resume`) and `oats instance upgrade`. Only
6954
7257
  `off` and retirement clear it.
7258
+ - **The old flag.** A same-work record, `<home>/.oats-same-work.json`
7259
+ (`{"sameWorkApi": 1, "parent": "<instance>", "at": "<ISO time>"}`), reads
7260
+ as a parent binding while nothing stands at the new record's name, by the
7261
+ same reader rules; so an instance flagged before the rename keeps its
7262
+ flag. When both exist, the new record wins, whatever it holds. The write
7263
+ that creates the new record removes the old one, and `off` removes both.
7264
+ `on` for a binding the old record already holds writes nothing. Both names
7265
+ are kernel-owned.
7266
+
7267
+ <a id="the-deprecated-aliases"></a>
7268
+ **The deprecated aliases.** `oats spawn … --same-work` is `--related-work`,
7269
+ and `oats instance same-work <instance> on|off` is `oats instance
7270
+ related-work`, with the same binding rule (the parent, else the sibling),
7271
+ the same refusals and the same answer; spawnInstance's `sameWork` option is
7272
+ `relatedWork`, and each call with it emits one Node `DeprecationWarning`
7273
+ (code `OATS_SAME_WORK`, `sameWork is renamed: use relatedWork`). Each CLI use prints one line on stderr, before the command runs
7274
+ or is sent with `--server`: `oats: --same-work is renamed: use
7275
+ --related-work`, or `oats: oats instance same-work is renamed: use oats
7276
+ instance related-work`. It is never in the `--json` answer: the envelope is
7277
+ the one the new spelling gives, with no `warnings`. The aliases, the
7278
+ feature `instance-same-work` and the [`sameWork`](#row-related-work) row
7279
+ field stay until their removal is decided on its own, with its own
7280
+ release-notes entry.
6955
7281
 
6956
7282
  **The verb.** The instance is addressed as `oats instance color` addresses
6957
7283
  it, and refused with the same answers.
6958
7284
 
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.
7285
+ - `on` binds the flag to the instance's recorded `parentInstance`, else to
7286
+ its recorded `siblingInstance`; an instance with neither is refused. `on`
7287
+ again while the flag holds that binding writes nothing; `on` after a
7288
+ relink rebinds it to the current relation.
7289
+ - `off` removes whatever stands at either record's name (a file, a link, a
7290
+ directory). It succeeds whether or not the flag was on and whether or not
7291
+ a relation is recorded; `off` again is the same answer.
6966
7292
 
6967
- The answer, the envelope's `result`, has exactly these two keys:
7293
+ The answer, the envelope's `result`, has exactly these three keys:
6968
7294
 
6969
7295
  ```json
6970
- {"instance":"dev-a","sameWork":true}
7296
+ {"instance":"dev-a","relatedWork":true,"sameWork":true}
6971
7297
  ```
6972
7298
 
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`).
7299
+ `relatedWork` is the binding rule read after the write: `true` after `on`,
7300
+ `false` after `off`. `sameWork` is the old verb's answer: `true` only when
7301
+ the flag holds a parent binding, so `false` for a sibling binding. The text
7302
+ answer is `dev-a: related work on` (or `off`).
6975
7303
 
6976
7304
  | Code | When |
6977
7305
  |---|---|
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` |
7306
+ | `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
7307
  | *(as `oats instance color`)* | Instance resolution: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME` |
6980
7308
  | `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
7309
  | `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
7310
 
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.
7311
+ **At spawn.** `oats spawn … --related-work` sets the flag on the new
7312
+ instance. It is bound to the parent the new home records, whichever
7313
+ relation gave it: `--parent <instance>` or `--relation child`; `--relation
7314
+ sibling` of an anchor that has a parent (the new instance shares it);
7315
+ `--relation parent` of an anchor that had a parent (the new instance
7316
+ inherits it); `--work attached` (the owner of the tree). Else it is bound to
7317
+ the sibling the new home records: `--relation sibling` of an anchor with no
7318
+ parent (the anchor itself), and `--relation parent` of an anchor with a
7319
+ sibling link and no parent (the new instance inherits the link). The record
7320
+ is written inside the spawn, before the launch, so the instance's first
7321
+ status row carries `relatedWork: true`; a spawn rolled back removes it with
7322
+ the home. When the new instance would record neither (no relation,
7323
+ `--relation unrelated`, `--relation parent` of a top-level anchor with no
7324
+ sibling link), the spawn is refused with `E_BAD_ARGS` before anything is
7325
+ created, `--preview` included: `--related-work needs a parent or a sibling:
7326
+ <instance> would record no parent or sibling instance …; nothing was
7327
+ spawned`.
6994
7328
 
6995
7329
  Routed with `--server <id>`, the verb runs on the host
6996
7330
  ([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).
7331
+ --related-work` sends the flag there. A host that advertises
7332
+ `instance-related-work` is sent the new spellings, the aliases included. A
7333
+ host that advertises only `instance-same-work` (an older OATS), and only
7334
+ that host, is asked by the old spellings when the binding is a parent:
7335
+ `--same-work` and `oats instance same-work`, its answer's `sameWork`
7336
+ returned with `relatedWork` beside it. The binding
7337
+ is read from the spawn's arguments and the host's own roster (the anchor's
7338
+ row for `--relation sibling|parent`, the instance's row for `on`). A sibling
7339
+ binding is refused there with `E_REMOTE_INCOMPATIBLE`, naming the host and
7340
+ the feature it lacks, and nothing is sent; it is never dropped. A host that
7341
+ advertises neither feature is refused with `E_REMOTE_INCOMPATIBLE` for
7342
+ either, and nothing is sent.
7343
+
7344
+ Where it is read: `relatedWork` (and `sameWork` beside it for a parent
7345
+ binding) on [status rows](#row-related-work) and on [remote roster
7346
+ rows](#the-remote-roster-oats-server-roster---json) (only `true` is
7347
+ relayed).
7004
7348
 
7005
7349
  ## Sessions and launch configurations
7006
7350