@awebai/oats 0.69.22 → 0.69.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/bin/oats.mjs +131 -23
  2. package/docs/capabilities.md +12 -2
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +206 -228
  5. package/docs/design/2026-11-19-sandboxes.md +878 -0
  6. package/docs/design/README.md +3 -0
  7. package/docs/desktop-cli-api.md +416 -72
  8. package/docs/desktop.md +60 -17
  9. package/docs/implementation.md +1 -1
  10. package/docs/integrations.md +3 -3
  11. package/docs/knowledge-capability-authoring.md +10 -7
  12. package/docs/knowledge-reference/acceptance.md +21 -19
  13. package/docs/knowledge-reference/adoption.md +18 -4
  14. package/docs/knowledge-reference/model.md +11 -9
  15. package/docs/knowledge-reference/package-craft.md +2 -2
  16. package/docs/knowledge-reference/proposal.md +117 -0
  17. package/docs/knowledge-reference/provider-mapping.md +10 -10
  18. package/docs/knowledge-reference/reader-capture.md +26 -22
  19. package/docs/knowledge-theory.md +1 -1
  20. package/docs/knowledge.md +5 -5
  21. package/docs/official-catalog.md +4 -4
  22. package/docs/packages.md +13 -13
  23. package/docs/release-notes/v0.69.23.md +231 -0
  24. package/docs/servers.md +10 -6
  25. package/docs/souls-and-instances.md +51 -22
  26. package/docs/tui.md +4 -3
  27. package/docs/upgrading.md +12 -5
  28. package/docs/workspaces.md +2 -2
  29. package/lib/argv.mjs +6 -2
  30. package/lib/capability-contract.mjs +2 -2
  31. package/lib/command-flags.mjs +39 -2
  32. package/lib/core.mjs +25 -14
  33. package/lib/instance-board.mjs +337 -0
  34. package/lib/instance-events.mjs +48 -10
  35. package/lib/instance-lifecycle.mjs +19 -15
  36. package/lib/instance-listing.mjs +18 -10
  37. package/lib/instance-related-work.mjs +143 -0
  38. package/lib/kernel-features.mjs +4 -1
  39. package/lib/servers.mjs +123 -13
  40. package/package-catalog.json +3 -3
  41. package/package.json +1 -1
  42. package/packages/client/deployment-data.mjs +4 -2
  43. package/packages/client/deployment-panel.mjs +2 -1
  44. package/packages/client/instance-tree.mjs +34 -4
  45. package/packages/client/keymap.mjs +5 -0
  46. package/packages/client/mail-contract.mjs +130 -0
  47. package/packages/client/panel-views.mjs +7 -7
  48. package/packages/client/related-work.mjs +84 -0
  49. package/packages/client/remote-roster.mjs +4 -3
  50. package/packages/client/workspace-cli.mjs +13 -2
  51. package/skills/oats-getting-started/SKILL.md +11 -8
  52. package/docs/knowledge-reference/harvester.md +0 -109
  53. package/lib/instance-same-work.mjs +0 -67
  54. package/packages/client/same-work.mjs +0 -49
@@ -0,0 +1,143 @@
1
+ /** The "related work" flag (feature instance-related-work; the same-work flag of awebai/oats#1577, renamed):
2
+ * an instance's declared "related work" with the instance it is bound to, its parent or its sibling, which
3
+ * clients draw as a line between the two. A home file of its own, `<home>/.oats-related-work.json`, so that a
4
+ * start, restart, stop or resume, which rewrite instance.json, never lose it; only `oats instance
5
+ * related-work … off` or retirement removes it. The kernel never sets it on its own: only `oats spawn
6
+ * --related-work` and the verb do (and their deprecated aliases, `--same-work` and `oats instance same-work`).
7
+ *
8
+ * The flag is BOUND to the relation it was set against: the home's recorded `parentInstance` when it has
9
+ * one, else its recorded `siblingInstance` (relatedWorkBinding, the one choice). The record names that
10
+ * instance and the kind of edge, and the flag is on only while that edge is still the home's
11
+ * (relatedWorkHeld, the one rule). A relink that changes the relation (a retire's splice, a `--relation
12
+ * parent` spawn re-pointing its anchor) leaves the record bound to the old name, so the flag reads off and
13
+ * nothing errors. A sibling binding names the sibling the home records: for a sibling of a root, that root;
14
+ * for a sibling of a sibling, the anchor it was spawned beside (lib/core.mjs records the anchor itself).
15
+ *
16
+ * The record is `{ relatedWorkApi: 1, parent | sibling, at }`, exactly one of `parent` and `sibling`,
17
+ * written atomically (writeThroughPrivateFile) at mode 0600; present means on. A reader takes a regular file
18
+ * only, without following a link, up to RECORD_MAX bytes: anything that is not a valid record reads as no
19
+ * binding (null), never an error.
20
+ *
21
+ * The compatibility layer with the same-work flag it replaced (item 4 of the related-work contract), all of
22
+ * it in this module and its callers named here: the old home file `.oats-same-work.json`,
23
+ * `{ sameWorkApi: 1, parent, at }`, reads as a parent binding while nothing stands at the new name
24
+ * (readRelatedWork); the write that creates the new file removes the old one, and a removal takes both
25
+ * (writeRelatedWork). Both names are kernel-owned (lib/capability-contract.mjs KERNEL_HOME_NAME_PREFIXES,
26
+ * lib/core.mjs KERNEL_HOME_RECEIPTS, the manifest schema). The old row field `sameWork: true` stands beside
27
+ * `relatedWork: true` for a parent binding (lib/instance-listing.mjs), and the old spellings are aliases
28
+ * (lib/command-flags.mjs SAME_WORK_ALIASES). Dependency-free: the status rows, spawn and the command all go
29
+ * through here. */
30
+ import { lstatSync, rmSync } from "node:fs";
31
+ import { join } from "node:path";
32
+ import { readFileHead } from "./bounded-read.mjs";
33
+ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
34
+
35
+ /** The record's own version. */
36
+ export const RELATED_WORK_API = 1;
37
+ /** The home file, kernel-owned: in KERNEL_HOME_NAME_PREFIXES (lib/capability-contract.mjs), the retire
38
+ * fingerprint's receipts (lib/core.mjs KERNEL_HOME_RECEIPTS) and the manifest schema. */
39
+ export const RELATED_WORK_FILE = ".oats-related-work.json";
40
+ /** The file of the same-work flag the new one replaced: read while the new one is absent, never written,
41
+ * removed by the write that creates the new one and by a removal; kernel-owned. */
42
+ export const SAME_WORK_FILE = ".oats-same-work.json";
43
+ /** The old record's own version. */
44
+ const SAME_WORK_API = 1;
45
+ /** A record larger than this is not one. */
46
+ export const RECORD_MAX = 4096;
47
+
48
+ const isName = (v) => typeof v === "string" && v !== "";
49
+
50
+ /** The binding a home with lineage `{ parentInstance, siblingInstance }` (its instance.json, or a spawn's
51
+ * lineage before it is written) takes: `{ parent }` when it records a parent, else `{ sibling }` when it
52
+ * records a sibling, else null (no flag can be set). The one choice: spawn, the verb and the route ask it. */
53
+ export function relatedWorkBinding(lineage) {
54
+ if (isName(lineage?.parentInstance)) return { parent: lineage.parentInstance };
55
+ if (isName(lineage?.siblingInstance)) return { sibling: lineage.siblingInstance };
56
+ return null;
57
+ }
58
+
59
+ /** The JSON object in the file at `path`, or null: no file, not a regular file (a link is never followed),
60
+ * over RECORD_MAX bytes, unreadable, not a JSON object. Never throws. */
61
+ function readRecord(path) {
62
+ try {
63
+ const { bytes, size } = readFileHead(path, RECORD_MAX + 1);
64
+ if (size > RECORD_MAX) return null;
65
+ const record = JSON.parse(bytes.toString("utf8"));
66
+ return record && typeof record === "object" && !Array.isArray(record) ? record : null;
67
+ } catch { return null; }
68
+ }
69
+
70
+ /** Whether anything at all stands at `path` (a file, a link, a directory, one that can't be read). */
71
+ function standsAt(path) {
72
+ try { lstatSync(path); return true; } catch (e) { return e?.code !== "ENOENT"; }
73
+ }
74
+
75
+ /** The binding `home`'s record holds, `{ parent }` or `{ sibling }`, or null. The new record, while anything
76
+ * stands at its name: null when it is not a record (readRecord), another relatedWorkApi, or not exactly one
77
+ * of a non-empty string `parent` and `sibling`. With nothing at the new name, the old same-work record, as
78
+ * a parent binding: null when it is not a record, another sameWorkApi, or no non-empty string `parent`.
79
+ * The one read of both files. Never throws. */
80
+ export function readRelatedWork(home) {
81
+ const path = join(home, RELATED_WORK_FILE);
82
+ if (!standsAt(path)) {
83
+ const old = readRecord(join(home, SAME_WORK_FILE));
84
+ return old?.sameWorkApi === SAME_WORK_API && isName(old.parent) ? { parent: old.parent } : null;
85
+ }
86
+ const record = readRecord(path);
87
+ if (!record || record.relatedWorkApi !== RELATED_WORK_API) return null;
88
+ const hasParent = Object.hasOwn(record, "parent"), hasSibling = Object.hasOwn(record, "sibling");
89
+ if (hasParent === hasSibling) return null;
90
+ if (hasParent) return isName(record.parent) ? { parent: record.parent } : null;
91
+ return isName(record.sibling) ? { sibling: record.sibling } : null;
92
+ }
93
+
94
+ const sameBinding = (a, b) => !!a && !!b && a.parent === b.parent && a.sibling === b.sibling;
95
+
96
+ /** Remove whatever stands at `path` (a file, a link, a directory), and nothing when nothing does. */
97
+ const removeAt = (path) => { if (standsAt(path)) rmSync(path, { recursive: true, force: true }); };
98
+
99
+ /** Bind `home`'s flag to `binding` (`{ parent: <name> }` or `{ sibling: <name> }`), or remove it when
100
+ * `binding` is null. → `{ changed }`. A home already holding `binding` (readRelatedWork: from either file)
101
+ * is no change: nothing is written. Otherwise the new record is written, and the old same-work file, if
102
+ * anything stands at its name, is removed after it. A removal takes whatever stands at either name (an
103
+ * unreadable file, a link, a directory), and is a change only when a valid binding was read. The caller
104
+ * decided `binding` (relatedWorkBinding of the home's record) and holds the right to change the home. */
105
+ export function writeRelatedWork(home, binding, { now = () => new Date() } = {}) {
106
+ if (binding !== null) {
107
+ const keys = binding && typeof binding === "object" && !Array.isArray(binding) ? Object.keys(binding) : [];
108
+ if (keys.length !== 1 || !["parent", "sibling"].includes(keys[0]) || !isName(binding[keys[0]])) {
109
+ throw new TypeError("writeRelatedWork: binding is { parent: <name> }, { sibling: <name> } or null");
110
+ }
111
+ }
112
+ const path = join(home, RELATED_WORK_FILE), oldPath = join(home, SAME_WORK_FILE);
113
+ const before = readRelatedWork(home);
114
+ if (binding !== null && sameBinding(before, binding)) return { changed: false };
115
+ if (binding === null) {
116
+ removeAt(path);
117
+ removeAt(oldPath);
118
+ return { changed: before !== null };
119
+ }
120
+ // A directory at the name is no record, and a rename cannot replace it: it goes first. A link or a file
121
+ // is replaced by the rename itself.
122
+ let present;
123
+ try { present = lstatSync(path); } catch (e) { if (e?.code !== "ENOENT") throw e; }
124
+ if (present?.isDirectory()) rmSync(path, { recursive: true, force: true });
125
+ const bytes = JSON.stringify({ relatedWorkApi: RELATED_WORK_API, ...binding, at: now().toISOString() }) + "\n";
126
+ writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, bytes, 0o600);
127
+ // The new record stands: the old one would never be read again.
128
+ removeAt(oldPath);
129
+ return { changed: true };
130
+ }
131
+
132
+ /** THE rule: the binding of `home` that holds against the row's current lineage `{ parentInstance,
133
+ * siblingInstance }`, or null. A parent binding holds only while its name is the current `parentInstance`;
134
+ * a sibling binding only while the row records no parent and its name is the current `siblingInstance`. */
135
+ export function relatedWorkHeld(home, lineage) {
136
+ const bound = readRelatedWork(home);
137
+ return bound !== null && sameBinding(bound, relatedWorkBinding(lineage)) ? bound : null;
138
+ }
139
+
140
+ /** Whether `home` does related work, by the rule (relatedWorkHeld). */
141
+ export function relatedWorkOf(home, lineage) {
142
+ return relatedWorkHeld(home, lineage) !== null;
143
+ }
@@ -8,6 +8,9 @@ import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
8
8
  /** `oats spawn --task-file -` reads the task from standard input: how a routed spawn's task reaches
9
9
  * its host (lib/servers.mjs routeCommand); a host that does not list this gets it as an argument. */
10
10
  export const SPAWN_TASK_STDIN_FEATURE = "spawn-task-stdin";
11
- export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-pin", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE]);
11
+ export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-pin", "instance-same-work", "instance-related-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE, "instance-board"]);
12
+ /** The agent's board (feature instance-board, lib/instance-board.mjs): `boardApi` in the probe, the board
13
+ * file and the board commands' answers. */
14
+ export const BOARD_API = 1;
12
15
  /** The warm reader's protocol (`oats reader --stdio`, lib/reader.mjs): `readerApi` in the probe and in the reader's hello. */
13
16
  export const READER_API = 1;
package/lib/servers.mjs CHANGED
@@ -28,6 +28,7 @@ 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";
@@ -37,6 +38,7 @@ import { compareSemver } from "./semver.mjs";
37
38
  import { SPAWN_TASK_STDIN_FEATURE } from "./kernel-features.mjs";
38
39
  import { sameRepo } from "./repo-moves.mjs";
39
40
  import { OATS_PACKAGE_NAME } from "./version.mjs";
41
+ import { readRemoteBoard } from "./instance-board.mjs";
40
42
  export { compareSemver } from "./semver.mjs";
41
43
 
42
44
  const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
@@ -744,8 +746,9 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
744
746
  // Feature instance-background: an older host would refuse the flag as unknown, or place the instance
745
747
  // in the main list; either is said here, before anything is sent.
746
748
  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");
749
+ // Feature instance-related-work: the flag as this host takes it (relatedWorkSpawnArgs), or refused here,
750
+ // before anything is sent; never dropped.
751
+ if (oatsArgs.includes("--related-work") || oatsArgs.includes("--same-work")) oatsArgs = relatedWorkSpawnArgs(remote, target, oatsArgs, status.result);
749
752
  const spawnOnHost = (args) => runRemote(target, json(withScope(["spawn", ...hostHarnessArgs(remote, args)])), { ...io, input: task });
750
753
  // A spawn that brings neither a decision nor a key is bound here: the host's preview decides, and
751
754
  // the apply carries that decision and a key of this request, so the same spawn sent again with
@@ -884,7 +887,7 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
884
887
  }
885
888
  if (cmd === "status") {
886
889
  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 };
890
+ return { envelope: envelope.ok ? { ...envelope, result: { ...relatedWorkRows(envelope.result), server: serverId, target, snapshots: listSnapshots(serverId) } } : envelope, stderr };
888
891
  }
889
892
  if (OPERATIONS_COMMANDS.has(cmd)) {
890
893
  // The operations contract (inspect, operation run): the
@@ -914,6 +917,8 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
914
917
  if (cmd === "inspect" && args.includes("--instructions")) requireRemoteFeature(remote, target, "soul-composed-instructions");
915
918
  // `inspect --skills` (feature soul-skills): the same, for the soul's own skills.
916
919
  if (cmd === "inspect" && args.includes("--skills")) requireRemoteFeature(remote, target, "soul-skills");
920
+ // `inspect --board` (feature instance-board): the same, for the board's history and context.
921
+ if (cmd === "inspect" && args.includes("--board")) requireRemoteFeature(remote, target, "instance-board");
917
922
  // `inspect --composed-skills` (feature soul-composed-skills): the same, for every skill a spawn would give.
918
923
  if (cmd === "inspect" && args.includes("--composed-skills")) requireRemoteFeature(remote, target, "soul-composed-skills");
919
924
  const scoped = args.includes("--dir") || args.includes("--home") ? args : [...args, "--dir", target.workspace];
@@ -923,6 +928,94 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
923
928
  throw serverError("E_USAGE", `--server routes spawn, retire, status, session, okf harvest, schedule, inspect, operation, readiness and instance only (not ${cmd})`);
924
929
  }
925
930
 
931
+ // ------------------------------------------------- related work on an older host
932
+
933
+ /** Whether a host's `features` say it is a kernel from before the related-work rename: it advertises
934
+ * instance-same-work (the flag by its old name, a parent binding only) and not instance-related-work. Only
935
+ * there is the flag sent by its old spelling, and a sibling binding refused. */
936
+ export function sameWorkOnly(features) {
937
+ return Array.isArray(features) && features.includes("instance-same-work") && !features.includes("instance-related-work");
938
+ }
939
+
940
+ /** The binding a routed spawn of `oatsArgs` would record, read from its arguments and the host's roster
941
+ * `roster` (its `status --json`): "parent" for `--parent`, `--relation child` and an attached spawn; for
942
+ * `--relation sibling|parent`, the binding the anchor's row gives (relatedWorkBinding, as the host's kernel
943
+ * chooses it): "sibling" when any row of that name gives a sibling, so that a sibling binding is never sent
944
+ * as a parent one; null when nothing here says (no relation, an anchor the roster does not list): the host
945
+ * answers that spawn itself. */
946
+ function routedSpawnBinding(oatsArgs, roster) {
947
+ const valueOf = (flag) => { const i = oatsArgs.indexOf(flag); return i >= 0 && oatsArgs[i + 1] && !oatsArgs[i + 1].startsWith("--") ? oatsArgs[i + 1] : undefined; };
948
+ const relation = valueOf("--relation"), relativeTo = valueOf("--relative-to");
949
+ if (valueOf("--parent") !== undefined || relation === "child") return "parent";
950
+ if ((relation === "sibling" || relation === "parent") && relativeTo) {
951
+ const anchors = (roster?.agents || []).flatMap((a) => a.instances || []).filter((i) => i?.instance === relativeTo);
952
+ // A sibling shares the anchor's parent, else links to the anchor; a new parent takes the anchor's slot.
953
+ const kinds = anchors.map((a) => relatedWorkBinding(relation === "sibling" ? { parentInstance: a.parentInstance, siblingInstance: a.instance } : a));
954
+ if (kinds.some((b) => b?.sibling)) return "sibling";
955
+ return kinds.some((b) => b?.parent) ? "parent" : null;
956
+ }
957
+ return !relation && valueOf("--work") === "attached" ? "parent" : null;
958
+ }
959
+
960
+ /** `oatsArgs` of a routed spawn that carries `--related-work` or its deprecated alias `--same-work`, as the
961
+ * host takes it: by a host that advertises instance-related-work, as `--related-work` (so that it says no
962
+ * deprecation of its own); by a host with only instance-same-work (sameWorkOnly), as `--same-work` when
963
+ * the spawn's binding is a parent or not known here (the host then refuses a spawn that records no parent
964
+ * itself), and refused with E_REMOTE_INCOMPATIBLE for a sibling binding, which that kernel cannot record;
965
+ * any other host refuses it (E_REMOTE_INCOMPATIBLE). */
966
+ function relatedWorkSpawnArgs(remote, target, oatsArgs, roster) {
967
+ const spelled = (flag) => oatsArgs.map((a) => (a === "--related-work" || a === "--same-work" ? flag : a)).filter((a, i, all) => a !== flag || all.indexOf(flag) === i);
968
+ if (remote.features.includes("instance-related-work")) return spelled("--related-work");
969
+ if (!sameWorkOnly(remote.features)) requireRemoteFeature(remote, target, "instance-related-work");
970
+ if (routedSpawnBinding(oatsArgs, roster) === "sibling") throw siblingNeedsRelatedWork(remote, target);
971
+ return spelled("--same-work");
972
+ }
973
+
974
+ 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`);
975
+
976
+ /** `args` of `instance related-work <instance> on|off …` (after `instance`, the route's --home pushed) for a
977
+ * host with only instance-same-work: the verb by its old name. `on` for an instance whose row on the host
978
+ * records no parent and a sibling is refused (E_REMOTE_INCOMPATIBLE): that kernel binds a parent only.
979
+ * `off`, and `on` for a row with a parent or none the roster lists, go as asked: the host answers them. */
980
+ function relatedWorkSurfaceArgs(remote, target, args, io) {
981
+ // The state is the one word after the instance that is no flag and no flag's value (as bin reads it).
982
+ const words = [];
983
+ 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]); }
984
+ if (words.length === 1 && words[0] === "on") {
985
+ const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
986
+ const home = valueOf("--home");
987
+ // The lineage is read in the scope the verb is sent to: its explicit --dir, else the registered workspace.
988
+ const status = runRemote(target, ["status", "--json", "--dir", valueOf("--dir") ?? target.workspace], { ...io, input: undefined }).envelope;
989
+ 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"}`);
990
+ const row = (status.result?.agents || []).flatMap((a) => a.instances || []).find((i) => i?.home && resolve(i.home) === resolve(home));
991
+ if (row && relatedWorkBinding(row)?.sibling) throw siblingNeedsRelatedWork(remote, target);
992
+ }
993
+ return ["same-work"];
994
+ }
995
+
996
+ /** A host's `status --json` result with each instance row's flag in this kernel's words, as rowRelatedWork
997
+ * reads it (the roster's rule): `relatedWork: true` or no key, and `sameWork: true` only beside it.
998
+ * Everything else is the host's answer as it gave it. */
999
+ function relatedWorkRows(result) {
1000
+ if (!result || typeof result !== "object" || !Array.isArray(result.agents)) return result;
1001
+ const features = hostFeatures(result);
1002
+ const row = (i) => {
1003
+ if (!i || typeof i !== "object") return i;
1004
+ const { sameWork: _sameWork, relatedWork: _relatedWork, ...rest } = i;
1005
+ return { ...rest, ...rowRelatedWork(i, features) };
1006
+ };
1007
+ return { ...result, agents: result.agents.map((a) => (a && typeof a === "object" && Array.isArray(a.instances) ? { ...a, instances: a.instances.map(row) } : a)) };
1008
+ }
1009
+
1010
+ /** The answer of an older host's `instance same-work`, `{ instance, sameWork }`, in this kernel's words, as
1011
+ * this kernel's verb answers: `relatedWork` beside its `sameWork` (an older host binds a parent only). A
1012
+ * refusal is relayed as is. */
1013
+ function relatedWorkAnswer(envelope) {
1014
+ if (!envelope?.ok || !envelope.result || typeof envelope.result !== "object" || !Object.hasOwn(envelope.result, "sameWork")) return envelope;
1015
+ const on = envelope.result.sameWork === true;
1016
+ return { ...envelope, result: { ...envelope.result, relatedWork: on, sameWork: on } };
1017
+ }
1018
+
926
1019
  /** The Desktop's per-instance reads and lifecycle plans, as the host's kernel
927
1020
  * answers them: the feature and API number the host must advertise first. */
928
1021
  const HOST_SURFACES = {
@@ -938,8 +1031,9 @@ const HOST_SURFACES = {
938
1031
  "instance background": { feature: "instance-background" },
939
1032
  // Feature instance-pin: the feature alone, as instance background.
940
1033
  "instance pin": { feature: "instance-pin" },
941
- // Feature instance-same-work: the feature alone, as instance color.
942
- "instance same-work": { feature: "instance-same-work" },
1034
+ // Feature instance-related-work: the feature alone, as instance color; a host with only instance-same-work
1035
+ // is asked by the old name (relatedWorkSurfaceArgs).
1036
+ "instance related-work": { feature: "instance-related-work" },
943
1037
  };
944
1038
 
945
1039
  function requireSurface(remote, target, surface) {
@@ -948,16 +1042,18 @@ function requireSurface(remote, target, surface) {
948
1042
  }
949
1043
  }
950
1044
 
951
- /** `readiness`, `instance events|git|diff|stop|color|background|pin|same-work` and `retire --plan` on the
1045
+ /** `readiness`, `instance events|git|diff|stop|color|background|pin|related-work` and `retire --plan` on the
952
1046
  * host: the instance is addressed as every routed session command addresses
953
1047
  * it (its name through a saved route or the host's roster, or an exact
954
1048
  * --home), the scope is an explicit --dir on the host or the registered
955
1049
  * workspace (readiness of a home is its own context), and the host's
956
1050
  * envelope is relayed unchanged. */
957
1051
  function routeHostSurface(serverId, cmd, oatsArgs, io) {
1052
+ // `instance same-work` is the deprecated alias of `instance related-work` (the dispatch said so): one route.
1053
+ if (cmd === "instance" && oatsArgs[0] === "same-work") oatsArgs = ["related-work", ...oatsArgs.slice(1)];
958
1054
  const key = cmd === "instance" ? `instance ${oatsArgs[0]}` : cmd === "retire" ? "retire plan" : cmd;
959
1055
  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})`);
1056
+ if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background, pin and related-work only (not ${key})`);
961
1057
  const args = [...oatsArgs];
962
1058
  const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
963
1059
  const name = cmd === "readiness" ? undefined : args[cmd === "instance" ? 1 : 0];
@@ -970,10 +1066,14 @@ function routeHostSurface(serverId, cmd, oatsArgs, io) {
970
1066
  target = route.target;
971
1067
  if (home === undefined) args.push("--home", route.home);
972
1068
  } else target = targetOf(io.server || getServer(serverId));
973
- requireSurface(checkRemote(target, io), target, surface);
1069
+ const remote = checkRemote(target, io);
1070
+ // An older host knows `instance related-work` by its old name only: asked by that name, or refused.
1071
+ const oldName = key === "instance related-work" && sameWorkOnly(remote.features);
1072
+ if (oldName) args.splice(0, 1, ...relatedWorkSurfaceArgs(remote, target, args, io));
1073
+ else requireSurface(remote, target, surface);
974
1074
  if (!args.includes("--dir") && !(cmd === "readiness" && home !== undefined)) args.push("--dir", target.workspace);
975
1075
  const { envelope, stderr } = runRemote(target, [cmd, ...args, "--json"], io);
976
- return { envelope, stderr };
1076
+ return { envelope: oldName ? relatedWorkAnswer(envelope) : envelope, stderr };
977
1077
  }
978
1078
 
979
1079
  // ------------------------------------------------------------------- roster
@@ -1021,6 +1121,11 @@ const rowBackground = (i) => (i.background === true ? { background: true } : {})
1021
1121
  /** `pinned` (feature instance-pin) as `background`: relayed ONLY when the host's row says exactly `true`;
1022
1122
  * absent is the only reading of "not pinned", so any other value (`"true"`, `1`) is dropped, never false. */
1023
1123
  const rowPinned = (i) => (i.pinned === true ? { pinned: true } : {});
1124
+ /** `board` (feature instance-board) as the host's row says it, read by this kernel's own rule
1125
+ * (lib/instance-board.mjs readRemoteBoard: every fact and question within its rules and the whole within
1126
+ * the row bound, else an empty board): relayed ONLY when the host's row has the key, so a host whose
1127
+ * kernel predates the feature says nothing. */
1128
+ const rowBoard = (i) => (Object.hasOwn(i, "board") ? { board: readRemoteBoard(i.board) } : {});
1024
1129
  /** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
1025
1130
  * key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
1026
1131
  * only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
@@ -1028,9 +1133,14 @@ const rowRetire = (i) => {
1028
1133
  const retire = Object.hasOwn(i, "retire") ? readRetireState(i.retire) : undefined;
1029
1134
  return retire ? { retire } : {};
1030
1135
  };
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 } : {});
1136
+ /** `relatedWork` (feature instance-related-work) as `background`: relayed ONLY as `true`, when the host's row
1137
+ * says `relatedWork: true`, or, from a host whose `features` (hostFeatures) have instance-same-work and not
1138
+ * instance-related-work, `sameWork: true`: that older kernel's flag, a parent binding by the old name. Anything
1139
+ * else, and a host that omits it, is absent. Beside it, `sameWork: true` (feature instance-same-work, the
1140
+ * compatibility layer) when the host's row says exactly that: a parent binding, which every host reports by
1141
+ * both names; never without `relatedWork`. The one rule of both keys, for the roster and the routed status. */
1142
+ const rowRelatedWork = (i, features) => (i.relatedWork === true || (sameWorkOnly(features) && i.sameWork === true)
1143
+ ? { relatedWork: true, ...(i.sameWork === true ? { sameWork: true } : {}) } : {});
1034
1144
  /** `sessionEnd` (feature session-resume, #1628) as `retire` is: relayed ONLY when the host's row has the
1035
1145
  * key, which a host whose kernel predates the feature never sends, so its rows say nothing. A value that
1036
1146
  * is not one of the contract's (lib/session-resume-contract.mjs SESSION_END) drops the key. */
@@ -1139,7 +1249,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
1139
1249
  harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
1140
1250
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
1141
1251
  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),
1252
+ ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
1143
1253
  // Every row the host reports is addressed by its home, saved
1144
1254
  // route or not; savedRoute says only that it was spawned from here.
1145
1255
  retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
@@ -3,12 +3,12 @@
3
3
  "packages": {
4
4
  "oats.okf": {
5
5
  "url": "https://github.com/awebai/oats-okf.git",
6
- "ref": "v6.2.0",
6
+ "ref": "v6.3.0",
7
7
  "path": "oats-package"
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.45.0",
11
+ "ref": "v1.46.0",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -48,7 +48,7 @@
48
48
  },
49
49
  "oats.framework": {
50
50
  "url": "https://github.com/awebai/oats.git",
51
- "ref": "oats-framework/v1.26.0",
51
+ "ref": "oats-framework/v1.27.0",
52
52
  "path": "oats-package"
53
53
  }
54
54
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.69.22",
3
+ "version": "0.69.23",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -236,8 +236,10 @@ export function deploymentStatusData(document, deployment) {
236
236
  // Session resume: how the instance's last session ended, one of SESSION_ENDS exactly. Any other value is
237
237
  // dropped, never checked: the row reads as one that did not say.
238
238
  if (own(instance, 'sessionEnd') && SESSION_END_VALUES.includes(instance.sessionEnd)) row.sessionEnd = instance.sessionEnd;
239
- // #1577 (feature instance-same-work): the child does its parent's work, so its parent line is drawn
240
- // (same-work.mjs). Boolean true only; any other value is dropped, never checked: the row reads unflagged.
239
+ // Related work (features instance-related-work, and instance-same-work before it): the row's work is
240
+ // related to its parent's, or a top-level row's to its sibling's, so the line between them is drawn
241
+ // (related-work.mjs). Boolean true only; any other value is dropped, never checked: the row reads unflagged.
242
+ if (own(instance, 'relatedWork') && instance.relatedWork === true) row.relatedWork = true;
241
243
  if (own(instance, 'sameWork') && instance.sameWork === true) row.sameWork = true;
242
244
  if (own(instance, 'modules')) row.modules = modules(instance.modules);
243
245
  if (own(instance, 'soul')) row.soul = soulSource(instance.soul);
@@ -127,7 +127,8 @@ export function panelInstance(i) {
127
127
  // Session resume: how the last session ended, as deployment-data.mjs validated it (SESSION_ENDS); absent stays
128
128
  // absent. The resume trigger reads it (session-resume-trigger.mjs lostLocalHomes).
129
129
  ...(i.sessionEnd !== undefined ? { sessionEnd: i.sessionEnd } : {}),
130
- // #1577: the kernel's same-work flag (deployment-data.mjs keeps it as true only); same-work.mjs reads it.
130
+ // The kernel's related-work flags (deployment-data.mjs keeps each as true only); related-work.mjs reads them.
131
+ ...(i.relatedWork === true ? { relatedWork: true } : {}),
131
132
  ...(i.sameWork === true ? { sameWork: true } : {}),
132
133
  ...(i.captured ? { captured: true } : {}),
133
134
  // Needs input (PR K): the validated claim (or null, unknown) as status reported it; absent stays absent.
@@ -6,7 +6,7 @@ import { waitingClaim } from './waiting-on-you.mjs';
6
6
  import { byRuntimeState } from './instance-presentation.mjs';
7
7
  import { retireData } from './retire-state.mjs';
8
8
  import { displayLine } from './display-text.mjs';
9
- import { drawingFirst } from './same-work.mjs';
9
+ import { drawingFirst, drawsSiblingLink } from './related-work.mjs';
10
10
 
11
11
  export function collapseKey(workspace, instance) {
12
12
  return `${workspace || ""}\u0000${instance}`;
@@ -139,6 +139,35 @@ export function instanceSiblings(instances, { pins = false } = {}) {
139
139
  return new Map([...ids].map(([id, set]) => [id, [...set].map((s) => byId.get(s)).sort(order)]));
140
140
  }
141
141
 
142
+ /** Each instance's siblings by a RELATED explicit link: Y is X's when X's sibling link resolves to Y and X draws it
143
+ * (related-work.mjs `drawsSiblingLink`: its host reports `relatedWork` on a top-level row), or the same from Y to
144
+ * X, so both ends of a related link name each other. The links are `instanceSiblings`' (direct links only, resolved
145
+ * by identity over `instances`, self excluded), kept where related. Pass one deployment's FULL roster, as there.
146
+ * Returns Map<instanceId, Set<instanceId>>; an instance with no related sibling is absent from the map. */
147
+ export function relatedSiblings(instances) {
148
+ const byName = new Map();
149
+ for (const i of instances) {
150
+ if (!byName.has(i.instance)) byName.set(i.instance, []);
151
+ byName.get(i.instance).push(i);
152
+ }
153
+ const out = new Map();
154
+ const add = (a, b) => {
155
+ if (!out.has(a)) out.set(a, new Set());
156
+ out.get(a).add(b);
157
+ };
158
+ for (const i of instances) {
159
+ if (!drawsSiblingLink(i)) continue;
160
+ const id = instanceId(i);
161
+ for (const name of siblingLinksOf(i)) {
162
+ const other = resolveLinkId(i, name, byName);
163
+ if (!other || other === id) continue;
164
+ add(id, other);
165
+ add(other, id);
166
+ }
167
+ }
168
+ return out;
169
+ }
170
+
142
171
  /** Group instances into agent CLUSTERS — connected components of the
143
172
  * undirected relation graph (parent/child spawn edges + sibling links).
144
173
  * Unrelated instances are single-node clusters. Within a cluster the
@@ -146,8 +175,9 @@ export function instanceSiblings(instances, { pins = false } = {}) {
146
175
  * cluster members related only by sibling links sit at depth 0.
147
176
  * Nodes are keyed by instanceId (composite identity), never bare name —
148
177
  * duplicate names across repos render as distinct nodes.
149
- * Under one parent, the children that draw their parent line come first (same-work.mjs `drawingFirst`: on a
150
- * host that declares instance-same-work, the flagged ones), each part in the roster's order (#1577). The product
178
+ * Under one parent, the children that draw their parent line come first (related-work.mjs `drawingFirst`: the
179
+ * ones their host reports related to their parent), each part in the roster's order (#1577). A related sibling
180
+ * link changes no order (the lead's choice B, 2026-11-20). The product
151
181
  * owner's contract (awebai/oats#1577, comment 6441606665) refines the roster's order inside one parent's children only: roots, clusters and groups keep it.
152
182
  * Returns [{ key, instances: [{...instance, depth}] }] with clusters ranked by
153
183
  * their first ROOT in the roster's order (`rosterOrder`; pinned clusters first, `pins` below), never by another member (#1262): a bundle sits where
@@ -251,7 +281,7 @@ export function clusterInstances(instances, { links = instanceLinks, roster = in
251
281
  * each parent. Nodes without a key follow every node with one, in their input order (a stable sort), so an
252
282
  * empty record returns the input order. A child stays under its parent: each cluster is walked again in
253
283
  * pre-order, every depth unchanged. A parent's children keep the roster's split (#1577): those that draw their
254
- * parent line first (same-work.mjs `drawingFirst`), recency deciding within each part; roots are not split. Parentage is read from the pre-order and the depths alone (a node's
284
+ * parent line first (related-work.mjs `drawingFirst`), recency deciding within each part; roots are not split. Parentage is read from the pre-order and the depths alone (a node's
255
285
  * children are the following rows one level deeper, until a row at its depth or above), never from names: the
256
286
  * tree was built by identity, and a malformed cycle's depth-0 leftovers are roots like any other. Returns new
257
287
  * cluster objects over the same rows; the input is not mutated. */
@@ -175,6 +175,11 @@ export const CHORDS = Object.freeze([
175
175
  // such action, so it binds no key for it (chordKeys skips a `does` it does not handle). Not one of
176
176
  // the seven the Ctrl+Shift family moves: Ctrl+Alt+R in both of those (the maintainer's ruling).
177
177
  { does: "edit-instance", mac: "cmd+alt+r", alt: "alt+r", other: "ctrl+alt+r" },
178
+ // The Desktop's alone for now (S2-M3): the agent's mail, a read-only sheet from the right. No leader key; the TUI
179
+ // skips it as it skips edit-instance until it has the sheet. Not one of the seven: Ctrl+Alt+M in both other
180
+ // families (Ctrl+Shift+M is zoom in the Ctrl+Shift family). Alt+M takes Emacs' M-m (back-to-indentation) and
181
+ // zsh's (copy-prev-shell-word) in a terminal; the program still gets it from Esc, then m.
182
+ { does: "mail", mac: "cmd+alt+m", alt: "alt+m", other: "ctrl+alt+m" },
178
183
  ].map((entry) => Object.freeze({ ...entry, alt: entry.alt ?? entry.other, shift: entry.shift ?? entry.other })));
179
184
 
180
185
  /** The palette's own keys, read only while the palette is open: there they win over every binding