@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
@@ -9,7 +9,7 @@
9
9
  * maxAge seconds the kernel may reuse remote observations on a miss (a local inspect only)
10
10
  * exec how the CLI is run (cli-adapter.mjs `runJson`'s `io.exec`); without it, execFile
11
11
  *
12
- * request { action: 'inspect', selector: { soul, agentsRoot } | { home }, refresh?, instructions?, skills?, composedSkills? }
12
+ * request { action: 'inspect', selector: { soul, agentsRoot } | { home }, refresh?, instructions?, skills?, composedSkills?, board? }
13
13
  * context { workspace, cli, agents, instances, localCwd, catalogKey }
14
14
  *
15
15
  * It resolves the kernel's result with `observedAt` and `refreshing`, and throws an Error with a stable `code`
@@ -28,7 +28,8 @@ import { cliCapability, operationArgs } from './cli-adapter.mjs';
28
28
  import { inspectKey } from './inspect-cache.mjs';
29
29
  import { observationData } from './deployment-data.mjs';
30
30
  import { OBSERVE_MAX_AGE_FEATURE } from './deployment-contract.mjs';
31
- import { hostComposes, hostReportsSkills, hostComposesSkills } from './composed-gate.mjs';
31
+ import { hostComposes, hostReportsSkills, hostComposesSkills, hostAdvertises, PROBE_FEATURES_FEATURE } from './composed-gate.mjs';
32
+ import { BOARD_FEATURE } from './instance-board.mjs';
32
33
  import { canAddressRemote, unaddressableSentence, hostReason, shownLabel, unroutableReason } from './remote-address.mjs';
33
34
 
34
35
  const fail = (message, code = 'E_BAD_ARGS') => { throw Object.assign(new Error(message), { code }); };
@@ -37,7 +38,7 @@ const TEAM_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
37
38
 
38
39
  /** Admit a capability request in its context, or throw. `actions`: the actions the caller serves (an inspect
39
40
  * boundary serves only 'inspect'); any other is the same refusal as an unknown one. Returns what the call needs:
40
- * `{ action, server, label, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context, key }`, where
41
+ * `{ action, server, label, refresh, instructions, skills, composedSkills, board, soul, agentsRoot, home, context, key }`, where
41
42
  * `context` is the --dir the CLI runs in and `key` the inspect cache's key for the subject. */
42
43
  export function capabilityAdmission(request, { workspace, cli, agents = [], instances = [], catalogKey = null }, actions = ['inspect', 'run']) {
43
44
  if (!workspace) fail('Select a known workspace', 'E_WORKSPACE_UNKNOWN');
@@ -78,6 +79,13 @@ export function capabilityAdmission(request, { workspace, cli, agents = [], inst
78
79
  // the same way again: inspect of a soul only; routed only when the held row says the host lists them (hostComposesSkills).
79
80
  if (request.composedSkills !== undefined && (action !== 'inspect' || typeof request.composedSkills !== 'boolean' || selector.soul === undefined)) fail('Invalid composed skills flag');
80
81
  const composedSkills = request.composedSkills === true && (!server || hostComposesSkills(cli, workspace.group));
82
+ // board (feature instance-board): the agent's board with each fact's history and each question's context
83
+ // (`inspect --home --board`), inspect of a home only, read-only. Sent only to a CLI that advertises the feature;
84
+ // routed only when the held roster row says the host has it too (its own probe.features, relayed by a CLI with
85
+ // server-probe-features); otherwise it is dropped and the read is today's, which carries no history.
86
+ if (request.board !== undefined && (action !== 'inspect' || typeof request.board !== 'boolean' || selector.home === undefined)) fail('Invalid board flag');
87
+ const has = feature => !!cli?.ok && Array.isArray(cli.features) && cli.features.includes(feature);
88
+ const board = request.board === true && has(BOARD_FEATURE) && (!server || (has(PROBE_FEATURES_FEATURE) && hostAdvertises(workspace.group, BOARD_FEATURE)));
81
89
  let soul, agentsRoot, home, key;
82
90
  let context = workspace.scope;
83
91
  if (selector.home !== undefined) {
@@ -101,15 +109,15 @@ export function capabilityAdmission(request, { workspace, cli, agents = [], inst
101
109
  context = dirname(agentsRoot);
102
110
  key = inspectKey({ deployment: workspace.scope, server, kind: 'soul', soul, agentsRoot, catalogKey, instructions, skills, composedSkills });
103
111
  } else fail('Select a soul or an instance home (inspection has no scope subject)');
104
- return { action, server, label, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context, key };
112
+ return { action, server, label, refresh, instructions, skills, composedSkills, board, soul, agentsRoot, home, context, key };
105
113
  }
106
114
 
107
115
  /** The CLI call's options for an admitted request (cli-adapter.mjs `cliCapability`). */
108
- export function capabilityCall(request, { action, server, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context }, { workspace, cli, localCwd, maxAge }) {
116
+ export function capabilityCall(request, { action, server, refresh, instructions, skills, composedSkills, board, soul, agentsRoot, home, context }, { workspace, cli, localCwd, maxAge }) {
109
117
  return {
110
118
  action, context, server, soul, agentsRoot, home,
111
119
  operation: request.operation, ...(request.args !== undefined ? { args: request.args } : {}), ...(instructions ? { instructions } : {}),
112
- ...(skills ? { skills } : {}), ...(composedSkills ? { composedSkills } : {}),
120
+ ...(skills ? { skills } : {}), ...(composedSkills ? { composedSkills } : {}), ...(board ? { board } : {}),
113
121
  localCwd: server ? localCwd : context || workspace.scope,
114
122
  // --max-age travels only on a LOCAL inspect (reuse is local only: the kernel refuses it with --server)
115
123
  // and only when the probe declared observe-max-age (the adapter's call).
@@ -140,10 +148,12 @@ export function createInspectBoundary({ invoke = cliCapability, cache = null, ma
140
148
  async inspect(request, context) {
141
149
  const { workspace, cli, localCwd } = context;
142
150
  const admitted = capabilityAdmission(request, context, ['inspect']);
143
- const { server, refresh, key } = admitted;
151
+ const { server, refresh, key, board } = admitted;
144
152
  const call = () => invoke(cli.bin, capabilityCall(request, admitted, { workspace, cli, localCwd, maxAge }), io);
145
153
  let envelope, observedAt, refreshing = false;
146
- if (cache) {
154
+ // A board read never goes through the cache, not even to join a flight in the air: the view reads the board when
155
+ // it changed, so a flight begun before that change answers for an earlier board (instance-board.mjs).
156
+ if (cache && !board) {
147
157
  // A remote workspace has no state key and no invalidation signal here: its inspections are shared
148
158
  // between concurrent requests but never served from an earlier visit (store: false).
149
159
  // Live (observes the remotes afresh): a refresh, a routed inspect (reuse is local only, so it never carries
@@ -10,6 +10,8 @@
10
10
  * { code: 'unsupported-session', sentence, origin? }
11
11
  * { code: 'not-running', sentence } an `open` act's only (`openAct`)
12
12
  * { code: 'state-unknown', sentence } an `open` act's only
13
+ * { code: 'no-terminal', sentence, link? } an `open` act's only: the row runs on a session provider
14
+ * link: { label, url }, what the provider offers instead
13
15
  *
14
16
  * A client may switch on `code`, and on `key` or `kind` when it needs to; never on the sentence.
15
17
  * The sentences are the ones the shared tables already produce. Two of them can be text this home did
@@ -49,12 +51,28 @@
49
51
  * running === true inspect, restart, stop, retire
50
52
  * running === false inspect, start, stop, retire
51
53
  * running unknown inspect, stop, retire
54
+ * A row on a session provider (instance-presentation.mjs `sessionProvider`: "bb", say) is offered by the
55
+ * same last three lines, from the `running` the kernel reports for it: the kernel starts, stops and retires
56
+ * it through its provider.
52
57
  *
53
58
  * openAct(instance) -> { verb: 'open', enabled, reason: Reason | null } | null
54
59
  *
55
60
  * Whether the row's terminal can be opened, and why not. It is not one of `acts`: it is read from
56
- * `instanceActs`'s answer and from nothing else of the row, so the order above is written once.
61
+ * `instanceActs`'s answer, and of the row only from whether it runs on a session provider, so the order
62
+ * above is written once.
57
63
  * blocked or limited is set null: the row's own reason says why, and a client adds no act
64
+ * a Herdr-recorded row not enabled, with Start's own reason (unsupported-session), as below
65
+ * a row on a session provider not enabled (no-terminal), whatever its state: it has no terminal.
66
+ * The sentence names where the agent runs ("Runs in a bb thread; open it
67
+ * in bb."), this home's own, built from the provider's name when the
68
+ * row's `backend` is one (`sessionProviderName`); a row whose `backend`
69
+ * is any other text says "Runs outside tmux; it has no terminal to
70
+ * open.", and none of that text. `link` is
71
+ * the row's `open` (`openLink`: `{ label, url }`, an http(s) url), there
72
+ * only for a row of this machine that carries one: another machine's url
73
+ * is its own loopback. A client may show `link` as an external link (the
74
+ * label through `displayLine`); none attaches, splits or opens a
75
+ * terminal for the row, and none restores a remembered tab for it.
58
76
  * restart is listed, enabled enabled: the row runs
59
77
  * start is listed, enabled not enabled (not-running)
60
78
  * start is listed, not enabled not enabled, with that act's own reason (unsupported-session)
@@ -63,12 +81,12 @@
63
81
  * client's, and is not here.
64
82
  */
65
83
  import { heldHome } from './instance-tree.mjs';
66
- import { unsupportedSession } from './instance-presentation.mjs';
84
+ import { unsupportedSession, sessionProvider, sessionProviderName, openLink } from './instance-presentation.mjs';
67
85
  import { canAddressRemote, rowReason } from './remote-address.mjs';
68
86
 
69
87
  const act = (verb, reason = null, secondary = false) => ({ verb, enabled: !reason, reason, ...(secondary ? { secondary: true } : {}) });
70
88
  // An `open` act's own two codes, and the one sentence both carry.
71
- const NOT_RUNNING = 'not-running', STATE_UNKNOWN = 'state-unknown';
89
+ const NOT_RUNNING = 'not-running', STATE_UNKNOWN = 'state-unknown', NO_TERMINAL = 'no-terminal';
72
90
  const NO_LIVE_TERMINAL = 'No live terminal is reported.';
73
91
 
74
92
  export function instanceActs(instance) {
@@ -97,6 +115,15 @@ export function instanceActs(instance) {
97
115
  export function openAct(instance) {
98
116
  const { blocked, limited, acts } = instanceActs(instance);
99
117
  if (blocked || limited) return null;
118
+ // A session provider's row has no terminal in any state. After the held and unaddressable rows, whose own
119
+ // reason stands; a Herdr-recorded row is no provider's (`sessionProvider`) and keeps Start's reason below.
120
+ const provider = sessionProvider(instance);
121
+ if (provider) {
122
+ const link = instance.server ? null : openLink(instance);
123
+ // The sentence is this home's own, shown as written: only a provider's name is set in it, never other text of the row.
124
+ const sentence = sessionProviderName(provider) ? `Runs in a ${provider} thread; open it in ${provider}.` : 'Runs outside tmux; it has no terminal to open.';
125
+ return act('open', { code: NO_TERMINAL, sentence, ...(link ? { link } : {}) });
126
+ }
100
127
  const restart = acts.find(({ verb }) => verb === 'restart'), start = acts.find(({ verb }) => verb === 'start');
101
128
  if (restart?.enabled) return act('open');
102
129
  if (start?.enabled) return act('open', { code: NOT_RUNNING, sentence: NO_LIVE_TERMINAL });
@@ -0,0 +1,206 @@
1
+ /** The agent's board (feature `instance-board`, `boardApi: 1`; docs/desktop-cli-api.md, "The agent's board"): the
2
+ * facts an agent keeps in a person's view and the questions it asks them, as the kernel reports them on an
3
+ * `oats status --json` row (`board`) and, with history and context, on `oats inspect --home <h> --board --json`.
4
+ * Agent-reported and display only (instance-activity-is-reported-not-inferred): nothing here reads a terminal.
5
+ *
6
+ * One shared design: both clients read the board through this module, so the facts a client shows, the order,
7
+ * the bounds and the answer it types are the same everywhere. Pure, no DOM, never throws. A contract module: the
8
+ * server imports it (deployment-data, remote-roster), so it imports contract modules only.
9
+ *
10
+ * Every text is validated against the kernel's own bounds, and a value out of the contract drops only itself:
11
+ * a malformed fact or question is left out, the rest of the board stays. The row's `board` is absent without the
12
+ * feature and `null` when the home has no board file; both read as "no board" (`boardData` → null), and a row
13
+ * whose kernel lacks the feature keeps today's terminal and waiting row (`rowHasBoard`). */
14
+ import { record } from './readiness-contract.mjs';
15
+ import { NOT_NOTE_TEXT, UNSAFE } from './display-text.mjs';
16
+
17
+ export const BOARD_FEATURE = 'instance-board';
18
+ export const BOARD_API = 1;
19
+ /** The kernel's bounds (contract v4): facts per board, open questions, options per question, history per fact. */
20
+ export const BOARD_LIMITS = Object.freeze({ facts: 12, questions: 9, optionsMin: 2, optionsMax: 4, history: 20,
21
+ label: 40, value: 80, unit: 16, option: 60, question: 200, context: 2000, link: 512 });
22
+ /** The facts shown before the fold. */
23
+ export const FACTS_SHOWN = 3;
24
+ /** The producer of the board's own needs-input claim (reason `attention`). */
25
+ export const BOARD_PRODUCER = 'oats.board';
26
+ /** The claim reasons that say a harness's own dialog is on the agent's screen (a screen an Enter answers). */
27
+ export const DIALOG_REASONS = Object.freeze(['permission', 'question']);
28
+
29
+ const KEY = /^[a-z0-9][a-z0-9-]{0,15}$/;
30
+ const points = v => [...v].length;
31
+ /** A one-line text of at most `max` code points: non-empty, not only spaces, none of the refused characters. */
32
+ const line = (v, max) => typeof v === 'string' && v.trim() !== '' && points(v) <= max && !NOT_NOTE_TEXT.test(v);
33
+ /** The kernel's time: an ISO-8601 instant that parses. */
34
+ const instant = v => typeof v === 'string' && v.length <= 40 && /^\d{4}-\d{2}-\d{2}T/.test(v) && Number.isFinite(Date.parse(v));
35
+ /** An absolute https: URL of at most 512 ASCII characters, with a host and no credentials. */
36
+ export function boardLink(v) {
37
+ if (typeof v !== 'string' || !v || v.length > BOARD_LIMITS.link || !/^[\x21-\x7e]+$/.test(v)) return null;
38
+ let url;
39
+ try { url = new URL(v); } catch { return null; }
40
+ if (url.protocol !== 'https:' || !url.hostname || url.username || url.password) return null;
41
+ return { href: v, host: url.hostname };
42
+ }
43
+ /** Whether a text the agent wrote may be shown as it is: valid, and not UNSAFE (a secret, a credentialed URL), which
44
+ * the display filter would withhold whole. */
45
+ const shown = v => !UNSAFE.test(v);
46
+
47
+ function fact(v) {
48
+ if (!record(v) || typeof v.key !== 'string' || !KEY.test(v.key) || !line(v.label, BOARD_LIMITS.label)
49
+ || !line(v.value, BOARD_LIMITS.value) || !instant(v.at)) return null;
50
+ const unit = v.unit == null ? null : line(v.unit, BOARD_LIMITS.unit) ? v.unit : undefined;
51
+ const link = v.link == null ? null : boardLink(v.link) ?? undefined;
52
+ if (unit === undefined || link === undefined) return null;
53
+ // An address the display filter would withhold (a token in its query, a known secret's shape) is never shown, nor
54
+ // opened: the fact stays, with no link, like any fact the agent gave none.
55
+ return { key: v.key, label: v.label, value: v.value, unit, link: link && shown(link.href) ? link : null, at: v.at, withheld: !shown(v.label) || !shown(v.value) || (unit !== null && !shown(unit)) };
56
+ }
57
+ function question(v) {
58
+ if (!record(v) || typeof v.id !== 'string' || !KEY.test(v.id) || !line(v.question, BOARD_LIMITS.question) || !instant(v.since)
59
+ || !Array.isArray(v.options) || v.options.length < BOARD_LIMITS.optionsMin || v.options.length > BOARD_LIMITS.optionsMax
60
+ || !v.options.every(o => line(o, BOARD_LIMITS.option))) return null;
61
+ return { id: v.id, question: v.question, options: [...v.options], hasContext: v.hasContext === true, since: v.since,
62
+ // A text the display filter withholds is never shown, so it is never typed either (answerText).
63
+ withheld: !shown(v.question), optionsWithheld: v.options.map(o => !shown(o)) };
64
+ }
65
+ /** The first of each key (facts) or id (questions), in the kernel's order, up to `max`. */
66
+ function unique(list, make, by, max) {
67
+ const out = [], seen = new Set();
68
+ for (const item of list) {
69
+ if (out.length >= max) break;
70
+ const made = make(item);
71
+ if (made && !seen.has(made[by])) { seen.add(made[by]); out.push(made); }
72
+ }
73
+ return out;
74
+ }
75
+
76
+ /** A row's `board`, validated: `{ facts, questions, malformed, dropped }` (facts in the order first set, questions in
77
+ * the order asked), or null when the row has none (absent or `null`: the home has no board file). A value that is not
78
+ * a board is `malformed` (nothing shown from it), and `dropped` counts the entries left out as out of the contract, so
79
+ * the view can say the board was not read whole: neither ever reads as "no questions". Never throws. */
80
+ export function boardData(v) {
81
+ if (v === null || v === undefined) return null;
82
+ if (!record(v)) return { facts: [], questions: [], malformed: true, dropped: 0 };
83
+ const lists = Array.isArray(v.facts ?? []) && Array.isArray(v.questions ?? []);
84
+ const rawFacts = Array.isArray(v.facts) ? v.facts : [], rawQuestions = Array.isArray(v.questions) ? v.questions : [];
85
+ const facts = unique(rawFacts, fact, 'key', BOARD_LIMITS.facts), questions = unique(rawQuestions, question, 'id', BOARD_LIMITS.questions);
86
+ return { facts, questions, malformed: !lists,
87
+ dropped: Math.min(rawFacts.length, BOARD_LIMITS.facts) - facts.length + Math.min(rawQuestions.length, BOARD_LIMITS.questions) - questions.length };
88
+ }
89
+ /** Whether the agent view replaces the plain terminal for this row: its kernel reports the board (the CLI lists
90
+ * BOARD_FEATURE and the row carries the field, `null` included). A remote row carries `board` only when its host
91
+ * relays it. Without it the tab is today's terminal with its waiting row. */
92
+ export const rowHasBoard = (row, features) => record(row) && Object.hasOwn(row, 'board')
93
+ && Array.isArray(features) && features.includes(BOARD_FEATURE);
94
+
95
+ /** `oats inspect --home <h> --board --json`'s board, validated, as one of five outcomes the view tells apart:
96
+ * - `{ state: 'ok', facts, questions }`: each fact's `history` (`[{ value, at }]`, oldest first, at most 20, each value
97
+ * within the contract's bounds) and each question's `context` (boardContext, or null) with its `since`;
98
+ * - `{ state: 'none' }`: the answer's board is `null` (the home has no board file);
99
+ * - `{ state: 'unsupported' }`: the answer has no board at all (an OATS, or a routed host, without the feature: the
100
+ * backend dropped the flag);
101
+ * - `{ state: 'malformed' }`: the answer is not an inspection, or its board is not one.
102
+ * The fifth, `failed` (the read refused or failed), is the caller's. The board is the answer's `board`, or its
103
+ * `instance.board`. Never throws. */
104
+ export function boardDetailData(v) {
105
+ if (!record(v)) return { state: 'malformed' };
106
+ const has = Object.hasOwn(v, 'board') ? 'board' : record(v.instance) && Object.hasOwn(v.instance, 'board') ? 'instance' : null;
107
+ if (!has) return { state: 'unsupported' };
108
+ const board = has === 'board' ? v.board : v.instance.board;
109
+ if (board === null) return { state: 'none' };
110
+ if (!record(board) || !Array.isArray(board.facts ?? []) || !Array.isArray(board.questions ?? [])) return { state: 'malformed' };
111
+ const facts = new Map(), questions = new Map();
112
+ for (const f of Array.isArray(board.facts) ? board.facts : []) {
113
+ if (!record(f) || typeof f.key !== 'string' || !KEY.test(f.key) || facts.has(f.key)) continue;
114
+ const history = (Array.isArray(f.history) ? f.history : [])
115
+ .filter(h => record(h) && line(h.value, BOARD_LIMITS.value) && instant(h.at))
116
+ .slice(-BOARD_LIMITS.history).map(h => ({ value: h.value, at: h.at }));
117
+ facts.set(f.key, { history });
118
+ if (facts.size >= BOARD_LIMITS.facts) break;
119
+ }
120
+ for (const q of Array.isArray(board.questions) ? board.questions : []) {
121
+ if (!record(q) || typeof q.id !== 'string' || !KEY.test(q.id) || questions.has(q.id)) continue;
122
+ // Its `since` too: the view shows a context only under the occurrence it was read for.
123
+ questions.set(q.id, { context: boardContext(q.context), since: instant(q.since) ? q.since : null });
124
+ if (questions.size >= BOARD_LIMITS.questions) break;
125
+ }
126
+ return { state: 'ok', facts, questions };
127
+ }
128
+ /** A question's context: lines of text (LF only), at most 2000 code points, none of the refused characters but the
129
+ * line feed, not UNSAFE; null otherwise. Kept as the agent wrote it, line breaks included: shown as a quote. */
130
+ export function boardContext(v) {
131
+ if (typeof v !== 'string' || !v.trim() || points(v) > BOARD_LIMITS.context) return null;
132
+ if (v.split('\n').some(l => NOT_NOTE_TEXT.test(l)) || UNSAFE.test(v)) return null;
133
+ return v;
134
+ }
135
+
136
+ /** A sparkline's points from a fact's history: the numeric values (the first number in each value, so "0.4312"
137
+ * and "41 %" both read), oldest first. Null under two numbers: a line needs two points. */
138
+ export function sparkValues(history) {
139
+ if (!Array.isArray(history)) return null;
140
+ const values = [];
141
+ for (const h of history) {
142
+ const m = typeof h?.value === 'string' ? h.value.match(/-?\d+(?:[.,]\d+)?/) : null;
143
+ if (m) values.push(Number(m[0].replace(',', '.')));
144
+ }
145
+ return values.length >= 2 && values.every(Number.isFinite) ? values : null;
146
+ }
147
+
148
+ /** The facts the strip shows, in the kernel's order: `shown` (at most FACTS_SHOWN, unless `unfolded`), `folded`
149
+ * (the rest of the visible ones) and `hidden` (those the person hid on this computer). `hiddenKeys`: a Map from a
150
+ * fact's key to the value it was hidden at; a fact whose value has changed since shows again (the agent said
151
+ * something new). `limit`: fewer shown where the pane is short (the agent view's budget). */
152
+ export function factsView(facts, hiddenKeys = new Map(), { unfolded = false, limit = FACTS_SHOWN } = {}) {
153
+ const visible = [], hidden = [];
154
+ for (const f of facts) (hiddenKeys.has(f.key) && hiddenKeys.get(f.key) === f.value ? hidden : visible).push(f);
155
+ const cut = unfolded ? visible.length : limit;
156
+ return { shown: visible.slice(0, cut), folded: visible.slice(cut), hidden };
157
+ }
158
+
159
+ /** Whether a live claim says the agent's terminal shows a harness dialog: any positive claim, from any producer, whose
160
+ * reason is `permission` or `question` (waiting-claims-may-only-withhold-automated-input). `claims`: the row's
161
+ * `waitingOnYou` and, read while the view is open, the events read's `waitingClaims`. Unknown is not a dialog:
162
+ * the card never sends on its own, so the person's Enter, with the terminal in view, stays the consent. */
163
+ export function dialogOpen(claims) {
164
+ return (Array.isArray(claims) ? claims : [claims]).some(c => record(c) && c.waiting !== false
165
+ && typeof c.reason === 'string' && DIALOG_REASONS.includes(c.reason));
166
+ }
167
+ /** Whether a claim is the board's own (its questions show in the question zone, not in the waiting row). */
168
+ export const boardClaim = claim => record(claim) && claim.producer === BOARD_PRODUCER;
169
+
170
+ /** What pressing option `index` (0-based) of `q` types on the agent's input line: `<id>: <option>`, one line, never
171
+ * a bare digit and never a line end, so nothing is sent until the person presses Enter. Null when there is nothing
172
+ * the person can see to type: no such option, or an option the display filter withholds. */
173
+ export function answerText(q, index) {
174
+ if (!record(q) || typeof q.id !== 'string' || !KEY.test(q.id) || !Array.isArray(q.options)) return null;
175
+ const option = q.options[index];
176
+ if (!line(option, BOARD_LIMITS.option) || q.optionsWithheld?.[index] === true || !shown(option)) return null;
177
+ return `${q.id}: ${option}`;
178
+ }
179
+
180
+ /** "question 2 of 3", or null for a single question. */
181
+ export const questionCount = (index, total) => total > 1 ? `question ${index + 1} of ${total}` : null;
182
+ /** The index after turning by `step` (±1) among `total` questions, wrapping at the ends. */
183
+ export const turnQuestion = (index, step, total) => total > 0 ? ((index + step) % total + total) % total : 0;
184
+
185
+ /** A fact's change, as the strip says it: "updated just now", "updated 4 min ago", "updated 3 h ago",
186
+ * "updated 2 d ago", then the date. A future time (clock skew) reads "just now". */
187
+ export function updatedText(at, now = Date.now()) {
188
+ const ms = now - Date.parse(at);
189
+ if (!Number.isFinite(ms)) return '';
190
+ const s = Math.max(0, Math.floor(ms / 1000));
191
+ if (s < 60) return 'updated just now';
192
+ const m = Math.floor(s / 60); if (m < 60) return `updated ${m} min ago`;
193
+ const h = Math.floor(m / 60); if (h < 24) return `updated ${h} h ago`;
194
+ const d = Math.floor(h / 24); if (d < 30) return `updated ${d} d ago`;
195
+ return `updated ${new Date(Date.parse(at)).toISOString().slice(0, 10)}`;
196
+ }
197
+ /** When the view reads the detail again (the maintainer's condition, 2026-11-19): a fact's `at` changed (or a fact
198
+ * came or went), or a question with context was asked (an occurrence: questionOccurrence). Never on an unchanged poll. */
199
+ export const detailSignature = board => board ? JSON.stringify([board.facts.map(f => [f.key, f.at]),
200
+ board.questions.filter(q => q.hasContext).map(questionOccurrence)]) : 'none';
201
+ /** A question's occurrence: its id and when it was asked. An id the agent clears and asks again (a new `since`) is
202
+ * another question, with its own answer and its own context, even when no poll saw it cleared in between. */
203
+ export const questionOccurrence = q => `${q.id}@${q.since}`;
204
+ /** A board's identity for repaints: changes when a fact's value or time, or the set of questions, changes. */
205
+ export const boardSignature = board => board ? JSON.stringify([board.facts.map(f => [f.key, f.value, f.unit, f.link?.href ?? null, f.at, f.label]),
206
+ board.questions.map(q => [q.id, q.question, q.options, q.hasContext, q.since])]) : 'none';
@@ -54,6 +54,61 @@ export function unsupportedSession(instance) {
54
54
  return (instance?.sessionTarget !== undefined && instance?.sessionTarget !== null) || instance?.backend === "herdr" ? stem : null;
55
55
  }
56
56
 
57
+ /** A session provider's name, by the session-provider contract: 1 to 40 lowercase letters, digits and dashes.
58
+ * Here it also starts with a letter or a digit: a name is a `--backend` value, and one that starts with a dash
59
+ * is an option to the CLI's parser. `tmux` is the kernel's own backend and `session-provider` the contract's
60
+ * word for any provider: both are reserved, never a provider's name. This is the rule for a name a client
61
+ * sends (`--backend`, cli-adapter.mjs), offers (session-backends.mjs) or sets in a sentence of its own
62
+ * (instance-acts.mjs); which row runs on a provider is `sessionProvider`'s, wider on purpose. Not on the
63
+ * stable surface. */
64
+ const PROVIDER_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
65
+ export const sessionProviderName = (value) => typeof value === "string" && value !== "tmux" && value !== "session-provider" && PROVIDER_NAME.test(value);
66
+
67
+ /** The session provider a row runs on, as the row's `backend` says it, or null for a row that runs in tmux. A provider (a
68
+ * capability's session backend, "bb" say) has no tmux target and no terminal: a client takes such a row's
69
+ * `running`, `runtimeState` and `runtimeError` from the kernel as given, never probes tmux for it
70
+ * (liveness.mjs) and opens, splits or restores no terminal for it (instance-acts.mjs `openAct`).
71
+ *
72
+ * It is the row's `backend` whenever that is text that is not empty and not "tmux": any such row is not tmux's, so none is ever
73
+ * asked of tmux, also one whose value is no name the contract allows (`sessionProviderName`): what is answered
74
+ * is then the row's own text, for display only through `displayLine`, and never set in a sentence or sent as
75
+ * an argument. A row with no `backend` (an older kernel's, or an older routed host's) is a tmux row, as one
76
+ * with "tmux" is, and reads as it always did; so does one whose `backend` is not text, or is empty: an empty
77
+ * `backend` names no backend, the kernel never sends one, and reading it as a provider's would take a tmux
78
+ * home's terminal away. A Herdr-recorded row
79
+ * (`unsupportedSession`, `backend: "herdr"` included) is never one: its own reason comes first, everywhere.
80
+ * Not on the stable surface: a client reads `openAct`'s answer. */
81
+ export function sessionProvider(instance) {
82
+ if (unsupportedSession(instance)) return null;
83
+ const backend = instance?.backend;
84
+ return typeof backend === "string" && backend !== "" && backend !== "tmux" ? backend : null;
85
+ }
86
+
87
+ /** What a provider offers in place of a terminal: the row's `open`, `{ label, url }`, or null. Kept only
88
+ * when both are text and the url is an http or https one with no credentials in it: a client opens nothing
89
+ * else in a browser. The label is the provider's own text: a client shows it through display-text.mjs
90
+ * `displayLine`. Not on the stable surface. */
91
+ // Together under display-text.mjs MAX_DISPLAY_LINE, so a client can show the label and the url as one line, whole.
92
+ const MAX_LINK_LABEL = 200, MAX_LINK_URL = 1800;
93
+ export function openLink(instance) {
94
+ const open = instance?.open;
95
+ if (open === null || typeof open !== "object" || Array.isArray(open)) return null;
96
+ const { label, url } = open;
97
+ if (typeof label !== "string" || !label || label.length > MAX_LINK_LABEL || typeof url !== "string" || !url || url.length > MAX_LINK_URL) return null;
98
+ let parsed;
99
+ try { parsed = new URL(url); } catch { return null; }
100
+ if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password) return null;
101
+ return { label, url };
102
+ }
103
+
104
+ /** The id of the provider's thread a row runs in: `session.threadId` when it is text, else null. Only a
105
+ * status row of this machine carries it: a row relayed from another host never does, and nothing here may
106
+ * depend on it. For display only, through `displayLine`: it addresses nothing. Not on the stable surface. */
107
+ export function sessionThreadId(instance) {
108
+ const id = instance?.session?.threadId;
109
+ return typeof id === "string" && id && id.length <= 200 ? id : null;
110
+ }
111
+
57
112
  /** Who wrote what `unsupportedSession` answers for a row as the kernel or a host reported it: "kernel"
58
113
  * for the row's own text, null for the stand-in written here (and for a row it answers null for). Asked
59
114
  * where the text is chosen (liveness.mjs, remote-roster.mjs), of the reported row: a panel's row already
@@ -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
@@ -4,14 +4,19 @@
4
4
  * of the serving process is liveness-main.mjs (see packages/desktop/server/oats-web.mjs), so a slow
5
5
  * terminal server cannot stall request handling. */
6
6
  import { createTmuxStatusReader, DEFAULT_TMUX_SESSION } from './tmux-status.mjs';
7
- import { unsupportedSession, unsupportedSessionOrigin } from './instance-presentation.mjs';
7
+ import { unsupportedSession, unsupportedSessionOrigin, sessionProvider } from './instance-presentation.mjs';
8
8
 
9
9
  export { DEFAULT_TMUX_SESSION };
10
10
  const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
11
11
 
12
- /** rows: [{ instance, running?, tmux?, sessionTarget?, runtimeState?, runtimeError? }] in, one liveness
12
+ /** rows: [{ instance, running?, tmux?, sessionTarget?, backend?, runtimeState?, runtimeError? }] in, one liveness
13
13
  * per row out. A Herdr-recorded row is never probed: it is unsupported, with the kernel's reason.
14
14
  *
15
+ * A row on a session provider (instance-presentation.mjs `sessionProvider`: its `backend` is a provider's
16
+ * name, "bb" say) is never probed either: it has no tmux target, so the reader would call it stopped. Its
17
+ * `running`, `runtimeState` and `runtimeError` stay the kernel's, as for a `running: null` row, and the
18
+ * answer carries no `tmux`. A row with no `backend`, or with "tmux", is read as before.
19
+ *
15
20
  * The probe refines a row only when the kernel answered `running` true or false. A row it answered
16
21
  * `running: null` is not probed: its `running`, `runtimeState` and `runtimeError` stay the kernel's,
17
22
  * and the answer carries no `tmux`, so the merged row keeps the kernel's own. The kernel answers
@@ -27,6 +32,11 @@ export function observeLiveness(rows, { tmuxReader = createTmuxStatusReader(), s
27
32
  const unsupported = unsupportedSession(row);
28
33
  if (unsupported) return { running: null, runtimeState: 'unsupported', runtimeError: unsupported.slice(0, 300), tmux: null };
29
34
  // After the unsupported check: an older kernel's Herdr row is `unreachable` with a sessionTarget, and reads unsupported.
35
+ if (sessionProvider(row)) {
36
+ const running = typeof row.running === 'boolean' ? row.running : null;
37
+ return { running, ...(row.runtimeState !== undefined || running === null ? { runtimeState: row.runtimeState ?? 'unreachable' } : {}),
38
+ ...(row.runtimeError ? { runtimeError: String(row.runtimeError).slice(0, 300) } : {}) };
39
+ }
30
40
  if (row.running === null) return { running: null, runtimeState: row.runtimeState ?? 'unreachable', ...(row.runtimeError ? { runtimeError: String(row.runtimeError).slice(0, 300) } : {}) };
31
41
  const tmux = record(row.tmux) ? row.tmux : undefined;
32
42
  const { tmux: observed, running, runtimeState, runtimeError } = tmuxReader({ instance: row.instance, tmux }, session);
@@ -37,12 +47,13 @@ export function observeLiveness(rows, { tmuxReader = createTmuxStatusReader(), s
37
47
  /** Who makes the `runtimeError` of a row's answer, when the answer has one: "kernel", "terminal-probe",
38
48
  * or null for the stand-in of an older kernel's Herdr row. By the order `observeLiveness` takes, which is
39
49
  * a function of the row alone: an invalid row and a probed one are the terminal check's, a Herdr row's
40
- * text is the kernel's or the stand-in, and a row the kernel answered `running: null` keeps the kernel's.
50
+ * text is the kernel's or the stand-in, and a row on a session provider and one the kernel answered
51
+ * `running: null` keep the kernel's.
41
52
  * The collector's answer crosses a process as JSON, so the speaker is not put on that wire: the reader of
42
53
  * the answers asks here, of the row it sent (deployment-panel.mjs `livenessAnswers`). Not on the stable surface. */
43
54
  export function livenessOrigin(row) {
44
55
  if (!record(row) || typeof row.instance !== 'string') return 'terminal-probe';
45
56
  if (unsupportedSession(row)) return unsupportedSessionOrigin(row);
46
- if (row.running === null) return 'kernel';
57
+ if (sessionProvider(row) || row.running === null) return 'kernel';
47
58
  return 'terminal-probe';
48
59
  }