@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
package/docs/upgrading.md CHANGED
@@ -6,12 +6,12 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.22** ([release notes](release-notes/v0.69.22.md)).
10
- The 0.69.22 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
9
+ The latest version is **OATS 0.69.23** ([release notes](release-notes/v0.69.23.md)).
10
+ The 0.69.23 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
11
11
  Desktop and the CLI can be upgraded [in either order](#either-order-works).
12
12
 
13
13
  **First, read the `## Upgrade` section of every release after yours, up to
14
- 0.69.22,** in the [release notes](release-notes/): it says what to do before
14
+ 0.69.23,** in the [release notes](release-notes/): it says what to do before
15
15
  the CLI changes, and what else must change with it (the Desktop, another
16
16
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
17
17
  names the releases that ask for more than the steps below. `oats version`
@@ -20,8 +20,8 @@ prints the version you have.
20
20
  Then, on each host:
21
21
 
22
22
  ```sh
23
- # 0. where the Desktop is installed: Desktop 0.69.22, in either order
24
- npm install -g @awebai/oats@0.69.22 # 1. the CLI
23
+ # 0. where the Desktop is installed: Desktop 0.69.23, in either order
24
+ npm install -g @awebai/oats@0.69.23 # 1. the CLI
25
25
  oats update # 2. in each deployment: the plan, then it asks before it runs
26
26
  oats doctor # 3. in the same deployment
27
27
  ```
@@ -217,6 +217,13 @@ of the Desktop and the CLI, and an optional package pin. A change a script
217
217
  must follow is in its release's Upgrade section whether or not it is listed
218
218
  here.
219
219
 
220
+ - **[0.69.23](release-notes/v0.69.23.md#upgrade):** the catalog pins
221
+ oats.framework 1.27.0, oats.aweb 1.46.0 and oats.okf 6.3.0. Respawn
222
+ instances, or move stopped ones with `oats instance upgrade`, to take the
223
+ board teaching and the mail read. `--same-work` and `oats instance
224
+ same-work` are deprecated aliases of `--related-work` and `oats instance
225
+ related-work`. A team image that ran the experimental
226
+ bb image is rebuilt, with the bb image from oats-project/oats-bb.
220
227
  - **[0.69.22](release-notes/v0.69.22.md#upgrade):** the catalog pins
221
228
  oats.aweb 1.45.0; `setup --install-aw` installs the tested aw by default.
222
229
  The Desktop's leader is Ctrl+Space (Ctrl+X a click away; a leader you set is
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.26.0 # bare version → resolves through the official catalog
58
- oats.okf: v6.2.0
57
+ oats.framework: v1.27.0 # bare version → resolves through the official catalog
58
+ oats.okf: v6.3.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone
package/lib/argv.mjs CHANGED
@@ -4,7 +4,7 @@
4
4
  * Dependency-free. */
5
5
 
6
6
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
7
- const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "background", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-background", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "same-work", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
7
+ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "background", "board", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-background", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "related-work", "replace", "run-source", "same-work", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
8
8
  /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
9
9
  * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
10
10
  * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
@@ -16,8 +16,12 @@ const INLINE_TEXT_FLAGS = new Set(["message"]);
16
16
  /** Free-text flags whose inline value is always kept whole, the empty one included:
17
17
  * `--description=` clears a trigger's or schedule's description. */
18
18
  const INLINE_WHOLE_FLAGS = new Set(["description"]);
19
+ /** A word that is a switch everywhere but one form, where it takes a value: `oats instance board ask
20
+ * --clear <id>` (feature instance-board). There, `--clear=<id>` is `--clear <id>`. */
21
+ const VALUE_IN_FORM = [{ words: ["instance", "board", "ask"], name: "clear" }];
19
22
  export function expandInlineValues(argv) {
20
23
  const out = [];
24
+ const valued = new Set(VALUE_IN_FORM.filter((f) => f.words.every((w, i) => argv[i] === w)).map((f) => f.name));
21
25
  const inline = new Map();
22
26
  let problem;
23
27
  for (const a of argv) {
@@ -25,7 +29,7 @@ export function expandInlineValues(argv) {
25
29
  if (!a.startsWith("--") || eq <= 2) { out.push(a); continue; }
26
30
  const name = a.slice(2, eq), value = a.slice(eq + 1);
27
31
  if (INLINE_WHOLE_FLAGS.has(name) || (INLINE_TEXT_FLAGS.has(name) && value.startsWith("--"))) { inline.set(name, value); out.push(`--${name}`); continue; }
28
- problem ??= KERNEL_SWITCHES.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : value.startsWith("--") ? `--${name}= takes a value, not an option (got ${a})` : undefined;
32
+ problem ??= KERNEL_SWITCHES.has(name) && !valued.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : value.startsWith("--") ? `--${name}= takes a value, not an option (got ${a})` : undefined;
29
33
  out.push(`--${name}`, value);
30
34
  }
31
35
  return { argv: out, problem, inline };
@@ -181,13 +181,13 @@ const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
181
181
  * declaration may not cover them: these exact names, and every exact name
182
182
  * starting with one of these prefixes (the events log; the stop, restart and
183
183
  * start receipts and locks; the rollback marker; AGENTS.md backups; the
184
- * attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the pin, `.oats-pinned.json`; the same-work flag, `.oats-same-work.json`). This is the one list: a new kernel-written top-level
184
+ * attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the pin, `.oats-pinned.json`; the related-work flag, `.oats-related-work.json`, and `.oats-same-work.json`, the file of the same-work flag it replaced, which the kernel still reads while the new one is absent; the agent's board, `.oats-board.json`, and its lock). This is the one list: a new kernel-written top-level
185
185
  * home entry MUST be added here and to the `not` patterns of
186
186
  * `retirement.disposable.home` in docs/capability-manifest.schema.json. A
187
187
  * prefix declaration can reach none of them except through `.oats-`, which is
188
188
  * refused whole; `.oats-<provider>` as an exact name stays declarable. */
189
189
  const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
190
- const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-pinned", ".oats-same-work"];
190
+ const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-pinned", ".oats-same-work", ".oats-related-work", ".oats-board"];
191
191
 
192
192
  /** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
193
193
  * name or prefix), "kernel-owned", or undefined when it is sound. */
@@ -6,8 +6,28 @@
6
6
  * missing here is not checked. Kernel-private, not exported from `./core`. Dependency-free. */
7
7
 
8
8
  export const RETIRE_DELETE_BRANCH_REFUSED = "oats retire no longer deletes branches: --delete-branch is not accepted. Retire without it; the branch is left in the repository. Inspect it there and delete it with Git if it is no longer wanted.";
9
+ /** The spellings the related-work rename (feature instance-related-work) kept as deprecated aliases
10
+ * (feature instance-same-work, the compatibility layer): `oats spawn … --same-work` is `--related-work`,
11
+ * and `oats instance same-work` is `oats instance related-work`. Each use prints its line on stderr, once,
12
+ * before the command runs or is sent to a --server host (sameWorkDeprecation, the dispatch's), and never
13
+ * in a --json answer. spawnInstance's `sameWork` option is the same alias (lib/core.mjs). */
14
+ export const SAME_WORK_ALIASES = Object.freeze({
15
+ flag: "--same-work is renamed: use --related-work",
16
+ verb: "oats instance same-work is renamed: use oats instance related-work",
17
+ });
18
+
19
+ /** spawnInstance's deprecated option, said as a DeprecationWarning (code OATS_SAME_WORK) by lib/core.mjs. */
20
+ export const SAME_WORK_OPTION_RENAMED = "sameWork is renamed: use relatedWork";
21
+
22
+ /** The deprecation line `argv` (the CLI's argv, after `oats`, as typed) earns by an alias of
23
+ * SAME_WORK_ALIASES, or undefined. */
24
+ export function sameWorkDeprecation(argv) {
25
+ if (argv[0] === "instance" && argv[1] === "same-work") return SAME_WORK_ALIASES.verb;
26
+ if (argv[0] === "spawn" && argv.some((a) => a === "--same-work" || a.startsWith("--same-work="))) return SAME_WORK_ALIASES.flag;
27
+ return undefined;
28
+ }
9
29
  export const RETIRE_USAGE = "usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--dir <d>] [--server <id>] [--self] [--discard-worktree] [--keep-dir] [--force] [--json]";
10
- export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
30
+ export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--related-work|--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
11
31
  export const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
12
32
  export const APPROVAL_REMOVED = "package approval was removed; declaring a package in packages: is the trust decision";
13
33
  export const TEAMS_USAGE = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
@@ -38,6 +58,16 @@ const waiting = (verb) => ({ command: `instance waiting ${verb}`, operands: [],
38
58
  usage: `usage: oats instance waiting ${verb} --producer <id>${verb === "set" ? " --reason permission|question|attention" : ""} [--message=<text>] [--home <abs>] [--dir <d>] [--json]` });
39
59
  const ATTENTION_USAGE = "usage: oats instance attention [--message=<text>] [--clear] [--json]";
40
60
  const attentionHasNo = (flag) => `oats instance attention has no ${flag}: it records the agent's own claim on the instance it runs in ($OATS_INSTANCE_HOME); ${ATTENTION_USAGE}`;
61
+ /** `oats instance board`'s forms (feature instance-board), each its own usage line; BOARD_USAGE all of them. */
62
+ const BOARD_FORMS = Object.freeze({
63
+ set: "oats instance board set <key> --label <text> --value <text> [--unit <text>] [--link <https-url>] [--json]",
64
+ unset: "oats instance board unset <key> [--json]",
65
+ ask: "oats instance board ask <question> --option <text> --option <text> [--option <text>]… [--id <id>] [--context-file <f>] [--json] | oats instance board ask --clear <id> [--json]",
66
+ });
67
+ export const BOARD_USAGE = `usage: ${Object.values(BOARD_FORMS).join(" | ")}`;
68
+ /** `oats instance board` records on the instance it runs in, as `attention` does: these are refused in its words. */
69
+ const boardRefused = (verb) => Object.freeze(Object.fromEntries(["--home", "--dir", "--server"].map((f) => [f, `oats instance board has no ${f}: it records on the board of the instance it runs in ($OATS_INSTANCE_HOME); usage: ${BOARD_FORMS[verb]}`])));
70
+ const board = (verb, operand, values, required = 1) => ({ command: `instance board ${verb}`, operands: [operand], required, values, switches: ["--json"], refused: boardRefused(verb), usage: `usage: ${BOARD_FORMS[verb]}` });
41
71
  const TRIGGER_RUN_SOURCE = Object.freeze(["--run-source", "--json"]);
42
72
  const SESSION_ADDRESS = Object.freeze(["--home", "--instance", "--server"]);
43
73
  /** Every `oats session` form refuses the captured path's selector in these words (bin's sessionCmd says them
@@ -82,7 +112,7 @@ export const COMMAND_FLAGS = Object.freeze([
82
112
  { command: "spawn", operands: ["soul"],
83
113
  values: ["--agents-root", "--backend", "--base", "--branch", "--dir", "--expect-decision", "--harness", "--herdr-socket", "--idempotency-key", "--instance", "--launch-config", "--max-age", "--model", "--name", "--parent", "--provider", "--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"],
84
114
  arity: { "--provider": 2 },
85
- switches: ["--allow-child-spawns", "--background", "--json", "--no-background", "--no-child-spawns", "--no-launch", "--no-yolo", "--preview", "--same-work", "--suggest-name", "--yolo"],
115
+ switches: ["--allow-child-spawns", "--background", "--json", "--no-background", "--no-child-spawns", "--no-launch", "--no-yolo", "--preview", "--related-work", "--same-work", "--suggest-name", "--yolo"],
86
116
  // Local souls (local-agents/) are gone with the workspace model: a soul is a member
87
117
  // repository's souls/<name>, so spawn never writes one.
88
118
  refused: { "--instructions-file": SPAWN_REMOVED_SOUL("--instructions-file"), "--def-file": SPAWN_REMOVED_SOUL("--def-file"),
@@ -103,11 +133,18 @@ export const COMMAND_FLAGS = Object.freeze([
103
133
  usage: "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d> | --server <id>] [--json]" },
104
134
  onOff("background"),
105
135
  onOff("pin"),
136
+ onOff("related-work"),
137
+ // The verb's deprecated alias (SAME_WORK_ALIASES): the same arguments.
106
138
  onOff("same-work"),
107
139
  waiting("set"),
108
140
  waiting("clear"),
109
141
  { command: "instance attention", operands: [], values: ["--message"], switches: ["--clear", "--json"],
110
142
  refused: Object.fromEntries(["--home", "--dir", "--producer", "--reason"].map((f) => [f, attentionHasNo(f)])), usage: ATTENTION_USAGE },
143
+ board("set", "key", ["--label", "--value", "--unit", "--link"]),
144
+ board("unset", "key", []),
145
+ // `--clear <id>` takes the id as its value, so the question is optional here; the command refuses a form
146
+ // with neither, or with both.
147
+ board("ask", "question", ["--option", "--id", "--context-file", "--clear"], 0),
111
148
  { command: "instance suggest-name", operands: [], values: ["--soul", "--task", "--task-file", "--harness", "--model", "--launch-config", "--dir"], switches: ["--json"],
112
149
  refused: { "--server": "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)" },
113
150
  usage: "usage: oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]" },
package/lib/core.mjs CHANGED
@@ -48,7 +48,7 @@ import { createHash, randomUUID } from "node:crypto";
48
48
  import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
49
49
  import { sameDirectory } from "../packages/record/lib/directory-identity.mjs";
50
50
  import { noteRuntimeName } from "./deprecation.mjs";
51
- import { RETIRE_DELETE_BRANCH_REFUSED } from "./command-flags.mjs";
51
+ import { RETIRE_DELETE_BRANCH_REFUSED, SAME_WORK_OPTION_RENAMED } from "./command-flags.mjs";
52
52
  import { attachSessionTarget, requireDetachKey } from "./session-viewer.mjs";
53
53
  import { AGENT_PANE_OPTION, inspectSessionTarget, inputSessionTarget, resolveAgentPane } from "./session-input.mjs";
54
54
  import { RETIRE_HOOK_WARNING_KIND, appendEvent, incarnationOf, recordStartBoundary, retireRefusedReason } from "./instance-events.mjs";
@@ -99,7 +99,8 @@ import { SCOPE_ENV_NAMES, agentScope, agentScopeArgv, agentScopeUnit, creatorPla
99
99
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
100
100
  import { readInstanceBackground, writeInstanceBackground } from "./instance-background.mjs";
101
101
  import { PIN_FILE } from "./instance-pin.mjs";
102
- import { SAME_WORK_FILE, writeSameWork } from "./instance-same-work.mjs";
102
+ import { BOARD_FILE, BOARD_LOCK } from "./instance-board.mjs";
103
+ import { RELATED_WORK_FILE, SAME_WORK_FILE, relatedWorkBinding, writeRelatedWork } from "./instance-related-work.mjs";
103
104
  import { HOST_STOP_REASON, readStartExited, sessionEndOf, START_EXITED_FILE, STOP_RECEIPT_FILE } from "./session-end.mjs";
104
105
  import { thisBoot } from "./session-seen.mjs";
105
106
  import { FRESH_REASON, RESUME_WAITING, SESSION_END } from "./session-resume-contract.mjs";
@@ -3683,7 +3684,13 @@ function* spawnBody(root, agent, o = {}) {
3683
3684
  if (relation === "unrelated" && relativeTo) throw new Error(`relation "unrelated" takes no relativeTo`);
3684
3685
  if (relation && relation !== "unrelated" && !relativeTo) throw new Error(`relation "${relation}" needs a relative-to instance`);
3685
3686
  if (typeof o.relativeRoot === "string" && o.relativeRoot.trim() && !relativeTo && !legacyParent) throw new Error(`relativeRoot only qualifies relativeTo/parent`);
3687
+ if (o.relatedWork !== undefined && typeof o.relatedWork !== "boolean") throw oatsError("E_BAD_ARGS", "relatedWork must be true or false");
3688
+ // `sameWork`, the option's old name, is an alias (the related-work compatibility layer): either sets the flag.
3689
+ // Its use is said once per call as Node's DeprecationWarning (stderr, never an answer); the CLI passes
3690
+ // `relatedWork`, its own alias having said so already (lib/command-flags.mjs SAME_WORK_ALIASES).
3686
3691
  if (o.sameWork !== undefined && typeof o.sameWork !== "boolean") throw oatsError("E_BAD_ARGS", "sameWork must be true or false");
3692
+ if (o.sameWork !== undefined) process.emitWarning(SAME_WORK_OPTION_RENAMED, { type: "DeprecationWarning", code: "OATS_SAME_WORK" });
3693
+ const relatedWorkAsked = o.relatedWork === true || o.sameWork === true;
3687
3694
  if (!relation && legacyParent) { relation = "child"; relativeTo = legacyParent; }
3688
3695
  if (relation === "unrelated") { relation = undefined; relativeTo = undefined; }
3689
3696
 
@@ -3814,11 +3821,12 @@ function* spawnBody(root, agent, o = {}) {
3814
3821
  if (anchorMeta?.siblingInstance) siblingInstance = anchorMeta.siblingInstance;
3815
3822
  }
3816
3823
  if (!relation && attachedOwner && attachedOwner !== instance) parentInstance = attachedOwner;
3817
- // Feature instance-same-work: the flag binds the parent the new home records, whichever relation gave
3818
- // it (child, a sibling of a non-root, --relation parent under a parented anchor, attached). None: refused
3819
- // here, before any home, worktree or hook, a preview's included.
3820
- if (o.sameWork === true && !(parentInstance && parentInstance !== instance)) {
3821
- throw oatsError("E_BAD_ARGS", `--same-work needs a parent: ${instance} would record no parent instance${relation ? ` (relation ${relation}${relativeTo ? ` to ${relativeTo}` : ""})` : ""}; spawn it with --parent <instance>, or without --same-work; nothing was spawned`);
3824
+ // Feature instance-related-work: the flag binds the parent the new home records, whichever relation gave
3825
+ // it (child, a sibling of a non-root, --relation parent under a parented anchor, attached), else the
3826
+ // sibling it records (a sibling of a root or of a root's sibling, --relation parent over an anchor with a
3827
+ // sibling link). Neither: refused here, before any home, worktree or hook, a preview's included.
3828
+ if (relatedWorkAsked && !relatedWorkBinding({ parentInstance: parentInstance !== instance ? parentInstance : undefined, siblingInstance: siblingInstance !== instance ? siblingInstance : undefined })) {
3829
+ throw oatsError("E_BAD_ARGS", `--related-work needs a parent or a sibling: ${instance} would record no parent or sibling instance${relation ? ` (relation ${relation}${relativeTo ? ` to ${relativeTo}` : ""})` : ""}; spawn it with --parent <instance> or --relation sibling --relative-to <instance>, or without --related-work; nothing was spawned`);
3822
3830
  }
3823
3831
  // K5 §4 — child-spawn permission is ENFORCED here, by the spawn route. The
3824
3832
  // parent's recorded policy (instance.json policy.childSpawns) says whether
@@ -4939,9 +4947,10 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
4939
4947
  Object.assign(meta, workspaceRecord);
4940
4948
  }
4941
4949
  const spawnWarnings = warnings;
4942
- // Feature instance-same-work: bound to the parent the home records, written before the launch so that
4943
- // the instance's first status shows it; the home's removal on a rollback takes it with the rest.
4944
- if (o.sameWork === true && meta.parentInstance) writeSameWork(home, meta.parentInstance);
4950
+ // Feature instance-related-work: bound to the parent the home records, else to its sibling (the one
4951
+ // choice, relatedWorkBinding), written before the launch so that the instance's first status shows it;
4952
+ // the home's removal on a rollback takes it with the rest.
4953
+ if (relatedWorkAsked && relatedWorkBinding(meta)) writeRelatedWork(home, relatedWorkBinding(meta));
4945
4954
 
4946
4955
  spawnTmux = meta.tmux;
4947
4956
  if (work === "directory") assertDirectoryRoots(home, homeReal);
@@ -5476,13 +5485,15 @@ function retireGitProbe(repo, args, { encoding } = {}) {
5476
5485
  * KERNEL_HOME_NAME_PREFIXES in lib/capability-contract.mjs, and the schema). */
5477
5486
  // `.oats-color.json` (feature instance-color) and `.oats-background.json` (feature instance-background) are
5478
5487
  // presentation anyone may change at any time: never work. `.oats-pinned.json` (feature instance-pin) is
5479
- // presentation of the same kind.
5480
- // `.oats-same-work.json` (feature instance-same-work) is kernel presentation of the same kind.
5488
+ // presentation of the same kind. `.oats-board.json` (feature instance-board) is the agent's own display, and
5489
+ // `.oats-board.lock` what a write killed while it held the lock leaves: never work.
5490
+ // `.oats-related-work.json` (feature instance-related-work) is kernel presentation of the same kind, and so is
5491
+ // `.oats-same-work.json`, the file of the flag it replaced: read while the new one is absent, never written.
5481
5492
  // `.oats-start-exited` (lib/session-end.mjs) is the window's record of how the harness ended: every
5482
5493
  // launched home whose harness ever ended holds it.
5483
5494
  // `.oats-start-env.json` and its key (lib/start-env.mjs) are written at every start that renders a
5484
5495
  // recipe, after the spawn's baseline: every launched home holds them.
5485
- const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json", ".oats-background.json", PIN_FILE, SAME_WORK_FILE, START_EXITED_FILE, START_ENV_FILE, START_ENV_KEY_FILE]);
5496
+ const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json", ".oats-background.json", PIN_FILE, BOARD_FILE, BOARD_LOCK, RELATED_WORK_FILE, SAME_WORK_FILE, START_EXITED_FILE, START_ENV_FILE, START_ENV_KEY_FILE]);
5486
5497
  // `instance.json.tmp-<pid>` is what a process killed between the two steps of writeJsonAtomic leaves
5487
5498
  // of the record: not a hidden name, so a capability cannot declare it (disposableHomeRootProblem).
5488
5499
  const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/, /^instance\.json\.tmp-\d+$/, START_ENV_TMP, LAUNCH_ENV_HANDOFF];
@@ -9559,7 +9570,7 @@ const claimCommand = (action) => action === "resume" ? "oats session start --res
9559
9570
  /** What each verb that meets a held claim says it did not do: the words its refusals end with,
9560
9571
  * before any effect. After a takeover ended a dead holder's step, every verb says the same
9561
9572
  * (lib/errors.mjs nothingAfter). */
9562
- const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", resume: "nothing was started", start: "nothing was started", "worktree add": "no tree was made", "instance color": "the colour was not changed", "instance same-work": "the flag was not changed", "instance background": "the background was not changed", "instance pin": "the pin was not changed" };
9573
+ const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", resume: "nothing was started", start: "nothing was started", "worktree add": "no tree was made", "instance color": "the colour was not changed", "instance related-work": "the flag was not changed", "instance background": "the background was not changed", "instance pin": "the pin was not changed" };
9563
9574
 
9564
9575
  /** The refusals of `arriving` ("retire", "stop", "upgrade", "resume", "start", or "worktree add", which
9565
9576
  * reads the claim and does not take it) of `name` (home `home`) that meets the lifecycle claim `lock`, as lib/claim.mjs asks