@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/lib/servers.mjs CHANGED
@@ -28,15 +28,18 @@ import { readWaitingClaim, validWaitingMessage } from "./instance-events.mjs";
28
28
  import { readRetireState } from "./retire-state.mjs";
29
29
  import { SESSION_END } from "./session-resume-contract.mjs";
30
30
  import { paletteColor } from "./instance-color.mjs";
31
+ import { relatedWorkBinding } from "./instance-related-work.mjs";
31
32
  import { readSpawnedBy } from "./spawned-by.mjs";
32
33
  import { withDirLock } from "./dir-lock.mjs";
33
34
  import { shellWord } from "./shell-word.mjs";
34
35
  import { DETACH_KEY_FEATURE, requireDetachKey } from "./session-viewer.mjs";
35
36
  import { LOGIN_CAPTURE_MAX_BYTES, LOGIN_SHELLS, loginPathEmitter, quoteFor, readLoginFrame } from "./login-environment.mjs";
36
37
  import { compareSemver } from "./semver.mjs";
37
- import { SPAWN_TASK_STDIN_FEATURE } from "./kernel-features.mjs";
38
+ import { SESSION_PROVIDERS_FEATURE, SPAWN_TASK_STDIN_FEATURE } from "./kernel-features.mjs";
39
+ import { relayedProviderRow, withoutRelayedEndpoint } from "./session-providers.mjs";
38
40
  import { sameRepo } from "./repo-moves.mjs";
39
41
  import { OATS_PACKAGE_NAME } from "./version.mjs";
42
+ import { readRemoteBoard } from "./instance-board.mjs";
40
43
  export { compareSemver } from "./semver.mjs";
41
44
 
42
45
  const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
@@ -328,9 +331,24 @@ export function operatorSshArgv(alias, words) {
328
331
 
329
332
  // ------------------------------------------------------------------ running
330
333
 
334
+ /** A host's envelope without a session provider's locator (feature session-providers): a provider
335
+ * home's endpoint, and the thread id a status row carries on its own host, are for the host where
336
+ * the home lives, and are never relayed. An answer's own `session` (a spawn's, a start's, an
337
+ * inspect's) and every roster row's are cut to `{ provider }`, whatever the host sent. */
338
+ function withoutProviderLocators(envelope) {
339
+ const result = envelope?.result;
340
+ if (envelope?.ok !== true || !result || typeof result !== "object") return envelope;
341
+ const rows = (agents) => agents.map((a) => (a && Array.isArray(a.instances) ? { ...a, instances: a.instances.map(withoutRelayedEndpoint) } : a));
342
+ const roster = (doc) => (doc && Array.isArray(doc.agents) ? { ...doc, agents: rows(doc.agents) } : doc);
343
+ const cut = Array.isArray(result.roots) ? { ...result, roots: result.roots.map(roster) } : roster(withoutRelayedEndpoint(result));
344
+ return { ...envelope, result: cut };
345
+ }
331
346
  /** Parse the remote kernel's JSON envelope; anything else on stdout is a
332
347
  * routing failure with the raw text attached, never a guess. */
333
348
  export function parseRemoteEnvelope(stdout) {
349
+ return withoutProviderLocators(parseRemoteEnvelopeAsSent(stdout));
350
+ }
351
+ function parseRemoteEnvelopeAsSent(stdout) {
334
352
  const text = String(stdout || "").trim();
335
353
  let doc;
336
354
  try {
@@ -497,6 +515,7 @@ export function dropRemoteProbes(serverId) {
497
515
 
498
516
  function probeRemote(target, io) {
499
517
  const { envelope } = runRemote(target, ["version", "--json"], { ...io, timeoutMs: 60000 });
518
+ if (!envelope.ok) throw relayedFailure(envelope, "version --json");
500
519
  const probe = envelope.result || {};
501
520
  if (probe.desktopApi !== 1 || typeof probe.version !== "string") {
502
521
  throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats at ${target.sshHost} answered an unknown version payload: ${JSON.stringify(probe).slice(0, 200)}`);
@@ -559,7 +578,10 @@ export function checkRemoteSupport(remote, target, oatsArgs, roster) {
559
578
  // A wake schedule at spawn is saved by the host: it must advertise schedules.
560
579
  if (["--wake-json", "--wake-every", "--wake-cron"].some((f) => oatsArgs.includes(f)) && !remote.features.includes("schedule")) refuse("a wake schedule at spawn (the host must advertise the schedule feature)");
561
580
  const backend = flagOf("--backend");
562
- if (backend && !remote.sessionBackends.includes(backend)) refuse(`session backend ${backend}`);
581
+ // A backend that is none of the host's built-in ones is a session provider (a capability's, resolved
582
+ // against the instance's modules there): relayed only to a host that lists the feature. A host
583
+ // without it knows tmux alone, and is never asked for another.
584
+ if (backend && !remote.sessionBackends.includes(backend) && !remote.features.includes(SESSION_PROVIDERS_FEATURE)) refuse(`session backend ${backend} (a session provider: the host must advertise ${SESSION_PROVIDERS_FEATURE})`);
563
585
  if (oatsArgs.includes("--yolo") && !remote.launchOptions.includes("yolo")) refuse("the yolo launch option");
564
586
  return { harness, backend, yolo: oatsArgs.includes("--yolo") };
565
587
  }
@@ -744,8 +766,9 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
744
766
  // Feature instance-background: an older host would refuse the flag as unknown, or place the instance
745
767
  // in the main list; either is said here, before anything is sent.
746
768
  if (oatsArgs.includes("--background") || oatsArgs.includes("--no-background")) requireRemoteFeature(remote, target, "instance-background");
747
- // A host without instance-same-work would refuse the flag as unknown: it is never sent there.
748
- if (oatsArgs.includes("--same-work")) requireRemoteFeature(remote, target, "instance-same-work");
769
+ // Feature instance-related-work: the flag as this host takes it (relatedWorkSpawnArgs), or refused here,
770
+ // before anything is sent; never dropped.
771
+ if (oatsArgs.includes("--related-work") || oatsArgs.includes("--same-work")) oatsArgs = relatedWorkSpawnArgs(remote, target, oatsArgs, status.result);
749
772
  const spawnOnHost = (args) => runRemote(target, json(withScope(["spawn", ...hostHarnessArgs(remote, args)])), { ...io, input: task });
750
773
  // A spawn that brings neither a decision nor a key is bound here: the host's preview decides, and
751
774
  // the apply carries that decision and a key of this request, so the same spawn sent again with
@@ -884,7 +907,7 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
884
907
  }
885
908
  if (cmd === "status") {
886
909
  const { envelope, stderr } = runRemote(target, json(withScope(["status", ...oatsArgs])), io);
887
- return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, target, snapshots: listSnapshots(serverId) } } : envelope, stderr };
910
+ return { envelope: envelope.ok ? { ...envelope, result: { ...relatedWorkRows(envelope.result), server: serverId, target, snapshots: listSnapshots(serverId) } } : envelope, stderr };
888
911
  }
889
912
  if (OPERATIONS_COMMANDS.has(cmd)) {
890
913
  // The operations contract (inspect, operation run): the
@@ -914,6 +937,8 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
914
937
  if (cmd === "inspect" && args.includes("--instructions")) requireRemoteFeature(remote, target, "soul-composed-instructions");
915
938
  // `inspect --skills` (feature soul-skills): the same, for the soul's own skills.
916
939
  if (cmd === "inspect" && args.includes("--skills")) requireRemoteFeature(remote, target, "soul-skills");
940
+ // `inspect --board` (feature instance-board): the same, for the board's history and context.
941
+ if (cmd === "inspect" && args.includes("--board")) requireRemoteFeature(remote, target, "instance-board");
917
942
  // `inspect --composed-skills` (feature soul-composed-skills): the same, for every skill a spawn would give.
918
943
  if (cmd === "inspect" && args.includes("--composed-skills")) requireRemoteFeature(remote, target, "soul-composed-skills");
919
944
  const scoped = args.includes("--dir") || args.includes("--home") ? args : [...args, "--dir", target.workspace];
@@ -923,6 +948,94 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
923
948
  throw serverError("E_USAGE", `--server routes spawn, retire, status, session, okf harvest, schedule, inspect, operation, readiness and instance only (not ${cmd})`);
924
949
  }
925
950
 
951
+ // ------------------------------------------------- related work on an older host
952
+
953
+ /** Whether a host's `features` say it is a kernel from before the related-work rename: it advertises
954
+ * instance-same-work (the flag by its old name, a parent binding only) and not instance-related-work. Only
955
+ * there is the flag sent by its old spelling, and a sibling binding refused. */
956
+ export function sameWorkOnly(features) {
957
+ return Array.isArray(features) && features.includes("instance-same-work") && !features.includes("instance-related-work");
958
+ }
959
+
960
+ /** The binding a routed spawn of `oatsArgs` would record, read from its arguments and the host's roster
961
+ * `roster` (its `status --json`): "parent" for `--parent`, `--relation child` and an attached spawn; for
962
+ * `--relation sibling|parent`, the binding the anchor's row gives (relatedWorkBinding, as the host's kernel
963
+ * chooses it): "sibling" when any row of that name gives a sibling, so that a sibling binding is never sent
964
+ * as a parent one; null when nothing here says (no relation, an anchor the roster does not list): the host
965
+ * answers that spawn itself. */
966
+ function routedSpawnBinding(oatsArgs, roster) {
967
+ const valueOf = (flag) => { const i = oatsArgs.indexOf(flag); return i >= 0 && oatsArgs[i + 1] && !oatsArgs[i + 1].startsWith("--") ? oatsArgs[i + 1] : undefined; };
968
+ const relation = valueOf("--relation"), relativeTo = valueOf("--relative-to");
969
+ if (valueOf("--parent") !== undefined || relation === "child") return "parent";
970
+ if ((relation === "sibling" || relation === "parent") && relativeTo) {
971
+ const anchors = (roster?.agents || []).flatMap((a) => a.instances || []).filter((i) => i?.instance === relativeTo);
972
+ // A sibling shares the anchor's parent, else links to the anchor; a new parent takes the anchor's slot.
973
+ const kinds = anchors.map((a) => relatedWorkBinding(relation === "sibling" ? { parentInstance: a.parentInstance, siblingInstance: a.instance } : a));
974
+ if (kinds.some((b) => b?.sibling)) return "sibling";
975
+ return kinds.some((b) => b?.parent) ? "parent" : null;
976
+ }
977
+ return !relation && valueOf("--work") === "attached" ? "parent" : null;
978
+ }
979
+
980
+ /** `oatsArgs` of a routed spawn that carries `--related-work` or its deprecated alias `--same-work`, as the
981
+ * host takes it: by a host that advertises instance-related-work, as `--related-work` (so that it says no
982
+ * deprecation of its own); by a host with only instance-same-work (sameWorkOnly), as `--same-work` when
983
+ * the spawn's binding is a parent or not known here (the host then refuses a spawn that records no parent
984
+ * itself), and refused with E_REMOTE_INCOMPATIBLE for a sibling binding, which that kernel cannot record;
985
+ * any other host refuses it (E_REMOTE_INCOMPATIBLE). */
986
+ function relatedWorkSpawnArgs(remote, target, oatsArgs, roster) {
987
+ const spelled = (flag) => oatsArgs.map((a) => (a === "--related-work" || a === "--same-work" ? flag : a)).filter((a, i, all) => a !== flag || all.indexOf(flag) === i);
988
+ if (remote.features.includes("instance-related-work")) return spelled("--related-work");
989
+ if (!sameWorkOnly(remote.features)) requireRemoteFeature(remote, target, "instance-related-work");
990
+ if (routedSpawnBinding(oatsArgs, roster) === "sibling") throw siblingNeedsRelatedWork(remote, target);
991
+ return spelled("--same-work");
992
+ }
993
+
994
+ const siblingNeedsRelatedWork = (remote, target) => serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise instance-related-work, which a sibling binding needs (its instance-same-work binds a parent only); upgrade it there; nothing was sent`);
995
+
996
+ /** `args` of `instance related-work <instance> on|off …` (after `instance`, the route's --home pushed) for a
997
+ * host with only instance-same-work: the verb by its old name. `on` for an instance whose row on the host
998
+ * records no parent and a sibling is refused (E_REMOTE_INCOMPATIBLE): that kernel binds a parent only.
999
+ * `off`, and `on` for a row with a parent or none the roster lists, go as asked: the host answers them. */
1000
+ function relatedWorkSurfaceArgs(remote, target, args, io) {
1001
+ // The state is the one word after the instance that is no flag and no flag's value (as bin reads it).
1002
+ const words = [];
1003
+ for (let i = 2; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
1004
+ if (words.length === 1 && words[0] === "on") {
1005
+ const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
1006
+ const home = valueOf("--home");
1007
+ // The lineage is read in the scope the verb is sent to: its explicit --dir, else the registered workspace.
1008
+ const status = runRemote(target, ["status", "--json", "--dir", valueOf("--dir") ?? target.workspace], { ...io, input: undefined }).envelope;
1009
+ if (!status.ok) throw serverError(status.error?.code || "E_REMOTE", `cannot read ${args[1]} on ${target.sshHost} before setting its related work: ${status.error?.message || "status failed"}`);
1010
+ const row = (status.result?.agents || []).flatMap((a) => a.instances || []).find((i) => i?.home && resolve(i.home) === resolve(home));
1011
+ if (row && relatedWorkBinding(row)?.sibling) throw siblingNeedsRelatedWork(remote, target);
1012
+ }
1013
+ return ["same-work"];
1014
+ }
1015
+
1016
+ /** A host's `status --json` result with each instance row's flag in this kernel's words, as rowRelatedWork
1017
+ * reads it (the roster's rule): `relatedWork: true` or no key, and `sameWork: true` only beside it.
1018
+ * Everything else is the host's answer as it gave it. */
1019
+ function relatedWorkRows(result) {
1020
+ if (!result || typeof result !== "object" || !Array.isArray(result.agents)) return result;
1021
+ const features = hostFeatures(result);
1022
+ const row = (i) => {
1023
+ if (!i || typeof i !== "object") return i;
1024
+ const { sameWork: _sameWork, relatedWork: _relatedWork, ...rest } = i;
1025
+ return { ...rest, ...rowRelatedWork(i, features) };
1026
+ };
1027
+ return { ...result, agents: result.agents.map((a) => (a && typeof a === "object" && Array.isArray(a.instances) ? { ...a, instances: a.instances.map(row) } : a)) };
1028
+ }
1029
+
1030
+ /** The answer of an older host's `instance same-work`, `{ instance, sameWork }`, in this kernel's words, as
1031
+ * this kernel's verb answers: `relatedWork` beside its `sameWork` (an older host binds a parent only). A
1032
+ * refusal is relayed as is. */
1033
+ function relatedWorkAnswer(envelope) {
1034
+ if (!envelope?.ok || !envelope.result || typeof envelope.result !== "object" || !Object.hasOwn(envelope.result, "sameWork")) return envelope;
1035
+ const on = envelope.result.sameWork === true;
1036
+ return { ...envelope, result: { ...envelope.result, relatedWork: on, sameWork: on } };
1037
+ }
1038
+
926
1039
  /** The Desktop's per-instance reads and lifecycle plans, as the host's kernel
927
1040
  * answers them: the feature and API number the host must advertise first. */
928
1041
  const HOST_SURFACES = {
@@ -938,8 +1051,9 @@ const HOST_SURFACES = {
938
1051
  "instance background": { feature: "instance-background" },
939
1052
  // Feature instance-pin: the feature alone, as instance background.
940
1053
  "instance pin": { feature: "instance-pin" },
941
- // Feature instance-same-work: the feature alone, as instance color.
942
- "instance same-work": { feature: "instance-same-work" },
1054
+ // Feature instance-related-work: the feature alone, as instance color; a host with only instance-same-work
1055
+ // is asked by the old name (relatedWorkSurfaceArgs).
1056
+ "instance related-work": { feature: "instance-related-work" },
943
1057
  };
944
1058
 
945
1059
  function requireSurface(remote, target, surface) {
@@ -948,16 +1062,18 @@ function requireSurface(remote, target, surface) {
948
1062
  }
949
1063
  }
950
1064
 
951
- /** `readiness`, `instance events|git|diff|stop|color|background|pin|same-work` and `retire --plan` on the
1065
+ /** `readiness`, `instance events|git|diff|stop|color|background|pin|related-work` and `retire --plan` on the
952
1066
  * host: the instance is addressed as every routed session command addresses
953
1067
  * it (its name through a saved route or the host's roster, or an exact
954
1068
  * --home), the scope is an explicit --dir on the host or the registered
955
1069
  * workspace (readiness of a home is its own context), and the host's
956
1070
  * envelope is relayed unchanged. */
957
1071
  function routeHostSurface(serverId, cmd, oatsArgs, io) {
1072
+ // `instance same-work` is the deprecated alias of `instance related-work` (the dispatch said so): one route.
1073
+ if (cmd === "instance" && oatsArgs[0] === "same-work") oatsArgs = ["related-work", ...oatsArgs.slice(1)];
958
1074
  const key = cmd === "instance" ? `instance ${oatsArgs[0]}` : cmd === "retire" ? "retire plan" : cmd;
959
1075
  const surface = HOST_SURFACES[key];
960
- if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background, pin and same-work only (not ${key})`);
1076
+ if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background, pin and related-work only (not ${key})`);
961
1077
  const args = [...oatsArgs];
962
1078
  const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
963
1079
  const name = cmd === "readiness" ? undefined : args[cmd === "instance" ? 1 : 0];
@@ -970,10 +1086,14 @@ function routeHostSurface(serverId, cmd, oatsArgs, io) {
970
1086
  target = route.target;
971
1087
  if (home === undefined) args.push("--home", route.home);
972
1088
  } else target = targetOf(io.server || getServer(serverId));
973
- requireSurface(checkRemote(target, io), target, surface);
1089
+ const remote = checkRemote(target, io);
1090
+ // An older host knows `instance related-work` by its old name only: asked by that name, or refused.
1091
+ const oldName = key === "instance related-work" && sameWorkOnly(remote.features);
1092
+ if (oldName) args.splice(0, 1, ...relatedWorkSurfaceArgs(remote, target, args, io));
1093
+ else requireSurface(remote, target, surface);
974
1094
  if (!args.includes("--dir") && !(cmd === "readiness" && home !== undefined)) args.push("--dir", target.workspace);
975
1095
  const { envelope, stderr } = runRemote(target, [cmd, ...args, "--json"], io);
976
- return { envelope, stderr };
1096
+ return { envelope: oldName ? relatedWorkAnswer(envelope) : envelope, stderr };
977
1097
  }
978
1098
 
979
1099
  // ------------------------------------------------------------------- roster
@@ -1021,6 +1141,11 @@ const rowBackground = (i) => (i.background === true ? { background: true } : {})
1021
1141
  /** `pinned` (feature instance-pin) as `background`: relayed ONLY when the host's row says exactly `true`;
1022
1142
  * absent is the only reading of "not pinned", so any other value (`"true"`, `1`) is dropped, never false. */
1023
1143
  const rowPinned = (i) => (i.pinned === true ? { pinned: true } : {});
1144
+ /** `board` (feature instance-board) as the host's row says it, read by this kernel's own rule
1145
+ * (lib/instance-board.mjs readRemoteBoard: every fact and question within its rules and the whole within
1146
+ * the row bound, else an empty board): relayed ONLY when the host's row has the key, so a host whose
1147
+ * kernel predates the feature says nothing. */
1148
+ const rowBoard = (i) => (Object.hasOwn(i, "board") ? { board: readRemoteBoard(i.board) } : {});
1024
1149
  /** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
1025
1150
  * key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
1026
1151
  * only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
@@ -1028,9 +1153,14 @@ const rowRetire = (i) => {
1028
1153
  const retire = Object.hasOwn(i, "retire") ? readRetireState(i.retire) : undefined;
1029
1154
  return retire ? { retire } : {};
1030
1155
  };
1031
- /** `sameWork` (feature instance-same-work) as `background`: relayed ONLY when the host's row says
1032
- * `sameWork: true`, the one value a row carries; anything else, and a host that omits it, is absent. */
1033
- const rowSameWork = (i) => (i.sameWork === true ? { sameWork: true } : {});
1156
+ /** `relatedWork` (feature instance-related-work) as `background`: relayed ONLY as `true`, when the host's row
1157
+ * says `relatedWork: true`, or, from a host whose `features` (hostFeatures) have instance-same-work and not
1158
+ * instance-related-work, `sameWork: true`: that older kernel's flag, a parent binding by the old name. Anything
1159
+ * else, and a host that omits it, is absent. Beside it, `sameWork: true` (feature instance-same-work, the
1160
+ * compatibility layer) when the host's row says exactly that: a parent binding, which every host reports by
1161
+ * both names; never without `relatedWork`. The one rule of both keys, for the roster and the routed status. */
1162
+ const rowRelatedWork = (i, features) => (i.relatedWork === true || (sameWorkOnly(features) && i.sameWork === true)
1163
+ ? { relatedWork: true, ...(i.sameWork === true ? { sameWork: true } : {}) } : {});
1034
1164
  /** `sessionEnd` (feature session-resume, #1628) as `retire` is: relayed ONLY when the host's row has the
1035
1165
  * key, which a host whose kernel predates the feature never sends, so its rows say nothing. A value that
1036
1166
  * is not one of the contract's (lib/session-resume-contract.mjs SESSION_END) drops the key. */
@@ -1136,10 +1266,12 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
1136
1266
  const snap = routeOf(i);
1137
1267
  g.instances.push({
1138
1268
  server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: result.root,
1139
- harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
1269
+ // A session provider's row (feature session-providers): its backend's name, `session`, `open`
1270
+ // and `runtimeState`, relayed in the kernel's own shapes only (relayedProviderRow).
1271
+ harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null, ...(relayedProviderRow(i) ?? {}),
1140
1272
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
1141
1273
  running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
1142
- ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowSameWork(i), ...rowSessionEnd(i),
1274
+ ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
1143
1275
  // Every row the host reports is addressed by its home, saved
1144
1276
  // route or not; savedRoute says only that it was spawned from here.
1145
1277
  retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
@@ -1553,7 +1685,9 @@ function probeHostOats(target, io) {
1553
1685
  const r = runHostCommand(target, [target.oatsPath, "version", "--json"], { ...io, timeoutMs: 60000 });
1554
1686
  if (r.status === 255) throw sshFailed(target, r);
1555
1687
  if (r.status === 126 || r.status === 127) return { missing: true };
1556
- const probe = parseRemoteEnvelope(r.stdout).result || {};
1688
+ const envelope = parseRemoteEnvelope(r.stdout);
1689
+ if (!envelope.ok) throw relayedFailure(envelope, "version --json");
1690
+ const probe = envelope.result || {};
1557
1691
  if (probe.desktopApi !== 1 || typeof probe.version !== "string") throw serverError("E_REMOTE_INCOMPATIBLE", `${target.oatsPath} at ${target.sshHost} answered an unknown version payload: ${JSON.stringify(probe).slice(0, 200)}`);
1558
1692
  return { version: probe.version, features: Array.isArray(probe.features) ? probe.features.map(String) : [] };
1559
1693
  }
@@ -1,6 +1,7 @@
1
- /** inspectInstanceSession: what a home's tmux session is, read under the home's runtime authority (its
2
- * recorded launch and receipts, the retirement baseline, the Herdr refusal) and the agent pane's
3
- * liveness. A leaf (awebai/oats#1630): `oats session inspect` reads it without loading core.mjs, which
1
+ /** inspectInstanceSession: what a home's session is, read under the home's runtime authority (its
2
+ * recorded launch and receipts, the retirement baseline, the Herdr refusal): a tmux session's agent
3
+ * pane and its liveness, or, for a home on a session provider (lib/session-providers.mjs), the
4
+ * provider's own answer. A leaf (awebai/oats#1630): `oats session inspect` reads it without loading core.mjs, which
4
5
  * imports these helpers and re-exports what it exported. */
5
6
  import { realPathOrNearest, canonicalHomePath } from "./real-path.mjs";
6
7
  import { existsSync, readFileSync, lstatSync } from "node:fs";
@@ -9,6 +10,7 @@ import { createHash } from "node:crypto";
9
10
  import { inspectSessionTarget } from "./session-input.mjs";
10
11
  import { liveWaiting } from "./instance-events.mjs";
11
12
  import { oatsError, herdrInstanceRemoved } from "./errors.mjs";
13
+ import { homeSessionProvider, isSessionProviderName, inspectProviderSession, launchSentOf, providerEndpointDifferences, providerRuntimeOf, unsettledLaunchSaid } from "./session-providers.mjs";
12
14
 
13
15
  /** A cleanup descriptor is usable only if it can DRIVE the retry, so it is checked
14
16
  * as the strict contract its one producer writes — the rollback above — and to the
@@ -112,15 +114,53 @@ function refuseHerdrHome(home) {
112
114
  if (recordsHerdr(readJsonOrUndefined(join(home, "instance.json")), readJsonOrUndefined(findRetirementBaseline(home)))) throw herdrInstanceRemoved(basename(home));
113
115
  }
114
116
 
117
+ /** What a receipt authorises: `{ launched: false }` (with `planned: { backend, provider }` for a home
118
+ * that will launch on a session provider), `{ launched: true, tmux }` for a tmux session, or
119
+ * `{ launched: true, session }` for a session provider's (`session`: providerRuntimeOf's
120
+ * `{ backend, provider, endpoint, stoppedAt }`); undefined when it is none of these. */
115
121
  function runtimeAuthorityOf(baseline) {
116
122
  const runtime = baseline?.runtime;
117
123
  if (!isPlainObject(runtime) || typeof runtime.launched !== "boolean") return undefined;
118
- if (!runtime.launched) return { launched: false };
124
+ if (!runtime.launched) {
125
+ if (runtime.backend === undefined && runtime.provider === undefined) return { launched: false };
126
+ if (!isSessionProviderName(runtime.backend) || typeof runtime.provider !== "string" || !runtime.provider || runtime.launchSent !== undefined) return undefined;
127
+ return { launched: false, planned: { backend: runtime.backend, provider: runtime.provider, launchSent: null } };
128
+ }
119
129
  if (runtime.sessionTarget !== undefined) return undefined;
130
+ // A launch that was sent for a home never launched, and has no recorded outcome (lib/session-providers.mjs
131
+ // launchSentOf): no endpoint yet. The home is still a planned one, whose record says not launched.
132
+ if (runtime.tmux === undefined && runtime.endpoint === undefined) {
133
+ const launchSent = launchSentOf(runtime);
134
+ if (!launchSent || !isSessionProviderName(runtime.backend) || typeof runtime.provider !== "string" || !runtime.provider) return undefined;
135
+ return { launched: false, planned: { backend: runtime.backend, provider: runtime.provider, launchSent } };
136
+ }
137
+ if (runtime.tmux === undefined) {
138
+ const session = providerRuntimeOf(runtime);
139
+ return session ? { launched: true, session: { backend: session.backend, provider: session.provider, endpoint: session.endpoint, stoppedAt: session.stoppedAt, launchSent: session.launchSent } } : undefined;
140
+ }
120
141
  const tmux = runtime.tmux;
121
142
  if (!isPlainObject(tmux) || ![tmux.session, tmux.window, tmux.socket].every((v) => typeof v === "string" && v.length > 0)) return undefined;
122
143
  return { launched: true, tmux: { session: tmux.session, window: tmux.window, socket: resolve(tmux.socket) } };
123
144
  }
145
+ /** The fields of instance.json's session that differ from the receipt's, for a home on a session
146
+ * provider, launched (`authority.session`) or planned (`authority.planned`: no endpoint yet). */
147
+ function providerDifferences(meta, authority) {
148
+ // While the receipt says a launch is unsettled, the record's endpoint is not compared: the
149
+ // launch that would have written it may have ended at any point (docs/design/2026-11-20-provider-home-lifecycle.md).
150
+ if (authority.session && !authority.session.launchSent) return providerEndpointDifferences(meta, authority.session);
151
+ const named = authority.session ?? authority.planned;
152
+ return [
153
+ ...(meta?.backend === named.backend ? [] : ["backend"]),
154
+ ...(meta?.session?.provider === named.provider ? [] : ["session.provider"]),
155
+ ];
156
+ }
157
+ /** The fields of instance.json's endpoint, of whichever backend the receipt records, that differ
158
+ * from the receipt's: tmux's labels, or a session provider's. A receipt that records no endpoint
159
+ * (never launched, planned on tmux) has none to differ from. */
160
+ function endpointDifferences(meta, authority) {
161
+ if (authority.session || authority.planned) return providerDifferences(meta, authority);
162
+ return authority.launched ? tmuxEndpointDifferences(meta, authority) : [];
163
+ }
124
164
 
125
165
  /** The fields of instance.json's tmux endpoint that differ from the one the independent receipt
126
166
  * authorises, as fixed labels in a fixed order: `tmux.session`, `tmux.window`, `tmux.socket`. */
@@ -133,6 +173,8 @@ function tmuxEndpointDifferences(meta, authority) {
133
173
  }
134
174
  /** instance.json's tmux endpoint is the one the independent receipt authorises. */
135
175
  function tmuxEndpointAgrees(meta, authority) { return tmuxEndpointDifferences(meta, authority).length === 0; }
176
+ /** instance.json's endpoint, of whichever backend the receipt records, is the one it authorises. */
177
+ function endpointAgrees(meta, authority) { return endpointDifferences(meta, authority).length === 0; }
136
178
 
137
179
  /** Whether a blocked or incomplete launch prompt explains metadata's `launched: false` beside a
138
180
  * launched receipt. */
@@ -142,18 +184,23 @@ function promptRetained(meta, authority) {
142
184
  /** A blocked prompt is a retained runtime, not evidence that no process exists.
143
185
  * The independent launched receipt and exact endpoint agreement remain mandatory. */
144
186
  function launchStateAgrees(meta, authority) {
145
- return meta.launched === authority.launched || (promptRetained(meta, authority) && tmuxEndpointAgrees(meta, authority));
187
+ // A launch that was sent for a home never launched (lib/session-providers.mjs launchSentOf): the
188
+ // record says `launched: true` meanwhile, so that a kernel from before session providers refuses
189
+ // the home; the two files are written one after the other, so either value agrees.
190
+ if ((authority.session ?? authority.planned)?.launchSent) return true;
191
+ return meta.launched === authority.launched || (promptRetained(meta, authority) && !authority.session && tmuxEndpointAgrees(meta, authority));
146
192
  }
147
193
 
148
194
  /** The refusal for instance.json that disagrees with the independent receipt. `details.fields` names
149
195
  * what differs, from a fixed vocabulary in a fixed order: `launched` (unless a blocked or incomplete
150
- * launch prompt explains metadata's `launched: false`), then, for a launched receipt, each differing
151
- * tmux endpoint field. Labels only: never a path, a value or the receipt. Callers throw it only once
196
+ * launch prompt explains metadata's `launched: false`), then each differing endpoint field: for a
197
+ * launched tmux receipt `tmux.session`, `tmux.window`, `tmux.socket`; for a session provider's
198
+ * `backend`, `session.provider`, `session.endpoint`. Labels only: never a path, a value or the receipt. Callers throw it only once
152
199
  * their own comparison has refused, so these labels diagnose a refusal and never decide one. */
153
200
  function authorityMismatch(message, meta, authority) {
154
201
  const fields = [
155
- ...(meta.launched === authority.launched || promptRetained(meta, authority) ? [] : ["launched"]),
156
- ...(authority.launched ? tmuxEndpointDifferences(meta, authority) : []),
202
+ ...(meta.launched === authority.launched || promptRetained(meta, authority) || (authority.session ?? authority.planned)?.launchSent ? [] : ["launched"]),
203
+ ...endpointDifferences(meta, authority),
157
204
  ];
158
205
  return Object.assign(oatsError("E_RUNTIME_AUTHORITY_MISMATCH", message), { details: { fields } });
159
206
  }
@@ -194,9 +241,17 @@ function instanceSessionTarget(home, { absentMeta } = {}) {
194
241
  if (!isPlainObject(meta)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: it holds no JSON object`);
195
242
  const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
196
243
  if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
197
- if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw authorityMismatch("instance metadata disagrees with independent session receipt", meta, authority);
198
- return { home, target: authority.launched ? { backend: "tmux", ...authority.tmux } : undefined, meta };
244
+ if (!launchStateAgrees(meta, authority) || !endpointAgrees(meta, authority)) throw authorityMismatch("instance metadata disagrees with independent session receipt", meta, authority);
245
+ // `unsettled`: a launch that was sent to the home's provider and never recorded, whether the home
246
+ // was launched before or not: `{ backend, provider, launchSent }`, or null. The one place that says so.
247
+ const recorded = authority.session ?? authority.planned ?? null;
248
+ return { home, target: authority.tmux ? { backend: "tmux", ...authority.tmux } : undefined, meta,
249
+ ...(authority.session ? { session: authority.session } : {}), ...(authority.planned ? { planned: authority.planned } : {}),
250
+ unsettled: recorded?.launchSent ? { backend: recorded.backend, provider: recorded.provider, launchSent: recorded.launchSent } : null };
199
251
  }
252
+ /** The answer for a tmux-only path that meets a home on a session provider (`s`: instanceSessionTarget's
253
+ * answer): the home has no tmux endpoint to read or act on. Undefined for any other home. */
254
+ function providerHomeOf(s) { return s.session ?? s.planned; }
200
255
 
201
256
  /** `wakeHold` (feature wake-hold): whether this home's capabilities said its dialogs become the claims
202
257
  * a wake holds on, from the home's record (instance.json `dialogClaims`): `on-claims` if any entry is
@@ -207,11 +262,47 @@ function wakeHoldOf(meta) {
207
262
  return answers.includes("reported") ? "on-claims" : answers.includes("none") ? "not-exposed" : "unknown";
208
263
  }
209
264
 
210
- /** `io` (`{ exec }`) is the tmux and process-table seam inspectSessionTarget takes. */
265
+ /** What a provider home's `session` is in an answer: the capability that supplies its backend and
266
+ * the endpoint the kernel recorded (null before the first launch). */
267
+ export function sessionOf(session) { return { provider: session.provider, endpoint: session.endpoint ?? null }; }
268
+ /** A launched provider home's session, as inspect answers it (docs/desktop-cli-api.md): the
269
+ * provider's own `{ present, state, running, open }`, with the kernel's `backend`, `session`,
270
+ * `waitingOnYou` and `wakeHold`; no pane and no size. Kernel-owned: a home OATS stopped (`stoppedAt`)
271
+ * answers stopped WITHOUT calling the provider, so a session the provider would restart on the next
272
+ * input reads as OATS left it. A provider that fails, refuses or answers outside the contract's
273
+ * words is E_SESSION_UNAVAILABLE, never stopped. `waitingOnYou` is a producer's claim, read
274
+ * whenever the session is not stopped (providerMayWait): an idle session can be the one waiting
275
+ * on a person. */
276
+ function inspectProviderHome(s, wakeHold, io) {
277
+ const answer = { home: s.home, backend: s.session.backend };
278
+ const kernel = { wakeHold, session: sessionOf(s.session) };
279
+ if (s.session.stoppedAt !== null) return { ...answer, present: false, state: "stopped", running: false, waitingOnYou: null, ...kernel, open: null };
280
+ const found = homeSessionProvider(s.home, s.meta, s.session.provider, s.session.backend);
281
+ if (found.problem) throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${found.problem}`);
282
+ const inspected = inspectProviderSession(found.binding, s.session.endpoint, { io });
283
+ if (inspected.unavailable) throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${inspected.unavailable}`);
284
+ const { present, state, running, open } = inspected.observed;
285
+ return { ...answer, present, state, running, waitingOnYou: providerMayWait(inspected.observed) ? liveWaiting(s.home) : null, ...kernel, open };
286
+ }
287
+ /** Whether a provider's session, as observed, can be waiting on a human: whenever it is not stopped
288
+ * (`running` true or null). An agent that waits on a question is idle where its provider runs it,
289
+ * so it reads `running: null`: the claim is shown then too. Never for a session that is gone (a
290
+ * lost one included) or in error, nor for a home OATS stopped, which is never observed. */
291
+ function providerMayWait(observed) { return observed.present === true && observed.running !== false; }
292
+
293
+ /** `io` (`{ exec }`) is the tmux and process-table seam inspectSessionTarget takes; for a home on a
294
+ * session provider, `io.spawnSync` is the provider call's. */
211
295
  export function inspectInstanceSession(home, { io, absentMeta } = {}) {
212
296
  if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped", running: false, waitingOnYou: null, wakeHold: wakeHoldOf(null) };
213
297
  const s = instanceSessionTarget(home, { absentMeta });
214
298
  const wakeHold = wakeHoldOf(s.meta);
299
+ // A launch that was sent and never recorded (launchSentOf), on a home launched before or not: a
300
+ // session may run that no record names. Unknown, never "not launched" or "stopped", until a stop
301
+ // or a start has settled it.
302
+ if (s.unsettled) throw oatsError("E_SESSION_UNAVAILABLE", unsettledLaunchSaid(basename(s.home), s.unsettled.backend, s.unsettled.launchSent));
303
+ if (s.session) return inspectProviderHome(s, wakeHold, io);
304
+ // A home that will launch on a session provider says which: nothing was launched yet.
305
+ if (s.planned) return { home: s.home, backend: s.planned.backend, present: false, state: "not-launched", running: false, waitingOnYou: null, wakeHold, session: sessionOf(s.planned), open: null };
215
306
  if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", running: false, waitingOnYou: null, wakeHold };
216
307
  let observed;
217
308
  try { observed = inspectSessionTarget(s.target, io, { includeSize: true }); }
@@ -226,4 +317,4 @@ export function inspectInstanceSession(home, { io, absentMeta } = {}) {
226
317
  * fallback shell nor a dead pane. Only such a session can be waiting on a human. */
227
318
  function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
228
319
 
229
- export { RETIRE_BASELINE_VERSION, authorityMismatch, harnessRunning, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, runtimeAuthorityOf, tmuxEndpointAgrees };
320
+ export { RETIRE_BASELINE_VERSION, authorityMismatch, endpointAgrees, harnessRunning, providerHomeOf, providerMayWait, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, runtimeAuthorityOf, tmuxEndpointAgrees };