@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/bin/oats.mjs CHANGED
@@ -19,7 +19,7 @@
19
19
  * `init` / `use` / `install` / `restore` / `list` / `catalog` / `remove` /
20
20
  * `migrate` / `trust` / `inject` are gone with the installed-capability tier.
21
21
  */
22
- import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
22
+ import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
23
23
  import { execFileSync, spawnSync } from "node:child_process";
24
24
  import { constants as osConstants, homedir, tmpdir } from "node:os";
25
25
  import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -83,7 +83,7 @@ const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = aw
83
83
  const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
84
84
  const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
85
85
  const { observeInstanceGit, diffInstanceFile, NO_FILE_MONITOR } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
86
- const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstancePin, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
86
+ const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstancePin, setInstanceRelatedWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
87
87
  const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
88
88
  const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
89
89
  const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
@@ -91,16 +91,17 @@ const { retireIncompleteProblems } = await kernelImport("retire-incomplete", ()
91
91
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
92
92
  const { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } = await kernelImport("instance-inspect", () => import("../lib/instance-inspect.mjs"));
93
93
  const { readEvents, setWaiting, incarnationOf } = await kernelImport("instance-events", () => import("../lib/instance-events.mjs"));
94
+ const { readBoardDetail, askBoardQuestion, clearBoardQuestion, setBoardFact, unsetBoardFact } = await kernelImport("instance-board", () => import("../lib/instance-board.mjs"));
94
95
  const { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } = await kernelImport("deployments", () => import("../lib/deployments.mjs"));
95
96
  const { observeResolvedDeployment } = await kernelImport("resolved-deployment", () => import("../lib/resolved-deployment.mjs"));
96
97
  const { SESSION_RESUME_FEATURE } = await kernelImport("session-resume-contract", () => import("../lib/session-resume-contract.mjs"));
97
- const { KERNEL_FEATURES, READER_API } = await kernelImport("kernel-features", () => import("../lib/kernel-features.mjs"));
98
+ const { BOARD_API, KERNEL_FEATURES, READER_API } = await kernelImport("kernel-features", () => import("../lib/kernel-features.mjs"));
98
99
  const { inheritedContextRefusal } = await kernelImport("captured-context", () => import("../lib/captured-context.mjs"));
99
100
  const { callSession, parseMaxAge, readBudget } = await kernelImport("read-call", () => import("../lib/read-call.mjs"));
100
101
  const { cachedWorkspace, legacyLayoutProblems, statusAnswer, statusView } = await kernelImport("roster-read", () => import("../lib/roster-read.mjs"));
101
102
  const { memberLabel, memberRows, packageRows, standaloneCatalogVersion, standalonePackages, workspaceName, workspaceStatusAnswer, workspaceStatusView } = await kernelImport("workspace-read", () => import("../lib/workspace-read.mjs"));
102
103
  const { expandInlineValues, flagValue } = await kernelImport("argv", () => import("../lib/argv.mjs"));
103
- const { APPROVAL_REMOVED, NATIVE_RECORD_REFUSED, HOST_RUN_USAGE, RESUME_LOCAL_ONLY, RETIRE_USAGE, SOUL_LAUNCH_USAGE, SPAWN_USAGE, SYNC_USAGE, TEAMS_USAGE, WORKTREE_USAGE, commandArgvProblem, commandFlags } = await kernelImport("command-flags", () => import("../lib/command-flags.mjs"));
104
+ const { APPROVAL_REMOVED, NATIVE_RECORD_REFUSED, HOST_RUN_USAGE, RESUME_LOCAL_ONLY, RETIRE_USAGE, SOUL_LAUNCH_USAGE, SPAWN_USAGE, SYNC_USAGE, TEAMS_USAGE, WORKTREE_USAGE, BOARD_USAGE, commandArgvProblem, commandFlags, sameWorkDeprecation } = await kernelImport("command-flags", () => import("../lib/command-flags.mjs"));
104
105
 
105
106
  const rawArgs = process.argv.slice(2);
106
107
  const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
@@ -618,12 +619,17 @@ async function inspectCmd() {
618
619
  // Feature soul-composed-skills: opt-in, soul subject only; it shares --instructions' one scratch composition.
619
620
  const composedSkills = args.includes("--composed-skills");
620
621
  if (composedSkills && flag("home") !== undefined) return bail("E_BAD_ARGS", "--composed-skills lists the skills a spawn of a soul would give its instance: it takes --soul, not --home (an instance's skills are in its home's .agents/skills/)");
622
+ // Feature instance-board: opt-in, instance subject only; the board's facts with their history and its
623
+ // questions with their context (the rows carry neither).
624
+ const board = args.includes("--board");
625
+ if (board && flag("home") === undefined) return bail("E_BAD_ARGS", "--board reads an instance's board: it takes --home <abs>, not --soul (a soul has no board)");
621
626
  let t = await workspaceTarget(bail, { command: "inspect" });
622
627
  if (t) {
623
628
  if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
624
629
  if (instructions || composedSkills) t = await withComposition(t, { instructions, skills: composedSkills });
625
630
  if (skills) t = await withSkills(t);
626
631
  const doc = inspectDocument(t, { kernel: OATS_VERSION });
632
+ if (board && doc.instance) doc.instance = { ...doc.instance, board: readBoardDetail(t.home) };
627
633
  if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
628
634
  printWorkspaceInspect(doc); return;
629
635
  }
@@ -672,6 +678,16 @@ function printWorkspaceInspect(doc) {
672
678
  for (const c of doc.capabilities) console.log(` ${c.id}@${c.version || "?"} ${c.from?.kind === "package" ? `package ${c.from.package}` : c.from?.kind === "member" ? `member ${c.from.repoKey}` : ""}${c.operations.length ? ` ops: ${c.operations.map((o) => `${o.name}${o.available ? "" : "(unavailable)"}`).join(", ")}` : ""}`);
673
679
  for (const p of doc.problems) console.log(` ! ${p.code}: ${p.message}`);
674
680
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
681
+ const board = doc.instance?.board;
682
+ if (board !== undefined) {
683
+ // The agent's own text: every refused character spelled out, never interpreted (terminalText).
684
+ if (board === null) console.log("\nBoard: none");
685
+ else {
686
+ console.log(`\nBoard: ${board.facts.length} fact${board.facts.length === 1 ? "" : "s"}, ${board.questions.length} open question${board.questions.length === 1 ? "" : "s"}`);
687
+ for (const f of board.facts) console.log(terminalText(` ${f.key} ${f.label}: ${f.value}${f.unit ? ` ${f.unit}` : ""}${f.link ? ` ${f.link}` : ""} (${f.history.length} value${f.history.length === 1 ? "" : "s"}, updated ${f.at})`));
688
+ for (const q of board.questions) console.log(terminalText(` ${q.id} ${q.question} [${q.options.map((o, i) => `${i + 1}. ${o}`).join(" ")}] (asked ${q.since})`));
689
+ }
690
+ }
675
691
  const composed = doc.souls[0].composedInstructions;
676
692
  if (composed !== undefined) console.log(composed ? `\nComposed AGENTS.md (a spawn here, resolution ${composed.resolution ?? "?"}${composed.truncated ? ", truncated" : ""}):\n\n${composed.text}` : "\nComposed AGENTS.md: unavailable (see the problems above)");
677
693
  const composedSkills = doc.souls[0].composedSkills;
@@ -1312,6 +1328,76 @@ function instanceWaitingCmd(sub, bail) {
1312
1328
  } catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
1313
1329
  }
1314
1330
 
1331
+ /** `oats instance board set|unset|ask` (feature instance-board, lib/instance-board.mjs): the agent's own
1332
+ * board, the facts it keeps in view for its person and the questions it asks them. Like `attention`, it
1333
+ * acts only on $OATS_INSTANCE_HOME (no --home, --dir or --server: lib/command-flags.mjs refuses them).
1334
+ * Display only: the kernel routes no answer. */
1335
+ function instanceBoardCmd(bail) {
1336
+ dropAmbientRoot();
1337
+ const verb = args[2];
1338
+ const usage = BOARD_USAGE;
1339
+ const forms = { set: ["label", "value", "unit", "link"], unset: [], ask: ["option", "id", "context-file", "clear"] };
1340
+ if (!Object.hasOwn(forms, verb)) return bail("E_BAD_ARGS", usage);
1341
+ // The form's words after the verb: its value flags (each once, but --option), and its operands. The
1342
+ // dispatch (commandArgvProblem) has refused an unknown flag and an argument too many.
1343
+ const values = new Map(), operands = [];
1344
+ for (let i = 3; i < args.length; i++) {
1345
+ const a = args[i];
1346
+ if (!a.startsWith("--")) { operands.push(a); continue; }
1347
+ const name = a.slice(2);
1348
+ if (name === "json") continue;
1349
+ if (!forms[verb].includes(name)) return bail("E_BAD_ARGS", `oats instance board ${verb}: unknown flag ${a}\n${usage}`);
1350
+ const v = args[i + 1];
1351
+ if (v === undefined || v.startsWith("--")) return bail("E_BAD_ARGS", `--${name} needs a value; ${usage}`);
1352
+ if (values.has(name) && name !== "option") return bail("E_BAD_ARGS", `--${name} is given more than once; ${usage}`);
1353
+ values.set(name, [...(values.get(name) ?? []), v]);
1354
+ i++;
1355
+ }
1356
+ const one = (name) => values.get(name)?.[0];
1357
+ const home = process.env.OATS_INSTANCE_HOME;
1358
+ if (!home || !isAbsolute(home) || incarnationOf(home) === null) return bail("E_USAGE", `oats instance board runs inside an instance session: $OATS_INSTANCE_HOME is ${home ? `${home}, which is not an instance home (no readable instance.json)` : "unset"}`);
1359
+ const root = agentsRootOfHome(home);
1360
+ const { resolveInstance } = await_import_lifecycle();
1361
+ try { resolveInstance(dirFlag(), root, basename(home), { home }); }
1362
+ catch (e) { return bail("E_USAGE", `$OATS_INSTANCE_HOME (${home}) is not an instance home under ${root}: ${e.message}`); }
1363
+ const instance = basename(home);
1364
+ let r, line;
1365
+ try {
1366
+ if (verb === "set") {
1367
+ if (operands.length !== 1) return bail("E_BAD_ARGS", `oats instance board set takes one key; ${usage}`);
1368
+ r = setBoardFact(home, { key: operands[0], label: one("label"), value: one("value"), unit: one("unit"), link: one("link") });
1369
+ line = `fact ${r.key} ${r.changed ? "set" : "unchanged"}`;
1370
+ } else if (verb === "unset") {
1371
+ if (operands.length !== 1) return bail("E_BAD_ARGS", `oats instance board unset takes one key; ${usage}`);
1372
+ r = unsetBoardFact(home, operands[0]);
1373
+ line = `fact ${r.key} ${r.changed ? "removed" : "was not set"}`;
1374
+ } else if (values.has("clear")) {
1375
+ if (operands.length || [...values.keys()].some((k) => k !== "clear")) return bail("E_BAD_ARGS", `--clear <id> takes nothing else; ${usage}`);
1376
+ r = clearBoardQuestion(home, one("clear"));
1377
+ line = `question ${r.id} ${r.changed ? "cleared" : "was not open"}`;
1378
+ } else {
1379
+ if (operands.length > 1) return bail("E_BAD_ARGS", `oats instance board ask takes one question (quote it); ${usage}`);
1380
+ // A file's trailing newlines are not content (a heredoc's final LF): they are trimmed before the
1381
+ // context is counted and stored (desktop-rework-lead, a detail filled within contract v4).
1382
+ let context;
1383
+ const file = one("context-file");
1384
+ if (file !== undefined) {
1385
+ try {
1386
+ const st = statSync(file);
1387
+ if (!st.isFile()) return bail("E_BAD_ARGS", `--context-file ${file} is not a regular file`);
1388
+ if (st.size > 64 * 1024) return bail("E_BAD_ARGS", `--context-file ${file} is over 64 KiB; a context is at most 2000 characters`);
1389
+ context = new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(file)).replace(/\n+$/, "");
1390
+ } catch (e) { return bail("E_BAD_ARGS", `--context-file ${file} cannot be read as UTF-8 text (${e.code || e.message})`); }
1391
+ }
1392
+ r = askBoardQuestion(home, { question: operands[0], options: values.get("option") ?? [], id: one("id"), context });
1393
+ line = `question ${r.id} ${r.changed ? "asked: answers arrive typed as" : "is already open: answers arrive typed as"} "${r.id}: <text>"`;
1394
+ }
1395
+ } catch (e) { return bail(e.code || "E_BOARD_FAILED", e.message, e.details); }
1396
+ const { board, changed, ...named } = r;
1397
+ if (JSON_MODE) { jsonOk({ boardApi: BOARD_API, instance, home, ...named, changed, board }); return; }
1398
+ console.log(`${instance}: ${line}`);
1399
+ }
1400
+
1315
1401
  /** A caller that closes its end of stdout or stderr (a tool shell killed, Desktop gone, an ssh
1316
1402
  * session that ended) has only stopped reading: the command goes on to its consistent end, what it
1317
1403
  * can no longer print is dropped, and its exit status is the one it would have had. Unhandled,
@@ -1452,9 +1538,10 @@ async function instanceCmd() {
1452
1538
  const sub = args[1], name = args[2];
1453
1539
  if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
1454
1540
  if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
1541
+ if (sub === "board") return instanceBoardCmd(bail);
1455
1542
  if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
1456
- const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1457
- if (!["git", "diff", "stop", "events", "color", "background", "pin", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1543
+ const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance board set|unset|ask … [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance related-work <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off (deprecated alias of related-work)";
1544
+ if (!["git", "diff", "stop", "events", "color", "background", "pin", "related-work", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1458
1545
  dropAmbientRoot();
1459
1546
  if (sub === "events") {
1460
1547
  // K7: typed producer events, bounded window; nothing inferred.
@@ -1547,20 +1634,21 @@ async function instanceCmd() {
1547
1634
  return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1548
1635
  }
1549
1636
  }
1550
- if (sub === "same-work") {
1551
- // Feature instance-same-work: presentation only, so no plan; addressed as color addresses an instance.
1637
+ // `oats instance same-work` is the verb's deprecated alias (the dispatch said so on stderr): the same command.
1638
+ if (sub === "related-work" || sub === "same-work") {
1639
+ // Feature instance-related-work: presentation only, so no plan; addressed as color addresses an instance.
1552
1640
  const homeOpt = flag("home");
1553
1641
  if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1554
- const sameWorkUsage = "usage: oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1642
+ const relatedWorkUsage = "usage: oats instance related-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1555
1643
  // The words after the instance that are not a flag or the value of --home or --dir: exactly one, on or off.
1556
1644
  const words = [];
1557
1645
  for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
1558
- if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${sameWorkUsage}`);
1646
+ if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${relatedWorkUsage}`);
1559
1647
  let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
1560
1648
  try {
1561
- const r = setInstanceSameWork(dirFlag(), root, name, { home: homeOpt, on: words[0] === "on" });
1649
+ const r = setInstanceRelatedWork(dirFlag(), root, name, { home: homeOpt, on: words[0] === "on" });
1562
1650
  if (JSON_MODE) { jsonOk(r); return; }
1563
- console.log(`${r.instance}: same work ${r.sameWork ? "on" : "off"}`);
1651
+ console.log(`${r.instance}: related work ${r.relatedWork ? "on" : "off"}`);
1564
1652
  return;
1565
1653
  } catch (e) {
1566
1654
  return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
@@ -2916,8 +3004,10 @@ async function spawnCmd() {
2916
3004
  prepared,
2917
3005
  purpose: flag("purpose"), ...(nameFlag !== undefined ? { name: String(nameFlag) } : {}), task: taskText ?? stdinTask, taskFile: stdinTask === undefined ? taskFileFlag : undefined, relation, relativeTo, relativeRoot,
2918
3006
  ...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
2919
- // Feature instance-same-work: the kernel binds it to the parent the new home records, or refuses.
2920
- ...(args.includes("--same-work") ? { sameWork: true } : {}),
3007
+ // Feature instance-related-work: the kernel binds it to the parent the new home records, else to its
3008
+ // sibling, or refuses.
3009
+ // `--same-work` is its deprecated alias (the dispatch said so on stderr).
3010
+ ...(args.includes("--related-work") || args.includes("--same-work") ? { relatedWork: true } : {}),
2921
3011
  // Directory execution uses deployment configuration, not an ambient Git
2922
3012
  // checkout (especially when invoked via --dir from a source instance).
2923
3013
  // An attached instance's repository is the repository of the tree it is attached to (derived by the kernel).
@@ -4217,7 +4307,7 @@ function versionCmd() {
4217
4307
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
4218
4308
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
4219
4309
  // never listed.
4220
- console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1, readerApi: READER_API, sessionViewer: readSessionViewer(), package: OATS_PACKAGE_NAME }));
4310
+ console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1, readerApi: READER_API, boardApi: BOARD_API, sessionViewer: readSessionViewer(), package: OATS_PACKAGE_NAME }));
4221
4311
  return;
4222
4312
  }
4223
4313
  console.log(`${OATS_PACKAGE_NAME} ${OATS_VERSION} (desktop API v1)`);
@@ -4816,6 +4906,9 @@ if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ co
4816
4906
  // A state-changing command's argv against the flags it defines (lib/command-flags.mjs), before it runs
4817
4907
  // and before a --server command is sent: a host on an older OATS would ignore a flag it does not read.
4818
4908
  { const problem = commandArgvProblem(rawArgs); if (problem) cmdFail(problem.code, problem.message, problem.details); }
4909
+ // A deprecated alias of the related-work flag or verb (lib/command-flags.mjs SAME_WORK_ALIASES) works as the
4910
+ // new spelling, and says so once on stderr, never in a --json answer: before it runs or is sent to a host.
4911
+ { const deprecated = sameWorkDeprecation(rawArgs); if (deprecated) process.stderr.write(`oats: ${deprecated}\n`); }
4819
4912
  // Session resume is local only (#1559, D1): a server resumes its own instances.
4820
4913
  if (cmd === "session" && args[1] === "start" && flag("server") !== undefined && args.includes("--resume")) cmdFail("E_BAD_ARGS", RESUME_LOCAL_ONLY);
4821
4914
  if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
@@ -5074,9 +5167,11 @@ Usage:
5074
5167
  [--relation child|sibling|parent|unrelated] anchor with --relative-to (except unrelated);
5075
5168
  [--relative-to <instance>] default: unrelated, top-level
5076
5169
  [--relative-root <agents-root>] disambiguates same-named anchors
5077
- [--same-work] record that the new instance does the same work as
5078
- its parent; clients draw the parent line for it
5079
- (needs a relation that records a parent)
5170
+ [--related-work] record that the new instance does related work with
5171
+ its parent, else its sibling; clients draw the
5172
+ line for it (needs a relation that records a
5173
+ parent or a sibling)
5174
+ [--same-work] deprecated alias of --related-work
5080
5175
  [--work worktree|checkout|attached|workspace|directory] override the soul's work mode
5081
5176
  [--work-dir <owner-work>] attached: the owner's work tree (always a child)
5082
5177
  [--branch <b>] [--base <ref>] worktree branch and starting ref;
@@ -5140,7 +5235,7 @@ Usage:
5140
5235
  a detached external retirement runs
5141
5236
  oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
5142
5237
  [--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
5143
- [--instructions] [--skills] installed capabilities with health, effective
5238
+ [--board] [--instructions] [--skills] installed capabilities with health, effective
5144
5239
  [--composed-skills] [--max-age <s>] layer bindings and activation, declared
5145
5240
  [--json] operations with availability; --home answers the
5146
5241
  running home's recorded modules and their drift
@@ -5148,6 +5243,8 @@ Usage:
5148
5243
  adds the AGENTS.md a spawn of the soul here would write;
5149
5244
  --skills (--soul only) adds the soul's own skills, the
5150
5245
  ones a spawn copies, with each file's text;
5246
+ --board (--home only) adds the agent's board, each
5247
+ fact's history and each question's context;
5151
5248
  --composed-skills (--soul only) adds every skill a spawn
5152
5249
  would give the instance, its capabilities' included
5153
5250
  oats operation run <layer>:<name> run an operation the soul's core capability for that
@@ -5248,6 +5345,15 @@ Usage:
5248
5345
  oats instance attention [--message=<text>] [--clear] [--json]
5249
5346
  run by the agent from its home: "I need a human's
5250
5347
  answer" (waiting --producer agent --reason attention)
5348
+ oats instance board set <key> --label <text> --value <text> [--unit <text>] [--link <https-url>] [--json]
5349
+ oats instance board unset <key> [--json]
5350
+ run by the agent from its home: a fact its person
5351
+ keeps in view on the agent's board (at most 12)
5352
+ oats instance board ask <question> --option <text> --option <text> [--option <text>]… [--id <id>] [--context-file <f>] [--json]
5353
+ oats instance board ask --clear <id> [--json]
5354
+ run by the agent from its home: a question with 2
5355
+ to 4 options (at most 9 open); answers arrive typed
5356
+ as "<id>: <text>"; clear it once read
5251
5357
  oats instance upgrade <instance> --plan [--undo] [--json]
5252
5358
  Preview package module moves and provider adoption; session must be stopped.
5253
5359
  oats instance upgrade <instance> --plan-revision <rev> --idempotency-key <key> [--undo] [--json]
@@ -5268,10 +5374,12 @@ Usage:
5268
5374
  pin the instance at the top of its machine's
5269
5375
  list; shared, as every viewer of the machine
5270
5376
  reads it from the home
5271
- oats instance same-work <instance> on|off [--home <abs>] [--json]
5272
- record that this instance does the same work as
5273
- its parent (on needs a recorded parent); clients
5274
- draw the parent line for it; off removes it
5377
+ oats instance related-work <instance> on|off [--home <abs>] [--json]
5378
+ record that this instance does related work with
5379
+ its parent, else its sibling (on needs one
5380
+ recorded); clients draw the line for it; off
5381
+ removes it; oats instance same-work is its
5382
+ deprecated alias
5275
5383
  oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi]
5276
5384
  [--model <m>] [--launch-config <n>] [--dir <d>] [--json]
5277
5385
  a name for a spawn by this machine's harness, as a
@@ -333,8 +333,9 @@ A self-contained package has an `oats.json`:
333
333
  - an exact name that is `.oats`, `.agents` or `.claude`, or that starts
334
334
  with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
335
335
  `.oats-agents-md`, `.oats-start`, `.oats-attachments`, `.oats-color`,
336
- `.oats-background`, `.oats-pinned` or `.oats-same-work`: the top-level entries the kernel
337
- itself writes in an instance home;
336
+ `.oats-background`, `.oats-pinned`, `.oats-related-work`, `.oats-same-work` (the
337
+ file of the flag `.oats-related-work` replaced, still read while the new one is absent) or
338
+ `.oats-board`: the top-level entries the kernel itself writes in an instance home;
338
339
  - a prefix that starts with `.oats-`.
339
340
 
340
341
  An exact name such as `.oats-aweb` is allowed: it is a provider's
@@ -1244,6 +1245,15 @@ bidi controls (U+202A–202E, U+2066–2069), U+200B, U+2060, U+FEFF and tag
1244
1245
  characters (U+E0000–E007F) are refused, and everything else (emoji ZWJ
1245
1246
  sequences, ZWNJ, LRM, RLM, ALM) is allowed.
1246
1247
 
1248
+ **The board's claim** (feature `instance-board`). An agent that needs a
1249
+ decision between 2 and 4 options asks it on its board, `oats instance board
1250
+ ask <question> --option <text> --option <text>`. While any board question is
1251
+ open, the kernel holds a claim of producer `oats.board`, reason `attention`,
1252
+ whose message is the oldest open question, and the last `oats instance board
1253
+ ask --clear <id>` removes it. It sits beside the agent's own `attention`
1254
+ claim and holds no scheduled wake. The board is in
1255
+ [desktop-cli-api.md](desktop-cli-api.md#the-agents-board-oats-instance-board).
1256
+
1247
1257
  **The Claude Code emitter.** For a Claude instance, oats.core's spawn and
1248
1258
  launch hooks (`bin/oats-core.mjs`, preview-aware) write Claude Code hooks
1249
1259
  into the home's project settings, `<home>/.claude/settings.json`. Each one
@@ -374,7 +374,7 @@
374
374
  "description": "Home entries the kernel owns cannot be declared.",
375
375
  "anyOf": [
376
376
  {"pattern": "^\\.(?:oats|agents|claude)$"},
377
- {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|pinned|same-work)"},
377
+ {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|pinned|same-work|related-work|board)"},
378
378
  {"pattern": "^\\.oats-.*\\*$"}
379
379
  ]
380
380
  }