@awebai/oats 0.69.22 → 0.69.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/bin/oats.mjs +185 -38
  2. package/docs/capabilities.md +365 -7
  3. package/docs/capability-manifest.schema.json +37 -1
  4. package/docs/configuration.md +27 -7
  5. package/docs/container.md +206 -228
  6. package/docs/design/2026-11-19-sandboxes.md +1352 -0
  7. package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
  8. package/docs/design/README.md +7 -0
  9. package/docs/desktop-cli-api.md +673 -81
  10. package/docs/desktop.md +241 -65
  11. package/docs/execution-targets.md +186 -3
  12. package/docs/first-team.md +11 -0
  13. package/docs/implementation.md +6 -2
  14. package/docs/integrations.md +3 -3
  15. package/docs/knowledge-capability-authoring.md +10 -7
  16. package/docs/knowledge-reference/acceptance.md +21 -19
  17. package/docs/knowledge-reference/adoption.md +18 -4
  18. package/docs/knowledge-reference/model.md +11 -9
  19. package/docs/knowledge-reference/package-craft.md +2 -2
  20. package/docs/knowledge-reference/proposal.md +127 -0
  21. package/docs/knowledge-reference/provider-mapping.md +10 -10
  22. package/docs/knowledge-reference/reader-capture.md +26 -22
  23. package/docs/knowledge-theory.md +1 -1
  24. package/docs/knowledge.md +25 -16
  25. package/docs/official-catalog.md +4 -4
  26. package/docs/packages.md +13 -13
  27. package/docs/release-notes/v0.69.23.md +231 -0
  28. package/docs/release-notes/v0.69.24.md +264 -0
  29. package/docs/servers.md +10 -6
  30. package/docs/souls-and-instances.md +96 -22
  31. package/docs/tui.md +25 -4
  32. package/docs/upgrading.md +19 -5
  33. package/docs/workspaces.md +14 -6
  34. package/lib/argv.mjs +6 -2
  35. package/lib/capability-contract.mjs +2 -2
  36. package/lib/capability-show.mjs +11 -1
  37. package/lib/command-flags.mjs +40 -3
  38. package/lib/compile-cache.mjs +1 -1
  39. package/lib/core.mjs +1201 -195
  40. package/lib/errors.mjs +4 -1
  41. package/lib/hook-env.mjs +106 -0
  42. package/lib/host-run.mjs +11 -3
  43. package/lib/instance-board.mjs +337 -0
  44. package/lib/instance-events.mjs +48 -10
  45. package/lib/instance-inspect.mjs +44 -0
  46. package/lib/instance-lifecycle.mjs +34 -18
  47. package/lib/instance-listing.mjs +113 -16
  48. package/lib/instance-related-work.mjs +143 -0
  49. package/lib/kernel-features.mjs +13 -1
  50. package/lib/node-version.mjs +9 -0
  51. package/lib/provider-call-child.mjs +60 -0
  52. package/lib/provider-resume.mjs +83 -0
  53. package/lib/provider-test-seams.mjs +20 -0
  54. package/lib/read-call.mjs +2 -0
  55. package/lib/reserved-launch-env.mjs +8 -1
  56. package/lib/retire-admission.mjs +5 -1
  57. package/lib/schedule.mjs +14 -4
  58. package/lib/servers.mjs +151 -17
  59. package/lib/session-inspect.mjs +104 -13
  60. package/lib/session-providers.mjs +528 -0
  61. package/lib/session-resume.mjs +68 -15
  62. package/lib/stable-node.mjs +3 -0
  63. package/lib/triggers.mjs +3 -1
  64. package/package-catalog.json +3 -3
  65. package/package.json +2 -1
  66. package/packages/client/capability-list.mjs +21 -0
  67. package/packages/client/cli-adapter.mjs +19 -4
  68. package/packages/client/cli-locator.mjs +5 -1
  69. package/packages/client/deployment-data.mjs +27 -3
  70. package/packages/client/deployment-panel.mjs +27 -4
  71. package/packages/client/home-board.mjs +33 -19
  72. package/packages/client/inspect-boundary.mjs +18 -8
  73. package/packages/client/instance-acts.mjs +30 -3
  74. package/packages/client/instance-board.mjs +206 -0
  75. package/packages/client/instance-presentation.mjs +55 -0
  76. package/packages/client/instance-tree.mjs +34 -4
  77. package/packages/client/keymap.mjs +5 -0
  78. package/packages/client/liveness.mjs +15 -4
  79. package/packages/client/mail-contract.mjs +130 -0
  80. package/packages/client/own-codes.mjs +5 -1
  81. package/packages/client/panel-views.mjs +7 -7
  82. package/packages/client/related-work.mjs +84 -0
  83. package/packages/client/remote-roster.mjs +9 -3
  84. package/packages/client/session-backends.mjs +31 -0
  85. package/packages/client/session-start.mjs +18 -6
  86. package/packages/client/spawn-apply-cli.mjs +5 -3
  87. package/packages/client/spawn-apply-contract.mjs +25 -2
  88. package/packages/client/spawn-apply.mjs +5 -1
  89. package/packages/client/spawn-messages.mjs +3 -0
  90. package/packages/client/terminal-contract.mjs +4 -0
  91. package/packages/client/waiting-on-you.mjs +12 -2
  92. package/packages/client/workspace-cli.mjs +13 -2
  93. package/packages/tui/lib/model.mjs +14 -3
  94. package/packages/tui/lib/store.mjs +12 -3
  95. package/skills/oats-getting-started/SKILL.md +11 -8
  96. package/docs/knowledge-reference/harvester.md +0 -109
  97. package/lib/instance-same-work.mjs +0 -67
  98. package/packages/client/same-work.mjs +0 -49
package/bin/oats.mjs CHANGED
@@ -19,24 +19,32 @@
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";
26
26
  import { fileURLToPath } from "node:url";
27
27
  import { performance } from "node:perf_hooks";
28
28
  import { spawnSync as spawnSyncProc } from "node:child_process";
29
+ import { nodeVersionFailure } from "../lib/node-version.mjs";
29
30
  import { enableCliCompileCache } from "../lib/compile-cache.mjs";
30
31
  import { hotImport, hotRead } from "../lib/hot-reads.mjs";
31
32
  import { installStamp } from "../lib/install-stamp.mjs";
32
33
 
34
+ const unsupportedNode = nodeVersionFailure(process.versions.node);
35
+ if (unsupportedNode) {
36
+ if (process.argv.includes("--json")) process.stdout.write(`${JSON.stringify(unsupportedNode)}\n`);
37
+ else process.stderr.write(`${unsupportedNode.error.message}\n`);
38
+ process.exit(1);
39
+ }
40
+
33
41
  // The warm reader's baseline (lib/reader.mjs): its install's stamp before any kernel module loads, so that an
34
42
  // install changed while the kernel loads is never the install the reader believes it answers from.
35
43
  const READER_STAMP = process.argv[2] === "reader" ? installStamp() : null;
36
44
 
37
45
  // Node's compile cache is on before the kernel is parsed (lib/compile-cache.mjs): static imports are
38
- // all parsed and linked before this module's body runs, so they are Node built-ins and the three small
39
- // dependency-free modules above, and the kernel and `yaml` are imported here, in order, once it is on.
46
+ // all parsed and linked before this module's body runs, so they are Node built-ins and the small
47
+ // dependency-free startup modules above, and the kernel and `yaml` are imported here once it is on.
40
48
  enableCliCompileCache();
41
49
  // A hot read (lib/hot-reads.mjs) imports only the leaves it uses, never core.mjs: each line below takes
42
50
  // the leaves its names come from, and every other command imports every module, in this order. A hot
@@ -83,7 +91,7 @@ const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = aw
83
91
  const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
84
92
  const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
85
93
  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"));
94
+ 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
95
  const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
88
96
  const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
89
97
  const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
@@ -91,16 +99,17 @@ const { retireIncompleteProblems } = await kernelImport("retire-incomplete", ()
91
99
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
92
100
  const { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } = await kernelImport("instance-inspect", () => import("../lib/instance-inspect.mjs"));
93
101
  const { readEvents, setWaiting, incarnationOf } = await kernelImport("instance-events", () => import("../lib/instance-events.mjs"));
102
+ const { readBoardDetail, askBoardQuestion, clearBoardQuestion, setBoardFact, unsetBoardFact } = await kernelImport("instance-board", () => import("../lib/instance-board.mjs"));
94
103
  const { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } = await kernelImport("deployments", () => import("../lib/deployments.mjs"));
95
104
  const { observeResolvedDeployment } = await kernelImport("resolved-deployment", () => import("../lib/resolved-deployment.mjs"));
96
105
  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"));
106
+ const { BOARD_API, BUILTIN_SESSION_BACKENDS, KERNEL_FEATURES, READER_API, SESSION_PROVIDER_NAME_RE } = await kernelImport("kernel-features", () => import("../lib/kernel-features.mjs"));
98
107
  const { inheritedContextRefusal } = await kernelImport("captured-context", () => import("../lib/captured-context.mjs"));
99
108
  const { callSession, parseMaxAge, readBudget } = await kernelImport("read-call", () => import("../lib/read-call.mjs"));
100
109
  const { cachedWorkspace, legacyLayoutProblems, statusAnswer, statusView } = await kernelImport("roster-read", () => import("../lib/roster-read.mjs"));
101
110
  const { memberLabel, memberRows, packageRows, standaloneCatalogVersion, standalonePackages, workspaceName, workspaceStatusAnswer, workspaceStatusView } = await kernelImport("workspace-read", () => import("../lib/workspace-read.mjs"));
102
111
  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"));
112
+ 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
113
 
105
114
  const rawArgs = process.argv.slice(2);
106
115
  const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
@@ -517,7 +526,8 @@ function scopeSouls(ctx, { extraRoots = [] } = {}) {
517
526
  const roots = [...new Set([findRoot(ctx), ...extraRoots].filter(Boolean).map((p) => realOrResolved(resolve(p))))];
518
527
  const souls = [];
519
528
  for (const root of roots) {
520
- for (const a of listInstances(root)) {
529
+ // Names only: no session provider is asked.
530
+ for (const a of listInstances(root, undefined, undefined, { askProviders: false })) {
521
531
  const soul = findAgent(root, a.name) || a;
522
532
  const e = soulEntry(soul, root);
523
533
  e.instances = (a.instances || []).map((i) => i.instance);
@@ -618,12 +628,17 @@ async function inspectCmd() {
618
628
  // Feature soul-composed-skills: opt-in, soul subject only; it shares --instructions' one scratch composition.
619
629
  const composedSkills = args.includes("--composed-skills");
620
630
  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/)");
631
+ // Feature instance-board: opt-in, instance subject only; the board's facts with their history and its
632
+ // questions with their context (the rows carry neither).
633
+ const board = args.includes("--board");
634
+ 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
635
  let t = await workspaceTarget(bail, { command: "inspect" });
622
636
  if (t) {
623
637
  if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
624
638
  if (instructions || composedSkills) t = await withComposition(t, { instructions, skills: composedSkills });
625
639
  if (skills) t = await withSkills(t);
626
640
  const doc = inspectDocument(t, { kernel: OATS_VERSION });
641
+ if (board && doc.instance) doc.instance = { ...doc.instance, board: readBoardDetail(t.home) };
627
642
  if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
628
643
  printWorkspaceInspect(doc); return;
629
644
  }
@@ -670,8 +685,20 @@ function printWorkspaceInspect(doc) {
670
685
  if (doc.identity) console.log(` identity: ${servedIdentityLine(doc.identity)}`);
671
686
  for (const l of LAYERS) console.log(` ${l} capability: ${doc.layers[l].id || "none"}`);
672
687
  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(", ")}` : ""}`);
688
+ // Feature session-providers: the backends `--backend` takes here beside tmux, each with the capability that supplies it.
689
+ if (doc.sessionProviders?.length) console.log(` session backends: tmux, ${doc.sessionProviders.map((p) => `${p.name} (${p.capability})`).join(", ")}`);
673
690
  for (const p of doc.problems) console.log(` ! ${p.code}: ${p.message}`);
674
691
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
692
+ const board = doc.instance?.board;
693
+ if (board !== undefined) {
694
+ // The agent's own text: every refused character spelled out, never interpreted (terminalText).
695
+ if (board === null) console.log("\nBoard: none");
696
+ else {
697
+ console.log(`\nBoard: ${board.facts.length} fact${board.facts.length === 1 ? "" : "s"}, ${board.questions.length} open question${board.questions.length === 1 ? "" : "s"}`);
698
+ 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})`));
699
+ 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})`));
700
+ }
701
+ }
675
702
  const composed = doc.souls[0].composedInstructions;
676
703
  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
704
  const composedSkills = doc.souls[0].composedSkills;
@@ -874,6 +901,16 @@ function doctorMachineLaunchConfigs() {
874
901
  return { file, present: true, ok: false, configurations: [], error: e.message };
875
902
  }
876
903
  }
904
+ /** The shared Git version probe reports support, not each repository's recorded fetch mode.
905
+ * An older Git is supported too; this is information, never a warning or a refusal. */
906
+ async function doctorGitInformation() {
907
+ const version = await remoteModule.gitVersion();
908
+ if (!version) return "git-version: Git version could not be read; partial-cache support unknown";
909
+ const mode = remoteModule.keepsPartialCache(version)
910
+ ? "partial caches supported (a remote or an existing cache may still use whole-tree fetches)"
911
+ : `whole-tree fallback (partial caches need Git ${remoteModule.PARTIAL_FETCH_GIT.join(".")} or later)`;
912
+ return `git-version: Git ${terminalText(version.text)}; ${mode}`;
913
+ }
877
914
  /** The machine's resume lock when it needs a person (lib/session-resume.mjs resumeLockProblem), as
878
915
  * doctor's problems: read where a sweep would take it, nothing taken. It is this machine's, the
879
916
  * same from every deployment. */
@@ -897,7 +934,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
897
934
  schemaVersion: 1, workspaceApi: 2, context: ctx,
898
935
  workspace: { file: ws.local.path, ref: ws.local.workspace },
899
936
  workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
900
- information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
937
+ information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), await doctorGitInformation(), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
901
938
  machineLaunchConfigs: doctorMachineLaunchConfigs(),
902
939
  composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
903
940
  ...(problems.length ? { problems } : {}),
@@ -957,7 +994,7 @@ async function doctor(dir) {
957
994
  const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
958
995
  for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
959
996
  if (!soulName) for (const w of doctorCaptureWarnings()) console.log(`\nwarning ${w.code} ${terminalText(w.message)}`);
960
- for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
997
+ for (const line of [await doctorGitInformation(), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
961
998
  for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
962
999
  if (soulName) {
963
1000
  const information = operationalKnowledgeNote(composition, soulName);
@@ -1140,8 +1177,11 @@ function launchPreview(bail) {
1140
1177
  let plan;
1141
1178
  try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true, pane: () => previewPaneEnvironment(meta ? { home, meta } : { deployment: context }) }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
1142
1179
  const { recipe } = plan;
1143
- const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
1144
- const d = describeLaunchCommand(command);
1180
+ // A home on a session provider has no command line: its launch is handed to the provider as data
1181
+ // (`command` and `argv` null, the executable's path null); its environment is listed by name.
1182
+ const onProvider = plan.command === undefined;
1183
+ const command = onProvider ? null : renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
1184
+ const d = onProvider ? { argv: null, environment: [...Object.keys(recipe.hooks?.env || {}).sort().map((name) => ({ name, redacted: true })), ...Object.keys(recipe.env || {}).sort().map((name) => (typeof recipe.env[name] === "string" ? { name, redacted: true } : { name, reference: true }))] } : describeLaunchCommand(command);
1145
1185
  const environment = d.environment.map((e) => e.reference && recipe.env[e.name] && typeof recipe.env[e.name] === "object" ? { name: e.name, ...recipe.env[e.name] } : e);
1146
1186
  jsonOk({ context, selected, ...(plan.warnings?.length ? { warnings: plan.warnings } : {}), selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
1147
1187
  }
@@ -1312,6 +1352,76 @@ function instanceWaitingCmd(sub, bail) {
1312
1352
  } catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
1313
1353
  }
1314
1354
 
1355
+ /** `oats instance board set|unset|ask` (feature instance-board, lib/instance-board.mjs): the agent's own
1356
+ * board, the facts it keeps in view for its person and the questions it asks them. Like `attention`, it
1357
+ * acts only on $OATS_INSTANCE_HOME (no --home, --dir or --server: lib/command-flags.mjs refuses them).
1358
+ * Display only: the kernel routes no answer. */
1359
+ function instanceBoardCmd(bail) {
1360
+ dropAmbientRoot();
1361
+ const verb = args[2];
1362
+ const usage = BOARD_USAGE;
1363
+ const forms = { set: ["label", "value", "unit", "link"], unset: [], ask: ["option", "id", "context-file", "clear"] };
1364
+ if (!Object.hasOwn(forms, verb)) return bail("E_BAD_ARGS", usage);
1365
+ // The form's words after the verb: its value flags (each once, but --option), and its operands. The
1366
+ // dispatch (commandArgvProblem) has refused an unknown flag and an argument too many.
1367
+ const values = new Map(), operands = [];
1368
+ for (let i = 3; i < args.length; i++) {
1369
+ const a = args[i];
1370
+ if (!a.startsWith("--")) { operands.push(a); continue; }
1371
+ const name = a.slice(2);
1372
+ if (name === "json") continue;
1373
+ if (!forms[verb].includes(name)) return bail("E_BAD_ARGS", `oats instance board ${verb}: unknown flag ${a}\n${usage}`);
1374
+ const v = args[i + 1];
1375
+ if (v === undefined || v.startsWith("--")) return bail("E_BAD_ARGS", `--${name} needs a value; ${usage}`);
1376
+ if (values.has(name) && name !== "option") return bail("E_BAD_ARGS", `--${name} is given more than once; ${usage}`);
1377
+ values.set(name, [...(values.get(name) ?? []), v]);
1378
+ i++;
1379
+ }
1380
+ const one = (name) => values.get(name)?.[0];
1381
+ const home = process.env.OATS_INSTANCE_HOME;
1382
+ 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"}`);
1383
+ const root = agentsRootOfHome(home);
1384
+ const { resolveInstance } = await_import_lifecycle();
1385
+ try { resolveInstance(dirFlag(), root, basename(home), { home }); }
1386
+ catch (e) { return bail("E_USAGE", `$OATS_INSTANCE_HOME (${home}) is not an instance home under ${root}: ${e.message}`); }
1387
+ const instance = basename(home);
1388
+ let r, line;
1389
+ try {
1390
+ if (verb === "set") {
1391
+ if (operands.length !== 1) return bail("E_BAD_ARGS", `oats instance board set takes one key; ${usage}`);
1392
+ r = setBoardFact(home, { key: operands[0], label: one("label"), value: one("value"), unit: one("unit"), link: one("link") });
1393
+ line = `fact ${r.key} ${r.changed ? "set" : "unchanged"}`;
1394
+ } else if (verb === "unset") {
1395
+ if (operands.length !== 1) return bail("E_BAD_ARGS", `oats instance board unset takes one key; ${usage}`);
1396
+ r = unsetBoardFact(home, operands[0]);
1397
+ line = `fact ${r.key} ${r.changed ? "removed" : "was not set"}`;
1398
+ } else if (values.has("clear")) {
1399
+ if (operands.length || [...values.keys()].some((k) => k !== "clear")) return bail("E_BAD_ARGS", `--clear <id> takes nothing else; ${usage}`);
1400
+ r = clearBoardQuestion(home, one("clear"));
1401
+ line = `question ${r.id} ${r.changed ? "cleared" : "was not open"}`;
1402
+ } else {
1403
+ if (operands.length > 1) return bail("E_BAD_ARGS", `oats instance board ask takes one question (quote it); ${usage}`);
1404
+ // A file's trailing newlines are not content (a heredoc's final LF): they are trimmed before the
1405
+ // context is counted and stored (desktop-rework-lead, a detail filled within contract v4).
1406
+ let context;
1407
+ const file = one("context-file");
1408
+ if (file !== undefined) {
1409
+ try {
1410
+ const st = statSync(file);
1411
+ if (!st.isFile()) return bail("E_BAD_ARGS", `--context-file ${file} is not a regular file`);
1412
+ if (st.size > 64 * 1024) return bail("E_BAD_ARGS", `--context-file ${file} is over 64 KiB; a context is at most 2000 characters`);
1413
+ context = new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(file)).replace(/\n+$/, "");
1414
+ } catch (e) { return bail("E_BAD_ARGS", `--context-file ${file} cannot be read as UTF-8 text (${e.code || e.message})`); }
1415
+ }
1416
+ r = askBoardQuestion(home, { question: operands[0], options: values.get("option") ?? [], id: one("id"), context });
1417
+ line = `question ${r.id} ${r.changed ? "asked: answers arrive typed as" : "is already open: answers arrive typed as"} "${r.id}: <text>"`;
1418
+ }
1419
+ } catch (e) { return bail(e.code || "E_BOARD_FAILED", e.message, e.details); }
1420
+ const { board, changed, ...named } = r;
1421
+ if (JSON_MODE) { jsonOk({ boardApi: BOARD_API, instance, home, ...named, changed, board }); return; }
1422
+ console.log(`${instance}: ${line}`);
1423
+ }
1424
+
1315
1425
  /** A caller that closes its end of stdout or stderr (a tool shell killed, Desktop gone, an ssh
1316
1426
  * session that ended) has only stopped reading: the command goes on to its consistent end, what it
1317
1427
  * can no longer print is dropped, and its exit status is the one it would have had. Unhandled,
@@ -1452,9 +1562,10 @@ async function instanceCmd() {
1452
1562
  const sub = args[1], name = args[2];
1453
1563
  if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
1454
1564
  if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
1565
+ if (sub === "board") return instanceBoardCmd(bail);
1455
1566
  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);
1567
+ 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)";
1568
+ if (!["git", "diff", "stop", "events", "color", "background", "pin", "related-work", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1458
1569
  dropAmbientRoot();
1459
1570
  if (sub === "events") {
1460
1571
  // K7: typed producer events, bounded window; nothing inferred.
@@ -1547,20 +1658,21 @@ async function instanceCmd() {
1547
1658
  return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1548
1659
  }
1549
1660
  }
1550
- if (sub === "same-work") {
1551
- // Feature instance-same-work: presentation only, so no plan; addressed as color addresses an instance.
1661
+ // `oats instance same-work` is the verb's deprecated alias (the dispatch said so on stderr): the same command.
1662
+ if (sub === "related-work" || sub === "same-work") {
1663
+ // Feature instance-related-work: presentation only, so no plan; addressed as color addresses an instance.
1552
1664
  const homeOpt = flag("home");
1553
1665
  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]";
1666
+ const relatedWorkUsage = "usage: oats instance related-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1555
1667
  // The words after the instance that are not a flag or the value of --home or --dir: exactly one, on or off.
1556
1668
  const words = [];
1557
1669
  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}`);
1670
+ if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${relatedWorkUsage}`);
1559
1671
  let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
1560
1672
  try {
1561
- const r = setInstanceSameWork(dirFlag(), root, name, { home: homeOpt, on: words[0] === "on" });
1673
+ const r = setInstanceRelatedWork(dirFlag(), root, name, { home: homeOpt, on: words[0] === "on" });
1562
1674
  if (JSON_MODE) { jsonOk(r); return; }
1563
- console.log(`${r.instance}: same work ${r.sameWork ? "on" : "off"}`);
1675
+ console.log(`${r.instance}: related work ${r.relatedWork ? "on" : "off"}`);
1564
1676
  return;
1565
1677
  } catch (e) {
1566
1678
  return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
@@ -2515,6 +2627,17 @@ async function capabilityShowCmd(bail) {
2515
2627
  }
2516
2628
  for (const p of doc.triggerSourceProblems ?? []) console.log(` trigger source problem: ${p.pointer} — ${safeText(p.message, 300)}`);
2517
2629
  }
2630
+ if (doc.sessionProviders !== undefined) {
2631
+ // As declared (a malformed declaration is shown, never refused), made safe to print.
2632
+ const { safeText } = await import("../lib/refused-text.mjs");
2633
+ const decl = doc.sessionProviders && typeof doc.sessionProviders === "object" && !Array.isArray(doc.sessionProviders) ? doc.sessionProviders : null;
2634
+ console.log(decl && Object.keys(decl).length ? " session providers:" : ` session providers: ${decl ? "(none)" : "(malformed — see session provider problems)"}`);
2635
+ for (const [n, provider] of Object.entries(decl ?? {})) {
2636
+ const o = provider && typeof provider === "object" ? provider : {};
2637
+ console.log(` ${safeText(n, 60)} harnesses ${Array.isArray(o.harnesses) ? o.harnesses.map((h) => safeText(String(h), 40)).join(",") : "?"}${typeof o.description === "string" ? ` — ${safeText(o.description, 200)}` : ""}`);
2638
+ }
2639
+ for (const p of doc.sessionProviderProblems ?? []) console.log(` session provider problem: ${p.pointer} — ${safeText(p.message, 300)}`);
2640
+ }
2518
2641
  for (const p of doc.problems) console.log(` problem: ${p.code}${p.path ? ` ${p.path}` : ""} — ${p.message}`);
2519
2642
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
2520
2643
  console.log(`\n a file's text: oats capabilities show ${doc.name}${doc.kind === "package" ? ` --package ${doc.package}` : ""} --file <path>`);
@@ -2643,7 +2766,7 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
2643
2766
  if (a.description) console.log(` ${a.description}`);
2644
2767
  for (const i of a.instances) {
2645
2768
  // Feature instance-background: the row is marked; it is listed like any other.
2646
- console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
2769
+ console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"}${i.session ? `, on ${i.backend}` : ""})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
2647
2770
  { const lost = lostLine(i); if (lost) console.log(` ${lost}`); }
2648
2771
  // Feature waiting-on-you: non-null only on a running row; the reader has
2649
2772
  // already validated the message (one line, no control characters).
@@ -2710,7 +2833,9 @@ async function spawnCmd() {
2710
2833
  const yolo = yoloFlag();
2711
2834
  { const herdr = herdrSpawnFlag(); if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); } }
2712
2835
  const backend = valueFlag("backend");
2713
- if (backend !== undefined && backend !== "tmux") bail("E_BAD_ARGS", "--backend must be tmux");
2836
+ // tmux, or a session provider one of the soul's capabilities declares: the kernel resolves the name
2837
+ // against the instance's modules (E_BACKEND_UNKNOWN names the backends available there).
2838
+ if (backend !== undefined && !SESSION_PROVIDER_NAME_RE.test(backend)) bail("E_BAD_ARGS", "--backend must be tmux or a session provider's name (1 to 40 lowercase letters, digits and dashes)");
2714
2839
  const requestedWork = valueFlag("work");
2715
2840
  const workDir = valueFlag("work-dir"), branch = valueFlag("branch"), repo = valueFlag("repo");
2716
2841
  const checkDirectoryOptions = (work) => {
@@ -2916,8 +3041,10 @@ async function spawnCmd() {
2916
3041
  prepared,
2917
3042
  purpose: flag("purpose"), ...(nameFlag !== undefined ? { name: String(nameFlag) } : {}), task: taskText ?? stdinTask, taskFile: stdinTask === undefined ? taskFileFlag : undefined, relation, relativeTo, relativeRoot,
2918
3043
  ...(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 } : {}),
3044
+ // Feature instance-related-work: the kernel binds it to the parent the new home records, else to its
3045
+ // sibling, or refuses.
3046
+ // `--same-work` is its deprecated alias (the dispatch said so on stderr).
3047
+ ...(args.includes("--related-work") || args.includes("--same-work") ? { relatedWork: true } : {}),
2921
3048
  // Directory execution uses deployment configuration, not an ambient Git
2922
3049
  // checkout (especially when invoked via --dir from a source instance).
2923
3050
  // An attached instance's repository is the repository of the tree it is attached to (derived by the kernel).
@@ -2977,7 +3104,8 @@ async function spawnCmd() {
2977
3104
  // #917: what this spawn's start did with Claude's development-channel prompt, as a start answers it.
2978
3105
  ...(r.launchPrompts ? { launchPrompts: r.launchPrompts } : {}),
2979
3106
  ...(wakeSchedule ? { wakeSchedule } : {}), ...(wakeScheduleError ? { wakeScheduleError } : {}),
2980
- tmux: r.tmux || null, backend: "tmux", repo: r.repo || null, harness: r.harness || null,
3107
+ // A home on a session provider carries its backend's name and `session` ({ provider, endpoint }), and no tmux.
3108
+ tmux: r.tmux || null, backend: r.session ? r.backend : "tmux", ...(r.session ? { session: r.session } : {}), repo: r.repo || null, harness: r.harness || null,
2981
3109
  model: r.model || null, parent: r.parentInstance || null,
2982
3110
  sibling: r.siblingInstance || null, relation: r.relation || null,
2983
3111
  spawnOrigin: r.spawnOrigin, attach: r.attach,
@@ -2995,7 +3123,7 @@ async function spawnCmd() {
2995
3123
  });
2996
3124
  return;
2997
3125
  }
2998
- console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
3126
+ console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? (r.session ? ` — ${r.backend} session` : ` — tmux window "${r.tmux.window}"`) : " — not launched"}`);
2999
3127
  console.log(` home: ${shortPath(r.home)}`);
3000
3128
  if (r.background === true) console.log(` list: background (from the ${r.backgroundFrom === "flag" ? "--background flag" : "soul"})`);
3001
3129
  { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
@@ -3005,7 +3133,8 @@ async function spawnCmd() {
3005
3133
  if (wakeScheduleError) console.error(` wake: NOT saved — ${wakeScheduleError.message} (the instance is created and launched; add the wake by hand with oats schedule add)`);
3006
3134
  if (!r.launched) console.log(` launch: oats session start --home ${shellQuote(r.home)}`);
3007
3135
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
3008
- console.log(` attach: ${r.attach}`);
3136
+ if (r.attach) console.log(` attach: ${r.attach}`);
3137
+ else if (r.session) console.log(` open: oats session inspect --home ${shellQuote(r.home)} --json (its \`open\` link; ${terminalText(r.backend)} has no terminal to attach to)`);
3009
3138
  }
3010
3139
 
3011
3140
  /** The line naming the branch a FAILED_SPAWN_BRANCH_LEFT item speaks of, on a line of its own: the item names
@@ -3496,7 +3625,7 @@ async function sessionCmd() {
3496
3625
  const deployment = flag("deployment");
3497
3626
  if (deployment === true || (typeof deployment === "string" && !deployment.trim())) throw Object.assign(new Error(`--deployment needs a deployment directory\n${usage}`), { code: "E_BAD_ARGS" });
3498
3627
  const { resumeSessions } = await import("../lib/session-resume.mjs");
3499
- const answer = await resumeSessions({ deployment, plan: args.includes("--plan"), kernel: { execPath: process.execPath, bin: CLI_BIN } });
3628
+ const answer = await resumeSessions({ deployment, plan: args.includes("--plan"), askProviders: !args.includes("--without-provider-inspect"), kernel: { execPath: process.execPath, bin: CLI_BIN } });
3500
3629
  if (JSON_MODE) { jsonOk(answer); return; }
3501
3630
  for (const d of answer.deployments) console.log(`${d.deployment}: ${d.swept ? "swept" : `not swept (${d.reason}${d.code ? `, ${d.code}` : ""})`}`);
3502
3631
  for (const r of answer.rows) console.log(` ${r.instance} ${answer.plan ? "would be " : ""}${r.outcome}${r.reason ? ` (${r.reason}${r.code ? `, ${r.code}` : ""})` : ""}${r.message ? `: ${terminalText(r.message)}` : ""}`);
@@ -4217,7 +4346,7 @@ function versionCmd() {
4217
4346
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
4218
4347
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
4219
4348
  // 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 }));
4349
+ console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: BUILTIN_SESSION_BACKENDS, 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
4350
  return;
4222
4351
  }
4223
4352
  console.log(`${OATS_PACKAGE_NAME} ${OATS_VERSION} (desktop API v1)`);
@@ -4697,7 +4826,7 @@ async function serverRouteCmd() {
4697
4826
  // The host's answer decides, not the flag: one that spawned is reported as the spawn it was.
4698
4827
  if (cmd === "spawn" && rest.includes("--preview") && r.preview === true) printSpawnPreview(r, { server: id, soulFetched: r.soulFetched === true });
4699
4828
  else if (cmd === "spawn") {
4700
- console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}` : " — not launched"}`);
4829
+ console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? (r.session ? ` — ${terminalText(r.backend)} session on ${r.target.sshHost}` : ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}`) : " — not launched"}`);
4701
4830
  console.log(` remote home: ${r.home}`);
4702
4831
  { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
4703
4832
  console.log(` route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
@@ -4816,6 +4945,9 @@ if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ co
4816
4945
  // A state-changing command's argv against the flags it defines (lib/command-flags.mjs), before it runs
4817
4946
  // and before a --server command is sent: a host on an older OATS would ignore a flag it does not read.
4818
4947
  { const problem = commandArgvProblem(rawArgs); if (problem) cmdFail(problem.code, problem.message, problem.details); }
4948
+ // A deprecated alias of the related-work flag or verb (lib/command-flags.mjs SAME_WORK_ALIASES) works as the
4949
+ // new spelling, and says so once on stderr, never in a --json answer: before it runs or is sent to a host.
4950
+ { const deprecated = sameWorkDeprecation(rawArgs); if (deprecated) process.stderr.write(`oats: ${deprecated}\n`); }
4819
4951
  // Session resume is local only (#1559, D1): a server resumes its own instances.
4820
4952
  if (cmd === "session" && args[1] === "start" && flag("server") !== undefined && args.includes("--resume")) cmdFail("E_BAD_ARGS", RESUME_LOCAL_ONLY);
4821
4953
  if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
@@ -5074,9 +5206,11 @@ Usage:
5074
5206
  [--relation child|sibling|parent|unrelated] anchor with --relative-to (except unrelated);
5075
5207
  [--relative-to <instance>] default: unrelated, top-level
5076
5208
  [--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)
5209
+ [--related-work] record that the new instance does related work with
5210
+ its parent, else its sibling; clients draw the
5211
+ line for it (needs a relation that records a
5212
+ parent or a sibling)
5213
+ [--same-work] deprecated alias of --related-work
5080
5214
  [--work worktree|checkout|attached|workspace|directory] override the soul's work mode
5081
5215
  [--work-dir <owner-work>] attached: the owner's work tree (always a child)
5082
5216
  [--branch <b>] [--base <ref>] worktree branch and starting ref;
@@ -5092,7 +5226,7 @@ Usage:
5092
5226
  is a unit (a conflicting --harness is refused)
5093
5227
  [--model <id>|@native-default] override the selected model; @native-default
5094
5228
  selects the harness's own model default
5095
- [--backend tmux] [--yolo|--no-yolo] session backend and launch permission option
5229
+ [--backend tmux|<provider>] [--yolo|--no-yolo] session backend (tmux, or a session provider of the soul's capabilities) and launch permission option
5096
5230
  [--background|--no-background] list the instance under Background (presentation
5097
5231
  only); default: the soul's background:, else no
5098
5232
  [--no-launch] [--json] scaffold without launching; JSON result envelope
@@ -5140,7 +5274,7 @@ Usage:
5140
5274
  a detached external retirement runs
5141
5275
  oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
5142
5276
  [--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
5143
- [--instructions] [--skills] installed capabilities with health, effective
5277
+ [--board] [--instructions] [--skills] installed capabilities with health, effective
5144
5278
  [--composed-skills] [--max-age <s>] layer bindings and activation, declared
5145
5279
  [--json] operations with availability; --home answers the
5146
5280
  running home's recorded modules and their drift
@@ -5148,6 +5282,8 @@ Usage:
5148
5282
  adds the AGENTS.md a spawn of the soul here would write;
5149
5283
  --skills (--soul only) adds the soul's own skills, the
5150
5284
  ones a spawn copies, with each file's text;
5285
+ --board (--home only) adds the agent's board, each
5286
+ fact's history and each question's context;
5151
5287
  --composed-skills (--soul only) adds every skill a spawn
5152
5288
  would give the instance, its capabilities' included
5153
5289
  oats operation run <layer>:<name> run an operation the soul's core capability for that
@@ -5248,6 +5384,15 @@ Usage:
5248
5384
  oats instance attention [--message=<text>] [--clear] [--json]
5249
5385
  run by the agent from its home: "I need a human's
5250
5386
  answer" (waiting --producer agent --reason attention)
5387
+ oats instance board set <key> --label <text> --value <text> [--unit <text>] [--link <https-url>] [--json]
5388
+ oats instance board unset <key> [--json]
5389
+ run by the agent from its home: a fact its person
5390
+ keeps in view on the agent's board (at most 12)
5391
+ oats instance board ask <question> --option <text> --option <text> [--option <text>]… [--id <id>] [--context-file <f>] [--json]
5392
+ oats instance board ask --clear <id> [--json]
5393
+ run by the agent from its home: a question with 2
5394
+ to 4 options (at most 9 open); answers arrive typed
5395
+ as "<id>: <text>"; clear it once read
5251
5396
  oats instance upgrade <instance> --plan [--undo] [--json]
5252
5397
  Preview package module moves and provider adoption; session must be stopped.
5253
5398
  oats instance upgrade <instance> --plan-revision <rev> --idempotency-key <key> [--undo] [--json]
@@ -5268,10 +5413,12 @@ Usage:
5268
5413
  pin the instance at the top of its machine's
5269
5414
  list; shared, as every viewer of the machine
5270
5415
  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
5416
+ oats instance related-work <instance> on|off [--home <abs>] [--json]
5417
+ record that this instance does related work with
5418
+ its parent, else its sibling (on needs one
5419
+ recorded); clients draw the line for it; off
5420
+ removes it; oats instance same-work is its
5421
+ deprecated alias
5275
5422
  oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi]
5276
5423
  [--model <m>] [--launch-config <n>] [--dir <d>] [--json]
5277
5424
  a name for a spawn by this machine's harness, as a